muse-code-msp 1.3.0__py3-none-any.whl

muse_code_msp/__init__.py

@@ -0,0 +1,2232 @@
+# GENERATED by scripts/gen-msp-py.sh -- DO NOT EDIT.
+# A hand edit or a stale rendering reds the required regen test
+# (crates/devtools/tests/msp_py_codegen.rs); rerun scripts/gen-msp-py.sh.
+"""Generated MSP wire types, stable surface. Import surface: `muse_code_msp`. The experimental surface is NOT re-exported here; import `muse_code_msp.experimental` explicitly (spec 638 FR-638-004)."""
+
+from __future__ import annotations
+
+from typing import Any, Final, Literal, TypedDict
+
+SCHEMA_FINGERPRINT: Final[str] = "sha256:ab69549a7ebb423fce94068762da0b5ff3cdec1f8fc263dcc17248eda117f852"
+SCHEMA_VERSION: Final[int] = 1
+EXPERIMENTAL: Final[bool] = False
+REQUIRED_HOST_VERSION: Final[str] = "1.3.0"
+
+ApprovalAmendmentDurability = str  # open enum (SS1.5.4): unknown values stay representable
+APPROVAL_AMENDMENT_DURABILITY_KNOWN_VALUES: Final[tuple[str, ...]] = ("session", "localPersistent",)
+
+ApprovalChoiceScope = str  # open enum (SS1.5.4): unknown values stay representable
+APPROVAL_CHOICE_SCOPE_KNOWN_VALUES: Final[tuple[str, ...]] = ("once", "session", "localPersistent",)
+
+ApprovalDecision = str  # open enum (SS1.5.4): unknown values stay representable
+APPROVAL_DECISION_KNOWN_VALUES: Final[tuple[str, ...]] = ("approved", "approvedForSession", "approvedPolicyAmendment", "denied", "deniedPolicyAmendment", "timedOut", "abort",)
+
+# The approval enforcement modes (tdd SS5.12, camelCased `ApprovalBackendMode`). **Closed** by design (D-006, select-never-create): a client selects a preconfigured mode and can never construct one; widening this enum is a deliberate, gate-visible protocol change.
+ApprovalMode = Literal["allowAll", "promptUnmatched", "onRequest", "denyUnmatched"]
+
+# Whether a mode change did anything (tdd SS5.12), mirroring `ApprovalReconfigureApplyOutcome`. Apply failures are `commandRejected`.
+ApprovalModeApplyOutcome = str  # open enum (SS1.5.4): unknown values stay representable
+APPROVAL_MODE_APPLY_OUTCOME_KNOWN_VALUES: Final[tuple[str, ...]] = ("completed", "noop",)
+
+# How an approval mode took effect (tdd SS5.12, the effective-mode projection's `source` vocabulary). Open.
+ApprovalModeSource = str  # open enum (SS1.5.4): unknown values stay representable
+APPROVAL_MODE_SOURCE_KNOWN_VALUES: Final[tuple[str, ...]] = ("startup", "replay", "approvalReconfigure",)
+
+ApprovalPersistenceStatus = str  # open enum (SS1.5.4): unknown values stay representable
+APPROVAL_PERSISTENCE_STATUS_KNOWN_VALUES: Final[tuple[str, ...]] = ("succeeded", "failed",)
+
+ApprovalPolicyResult = str  # open enum (SS1.5.4): unknown values stay representable
+APPROVAL_POLICY_RESULT_KNOWN_VALUES: Final[tuple[str, ...]] = ("allow", "deny",)
+
+ApprovalResolvedBy = str  # open enum (SS1.5.4): unknown values stay representable
+APPROVAL_RESOLVED_BY_KNOWN_VALUES: Final[tuple[str, ...]] = ("user", "policy", "llmJudge",)
+
+# One attention flag (tdd SS2.4, ADR 31983 D3): a pending server-initiated request class parked on the session. Open on the wire — clients MUST ignore unknown values; future attention kinds are additive.
+AttentionFlag = str  # open enum (SS1.5.4): unknown values stay representable
+ATTENTION_FLAG_KNOWN_VALUES: Final[tuple[str, ...]] = ("approvalPending", "inputPending",)
+
+# Who durably backgrounded a task (tdd SS4.5.5, `TaskBackgroundedInitiator`). Open — runtime vocabulary.
+BackgroundInitiator = str  # open enum (SS1.5.4): unknown values stay representable
+BACKGROUND_INITIATOR_KNOWN_VALUES: Final[tuple[str, ...]] = ("user", "timeout",)
+
+# A grantable capability name (SS1.4.4). Open: the reserved `rawLog` entry joins this domain as an additive open-enum extension when SS6 un-defers (#13929, Scenario 5 AS-3) — closed would make that a retype.
+CapabilityName = str  # open enum (SS1.5.4): unknown values stay representable
+CAPABILITY_NAME_KNOWN_VALUES: Final[tuple[str, ...]] = ("userShell", "sessionMcp",)
+
+# The ack-status vocabulary (`tdd.md` SS3.1/SS3.1.2): `"accepted"` for every admitted command; `session/compact` alone may answer `"noop"`. Closed: SS3.1.2 names exactly these two values, so SDK clients get a discriminated type and validation catches a wrong status (PR #21550 review) — 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.
+CommandAckStatus = Literal["accepted", "noop"]
+
+# The SS3.1.2 ack `status`: `accepted` for every admitted command. `session/compact` is the one method that may additionally answer `noop` ([`crate::method::runtime::CompactStatus`]); no other command uses another status (tdd SS3.1.2).
+CommandStatus = str  # open enum (SS1.5.4): unknown values stay representable
+COMMAND_STATUS_KNOWN_VALUES: Final[tuple[str, ...]] = ("accepted",)
+
+# `session/compact`'s ack status (tdd SS3.7): the one method that may answer `noop` in addition to the SS3.1.2 `accepted`. A noop is a success, not an error, and it is durably settled like any other outcome.
+CompactStatus = str  # open enum (SS1.5.4): unknown values stay representable
+COMPACT_STATUS_KNOWN_VALUES: Final[tuple[str, ...]] = ("accepted", "noop",)
+
+# Compaction outcome (tdd SS4.5.10, the SS3.7 vocabulary). Open.
+CompactionOutcome = str  # open enum (SS1.5.4): unknown values stay representable
+COMPACTION_OUTCOME_KNOWN_VALUES: Final[tuple[str, ...]] = ("compacted", "noop", "failed", "cancelled",)
+
+# What initiated a compaction (tdd SS4.5.10). Open.
+CompactionTrigger = str  # open enum (SS1.5.4): unknown values stay representable
+COMPACTION_TRIGGER_KNOWN_VALUES: Final[tuple[str, ...]] = ("manual", "auto",)
+
+# Context pressure level (tdd SS4.6.6): hard threshold first, both inclusive `>=`. Open.
+ContextPressureLevel = str  # open enum (SS1.5.4): unknown values stay representable
+CONTEXT_PRESSURE_LEVEL_KNOWN_VALUES: Final[tuple[str, ...]] = ("normal", "warning", "blocked",)
+
+# A stable `error.data.kind` category (SS1.6): camelCase, the value clients branch on. Open: SS2–SS5 lanes add kinds additively as their methods land (Appendix B already registers them), and the spec's edge-case rule makes a new `kind` additive only because this domain is declared open.
+ErrorKind = str  # open enum (SS1.5.4): unknown values stay representable
+ERROR_KIND_KNOWN_VALUES: Final[tuple[str, ...]] = ("parseError", "invalidRequest", "notInitialized", "alreadyInitialized", "methodNotFound", "invalidParams", "experimentalRequired", "internal", "pageEventTooLarge", "outputResultTooLarge", "overloaded", "inputTooLarge", "capabilityRequired", "notFound", "interrupted", "cancelled", "sessionNotFound", "sessionInUse", "sessionAmbiguous", "forkBoundaryInvalid", "sessionNotLoaded", "sessionStreamMismatch", "commandRejected", "backpressured", "skillNotFound", "viewTruncated", "outputUnavailable", "boundaryPruned", "boundaryUnusable", "noBoundary", "approvalNotFound", "approvalAlreadyResolved", "approvalChoiceInvalid", "approvalRequirementStale", "approvalReviewerUnavailable", "userInputNotFound", "userInputAlreadySettled", "userInputAnswerInvalid",)
+
+# What history a lifecycle result actually served (tdd SS2.5.2). Open on the client side: report-what-was-served means a client treats an unknown mode as "page it yourself".
+HistoryMode = str  # open enum (SS1.5.4): unknown values stay representable
+HISTORY_MODE_KNOWN_VALUES: Final[tuple[str, ...]] = ("anchoredSnapshot", "inline", "snapshot", "none",)
+
+# Why a result served `history.mode: "none"` — spec 208 FM-005's typed unavailability (tdd SS2.5.2; D-050). 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 (spec 208 INV-19734-1).
+HistoryNoneReason = str  # open enum (SS1.5.4): unknown values stay representable
+HISTORY_NONE_REASON_KNOWN_VALUES: Final[tuple[str, ...]] = ("excluded", "cursorSuffix", "historyBudget", "projectionUnavailable", "projectionReadLimit",)
+
+# The `history` request preference of `session/resume` (tdd SS2.5.2). The forced values downgrade `anchored` → `inline` → `snapshot` → `none`; under `auto` the full rung order is anchoredSnapshot → inline → snapshot → elided snapshot → none.
+HistoryPreference = Literal["auto", "inline", "snapshot", "anchored"]
+
+# Disposition when a turn is already running (tdd SS3.2). The wire default is `queue`: an SDK caller who has not looked at session state should not silently mutate an in-flight turn.
+IfBusy = Literal["queue", "steer", "replace"]
+
+# The nine v1 item kinds (tdd SS4.5.2–4.5.10). Open: a new kind is additive evolution, and clients MUST render unknown kinds generically (tdd SS4.10).
+ItemKind = str  # open enum (SS1.5.4): unknown values stay representable
+ITEM_KIND_KNOWN_VALUES: Final[tuple[str, ...]] = ("userMessage", "agentMessage", "reasoning", "toolCall", "userShell", "subagent", "workflow", "reminderChild", "compaction",)
+
+# The `item/readOutput` content encoding (tdd SS4.7.4). Closed: text media is ALWAYS `utf8` and binary media `base64`; a third value would change the client's decode contract.
+ItemReadOutputEncoding = Literal["utf8", "base64"]
+
+# Item status (tdd SS4.4.1). Open; terminal = anything other than `"inProgress"`, and unknown values are terminal-unknown, rendered generically.
+ItemStatus = str  # open enum (SS1.5.4): unknown values stay representable
+ITEM_STATUS_KNOWN_VALUES: Final[tuple[str, ...]] = ("inProgress", "completed", "failed", "cancelled", "rejected", "timedOut",)
+
+# The literal `"2.0"` every frame carries (SS1.2).
+JsonRpcVersion = Literal["2.0"]
+
+# Where a model catalog came from (tdd SS3.10). **Open**: an unrecognized value is an unknown source, not an error.
+ModelCatalogSource = str  # open enum (SS1.5.4): unknown values stay representable
+MODEL_CATALOG_SOURCE_KNOWN_VALUES: Final[tuple[str, ...]] = ("providerCatalog", "fakeCatalog", "unresolvedCatalog", "bundledCatalog", "configCatalog",)
+
+# What drove a model selection (tdd SS4.6.1). Open.
+ModelChangeSource = str  # open enum (SS1.5.4): unknown values stay representable
+MODEL_CHANGE_SOURCE_KNOWN_VALUES: Final[tuple[str, ...]] = ("user", "default", "policy",)
+
+# Whether a stored output's bytes are servable (tdd SS4.5.5). Open — durable runtime vocabulary may grow additively.
+OutputRefAvailability = str  # open enum (SS1.5.4): unknown values stay representable
+OUTPUT_REF_AVAILABILITY_KNOWN_VALUES: Final[tuple[str, ...]] = ("available", "missing", "unsupported", "accessFailed",)
+
+# The `pendingRequests` discriminator (tdd SS2.5.2). Open enum, v1 values `approval` and `userInput`.
+PendingRequestKind = str  # open enum (SS1.5.4): unknown values stay representable
+PENDING_REQUEST_KIND_KNOWN_VALUES: Final[tuple[str, ...]] = ("approval", "userInput",)
+
+# The server runtime's platform family (SS1.4.1); may differ from the client's. Closed: SS1.4.1 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, data-model.md §5.2).
+PlatformFamily = Literal["unix", "windows"]
+
+# The server's operating system (SS1.4.1). Closed, for the same reason as [`PlatformFamily`].
+PlatformOs = Literal["macos", "linux", "windows"]
+
+# The reasoning-effort tier sampled at submission (tdd SS3.2, SS3.3). 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".
+ReasoningEffort = Literal["none", "minimal", "low", "medium", "high", "xhigh", "max", "ultra"]
+
+# What drove a reasoning-effort default change (tdd SS4.6.9). Open; v1's only producer is `user` (an accepted `session/setReasoningEffort`).
+ReasoningEffortChangeSource = str  # open enum (SS1.5.4): unknown values stay representable
+REASONING_EFFORT_CHANGE_SOURCE_KNOWN_VALUES: Final[tuple[str, ...]] = ("user", "default", "policy",)
+
+# A request id (SS1.3): client-chosen string or integer. `1` and `"1"` do not compare equal; each direction owns its own id space.
+RequestId = int | str
+
+# Whether this host writes its sessions to disk (SS1.4.1, SS2.13). 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 (#14401) has candidate resolutions that add a third value here, so closed would make that a breaking change.
+SessionDurability = str  # open enum (SS1.5.4): unknown values stay representable
+SESSION_DURABILITY_KNOWN_VALUES: Final[tuple[str, ...]] = ("durable", "ephemeral",)
+
+# Startup failure posture for a session MCP server.
+SessionMcpServerMode = Literal["required", "optional"]
+
+# Stdio framing choices exposed by session MCP configuration.
+SessionMcpStdioFraming = Literal["auto", "contentLength", "lineDelimitedJson"]
+
+# A session's load state (tdd SS2.4).
+SessionStatus = str  # open enum (SS1.5.4): unknown values stay representable
+SESSION_STATUS_KNOWN_VALUES: Final[tuple[str, ...]] = ("notLoaded", "idle", "running",)
+
+# The view-health state (tdd SS2.5.2 companion). 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 (ADR 32557 D1 names it `healthy`) and for the #14401 durable-degraded axis, so no never-emitted token is baked onto the stable surface now.
+SessionViewHealth = str  # open enum (SS1.5.4): unknown values stay representable
+SESSION_VIEW_HEALTH_KNOWN_VALUES: Final[tuple[str, ...]] = ("unavailable",)
+
+# A skill row's source scope (tdd SS3.22.1): the projection of the skills crate's `SkillsSourceScope`. Open (server-produced result vocabulary, the #22785 enum-openness rule): a future scope value is additive.
+SkillSource = str  # open enum (SS1.5.4): unknown values stay representable
+SKILL_SOURCE_KNOWN_VALUES: Final[tuple[str, ...]] = ("bundled", "user", "project", "plugin",)
+
+# Subagent control status (tdd SS4.5.7, camelCased `SubagentControlStatus`). Open; the generic item `status` is the terminal authority.
+SubagentControlStatus = str  # open enum (SS1.5.4): unknown values stay representable
+SUBAGENT_CONTROL_STATUS_KNOWN_VALUES: Final[tuple[str, ...]] = ("accepted", "starting", "running", "resultReady", "closing", "closed", "recoveryPending", "manualReconciliation",)
+
+# Todo status (tdd SS4.6.3): closed in the runtime, wire-open.
+TodoStatus = str  # open enum (SS1.5.4): unknown values stay representable
+TODO_STATUS_KNOWN_VALUES: Final[tuple[str, ...]] = ("pending", "inProgress", "completed", "cancelled",)
+
+# Turn failure classes (tdd SS4.5.1, `TerminalErrorKind` plus the model-task failure class). Open.
+TurnErrorKind = str  # open enum (SS1.5.4): unknown values stay representable
+TURN_ERROR_KIND_KNOWN_VALUES: Final[tuple[str, ...]] = ("stepLimit", "configError", "projectionError", "logError", "workflowLaunchError", "environmentError", "modelError", "launchError", "authRequired",)
+
+# The `type` discriminator of a turn input part (tdd SS3.2). Closed: an unknown part type is `invalidParams` (tdd SS3.1.2).
+TurnInputPartType = Literal["text", "image", "skill"]
+
+# What `turn/start` did with the input (tdd SS3.2). Resolves OQ-H in v1: since `queue` is the default `ifBusy`, clients need to distinguish these without folding history.
+TurnStartDisposition = str  # open enum (SS1.5.4): unknown values stay representable
+TURN_START_DISPOSITION_KNOWN_VALUES: Final[tuple[str, ...]] = ("started", "queued", "steered",)
+
+# Turn terminal vocabulary (tdd SS4.5.1): exactly the runtime's `RunTerminalKind` — closed in the runtime, wire-open for evolution.
+TurnTerminal = str  # open enum (SS1.5.4): unknown values stay representable
+TURN_TERMINAL_KNOWN_VALUES: Final[tuple[str, ...]] = ("completed", "failed", "cancelled",)
+
+UserInputOutcome = str  # open enum (SS1.5.4): unknown values stay representable
+USER_INPUT_OUTCOME_KNOWN_VALUES: Final[tuple[str, ...]] = ("answered", "cancelled", "interrupted", "clarified", "timedOut", "aborted",)
+
+UserInputSelectionMode = Literal["single", "multiple"]
+
+# Version-control system of a branch observation (tdd SS4.6.4). Open.
+Vcs = str  # open enum (SS1.5.4): unknown values stay representable
+VCS_KNOWN_VALUES: Final[tuple[str, ...]] = ("git", "sapling",)
+
+# The `view/page` request-mode anchor (tdd SS4.7.3). Declared **open**: the tdd spells it "open string enum, v1 value `latestCompaction`".
+ViewPageAnchor = str  # open enum (SS1.5.4): unknown values stay representable
+VIEW_PAGE_ANCHOR_KNOWN_VALUES: Final[tuple[str, ...]] = ("latestCompaction",)
+
+# The `view/page` paging direction (tdd SS4.7.3). Closed: the tdd spells exactly two values and a third would change the paging contract.
+ViewPageDirection = Literal["forward", "backward"]
+
+# Which control to apply to the child's current attempt (tdd SS3.20). Closed on the wire: an unknown value is `-32602 invalidParams`.
+WorkflowChildAction = Literal["skip", "retry"]
+
+class ApprovalAmendment(TypedDict):
+    durability: ApprovalAmendmentDurability
+    rulePreview: str
+
+
+class _ApprovalChangeBase(TypedDict):
+    kind: str
+
+
+class ApprovalChange(_ApprovalChangeBase, total=False):
+    choiceId: str
+    decision: ApprovalDecision
+    executable: bool
+    reason: str
+    reparsed: bool
+    requirementId: ApprovalRequirementRef
+    status: ApprovalPersistenceStatus
+
+
+class _ApprovalChoiceBase(TypedDict):
+    choiceId: str
+    decision: ApprovalDecision
+    label: str
+    scope: ApprovalChoiceScope
+
+
+class ApprovalChoice(_ApprovalChoiceBase, total=False):
+    acceptsFeedback: bool
+    rulePreview: str
+
+
+class _ApprovalDecideParamsBase(TypedDict):
+    approvalId: str
+    choiceId: str
+    commandId: str
+    requirementId: ApprovalRequirementRef
+    sessionId: str
+
+
+class ApprovalDecideParams(_ApprovalDecideParamsBase, total=False):
+    """`approval/decide` params (tdd SS5.4): the decision. A standard SS3 command — requires the session loaded on this host, requires `commandId`, durable intake before ack, value-identical replay."""
+
+    feedback: str | None
+
+
+class ApprovalDecideResult(TypedDict):
+    """`approval/decide` result (tdd SS5.4). Admission-ack rules still apply: the authoritative outcome is `approval/resolved` / `approval/updated` on the view stream."""
+
+    approvalId: str
+    commandId: str
+    status: CommandStatus
+    terminal: bool
+
+
+class ApprovalListPendingParams(TypedDict):
+    """`approval/listPending` params (tdd SS5.7): the pull dual of the re-issued requests. A log-fold read — no lease, works on loaded and unloaded sessions, never subscribes."""
+
+    sessionId: str
+
+
+class ApprovalListPendingResult(TypedDict):
+    """`approval/listPending` result (tdd SS5.7). 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."""
+
+    approvals: list[ApprovalRequestParams]
+    userInputs: list[UserInputRequestParams]
+
+
+class _ApprovalOriginBase(TypedDict):
+    kind: str
+
+
+class ApprovalOrigin(_ApprovalOriginBase, total=False):
+    command: str
+    url: str
+
+
+class ApprovalRequestParams(TypedDict):
+    """Full params shared by `approval/request` and `approval/requested`."""
+
+    approvalId: str
+    availableChoices: list[ApprovalChoice]
+    currentRequirementId: ApprovalRequirementRef
+    itemId: str
+    judgeEscalated: bool
+    protectedWrite: bool
+    rawArgs: str
+    sessionId: str
+    sourceRange: SourceRange
+    subject: ApprovalSubject
+    taskId: str
+    toolCallId: str
+    toolName: str
+    turnId: str
+    viewCursor: str
+
+
+class ApprovalRequirementRef(TypedDict):
+    """Approval-stage token carried in SS5 params and stale-requirement errors."""
+
+    approvalId: str
+    sourceIndex: int
+
+
+class ApprovalResolutionSummary(TypedDict):
+    """Winning terminal returned to a losing `approval/decide` command."""
+
+    decision: str
+    resolvedBy: str
+    viewCursor: str
+
+
+class _ApprovalResolvedParamsBase(TypedDict):
+    approvalId: str
+    decision: ApprovalDecision
+    itemId: str
+    policyResult: ApprovalPolicyResult
+    resolvedBy: ApprovalResolvedBy
+    sessionId: str
+    sourceRange: SourceRange
+    stageEvidence: list[ApprovalStageEvidence]
+    turnId: str
+    viewCursor: str
+
+
+class ApprovalResolvedParams(_ApprovalResolvedParamsBase, total=False):
+    """`approval/resolved` params: the first durable terminal decision."""
+
+    amendment: ApprovalAmendment
+    decidedByCommandId: str
+
+
+class _ApprovalStageBase(TypedDict):
+    argv: list[str]
+    argvComplete: bool
+    position: int
+    requirementId: ApprovalRequirementRef
+    resolution: ApprovalStageResolution
+    totalStages: int
+
+
+class ApprovalStage(_ApprovalStageBase, total=False):
+    suggestedPrefix: ApprovalSuggestedPrefix
+
+
+class ApprovalStageEvidence(TypedDict):
+    argv: list[str]
+    position: int
+    requirementId: ApprovalRequirementRef
+    resolution: ApprovalStageResolution
+    totalStages: int
+
+
+class _ApprovalStageResolutionBase(TypedDict):
+    kind: str
+
+
+class ApprovalStageResolution(_ApprovalStageResolutionBase, total=False):
+    argvPrefix: list[str]
+    diagnostic: str
+
+
+class _ApprovalSubjectBase(TypedDict):
+    kind: str
+
+
+class ApprovalSubject(_ApprovalSubjectBase, total=False):
+    """Open approval subject union. Unknown kinds are rendered generically and never auto-approved by clients (tdd SS5.2)."""
+
+    access: str
+    command: str
+    host: str
+    origin: ApprovalOrigin
+    path: str
+    port: int
+    protocol: str
+    stages: list[ApprovalStage]
+    target: str
+    toolName: str
+    workspaceRoot: str
+
+
+class ApprovalSuggestedPrefix(TypedDict):
+    argvPrefix: list[str]
+    label: str
+
+
+class ApprovalUpdatedParams(TypedDict):
+    """`approval/updated` params: the refreshed pending view plus one change."""
+
+    approvalId: str
+    availableChoices: list[ApprovalChoice]
+    change: ApprovalChange
+    currentRequirementId: ApprovalRequirementRef
+    sessionId: str
+    sourceRange: SourceRange
+    subject: ApprovalSubject
+    viewCursor: str
+
+
+class _BranchStateBase(TypedDict):
+    branch: str | None
+    workspaceRoot: str
+
+
+class BranchState(_BranchStateBase, total=False):
+    """The latest branch observation in the snapshot (tdd SS4.6.4, SS4.9.1)."""
+
+    vcs: Vcs
+
+
+class ClientCapabilities(TypedDict, total=False):
+    """The client's requested capability posture (SS1.4.1). Every member defaults; an absent `capabilities` object means all defaults."""
+
+    experimentalApi: bool
+    optOutNotificationMethods: list[str]
+    requestedCapabilities: list[str]
+    userInputDialogs: bool
+
+
+class _ClientInfoBase(TypedDict):
+    name: str
+    version: str
+
+
+class ClientInfo(_ClientInfoBase, total=False):
+    """Client identification inside `initialize` params (SS1.4.1). Diagnostics and telemetry attribution only; never an authority claim (SS1.10)."""
+
+    title: str
+
+
+class CommandAcceptedResult(TypedDict):
+    """The uniform SS3.1.2 command acknowledgement: admission only, never an outcome. `session/compact` alone may answer `\"noop\"`; every other command answers `\"accepted\"`."""
+
+    commandId: str
+    status: CommandAckStatus
+
+
+class _ContextUsageBase(TypedDict):
+    pressure: ContextPressureLevel
+    usedTokens: int
+
+
+class ContextUsage(_ContextUsageBase, total=False):
+    """The SS4.9.1 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)."""
+
+    windowTokens: int
+
+
+class CumulativeTokenUsage(TypedDict):
+    """Session running totals of counted-once usage (tdd SS4.6.5)."""
+
+    outputTokens: int
+    promptTokens: int
+    totalTokens: int
+
+
+class EffectiveApprovalModeState(TypedDict):
+    """The effective approval-mode projection (`EffectiveApprovalModeState`, tdd SS5.12): the same object `session/setApprovalMode` returns as `effectiveMode` and the `Session` object carries as `approvalMode`."""
+
+    lastCommandId: str | None
+    mode: ApprovalMode
+    source: ApprovalModeSource
+
+
+class EffectiveModel(TypedDict):
+    """The latest effective-model fact in the snapshot (tdd SS4.9.1)."""
+
+    modelId: str
+    providerId: str | None
+    source: ModelChangeSource
+
+
+class _ErrorDataBase(TypedDict):
+    kind: ErrorKind
+
+
+class ErrorData(_ErrorDataBase, total=False):
+    """The optional `error.data` object (SS1.6). All members additive-optional; `kind` is always present when `data` is."""
+
+    alignedNextOffset: int
+    anchor: str | None
+    approvalId: str
+    availability: str
+    capability: CapabilityName
+    capacity: int
+    choiceId: str
+    commandId: str
+    currentRequirementId: ApprovalRequirementRef
+    descriptor: str
+    details: dict[str, Any]
+    earliestCursor: str | None
+    itemId: str
+    lastTurnId: str
+    latestBoundaryCursor: str | None
+    limitBytes: int
+    outputRef: str
+    paths: list[str]
+    reason: str
+    resolution: ApprovalResolutionSummary
+    retryable: bool
+    selector: str
+    sessionId: str
+    settlement: UserInputSettlementSummary
+    userInputId: str
+    viewCursor: str
+
+
+class _ErrorObjectBase(TypedDict):
+    code: int
+    message: str
+
+
+class ErrorObject(_ErrorObjectBase, total=False):
+    """The `error` member of an error response (SS1.2 §2.4)."""
+
+    data: ErrorData
+
+
+class ErrorResponse(TypedDict):
+    """An error response frame (SS1.2 §2.4). Exactly one of `result` or `error` appears on a response; this type is the `error` half."""
+
+    error: ErrorObject
+    id: RequestId | None
+    jsonrpc: JsonRpcVersion
+
+
+class ForkCutPoint(TypedDict):
+    """Where a fork cuts the source history (tdd SS2.5.3). Turn ids are used instead of counts because ids stay stable across compaction and concurrent appends while indices do not."""
+
+    lastTurnId: str
+
+
+class ForkProvenance(TypedDict):
+    """Fork provenance folded from the durable `session.fork.created` record (`ForkProvenance`, tdd SS2.4)."""
+
+    commandId: str
+    cutCursor: str
+    cutExplicit: bool
+    sessionId: str
+
+
+class _GoalBase(TypedDict):
+    objective: str
+    percentComplete: int
+    status: str
+
+
+class Goal(_GoalBase, total=False):
+    """The session goal block (tdd SS4.6.2, mirrors the runtime's goal state, camelCased). `status` and `percentComplete` are carried **verbatim** — out-of-contract status strings and >100 percents pass through; display clamping is the renderer's job."""
+
+    currentWork: str
+    nextWork: str
+
+
+class GoalClearParams(TypedDict):
+    """`goal/clear` params (tdd SS3.18). An `objective` here is an unknown field and rejects `-32602 invalidParams` — the bare verbs carry exactly this pair."""
+
+    commandId: str
+    sessionId: str
+
+
+class _GoalCommandResultBase(TypedDict):
+    commandId: str
+    status: CommandStatus
+
+
+class GoalCommandResult(_GoalCommandResultBase, total=False):
+    """The shared SS3.18 goal ack, admission-only: all five verbs answer this one shape (the tdd's \"Shared contract\"), differing only in when `turnId` is present."""
+
+    turnId: str
+
+
+class GoalEditParams(TypedDict):
+    """`goal/edit` params (tdd SS3.18): replace the current goal's objective. Same shape as `goal/set`; the verbs differ in their `missing_goal` precondition, not their payload."""
+
+    commandId: str
+    objective: str
+    sessionId: str
+
+
+class GoalPauseParams(TypedDict):
+    """`goal/pause` params (tdd SS3.18); shape as `goal/clear`."""
+
+    commandId: str
+    sessionId: str
+
+
+class GoalResumeParams(TypedDict):
+    """`goal/resume` params (tdd SS3.18); shape as `goal/clear`."""
+
+    commandId: str
+    sessionId: str
+
+
+class GoalSetParams(TypedDict):
+    """`goal/set` params (tdd SS3.18): set the session's goal objective."""
+
+    commandId: str
+    objective: str
+    sessionId: str
+
+
+class _InitializeParamsBase(TypedDict):
+    clientInfo: ClientInfo
+
+
+class InitializeParams(_InitializeParamsBase, total=False):
+    """`initialize` request params (SS1.4.1)."""
+
+    capabilities: ClientCapabilities
+
+
+class _InitializeResultBase(TypedDict):
+    experimentalApi: bool
+    grantedCapabilities: list[CapabilityName]
+    museHome: str
+    platformFamily: PlatformFamily
+    platformOs: PlatformOs
+    schema: SchemaInfo
+    serverInfo: ServerInfo
+    userAgent: str
+
+
+class InitializeResult(_InitializeResultBase, total=False):
+    """The `initialize` result (SS1.4.1)."""
+
+    sessionDurability: SessionDurability
+
+
+class _ItemBase(TypedDict):
+    itemId: str
+    kind: ItemKind
+    revision: int
+    status: ItemStatus
+
+
+class Item(_ItemBase, total=False):
+    """One transcript item at one revision (tdd SS4.4.1 common fields plus the per-kind fields of SS4.5.2–4.5.10, all optional and owned by the kind their doc names). `item/started`, `item/updated`, and `item/completed` carry the full object; `item/delta` appends to it by field path."""
+
+    agentPath: str
+    approvalId: str
+    args: str
+    attachments: list[MessageAttachment]
+    background: bool
+    backgroundInitiator: BackgroundInitiator
+    callId: str
+    childSessionId: str
+    childSessionLogPath: str
+    children: list[WorkflowChild]
+    commandId: str
+    commandText: str
+    controlStatus: SubagentControlStatus
+    depth: int
+    displayText: str
+    durationMs: int
+    entryId: str
+    exitCode: int
+    exitSignal: int
+    failureKind: str
+    failureReason: str
+    fallbackText: str
+    generationId: int
+    message: str
+    modelVisibleContent: list[ModelVisibleContent]
+    objective: str
+    outcome: CompactionOutcome
+    outputRef: OutputRef
+    patchRef: OutputRef
+    patchSummary: PatchSummary
+    providerItemId: str
+    reason: str
+    recordedAt: str
+    reminderAgentId: str
+    result: SubagentResult
+    resumeFromRunId: str
+    retracted: bool
+    role: str
+    scriptId: str
+    steered: bool
+    strategyId: str
+    subagentId: str
+    summarizedThrough: str
+    summary: list[str]
+    taskId: str
+    text: str
+    tokensAfter: int
+    tokensBefore: int
+    tool: str
+    trigger: CompactionTrigger
+    triggerSource: str
+    truncated: bool
+    turnId: str | None
+    usage: TokenUsage
+    visibleOutput: str
+    workflowRunId: str
+
+
+class ItemCompletedParams(TypedDict):
+    """`item/completed` params (tdd SS4.3): the item reached its terminal state — the authoritative final object. Always cites a durable `sourceRange` (tdd SS4.2). Clients MUST accept `item/completed` for an `itemId` they never saw `item/started` for (single-shot kinds; after a gap fill; tdd SS4.4.1)."""
+
+    item: Item
+    sessionId: str
+    sourceRange: SourceRange
+    viewCursor: str
+
+
+class _ItemDeltaParamsBase(TypedDict):
+    delta: str
+    itemId: str
+    sessionId: str
+    viewCursor: str
+
+
+class ItemDeltaParams(_ItemDeltaParamsBase, total=False):
+    """`item/delta` params (tdd SS4.3.1): 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 (spec 14653 INV-009 — the schema enforces the exemption). Deltas never bump `revision`."""
+
+    field: str
+
+
+class _ItemReadOutputParamsBase(TypedDict):
+    itemId: str
+    outputRef: str
+    sessionId: str
+
+
+class ItemReadOutputParams(_ItemReadOutputParamsBase, total=False):
+    """`item/readOutput` params (tdd SS4.7.4): byte-ranged fetch of stored full output that the view truncated — the `outputRef` fetch path SS3.9 and SS4.5.5 owe. Read-only; works on loaded and unloaded sessions; no lease."""
+
+    lengthBytes: int
+    offsetBytes: int
+
+
+class ItemReadOutputResult(TypedDict):
+    """`item/readOutput` result (tdd SS4.7.4): one stored-byte page."""
+
+    byteLen: int
+    content: str
+    encoding: ItemReadOutputEncoding
+    eof: bool
+    mediaType: str
+    offsetBytes: int
+
+
+class _ItemStartedParamsBase(TypedDict):
+    item: Item
+    sessionId: str
+    viewCursor: str
+
+
+class ItemStartedParams(_ItemStartedParamsBase, total=False):
+    """`item/started` params (tdd SS4.3): 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` (tdd SS4.2)."""
+
+    sourceRange: SourceRange
+
+
+class ItemUpdatedParams(TypedDict):
+    """`item/updated` params (tdd SS4.4.2): 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)."""
+
+    item: Item
+    sessionId: str
+    sourceRange: SourceRange
+    viewCursor: str
+
+
+class _MessageAttachmentBase(TypedDict):
+    mediaType: str
+    type: str
+
+
+class MessageAttachment(_MessageAttachmentBase, total=False):
+    """`userMessage` image attachment metadata (tdd SS4.5.2): metadata only — the durable bytes live in the log and are reachable on the raw altitude."""
+
+    height: int
+    width: int
+
+
+class ModelCatalogEntry(TypedDict):
+    """One visible catalog row (tdd SS3.10). Catalog rows marked hidden never reach the wire, so a client cannot select one."""
+
+    contextLimit: int | None
+    cost: ModelCost | None
+    description: str | None
+    displayLabel: str
+    isActive: bool
+    isDefault: bool
+    modelId: str
+    outputLimit: int | None
+    profileId: str | None
+    providerId: str
+    releaseDate: str | None
+
+
+class ModelCost(TypedDict):
+    """Per-1M-token catalog cost, carried **verbatim** for display and never rounded or re-formatted by the host (tdd SS3.10). Cost arithmetic stays client-local view math."""
+
+    cached: str
+    currency: str | None
+    input: str
+    output: str
+
+
+class ModelListParams(TypedDict, total=False):
+    """`model/list` params (tdd SS3.10): the discovery half of the model-picker gesture. **A query, not a command** — no `commandId`, no durable intake record, no view event."""
+
+    sessionId: str
+
+
+class ModelListResult(TypedDict):
+    """`model/list` result (tdd SS3.10). 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."""
+
+    models: list[ModelCatalogEntry]
+    profileId: str | None
+    providerId: str
+    source: ModelCatalogSource
+
+
+class _ModelSelectionBase(TypedDict):
+    modelId: str
+
+
+class ModelSelection(_ModelSelectionBase, total=False):
+    """A model selection (tdd SS3.8). Empty strings are normalized to absent."""
+
+    displayLabel: str
+    profileId: str | None
+    providerId: str
+
+
+class _ModelVisibleContentBase(TypedDict):
+    mediaType: str
+    path: str
+    sourceToolName: str
+    type: str
+
+
+class ModelVisibleContent(_ModelVisibleContentBase, total=False):
+    """Rich content the model saw beyond text (tdd SS4.5.5, `ModelVisibleToolContent`): metadata only — fetch bytes via `item/readOutput` when an `outputRef` exists."""
+
+    height: int
+    width: int
+
+
+class _NotificationBase(TypedDict):
+    jsonrpc: JsonRpcVersion
+    method: str
+
+
+class Notification(_NotificationBase, total=False):
+    """A notification frame, either direction (SS1.2 §2.2). No `id`; a notification is never answered."""
+
+    emittedAtMs: int
+    params: dict[str, Any]
+
+
+class _OutputRefBase(TypedDict):
+    availability: OutputRefAvailability
+    byteLen: int
+    id: str
+    kind: str
+    uri: str
+
+
+class OutputRef(_OutputRefBase, total=False):
+    """Stored-output reference (tdd SS4.5.5): the camelCased fold of the durable `ToolOutputRef`. The fetch path is `item/readOutput` (#208)."""
+
+    digest: str
+    mediaType: str
+    path: str
+
+
+class PatchSummary(TypedDict):
+    """Server-authored edit-family diff summary (tdd SS4.5.5, #33025): `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`."""
+
+    added: int
+    files: int
+    removed: int
+
+
+class _PendingApprovalPointerBase(TypedDict):
+    approvalId: str
+    viewCursor: str
+
+
+class PendingApprovalPointer(_PendingApprovalPointerBase, total=False):
+    """A pending approval in the snapshot: the SS2.5.2 pointer shape plus the gated `itemId` when one exists (tdd SS4.9.1)."""
+
+    itemId: str
+
+
+class _PendingRequestPointerBase(TypedDict):
+    kind: PendingRequestKind
+    viewCursor: str
+
+
+class PendingRequestPointer(_PendingRequestPointerBase, total=False):
+    """A late-joiner pointer at an unsettled server-initiated request (tdd SS2.5.2, SS2.2.1). The full payloads arrive as re-issued server-to-client requests right after a `session/resume` response (tdd SS5.6); `session/read` never re-issues them (tdd SS2.5.5).  **A second E4 instance, RULED with E4 (#22785, owner, 2026-08-26): the flat discriminated-object precedent is accepted for this type too, on the `ApprovalSubject` precedent, with the serialized JSON unchanged. A strict union node kind may be funded later; if it is, it must cover both this type and `TurnInputPart`.** SS2.5.2 ratifies two kind-discriminated entry shapes (`{kind: \"approval\", approvalId, viewCursor}` / `{kind: \"userInput\", userInputId, viewCursor}`); this is one flat object with both ids optional, so the published schema accepts `{\"kind\":\"approval\",\"userInputId\":…}` and an entry carrying no id at all. The v1 model names no object-variant union (the `ApprovalSubject` precedent, followed for `TurnInputPart`), and this instance differs from that one in a way the ruling should see: `kind` here is an OPEN enum, where `TurnInputPart.type` is closed."""
+
+    approvalId: str
+    userInputId: str
+
+
+class _PendingUserInputPointerBase(TypedDict):
+    userInputId: str
+    viewCursor: str
+
+
+class PendingUserInputPointer(_PendingUserInputPointerBase, total=False):
+    """A pending user-input prompt in the snapshot (tdd SS4.9.1, SS5.10)."""
+
+    itemId: str
+
+
+class ReasoningEffortState(TypedDict):
+    """The snapshot's standing session-default reasoning effort (tdd SS4.9.1, ADR 31255 D1): the fold of the latest completed `runtime.reasoning_effort_reconfigure` fact — the same pair `session/reasoningEffortChanged` carries."""
+
+    reasoningEffort: ReasoningEffort
+    source: ReasoningEffortChangeSource
+
+
+class RecordPosition(TypedDict):
+    """One end of a [`SourceRange`]: a record's event id and its sequence number within the stream (tdd SS4.2)."""
+
+    id: str
+    sequence: int
+
+
+class _RequestBase(TypedDict):
+    id: RequestId
+    jsonrpc: JsonRpcVersion
+    method: str
+
+
+class Request(_RequestBase, total=False):
+    """A request frame, either direction (SS1.2 §2.1)."""
+
+    params: dict[str, Any]
+    trace: TraceContext
+
+
+class RequestReceipt(TypedDict):
+    """The SS5.3.3 presentation receipt — the client's response to a server-initiated request (`approval/request`, `userInput/request`).  The response acknowledges presentation only (\"a surface showed or will show this\"): it changes no state, the server uses it for diagnostics alone, and the decision/answer travels as a command (`approval/decide`, `userInput/answer`). An error response or a dropped connection means this connection could not present the request; the approval or prompt stays pending and the request is re-issued on the next subscribe (SS5.6). There is no dismiss-without-deciding on the wire."""
+
+    pass
+
+
+class SchemaInfo(TypedDict):
+    """The `schema` pair in [`InitializeResult`] (SS1.4.1, SS1.5.3). `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 (INV-006a)."""
+
+    fingerprint: str
+    version: int
+
+
+class ServerInfo(TypedDict):
+    """Server identification inside [`InitializeResult`]."""
+
+    name: str
+    version: str
+
+
+class _SessionBase(TypedDict):
+    activeTurnId: str | None
+    createdAt: str
+    forkedFrom: ForkProvenance | None
+    modelId: str | None
+    path: str
+    providerId: str | None
+    sessionId: str
+    status: SessionStatus
+    turnCount: int
+    updatedAt: str
+    workspaceRoot: str | None
+
+
+class Session(_SessionBase, total=False):
+    """The session object every lifecycle method returns or lists (tdd SS2.4).  Additive-optional evolution applies: clients must ignore unknown fields."""
+
+    approvalMode: EffectiveApprovalModeState
+    attention: list[AttentionFlag]
+    branch: str
+    firstUserPrompt: str
+    lastActivityAt: str
+    name: str
+    title: str
+
+
+class SessionApprovalModeChangedParams(TypedDict):
+    """`session/approvalModeChanged` params (tdd SS5.12): 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."""
+
+    clientName: str
+    commandId: str
+    mode: ApprovalMode
+    sessionId: str
+    source: ApprovalModeSource
+    sourceRange: SourceRange
+    viewCursor: str
+
+
+class _SessionBranchChangedParamsBase(TypedDict):
+    sessionId: str
+    sourceRange: SourceRange
+    viewCursor: str
+    workspaceRoot: str
+
+
+class SessionBranchChangedParams(_SessionBranchChangedParamsBase, total=False):
+    """`session/branchChanged` params (tdd SS4.6.4): a durable workspace-branch observation landed."""
+
+    branch: str
+    vcs: Vcs
+
+
+class _SessionCompactParamsBase(TypedDict):
+    commandId: str
+    sessionId: str
+
+
+class SessionCompactParams(_SessionCompactParamsBase, total=False):
+    """`session/compact` params (tdd SS3.7): manually compact the session's conversation context — the `/compact` gesture. Compaction runs asynchronously; the ack is admission only."""
+
+    turnId: str
+
+
+class _SessionCompactResultBase(TypedDict):
+    commandId: str
+    status: CompactStatus
+
+
+class SessionCompactResult(_SessionCompactResultBase, total=False):
+    """`session/compact` result (tdd SS3.7). Failures *after* admission (`summarizer_failed`, `install_rejected`, `cancelled`) are not wire errors — they arrive as the compaction's terminal view event."""
+
+    reason: str
+
+
+class SessionConfig(TypedDict, total=False):
+    """The open configuration extension object shared by `session/start` and `session/resume` (ADR 32760 D1).  Unknown keys are ignored on the wire, never rejected (tdd SS1.5.4, spec 206 INV-015; D-052 resolving [#23456](https://github.com/mslsrc/tbh/issues/23456)): the live decoder is D-042's tolerant path, and TEST-024 keeps every exported bundle free of `additionalProperties: false`. The Rust typed model's `deny_unknown_fields` is internal and never exported — the #22785 E6b closedness export applies nowhere, and the `x-msp-closed` opt-in mechanism stays inert. Recognized `mcpServers` values are typed and validated before they leave the wire boundary."""
+
+    mcpServers: dict[str, SessionMcpServerConfig]
+
+
+class _SessionContextUsageParamsBase(TypedDict):
+    pressure: ContextPressureLevel
+    sessionId: str
+    sourceRange: SourceRange
+    usedTokens: int
+    viewCursor: str
+
+
+class SessionContextUsageParams(_SessionContextUsageParamsBase, total=False):
+    """`session/contextUsage` params (tdd SS4.6.6, #14405): 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)."""
+
+    windowTokens: int
+
+
+class _SessionForkParamsBase(TypedDict):
+    commandId: str
+    sessionId: str
+
+
+class SessionForkParams(_SessionForkParamsBase, total=False):
+    """`session/fork` params (tdd SS2.5.3)."""
+
+    cutPoint: ForkCutPoint
+    excludeItems: bool
+
+
+class SessionForkResult(TypedDict):
+    """`session/fork` result (tdd SS2.5.3): the `session/resume` envelope for the **new** session, whose `session.forkedFrom` carries the provenance."""
+
+    history: SessionHistory
+    pendingRequests: list[PendingRequestPointer]
+    session: Session
+    viewCursor: str
+
+
+class _SessionGoalChangedParamsBase(TypedDict):
+    sessionId: str
+    sourceRange: SourceRange
+    viewCursor: str
+
+
+class SessionGoalChangedParams(_SessionGoalChangedParamsBase, total=False):
+    """`session/goalChanged` params (tdd SS4.6.2): 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."""
+
+    goal: Goal
+
+
+class _SessionHistoryBase(TypedDict):
+    items: list[Item] | None
+    mode: HistoryMode
+    snapshot: ViewSnapshot | None
+
+
+class SessionHistory(_SessionHistoryBase, total=False):
+    """The `history` envelope shared by `session/resume`, `session/fork`, and `session/read` (tdd SS2.5.2)."""
+
+    noneReason: HistoryNoneReason
+
+
+class SessionListParams(TypedDict, total=False):
+    """`session/list` params (tdd SS2.5.4). Read-only; never touches leases."""
+
+    cursor: str | None
+    limit: int
+    updatedAfter: str
+    workspaceRoot: str
+
+
+class SessionListResult(TypedDict):
+    """`session/list` result (tdd SS2.5.4). Ordering is `updatedAt` descending."""
+
+    nextCursor: str | None
+    sessions: list[Session]
+
+
+class _SessionModelChangedParamsBase(TypedDict):
+    modelId: str
+    sessionId: str
+    source: ModelChangeSource
+    sourceRange: SourceRange
+    viewCursor: str
+
+
+class SessionModelChangedParams(_SessionModelChangedParamsBase, total=False):
+    """`session/modelChanged` params (tdd SS4.6.1): a durable model-selection record landed (tdd SS3.8)."""
+
+    providerId: str
+
+
+class _SessionModelRouteUnservedParamsBase(TypedDict):
+    commandId: str
+    installedProviderId: str
+    modelId: str
+    sessionId: str
+    sourceRange: SourceRange
+    viewCursor: str
+
+
+class SessionModelRouteUnservedParams(_SessionModelRouteUnservedParamsBase, total=False):
+    """`session/modelRouteUnserved` params (#25603, ADR 25603 D1, spec 5469 Amendment 16): 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."""
+
+    providerId: str
+
+
+class SessionNameChangedParams(TypedDict):
+    """`session/nameChanged` params (tdd SS4.6.7, #27598): 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 SS4.6 sibling."""
+
+    name: str
+    sessionId: str
+    sourceRange: SourceRange
+    viewCursor: str
+
+
+class _SessionReadParamsBase(TypedDict):
+    sessionId: str
+
+
+class SessionReadParams(_SessionReadParamsBase, total=False):
+    """`session/read` params (tdd SS2.5.5): read one stored session **without attaching** — no writer lease, no load, no subscription, no `SessionResumed` record."""
+
+    excludeItems: bool
+
+
+class SessionReadResult(TypedDict):
+    """`session/read` result (tdd SS2.5.5). The `viewCursor` is the fold head at read time — a point-in-time read, immediately stale if a foreign host is appending."""
+
+    history: SessionHistory
+    pendingRequests: list[PendingRequestPointer]
+    session: Session
+    viewCursor: str
+
+
+class SessionReasoningEffortChangedParams(TypedDict):
+    """`session/reasoningEffortChanged` params (tdd SS4.6.9, ADR 31255 D1): a durable reasoning-effort reconfigure record landed (tdd SS3.21). Replace wholesale, latest wins; the snapshot carries the latest value (SS4.9.1)."""
+
+    reasoningEffort: ReasoningEffort
+    sessionId: str
+    source: ReasoningEffortChangeSource
+    sourceRange: SourceRange
+    viewCursor: str
+
+
+class SessionRenameParams(TypedDict):
+    """`session/rename` params (tdd SS2.14.2, #27598): set or change the durable allocated session name through the runtime `session_name` command. One writer; withheld under the ephemeral profile."""
+
+    commandId: str
+    name: str
+    sessionId: str
+
+
+class _SessionRenameResultBase(TypedDict):
+    commandId: str
+    status: CommandStatus
+
+
+class SessionRenameResult(_SessionRenameResultBase, total=False):
+    """`session/rename` result (tdd SS2.14.2, #27598): `name` is the canonical (normalized) name the durable record settled."""
+
+    name: str
+
+
+class _SessionResumeParamsBase(TypedDict):
+    commandId: str
+    sessionId: str
+
+
+class SessionResumeParams(_SessionResumeParamsBase, total=False):
+    """`session/resume` params (tdd SS2.5.2)."""
+
+    config: SessionConfig
+    cursor: str | None
+    excludeItems: bool
+    history: HistoryPreference
+
+
+class SessionResumeResult(TypedDict):
+    """`session/resume` result (tdd SS2.5.2)."""
+
+    history: SessionHistory
+    pendingRequests: list[PendingRequestPointer]
+    session: Session
+    viewCursor: str
+
+
+class SessionSetApprovalModeParams(TypedDict):
+    """`session/setApprovalMode` params (tdd SS5.12): switch the session's approval enforcement mode mid-session. A standard SS3 command.  **Select, never create.** A client may *select* a mode the host's configuration already defines; it may not construct one, supply inline rules, or otherwise describe a policy on the wire — which is why [`ApprovalMode`] is closed."""
+
+    commandId: str
+    mode: ApprovalMode
+    sessionId: str
+
+
+class SessionSetApprovalModeResult(TypedDict):
+    """`session/setApprovalMode` result (tdd SS5.12). Applies next-action — an in-flight tool action's pending approval is not retroactively decided by a mode change."""
+
+    applyOutcome: ApprovalModeApplyOutcome
+    commandId: str
+    effectiveMode: EffectiveApprovalModeState
+    status: CommandStatus
+
+
+class SessionSetModelParams(TypedDict):
+    """`session/setModel` params (tdd SS3.8): the model-picker gesture. The selection is durable and applies to subsequent model calls."""
+
+    commandId: str
+    model: ModelSelection
+    sessionId: str
+
+
+class SessionSetModelResult(TypedDict):
+    """`session/setModel` result (tdd SS3.8). 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."""
+
+    commandId: str
+    status: CommandStatus
+
+
+class SessionSetReasoningEffortParams(TypedDict):
+    """`session/setReasoningEffort` params (tdd SS3.21, ADR 31255 D1): 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` (SS3.8)."""
+
+    commandId: str
+    reasoningEffort: ReasoningEffort
+    sessionId: str
+
+
+class SessionSetReasoningEffortResult(TypedDict):
+    """`session/setReasoningEffort` result (tdd SS3.21). The default is durable on ack and applies to turns launched after admission; a running turn keeps the request options it already resolved."""
+
+    commandId: str
+    status: CommandStatus
+
+
+class _SessionStartParamsBase(TypedDict):
+    commandId: str
+
+
+class SessionStartParams(_SessionStartParamsBase, total=False):
+    """`session/start` params (tdd SS2.5.1)."""
+
+    approvalMode: ApprovalMode | None
+    config: SessionConfig
+    modelId: str
+    providerId: str | None
+    sessionId: str
+    workspaceRoot: str
+
+
+class SessionStartResult(TypedDict):
+    """`session/start` result (tdd SS2.5.1)."""
+
+    session: Session
+    viewCursor: str
+
+
+class _SessionStatusChangedParamsBase(TypedDict):
+    sessionId: str
+    status: SessionStatus
+    viewCursor: str | None
+
+
+class SessionStatusChangedParams(_SessionStatusChangedParamsBase, total=False):
+    """`session/statusChanged` params (tdd SS4.6.10, ADR 31983 D2): 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)."""
+
+    attention: list[AttentionFlag]
+
+
+class SessionTodoListChangedParams(TypedDict):
+    """`session/todoListChanged` params (tdd SS4.6.3): a `TodoSnapshotUpdated` record landed. Replace the whole list on every event; an empty `items` array is a cleared list, not a no-op."""
+
+    items: list[TodoItem]
+    revision: int
+    sessionId: str
+    sourceRange: SourceRange
+    sourceTool: str
+    viewCursor: str
+
+
+class _SessionTokenUsageParamsBase(TypedDict):
+    cumulative: CumulativeTokenUsage
+    promptTokens: int
+    sessionId: str
+    sourceRange: SourceRange
+    totalTokens: int
+    turnId: str
+    usage: TokenUsage
+    viewCursor: str
+
+
+class SessionTokenUsageParams(_SessionTokenUsageParamsBase, total=False):
+    """`session/tokenUsage` params (tdd SS4.6.5): one per model completion that reports usage. Carries the raw counters verbatim plus the server-derived counted-once `promptTokens`/`totalTokens` (#8803: clients display and sum these and never re-derive the provider's cache convention) and the session `cumulative` block. Accumulate-only: `cumulative` never goes backward."""
+
+    durationMs: int
+    finishReason: str
+    modelId: str
+
+
+class SessionUserShellParams(TypedDict):
+    """`session/userShell` params (tdd SS3.9): 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 SS1.10 spawn boundary."""
+
+    commandId: str
+    commandText: str
+    sessionId: str
+
+
+class SessionUserShellResult(TypedDict):
+    """`session/userShell` result (tdd SS3.9): 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."""
+
+    commandId: str
+    status: CommandStatus
+
+
+class _SessionViewHealthChangedParamsBase(TypedDict):
+    health: SessionViewHealth
+    sessionId: str
+
+
+class SessionViewHealthChangedParams(_SessionViewHealthChangedParamsBase, total=False):
+    """`session/viewHealthChanged` params (ADR 32557; #32557): the named session's live view stream became unavailable, and why.  Best-effort: ordered after already-queued view frames and may be dropped (for example when the connection is closing), so a client MUST NOT assume a guaranteed push and still reads `history.noneReason` on its next resume/read (FM-005)."""
+
+    noneReason: HistoryNoneReason
+
+
+class _SkillCatalogEntryBase(TypedDict):
+    description: str
+    displayName: str
+    selector: str
+    source: SkillSource
+
+
+class SkillCatalogEntry(_SkillCatalogEntryBase, total=False):
+    """One typed-invocable shortcut spelling (tdd SS3.22.1). A plugin skill may contribute two rows: its bare-name winner and its qualified `<pluginId>:<skillId>` form."""
+
+    argumentHint: str
+    pluginId: str
+
+
+class SkillChangedParams(TypedDict):
+    """`skill/changed` params (tdd SS3.22.2): 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 (ADR 32471 D3)."""
+
+    sessionId: str
+
+
+class SkillListParams(TypedDict):
+    """`skill/list` params (tdd SS3.22.1). Per-session because skill scope follows the session's workspace and plugin state."""
+
+    sessionId: str
+
+
+class SkillListResult(TypedDict):
+    """`skill/list` result (tdd SS3.22.1): one row per typed-invocable shortcut spelling — exactly the invocations the first-party typed dispatch accepts (spec 11352 INV-007 predicate and the shared shortcut layer's name resolution, both by call-through; ADR 32471 D2)."""
+
+    skills: list[SkillCatalogEntry]
+
+
+class SnapshotAnchor(TypedDict):
+    """The compaction boundary an anchored snapshot is anchored at (tdd SS2.5.2)."""
+
+    boundaryCursor: str
+    summarizedThrough: str
+
+
+class _SnapshotStateBase(TypedDict):
+    activeTurn: TurnRef | None
+    approvalMode: EffectiveApprovalModeState
+    branch: BranchState | None
+    effectiveModel: EffectiveModel | None
+    goal: Goal | None
+    items: list[Item]
+    pendingApprovals: list[PendingApprovalPointer]
+    pendingUserInputs: list[PendingUserInputPointer]
+    queuedTurns: list[TurnRef]
+    todoList: TodoListState | None
+    tokenUsage: CumulativeTokenUsage
+    turnCount: int
+
+
+class SnapshotState(_SnapshotStateBase, total=False):
+    """The complete folded view at the snapshot cursor (tdd SS4.9.1).  Additive-optional evolution applies exactly as everywhere else; unknown members MUST be ignored, and preserved if re-serialized.  **One served site does not satisfy this type today, escalated under #22785 (E8).** The genesis snapshot rung serves `state: {\"items\": [...]}` alone (`tbh-session-view-serve`'s `materialized_fold.rs`, the `select_genesis_history` call), while the anchored rung serves the full folded state. A schema-validating client resuming with `{\"history\": \"snapshot\"}` against the real fold therefore sees the other required members missing. The fix is a serving change in the #208/#14653 lane (serialize the `SessionViewState` the genesis path already folds, as the anchored path does) plus its own RED against the real fold; it is not a shape change here, because SS4.9.1 ratifies this shape."""
+
+    contextUsage: ContextUsage
+    name: str
+    reasoningEffort: ReasoningEffortState
+
+
+class SourceRange(TypedDict):
+    """The inclusive raw-record range a durable-sourced view event folded from (tdd SS4.2) — 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 (tdd SS7.5; spec 14653 T041/INV-009). In v1 it is an **opaque provenance token**: no wire method reads what it points at (the SS6 raw-log altitude is deferred, #13929).  Ephemeral-sourced events (`item/delta`, and an `item/started` that opens on an ephemeral record) carry no `sourceRange` — ephemeral records may be evicted by retention (tdd SS4.2; spec 14653 INV-009)."""
+
+    first: RecordPosition
+    last: RecordPosition
+    stream: StreamRef
+
+
+class StreamRef(TypedDict):
+    """One raw stream named by a [`SourceRange`] (tdd SS4.2)."""
+
+    id: str
+    kind: str
+
+
+class SubagentInputParams(TypedDict):
+    """Params for `subagent/sendMessage` and `subagent/followupTask` (SS3.16): a child target plus the input body."""
+
+    body: str
+    commandId: str
+    sessionId: str
+    subagentId: str
+
+
+class _SubagentOwnerReasonParamsBase(TypedDict):
+    commandId: str
+    sessionId: str
+    subagentId: str
+
+
+class SubagentOwnerReasonParams(_SubagentOwnerReasonParamsBase, total=False):
+    """Params for `subagent/interrupt`, `subagent/stop`, and `subagent/close` (SS3.16): a child target plus an optional human-readable reason that is preserved on the durable effect record."""
+
+    reason: str
+
+
+class _SubagentResultBase(TypedDict):
+    artifactRefs: list[str]
+    evidenceRefs: list[str]
+    summary: str
+
+
+class SubagentResult(_SubagentResultBase, total=False):
+    """A subagent's result envelope (tdd SS4.5.7, `SubagentResultEnvelope`)."""
+
+    errorKind: str
+    structuredData: dict[str, Any]
+    text: str
+
+
+class SubagentTargetParams(TypedDict):
+    """Params for `subagent/resume`, `subagent/reopen`, and `subagent/readResult` (SS3.16): the bare child target."""
+
+    commandId: str
+    sessionId: str
+    subagentId: str
+
+
+class SubscriptionUsage(TypedDict):
+    """The one usage payload shape: the `usage/read` result's `usage` member and the `usage/changed` params (ADR 32563 D2/D3). The numbers are point-in-time — `observedAtMs` is the host's arrival stamp, so a client renders \"as of\", never implies live data (spec 18742 US-FR-004)."""
+
+    observedAtMs: int
+    tier: str
+    weekly: SubscriptionUsageWeekly
+    window: SubscriptionUsageWindow
+
+
+class SubscriptionUsageWeekly(TypedDict):
+    """The rolling weekly block: same semantics as [`SubscriptionUsageWindow`] without a duration (ADR 32563 D2)."""
+
+    resetsAtMs: int
+    usedPercent: int
+
+
+class SubscriptionUsageWindow(TypedDict):
+    """The current usage window (the provider's 5-hour-class block): verbatim provider percentages with the reset stamp normalized to epoch milliseconds (ADR 32563 D2)."""
+
+    resetsAtMs: int
+    usedPercent: int
+    windowDurationMins: int
+
+
+class SuccessResponse(TypedDict):
+    """A success response frame (SS1.2 §2.3)."""
+
+    id: RequestId
+    jsonrpc: JsonRpcVersion
+    result: dict[str, Any]
+
+
+class TaskBackgroundParams(TypedDict):
+    """`task/background` params (tdd §3.13): durably send a running foreground tool task to the background."""
+
+    commandId: str
+    sessionId: str
+    taskId: str
+
+
+class TaskCommandResult(TypedDict):
+    """The `task/background` / `task/stop` ack (tdd §3.13/§3.14): admission-only, echoing the targeted task."""
+
+    commandId: str
+    status: CommandStatus
+    taskId: str
+
+
+class TaskStopAllParams(TypedDict):
+    """`task/stopAll` params (tdd §3.15): stop every stoppable background workload live at admission."""
+
+    commandId: str
+    sessionId: str
+
+
+class TaskStopAllResult(TypedDict):
+    """The `task/stopAll` ack (tdd §3.15): 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."""
+
+    commandId: str
+    status: CommandStatus
+
+
+class TaskStopParams(TypedDict):
+    """`task/stop` params (tdd §3.14): stop one named background task. Required target, never \"whichever is loudest\" — §3.15 is the blanket verb."""
+
+    commandId: str
+    sessionId: str
+    taskId: str
+
+
+class _TodoItemBase(TypedDict):
+    status: TodoStatus
+    text: str
+
+
+class TodoItem(_TodoItemBase, total=False):
+    """One todo entry (tdd SS4.6.3)."""
+
+    activeForm: str
+
+
+class TodoListState(TypedDict):
+    """The latest todo-list fact in the snapshot (tdd SS4.6.3, SS4.9.1)."""
+
+    items: list[TodoItem]
+    revision: int
+    sourceTool: str
+
+
+class _TokenUsageBase(TypedDict):
+    cachedTokens: int
+    inputTokens: int
+    outputTokens: int
+    reasoningTokens: int
+
+
+class TokenUsage(_TokenUsageBase, total=False):
+    """Raw token counters, verbatim from the durable record (tdd SS4.6.5, the runtime's `Usage`, camelCased). Not directly summable across providers — sum the counted-once derivations instead (#8803)."""
+
+    cacheReadTokens: int
+    cacheWriteTokens: int
+
+
+class TraceContext(TypedDict, total=False):
+    """Optional W3C trace context, on requests in both directions only — never on responses or notifications (SS1.8)."""
+
+    traceparent: str
+    tracestate: str
+
+
+class _TurnCancelParamsBase(TypedDict):
+    commandId: str
+    sessionId: str
+
+
+class TurnCancelParams(_TurnCancelParamsBase, total=False):
+    """`turn/cancel` params (tdd SS3.5): 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`."""
+
+    turnId: str
+
+
+class TurnCancelResult(TypedDict):
+    """`turn/cancel` result (tdd SS3.5): identical envelope to `turn/interrupt`."""
+
+    commandId: str
+    status: CommandStatus
+    turnId: str
+
+
+class _TurnCompletedParamsBase(TypedDict):
+    sessionId: str
+    sourceRange: SourceRange
+    terminal: TurnTerminal
+    turnId: str
+    viewCursor: str
+
+
+class TurnCompletedParams(_TurnCompletedParamsBase, total=False):
+    """`turn/completed` params (tdd SS4.5.1): the run's durable terminal record landed."""
+
+    durationMs: int
+    error: TurnError
+    reason: str
+    timeToFirstTokenMs: int
+    usage: TokenUsage
+
+
+class TurnError(TypedDict):
+    """The settled turn-failure object (tdd SS4.5.1): `{kind, message, retryable}`."""
+
+    kind: TurnErrorKind
+    message: str
+    retryable: bool
+
+
+class _TurnInputPartBase(TypedDict):
+    type: TurnInputPartType
+
+
+class TurnInputPart(_TurnInputPartBase, total=False):
+    """One ordered content part of a turn submission (tdd SS3.2). 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` (tdd SS3.1.2, SS3.2) — which is what closes [`TurnInputPartType`].  Modelled as a discriminated flat object rather than a Rust `enum`, the convention [`crate::view::approval::ApprovalSubject`] already established for a wire union in this crate: the v1 schema model names no object-variant union shape and fails closed on one. The serialized JSON is the tdd shape either way; what a flat object cannot express is \"`mediaType` is required exactly when `type` is `image`\".  **RULED (#22785 E4, owner, 2026-08-26): the precedent is accepted.** A strict union node kind may be funded later as a follow-up; if it is, it must cover [`crate::method::lifecycle::PendingRequestPointer`] too."""
+
+    arguments: str
+    base64Data: str
+    height: int
+    mediaType: str
+    selector: str
+    text: str
+    width: int
+
+
+class _TurnInterruptParamsBase(TypedDict):
+    commandId: str
+    sessionId: str
+
+
+class TurnInterruptParams(_TurnInterruptParamsBase, total=False):
+    """`turn/interrupt` params (tdd SS3.4): the \"user pressed stop\" gesture, on the runtime's priority lane."""
+
+    retract: bool
+    turnId: str
+
+
+class TurnInterruptResult(TypedDict):
+    """`turn/interrupt` result (tdd SS3.4). 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`."""
+
+    commandId: str
+    status: CommandStatus
+    turnId: str
+
+
+class TurnRef(TypedDict):
+    """A turn named by the snapshot's active/queued lists (tdd SS4.9.1)."""
+
+    commandId: str
+    turnId: str
+
+
+class TurnRetractedParams(TypedDict):
+    """`turn/retracted` params (tdd SS4.5.1): an interrupt-paired retract was durably accepted. The retracted user-message item is re-emitted via `item/updated` with `retracted: true`."""
+
+    commandId: str
+    sessionId: str
+    sourceRange: SourceRange
+    turnId: str
+    viewCursor: str
+
+
+class TurnRetryScheduledParams(TypedDict):
+    """`turn/retryScheduled` params (tdd SS4.5.1, spec 14412; D-026): 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 (tdd SS3.1.4). 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 (tdd SS4.2)."""
+
+    attempt: int
+    maxAttempts: int
+    nextAttempt: int
+    reason: str
+    retryDelayMs: int
+    sessionId: str
+    sourceRange: SourceRange
+    turnId: str
+    viewCursor: str
+
+
+class _TurnStartParamsBase(TypedDict):
+    commandId: str
+    input: list[TurnInputPart]
+    sessionId: str
+
+
+class TurnStartParams(_TurnStartParamsBase, total=False):
+    """`turn/start.providerRequestOptions` is deliberately absent: **RULED (#22785 E3, owner, 2026-08-26) to stay off the published schema.** The schema is the contract, and a free-form-object node kind is revisited only if the experimental field graduates. `turn/start` params (tdd SS3.2)."""
+
+    displayText: str
+    ifBusy: IfBusy
+    reasoningEffort: ReasoningEffort
+
+
+class TurnStartResult(TypedDict):
+    """`turn/start` result (tdd SS3.2)."""
+
+    commandId: str
+    disposition: TurnStartDisposition
+    startedNewTurn: bool
+    status: CommandStatus
+    turnId: str
+
+
+class TurnStartedParams(TypedDict):
+    """`turn/started` params (tdd SS4.5.1): a foreground turn began running — fresh submits immediately, queued submits at their launch boundary, never steered submits."""
+
+    commandId: str
+    sessionId: str
+    sourceRange: SourceRange
+    turnId: str
+    viewCursor: str
+
+
+class _TurnSteerParamsBase(TypedDict):
+    commandId: str
+    expectedTurnId: str
+    input: list[TurnInputPart]
+    sessionId: str
+
+
+class TurnSteerParams(_TurnSteerParamsBase, total=False):
+    """`turn/steer` params (tdd SS3.3): exact-target steering into the currently running turn."""
+
+    reasoningEffort: ReasoningEffort
+
+
+class TurnSteerResult(TypedDict):
+    """`turn/steer` result (tdd SS3.3)."""
+
+    commandId: str
+    status: CommandStatus
+    turnId: str
+
+
+class TurnUnqueueParams(TypedDict):
+    """`turn/unqueue` params (tdd SS3.6): 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."""
+
+    commandId: str
+    sessionId: str
+    turnId: str
+
+
+class TurnUnqueueResult(TypedDict):
+    """`turn/unqueue` result (tdd SS3.6). 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."""
+
+    commandId: str
+    status: CommandStatus
+    turnId: str
+
+
+class TurnUnqueuedParams(TypedDict):
+    """`turn/unqueued` params (tdd SS3.6, SS4.5.1): 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` (SDK turn-waits settle on this event too, tdd SS3.1.4). `sourceRange` cites the SESSION stream's reclaim record — a reclaimed turn never had a run stream."""
+
+    commandId: str
+    sessionId: str
+    sourceRange: SourceRange
+    turnId: str
+    viewCursor: str
+
+
+class UnframedViewNotification(TypedDict):
+    """One element of a `view/page` result's `events` array: an **unframed view notification** exactly as tdd SS4.2.1 defines it — 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. SS4.2.1 is the single normative definition; SS4.7.3 and SS7.4 both cite it, so the two surfaces cannot drift."""
+
+    method: str
+    params: UnframedViewNotificationParams
+
+
+class UnframedViewNotificationParams(TypedDict):
+    """The `params` of an unframed view notification (tdd SS4.2.1, SS4.2).  Declares the SS4.2 base members every view notification carries, and stays **open** for the event-specific fields SS4.5/SS4.6/SS5 add per event type. The v1 schema model names no method-correlated union (the SS4.7.3 `events` element's `params` arm is selected by its sibling `method`), so the per-event arms cannot be expressed here without one; enumerating them as an uncorrelated union would additionally exclude `turn/unqueued`, whose notification row is another lane's ratified deferral (#207/#14407) — a published schema that rejects a real page element is the exact #19923 defect this PR exists to close. Recorded as a Design delta on #22785.  `sourceRange` is required here and not optional: `view/page` serves durable-sourced events only (tdd SS4.7.3), and durable-sourced is *defined* as carrying a `sourceRange` — the SS4.2 ephemeral-sourced exemption applies to `item/delta`, which `view/page` never replays."""
+
+    sessionId: str
+    sourceRange: SourceRange
+    viewCursor: str
+
+
+class UsageReadResult(TypedDict, total=False):
+    """`usage/read` result: `{usage?}` — omitted, never `null`, when the host has observed nothing (ADR 32563 D2: truthful absence, no \"nothing observed\" error)."""
+
+    usage: SubscriptionUsage
+
+
+class _UserInputAnswerBase(TypedDict):
+    questionId: str
+
+
+class UserInputAnswer(_UserInputAnswerBase, total=False):
+    freeText: str
+    note: str
+    selectedLabel: str
+    selectedLabels: list[str]
+
+
+class UserInputAnswerParams(TypedDict):
+    """`userInput/answer` params (tdd SS5.10.2): answer every question.  Each answer carries `questionId` then exactly one of `selectedLabel` (single mode), `selectedLabels` (multiple mode, within min/max bounds), or `freeText` (<=500 chars); plus an optional `note` (<=500). Answers that do not match the prompt fail -32057 `userInputAnswerInvalid`. Image `attachments` are a **reserved** field in v1, rejected if sent, because the blob-upload path they reference is reserved in tdd SS3.2."""
+
+    answers: list[UserInputAnswer]
+    commandId: str
+    sessionId: str
+    userInputId: str
+
+
+class UserInputAnswerResult(TypedDict):
+    """`userInput/answer` result (tdd SS5.10.2)."""
+
+    commandId: str
+    status: CommandStatus
+    userInputId: str
+
+
+class _UserInputCancelParamsBase(TypedDict):
+    commandId: str
+    sessionId: str
+    userInputId: str
+
+
+class UserInputCancelParams(_UserInputCancelParamsBase, total=False):
+    """`userInput/cancel` params (tdd SS5.10.2): decline to answer; the tool call resolves with a cancelled result the model sees."""
+
+    reason: str
+
+
+class UserInputCancelResult(TypedDict):
+    """`userInput/cancel` result (tdd SS5.10.2)."""
+
+    commandId: str
+    status: CommandStatus
+    userInputId: str
+
+
+class UserInputClarification(TypedDict):
+    content: str
+    format: str
+
+
+class UserInputClarifyParams(TypedDict):
+    """`userInput/clarify` params (tdd SS5.10.2): 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."""
+
+    clarification: UserInputClarification
+    commandId: str
+    sessionId: str
+    userInputId: str
+
+
+class UserInputClarifyResult(TypedDict):
+    """`userInput/clarify` result (tdd SS5.10.2)."""
+
+    commandId: str
+    status: CommandStatus
+    userInputId: str
+
+
+class _UserInputOptionBase(TypedDict):
+    label: str
+
+
+class UserInputOption(_UserInputOptionBase, total=False):
+    description: str
+    preview: UserInputOptionPreview
+
+
+class UserInputOptionPreview(TypedDict):
+    content: str
+    format: str
+
+
+class UserInputQuestion(TypedDict):
+    header: str
+    id: str
+    options: list[UserInputOption]
+    question: str
+    selection: UserInputSelection
+
+
+class _UserInputRequestParamsBase(TypedDict):
+    itemId: str
+    questions: list[UserInputQuestion]
+    sessionId: str
+    toolCallId: str
+    toolName: str
+    turnId: str
+    userInputId: str
+    viewCursor: str
+
+
+class UserInputRequestParams(_UserInputRequestParamsBase, total=False):
+    """Full params shared by `userInput/request` and `userInput/requested`."""
+
+    autoResolutionMs: int
+    sourceRange: SourceRange
+
+
+class _UserInputSelectionBase(TypedDict):
+    mode: UserInputSelectionMode
+
+
+class UserInputSelection(_UserInputSelectionBase, total=False):
+    maxSelections: int
+    minSelections: int
+
+
+class UserInputSettledParams(TypedDict):
+    """`userInput/settled` params: the first durable prompt settlement."""
+
+    answers: list[UserInputAnswer]
+    clarification: UserInputClarification | None
+    decidedByCommandId: str | None
+    outcome: UserInputOutcome
+    reason: str | None
+    sessionId: str
+    sourceRange: SourceRange
+    userInputId: str
+    viewCursor: str
+
+
+class UserInputSettlementSummary(TypedDict):
+    """Winning terminal returned to a late user-input command."""
+
+    outcome: str
+    viewCursor: str
+
+
+class ViewGapParams(TypedDict):
+    """`view/gap` params (spec 208 SS4.8, FM-001): push delivery dropped events, and this names the hole.  The bracket is deferred (D-16487-2): it flushes at the subscription's next ACCEPTED delivery, never at enqueue time, so `next` always names an event whose own delivery is proven. A run of consecutive undelivered events coalesces into one bracket keeping the FIRST range's `after` (D-16487-1). The gap rides the protected reserved queue, so no wire-interleaving order against neighbouring deliveries is promised — the cursors carry the semantics (INV-002, D-16487-3).  On receipt a client may take either sanctioned recovery (D-030, FR-013): splice-fill — buffer live events at cursors >= `next`, page `(after, next)` forward, discard the overlap, splice — or re-anchor through the anchored read surface. The server requires neither, cannot distinguish clients by their choice, and holds no partial-fill state."""
+
+    after: str
+    next: str
+    sessionId: str
+
+
+class _ViewPageParamsBase(TypedDict):
+    limit: int
+    sessionId: str
+
+
+class ViewPageParams(_ViewPageParamsBase, total=False):
+    """`view/page` params (tdd SS4.7.3): cursor-paged reads of the session view."""
+
+    anchor: ViewPageAnchor
+    cursor: str
+    direction: ViewPageDirection
+
+
+class ViewPageResolvedAnchor(TypedDict):
+    """The `resolvedAnchor` echo (tdd SS4.7.3): subsequent pages pass ordinary cursors, so the anchor never needs re-resolving."""
+
+    boundaryCursor: str
+
+
+class _ViewPageResultBase(TypedDict):
+    events: list[UnframedViewNotification]
+    nextCursor: str | None
+
+
+class ViewPageResult(_ViewPageResultBase, total=False):
+    """`view/page` result (tdd SS4.7.3)."""
+
+    resolvedAnchor: ViewPageResolvedAnchor
+
+
+class _ViewSnapshotBase(TypedDict):
+    schemaVersion: int
+    state: SnapshotState
+    viewCursor: str
+
+
+class ViewSnapshot(_ViewSnapshotBase, total=False):
+    """The `snapshot` object returned by `session/resume` / `session/read` (tdd SS4.9)."""
+
+    anchor: SnapshotAnchor
+
+
+class _ViewSubscribeParamsBase(TypedDict):
+    sessionId: str
+
+
+class ViewSubscribeParams(_ViewSubscribeParamsBase, total=False):
+    """`view/subscribe` params (tdd SS4.7.1): attach this connection's live view subscription for a session at an explicit cursor — the fine-grained counterpart of the SS2 auto-subscribe, and the gap-free re-attachment path after `view/unsubscribe`. It never loads a session, takes no lease, writes nothing."""
+
+    after: str
+
+
+class ViewSubscribeResult(TypedDict):
+    """`view/subscribe` result (tdd SS4.7.1)."""
+
+    viewCursor: str
+
+
+class ViewUnsubscribeParams(TypedDict):
+    """`view/unsubscribe` params (tdd SS4.7.2): remove this connection from the session's view subscription set — the protocol's single unsubscribe operation, at the altitude that owns subscriptions (tdd SS2.5.6 points here). It does not unload the session; unloading is the idle policy (tdd SS2.8)."""
+
+    sessionId: str
+
+
+class ViewUnsubscribeResult(TypedDict):
+    """`view/unsubscribe` result (tdd SS4.7.2): the empty object. Idempotent — unsubscribing while not subscribed returns `{}`."""
+
+    pass
+
+
+class WorkflowCancelParams(TypedDict):
+    """`workflow/cancel` params (tdd SS3.19): cancel a live workflow run."""
+
+    commandId: str
+    sessionId: str
+    workflowRunId: str
+
+
+class _WorkflowChildBase(TypedDict):
+    attempt: int
+    childId: str
+    status: str
+
+
+class WorkflowChild(_WorkflowChildBase, total=False):
+    """One workflow child's folded state (tdd SS4.5.8, `WorkflowChildLifecycleFact`), keyed by `(childId, attempt)`."""
+
+    durationMs: int
+    label: str
+    phase: str
+    resultRef: str
+    terminal: TurnTerminal
+    usage: TokenUsage
+
+
+class WorkflowChildControlParams(TypedDict):
+    """`workflow/childControl` params (tdd SS3.20): skip or retry one workflow child, keyed by the `(childId, attempt)` pair the `workflow` item's `children[]` carries."""
+
+    action: WorkflowChildAction
+    attempt: int
+    childId: str
+    commandId: str
+    sessionId: str
+    workflowRunId: str
+
+
+class WorkflowControlResult(TypedDict):
+    """The shared SS3.19/SS3.20 admission-only ack: deliberately bare `{commandId, status}` — settlement arrives as the workflow item's view events, never through the ack."""
+
+    commandId: str
+    status: CommandStatus
+
+
+class __SessionMcpServerConfigStdioBase(TypedDict):
+    command: str
+    transport: Literal["stdio"]
+
+
+class _SessionMcpServerConfigStdio(__SessionMcpServerConfigStdioBase, total=False):
+    args: list[str]
+    env: dict[str, str]
+    framing: SessionMcpStdioFraming
+    mode: SessionMcpServerMode
+
+
+class __SessionMcpServerConfigStreamableHttpBase(TypedDict):
+    transport: Literal["streamableHttp"]
+    url: str
+
+
+class _SessionMcpServerConfigStreamableHttp(__SessionMcpServerConfigStreamableHttpBase, total=False):
+    headers: dict[str, str]
+    mode: SessionMcpServerMode
+
+
+# One native MCP server supplied at session construction (ADR 32760 D1).  **Closed union** (#33295 owner ruling A1, extending D-033/D-050 to `oneOf`): a validator MUST reject an undeclared `transport` arm — the server fails `session/start` decode on an unknown transport, and a future transport arrives as an explicit schema addition.
+SessionMcpServerConfig = _SessionMcpServerConfigStdio | _SessionMcpServerConfigStreamableHttp
+
+class MethodSpec(TypedDict):
+    description: str
+    params: str | None
+    result: str | None
+
+
+class NotificationSpec(TypedDict):
+    description: str
+    params: str | None
+
+
+class ErrorSpec(TypedDict):
+    code: int
+    kind: str
+    retryable: bool
+    overrideKinds: tuple[str, ...]
+
+
+METHODS: Final[dict[str, MethodSpec]] = {
+    "approval/decide": {"description": "Decides a pending approval, guarded by the current requirement id against the multi-stage race (SS5.4).", "params": "ApprovalDecideParams", "result": "ApprovalDecideResult"},
+    "approval/listPending": {"description": "Reads the full pending approval and user-input payloads for a session; a lease-free fold read (SS5.7).", "params": "ApprovalListPendingParams", "result": "ApprovalListPendingResult"},
+    "goal/clear": {"description": "Clears the session goal; never wakes and its ack never names a turn (tdd SS3.18, spec 14408; enrolled by #33066).", "params": "GoalClearParams", "result": "GoalCommandResult"},
+    "goal/edit": {"description": "Replaces the current goal's objective under the same wake gate as goal/set (tdd SS3.18, spec 14408; enrolled by #33066).", "params": "GoalEditParams", "result": "GoalCommandResult"},
+    "goal/pause": {"description": "Pauses the session goal; never wakes and its ack never names a turn (tdd SS3.18, spec 14408; enrolled by #33066).", "params": "GoalPauseParams", "result": "GoalCommandResult"},
+    "goal/resume": {"description": "Resumes a paused goal under the same wake gate as goal/set (tdd SS3.18, spec 14408; enrolled by #33066).", "params": "GoalResumeParams", "result": "GoalCommandResult"},
+    "goal/set": {"description": "Sets the session goal objective; wakes a goal-driving turn iff idle and the resulting goal is unfinished (tdd SS3.18, spec 14408; enrolled by #33066).", "params": "GoalSetParams", "result": "GoalCommandResult"},
+    "initialize": {"description": "Opens the connection: client identification, capability requests, and the experimental opt-in; the reply carries the envelope schema version and the stable-surface fingerprint (SS1.4.1).", "params": "InitializeParams", "result": "InitializeResult"},
+    "item/readOutput": {"description": "Byte-ranged read of stored full output the view truncated; works on loaded and unloaded sessions and takes no lease (SS4.7.4).", "params": "ItemReadOutputParams", "result": "ItemReadOutputResult"},
+    "model/list": {"description": "Reads the catalog of models the host will accept in `session/setModel`; a query, not a command (SS3.10).", "params": "ModelListParams", "result": "ModelListResult"},
+    "session/compact": {"description": "Compacts the session's conversation context; runs asynchronously, so the ack is admission only (SS3.7).", "params": "SessionCompactParams", "result": "SessionCompactResult"},
+    "session/fork": {"description": "Branches a session into a new id whose log copies the source through a cut point, with durable provenance (SS2.5.3).", "params": "SessionForkParams", "result": "SessionForkResult"},
+    "session/list": {"description": "Pages through stored sessions under the sessions root for history and picker UIs; read-only, never touches leases (SS2.5.4).", "params": "SessionListParams", "result": "SessionListResult"},
+    "session/read": {"description": "Reads one stored session without attaching: no lease, no load, no subscription, no resume record (SS2.5.5).", "params": "SessionReadParams", "result": "SessionReadResult"},
+    "session/rename": {"description": "Sets or changes the durable allocated session name through the runtime session_name command; withheld under the ephemeral profile (SS2.14.2, #27598).", "params": "SessionRenameParams", "result": "SessionRenameResult"},
+    "session/resume": {"description": "Loads a stored session on this host, auto-subscribes this connection, and returns the history needed to render it (SS2.5.2).", "params": "SessionResumeParams", "result": "SessionResumeResult"},
+    "session/setApprovalMode": {"description": "Selects a preconfigured approval enforcement mode mid-session; select, never create (SS5.12).", "params": "SessionSetApprovalModeParams", "result": "SessionSetApprovalModeResult"},
+    "session/setModel": {"description": "Reconfigures the session's model; the selection is durable and applies to subsequent model calls (SS3.8).", "params": "SessionSetModelParams", "result": "SessionSetModelResult"},
+    "session/setReasoningEffort": {"description": "Sets the session's standing reasoning-effort default; a turn carrying its own tier overrides it for that turn only (SS3.21, ADR 31255 D1).", "params": "SessionSetReasoningEffortParams", "result": "SessionSetReasoningEffortResult"},
+    "session/start": {"description": "Creates a brand-new session, loads it on this host, durably records the start, and auto-subscribes this connection (SS2.5.1).", "params": "SessionStartParams", "result": "SessionStartResult"},
+    "session/userShell": {"description": "Runs a user-initiated shell command in the session's workspace; capability-gated on `userShell` (SS3.9).", "params": "SessionUserShellParams", "result": "SessionUserShellResult"},
+    "skill/list": {"description": "Reads the session's user-invocable skill rows — one per typed-invocable shortcut spelling, the INV-007 predicate and shared name resolution by call-through; a query, not a command (SS3.22.1).", "params": "SkillListParams", "result": "SkillListResult"},
+    "subagent/close": {"description": "Owner-close a child; the terminal mapping folds per SS4.5.7 (SS3.16).", "params": "SubagentOwnerReasonParams", "result": "CommandAcceptedResult"},
+    "subagent/followupTask": {"description": "Queue a follow-up task for a child; admission-only ack, the task settles on the child session's view stream (SS3.16).", "params": "SubagentInputParams", "result": "CommandAcceptedResult"},
+    "subagent/interrupt": {"description": "Ask a child to yield at its next boundary; outcome folds to the parent's subagent item (SS3.16, SS4.5.7).", "params": "SubagentOwnerReasonParams", "result": "CommandAcceptedResult"},
+    "subagent/readResult": {"description": "Consume a ready child result (state-changing; the content is already the subagent item's result field) (SS3.16).", "params": "SubagentTargetParams", "result": "CommandAcceptedResult"},
+    "subagent/reopen": {"description": "Reopen a stopped/closed child as a durable later attempt (SS3.16).", "params": "SubagentTargetParams", "result": "CommandAcceptedResult"},
+    "subagent/resume": {"description": "Resume a paused/recoverable child as a durable later attempt (SS3.16).", "params": "SubagentTargetParams", "result": "CommandAcceptedResult"},
+    "subagent/sendMessage": {"description": "Queue a user note into a running child; admission-only ack, the note settles on the child session's view stream (SS3.16).", "params": "SubagentInputParams", "result": "CommandAcceptedResult"},
+    "subagent/stop": {"description": "Stop a running child; outcome folds to the parent's subagent item (SS3.16, SS4.5.7).", "params": "SubagentOwnerReasonParams", "result": "CommandAcceptedResult"},
+    "task/background": {"description": "Durably sends a running foreground tool task to the background; the `TaskBackgrounded` record lands before the ack and the `toolCall` item's `item/updated` folds the flip (tdd §3.13, #14411; enrolled under the #33065 T1 ruling).", "params": "TaskBackgroundParams", "result": "TaskCommandResult"},
+    "task/stop": {"description": "Stops one named background task; the kill settles durably and the item folds a terminal (tdd §3.14, #14411; enrolled under the #33065 T1 ruling).", "params": "TaskStopParams", "result": "TaskCommandResult"},
+    "task/stopAll": {"description": "Stops every stoppable background workload live at admission; always accepted, one item terminal folds per stopped item-visible task (tdd §3.15, #14411; enrolled under the #33065 T1 ruling).", "params": "TaskStopAllParams", "result": "TaskStopAllResult"},
+    "turn/cancel": {"description": "Cancels a turn on the normal command lane, recording no priority interrupt intent (SS3.5).", "params": "TurnCancelParams", "result": "TurnCancelResult"},
+    "turn/interrupt": {"description": "Stops the running turn on the runtime's priority lane, optionally pairing a durable retract intent (SS3.4).", "params": "TurnInterruptParams", "result": "TurnInterruptResult"},
+    "turn/start": {"description": "Submits user input to a session; the optional disposition controls queue, steer, or replace when a turn is already running (SS3.2).", "params": "TurnStartParams", "result": "TurnStartResult"},
+    "turn/steer": {"description": "Injects input into the turn the caller names, failing if that turn is no longer active (SS3.3).", "params": "TurnSteerParams", "result": "TurnSteerResult"},
+    "turn/unqueue": {"description": "Reclaims a queued submit before it launches; never upgrades into a cancel once the target is running (SS3.6).", "params": "TurnUnqueueParams", "result": "TurnUnqueueResult"},
+    "usage/read": {"description": "Reads the host's last-observed subscription usage window (5h-class and weekly percent blocks, tier, arrival stamp) without a model call; the usage member is omitted when nothing has been observed (ADR 32563 D2).", "params": None, "result": "UsageReadResult"},
+    "userInput/answer": {"description": "Answers every question of an open user-input prompt (SS5.10.2).", "params": "UserInputAnswerParams", "result": "UserInputAnswerResult"},
+    "userInput/cancel": {"description": "Declines an open user-input prompt; the tool call resolves with a cancelled result the model sees (SS5.10.2).", "params": "UserInputCancelParams", "result": "UserInputCancelResult"},
+    "userInput/clarify": {"description": "Answers an open user-input prompt with a free-form clarification the model re-decides against (SS5.10.2).", "params": "UserInputClarifyParams", "result": "UserInputClarifyResult"},
+    "view/page": {"description": "Cursor-paged reads of the session view, forward or backward; each result element is an unframed view notification, the nested {method, params} pair of SS4.2.1 (SS4.7.3).", "params": "ViewPageParams", "result": "ViewPageResult"},
+    "view/subscribe": {"description": "Attaches this connection's live view subscription for a session at an explicit cursor, replaying `(after, head]` before any live event; the re-attach path after `view/unsubscribe` (SS4.7.1).", "params": "ViewSubscribeParams", "result": "ViewSubscribeResult"},
+    "view/unsubscribe": {"description": "Removes this connection from the session's view subscription set; does not unload the session (SS4.7.2).", "params": "ViewUnsubscribeParams", "result": "ViewUnsubscribeResult"},
+    "workflow/cancel": {"description": "Cancels a live workflow run; admission-only bare ack, the cancellation's truth arrives as the workflow item's view events (tdd SS3.19, spec 14410; enrolled by the #33065 sweep).", "params": "WorkflowCancelParams", "result": "WorkflowControlResult"},
+    "workflow/childControl": {"description": "Skips or retries one workflow child keyed by the item's (childId, attempt) pair; admission-only bare ack (tdd SS3.20, spec 14410; enrolled by the #33065 sweep).", "params": "WorkflowChildControlParams", "result": "WorkflowControlResult"},
+}
+
+NOTIFICATIONS: Final[dict[str, NotificationSpec]] = {
+    "approval/requested": {"description": "An approval opened: the fold of its durable Requested record (SS5.5.1).", "params": "ApprovalRequestParams"},
+    "approval/resolved": {"description": "The first durable approval terminal landed; protected delivery (SS5.5).", "params": "ApprovalResolvedParams"},
+    "approval/updated": {"description": "A non-terminal approval record changed the pending view (SS5.5.1).", "params": "ApprovalUpdatedParams"},
+    "initialized": {"description": "Client-to-server notification closing the handshake; no params (SS1.4.2).", "params": None},
+    "item/completed": {"description": "An item reached its terminal state: the authoritative final object (SS4.3).", "params": "ItemCompletedParams"},
+    "item/delta": {"description": "Streaming append to an open item's field path (ephemeral-sourced, no sourceRange; opt-out-able) (SS4.3.1).", "params": "ItemDeltaParams"},
+    "item/started": {"description": "An item opened on the transcript (SS4.3).", "params": "ItemStartedParams"},
+    "item/updated": {"description": "An open item changed non-terminally: full re-emission at a higher revision (SS4.4.2).", "params": "ItemUpdatedParams"},
+    "session/approvalModeChanged": {"description": "The approval enforcement mode changed: the fold of the durable reconfigure audit fact (SS5.12).", "params": "SessionApprovalModeChangedParams"},
+    "session/branchChanged": {"description": "A durable workspace-branch observation landed; null branch is a detached-HEAD fact (SS4.6.4).", "params": "SessionBranchChangedParams"},
+    "session/contextUsage": {"description": "A provider-reported context-occupancy fact folded to a changed (windowTokens, usedTokens, pressure) triple (SS4.6.6).", "params": "SessionContextUsageParams"},
+    "session/goalChanged": {"description": "The session's goal block changed value; replace wholesale, an explicit null clears (SS4.6.2).", "params": "SessionGoalChangedParams"},
+    "session/modelChanged": {"description": "A durable model selection took effect (SS4.6.1).", "params": "SessionModelChangedParams"},
+    "session/modelRouteUnserved": {"description": "An accepted login credential update installed a provider that cannot serve the session's standing model route; the standing selection is unchanged and a routable session/setModel repairs it (#25603, spec 5469 Amendment 16).", "params": "SessionModelRouteUnservedParams"},
+    "session/nameChanged": {"description": "A durable session-name record landed (rename or first naming): the fold of the session_name record (SS4.6.7, #27598).", "params": "SessionNameChangedParams"},
+    "session/reasoningEffortChanged": {"description": "A durable session-default reasoning-effort change took effect (SS4.6.9, ADR 31255 D1).", "params": "SessionReasoningEffortChangedParams"},
+    "session/statusChanged": {"description": "A loaded session's (status, attention) flipped; command-plane broadcast, cursor-stamped, not subscription-gated (SS4.6.10, ADR 31983 D2).", "params": "SessionStatusChangedParams"},
+    "session/todoListChanged": {"description": "The todo list was replaced wholesale; empty items is a cleared list (SS4.6.3).", "params": "SessionTodoListChangedParams"},
+    "session/tokenUsage": {"description": "A model call completed with usage: raw counters plus counted-once derivations plus session cumulative (SS4.6.5).", "params": "SessionTokenUsageParams"},
+    "session/viewHealthChanged": {"description": "A loaded session's live view stream became unavailable, and why: a command-plane push delivered independent of the view subscription set when the materialized projection fails closed (ADR 32557; #32557).", "params": "SessionViewHealthChangedParams"},
+    "skill/changed": {"description": "The session's user-invocable skill set changed; clients re-issue skill/list. A live host-state projection, not a view event (SS3.22.2).", "params": "SkillChangedParams"},
+    "turn/completed": {"description": "Turn terminal: completed | failed | cancelled, with usage and the settled error object (SS4.5.1).", "params": "TurnCompletedParams"},
+    "turn/retracted": {"description": "An interrupt-paired retract was durably accepted (SS4.5.1).", "params": "TurnRetractedParams"},
+    "turn/retryScheduled": {"description": "A failing model attempt's retry is scheduled and waiting out its backoff; observable mid-turn, non-terminal (SS4.5.1, D-026).", "params": "TurnRetryScheduledParams"},
+    "turn/started": {"description": "A foreground turn began running (SS4.5.1).", "params": "TurnStartedParams"},
+    "turn/unqueued": {"description": "A queued submit's reclaim durably won: its pre-minted turn never runs, and no turn/started or turn/completed will follow for that turnId (SS3.6, SS4.5.1).", "params": "TurnUnqueuedParams"},
+    "usage/changed": {"description": "The host's last-observed subscription usage DATA changed (window, weekly, or tier — not a stamp-only refresh), with the same payload shape as usage/read's usage member; the absent-to-present first observation emits (ADR 32563 D3).", "params": "SubscriptionUsage"},
+    "userInput/requested": {"description": "A user-input prompt opened: the fold of its durable Requested record (SS5.10.1).", "params": "UserInputRequestParams"},
+    "userInput/settled": {"description": "The first durable user-input settlement landed; protected delivery (SS5.10.3).", "params": "UserInputSettledParams"},
+    "view/gap": {"description": "Push delivery dropped events: `(after, next)` brackets the undelivered range and delivery continues from `next` (SS4.8; spec 208 FM-001).", "params": "ViewGapParams"},
+}
+
+ERRORS: Final[tuple[ErrorSpec, ...]] = (
+    {"code": -32700, "kind": "parseError", "retryable": False, "overrideKinds": ()},
+    {"code": -32600, "kind": "invalidRequest", "retryable": False, "overrideKinds": ("notInitialized", "alreadyInitialized",)},
+    {"code": -32601, "kind": "methodNotFound", "retryable": False, "overrideKinds": ("experimentalRequired",)},
+    {"code": -32602, "kind": "invalidParams", "retryable": False, "overrideKinds": ("experimentalRequired",)},
+    {"code": -32603, "kind": "internal", "retryable": False, "overrideKinds": ("pageEventTooLarge", "outputResultTooLarge",)},
+    {"code": -32001, "kind": "overloaded", "retryable": True, "overrideKinds": ()},
+    {"code": -32002, "kind": "inputTooLarge", "retryable": False, "overrideKinds": ()},
+    {"code": -32010, "kind": "capabilityRequired", "retryable": False, "overrideKinds": ()},
+    {"code": -32011, "kind": "notFound", "retryable": False, "overrideKinds": ()},
+    {"code": -32013, "kind": "interrupted", "retryable": False, "overrideKinds": ()},
+    {"code": -32014, "kind": "cancelled", "retryable": False, "overrideKinds": ()},
+    {"code": -32020, "kind": "sessionNotFound", "retryable": False, "overrideKinds": ()},
+    {"code": -32021, "kind": "sessionInUse", "retryable": False, "overrideKinds": ()},
+    {"code": -32022, "kind": "sessionAmbiguous", "retryable": False, "overrideKinds": ()},
+    {"code": -32023, "kind": "forkBoundaryInvalid", "retryable": False, "overrideKinds": ()},
+    {"code": -32024, "kind": "sessionNotLoaded", "retryable": False, "overrideKinds": ()},
+    {"code": -32025, "kind": "sessionStreamMismatch", "retryable": False, "overrideKinds": ()},
+    {"code": -32030, "kind": "commandRejected", "retryable": False, "overrideKinds": ()},
+    {"code": -32031, "kind": "backpressured", "retryable": True, "overrideKinds": ()},
+    {"code": -32032, "kind": "skillNotFound", "retryable": False, "overrideKinds": ()},
+    {"code": -32040, "kind": "viewTruncated", "retryable": False, "overrideKinds": ()},
+    {"code": -32041, "kind": "outputUnavailable", "retryable": False, "overrideKinds": ()},
+    {"code": -32042, "kind": "boundaryPruned", "retryable": False, "overrideKinds": ("boundaryUnusable", "noBoundary",)},
+    {"code": -32050, "kind": "approvalNotFound", "retryable": False, "overrideKinds": ()},
+    {"code": -32051, "kind": "approvalAlreadyResolved", "retryable": False, "overrideKinds": ()},
+    {"code": -32052, "kind": "approvalChoiceInvalid", "retryable": False, "overrideKinds": ()},
+    {"code": -32053, "kind": "approvalRequirementStale", "retryable": False, "overrideKinds": ()},
+    {"code": -32054, "kind": "approvalReviewerUnavailable", "retryable": False, "overrideKinds": ()},
+    {"code": -32055, "kind": "userInputNotFound", "retryable": False, "overrideKinds": ()},
+    {"code": -32056, "kind": "userInputAlreadySettled", "retryable": False, "overrideKinds": ()},
+    {"code": -32057, "kind": "userInputAnswerInvalid", "retryable": False, "overrideKinds": ()},
+)
+
+GRANTABLE_CAPABILITIES: Final[tuple[str, ...]] = ("userShell", "sessionMcp",)