Skip to main content

Module msp

Module msp 

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

AdmissionResolutionSummary
Winning terminal returned to a losing admission/decide command: resolvedBy is omitted on timeout.
ApprovalAmendment
The policy rule a decision created, in display form; the full rule is not included.
ApprovalChange
The change an approval/updated event reports. kind says what happened, and only the fields for that kind are present.
ApprovalChoice
One option the server offers for deciding an approval. Clients pick one and send its choiceId in approval/decide; they never build their own.
ApprovalCuaCardFacts
One Computer Use card’s facts. Empty collections and absent rows are omitted, never null.
ApprovalCuaPage
The page’s full host, no path or query.
ApprovalCuaPoint
A point in the model’s 0–1000 coordinates.
ApprovalCuaStep
One consequential step. A client renders “Step N: “
ApprovalDecideParams
approval/decide params: the decision. A standard command — requires the session loaded on this host, requires commandId, durable intake before ack, value-identical replay.
ApprovalDecideResult
approval/decide result. Admission-ack rules still apply: the authoritative outcome is approval/resolved / approval/updated on the view stream.
ApprovalListPendingParams
approval/listPending params: the pull dual of the re-issued requests. A log-fold read — no lease, works on loaded and unloaded sessions, never subscribes.
ApprovalListPendingResult
approval/listPending result. Ordering is by opening viewCursor; empty arrays when nothing is pending. The result is point-in-time — to act on it race-safely, approval/decide carries the requirementId guard regardless of how the client learned the state.
ApprovalOrigin
What triggered a tool action, shown so the user can judge it. It is display-only and untrusted, and policy rules never match on it.
ApprovalRequestParams
Full params shared by approval/request and approval/requested.
ApprovalRequirementRef
Identifies one requirement of an approval: for a shell approval, one stage. A client sends it back as requirementId in approval/decide, and a stale-requirement error names the current one.
ApprovalResolutionSummary
Winning terminal returned to a losing approval/decide command.
ApprovalResolvedParams
approval/resolved params: the first durable terminal decision.
ApprovalStage
One stage of a shell approval: a single command from the pipeline or command list, approved separately from the others.
ApprovalStageEvidence
How one stage of a shell approval was resolved when the decision became final.
ApprovalStageResolution
Whether a shell stage still needs a decision, or how it was satisfied. Satisfied stages are included so a client can show progress.
ApprovalSubagentOrigin
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.
ApprovalSubject
Open approval subject union. Unknown kinds are rendered generically and never auto-approved by clients.
ApprovalSuggestedPrefix
A suggested always-allow rule for a shell stage: commands starting with argvPrefix would run in this workspace without asking.
ApprovalUpdatedParams
approval/updated params: the refreshed pending view plus one change.
BackgroundStatus
The backgrounded-row payload for a running toolCall item: the presentation state plus the live status text the row body renders. Experimental — stable clients ignore the member.
BackgroundTerminalCompletion
backgroundTerminalCompletion: the five facts the Finished cell renders. The fold reads them from the inbox terminal record and the backgrounded call it names; every member is required (empty output serializes as "", never absent).
BlockedPrompt
The cold recall seed on session/resume and session/read results: at most one, the latest blocked Main prompt — exactly the host’s mirror of prompt_recovery::replay::ReplayInput’s choice.
BranchState
The latest branch observation in the snapshot.
CheckpointBoundary
A served checkpoint-prune boundary: through_item_id names the last first-opened item that opened strictly before the boundary checkpoint event.
ClientCapabilities
The client’s requested capability posture. Every member defaults; an absent capabilities object means all defaults.
ClientInfo
Client identification inside initialize params. Diagnostics and telemetry attribution only; never an authority claim.
CodeModeOutputSpan
One public-output span inside the item’s visibleOutput.
CodeModeReceipt
Code Mode’s details payload.
CommandAcceptedResult
The uniform command acknowledgement: admission only, never an outcome. session/compact alone may answer "noop"; every other command answers "accepted".
ComputerUseApp
One row of the Settings apps list.
ComputerUseAppPatch
One per-app choice to set in computerUseSettings/update.
ComputerUseBlockedApp
One row of the Settings blocked-apps list.
ComputerUseInstalledApp
One installed or running app, for Settings’ app picker.
ComputerUseSettings
computerUseSettings/read result, also answered by computerUseSettings/update.
ComputerUseSettingsReadParams
computerUseSettings/read params.
ComputerUseSettingsUpdateParams
computerUseSettings/update params: a patch. Omitted members are left alone; the whole patch applies or none of it does.
ComputerUseSetupChanged
computerUseSetup/changed params.
ComputerUseSetupReadParams
computerUseSetup/read params.
ComputerUseSetupStartParams
computerUseSetup/start params: a human command.
ComputerUseSetupState
The session’s setup state: the result of both methods and the computerUseSetup/changed payload’s state.
ContextUsage
The snapshot contextUsage block: the latest (windowTokens, usedTokens, pressure) triple; the snapshot member is null until the fold’s generation chain holds a tracked anchor AND the current basis is present (absent is never fabricated).
CronReceipt
Cron’s details payload.
CronReceiptJob
One row of the Cron list receipt’s jobs array.
CumulativeCost
Server-computed session cost member of CumulativeTokenUsage.
CumulativeTokenUsage
Session running totals of counted-once usage.
DamagedRange
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.
EffectiveApprovalModeState
The effective approval-mode projection: the same object session/setApprovalMode returns as effectiveMode and the Session object carries as approvalMode.
EffectiveModel
The latest effective-model fact in the snapshot.
EffectivePermissionState
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/setPermissionProfile returns and the Session object carries as permissionState. Served values must be coherent: a read never combines an old profile with a newer runtime’s attachment claim.
ErrorData
The optional error.data object. All members additive-optional; kind is always present when data is.
ErrorObject
The error member of an error response.
ErrorResponse
An error response frame. Exactly one of result or error appears on a response; this type is the error half.
FeedbackSubmitParams
feedback/submit params: mirrors the TUI confirm-time FeedbackRequest. The call itself is the explicit confirm.
FeedbackSubmitResult
feedback/submit result: the upload receipt.
ForkCutPoint
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.
ForkProvenance
Fork provenance folded from the durable session.fork.created record.
Goal
The session goal block. status and percentComplete are carried verbatim — out-of-contract status strings and >100 percents pass through; display clamping is the renderer’s job.
GoalClearParams
goal/clear params. An objective here is an unknown field and rejects -32602 invalidParams — the bare verbs carry exactly this pair.
GoalCommandResult
The shared goal ack, admission-only: all five verbs answer this one shape, differing only in when turnId is present.
GoalEditParams
goal/edit params: replace the current goal’s objective. Same shape as goal/set; the verbs differ in their missing_goal precondition, not their payload.
GoalPauseParams
goal/pause params; shape as goal/clear.
GoalResumeParams
goal/resume params; shape as goal/clear.
GoalSetParams
goal/set params: set the session’s goal objective.
HookCatalogEntry
One installed handler.
HookListParams
hook/list params. Per-session because hook scope follows the session’s workspace and plugin state.
HookListResult
hook/list result: one row per installed handler per event — a ResolvedHookHandler carries one event, and grouping would lose matcher/command identity.
InitializeParams
initialize request params.
InitializeResult
The initialize result.
Item
One transcript item at one revision. item/started, item/updated, and item/completed carry the full object; item/delta appends to it by field path.
ItemCompletedParams
item/completed params: the item reached its terminal state — the authoritative final object. Always cites a durable sourceRange. Clients MUST accept item/completed for an itemId they never saw item/started for.
ItemDeltaParams
item/delta params: a UTF-8-safe streaming append to an open item’s field. Ephemeral-sourced by definition: this params object has no sourceRange member at all. Deltas never bump revision.
ItemReadOutputParams
item/readOutput params: byte-ranged fetch of stored full output that the view truncated, via the item’s outputRef. Read-only; works on loaded and unloaded sessions; no lease.
ItemReadOutputResult
item/readOutput result: one stored-byte page.
ItemStartedParams
item/started params: a new item opened on the transcript. sourceRange is absent when the item opens on an ephemeral record (the delta-streamed kinds); the item’s authoritative open is re-stated by its durable-sourced item/completed.
ItemUpdatedParams
item/updated params: 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).
LastTurn
The last turn/completed the session-view fold applied, restated on session/resume and session/read so a reopened session can report a failed last turn.
LimitsAboveMaxAxis
One too-wide axis in a -32028 limitsAboveMax refusal: every too-wide axis is listed, never the first only. requested/max carry the axis’s own JSON values.
MediaUploadParams
media/upload params: one chunk of a client-minted upload. All members required.
MediaUploadResult
media/upload result: echoes the client-minted id, on every chunk and replay.
MessageAttachment
userMessage image attachment metadata: metadata only — the durable bytes live in the log and are reachable on the raw altitude.
ModelCatalogEntry
One visible catalog row. Catalog rows marked hidden never reach the wire, so a client cannot select one.
ModelCost
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.
ModelDescribedReasoningEffort
One described reasoning-effort tier of a model/list row: a selectable tier plus the catalog’s display string for it when declared.
ModelListParams
model/list params: the discovery half of the model-picker gesture. A query, not a command — no commandId, no durable intake record, no view event.
ModelListResult
model/list result. A snapshot at call time: v1 has no catalog subscription. models MAY be empty — a build shipped with no bundled models is a supported configuration.
ModelSelection
A model selection. Empty strings are normalized to absent.
ModelVisibleContent
Rich content the model saw beyond text: metadata only — fetch bytes via item/readOutput when an outputRef exists.
MonitorInboxItemAdmittedParams
monitor/inboxItemAdmitted params: one monitor inbox admission — the fold keys gate-off consumes.
MonitorInboxItemDrainedParams
monitor/inboxItemDrained params: one monitor inbox drain — a consumption marker with its recorded stamp.
MonitorInboxItemVoidedParams
monitor/inboxItemVoided params: one wake-missed void — count-only, no transcript row.
Notification
A notification frame, either direction. No id; a notification is never answered.
OutputRef
Stored-output reference: the camelCased fold of the durable ToolOutputRef. The fetch path is item/readOutput.
PatchSummary
Server-authored edit-family diff summary: files counts the stored patch document’s file entries; added and removed are the total +/- prefixed LINE counts summed over the stored patch’s hunks across all files — line counts, never hunk or byte counts. Rides the toolCall item beside patchRef; the body is fetched via item/readOutput with patchRef.id.
PendingApprovalPointer
A pending approval in the snapshot: the pointer shape plus the gated itemId when one exists.
PendingRequestPointer
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/resume response; session/read never re-issues them.
PendingUserInputPointer
A pending user-input prompt in the snapshot.
PermissionAxes
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 served reviewerAuthority.
PluginCatalogEntry
One installed plugin record.
PluginChangedParams
plugin/changed params: an install landed; clients re-issue plugin/list (plus hook/list and skill/list).
PluginInstallLocalPathTarget
The plugin/install local-path arm.
PluginInstallMarketplaceTarget
The plugin/install marketplace arm.
PluginInstallParams
plugin/install params. Per-session params plus a client-generated commandId (UUIDv7) with the uniform idempotency contract.
PluginInstallResult
plugin/install result: the ack envelope plus the installed receipt.
PluginInstallTarget
The one structured install target: a flat object with two optional arms, exactly one present — the TurnInputPart convention, since the v1 schema model names no object-variant union. Both arms or neither is -32602 invalidParams.
PluginListParams
plugin/list params. Per-session params; rows are the installed plugin records.
PluginListResult
plugin/list result: one row per installed plugin record; the spec promises the set, not an order.
PluginMarketplaceAddParams
plugin/marketplaceAdd params. Per-session params plus a client-generated commandId (UUIDv7).
PluginMarketplaceChangedParams
plugin/marketplaceChanged params: a marketplace was added, updated, or removed.
PluginMarketplaceRecordResult
The stored marketplace record both add and update answer: the ack envelope plus the record.
PluginMarketplaceRemoveParams
plugin/marketplaceRemove params. Per-session params plus a client-generated commandId (UUIDv7).
PluginMarketplaceRemoveResult
plugin/marketplaceRemove result: the ack envelope plus the removed name.
PluginMarketplaceSkippedEntry
One skipped marketplace entry.
PluginMarketplaceSourceShape
The normalized stored marketplace source.
PluginMarketplaceUpdateParams
plugin/marketplaceUpdate params. Per-session params plus a client-generated commandId (UUIDv7).
QuotaDetail
Typed quota-exhaustion detail: the limit kind plus the provider’s reset instant.
ReasoningEffortState
The snapshot’s standing session-default reasoning effort: the fold of the latest completed runtime.reasoning_effort_reconfigure fact — the same pair session/reasoningEffortChanged carries.
RecapCancelParams
recap/cancel params: the session plus the cancel’s own retry id. No target — one in-flight slot per session makes the target unambiguous.
RecapCancelResult
recap/cancel result: admission only. In flight → the recap settles cancelled; idle → accepted no-op.
RecapCompletedParams
recap/completed params: the settlement, delivered to the requesting connection outside the view stream — no viewCursor, no sourceRange. text is required on completed; reason is required on failed; neither rides cancelled/timedOut. The struct marks the conditional members optional; the SS prose pins the per-outcome rule, the turn/completed usage/error convention.
RecapRequestParams
recap/request params: the session plus the client-minted UUIDv7 retry id. No other param; unknown fields are invalidParams.
RecapRequestResult
recap/request result: admission only — the ack is never the recap.
RecordPosition
One end of a SourceRange: a record’s event id and its sequence number within the stream.
RecoveryObservation
One coherent producer snapshot; all members are required and non-null.
Request
A request frame, either direction.
RequestReceipt
The presentation receipt — the client’s response to a server-initiated request (approval/request, userInput/request).
ScheduledFireMembers
scheduledFire members, flattened into the item row.
SchemaInfo
The schema pair in InitializeResult. version is the wire envelope schema version — distinct from the session-view schemaVersion, the raw-log schema_version, and the 0.x/1.0 stability posture, which is not on the wire at all.
ServerInfo
Server identification inside InitializeResult.
Session
The session object every lifecycle method returns or lists.
SessionApprovalModeChangedParams
session/approvalModeChanged params: 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.
SessionBranchChangedParams
session/branchChanged params: a durable workspace-branch observation landed.
SessionClosedParams
session/closed params: a loaded session was unloaded from this host, broadcast to every initialized connection. After it, the session is notLoaded; the log remains on disk and session/resume reloads it. A crash emits nothing — only the orderly unload paths do (idle unload, host shutdown and a released session/leave), and each writes the durable SessionEnd record first.
SessionCompactParams
session/compact params: manually compact the session’s conversation context — the /compact gesture. Compaction runs asynchronously; the ack is admission only.
SessionCompactResult
session/compact result. Failures after admission (summarizer_failed, install_rejected, cancelled) are not wire errors — they arrive as the compaction’s terminal view event.
SessionConfig
The open configuration extension object shared by session/start and session/resume.
SessionContextUsageParams
session/contextUsage params: 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).
SessionForkParams
session/fork params.
SessionForkResult
session/fork result: the session/resume envelope for the new session, whose session.forkedFrom carries the provenance.
SessionGoalChangedParams
session/goalChanged params: the projected goal block’s value changed — identical adoptions emit nothing (the change gate), and an explicit null clears. Replace wholesale; null never means unchanged.
SessionHistory
The history envelope shared by session/resume, session/fork, and session/read.
SessionLeaveCompletedParams
Params of the protected, non-view leave terminal notification.
SessionLeaveFailureReason
Current producer failure reasons for session/leaveCompleted; receiver-open for additive future reasons.
SessionLeaveOutcome
Current producer outcomes for session/leaveCompleted; receiver-open.
SessionLeaveParams
session/leave params.
SessionLeaveResult
The admission-only session/leave result.
SessionLimits
A five-axis limits report: every maxLimits / currentLimits member is this one definition, and every member is required — reporting always fills all five, so readers never see an absence.
SessionLimitsChoice
The session/start limits choice: every member is optional — a start names only the axes it chooses. Reports use SessionLimits, whose members are always present.
SessionListBranchFilter
Exact branch selection.
SessionListChangedParams
session/listChanged params: one changed row of the session/list shape — 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 the sessionListStream capability at initialize; row birth stays on session/started, unload pairs with session/closed.
SessionListFilter
The session/list filter. Members are ANDed with each other and with the top-level workspaceRoot and updatedAfter; values inside each anyOf are ORed. The canonical form the server echoes deduplicates and sorts every set, spells session IDs as canonical UUIDs, lowercases text terms, and orders text.fields name then title.
SessionListParams
session/list params. Read-only; never touches leases.
SessionListResult
session/list result. Ordering is updatedAt descending.
SessionListSessionIdFilter
Exact session-ID selection.
SessionListTextFilter
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 (check matches Checkout; eck does 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.
SessionModelChangedParams
session/modelChanged params: a durable model-selection record landed.
SessionModelRouteUnservedParams
session/modelRouteUnserved params: an accepted login.credential_update installed a provider that cannot serve the session’s STANDING model route. Disclosure only — the standing selection is unchanged (no session/modelChanged fires) and the repair path is a routable session/setModel. Folded from the durable runtime.provider_reconfigure.standing_route_unserved record; additive — clients that predate it skip the unknown method.
SessionNameChangedParams
session/nameChanged params: the fold of ANY durable session-name record — the FIRST-NAMING automatic allocate as well as an accepted session/rename (or the same in-process runtime command). Replace-wholesale like every sibling.
SessionReadParams
session/read params: read one stored session without attaching — no writer lease, no load, no subscription, no SessionResumed record.
SessionReadResult
session/read result. The viewCursor is the fold head at read time — a point-in-time read, immediately stale if a foreign host is appending.
SessionReasoningEffortChangedParams
session/reasoningEffortChanged params: a durable reasoning-effort reconfigure record landed. Replace wholesale, latest wins; the snapshot carries the latest value.
SessionRenameParams
session/rename params: set or change the durable allocated session name through the runtime session_name command. One writer; withheld under the ephemeral profile.
SessionRenameResult
session/rename result: name is the canonical (normalized) name the durable record settled.
SessionResumeParams
session/resume params.
SessionResumeResult
session/resume result.
SessionSetApprovalModeParams
session/setApprovalMode params: switch the session’s approval enforcement mode mid-session. A standard command.
SessionSetApprovalModeResult
session/setApprovalMode result. Applies next-action — an in-flight tool action’s pending approval is not retroactively decided by a mode change.
SessionSetModelParams
session/setModel params: the model-picker gesture. The selection is durable and applies to subsequent model calls.
SessionSetModelResult
session/setModel result. 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.
SessionSetReasoningEffortParams
session/setReasoningEffort params: set the session’s standing reasoning-effort default. A turn carrying its own reasoningEffort overrides it for that turn only; the default overrides the host’s configured default. Same accept/reject and commandId idempotency shape as session/setModel.
SessionSetReasoningEffortResult
session/setReasoningEffort result. The default is durable on ack and applies to turns launched after admission; a running turn keeps the request options it already resolved.
SessionSideChatParams
session/sideChat params.
SessionSideChatResult
session/sideChat result: the session/resume envelope for the new side session, whose session.sideFrom carries the provenance. The side opens empty.
SessionStartParams
session/start params.
SessionStartResult
session/start result.
SessionStartedParams
session/started params: a session became newly loaded on this host via session/start, session/fork, or session/sideChat, broadcast to every initialized connection.
SessionStatusChangedParams
session/statusChanged params: 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, no sourceRange; the same facts live on the Session object, which is how a client seeds its table (no initial burst on connect).
SessionTodoListChangedParams
session/todoListChanged params: a TodoSnapshotUpdated record landed. Replace the whole list on every event; an empty items array is a cleared list, not a no-op.
SessionTokenUsageParams
session/tokenUsage params: one per model completion that reports usage. Carries the raw counters verbatim plus the server-derived counted-once promptTokens/totalTokens and the session cumulative block. Accumulate-only: cumulative never goes backward.
SessionUserShellParams
session/userShell params: run a user-initiated shell command in the session’s workspace — the TUI’s ! escape hatch. Capability-gated: the connection must negotiate userShell at initialize, and the whole justification is the spawn boundary.
SessionUserShellResult
session/userShell result: immediate. The shell runs off the command worker so a long command cannot stall the command plane; the output arrives as the userShell item’s terminal view event.
SessionViewHealthChangedParams
session/viewHealthChanged params: the named session’s live view stream became unavailable, and why.
SessionWorktree
The Session worktree member: path and origin only — the branch stays in the existing branch member.
SideProvenance
Side provenance folded from the durable side provenance.
SkillCatalogEntry
One typed-invocable shortcut spelling. A plugin skill may contribute two rows: its bare-name winner and its qualified <pluginId>:<skillId> form.
SkillChangedParams
skill/changed params: the session’s user-invocable set changed; clients re-issue skill/list. Advisory — the host may coalesce bursts and guarantees no ordering relative to view events.
SkillImportCounts
The four receipt-list lengths: a client renders counts without walking lists.
SkillImportFailure
One import candidate that could neither install nor quarantine: recorded so the run continues past it. id is null when the candidate never yielded one — present-but-null, never omitted.
SkillImportParams
skill/import params: import foreign skills through the single SkillsService::import_skills seam.
SkillImportQuarantine
One quarantined import candidate: kept, not loaded.
SkillImportResult
skill/import result: the ack envelope plus the service receipt projection.
SkillListParams
skill/list params. Per-session because skill scope follows the session’s workspace and plugin state.
SkillListResult
skill/list result: one row per typed-invocable shortcut spelling — exactly the invocations the first-party typed dispatch accepts.
SkillSetActivationParams
skill/setActivation params: turn one skill on or off in any scope through the single SkillsService::set_activation seam.
SkillSetActivationResult
skill/setActivation result: the ack envelope plus the applied state.
SnapshotAnchor
The compaction boundary an anchored snapshot is anchored at.
SnapshotState
The complete folded view at the snapshot cursor.
SourceRange
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.
StatusAttempt
toolCall.statusAttempt: the latest TaskExternalAttemptDetail, field-for-field — countdown inputs the client renders the tick from, so no event spam.
StatusChildren
toolCall.statusChildren: the latest TaskChildSummaryDetail, field-for-field.
StatusHealth
toolCall.statusHealth: the latest TaskHealthDetail, field-for-field.
StatusProgress
toolCall.statusProgress: the latest TaskProgressDetail, field-for-field.
StatusStep
toolCall.statusStep: the latest TaskActiveStepDetail, field-for-field.
StreamRef
One raw stream named by a SourceRange.
SubagentInputParams
Params for subagent/sendMessage and subagent/followupTask: a child target plus the input body.
SubagentOwnerReasonParams
Params for subagent/interrupt, subagent/stop, and subagent/close: a child target plus an optional human-readable reason that is preserved on the durable effect record.
SubagentResult
A subagent’s result envelope.
SubagentTargetParams
Params for subagent/resume, subagent/reopen, and subagent/readResult: the bare child target.
SubscriptionUsage
The one usage payload shape: the usage/read result’s usage member and the usage/changed params. The numbers are point-in-time — observedAtMs is the host’s arrival stamp, so a client renders “as of”, never implies live data.
SubscriptionUsageWeekly
The rolling weekly block: same semantics as SubscriptionUsageWindow without a duration.
SubscriptionUsageWindow
The current usage window (the provider’s 5-hour-class block): verbatim provider percentages with the reset stamp normalized to epoch milliseconds.
SuccessResponse
A success response frame.
TaskBackgroundParams
task/background params: durably send a running foreground tool task to the background.
TaskCommandResult
The task/background / task/stop ack: admission-only, echoing the targeted task.
TaskListEntry
One task inventory row. The row is the stable contract: kind and status stay open so a future state extends them without breaking clients.
TaskListParams
task/list params: the session whose background-task inventory to read. A read-only query in the skill/list mold: no commandId, no durable record, no view event.
TaskListResult
task/list result: one row per live workload, background and foreground, oldest first; empty when nothing is running.
TaskStopAllParams
task/stopAll params: stop every stoppable background workload live at admission.
TaskStopAllResult
The task/stopAll ack: always accepted, 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.
TaskStopParams
task/stop params: stop one named background task. Required target, never “whichever is loudest” — is the blanket verb.
TodoItem
One todo entry.
TodoListState
The latest todo-list fact in the snapshot.
TokenUsage
Raw token counters, verbatim from the durable record. Not directly summable across providers — sum the counted-once derivations instead.
ToolCallMembers
toolCall members, flattened into the item row.
ToolDisplayLabel
toolCall.displayLabel: the call’s words in three forms, each one line of plain text, always present together. The item’s status picks the form.
ToolReceipt
The shared toolReceipt container.
TraceContext
Optional W3C trace context, on requests in both directions only — never on responses or notifications.
TurnCancelParams
turn/cancel params: plain cancellation on the normal command lane. Same shape as turn/interrupt, without retract — pairing a retract with a plain cancel is durably rejected not_paired_interrupt.
TurnCancelResult
turn/cancel result: identical envelope to turn/interrupt.
TurnCompletedParams
turn/completed params: the run’s durable terminal record landed.
TurnError
The settled turn-failure object: {kind, message, retryable}.
TurnForegroundCompletedParams
turn/foregroundCompleted params: the turn’s foreground work is done and named background reminder checks hold the turn open. Explicitly non-terminal: the turn ends only at turn/completed / turn/unqueued.
TurnInputPart
One ordered content part of a turn submission. File mentions are text, not a part type: write @relative/path in a text part. A structured mention part is reserved and currently rejected, and an unknown part type is invalidParams — which is what closes TurnInputPartType.
TurnInterruptParams
turn/interrupt params: the “user pressed stop” gesture, on the runtime’s priority lane.
TurnInterruptResult
turn/interrupt result. Acceptance means the interrupt was admitted, not that the turn is already stopped: the turn is over when you fold its turn/completed with terminal cancelled.
TurnModelRetryScheduledParams
turn/modelRetryScheduled params: 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 sibling turn/retryScheduled shape at the model layer: same member names and semantics (attempt/nextAttempt/maxAttempts/ retryDelayMs/system/errorKind/httpStatus), minus reason — the row’s words derive from errorKind through 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. sourceRange cites the session stream’s mirror of the task-lifecycle record.
TurnRef
A turn named by the snapshot’s active/queued lists.
TurnRetractedParams
turn/retracted params: an interrupt-paired retract durably settled, accepted or declined. On "accepted" the retracted user-message item is re-emitted via item/updated with retracted: true; on "declined" the client folds the legacy declined rollback instead and no item is re-emitted.
TurnRetryScheduledParams
turn/retryScheduled params: 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. sourceRange cites the session stream’s mirror of the task-lifecycle record.
TurnStartParams
turn/start params.
TurnStartResult
turn/start result.
TurnStartedParams
turn/started params: a foreground turn began running — fresh submits immediately, queued submits at their launch boundary, never steered submits.
TurnSteerParams
turn/steer params: exact-target steering into the currently running turn.
TurnSteerResult
turn/steer result.
TurnUnqueueParams
turn/unqueue params: 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.
TurnUnqueueResult
turn/unqueue result. Admission only — but for this command admission is the race: an admitted reclaim implies the turn will not launch. The authoritative removal is the turn/unqueued view event.
TurnUnqueuedParams
turn/unqueued params: a queued submit’s reclaim durably won; its pre-minted turn never runs. Carries the reclaimed turnId and the commandId of the turn/start that queued it, so a client can restore the submission’s text exactly as for turn/retracted. No turn/started/turn/completed is ever emitted for this turnId. sourceRange cites the SESSION stream’s reclaim record — a reclaimed turn never had a run stream.
TurnUserShell
The queued ! shell action a turn/start carries: the !cmd typed while a turn runs. The shell’s command id derives from the carrying turn’s commandId, exactly as the app’s own queued submit does; the params’ sibling displayText carries the !… presentation form.
UnframedViewNotification
One element of a view/page result’s events array: an unframed view notification — the nested pair {"method", "params"}, which is the live notification minus jsonrpc and emittedAtMs, with nothing lifted out of params and nothing spliced into it. view/page and muse exec --json share this one definition, so the two surfaces cannot drift.
UnframedViewNotificationParams
The params of an unframed view notification.
UsageReadResult
usage/read result: {usage?} — omitted, never null, when the host has observed nothing.
UserInputAnswer
One question’s answer, as sent in userInput/answer or userInput/interrupt and as recorded in userInput/settled.
UserInputAnswerParams
userInput/answer params: answer every question.
UserInputAnswerResult
userInput/answer result.
UserInputCancelParams
userInput/cancel params: decline to answer; the tool call resolves with a cancelled result the model sees.
UserInputCancelResult
userInput/cancel result.
UserInputClarification
A free-form reply the user gives instead of choosing from the options; the model reads it and decides again.
UserInputClarifyParams
userInput/clarify params: 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.
UserInputClarifyResult
userInput/clarify result.
UserInputEngagedParams
userInput/engaged params: 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, no commandId, no ledger row.
UserInputInterruptParams
userInput/interrupt params: interrupt the named prompt carrying confirmed partial answers, then stop the turn.
UserInputInterruptResult
userInput/interrupt result.
UserInputOption
One option offered for a question.
UserInputOptionPreview
Rich content a client can show for an option. Only single-select questions carry previews.
UserInputQuestion
One question in a user-input prompt.
UserInputRequestParams
Full params shared by userInput/request and userInput/requested.
UserInputSelection
How many options the user may pick for a question.
UserInputSettledParams
userInput/settled params: the first durable prompt settlement.
UserInputSettlementSummary
Winning terminal returned to a late user-input command.
ViewGapParams
view/gap params: push delivery dropped events, and this names the hole.
ViewPageParams
view/page params: cursor-paged reads of the session view.
ViewPageResolvedAnchor
The resolvedAnchor echo: subsequent pages pass ordinary cursors, so the anchor never needs re-resolving.
ViewPageResult
view/page result.
ViewSnapshot
The snapshot object returned by session/resume / session/read.
ViewSubscribeParams
view/subscribe params: 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 after view/unsubscribe. It never loads a session, takes no lease, writes nothing.
ViewSubscribeResult
view/subscribe result.
ViewUnsubscribeParams
view/unsubscribe params: 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.
ViewUnsubscribeResult
view/unsubscribe result: the empty object. Idempotent — unsubscribing while not subscribed returns {}.
WebSearchHit
webSearch: one typed result hit — result schema v1.
WorkflowCancelParams
workflow/cancel params: cancel a live workflow run.
WorkflowChild
One workflow child’s folded state, keyed by (childId, attempt).
WorkflowChildControlParams
workflow/childControl params: skip or retry one workflow child, keyed by the (childId, attempt) pair the workflow item’s children[] carries.
WorkflowControlResult
The shared admission-only ack: deliberately bare {commandId, status} — settlement arrives as the workflow item’s view events, never through the ack.
WorkflowPauseParams
workflow/pause params: pause a live workflow run, shaped exactly like workflow/cancel.
WorkflowResumeParams
workflow/resume params: resume a paused workflow run, host-driven.
WorkflowResumeResult
workflow/resume result: admission-only plus the driven turn — always present, since resume always drives (idle fresh turn or busy steer).
WorkflowTokenBudget
workflow: the run’s launch token budget.

Enums§

ApprovalAmendmentDurability
How long a rule created by an approval decision lasts. The set is open, so newer hosts may send other values.
ApprovalChoiceScope
How long a grant made by a choice lasts. The set is open, so newer hosts may send other values.
ApprovalDecision
The kind of decision a choice applies or an approval received. The set is open, so newer hosts may send values this version does not list.
ApprovalMode
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.
ApprovalModeApplyOutcome
Whether a mode change did anything, mirroring ApprovalReconfigureApplyOutcome. Apply failures are commandRejected.
ApprovalModeSource
How an approval mode took effect. Open.
ApprovalPersistenceStatus
The result of saving a granted rule to the local policy store. The set is open, so newer hosts may send other values.
ApprovalPolicyResult
Whether an approval’s final decision lets the action run. The set is open, so newer hosts may send other values.
ApprovalResolvedBy
Who or what made an approval’s final decision. The set is open, so newer hosts may send other values.
AttentionFlag
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.
BackgroundInitiator
Who durably backgrounded a task. Open — runtime vocabulary.
BackgroundState
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 durable TaskBackgrounded).
CapabilityName
A grantable capability name. Open: the experimental-only rawLog entry joins the stable domain as an additive open-enum extension when it graduates — closed would make that a retype.
CodeModeLanguage
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.
CodeModeOutputStream
What a Code Mode output span’s bytes are. Open: each engine mints its own values.
CommandAckStatus
The ack-status vocabulary: "accepted" for every admitted command; session/compact alone may answer "noop". Closed: the protocol defines 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.
CommandStatus
The ack status: accepted for every admitted command. session/compact is the one method that may additionally answer noop (crate::msp::method::runtime::CompactStatus); no other command uses another status.
CompactStatus
session/compact’s ack status: the one method that may answer noop in addition to the accepted. A noop is a success, not an error, and it is durably settled like any other outcome.
CompactionOutcome
Compaction outcome. Open.
CompactionTrigger
What initiated a compaction. Open.
ComputerUseAppChoice
A per-app choice. Open, like ComputerUseChoice.
ComputerUseAppLock
Why Settings can’t change a row. Open.
ComputerUseChoice
A capability dropdown’s value. Open: the read result carries it, so an older client tolerates a value it does not know.
ComputerUsePermission
One macOS permission as setup last saw it. Open, like the phase.
ComputerUseSetupPhase
Where the session’s setup stands: cua_setup’s state codes, camelCase. Open: a result vocabulary, so an older client tolerates a new state.
ContextPressureLevel
Context pressure level: hard threshold first, both inclusive >=. Open.
ErrorKind
A stable error.data.kind category: camelCase, the value clients branch on. Open: new kinds are added as their methods land, and a new kind is additive only because this domain is declared open.
FeedbackClassification
feedback/submit classification: the four TUI classes in camelCase wire spelling. Closed: a client-selected param vocabulary.
FeedbackSubmitOutcome
feedback/submit result outcome: how one confirmed submit resolved, mirroring the TUI FeedbackSubmitOutcome taxonomy. 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.
HistoryMode
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”.
HistoryNoneReason
Why a result served history.mode: "none": the server’s typed reason for serving no history. Open on the client side: an absent (older server) or unknown (newer server) value decodes conservatively as an unknown reason, and viewCursor text never substitutes for it.
HistoryPreference
The history request preference of session/resume. The forced values downgrade anchored → inline → snapshot → none; under auto the full rung order is anchoredSnapshot → inline → snapshot → elided snapshot → none.
HookEventName
Hook event names: the lowercase-first-letter spelling of every HookEventKind::all() variant. Open: a future event value is additive.
HookHandlerKind
A hook row’s origin: the config HookSourceKind values plus plugin-contributed. Open: a future origin is additive.
HookRunStatus
hookRun durable 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.
ItemKind
The eleven v1 item kinds plus post-v1 kinds. Open: a new kind is additive evolution, and clients MUST render unknown kinds generically.
ItemReadOutputEncoding
The item/readOutput content encoding. Closed: text media is ALWAYS utf8 and binary media base64; a third value would change the client’s decode contract.
ItemStatus
Item status. Open; terminal = anything other than "inProgress", and unknown values are terminal-unknown, rendered generically.
JsonRpcVersion
The literal "2.0" every frame carries.
LimitKind
Quota limit kinds: open for evolution.
LimitsAxisValue
One axis value in a limits refusal: a boolean on the four boolean axes, the mode string on sandboxNetwork. Closed: exactly the two shapes, never another — named in the governing rules closed untagged-union list (CLOSED_WITHOUT_MARKER), since the untagged shape carries no schema marker. Untagged so the wire carries the bare JSON value; untagged also keeps the shape the schema builder requires (a bare serde_json::Value renders no type and is rejected).
LimitsNetworkMode
The sandbox-network axis values. Closed: a client selects one of the three serve spellings and can never construct another; the socket promise is same-version, so the result use needs no unknown arm.
MessagePhase
agentMessage.messagePhase: the phase the model declared on the commit, never inferred from position. Set on the completed item only; absent on item/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/completed is.
ModelCatalogSource
Where a model catalog came from. Open: an unrecognized value is an unknown source, not an error.
ModelChangeSource
What drove a model selection. Open.
ModelReasoningEffortVariants
A complete ordered effort set, or an explicit unknown capability.
OutputRefAvailability
Whether a stored output’s bytes are servable. Open — durable runtime vocabulary may grow additively.
PendingRequestKind
The pendingRequests discriminator. Open enum, v1 values approval and userInput.
PermissionApprovalAxis
A profile’s effective approval axis. Open: the vocabulary can widen.
PermissionFilesystemAxis
A profile’s effective filesystem axis. Open: the vocabulary can widen.
PermissionNetworkAxis
A profile’s effective local-command network axis. Open: the vocabulary can widen.
PlatformFamily
The server runtime’s platform family; may differ from the client’s. Closed: the protocol fixes the value set, so widening it is a deliberate, gate-visible protocol change rather than a silent addition (a later Closed→Open flip is itself additive).
PlatformOs
The server’s operating system. Closed, for the same reason as PlatformFamily.
PluginInstallScope
The plugin/install local-path scope. Closed: an unknown scope is -32602 invalidParams.
PluginMarketplaceChange
What happened to a marketplace. Closed: an unknown change is a contract violation, never tolerated.
PluginSource
A plugin row’s source provenance: camelCase of PluginSourceProvenance. Open: a future provenance is additive.
ReasoningEffort
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. none is a tier of the vocabulary (ask for no reasoning), not a way to say “unset”.
ReasoningEffortChangeSource
What drove a reasoning-effort default change. Open; v1’s only producer is user (an accepted session/setReasoningEffort).
RecapFailureReason
recap/completed failure reason: post-ack failures fold to the single initial value. Open: later splits stay additive.
RecapOutcome
recap/completed outcome: the terminal vocabulary, in camelCase. Open: a server-produced result vocabulary.
RecoveryEffectiveSource
Proven effective-choice provenance, independently of input presence.
RecoveryMode
A requested construction choice; omission is distinct from explicit OFF.
RecoveryObservedMode
A proven mode or unknown; future strings cannot establish OFF.
RecoveryQualification
This construction’s assessment, never an operation acceptance receipt.
RequestId
A request id: client-chosen string or integer. 1 and "1" do not compare equal; each direction owns its own id space.
RetractOutcome
A turn/retracted settlement outcome. Open enum: decode is tolerant — a value outside the list reads as Accepted (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.
ReviewerAuthority
A profile’s selected reviewer authority. Open: the reviewer vocabulary can widen.
SandboxAvailability
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.
SandboxUnavailableReason
Why sandbox enforcement is impossible on this host. Sent only when SandboxAvailability is unavailable; 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.
SessionClosedReason
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.
SessionDurability
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.
SessionKind
What kind of session this is.
SessionListTextField
A served session field session/list text search reads. The client selects it, so the set is closed.
SessionMcpServerConfig
One native MCP server supplied at session construction.
SessionMcpServerMode
Startup failure posture for a session MCP server.
SessionMcpStdioFraming
Stdio framing choices exposed by session MCP configuration.
SessionNameOrigin
How the served session name was set. Open enum (x-msp-openness: open): v1 serves automatic and custom; 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.
SessionStatus
A session’s load state.
SessionViewHealth
The view-health state. Open enum (x-msp-openness: open): a client MUST ignore an unrecognized value. v1 emits only Unavailable; 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.
SkillActivationScope
skill/setActivation activation 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-side SkillSource.
SkillActivationState
The three-state skill activation. Closed: a client-selected write vocabulary.
SkillImportSource
skill/import foreign 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 (the foreign_skills_sources derivation); no client paths cross the wire.
SkillInvocationSource
A skill input part’s picked-copy source: the catalog-row source enum 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 is invalidParams, never a fall-through to the bare row. Contrast the open read-side SkillSource.
SkillSource
A skill row’s source scope: the projection of the skills crate’s SkillsSourceScope. Open: a future scope value is additive.
StatusHealthLevel
toolCall.statusHealth.level: the durable TaskHealthLevel vocabulary verbatim. Open — runtime vocabulary may grow additively, and clients MUST render unknown levels generically.
SubagentControlStatus
Subagent control status. Open; the generic item status is the terminal authority.
TaskExecutionMode
A task row’s execution mode. Open: clients MUST ignore unknown modes.
TaskListStatus
A task row’s status. Open: a future state is additive, and clients MUST ignore unknown statuses.
TodoStatus
Todo status: closed in the runtime, wire-open.
ToolReceiptBody
The family-selected body of a receipt: the family discriminator and the one details object whose shape that discriminator chooses.
ToolReceiptOperation
Which operation within the family the receipt describes. Open — registered per family, never derived from the tool name.
ToolReceiptOutcome
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 status values are bound to the value here rather than per family.
TurnErrorKind
Turn failure classes. Open.
TurnInputPartType
The type discriminator of a turn input part. Closed: an unknown part type is invalidParams.
TurnStartDisposition
What turn/start did with the input. Resolves OQ-H in v1: since queue is the default ifBusy, clients need to distinguish these without folding history.
TurnTerminal
Turn terminal vocabulary: exactly the runtime’s RunTerminalKind — closed in the runtime, wire-open for evolution.
UnknownModelReasoningEffortVariants
The only scalar alternative to a known effort array. Kept as a closed singleton so arbitrary strings and uppercase spellings fail decoding.
UserInputOutcome
How a user-input prompt settled. More values may be added, so handle values you do not recognize.
UserInputSelectionMode
Whether a question takes one option or several.
Vcs
Version-control system of a branch observation. Open.
ViewPageAnchor
The view/page request-mode anchor. Declared open: the protocol spells it “open string enum, v1 value latestCompaction”.
ViewPageDirection
The view/page paging direction. Closed: the protocol spells exactly two values and a third would change the paging contract.
WorkflowChildAction
Which control to apply to the child’s current attempt. Closed on the wire: an unknown value is -32602 invalidParams.
WorktreeOrigin
Where a session’s worktree came from: created means the host allocated it for the session, attached means the host bound a caller-provided worktree.
WorktreeStartRequest
session/start worktree param: absent means no worktree — the start proceeds exactly as today. Adjacently tagged on mode: a create carries an optional baseRef, an existing carries a required path (omitted path fails 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.