Protocol

session_id SessionId required

model AgentModel required

model string required

reasoning string optional

small AgentModel optional

medium AgentModel optional

models AgentModels defaulted

path string optional

revision AgentConfigRev required

config AgentsConfig required

revision AgentConfigRev required

config AgentsConfig required

model AgentModelSlot required

slot AgentModelSlot required

model string required

reasoning string required

revision AgentConfigRev required

This type identifies the client connection.

name string required The client connection name.

version string required The client build version.

This part holds plain text.

text string required

This part holds an image source and an optional detail hint.

source MediaSource required

detail string optional

This part holds an audio source and its format.

source MediaSource required

format string required

This part holds a file source and an optional file name.

source MediaSource required

filename string optional

A content-addressed blob. No blob store exists yet, so a request that carries one is refused.

hash [64]u8 required

mime string required

bytes u64 required

These are the parameters for auth.cancel_login.

login_id LoginId required

This payload describes auth.changed.

provider AuthProvider required

This result describes auth.list.

providers []AuthProvider required

The engine returns these device authorization details only to the connection that sent the request.

login_id LoginId required

verification_url string required

user_code string required

This payload describes auth.login_finished.

login_id LoginId required

provider_id ProviderId required

outcome AuthLoginOutcome required

The login was explicitly canceled.

The login failed without changing durable credentials.

message string required

The engine completed login and durably stored the credentials.

These are the parameters for auth.login.

provider_id ProviderId required

These parameters select the local credential to remove, an API key or a grant.

provider_id ProviderId required

Public authentication state and capabilities for one provider.

provider_id ProviderId required

credential_kind AuthCredentialKind optional

can_login bool required

These auth.set_api_key parameters carry a key that the wire never returns.

provider_id ProviderId required

api_key string required

This payload describes catalog.changed.

catalog_rev CatalogRev required

These are the parameters for catalog.list.

since_rev CatalogRev optional

The client sent a stale or absent revision, so the engine returns the full catalog.

catalog_rev CatalogRev required

providers []ProviderInfo required

models []ModelInfo required

This type describes one configured provider. Its state tells a client why it cannot serve a turn.

id string required The provider name inside its origin. Two origins can use one id.

name string required

state ProviderState required

The client sent the current revision, so the engine returns no catalog data.

catalog_rev CatalogRev required

This result reports the merged catalog revision after catalog.reload and whether it moved.

catalog_rev CatalogRev required

changed bool required

These costs use United States dollars per million tokens.

input f64 optional

output f64 optional

cache_read f64 optional

cache_write f64 optional

This type exposes a closed projection of a provider model record. Its fields borrow their data.

id ModelId required

provider string required

selector string required The token that selects this model. A client echoes it back and never parses or builds it.

name string required

context_window u64 optional

max_output_tokens u64 optional

reasoning_levels []string required

default_reasoning string required

supports_vision bool optional

supports_tools bool optional

cost ModelCost required

This type carries an RPC request.

id RequestId required

method MethodName required

params RequestParams required

This type carries a successful RPC response.

id RequestId required

result ResponseResult required

This type carries a failed RPC response.

id RequestId required

error ErrorObject required

This type carries an RPC notification.

method BroadcastName required

params BroadcastData required

This state marks the first phase of a run.

run_id RunId required

started_at_ms u64 required

This state marks an active compaction model call.

run_id RunId required

reason CompactionReason required

started_at_ms u64 required

This state marks a session with no active work.

The model produces reasoning in this state.

run_id RunId required

message_id MessageId required

part_id PartId required

This state marks a run that waits for a retry.

run_id RunId required

attempt u64 required

max_attempts u64 required

next_at_ms u64 required

code RunErrorCode required

message string required

This state marks an active run.

run_id RunId required

started_at_ms u64 required

This state marks an active tool call.

run_id RunId required

message_id MessageId required

part_id PartId required

tool_name string required

started_at_ms u64 required

This payload describes input.canceled.

session_id SessionId required

seq Seq required

input_id InputId required

Raw content parts.

content []ContentPart required

This payload describes input.queued.

session_id SessionId required

seq Seq required

input QueuedInput required

This payload asks the connected frontend to put one question to the user.

interaction_id u64 required

request InteractionRequest required

session_id SessionId optional

title string required

message string required

title string required

options []string required

secret bool optional

title string required

placeholder string optional

These parameters answer one pending question.

interaction_id u64 required

response InteractionResponse required

value bool required

value string required

This type describes a skill invocation.

skill SkillRef required

This type records discovered skill metadata.

name string required

description string required

scope SkillScope required This scope identifies a project or personal skill.

argument_hint string required

This type names a skill and holds its rendered arguments.

name string required

arguments string required

This result lists discovered skills.

skills []SkillInfo required This field lists discovered skills.

This is the assistant draft that a run streams. Its fields borrow their data.

message AssistantMessage required

This payload describes an assistant transcript message. Its fields borrow their data.

id MessageId required

run_id RunId required

config_rev ConfigRev required

agent string required

content []AssistantPart required

finish StopReason optional

tokens TokenUsage optional

cost f64 optional

time MessageTime required

error MessageError optional

provenance TurnProvenance optional

This payload describes a compaction transcript message. Its fields borrow their data.

id MessageId required

run_id RunId required

reason CompactionReason required

summary string required

first_kept_id MessageId optional

tokens_before u64 required

tokens_after u64 required

time CreatedTime required

This payload describes message.committed.

session_id SessionId required

seq Seq required

message Message required

This payload describes message.discarded.

session_id SessionId required

message_id MessageId required

This type describes an assistant error with finish: "error". Its fields borrow their data.

type string required

message string required

This payload describes message.part_added.

session_id SessionId required

message_id MessageId required

part AssistantPart required

This payload describes message.part_finalized. The engine sends it at block stop.

session_id SessionId required

message_id MessageId required

part_id PartId required

final PartFinal required

This payload describes message.started when the engine opens a draft.

session_id SessionId required

message_id MessageId required

run_id RunId required

config_rev ConfigRev required

agent string required

created_at_ms u64 required

Creation and completion times for an assistant message.

created_at_ms u64 required

completed_at_ms u64 optional

This payload holds more text or reasoning bytes for a draft.

session_id SessionId required

message_id MessageId required

part_id PartId required

delta string required

offset u64 required

The engine attaches the reasoning signature at block stop. An empty string means none.

signature string required

This payload describes a reasoning part in an assistant message. Its fields borrow their data.

id PartId required

text string required

signature string required

The engine attaches the opaque redacted reasoning data at block stop.

data string required

This payload holds opaque, safety-redacted model reasoning. Its fields borrow their data.

id PartId required

data string required

This payload describes a text part in an assistant message. Its fields borrow their data.

id PartId required

text string required

This type records token counts for one assistant message.

input u64 required

output u64 required

reasoning u64 required

cache_read u64 required

cache_write u64 required

This payload describes a tool part in an assistant message. Its fields borrow their data.

id PartId required

call_id string optional

name string required

arguments string required

input_view []View optional

state ToolState required

This type records the provider that produced an assistant turn. Its fields borrow their data.

protocol ProviderProtocol required

model string required

This payload describes a user transcript message. Its fields borrow their data.

source InputSource optional

id MessageId required

content []ContentPart required

input_id InputId required

skill SkillRef optional

time CreatedTime required

This payload describes config.changed.

session_id SessionId required

seq Seq required

config RunConfig required

These are the session.create input fields. They borrow their data.

workspace_path string required The workspace root. The caller names it; the engine holds no default directory.

profile string optional

model string optional

reasoning string optional

system_prompt string optional

max_rounds u64 optional

initial_input Input optional

child ChildSession optional

This type records the creation time for a user or compaction message.

created_at_ms u64 required

This type records the engine build. Its fields borrow their data.

version string required

Empty params or result object.

This type records request failure details. Its fields borrow their data.

code ErrorCode required

message string required

This result contains the coarse engine snapshot after initialize.

protocol u32 required

engine EngineInfo required

session_revision SessionRevision required

catalog_rev CatalogRev required

The engine broadcasts this diagnostic notice to all connections. Its fields borrow their data.

level NoticeLevel required

source string required

message string required

session_id SessionId required

message_id MessageId required

part_id PartId required

session_id SessionId required

run_id RunId required

path string required

outcome RunOutcome required

partial bool required

truncated bool required

session_id SessionId required

path string required

input_ids []InputId required

run_id RunId required

kind RunKind required

This input waits behind an active turn.

source InputSource optional

input_id InputId required

content []ContentPart required

queued_at_ms u64 required

The engine owns this session summary.

id SessionId required

root string required The canonical workspace directory this session runs in.

profile string required

model string required

reasoning string required

config_rev ConfigRev required

max_rounds u64 optional

title string required

message_count u64 required

usage_total TokenUsage required

created_at_ms u64 required

updated_at_ms u64 required

created_by Client optional

origin SessionOrigin required

agent string optional

name string optional

This payload describes transcript.truncated.

session_id SessionId required

seq Seq required

first_removed_id MessageId required

This type records run start and end times. The engine records no start time when a queued run never starts.

started_at_ms u64 optional

ended_at_ms u64 required

The engine saves these run settings at run start.

config_rev ConfigRev required

model string required

reasoning string required

This payload describes run.done.

session_id SessionId required

seq Seq required

run_id RunId required

kind RunKind required

timing RunCanceledTiming required

outcome RunOutcome required

The user or engine canceled the run. The terminal envelope carries its timing.

The engine completed a manual compaction and produced a summary.

message_id MessageId required

The engine reports failure after it exhausts its retry policy.

code RunErrorCode required

message string required

The engine skipped a manual compaction without producing a summary.

reason CompactSkipReason required

The engine completed a turn after some round trips and recorded its stop reason.

finish StopReason required

rounds u64 required

This payload describes run.started.

session_id SessionId required

seq Seq required

run_id RunId required

kind RunKind required

reason CompactionReason optional

config_rev ConfigRev required

started_at_ms u64 required

Coarse live session state.

state ActivityState required

config RunConfig optional

queued u64 required

context_usage TokenUsage required

pending_compaction RunId optional

This payload describes session.activity_changed.

session_id SessionId required

activity SessionActivity required

These are the parameters for session.cancel_input.

session_id SessionId required

input_id InputId required

This result identifies the canceled input.

canceled_input InputId required

These are the parameters for session.cancel_run.

session_id SessionId required

run_id RunId optional

clear_queue bool optional

This result identifies the canceled run and cleared inputs.

canceled_run RunId optional

cleared_inputs []InputId required

cleared_compaction RunId optional

These are the parameters for session.compact.

session_id SessionId required

This result describes session.compact.

status CompactStatus required

run_id RunId required

These are the parameters for session.config.get.

session_id SessionId required

config_rev ConfigRev optional

This result describes session.config.get.

config RunConfig required

system_prompt string optional

These are the parameters for session.fork.

session_id SessionId required

before_message_id MessageId optional

These are the parameters for session.get.

session_id SessionId required

These are the parameters for session.history.

session_id SessionId required

before_message_id MessageId required

limit u64 optional

This result describes session.history.

session_id SessionId required

messages []Message required

configs []RunConfig required

has_more bool required

This row summarizes a session for session.list, session.get, and session broadcasts. Its fields borrow their data.

session Session required

activity SessionActivity required

These are the session.list input fields. They borrow their data.

population SessionPopulation defaulted

view SessionView defaulted

limit u64 optional

cursor string optional

This result contains one bounded session.list page. Its fields borrow their data.

revision SessionRevision required

items []SessionListItem required

next_cursor string optional

total u64 required

This origin links a session to its parent session and message part.

parent_id SessionId required

parent_message_id MessageId required

parent_part_id PartId required

This origin links a session to its source session.

source_id SessionId required

This origin marks a user-created root session.

An absent field leaves the current value unchanged. The engine stores the system prompt at creation. The system prompt remains fixed, and the fields borrow their data.

model string optional

reasoning string optional

max_rounds u64 optional

These are the parameters for session.patch.

session_id SessionId required

patch SessionPatch required

This option selects every session regardless of origin.

This option selects the immediate persistent children of one session.

parent_id SessionId required

This option selects root sessions and forks for user-facing conversations.

These are the parameters for session.queue.

session_id SessionId required

This result lists the queued inputs of one session, oldest first.

items []QueuedInput required

These are the parameters for session.remove.

session_id SessionId required

cascade_children bool defaulted

This payload describes session.removed.

revision SessionRevision required

session_id SessionId required

This result contains the session after creation, a fork, or a patch.

session Session required

input SessionSendInputResult optional

The live parent tool site and the stable name of a new child.

parent_id SessionId required

parent_message_id MessageId required

parent_part_id PartId required

name string required

active u64 required

limit u64 required

These are the parameters for session.rewind.

session_id SessionId required

before_message_id MessageId required

These are the parameters for session.send_input.

session_id SessionId required

input Input required

The engine queued the input behind an active turn.

input_id InputId required

reason InputQueueReason required

capacity ChildCapacity optional

The engine started the input immediately.

input_id InputId required

run_id RunId required

capacity ChildCapacity optional

This payload describes session.summary_changed.

revision SessionRevision required

session Session required

The user or engine canceled the call.

duration_ms u64 optional

This payload describes tool.state_changed.

session_id SessionId required

message_id MessageId required

part_id PartId required

state ToolState required

The tool call completed successfully.

output string required

view []View optional

duration_ms u64 required

The tool call failed.

error string required

view []View optional

duration_ms u64 required

The tool call has not started.

The tool call is active.

started_at_ms u64 required

output string optional

This type describes one file in a diff view.

path string required

old_path string optional

hunks []DiffHunk required

This type describes one hunk of a unified diff.

old_start u64 required

old_lines u64 required

new_start u64 required

new_lines u64 required

lines []string required

This view displays a unified diff.

files []DiffFile required

This view displays an image.

source MediaSource required

alt string optional

This view displays JSON text.

text string required

This view displays Markdown text.

text string required

This view displays plain text.

text string required

language string optional

This type describes one part of a message's content.

ContentTextContentImageContentAudioContentFile

This type identifies where media bytes live.

MediaBlob

This union reports the terminal outcome of an engine-owned login attempt.

AuthLoginOutcomeSucceededAuthLoginOutcomeCanceledAuthLoginOutcomeFailed

This result reports a catalog unchanged since since_rev, or a full catalog snapshot.

CatalogListResultUnchangedCatalogListResultFull

This state holds the locator fields that place the session in its transcript.

ActivityStateIdleActivityStateBuildingActivityStateRunningActivityStateReasoningActivityStateRunningToolActivityStateRetryingActivityStateCompacting

This type accepts raw content or a skill invocation. Its fields borrow their data.

InputContentInputSkill

Native code assigns this source; public input has no source field.

ParentInstructionChildReportChildInputCanceledEngineInterruption

This union carries one frontend-neutral question.

InteractionConfirmInteractionSelectInteractionInput

This union answers a question. Its arm matches the question, or the user canceled.

InteractionConfirmedInteractionValueInteractionValueEmpty

This type describes one element of an assistant message's content. Its fields borrow their data.

TextPartReasoningPartRedactedReasoningPartToolPart

This union describes a transcript message. Its fields borrow their data.

UserMessageAssistantMessageCompactionMessage

The final metadata for a stopped reasoning part. Tool parts finalize through tool.state_changed.

ReasoningFinalRedactedReasoningFinal

This union describes the terminal run outcome. The type field selects the outcome.

RunOutcomeTurnRunOutcomeCompactedRunOutcomeSkippedRunOutcomeCanceledRunOutcomeFailed

This union records how the engine created the session.

SessionOriginRootSessionOriginChildSessionOriginFork

This union selects the session relationships that session.list returns.

SessionPopulationTopLevelSessionPopulationChildrenSessionPopulationAll

This result says whether the engine started or queued the input.

SessionSendInputResultStartedSessionSendInputResultQueued

This union records a tool part's lifecycle state. Its fields borrow their data.

ToolStatePendingToolStateRunningToolStateCompletedToolStateErrorToolStateCanceled

A frontend can render this hint natively or ignore it. Its fields borrow their data.

ViewTextViewMarkdownViewJsonViewDiffViewImage

This union carries client request parameters.

AgentsSetModelParamsAgentsUpdateParamsAgentsResolveParamsSessionListParamsSessionGetParamsCreateSessionSessionPatchParamsSessionRemoveParamsSessionForkParamsSessionCompactParamsSessionRewindParamsSessionSendInputParamsSessionCancelInputParamsSessionQueueParamsSessionCancelRunParamsSessionHistoryParamsSessionConfigParamsCatalogListParamsEmptyAuthSetApiKeyParamsAuthLoginParamsAuthCancelLoginParamsAuthRemoveParamsInteractionRespondParams

This union carries server response results.

AgentsGetResultAgentsResolveResultInitializeResultSessionListResultSessionListItemSessionResultEmptySessionCompactResultSessionSendInputResultSessionCancelInputResultSessionQueueResultSessionCancelRunResultSessionHistoryResultSessionConfigResultCatalogListResultCatalogReloadResultAuthListResultAuthLoginResult

This union carries server broadcast data.

SessionSummaryChangedDataSessionActivityChangedDataSessionRemovedDataCatalogChangedDataAuthLoginFinishedDataAuthChangedDataNoticeMessageCommittedDataRunStartedDataRunDoneDataConfigChangedDataTranscriptTruncatedDataMessageStartedDataMessageDiscardedDataMessagePartAddedDataMessagePartDeltaDataMessagePartFinalizedDataToolStateChangedDataToolOutputDeltaDataInputQueuedDataInputCanceledDataInteractionRequestedData

This union carries an RPC response.

ResponseOkResponseError

small

medium

session_busy

concurrency_limit

Workspace execution environment. Advertised engine capability. Numeric JSON-RPC and yuke error codes.

-32602

-32600

-32601

-31000

-31002

-31003

-31004

-31005

-31006

-31009

-31010

-31011

-31012

-31015

-31016

-31017

-31018

-31019

-31020

-31022

-31023

-31024

-31025

-31026

-31027

-31028

-32603

-31021

api_key

oauth

session.summary_changed A session's summary metadata changed.

session.activity_changed A session's activity state changed.

session.removed The engine removed a session.

catalog.changed The model catalog changed.

auth.login_finished The engine finished an authentication login flow.

auth.changed Authentication state changed.

notice The engine sent an out-of-band notice.

interaction.requested An extension asks the connected frontend to interact with the user.

message.committed The engine committed a message to a session transcript.

run.started A run started.

run.done A run finished.

config.changed A session's run config changed.

transcript.truncated The engine truncated older transcript messages.

message.started A new streaming message started.

message.discarded The engine discarded an unfinished message.

message.part_added The engine added a part to a message.

message.part_delta The engine sent more content for a message part.

message.part_finalized The engine attached final metadata to a stopped part.

tool.state_changed A tool call's state changed.

tool.output_delta The engine sent more output from a tool.

input.queued The engine queued an input behind the active run.

input.canceled The engine canceled a queued input.

Run failure category.

interrupted

provider

protocol

network

timeout

rate_limited

quota_exhausted

auth

unknown_model

unsupported_reasoning

max_rounds

context_overflow

runtime

internal

agents.get

agents.update

agents.resolve

agents.set_model

initialize Establish the connection and negotiate the protocol version.

session.list List the sessions.

session.get Read one session with its resident activity, or its durable idle activity.

session.create Create a session.

session.patch Update a session's mutable fields.

session.remove Remove a session.

session.fork Fork a session at a message.

session.compact Compact a session's transcript.

session.rewind Rewind a session to before a message.

session.send_input Send user input to a session.

session.cancel_input Cancel a queued input.

session.queue List the durable queued inputs of a session, oldest first.

session.cancel_run Cancel the active run.

session.history Fetch a page from a session transcript.

session.config Fetch a session's run config.

catalog.list List the model catalog.

catalog.reload Read providers.json again and rebuild the catalog.

auth.list List the local providers and the credential each one holds.

auth.set_api_key Set an API key for a provider.

auth.login Begin a provider login flow.

auth.cancel_login Cancel an active login flow.

auth.remove Remove the credential the engine holds for a provider.

interaction.respond Answer one pending extension interaction.

Notice severity level.

info

warn

error

turn

compaction

nothing_to_summarize

too_few_messages

Assistant stop reason. refusal is a model decline; content_filter is a filter that cut content.

stop

length

content_filter

refusal

tool_calls

canceled

error

unknown

started

queued

Session list view.

active

recent

active_recent

auto

manual

Provider protocol kind.

anthropic_messages

openai_chat

openai_responses

Report whether a configured provider can serve a request now, and why it cannot.

ready

needs_credential No credential reached the engine.

needs_route A route field is missing, so the engine cannot build a request.

expired The grant expired. The user must authenticate again.

project

personal