ui

package
v0.32.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 31, 2026 License: MIT Imports: 3 Imported by: 0

Documentation

Index

Constants

View Source
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

type HITLChoiceMessage struct {
	ID    string `json:"id"`
	Label string `json:"label"`
}

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL