// Generated MSP wire declarations, bundled into the published package.
//
// Copied verbatim from `schema/msp/msp.d.ts` at pack time by
// `scripts/bundle-msp-types.mjs`. Do not edit, and do not commit: this file
// exists only in build output, so the repo keeps one copy of the generated
// artifact (spec 14990 INV-008) while the tarball stays self-contained.

// Muse Session Protocol (MSP) v1 TypeScript declarations.
// STABLE surface only; experimental twin: experimental/msp.d.ts.
// Generated by tbh-protocol (spec 206) from the same schema model as
// the JSON Schema bundle (INV-017). Do not edit by hand.

/** The policy rule a decision created, in display form; the full rule is not included. */
export interface ApprovalAmendment {
  /** How long the rule lasts: `session` or `localPersistent`. */
  durability: ApprovalAmendmentDurability;
  /** A human-readable preview of the rule, for display. */
  rulePreview: string;
}

/** How long a rule created by an approval decision lasts. The set is open, so newer hosts may send other values. */
export type ApprovalAmendmentDurability = "session" | "localPersistent" | (string & {});

/** The change an `approval/updated` event reports. `kind` says what happened, and only the fields for that kind are present. */
export interface ApprovalChange {
  /** The `choiceId` that satisfied the stage. Present only when `kind` is `stageResolved`. */
  choiceId?: string;
  /** The decision the chosen option applied to the stage. Present only when `kind` is `stageResolved`. */
  decision?: ApprovalDecision;
  /** A recovery detail: whether the action could run without a new decision. Present only when `kind` is `restartRecovered`. */
  executable?: boolean;
  /** What happened: for example `stageResolved` (a shell stage was satisfied), `policyPersistence` (saving a rule succeeded or failed), `reviewStarted` or `reviewCompleted` (the automated LLM judge started or finished reviewing), `restartRecovered` (a host restart recovered this approval: either the host first resolves it `abort` and a re-ask comes as a new approval with a new `approvalId`, or it stays pending under the same `approvalId` with refreshed choices) or `alreadyTerminal` (recovery found it already decided). The set is open, so newer hosts may add kinds. */
  kind: string;
  /** Why saving the policy rule failed, as human-readable text. Present only when `kind` is `policyPersistence` and `status` is `failed`. */
  reason?: string;
  /** A recovery detail: whether the command was re-parsed during recovery. Present only when `kind` is `restartRecovered`. */
  reparsed?: boolean;
  /** The stage requirement that was satisfied. Present only when `kind` is `stageResolved`. */
  requirementId?: ApprovalRequirementRef;
  /** Whether saving the policy rule succeeded or failed; present only when `kind` is `policyPersistence`. A failure does not undo the decision; only the saved rule is missing. */
  status?: ApprovalPersistenceStatus;
}

/** One option the server offers for deciding an approval. Clients pick one and send its `choiceId` in `approval/decide`; they never build their own. */
export interface ApprovalChoice {
  /** `true` when this choice takes optional `feedback` text in `approval/decide`, which reaches the model as guidance. Omitted when `false`. */
  acceptsFeedback?: boolean;
  /** The id to send as `choiceId` in `approval/decide`. The set of ids is open, so show `label` and do not base behavior on specific ids. */
  choiceId: string;
  /** The decision this choice applies, so a client can act on approve or reject without knowing choice ids. */
  decision: ApprovalDecision;
  /** The human-readable label to show for this choice. */
  label: string;
  /** A human-readable preview of what this choice grants, such as the policy rule it would create; show it exactly as given. */
  rulePreview?: string;
  /** The grant duration this choice declares: `once` (this request only), `session` (the rest of the session) or `localPersistent` (saved in the local policy store). */
  scope: ApprovalChoiceScope;
}

/** How long a grant made by a choice lasts. The set is open, so newer hosts may send other values. */
export type ApprovalChoiceScope = "once" | "session" | "localPersistent" | (string & {});

/** One Computer Use card's facts. Empty collections and absent rows are omitted, never `null`. */
export interface ApprovalCuaCardFacts {
  /** For a browser, the host of the window's current page. */
  page?: ApprovalCuaPage;
  /** Only the consequential steps, in call order. */
  steps?: ApprovalCuaStep[];
  /** The target window's title: the app's own text, which a page can set; a client shows it quoted and as plain text, never as markup or a choice, and may cap it. */
  windowTitle?: string;
}

/** The page's full host, no path or query. */
export interface ApprovalCuaPage {
  /** The host in Unicode. */
  host: string;
  /** The host's `xn--` form; equal to `host` when they don't differ. */
  hostAscii: string;
}

/** A point in the model's 0–1000 coordinates. */
export interface ApprovalCuaPoint {
  x: number;
  y: number;
}

/** One consequential step. A client renders "Step N: <action> <roleWord> "<label>" — <effect>"; a key step names its `chord`, and only a step with a `point` (and no label or chord) reads "at x,y". */
export interface ApprovalCuaStep {
  /** The host's verb phrase, such as `click` or `type into`. */
  action: string;
  /** The chord, for a key step. */
  chord?: string;
  /** The host's trusted sentence for what the step may do. */
  effect: string;
  /** An open tag for styling and tests only (`verb:<class>`, `unresolved`, `unlabeled`); a client that doesn't know a value renders the step from `effect` and its label as usual. */
  kind: string;
  /** The control's label: the app's own text, shown quoted and as plain text; a client may cap it. */
  label?: string;
  /** The step's own 0–1000 model coordinates, only for a point step. */
  point?: ApprovalCuaPoint;
  /** `button`, `link`, `menu item` or `key`; absent for a point step. */
  roleWord?: string;
  /** 1-based, as the batch numbers its steps. */
  step: number;
}

/** `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. */
export interface ApprovalDecideParams {
  /** The approval being decided. */
  approvalId: string;
  /** One of the current `availableChoices`; else -32052. */
  choiceId: string;
  /** The SS3.1.1 idempotency handle (UUIDv7). */
  commandId: string;
  /** Free-text guidance delivered to the model with the denial. Only valid on choices with `acceptsFeedback`. Never persisted in the durable audit record (live steer only), so it is absent from `approval/resolved` (tdd SS5.4). Omitted and explicit `null` both mean "no feedback" (#23468). */
  feedback?: string | null;
  /** Must equal the approval's `currentRequirementId`. The multi-stage race guard: a decision aimed at stage 1 can never accidentally satisfy stage 2, and a stale value is -32053 (tdd SS5.4). */
  requirementId: ApprovalRequirementRef;
  /** The target session. */
  sessionId: string;
}

/** `approval/decide` result (tdd SS5.4). Admission-ack rules still apply: the authoritative outcome is `approval/resolved` / `approval/updated` on the view stream. */
export interface ApprovalDecideResult {
  /** The approval this decision was applied to. */
  approvalId: string;
  /** Echoes the client's id. */
  commandId: string;
  /** Admission status. */
  status: CommandStatus;
  /** `false` when the choice satisfied a stage but further requirements remain (the approval stays pending and an updated `approval/request` follows); `true` when this decision produced the terminal `DecisionApplied` (tdd SS5.4). */
  terminal: boolean;
}

/** The kind of decision a choice applies or an approval received. The set is open, so newer hosts may send values this version does not list. */
export type ApprovalDecision = "approved" | "approvedForSession" | "approvedPolicyAmendment" | "denied" | "deniedPolicyAmendment" | "timedOut" | "abort" | (string & {});

/** `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. */
export interface ApprovalListPendingParams {
  /** The session to read. */
  sessionId: string;
}

/** `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. */
export interface ApprovalListPendingResult {
  /** Exactly the `approval/request` params, one per pending approval. */
  approvals: ApprovalRequestParams[];
  /** Exactly the `userInput/request` params, one per pending prompt. */
  userInputs: UserInputRequestParams[];
}

/** 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. */
export type ApprovalMode = "allowAll" | "promptUnmatched" | "onRequest" | "denyUnmatched";

/** Whether a mode change did anything (tdd SS5.12), mirroring `ApprovalReconfigureApplyOutcome`. Apply failures are `commandRejected`. */
export type ApprovalModeApplyOutcome = "completed" | "noop" | (string & {});

/** How an approval mode took effect (tdd SS5.12, the effective-mode projection's `source` vocabulary). Open. */
export type ApprovalModeSource = "startup" | "replay" | "approvalReconfigure" | (string & {});

/** What triggered a tool action, shown so the user can judge it. It is display-only and untrusted, and policy rules never match on it. */
export interface ApprovalOrigin {
  /** The shell command whose process asked for the action. Present when `kind` is `shellCommand`. */
  command?: string;
  /** Which kind of origin this is: `shellCommand` or `url`. */
  kind: string;
  /** The full URL a fetch tool is requesting. Present when `kind` is `url`. */
  url?: string;
}

/** The result of saving a granted rule to the local policy store. The set is open, so newer hosts may send other values. */
export type ApprovalPersistenceStatus = "succeeded" | "failed" | (string & {});

/** Whether an approval's final decision lets the action run. The set is open, so newer hosts may send other values. */
export type ApprovalPolicyResult = "allow" | "deny" | (string & {});

/** Full params shared by `approval/request` and `approval/requested`. */
export interface ApprovalRequestParams {
  /** The approval's stable id. Match `approval/decide`, `approval/updated` and `approval/resolved` by it, never by the JSON-RPC request id, which belongs to one connection. */
  approvalId: string;
  /** The choices the server offers for the current requirement. Send the chosen one's `choiceId` in `approval/decide`; clients never build their own. */
  availableChoices: ApprovalChoice[];
  /** A Computer Use card's facts: the page, the window and each step that may have an effect, in the host's words; absent on every other approval. */
  cuaCardFacts?: ApprovalCuaCardFacts;
  /** The requirement the next decision must target; send it unchanged as `requirementId` in `approval/decide`. For `shell` it names the first stage still needing a decision; for other kinds its `sourceIndex` is 0. */
  currentRequirementId: ApprovalRequirementRef;
  /** The `toolCall` view item waiting on this approval. */
  itemId: string;
  /** `true` when the automated LLM judge saw this request first and handed it to a person without deciding. A display hint only. The host sends it as `false` when it re-issues the request after a restart or on `session/resume`; a re-send for a later stage keeps it. */
  judgeEscalated: boolean;
  /** `true` when this approval guards a write to a protected file. Only allow-once and reject choices are offered, and a decision is accepted only while at least one client is subscribed to the session. */
  protectedWrite: boolean;
  /** The tool call's arguments as a string, usually JSON. With `toolName`, it lets a client show a subject whose `kind` it does not recognize. */
  rawArgs: string;
  /** The owning session. For a subagent's approval shown on the parent, this is the parent session. */
  sessionId: string;
  /** The stored records this event was folded from: an opaque token clients must not interpret. */
  sourceRange: SourceRange;
  /** Present only for a child (native subagent) approval projected onto the parent session's plane (ADR 36182); parent-own approvals omit it. */
  subagentOrigin?: ApprovalSubagentOrigin;
  /** What the approval is for. Show a `kind` you do not recognize generically, and never auto-approve it. */
  subject: ApprovalSubject;
  /** The id of the task running the tool call. */
  taskId: string;
  /** The model provider's id for this tool call. */
  toolCallId: string;
  /** The name of the tool being called. */
  toolName: string;
  /** The turn whose tool call is waiting on this approval. */
  turnId: string;
  /** The cursor of the `approval/requested` event that opened this request. A re-send for a later stage keeps this cursor, so `view/page` at it returns the opening stage, which may be older than this payload. */
  viewCursor: string;
}

/** Identifies one requirement of an approval: for a `shell` approval, one stage. A client sends it back as `requirementId` in `approval/decide`, and a stale-requirement error names the current one. */
export interface ApprovalRequirementRef {
  /** The approval this requirement belongs to. */
  approvalId: string;
  /** The requirement's index within the approval, counting from 0; an approval with a single requirement uses 0. */
  sourceIndex: number;
}

/** Winning terminal returned to a losing `approval/decide` command. */
export interface ApprovalResolutionSummary {
  /** The winning decision, as an `approval/resolved` decision value such as `approved` or `abort`. */
  decision: string;
  /** Who made the winning decision, such as `user`, `policy` or `llmJudge`. */
  resolvedBy: string;
  /** The view cursor of the winning `approval/resolved` event. */
  viewCursor: string;
}

/** Who or what made an approval's final decision. The set is open, so newer hosts may send other values. */
export type ApprovalResolvedBy = "user" | "policy" | "llmJudge" | (string & {});

/** `approval/resolved` params: the first durable terminal decision. */
export interface ApprovalResolvedParams {
  /** The policy rule the decision created. Present only when the decision created one. */
  amendment?: ApprovalAmendment;
  /** The approval that was decided. */
  approvalId: string;
  /** The decision time as RFC3339, projected from the durable `DecisionApplied` record's own stamp (ADR 45450 D3): optional on the wire so decoders tolerate its absence, always populated by current hosts. */
  decidedAt?: string;
  /** The `commandId` of the `approval/decide` command that won. Absent when no such command made the decision, for example a policy or LLM judge decision. */
  decidedByCommandId?: string;
  /** The final decision. */
  decision: ApprovalDecision;
  /** The `toolCall` view item this approval was holding. */
  itemId: string;
  /** Whether the final decision lets the action run (`allow`) or blocks it (`deny`). */
  policyResult: ApprovalPolicyResult;
  /** Who or what made the decision: `user`, `policy` or `llmJudge`. */
  resolvedBy: ApprovalResolvedBy;
  /** The owning session. */
  sessionId: string;
  /** The stored records this event was folded from: an opaque token clients must not interpret. */
  sourceRange: SourceRange;
  /** For a `shell` approval, how each stage was resolved when the decision became final. Empty for other subject kinds, and it can be empty for `shell` too. */
  stageEvidence: ApprovalStageEvidence[];
  /** Present only for a child (native subagent) approval projected onto the parent session's plane (ADR 36182); parent-own approvals omit it. */
  subagentOrigin?: ApprovalSubagentOrigin;
  /** The turn whose tool call this approval was holding. */
  turnId: string;
  /** This event's view cursor: opaque, and strictly increasing within the session. */
  viewCursor: string;
}

/** One stage of a `shell` approval: a single command from the pipeline or command list, approved separately from the others. */
export interface ApprovalStage {
  /** The stage's command words as parsed. When `argvComplete` is `false`, this can be a single unparsed piece of the command. */
  argv: string[];
  /** `true` when `argv` is the stage's complete command, known before it runs; `false` when part of it cannot be resolved ahead of time (for example a command substitution). A stage with `false` never has a `suggestedPrefix`. */
  argvComplete: boolean;
  /** This stage's 1-based position in the command; it equals `requirementId.sourceIndex + 1`. */
  position: number;
  /** This stage's requirement id. When it equals the approval's `currentRequirementId`, send it as `requirementId` in `approval/decide`. */
  requirementId: ApprovalRequirementRef;
  /** Whether this stage still needs a decision or, if not, how it was satisfied. */
  resolution: ApprovalStageResolution;
  /** A command prefix the host suggests always allowing in this workspace, present only when one can be taken from a fully parsed stage. `availableChoices` shows whether that grant is offered. */
  suggestedPrefix?: ApprovalSuggestedPrefix;
  /** The total number of stages in the command. */
  totalStages: number;
}

/** How one stage of a `shell` approval was resolved when the decision became final. */
export interface ApprovalStageEvidence {
  /** The stage's command words as parsed. */
  argv: string[];
  /** The stage's 1-based position in the command. */
  position: number;
  /** The stage's requirement id. */
  requirementId: ApprovalRequirementRef;
  /** How the stage was resolved at the final decision. */
  resolution: ApprovalStageResolution;
  /** The total number of stages in the command. */
  totalStages: number;
}

/** Whether a shell stage still needs a decision, or how it was satisfied. Satisfied stages are included so a client can show progress. */
export interface ApprovalStageResolution {
  /** The command prefix saved as an always-allow rule when this stage was approved. Present only when `kind` is `policyAmendment`. */
  argvPrefix?: string[];
  /** Free-form text naming the rule or mode that allowed the stage, for display or troubleshooting. Present only when `kind` is `policyAllow`. */
  diagnostic?: string;
  /** One of `unresolved`, `knownSafe`, `policyAllow`, `allowOnce` or `policyAmendment`. The set is open, so newer hosts may add values. */
  kind: string;
}

/** Child (native subagent) provenance for an approval projected onto the PARENT session's approval plane (#36182 / ADR 36182): identifies the originating child run/agent so a client can attribute the prompt. Omitted (`skip_serializing_if`) on the parent's own approvals, so pre-existing parent frames stay byte-identical. */
export interface ApprovalSubagentOrigin {
  /** The child run that parked on this approval. */
  childRunId: string;
  /** The child session stream id whose records carry this approval. */
  childSessionId: string;
  /** The originating child's subagent id, from the parent session's durable subagent control records. */
  subagentId: string;
}

/** Open approval subject union. Unknown kinds are rendered generically and never auto-approved by clients (tdd SS5.2). */
export interface ApprovalSubject {
  /** The access asked for: `read` or `write` for `fileAccess`, `control` for `process`. Absent for other kinds. */
  access?: string;
  /** The full raw shell command. Present when `kind` is `shell`. */
  command?: string;
  /** The network host the tool wants to reach. Present when `kind` is `network`. */
  host?: string;
  /** Open discriminator: `shell | fileAccess | network | unixSocket | process | tool`. */
  kind: string;
  /** What triggered the action (a shell command or a URL), for display only and untrusted. It is not sent on `shell` subjects, and policy rules never match on it. */
  origin?: ApprovalOrigin;
  /** For `fileAccess`, the path the tool asked to access, normalized by the host (workspace-relative inside the workspace); for `unixSocket`, the exact resolved socket path, sent unescaped, so escape it before display. */
  path?: string;
  /** The network port, present only on `network` subjects that name one. A session grant made from a subject without a port covers every port. */
  port?: number;
  /** The network protocol, for example `https`. Present only on `network` subjects that name one. */
  protocol?: string;
  /** The shell command split into stages that are approved separately (the commands of a pipeline or command list), in order. Present on `shell` subjects; it may be empty. */
  stages?: ApprovalStage[];
  /** Display text naming the process the tool wants to control. Present when `kind` is `process`. */
  target?: string;
  /** The tool asking for the action. Present for every kind except `shell`. */
  toolName?: string;
  /** The canonical workspace root the shell command runs in, present on `shell` subjects when the host knows it. Saved command-prefix rules apply only within this root. */
  workspaceRoot?: string;
}

/** A suggested always-allow rule for a shell stage: commands starting with `argvPrefix` would run in this workspace without asking. */
export interface ApprovalSuggestedPrefix {
  /** The leading command words the rule would allow, for example `["cargo", "test"]`. */
  argvPrefix: string[];
  /** A human-readable label for the suggestion, ready to show as is. */
  label: string;
}

/** `approval/updated` params: the refreshed pending view plus one change. */
export interface ApprovalUpdatedParams {
  /** The approval that changed. */
  approvalId: string;
  /** The refreshed choices for the current requirement. */
  availableChoices: ApprovalChoice[];
  /** What changed; `change.kind` names the kind of change. */
  change: ApprovalChange;
  /** The requirement the next decision must target after this change; send it as `requirementId` in `approval/decide`. */
  currentRequirementId: ApprovalRequirementRef;
  /** The owning session. */
  sessionId: string;
  /** The stored records this event was folded from: an opaque token clients must not interpret. */
  sourceRange: SourceRange;
  /** Present only for a child (native subagent) approval projected onto the parent session's plane (ADR 36182); parent-own approvals omit it. */
  subagentOrigin?: ApprovalSubagentOrigin;
  /** The approval's subject, with `stages` refreshed for this change. */
  subject: ApprovalSubject;
  /** This event's view cursor: opaque, and strictly increasing within the session. */
  viewCursor: string;
}

/** 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. */
export type AttentionFlag = "approvalPending" | "inputPending" | (string & {});

/** Who durably backgrounded a task (tdd SS4.5.5, `TaskBackgroundedInitiator`). Open — runtime vocabulary. */
export type BackgroundInitiator = "user" | "timeout" | (string & {});

/** `backgroundTerminalCompletion`: the five facts the Finished cell renders (ADR 50041 D3/D4). The fold reads them from the inbox terminal record and the backgrounded call it names; every member is required (empty output serializes as `""`, never absent). */
export interface BackgroundTerminalCompletion {
  /** The title text gate-off shows for the backgrounded command. */
  command: string;
  /** The completion text; empty when the terminal carries none. */
  output: string;
  /** True when `output` is a prefix of the terminal text. */
  outputTruncated: boolean;
  /** One of `completed`, `failed`, `cancelled`, `timedOut`, `rejected` (the ItemStatus wire vocabulary, tdd SS4.4.1). */
  terminalStatus: string;
  /** The backgrounded call's call id: the live/history correlation key behind the skip-when-minted rule (ADR 50041 D6). */
  toolCallId: string;
}

/** The cold recall seed on `session/resume` and `session/read` results (ADR 50074 D2): at most one, the latest blocked Main prompt — exactly the host's mirror of `prompt_recovery::replay::ReplayInput`'s choice. */
export interface BlockedPrompt {
  /** The exact submitted prompt, verbatim — no truncation, no normalization; recall fidelity requires exactness. */
  text: string;
}

/** The latest branch observation in the snapshot (tdd SS4.6.4, SS4.9.1). */
export interface BranchState {
  /** The observed branch; `null` on a detached-HEAD observation. */
  branch: string | null;
  /** The detected version-control system; absent when none was detected. */
  vcs?: Vcs;
  /** The observed workspace root. */
  workspaceRoot: string;
}

/** A grantable capability name. Open: the experimental-only `rawLog` entry joins the stable domain as an additive open-enum extension when it graduates — closed would make that a retype. */
export type CapabilityName = "userShell" | "sessionMcp" | "sessionListStream" | "feedback" | "computerUseSetup" | "computerUseHostSetup" | "sessionRename" | (string & {});

/** A served checkpoint-prune boundary (spec 13929 amendment FR-50042-1; ADR 50042 D3): `through_item_id` names the last first-opened item that opened strictly before the boundary checkpoint event. */
export interface CheckpointBoundary {
  /** The last pre-boundary item's id, in served (first-opened) order. */
  throughItemId: string;
}

/** The client's requested capability posture (SS1.4.1). Every member defaults; an absent `capabilities` object means all defaults. */
export interface ClientCapabilities {
  /** Opt into experimental methods, fields, and variants (default `false`). */
  experimentalApi?: boolean;
  /** Exact notification method names the client declines; no wildcards; unknown names accepted and ignored; the protected set (SS1.7) cannot be opted out. */
  optOutNotificationMethods?: string[];
  /** Names from the capability registry. Unknown entries are not an error and simply do not appear in `grantedCapabilities` — which is why this is a list of free strings rather than of registry names. */
  requestedCapabilities?: string[];
  /** Whether this client can render a `userInput/request` dialog and answer it (SS5.10). **Absent means capable** (D-047): a client that predates the member keeps today's contract, so no existing client changes its handshake. `false` makes the host withhold `userInput/request` toward this client — the D-027 additive-optional-field + withheld-method convention.  Deliberately NOT a `requestedCapabilities` name: that registry records operations a host GRANTS (SS1.4.4), and whether a client can draw a dialog is a fact about the client, never a privilege the host hands out. */
  userInputDialogs?: boolean;
}

/** Client identification inside `initialize` params (SS1.4.1). Diagnostics and telemetry attribution only; never an authority claim (SS1.10). */
export interface ClientInfo {
  /** Machine identifier, `[a-z0-9_]+` (SS1.4.1). */
  name: string;
  /** Human display name. */
  title?: string;
  /** Client version string. */
  version: string;
}

/** The language a Code Mode cell ran in (ADR 42727 D2). Open: values are lowercase VS Code language identifiers, and only `javascript` (the V8 engine) is minted today. */
export type CodeModeLanguage = "javascript" | (string & {});

/** One public-output span inside the item's `visibleOutput` (ADR 42727 D3).  Offsets index the UTF-8 encoding of the **decoded** `visibleOutput` string, never the JSON-escaped wire text; both ends fall on code-point boundaries; named and measured like `item/readOutput`'s byte range. */
export interface CodeModeOutputSpan {
  /** Length of the span, in bytes. Range 0–9007199254740991 inclusive. */
  lengthBytes: number;
  /** Start of the span, in bytes. Range 0–9007199254740991 inclusive. */
  offsetBytes: number;
  /** What the bytes are. */
  stream: CodeModeOutputStream;
}

/** What a Code Mode output span's bytes are (ADR 42727 D3). Open: each engine mints its own values. */
export type CodeModeOutputStream = "transcript" | (string & {});

/** Code Mode's `details` payload (ADR 42727 D2/D3).  Every member is absent when it does not apply, never `null`; an empty `outputSpans` list is never served. */
export interface CodeModeReceipt {
  /** `wait` only, when the producer resolved it: the `itemId` of the `execute` item that started the cell. */
  cellItemId?: string;
  /** `execute`, and `wait` when the producer resolved the originating execute: the language the cell ran in. */
  language?: CodeModeLanguage;
  /** The public cell-output spans, ascending and non-overlapping; absent when there is no cell body or a hook rewrote the served body. */
  outputSpans?: CodeModeOutputSpan[];
  /** `execute` only: the top-level key of the item's `args` object whose value is the cell source. A pointer, never source bytes. */
  sourceArg?: string;
}

/** The uniform SS3.1.2 command acknowledgement: admission only, never an outcome. `session/compact` alone may answer `"noop"`; every other command answers `"accepted"`. */
export interface CommandAcceptedResult {
  /** Echo of the client-minted UUIDv7 `commandId` (SS3.1.1). */
  commandId: string;
  /** `"accepted"` for every admitted command (SS3.1.2; closed vocabulary). */
  status: CommandAckStatus;
}

/** The ack-status vocabulary: `"accepted"` for every admitted command; `session/compact` alone may answer `"noop"`. Closed: the protocol defines exactly these two values, so SDK clients get a discriminated type and validation catches a wrong status — and a client that received a third value would have been told nothing it can act on, unlike [`TurnStartDisposition`], where "acked, not otherwise classified" is a usable reading. */
export type CommandAckStatus = "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). */
export type CommandStatus = "accepted" | (string & {});

/** `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. */
export type CompactStatus = "accepted" | "noop" | (string & {});

/** Compaction outcome (tdd SS4.5.10, the SS3.7 vocabulary). Open. */
export type CompactionOutcome = "compacted" | "noop" | "failed" | "cancelled" | (string & {});

/** What initiated a compaction (tdd SS4.5.10). Open. */
export type CompactionTrigger = "manual" | "auto" | (string & {});

/** One row of the Settings apps list. */
export interface ComputerUseApp {
  /** The app's bundle ID: the stored key. */
  bundleId: string;
  /** The choice as it applies: a block wins over a grant. */
  choice: ComputerUseAppChoice;
  /** When Computer Use last showed an approval card for the app, RFC3339 UTC; absent when it never has. */
  lastAskedAt?: string;
  /** Settings can't change this row; its choice is `blocked`. Omitted means false. */
  locked?: boolean;
  /** Why the row is locked, when it is. */
  lockedBy?: ComputerUseAppLock;
  /** The name the approval card shows for it, else the name stored with its grant or its last card; absent when there is none. */
  name?: string;
}

/** A per-app choice. **Open**, like `ComputerUseChoice`. */
export type ComputerUseAppChoice = "ask" | "alwaysAllow" | "blocked" | (string & {});

/** Why Settings can't change a row. **Open**. */
export type ComputerUseAppLock = "builtIn" | "file" | (string & {});

/** One per-app choice to set in `computerUseSettings/update`. */
export interface ComputerUseAppPatch {
  /** The app's bundle ID. */
  bundleId: string;
  /** `ask` removes the app's grant and the user's block; `alwaysAllow` saves a grant and removes the user's block; `blocked` adds the user's block and removes the grant. */
  choice: ComputerUseAppChoice;
}

/** One row of the Settings blocked-apps list. */
export interface ComputerUseBlockedApp {
  /** The app's bundle ID, or the family prefix when `prefix` is true. */
  bundleId: string;
  /** A built-in block, which Settings cannot remove (ADR 630 D18.8). */
  locked: boolean;
  /** A built-in family row: it blocks every bundle ID that starts with `bundleId`. Omitted means false; only locked rows are prefixes. */
  prefix?: boolean;
}

/** A capability dropdown's value (ADR 630 D18.4). **Open**: the read result carries it, so an older client tolerates a value it does not know. */
export type ComputerUseChoice = "ask" | "alwaysAllow" | (string & {});

/** One installed or running app, for Settings' app picker. */
export interface ComputerUseInstalledApp {
  /** The app's bundle ID. */
  bundleId: string;
  /** The name the approval card shows for it. */
  name: string;
}

/** One macOS permission as setup last saw it. **Open**, like the phase. */
export type ComputerUsePermission = "granted" | "missing" | "unknown" | (string & {});

/** `computerUseSettings/read` result, also answered by `computerUseSettings/update`. */
export interface ComputerUseSettings {
  /** The apps list: apps Computer Use has asked about, most recent first; then the other saved grants, then the user's other blocks; then the locked rows. Each app once. A host that serves the list always answers it, so its absence means an older host. */
  apps?: ComputerUseApp[];
  /** The user's blocks in the order they were added, then the built-in blocks when `showBuiltIns` asked for them. */
  blockedApps: ComputerUseBlockedApp[];
  /** The computer-control dropdown, as it applies: `ask` while the stored blocked-apps list can't be read (ADR 630 D18.4). */
  computerControl: ComputerUseChoice;
  /** The installed and running apps, sorted by name, when the read asked for `installed`. */
  installedApps?: ComputerUseInstalledApp[];
  /** The screenshots dropdown, under the same rule. */
  screenshots: ComputerUseChoice;
}

/** `computerUseSettings/read` params. */
export interface ComputerUseSettingsReadParams {
  /** Also answer `installedApps`, for an app picker. Omitted means false. */
  installed?: boolean;
  /** Also list the built-in blocks as locked rows (the D18.8 toggle). Omitted means false. */
  showBuiltIns?: boolean;
}

/** `computerUseSettings/update` params: a patch. Omitted members are left alone; the whole patch applies or none of it does. */
export interface ComputerUseSettingsUpdateParams {
  /** Per-app choices to set. A locked app is refused; so is a bundle ID named twice, or also in `blockApps` or `unblockApps`. */
  apps?: ComputerUseAppPatch[];
  /** Bundle IDs to add to the user's blocked apps. A built-in block is refused: it is already blocked. */
  blockApps?: string[];
  /** The new computer-control dropdown value. */
  computerControl?: ComputerUseChoice;
  /** The new screenshots dropdown value. */
  screenshots?: ComputerUseChoice;
  /** Bundle IDs to remove from the user's blocked apps. Only the user's own entries can be removed; a built-in block stays. */
  unblockApps?: string[];
}

/** `computerUseSetup/changed` params. */
export interface ComputerUseSetupChanged {
  /** The session whose setup state changed; absent for the host's own setup, which only `computerUseHostSetup` holders receive. */
  sessionId?: string;
  /** Its new state. */
  state: ComputerUseSetupState;
}

/** Where the session's setup stands: `cua_setup`'s state codes, camelCase. **Open**: a result vocabulary, so an older client tolerates a new state. */
export type ComputerUseSetupPhase = "dormant" | "inProgress" | "restartRequired" | "readyForTarget" | "stopped" | (string & {});

/** `computerUseSetup/read` params. */
export interface ComputerUseSetupReadParams {
  /** The session whose setup to read. Omitted reads the host's own setup, which needs the `computerUseHostSetup` grant. */
  sessionId?: string;
}

/** `computerUseSetup/start` params: a human command. */
export interface ComputerUseSetupStartParams {
  /** The client's id for this command. */
  commandId: string;
  /** The session whose setup to start. Omitted starts the host's own setup, which needs the `computerUseHostSetup` grant. */
  sessionId?: string;
}

/** The session's setup state: the result of both methods and the `computerUseSetup/changed` payload's `state`. */
export interface ComputerUseSetupState {
  /** Accessibility. */
  accessibility: ComputerUsePermission;
  /** Input Monitoring: computer use is ready without it; some actions need it. */
  inputMonitoring: ComputerUsePermission;
  /** The sentence `cua_setup` gives the user for this answer. */
  message?: string;
  /** The `cua_setup` refusal code when the call was refused, verbatim. */
  refused?: string;
  /** Screen Recording. */
  screenRecording: ComputerUsePermission;
  /** Where setup stands. */
  setup: ComputerUseSetupPhase;
}

/** Context pressure level (tdd SS4.6.6): hard threshold first, both inclusive `>=`. Open. */
export type ContextPressureLevel = "normal" | "warning" | "blocked" | (string & {});

/** 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). */
export interface ContextUsage {
  /** Server-computed pressure level. */
  pressure: ContextPressureLevel;
  /** Counted-once occupancy at the latest provider-reported fact. */
  usedTokens: number;
  /** The effective context-window size; absent when the basis has no limit. */
  windowTokens?: number;
}

/** Cron's `details` payload (ADR 42728 D2, thirteenth directive).  Every field a family owns lives here, under the container's one `details` key, rather than flat beside the discriminators. Each is a **bounded machine fact**: scalars, short identifiers and a small fixed-shape array of those. */
export interface CronReceipt {
  /** Cron `create` and `delete`: the job id. On `delete`'s `missing` arm this is the caller's own id echoed back — that arm has no server-side subject to name.  On the `created` + `cancelled` pairing, this field also conveys the hidden fact: a job row was committed and will fire. */
  jobId?: string;
  /** Cron `list`: the served jobs in server order, `active` and `firing` rows only. */
  jobs?: CronReceiptJob[];
  /** Cron `create` (`created`, `duplicate`): absolute epoch-milliseconds of the job's next scheduled fire (the existing job's on `duplicate`, ADR 42728 D2). */
  nextFireAtMs?: number;
}

/** One row of the Cron `list` receipt's `jobs` array (ADR 42728 D2).  Server order, and **`active` + `firing` rows only**. A small fixed-shape array of scalars, which is what keeps it a bounded machine fact. */
export interface CronReceiptJob {
  /** The job's server-owned id. */
  jobId: string;
  /** Absolute epoch-milliseconds of the job's next scheduled fire. */
  nextFireAtMs: number;
}

/** Server-computed session cost member of [`CumulativeTokenUsage`] (tdd SS4.6.5, Amendment #41610 FR-41610-2/3). */
export interface CumulativeCost {
  /** True when at least one leg lacked price data — clients render `(partial)`. */
  partial: boolean;
  /** Estimated USD total, finite and non-negative. */
  usd: number;
}

/** Session running totals of counted-once usage (tdd SS4.6.5).  The cache splits and server-computed `cost` join the counters. The counters stay accumulate-only; `cost` is the documented exception — it may move either way on price re-adoption and is labeled estimate. `Copy` was dropped for the `cost` member. */
export interface CumulativeTokenUsage {
  /** Cache-read tokens, session total (FR-41610-1): saturating sum of the per-completion splits; an absent split contributes 0. Additive-optional: absent on the wire reads as 0 and zero totals are omitted, so pre-feature bytes decode and re-encode identically. */
  cacheReadTokens?: number;
  /** Cache-write tokens, session total (FR-41610-1). Additive-optional like the read split. */
  cacheWriteTokens?: number;
  /** Server-computed session cost (FR-41610-2): `None` (wire-absent) when no leg is priced — clients omit the row. Additive-optional: absent reads as unpriced. */
  cost?: CumulativeCost;
  /** Output tokens, session total. */
  outputTokens: number;
  /** Counted-once prompt tokens, session total. */
  promptTokens: number;
  /** Counted-once totals, session total. */
  totalTokens: number;
}

/** `damagedRange`: what one damaged range of the session log cost (ADR 60914 D1/D2). The reader finds the range in the log bytes; no log record is written for it, so every member is derived from the readable records around it. */
export interface DamagedRange {
  /** The last finished turn before the first damaged range, when one exists: the safe `session/fork` cut (ADR 60914 D1 "Fork cuts", D4). */
  lastGoodTurnId?: string;
  /** Records the log proves missing (session-stream sequence numbers no readable record or unreadable line accounts for). */
  missingRecords: number;
  /** RFC3339 `recordedAt` of the first readable record after the range; always present, since a range is read past only when readable records follow it (ADR 60914 D1). */
  readableAfterAt: string;
  /** RFC3339 `recordedAt` of the last readable record before the range; absent when the range starts the log. */
  readableBeforeAt?: string;
  /** Physical log lines in the range that are not a readable record. */
  unreadableLines: number;
}

/** The effective approval-mode projection (`EffectiveApprovalModeState`, tdd SS5.12): the same object `session/setApprovalMode` returns as `effectiveMode` and the `Session` object carries as `approvalMode`. */
export interface EffectiveApprovalModeState {
  /** The command that last set it; `null` when no command did. */
  lastCommandId: string | null;
  /** The mode in effect. */
  mode: ApprovalMode;
  /** How the mode took effect. */
  source: ApprovalModeSource;
}

/** The latest effective-model fact in the snapshot (tdd SS4.9.1). */
export interface EffectiveModel {
  /** The selected model. */
  modelId: string;
  /** The selected provider; `null` when the selection names none. */
  providerId: string | null;
  /** What drove the selection. */
  source: ModelChangeSource;
}

/** The optional `error.data` object (SS1.6). All members additive-optional; `kind` is always present when `data` is. */
export interface ErrorData {
  /** The next provable UTF-8 boundary on a misaligned text-media `item/readOutput` read (`-32602` `invalidParams`, FR-016b/D-17214-2): absent when no boundary is provable from the stored bytes ahead. */
  alignedNextOffset?: number;
  /** The rejected anchor value on `notFound`/`missingAnchor` and the `-32042` boundary arms (SS4.7.3, SS4.11); on `-32042` it is served as an explicit `null` when the request named no concrete anchor (spec 208 FM-005). */
  anchor?: string | null;
  /** Approval id on approval errors. */
  approvalId?: string;
  /** The stored output's availability on `outputUnavailable` — the durable `ToolOutputAvailability` value, read-time-derived when the durable record still says `available` (SS4.5.5; spec 208 FM-008). */
  availability?: string;
  /** The missing capability, on `capabilityRequired` errors. Typed on the grantable registry, so the experimental-only `rawLog` joins the stable domain as an additive open-enum extension when it graduates. */
  capability?: CapabilityName;
  /** The configured command-admission bound, on `backpressured` errors. */
  capacity?: number;
  /** Rejected server-minted choice on `approvalChoiceInvalid`. */
  choiceId?: string;
  /** The rejected command's identifier, on `commandRejected` errors. The ratified v1 contract pairs it with `reason` (specs/13929-msp-activation/tdd.md SS3.6 admission-failure table and its `-32030` example), so a client can settle the exact command it sent without parsing the message string. */
  commandId?: string;
  /** Current stage token on `approvalRequirementStale`. */
  currentRequirementId?: ApprovalRequirementRef;
  /** On `experimentalRequired` errors, the name of the experimental method, field or variant the request used, for example `turn/start.providerRequestOptions`. */
  descriptor?: string;
  /** Free-form additive detail. */
  details?: Record<string, unknown>;
  /** The oldest servable view position on `viewTruncated` (`-32040`, SS4.11); served as an explicit `null` when nothing before the head is servable — the null is present on the wire, never a dropped key (spec 208 FM-005 / Scenario 6.2). */
  earliestCursor?: string | null;
  /** The item whose stored output was requested, on the `item/readOutput` arms (`notFound`, `outputUnavailable`, and the misaligned-offset `invalidParams`). */
  itemId?: string;
  /** The stable camelCase category clients branch on. */
  kind: ErrorKind;
  /** Rejected inclusive fork boundary on `forkBoundaryInvalid`. */
  lastTurnId?: string;
  /** The latest installed boundary's view cursor on the `-32042` arms — always present in the `-32042` JSON and explicitly `null` when no boundary exists (SS4.11, FM-004). */
  latestBoundaryCursor?: string | null;
  /** The exceeded byte limit, on `inputTooLarge` errors. */
  limitBytes?: number;
  /** The store on `pluginNotFound` (`-32035`, SS3.29.1). */
  marketplace?: string;
  /** The rejected marketplace name on `marketplaceNotFound` (`-32034`, SS3.29.7) and `marketplaceAlreadyExists` (`-32036`, SS3.29.2); the rejected plugin name on `pluginNotFound` (`-32035`, SS3.29.1). */
  name?: string;
  /** The requested `outputRef.id`, on the same `item/readOutput` arms. */
  outputRef?: string;
  /** Candidate retained paths on `sessionAmbiguous`. */
  paths?: string[];
  /** Failure detail vocabulary (e.g. `"missingAnchor"` on `notFound` for a missing view-cursor anchor). */
  reason?: string;
  /** The original recovery-dependent construction's coherent observation. An absent or unusable observation establishes no supported recovery. */
  recoveryObservation?: RecoveryObservation;
  /** Winning resolution on `approvalAlreadyResolved`. */
  resolution?: ApprovalResolutionSummary;
  /** Whether retrying can succeed (e.g. `overloaded`). When present, overrides the error table row's `retryable` default for this code. */
  retryable?: boolean;
  /** Why the branch seed did not use a checkpoint, on the same arms: one of `no_usable_checkpoint`, `unsupported_checkpoint_shape`, `checkpoint_has_model_visible_tail`, `checkpoint_missing_suffix`; absent when the seed used a checkpoint or no fallback was recorded. */
  seedFallbackReason?: string;
  /** The branch-seed path the host read before rejecting, on branch-validation rejections (`session/fork`, `session/sideChat`: the `forkBoundaryInvalid`, `commandRejected` and `sessionNotFound` arms; SS2.5.3, SS2.5.7; #51365): one of `runtime_checkpoint_tail`, `runtime_full_replay`, `legacy_session_data` — the durable branch-seed vocabulary, so the client cites the real seed decision instead of guessing at a stale binary. */
  seedPath?: string;
  /** The rejected skill selector on `skillNotFound` (`-32032`, SS3.22.4). */
  selector?: string;
  /** Session identity on errors whose lookup is session-scoped. */
  sessionId?: string;
  /** Winning settlement on `userInputAlreadySettled`. */
  settlement?: UserInputSettlementSummary;
  /** The rejected upload id on `uploadNotFound` (`-32038`, SS3.33). */
  uploadId?: string;
  /** Prompt identity on user-input errors. */
  userInputId?: string;
  /** The blocked view position on `pageEventTooLarge` errors. */
  viewCursor?: string;
}

/** A stable `error.data.kind` category: camelCase, the value clients branch on. Open: new kinds are added as their methods land, and a new `kind` is additive only because this domain is declared open. */
export type ErrorKind = "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" | "computerUseUnavailable" | "marketplaceNotFound" | "pluginNotFound" | "marketplaceAlreadyExists" | "pluginMutationsDisabled" | "uploadNotFound" | "viewTruncated" | "outputUnavailable" | "boundaryPruned" | "boundaryUnusable" | "noBoundary" | "approvalNotFound" | "approvalAlreadyResolved" | "approvalChoiceInvalid" | "approvalRequirementStale" | "approvalReviewerUnavailable" | "userInputNotFound" | "userInputAlreadySettled" | "userInputAnswerInvalid" | (string & {});

/** The `error` member of an error response (SS1.2 §2.4). */
export interface ErrorObject {
  /** Registry code (Appendix B). Typed as a plain integer on the wire; the value domain is the registry below (INV-018). */
  code: number;
  /** Structured detail; carries `kind` when present. */
  data?: ErrorData;
  /** Human-readable message. Never a branch point (SS1.6). */
  message: string;
}

/** An error response frame (SS1.2 §2.4). Exactly one of `result` or `error` appears on a response; this type is the `error` half. */
export interface ErrorResponse {
  /** The error payload (Appendix B registry). */
  error: ErrorObject;
  /** Echo of the request id; `null` **only** for an unrecoverable parse error whose offending id could not be recovered (SS1.3). Always serialized, so `None` renders as `null` rather than being omitted — required-but-nullable (see [`require_nullable_id`]). */
  id: RequestId | null;
  /** The literal `"2.0"`. */
  jsonrpc: JsonRpcVersion;
}

/** `feedback/submit` classification (tdd SS3.25): the four TUI classes in camelCase wire spelling. **Closed**: a client-selected param vocabulary (#22785 E2). */
export type FeedbackClassification = "bug" | "badResult" | "goodResult" | "other";

/** `feedback/submit` result `outcome` (tdd SS3.25): how one confirmed submit resolved, mirroring the TUI `FeedbackSubmitOutcome` taxonomy. **Open**: a server-produced result vocabulary (#22785 E2) — an older client reading a newer value it does not know follows the open-enum tolerance rule instead of rejecting it. */
export type FeedbackSubmitOutcome = "uploaded" | "recorded" | "acceptedWithoutReceipt" | "trackingFailed" | "trackingUncertain" | "dark" | "disabled" | "noCredential" | "authRejected" | "rateLimited" | "failed" | (string & {});

/** `feedback/submit` params (tdd SS3.25): mirrors the TUI confirm-time `FeedbackRequest`. The call itself is the explicit confirm. */
export interface FeedbackSubmitParams {
  /** Consent to attach the session record; honored only for `bug`/`badResult` with `session_id` present. `true` with `with_files: false`, with a non-`bug`/`badResult` classification, or without `session_id` is `invalidParams` (F4, F8). Defaults to `false`. */
  attachSessionRecord?: boolean;
  /** The report class (required). */
  classification: FeedbackClassification;
  /** An absolute same-host path to a client-packed bundle, admitted only as a regular file under a size cap. */
  clientArtifactsPath?: string;
  /** The user report text (required; non-empty for `bug`). */
  note: string;
  /** Names the session this call is about when present (F8, superseding F3): the bundle lands in that session's dir. Names a session this host owns. When absent, the bundle lands in the host-level feedback folder and the `session_id` tag is omitted. */
  sessionId?: string;
  /** The files-consent decision (required). */
  withFiles: boolean;
}

/** `feedback/submit` result (tdd SS3.25): the upload receipt. */
export interface FeedbackSubmitResult {
  /** The host-local absolute path of the always-written local bundle. */
  bundlePath: string;
  /** The failure cause on the `failed`, `acceptedWithoutReceipt`, `trackingFailed`, and `trackingUncertain` arms. */
  cause?: string;
  /** The consent-vs-reality local-tracing note, kept for display. */
  localTracingNote?: string;
  /** How the submit resolved. */
  outcome: FeedbackSubmitOutcome;
  /** The effective retry delay in milliseconds, on `rateLimited`. */
  retryAfterMs?: number;
  /** The consent-vs-reality session note, kept for display. */
  sessionNote?: string;
  /** Whether the consented session record rode at all. */
  sessionRecordAttached: boolean;
  /** Whether the consented session record rode shortened to fit. */
  sessionRecordTruncated: boolean;
  /** The internal receipt-Task id once that Task succeeds. */
  taskId?: string;
  /** The intake's accept id — always present on the `uploaded` arm, optional on `trackingFailed`/`trackingUncertain`; never fabricated on `recorded`. */
  uploadId?: string;
}

/** 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. */
export interface ForkCutPoint {
  /** The last completed turn to copy, inclusive. Naming an in-progress or unknown turn fails `forkBoundaryInvalid`. */
  lastTurnId: string;
}

/** Fork provenance folded from the durable `session.fork.created` record (`ForkProvenance`, tdd SS2.4). */
export interface ForkProvenance {
  /** The `commandId` of the `session/fork` that created it. */
  commandId: string;
  /** An **opaque provenance string** preserved verbatim from the durable record. Display-only — not one of the SS6.2 cursor families: clients MUST NOT parse it and no method accepts it (tdd SS2.4). */
  cutCursor: string;
  /** Whether the fork named an explicit cut point. */
  cutExplicit: boolean;
  /** The source session this fork was cut from. */
  sessionId: string;
}

/** 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. */
export interface Goal {
  /** Goal creation time, epoch milliseconds, verbatim from the durable row. Absent on blocks whose producer never carried it (tool-result adoptions, older logs); absence must never render as a fabricated zero. */
  createdAtMs?: number;
  /** Current work description, when present. */
  currentWork?: string;
  /** Next work description, when present. */
  nextWork?: string;
  /** The goal objective text. */
  objective: string;
  /** Percent complete, verbatim (>100 passes through). */
  percentComplete: number;
  /** Goal status, verbatim from the durable goal state (free string by design: out-of-contract values pass through). */
  status: string;
  /** Last goal mutation time, epoch milliseconds, verbatim from the durable row. Same absence rule as `createdAtMs`. */
  updatedAtMs?: number;
}

/** `goal/clear` params (tdd SS3.18). An `objective` here is an unknown field and rejects `-32602 invalidParams` — the bare verbs carry exactly this pair. */
export interface GoalClearParams {
  /** The SS3.1.1 idempotency handle (UUIDv7). */
  commandId: string;
  /** The target session. */
  sessionId: string;
}

/** 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. */
export interface GoalCommandResult {
  /** Echoes the client's id. */
  commandId: string;
  /** Admission status. */
  status: CommandStatus;
  /** Present by exactly the four SS3.18 result cases: an idle wake carries the fresh goal turn's id; a busy `set`/`edit`/`resume` carries the admission-time active turn's id (a routing fact, not a delivery promise); `pause`/`clear` never carry it; an idle admission whose resulting goal is not unfinished parks the notification and carries none. **Additive-optional**: absent means "no turn named", never fabricated. */
  turnId?: string;
}

/** `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. */
export interface GoalEditParams {
  /** The SS3.1.1 idempotency handle (UUIDv7). */
  commandId: string;
  /** The replacement objective; same trim/non-empty rule as `goal/set`. */
  objective: string;
  /** The target session. */
  sessionId: string;
}

/** `goal/pause` params (tdd SS3.18); shape as `goal/clear`. */
export interface GoalPauseParams {
  /** The SS3.1.1 idempotency handle (UUIDv7). */
  commandId: string;
  /** The target session. */
  sessionId: string;
}

/** `goal/resume` params (tdd SS3.18); shape as `goal/clear`. */
export interface GoalResumeParams {
  /** The SS3.1.1 idempotency handle (UUIDv7). */
  commandId: string;
  /** The target session. */
  sessionId: string;
}

/** `goal/set` params (tdd SS3.18): set the session's goal objective. */
export interface GoalSetParams {
  /** The SS3.1.1 idempotency handle (UUIDv7). */
  commandId: string;
  /** The objective text; required, non-empty after Unicode-whitespace trim (the trimmed text is the payload). Empty-after-trim is `-32602 invalidParams` (tdd SS3.18). */
  objective: string;
  /** The target session. */
  sessionId: string;
}

/** 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". */
export type HistoryMode = "anchoredSnapshot" | "inline" | "snapshot" | "none" | (string & {});

/** Why a result served `history.mode: "none"`: the server's typed reason for serving no history. Open on the client side: an absent (older server) or unknown (newer server) value decodes conservatively as an unknown reason, and `viewCursor` text never substitutes for it. */
export type HistoryNoneReason = "excluded" | "cursorSuffix" | "historyBudget" | "projectionUnavailable" | "projectionReadLimit" | (string & {});

/** 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. */
export type HistoryPreference = "auto" | "inline" | "snapshot" | "anchored";

/** One installed handler (tdd SS3.26.1). */
export interface HookCatalogEntry {
  /** The row's own switch (tdd SS3.26.1). Non-enabled rows are included as `false`, never dropped. */
  enabled: boolean;
  /** The event the handler runs on (ADR 33398 D7 item 2). */
  event: HookEventName;
  /** Where the handler comes from (ADR 33398 D7 item 1). */
  handlerKind: HookHandlerKind;
  /** The handler key (config key or plugin hook id). */
  key: string;
}

/** Hook event names (tdd SS3.26.1, ADR 33398 D7 item 2): the lowercase-first-letter spelling of every `HookEventKind::all()` variant. Open (server-produced result vocabulary, the #22785 enum-openness rule): a future event value is additive. */
export type HookEventName = "sessionStart" | "userPromptSubmit" | "preToolUse" | "permissionRequest" | "postToolUse" | "preLLMCall" | "postLLMCall" | "preCompact" | "postCompact" | "subagentStart" | "subagentStop" | "stop" | "sessionEnd" | "notification" | "postToolUseFailure" | "stopFailure" | "postToolBatch" | "interrupt" | "sessionFork" | "toolUseStart" | (string & {});

/** A hook row's origin (tdd SS3.26.1, ADR 33398 D7 item 1): the config `HookSourceKind` values plus plugin-contributed. Open (server-produced result vocabulary, the #22785 enum-openness rule): a future origin is additive. */
export type HookHandlerKind = "managed" | "user" | "project" | "plugin" | (string & {});

/** `hook/list` params (tdd SS3.26.1). Per-session because hook scope follows the session's workspace and plugin state. */
export interface HookListParams {
  /** The target session. */
  sessionId: string;
}

/** `hook/list` result (tdd SS3.26.1): one row per installed handler per event — a `ResolvedHookHandler` carries one event, and grouping would lose matcher/command identity (ADR 33398 D7 item 1). */
export interface HookListResult {
  /** The session's installed hook rows (tdd SS3.26.1 promises the set, not an order). */
  hooks: HookCatalogEntry[];
}

/** `hookRun` durable outcome (tdd SS4.5.11). Open: new outcomes are additive, and clients MUST render unknown values generically. */
export type HookRunStatus = "completed" | "blocked" | "failed" | "timedOut" | "cancelled" | (string & {});

/** 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. */
export type IfBusy = "queue" | "steer" | "replace";

/** `initialize` request params (SS1.4.1). */
export interface InitializeParams {
  /** Capability posture; absent means all defaults. */
  capabilities?: ClientCapabilities;
  /** Client identification. */
  clientInfo: ClientInfo;
}

/** The `initialize` result (SS1.4.1). */
export interface InitializeResult {
  /** Echo of the effective negotiated experimental setting. */
  experimentalApi: boolean;
  /** Subset of the requested capabilities, plus policy-implicit grants. Fixed for the connection lifetime (INV-009). */
  grantedCapabilities: CapabilityName[];
  /** Absolute path of the muse home directory. */
  museHome: string;
  /** Server runtime platform family. */
  platformFamily: PlatformFamily;
  /** Server operating system. */
  platformOs: PlatformOs;
  /** Whether this host can enforce the sandbox. Optional so adding it stays backward compatible; a v1 host always sends it, and a client reads absent as unknown — the host predates the field, so the client falls back to its own probe rather than inventing an answer. */
  sandboxAvailability?: SandboxAvailability;
  /** Why enforcement is impossible. Sent only when `sandbox_availability` is `unavailable`; a client MUST NOT infer a reason when none is sent. */
  sandboxUnavailableReason?: SandboxUnavailableReason;
  /** Envelope schema version and stable-surface fingerprint. */
  schema: SchemaInfo;
  /** Server identification. */
  serverInfo: ServerInfo;
  /** Whether this host persists its sessions. Optional so adding it stays backward compatible; a v1 host always sends it, and a client reads absent as `durable` because no server that omits it has the ephemeral profile. */
  sessionDurability?: SessionDurability;
  /** Exact user-agent string presented to upstream model providers. */
  userAgent: string;
}

/** One transcript item at one revision (tdd SS4.4.1 common fields plus the per-kind fields of SS4.5.2–4.5.11, 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. */
export interface Item {
  /** `subagent`: agent definition path. */
  agentPath?: string;
  /** `toolCall`: the approval that gated this call (tdd SS5); join key for the approval view events. */
  approvalId?: string;
  /** `toolCall`: the model-authored argument JSON, **verbatim**; clients parse. Verbatim keeps the fold byte-deterministic and survives model-emitted almost-JSON (tdd SS4.5.5). */
  args?: string;
  /** `userMessage`: image attachment metadata only — base64 payloads are not echoed back on the view (tdd SS4.5.2). */
  attachments?: MessageAttachment[];
  /** `toolCall`: `true` once the task was durably backgrounded; delivered via `item/updated`. */
  background?: boolean;
  /** `toolCall`: who backgrounded the task; absent on pre-split records — never inferred (tdd SS4.5.5). */
  backgroundInitiator?: BackgroundInitiator;
  /** `backgroundTerminalCompletion`: the five facts the Finished cell renders (ADR 50041 D4). */
  backgroundTerminalCompletion?: BackgroundTerminalCompletion;
  /** `reminderChild`: `true` when this child is a blocking reminder (it holds the turn open until it settles); absent otherwise, never `false` (ADR 41191 D4). The status word stays off the wire; clients name the reminder from `reminderAgentId`. */
  blocking?: boolean;
  /** `toolCall`: the provider call id (`call_...`), opaque. */
  callId?: string;
  /** `workflow`: one `outputRef`-shaped link per recorded child spawn with an objective (`kind: "workflow_child_prompt"`), fetched via `item/readOutput` (tdd SS4.5.8/SS4.7.4, #45449). */
  childPromptRefs?: OutputRef[];
  /** `subagent`/`reminderChild`: the child's own session id, readable via `session/read`/`view/page` — child transcript drill-down without a second protocol (tdd SS4.5.7). */
  childSessionId?: string;
  /** `reminderChild`: parent-session-dir-relative child log path; absent when no filesystem log. */
  childSessionLogPath?: string;
  /** `workflow`: folded per-child state, keyed by `(childId, attempt)`, re-emitted whole on every change — the item `revision` is the ordering guard (tdd SS4.5.8). */
  children?: WorkflowChild[];
  /** `userMessage`/`userShell`: the submitting command — multi-client UIs de-duplicate their local echo on it. */
  commandId?: string;
  /** `userShell`: the command text as submitted. */
  commandText?: string;
  /** `subagent`: camelCased `SubagentControlStatus` (open enum); `status` stays the generic item vocabulary. */
  controlStatus?: SubagentControlStatus;
  /** `agentMessage`: `true` when the provider stream died mid-reply and the run failed with this partial text committed (ADR 50063 D2) — the wire mark for the gate-off "incomplete response" rule (#13328). Absent otherwise; never cleared once set. */
  cutOff?: boolean;
  /** `damagedRange`: what the damaged range cost (ADR 60914 D2). */
  damagedRange?: DamagedRange;
  /** `workflow`: the run-level declared-phase label — the last `Phase` detail-row label of the reconciled projection; terminal-only, absent while live (tdd SS4.5.8, #45449). */
  declaredPhase?: string;
  /** `scheduledFire`: the occurrence number within the job's history, present with occurrence metadata (tdd SS4.5.17; ADR 45446 D2). */
  deliveryNumber?: number;
  /** `subagent`: nesting depth. */
  depth?: number;
  /** `toolCall`: the tool's own words for this call; absent = none (tdd SS4.5.5). */
  displayLabel?: ToolDisplayLabel;
  /** `userMessage`: presentation form (tdd SS3.2); absent when the client sent none. */
  displayText?: string;
  /** `userShell`/`subagent`: observed wall-clock duration. `workflow`: the run's wall time from launch to reconciliation, set only on the settling `item/completed` — never a sum of child durations. `toolCall`: the Backgrounded row's duration (ADR 50041 D11) — the open→update record delta in whole ms, served on the `backgroundStatus` re-emission and frozen there; absent otherwise. */
  durationMs?: number;
  /** `workflow`: launched entry identity. */
  entryId?: string;
  /** `hookRun`: the hook event in Q2 camelCase vocabulary (tdd SS4.5.11). */
  event?: HookEventName;
  /** `userShell`: the process exit code, when it exited by code. */
  exitCode?: number;
  /** `userShell`: the terminating signal NUMBER, when signalled (e.g. 9) — the durable payload verbatim; nothing maps numbers to names, and the fold never invents one. */
  exitSignal?: number;
  /** `toolCall`: machine-readable failure class (`TaskFailureKind`, snake_case verbatim — durable runtime vocabulary, the SS1.6 casing exemption). */
  failureKind?: string;
  /** `toolCall`/`subagent`: `Failed`/`Rejected`/`Cancelled` reason text, verbatim. */
  failureReason?: string;
  /** Server-provided one-line human summary any kind MAY carry, for generic rendering of kinds a client does not recognize; new kinds SHOULD carry it during their first release cycle (tdd SS4.10). */
  fallbackText?: string;
  /** `workflow`: the human terminal summary projected from the reconciled Launch envelope, bounded at the 64 KiB surface budget; terminal-only (tdd SS4.5.8, #45449). */
  finalSummary?: string;
  /** `reminderChild`: the reminder generation. */
  generationId?: number;
  /** `hookRun`: the durable `hook_key` (tdd SS4.5.11). */
  hookKey?: string;
  /** Bare UUIDv7; the item's identity across its whole lifecycle. Identity rule (tdd SS4.4.1): the task id for task-backed kinds (`toolCall`, `subagent`), the pre-minted commit `message_id` for delta-streamed kinds (`agentMessage`, `reasoning`), `EventId::derive` over the session id and the range's starting sequence number for `damagedRange` (no record carries it, SS4.5.16), and the opening durable record's event id for everything else. Opaque to clients. */
  itemId: string;
  /** `scheduledFire`: the cron job id that fired (tdd SS4.5.17; ADR 45446 D2, spec 13929 amendment #62595 FR-62595-1). */
  jobId?: string;
  /** The item kind (open enum): clients MUST render unknown kinds generically — kind name plus `status` plus `fallbackText` (tdd SS4.10). */
  kind: ItemKind;
  /** `hookRun`: capped display label (tdd SS4.5.11). */
  label?: string;
  /** `workflow`: the reconciled terminal message, set on completion. */
  message?: string;
  /** `agentMessage`: the phase the model declared on the commit; see [`MessagePhase`]. */
  messagePhase?: MessagePhase;
  /** `toolCall`: rich content the model saw beyond text; base64 is not inlined on the view (tdd SS4.5.5). */
  modelVisibleContent?: ModelVisibleContent[];
  /** `monitorFeed`: the monitor's arm-time description with the durable `"Monitor event: "` summary prefix stripped; model- controlled tool input under the 64 KiB per-surface budget — sanitize before render (ADR 50058-monitor-feed-wire D1/D3). */
  monitorDescription?: string;
  /** `monitorFeed`: the monitor task id — the same value as that monitor's `toolCall` `itemId` (ADR 50058-monitor-feed-wire D1). */
  monitorId?: string;
  /** `scheduledFire`: the next scheduled epoch in milliseconds; absent on a final delivery (tdd SS4.5.17; ADR 45446 D2). */
  nextFireAtMs?: number;
  /** `subagent`: objective as spawned, bounded on the wire at the 64 KiB retained-text budget (tdd SS4.5.4, ADR 35691 D9); a cut sets `truncated`. The durable record stays verbatim. */
  objective?: string;
  /** `compaction`: terminal only — folds installed/fallback status. */
  outcome?: CompactionOutcome;
  /** `toolCall`/`userShell`: stored-output reference; fetch the full bytes via `item/readOutput` (served by #208). */
  outputRef?: OutputRef;
  /** `toolCall`: stored structured-patch reference (`kind: "tool_patch"`, `mediaType: "application/json"`); the body is fetched via `item/readOutput` with `patchRef.id`, and the ref survives the SS2.5.2 elided-snapshot rung exactly like `outputRef` without ever being an elision trigger (tdd SS2.5.2, SS4.5.5; #33025). */
  patchRef?: OutputRef;
  /** `toolCall`: server-authored edit-family diff summary (#33025) — always beside `patchRef`; absent = no diff available (tdd SS4.5.5). */
  patchSummary?: PatchSummary;
  /** `workflow`: `true` only while a durable pause fact is in force for the run's generation; absent otherwise, never `false` (tdd SS4.5.8, ADR 45437 D2; the fold sets it on pause commit and clears it on resume-commit supersession or the generation's terminal). */
  paused?: boolean;
  /** `reasoning`: provider reasoning item id (e.g. `rs_...`), for provider-side correlation. */
  providerItemId?: string;
  /** `compaction`: noop/failure reason, verbatim (snake_case durable vocabulary, e.g. `"no_compactable_history"`). `hookRun`: terminal-only capped terminal reason (tdd SS4.5.11). */
  reason?: string;
  /** RFC3339 timestamp of the item's driving durable record. Absent on ephemeral-opened items until first durable re-emission (tdd SS4.4.1). */
  recordedAt?: string;
  /** `reminderChild`: the reminder agent's id. */
  reminderAgentId?: string;
  /** `subagent`: the result envelope from `ResultReady` (tdd SS4.5.7). */
  result?: SubagentResult;
  /** `workflow`: set on resumed launches. */
  resumeFromRunId?: string;
  /** `userMessage`: `true` after an accepted retract (tdd SS4.5.1); re-emitted via `item/updated`. */
  retracted?: boolean;
  /** Integer >= 1, strictly monotonic per item; apply rule is replace-iff-higher. `item/delta` never bumps it (tdd SS4.4.1). */
  revision: number;
  /** `subagent`: role as spawned. */
  role?: string;
  /** `hookRun`: terminal-only durable outcome; stays `blocked` when the item settles `rejected` (tdd SS4.5.11). */
  runStatus?: HookRunStatus;
  /** `scheduledFire`: the fire's scheduled epoch in milliseconds (tdd SS4.5.17; ADR 45446 D2). */
  scheduledFireAtMs?: number;
  /** `workflow`: launched script identity. */
  scriptId?: string;
  /** `sideChat`: the side's own session id, readable via `session/read`/`view/page` — drill-down without a second protocol (tdd SS4.5.13; ADR 45435 D3). */
  sideSessionId?: string;
  /** Open enum; terminal = anything other than `"inProgress"`. Unknown values MUST be treated as terminal-unknown and rendered generically (tdd SS4.4.1). */
  status: ItemStatus;
  /** `toolCall`: the latest external-attempt facet, field-for-field — countdown inputs the client renders the tick from; absent when the latest detail carries none (tdd SS4.5.5, #45448). */
  statusAttempt?: StatusAttempt;
  /** `toolCall`: the latest child-summary facet, field-for-field; absent when the latest detail carries none (tdd SS4.5.5, #45448). */
  statusChildren?: StatusChildren;
  /** `toolCall`: the latest health facet, field-for-field; absent when the latest detail carries none (tdd SS4.5.5, #45448). */
  statusHealth?: StatusHealth;
  /** `toolCall`: the task's visible latest-status line — the latest `Status` message through the shared detail normalization; absent when no status folded or nothing displayable remains (tdd SS4.5.5, #45448). */
  statusLine?: string;
  /** `toolCall`: the latest detail's phase row, verbatim; absent when the latest detail carries none (tdd SS4.5.5, #45448). */
  statusPhase?: string;
  /** `toolCall`: the latest progress facet, field-for-field; absent when the latest detail carries none (tdd SS4.5.5, #45448). */
  statusProgress?: StatusProgress;
  /** `toolCall`: the latest active-step facet, field-for-field; absent when the latest detail carries none (tdd SS4.5.5, #45448). */
  statusStep?: StatusStep;
  /** `userMessage`: `true` when injected mid-turn via `turn/steer` or `ifBusy: "steer"`; absent otherwise. */
  steered?: boolean;
  /** `workflow`: display-only stop affordance — `true` while the run is open, `false` once settled; stopping rides `workflow/cancel` (tdd SS4.5.8, #45449). Authorizes nothing. */
  stopAvailable?: boolean;
  /** `compaction`: summarizer strategy (installed only). */
  strategyId?: string;
  /** `subagent`: durable child identity (`subagent_id`). */
  subagentId?: string;
  /** `compaction`: opaque provenance string naming the compaction boundary. Also a compaction-anchored read anchor, accepted by `session/resume` and `view/page`. Still opaque — clients relay it, never parse it. */
  summarizedThrough?: string;
  /** `reasoning`: one entry per summary part; part *n* streams via `item/delta` field `"summary.n"` (part boundary = index change). */
  summary?: string[];
  /** `reminderChild`: the linked task id. */
  taskId?: string;
  /** `userMessage`: the prompt text as submitted. `agentMessage`: the accumulated reply, streamed via `item/delta` field `"text"`. `reasoning`: raw committed reasoning text where the provider exposes it (never streamed in v1, tdd SS4.5.4). */
  text?: string;
  /** `workflow`: the run's launch token budget, set from the launch fact (tdd SS4.5.8, #45449); absent when the launch carried none. */
  tokenBudget?: WorkflowTokenBudget;
  /** `compaction`: token budget snapshot after, when measured. */
  tokensAfter?: number;
  /** `compaction`: token budget snapshot before, when measured. */
  tokensBefore?: number;
  /** `toolCall`: tool name. */
  tool?: string;
  /** `toolCall`: the shared semantic receipt — what the operation did, as machine-readable fact (ADR 43399 D1, tdd SS4.5.5). Optional and additive: absence is always valid and is never an error (D3). When present, a server serves the **same** receipt on every item path — `item/completed`, `view/page`, seeded snapshots and resume (D3). Observation only; carries no control authority (D4), and no field in it enters model-visible content (D7). */
  toolReceipt?: ToolReceipt;
  /** `compaction`: what initiated the compaction. */
  trigger?: CompactionTrigger;
  /** `workflow`: camelCased `WorkflowLaunchTriggerSource`, verbatim (durable runtime vocabulary, e.g. `"modelProposal"`). */
  triggerSource?: string;
  /** `true` when the server's per-surface text budget saturated a streamed surface (`agentMessage.text`, `reasoning.summary[*]`, `toolCall.visibleOutput`, `userShell.visibleOutput`), cut a `subagent` surface (`objective`, `fallbackText`, `result.summary`, `result.text`), or cut a `monitorFeed` surface (`text`, `fallbackText`, `monitorDescription`) (ADR 50058-monitor-feed-wire D3). On a `subagent` item the flag is item-level and never cleared: once any of those four is cut, every later update keeps it, even when `result.text` arrives whole (ADR 35691 D9). The durable full text remains in the log (tdd SS4.5.4). */
  truncated?: boolean;
  /** The owning turn (== the submitting `commandId` for fresh turns, tdd SS3.1.4). `null` for the kinds outside a turn: `userShell` always (tdd SS4.5.6), `hookRun` for session-boundary runs, `monitorFeed` always (ADR 50058-monitor-feed-wire D1), `sideChat` always (SS4.5.13), `damagedRange` always (ADR 60914 D2). */
  turnId?: string | null;
  /** `subagent`: **transitive** observed usage — the child and its own descendants; updated in place, absent until first observation; never folded into `session/tokenUsage.cumulative` (tdd SS4.6.5). */
  usage?: TokenUsage;
  /** `toolCall`/`userShell`: bounded transcript-visible result text (budget per tdd SS4.5.4); streams via `item/delta` field `"output"`. */
  visibleOutput?: string;
  /** `subagent`/`workflow`: the owning durable workflow run id (opaque string — not a UUID family). */
  workflowRunId?: string;
}

/** `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). */
export interface ItemCompletedParams {
  /** The full item at its terminal revision. */
  item: Item;
  /** The owning session. */
  sessionId: string;
  /** The durable records this event folded from. */
  sourceRange: SourceRange;
  /** Opaque, strictly monotonic view cursor (tdd SS4.1). */
  viewCursor: string;
}

/** `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`. */
export interface ItemDeltaParams {
  /** The appended text; concatenation of a field path's deltas in cursor order equals that field's value on `item/completed` unless the surface saturated (spec 14653 INV-005). */
  delta: string;
  /** Dotted field path the append targets (`"summary.0"`, `"output"`, ...); absent means `"text"` (tdd SS4.3.1). */
  field?: string;
  /** The open item being appended to. */
  itemId: string;
  /** The owning session. */
  sessionId: string;
  /** Opaque, strictly monotonic view cursor (tdd SS4.1). */
  viewCursor: string;
}

/** The eleven v1 item kinds (tdd SS4.5.2–4.5.13) plus post-v1 kinds (tdd SS4.5.14+). Open: a new kind is additive evolution, and clients MUST render unknown kinds generically (tdd SS4.10). */
export type ItemKind = "userMessage" | "agentMessage" | "reasoning" | "toolCall" | "userShell" | "subagent" | "workflow" | "reminderChild" | "compaction" | "hookRun" | "sideChat" | "webSearch" | "monitorFeed" | "damagedRange" | "scheduledFire" | "backgroundTerminalCompletion" | "overdueNotice" | (string & {});

/** 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. */
export type ItemReadOutputEncoding = "utf8" | "base64";

/** `item/readOutput` params: byte-ranged fetch of stored full output that the view truncated, via the item's `outputRef`. Read-only; works on loaded and unloaded sessions; no lease. */
export interface ItemReadOutputParams {
  /** The item whose stored output is fetched. */
  itemId: string;
  /** STORED bytes requested; default and max 6 MiB (tdd SS4.7.4). A value above the max is served at the max. */
  lengthBytes?: number;
  /** STORED-byte offset to start from; 0 when omitted. STORED bytes are a property of the output, not of a transport (tdd SS4.7.4). */
  offsetBytes?: number;
  /** The `outputRef.id` from the item (never the `uri`; the uri is display/provenance). */
  outputRef: string;
  /** The session the item belongs to. */
  sessionId: string;
}

/** `item/readOutput` result (tdd SS4.7.4): one stored-byte page. */
export interface ItemReadOutputResult {
  /** STORED bytes served in THIS response (not the output's total; that is `outputRef.byteLen` on the item). The next page's `offsetBytes` is `offsetBytes + byteLen` — short-serving and advancing are separate, so paging never skips or double-reads a byte (tdd SS4.7.4). */
  byteLen: number;
  /** The served range, decoded per `encoding`. */
  content: string;
  /** How `content` encodes the stored bytes. */
  encoding: ItemReadOutputEncoding;
  /** `true` when this range reached the end of the stored output. */
  eof: boolean;
  /** The stored output's media type (e.g. `text/plain`). */
  mediaType: string;
  /** The STORED-byte offset this response actually served from. */
  offsetBytes: number;
}

/** `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). */
export interface ItemStartedParams {
  /** The full item at revision 1. */
  item: Item;
  /** The owning session. */
  sessionId: string;
  /** The durable records this event folded from; absent on an ephemeral-sourced open (spec 14653 INV-009). */
  sourceRange?: SourceRange;
  /** Opaque, strictly monotonic view cursor (tdd SS4.1). */
  viewCursor: string;
}

/** Item status (tdd SS4.4.1). Open; terminal = anything other than `"inProgress"`, and unknown values are terminal-unknown, rendered generically. */
export type ItemStatus = "inProgress" | "completed" | "failed" | "cancelled" | "rejected" | "timedOut" | (string & {});

/** `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). */
export interface ItemUpdatedParams {
  /** The full item at a higher revision. */
  item: Item;
  /** The owning session. */
  sessionId: string;
  /** The durable records this event folded from. */
  sourceRange: SourceRange;
  /** Opaque, strictly monotonic view cursor (tdd SS4.1). */
  viewCursor: string;
}

/** The literal `"2.0"` every frame carries (SS1.2). */
export type JsonRpcVersion = "2.0";

/** The last `turn/completed` the session-view fold applied, restated on `session/resume` and `session/read` so a reopened session can report a failed last turn (tdd SS2.5.2, ADR 36635 D2/D3). */
export interface LastTurn {
  /** Copied when the `turn/completed` carried it: runtime `failed` terminals do, host-death `failed` terminals do not (ADR 36635 D2). */
  error?: TurnError;
  /** Copied when the `turn/completed` carried it; a synthesized host-death `failed` terminal carries only this (`crash`, `crash_inferred`, or `incomplete`). Free display text: clients never branch on it. */
  reason?: string;
  /** The turn's terminal (tdd SS4.5.1; open enum). */
  terminal: TurnTerminal;
  /** The turn's id, as on its `turn/completed`; clients deduplicate a live `turn/completed` against this member by it (ADR 36635 D2). */
  turnId: string;
}

/** Quota limit kinds (tdd SS4.5.1, ADR 50047 D2): open for evolution. */
export type LimitKind = "tierLimit" | (string & {});

/** `media/upload` params (tdd SS3.33, ADR 45443 D5): one chunk of a client-minted upload. All members required. */
export interface MediaUploadParams {
  /** This chunk's bytes; each call's frame stays in the SS1.1 budget. */
  chunkBase64: string;
  /** The upload's chunk total; positive. */
  chunkCount: number;
  /** This chunk's 0-based position. */
  chunkIndex: number;
  /** One per call. While the host runs, replaying it with the same params returns the recorded receipt, and reusing it with different params is refused. After a host restart, start over under a new `uploadId`. */
  commandId: string;
  /** `video/mp4` or `video/quicktime`, matching `VideoInput`. */
  mediaType: string;
  /** The session owning the video store. */
  sessionId: string;
  /** The assembled byte count; must equal the bytes the chunks deliver. */
  totalBytes: number;
  /** The client-minted upload id (UUIDv7), sent on every chunk. */
  uploadId: string;
}

/** `media/upload` result (tdd SS3.33): echoes the client-minted id, on every chunk and replay. */
export interface MediaUploadResult {
  /** The receipt the turn part references. */
  uploadId: string;
}

/** `userMessage` image attachment metadata (tdd SS4.5.2): metadata only — the durable bytes live in the log and are reachable on the raw altitude. */
export interface MessageAttachment {
  /** This attachment's name, `<itemId>/<n>` — the item's id plus this entry's 1-based position in its `attachments` array (tdd SS4.5.2, D-071, ADR 42850; #42850). Name only: no link form and no byte read by id (#42648).  Set by the server on every attachment entry it emits, and identical on live, paging, snapshot and rebuild paths (tdd SS4.5.2). Optional in the schema so older servers stay valid; clients compare and store the whole string and MUST NOT parse it (ADR 42850). */
  attachmentId?: string;
  /** Pixel height, when known. */
  height?: number;
  /** The image media type (e.g. `"image/png"`). */
  mediaType: string;
  /** Attachment type, `"image"` in v1 (free string: attachment vocabulary grows additively with the runtime's intake surface). */
  type: string;
  /** Pixel width, when known. */
  width?: number;
}

/** `agentMessage.messagePhase` (tdd SS4.5.3, #50254): the phase the model declared on the commit, never inferred from position. Set on the completed item only; absent on `item/started`, which opens before the phase is recorded. Open: a client reads an absent or unknown value on a completed item as `"finalAnswer"` and still decodes the item. Not a turn-done signal; `turn/completed` is. */
export type MessagePhase = "commentary" | "finalAnswer" | (string & {});

/** One visible catalog row (tdd SS3.10). Catalog rows marked hidden never reach the wire, so a client cannot select one. */
export interface ModelCatalogEntry {
  /** Context limit; `null` when the catalog source declared nothing. */
  contextLimit: number | null;
  /** Cost block; `null` when the catalog source declared nothing. */
  cost: ModelCost | null;
  /** The row's catalog default. Optional only for decoding older hosts; a present value is never null and is always a member of `variants`. Absent under `"unknown"` (ADR 33400 D2). */
  defaultReasoningEffort?: ReasoningEffort;
  /** Description; `null` when the catalog source declared nothing. */
  description: string | null;
  /** Presentation label. */
  displayLabel: string;
  /** Marks the session's effective model when `sessionId` was supplied. May be false for every row — a client MUST NOT assume exactly one. */
  isActive: boolean;
  /** Marks the catalog's default row. May be false for every row. */
  isDefault: boolean;
  /** The selectable model id. */
  modelId: string;
  /** Output limit; `null` when the catalog source declared nothing. */
  outputLimit: number | null;
  /** Provider profile; `null` when the catalog source declared nothing. */
  profileId: string | null;
  /** Provider routing. */
  providerId: string;
  /** Described selectable tiers, a same-order subset of `variants`. Optional only for decoding older hosts; a present value is never null. Absent under `"unknown"` (ADR 33400 D2). */
  reasoningEffortVariants?: ModelDescribedReasoningEffort[];
  /** Release date; `null` when the catalog source declared nothing. */
  releaseDate: string | null;
  /** Complete ordered selectable efforts. Optional only for decoding older hosts; a present value is never null. Current hosts always send it. */
  variants?: ModelReasoningEffortVariants;
}

/** Where a model catalog came from (tdd SS3.10). **Open**: an unrecognized value is an unknown source, not an error. */
export type ModelCatalogSource = "providerCatalog" | "fakeCatalog" | "unresolvedCatalog" | "bundledCatalog" | "configCatalog" | (string & {});

/** What drove a model selection (tdd SS4.6.1). Open. */
export type ModelChangeSource = "user" | "default" | "policy" | (string & {});

/** 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. */
export interface ModelCost {
  /** Cached-input cost, a decimal string. */
  cached: string;
  /** Currency; nullable — today's catalogs are USD. */
  currency: string | null;
  /** Input cost, a decimal string. */
  input: string;
  /** Output cost, a decimal string. */
  output: string;
}

/** One described reasoning-effort tier of a `model/list` row (tdd SS3.10, ADR 33400 D2): a selectable tier plus the catalog's display string for it when declared. */
export interface ModelDescribedReasoningEffort {
  /** The catalog's per-tier display string; absent when the catalog declared none. Optional only for decoding; a present value is never null. */
  description?: string;
  /** The tier, in the closed D-024 vocabulary. */
  tier: ReasoningEffort;
}

/** `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. */
export interface ModelListParams {
  /** When present, the row matching that session's effective model is flagged `isActive`. When absent, no row is active — a client may list before it has a session (tdd SS3.10). */
  sessionId?: string;
}

/** `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. */
export interface ModelListResult {
  /** Visible rows only, newest `releaseDate` first. */
  models: ModelCatalogEntry[];
  /** The catalog's profile; `null` when none. */
  profileId: string | null;
  /** The catalog's provider. */
  providerId: string;
  /** Where the catalog came from — how a client tells a live provider catalog from a test fake and labels it honestly. */
  source: ModelCatalogSource;
}

/** A complete ordered effort set, or an explicit unknown capability. */
export type ModelReasoningEffortVariants = ReasoningEffort[] | UnknownModelReasoningEffortVariants;

/** A model selection (tdd SS3.8). Empty strings are normalized to absent. */
export interface ModelSelection {
  /** Presentation label. */
  displayLabel?: string;
  /** Catalog model id. Required. */
  modelId: string;
  /** Provider profile. Omitted and explicit `null` both mean "no profile" (#23468). */
  profileId?: string | null;
  /** Provider routing. */
  providerId?: string;
}

/** Rich content the model saw beyond text (tdd SS4.5.5, `ModelVisibleToolContent`): metadata only — fetch bytes via `item/readOutput` when an `outputRef` exists. */
export interface ModelVisibleContent {
  /** Pixel height, when known. */
  height?: number;
  /** The content media type. */
  mediaType: string;
  /** The recorded content path. */
  path: string;
  /** The tool that produced the content. */
  sourceToolName: string;
  /** Content type, `"image"` in v1 (free string, grows with the durable vocabulary). */
  type: string;
  /** Pixel width, when known. */
  width?: number;
}

/** `monitor/inboxItemAdmitted` params (tdd SS4.5.18): one monitor inbox admission — the fold keys gate-off consumes. */
export interface MonitorInboxItemAdmittedParams {
  /** The model-facing delivery text. */
  body: string;
  /** The producer-recorded pre-augmentation content; absent on pre-#24686 records. */
  displayBody?: string;
  /** Per-task event order key (with `line_index`). */
  eventIndex: number;
  /** Monitor event kind, snake_case, open vocabulary — clients ignore unknown kinds. */
  eventKind: string;
  /** The inbox item id (dedupe key). */
  itemId: string;
  /** Line order key; absent when the event has no line. */
  lineIndex?: number;
  /** Admission stamp (RFC3339); consumed by the pending sort. */
  queuedAt: string;
  /** The owning session. */
  sessionId: string;
  /** Whether the event carries displayable lines. */
  showLines: boolean;
  /** The durable records this event folded from. */
  sourceRange: SourceRange;
  /** The notice-text summary. */
  summary: string;
  /** The owning monitor task id (per-task set key). */
  taskId: string;
  /** Opaque, strictly monotonic view cursor (tdd SS4.1). */
  viewCursor: string;
}

/** `monitor/inboxItemDrained` params (tdd SS4.5.18): one monitor inbox drain — a consumption marker with its recorded stamp. */
export interface MonitorInboxItemDrainedParams {
  /** False is a local claim-only recall: no delivery row or recovery consequence, but the drain still stamps the awaiting verdict. */
  deliveryVisible: boolean;
  /** The draining run stream (`StreamRef`), absent means the current draining run. */
  drainTargetRunStream?: StreamRef;
  /** The drain record's recorded stamp (RFC3339), the drain-side operand of drain-vs-void latest-wins. */
  drainedAt: string;
  /** The drained inbox item id. */
  itemId: string;
  /** The owning session. */
  sessionId: string;
  /** The durable records this event folded from. */
  sourceRange: SourceRange;
  /** Opaque, strictly monotonic view cursor (tdd SS4.1). */
  viewCursor: string;
}

/** `monitor/inboxItemVoided` params (tdd SS4.5.18): one wake-missed void — count-only, no transcript row (spec 9627 D15). */
export interface MonitorInboxItemVoidedParams {
  /** The voided inbox item id. */
  itemId: string;
  /** The owning session. */
  sessionId: string;
  /** The durable records this event folded from. */
  sourceRange: SourceRange;
  /** Opaque, strictly monotonic view cursor (tdd SS4.1). */
  viewCursor: string;
  /** The anomaly's recorded stamp (RFC3339), the void-side operand of drain-vs-void latest-wins. */
  voidedAt: string;
}

/** A notification frame, either direction (SS1.2 §2.2). No `id`; a notification is never answered. */
export interface Notification {
  /** Emission time in Unix milliseconds, recorded once at emission; server→client notifications only (SS1.2.5). Optional on the wire so decoders tolerate older servers. */
  emittedAtMs?: number;
  /** The literal `"2.0"`. */
  jsonrpc: JsonRpcVersion;
  /** Notification method name. */
  method: string;
  /** Method-specific parameters; omitted entirely when empty. */
  params?: Record<string, unknown>;
}

/** Stored-output reference (tdd SS4.5.5): the camelCased fold of the durable `ToolOutputRef`. The fetch path is `item/readOutput` (#208). */
export interface OutputRef {
  /** Whether the bytes are servable (tdd SS4.5.5). */
  availability: OutputRefAvailability;
  /** Stored byte length. */
  byteLen: number;
  /** Content digest (e.g. `"sha256:..."`), when recorded. */
  digest?: string;
  /** The stored output's durable id. */
  id: string;
  /** The stored output's kind, verbatim durable vocabulary (e.g. `"tool_output"`; snake_case per the SS1.6 casing exemption). */
  kind: string;
  /** Media type, when recorded. */
  mediaType?: string;
  /** Stored path, when recorded. */
  path?: string;
  /** The stored output's URI. */
  uri: string;
}

/** Whether a stored output's bytes are servable (tdd SS4.5.5). Open — durable runtime vocabulary may grow additively. */
export type OutputRefAvailability = "available" | "missing" | "unsupported" | "accessFailed" | (string & {});

/** 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`. */
export interface PatchSummary {
  /** Total `+`-prefixed line count across all files' hunks. */
  added: number;
  /** File entries in the stored patch document. */
  files: number;
  /** Total `-`-prefixed line count across all files' hunks. */
  removed: number;
}

/** A pending approval in the snapshot: the SS2.5.2 pointer shape plus the gated `itemId` when one exists (tdd SS4.9.1). */
export interface PendingApprovalPointer {
  /** The pending approval's id. */
  approvalId: string;
  /** The parked item, when one exists. */
  itemId?: string;
  /** The cursor the approval opened at. */
  viewCursor: string;
}

/** The `pendingRequests` discriminator (tdd SS2.5.2). Open enum, v1 values `approval` and `userInput`. */
export type PendingRequestKind = "approval" | "userInput" | (string & {});

/** 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).  The protocol defines two kind-discriminated entry shapes (`{kind: "approval", approvalId, viewCursor}` / `{kind: "userInput", userInputId, viewCursor}`). This type is one flat object with both ids optional, as for `ApprovalSubject` and `TurnInputPart`, because the v1 model names no object-variant union; the serialized JSON is the same, but the published schema also accepts `{"kind":"approval","userInputId":…}` and an entry carrying no id at all. Unlike `TurnInputPart.type`, `kind` here is an OPEN enum. */
export interface PendingRequestPointer {
  /** Present on an `approval` entry. */
  approvalId?: string;
  /** The discriminator; v1 values `approval` and `userInput`. */
  kind: PendingRequestKind;
  /** Present on a `userInput` entry. */
  userInputId?: string;
  /** The cursor the request opened at. */
  viewCursor: string;
}

/** A pending user-input prompt in the snapshot (tdd SS4.9.1, SS5.10). */
export interface PendingUserInputPointer {
  /** The parked item, when one exists. */
  itemId?: string;
  /** The pending prompt's id. */
  userInputId: string;
  /** The cursor the prompt opened at. */
  viewCursor: string;
}

/** The server runtime's platform family; may differ from the client's. Closed: the protocol fixes the value set, so widening it is a deliberate, gate-visible protocol change rather than a silent addition (a later `Closed`→`Open` flip is itself additive). */
export type PlatformFamily = "unix" | "windows";

/** The server's operating system (SS1.4.1). Closed, for the same reason as [`PlatformFamily`]. */
export type PlatformOs = "macos" | "linux" | "windows";

/** One installed plugin record (tdd SS3.26.2). */
export interface PluginCatalogEntry {
  /** The record's own install switch; non-enabled rows are included as `false`, never dropped. */
  enabled: boolean;
  /** The installed plugin's identifier. */
  id: string;
  /** The installed record's source provenance (ADR 33398 D7 item 3). */
  source: PluginSource;
  /** The installed version. */
  version: string;
}

/** `plugin/changed` params (tdd SS3.29.5): an install landed; clients re-issue `plugin/list` (plus `hook/list` and `skill/list`). */
export interface PluginChangedParams {
  /** The installed record's own switch. */
  enabled: boolean;
  /** The installed record's identifier. */
  id: string;
  /** The acting session. */
  sessionId: string;
  /** The installed-list provenance vocabulary (tdd SS3.26.2). */
  source: PluginSource;
  /** The installed record's version. */
  version: string;
}

/** The `plugin/install` local-path arm (tdd SS3.29.1). */
export interface PluginInstallLocalPathTarget {
  /** The host folder to install from; absolute recommended, relative resolves against the host working directory. */
  path: string;
  /** The install lane; omitted means `default`. */
  scope?: PluginInstallScope;
}

/** The `plugin/install` marketplace arm (tdd SS3.29.1). */
export interface PluginInstallMarketplaceTarget {
  /** The configured marketplace name. */
  marketplace: string;
  /** The plugin name within the store. */
  name: string;
}

/** `plugin/install` params (tdd SS3.29.1). Per-session params plus a client-generated `commandId` (UUIDv7) with the uniform SS3.1.1 idempotency contract. */
export interface PluginInstallParams {
  /** The client-generated idempotency key (UUIDv7). */
  commandId: string;
  /** The target session; its workspace resolves project scope. */
  sessionId: string;
  /** Exactly one install target arm. */
  target: PluginInstallTarget;
}

/** `plugin/install` result (tdd SS3.29.1): the SS3.1.2 ack envelope plus the installed receipt. */
export interface PluginInstallResult {
  /** The echoed idempotency key. */
  commandId: string;
  /** The installed record's own switch. */
  enabled: boolean;
  /** The installed record's identifier. */
  id: string;
  /** The installed-list provenance vocabulary (tdd SS3.26.2). */
  source: PluginSource;
  /** The ack status. */
  status: CommandStatus;
  /** The installed record's version. */
  version: string;
  /** The installer's advisory text when the install succeeded with a caveat; absent otherwise. */
  warning?: string;
}

/** The `plugin/install` local-path scope (tdd SS3.29.1). Closed: an unknown scope is `-32602 invalidParams`. */
export type PluginInstallScope = "default" | "user" | "project";

/** The one structured install target (tdd SS3.29.1): a flat object with two optional arms, exactly one present — the `TurnInputPart` convention, since the v1 schema model names no object-variant union. Both arms or neither is `-32602 invalidParams`. */
export interface PluginInstallTarget {
  /** The local-path arm: install from a host folder. */
  localPath?: PluginInstallLocalPathTarget;
  /** The marketplace arm: install a named plugin from a store. */
  marketplace?: PluginInstallMarketplaceTarget;
}

/** `plugin/list` params (tdd SS3.26.2). Per-session params; rows are the installed plugin records. */
export interface PluginListParams {
  /** The target session. */
  sessionId: string;
}

/** `plugin/list` result (tdd SS3.26.2): one row per installed plugin record; the spec promises the set, not an order. */
export interface PluginListResult {
  /** The installed plugin rows. */
  plugins: PluginCatalogEntry[];
}

/** `plugin/marketplaceAdd` params (tdd SS3.29.2). Per-session params plus a client-generated `commandId` (UUIDv7). */
export interface PluginMarketplaceAddParams {
  /** The client-generated idempotency key (UUIDv7). */
  commandId: string;
  /** The marketplace name to configure. */
  name: string;
  /** The target session. */
  sessionId: string;
  /** The app's source vocabulary: `owner/repo`, a git URL, a `file://` URL, or a local path. */
  source: string;
}

/** What happened to a marketplace (tdd SS3.29.6). Closed: an unknown change is a contract violation, never tolerated. */
export type PluginMarketplaceChange = "added" | "updated" | "removed";

/** `plugin/marketplaceChanged` params (tdd SS3.29.6): a marketplace was added, updated, or removed. */
export interface PluginMarketplaceChangedParams {
  /** What happened. */
  change: PluginMarketplaceChange;
  /** The marketplace name. */
  name: string;
  /** The stored record's plugin count; omitted on `removed`, never fabricated. */
  pluginCount?: number;
  /** The acting session. */
  sessionId: string;
  /** The stored record's skipped count; omitted on `removed`, never fabricated. */
  skippedCount?: number;
}

/** The stored marketplace record both add and update answer (tdd SS3.29.2, SS3.29.3): the SS3.1.2 ack envelope plus the record. */
export interface PluginMarketplaceRecordResult {
  /** The echoed idempotency key. */
  commandId: string;
  /** The configured marketplace name. */
  name: string;
  /** The plugins the store now offers. */
  pluginCount: number;
  /** Entries the store could not offer, with the reason each was skipped; empty when nothing was skipped. */
  skipped: PluginMarketplaceSkippedEntry[];
  /** The normalized stored source. */
  source: PluginMarketplaceSourceShape;
  /** The ack status. */
  status: CommandStatus;
}

/** `plugin/marketplaceRemove` params (tdd SS3.29.4). Per-session params plus a client-generated `commandId` (UUIDv7). */
export interface PluginMarketplaceRemoveParams {
  /** The client-generated idempotency key (UUIDv7). */
  commandId: string;
  /** The marketplace name to remove. */
  name: string;
  /** The target session. */
  sessionId: string;
}

/** `plugin/marketplaceRemove` result (tdd SS3.29.4): the SS3.1.2 ack envelope plus the removed name. */
export interface PluginMarketplaceRemoveResult {
  /** The echoed idempotency key. */
  commandId: string;
  /** The removed marketplace name. */
  name: string;
  /** The ack status. */
  status: CommandStatus;
}

/** One skipped marketplace entry (tdd SS3.29.2). */
export interface PluginMarketplaceSkippedEntry {
  /** The skipped plugin. */
  plugin: string;
  /** Why it was skipped. */
  reason: string;
}

/** The normalized stored marketplace source (tdd SS3.29.2). */
export interface PluginMarketplaceSourceShape {
  /** The stored source kind. */
  kind: string;
  /** The stored source path. */
  path: string;
}

/** `plugin/marketplaceUpdate` params (tdd SS3.29.3). Per-session params plus a client-generated `commandId` (UUIDv7). */
export interface PluginMarketplaceUpdateParams {
  /** The client-generated idempotency key (UUIDv7). */
  commandId: string;
  /** The marketplace name to refresh. */
  name: string;
  /** The target session. */
  sessionId: string;
}

/** A plugin row's source provenance (tdd SS3.26.2, ADR 33398 D7 item 3): camelCase of `PluginSourceProvenance`. Open (server-produced result vocabulary, the #22785 enum-openness rule): a future provenance is additive. */
export type PluginSource = "curated" | "marketplaceUserAdded" | "foreignImport" | "nativeLocal" | (string & {});

/** Typed quota-exhaustion detail (tdd SS4.5.1, ADR 50047 D2): the limit kind plus the provider's reset instant. */
export interface QuotaDetail {
  /** Which quota was exhausted (open enum; unknown values fall back). */
  limitKind: LimitKind;
  /** Epoch milliseconds at which the provider says usage resets. */
  resetsAtMs: number;
}

/** 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". */
export type ReasoningEffort = "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`). */
export type ReasoningEffortChangeSource = "user" | "default" | "policy" | (string & {});

/** 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. */
export interface ReasoningEffortState {
  /** The standing default tier — the closed SS3.2 vocabulary, spelled identically to `turn/start.reasoningEffort`. */
  reasoningEffort: ReasoningEffort;
  /** Which actor class set the default. */
  source: ReasoningEffortChangeSource;
}

/** `recap/cancel` params (tdd SS3.28.5): the session plus the cancel's own retry id. No target — one in-flight slot per session makes the target unambiguous. */
export interface RecapCancelParams {
  /** The cancel's own retry id (required, SS3.1.1). */
  commandId: string;
  /** The session whose in-flight recap to cancel (required). */
  sessionId: string;
}

/** `recap/cancel` result (tdd SS3.28.5): admission only. In flight → the recap settles `cancelled`; idle → accepted no-op. */
export interface RecapCancelResult {
  /** The cancel's id, echoed. */
  commandId: string;
  /** Always `accepted` on this path. */
  status: CommandStatus;
}

/** `recap/completed` params (tdd SS3.28.2): the settlement, delivered to the requesting connection outside the view stream — no `viewCursor`, no `sourceRange`. `text` is required on `completed` (plus optional `title`, untrusted model output — clients MUST sanitize per spec 442 INV-015); `reason` is required on `failed`; neither rides `cancelled`/`timedOut`. The struct marks the conditional members optional; the SS prose pins the per-outcome rule, the `turn/completed` usage/error convention. */
export interface RecapCompletedParams {
  /** The request's id — the correlation key. */
  commandId: string;
  /** How the request settled. */
  outcome: RecapOutcome;
  /** Why the side-call failed (on `failed`). */
  reason?: RecapFailureReason;
  /** The recapped session. */
  sessionId: string;
  /** The recap text verbatim (on `completed`). */
  text?: string;
  /** The model-produced short title (on `completed`, when produced). */
  title?: string;
}

/** `recap/completed` failure reason (tdd SS3.28.2/SS3.28.8): post-ack failures fold to the single initial value. **Open**: later splits stay additive (#22785 E2). */
export type RecapFailureReason = "providerFailed" | (string & {});

/** `recap/completed` outcome: the terminal vocabulary, in camelCase. **Open**: a server-produced result vocabulary. */
export type RecapOutcome = "completed" | "failed" | "cancelled" | "timedOut" | (string & {});

/** `recap/request` params (tdd SS3.28.1): the session plus the client-minted UUIDv7 retry id. No other param; unknown fields are `invalidParams`. */
export interface RecapRequestParams {
  /** The client-minted retry id (required, SS3.1.1). */
  commandId: string;
  /** The session to recap (required). */
  sessionId: string;
}

/** `recap/request` result (tdd SS3.28.1): admission only — the ack is never the recap. */
export interface RecapRequestResult {
  /** The request's id, echoed. */
  commandId: string;
  /** Always `accepted` on this path. */
  status: CommandStatus;
}

/** One end of a [`SourceRange`]: a record's event id and its sequence number within the stream (tdd SS4.2). */
export interface RecordPosition {
  /** The record's event id. */
  id: string;
  /** The record's sequence number within its stream. */
  sequence: number;
}

/** Proven effective-choice provenance, independently of input presence. */
export type RecoveryEffectiveSource = "request" | "retained" | "legacyOmission" | "hostPolicy" | "unknown" | (string & {});

/** A requested construction choice; omission is distinct from explicit OFF. */
export type RecoveryMode = "on" | "off";

/** One coherent producer snapshot; all members are required and non-null. */
export interface RecoveryObservation {
  constructionId: string;
  effectiveMode: RecoveryObservedMode;
  effectiveSource: RecoveryEffectiveSource;
  qualification: RecoveryQualification;
  requestedMode: RecoveryObservedMode;
  sessionId: string;
}

/** A proven mode or unknown; future strings cannot establish OFF. */
export type RecoveryObservedMode = "on" | "off" | "unknown" | (string & {});

/** This construction's assessment, never an operation acceptance receipt. */
export type RecoveryQualification = "qualified" | "unavailable" | "notRequired" | "unknown" | (string & {});

/** A request frame, either direction (SS1.2 §2.1). */
export interface Request {
  /** Client-chosen id, unique among that client's in-flight requests. */
  id: RequestId;
  /** The literal `"2.0"`. */
  jsonrpc: JsonRpcVersion;
  /** Slash-namespaced camelCase method name. */
  method: string;
  /** Method-specific parameters; omitted entirely when empty, never `null`. */
  params?: Record<string, unknown>;
  /** W3C trace passthrough (SS1.8); requests only. */
  trace?: TraceContext;
}

/** A request id (SS1.3): client-chosen string or integer. `1` and `"1"` do not compare equal; each direction owns its own id space. */
export type RequestId = number | string;

/** 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. */
export interface RequestReceipt {
}

/** A `turn/retracted` settlement outcome (tdd SS4.5.1, ADR 50074 D1). Open enum (D-033): decode is tolerant — a value outside the list reads as `Accepted` (the event's historical meaning — pre-feature hosts emit it only for accepted retracts), never fails. The bundle keeps enumerating the known values for codegen and docs. */
export type RetractOutcome = "accepted" | "declined" | (string & {});

/** Whether this host can enforce the sandbox (ADR 50064-startup-report-sandbox-availability D2/D4). A property of the host process, probed once at construction and identical for every session and every connection it serves — never requested, granted, or negotiated, which is why it is not a capability. Open: a future enforcement posture arrives as a new value, read by older clients as unknown. */
export type SandboxAvailability = "available" | "unavailable" | (string & {});

/** Why sandbox enforcement is impossible on this host. Sent only when [`SandboxAvailability`] is `unavailable`; a client MUST NOT infer a reason when none is sent. Open: a future reason arrives as a new value, read by older clients as unknown. */
export type SandboxUnavailableReason = "userNamespacesDenied" | "bubblewrapUnavailable" | (string & {});

/** 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). */
export interface SchemaInfo {
  /** `sha256:<64 lower hex>` content hash of this server binary's stable-surface bundle (INV-003). A mismatch is a warning condition, not an error (SS1.4.1). */
  fingerprint: string;
  /** Envelope schema version; `1` in v1, expected to stay `1` for a long time (SS1.4.1). */
  version: number;
}

/** Server identification inside [`InitializeResult`]. */
export interface ServerInfo {
  /** Server name. */
  name: string;
  /** Server version string. */
  version: string;
}

/** The session object every lifecycle method returns or lists (tdd SS2.4).  Additive-optional evolution applies: clients must ignore unknown fields. */
export interface Session {
  /** The `turnId` of the current foreground turn when `status` is `running`, and `null` when the session is idle (tdd SS2.4).  **Required-nullable.** Every served `Session` carries the member: `null` when the session is idle or not loaded, the turn id when it is running. An optional-absent shape would publish it as plain `string` and reject every idle `Session` frame the host sends. */
  activeTurnId: string | null;
  /** The folded effective approval mode. **Additive-optional**: a Session object that omits it means the host has not folded a mode, which is why the index-derived `session/list` entry may legitimately omit it (tdd SS2.4, SS5.12). */
  approvalMode?: EffectiveApprovalModeState;
  /** Attention flags (tdd SS2.4, ADR 31983 D3). **Additive-optional**, present only when at least one flag is set; absence is a NON-assertion (nothing pending, or the loaded session's pending source declined to answer). Loaded sessions only: a `notLoaded` row omits it even while its durable pending set is non-empty. */
  attention?: AttentionFlag[];
  /** Derived workspace branch (tdd SS2.14.1, #27598) — the index's last derived value; the live-change signal stays `session/branchChanged` (SS4.6.4). **Additive-optional**, omitted when underivable. */
  branch?: string;
  /** RFC3339. For a fork this is the fork session id's UUIDv7 mint instant (tdd SS2.4). */
  createdAt: string;
  /** The handshake `ClientInfo` recorded when the session was opened (FR-003), echoed verbatim — provenance, never an interpretation, and never a visibility gate (INV-005). **Additive-optional**; absence has four indistinguishable causes (INV-004): an in-process open; a pre-#23124 record; a half stamp where only one of name/version was recorded (FM-005) and `ClientInfo` requires both; and a session with no admitting handshake of its own — a fork child or a subagent — which never carries a stamp to begin with. */
  createdByClient?: ClientInfo;
  /** Derived first-user-prompt preview (tdd SS2.14.1, #27598). **Additive-optional**, omitted when underivable. */
  firstUserPrompt?: string;
  /** `null` for root sessions; fork provenance otherwise (tdd SS2.4). */
  forkedFrom: ForkProvenance | null;
  /** The served generated short title (tdd SS2.4/SS2.14.1, #50048; ADR 50048-generated-name D1). **Additive-optional**, **fold-only**: the snapshot fold derives the latest retained generated pair's short title from the log; `session/list` rows never carry it. Omitted when no pair was ever published — absent reads as unpublished, never fabricated, never inferred from the name text. `name` stays the canonical name it always was. */
  generatedName?: string;
  /** What kind of session this is (spec 42713 FR-001, ADR 42713 D1/D4). **Open enum**, v1 values `"root"` and `"subagent"`; a client treats an unknown value as an unknown-but-present kind and renders it, never rejecting the row. **Additive-optional**: absence asserts nothing — the host could not determine the home shape (FM-001), or the value is not yet available to serve (FM-003). */
  kind?: SessionKind;
  /** Content-activity recency, RFC3339 (tdd SS2.4, ADR 31983 D5). **Additive-optional**: omitted when no content record exists. Never advanced by lifecycle bookkeeping (the resume marker, re-stamps) or a fork's copied seed-replay records, and never precedes `createdAt`. */
  lastActivityAt?: string;
  /** The winning metadata fold's model; `null` when that record omits it. */
  modelId: string | null;
  /** The durable allocated session name (tdd SS2.4/SS2.14.1, #27598; ADR 27598 D2/D4). **Additive-optional**: present when the serving path holds an allocated name, omitted otherwise — absent is never fabricated. Authoritative and renameable via `session/rename`. */
  name?: string;
  /** How the served `name` was set (tdd SS2.4/SS2.14.1, #50048; ADR 50048 D1/D2). **Additive-optional**, **fold-only**: the snapshot fold (`session/read`, the resume/start/fork-ack snapshot) derives and carries it from the log; `session/list` rows never carry it. Absent — and any value the client does not recognize — reads as unknown, never fabricated. */
  nameOrigin?: SessionNameOrigin;
  /** The containing session's id when `kind` is `"subagent"` (FR-002, INV-002) — the id of the TOP-LEVEL session whose home holds this child, which is **not necessarily the session that spawned it**: native-child homes are physical siblings under the outer session's `subagent/` directory, so a subagent spawned by another subagent resolves to the outer session, not to its spawner. A client building a tree from this field gets one level, not a chain. Flat rather than nested: there is exactly one fact to carry, unlike `forkedFrom`'s four-field `ForkProvenance`. **Additive-optional**; a root carries none. */
  parentSessionId?: string;
  /** Absolute path of the session's durable log; non-nullable. Under the ephemeral session profile it is the **empty string**, meaning "no durable log exists" (tdd SS2.13.2) — the one value a client must not hand to a filesystem call. */
  path: string;
  /** The winning metadata fold's provider; `null` when that record omits it. */
  providerId: string | null;
  /** The session identity. */
  sessionId: string;
  /** `null` for root sessions and forks; side provenance otherwise (tdd SS2.4/SS2.5.7; ADR 45435 D2). A session carries at most one of `forkedFrom` and `sideFrom`. */
  sideFrom?: SideProvenance | null;
  /** Load state as this host knows it; `session/list` reports `notLoaded` for sessions loaded by *other* hosts (tdd SS2.4). */
  status: SessionStatus;
  /** Derived display title (tdd SS2.14.1, #27598): a heuristic that may evolve — its carriage, not its derivation, is the contract. **Additive-optional**, omitted when underivable. */
  title?: string;
  /** Completed-turn count from the session view fold (tdd SS2.4). */
  turnCount: number;
  /** RFC3339; never precedes `createdAt` (tdd SS2.4). */
  updatedAt: string;
  /** The winning metadata fold's workspace root; `null` when that record omits it — absent is never fabricated (tdd SS2.4). */
  workspaceRoot: string | null;
}

/** `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. */
export interface SessionApprovalModeChangedParams {
  /** The requesting client's `clientInfo.name` (tdd SS1.4.1), recorded on the audit fact. */
  clientName: string;
  /** The command that changed it. */
  commandId: string;
  /** The mode now in effect. */
  mode: ApprovalMode;
  /** The owning session. */
  sessionId: string;
  /** How the mode took effect. */
  source: ApprovalModeSource;
  /** The durable records this event folded from. */
  sourceRange: SourceRange;
  /** Opaque, strictly monotonic view cursor (tdd SS4.1). */
  viewCursor: string;
}

/** `session/branchChanged` params (tdd SS4.6.4): a durable workspace-branch observation landed. */
export interface SessionBranchChangedParams {
  /** The observed branch; `null` on a detached-HEAD observation — a fact, not "unchanged" (tdd SS4.6.4). */
  branch: string | null;
  /** The owning session. */
  sessionId: string;
  /** The durable records this event folded from. */
  sourceRange: SourceRange;
  /** The detected version-control system; absent when no repository was detected. */
  vcs?: Vcs;
  /** Opaque, strictly monotonic view cursor (tdd SS4.1). */
  viewCursor: string;
  /** The observed workspace root. */
  workspaceRoot: string;
}

/** `session/closed` params (tdd SS2.6.2; enrolled by #33065): a loaded session was unloaded from this host, broadcast to every initialized connection. After it, the session is `notLoaded`; the log remains on disk and `session/resume` reloads it. A crash emits nothing — only the orderly unload paths do (idle unload, host shutdown and a released `session/leave`), and each writes the durable `SessionEnd` record first. */
export interface SessionClosedParams {
  /** Which orderly unload path fired. */
  reason: SessionClosedReason;
  /** The unloaded session. */
  sessionId: string;
  /** The final view head; a client that stores it can later `session/resume {cursor}` and receive exactly the (empty) suffix. An **opaque** view cursor: clients relay it, never parse it (tdd SS4.1).  **Required-nullable**: the producers always write the member and write `null` when the final fold failed at unload (`session/idle.rs`, `serve/shutdown.rs`; PR #16779 review) — the host defines no cursor values of its own and never invents one, and the subscriber still learns the session closed. */
  viewCursor: string | null;
}

/** The SS2.6.2 closed-reason vocabulary. Server-produced and published OPEN by owner ruling — the #33065 menu-B pick (PR #33201 comment 5638727249, recorded in the enrollment decision record), which settles that this notification reason enum publishes open rather than resting on E2's result-vocabulary rule by analogy. A crash is deliberately not a reason, because a crash emits no notification at all. */
export type SessionClosedReason = "idle" | "hostShutdown" | "leave" | (string & {});

/** `session/compact` params (tdd SS3.7): manually compact the session's conversation context — the `/compact` gesture. Compaction runs asynchronously; the ack is admission only. */
export interface SessionCompactParams {
  /** The SS3.1.1 idempotency handle (UUIDv7). */
  commandId: string;
  /** The target session. */
  sessionId: string;
  /** The run whose context to compact. Omit and the server resolves the session's current/latest run; a session with no resolvable run rejects with `commandRejected` reason `missing_run` (tdd SS3.7). Any syntactically valid UUID: a turn from an older session may carry a v4 or v5 id. A malformed id is `invalidParams`. */
  turnId?: string;
}

/** `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. */
export interface SessionCompactResult {
  /** Echoes the client's id. */
  commandId: string;
  /** Why the command was a noop, e.g. `no_compactable_history`. Present on a `noop` status (tdd SS3.7). */
  reason?: string;
  /** Admission status, or `noop`. */
  status: CompactStatus;
}

/** The open configuration extension object shared by `session/start` and `session/resume` (ADR 32760 D1).  Unknown keys are ignored on the wire, never rejected: the live decoder tolerates them, and no exported bundle carries `additionalProperties: false`. The Rust typed model's `deny_unknown_fields` is internal and never exported — the 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. */
export interface SessionConfig {
  /** Native MCP servers added only to this session runtime. */
  mcpServers?: Record<string, SessionMcpServerConfig>;
}

/** `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). */
export interface SessionContextUsageParams {
  /** Server-computed pressure level over the basis thresholds. */
  pressure: ContextPressureLevel;
  /** The owning session. */
  sessionId: string;
  /** The durable records this event folded from. */
  sourceRange: SourceRange;
  /** Counted-once prompt tokens (#8803) plus output tokens of the driving record, saturating — the honest occupancy floor. */
  usedTokens: number;
  /** Opaque, strictly monotonic view cursor (tdd SS4.1). */
  viewCursor: string;
  /** The effective context-window size from the host's pressure basis; absent when the basis has no limit — the limit part is omitted, never invented (tdd SS4.6.6). */
  windowTokens?: number;
}

/** 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. */
export type SessionDurability = "durable" | "ephemeral" | (string & {});

/** `session/fork` params (tdd SS2.5.3). */
export interface SessionForkParams {
  /** The SS2.5 idempotency handle (UUIDv7). */
  commandId: string;
  /** Copy history through a completed turn, inclusive. Omitted means "all completed turns" (tdd SS2.5.3). */
  cutPoint?: ForkCutPoint;
  /** Skip inline history in the result and page it later — same as `session/resume` (tdd SS2.5.3). */
  excludeItems?: boolean;
  /** The source session. */
  sessionId: string;
}

/** `session/fork` result (tdd SS2.5.3): the `session/resume` envelope for the **new** session, whose `session.forkedFrom` carries the provenance. */
export interface SessionForkResult {
  /** The served history. */
  history: SessionHistory;
  /** The late-joiner pointer set. */
  pendingRequests: PendingRequestPointer[];
  /** The new fork session, carrying `forkedFrom` provenance. */
  session: Session;
  /** The new session's view head. */
  viewCursor: string;
}

/** `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. */
export interface SessionGoalChangedParams {
  /** The full current goal block, or `null` to clear. */
  goal: Goal | null;
  /** The owning session. */
  sessionId: string;
  /** The durable records this event folded from. */
  sourceRange: SourceRange;
  /** Opaque, strictly monotonic view cursor (tdd SS4.1). */
  viewCursor: string;
}

/** The `history` envelope shared by `session/resume`, `session/fork`, and `session/read` (tdd SS2.5.2). */
export interface SessionHistory {
  /** The checkpoint-prune boundary (spec 13929 amendment FR-50042-1): rows for served items at-or-before `through_item_id` in served order predate the selected checkpoint. Additive-optional; absence is a non-assertion (ADR 50042 D6). */
  checkpointBoundary?: CheckpointBoundary;
  /** The full folded item array when `mode` is `inline`; `null` otherwise. */
  items: Item[] | null;
  /** What was actually served — never what was asked for (tdd SS2.5.2). */
  mode: HistoryMode;
  /** Why no history was served — sent exactly when `mode` is `"none"` (tdd SS2.5.2; D-050, spec 208 INV-19734-1). */
  noneReason?: HistoryNoneReason;
  /** The folded view state when `mode` is `snapshot` or `anchoredSnapshot`; `null` otherwise. */
  snapshot: ViewSnapshot | null;
}

/** What kind of session this is (spec 42713 FR-001/FR-005, ADR 42713 D1/D4).  **Open**: a new kind is additive evolution, and a client MUST render an unknown value as an unknown-but-present kind rather than rejecting the row. Both v1 values are terms the tree already uses — the child log directory is `subagent` and `ItemKind` already carries a `subagent` variant — so no new vocabulary is minted. */
export type SessionKind = "root" | "subagent" | (string & {});

/** Params of the protected, non-view leave terminal notification. */
export interface SessionLeaveCompletedParams {
  /** The leave command's id, matching the `session/leave` request. */
  commandId: string;
  /** How the leave ended: `released` or `failed`. The set is open, so newer hosts may add outcomes. */
  outcome: SessionLeaveOutcome;
  /** Why the leave failed. Present when `outcome` is `failed`. */
  reason?: SessionLeaveFailureReason;
  /** The session the leave was for. */
  sessionId: string;
  /** The session's view cursor at release: everything up to it was folded before the host let go. Present when `outcome` is `released`. */
  viewCursor?: string;
}

/** Current producer failure reasons for `session/leaveCompleted`; receiver-open for additive future reasons. */
export type SessionLeaveFailureReason = "timeout" | "responseUndelivered" | "persistenceFailed" | "runtimeFailed" | "abandoned" | (string & {});

/** Current producer outcomes for `session/leaveCompleted`; receiver-open. */
export type SessionLeaveOutcome = "released" | "failed" | (string & {});

/** `session/leave` params (tdd SS2.15, ADR 31741 D2/D8). */
export interface SessionLeaveParams {
  /** Client-minted UUIDv7 command identity. */
  commandId: string;
  /** The exact loaded session whose ownership is to be released. */
  sessionId: string;
  /** Explicitly cancel unfinished work before leaving. Omitted is `false`. */
  stop?: boolean;
}

/** The admission-only `session/leave` result. */
export interface SessionLeaveResult {
  /** The leave command's id. */
  commandId: string;
  /** The admission status, `accepted` once the leave is admitted. The final result arrives later as `session/leaveCompleted`. Sending the same leave command again returns `accepted` and re-pushes the recorded result if there is one, from the host that ran the leave (for as long as it runs, even after the release) or from a host that has the session loaded (after a host crash, `abandoned` among them). Any other host treats it as a fresh leave: a durable host that has not loaded the session refuses it with `sessionNotLoaded` until it is resumed there. */
  status: CommandAckStatus;
}

/** Exact branch selection (#42035 FR-42035-2). */
export interface SessionListBranchFilter {
  /** 1–32 nonempty branch names, each 1–256 UTF-8 bytes, counted before deduplication; `null` selects sessions with no branch. */
  anyOf: (string | null)[];
}

/** `session/listChanged` params (#33084, ADR 33084 D3): one changed row of the `session/list` shape — the full SS2.4 Session object as the answering host's list face serves it at emission (the ADR 29243 live-overlaid row), a replace, never a delta. Emitted only on connections that negotiated the `sessionListStream` capability at `initialize` (ADR 33084 D2); row birth stays on `session/started`, unload pairs with `session/closed`. */
export interface SessionListChangedParams {
  /** The served list row for the changed session. */
  session: Session;
}

/** The `session/list` filter (#42035, spec 207 FR-42035-2..5). Members are ANDed with each other and with the top-level `workspaceRoot` and `updatedAfter`; values inside each `anyOf` are ORed. The canonical form the server echoes deduplicates and sorts every set, spells session IDs as canonical UUIDs, lowercases text terms, and orders `text.fields` `name` then `title`. */
export interface SessionListFilter {
  /** Only sessions whose branch is one of these. */
  branch?: SessionListBranchFilter;
  /** Only sessions whose ID is one of these. */
  sessionId?: SessionListSessionIdFilter;
  /** Only sessions whose served name or title matches these token prefixes. */
  text?: SessionListTextFilter;
}

/** `session/list` params (tdd SS2.5.4). Read-only; never touches leases. */
export interface SessionListParams {
  /** Opaque page cursor from a prior result. Page cursors are a distinct opaque-string family from view cursors and stream cursors, valid only for re-issuing the same listing (tdd SS2.5.4). Omitted and explicit `null` both mean "first page" (#23468). */
  cursor?: string | null;
  /** Optional structured selection applied inside the bounded index query before paging (#42035, spec 207 FR-42035-1). Present — including `{}` — makes a supporting server echo its canonical form as `appliedFilter`; omitted keeps the pre-#42035 behavior. */
  filter?: SessionListFilter;
  /** Page size; default 50, max 200 — the schema publishes the cap. Maximum 200. */
  limit?: number;
  /** Only sessions with log activity after this RFC3339 instant. */
  updatedAfter?: string;
  /** Only sessions whose metadata workspace root equals this path. */
  workspaceRoot?: string;
}

/** `session/list` result (tdd SS2.5.4). Ordering is `updatedAt` descending. */
export interface SessionListResult {
  /** The canonical filter the server applied, present exactly when the request carried `filter` (#42035, spec 207 FR-42035-1). The probe is per-predicate PRESENCE (ADR 42035 D6): a client that requires filtering checks that every predicate it sent comes back as a member here, and treats a missing member as unsupported. Value equality is the wrong test — canonicalization trims, lowercases, NFC-normalizes, dedupes and sorts, so the echoed values often differ from the sent ones on a correctly filtered page. */
  appliedFilter?: SessionListFilter;
  /** The next page's cursor; `null` on the last page. */
  nextCursor: string | null;
  /** The page of stored sessions. */
  sessions: Session[];
}

/** Exact session-ID selection (#42035 FR-42035-2). */
export interface SessionListSessionIdFilter {
  /** 1–200 session UUIDs, counted before deduplication. */
  anyOf: string[];
}

/** A served session field `session/list` text search reads (#42035 FR-42035-3). The client selects it, so the set is closed. */
export type SessionListTextField = "name" | "title";

/** Name/title token-prefix search (#42035 FR-42035-3/FR-42035-4). Each term is trimmed, lowercased with ordinary Unicode lowercase, then NFC- normalized, and matches the beginning of an alphanumeric token, accent-sensitively (`check` matches `Checkout`; `eck` does not). NFC means a decomposed and a precomposed spelling of one term are the same term, and the echo returns the composed form. Matching never reorders rows. */
export interface SessionListTextFilter {
  /** Every term must match at least one selected field. */
  allOf?: string[];
  /** At least one term must match a selected field. `allOf` plus `anyOf` carry 1–16 terms in total, each 1–128 UTF-8 bytes in its canonical form (trimmed, lowercased, NFC) — the bytes `appliedFilter` echoes. Lowercasing and NFC can both lengthen a term, so a term inside the bound raw may still exceed it canonically. */
  anyOf?: string[];
  /** The 1–2 unique served fields searched. */
  fields: SessionListTextField[];
}

/** 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. */
export type SessionMcpServerConfig = { /** Ordered child arguments. */ args?: string[]; /** Executable name or path. Configuration diagnostics never echo it. */ command: string; /** Explicit child environment additions. */ env?: Record<string, string>; /** Stdio framing mode; defaults to automatic detection. */ framing?: SessionMcpStdioFraming; /** Required/optional startup posture; defaults to required. */ mode?: SessionMcpServerMode; transport: "stdio"; } | { /** Explicit request headers. */ headers?: Record<string, string>; /** Required/optional startup posture; defaults to required. */ mode?: SessionMcpServerMode; transport: "streamableHttp"; /** HTTP(S) endpoint. Configuration diagnostics never echo it. */ url: string; };

/** Startup failure posture for a session MCP server. */
export type SessionMcpServerMode = "required" | "optional";

/** Stdio framing choices exposed by session MCP configuration. */
export type SessionMcpStdioFraming = "auto" | "contentLength" | "lineDelimitedJson";

/** `session/modelChanged` params (tdd SS4.6.1): a durable model-selection record landed (tdd SS3.8). */
export interface SessionModelChangedParams {
  /** The selected model. */
  modelId: string;
  /** The selected provider; `null` when the selection names none. */
  providerId: string | null;
  /** The owning session. */
  sessionId: string;
  /** What drove the selection. */
  source: ModelChangeSource;
  /** The durable records this event folded from. */
  sourceRange: SourceRange;
  /** Opaque, strictly monotonic view cursor (tdd SS4.1). */
  viewCursor: string;
}

/** `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. */
export interface SessionModelRouteUnservedParams {
  /** The command whose accepted swap installed the provider. */
  commandId: string;
  /** The provider id the swap installed. */
  installedProviderId: string;
  /** The standing (still bound, now unroutable) model. */
  modelId: string;
  /** The standing model's provider; `null` when the selection names none. */
  providerId: string | null;
  /** The owning session. */
  sessionId: string;
  /** The durable records this event folded from. */
  sourceRange: SourceRange;
  /** Opaque, strictly monotonic view cursor (tdd SS4.1). */
  viewCursor: string;
}

/** `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. */
export interface SessionNameChangedParams {
  /** The latest retained generated short title (tdd SS2.4/SS4.6.7, #50048; ADR 50048-generated-name D1). **Additive-optional**: carried at generated-pair publication and at settlement when a pair is already published; omitted when no pair was ever published — absent reads as unpublished, never fabricated. `name` stays canonical. */
  generatedName?: string;
  /** The new canonical name now in effect. */
  name: string;
  /** How the new name was set (tdd SS2.4/SS4.6.7, #50048; ADR 50048 D1/D2). **Additive-optional**: omitted when the emitting fold cannot prove an origin — absent reads as unknown, never fabricated. */
  nameOrigin?: SessionNameOrigin;
  /** The owning session. */
  sessionId: string;
  /** The durable records this event folded from. */
  sourceRange: SourceRange;
  /** Opaque, strictly monotonic view cursor (tdd SS4.1). */
  viewCursor: string;
}

/** How the served session name was set (tdd SS2.4/SS4.6.7, #50048; ADR 50048 D1). **Open enum** (`x-msp-openness: open`): v1 serves `automatic` and `custom`; a client MUST read absent — and any value it does not recognize — as unknown, never fabricated. Open: a future source such as conversation-generated names (#35260) adds a value here, so closed would make that a breaking change. */
export type SessionNameOrigin = "automatic" | "custom" | (string & {});

/** `session/read` params (tdd SS2.5.5): read one stored session **without attaching** — no writer lease, no load, no subscription, no `SessionResumed` record. */
export interface SessionReadParams {
  /** Metadata-only unless you ask: `false` carries the folded item history. Same name and polarity as `session/resume`/`session/fork`; only the default differs — here it is `true` (tdd SS2.5.5). */
  excludeItems?: boolean;
  /** The session to read. */
  sessionId: string;
}

/** `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. */
export interface SessionReadResult {
  /** Same member as `session/resume` (tdd SS2.5.5, ADR 50074 D2). */
  blockedPrompt?: BlockedPrompt;
  /** The served history. */
  history: SessionHistory;
  /** Same member as `session/resume` (tdd SS2.5.5, ADR 36635 D2). */
  lastTurn?: LastTurn;
  /** The same pointer shape as `session/resume`. Because `session/read` never subscribes this is a point-in-time log read only: no requests are re-issued after it (tdd SS2.5.5). */
  pendingRequests: PendingRequestPointer[];
  /** Current local construction only; never inferred from retained history. Absence establishes neither a choice nor supported recovery. */
  recoveryObservation?: RecoveryObservation;
  /** The session as folded point-in-time. */
  session: Session;
  /** The fold head at read time. */
  viewCursor: string;
}

/** `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). */
export interface SessionReasoningEffortChangedParams {
  /** The new session default: the same closed eight-string tier vocabulary as `turn/start`. */
  reasoningEffort: ReasoningEffort;
  /** The owning session. */
  sessionId: string;
  /** What drove the change. */
  source: ReasoningEffortChangeSource;
  /** The durable records this event folded from. */
  sourceRange: SourceRange;
  /** Opaque, strictly monotonic view cursor (tdd SS4.1). */
  viewCursor: string;
}

/** `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. */
export interface SessionRenameParams {
  /** The SS3.1.1 idempotency handle (UUIDv7). */
  commandId: string;
  /** The requested name; the runtime's normalization and validation apply. */
  name: string;
  /** The target session. */
  sessionId: string;
}

/** `session/rename` result (tdd SS2.14.2, #27598): `name` is the canonical (normalized) name the durable record settled. */
export interface SessionRenameResult {
  /** Echoes the client's id. */
  commandId: string;
  /** The settled canonical name. Omitted on the `RecoveryPending` arm, which answers `{commandId, status: "accepted"}` and delivers the name via `session/nameChanged` / `Session.name` (tdd SS2.14.2). */
  name?: string;
  /** Admission status. */
  status: CommandStatus;
}

/** `session/resume` params (tdd SS2.5.2). */
export interface SessionResumeParams {
  /** The SS2.5 idempotency handle (UUIDv7). A resume that loads a session writes a durable `SessionResumed` record. */
  commandId: string;
  /** The same open construction-time extension object as `session/start`. */
  config?: SessionConfig;
  /** A view cursor previously observed by this client — or an observed `summarizedThrough` compaction anchor. When it names an event the server still holds, the server returns only the suffix and `history.mode` is `none`. A cursor the server minted that names no event yet, such as the empty start cursor of a session that had no events, is treated as no cursor: the server serves what a resume without a cursor would. A cursor older than the earliest event the server still holds gets a snapshot, or `-32040` `viewTruncated` when none fits. A cursor this session's view never minted is refused with `-32011` `notFound`, reason `missingAnchor`, and a compaction anchor naming a boundary the server has pruned is refused with `-32042` `boundaryPruned`. Omitted and explicit `null` both mean "no cursor". */
  cursor?: string | null;
  /** Return only session metadata and live resume state; page history separately with `view/page`. Default `false` (tdd SS2.5.2). */
  excludeItems?: boolean;
  /** History mode preference, default `auto`. A PREFERENCE, not a budget override: when the requested mode does not fit the history budget the server downgrades it and `history.mode` reports what was actually served (tdd SS2.5.2). Ignored when `cursor` or `excludeItems` makes it moot. */
  history?: HistoryPreference;
  /** The launch permission-profile pick (amendment 42624 FR-42624-1, #50054): a profile id the host catalog already admits. Select, never create. Omitted means today's behavior: restore retained authority only, no override. The host restores first, then applies the pick in the same pre-marker step; a pick that fails admission refuses the resume `commandRejected` (-32030; `permission_profile_unknown` / `permission_profile_unavailable`) before any durable byte. Explicit `null` is invalid params (the same closed null-tolerant set as at start). */
  permissionProfile?: string;
  /** Cold-resume replacement choice; omission preserves the retained choice. A warm attach rejects a different or unestablished choice as invalidParams. Explicit null is invalid. */
  recoveryMode?: RecoveryMode;
  /** The session to load. */
  sessionId: string;
}

/** `session/resume` result (tdd SS2.5.2). */
export interface SessionResumeResult {
  /** The recallable blocked prompt's refill text (ADR 50074 D2). **Additive-optional**; absence means no blocked prompt to recall (an unblocked session, or a pre-feature host). Data only, never a rendered row: clients seed cold recall from it (C-p refills `text`) and MUST NOT display it as history. */
  blockedPrompt?: BlockedPrompt;
  /** The served history. */
  history: SessionHistory;
  /** How the last folded turn ended (tdd SS2.5.2, ADR 36635 D2). **Additive-optional**; absence is a non-assertion. */
  lastTurn?: LastTurn;
  /** The late-joiner pointer set; empty when nothing is pending. */
  pendingRequests: PendingRequestPointer[];
  /** The loaded session. */
  session: Session;
  /** The session view head; the connection is subscribed after it. A still-loaded session a prior `view/unsubscribe` detached is RE-ATTACHED by this resume (spec 208 FR-002a, #28920): live delivery resumes from this head. Explicit-cursor re-attach with `(after, head]` engine replay stays `view/subscribe` (SS4.7.1). */
  viewCursor: string;
}

/** `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. */
export interface SessionSetApprovalModeParams {
  /** The SS3.1.1 idempotency handle (UUIDv7). */
  commandId: string;
  /** The preconfigured mode to select. The requesting actor is recorded from the connection's `clientInfo.name` (tdd SS1.4.1). */
  mode: ApprovalMode;
  /** The target session. */
  sessionId: string;
}

/** `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. */
export interface SessionSetApprovalModeResult {
  /** Whether the change did anything. */
  applyOutcome: ApprovalModeApplyOutcome;
  /** Echoes the client's id. */
  commandId: string;
  /** The folded effective-mode projection — the same object the `Session` carries as `approvalMode` (tdd SS2.4, SS5.12). */
  effectiveMode: EffectiveApprovalModeState;
  /** Admission status. */
  status: CommandStatus;
}

/** `session/setModel` params (tdd SS3.8): the model-picker gesture. The selection is durable and applies to subsequent model calls. */
export interface SessionSetModelParams {
  /** The SS3.1.1 idempotency handle (UUIDv7). */
  commandId: string;
  /** The selection. */
  model: ModelSelection;
  /** The target session. */
  sessionId: string;
}

/** `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. */
export interface SessionSetModelResult {
  /** Echoes the client's id. */
  commandId: string;
  /** Admission status. */
  status: CommandStatus;
}

/** `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). */
export interface SessionSetReasoningEffortParams {
  /** The SS3.1.1 idempotency handle (UUIDv7). */
  commandId: string;
  /** The new session default: the closed eight-string tier vocabulary `turn/start` carries (SS3.2), spelled identically. Invalid tiers are invalid params. A default of `max` rides provider requests verbatim, never clamped (ADR 28621 D8, ADR 31131 D1). */
  reasoningEffort: ReasoningEffort;
  /** The target session. */
  sessionId: string;
}

/** `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. */
export interface SessionSetReasoningEffortResult {
  /** Echoes the client's id. */
  commandId: string;
  /** Admission status. */
  status: CommandStatus;
}

/** `session/sideChat` params (tdd SS2.5.7; ADR 45435 D2). */
export interface SessionSideChatParams {
  /** The SS2.5 idempotency handle (UUIDv7). */
  commandId: string;
  /** The source main session. */
  sessionId: string;
}

/** `session/sideChat` result (tdd SS2.5.7; ADR 45435 D2): the `session/resume` envelope for the **new** side session, whose `session.sideFrom` carries the provenance. The side opens empty. */
export interface SessionSideChatResult {
  /** The served history (inline; SS2.5.7's empty-items half is #49416 — inherited turns surface until the boundary-aware fold lands). */
  history: SessionHistory;
  /** The late-joiner pointer set. */
  pendingRequests: PendingRequestPointer[];
  /** The new side session, carrying `sideFrom` provenance. */
  session: Session;
  /** The new side session's view head. */
  viewCursor: string;
}

/** `session/start` params (tdd SS2.5.1). */
export interface SessionStartParams {
  /** The session's starting approval mode; server default when omitted or explicit `null` — both spellings select the default (#23468). Select, never create — the value names a mode the host's configuration already defines (tdd SS2.5.1, SS5.12). This is the only surface that declares a non-interactive run's policy (tdd SS5.11, D-008). */
  approvalMode?: ApprovalMode | null;
  /** The SS2.5 idempotency handle (UUIDv7). Required; the server never mints one. */
  commandId: string;
  /** Reserved for future per-session overrides; only its `mcpServers` member is admitted. */
  config?: SessionConfig;
  /** Initial model; server default when omitted. */
  modelId?: string;
  /** The new session's initial permission profile (amendment 42624 FR-42624-1, ADR 42197 D2): a profile id the host catalog already admits — the rows `permissionProfile/list` serves without `sessionId`. Select, never create. Omitted means today's behavior: the host's configured default under native admission, unchanged. An id the catalog does not carry, or one it serves unavailable, refuses the start `commandRejected` (-32030; `permission_profile_unknown` / `permission_profile_unavailable`) before any durable byte, and an ephemeral host refuses any id (`permission_profile_ephemeral_fixed`). `session/fork` does not admit the member; `session/resume` admits it as the launch pick (FR-42624-1, #50054). Explicit `null` is invalid params: the set of members that tolerate `null` is closed and excludes this one, exactly as it excludes `workspaceRoots`. */
  permissionProfile?: string;
  /** Initial provider routing; server default when omitted or explicit `null` — both spellings select the default (#23468). */
  providerId?: string | null;
  /** Recovery choice for this construction; omission keeps legacy behavior. Explicit null is invalid. */
  recoveryMode?: RecoveryMode;
  /** Exact identity for this new root session. When omitted the server mints a UUIDv7. This field never selects an existing session: a retained or reserved id is rejected `commandRejected` with reason `session_id_conflict` (tdd SS2.5.1). */
  sessionId?: string;
  /** Absolute path, folded into the first metadata record. */
  workspaceRoot?: string;
  /** The session's initial runtime workspace-root set: ordered absolute canonical existing directory paths; the first root is the CWD and plays the primary-root role; every root receives the ADR 11237 `:workspace_roots` rules; extra roots grant no Project Trust. When `workspaceRoot` is also present the two must name the same folder, compared on canonical forms (the raw `workspaceRoot` is canonicalized first; ADR 37313 D9), or the request is invalid params, and so is explicit `null` (the D-049 null-tolerant set is closed and excludes this member). Omitted preserves single-root behavior (tdd SS2.5.1, ADR 37313, #37313). */
  workspaceRoots?: string[];
}

/** `session/start` result (tdd SS2.5.1). */
export interface SessionStartResult {
  /** The new session. */
  session: Session;
  /** The session view head after the start fold; the connection is subscribed and receives every view event after this cursor. A deduplicated retry returns this same result (tdd SS2.5.1). */
  viewCursor: string;
}

/** `session/started` params (tdd SS2.6.1; enrolled by #33065): a session became newly loaded on this host via `session/start`, `session/fork`, or `session/sideChat` (never `session/resume` — Appendix C, OQ-F), broadcast to every initialized connection.  The one member is the same `$defs/Session` object the `session/start`/`session/fork` results carry, so the broadcast and the result describe one fact through one type — the host builds the broadcast payload as a `$defs/Session` — the fresh-start arm reuses the result's `session` member, the start-replay arm builds the live attach snapshot — and the emission is parity-gated against this type at the producer (`session-server` prod-assembly capture) and over the committed transcript corpus (conformance `session_lifecycle_enrollment`). */
export interface SessionStartedParams {
  /** The newly loaded session, as of the start/fork fold. */
  session: Session;
}

/** A session's load state (tdd SS2.4). */
export type SessionStatus = "notLoaded" | "idle" | "running" | (string & {});

/** `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). */
export interface SessionStatusChangedParams {
  /** Attention flags after the transition; present only when at least one flag is set (tdd SS2.4, ADR 31983 D3). */
  attention?: AttentionFlag[];
  /** The owning session. */
  sessionId: string;
  /** Load state after the transition (the closed SS2.4 enum, unchanged). */
  status: SessionStatus;
  /** The causing record's view cursor (ADR 31983 D4). Required-nullable: `null` exactly when the paired `session/closed`'s cursor is `null` (the unload fold-failure arm); a definite cursor everywhere else. */
  viewCursor: string | null;
}

/** `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. */
export interface SessionTodoListChangedParams {
  /** The full todo list, replaced wholesale. */
  items: TodoItem[];
  /** The snapshot revision. Diagnostics only, never an ordering guard — `viewCursor` orders (tdd SS4.6.3). */
  revision: number;
  /** The owning session. */
  sessionId: string;
  /** The durable records this event folded from. */
  sourceRange: SourceRange;
  /** The tool that produced the snapshot, verbatim. */
  sourceTool: string;
  /** Opaque, strictly monotonic view cursor (tdd SS4.1). */
  viewCursor: string;
}

/** `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. */
export interface SessionTokenUsageParams {
  /** Session running totals at this cursor; the fold owns the accumulation. Subagent/workflow-child usage is never folded in — it rides the owning items (tdd SS4.6.5). */
  cumulative: CumulativeTokenUsage;
  /** Model-call wall time, when measured. */
  durationMs?: number;
  /** Provider finish reason when reported (open vocabulary, verbatim). */
  finishReason?: string;
  /** The effective model that produced this usage; `null` on pre-schema records — never back-filled, an unpriced leg (tdd SS4.6.5). */
  modelId: string | null;
  /** Prompt tokens counted exactly once under the provider's cache convention (#8803). Server-derived; deterministic — the provider is in the log. */
  promptTokens: number;
  /** The owning session. */
  sessionId: string;
  /** The durable records this event folded from. */
  sourceRange: SourceRange;
  /** `promptTokens + outputTokens` — the honest per-completion total. */
  totalTokens: number;
  /** The turn whose model call completed. */
  turnId: string;
  /** Raw counters verbatim from the durable record. */
  usage: TokenUsage;
  /** Opaque, strictly monotonic view cursor (tdd SS4.1). */
  viewCursor: string;
}

/** `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. */
export interface SessionUserShellParams {
  /** The SS3.1.1 idempotency handle (UUIDv7). */
  commandId: string;
  /** The shell command to run. */
  commandText: string;
  /** The target session. */
  sessionId: string;
}

/** `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. */
export interface SessionUserShellResult {
  /** Echoes the client's id. */
  commandId: string;
  /** Admission status. */
  status: CommandStatus;
}

/** 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. */
export type SessionViewHealth = "unavailable" | (string & {});

/** `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). */
export interface SessionViewHealthChangedParams {
  /** The new view-health state. In v1 the host emits only `Unavailable`. */
  health: SessionViewHealth;
  /** Why the view is unavailable — the SAME typed `HistoryNoneReason` vocabulary the pull path stamps on `history.noneReason` (tdd SS2.5.2, D-050), so a client reuses one handler for push and pull. `projectionUnavailable` in v1; present only when `health` is `Unavailable`. Open on the client side: an unknown reason decodes conservatively and renders generically. */
  noneReason?: HistoryNoneReason;
  /** The session whose live view health changed. */
  sessionId: string;
}

/** Side provenance folded from the durable side provenance (`SideChatProvenance`, tdd SS2.4/SS2.5.7; ADR 45435 D2). */
export interface SideProvenance {
  /** The `commandId` of the `session/sideChat` that created it. */
  commandId: string;
  /** An **opaque provenance string** preserved verbatim from the durable side provenance (`source_cut_cursor`). Display-only — not one of the cursor families: clients MUST NOT parse it and no method accepts it (tdd SS2.4). */
  cutCursor: string;
  /** The source main session this side was opened from. */
  sessionId: string;
}

/** `skill/setActivation` activation target (tdd SS3.30.1). **Closed**: a client-selected write vocabulary (ADR 45433 D2) — a write must fail a scope the host does not implement rather than record activation against an unknown target. Contrast the open read-side [`SkillSource`]. */
export type SkillActivationScope = "user" | "project" | "bundled" | "plugin";

/** The three-state skill activation (tdd SS3.30.1, ADR 10512 — no new state). **Closed**: a client-selected write vocabulary (ADR 45433 D2). */
export type SkillActivationState = "on" | "userInvocableOnly" | "off";

/** 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. */
export interface SkillCatalogEntry {
  /** Present when the skill declares an argument hint. */
  argumentHint?: string;
  /** The skill's palette summary. */
  description: string;
  /** The skill display name the first-party palette shows. */
  displayName: string;
  /** The owning plugin's identifier; present when `source` is `plugin`. */
  pluginId?: string;
  /** The shortcut token without the leading slash — bare (`fix-bug`) or plugin-qualified (`acme:deploy`) — the exact value a `skill` input part submits. Unique within one response. */
  selector: string;
  /** Where the skill comes from. */
  source: SkillSource;
  /** The skill's declared human-readable name (`SKILL.md` `metadata.display-name`), for clients to show where people read the skill's name; absent when the skill declares none (ADR 56597 D2). The palette keeps showing `displayName`. */
  title?: string;
}

/** `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). */
export interface SkillChangedParams {
  /** The session whose set changed. */
  sessionId: string;
}

/** The four receipt-list lengths (tdd SS3.30.2): a client renders counts without walking lists. */
export interface SkillImportCounts {
  /** `failed.len()`. */
  failed: number;
  /** `installed.len()`. */
  installed: number;
  /** `quarantined.len()`. */
  quarantined: number;
  /** `skipped.len()`. */
  skipped: number;
}

/** One import candidate that could neither install nor quarantine (tdd SS3.30.2): recorded so the run continues past it. `id` is null when the candidate never yielded one — present-but-null, never omitted. */
export interface SkillImportFailure {
  /** The candidate's id, or null when it never yielded one. */
  id: string | null;
  /** Why the candidate failed. */
  reason: string;
}

/** `skill/import` params (tdd SS3.30.2, #45433): import foreign skills through the single `SkillsService::import_skills` seam. */
export interface SkillImportParams {
  /** The SS3.1.1 idempotency handle (UUIDv7) — required even for `dryRun` previews. */
  commandId: string;
  /** Preview for the consent UI; writes nothing. Additive-optional, default false. */
  dryRun?: boolean;
  /** Re-import over already-imported ids (the CLI `--force` twin). Additive-optional, default false. */
  force?: boolean;
  /** The target session. */
  sessionId: string;
  /** The foreign ecosystem to import from. */
  source: SkillImportSource;
}

/** One quarantined import candidate (tdd SS3.30.2): kept, not loaded. */
export interface SkillImportQuarantine {
  /** The candidate's id. */
  id: string;
  /** The quarantine reasons. */
  reasons: string[];
}

/** `skill/import` result (tdd SS3.30.2, #45433): the ack envelope plus the service receipt projection. */
export interface SkillImportResult {
  /** Echoes the client's id. */
  commandId: string;
  /** The four list lengths. */
  counts: SkillImportCounts;
  /** Echoes the call's preview flag. */
  dryRun: boolean;
  /** Candidates that could neither install nor quarantine. Import never aborts the whole run on one bad candidate. */
  failed: SkillImportFailure[];
  /** The ids the run installed, in pipeline order. */
  installed: string[];
  /** Kept, not loaded, with reasons. */
  quarantined: SkillImportQuarantine[];
  /** Ids the run did not install: already-imported ids and in-run duplicates, verbatim from the seam's `skipped` vec. */
  skipped: string[];
  /** Echoes the call's ecosystem. */
  source: SkillImportSource;
  /** Admission status. */
  status: CommandStatus;
}

/** `skill/import` foreign ecosystem (tdd SS3.30.2). **Closed**: a client-selected write vocabulary (ADR 45433 D2) — a write must fail an ecosystem the host does not implement rather than import from an unknown dir. The host resolves its own foreign dir (the `foreign_skills_sources` derivation); no client paths cross the wire. */
export type SkillImportSource = "claude" | "codex";

/** A `skill` input part's picked-copy source (tdd SS3.22.3; ADR 32471 D12): the D2 catalog-row `source` enum values, sent by the TUI on every skill submit so the host resolves the exact `(selector, source)` row. **Closed**: a client-selected write vocabulary (ADR 45433 D2) — an unknown value is `invalidParams`, never a fall-through to the bare row. Contrast the open read-side [`SkillSource`]. */
export type SkillInvocationSource = "bundled" | "user" | "project" | "plugin";

/** `skill/list` params (tdd SS3.22.1, SS3.30.3). Per-session because skill scope follows the session's workspace and plugin state. */
export interface SkillListParams {
  /** The target session. */
  sessionId: string;
}

/** `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). */
export interface SkillListResult {
  /** The session's user-invocable skill rows. */
  skills: SkillCatalogEntry[];
}

/** `skill/setActivation` params (tdd SS3.30.1, #45433): turn one skill on or off in any scope through the single `SkillsService::set_activation` seam. */
export interface SkillSetActivationParams {
  /** The activation to apply. */
  activation: SkillActivationState;
  /** The SS3.1.1 idempotency handle (UUIDv7). */
  commandId: string;
  /** The activation target. */
  scope: SkillActivationScope;
  /** Names one skill: a bare or plugin-qualified token from the session's full catalog (tdd SS3.30.3), the SS3.22.1 row vocabulary. */
  selector: string;
  /** The target session. */
  sessionId: string;
}

/** `skill/setActivation` result (tdd SS3.30.1, #45433): the ack envelope plus the applied state. */
export interface SkillSetActivationResult {
  /** The applied activation. */
  activation: SkillActivationState;
  /** Echoes the client's id. */
  commandId: string;
  /** The activation value in force for that `(selector, scope)` immediately before the write: the same value a full-catalog `skill/list` row would have carried in `activation` for it. */
  previous: SkillActivationState;
  /** Echoes the applied write's scope. */
  scope: SkillActivationScope;
  /** Echoes the applied write's selector. */
  selector: string;
  /** Admission status. */
  status: CommandStatus;
}

/** 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. */
export type SkillSource = "bundled" | "user" | "project" | "plugin" | (string & {});

/** The compaction boundary an anchored snapshot is anchored at (tdd SS2.5.2). */
export interface SnapshotAnchor {
  /** The view cursor of the boundary's `compaction` event. */
  boundaryCursor: string;
  /** The boundary's opaque compaction anchor (tdd SS4.5.10). */
  summarizedThrough: string;
}

/** 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. */
export interface SnapshotState {
  /** The running foreground turn; `null` when none is running. */
  activeTurn: TurnRef | null;
  /** The effective approval mode at this cursor — the same object the `Session` carries (tdd SS2.4, SS5.12). */
  approvalMode: EffectiveApprovalModeState;
  /** Latest branch observation; `null` when no fact has landed. */
  branch: BranchState | null;
  /** The latest `(windowTokens, usedTokens, pressure)` triple. The protocol allows "`null`/absent" and its worked example OMITS the member; the binary omits it too, so this is the absent arm — the four siblings above are present-null in the same frame. A member is published as one or the other, never both. */
  contextUsage?: ContextUsage;
  /** Latest effective model; `null` when no fact has landed. */
  effectiveModel: EffectiveModel | null;
  /** Latest goal block; `null` when no fact has landed. */
  goal: Goal | null;
  /** Every item, in first-opened order, each at its latest revision at the snapshot cursor. One schema per kind, shared with the notification item object — which is what makes snapshot+suffix a pure splice (tdd SS4.9.1). */
  items: Item[];
  /** The settled canonical session name; `null` when the session was never named (#27598, tdd SS4.9.1 / SS2.14). Folds the same durable `session/nameChanged` record `Session.name` reports. */
  name?: string | null;
  /** The pending-approval half of the pending set. */
  pendingApprovals: PendingApprovalPointer[];
  /** The pending-user-input half of the pending set. */
  pendingUserInputs: PendingUserInputPointer[];
  /** Admitted-but-not-launched submits, in launch order (tdd SS3.1.4). */
  queuedTurns: TurnRef[];
  /** The latest session-default reasoning effort with its source; ABSENT until a set lands (tdd SS4.9.1 `reasoningEffort`, ADR 31255 D1 — the `contextUsage` absent arm, never present-null). */
  reasoningEffort?: ReasoningEffortState;
  /** Latest todo list; `null` when no fact has landed. */
  todoList: TodoListState | null;
  /** The `cumulative` block of the last `session/tokenUsage` event; zeroes when none (tdd SS4.9.1). */
  tokenUsage: CumulativeTokenUsage;
  /** Completed-turn count at this cursor. */
  turnCount: number;
}

/** 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). */
export interface SourceRange {
  /** The first record of the inclusive range. */
  first: RecordPosition;
  /** The last record of the inclusive range; equal to `first` for an event folded from one record. */
  last: RecordPosition;
  /** The stream the folded records live on (run stream, or the session stream's mirror of task/approval/subagent-control records — whichever the fold actually consumed, tdd SS4.2). */
  stream: StreamRef;
}

/** `toolCall.statusAttempt` (tdd SS4.5.5, #45448): the latest `TaskExternalAttemptDetail`, field-for-field — countdown inputs the client renders the tick from, so no event spam. */
export interface StatusAttempt {
  /** The attempt number. */
  attempt: number;
  /** The error kind (durable vocabulary, verbatim), when recorded. */
  errorKind?: string;
  /** The HTTP status, when recorded. */
  httpStatus?: number;
  /** The maximum attempts, when known. */
  maxAttempts?: number;
  /** The scheduled next attempt, when known. */
  nextAttempt?: number;
  /** The operation (durable vocabulary, verbatim). */
  operation: string;
  /** The retry delay in ms, when known. */
  retryDelayMs?: number;
  /** The external system (durable vocabulary, verbatim). */
  system: string;
}

/** `toolCall.statusChildren` (tdd SS4.5.5, #45448): the latest `TaskChildSummaryDetail`, field-for-field. */
export interface StatusChildren {
  /** Active children. */
  active: number;
  /** Cancelled children. */
  cancelled: number;
  /** Completed children. */
  completed: number;
  /** Failed children. */
  failed: number;
  /** Total children, when known. */
  total?: number;
}

/** `toolCall.statusHealth` (tdd SS4.5.5, #45448): the latest `TaskHealthDetail`, field-for-field. */
export interface StatusHealth {
  /** The health level (the durable `TaskHealthLevel` vocabulary verbatim). */
  level: StatusHealthLevel;
  /** The reason, when recorded. */
  reason?: string;
}

/** `toolCall.statusHealth.level` (tdd SS4.5.5, #45448): the durable `TaskHealthLevel` vocabulary verbatim. Open — runtime vocabulary may grow additively, and clients MUST render unknown levels generically. */
export type StatusHealthLevel = "ok" | "waiting" | "degraded" | "retrying" | "blocked" | "failed" | (string & {});

/** `toolCall.statusProgress` (tdd SS4.5.5, #45448): the latest `TaskProgressDetail`, field-for-field. */
export interface StatusProgress {
  /** Completed units. */
  current: number;
  /** Total units, when known. */
  total?: number;
  /** Unit label, when recorded. */
  unit?: string;
}

/** `toolCall.statusStep` (tdd SS4.5.5, #45448): the latest `TaskActiveStepDetail`, field-for-field. */
export interface StatusStep {
  /** The step index, when known. */
  index?: number;
  /** The active step's label. */
  label: string;
  /** The step count, when known. */
  total?: number;
}

/** One raw stream named by a [`SourceRange`] (tdd SS4.2). */
export interface StreamRef {
  /** The stream id. */
  id: string;
  /** The stream kind, verbatim raw-log vocabulary (e.g. `"run"`, `"session"`). A free string, not an enum: `sourceRange` is an opaque provenance token in v1 and the raw stream vocabulary is the deferred SS6 altitude's to freeze (#13929). */
  kind: string;
}

/** Subagent control status (tdd SS4.5.7, camelCased `SubagentControlStatus`). Open; the generic item `status` is the terminal authority. */
export type SubagentControlStatus = "accepted" | "starting" | "running" | "resultReady" | "closing" | "closed" | "recoveryPending" | "manualReconciliation" | (string & {});

/** Params for `subagent/sendMessage` and `subagent/followupTask` (SS3.16): a child target plus the input body. */
export interface SubagentInputParams {
  /** The note/task text: trimmed with Unicode-whitespace semantics, rejected when empty after trimming, delivered trimmed with multibyte content byte-for-byte intact (SS3.16). */
  body: string;
  /** Client-minted UUIDv7 command id (SS3.1.1). */
  commandId: string;
  /** Target session (UUIDv7 string; SS3 preamble). */
  sessionId: string;
  /** Durable child id (the SS4.5.7 item's `subagentId`; opaque string). */
  subagentId: string;
}

/** 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. */
export interface SubagentOwnerReasonParams {
  /** Client-minted UUIDv7 command id (SS3.1.1). */
  commandId: string;
  /** Optional reason, preserved on the durable owner-command record. */
  reason?: string;
  /** Target session (UUIDv7 string; SS3 preamble). */
  sessionId: string;
  /** Durable child id (the SS4.5.7 item's `subagentId`; opaque string). */
  subagentId: string;
}

/** A subagent's result envelope (tdd SS4.5.7, `SubagentResultEnvelope`). */
export interface SubagentResult {
  /** Artifact references, verbatim. */
  artifactRefs: string[];
  /** `true` once the parent consumed the result (the inbox join fact the gate-off drain arm folds into the `Finished` marker — tdd SS4.5.7). Absent otherwise; never cleared once set. Clients mint the `Finished` marker off this flag instead of re-deriving the join. */
  drained?: boolean;
  /** Error kind, verbatim durable vocabulary, when the child failed. */
  errorKind?: string;
  /** Evidence references, verbatim. */
  evidenceRefs: string[];
  /** Structured result data, verbatim, when present. */
  structuredData?: Record<string, unknown>;
  /** Result summary, bounded on the wire at the 64 KiB retained-text budget (tdd SS4.5.4 and SS4.5.7, ADR 35691 D9); a cut sets the item's `truncated`. The durable record stays verbatim. */
  summary: string;
  /** Result text, when present, bounded on the wire at the same 64 KiB budget (ADR 35691 D9); a cut sets the item's `truncated`. */
  text?: string;
}

/** Params for `subagent/resume`, `subagent/reopen`, and `subagent/readResult` (SS3.16): the bare child target. */
export interface SubagentTargetParams {
  /** Client-minted UUIDv7 command id (SS3.1.1). */
  commandId: string;
  /** Target session (UUIDv7 string; SS3 preamble). */
  sessionId: string;
  /** Durable child id (the SS4.5.7 item's `subagentId`; opaque string). */
  subagentId: string;
}

/** 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). */
export interface SubscriptionUsage {
  /** When the host RECEIVED this observation (frame arrival or mint request-send), epoch milliseconds. */
  observedAtMs: number;
  /** The provider's subscription tier id, verbatim. */
  tier: string;
  /** The rolling weekly block. */
  weekly: SubscriptionUsageWeekly;
  /** The current window. */
  window: SubscriptionUsageWindow;
}

/** The rolling weekly block: same semantics as [`SubscriptionUsageWindow`] without a duration (ADR 32563 D2). */
export interface SubscriptionUsageWeekly {
  /** When the weekly window resets, epoch milliseconds. */
  resetsAtMs: number;
  /** Percent of the weekly budget used (integer ≥ 0, may exceed 100). */
  usedPercent: number;
}

/** 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). */
export interface SubscriptionUsageWindow {
  /** When the window resets, epoch milliseconds. */
  resetsAtMs: number;
  /** Percent of the window's budget used: an integer ≥ 0, verbatim from the provider — over-quota values above 100 are valid. */
  usedPercent: number;
  /** The window's length in minutes (> 0). */
  windowDurationMins: number;
}

/** A success response frame (SS1.2 §2.3). */
export interface SuccessResponse {
  /** Echo of the request id. */
  id: RequestId;
  /** The literal `"2.0"`. */
  jsonrpc: JsonRpcVersion;
  /** Always a JSON object, possibly `{}`, never a bare scalar — so every result can grow additive-optional members (SS1.2). */
  result: Record<string, unknown>;
}

/** `task/background` params (tdd §3.13): durably send a running foreground tool task to the background. */
export interface TaskBackgroundParams {
  /** The SS3.1.1 idempotency handle (UUIDv7). */
  commandId: string;
  /** The target session. */
  sessionId: string;
  /** The task to background, exactly as the view names it: the `toolCall` item's `itemId` IS the task id (SS4.5.5). */
  taskId: string;
}

/** The `task/background` / `task/stop` ack (tdd §3.13/§3.14): admission-only, echoing the targeted task. */
export interface TaskCommandResult {
  /** Echoes the client's id. */
  commandId: string;
  /** Admission status. */
  status: CommandStatus;
  /** Echoes the targeted task id. */
  taskId: string;
}

/** A task row's execution mode (tdd SS3.31, ADR 62268 D2). Open (server-produced result vocabulary, the #22785 enum-openness rule): clients MUST ignore unknown modes. */
export type TaskExecutionMode = "foreground" | "background" | (string & {});

/** One task inventory row (tdd SS3.31). The row is the stable contract: `kind` and `status` stay open so a future state extends them without breaking clients. */
export interface TaskListEntry {
  /** Who backgrounded the task, mirroring the item field. **Additive-optional**: absent on pre-split records and registry-only rows, never inferred. */
  backgroundInitiator?: BackgroundInitiator;
  /** The raw command text: the joined `toolCall` item's `command` argument verbatim (ADR 62268 D2). **Additive-optional**: omitted when the row has no item or the item carries no command. Monitors join raw — clients redact (INV-17544-6). */
  command?: string;
  /** `"foreground" | "background"` (ADR 62268 D2). **Additive-optional**: absent means `"background"` (only pre-change hosts omit it, and those list background rows only); never guessed. */
  executionMode?: TaskExecutionMode;
  /** What the workload is: `"tool"` or `"tool.*"` for item rows (the recorded kind when the registry records one, else `"tool"`); the recorded registry kind string verbatim for registry-only rows. Open vocabulary — clients MUST ignore unknown kinds. A `String`, not an enum: registry kind strings are unbounded. */
  kind: string;
  /** The host-known task start, RFC3339. **Additive-optional**: omitted, never guessed, when the host does not know it. */
  startedAt?: string;
  /** `"inProgress"` — the only value at this increment, since every listed row is non-terminal by construction. */
  status: TaskListStatus;
  /** The `toolCall` item's `itemId` for item rows; the runtime registry id for registry-only rows. */
  taskId: string;
  /** The short tool name on item-visible tool rows only; never a label, never arguments. **Additive-optional**: absent elsewhere. */
  tool?: string;
}

/** `task/list` params (tdd SS3.31): the session whose background-task inventory to read. A read-only query in the `skill/list` mold: no `commandId`, no durable record, no view event. */
export interface TaskListParams {
  /** The target session. */
  sessionId: string;
}

/** `task/list` result (tdd SS3.31): one row per live workload, background and foreground (ADR 62268 D1), oldest first; empty when nothing is running. */
export interface TaskListResult {
  /** The session's live task rows. */
  tasks: TaskListEntry[];
}

/** A task row's status (tdd SS3.31). Open (server-produced result vocabulary, the #22785 enum-openness rule): a future state is additive, and clients MUST ignore unknown statuses. */
export type TaskListStatus = "inProgress" | (string & {});

/** `task/stopAll` params (tdd §3.15): stop every stoppable background workload live at admission. */
export interface TaskStopAllParams {
  /** The SS3.1.1 idempotency handle (UUIDv7). */
  commandId: string;
  /** The target session. */
  sessionId: string;
}

/** 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. */
export interface TaskStopAllResult {
  /** Echoes the client's id. */
  commandId: string;
  /** Admission status. */
  status: CommandStatus;
}

/** `task/stop` params (tdd §3.14): stop one named background task. Required target, never "whichever is loudest" — §3.15 is the blanket verb. */
export interface TaskStopParams {
  /** The SS3.1.1 idempotency handle (UUIDv7). */
  commandId: string;
  /** The target session. */
  sessionId: string;
  /** The task to stop, the `toolCall` item's `itemId` (SS4.5.5). */
  taskId: string;
}

/** One todo entry (tdd SS4.6.3). */
export interface TodoItem {
  /** Present-tense active form, when the tool supplied one. */
  activeForm?: string;
  /** The todo status (camelCased runtime `TodoStatus`). */
  status: TodoStatus;
  /** The todo text. */
  text: string;
}

/** The latest todo-list fact in the snapshot (tdd SS4.6.3, SS4.9.1). */
export interface TodoListState {
  /** The full todo list. */
  items: TodoItem[];
  /** The snapshot revision. Diagnostics only, never an ordering guard. */
  revision: number;
  /** The tool that produced the snapshot, verbatim. */
  sourceTool: string;
}

/** Todo status (tdd SS4.6.3): closed in the runtime, wire-open. */
export type TodoStatus = "pending" | "inProgress" | "completed" | "cancelled" | (string & {});

/** 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). */
export interface TokenUsage {
  /** Cache read tokens, only when the provider distinguishes writes/reads. */
  cacheReadTokens?: number;
  /** Cache write tokens, only when the provider distinguishes writes/reads. */
  cacheWriteTokens?: number;
  /** Provider-reported cache tokens (inside or beside `inputTokens`, provider-convention-dependent — the reason `promptTokens` exists). */
  cachedTokens: number;
  /** Provider-reported input tokens. */
  inputTokens: number;
  /** Provider-reported output tokens. */
  outputTokens: number;
  /** Output tokens spent on reasoning, when the provider reports it. */
  reasoningTokens: number;
}

/** `toolCall.displayLabel`: the call's words in three forms, each one line of plain text, always present together. The item's `status` picks the form. */
export interface ToolDisplayLabel {
  /** Shown while the call runs (`inProgress`), e.g. "Setting up Computer Use". */
  active: string;
  /** Shown after the call succeeds (`completed`), e.g. "Set up Computer Use". */
  done: string;
  /** Shown for every other status (failed, rejected, timed out, cancelled), beside that status; never implies success. */
  neutral: string;
}

export type ToolReceipt = { details?: CronReceipt; family: "cron"; operation: ToolReceiptOperation; outcome: ToolReceiptOutcome; } | { details?: CodeModeReceipt; family: "codeMode"; operation: ToolReceiptOperation; outcome: ToolReceiptOutcome; } | { details?: Record<string, unknown>; family: string; operation: string; outcome: string; };

/** Which operation within the family the receipt describes (ADR 43399 D1/D2). Open — registered per family, never derived from the tool name. */
export type ToolReceiptOperation = "create" | "delete" | "list" | "execute" | "wait" | (string & {});

/** What the operation did (ADR 43399 D1/D2). Open, and a **single shared vocabulary**: a value appearing in two families means the same thing in both, which is why the permitted `status` values are bound to the value here rather than per family. */
export type ToolReceiptOutcome = "created" | "duplicate" | "deleted" | "missing" | "listed" | "rejected" | "completed" | "pending" | "failed" | "timedOut" | "cancelled" | (string & {});

/** Optional W3C trace context, on requests in both directions only — never on responses or notifications (SS1.8). */
export interface TraceContext {
  /** W3C `traceparent` string; receivers that do not trace ignore it. */
  traceparent?: string;
  /** W3C `tracestate` string. */
  tracestate?: string;
}

/** `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`. */
export interface TurnCancelParams {
  /** The SS3.1.1 idempotency handle (UUIDv7). */
  commandId: string;
  /** The target session. */
  sessionId: string;
  /** The exact turn to cancel; omit to target the current foreground turn. Any syntactically valid UUID: a turn from an older session may carry a v4 or v5 id. A malformed id is `invalidParams`. */
  turnId?: string;
}

/** `turn/cancel` result (tdd SS3.5): identical envelope to `turn/interrupt`. */
export interface TurnCancelResult {
  /** Echoes the client's id. */
  commandId: string;
  /** Admission status. */
  status: CommandStatus;
  /** The cancelled turn. */
  turnId: string;
}

/** `turn/completed` params (tdd SS4.5.1): the run's durable terminal record landed. */
export interface TurnCompletedParams {
  /** Turn duration; absent means unmeasured, never fabricated. */
  durationMs?: number;
  /** Present when `terminal` is `"failed"`, except on a synthesized host-death terminal, which carries `reason` instead (tdd SS4.5.1, ADR 36635 D2): mid-turn failures reach the client here — never as a JSON-RPC error. */
  error?: TurnError;
  /** The runtime's free-text terminal reason, verbatim. Display and diagnostics only; never branch on it. */
  reason?: string;
  /** The owning session. */
  sessionId: string;
  /** The durable records this event folded from. */
  sourceRange: SourceRange;
  /** The turn terminal (open enum). */
  terminal: TurnTerminal;
  /** Time to first token, when measured. */
  timeToFirstTokenMs?: number;
  /** The terminated turn. */
  turnId: string;
  /** The turn's aggregate token usage, summed across the turn's model completions (same shape as `session/tokenUsage.usage`). */
  usage?: TokenUsage;
  /** Opaque, strictly monotonic view cursor (tdd SS4.1). */
  viewCursor: string;
}

/** The settled turn-failure object (tdd SS4.5.1): `{kind, message, retryable}`. */
export interface TurnError {
  /** The failure class (open camelCase enum grounded in the runtime's terminal failure classification). */
  kind: TurnErrorKind;
  /** Human-readable failure text. */
  message: string;
  /** Typed quota-exhaustion detail (ADR 50047 D2/D3): present iff the stopping failure was the quota class. Clients branch on presence, never by parsing `message`. */
  quota?: QuotaDetail;
  /** The server's judgment that resubmitting the same input may succeed. */
  retryable: boolean;
}

/** Turn failure classes (tdd SS4.5.1, `TerminalErrorKind` plus the model-task failure class). Open. */
export type TurnErrorKind = "stepLimit" | "configError" | "projectionError" | "logError" | "workflowLaunchError" | "environmentError" | "modelError" | "launchError" | "authRequired" | "mcpLinkError" | (string & {});

/** `turn/foregroundCompleted` params (tdd SS4.5.12): the turn's foreground work is done and named background reminder checks hold the turn open. Explicitly non-terminal: the turn ends only at `turn/completed` / `turn/unqueued`. */
export interface TurnForegroundCompletedParams {
  /** `reminderAgentId`s of the firing's blocking set, never empty; agent ids, never display names. Live-best-effort: reads, resume, and replay may narrow it to the linked subset. */
  blockingAgents: string[];
  /** The owning session. */
  sessionId: string;
  /** The durable records this event folded from, anchored at the first blocking link of the firing window. */
  sourceRange: SourceRange;
  /** The turn whose foreground completed. */
  turnId: string;
  /** Opaque, strictly monotonic view cursor (tdd SS4.1). */
  viewCursor: string;
}

/** 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 same either way; what a flat object cannot express is "`mediaType` is required exactly when `type` is `image`". `height` may only appear together with `width`. `width` may only appear together with `height`. */
export interface TurnInputPart {
  /** Free-text skill arguments, optional on a `skill` part — the wire twin of what the TUI accepts after the shortcut token (tdd SS3.22.3). */
  arguments?: string;
  /** Base64 payload, required on an `image` part. Invalid base64 or an empty payload is rejected with invalid params. */
  base64Data?: string;
  /** Pixel height; must be provided together with `width` or not at all (tdd SS3.2, #22785 E6c). */
  height?: number;
  /** Media type, required on an `image` part. */
  mediaType?: string;
  /** The skill to invoke, required on a `skill` part (tdd SS3.2, SS3.22.3; ADR 32471 D4): a bare or plugin-qualified shortcut token from `skill/list`. The HOST resolves and expands; an unknown selector is the typed `-32032 skillNotFound` request error. */
  selector?: string;
  /** The picked copy's source, optional on a `skill` part: one of the catalog rows' `source` values. When present the host resolves the exact `(selector, source)` row; when absent it resolves the selector, bare or plugin-qualified, against the session's skill catalog, as the TUI shortcut does. Closed: an unknown value is `invalidParams`, never a fall-through. */
  source?: SkillInvocationSource;
  /** User prompt text, on a `text` part. Multiple text parts are joined in order into the turn's prompt. */
  text?: string;
  /** The part type. */
  type: TurnInputPartType;
  /** The upload receipt, required on a `video` part (tdd SS3.2, SS3.33; ADR 45443 D5): the client-minted id `media/upload` echoed. */
  uploadId?: string;
  /** Pixel width; must be provided together with `height` or not at all. Published as a `dependentRequired` pair. */
  width?: number;
}

/** The `type` discriminator of a turn input part (tdd SS3.2). Closed: an unknown part type is `invalidParams` (tdd SS3.1.2). */
export type TurnInputPartType = "text" | "image" | "skill" | "video";

/** `turn/interrupt` params (tdd SS3.4): the "user pressed stop" gesture, on the runtime's priority lane. */
export interface TurnInterruptParams {
  /** The SS3.1.1 idempotency handle (UUIDv7). */
  commandId: string;
  /** Pair a retract intent with the interrupt: if the turn is cancelled before any assistant output committed, the submission is durably retracted (view event `turn/retracted`) so the client may restore the prompt text. A rejected retract does not undo the interrupt. Default `false` (tdd SS3.4). */
  retract?: boolean;
  /** The target session. */
  sessionId: string;
  /** The exact turn to interrupt. Omit to target the session's current foreground turn, resolved at admission; prefer passing the explicit id when you have one (tdd SS3.4). Any syntactically valid UUID: a turn from an older session may carry a v4 or v5 id. A malformed id is `invalidParams`. */
  turnId?: string;
}

/** `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`. */
export interface TurnInterruptResult {
  /** Echoes the client's id. */
  commandId: string;
  /** Admission status. */
  status: CommandStatus;
  /** The interrupted turn. */
  turnId: string;
}

/** `turn/modelRetryScheduled` params (tdd SS4.5.1; ADR `50047-model-retry-scheduled-members` D1): a durable model-stream retry-scheduled fact folded — the provider backoff behind one model attempt is observable BEFORE the turn terminates, so a streaming client can render "system words · retrying in Ss · attempt N/M" instead of dead air. Non-terminal: it never resolves a turn-wait. The sibling `turn/retryScheduled` shape at the model layer: same member names and semantics (attempt/nextAttempt/maxAttempts/ retryDelayMs/system/errorKind/httpStatus), minus `reason` — the row's words derive from `errorKind` through the shared gate-off mapping, and the recorded machine message is not user text. The delay is the recorded scheduled backoff, never an absolute fire time — clients derive any countdown locally. `sourceRange` cites the session stream's mirror of the task-lifecycle record (tdd SS4.2). */
export interface TurnModelRetryScheduledParams {
  /** The failed model attempt (producer-normalized, >= 1). */
  attempt: number;
  /** The failing model attempt's durable kind, verbatim (ADR 50047 D2) — a plain string: the durable vocabulary is open-ended. */
  errorKind?: string;
  /** The failing model attempt's HTTP status (ADR 50047 D2). */
  httpStatus?: number;
  /** The model-retry chain bound. */
  maxAttempts: number;
  /** The scheduled model attempt (producer contract: attempt < nextAttempt <= maxAttempts; not a schema constraint). */
  nextAttempt: number;
  /** The scheduled backoff delay in milliseconds, verbatim from the durable fact. */
  retryDelayMs: number;
  /** The owning session. */
  sessionId: string;
  /** The durable record this event folded from (the session stream's mirror of the scheduled model task status; `first == last`). */
  sourceRange: SourceRange;
  /** The failing model attempt's provider system, verbatim (ADR 50047 D2) — e.g. `"meta"`. Always present from this producer (the durable `system` is a required `String`); optional on the wire so a future omission folds absent instead of failing the frame. */
  system?: string;
  /** The running turn whose model attempt is being retried. */
  turnId: string;
  /** Opaque, strictly monotonic view cursor (tdd SS4.1). */
  viewCursor: string;
}

/** A turn named by the snapshot's active/queued lists (tdd SS4.9.1). */
export interface TurnRef {
  /** The `commandId` of the submit that minted it. */
  commandId: string;
  /** `queuedTurns[]` only (#45455; ADR 45443 D7): the queued submit's presentation text, so a late joiner can render it without waiting for launch. A current host sets it on every entry it admits; absent means an older host (or a pre-feature restored entry). Never set on `activeTurn`: the running turn's text is its `userMessage` item. */
  displayText?: string;
  /** `queuedTurns[]` only: set when `displayText` was cut to the committed-surface budget, mirroring `userMessage.truncated` (tdd SS4.5.2). Absent unless `true`. */
  truncated?: boolean;
  /** The turn's id, minted at admission. */
  turnId: string;
}

/** `turn/retracted` params (tdd SS4.5.1): an interrupt-paired retract durably settled, accepted or declined (ADR 50074 D1). On `"accepted"` the retracted user-message item is re-emitted via `item/updated` with `retracted: true`; on `"declined"` the client folds the legacy declined rollback instead and no item is re-emitted. */
export interface TurnRetractedParams {
  /** The retracted submission's command id. */
  commandId: string;
  /** The retract settlement outcome (tdd SS4.5.1, ADR 50074 D1). Additive-optional: absent reads as `"accepted"` — pre-feature hosts emit the event only for accepted retracts — and so does an unrecognized value (open enum, D-033). */
  outcome?: RetractOutcome;
  /** The owning session. */
  sessionId: string;
  /** The durable records this event folded from. */
  sourceRange: SourceRange;
  /** The turn whose submission was retracted. */
  turnId: string;
  /** Opaque, strictly monotonic view cursor (tdd SS4.1). */
  viewCursor: string;
}

/** `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). */
export interface TurnRetryScheduledParams {
  /** The attempt that failed (producer-normalized, >= 1). */
  attempt: number;
  /** The failing model attempt's durable kind, verbatim (ADR 50047 D2/D3) — a plain string: the durable vocabulary is open-ended. */
  errorKind?: string;
  /** The failing model attempt's HTTP status (ADR 50047 D2/D3). */
  httpStatus?: number;
  /** The turn's model-retry chain bound. */
  maxAttempts: number;
  /** The attempt about to run (producer contract: attempt < nextAttempt <= maxAttempts; not a schema constraint). */
  nextAttempt: number;
  /** The recorded stopping reason through the shared task-detail normalization (non-empty; capped at 160 characters). */
  reason: string;
  /** The scheduled backoff delay in milliseconds, verbatim from the durable fact. */
  retryDelayMs: number;
  /** The owning session. */
  sessionId: string;
  /** The durable record this event folded from (the session stream's mirror of the retry-scheduled task status; `first == last`). */
  sourceRange: SourceRange;
  /** The failing model attempt's provider system, verbatim (ADR 50047 D2/D3) — e.g. `"meta"`. Absent when no model-attempt facet precedes the retry status on the task (old logs). */
  system?: string;
  /** The running turn whose model attempt is being retried. */
  turnId: string;
  /** Opaque, strictly monotonic view cursor (tdd SS4.1). */
  viewCursor: string;
}

/** 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. */
export type TurnStartDisposition = "started" | "queued" | "steered" | (string & {});

/** `turn/start` params (tdd SS3.2).  `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. */
export interface TurnStartParams {
  /** The SS3.1.1 idempotency handle (UUIDv7). The fresh turn's `turnId` derives from it (tdd SS3.1.4). */
  commandId: string;
  /** Presentation form of the prompt for transcripts. Durable; carried on the resulting user-message view item. Never model-visible (tdd SS3.2). */
  displayText?: string;
  /** Disposition when a turn is already running; default `queue`. */
  ifBusy?: IfBusy;
  /** Ordered content parts; required and non-empty. */
  input: TurnInputPart[];
  /** Reasoning tier sampled at submission for this turn. */
  reasoningEffort?: ReasoningEffort;
  /** The target session. */
  sessionId: string;
  /** A queued `!` shell action riding this turn (tdd SS3.2, ADR 50034): the `!cmd` typed while a turn runs, executed at the next model-call boundary before any later steer. Exclusive with `text` and `skill` input; `input` may be empty only when this member is present. Capability-gated on `userShell`: a carrying turn on a connection without the grant fails `-32010 capabilityRequired`. Explicit `null` is invalid params (the null-tolerant set is closed). A v1 stable member. */
  userShell?: TurnUserShell;
  /** A sticky REPLACEMENT of the session's runtime workspace-root set, binding at this turn's launch and persisting for subsequent turns until replaced again — unlike `reasoningEffort`, which is this-turn-only. Same shape and validation as `session/start.workspaceRoots`; invalid params on an explicit `ifBusy: "steer"` submit and so is explicit `null` (the D-049 null-tolerant set is closed); omitted means "unchanged", never "reset" (tdd SS3.2, ADR 37313 D3, #37313). */
  workspaceRoots?: string[];
}

/** `turn/start` result (tdd SS3.2). */
export interface TurnStartResult {
  /** Echoes the client's id. */
  commandId: string;
  /** What happened to the input. */
  disposition: TurnStartDisposition;
  /** `true` iff `disposition` is `started`; retained as the boolean shorthand — `disposition` is authoritative (tdd SS3.2). */
  startedNewTurn: boolean;
  /** Admission status. */
  status: CommandStatus;
  /** The turn that will carry (or absorbed) this input. Authoritative: always take it from the ack rather than deriving it (tdd SS3.2). */
  turnId: string;
}

/** `turn/started` params (tdd SS4.5.1): a foreground turn began running — fresh submits immediately, queued submits at their launch boundary, never steered submits. */
export interface TurnStartedParams {
  /** The submitting command; `turnId == commandId` for fresh turns (tdd SS3.1.4). */
  commandId: string;
  /** The owning session. */
  sessionId: string;
  /** The durable records this event folded from. */
  sourceRange: SourceRange;
  /** The started turn. */
  turnId: string;
  /** Opaque, strictly monotonic view cursor (tdd SS4.1). */
  viewCursor: string;
}

/** `turn/steer` params (tdd SS3.3): exact-target steering into the currently running turn. */
export interface TurnSteerParams {
  /** The SS3.1.1 idempotency handle (UUIDv7). */
  commandId: string;
  /** The turn you believe is running. Closes the race where the turn completes or is replaced between your read and your steer: input meant for turn A can never leak into turn B (tdd SS3.3). Any syntactically valid UUID: a turn from an older session may carry a v4 or v5 id. A malformed id is `invalidParams`; an id that is not the running turn is refused. */
  expectedTurnId: string;
  /** Same content parts as `turn/start`. */
  input: TurnInputPart[];
  /** Reasoning tier for the model calls this steer's input reaches. Applies forward, never backward; absent means unspecified, not "reset" (tdd SS3.3, D-024). */
  reasoningEffort?: ReasoningEffort;
  /** The target session. */
  sessionId: string;
}

/** `turn/steer` result (tdd SS3.3). */
export interface TurnSteerResult {
  /** Echoes the client's id. */
  commandId: string;
  /** Admission status. */
  status: CommandStatus;
  /** The running turn that absorbed the input. */
  turnId: string;
}

/** Turn terminal vocabulary (tdd SS4.5.1): exactly the runtime's `RunTerminalKind` — closed in the runtime, wire-open for evolution. */
export type TurnTerminal = "completed" | "failed" | "cancelled" | (string & {});

/** `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. */
export interface TurnUnqueueParams {
  /** The SS3.1.1 idempotency handle (UUIDv7). */
  commandId: string;
  /** The target session. */
  sessionId: string;
  /** The queued turn to reclaim, exactly as the queueing `turn/start`'s ack minted it and as snapshot `queuedTurns` lists it. Required, and never "whichever is newest" (tdd SS3.6). Any syntactically valid UUID: a turn from an older session may carry a v4 or v5 id. A malformed id is `invalidParams`. */
  turnId: string;
}

/** `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. */
export interface TurnUnqueueResult {
  /** Echoes the client's id. */
  commandId: string;
  /** Admission status. */
  status: CommandStatus;
  /** The reclaimed turn. */
  turnId: string;
}

/** `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. */
export interface TurnUnqueuedParams {
  /** The `commandId` of the `turn/start` that queued the reclaimed turn. */
  commandId: string;
  /** The owning session. */
  sessionId: string;
  /** The durable records this event folded from (the session stream's reclaim record). */
  sourceRange: SourceRange;
  /** The reclaimed turn: pre-minted at admission, never launched. */
  turnId: string;
  /** Opaque, strictly monotonic view cursor (tdd SS4.1). */
  viewCursor: string;
}

/** The queued `!` shell action a `turn/start` carries (tdd SS3.2, ADR 50034): the `!cmd` typed while a turn runs. The shell's command id derives from the carrying turn's `commandId`, exactly as the app's own queued submit does; the params' sibling `displayText` carries the `!…` presentation form. */
export interface TurnUserShell {
  /** The shell command text, without the leading `!`. */
  commandText: string;
}

/** One element of a `view/page` result's `events` array: an **unframed view notification** — the nested pair `{"method", "params"}`, which is the live notification minus `jsonrpc` and `emittedAtMs`, with nothing lifted out of `params` and nothing spliced into it. `view/page` and `muse exec --json` share this one definition, so the two surfaces cannot drift. */
export interface UnframedViewNotification {
  /** The event type — the live notification's method name, retained because the type lives only in the notification name and would otherwise be lost (tdd SS4.2.1). */
  method: string;
  /** The notification's params object, verbatim. */
  params: UnframedViewNotificationParams;
}

/** The `params` of an unframed view notification (tdd SS4.2.1, SS4.2).  Declares the base members every view notification carries, and stays **open** for the event-specific fields each event type adds. The v1 schema model names no method-correlated union (the `events` element's `params` arm is selected by its sibling `method`), so the per-event arms cannot be expressed here without one, and an uncorrelated union of them could reject a real page element, which a published schema must not do.  `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. */
export interface UnframedViewNotificationParams {
  /** The owning session (tdd SS4.2). */
  sessionId: string;
  /** The durable records this event folded from (tdd SS4.2, SS6.8). */
  sourceRange: SourceRange;
  /** The event's opaque, strictly monotonic view cursor. It stays **inside** `params`, where every live notification already carries it (tdd SS4.2.1) — nothing is spliced beside `method`. */
  viewCursor: string;
}

/** The only scalar alternative to a known effort array. Kept as a closed singleton so arbitrary strings and uppercase spellings fail decoding. */
export type UnknownModelReasoningEffortVariants = "unknown";

/** `usage/read` result: `{usage?}` — omitted, never `null`, when the host has observed nothing (ADR 32563 D2: truthful absence, no "nothing observed" error). */
export interface UsageReadResult {
  /** The last-observed subscription usage window, when one exists. */
  usage?: SubscriptionUsage;
}

/** One question's answer, as sent in `userInput/answer` or `userInput/interrupt` and as recorded in `userInput/settled`. */
export interface UserInputAnswer {
  /** A free-form answer, at most 500 characters. */
  freeText?: string;
  /** An optional comment the user adds to the answer, at most 500 characters. */
  note?: string;
  /** The `id` of the question this answers. */
  questionId: string;
  /** The label of the chosen option, for a `single` question. */
  selectedLabel?: string;
  /** The labels of the chosen options for a `multiple` question, within its selection bounds; omitted when empty. */
  selectedLabels?: string[];
}

/** `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 also reserved. */
export interface UserInputAnswerParams {
  /** One entry per question. */
  answers: UserInputAnswer[];
  /** The SS3.1.1 idempotency handle (UUIDv7). */
  commandId: string;
  /** The target session. */
  sessionId: string;
  /** The prompt being answered. */
  userInputId: string;
}

/** `userInput/answer` result (tdd SS5.10.2). */
export interface UserInputAnswerResult {
  /** Echoes the client's id. */
  commandId: string;
  /** Admission status. */
  status: CommandStatus;
  /** The prompt this answer settled. */
  userInputId: string;
}

/** `userInput/cancel` params (tdd SS5.10.2): decline to answer; the tool call resolves with a cancelled result the model sees. */
export interface UserInputCancelParams {
  /** The SS3.1.1 idempotency handle (UUIDv7). */
  commandId: string;
  /** Why the prompt was declined. */
  reason?: string;
  /** The target session. */
  sessionId: string;
  /** The prompt being declined. */
  userInputId: string;
}

/** `userInput/cancel` result (tdd SS5.10.2). */
export interface UserInputCancelResult {
  /** Echoes the client's id. */
  commandId: string;
  /** Admission status. */
  status: CommandStatus;
  /** The prompt this cancellation settled. */
  userInputId: string;
}

/** A free-form reply the user gives instead of choosing from the options; the model reads it and decides again. */
export interface UserInputClarification {
  /** The clarification text, at most 500 characters. */
  content: string;
  /** The content format. `text` is the only value today, and more may be added. */
  format: string;
}

/** `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. */
export interface UserInputClarifyParams {
  /** `format` is `"text"` in v1 (open); `content` is <=500 chars. */
  clarification: UserInputClarification;
  /** The SS3.1.1 idempotency handle (UUIDv7). */
  commandId: string;
  /** The target session. */
  sessionId: string;
  /** The prompt being clarified. */
  userInputId: string;
}

/** `userInput/clarify` result (tdd SS5.10.2). */
export interface UserInputClarifyResult {
  /** Echoes the client's id. */
  commandId: string;
  /** Admission status. */
  status: CommandStatus;
  /** The prompt this clarification settled. */
  userInputId: string;
}

/** `userInput/engaged` params (tdd SS5.10.4, ADR 45450 D2): a fire-and-forget engagement note — the user started interacting with a timed prompt, so the host disarms that prompt's auto-resolution countdown. No result, no errors, no `commandId`, no ledger row. */
export interface UserInputEngagedParams {
  /** The target session. */
  sessionId: string;
  /** The prompt being engaged. */
  userInputId: string;
}

/** `userInput/interrupt` params (tdd SS5.10.2, ADR 45450 D1): interrupt the named prompt carrying confirmed partial answers, then stop the turn.  `answers` is optional and, when present, follows exactly the `userInput/answer` shape and limits (same `questionId` + one-of + `note` rules, same -32057 `userInputAnswerInvalid` on mismatch); absent or empty means interrupt with no confirmed answers. */
export interface UserInputInterruptParams {
  /** Confirmed partial answers the named settlement carries. */
  answers?: UserInputAnswer[];
  /** The SS3.1.1 idempotency handle (UUIDv7). */
  commandId: string;
  /** The target session. */
  sessionId: string;
  /** The prompt being interrupted. */
  userInputId: string;
}

/** `userInput/interrupt` result (tdd SS5.10.2). */
export interface UserInputInterruptResult {
  /** Echoes the client's id. */
  commandId: string;
  /** Admission status. */
  status: CommandStatus;
  /** The prompt this interruption settled. */
  userInputId: string;
}

/** One option offered for a question. */
export interface UserInputOption {
  /** An optional longer explanation of the option, at most 240 characters. */
  description?: string;
  /** The option's text, at most 80 characters and unique within its question; an answer selects the option by this exact label. */
  label: string;
  /** An optional rich preview of the option, present only on single-select questions. */
  preview?: UserInputOptionPreview;
}

/** Rich content a client can show for an option. Only single-select questions carry previews. */
export interface UserInputOptionPreview {
  /** The preview content in that format, at most 2000 characters. */
  content: string;
  /** The content format, for example `markdown`. */
  format: string;
}

/** How a user-input prompt settled. More values may be added, so handle values you do not recognize. */
export type UserInputOutcome = "answered" | "cancelled" | "interrupted" | "clarified" | "timedOut" | "aborted" | (string & {});

/** One question in a user-input prompt. */
export interface UserInputQuestion {
  /** A short title for the question, at most 12 characters. */
  header: string;
  /** The question's id, unique within the prompt and at most 64 characters. An answer names it in `questionId`. */
  id: string;
  /** The options offered, two or three, in order. */
  options: UserInputOption[];
  /** The full question text to show the user. */
  question: string;
  /** Whether the user picks one option or several. */
  selection: UserInputSelection;
}

/** Full params shared by `userInput/request` and `userInput/requested`. */
export interface UserInputRequestParams {
  /** The auto-resolution time per question, in milliseconds: a prompt nobody engages with settles as `timedOut` after this value times the number of questions. */
  autoResolutionMs?: number;
  /** The `toolCall` view item of the tool call waiting on this prompt. */
  itemId: string;
  /** The questions to ask, one to three, in order. */
  questions: UserInputQuestion[];
  /** The session that owns the prompt. */
  sessionId: string;
  /** The stored records this prompt was folded from, when sent: an opaque token clients must not interpret. */
  sourceRange?: SourceRange;
  /** The provider's id for the tool call that opened the prompt. */
  toolCallId: string;
  /** The name of the tool that opened the prompt. */
  toolName: string;
  /** The turn whose tool call is waiting on this prompt. */
  turnId: string;
  /** The prompt's stable id. Pass it to `userInput/answer`, `userInput/cancel`, `userInput/clarify` and `userInput/interrupt`, and use it to match the later `userInput/settled`. */
  userInputId: string;
  /** The cursor of the `userInput/requested` event for this prompt. A client that missed the request can read the same payload at this cursor with `view/page`. */
  viewCursor: string;
}

/** How many options the user may pick for a question. */
export interface UserInputSelection {
  /** The most options the user may pick. Sent only in `multiple` mode; when absent the maximum is the number of options. */
  maxSelections?: number;
  /** The minimum selection count for a `multiple` answer. Sent only in `multiple` mode; when absent the minimum is 1. */
  minSelections?: number;
  /** `single` or `multiple`: whether an answer selects one option or several. */
  mode: UserInputSelectionMode;
}

/** Whether a question takes one option or several. */
export type UserInputSelectionMode = "single" | "multiple";

/** `userInput/settled` params: the first durable prompt settlement. */
export interface UserInputSettledParams {
  /** The recorded answers: one per question for `answered`, any confirmed partial answers for `interrupted`, and empty for every other outcome. */
  answers: UserInputAnswer[];
  /** The user's free-form clarification when the outcome is `clarified`; `null` otherwise. */
  clarification: UserInputClarification | null;
  /** The decision time as RFC3339, projected from the durable settlement record's own stamp (ADR 45450 D3, ruling 2026-10-01): always present on the wire (schema-required, `null`-able); decoders still tolerate its absence (`default`, never skipped — SS5.10.3 keeps every member present), and current hosts always populate it. */
  decidedAt: string | null;
  /** The `commandId` of the client command that settled the prompt; `null` when no command did, for example after a timeout or an abort. */
  decidedByCommandId: string | null;
  /** How the prompt ended. */
  outcome: UserInputOutcome;
  /** The reason, when one applies: the optional reason given with a cancel, or why an `aborted` prompt was closed; `null` otherwise. */
  reason: string | null;
  /** The session that owns the prompt. */
  sessionId: string;
  /** The stored records this event was folded from: an opaque token clients must not interpret. */
  sourceRange: SourceRange;
  /** The prompt that settled. Accept a settlement even for a prompt whose request you never saw. */
  userInputId: string;
  /** This event's view cursor: opaque, and strictly increasing within the session. */
  viewCursor: string;
}

/** Winning terminal returned to a late user-input command. */
export interface UserInputSettlementSummary {
  /** How the prompt settled, as a `userInput/settled` outcome value such as `answered` or `timedOut`. */
  outcome: string;
  /** The view cursor of the `userInput/settled` event that recorded the settlement. */
  viewCursor: string;
}

/** Version-control system of a branch observation (tdd SS4.6.4). Open. */
export type Vcs = "git" | "sapling" | (string & {});

/** `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. */
export interface ViewGapParams {
  /** The last cursor delivered before the hole — the exclusive lower bound of the undelivered range. An **opaque** view cursor: clients relay it, never parse it (tdd SS4.1). */
  after: string;
  /** The first cursor delivered after the hole — the exclusive upper bound of the undelivered range, and the position delivery continues from. An **opaque** view cursor: clients relay it, never parse it (tdd SS4.1). */
  next: string;
  /** The session whose subscription dropped events. */
  sessionId: string;
}

/** The `view/page` request-mode anchor. Declared **open**: the protocol spells it "open string enum, v1 value `latestCompaction`". */
export type ViewPageAnchor = "latestCompaction" | (string & {});

/** The `view/page` paging direction. Closed: the protocol spells exactly two values and a third would change the paging contract. */
export type ViewPageDirection = "forward" | "backward";

/** `view/page` params (tdd SS4.7.3): cursor-paged reads of the session view. */
export interface ViewPageParams {
  /** The cold-client request mode (D-029; spec 208 FR-008), resolved at call time to the latest installed compaction boundary. The one named exception to the SS4.1 observed-only rule. */
  anchor?: ViewPageAnchor;
  /** The exclusive anchor. Forward: the page starts strictly after it; omitted means from the beginning of the view. Backward: the page ends strictly before it; omitted means from the head. Mutually exclusive with `anchor` (tdd SS4.7.3; spec 208 FR-008a). */
  cursor?: string;
  /** Paging direction; `forward` when omitted. */
  direction?: ViewPageDirection;
  /** Maximum events to return, 1–1000. The server MAY return fewer.  The 1–1000 range is ratified and **published**: the model carries the bound and the bundle renders `minimum`/`maximum` instead of a bare `integer`. Range 1–1000 inclusive. */
  limit: number;
  /** The session to page. */
  sessionId: string;
}

/** The `resolvedAnchor` echo (tdd SS4.7.3): subsequent pages pass ordinary cursors, so the anchor never needs re-resolving. */
export interface ViewPageResolvedAnchor {
  /** The view cursor of the resolved boundary's `compaction` event. */
  boundaryCursor: string;
}

/** `view/page` result (tdd SS4.7.3). */
export interface ViewPageResult {
  /** The page's events, always ascending by `viewCursor` in both directions. Durable-sourced only; pages are contiguous and can never skip a cursor. */
  events: UnframedViewNotification[];
  /** The anchor for the next page in the same direction: forward, the last event's cursor; backward, the first's. `null` at the end of the view in that direction — never omitted. */
  nextCursor: string | null;
  /** The resolution echo, present exactly when the request used `anchor` (tdd SS4.7.3; spec 208 FR-008). */
  resolvedAnchor?: ViewPageResolvedAnchor;
}

/** The `snapshot` object returned by `session/resume` / `session/read` (tdd SS4.9). */
export interface ViewSnapshot {
  /** Present exactly when `history.mode` is `anchoredSnapshot` (tdd SS2.5.2). */
  anchor?: SnapshotAnchor;
  /** Snapshot schema version. A client whose generated types are older than this must fall back to inline/paged history (tdd SS4.9.2, SS2.5.2). */
  schemaVersion: number;
  /** The complete folded view at `viewCursor` (tdd SS4.9.1). */
  state: SnapshotState;
  /** The cursor the state is folded at; every event after it streams as the suffix (tdd SS4.9). */
  viewCursor: string;
}

/** `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. */
export interface ViewSubscribeParams {
  /** Resume cursor. When present, the server replays `(after, head]` as ordinary view notifications before any live event — one gapless cursor sequence. Omitted means "from now": no historical replay (tdd SS4.7.1). */
  after?: string;
  /** The session to follow. */
  sessionId: string;
}

/** `view/subscribe` result (tdd SS4.7.1). */
export interface ViewSubscribeResult {
  /** The view head at subscribe time; the client knows it is live once cursors pass it. */
  viewCursor: string;
}

/** `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). */
export interface ViewUnsubscribeParams {
  /** The session to stop following. */
  sessionId: string;
}

/** `view/unsubscribe` result (tdd SS4.7.2): the empty object. Idempotent — unsubscribing while not subscribed returns `{}`. */
export interface ViewUnsubscribeResult {
}

/** `workflow/cancel` params (tdd SS3.19): cancel a live workflow run. */
export interface WorkflowCancelParams {
  /** The SS3.1.1 idempotency handle (UUIDv7). */
  commandId: string;
  /** The target session. */
  sessionId: string;
  /** The run to cancel, exactly as the `workflow` item names it (SS4.5.8); required, non-empty. */
  workflowRunId: string;
}

/** One workflow child's folded state (tdd SS4.5.8, `WorkflowChildLifecycleFact`), keyed by `(childId, attempt)`. */
export interface WorkflowChild {
  /** The attempt number. */
  attempt: number;
  /** The child's id within the run. */
  childId: string;
  /** The child's observed duration, when recorded. */
  durationMs?: number;
  /** The attempt's machine failure class, verbatim when recorded (open, snake_case durable runtime vocabulary — the SS1.6 casing exemption). The attempt's outcome (`terminal`, else `status`) stays authoritative, except that `"completed"` with `failureKind` present means it failed (#17769). */
  failureKind?: string;
  /** The attempt's failure reason text, verbatim when recorded except cut to at most 2,048 UTF-8 bytes ending in U+2026 when longer. */
  failureReason?: string;
  /** The child's display label, when recorded. */
  label?: string;
  /** The child's phase, when recorded. */
  phase?: string;
  /** The child's recorded result reference, verbatim, when present — an opaque string, matching the durable owner. */
  resultRef?: string;
  /** camelCased `WorkflowChildLifecycleStatus`, verbatim (durable runtime vocabulary). */
  status: string;
  /** The child's terminal, turn vocabulary (tdd SS4.5.8). */
  terminal?: TurnTerminal;
  /** The child's observed usage, when recorded. */
  usage?: TokenUsage;
}

/** Which control to apply to the child's current attempt (tdd SS3.20). Closed on the wire: an unknown value is `-32602 invalidParams`. */
export type WorkflowChildAction = "skip" | "retry";

/** `workflow/childControl` params (tdd SS3.20): skip or retry one workflow child, keyed by the `(childId, attempt)` pair the `workflow` item's `children[]` carries. */
export interface WorkflowChildControlParams {
  /** The control to apply. */
  action: WorkflowChildAction;
  /** The child's CURRENT attempt (integer >= 1). A stale value rejects `"stale_attempt"`; re-read the item and re-key — never guess. Minimum 1. */
  attempt: number;
  /** The child, from the item's `children[]`; required, non-empty. */
  childId: string;
  /** The SS3.1.1 idempotency handle (UUIDv7). */
  commandId: string;
  /** The target session. */
  sessionId: string;
  /** The run owning the child (SS4.5.8); required, non-empty. */
  workflowRunId: string;
}

/** The shared SS3.19/SS3.20/SS3.32 admission-only ack: deliberately bare `{commandId, status}` — settlement arrives as the workflow item's view events, never through the ack. */
export interface WorkflowControlResult {
  /** Echoes the client's id. */
  commandId: string;
  /** Admission status. */
  status: CommandStatus;
}

/** `workflow/pause` params (tdd SS3.32, ADR 45437 D2): pause a live workflow run, shaped exactly like `workflow/cancel`. */
export interface WorkflowPauseParams {
  /** The SS3.1.1 idempotency handle (UUIDv7). */
  commandId: string;
  /** The target session. */
  sessionId: string;
  /** The run to pause, exactly as the `workflow` item names it (SS4.5.8); required, non-empty. */
  workflowRunId: string;
}

/** `workflow/resume` params (tdd SS3.34, ADR 45437 D3): resume a paused workflow run, host-driven. */
export interface WorkflowResumeParams {
  /** The SS3.1.1 idempotency handle (UUIDv7). */
  commandId: string;
  /** The target session. */
  sessionId: string;
  /** The paused run to resume, exactly as the `workflow` item names it (SS4.5.8); required, non-empty. */
  workflowRunId: string;
}

/** `workflow/resume` result (tdd SS3.34): admission-only plus the driven turn — always present, since resume always drives (idle fresh turn or busy steer). */
export interface WorkflowResumeResult {
  /** Echoes the client's id. */
  commandId: string;
  /** Admission status. */
  status: CommandStatus;
  /** The turn the host drove: the fresh resume turn on an idle session, the admission-time active turn on a busy session (a routing fact like the SS3.18 wake-gate's, not settlement). */
  turnId: string;
}

/** `workflow`: the run's launch token budget (tdd SS4.5.8, #45449). */
export interface WorkflowTokenBudget {
  /** The effective launch budget in tokens, verbatim from the launch fact. */
  total: number;
}

/** Every wire method in this schema (SS1.9 index). */
export type MspMethod = "initialize" | "subagent/sendMessage" | "subagent/followupTask" | "subagent/interrupt" | "subagent/stop" | "subagent/resume" | "subagent/reopen" | "subagent/close" | "subagent/readResult" | "session/start" | "session/resume" | "session/fork" | "session/leave" | "session/list" | "session/read" | "session/sideChat" | "turn/start" | "turn/steer" | "turn/interrupt" | "turn/cancel" | "turn/unqueue" | "session/compact" | "session/setModel" | "session/rename" | "session/setReasoningEffort" | "session/userShell" | "model/list" | "skill/list" | "skill/setActivation" | "skill/import" | "hook/list" | "plugin/list" | "plugin/install" | "plugin/marketplaceAdd" | "plugin/marketplaceUpdate" | "plugin/marketplaceRemove" | "task/background" | "task/stop" | "task/stopAll" | "task/list" | "goal/set" | "goal/edit" | "goal/clear" | "goal/pause" | "goal/resume" | "workflow/cancel" | "workflow/childControl" | "workflow/pause" | "workflow/resume" | "media/upload" | "view/subscribe" | "view/unsubscribe" | "view/page" | "item/readOutput" | "approval/decide" | "approval/listPending" | "session/setApprovalMode" | "userInput/answer" | "userInput/cancel" | "userInput/clarify" | "userInput/interrupt" | "usage/read" | "feedback/submit" | "recap/request" | "recap/cancel" | "computerUseSettings/read" | "computerUseSettings/update" | "computerUseSetup/read" | "computerUseSetup/start" | "computerUseSetup/check";
/** Every wire notification in this schema (SS1.9 index). */
export type MspNotification = "initialized" | "session/started" | "session/closed" | "session/leaveCompleted" | "skill/changed" | "turn/started" | "turn/completed" | "turn/retracted" | "turn/retryScheduled" | "turn/modelRetryScheduled" | "turn/unqueued" | "turn/foregroundCompleted" | "item/started" | "item/updated" | "item/delta" | "item/completed" | "view/gap" | "approval/requested" | "approval/updated" | "approval/reviewing" | "approval/resolved" | "userInput/requested" | "userInput/settled" | "userInput/engaged" | "session/modelChanged" | "session/reasoningEffortChanged" | "session/statusChanged" | "session/goalChanged" | "session/todoListChanged" | "session/branchChanged" | "session/tokenUsage" | "session/contextUsage" | "session/approvalModeChanged" | "recap/completed" | "session/modelRouteUnserved" | "session/nameChanged" | "session/viewHealthChanged" | "session/listChanged" | "usage/changed" | "computerUseSetup/changed" | "plugin/changed" | "plugin/marketplaceChanged" | "monitor/inboxItemAdmitted" | "monitor/inboxItemDrained" | "monitor/inboxItemVoided";
/** Every server-initiated wire request in this schema (SS5.3/SS5.10.1 index). */
export type MspServerRequest = "approval/request" | "userInput/request";
/** Every error `data.kind` in this schema's error table (SS1.6) — each code's primary kind plus its override kinds. */
export type MspErrorDataKind = "parseError" | "invalidRequest" | "notInitialized" | "alreadyInitialized" | "methodNotFound" | "experimentalRequired" | "invalidParams" | "internal" | "pageEventTooLarge" | "outputResultTooLarge" | "overloaded" | "inputTooLarge" | "capabilityRequired" | "notFound" | "interrupted" | "cancelled" | "sessionNotFound" | "sessionInUse" | "sessionAmbiguous" | "forkBoundaryInvalid" | "sessionNotLoaded" | "sessionStreamMismatch" | "commandRejected" | "backpressured" | "skillNotFound" | "computerUseUnavailable" | "marketplaceNotFound" | "pluginNotFound" | "marketplaceAlreadyExists" | "pluginMutationsDisabled" | "uploadNotFound" | "viewTruncated" | "outputUnavailable" | "boundaryPruned" | "boundaryUnusable" | "noBoundary" | "approvalNotFound" | "approvalAlreadyResolved" | "approvalChoiceInvalid" | "approvalRequirementStale" | "approvalReviewerUnavailable" | "userInputNotFound" | "userInputAlreadySettled" | "userInputAnswerInvalid";