@muse-code/sdk 1.4.2 → 1.4.4

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
@@ -142,6 +142,8 @@ export type ApprovalResolvedBy = "user" | "policy" | "llmJudge" | (string & {});
142
142
  export interface ApprovalResolvedParams {
143
143
  amendment?: ApprovalAmendment;
144
144
  approvalId: string;
145
+ /** 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. */
146
+ decidedAt?: string;
145
147
  decidedByCommandId?: string;
146
148
  decision: ApprovalDecision;
147
149
  itemId: string;
@@ -267,6 +269,34 @@ export interface ClientInfo {
267
269
  version: string;
268
270
  }
269
271
 
272
+ /** 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. */
273
+ export type CodeModeLanguage = "javascript" | (string & {});
274
+
275
+ /** 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. */
276
+ export interface CodeModeOutputSpan {
277
+ /** Length of the span, in bytes. Range 0–9007199254740991 inclusive. */
278
+ lengthBytes: number;
279
+ /** Start of the span, in bytes. Range 0–9007199254740991 inclusive. */
280
+ offsetBytes: number;
281
+ /** What the bytes are. */
282
+ stream: CodeModeOutputStream;
283
+ }
284
+
285
+ /** What a Code Mode output span's bytes are (ADR 42727 D3). Open: each engine mints its own values. */
286
+ export type CodeModeOutputStream = "transcript" | (string & {});
287
+
288
+ /** 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. */
289
+ export interface CodeModeReceipt {
290
+ /** `wait` only, when the producer resolved it: the `itemId` of the `execute` item that started the cell. */
291
+ cellItemId?: string;
292
+ /** `execute`, and `wait` when the producer resolved the originating execute: the language the cell ran in. */
293
+ language?: CodeModeLanguage;
294
+ /** The public cell-output spans, ascending and non-overlapping; absent when there is no cell body or a hook rewrote the served body. */
295
+ outputSpans?: CodeModeOutputSpan[];
296
+ /** `execute` only: the top-level key of the item's `args` object whose value is the cell source. A pointer, never source bytes. */
297
+ sourceArg?: string;
298
+ }
299
+
270
300
  /** The uniform SS3.1.2 command acknowledgement: admission only, never an outcome. `session/compact` alone may answer `"noop"`; every other command answers `"accepted"`. */
271
301
  export interface CommandAcceptedResult {
272
302
  /** Echo of the client-minted UUIDv7 `commandId` (SS3.1.1). */
@@ -290,6 +320,47 @@ export type CompactionOutcome = "compacted" | "noop" | "failed" | "cancelled" |
290
320
  /** What initiated a compaction (tdd SS4.5.10). Open. */
291
321
  export type CompactionTrigger = "manual" | "auto" | (string & {});
292
322
 
323
+ /** One row of the Settings blocked-apps list. */
324
+ export interface ComputerUseBlockedApp {
325
+ /** The app's bundle ID, or the family prefix when `prefix` is true. */
326
+ bundleId: string;
327
+ /** A built-in block, which Settings cannot remove (ADR 630 D18.8). */
328
+ locked: boolean;
329
+ /** A built-in family row: it blocks every bundle ID that starts with `bundleId`. Omitted means false; only locked rows are prefixes. */
330
+ prefix?: boolean;
331
+ }
332
+
333
+ /** 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. */
334
+ export type ComputerUseChoice = "ask" | "alwaysAllow" | (string & {});
335
+
336
+ /** `computerUseSettings/read` result, also answered by `computerUseSettings/update`. */
337
+ export interface ComputerUseSettings {
338
+ /** The user's blocks in the order they were added, then the built-in blocks when `showBuiltIns` asked for them. */
339
+ blockedApps: ComputerUseBlockedApp[];
340
+ /** The computer-control dropdown, as it applies: `ask` while the stored blocked-apps list can't be read (ADR 630 D18.4). */
341
+ computerControl: ComputerUseChoice;
342
+ /** The screenshots dropdown, under the same rule. */
343
+ screenshots: ComputerUseChoice;
344
+ }
345
+
346
+ /** `computerUseSettings/read` params. */
347
+ export interface ComputerUseSettingsReadParams {
348
+ /** Also list the built-in blocks as locked rows (the D18.8 toggle). Omitted means false. */
349
+ showBuiltIns?: boolean;
350
+ }
351
+
352
+ /** `computerUseSettings/update` params: a patch. Omitted members are left alone; the whole patch applies or none of it does. */
353
+ export interface ComputerUseSettingsUpdateParams {
354
+ /** Bundle IDs to add to the user's blocked apps. A built-in block is refused: it is already blocked. */
355
+ blockApps?: string[];
356
+ /** The new computer-control dropdown value. */
357
+ computerControl?: ComputerUseChoice;
358
+ /** The new screenshots dropdown value. */
359
+ screenshots?: ComputerUseChoice;
360
+ /** Bundle IDs to remove from the user's blocked apps. Only the user's own entries can be removed; a built-in block stays. */
361
+ unblockApps?: string[];
362
+ }
363
+
293
364
  /** Context pressure level (tdd SS4.6.6): hard threshold first, both inclusive `>=`. Open. */
294
365
  export type ContextPressureLevel = "normal" | "warning" | "blocked" | (string & {});
295
366
 
@@ -303,6 +374,24 @@ export interface ContextUsage {
303
374
  windowTokens?: number;
304
375
  }
305
376
 
377
+ /** 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 — ADR 43399 D5 as amended. Each is a **bounded machine fact**: scalars, short identifiers and a small fixed-shape array of those. */
378
+ export interface CronReceipt {
379
+ /** Cron `create` and `delete`: the job id. On `delete`'s `missing` arm this is the caller's own id echoed back under ADR 43399 D1's declared echo — that arm has no server-side subject to name. Also the field ADR 42728 D4's D8 declaration names as conveying the hidden fact on the declared `created` + `cancelled` pairing: a job row was committed and will fire. */
380
+ jobId?: string;
381
+ /** Cron `list`: the served jobs in server order, `active` and `firing` rows only. */
382
+ jobs?: CronReceiptJob[];
383
+ /** Cron `create` (`created`, `duplicate`): absolute epoch-milliseconds of the job's next scheduled fire (the existing job's on `duplicate`, ADR 42728 D2). */
384
+ nextFireAtMs?: number;
385
+ }
386
+
387
+ /** One row of the Cron `list` receipt's `jobs` array (ADR 42728 D2). Server order, and **`active` + `firing` rows only** — the owner's `Serve active+firing only` directive. A small fixed-shape array of scalars, which is what keeps it inside D5's bounded-machine-fact rule. */
388
+ export interface CronReceiptJob {
389
+ /** The job's server-owned id. */
390
+ jobId: string;
391
+ /** Absolute epoch-milliseconds of the job's next scheduled fire. */
392
+ nextFireAtMs: number;
393
+ }
394
+
306
395
  /** Server-computed session cost member of [`CumulativeTokenUsage`] (tdd SS4.6.5, Amendment #41610 FR-41610-2/3). */
307
396
  export interface CumulativeCost {
308
397
  /** True when at least one leg lacked price data — clients render `(partial)`. */
@@ -399,6 +488,8 @@ export interface ErrorData {
399
488
  sessionId?: string;
400
489
  /** Winning settlement on `userInputAlreadySettled`. */
401
490
  settlement?: UserInputSettlementSummary;
491
+ /** The rejected upload id on `uploadNotFound` (`-32038`, SS3.33). */
492
+ uploadId?: string;
402
493
  /** User-input prompt identity on SS5.10 errors. */
403
494
  userInputId?: string;
404
495
  /** The blocked view position on `pageEventTooLarge` errors. */
@@ -406,7 +497,7 @@ export interface ErrorData {
406
497
  }
407
498
 
408
499
  /** 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. */
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 & {});
500
+ 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" | "uploadNotFound" | "viewTruncated" | "outputUnavailable" | "boundaryPruned" | "boundaryUnusable" | "noBoundary" | "approvalNotFound" | "approvalAlreadyResolved" | "approvalChoiceInvalid" | "approvalRequirementStale" | "approvalReviewerUnavailable" | "userInputNotFound" | "userInputAlreadySettled" | "userInputAnswerInvalid" | (string & {});
410
501
 
411
502
  /** The `error` member of an error response (SS1.2 §2.4). */
412
503
  export interface ErrorObject {
@@ -436,7 +527,7 @@ export type FeedbackSubmitOutcome = "uploaded" | "recorded" | "acceptedWithoutRe
436
527
 
437
528
  /** `feedback/submit` params (tdd SS3.25): mirrors the TUI confirm-time `FeedbackRequest`. The call itself is the explicit confirm. */
438
529
  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`. */
530
+ /** 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`. */
440
531
  attachSessionRecord?: boolean;
441
532
  /** The report class (required). */
442
533
  classification: FeedbackClassification;
@@ -444,8 +535,8 @@ export interface FeedbackSubmitParams {
444
535
  clientArtifactsPath?: string;
445
536
  /** The user report text (required; non-empty for `bug`). */
446
537
  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;
538
+ /** 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. */
539
+ sessionId?: string;
449
540
  /** The files-consent decision (required). */
450
541
  withFiles: boolean;
451
542
  }
@@ -569,6 +660,39 @@ export type HistoryNoneReason = "excluded" | "cursorSuffix" | "historyBudget" |
569
660
  /** 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. */
570
661
  export type HistoryPreference = "auto" | "inline" | "snapshot" | "anchored";
571
662
 
663
+ /** One installed handler (tdd SS3.26.1). */
664
+ export interface HookCatalogEntry {
665
+ /** The row's own switch (tdd SS3.26.1). Non-enabled rows are included as `false`, never dropped. */
666
+ enabled: boolean;
667
+ /** The event the handler runs on (ADR 33398 D7 item 2). */
668
+ event: HookEventName;
669
+ /** Where the handler comes from (ADR 33398 D7 item 1). */
670
+ handlerKind: HookHandlerKind;
671
+ /** The handler key (config key or plugin hook id). */
672
+ key: string;
673
+ }
674
+
675
+ /** 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. */
676
+ export type HookEventName = "sessionStart" | "userPromptSubmit" | "preToolUse" | "permissionRequest" | "postToolUse" | "preCompact" | "postCompact" | "subagentStart" | "subagentStop" | "stop" | "sessionEnd" | "notification" | "postToolUseFailure" | "stopFailure" | "postToolBatch" | "interrupt" | "sessionFork" | "toolUseStart" | "preLLMCall" | "postLLMCall" | (string & {});
677
+
678
+ /** 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. */
679
+ export type HookHandlerKind = "managed" | "user" | "project" | "plugin" | (string & {});
680
+
681
+ /** `hook/list` params (tdd SS3.26.1). Per-session because hook scope follows the session's workspace and plugin state. */
682
+ export interface HookListParams {
683
+ /** The target session. */
684
+ sessionId: string;
685
+ }
686
+
687
+ /** `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). */
688
+ export interface HookListResult {
689
+ /** The session's installed hook rows (tdd SS3.26.1 promises the set, not an order). */
690
+ hooks: HookCatalogEntry[];
691
+ }
692
+
693
+ /** `hookRun` durable outcome (tdd SS4.5.11). Open: new outcomes are additive, and clients MUST render unknown values generically. */
694
+ export type HookRunStatus = "completed" | "blocked" | "failed" | "timedOut" | "cancelled" | (string & {});
695
+
572
696
  /** 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. */
573
697
  export type IfBusy = "queue" | "steer" | "replace";
574
698
 
@@ -602,7 +726,7 @@ export interface InitializeResult {
602
726
  userAgent: string;
603
727
  }
604
728
 
605
- /** One transcript item at one revision (tdd SS4.4.1 common fields plus the per-kind fields of SS4.5.2–4.5.10, all optional and owned by the kind their doc names). `item/started`, `item/updated`, and `item/completed` carry the full object; `item/delta` appends to it by field path. */
729
+ /** 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. */
606
730
  export interface Item {
607
731
  /** `subagent`: agent definition path. */
608
732
  agentPath?: string;
@@ -616,8 +740,12 @@ export interface Item {
616
740
  background?: boolean;
617
741
  /** `toolCall`: who backgrounded the task; absent on pre-split records — never inferred (tdd SS4.5.5). */
618
742
  backgroundInitiator?: BackgroundInitiator;
743
+ /** `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`. */
744
+ blocking?: boolean;
619
745
  /** `toolCall`: the provider call id (`call_...`), opaque. */
620
746
  callId?: string;
747
+ /** `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). */
748
+ childPromptRefs?: OutputRef[];
621
749
  /** `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). */
622
750
  childSessionId?: string;
623
751
  /** `reminderChild`: parent-session-dir-relative child log path; absent when no filesystem log. */
@@ -630,14 +758,18 @@ export interface Item {
630
758
  commandText?: string;
631
759
  /** `subagent`: camelCased `SubagentControlStatus` (open enum); `status` stays the generic item vocabulary. */
632
760
  controlStatus?: SubagentControlStatus;
761
+ /** `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). */
762
+ declaredPhase?: string;
633
763
  /** `subagent`: nesting depth. */
634
764
  depth?: number;
635
765
  /** `userMessage`: presentation form (tdd SS3.2); absent when the client sent none. */
636
766
  displayText?: string;
637
- /** `userShell`/`subagent`: observed wall-clock duration. */
767
+ /** `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. */
638
768
  durationMs?: number;
639
769
  /** `workflow`: launched entry identity. */
640
770
  entryId?: string;
771
+ /** `hookRun`: the hook event in Q2 camelCase vocabulary (tdd SS4.5.11). */
772
+ event?: HookEventName;
641
773
  /** `userShell`: the process exit code, when it exited by code. */
642
774
  exitCode?: number;
643
775
  /** `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. */
@@ -648,12 +780,18 @@ export interface Item {
648
780
  failureReason?: string;
649
781
  /** 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). */
650
782
  fallbackText?: string;
783
+ /** `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). */
784
+ finalSummary?: string;
651
785
  /** `reminderChild`: the reminder generation. */
652
786
  generationId?: number;
787
+ /** `hookRun`: the durable `hook_key` (tdd SS4.5.11). */
788
+ hookKey?: string;
653
789
  /** 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`), and the opening durable record's event id for everything else. Opaque to clients. */
654
790
  itemId: string;
655
791
  /** The item kind (open enum): clients MUST render unknown kinds generically — kind name plus `status` plus `fallbackText` (tdd SS4.10). */
656
792
  kind: ItemKind;
793
+ /** `hookRun`: capped display label (tdd SS4.5.11). */
794
+ label?: string;
657
795
  /** `workflow`: the reconciled terminal message, set on completion. */
658
796
  message?: string;
659
797
  /** `toolCall`: rich content the model saw beyond text; base64 is not inlined on the view (tdd SS4.5.5). */
@@ -668,9 +806,11 @@ export interface Item {
668
806
  patchRef?: OutputRef;
669
807
  /** `toolCall`: server-authored edit-family diff summary (#33025) — always beside `patchRef`; absent = no diff available (tdd SS4.5.5). */
670
808
  patchSummary?: PatchSummary;
809
+ /** `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). */
810
+ paused?: boolean;
671
811
  /** `reasoning`: provider reasoning item id (e.g. `rs_...`), for provider-side correlation. */
672
812
  providerItemId?: string;
673
- /** `compaction`: noop/failure reason, verbatim (snake_case durable vocabulary, e.g. `"no_compactable_history"`). */
813
+ /** `compaction`: noop/failure reason, verbatim (snake_case durable vocabulary, e.g. `"no_compactable_history"`). `hookRun`: terminal-only capped terminal reason (tdd SS4.5.11). */
674
814
  reason?: string;
675
815
  /** RFC3339 timestamp of the item's driving durable record. Absent on ephemeral-opened items until first durable re-emission (tdd SS4.4.1). */
676
816
  recordedAt?: string;
@@ -686,12 +826,32 @@ export interface Item {
686
826
  revision: number;
687
827
  /** `subagent`: role as spawned. */
688
828
  role?: string;
829
+ /** `hookRun`: terminal-only durable outcome; stays `blocked` when the item settles `rejected` (tdd SS4.5.11). */
830
+ runStatus?: HookRunStatus;
689
831
  /** `workflow`: launched script identity. */
690
832
  scriptId?: string;
833
+ /** `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). */
834
+ sideSessionId?: string;
691
835
  /** Open enum; terminal = anything other than `"inProgress"`. Unknown values MUST be treated as terminal-unknown and rendered generically (tdd SS4.4.1). */
692
836
  status: ItemStatus;
837
+ /** `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). */
838
+ statusAttempt?: StatusAttempt;
839
+ /** `toolCall`: the latest child-summary facet, field-for-field; absent when the latest detail carries none (tdd SS4.5.5, #45448). */
840
+ statusChildren?: StatusChildren;
841
+ /** `toolCall`: the latest health facet, field-for-field; absent when the latest detail carries none (tdd SS4.5.5, #45448). */
842
+ statusHealth?: StatusHealth;
843
+ /** `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). */
844
+ statusLine?: string;
845
+ /** `toolCall`: the latest detail's phase row, verbatim; absent when the latest detail carries none (tdd SS4.5.5, #45448). */
846
+ statusPhase?: string;
847
+ /** `toolCall`: the latest progress facet, field-for-field; absent when the latest detail carries none (tdd SS4.5.5, #45448). */
848
+ statusProgress?: StatusProgress;
849
+ /** `toolCall`: the latest active-step facet, field-for-field; absent when the latest detail carries none (tdd SS4.5.5, #45448). */
850
+ statusStep?: StatusStep;
693
851
  /** `userMessage`: `true` when injected mid-turn via `turn/steer` or `ifBusy: "steer"`; absent otherwise. */
694
852
  steered?: boolean;
853
+ /** `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. */
854
+ stopAvailable?: boolean;
695
855
  /** `compaction`: summarizer strategy (installed only). */
696
856
  strategyId?: string;
697
857
  /** `subagent`: durable child identity (`subagent_id`). */
@@ -704,12 +864,16 @@ export interface Item {
704
864
  taskId?: string;
705
865
  /** `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). */
706
866
  text?: string;
867
+ /** `workflow`: the run's launch token budget, set from the launch fact (tdd SS4.5.8, #45449); absent when the launch carried none. */
868
+ tokenBudget?: WorkflowTokenBudget;
707
869
  /** `compaction`: token budget snapshot after, when measured. */
708
870
  tokensAfter?: number;
709
871
  /** `compaction`: token budget snapshot before, when measured. */
710
872
  tokensBefore?: number;
711
873
  /** `toolCall`: tool name. */
712
874
  tool?: string;
875
+ /** `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). */
876
+ toolReceipt?: ToolReceipt;
713
877
  /** `compaction`: what initiated the compaction. */
714
878
  trigger?: CompactionTrigger;
715
879
  /** `workflow`: camelCased `WorkflowLaunchTriggerSource`, verbatim (durable runtime vocabulary, e.g. `"modelProposal"`). */
@@ -752,8 +916,8 @@ export interface ItemDeltaParams {
752
916
  viewCursor: string;
753
917
  }
754
918
 
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). */
756
- export type ItemKind = "userMessage" | "agentMessage" | "reasoning" | "toolCall" | "userShell" | "subagent" | "workflow" | "reminderChild" | "compaction" | (string & {});
919
+ /** The eleven v1 item kinds (tdd SS4.5.2–4.5.13). Open: a new kind is additive evolution, and clients MUST render unknown kinds generically (tdd SS4.10). */
920
+ export type ItemKind = "userMessage" | "agentMessage" | "reasoning" | "toolCall" | "userShell" | "subagent" | "workflow" | "reminderChild" | "compaction" | "hookRun" | "sideChat" | (string & {});
757
921
 
758
922
  /** 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
923
  export type ItemReadOutputEncoding = "utf8" | "base64";
@@ -818,8 +982,48 @@ export interface ItemUpdatedParams {
818
982
  /** The literal `"2.0"` every frame carries (SS1.2). */
819
983
  export type JsonRpcVersion = "2.0";
820
984
 
985
+ /** 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). */
986
+ export interface LastTurn {
987
+ /** Copied when the `turn/completed` carried it: runtime `failed` terminals do, host-death `failed` terminals do not (ADR 36635 D2). */
988
+ error?: TurnError;
989
+ /** 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. */
990
+ reason?: string;
991
+ /** The turn's terminal (tdd SS4.5.1; open enum). */
992
+ terminal: TurnTerminal;
993
+ /** The turn's id, as on its `turn/completed`; clients deduplicate a live `turn/completed` against this member by it (ADR 36635 D2). */
994
+ turnId: string;
995
+ }
996
+
997
+ /** `media/upload` params (tdd SS3.33, ADR 45443 D5): one chunk of a client-minted upload. All members required. */
998
+ export interface MediaUploadParams {
999
+ /** This chunk's bytes; each call's frame stays in the SS1.1 budget. */
1000
+ chunkBase64: string;
1001
+ /** The upload's chunk total; positive. */
1002
+ chunkCount: number;
1003
+ /** This chunk's 0-based position. */
1004
+ chunkIndex: number;
1005
+ /** One per call; SS3.1.1 replay answers the recorded receipt. */
1006
+ commandId: string;
1007
+ /** `video/mp4` or `video/quicktime`, matching `VideoInput`. */
1008
+ mediaType: string;
1009
+ /** The session owning the video store. */
1010
+ sessionId: string;
1011
+ /** The assembled byte count; must equal the bytes the chunks deliver. */
1012
+ totalBytes: number;
1013
+ /** The client-minted upload id (UUIDv7), sent on every chunk. */
1014
+ uploadId: string;
1015
+ }
1016
+
1017
+ /** `media/upload` result (tdd SS3.33): echoes the client-minted id, on every chunk and replay. */
1018
+ export interface MediaUploadResult {
1019
+ /** The receipt the turn part references. */
1020
+ uploadId: string;
1021
+ }
1022
+
821
1023
  /** `userMessage` image attachment metadata (tdd SS4.5.2): metadata only — the durable bytes live in the log and are reachable on the raw altitude. */
822
1024
  export interface MessageAttachment {
1025
+ /** 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). */
1026
+ attachmentId?: string;
823
1027
  /** Pixel height, when known. */
824
1028
  height?: number;
825
1029
  /** The image media type (e.g. `"image/png"`). */
@@ -1023,6 +1227,33 @@ export type PlatformFamily = "unix" | "windows";
1023
1227
  /** The server's operating system (SS1.4.1). Closed, for the same reason as [`PlatformFamily`]. */
1024
1228
  export type PlatformOs = "macos" | "linux" | "windows";
1025
1229
 
1230
+ /** One installed plugin record (tdd SS3.26.2). */
1231
+ export interface PluginCatalogEntry {
1232
+ /** The record's own install switch; non-enabled rows are included as `false`, never dropped. */
1233
+ enabled: boolean;
1234
+ /** The installed plugin's identifier. */
1235
+ id: string;
1236
+ /** The installed record's source provenance (ADR 33398 D7 item 3). */
1237
+ source: PluginSource;
1238
+ /** The installed version. */
1239
+ version: string;
1240
+ }
1241
+
1242
+ /** `plugin/list` params (tdd SS3.26.2). Per-session params; rows are the installed plugin records. */
1243
+ export interface PluginListParams {
1244
+ /** The target session. */
1245
+ sessionId: string;
1246
+ }
1247
+
1248
+ /** `plugin/list` result (tdd SS3.26.2): one row per installed plugin record; the spec promises the set, not an order. */
1249
+ export interface PluginListResult {
1250
+ /** The installed plugin rows. */
1251
+ plugins: PluginCatalogEntry[];
1252
+ }
1253
+
1254
+ /** 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. */
1255
+ export type PluginSource = "curated" | "marketplaceUserAdded" | "foreignImport" | "nativeLocal" | (string & {});
1256
+
1026
1257
  /** 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". */
1027
1258
  export type ReasoningEffort = "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max" | "ultra";
1028
1259
 
@@ -1094,22 +1325,30 @@ export interface Session {
1094
1325
  branch?: string;
1095
1326
  /** RFC3339. For a fork this is the fork session id's UUIDv7 mint instant (tdd SS2.4). */
1096
1327
  createdAt: string;
1328
+ /** 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. */
1329
+ createdByClient?: ClientInfo;
1097
1330
  /** Derived first-user-prompt preview (tdd SS2.14.1, #27598). **Additive-optional**, omitted when underivable. */
1098
1331
  firstUserPrompt?: string;
1099
1332
  /** `null` for root sessions; fork provenance otherwise (tdd SS2.4). */
1100
1333
  forkedFrom: ForkProvenance | null;
1334
+ /** 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). */
1335
+ kind?: SessionKind;
1101
1336
  /** 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
1337
  lastActivityAt?: string;
1103
1338
  /** The winning metadata fold's model; `null` when that record omits it. */
1104
1339
  modelId: string | null;
1105
1340
  /** 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
1341
  name?: string;
1342
+ /** 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. */
1343
+ parentSessionId?: string;
1107
1344
  /** 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. */
1108
1345
  path: string;
1109
1346
  /** The winning metadata fold's provider; `null` when that record omits it. */
1110
1347
  providerId: string | null;
1111
1348
  /** The session identity. */
1112
1349
  sessionId: string;
1350
+ /** `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`. */
1351
+ sideFrom?: SideProvenance;
1113
1352
  /** Load state as this host knows it; `session/list` reports `notLoaded` for sessions loaded by *other* hosts (tdd SS2.4). */
1114
1353
  status: SessionStatus;
1115
1354
  /** 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. */
@@ -1211,37 +1450,6 @@ export interface SessionContextUsageParams {
1211
1450
  windowTokens?: number;
1212
1451
  }
1213
1452
 
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
-
1245
1453
  /** 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. */
1246
1454
  export type SessionDurability = "durable" | "ephemeral" | (string & {});
1247
1455
 
@@ -1293,6 +1501,9 @@ export interface SessionHistory {
1293
1501
  snapshot: ViewSnapshot | null;
1294
1502
  }
1295
1503
 
1504
+ /** 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. */
1505
+ export type SessionKind = "root" | "subagent" | (string & {});
1506
+
1296
1507
  /** Exact branch selection (#42035 FR-42035-2). */
1297
1508
  export interface SessionListBranchFilter {
1298
1509
  /** 1–32 nonempty branch names, each 1–256 UTF-8 bytes, counted before deduplication; `null` selects sessions with no branch. */
@@ -1425,6 +1636,8 @@ export interface SessionReadParams {
1425
1636
  export interface SessionReadResult {
1426
1637
  /** The served history. */
1427
1638
  history: SessionHistory;
1639
+ /** Same member as `session/resume` (tdd SS2.5.5, ADR 36635 D2). */
1640
+ lastTurn?: LastTurn;
1428
1641
  /** 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). */
1429
1642
  pendingRequests: PendingRequestPointer[];
1430
1643
  /** The session as folded point-in-time. */
@@ -1487,6 +1700,8 @@ export interface SessionResumeParams {
1487
1700
  export interface SessionResumeResult {
1488
1701
  /** The served history. */
1489
1702
  history: SessionHistory;
1703
+ /** How the last folded turn ended (tdd SS2.5.2, ADR 36635 D2). **Additive-optional**; absence is a non-assertion. */
1704
+ lastTurn?: LastTurn;
1490
1705
  /** The late-joiner pointer set; empty when nothing is pending. */
1491
1706
  pendingRequests: PendingRequestPointer[];
1492
1707
  /** The loaded session. */
@@ -1553,6 +1768,26 @@ export interface SessionSetReasoningEffortResult {
1553
1768
  status: CommandStatus;
1554
1769
  }
1555
1770
 
1771
+ /** `session/sideChat` params (tdd SS2.5.7; ADR 45435 D2). */
1772
+ export interface SessionSideChatParams {
1773
+ /** The SS2.5 idempotency handle (UUIDv7). */
1774
+ commandId: string;
1775
+ /** The source main session. */
1776
+ sessionId: string;
1777
+ }
1778
+
1779
+ /** `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. */
1780
+ export interface SessionSideChatResult {
1781
+ /** The served history (inline; SS2.5.7's empty-items half is #49416 — inherited turns surface until the boundary-aware fold lands). */
1782
+ history: SessionHistory;
1783
+ /** The late-joiner pointer set. */
1784
+ pendingRequests: PendingRequestPointer[];
1785
+ /** The new side session, carrying `sideFrom` provenance. */
1786
+ session: Session;
1787
+ /** The new side session's view head. */
1788
+ viewCursor: string;
1789
+ }
1790
+
1556
1791
  /** `session/start` params (tdd SS2.5.1). */
1557
1792
  export interface SessionStartParams {
1558
1793
  /** 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). */
@@ -1581,7 +1816,7 @@ export interface SessionStartResult {
1581
1816
  viewCursor: string;
1582
1817
  }
1583
1818
 
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`). */
1819
+ /** `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`). */
1585
1820
  export interface SessionStartedParams {
1586
1821
  /** The newly loaded session, as of the start/fork fold. */
1587
1822
  session: Session;
@@ -1675,6 +1910,22 @@ export interface SessionViewHealthChangedParams {
1675
1910
  sessionId: string;
1676
1911
  }
1677
1912
 
1913
+ /** Side provenance folded from the durable side provenance (`SideChatProvenance`, tdd SS2.4/SS2.5.7; ADR 45435 D2). */
1914
+ export interface SideProvenance {
1915
+ /** The `commandId` of the `session/sideChat` that created it. */
1916
+ commandId: string;
1917
+ /** 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). */
1918
+ cutCursor: string;
1919
+ /** The source main session this side was opened from. */
1920
+ sessionId: string;
1921
+ }
1922
+
1923
+ /** `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`]. */
1924
+ export type SkillActivationScope = "user" | "project" | "bundled" | "plugin";
1925
+
1926
+ /** The three-state skill activation (tdd SS3.30.1, ADR 10512 — no new state). **Closed**: a client-selected write vocabulary (ADR 45433 D2). */
1927
+ export type SkillActivationState = "on" | "userInvocableOnly" | "off";
1928
+
1678
1929
  /** 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
1930
  export interface SkillCatalogEntry {
1680
1931
  /** Present when the skill declares an argument hint. */
@@ -1697,7 +1948,7 @@ export interface SkillChangedParams {
1697
1948
  sessionId: string;
1698
1949
  }
1699
1950
 
1700
- /** `skill/list` params (tdd SS3.22.1). Per-session because skill scope follows the session's workspace and plugin state. */
1951
+ /** `skill/list` params (tdd SS3.22.1, SS3.30.3). Per-session because skill scope follows the session's workspace and plugin state. */
1701
1952
  export interface SkillListParams {
1702
1953
  /** The target session. */
1703
1954
  sessionId: string;
@@ -1709,6 +1960,36 @@ export interface SkillListResult {
1709
1960
  skills: SkillCatalogEntry[];
1710
1961
  }
1711
1962
 
1963
+ /** `skill/setActivation` params (tdd SS3.30.1, #45433): turn one skill on or off in any scope through the single `SkillsService::set_activation` seam. */
1964
+ export interface SkillSetActivationParams {
1965
+ /** The activation to apply. */
1966
+ activation: SkillActivationState;
1967
+ /** The SS3.1.1 idempotency handle (UUIDv7). */
1968
+ commandId: string;
1969
+ /** The activation target. */
1970
+ scope: SkillActivationScope;
1971
+ /** 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. */
1972
+ selector: string;
1973
+ /** The target session. */
1974
+ sessionId: string;
1975
+ }
1976
+
1977
+ /** `skill/setActivation` result (tdd SS3.30.1, #45433): the ack envelope plus the applied state. */
1978
+ export interface SkillSetActivationResult {
1979
+ /** The applied activation. */
1980
+ activation: SkillActivationState;
1981
+ /** Echoes the client's id. */
1982
+ commandId: string;
1983
+ /** 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. */
1984
+ previous: SkillActivationState;
1985
+ /** Echoes the applied write's scope. */
1986
+ scope: SkillActivationScope;
1987
+ /** Echoes the applied write's selector. */
1988
+ selector: string;
1989
+ /** Admission status. */
1990
+ status: CommandStatus;
1991
+ }
1992
+
1712
1993
  /** 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
1994
  export type SkillSource = "bundled" | "user" | "project" | "plugin" | (string & {});
1714
1995
 
@@ -1764,6 +2045,71 @@ export interface SourceRange {
1764
2045
  stream: StreamRef;
1765
2046
  }
1766
2047
 
2048
+ /** `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. */
2049
+ export interface StatusAttempt {
2050
+ /** The attempt number. */
2051
+ attempt: number;
2052
+ /** The error kind (durable vocabulary, verbatim), when recorded. */
2053
+ errorKind?: string;
2054
+ /** The HTTP status, when recorded. */
2055
+ httpStatus?: number;
2056
+ /** The maximum attempts, when known. */
2057
+ maxAttempts?: number;
2058
+ /** The scheduled next attempt, when known. */
2059
+ nextAttempt?: number;
2060
+ /** The operation (durable vocabulary, verbatim). */
2061
+ operation: string;
2062
+ /** The retry delay in ms, when known. */
2063
+ retryDelayMs?: number;
2064
+ /** The external system (durable vocabulary, verbatim). */
2065
+ system: string;
2066
+ }
2067
+
2068
+ /** `toolCall.statusChildren` (tdd SS4.5.5, #45448): the latest `TaskChildSummaryDetail`, field-for-field. */
2069
+ export interface StatusChildren {
2070
+ /** Active children. */
2071
+ active: number;
2072
+ /** Cancelled children. */
2073
+ cancelled: number;
2074
+ /** Completed children. */
2075
+ completed: number;
2076
+ /** Failed children. */
2077
+ failed: number;
2078
+ /** Total children, when known. */
2079
+ total?: number;
2080
+ }
2081
+
2082
+ /** `toolCall.statusHealth` (tdd SS4.5.5, #45448): the latest `TaskHealthDetail`, field-for-field. */
2083
+ export interface StatusHealth {
2084
+ /** The health level (the durable `TaskHealthLevel` vocabulary verbatim). */
2085
+ level: StatusHealthLevel;
2086
+ /** The reason, when recorded. */
2087
+ reason?: string;
2088
+ }
2089
+
2090
+ /** `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. */
2091
+ export type StatusHealthLevel = "ok" | "waiting" | "degraded" | "retrying" | "blocked" | "failed" | (string & {});
2092
+
2093
+ /** `toolCall.statusProgress` (tdd SS4.5.5, #45448): the latest `TaskProgressDetail`, field-for-field. */
2094
+ export interface StatusProgress {
2095
+ /** Completed units. */
2096
+ current: number;
2097
+ /** Total units, when known. */
2098
+ total?: number;
2099
+ /** Unit label, when recorded. */
2100
+ unit?: string;
2101
+ }
2102
+
2103
+ /** `toolCall.statusStep` (tdd SS4.5.5, #45448): the latest `TaskActiveStepDetail`, field-for-field. */
2104
+ export interface StatusStep {
2105
+ /** The step index, when known. */
2106
+ index?: number;
2107
+ /** The active step's label. */
2108
+ label: string;
2109
+ /** The step count, when known. */
2110
+ total?: number;
2111
+ }
2112
+
1767
2113
  /** One raw stream named by a [`SourceRange`] (tdd SS4.2). */
1768
2114
  export interface StreamRef {
1769
2115
  /** The stream id. */
@@ -1885,6 +2231,37 @@ export interface TaskCommandResult {
1885
2231
  taskId: string;
1886
2232
  }
1887
2233
 
2234
+ /** One background-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. */
2235
+ export interface TaskListEntry {
2236
+ /** Who backgrounded the task, mirroring the item field. **Additive-optional**: absent on pre-split records and registry-only rows, never inferred. */
2237
+ backgroundInitiator?: BackgroundInitiator;
2238
+ /** 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. */
2239
+ kind: string;
2240
+ /** The host-known task start, RFC3339. **Additive-optional**: omitted, never guessed, when the host does not know it. */
2241
+ startedAt?: string;
2242
+ /** `"inProgress"` — the only value at this increment, since every listed row is non-terminal by construction. */
2243
+ status: TaskListStatus;
2244
+ /** The `toolCall` item's `itemId` for item rows; the runtime registry id for registry-only rows. */
2245
+ taskId: string;
2246
+ /** The short tool name on item-visible tool rows only; never a label, never arguments. **Additive-optional**: absent elsewhere. */
2247
+ tool?: string;
2248
+ }
2249
+
2250
+ /** `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. */
2251
+ export interface TaskListParams {
2252
+ /** The target session. */
2253
+ sessionId: string;
2254
+ }
2255
+
2256
+ /** `task/list` result (tdd SS3.31): one row per running background workload in `task/stopAll` reach, oldest first; empty when nothing is running. */
2257
+ export interface TaskListResult {
2258
+ /** The session's live background-task rows. */
2259
+ tasks: TaskListEntry[];
2260
+ }
2261
+
2262
+ /** 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. */
2263
+ export type TaskListStatus = "inProgress" | (string & {});
2264
+
1888
2265
  /** `task/stopAll` params (tdd §3.15): stop every stoppable background workload live at admission. */
1889
2266
  export interface TaskStopAllParams {
1890
2267
  /** The SS3.1.1 idempotency handle (UUIDv7). */
@@ -1950,6 +2327,14 @@ export interface TokenUsage {
1950
2327
  reasoningTokens: number;
1951
2328
  }
1952
2329
 
2330
+ 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; };
2331
+
2332
+ /** Which operation within the family the receipt describes (ADR 43399 D1/D2). Open — registered per family, never derived from the tool name. */
2333
+ export type ToolReceiptOperation = "create" | "delete" | "list" | "execute" | "wait" | (string & {});
2334
+
2335
+ /** 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. */
2336
+ export type ToolReceiptOutcome = "created" | "duplicate" | "deleted" | "missing" | "listed" | "rejected" | "completed" | "pending" | "failed" | "timedOut" | "cancelled" | (string & {});
2337
+
1953
2338
  /** Optional W3C trace context, on requests in both directions only — never on responses or notifications (SS1.8). */
1954
2339
  export interface TraceContext {
1955
2340
  /** W3C `traceparent` string; receivers that do not trace ignore it. */
@@ -1982,7 +2367,7 @@ export interface TurnCancelResult {
1982
2367
  export interface TurnCompletedParams {
1983
2368
  /** Turn duration; absent means unmeasured, never fabricated. */
1984
2369
  durationMs?: number;
1985
- /** Present iff `terminal` is `"failed"` (tdd SS4.5.1): mid-turn failures reach the client here — never as a JSON-RPC error. */
2370
+ /** 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. */
1986
2371
  error?: TurnError;
1987
2372
  /** The runtime's free-text terminal reason, verbatim. Display and diagnostics only; never branch on it. */
1988
2373
  reason?: string;
@@ -2015,6 +2400,20 @@ export interface TurnError {
2015
2400
  /** Turn failure classes (tdd SS4.5.1, `TerminalErrorKind` plus the model-task failure class). Open. */
2016
2401
  export type TurnErrorKind = "stepLimit" | "configError" | "projectionError" | "logError" | "workflowLaunchError" | "environmentError" | "modelError" | "launchError" | "authRequired" | (string & {});
2017
2402
 
2403
+ /** `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`. */
2404
+ export interface TurnForegroundCompletedParams {
2405
+ /** `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. */
2406
+ blockingAgents: string[];
2407
+ /** The owning session. */
2408
+ sessionId: string;
2409
+ /** The durable records this event folded from, anchored at the first blocking link of the firing window. */
2410
+ sourceRange: SourceRange;
2411
+ /** The turn whose foreground completed. */
2412
+ turnId: string;
2413
+ /** Opaque, strictly monotonic view cursor (tdd SS4.1). */
2414
+ viewCursor: string;
2415
+ }
2416
+
2018
2417
  /** 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`. */
2019
2418
  export interface TurnInputPart {
2020
2419
  /** 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). */
@@ -2031,12 +2430,14 @@ export interface TurnInputPart {
2031
2430
  text?: string;
2032
2431
  /** The part type. */
2033
2432
  type: TurnInputPartType;
2433
+ /** The upload receipt, required on a `video` part (tdd SS3.2, SS3.33; ADR 45443 D5): the client-minted id `media/upload` echoed. */
2434
+ uploadId?: string;
2034
2435
  /** Pixel width; must be provided together with `height` or not at all (tdd SS3.2). Published as a `dependentRequired` pair under #22785 E6c. */
2035
2436
  width?: number;
2036
2437
  }
2037
2438
 
2038
2439
  /** The `type` discriminator of a turn input part (tdd SS3.2). Closed: an unknown part type is `invalidParams` (tdd SS3.1.2). */
2039
- export type TurnInputPartType = "text" | "image" | "skill";
2440
+ export type TurnInputPartType = "text" | "image" | "skill" | "video";
2040
2441
 
2041
2442
  /** `turn/interrupt` params (tdd SS3.4): the "user pressed stop" gesture, on the runtime's priority lane. */
2042
2443
  export interface TurnInterruptParams {
@@ -2064,6 +2465,10 @@ export interface TurnInterruptResult {
2064
2465
  export interface TurnRef {
2065
2466
  /** The `commandId` of the submit that minted it. */
2066
2467
  commandId: string;
2468
+ /** `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. */
2469
+ displayText?: string;
2470
+ /** `queuedTurns[]` only: set when `displayText` was cut to the committed-surface budget, mirroring `userMessage.truncated` (tdd SS4.5.2). Absent unless `true`. */
2471
+ truncated?: boolean;
2067
2472
  /** The turn's id, pre-minted per tdd SS3.1.4. */
2068
2473
  turnId: string;
2069
2474
  }
@@ -2320,6 +2725,36 @@ export interface UserInputClarifyResult {
2320
2725
  userInputId: string;
2321
2726
  }
2322
2727
 
2728
+ /** `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. */
2729
+ export interface UserInputEngagedParams {
2730
+ /** The target session. */
2731
+ sessionId: string;
2732
+ /** The prompt being engaged. */
2733
+ userInputId: string;
2734
+ }
2735
+
2736
+ /** `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. */
2737
+ export interface UserInputInterruptParams {
2738
+ /** Confirmed partial answers the named settlement carries. */
2739
+ answers?: UserInputAnswer[];
2740
+ /** The SS3.1.1 idempotency handle (UUIDv7). */
2741
+ commandId: string;
2742
+ /** The target session. */
2743
+ sessionId: string;
2744
+ /** The prompt being interrupted. */
2745
+ userInputId: string;
2746
+ }
2747
+
2748
+ /** `userInput/interrupt` result (tdd SS5.10.2). */
2749
+ export interface UserInputInterruptResult {
2750
+ /** Echoes the client's id. */
2751
+ commandId: string;
2752
+ /** Admission status. */
2753
+ status: CommandStatus;
2754
+ /** The prompt this interruption settled. */
2755
+ userInputId: string;
2756
+ }
2757
+
2323
2758
  export interface UserInputOption {
2324
2759
  description?: string;
2325
2760
  label: string;
@@ -2367,6 +2802,8 @@ export type UserInputSelectionMode = "single" | "multiple";
2367
2802
  export interface UserInputSettledParams {
2368
2803
  answers: UserInputAnswer[];
2369
2804
  clarification: UserInputClarification | null;
2805
+ /** 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. */
2806
+ decidedAt: string | null;
2370
2807
  decidedByCommandId: string | null;
2371
2808
  outcome: UserInputOutcome;
2372
2809
  reason: string | null;
@@ -2485,6 +2922,10 @@ export interface WorkflowChild {
2485
2922
  childId: string;
2486
2923
  /** The child's observed duration, when recorded. */
2487
2924
  durationMs?: number;
2925
+ /** 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). */
2926
+ failureKind?: string;
2927
+ /** 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. */
2928
+ failureReason?: string;
2488
2929
  /** The child's display label, when recorded. */
2489
2930
  label?: string;
2490
2931
  /** The child's phase, when recorded. */
@@ -2518,7 +2959,7 @@ export interface WorkflowChildControlParams {
2518
2959
  workflowRunId: string;
2519
2960
  }
2520
2961
 
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. */
2962
+ /** 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. */
2522
2963
  export interface WorkflowControlResult {
2523
2964
  /** Echoes the client's id. */
2524
2965
  commandId: string;
@@ -2526,11 +2967,27 @@ export interface WorkflowControlResult {
2526
2967
  status: CommandStatus;
2527
2968
  }
2528
2969
 
2970
+ /** `workflow/pause` params (tdd SS3.32, ADR 45437 D2): pause a live workflow run, shaped exactly like `workflow/cancel`. */
2971
+ export interface WorkflowPauseParams {
2972
+ /** The SS3.1.1 idempotency handle (UUIDv7). */
2973
+ commandId: string;
2974
+ /** The target session. */
2975
+ sessionId: string;
2976
+ /** The run to pause, exactly as the `workflow` item names it (SS4.5.8); required, non-empty. */
2977
+ workflowRunId: string;
2978
+ }
2979
+
2980
+ /** `workflow`: the run's launch token budget (tdd SS4.5.8, #45449). */
2981
+ export interface WorkflowTokenBudget {
2982
+ /** The effective launch budget in tokens, verbatim from the launch fact. */
2983
+ total: number;
2984
+ }
2985
+
2529
2986
  /** Every wire method in this schema (SS1.9 index). */
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";
2987
+ 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" | "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" | "hook/list" | "plugin/list" | "task/background" | "task/stop" | "task/stopAll" | "goal/set" | "goal/edit" | "goal/clear" | "goal/pause" | "goal/resume" | "workflow/cancel" | "workflow/childControl" | "workflow/pause" | "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" | "computerUseSettings/read" | "computerUseSettings/update";
2531
2988
  /** Every wire notification in this schema (SS1.9 index). */
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";
2989
+ export type MspNotification = "initialized" | "session/started" | "session/closed" | "skill/changed" | "turn/started" | "turn/completed" | "turn/retracted" | "turn/retryScheduled" | "turn/unqueued" | "turn/foregroundCompleted" | "item/started" | "item/updated" | "item/delta" | "item/completed" | "view/gap" | "approval/requested" | "approval/updated" | "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" | "session/modelRouteUnserved" | "session/nameChanged" | "session/viewHealthChanged" | "session/listChanged" | "usage/changed";
2533
2990
  /** Every server-initiated wire request in this schema (SS5.3/SS5.10.1 index). */
2534
2991
  export type MspServerRequest = "approval/request" | "userInput/request";
2535
2992
  /** Every error `data.kind` in this schema's error table (SS1.6) — each code's primary kind plus its override kinds. */
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";
2993
+ 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" | "uploadNotFound" | "viewTruncated" | "outputUnavailable" | "boundaryPruned" | "boundaryUnusable" | "noBoundary" | "approvalNotFound" | "approvalAlreadyResolved" | "approvalChoiceInvalid" | "approvalRequirementStale" | "approvalReviewerUnavailable" | "userInputNotFound" | "userInputAlreadySettled" | "userInputAnswerInvalid";