turn.proto

classDiagram
direction LR
%% Mermaid Diagram for package: blitz.v1

%% A turn: one prompt to the agent and everything that happens until it answers. Mirrors pkg/api's Turn, Event and TurnResult. Turn is one prompt for the agent.

class Turn {
  + string text
  + string prompt
  + bool plan
  + string read_only
  + bool aside
  + bool accepted
  + List~string~ image_ids
  + int32 max_turns
  + List~string~ fetch_grants
  + double max_cost_usd
  + google.protobuf.Duration timeout
  + bool command
  + List~ContextBlock~ context
}
Turn --> `ContextBlock`

%% ContextBlock is content the user added to a turn from elsewhere.

class ContextBlock {
  + string kind
  + string url
  + string title
  + string html
  + string text
}

%% TurnEvent is something that happened during a turn. Events arrive in order; the last one is always `finished`.

class TurnEvent {
  + string author
  + Oneof~Accepted~ accepted [oneof: kind]
  + Oneof~Text~ text [oneof: kind]
  + Oneof~ToolCall~ tool_call [oneof: kind]
  + Oneof~ToolResult~ tool_result [oneof: kind]
  + Oneof~ApprovalRequest~ approval_request [oneof: kind]
  + Oneof~Question~ question [oneof: kind]
  + Oneof~TurnFinished~ finished [oneof: kind]
  + Oneof~Tasks~ tasks [oneof: kind]
  + Oneof~Notice~ notice [oneof: kind]
  + Oneof~FlowStep~ flow_step [oneof: kind]
}
TurnEvent --> `Accepted`
TurnEvent --> `Text`
TurnEvent --> `ToolCall`
TurnEvent --> `ToolResult`
TurnEvent --> `ApprovalRequest`
TurnEvent --> `Question`
TurnEvent --> `TurnFinished`
TurnEvent --> `Tasks`
TurnEvent --> `Notice`
TurnEvent --> `FlowStep`

%% A workflow's step starting, or how it ended.

class FlowStep {
  + string workflow
  + string id
  + string title
  + string type
  + int32 index
  + int32 count
  + string status
  + string output
  + string error
  + string run
}

%% A message from Blitz itself about a turn.

class Notice {
  + string text
  + bool error
  + bool transient
}

%% Tasks is the agent's task list (the todo tool).

class Tasks {
  + List~Task~ items
}
Tasks --> `Task`

%% One item of the agent's task list (the todo tool): its text and state.

class Task {
  + string content
  + string status
}

%% Accepted marks the prompt as recorded and about to be sent.

class Accepted {
}

%% Text is model output. With streaming, partial chunks arrive first and a final event then repeats them in full (repeat); without streaming only final text arrives. To show text once, show partial chunks and final text that isn't a repeat.

class Text {
  + string text
  + bool partial
  + bool repeat
  + bool thought
}

%% ToolCall is the agent calling a tool.

class ToolCall {
  + string id
  + string name
  + google.protobuf.Struct args
  + bool partial
}

%% ToolResult is what a tool returned.

class ToolResult {
  + string id
  + string name
  + google.protobuf.Struct result
}

%% ApprovalRequest asks permission for one action.

class ApprovalRequest {
  + string request_id
  + string tool
  + ActionKind kind
  + string detail
  + string diff
  + string scope_label
  + string agent
  + string task_id
}
ApprovalRequest --> `ActionKind`

%% Question is the agent asking the user something.

class Question {
  + string request_id
  + string question
  + List~string~ options
  + string agent
  + string task_id
  + bool multi_select
}

%% Usage is the token usage and estimated cost of a session.

class Usage {
  + int32 calls
  + int64 input
  + int64 cached
  + int64 cache_write
  + int64 output
  + int64 last_prompt
  + double cost_usd
  + bool priced
  + int32 search_queries
  + double search_cost_usd
}

%% TurnFinished ends a turn's events.

class TurnFinished {
  + string output
  + Usage before
  + Usage after
  + List~string~ leftover
  + ErrorInfo error
}
TurnFinished --> `Usage`
TurnFinished --> `Usage`
TurnFinished --> `ErrorInfo`

%% ErrorInfo is a machine-readable error, also attached to failed calls as a Connect error detail. Clients word and localise it from reason and metadata; message is an English fallback.

class ErrorInfo {
  + string reason
  + Map~string,  string~ metadata
  + string message
}
%% ActionKind is the kind of action an approval covers.

class ActionKind{
  <<enumeration>>
  ACTION_KIND_UNSPECIFIED
  ACTION_KIND_COMMAND
  ACTION_KIND_WRITE
  ACTION_KIND_DELETE
  ACTION_KIND_NETWORK
  ACTION_KIND_MCP
}
%% Decision answers an ApprovalRequest.

class Decision{
  <<enumeration>>
  DECISION_UNSPECIFIED
  DECISION_DENY
  DECISION_ONCE
  DECISION_SESSION
  DECISION_ALWAYS
}

classDiagram
direction LR
%% ActionKind is the kind of action an approval covers.

class ActionKind{
  <<enumeration>>
  ACTION_KIND_UNSPECIFIED
  ACTION_KIND_COMMAND
  ACTION_KIND_WRITE
  ACTION_KIND_DELETE
  ACTION_KIND_NETWORK
  ACTION_KIND_MCP
}

classDiagram
direction LR
%% Decision answers an ApprovalRequest.

class Decision{
  <<enumeration>>
  DECISION_UNSPECIFIED
  DECISION_DENY
  DECISION_ONCE
  DECISION_SESSION
  DECISION_ALWAYS
}

classDiagram
direction LR

%% A turn: one prompt to the agent and everything that happens until it answers. Mirrors pkg/api's Turn, Event and TurnResult. Turn is one prompt for the agent.

class Turn {
  + string text
  + string prompt
  + bool plan
  + string read_only
  + bool aside
  + bool accepted
  + List~string~ image_ids
  + int32 max_turns
  + List~string~ fetch_grants
  + double max_cost_usd
  + google.protobuf.Duration timeout
  + bool command
  + List~ContextBlock~ context
}
Turn --> `ContextBlock`

classDiagram
direction LR

%% ContextBlock is content the user added to a turn from elsewhere.

class ContextBlock {
  + string kind
  + string url
  + string title
  + string html
  + string text
}

classDiagram
direction LR

%% TurnEvent is something that happened during a turn. Events arrive in order; the last one is always `finished`.

class TurnEvent {
  + string author
  + Oneof~Accepted~ accepted [oneof: kind]
  + Oneof~Text~ text [oneof: kind]
  + Oneof~ToolCall~ tool_call [oneof: kind]
  + Oneof~ToolResult~ tool_result [oneof: kind]
  + Oneof~ApprovalRequest~ approval_request [oneof: kind]
  + Oneof~Question~ question [oneof: kind]
  + Oneof~TurnFinished~ finished [oneof: kind]
  + Oneof~Tasks~ tasks [oneof: kind]
  + Oneof~Notice~ notice [oneof: kind]
  + Oneof~FlowStep~ flow_step [oneof: kind]
}
TurnEvent --> `Accepted`
TurnEvent --> `Text`
TurnEvent --> `ToolCall`
TurnEvent --> `ToolResult`
TurnEvent --> `ApprovalRequest`
TurnEvent --> `Question`
TurnEvent --> `TurnFinished`
TurnEvent --> `Tasks`
TurnEvent --> `Notice`
TurnEvent --> `FlowStep`

classDiagram
direction LR

%% A workflow's step starting, or how it ended.

class FlowStep {
  + string workflow
  + string id
  + string title
  + string type
  + int32 index
  + int32 count
  + string status
  + string output
  + string error
  + string run
}

classDiagram
direction LR

%% A message from Blitz itself about a turn.

class Notice {
  + string text
  + bool error
  + bool transient
}

classDiagram
direction LR

%% Tasks is the agent's task list (the todo tool).

class Tasks {
  + List~Task~ items
}
Tasks --> `Task`

classDiagram
direction LR

%% One item of the agent's task list (the todo tool): its text and state.

class Task {
  + string content
  + string status
}

classDiagram
direction LR

%% Accepted marks the prompt as recorded and about to be sent.

class Accepted {
}

classDiagram
direction LR

%% Text is model output. With streaming, partial chunks arrive first and a final event then repeats them in full (repeat); without streaming only final text arrives. To show text once, show partial chunks and final text that isn't a repeat.

class Text {
  + string text
  + bool partial
  + bool repeat
  + bool thought
}

classDiagram
direction LR

%% ToolCall is the agent calling a tool.

class ToolCall {
  + string id
  + string name
  + google.protobuf.Struct args
  + bool partial
}

classDiagram
direction LR

%% ToolResult is what a tool returned.

class ToolResult {
  + string id
  + string name
  + google.protobuf.Struct result
}

classDiagram
direction LR

%% ApprovalRequest asks permission for one action.

class ApprovalRequest {
  + string request_id
  + string tool
  + ActionKind kind
  + string detail
  + string diff
  + string scope_label
  + string agent
  + string task_id
}
ApprovalRequest --> `ActionKind`

classDiagram
direction LR

%% Question is the agent asking the user something.

class Question {
  + string request_id
  + string question
  + List~string~ options
  + string agent
  + string task_id
  + bool multi_select
}

classDiagram
direction LR

%% Usage is the token usage and estimated cost of a session.

class Usage {
  + int32 calls
  + int64 input
  + int64 cached
  + int64 cache_write
  + int64 output
  + int64 last_prompt
  + double cost_usd
  + bool priced
  + int32 search_queries
  + double search_cost_usd
}

classDiagram
direction LR

%% TurnFinished ends a turn's events.

class TurnFinished {
  + string output
  + Usage before
  + Usage after
  + List~string~ leftover
  + ErrorInfo error
}
TurnFinished --> `Usage`
TurnFinished --> `Usage`
TurnFinished --> `ErrorInfo`

classDiagram
direction LR

%% ErrorInfo is a machine-readable error, also attached to failed calls as a Connect error detail. Clients word and localise it from reason and metadata; message is an English fallback.

class ErrorInfo {
  + string reason
  + Map~string,  string~ metadata
  + string message
}

gdoc_arrow_left_alt session.proto workspace.proto gdoc_arrow_right_alt