@muse-code/sdk 0.1.1 → 1.4.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/src/msp.d.ts CHANGED
@@ -6,6 +6,7 @@
6
6
  // artifact (spec 14990 INV-008) while the tarball stays self-contained.
7
7
 
8
8
  // Muse Session Protocol (MSP) v1 TypeScript declarations.
9
+ // STABLE surface only; experimental twin: experimental/msp.d.ts.
9
10
  // Generated by tbh-protocol (spec 206) from the same schema model as
10
11
  // the JSON Schema bundle (INV-017). Do not edit by hand.
11
12
 
@@ -112,6 +113,8 @@ export interface ApprovalRequestParams {
112
113
  rawArgs: string;
113
114
  sessionId: string;
114
115
  sourceRange: SourceRange;
116
+ /** Present only for a child (native subagent) approval projected onto the parent session's plane (ADR 36182); parent-own approvals omit it. */
117
+ subagentOrigin?: ApprovalSubagentOrigin;
115
118
  subject: ApprovalSubject;
116
119
  taskId: string;
117
120
  toolCallId: string;
@@ -147,6 +150,8 @@ export interface ApprovalResolvedParams {
147
150
  sessionId: string;
148
151
  sourceRange: SourceRange;
149
152
  stageEvidence: ApprovalStageEvidence[];
153
+ /** Present only for a child (native subagent) approval projected onto the parent session's plane (ADR 36182); parent-own approvals omit it. */
154
+ subagentOrigin?: ApprovalSubagentOrigin;
150
155
  turnId: string;
151
156
  viewCursor: string;
152
157
  }
@@ -175,12 +180,22 @@ export interface ApprovalStageResolution {
175
180
  kind: string;
176
181
  }
177
182
 
183
+ /** 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. */
184
+ export interface ApprovalSubagentOrigin {
185
+ /** The child run that parked on this approval. */
186
+ childRunId: string;
187
+ /** The child session stream id whose records carry this approval. */
188
+ childSessionId: string;
189
+ /** The originating child's subagent id, from the parent session's durable subagent control records. */
190
+ subagentId: string;
191
+ }
192
+
178
193
  /** Open approval subject union. Unknown kinds are rendered generically and never auto-approved by clients (tdd SS5.2). */
179
194
  export interface ApprovalSubject {
180
195
  access?: string;
181
196
  command?: string;
182
197
  host?: string;
183
- /** Open discriminator: `shell | fileAccess | network | process | tool`. */
198
+ /** Open discriminator: `shell | fileAccess | network | unixSocket | process | tool`. */
184
199
  kind: string;
185
200
  origin?: ApprovalOrigin;
186
201
  path?: string;
@@ -205,10 +220,15 @@ export interface ApprovalUpdatedParams {
205
220
  currentRequirementId: ApprovalRequirementRef;
206
221
  sessionId: string;
207
222
  sourceRange: SourceRange;
223
+ /** Present only for a child (native subagent) approval projected onto the parent session's plane (ADR 36182); parent-own approvals omit it. */
224
+ subagentOrigin?: ApprovalSubagentOrigin;
208
225
  subject: ApprovalSubject;
209
226
  viewCursor: string;
210
227
  }
211
228
 
229
+ /** 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. */
230
+ export type AttentionFlag = "approvalPending" | "inputPending" | (string & {});
231
+
212
232
  /** Who durably backgrounded a task (tdd SS4.5.5, `TaskBackgroundedInitiator`). Open — runtime vocabulary. */
213
233
  export type BackgroundInitiator = "user" | "timeout" | (string & {});
214
234
 
@@ -223,7 +243,7 @@ export interface BranchState {
223
243
  }
224
244
 
225
245
  /** A grantable capability name (SS1.4.4). Open: the reserved `rawLog` entry joins this domain as an additive open-enum extension when SS6 un-defers (#13929, Scenario 5 AS-3) — closed would make that a retype. */
226
- export type CapabilityName = "userShell" | (string & {});
246
+ export type CapabilityName = "userShell" | "sessionMcp" | "sessionListStream" | "feedback" | (string & {});
227
247
 
228
248
  /** The client's requested capability posture (SS1.4.1). Every member defaults; an absent `capabilities` object means all defaults. */
229
249
  export interface ClientCapabilities {
@@ -233,6 +253,8 @@ export interface ClientCapabilities {
233
253
  optOutNotificationMethods?: string[];
234
254
  /** 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. */
235
255
  requestedCapabilities?: string[];
256
+ /** 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. */
257
+ userInputDialogs?: boolean;
236
258
  }
237
259
 
238
260
  /** Client identification inside `initialize` params (SS1.4.1). Diagnostics and telemetry attribution only; never an authority claim (SS1.10). */
@@ -281,8 +303,22 @@ export interface ContextUsage {
281
303
  windowTokens?: number;
282
304
  }
283
305
 
284
- /** Session running totals of counted-once usage (tdd SS4.6.5). */
306
+ /** Server-computed session cost member of [`CumulativeTokenUsage`] (tdd SS4.6.5, Amendment #41610 FR-41610-2/3). */
307
+ export interface CumulativeCost {
308
+ /** True when at least one leg lacked price data — clients render `(partial)`. */
309
+ partial: boolean;
310
+ /** Estimated USD total, finite and non-negative. */
311
+ usd: number;
312
+ }
313
+
314
+ /** Session running totals of counted-once usage (tdd SS4.6.5). Amendment #41610: 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 (INV-41610-1). `Copy` was dropped for the `cost` member. */
285
315
  export interface CumulativeTokenUsage {
316
+ /** 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. */
317
+ cacheReadTokens?: number;
318
+ /** Cache-write tokens, session total (FR-41610-1). Additive-optional like the read split. */
319
+ cacheWriteTokens?: number;
320
+ /** 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. */
321
+ cost?: CumulativeCost;
286
322
  /** Output tokens, session total. */
287
323
  outputTokens: number;
288
324
  /** Counted-once prompt tokens, session total. */
@@ -319,6 +355,8 @@ export interface ErrorData {
319
355
  anchor?: string | null;
320
356
  /** Approval identity on SS5 errors. */
321
357
  approvalId?: string;
358
+ /** 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). */
359
+ availability?: string;
322
360
  /** The missing capability, on `capabilityRequired` errors. Typed on the grantable registry, so `rawLog` is outside the v1 domain and joins it as an additive open-enum extension when SS6 un-defers (TEST-009). */
323
361
  capability?: CapabilityName;
324
362
  /** The configured command-admission bound, on `backpressured` errors. */
@@ -335,6 +373,8 @@ export interface ErrorData {
335
373
  details?: Record<string, unknown>;
336
374
  /** 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). */
337
375
  earliestCursor?: string | null;
376
+ /** The item whose stored output was requested, on the `item/readOutput` arms (`notFound`, `outputUnavailable`, and the misaligned-offset `invalidParams`). */
377
+ itemId?: string;
338
378
  /** The stable camelCase category clients branch on. */
339
379
  kind: ErrorKind;
340
380
  /** Rejected inclusive fork boundary on `forkBoundaryInvalid`. */
@@ -343,6 +383,8 @@ export interface ErrorData {
343
383
  latestBoundaryCursor?: string | null;
344
384
  /** The exceeded byte limit, on `inputTooLarge` errors. */
345
385
  limitBytes?: number;
386
+ /** The requested `outputRef.id`, on the same `item/readOutput` arms. */
387
+ outputRef?: string;
346
388
  /** Candidate retained paths on `sessionAmbiguous`. */
347
389
  paths?: string[];
348
390
  /** Failure detail vocabulary (e.g. `"missingAnchor"` on `notFound` for a missing view-cursor anchor). */
@@ -351,6 +393,8 @@ export interface ErrorData {
351
393
  resolution?: ApprovalResolutionSummary;
352
394
  /** Whether retrying can succeed (e.g. `overloaded`). When present, overrides the error table row's `retryable` default for this code. */
353
395
  retryable?: boolean;
396
+ /** The rejected skill selector on `skillNotFound` (`-32032`, SS3.22.4). */
397
+ selector?: string;
354
398
  /** Session identity on errors whose lookup is session-scoped. */
355
399
  sessionId?: string;
356
400
  /** Winning settlement on `userInputAlreadySettled`. */
@@ -362,7 +406,7 @@ export interface ErrorData {
362
406
  }
363
407
 
364
408
  /** A stable `error.data.kind` category (SS1.6): camelCase, the value clients branch on. Open: SS2–SS5 lanes add kinds additively as their methods land (Appendix B already registers them), and the spec's edge-case rule makes a new `kind` additive only because this domain is declared open. */
365
- 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" | "viewTruncated" | "boundaryPruned" | "boundaryUnusable" | "noBoundary" | "approvalNotFound" | "approvalAlreadyResolved" | "approvalChoiceInvalid" | "approvalRequirementStale" | "approvalReviewerUnavailable" | "userInputNotFound" | "userInputAlreadySettled" | "userInputAnswerInvalid" | (string & {});
409
+ 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" | "viewTruncated" | "outputUnavailable" | "boundaryPruned" | "boundaryUnusable" | "noBoundary" | "approvalNotFound" | "approvalAlreadyResolved" | "approvalChoiceInvalid" | "approvalRequirementStale" | "approvalReviewerUnavailable" | "userInputNotFound" | "userInputAlreadySettled" | "userInputAnswerInvalid" | (string & {});
366
410
 
367
411
  /** The `error` member of an error response (SS1.2 §2.4). */
368
412
  export interface ErrorObject {
@@ -384,6 +428,52 @@ export interface ErrorResponse {
384
428
  jsonrpc: JsonRpcVersion;
385
429
  }
386
430
 
431
+ /** `feedback/submit` classification (tdd SS3.25): the four TUI classes in camelCase wire spelling. **Closed**: a client-selected param vocabulary (#22785 E2). */
432
+ export type FeedbackClassification = "bug" | "badResult" | "goodResult" | "other";
433
+
434
+ /** `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. */
435
+ export type FeedbackSubmitOutcome = "uploaded" | "recorded" | "acceptedWithoutReceipt" | "trackingFailed" | "trackingUncertain" | "dark" | "disabled" | "noCredential" | "authRejected" | "rateLimited" | "failed" | (string & {});
436
+
437
+ /** `feedback/submit` params (tdd SS3.25): mirrors the TUI confirm-time `FeedbackRequest`. The call itself is the explicit confirm. */
438
+ export interface FeedbackSubmitParams {
439
+ /** Consent to attach the session record; honored only for `bug`/`badResult`. `true` with `with_files: false` or a non-`bug`/`badResult` classification is `invalidParams` (F4). Defaults to `false`. */
440
+ attachSessionRecord?: boolean;
441
+ /** The report class (required). */
442
+ classification: FeedbackClassification;
443
+ /** An absolute same-host path to a client-packed bundle, admitted only as a regular file under a size cap. */
444
+ clientArtifactsPath?: string;
445
+ /** The user report text (required; non-empty for `bug`). */
446
+ note: string;
447
+ /** Names the session this call is about (required, F3): the bundle always lands in that session's dir. Names a session this host owns; a client with no session cannot send feedback. */
448
+ sessionId: string;
449
+ /** The files-consent decision (required). */
450
+ withFiles: boolean;
451
+ }
452
+
453
+ /** `feedback/submit` result (tdd SS3.25): the upload receipt. */
454
+ export interface FeedbackSubmitResult {
455
+ /** The host-local absolute path of the always-written local bundle. */
456
+ bundlePath: string;
457
+ /** The failure cause on the `failed`, `acceptedWithoutReceipt`, `trackingFailed`, and `trackingUncertain` arms. */
458
+ cause?: string;
459
+ /** The consent-vs-reality local-tracing note, kept for display. */
460
+ localTracingNote?: string;
461
+ /** How the submit resolved. */
462
+ outcome: FeedbackSubmitOutcome;
463
+ /** The effective retry delay in milliseconds, on `rateLimited`. */
464
+ retryAfterMs?: number;
465
+ /** The consent-vs-reality session note, kept for display. */
466
+ sessionNote?: string;
467
+ /** Whether the consented session record rode at all. */
468
+ sessionRecordAttached: boolean;
469
+ /** Whether the consented session record rode shortened to fit. */
470
+ sessionRecordTruncated: boolean;
471
+ /** The internal receipt-Task id once that Task succeeds. */
472
+ taskId?: string;
473
+ /** The intake's accept id — always present on the `uploaded` arm, optional on `trackingFailed`/`trackingUncertain`; never fabricated on `recorded`. */
474
+ uploadId?: string;
475
+ }
476
+
387
477
  /** 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. */
388
478
  export interface ForkCutPoint {
389
479
  /** The last completed turn to copy, inclusive. Naming an in-progress or unknown turn fails `forkBoundaryInvalid`. */
@@ -416,6 +506,60 @@ export interface Goal {
416
506
  status: string;
417
507
  }
418
508
 
509
+ /** `goal/clear` params (tdd SS3.18). An `objective` here is an unknown field and rejects `-32602 invalidParams` — the bare verbs carry exactly this pair. */
510
+ export interface GoalClearParams {
511
+ /** The SS3.1.1 idempotency handle (UUIDv7). */
512
+ commandId: string;
513
+ /** The target session. */
514
+ sessionId: string;
515
+ }
516
+
517
+ /** 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. */
518
+ export interface GoalCommandResult {
519
+ /** Echoes the client's id. */
520
+ commandId: string;
521
+ /** Admission status. */
522
+ status: CommandStatus;
523
+ /** 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. */
524
+ turnId?: string;
525
+ }
526
+
527
+ /** `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. */
528
+ export interface GoalEditParams {
529
+ /** The SS3.1.1 idempotency handle (UUIDv7). */
530
+ commandId: string;
531
+ /** The replacement objective; same trim/non-empty rule as `goal/set`. */
532
+ objective: string;
533
+ /** The target session. */
534
+ sessionId: string;
535
+ }
536
+
537
+ /** `goal/pause` params (tdd SS3.18); shape as `goal/clear`. */
538
+ export interface GoalPauseParams {
539
+ /** The SS3.1.1 idempotency handle (UUIDv7). */
540
+ commandId: string;
541
+ /** The target session. */
542
+ sessionId: string;
543
+ }
544
+
545
+ /** `goal/resume` params (tdd SS3.18); shape as `goal/clear`. */
546
+ export interface GoalResumeParams {
547
+ /** The SS3.1.1 idempotency handle (UUIDv7). */
548
+ commandId: string;
549
+ /** The target session. */
550
+ sessionId: string;
551
+ }
552
+
553
+ /** `goal/set` params (tdd SS3.18): set the session's goal objective. */
554
+ export interface GoalSetParams {
555
+ /** The SS3.1.1 idempotency handle (UUIDv7). */
556
+ commandId: string;
557
+ /** 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). */
558
+ objective: string;
559
+ /** The target session. */
560
+ sessionId: string;
561
+ }
562
+
419
563
  /** 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". */
420
564
  export type HistoryMode = "anchoredSnapshot" | "inline" | "snapshot" | "none" | (string & {});
421
565
 
@@ -514,12 +658,16 @@ export interface Item {
514
658
  message?: string;
515
659
  /** `toolCall`: rich content the model saw beyond text; base64 is not inlined on the view (tdd SS4.5.5). */
516
660
  modelVisibleContent?: ModelVisibleContent[];
517
- /** `subagent`: objective as spawned. */
661
+ /** `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. */
518
662
  objective?: string;
519
663
  /** `compaction`: terminal only — folds installed/fallback status. */
520
664
  outcome?: CompactionOutcome;
521
665
  /** `toolCall`/`userShell`: stored-output reference; fetch the full bytes via `item/readOutput` (served by #208). */
522
666
  outputRef?: OutputRef;
667
+ /** `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). */
668
+ patchRef?: OutputRef;
669
+ /** `toolCall`: server-authored edit-family diff summary (#33025) — always beside `patchRef`; absent = no diff available (tdd SS4.5.5). */
670
+ patchSummary?: PatchSummary;
523
671
  /** `reasoning`: provider reasoning item id (e.g. `rs_...`), for provider-side correlation. */
524
672
  providerItemId?: string;
525
673
  /** `compaction`: noop/failure reason, verbatim (snake_case durable vocabulary, e.g. `"no_compactable_history"`). */
@@ -566,10 +714,10 @@ export interface Item {
566
714
  trigger?: CompactionTrigger;
567
715
  /** `workflow`: camelCased `WorkflowLaunchTriggerSource`, verbatim (durable runtime vocabulary, e.g. `"modelProposal"`). */
568
716
  triggerSource?: string;
569
- /** `true` when the server's per-surface text budget saturated a streamed surface (`agentMessage.text`, `reasoning.summary[*]`, `toolCall.visibleOutput`, `userShell.visibleOutput`); the durable full text remains in the log (tdd SS4.5.4). */
717
+ /** `true` when the server's per-surface text budget saturated a streamed surface (`agentMessage.text`, `reasoning.summary[*]`, `toolCall.visibleOutput`, `userShell.visibleOutput`), or cut a `subagent` surface (`objective`, `fallbackText`, `result.summary`, `result.text`). 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). */
570
718
  truncated?: boolean;
571
719
  /** The owning turn (== the submitting `commandId` for fresh turns, tdd SS3.1.4). `null` only for `userShell` — the one kind outside a turn (tdd SS4.5.6). */
572
- turnId?: string;
720
+ turnId?: string | null;
573
721
  /** `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). */
574
722
  usage?: TokenUsage;
575
723
  /** `toolCall`/`userShell`: bounded transcript-visible result text (budget per tdd SS4.5.4); streams via `item/delta` field `"output"`. */
@@ -607,6 +755,39 @@ export interface ItemDeltaParams {
607
755
  /** The nine v1 item kinds (tdd SS4.5.2–4.5.10). Open: a new kind is additive evolution, and clients MUST render unknown kinds generically (tdd SS4.10). */
608
756
  export type ItemKind = "userMessage" | "agentMessage" | "reasoning" | "toolCall" | "userShell" | "subagent" | "workflow" | "reminderChild" | "compaction" | (string & {});
609
757
 
758
+ /** 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. */
759
+ export type ItemReadOutputEncoding = "utf8" | "base64";
760
+
761
+ /** `item/readOutput` params (tdd SS4.7.4): byte-ranged fetch of stored full output that the view truncated — the `outputRef` fetch path SS3.9 and SS4.5.5 owe. Read-only; works on loaded and unloaded sessions; no lease. */
762
+ export interface ItemReadOutputParams {
763
+ /** The item whose stored output is fetched. */
764
+ itemId: string;
765
+ /** STORED bytes requested; default and max 6 MiB (tdd SS4.7.4). A value above the max is served at the max. */
766
+ lengthBytes?: number;
767
+ /** 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). */
768
+ offsetBytes?: number;
769
+ /** The `outputRef.id` from the item (never the `uri`; the uri is display/provenance). */
770
+ outputRef: string;
771
+ /** The session the item belongs to. */
772
+ sessionId: string;
773
+ }
774
+
775
+ /** `item/readOutput` result (tdd SS4.7.4): one stored-byte page. */
776
+ export interface ItemReadOutputResult {
777
+ /** 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). */
778
+ byteLen: number;
779
+ /** The served range, decoded per `encoding`. */
780
+ content: string;
781
+ /** How `content` encodes the stored bytes. */
782
+ encoding: ItemReadOutputEncoding;
783
+ /** `true` when this range reached the end of the stored output. */
784
+ eof: boolean;
785
+ /** The stored output's media type (e.g. `text/plain`). */
786
+ mediaType: string;
787
+ /** The STORED-byte offset this response actually served from. */
788
+ offsetBytes: number;
789
+ }
790
+
610
791
  /** `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). */
611
792
  export interface ItemStartedParams {
612
793
  /** The full item at revision 1. */
@@ -655,6 +836,8 @@ export interface ModelCatalogEntry {
655
836
  contextLimit: number | null;
656
837
  /** Cost block; `null` when the catalog source declared nothing. */
657
838
  cost: ModelCost | null;
839
+ /** 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). */
840
+ defaultReasoningEffort?: ReasoningEffort;
658
841
  /** Description; `null` when the catalog source declared nothing. */
659
842
  description: string | null;
660
843
  /** Presentation label. */
@@ -671,8 +854,12 @@ export interface ModelCatalogEntry {
671
854
  profileId: string | null;
672
855
  /** Provider routing. */
673
856
  providerId: string;
857
+ /** 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). */
858
+ reasoningEffortVariants?: ModelDescribedReasoningEffort[];
674
859
  /** Release date; `null` when the catalog source declared nothing. */
675
860
  releaseDate: string | null;
861
+ /** Complete ordered selectable efforts. Optional only for decoding older hosts; a present value is never null. Current hosts always send it. */
862
+ variants?: ModelReasoningEffortVariants;
676
863
  }
677
864
 
678
865
  /** Where a model catalog came from (tdd SS3.10). **Open**: an unrecognized value is an unknown source, not an error. */
@@ -693,6 +880,14 @@ export interface ModelCost {
693
880
  output: string;
694
881
  }
695
882
 
883
+ /** 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. */
884
+ export interface ModelDescribedReasoningEffort {
885
+ /** The catalog's per-tier display string; absent when the catalog declared none. Optional only for decoding; a present value is never null. */
886
+ description?: string;
887
+ /** The tier, in the closed D-024 vocabulary. */
888
+ tier: ReasoningEffort;
889
+ }
890
+
696
891
  /** `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. */
697
892
  export interface ModelListParams {
698
893
  /** 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). */
@@ -711,6 +906,9 @@ export interface ModelListResult {
711
906
  source: ModelCatalogSource;
712
907
  }
713
908
 
909
+ /** A complete ordered effort set, or an explicit unknown capability. */
910
+ export type ModelReasoningEffortVariants = ReasoningEffort[] | UnknownModelReasoningEffortVariants;
911
+
714
912
  /** A model selection (tdd SS3.8). Empty strings are normalized to absent. */
715
913
  export interface ModelSelection {
716
914
  /** Presentation label. */
@@ -774,6 +972,16 @@ export interface OutputRef {
774
972
  /** Whether a stored output's bytes are servable (tdd SS4.5.5). Open — durable runtime vocabulary may grow additively. */
775
973
  export type OutputRefAvailability = "available" | "missing" | "unsupported" | "accessFailed" | (string & {});
776
974
 
975
+ /** 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`. */
976
+ export interface PatchSummary {
977
+ /** Total `+`-prefixed line count across all files' hunks. */
978
+ added: number;
979
+ /** File entries in the stored patch document. */
980
+ files: number;
981
+ /** Total `-`-prefixed line count across all files' hunks. */
982
+ removed: number;
983
+ }
984
+
777
985
  /** A pending approval in the snapshot: the SS2.5.2 pointer shape plus the gated `itemId` when one exists (tdd SS4.9.1). */
778
986
  export interface PendingApprovalPointer {
779
987
  /** The pending approval's id. */
@@ -816,7 +1024,18 @@ export type PlatformFamily = "unix" | "windows";
816
1024
  export type PlatformOs = "macos" | "linux" | "windows";
817
1025
 
818
1026
  /** 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". */
819
- export type ReasoningEffort = "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "ultra";
1027
+ export type ReasoningEffort = "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max" | "ultra";
1028
+
1029
+ /** What drove a reasoning-effort default change (tdd SS4.6.9). Open; v1's only producer is `user` (an accepted `session/setReasoningEffort`). */
1030
+ export type ReasoningEffortChangeSource = "user" | "default" | "policy" | (string & {});
1031
+
1032
+ /** 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. */
1033
+ export interface ReasoningEffortState {
1034
+ /** The standing default tier — the closed SS3.2 vocabulary, spelled identically to `turn/start.reasoningEffort`. */
1035
+ reasoningEffort: ReasoningEffort;
1036
+ /** Which actor class set the default. */
1037
+ source: ReasoningEffortChangeSource;
1038
+ }
820
1039
 
821
1040
  /** One end of a [`SourceRange`]: a record's event id and its sequence number within the stream (tdd SS4.2). */
822
1041
  export interface RecordPosition {
@@ -843,6 +1062,10 @@ export interface Request {
843
1062
  /** A request id (SS1.3): client-chosen string or integer. `1` and `"1"` do not compare equal; each direction owns its own id space. */
844
1063
  export type RequestId = number | string;
845
1064
 
1065
+ /** 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. */
1066
+ export interface RequestReceipt {
1067
+ }
1068
+
846
1069
  /** 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). */
847
1070
  export interface SchemaInfo {
848
1071
  /** `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). */
@@ -865,12 +1088,22 @@ export interface Session {
865
1088
  activeTurnId: string | null;
866
1089
  /** 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). */
867
1090
  approvalMode?: EffectiveApprovalModeState;
1091
+ /** 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. */
1092
+ attention?: AttentionFlag[];
1093
+ /** 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. */
1094
+ branch?: string;
868
1095
  /** RFC3339. For a fork this is the fork session id's UUIDv7 mint instant (tdd SS2.4). */
869
1096
  createdAt: string;
1097
+ /** Derived first-user-prompt preview (tdd SS2.14.1, #27598). **Additive-optional**, omitted when underivable. */
1098
+ firstUserPrompt?: string;
870
1099
  /** `null` for root sessions; fork provenance otherwise (tdd SS2.4). */
871
1100
  forkedFrom: ForkProvenance | null;
1101
+ /** 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`. */
1102
+ lastActivityAt?: string;
872
1103
  /** The winning metadata fold's model; `null` when that record omits it. */
873
1104
  modelId: string | null;
1105
+ /** 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`. */
1106
+ name?: string;
874
1107
  /** 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. */
875
1108
  path: string;
876
1109
  /** The winning metadata fold's provider; `null` when that record omits it. */
@@ -879,6 +1112,8 @@ export interface Session {
879
1112
  sessionId: string;
880
1113
  /** Load state as this host knows it; `session/list` reports `notLoaded` for sessions loaded by *other* hosts (tdd SS2.4). */
881
1114
  status: SessionStatus;
1115
+ /** 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. */
1116
+ title?: string;
882
1117
  /** Completed-turn count from the session view fold (tdd SS2.4). */
883
1118
  turnCount: number;
884
1119
  /** RFC3339; never precedes `createdAt` (tdd SS2.4). */
@@ -921,13 +1156,26 @@ export interface SessionBranchChangedParams {
921
1156
  workspaceRoot: string;
922
1157
  }
923
1158
 
1159
+ /** `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 two orderly unload paths do, and both write the durable `SessionEnd` record first. */
1160
+ export interface SessionClosedParams {
1161
+ /** Which orderly unload path fired. */
1162
+ reason: SessionClosedReason;
1163
+ /** The unloaded session. */
1164
+ sessionId: string;
1165
+ /** 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. */
1166
+ viewCursor: string | null;
1167
+ }
1168
+
1169
+ /** 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. */
1170
+ export type SessionClosedReason = "idle" | "hostShutdown" | (string & {});
1171
+
924
1172
  /** `session/compact` params (tdd SS3.7): manually compact the session's conversation context — the `/compact` gesture. Compaction runs asynchronously; the ack is admission only. */
925
1173
  export interface SessionCompactParams {
926
1174
  /** The SS3.1.1 idempotency handle (UUIDv7). */
927
1175
  commandId: string;
928
1176
  /** The target session. */
929
1177
  sessionId: string;
930
- /** 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). */
1178
+ /** 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`. */
931
1179
  turnId?: string;
932
1180
  }
933
1181
 
@@ -941,8 +1189,10 @@ export interface SessionCompactResult {
941
1189
  status: CompactStatus;
942
1190
  }
943
1191
 
944
- /** `session/start`'s reserved `config` object (tdd SS2.5.1): no members in v1. SS2.5.1 also ratifies "unknown keys are rejected, not ignored". That is #22785 E6b, ruled and NOT exported: spec 206 INV-015 forbids it categorically and TEST-024 enforces that. The model carries the opt-in mechanism; this type does not opt in, so the published surface is unchanged. See [#23456](https://github.com/mslsrc/tbh/issues/23456). */
1192
+ /** The open configuration extension object shared by `session/start` and `session/resume` (ADR 32760 D1). Unknown keys are ignored on the wire, never rejected (tdd SS1.5.4, spec 206 INV-015; D-052 resolving [#23456](https://github.com/mslsrc/tbh/issues/23456)): the live decoder is D-042's tolerant path, and TEST-024 keeps every exported bundle free of `additionalProperties: false`. The Rust typed model's `deny_unknown_fields` is internal and never exported — the #22785 E6b closedness export applies nowhere, and the `x-msp-closed` opt-in mechanism stays inert. Recognized `mcpServers` values are typed and validated before they leave the wire boundary. */
945
1193
  export interface SessionConfig {
1194
+ /** Native MCP servers added only to this session runtime. */
1195
+ mcpServers?: Record<string, SessionMcpServerConfig>;
946
1196
  }
947
1197
 
948
1198
  /** `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). */
@@ -961,6 +1211,37 @@ export interface SessionContextUsageParams {
961
1211
  windowTokens?: number;
962
1212
  }
963
1213
 
1214
+ /** The persisted deletion terminal, separate from admission (SS3.24). The shared schema is one object. Actual failed producers send both optional fields; completed producers omit both. Clients enforce those obligations before interpreting a known outcome. Preserve unknown strings without treating them as successful completion. */
1215
+ export interface SessionDeleteCompletedParams {
1216
+ /** Idempotency key of the original deletion command. */
1217
+ commandId: string;
1218
+ /** Deletion result; an unknown value leaves the command pending. */
1219
+ outcome: SessionDeleteOutcome;
1220
+ /** Erasure evidence for a failed result; omitted for a completed result. */
1221
+ physicalChange?: SessionDeletePhysicalChange;
1222
+ /** Required for a failed result and omitted for a completed result. */
1223
+ reason?: SessionDeleteFailureReason;
1224
+ /** Session named by the original deletion command. */
1225
+ sessionId: string;
1226
+ }
1227
+
1228
+ /** Stable deletion-failure vocabulary known to this version (SS3.24). The server emits only these values. Future reason strings remain an open result vocabulary; consumers cannot infer completion from any reason. */
1229
+ export type SessionDeleteFailureReason = "ownershipUnavailable" | "sharedSource" | "writerBusy" | "unsafeSource" | "sourceChanged" | "quiescenceFailed" | "cancelled" | "storageFailure" | "cleanupIncomplete" | "unsupportedLayout" | (string & {});
1230
+
1231
+ /** Known terminal outcomes. A future outcome cannot authorize success or exit. */
1232
+ export type SessionDeleteOutcome = "completed" | "failed" | (string & {});
1233
+
1234
+ /** `session/delete` params. The host validates a non-nil legacy-valid UUID target and a UUID-v7 command identity before admission. Unknown members are ignored and do not enter the normalized command identity (SS1.5.4). */
1235
+ export interface SessionDeleteParams {
1236
+ /** UUID-v7 idempotency key for this deletion command. */
1237
+ commandId: string;
1238
+ /** Non-nil UUID of the session selected for deletion. */
1239
+ sessionId: string;
1240
+ }
1241
+
1242
+ /** The failed attempt's immutable snapshot of persisted physical evidence. `possible` is recorded before a detach/unlink, `confirmed` after a proved owned effect. A failure never resets that evidence merely because the session path is absent. Unknown strings remain representable; consumers must treat them conservatively as `possible`. */
1243
+ export type SessionDeletePhysicalChange = "none" | "possible" | "confirmed" | (string & {});
1244
+
964
1245
  /** 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. */
965
1246
  export type SessionDurability = "durable" | "ephemeral" | (string & {});
966
1247
 
@@ -1012,10 +1293,34 @@ export interface SessionHistory {
1012
1293
  snapshot: ViewSnapshot | null;
1013
1294
  }
1014
1295
 
1296
+ /** Exact branch selection (#42035 FR-42035-2). */
1297
+ export interface SessionListBranchFilter {
1298
+ /** 1–32 nonempty branch names, each 1–256 UTF-8 bytes, counted before deduplication; `null` selects sessions with no branch. */
1299
+ anyOf: (string | null)[];
1300
+ }
1301
+
1302
+ /** `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`. */
1303
+ export interface SessionListChangedParams {
1304
+ /** The served list row for the changed session. */
1305
+ session: Session;
1306
+ }
1307
+
1308
+ /** 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`. */
1309
+ export interface SessionListFilter {
1310
+ /** Only sessions whose branch is one of these. */
1311
+ branch?: SessionListBranchFilter;
1312
+ /** Only sessions whose ID is one of these. */
1313
+ sessionId?: SessionListSessionIdFilter;
1314
+ /** Only sessions whose served name or title matches these token prefixes. */
1315
+ text?: SessionListTextFilter;
1316
+ }
1317
+
1015
1318
  /** `session/list` params (tdd SS2.5.4). Read-only; never touches leases. */
1016
1319
  export interface SessionListParams {
1017
1320
  /** 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). */
1018
1321
  cursor?: string | null;
1322
+ /** 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. */
1323
+ filter?: SessionListFilter;
1019
1324
  /** Page size; default 50, max 200 — the cap is published under #22785 E6c (owner-ruled 2026-08-26). Maximum 200. */
1020
1325
  limit?: number;
1021
1326
  /** Only sessions with log activity after this RFC3339 instant. */
@@ -1026,12 +1331,42 @@ export interface SessionListParams {
1026
1331
 
1027
1332
  /** `session/list` result (tdd SS2.5.4). Ordering is `updatedAt` descending. */
1028
1333
  export interface SessionListResult {
1334
+ /** 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. */
1335
+ appliedFilter?: SessionListFilter;
1029
1336
  /** The next page's cursor; `null` on the last page. */
1030
1337
  nextCursor: string | null;
1031
1338
  /** The page of stored sessions. */
1032
1339
  sessions: Session[];
1033
1340
  }
1034
1341
 
1342
+ /** Exact session-ID selection (#42035 FR-42035-2). */
1343
+ export interface SessionListSessionIdFilter {
1344
+ /** 1–200 session UUIDs, counted before deduplication. */
1345
+ anyOf: string[];
1346
+ }
1347
+
1348
+ /** A served session field `session/list` text search reads (#42035 FR-42035-3). The client selects it, so the set is closed. */
1349
+ export type SessionListTextField = "name" | "title";
1350
+
1351
+ /** 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. */
1352
+ export interface SessionListTextFilter {
1353
+ /** Every term must match at least one selected field. */
1354
+ allOf?: string[];
1355
+ /** 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. */
1356
+ anyOf?: string[];
1357
+ /** The 1–2 unique served fields searched. */
1358
+ fields: SessionListTextField[];
1359
+ }
1360
+
1361
+ /** 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. */
1362
+ 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; };
1363
+
1364
+ /** Startup failure posture for a session MCP server. */
1365
+ export type SessionMcpServerMode = "required" | "optional";
1366
+
1367
+ /** Stdio framing choices exposed by session MCP configuration. */
1368
+ export type SessionMcpStdioFraming = "auto" | "contentLength" | "lineDelimitedJson";
1369
+
1035
1370
  /** `session/modelChanged` params (tdd SS4.6.1): a durable model-selection record landed (tdd SS3.8). */
1036
1371
  export interface SessionModelChangedParams {
1037
1372
  /** The selected model. */
@@ -1048,6 +1383,36 @@ export interface SessionModelChangedParams {
1048
1383
  viewCursor: string;
1049
1384
  }
1050
1385
 
1386
+ /** `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. */
1387
+ export interface SessionModelRouteUnservedParams {
1388
+ /** The command whose accepted swap installed the provider. */
1389
+ commandId: string;
1390
+ /** The provider id the swap installed. */
1391
+ installedProviderId: string;
1392
+ /** The standing (still bound, now unroutable) model. */
1393
+ modelId: string;
1394
+ /** The standing model's provider; `null` when the selection names none. */
1395
+ providerId?: string;
1396
+ /** The owning session. */
1397
+ sessionId: string;
1398
+ /** The durable records this event folded from. */
1399
+ sourceRange: SourceRange;
1400
+ /** Opaque, strictly monotonic view cursor (tdd SS4.1). */
1401
+ viewCursor: string;
1402
+ }
1403
+
1404
+ /** `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. */
1405
+ export interface SessionNameChangedParams {
1406
+ /** The new canonical name now in effect. */
1407
+ name: string;
1408
+ /** The owning session. */
1409
+ sessionId: string;
1410
+ /** The durable records this event folded from. */
1411
+ sourceRange: SourceRange;
1412
+ /** Opaque, strictly monotonic view cursor (tdd SS4.1). */
1413
+ viewCursor: string;
1414
+ }
1415
+
1051
1416
  /** `session/read` params (tdd SS2.5.5): read one stored session **without attaching** — no writer lease, no load, no subscription, no `SessionResumed` record. */
1052
1417
  export interface SessionReadParams {
1053
1418
  /** 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). */
@@ -1068,10 +1433,46 @@ export interface SessionReadResult {
1068
1433
  viewCursor: string;
1069
1434
  }
1070
1435
 
1436
+ /** `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). */
1437
+ export interface SessionReasoningEffortChangedParams {
1438
+ /** The new session default: the closed eight-string tier vocabulary of tdd SS3.2, spelled identically. */
1439
+ reasoningEffort: ReasoningEffort;
1440
+ /** The owning session. */
1441
+ sessionId: string;
1442
+ /** What drove the change. */
1443
+ source: ReasoningEffortChangeSource;
1444
+ /** The durable records this event folded from. */
1445
+ sourceRange: SourceRange;
1446
+ /** Opaque, strictly monotonic view cursor (tdd SS4.1). */
1447
+ viewCursor: string;
1448
+ }
1449
+
1450
+ /** `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. */
1451
+ export interface SessionRenameParams {
1452
+ /** The SS3.1.1 idempotency handle (UUIDv7). */
1453
+ commandId: string;
1454
+ /** The requested name; the runtime's normalization and validation apply. */
1455
+ name: string;
1456
+ /** The target session. */
1457
+ sessionId: string;
1458
+ }
1459
+
1460
+ /** `session/rename` result (tdd SS2.14.2, #27598): `name` is the canonical (normalized) name the durable record settled. */
1461
+ export interface SessionRenameResult {
1462
+ /** Echoes the client's id. */
1463
+ commandId: string;
1464
+ /** 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). */
1465
+ name?: string;
1466
+ /** Admission status. */
1467
+ status: CommandStatus;
1468
+ }
1469
+
1071
1470
  /** `session/resume` params (tdd SS2.5.2). */
1072
1471
  export interface SessionResumeParams {
1073
1472
  /** The SS2.5 idempotency handle (UUIDv7). A resume that loads a session writes a durable `SessionResumed` record. */
1074
1473
  commandId: string;
1474
+ /** The same open construction-time extension object as `session/start`. */
1475
+ config?: SessionConfig;
1075
1476
  /** A view cursor previously observed by this client — or an observed `summarizedThrough` compaction anchor (tdd SS4.5.10, D-029). When present the server returns only the suffix and `history.mode` is `none` (tdd SS2.5.2). Omitted and explicit `null` both mean "no cursor" (#23468). */
1076
1477
  cursor?: string | null;
1077
1478
  /** Return only session metadata and live resume state; page history separately with `view/page`. Default `false` (tdd SS2.5.2). */
@@ -1090,7 +1491,7 @@ export interface SessionResumeResult {
1090
1491
  pendingRequests: PendingRequestPointer[];
1091
1492
  /** The loaded session. */
1092
1493
  session: Session;
1093
- /** The session view head; the connection is subscribed after it. */
1494
+ /** 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). */
1094
1495
  viewCursor: string;
1095
1496
  }
1096
1497
 
@@ -1134,13 +1535,31 @@ export interface SessionSetModelResult {
1134
1535
  status: CommandStatus;
1135
1536
  }
1136
1537
 
1538
+ /** `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). */
1539
+ export interface SessionSetReasoningEffortParams {
1540
+ /** The SS3.1.1 idempotency handle (UUIDv7). */
1541
+ commandId: string;
1542
+ /** 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). */
1543
+ reasoningEffort: ReasoningEffort;
1544
+ /** The target session. */
1545
+ sessionId: string;
1546
+ }
1547
+
1548
+ /** `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. */
1549
+ export interface SessionSetReasoningEffortResult {
1550
+ /** Echoes the client's id. */
1551
+ commandId: string;
1552
+ /** Admission status. */
1553
+ status: CommandStatus;
1554
+ }
1555
+
1137
1556
  /** `session/start` params (tdd SS2.5.1). */
1138
1557
  export interface SessionStartParams {
1139
1558
  /** 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). */
1140
1559
  approvalMode?: ApprovalMode | null;
1141
1560
  /** The SS2.5 idempotency handle (UUIDv7). Required; the server never mints one. */
1142
1561
  commandId: string;
1143
- /** Reserved for per-session overrides owned by a future Configuration section, which is why [`SessionConfig`] declares no members. */
1562
+ /** Reserved for per-session overrides owned by a future Configuration section. Issue #32760 admits only its `mcpServers` member. */
1144
1563
  config?: SessionConfig;
1145
1564
  /** Initial model; server default when omitted. */
1146
1565
  modelId?: string;
@@ -1150,6 +1569,8 @@ export interface SessionStartParams {
1150
1569
  sessionId?: string;
1151
1570
  /** Absolute path, folded into the first metadata record. */
1152
1571
  workspaceRoot?: string;
1572
+ /** 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). */
1573
+ workspaceRoots?: string[];
1153
1574
  }
1154
1575
 
1155
1576
  /** `session/start` result (tdd SS2.5.1). */
@@ -1160,9 +1581,27 @@ export interface SessionStartResult {
1160
1581
  viewCursor: string;
1161
1582
  }
1162
1583
 
1584
+ /** `session/started` params (tdd SS2.6.1; enrolled by #33065): a session became newly loaded on this host via `session/start` or `session/fork` (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`). */
1585
+ export interface SessionStartedParams {
1586
+ /** The newly loaded session, as of the start/fork fold. */
1587
+ session: Session;
1588
+ }
1589
+
1163
1590
  /** A session's load state (tdd SS2.4). */
1164
1591
  export type SessionStatus = "notLoaded" | "idle" | "running" | (string & {});
1165
1592
 
1593
+ /** `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). */
1594
+ export interface SessionStatusChangedParams {
1595
+ /** Attention flags after the transition; present only when at least one flag is set (tdd SS2.4, ADR 31983 D3). */
1596
+ attention?: AttentionFlag[];
1597
+ /** The owning session. */
1598
+ sessionId: string;
1599
+ /** Load state after the transition (the closed SS2.4 enum, unchanged). */
1600
+ status: SessionStatus;
1601
+ /** 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. */
1602
+ viewCursor: string | null;
1603
+ }
1604
+
1166
1605
  /** `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. */
1167
1606
  export interface SessionTodoListChangedParams {
1168
1607
  /** The full todo list, replaced wholesale. */
@@ -1223,6 +1662,56 @@ export interface SessionUserShellResult {
1223
1662
  status: CommandStatus;
1224
1663
  }
1225
1664
 
1665
+ /** 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. */
1666
+ export type SessionViewHealth = "unavailable" | (string & {});
1667
+
1668
+ /** `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). */
1669
+ export interface SessionViewHealthChangedParams {
1670
+ /** The new view-health state. In v1 the host emits only `Unavailable`. */
1671
+ health: SessionViewHealth;
1672
+ /** 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. */
1673
+ noneReason?: HistoryNoneReason;
1674
+ /** The session whose live view health changed. */
1675
+ sessionId: string;
1676
+ }
1677
+
1678
+ /** 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. */
1679
+ export interface SkillCatalogEntry {
1680
+ /** Present when the skill declares an argument hint. */
1681
+ argumentHint?: string;
1682
+ /** The skill's palette summary. */
1683
+ description: string;
1684
+ /** The skill display name the first-party palette shows. */
1685
+ displayName: string;
1686
+ /** The owning plugin's identifier; present when `source` is `plugin`. */
1687
+ pluginId?: string;
1688
+ /** 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. */
1689
+ selector: string;
1690
+ /** Where the skill comes from. */
1691
+ source: SkillSource;
1692
+ }
1693
+
1694
+ /** `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). */
1695
+ export interface SkillChangedParams {
1696
+ /** The session whose set changed. */
1697
+ sessionId: string;
1698
+ }
1699
+
1700
+ /** `skill/list` params (tdd SS3.22.1). Per-session because skill scope follows the session's workspace and plugin state. */
1701
+ export interface SkillListParams {
1702
+ /** The target session. */
1703
+ sessionId: string;
1704
+ }
1705
+
1706
+ /** `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). */
1707
+ export interface SkillListResult {
1708
+ /** The session's user-invocable skill rows. */
1709
+ skills: SkillCatalogEntry[];
1710
+ }
1711
+
1712
+ /** 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. */
1713
+ export type SkillSource = "bundled" | "user" | "project" | "plugin" | (string & {});
1714
+
1226
1715
  /** The compaction boundary an anchored snapshot is anchored at (tdd SS2.5.2). */
1227
1716
  export interface SnapshotAnchor {
1228
1717
  /** The view cursor of the boundary's `compaction` event. */
@@ -1247,12 +1736,16 @@ export interface SnapshotState {
1247
1736
  goal: Goal | null;
1248
1737
  /** 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). */
1249
1738
  items: Item[];
1739
+ /** 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. */
1740
+ name?: string;
1250
1741
  /** The pending-approval half of the pending set. */
1251
1742
  pendingApprovals: PendingApprovalPointer[];
1252
1743
  /** The pending-user-input half of the pending set. */
1253
1744
  pendingUserInputs: PendingUserInputPointer[];
1254
1745
  /** Admitted-but-not-launched submits, in launch order (tdd SS3.1.4). */
1255
1746
  queuedTurns: TurnRef[];
1747
+ /** 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). */
1748
+ reasoningEffort?: ReasoningEffortState;
1256
1749
  /** Latest todo list; `null` when no fact has landed. */
1257
1750
  todoList: TodoListState | null;
1258
1751
  /** The `cumulative` block of the last `session/tokenUsage` event; zeroes when none (tdd SS4.9.1). */
@@ -1316,9 +1809,9 @@ export interface SubagentResult {
1316
1809
  evidenceRefs: string[];
1317
1810
  /** Structured result data, verbatim, when present. */
1318
1811
  structuredData?: Record<string, unknown>;
1319
- /** Bounded result summary (<=512 chars, runtime-enforced). */
1812
+ /** 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. */
1320
1813
  summary: string;
1321
- /** Result text (<=32 KiB), when present. */
1814
+ /** Result text, when present, bounded on the wire at the same 64 KiB budget (ADR 35691 D9); a cut sets the item's `truncated`. */
1322
1815
  text?: string;
1323
1816
  }
1324
1817
 
@@ -1332,6 +1825,36 @@ export interface SubagentTargetParams {
1332
1825
  subagentId: string;
1333
1826
  }
1334
1827
 
1828
+ /** 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). */
1829
+ export interface SubscriptionUsage {
1830
+ /** When the host RECEIVED this observation (frame arrival or mint request-send), epoch milliseconds. */
1831
+ observedAtMs: number;
1832
+ /** The provider's subscription tier id, verbatim. */
1833
+ tier: string;
1834
+ /** The rolling weekly block. */
1835
+ weekly: SubscriptionUsageWeekly;
1836
+ /** The current window. */
1837
+ window: SubscriptionUsageWindow;
1838
+ }
1839
+
1840
+ /** The rolling weekly block: same semantics as [`SubscriptionUsageWindow`] without a duration (ADR 32563 D2). */
1841
+ export interface SubscriptionUsageWeekly {
1842
+ /** When the weekly window resets, epoch milliseconds. */
1843
+ resetsAtMs: number;
1844
+ /** Percent of the weekly budget used (integer ≥ 0, may exceed 100). */
1845
+ usedPercent: number;
1846
+ }
1847
+
1848
+ /** 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). */
1849
+ export interface SubscriptionUsageWindow {
1850
+ /** When the window resets, epoch milliseconds. */
1851
+ resetsAtMs: number;
1852
+ /** Percent of the window's budget used: an integer ≥ 0, verbatim from the provider — over-quota values above 100 are valid. */
1853
+ usedPercent: number;
1854
+ /** The window's length in minutes (> 0). */
1855
+ windowDurationMins: number;
1856
+ }
1857
+
1335
1858
  /** A success response frame (SS1.2 §2.3). */
1336
1859
  export interface SuccessResponse {
1337
1860
  /** Echo of the request id. */
@@ -1342,6 +1865,52 @@ export interface SuccessResponse {
1342
1865
  result: Record<string, unknown>;
1343
1866
  }
1344
1867
 
1868
+ /** `task/background` params (tdd §3.13): durably send a running foreground tool task to the background. */
1869
+ export interface TaskBackgroundParams {
1870
+ /** The SS3.1.1 idempotency handle (UUIDv7). */
1871
+ commandId: string;
1872
+ /** The target session. */
1873
+ sessionId: string;
1874
+ /** The task to background, exactly as the view names it: the `toolCall` item's `itemId` IS the task id (SS4.5.5). */
1875
+ taskId: string;
1876
+ }
1877
+
1878
+ /** The `task/background` / `task/stop` ack (tdd §3.13/§3.14): admission-only, echoing the targeted task. */
1879
+ export interface TaskCommandResult {
1880
+ /** Echoes the client's id. */
1881
+ commandId: string;
1882
+ /** Admission status. */
1883
+ status: CommandStatus;
1884
+ /** Echoes the targeted task id. */
1885
+ taskId: string;
1886
+ }
1887
+
1888
+ /** `task/stopAll` params (tdd §3.15): stop every stoppable background workload live at admission. */
1889
+ export interface TaskStopAllParams {
1890
+ /** The SS3.1.1 idempotency handle (UUIDv7). */
1891
+ commandId: string;
1892
+ /** The target session. */
1893
+ sessionId: string;
1894
+ }
1895
+
1896
+ /** 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. */
1897
+ export interface TaskStopAllResult {
1898
+ /** Echoes the client's id. */
1899
+ commandId: string;
1900
+ /** Admission status. */
1901
+ status: CommandStatus;
1902
+ }
1903
+
1904
+ /** `task/stop` params (tdd §3.14): stop one named background task. Required target, never "whichever is loudest" — §3.15 is the blanket verb. */
1905
+ export interface TaskStopParams {
1906
+ /** The SS3.1.1 idempotency handle (UUIDv7). */
1907
+ commandId: string;
1908
+ /** The target session. */
1909
+ sessionId: string;
1910
+ /** The task to stop, the `toolCall` item's `itemId` (SS4.5.5). */
1911
+ taskId: string;
1912
+ }
1913
+
1345
1914
  /** One todo entry (tdd SS4.6.3). */
1346
1915
  export interface TodoItem {
1347
1916
  /** Present-tense active form, when the tool supplied one. */
@@ -1395,7 +1964,7 @@ export interface TurnCancelParams {
1395
1964
  commandId: string;
1396
1965
  /** The target session. */
1397
1966
  sessionId: string;
1398
- /** The exact turn to cancel; omit to target the current foreground turn. */
1967
+ /** 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`. */
1399
1968
  turnId?: string;
1400
1969
  }
1401
1970
 
@@ -1444,16 +2013,20 @@ export interface TurnError {
1444
2013
  }
1445
2014
 
1446
2015
  /** Turn failure classes (tdd SS4.5.1, `TerminalErrorKind` plus the model-task failure class). Open. */
1447
- export type TurnErrorKind = "stepLimit" | "configError" | "projectionError" | "logError" | "workflowLaunchError" | "environmentError" | "modelError" | "launchError" | (string & {});
2016
+ export type TurnErrorKind = "stepLimit" | "configError" | "projectionError" | "logError" | "workflowLaunchError" | "environmentError" | "modelError" | "launchError" | "authRequired" | (string & {});
1448
2017
 
1449
2018
  /** One ordered content part of a turn submission (tdd SS3.2). File mentions are text, not a part type: write `@relative/path` in a text part. A structured `mention` part is reserved and currently rejected, and an unknown part type is `invalidParams` (tdd SS3.1.2, SS3.2) — which is what closes [`TurnInputPartType`]. Modelled as a discriminated flat object rather than a Rust `enum`, the convention [`crate::view::approval::ApprovalSubject`] already established for a wire union in this crate: the v1 schema model names no object-variant union shape and fails closed on one. The serialized JSON is the tdd shape either way; what a flat object cannot express is "`mediaType` is required exactly when `type` is `image`". **RULED (#22785 E4, owner, 2026-08-26): the precedent is accepted.** A strict union node kind may be funded later as a follow-up; if it is, it must cover [`crate::method::lifecycle::PendingRequestPointer`] too. `height` may only appear together with `width`. `width` may only appear together with `height`. */
1450
2019
  export interface TurnInputPart {
2020
+ /** 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). */
2021
+ arguments?: string;
1451
2022
  /** Base64 payload, required on an `image` part. Invalid base64 or an empty payload is rejected with invalid params. */
1452
2023
  base64Data?: string;
1453
2024
  /** Pixel height; must be provided together with `width` or not at all (tdd SS3.2, #22785 E6c). */
1454
2025
  height?: number;
1455
2026
  /** Media type, required on an `image` part. */
1456
2027
  mediaType?: string;
2028
+ /** 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. */
2029
+ selector?: string;
1457
2030
  /** User prompt text, on a `text` part. Multiple text parts are joined in order into the turn's prompt. */
1458
2031
  text?: string;
1459
2032
  /** The part type. */
@@ -1463,7 +2036,7 @@ export interface TurnInputPart {
1463
2036
  }
1464
2037
 
1465
2038
  /** The `type` discriminator of a turn input part (tdd SS3.2). Closed: an unknown part type is `invalidParams` (tdd SS3.1.2). */
1466
- export type TurnInputPartType = "text" | "image";
2039
+ export type TurnInputPartType = "text" | "image" | "skill";
1467
2040
 
1468
2041
  /** `turn/interrupt` params (tdd SS3.4): the "user pressed stop" gesture, on the runtime's priority lane. */
1469
2042
  export interface TurnInterruptParams {
@@ -1473,7 +2046,7 @@ export interface TurnInterruptParams {
1473
2046
  retract?: boolean;
1474
2047
  /** The target session. */
1475
2048
  sessionId: string;
1476
- /** 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). */
2049
+ /** 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`. */
1477
2050
  turnId?: string;
1478
2051
  }
1479
2052
 
@@ -1548,6 +2121,8 @@ export interface TurnStartParams {
1548
2121
  reasoningEffort?: ReasoningEffort;
1549
2122
  /** The target session. */
1550
2123
  sessionId: string;
2124
+ /** 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). */
2125
+ workspaceRoots?: string[];
1551
2126
  }
1552
2127
 
1553
2128
  /** `turn/start` result (tdd SS3.2). */
@@ -1582,7 +2157,7 @@ export interface TurnStartedParams {
1582
2157
  export interface TurnSteerParams {
1583
2158
  /** The SS3.1.1 idempotency handle (UUIDv7). */
1584
2159
  commandId: string;
1585
- /** 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). */
2160
+ /** 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. */
1586
2161
  expectedTurnId: string;
1587
2162
  /** Same content parts as `turn/start`. */
1588
2163
  input: TurnInputPart[];
@@ -1611,7 +2186,7 @@ export interface TurnUnqueueParams {
1611
2186
  commandId: string;
1612
2187
  /** The target session. */
1613
2188
  sessionId: string;
1614
- /** 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). */
2189
+ /** 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`. */
1615
2190
  turnId: string;
1616
2191
  }
1617
2192
 
@@ -1657,6 +2232,15 @@ export interface UnframedViewNotificationParams {
1657
2232
  viewCursor: string;
1658
2233
  }
1659
2234
 
2235
+ /** The only scalar alternative to a known effort array. Kept as a closed singleton so arbitrary strings and uppercase spellings fail decoding. */
2236
+ export type UnknownModelReasoningEffortVariants = "unknown";
2237
+
2238
+ /** `usage/read` result: `{usage?}` — omitted, never `null`, when the host has observed nothing (ADR 32563 D2: truthful absence, no "nothing observed" error). */
2239
+ export interface UsageReadResult {
2240
+ /** The last-observed subscription usage window, when one exists. */
2241
+ usage?: SubscriptionUsage;
2242
+ }
2243
+
1660
2244
  export interface UserInputAnswer {
1661
2245
  freeText?: string;
1662
2246
  note?: string;
@@ -1859,6 +2443,20 @@ export interface ViewSnapshot {
1859
2443
  viewCursor: string;
1860
2444
  }
1861
2445
 
2446
+ /** `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. */
2447
+ export interface ViewSubscribeParams {
2448
+ /** 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). */
2449
+ after?: string;
2450
+ /** The session to follow. */
2451
+ sessionId: string;
2452
+ }
2453
+
2454
+ /** `view/subscribe` result (tdd SS4.7.1). */
2455
+ export interface ViewSubscribeResult {
2456
+ /** The view head at subscribe time; the client knows it is live once cursors pass it. */
2457
+ viewCursor: string;
2458
+ }
2459
+
1862
2460
  /** `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). */
1863
2461
  export interface ViewUnsubscribeParams {
1864
2462
  /** The session to stop following. */
@@ -1869,6 +2467,16 @@ export interface ViewUnsubscribeParams {
1869
2467
  export interface ViewUnsubscribeResult {
1870
2468
  }
1871
2469
 
2470
+ /** `workflow/cancel` params (tdd SS3.19): cancel a live workflow run. */
2471
+ export interface WorkflowCancelParams {
2472
+ /** The SS3.1.1 idempotency handle (UUIDv7). */
2473
+ commandId: string;
2474
+ /** The target session. */
2475
+ sessionId: string;
2476
+ /** The run to cancel, exactly as the `workflow` item names it (SS4.5.8); required, non-empty. */
2477
+ workflowRunId: string;
2478
+ }
2479
+
1872
2480
  /** One workflow child's folded state (tdd SS4.5.8, `WorkflowChildLifecycleFact`), keyed by `(childId, attempt)`. */
1873
2481
  export interface WorkflowChild {
1874
2482
  /** The attempt number. */
@@ -1891,9 +2499,38 @@ export interface WorkflowChild {
1891
2499
  usage?: TokenUsage;
1892
2500
  }
1893
2501
 
2502
+ /** Which control to apply to the child's current attempt (tdd SS3.20). Closed on the wire: an unknown value is `-32602 invalidParams`. */
2503
+ export type WorkflowChildAction = "skip" | "retry";
2504
+
2505
+ /** `workflow/childControl` params (tdd SS3.20): skip or retry one workflow child, keyed by the `(childId, attempt)` pair the `workflow` item's `children[]` carries. */
2506
+ export interface WorkflowChildControlParams {
2507
+ /** The control to apply. */
2508
+ action: WorkflowChildAction;
2509
+ /** The child's CURRENT attempt (integer >= 1). A stale value rejects `"stale_attempt"`; re-read the item and re-key — never guess. Minimum 1. */
2510
+ attempt: number;
2511
+ /** The child, from the item's `children[]`; required, non-empty. */
2512
+ childId: string;
2513
+ /** The SS3.1.1 idempotency handle (UUIDv7). */
2514
+ commandId: string;
2515
+ /** The target session. */
2516
+ sessionId: string;
2517
+ /** The run owning the child (SS4.5.8); required, non-empty. */
2518
+ workflowRunId: string;
2519
+ }
2520
+
2521
+ /** The shared SS3.19/SS3.20 admission-only ack: deliberately bare `{commandId, status}` — settlement arrives as the workflow item's view events, never through the ack. */
2522
+ export interface WorkflowControlResult {
2523
+ /** Echoes the client's id. */
2524
+ commandId: string;
2525
+ /** Admission status. */
2526
+ status: CommandStatus;
2527
+ }
2528
+
1894
2529
  /** Every wire method in this schema (SS1.9 index). */
1895
- 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/list" | "session/read" | "turn/start" | "turn/steer" | "turn/interrupt" | "turn/cancel" | "turn/unqueue" | "session/compact" | "session/setModel" | "session/userShell" | "model/list" | "view/unsubscribe" | "view/page" | "approval/decide" | "approval/listPending" | "session/setApprovalMode" | "userInput/answer" | "userInput/cancel" | "userInput/clarify";
2530
+ 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/list" | "session/read" | "turn/start" | "turn/steer" | "turn/interrupt" | "turn/cancel" | "turn/unqueue" | "session/compact" | "session/delete" | "session/setModel" | "session/rename" | "session/setReasoningEffort" | "session/userShell" | "model/list" | "skill/list" | "task/background" | "task/stop" | "task/stopAll" | "goal/set" | "goal/edit" | "goal/clear" | "goal/pause" | "goal/resume" | "workflow/cancel" | "workflow/childControl" | "view/subscribe" | "view/unsubscribe" | "view/page" | "item/readOutput" | "approval/decide" | "approval/listPending" | "session/setApprovalMode" | "userInput/answer" | "userInput/cancel" | "userInput/clarify" | "usage/read" | "feedback/submit";
1896
2531
  /** Every wire notification in this schema (SS1.9 index). */
1897
- export type MspNotification = "initialized" | "turn/started" | "turn/completed" | "turn/retracted" | "turn/retryScheduled" | "turn/unqueued" | "item/started" | "item/updated" | "item/delta" | "item/completed" | "view/gap" | "approval/requested" | "approval/updated" | "approval/resolved" | "userInput/requested" | "userInput/settled" | "session/modelChanged" | "session/goalChanged" | "session/todoListChanged" | "session/branchChanged" | "session/tokenUsage" | "session/contextUsage" | "session/approvalModeChanged";
2532
+ export type MspNotification = "initialized" | "session/started" | "session/closed" | "session/deleteCompleted" | "skill/changed" | "turn/started" | "turn/completed" | "turn/retracted" | "turn/retryScheduled" | "turn/unqueued" | "item/started" | "item/updated" | "item/delta" | "item/completed" | "view/gap" | "approval/requested" | "approval/updated" | "approval/resolved" | "userInput/requested" | "userInput/settled" | "session/modelChanged" | "session/reasoningEffortChanged" | "session/statusChanged" | "session/goalChanged" | "session/todoListChanged" | "session/branchChanged" | "session/tokenUsage" | "session/contextUsage" | "session/approvalModeChanged" | "session/modelRouteUnserved" | "session/nameChanged" | "session/viewHealthChanged" | "session/listChanged" | "usage/changed";
2533
+ /** Every server-initiated wire request in this schema (SS5.3/SS5.10.1 index). */
2534
+ export type MspServerRequest = "approval/request" | "userInput/request";
1898
2535
  /** Every error `data.kind` in this schema's error table (SS1.6) — each code's primary kind plus its override kinds. */
1899
- 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" | "viewTruncated" | "boundaryPruned" | "boundaryUnusable" | "noBoundary" | "approvalNotFound" | "approvalAlreadyResolved" | "approvalChoiceInvalid" | "approvalRequirementStale" | "approvalReviewerUnavailable" | "userInputNotFound" | "userInputAlreadySettled" | "userInputAnswerInvalid";
2536
+ 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" | "viewTruncated" | "outputUnavailable" | "boundaryPruned" | "boundaryUnusable" | "noBoundary" | "approvalNotFound" | "approvalAlreadyResolved" | "approvalChoiceInvalid" | "approvalRequirementStale" | "approvalReviewerUnavailable" | "userInputNotFound" | "userInputAlreadySettled" | "userInputAnswerInvalid";