Documentation
¶
Index ¶
- Constants
- type ApprovalRequestMessage
- type ApprovalResponseMessage
- type CodeExecStdoutMessage
- type Envelope
- type FileAttachment
- type HITLChoiceMessage
- type HITLRequestMessage
- type HITLResponseMessage
- type InputMessage
- type OutputMessage
- type PlanDisplayMessage
- type PlanDisplayStep
- type SessionInfo
- type StatusMessage
- type StreamChunkMessage
- type StreamEndMessage
- type StreamHoldMessage
- type StreamRetractMessage
- type ThinkingMessage
- type UIAdapter
- type WorkerStatusMessage
- type WorkflowStatusMessage
Constants ¶
const ( // Inbound (client -> server) TypeInput = "input" TypeApprovalResponse = "approval_response" TypePing = "ping" TypeFileList = "file_list" TypeFileDownload = "file_download" TypeCancelRequest = "cancel_request" TypeResumeRequest = "resume_request" TypeHITLResponse = "hitl_response" // Outbound (server -> client) TypeOutput = "output" TypeStreamChunk = "stream_chunk" // TypeStreamHold announces that an output gate has suspended the stream // pending review, and (with resumed set) that it has released it again. A // stream that simply goes quiet is indistinguishable from a hung turn, so // a client renders a reviewing indicator rather than a stalled cursor. TypeStreamHold = "stream_hold" // TypeStreamRetract tells a client that an output gate blocked the stream // mid-flight and the text rendered for that turn is disowned. A client // that owns its render buffer should erase it; the replacement arrives as // an ordinary output message. TypeStreamRetract = "stream_retract" TypeStreamEnd = "stream_end" TypeStatus = "status" TypeApprovalRequest = "approval_request" TypePong = "pong" TypeFileListResult = "file_list_result" TypeFileContent = "file_content" TypeFileChanged = "file_changed" TypeSessionReset = "session_reset" TypeCancelComplete = "cancel_complete" TypeHITLRequest = "hitl_request" TypeCodeExecStdout = "code_exec_stdout" TypeWorkerStatus = "worker_status" TypeWorkflowStatus = "workflow_status" )
Message type constants for the WebSocket protocol.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ApprovalRequestMessage ¶
type ApprovalRequestMessage struct {
PromptID string `json:"prompt_id"`
Description string `json:"description"`
ToolCall string `json:"tool_call"`
Risk string `json:"risk"`
}
ApprovalRequestMessage asks the user to approve an action.
type ApprovalResponseMessage ¶
type ApprovalResponseMessage struct {
PromptID string `json:"prompt_id"`
Approved bool `json:"approved"`
Always bool `json:"always"`
}
ApprovalResponseMessage carries the user's approval decision.
type CodeExecStdoutMessage ¶
type CodeExecStdoutMessage struct {
CallID string `json:"call_id"`
TurnID string `json:"turn_id"`
Chunk string `json:"chunk"`
Final bool `json:"final"`
Truncated bool `json:"truncated"`
}
CodeExecStdoutMessage streams a chunk of stdout from a run_code script while it is still executing. CallID keys the message so IO plugins can render each script as its own collapsible section. Final=true on the last chunk signals the stream is closed.
type Envelope ¶
type Envelope struct {
Type string `json:"type"`
ID string `json:"id"`
SessionID string `json:"session_id"`
Timestamp time.Time `json:"timestamp"`
Payload json.RawMessage `json:"payload"`
}
Envelope is the wire format for all messages over the UI transport.
type FileAttachment ¶
type FileAttachment struct {
Name string `json:"name"`
MimeType string `json:"mime_type"`
Data []byte `json:"data"`
}
FileAttachment is a file attached to user input.
type HITLChoiceMessage ¶
HITLChoiceMessage is one option presented in a multi-choice human-in-the-loop request.
type HITLRequestMessage ¶
type HITLRequestMessage struct {
RequestID string `json:"request_id"`
Prompt string `json:"prompt"`
Mode string `json:"mode"`
Choices []HITLChoiceMessage `json:"choices,omitempty"`
TurnID string `json:"turn_id,omitempty"`
}
HITLRequestMessage is the IO-facing payload for a hitl.requested event. IO plugins render Prompt and (when present) Choices, then return a HITLResponseMessage carrying the operator's pick or freeform answer.
type HITLResponseMessage ¶
type HITLResponseMessage struct {
RequestID string `json:"request_id"`
ChoiceID string `json:"choice_id,omitempty"`
FreeText string `json:"free_text,omitempty"`
}
HITLResponseMessage carries the operator's reply.
type InputMessage ¶
type InputMessage struct {
Content string `json:"content"`
Files []FileAttachment `json:"files"`
}
InputMessage carries user input from the UI.
type OutputMessage ¶
type OutputMessage struct {
Content string `json:"content"`
Role string `json:"role"`
Metadata map[string]any `json:"metadata"`
TurnID string `json:"turn_id"`
}
OutputMessage carries a complete agent output to the UI.
type PlanDisplayMessage ¶
type PlanDisplayMessage struct {
PlanID string `json:"plan_id"`
Summary string `json:"summary"`
Steps []PlanDisplayStep `json:"steps"`
Source string `json:"source"`
TurnID string `json:"turn_id"`
}
PlanDisplayMessage carries a plan overview to the UI.
type PlanDisplayStep ¶
type PlanDisplayStep struct {
ID string `json:"id"`
Description string `json:"description"`
Status string `json:"status"`
Order int `json:"order"`
SpawnID string `json:"spawn_id,omitempty"`
}
PlanDisplayStep is a single step for UI display.
SpawnID, when set, links the step to a subagent worker so the UI can inline progress (iteration count, tool calls, terminal totals) onto the plan step. Empty when the agent executes the step inline.
type SessionInfo ¶
type SessionInfo struct {
ID string `json:"id"`
Transport string `json:"transport"`
ConnectedAt time.Time `json:"connected_at"`
UserAgent string `json:"user_agent"`
WorkspaceDir string `json:"workspace_dir"`
FilesDir string `json:"files_dir"`
}
SessionInfo describes a connected UI session.
type StatusMessage ¶
type StatusMessage struct {
State string `json:"state"`
Detail string `json:"detail"`
ToolID string `json:"tool_id"`
}
StatusMessage conveys the agent's current operational state.
type StreamChunkMessage ¶
type StreamChunkMessage struct {
Content string `json:"content"`
TurnID string `json:"turn_id"`
Index int `json:"index"`
}
StreamChunkMessage carries a single chunk of streamed output.
type StreamEndMessage ¶
type StreamEndMessage struct {
TurnID string `json:"turn_id"`
Metadata map[string]any `json:"metadata"`
}
StreamEndMessage signals the end of a streaming response.
type StreamHoldMessage ¶
type StreamHoldMessage struct {
TurnID string `json:"turn_id"`
Held int `json:"held"`
Reason string `json:"reason,omitempty"`
Resumed bool `json:"resumed"`
}
StreamHoldMessage carries both edges of a suspended stream: Resumed is false when a gate starts withholding text and true when it releases it. Held is the number of bytes currently withheld, and is zero on the resume edge.
type StreamRetractMessage ¶
type StreamRetractMessage struct {
TurnID string `json:"turn_id"`
ReleasedLen int `json:"released_len"`
Reason string `json:"reason,omitempty"`
}
StreamRetractMessage disowns the text already rendered for a turn whose stream an output gate blocked. ReleasedLen is how many bytes got out before the block landed — the size of what the client is being asked to erase.
type ThinkingMessage ¶
type ThinkingMessage struct {
Content string `json:"content"`
Phase string `json:"phase"`
Source string `json:"source"`
TurnID string `json:"turn_id"`
}
ThinkingMessage carries an intermediate reasoning step to the UI.
type UIAdapter ¶
type UIAdapter interface {
Start(ctx context.Context) error
Stop(ctx context.Context) error
// Outbound (engine -> user)
SendOutput(msg OutputMessage) error
SendStreamChunk(msg StreamChunkMessage) error
SendStreamEnd(msg StreamEndMessage) error
SendStatus(msg StatusMessage) error
RequestApproval(msg ApprovalRequestMessage) (ApprovalResponseMessage, error)
// Inbound (user -> engine) — delivered via callback
OnInput(handler func(InputMessage))
OnApprovalResponse(handler func(ApprovalResponseMessage))
// Session
Sessions() []SessionInfo
}
UIAdapter defines the contract between the engine and a UI transport. IO plugins implement this interface; the engine consumes it.
type WorkerStatusMessage ¶
type WorkerStatusMessage struct {
Kind string `json:"kind"`
SpawnID string `json:"spawn_id"`
Task string `json:"task,omitempty"`
Iteration int `json:"iteration,omitempty"`
Content string `json:"content,omitempty"`
ToolCount int `json:"tool_count,omitempty"`
Result string `json:"result,omitempty"`
Error string `json:"error,omitempty"`
Iterations int `json:"iterations,omitempty"`
TotalTokens int `json:"total_tokens,omitempty"`
ParentTurnID string `json:"parent_turn_id,omitempty"`
}
WorkerStatusMessage carries a single subagent lifecycle event to the UI.
One worker_status envelope is sent per bus event in the subagent.started → subagent.iteration* → subagent.complete sequence, keyed by SpawnID. The frontend tracks workers by SpawnID and updates in place on each new envelope. Kind is the discriminator:
"started" — worker just began; Task is set, Iteration=0.
"iteration" — worker finished iteration N; Content/ToolCount describe
the assistant turn that just landed.
"complete" — worker finished (success or error). Result/Error/
Iterations/TotalTokens summarize the run.
ParentTurnID lets the UI correlate workers with the orchestrator turn that spawned them, so progress can clear at the start of the next turn.
type WorkflowStatusMessage ¶
type WorkflowStatusMessage struct {
WorkflowID string `json:"workflow_id"`
WorkflowName string `json:"workflow_name,omitempty"`
RunID string `json:"run_id"`
Stage string `json:"stage,omitempty"`
StageLabel string `json:"stage_label,omitempty"`
StageIndex int `json:"stage_index,omitempty"`
StageTotal int `json:"stage_total,omitempty"`
Iteration int `json:"iteration,omitempty"`
MaxIterations int `json:"max_iterations,omitempty"`
Turn int `json:"turn,omitempty"`
MaxTurns int `json:"max_turns,omitempty"`
ItemsDone int `json:"items_done,omitempty"`
ItemsTotal int `json:"items_total,omitempty"`
CurrentItem string `json:"current_item,omitempty"`
Status string `json:"status"`
Detail string `json:"detail,omitempty"`
Failures []string `json:"failures,omitempty"`
}
WorkflowStatusMessage powers a dedicated workflow status surface in the UI — a sticky panel in the TUI right rail; a header indicator in the browser. One message per workflow.progress bus event.
IO plugins translate events.WorkflowProgress into this shape so the UI rendering code is provider-agnostic: ICM, planexec, and any future workflow plugin look the same in the panel.