Expand description
Stable Muse Session Protocol (MSP) wire types.
Serde names equal the stable schema names; use these types and never rename an MSP field or variant by hand.
Structs§
- Admission
Resolution Summary - Winning terminal returned to a losing
admission/decidecommand:resolvedByis omitted on timeout. - Approval
Amendment - Approval
Change - Approval
Choice - Approval
Decide Params approval/decideparams: the decision. A standard command — requires the session loaded on this host, requirescommandId, durable intake before ack, value-identical replay.- Approval
Decide Result approval/decideresult. Admission-ack rules still apply: the authoritative outcome isapproval/resolved/approval/updatedon the view stream.- Approval
List Pending Params approval/listPendingparams: the pull dual of the re-issued requests. A log-fold read — no lease, works on loaded and unloaded sessions, never subscribes.- Approval
List Pending Result approval/listPendingresult. Ordering is by openingviewCursor; empty arrays when nothing is pending. The result is point-in-time — to act on it race-safely,approval/decidecarries therequirementIdguard regardless of how the client learned the state.- Approval
Origin - Approval
Request Params - Full params shared by
approval/requestandapproval/requested. - Approval
Requirement Ref - Approval-stage token carried in the protocol spec params and stale-requirement errors.
- Approval
Resolution Summary - Winning terminal returned to a losing
approval/decidecommand. - Approval
Resolved Params approval/resolvedparams: the first durable terminal decision.- Approval
Stage - Approval
Stage Evidence - Approval
Stage Resolution - Approval
Subagent Origin - Child (native subagent) provenance for an approval projected onto the PARENT
session’s approval plane: identifies the originating child run/agent so a
client can attribute the prompt. Omitted (
skip_serializing_if) on the parent’s own approvals, so pre-existing parent frames stay byte-identical. - Approval
Subject - Open approval subject union. Unknown kinds are rendered generically and never auto-approved by clients.
- Approval
Suggested Prefix - Approval
Updated Params approval/updatedparams: the refreshed pending view plus one change.- Background
Status - The backgrounded-row payload for a running
toolCallitem: the presentation state plus the live status text the row body renders. Experimental — stable clients ignore the member. - Branch
State - The latest branch observation in the snapshot.
- Client
Capabilities - The client’s requested capability posture. Every member defaults; an absent
capabilitiesobject means all defaults. - Client
Info - Client identification inside
initializeparams. Diagnostics and telemetry attribution only; never an authority claim. - Code
Mode Output Span - One public-output span inside the item’s
visibleOutput. - Code
Mode Receipt - Code Mode’s
detailspayload. - Command
Accepted Result - The uniform command acknowledgement: admission only, never an outcome.
session/compactalone may answer"noop"; every other command answers"accepted". - Computer
UseApp - One row of the Settings apps list.
- Computer
UseApp Patch - One per-app choice to set in
computerUseSettings/update. - Computer
UseBlocked App - One row of the Settings blocked-apps list.
- Computer
UseInstalled App - One installed or running app, for Settings’ app picker.
- Computer
UseSettings computerUseSettings/readresult, also answered bycomputerUseSettings/update.- Computer
UseSettings Read Params computerUseSettings/readparams.- Computer
UseSettings Update Params computerUseSettings/updateparams: a patch. Omitted members are left alone; the whole patch applies or none of it does.- Computer
UseSetup Changed computerUseSetup/changedparams.- Computer
UseSetup Read Params computerUseSetup/readparams.- Computer
UseSetup Start Params computerUseSetup/startparams: a human command.- Computer
UseSetup State - The session’s setup state: the result of both methods and the
computerUseSetup/changedpayload’sstate. - Context
Usage - The snapshot
contextUsageblock: the latest(windowTokens, usedTokens, pressure)triple; the snapshot member isnulluntil the fold’s generation chain holds a tracked anchor AND the current basis is present (absent is never fabricated). - Cron
Receipt - Cron’s
detailspayload. - Cron
Receipt Job - One row of the Cron
listreceipt’sjobsarray. - Cumulative
Cost - Server-computed session cost member of
CumulativeTokenUsage. - Cumulative
Token Usage - Session running totals of counted-once usage.
- Damaged
Range damagedRange: what one damaged range of the session log cost. The reader finds the range in the log bytes; no log record is written for it, so every member is derived from the readable records around it.- Effective
Approval Mode State - The effective approval-mode projection: the same object
session/setApprovalModereturns aseffectiveModeand theSessionobject carries asapprovalMode. - Effective
Model - The latest effective-model fact in the snapshot.
- Effective
Permission State - The effective permission-state projection: the committed native permission
snapshot (profile identity, reviewer authority) plus the live per-session
runtime’s attachment evidence. The same object
session/setPermissionProfilereturns and theSessionobject carries aspermissionState. Served values must be coherent: a read never combines an old profile with a newer runtime’s attachment claim. - Error
Data - The optional
error.dataobject. All members additive-optional;kindis always present whendatais. - Error
Object - The
errormember of an error response. - Error
Response - An error response frame. Exactly one of
resultorerrorappears on a response; this type is theerrorhalf. - Feedback
Submit Params feedback/submitparams: mirrors the TUI confirm-timeFeedbackRequest. The call itself is the explicit confirm.- Feedback
Submit Result feedback/submitresult: the upload receipt.- Fork
CutPoint - Where a fork cuts the source history. Turn ids are used instead of counts because ids stay stable across compaction and concurrent appends while indices do not.
- Fork
Provenance - Fork provenance folded from the durable
session.fork.createdrecord. - Goal
- The session goal block.
statusandpercentCompleteare carried verbatim — out-of-contract status strings and >100 percents pass through; display clamping is the renderer’s job. - Goal
Clear Params goal/clearparams. Anobjectivehere is an unknown field and rejects-32602 invalidParams— the bare verbs carry exactly this pair.- Goal
Command Result - The shared goal ack, admission-only: all five verbs answer this one shape,
differing only in when
turnIdis present. - Goal
Edit Params goal/editparams: replace the current goal’s objective. Same shape asgoal/set; the verbs differ in theirmissing_goalprecondition, not their payload.- Goal
Pause Params goal/pauseparams; shape asgoal/clear.- Goal
Resume Params goal/resumeparams; shape asgoal/clear.- Goal
SetParams goal/setparams: set the session’s goal objective.- Hook
Catalog Entry - One installed handler.
- Hook
List Params hook/listparams. Per-session because hook scope follows the session’s workspace and plugin state.- Hook
List Result hook/listresult: one row per installed handler per event — aResolvedHookHandlercarries one event, and grouping would lose matcher/command identity.- Initialize
Params initializerequest params.- Initialize
Result - The
initializeresult. - Item
- One transcript item at one revision.
item/started,item/updated, anditem/completedcarry the full object;item/deltaappends to it by field path. - Item
Completed Params item/completedparams: the item reached its terminal state — the authoritative final object. Always cites a durablesourceRange. Clients MUST acceptitem/completedfor anitemIdthey never sawitem/startedfor.- Item
Delta Params item/deltaparams: a UTF-8-safe streaming append to an open item’s field. Ephemeral-sourced by definition: this params object has nosourceRangemember at all. Deltas never bumprevision.- Item
Read Output Params item/readOutputparams: byte-ranged fetch of stored full output that the view truncated — theoutputReffetch path the protocol’s sections owe. Read-only; works on loaded and unloaded sessions; no lease.- Item
Read Output Result item/readOutputresult: one stored-byte page.- Item
Started Params item/startedparams: a new item opened on the transcript.sourceRangeis absent when the item opens on an ephemeral record (the delta-streamed kinds); the item’s authoritative open is re-stated by its durable-sourceditem/completed.- Item
Updated Params item/updatedparams: an open item changed non-terminally in a way deltas cannot express — the full item re-emitted at a higher revision (apply rule: replace iff higher).- Last
Turn - The last
turn/completedthe session-view fold applied, restated onsession/resumeandsession/readso a reopened session can report a failed last turn. - Media
Upload Params media/uploadparams: one chunk of a client-minted upload. All members required.- Media
Upload Result media/uploadresult: echoes the client-minted id, on every chunk and replay.- Message
Attachment userMessageimage attachment metadata: metadata only — the durable bytes live in the log and are reachable on the raw altitude.- Model
Catalog Entry - One visible catalog row. Catalog rows marked hidden never reach the wire, so a client cannot select one.
- Model
Cost - Per-1M-token catalog cost, carried verbatim for display and never rounded or re-formatted by the host. Cost arithmetic stays client-local view math.
- Model
Described Reasoning Effort - One described reasoning-effort tier of a
model/listrow: a selectable tier plus the catalog’s display string for it when declared. - Model
List Params model/listparams: the discovery half of the model-picker gesture. A query, not a command — nocommandId, no durable intake record, no view event.- Model
List Result model/listresult. A snapshot at call time: v1 has no catalog subscription.modelsMAY be empty — a build shipped with no bundled models is a supported configuration.- Model
Selection - A model selection. Empty strings are normalized to absent.
- Model
Visible Content - Rich content the model saw beyond text: metadata only — fetch bytes via
item/readOutputwhen anoutputRefexists. - Monitor
Inbox Item Admitted Params monitor/inboxItemAdmittedparams: one monitor inbox admission — the fold keys gate-off consumes.- Monitor
Inbox Item Drained Params monitor/inboxItemDrainedparams: one monitor inbox drain — a consumption marker with its recorded stamp.- Monitor
Inbox Item Voided Params monitor/inboxItemVoidedparams: one wake-missed void — count-only, no transcript row.- Notification
- A notification frame, either direction. No
id; a notification is never answered. - Output
Ref - Stored-output reference: the camelCased fold of the durable
ToolOutputRef. The fetch path isitem/readOutput. - Patch
Summary - Server-authored edit-family diff summary:
filescounts the stored patch document’s file entries;addedandremovedare the total+/-prefixed LINE counts summed over the stored patch’s hunks across all files — line counts, never hunk or byte counts. Rides thetoolCallitem besidepatchRef; the body is fetched viaitem/readOutputwithpatchRef.id. - Pending
Approval Pointer - A pending approval in the snapshot: the pointer shape plus the gated
itemIdwhen one exists. - Pending
Request Pointer - A late-joiner pointer at an unsettled server-initiated request. The full
payloads arrive as re-issued server-to-client requests right after a
session/resumeresponse;session/readnever re-issues them. - Pending
User Input Pointer - A pending user-input prompt in the snapshot.
- Permission
Axes - A committed profile’s effective four axis values: the resolved filesystem,
network, approval, and reviewer the YOLO predicate reads. The reviewer
member reuses
ReviewerAuthority, so its spelling never drifts from the servedreviewerAuthority. - Plugin
Catalog Entry - One installed plugin record.
- Plugin
Changed Params plugin/changedparams: an install landed; clients re-issueplugin/list(plushook/listandskill/list).- Plugin
Install Local Path Target - The
plugin/installlocal-path arm. - Plugin
Install Marketplace Target - The
plugin/installmarketplace arm. - Plugin
Install Params plugin/installparams. Per-session params plus a client-generatedcommandId(UUIDv7) with the uniform idempotency contract.- Plugin
Install Result plugin/installresult: the ack envelope plus the installed receipt.- Plugin
Install Target - The one structured install target: a flat object with two optional arms,
exactly one present — the
TurnInputPartconvention, since the v1 schema model names no object-variant union. Both arms or neither is-32602 invalidParams. - Plugin
List Params plugin/listparams. Per-session params; rows are the installed plugin records.- Plugin
List Result plugin/listresult: one row per installed plugin record; the spec promises the set, not an order.- Plugin
Marketplace AddParams plugin/marketplaceAddparams. Per-session params plus a client-generatedcommandId(UUIDv7).- Plugin
Marketplace Changed Params plugin/marketplaceChangedparams: a marketplace was added, updated, or removed.- Plugin
Marketplace Record Result - The stored marketplace record both add and update answer: the ack envelope plus the record.
- Plugin
Marketplace Remove Params plugin/marketplaceRemoveparams. Per-session params plus a client-generatedcommandId(UUIDv7).- Plugin
Marketplace Remove Result plugin/marketplaceRemoveresult: the ack envelope plus the removed name.- Plugin
Marketplace Skipped Entry - One skipped marketplace entry.
- Plugin
Marketplace Source Shape - The normalized stored marketplace source.
- Plugin
Marketplace Update Params plugin/marketplaceUpdateparams. Per-session params plus a client-generatedcommandId(UUIDv7).- Quota
Detail - Typed quota-exhaustion detail: the limit kind plus the provider’s reset instant.
- Reasoning
Effort State - The snapshot’s standing session-default reasoning effort: the fold of the
latest completed
runtime.reasoning_effort_reconfigurefact — the same pairsession/reasoningEffortChangedcarries. - Recap
Cancel Params recap/cancelparams: the session plus the cancel’s own retry id. No target — one in-flight slot per session makes the target unambiguous.- Recap
Cancel Result recap/cancelresult: admission only. In flight → the recap settlescancelled; idle → accepted no-op.- Recap
Completed Params recap/completedparams: the settlement, delivered to the requesting connection outside the view stream — noviewCursor, nosourceRange.textis required oncompleted;reasonis required onfailed; neither ridescancelled/timedOut. The struct marks the conditional members optional; the SS prose pins the per-outcome rule, theturn/completedusage/error convention.- Recap
Request Params recap/requestparams: the session plus the client-minted UUIDv7 retry id. No other param; unknown fields areinvalidParams.- Recap
Request Result recap/requestresult: admission only — the ack is never the recap.- Record
Position - One end of a
SourceRange: a record’s event id and its sequence number within the stream. - Recovery
Observation - One coherent producer snapshot; all members are required and non-null.
- Request
- A request frame, either direction.
- Request
Receipt - The presentation receipt — the client’s response to a server-initiated
request (
approval/request,userInput/request). - Scheduled
Fire Members scheduledFiremembers, flattened into the item row.- Schema
Info - The
schemapair inInitializeResult.versionis the wire envelope schema version — distinct from the session-viewschemaVersion, the raw-logschema_version, and the 0.x/1.0 stability posture, which is not on the wire at all. - Server
Info - Server identification inside
InitializeResult. - Session
- The session object every lifecycle method returns or lists.
- Session
Approval Mode Changed Params session/approvalModeChangedparams: the fold of the durable approval-mode reconfigure audit fact — every accepted change writes one; a mode flip without an audit fact is a runtime bug by design.- Session
Branch Changed Params session/branchChangedparams: a durable workspace-branch observation landed.- Session
Closed Params session/closedparams: a loaded session was unloaded from this host, broadcast to every initialized connection. After it, the session isnotLoaded; the log remains on disk andsession/resumereloads it. A crash emits nothing — only the orderly unload paths do (idle unload, host shutdown and a releasedsession/leave), and each writes the durableSessionEndrecord first.- Session
Compact Params session/compactparams: manually compact the session’s conversation context — the/compactgesture. Compaction runs asynchronously; the ack is admission only.- Session
Compact Result session/compactresult. Failures after admission (summarizer_failed,install_rejected,cancelled) are not wire errors — they arrive as the compaction’s terminal view event.- Session
Config - The open configuration extension object shared by
session/startandsession/resume. - Session
Context Usage Params session/contextUsageparams: context-window pressure — the counted-once occupancy at the latest provider-reported durable fact, joined with the host’s pressure basis. Replace wholesale; emitted only when the(windowTokens, usedTokens, pressure)triple changes value (identical adoptions emit nothing).- Session
Fork Params session/forkparams.- Session
Fork Result session/forkresult: thesession/resumeenvelope for the new session, whosesession.forkedFromcarries the provenance.- Session
Goal Changed Params session/goalChangedparams: the projected goal block’s value changed — identical adoptions emit nothing (the change gate), and an explicitnullclears. Replace wholesale;nullnever means unchanged.- Session
History - The
historyenvelope shared bysession/resume,session/fork, andsession/read. - Session
Leave Completed Params - Params of the protected, non-view leave terminal notification.
- Session
Leave Failure Reason - Current producer failure reasons for
session/leaveCompleted; receiver-open for additive future reasons. - Session
Leave Outcome - Current producer outcomes for
session/leaveCompleted; receiver-open. - Session
Leave Params session/leaveparams.- Session
Leave Result - The admission-only
session/leaveresult. - Session
List Branch Filter - Exact branch selection.
- Session
List Changed Params session/listChangedparams: one changed row of thesession/listshape — the full Session object as the answering host’s list face serves it at emission, a replace, never a delta. Emitted only on connections that negotiated thesessionListStreamcapability atinitialize; row birth stays onsession/started, unload pairs withsession/closed.- Session
List Filter - The
session/listfilter. Members are ANDed with each other and with the top-levelworkspaceRootandupdatedAfter; values inside eachanyOfare ORed. The canonical form the server echoes deduplicates and sorts every set, spells session IDs as canonical UUIDs, lowercases text terms, and orderstext.fieldsnamethentitle. - Session
List Params session/listparams. Read-only; never touches leases.- Session
List Result session/listresult. Ordering isupdatedAtdescending.- Session
List Session IdFilter - Exact session-ID selection.
- Session
List Text Filter - Name/title token-prefix search. Each term is trimmed, lowercased with
ordinary Unicode lowercase, then NFC- normalized, and matches the beginning
of an alphanumeric token, accent-sensitively (
checkmatchesCheckout;eckdoes not). NFC means a decomposed and a precomposed spelling of one term are the same term, and the echo returns the composed form. Matching never reorders rows. - Session
Model Changed Params session/modelChangedparams: a durable model-selection record landed.- Session
Model Route Unserved Params session/modelRouteUnservedparams: an acceptedlogin.credential_updateinstalled a provider that cannot serve the session’s STANDING model route. Disclosure only — the standing selection is unchanged (nosession/modelChangedfires) and the repair path is a routablesession/setModel. Folded from the durableruntime.provider_reconfigure.standing_route_unservedrecord; additive — clients that predate it skip the unknown method.- Session
Name Changed Params session/nameChangedparams: the fold of ANY durable session-name record — the FIRST-NAMING automatic allocate as well as an acceptedsession/rename(or the same in-process runtime command). Replace-wholesale like every sibling.- Session
Read Params session/readparams: read one stored session without attaching — no writer lease, no load, no subscription, noSessionResumedrecord.- Session
Read Result session/readresult. TheviewCursoris the fold head at read time — a point-in-time read, immediately stale if a foreign host is appending.- Session
Reasoning Effort Changed Params session/reasoningEffortChangedparams: a durable reasoning-effort reconfigure record landed. Replace wholesale, latest wins; the snapshot carries the latest value.- Session
Rename Params session/renameparams: set or change the durable allocated session name through the runtimesession_namecommand. One writer; withheld under the ephemeral profile.- Session
Rename Result session/renameresult:nameis the canonical (normalized) name the durable record settled.- Session
Resume Params session/resumeparams.- Session
Resume Result session/resumeresult.- Session
SetApproval Mode Params session/setApprovalModeparams: switch the session’s approval enforcement mode mid-session. A standard command.- Session
SetApproval Mode Result session/setApprovalModeresult. Applies next-action — an in-flight tool action’s pending approval is not retroactively decided by a mode change.- Session
SetModel Params session/setModelparams: the model-picker gesture. The selection is durable and applies to subsequent model calls.- Session
SetModel Result session/setModelresult. If a turn is running the selection is admitted now and applied at the next model-call boundary; the ack does not wait for that boundary.- Session
SetReasoning Effort Params session/setReasoningEffortparams: set the session’s standing reasoning-effort default. A turn carrying its ownreasoningEffortoverrides it for that turn only; the default overrides the host’s configured default. Same accept/reject andcommandIdidempotency shape assession/setModel.- Session
SetReasoning Effort Result session/setReasoningEffortresult. The default is durable on ack and applies to turns launched after admission; a running turn keeps the request options it already resolved.- Session
Side Chat Params session/sideChatparams.- Session
Side Chat Result session/sideChatresult: thesession/resumeenvelope for the new side session, whosesession.sideFromcarries the provenance. The side opens empty.- Session
Start Params session/startparams.- Session
Start Result session/startresult.- Session
Started Params session/startedparams: a session became newly loaded on this host viasession/start,session/fork, orsession/sideChat, broadcast to every initialized connection.- Session
Status Changed Params session/statusChangedparams: a loaded session’s projected(status, attention)value flipped. A command-plane broadcast — delivered to every connection regardless of its view subscription set, never gated, nosourceRange; the same facts live on the Session object, which is how a client seeds its table (no initial burst on connect).- Session
Todo List Changed Params session/todoListChangedparams: aTodoSnapshotUpdatedrecord landed. Replace the whole list on every event; an emptyitemsarray is a cleared list, not a no-op.- Session
Token Usage Params session/tokenUsageparams: one per model completion that reports usage. Carries the raw counters verbatim plus the server-derived counted-oncepromptTokens/totalTokensand the sessioncumulativeblock. Accumulate-only:cumulativenever goes backward.- Session
User Shell Params session/userShellparams: run a user-initiated shell command in the session’s workspace — the TUI’s!escape hatch. Capability-gated: the connection must negotiateuserShellatinitialize, and the whole justification is the spawn boundary.- Session
User Shell Result session/userShellresult: immediate. The shell runs off the command worker so a long command cannot stall the command plane; the output arrives as theuserShellitem’s terminal view event.- Session
View Health Changed Params session/viewHealthChangedparams: the named session’s live view stream became unavailable, and why.- Session
Worktree - The Session
worktreemember: path and origin only — the branch stays in the existingbranchmember. - Side
Provenance - Side provenance folded from the durable side provenance.
- Skill
Catalog Entry - One typed-invocable shortcut spelling. A plugin skill may contribute two
rows: its bare-name winner and its qualified
<pluginId>:<skillId>form. - Skill
Changed Params skill/changedparams: the session’s user-invocable set changed; clients re-issueskill/list. Advisory — the host may coalesce bursts and guarantees no ordering relative to view events.- Skill
Import Counts - The four receipt-list lengths: a client renders counts without walking lists.
- Skill
Import Failure - One import candidate that could neither install nor quarantine: recorded so
the run continues past it.
idis null when the candidate never yielded one — present-but-null, never omitted. - Skill
Import Params skill/importparams: import foreign skills through the singleSkillsService::import_skillsseam.- Skill
Import Quarantine - One quarantined import candidate: kept, not loaded.
- Skill
Import Result skill/importresult: the ack envelope plus the service receipt projection.- Skill
List Params skill/listparams. Per-session because skill scope follows the session’s workspace and plugin state.- Skill
List Result skill/listresult: one row per typed-invocable shortcut spelling — exactly the invocations the first-party typed dispatch accepts.- Skill
SetActivation Params skill/setActivationparams: turn one skill on or off in any scope through the singleSkillsService::set_activationseam.- Skill
SetActivation Result skill/setActivationresult: the ack envelope plus the applied state.- Snapshot
Anchor - The compaction boundary an anchored snapshot is anchored at.
- Snapshot
State - The complete folded view at the snapshot cursor.
- Source
Range - The inclusive raw-record range a durable-sourced view event folded from —
the reconciliation token: re-folding the cited records from the canonical
fold state immediately before
first— appended host-death terminals seed from the end-of-records state — reproduces the event. In v1 it is an opaque provenance token: no wire method reads what it points at. - Status
Attempt toolCall.statusAttempt: the latestTaskExternalAttemptDetail, field-for-field — countdown inputs the client renders the tick from, so no event spam.- Status
Children toolCall.statusChildren: the latestTaskChildSummaryDetail, field-for-field.- Status
Health toolCall.statusHealth: the latestTaskHealthDetail, field-for-field.- Status
Progress toolCall.statusProgress: the latestTaskProgressDetail, field-for-field.- Status
Step toolCall.statusStep: the latestTaskActiveStepDetail, field-for-field.- Stream
Ref - One raw stream named by a
SourceRange. - Subagent
Input Params - Params for
subagent/sendMessageandsubagent/followupTask: a child target plus the input body. - Subagent
Owner Reason Params - Params for
subagent/interrupt,subagent/stop, andsubagent/close: a child target plus an optional human-readable reason that is preserved on the durable effect record. - Subagent
Result - A subagent’s result envelope.
- Subagent
Target Params - Params for
subagent/resume,subagent/reopen, andsubagent/readResult: the bare child target. - Subscription
Usage - The one usage payload shape: the
usage/readresult’susagemember and theusage/changedparams. The numbers are point-in-time —observedAtMsis the host’s arrival stamp, so a client renders “as of”, never implies live data. - Subscription
Usage Weekly - The rolling weekly block: same semantics as
SubscriptionUsageWindowwithout a duration. - Subscription
Usage Window - The current usage window (the provider’s 5-hour-class block): verbatim provider percentages with the reset stamp normalized to epoch milliseconds.
- Success
Response - A success response frame.
- Task
Background Params task/backgroundparams: durably send a running foreground tool task to the background.- Task
Command Result - The
task/background/task/stopack: admission-only, echoing the targeted task. - Task
List Entry - One background-task inventory row. The row is the stable contract:
kindandstatusstay open so a future state extends them without breaking clients. - Task
List Params task/listparams: the session whose background-task inventory to read. A read-only query in theskill/listmold: nocommandId, no durable record, no view event.- Task
List Result task/listresult: one row per running background workload intask/stopAllreach, oldest first; empty when nothing is running.- Task
Stop AllParams task/stopAllparams: stop every stoppable background workload live at admission.- Task
Stop AllResult - The
task/stopAllack: alwaysaccepted, including over an empty set — a blanket stop over nothing is a satisfied gesture. The ack deliberately carries no stopped-task list; count the kills from the view. - Task
Stop Params task/stopparams: stop one named background task. Required target, never “whichever is loudest” — is the blanket verb.- Todo
Item - One todo entry.
- Todo
List State - The latest todo-list fact in the snapshot.
- Token
Usage - Raw token counters, verbatim from the durable record. Not directly summable across providers — sum the counted-once derivations instead.
- Tool
Call Members toolCallmembers, flattened into the item row.- Tool
Display Label toolCall.displayLabel: the call’s words in three forms, each one line of plain text, always present together. The item’sstatuspicks the form.- Tool
Receipt - The shared
toolReceiptcontainer. - Trace
Context - Optional W3C trace context, on requests in both directions only — never on responses or notifications.
- Turn
Cancel Params turn/cancelparams: plain cancellation on the normal command lane. Same shape asturn/interrupt, withoutretract— pairing a retract with a plain cancel is durably rejectednot_paired_interrupt.- Turn
Cancel Result turn/cancelresult: identical envelope toturn/interrupt.- Turn
Completed Params turn/completedparams: the run’s durable terminal record landed.- Turn
Error - The settled turn-failure object:
{kind, message, retryable}. - Turn
Foreground Completed Params turn/foregroundCompletedparams: the turn’s foreground work is done and named background reminder checks hold the turn open. Explicitly non-terminal: the turn ends only atturn/completed/turn/unqueued.- Turn
Input Part - One ordered content part of a turn submission. File mentions are text, not a
part type: write
@relative/pathin a text part. A structuredmentionpart is reserved and currently rejected, and an unknown part type isinvalidParams— which is what closesTurnInputPartType. - Turn
Interrupt Params turn/interruptparams: the “user pressed stop” gesture, on the runtime’s priority lane.- Turn
Interrupt Result turn/interruptresult. Acceptance means the interrupt was admitted, not that the turn is already stopped: the turn is over when you fold itsturn/completedwith terminalcancelled.- Turn
Model Retry Scheduled Params turn/modelRetryScheduledparams: a durable model-stream retry-scheduled fact folded — the provider backoff behind one model attempt is observable BEFORE the turn terminates, so a streaming client can render “system words · retrying in Ss · attempt N/M” instead of dead air. Non-terminal: it never resolves a turn-wait. The siblingturn/retryScheduledshape at the model layer: same member names and semantics (attempt/nextAttempt/maxAttempts/ retryDelayMs/system/errorKind/httpStatus), minusreason— the row’s words derive fromerrorKindthrough the shared gate-off mapping, and the recorded machine message is not user text. The delay is the recorded scheduled backoff, never an absolute fire time — clients derive any countdown locally.sourceRangecites the session stream’s mirror of the task-lifecycle record.- TurnRef
- A turn named by the snapshot’s active/queued lists.
- Turn
Retracted Params turn/retractedparams: an interrupt-paired retract durably settled, accepted or declined. On"accepted"the retracted user-message item is re-emitted viaitem/updatedwithretracted: true; on"declined"the client folds the legacy declined rollback instead and no item is re-emitted.- Turn
Retry Scheduled Params turn/retryScheduledparams: a durable turn retry-scheduled fact folded — the failing model attempt’s scheduled retry is observable BEFORE the turn terminates, so a streaming client can render “attempt N/M · retrying in Ss · reason” instead of dead air. Non-terminal: it never resolves a turn-wait. The delay is the recorded scheduled backoff, never an absolute fire time — clients derive any countdown locally.sourceRangecites the session stream’s mirror of the task-lifecycle record.- Turn
Start Params turn/startparams.- Turn
Start Result turn/startresult.- Turn
Started Params turn/startedparams: a foreground turn began running — fresh submits immediately, queued submits at their launch boundary, never steered submits.- Turn
Steer Params turn/steerparams: exact-target steering into the currently running turn.- Turn
Steer Result turn/steerresult.- Turn
Unqueue Params turn/unqueueparams: reclaim a queued submit before it launches. It is not a stop — a reclaim that arrives after its target launched is durably rejected, never silently upgraded into a cancel.- Turn
Unqueue Result turn/unqueueresult. Admission only — but for this command admission is the race: an admitted reclaim implies the turn will not launch. The authoritative removal is theturn/unqueuedview event.- Turn
Unqueued Params turn/unqueuedparams: a queued submit’s reclaim durably won; its pre-minted turn never runs. Carries the reclaimedturnIdand thecommandIdof theturn/startthat queued it, so a client can restore the submission’s text exactly as forturn/retracted. Noturn/started/turn/completedis ever emitted for thisturnId.sourceRangecites the SESSION stream’s reclaim record — a reclaimed turn never had a run stream.- Turn
User Shell - The queued
!shell action aturn/startcarries: the!cmdtyped while a turn runs. The shell’s command id derives from the carrying turn’scommandId, exactly as the app’s own queued submit does; the params’ siblingdisplayTextcarries the!…presentation form. - Unframed
View Notification - One element of a
view/pageresult’seventsarray: an unframed view notification exactly as the protocol spec defines it — the nested pair{"method", "params"}, which is the live notification minusjsonrpcandemittedAtMs, with nothing lifted out ofparamsand nothing spliced into it. the protocol spec is the single normative definition; the protocol’s sections both cite it, so the two surfaces cannot drift. - Unframed
View Notification Params - The
paramsof an unframed view notification. - Usage
Read Result usage/readresult:{usage?}— omitted, nevernull, when the host has observed nothing.- User
Input Answer - User
Input Answer Params userInput/answerparams: answer every question.- User
Input Answer Result userInput/answerresult.- User
Input Cancel Params userInput/cancelparams: decline to answer; the tool call resolves with a cancelled result the model sees.- User
Input Cancel Result userInput/cancelresult.- User
Input Clarification - User
Input Clarify Params userInput/clarifyparams: answer with a free-form clarification instead of the structured options — the “let me explain” path; the model receives the clarification text and re-decides.- User
Input Clarify Result userInput/clarifyresult.- User
Input Engaged Params userInput/engagedparams: a fire-and-forget engagement note — the user started interacting with a timed prompt, so the host disarms that prompt’s auto-resolution countdown. No result, no errors, nocommandId, no ledger row.- User
Input Interrupt Params userInput/interruptparams: interrupt the named prompt carrying confirmed partial answers, then stop the turn.- User
Input Interrupt Result userInput/interruptresult.- User
Input Option - User
Input Option Preview - User
Input Question - User
Input Request Params - Full params shared by
userInput/requestanduserInput/requested. - User
Input Selection - User
Input Settled Params userInput/settledparams: the first durable prompt settlement.- User
Input Settlement Summary - Winning terminal returned to a late user-input command.
- View
GapParams view/gapparams: push delivery dropped events, and this names the hole.- View
Page Params view/pageparams: cursor-paged reads of the session view.- View
Page Resolved Anchor - The
resolvedAnchorecho: subsequent pages pass ordinary cursors, so the anchor never needs re-resolving. - View
Page Result view/pageresult.- View
Snapshot - The
snapshotobject returned bysession/resume/session/read. - View
Subscribe Params view/subscribeparams: attach this connection’s live view subscription for a session at an explicit cursor — the fine-grained counterpart of the auto-subscribe, and the gap-free re-attachment path afterview/unsubscribe. It never loads a session, takes no lease, writes nothing.- View
Subscribe Result view/subscriberesult.- View
Unsubscribe Params view/unsubscribeparams: remove this connection from the session’s view subscription set — the protocol’s single unsubscribe operation, at the altitude that owns subscriptions. It does not unload the session; unloading is the idle policy.- View
Unsubscribe Result view/unsubscriberesult: the empty object. Idempotent — unsubscribing while not subscribed returns{}.- WebSearch
Hit webSearch: one typed result hit — result schema v1.- Workflow
Cancel Params workflow/cancelparams: cancel a live workflow run.- Workflow
Child - One workflow child’s folded state, keyed by
(childId, attempt). - Workflow
Child Control Params workflow/childControlparams: skip or retry one workflow child, keyed by the(childId, attempt)pair theworkflowitem’schildren[]carries.- Workflow
Control Result - The shared admission-only ack: deliberately bare
{commandId, status}— settlement arrives as the workflow item’s view events, never through the ack. - Workflow
Pause Params workflow/pauseparams: pause a live workflow run, shaped exactly likeworkflow/cancel.- Workflow
Resume Params workflow/resumeparams: resume a paused workflow run, host-driven.- Workflow
Resume Result workflow/resumeresult: admission-only plus the driven turn — always present, since resume always drives (idle fresh turn or busy steer).- Workflow
Token Budget workflow: the run’s launch token budget.
Enums§
- Approval
Amendment Durability - Approval
Choice Scope - Approval
Decision - Approval
Mode - The approval enforcement modes. Closed by design: a client selects a preconfigured mode and can never construct one; widening this enum is a deliberate, gate-visible protocol change.
- Approval
Mode Apply Outcome - Whether a mode change did anything, mirroring
ApprovalReconfigureApplyOutcome. Apply failures arecommandRejected. - Approval
Mode Source - How an approval mode took effect. Open.
- Approval
Persistence Status - Approval
Policy Result - Approval
Resolved By - Attention
Flag - One attention flag: a pending server-initiated request class parked on the session. Open on the wire — clients MUST ignore unknown values; future attention kinds are additive.
- Background
Initiator - Who durably backgrounded a task. Open — runtime vocabulary.
- Background
State - Presentation state of a backgrounded running tool item. Open — new states
are additive. Asserts presentation only, never durable backgrounding (that
claim stays
Item::background, set only behind a durableTaskBackgrounded). - Capability
Name - A grantable capability name. Open: the reserved
rawLogentry joins this domain as an additive open-enum extension when the protocol spec un-defers — closed would make that a retype. - Code
Mode Language - The language a Code Mode cell ran in. Open: values are lowercase VS Code
language identifiers, and only
javascript(the V8 engine) is minted today. - Code
Mode Output Stream - What a Code Mode output span’s bytes are. Open: each engine mints its own values.
- Command
AckStatus - The ack-status vocabulary:
"accepted"for every admitted command;session/compactalone may answer"noop". Closed: the protocol spec names exactly these two values, so SDK clients get a discriminated type and validation catches a wrong status — and a client that received a third value would have been told nothing it can act on, unlike [TurnStartDisposition], where “acked, not otherwise classified” is a usable reading. - Command
Status - The ack
status:acceptedfor every admitted command.session/compactis the one method that may additionally answernoop(crate::msp::method::runtime::CompactStatus); no other command uses another status. - Compact
Status session/compact’s ack status: the one method that may answernoopin addition to theaccepted. A noop is a success, not an error, and it is durably settled like any other outcome.- Compaction
Outcome - Compaction outcome. Open.
- Compaction
Trigger - What initiated a compaction. Open.
- Computer
UseApp Choice - A per-app choice. Open, like
ComputerUseChoice. - Computer
UseApp Lock - Why Settings can’t change a row. Open.
- Computer
UseChoice - A capability dropdown’s value. Open: the read result carries it, so an older client tolerates a value it does not know.
- Computer
UsePermission - One macOS permission as setup last saw it. Open, like the phase.
- Computer
UseSetup Phase - Where the session’s setup stands:
cua_setup’s state codes, camelCase. Open: a result vocabulary, so an older client tolerates a new state. - Context
Pressure Level - Context pressure level: hard threshold first, both inclusive
>=. Open. - Error
Kind - A stable
error.data.kindcategory: camelCase, the value clients branch on. Open: the protocol spec lanes add kinds additively as their methods land, and the spec’s edge-case rule makes a newkindadditive only because this domain is declared open. - Feedback
Classification feedback/submitclassification: the four TUI classes in camelCase wire spelling. Closed: a client-selected param vocabulary.- Feedback
Submit Outcome feedback/submitresultoutcome: how one confirmed submit resolved, mirroring the TUIFeedbackSubmitOutcometaxonomy. Open: a server-produced result vocabulary — an older client reading a newer value it does not know follows the open-enum tolerance rule instead of rejecting it.- History
Mode - What history a lifecycle result actually served. Open on the client side: report-what-was-served means a client treats an unknown mode as “page it yourself”.
- History
None Reason - Why a result served
history.mode: "none"— the owning spec typed unavailability. Open on the client side: an absent (older server) or unknown (newer server) value decodes conservatively as an unknown reason, andviewCursortext never substitutes for it. - History
Preference - The
historyrequest preference ofsession/resume. The forced values downgradeanchored→inline→snapshot→none; underautothe full rung order is anchoredSnapshot → inline → snapshot → elided snapshot → none. - Hook
Event Name - Hook event names: the lowercase-first-letter spelling of every
HookEventKind::all()variant. Open: a future event value is additive. - Hook
Handler Kind - A hook row’s origin: the config
HookSourceKindvalues plus plugin-contributed. Open: a future origin is additive. - Hook
RunStatus hookRundurable outcome. Open: new outcomes are additive, and clients MUST render unknown values generically.- IfBusy
- Disposition when a turn is already running. The wire default is
queue: an SDK caller who has not looked at session state should not silently mutate an in-flight turn. - Item
Kind - The eleven v1 item kinds plus post-v1 kinds. Open: a new kind is additive evolution, and clients MUST render unknown kinds generically.
- Item
Read Output Encoding - The
item/readOutputcontent encoding. Closed: text media is ALWAYSutf8and binary mediabase64; a third value would change the client’s decode contract. - Item
Status - Item status. Open; terminal = anything other than
"inProgress", and unknown values are terminal-unknown, rendered generically. - Json
RpcVersion - The literal
"2.0"every frame carries. - Limit
Kind - Quota limit kinds: open for evolution.
- Message
Phase agentMessage.messagePhase: the phase the model declared on the commit, never inferred from position. Set on the completed item only; absent onitem/started, which opens before the phase is recorded. Open: a client reads an absent or unknown value on a completed item as"finalAnswer"and still decodes the item. Not a turn-done signal;turn/completedis.- Model
Catalog Source - Where a model catalog came from. Open: an unrecognized value is an unknown source, not an error.
- Model
Change Source - What drove a model selection. Open.
- Model
Reasoning Effort Variants - A complete ordered effort set, or an explicit unknown capability.
- Output
RefAvailability - Whether a stored output’s bytes are servable. Open — durable runtime vocabulary may grow additively.
- Pending
Request Kind - The
pendingRequestsdiscriminator. Open enum, v1 valuesapprovalanduserInput. - Permission
Approval Axis - A profile’s effective approval axis. Open: the vocabulary can widen.
- Permission
Filesystem Axis - A profile’s effective filesystem axis. Open: the vocabulary can widen.
- Permission
Network Axis - A profile’s effective local-command network axis. Open: the vocabulary can widen.
- Platform
Family - The server runtime’s platform family; may differ from the client’s. Closed: the protocol spec fixes the value set, so widening it is a deliberate, gate-visible protocol change rather than a silent addition.
- Platform
Os - The server’s operating system. Closed, for the same reason as
PlatformFamily. - Plugin
Install Scope - The
plugin/installlocal-path scope. Closed: an unknown scope is-32602 invalidParams. - Plugin
Marketplace Change - What happened to a marketplace. Closed: an unknown change is a contract violation, never tolerated.
- Plugin
Source - A plugin row’s source provenance: camelCase of
PluginSourceProvenance. Open: a future provenance is additive. - Reasoning
Effort - The reasoning-effort tier sampled at submission. The same closed tier
vocabulary on both the fresh-turn and steer lanes, spelled identically;
invalid tiers are invalid params.
noneis a tier of the vocabulary (ask for no reasoning), not a way to say “unset”. - Reasoning
Effort Change Source - What drove a reasoning-effort default change. Open; v1’s only producer is
user(an acceptedsession/setReasoningEffort). - Recap
Failure Reason recap/completedfailure reason: post-ack failures fold to the single initial value. Open: later splits stay additive.- Recap
Outcome recap/completedoutcome: the terminal vocabulary, camelCase per the protocol spec. Open: a server-produced result vocabulary.- Recovery
Effective Source - Proven effective-choice provenance, independently of input presence.
- Recovery
Mode - A requested construction choice; omission is distinct from explicit OFF.
- Recovery
Observed Mode - A proven mode or unknown; future strings cannot establish OFF.
- Recovery
Qualification - This construction’s assessment, never an operation acceptance receipt.
- Request
Id - A request id: client-chosen string or integer.
1and"1"do not compare equal; each direction owns its own id space. - Retract
Outcome - A
turn/retractedsettlement outcome. Open enum: decode is tolerant — a value outside the list reads asAccepted(the event’s historical meaning — pre-feature hosts emit it only for accepted retracts), never fails. The bundle keeps enumerating the known values for codegen and docs. - Reviewer
Authority - A profile’s selected reviewer authority. Open: the reviewer vocabulary can widen.
- Sandbox
Availability - Whether this host can enforce the sandbox. A property of the host process, probed once at construction and identical for every session and every connection it serves — never requested, granted, or negotiated, which is why it is not a capability. Open: a future enforcement posture arrives as a new value, read by older clients as unknown.
- Sandbox
Unavailable Reason - Why sandbox enforcement is impossible on this host. Sent only when
SandboxAvailabilityisunavailable; a client MUST NOT infer a reason when none is sent. Open: a future reason arrives as a new value, read by older clients as unknown. - Session
Closed Reason - The closed-reason vocabulary. Server-produced and published OPEN by owner ruling — the menu-B pick, which settles that this notification reason enum publishes open rather than resting on the result-vocabulary rule by analogy. A crash is deliberately not a reason, because a crash emits no notification at all.
- Session
Durability - Whether this host writes its sessions to disk. A property of the host process, fixed at construction and identical for every session and every connection it serves — never requested, granted, or negotiated, which is why it is not a capability. Open: the unrepresented degraded state has candidate resolutions that add a third value here, so closed would make that a breaking change.
- Session
Kind - What kind of session this is.
- Session
List Text Field - A served session field
session/listtext search reads. The client selects it, so the set is closed. - Session
McpServer Config - One native MCP server supplied at session construction.
- Session
McpServer Mode - Startup failure posture for a session MCP server.
- Session
McpStdio Framing - Stdio framing choices exposed by session MCP configuration.
- Session
Name Origin - How the served session name was set. Open enum (
x-msp-openness: open): v1 servesautomaticandcustom; a client MUST read absent — and any value it does not recognize — as unknown, never fabricated. Open: a future source such as conversation-generated names adds a value here, so closed would make that a breaking change. - Session
Status - A session’s load state.
- Session
View Health - The view-health state. Open enum (
x-msp-openness: open): a client MUST ignore an unrecognized value. v1 emits onlyUnavailable; openness itself reserves additive room for a future re-arm and for the durable-degraded axis, so no never-emitted token is baked onto the stable surface now. - Skill
Activation Scope skill/setActivationactivation target. Closed: a client-selected write vocabulary — a write must fail a scope the host does not implement rather than record activation against an unknown target. Contrast the open read-sideSkillSource.- Skill
Activation State - The three-state skill activation. Closed: a client-selected write vocabulary.
- Skill
Import Source skill/importforeign ecosystem. Closed: a client-selected write vocabulary — a write must fail an ecosystem the host does not implement rather than import from an unknown dir. The host resolves its own foreign dir (theforeign_skills_sourcesderivation); no client paths cross the wire.- Skill
Invocation Source - A
skillinput part’s picked-copy source: the catalog-rowsourceenum values, sent by the TUI on every skill submit so the host resolves the exact(selector, source)row. Closed: a client-selected write vocabulary — an unknown value isinvalidParams, never a fall-through to the bare row. Contrast the open read-sideSkillSource. - Skill
Source - A skill row’s source scope: the projection of the skills crate’s
SkillsSourceScope. Open: a future scope value is additive. - Status
Health Level toolCall.statusHealth.level: the durableTaskHealthLevelvocabulary verbatim. Open — runtime vocabulary may grow additively, and clients MUST render unknown levels generically.- Subagent
Control Status - Subagent control status. Open; the generic item
statusis the terminal authority. - Task
List Status - A task row’s status. Open: a future state is additive, and clients MUST ignore unknown statuses.
- Todo
Status - Todo status: closed in the runtime, wire-open.
- Tool
Receipt Body - The family-selected body of a receipt: the
familydiscriminator and the onedetailsobject whose shape that discriminator chooses. - Tool
Receipt Operation - Which operation within the family the receipt describes. Open — registered per family, never derived from the tool name.
- Tool
Receipt Outcome - What the operation did. Open, and a single shared vocabulary: a value
appearing in two families means the same thing in both, which is why the
permitted
statusvalues are bound to the value here rather than per family. - Turn
Error Kind - Turn failure classes. Open.
- Turn
Input Part Type - The
typediscriminator of a turn input part. Closed: an unknown part type isinvalidParams. - Turn
Start Disposition - What
turn/startdid with the input. Resolves OQ-H in v1: sincequeueis the defaultifBusy, clients need to distinguish these without folding history. - Turn
Terminal - Turn terminal vocabulary: exactly the runtime’s
RunTerminalKind— closed in the runtime, wire-open for evolution. - Unknown
Model Reasoning Effort Variants - The only scalar alternative to a known effort array. Kept as a closed singleton so arbitrary strings and uppercase spellings fail decoding.
- User
Input Outcome - User
Input Selection Mode - Vcs
- Version-control system of a branch observation. Open.
- View
Page Anchor - The
view/pagerequest-mode anchor. Declared open: the protocol spec spells it “open string enum, v1 valuelatestCompaction”. - View
Page Direction - The
view/pagepaging direction. Closed: the protocol spec spells exactly two values and a third would change the paging contract. - Workflow
Child Action - Which control to apply to the child’s current attempt. Closed on the wire:
an unknown value is
-32602 invalidParams. - Worktree
Origin - Where a session’s worktree came from:
createdmeans the host allocated it for the session,attachedmeans the host bound a caller-provided worktree. - Worktree
Start Request session/startworktreeparam: absent means no worktree — the start proceeds exactly as today. Adjacently tagged onmode: a create carries an optionalbaseRef, an existing carries a requiredpath(omittedpathfails decode — the pre-existing invalid-params class, never a new message).
Constants§
- GENERATED_
FINGERPRINT - Fingerprint of the stable schema these types were generated from; the SDK pin test checks it against the committed manifest.