@muse-code/sdk 1.4.11 → 1.4.12

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.
@@ -47,6 +47,7 @@ const REFRESH_FROM_UPDATE = [
47
47
  ];
48
48
  const REFRESH_FROM_REQUEST = [
49
49
  "approvalId",
50
+ "cuaCardFacts",
50
51
  "itemId",
51
52
  "judgeEscalated",
52
53
  "protectedWrite",
@@ -184,6 +185,11 @@ export class ApprovalRouter {
184
185
  // parent's own approvals by contract (#36182 `skip_serializing_if`).
185
186
  if (params.subagentOrigin !== undefined)
186
187
  refreshed.subagentOrigin = params.subagentOrigin;
188
+ // A Computer Use card's facts belong to the call, so they stay with the
189
+ // retained request across stages; omitted when absent.
190
+ if (requested.cuaCardFacts !== undefined) {
191
+ refreshed.cuaCardFacts = requested.cuaCardFacts;
192
+ }
187
193
  const acked = this.#inFlight.get(requested.approvalId);
188
194
  if (acked !== undefined)
189
195
  return this.#afterAck(acked, refreshed);
@@ -13,7 +13,7 @@
13
13
  * (tdd SS1.4.1) — additive-optional evolution means an older SDK keeps
14
14
  * working against a newer host.
15
15
  */
16
- export declare const EXPECTED_SCHEMA_FINGERPRINT = "sha256:f282ad16e21520d0cda68cb190149b86e2b062eef1dd282749360c05aa3d1082";
16
+ export declare const EXPECTED_SCHEMA_FINGERPRINT = "sha256:cfdb6d2525601b9bac76584ccb0610ab3a5539b5e4f51141f079b99b39fcb4e0";
17
17
  /**
18
18
  * What a build-time mismatch MEANS, in the words a human needs at 2am.
19
19
  *
@@ -13,7 +13,7 @@
13
13
  * (tdd SS1.4.1) — additive-optional evolution means an older SDK keeps
14
14
  * working against a newer host.
15
15
  */
16
- export const EXPECTED_SCHEMA_FINGERPRINT = "sha256:f282ad16e21520d0cda68cb190149b86e2b062eef1dd282749360c05aa3d1082";
16
+ export const EXPECTED_SCHEMA_FINGERPRINT = "sha256:cfdb6d2525601b9bac76584ccb0610ab3a5539b5e4f51141f079b99b39fcb4e0";
17
17
  /**
18
18
  * What a build-time mismatch MEANS, in the words a human needs at 2am.
19
19
  *
package/dist/src/msp.d.ts CHANGED
@@ -10,35 +10,100 @@
10
10
  // Generated by tbh-protocol (spec 206) from the same schema model as
11
11
  // the JSON Schema bundle (INV-017). Do not edit by hand.
12
12
 
13
+ /** The policy rule a decision created, in display form; the full rule is not included. */
13
14
  export interface ApprovalAmendment {
15
+ /** How long the rule lasts: `session` or `localPersistent`. */
14
16
  durability: ApprovalAmendmentDurability;
17
+ /** A human-readable preview of the rule, for display. */
15
18
  rulePreview: string;
16
19
  }
17
20
 
21
+ /** How long a rule created by an approval decision lasts. The set is open, so newer hosts may send other values. */
18
22
  export type ApprovalAmendmentDurability = "session" | "localPersistent" | (string & {});
19
23
 
24
+ /** The change an `approval/updated` event reports. `kind` says what happened, and only the fields for that kind are present. */
20
25
  export interface ApprovalChange {
26
+ /** The `choiceId` that satisfied the stage. Present only when `kind` is `stageResolved`. */
21
27
  choiceId?: string;
28
+ /** The decision the chosen option applied to the stage. Present only when `kind` is `stageResolved`. */
22
29
  decision?: ApprovalDecision;
30
+ /** A recovery detail: whether the action could run without a new decision. Present only when `kind` is `restartRecovered`. */
23
31
  executable?: boolean;
32
+ /** What happened: for example `stageResolved` (a shell stage was satisfied), `policyPersistence` (saving a rule succeeded or failed), `reviewStarted` or `reviewCompleted` (the automated LLM judge started or finished reviewing), `restartRecovered` (a host restart recovered this approval: either the host first resolves it `abort` and a re-ask comes as a new approval with a new `approvalId`, or it stays pending under the same `approvalId` with refreshed choices) or `alreadyTerminal` (recovery found it already decided). The set is open, so newer hosts may add kinds. */
24
33
  kind: string;
34
+ /** Why saving the policy rule failed, as human-readable text. Present only when `kind` is `policyPersistence` and `status` is `failed`. */
25
35
  reason?: string;
36
+ /** A recovery detail: whether the command was re-parsed during recovery. Present only when `kind` is `restartRecovered`. */
26
37
  reparsed?: boolean;
38
+ /** The stage requirement that was satisfied. Present only when `kind` is `stageResolved`. */
27
39
  requirementId?: ApprovalRequirementRef;
40
+ /** Whether saving the policy rule succeeded or failed; present only when `kind` is `policyPersistence`. A failure does not undo the decision; only the saved rule is missing. */
28
41
  status?: ApprovalPersistenceStatus;
29
42
  }
30
43
 
44
+ /** One option the server offers for deciding an approval. Clients pick one and send its `choiceId` in `approval/decide`; they never build their own. */
31
45
  export interface ApprovalChoice {
46
+ /** `true` when this choice takes optional `feedback` text in `approval/decide`, which reaches the model as guidance. Omitted when `false`. */
32
47
  acceptsFeedback?: boolean;
48
+ /** The id to send as `choiceId` in `approval/decide`. The set of ids is open, so show `label` and do not base behavior on specific ids. */
33
49
  choiceId: string;
50
+ /** The decision this choice applies, so a client can act on approve or reject without knowing choice ids. */
34
51
  decision: ApprovalDecision;
52
+ /** The human-readable label to show for this choice. */
35
53
  label: string;
54
+ /** A human-readable preview of what this choice grants, such as the policy rule it would create; show it exactly as given. */
36
55
  rulePreview?: string;
56
+ /** The grant duration this choice declares: `once` (this request only), `session` (the rest of the session) or `localPersistent` (saved in the local policy store). */
37
57
  scope: ApprovalChoiceScope;
38
58
  }
39
59
 
60
+ /** How long a grant made by a choice lasts. The set is open, so newer hosts may send other values. */
40
61
  export type ApprovalChoiceScope = "once" | "session" | "localPersistent" | (string & {});
41
62
 
63
+ /** One Computer Use card's facts. Empty collections and absent rows are omitted, never `null`. */
64
+ export interface ApprovalCuaCardFacts {
65
+ /** For a browser, the host of the window's current page. */
66
+ page?: ApprovalCuaPage;
67
+ /** Only the consequential steps, in call order. */
68
+ steps?: ApprovalCuaStep[];
69
+ /** The target window's title: the app's own text, which a page can set; a client shows it quoted and as plain text, never as markup or a choice, and may cap it. */
70
+ windowTitle?: string;
71
+ }
72
+
73
+ /** The page's full host, no path or query. */
74
+ export interface ApprovalCuaPage {
75
+ /** The host in Unicode. */
76
+ host: string;
77
+ /** The host's `xn--` form; equal to `host` when they don't differ. */
78
+ hostAscii: string;
79
+ }
80
+
81
+ /** A point in the model's 0–1000 coordinates. */
82
+ export interface ApprovalCuaPoint {
83
+ x: number;
84
+ y: number;
85
+ }
86
+
87
+ /** One consequential step. A client renders "Step N: <action> <roleWord> "<label>" — <effect>"; a key step names its `chord`, and only a step with a `point` (and no label or chord) reads "at x,y". */
88
+ export interface ApprovalCuaStep {
89
+ /** The host's verb phrase, such as `click` or `type into`. */
90
+ action: string;
91
+ /** The chord, for a key step. */
92
+ chord?: string;
93
+ /** The host's trusted sentence for what the step may do. */
94
+ effect: string;
95
+ /** An open tag for styling and tests only (`verb:<class>`, `unresolved`, `unlabeled`); a client that doesn't know a value renders the step from `effect` and its label as usual. */
96
+ kind: string;
97
+ /** The control's label: the app's own text, shown quoted and as plain text; a client may cap it. */
98
+ label?: string;
99
+ /** The step's own 0–1000 model coordinates, only for a point step. */
100
+ point?: ApprovalCuaPoint;
101
+ /** `button`, `link`, `menu item` or `key`; absent for a point step. */
102
+ roleWord?: string;
103
+ /** 1-based, as the batch numbers its steps. */
104
+ step: number;
105
+ }
106
+
42
107
  /** `approval/decide` params (tdd SS5.4): the decision. A standard SS3 command — requires the session loaded on this host, requires `commandId`, durable intake before ack, value-identical replay. */
43
108
  export interface ApprovalDecideParams {
44
109
  /** The approval being decided. */
@@ -67,6 +132,7 @@ export interface ApprovalDecideResult {
67
132
  terminal: boolean;
68
133
  }
69
134
 
135
+ /** The kind of decision a choice applies or an approval received. The set is open, so newer hosts may send values this version does not list. */
70
136
  export type ApprovalDecision = "approved" | "approvedForSession" | "approvedPolicyAmendment" | "denied" | "deniedPolicyAmendment" | "timedOut" | "abort" | (string & {});
71
137
 
72
138
  /** `approval/listPending` params (tdd SS5.7): the pull dual of the re-issued requests. A log-fold read — no lease, works on loaded and unloaded sessions, never subscribes. */
@@ -77,9 +143,9 @@ export interface ApprovalListPendingParams {
77
143
 
78
144
  /** `approval/listPending` result (tdd SS5.7). Ordering is by opening `viewCursor`; empty arrays when nothing is pending. The result is point-in-time — to act on it race-safely, `approval/decide` carries the `requirementId` guard regardless of how the client learned the state. */
79
145
  export interface ApprovalListPendingResult {
80
- /** Exactly the `approval/request` params of tdd SS5.3, one per pending approval. */
146
+ /** Exactly the `approval/request` params, one per pending approval. */
81
147
  approvals: ApprovalRequestParams[];
82
- /** Exactly the `userInput/request` params of tdd SS5.10, one per pending prompt. */
148
+ /** Exactly the `userInput/request` params, one per pending prompt. */
83
149
  userInputs: UserInputRequestParams[];
84
150
  }
85
151
 
@@ -92,93 +158,152 @@ export type ApprovalModeApplyOutcome = "completed" | "noop" | (string & {});
92
158
  /** How an approval mode took effect (tdd SS5.12, the effective-mode projection's `source` vocabulary). Open. */
93
159
  export type ApprovalModeSource = "startup" | "replay" | "approvalReconfigure" | (string & {});
94
160
 
161
+ /** What triggered a tool action, shown so the user can judge it. It is display-only and untrusted, and policy rules never match on it. */
95
162
  export interface ApprovalOrigin {
163
+ /** The shell command whose process asked for the action. Present when `kind` is `shellCommand`. */
96
164
  command?: string;
165
+ /** Which kind of origin this is: `shellCommand` or `url`. */
97
166
  kind: string;
167
+ /** The full URL a fetch tool is requesting. Present when `kind` is `url`. */
98
168
  url?: string;
99
169
  }
100
170
 
171
+ /** The result of saving a granted rule to the local policy store. The set is open, so newer hosts may send other values. */
101
172
  export type ApprovalPersistenceStatus = "succeeded" | "failed" | (string & {});
102
173
 
174
+ /** Whether an approval's final decision lets the action run. The set is open, so newer hosts may send other values. */
103
175
  export type ApprovalPolicyResult = "allow" | "deny" | (string & {});
104
176
 
105
177
  /** Full params shared by `approval/request` and `approval/requested`. */
106
178
  export interface ApprovalRequestParams {
179
+ /** The approval's stable id. Match `approval/decide`, `approval/updated` and `approval/resolved` by it, never by the JSON-RPC request id, which belongs to one connection. */
107
180
  approvalId: string;
181
+ /** The choices the server offers for the current requirement. Send the chosen one's `choiceId` in `approval/decide`; clients never build their own. */
108
182
  availableChoices: ApprovalChoice[];
183
+ /** A Computer Use card's facts: the page, the window and each step that may have an effect, in the host's words; absent on every other approval. */
184
+ cuaCardFacts?: ApprovalCuaCardFacts;
185
+ /** The requirement the next decision must target; send it unchanged as `requirementId` in `approval/decide`. For `shell` it names the first stage still needing a decision; for other kinds its `sourceIndex` is 0. */
109
186
  currentRequirementId: ApprovalRequirementRef;
187
+ /** The `toolCall` view item waiting on this approval. */
110
188
  itemId: string;
189
+ /** `true` when the automated LLM judge saw this request first and handed it to a person without deciding. A display hint only. The host sends it as `false` when it re-issues the request after a restart or on `session/resume`; a re-send for a later stage keeps it. */
111
190
  judgeEscalated: boolean;
191
+ /** `true` when this approval guards a write to a protected file. Only allow-once and reject choices are offered, and a decision is accepted only while at least one client is subscribed to the session. */
112
192
  protectedWrite: boolean;
193
+ /** The tool call's arguments as a string, usually JSON. With `toolName`, it lets a client show a subject whose `kind` it does not recognize. */
113
194
  rawArgs: string;
195
+ /** The owning session. For a subagent's approval shown on the parent, this is the parent session. */
114
196
  sessionId: string;
197
+ /** The stored records this event was folded from: an opaque token clients must not interpret. */
115
198
  sourceRange: SourceRange;
116
199
  /** Present only for a child (native subagent) approval projected onto the parent session's plane (ADR 36182); parent-own approvals omit it. */
117
200
  subagentOrigin?: ApprovalSubagentOrigin;
201
+ /** What the approval is for. Show a `kind` you do not recognize generically, and never auto-approve it. */
118
202
  subject: ApprovalSubject;
203
+ /** The id of the task running the tool call. */
119
204
  taskId: string;
205
+ /** The model provider's id for this tool call. */
120
206
  toolCallId: string;
207
+ /** The name of the tool being called. */
121
208
  toolName: string;
209
+ /** The turn whose tool call is waiting on this approval. */
122
210
  turnId: string;
211
+ /** The cursor of the `approval/requested` event that opened this request. A re-send for a later stage keeps this cursor, so `view/page` at it returns the opening stage, which may be older than this payload. */
123
212
  viewCursor: string;
124
213
  }
125
214
 
126
- /** Approval-stage token carried in SS5 params and stale-requirement errors. */
215
+ /** Identifies one requirement of an approval: for a `shell` approval, one stage. A client sends it back as `requirementId` in `approval/decide`, and a stale-requirement error names the current one. */
127
216
  export interface ApprovalRequirementRef {
217
+ /** The approval this requirement belongs to. */
128
218
  approvalId: string;
219
+ /** The requirement's index within the approval, counting from 0; an approval with a single requirement uses 0. */
129
220
  sourceIndex: number;
130
221
  }
131
222
 
132
223
  /** Winning terminal returned to a losing `approval/decide` command. */
133
224
  export interface ApprovalResolutionSummary {
225
+ /** The winning decision, as an `approval/resolved` decision value such as `approved` or `abort`. */
134
226
  decision: string;
227
+ /** Who made the winning decision, such as `user`, `policy` or `llmJudge`. */
135
228
  resolvedBy: string;
229
+ /** The view cursor of the winning `approval/resolved` event. */
136
230
  viewCursor: string;
137
231
  }
138
232
 
233
+ /** Who or what made an approval's final decision. The set is open, so newer hosts may send other values. */
139
234
  export type ApprovalResolvedBy = "user" | "policy" | "llmJudge" | (string & {});
140
235
 
141
236
  /** `approval/resolved` params: the first durable terminal decision. */
142
237
  export interface ApprovalResolvedParams {
238
+ /** The policy rule the decision created. Present only when the decision created one. */
143
239
  amendment?: ApprovalAmendment;
240
+ /** The approval that was decided. */
144
241
  approvalId: string;
145
242
  /** 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
243
  decidedAt?: string;
244
+ /** The `commandId` of the `approval/decide` command that won. Absent when no such command made the decision, for example a policy or LLM judge decision. */
147
245
  decidedByCommandId?: string;
246
+ /** The final decision. */
148
247
  decision: ApprovalDecision;
248
+ /** The `toolCall` view item this approval was holding. */
149
249
  itemId: string;
250
+ /** Whether the final decision lets the action run (`allow`) or blocks it (`deny`). */
150
251
  policyResult: ApprovalPolicyResult;
252
+ /** Who or what made the decision: `user`, `policy` or `llmJudge`. */
151
253
  resolvedBy: ApprovalResolvedBy;
254
+ /** The owning session. */
152
255
  sessionId: string;
256
+ /** The stored records this event was folded from: an opaque token clients must not interpret. */
153
257
  sourceRange: SourceRange;
258
+ /** For a `shell` approval, how each stage was resolved when the decision became final. Empty for other subject kinds, and it can be empty for `shell` too. */
154
259
  stageEvidence: ApprovalStageEvidence[];
155
260
  /** Present only for a child (native subagent) approval projected onto the parent session's plane (ADR 36182); parent-own approvals omit it. */
156
261
  subagentOrigin?: ApprovalSubagentOrigin;
262
+ /** The turn whose tool call this approval was holding. */
157
263
  turnId: string;
264
+ /** This event's view cursor: opaque, and strictly increasing within the session. */
158
265
  viewCursor: string;
159
266
  }
160
267
 
268
+ /** One stage of a `shell` approval: a single command from the pipeline or command list, approved separately from the others. */
161
269
  export interface ApprovalStage {
270
+ /** The stage's command words as parsed. When `argvComplete` is `false`, this can be a single unparsed piece of the command. */
162
271
  argv: string[];
272
+ /** `true` when `argv` is the stage's complete command, known before it runs; `false` when part of it cannot be resolved ahead of time (for example a command substitution). A stage with `false` never has a `suggestedPrefix`. */
163
273
  argvComplete: boolean;
274
+ /** This stage's 1-based position in the command; it equals `requirementId.sourceIndex + 1`. */
164
275
  position: number;
276
+ /** This stage's requirement id. When it equals the approval's `currentRequirementId`, send it as `requirementId` in `approval/decide`. */
165
277
  requirementId: ApprovalRequirementRef;
278
+ /** Whether this stage still needs a decision or, if not, how it was satisfied. */
166
279
  resolution: ApprovalStageResolution;
280
+ /** A command prefix the host suggests always allowing in this workspace, present only when one can be taken from a fully parsed stage. `availableChoices` shows whether that grant is offered. */
167
281
  suggestedPrefix?: ApprovalSuggestedPrefix;
282
+ /** The total number of stages in the command. */
168
283
  totalStages: number;
169
284
  }
170
285
 
286
+ /** How one stage of a `shell` approval was resolved when the decision became final. */
171
287
  export interface ApprovalStageEvidence {
288
+ /** The stage's command words as parsed. */
172
289
  argv: string[];
290
+ /** The stage's 1-based position in the command. */
173
291
  position: number;
292
+ /** The stage's requirement id. */
174
293
  requirementId: ApprovalRequirementRef;
294
+ /** How the stage was resolved at the final decision. */
175
295
  resolution: ApprovalStageResolution;
296
+ /** The total number of stages in the command. */
176
297
  totalStages: number;
177
298
  }
178
299
 
300
+ /** Whether a shell stage still needs a decision, or how it was satisfied. Satisfied stages are included so a client can show progress. */
179
301
  export interface ApprovalStageResolution {
302
+ /** The command prefix saved as an always-allow rule when this stage was approved. Present only when `kind` is `policyAmendment`. */
180
303
  argvPrefix?: string[];
304
+ /** Free-form text naming the rule or mode that allowed the stage, for display or troubleshooting. Present only when `kind` is `policyAllow`. */
181
305
  diagnostic?: string;
306
+ /** One of `unresolved`, `knownSafe`, `policyAllow`, `allowOnce` or `policyAmendment`. The set is open, so newer hosts may add values. */
182
307
  kind: string;
183
308
  }
184
309
 
@@ -194,37 +319,59 @@ export interface ApprovalSubagentOrigin {
194
319
 
195
320
  /** Open approval subject union. Unknown kinds are rendered generically and never auto-approved by clients (tdd SS5.2). */
196
321
  export interface ApprovalSubject {
322
+ /** The access asked for: `read` or `write` for `fileAccess`, `control` for `process`. Absent for other kinds. */
197
323
  access?: string;
324
+ /** The full raw shell command. Present when `kind` is `shell`. */
198
325
  command?: string;
326
+ /** The network host the tool wants to reach. Present when `kind` is `network`. */
199
327
  host?: string;
200
328
  /** Open discriminator: `shell | fileAccess | network | unixSocket | process | tool`. */
201
329
  kind: string;
330
+ /** What triggered the action (a shell command or a URL), for display only and untrusted. It is not sent on `shell` subjects, and policy rules never match on it. */
202
331
  origin?: ApprovalOrigin;
332
+ /** For `fileAccess`, the path the tool asked to access, normalized by the host (workspace-relative inside the workspace); for `unixSocket`, the exact resolved socket path, sent unescaped, so escape it before display. */
203
333
  path?: string;
334
+ /** The network port, present only on `network` subjects that name one. A session grant made from a subject without a port covers every port. */
204
335
  port?: number;
336
+ /** The network protocol, for example `https`. Present only on `network` subjects that name one. */
205
337
  protocol?: string;
338
+ /** The shell command split into stages that are approved separately (the commands of a pipeline or command list), in order. Present on `shell` subjects; it may be empty. */
206
339
  stages?: ApprovalStage[];
340
+ /** Display text naming the process the tool wants to control. Present when `kind` is `process`. */
207
341
  target?: string;
342
+ /** The tool asking for the action. Present for every kind except `shell`. */
208
343
  toolName?: string;
344
+ /** The canonical workspace root the shell command runs in, present on `shell` subjects when the host knows it. Saved command-prefix rules apply only within this root. */
209
345
  workspaceRoot?: string;
210
346
  }
211
347
 
348
+ /** A suggested always-allow rule for a shell stage: commands starting with `argvPrefix` would run in this workspace without asking. */
212
349
  export interface ApprovalSuggestedPrefix {
350
+ /** The leading command words the rule would allow, for example `["cargo", "test"]`. */
213
351
  argvPrefix: string[];
352
+ /** A human-readable label for the suggestion, ready to show as is. */
214
353
  label: string;
215
354
  }
216
355
 
217
356
  /** `approval/updated` params: the refreshed pending view plus one change. */
218
357
  export interface ApprovalUpdatedParams {
358
+ /** The approval that changed. */
219
359
  approvalId: string;
360
+ /** The refreshed choices for the current requirement. */
220
361
  availableChoices: ApprovalChoice[];
362
+ /** What changed; `change.kind` names the kind of change. */
221
363
  change: ApprovalChange;
364
+ /** The requirement the next decision must target after this change; send it as `requirementId` in `approval/decide`. */
222
365
  currentRequirementId: ApprovalRequirementRef;
366
+ /** The owning session. */
223
367
  sessionId: string;
368
+ /** The stored records this event was folded from: an opaque token clients must not interpret. */
224
369
  sourceRange: SourceRange;
225
370
  /** Present only for a child (native subagent) approval projected onto the parent session's plane (ADR 36182); parent-own approvals omit it. */
226
371
  subagentOrigin?: ApprovalSubagentOrigin;
372
+ /** The approval's subject, with `stages` refreshed for this change. */
227
373
  subject: ApprovalSubject;
374
+ /** This event's view cursor: opaque, and strictly increasing within the session. */
228
375
  viewCursor: string;
229
376
  }
230
377
 
@@ -234,6 +381,26 @@ export type AttentionFlag = "approvalPending" | "inputPending" | (string & {});
234
381
  /** Who durably backgrounded a task (tdd SS4.5.5, `TaskBackgroundedInitiator`). Open — runtime vocabulary. */
235
382
  export type BackgroundInitiator = "user" | "timeout" | (string & {});
236
383
 
384
+ /** `backgroundTerminalCompletion`: the five facts the Finished cell renders (ADR 50041 D3/D4). The fold reads them from the inbox terminal record and the backgrounded call it names; every member is required (empty output serializes as `""`, never absent). */
385
+ export interface BackgroundTerminalCompletion {
386
+ /** The title text gate-off shows for the backgrounded command. */
387
+ command: string;
388
+ /** The completion text; empty when the terminal carries none. */
389
+ output: string;
390
+ /** True when `output` is a prefix of the terminal text. */
391
+ outputTruncated: boolean;
392
+ /** One of `completed`, `failed`, `cancelled`, `timedOut`, `rejected` (the ItemStatus wire vocabulary, tdd SS4.4.1). */
393
+ terminalStatus: string;
394
+ /** The backgrounded call's call id: the live/history correlation key behind the skip-when-minted rule (ADR 50041 D6). */
395
+ toolCallId: string;
396
+ }
397
+
398
+ /** The cold recall seed on `session/resume` and `session/read` results (ADR 50074 D2): at most one, the latest blocked Main prompt — exactly the host's mirror of `prompt_recovery::replay::ReplayInput`'s choice. */
399
+ export interface BlockedPrompt {
400
+ /** The exact submitted prompt, verbatim — no truncation, no normalization; recall fidelity requires exactness. */
401
+ text: string;
402
+ }
403
+
237
404
  /** The latest branch observation in the snapshot (tdd SS4.6.4, SS4.9.1). */
238
405
  export interface BranchState {
239
406
  /** The observed branch; `null` on a detached-HEAD observation. */
@@ -244,9 +411,15 @@ export interface BranchState {
244
411
  workspaceRoot: string;
245
412
  }
246
413
 
247
- /** 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. */
414
+ /** A grantable capability name. Open: the experimental-only `rawLog` entry joins the stable domain as an additive open-enum extension when it graduates — closed would make that a retype. */
248
415
  export type CapabilityName = "userShell" | "sessionMcp" | "sessionListStream" | "feedback" | "computerUseSetup" | "computerUseHostSetup" | "sessionRename" | (string & {});
249
416
 
417
+ /** A served checkpoint-prune boundary (spec 13929 amendment FR-50042-1; ADR 50042 D3): `through_item_id` names the last first-opened item that opened strictly before the boundary checkpoint event. */
418
+ export interface CheckpointBoundary {
419
+ /** The last pre-boundary item's id, in served (first-opened) order. */
420
+ throughItemId: string;
421
+ }
422
+
250
423
  /** The client's requested capability posture (SS1.4.1). Every member defaults; an absent `capabilities` object means all defaults. */
251
424
  export interface ClientCapabilities {
252
425
  /** Opt into experimental methods, fields, and variants (default `false`). */
@@ -305,7 +478,7 @@ export interface CommandAcceptedResult {
305
478
  status: CommandAckStatus;
306
479
  }
307
480
 
308
- /** The ack-status vocabulary (`tdd.md` SS3.1/SS3.1.2): `"accepted"` for every admitted command; `session/compact` alone may answer `"noop"`. Closed: SS3.1.2 names exactly these two values, so SDK clients get a discriminated type and validation catches a wrong status (PR #21550 review) — and a client that received a third value would have been told nothing it can act on, unlike [`TurnStartDisposition`], where "acked, not otherwise classified" is a usable reading. */
481
+ /** The ack-status vocabulary: `"accepted"` for every admitted command; `session/compact` alone may answer `"noop"`. Closed: the protocol defines exactly these two values, so SDK clients get a discriminated type and validation catches a wrong status — and a client that received a third value would have been told nothing it can act on, unlike [`TurnStartDisposition`], where "acked, not otherwise classified" is a usable reading. */
309
482
  export type CommandAckStatus = "accepted" | "noop";
310
483
 
311
484
  /** The SS3.1.2 ack `status`: `accepted` for every admitted command. `session/compact` is the one method that may additionally answer `noop` ([`crate::method::runtime::CompactStatus`]); no other command uses another status (tdd SS3.1.2). */
@@ -464,9 +637,9 @@ export interface ContextUsage {
464
637
  windowTokens?: number;
465
638
  }
466
639
 
467
- /** 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. */
640
+ /** Cron's `details` payload (ADR 42728 D2, thirteenth directive). Every field a family owns lives here, under the container's one `details` key, rather than flat beside the discriminators. Each is a **bounded machine fact**: scalars, short identifiers and a small fixed-shape array of those. */
468
641
  export interface CronReceipt {
469
- /** 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. */
642
+ /** Cron `create` and `delete`: the job id. On `delete`'s `missing` arm this is the caller's own id echoed back — that arm has no server-side subject to name. On the `created` + `cancelled` pairing, this field also conveys the hidden fact: a job row was committed and will fire. */
470
643
  jobId?: string;
471
644
  /** Cron `list`: the served jobs in server order, `active` and `firing` rows only. */
472
645
  jobs?: CronReceiptJob[];
@@ -474,7 +647,7 @@ export interface CronReceipt {
474
647
  nextFireAtMs?: number;
475
648
  }
476
649
 
477
- /** 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. */
650
+ /** One row of the Cron `list` receipt's `jobs` array (ADR 42728 D2). Server order, and **`active` + `firing` rows only**. A small fixed-shape array of scalars, which is what keeps it a bounded machine fact. */
478
651
  export interface CronReceiptJob {
479
652
  /** The job's server-owned id. */
480
653
  jobId: string;
@@ -490,7 +663,7 @@ export interface CumulativeCost {
490
663
  usd: number;
491
664
  }
492
665
 
493
- /** 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. */
666
+ /** Session running totals of counted-once usage (tdd SS4.6.5). The cache splits and server-computed `cost` join the counters. The counters stay accumulate-only; `cost` is the documented exception — it may move either way on price re-adoption and is labeled estimate. `Copy` was dropped for the `cost` member. */
494
667
  export interface CumulativeTokenUsage {
495
668
  /** 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. */
496
669
  cacheReadTokens?: number;
@@ -546,11 +719,11 @@ export interface ErrorData {
546
719
  alignedNextOffset?: number;
547
720
  /** The rejected anchor value on `notFound`/`missingAnchor` and the `-32042` boundary arms (SS4.7.3, SS4.11); on `-32042` it is served as an explicit `null` when the request named no concrete anchor (spec 208 FM-005). */
548
721
  anchor?: string | null;
549
- /** Approval identity on SS5 errors. */
722
+ /** Approval id on approval errors. */
550
723
  approvalId?: string;
551
724
  /** 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). */
552
725
  availability?: string;
553
- /** 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). */
726
+ /** The missing capability, on `capabilityRequired` errors. Typed on the grantable registry, so the experimental-only `rawLog` joins the stable domain as an additive open-enum extension when it graduates. */
554
727
  capability?: CapabilityName;
555
728
  /** The configured command-admission bound, on `backpressured` errors. */
556
729
  capacity?: number;
@@ -560,7 +733,7 @@ export interface ErrorData {
560
733
  commandId?: string;
561
734
  /** Current stage token on `approvalRequirementStale`. */
562
735
  currentRequirementId?: ApprovalRequirementRef;
563
- /** SS1.5.1 descriptor, on `experimentalRequired` errors. */
736
+ /** On `experimentalRequired` errors, the name of the experimental method, field or variant the request used, for example `turn/start.providerRequestOptions`. */
564
737
  descriptor?: string;
565
738
  /** Free-form additive detail. */
566
739
  details?: Record<string, unknown>;
@@ -604,13 +777,13 @@ export interface ErrorData {
604
777
  settlement?: UserInputSettlementSummary;
605
778
  /** The rejected upload id on `uploadNotFound` (`-32038`, SS3.33). */
606
779
  uploadId?: string;
607
- /** User-input prompt identity on SS5.10 errors. */
780
+ /** Prompt identity on user-input errors. */
608
781
  userInputId?: string;
609
782
  /** The blocked view position on `pageEventTooLarge` errors. */
610
783
  viewCursor?: string;
611
784
  }
612
785
 
613
- /** 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. */
786
+ /** A stable `error.data.kind` category: camelCase, the value clients branch on. Open: new kinds are added as their methods land, and a new `kind` is additive only because this domain is declared open. */
614
787
  export type ErrorKind = "parseError" | "invalidRequest" | "notInitialized" | "alreadyInitialized" | "methodNotFound" | "invalidParams" | "experimentalRequired" | "internal" | "pageEventTooLarge" | "outputResultTooLarge" | "overloaded" | "inputTooLarge" | "capabilityRequired" | "notFound" | "interrupted" | "cancelled" | "sessionNotFound" | "sessionInUse" | "sessionAmbiguous" | "forkBoundaryInvalid" | "sessionNotLoaded" | "sessionStreamMismatch" | "commandRejected" | "backpressured" | "skillNotFound" | "computerUseUnavailable" | "marketplaceNotFound" | "pluginNotFound" | "marketplaceAlreadyExists" | "pluginMutationsDisabled" | "uploadNotFound" | "viewTruncated" | "outputUnavailable" | "boundaryPruned" | "boundaryUnusable" | "noBoundary" | "approvalNotFound" | "approvalAlreadyResolved" | "approvalChoiceInvalid" | "approvalRequirementStale" | "approvalReviewerUnavailable" | "userInputNotFound" | "userInputAlreadySettled" | "userInputAnswerInvalid" | (string & {});
615
788
 
616
789
  /** The `error` member of an error response (SS1.2 §2.4). */
@@ -699,7 +872,7 @@ export interface ForkProvenance {
699
872
 
700
873
  /** The session goal block (tdd SS4.6.2, mirrors the runtime's goal state, camelCased). `status` and `percentComplete` are carried **verbatim** — out-of-contract status strings and >100 percents pass through; display clamping is the renderer's job. */
701
874
  export interface Goal {
702
- /** ADR 50064 D2 (pick-4): goal creation time, epoch milliseconds, verbatim from the durable row. Absent on blocks whose producer never carried it (tool-result adoptions, pre-pick-4 logs); absence must never render as a fabricated zero. */
875
+ /** Goal creation time, epoch milliseconds, verbatim from the durable row. Absent on blocks whose producer never carried it (tool-result adoptions, older logs); absence must never render as a fabricated zero. */
703
876
  createdAtMs?: number;
704
877
  /** Current work description, when present. */
705
878
  currentWork?: string;
@@ -711,7 +884,7 @@ export interface Goal {
711
884
  percentComplete: number;
712
885
  /** Goal status, verbatim from the durable goal state (free string by design: out-of-contract values pass through). */
713
886
  status: string;
714
- /** ADR 50064 D2 (pick-4): last goal mutation time, epoch milliseconds, verbatim from the durable row. Same absence rule as `createdAtMs`. */
887
+ /** Last goal mutation time, epoch milliseconds, verbatim from the durable row. Same absence rule as `createdAtMs`. */
715
888
  updatedAtMs?: number;
716
889
  }
717
890
 
@@ -772,7 +945,7 @@ export interface GoalSetParams {
772
945
  /** 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". */
773
946
  export type HistoryMode = "anchoredSnapshot" | "inline" | "snapshot" | "none" | (string & {});
774
947
 
775
- /** Why a result served `history.mode: "none"` — spec 208 FM-005's typed unavailability (tdd SS2.5.2; D-050). Open on the client side: an absent (older server) or unknown (newer server) value decodes conservatively as an unknown reason, and `viewCursor` text never substitutes for it (spec 208 INV-19734-1). */
948
+ /** Why a result served `history.mode: "none"`: the server's typed reason for serving no history. Open on the client side: an absent (older server) or unknown (newer server) value decodes conservatively as an unknown reason, and `viewCursor` text never substitutes for it. */
776
949
  export type HistoryNoneReason = "excluded" | "cursorSuffix" | "historyBudget" | "projectionUnavailable" | "projectionReadLimit" | (string & {});
777
950
 
778
951
  /** 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. */
@@ -791,7 +964,7 @@ export interface HookCatalogEntry {
791
964
  }
792
965
 
793
966
  /** 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. */
794
- export type HookEventName = "sessionStart" | "userPromptSubmit" | "preToolUse" | "permissionRequest" | "postToolUse" | "preCompact" | "postCompact" | "subagentStart" | "subagentStop" | "stop" | "sessionEnd" | "notification" | "postToolUseFailure" | "stopFailure" | "postToolBatch" | "interrupt" | "sessionFork" | "toolUseStart" | "preLLMCall" | "postLLMCall" | (string & {});
967
+ export type HookEventName = "sessionStart" | "userPromptSubmit" | "preToolUse" | "permissionRequest" | "postToolUse" | "preLLMCall" | "postLLMCall" | "preCompact" | "postCompact" | "subagentStart" | "subagentStop" | "stop" | "sessionEnd" | "notification" | "postToolUseFailure" | "stopFailure" | "postToolBatch" | "interrupt" | "sessionFork" | "toolUseStart" | (string & {});
795
968
 
796
969
  /** 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. */
797
970
  export type HookHandlerKind = "managed" | "user" | "project" | "plugin" | (string & {});
@@ -834,7 +1007,7 @@ export interface InitializeResult {
834
1007
  platformFamily: PlatformFamily;
835
1008
  /** Server operating system. */
836
1009
  platformOs: PlatformOs;
837
- /** Whether this host can enforce the sandbox (ADR 50064-startup-report-sandbox-availability D2/D4). Optional so the addition is additive under SS1.5.4; a v1 host always sends it, and a client reads absent as unknown — the host predates the field, so the client falls back to its own probe rather than inventing an answer. */
1010
+ /** Whether this host can enforce the sandbox. Optional so adding it stays backward compatible; a v1 host always sends it, and a client reads absent as unknown — the host predates the field, so the client falls back to its own probe rather than inventing an answer. */
838
1011
  sandboxAvailability?: SandboxAvailability;
839
1012
  /** Why enforcement is impossible. Sent only when `sandbox_availability` is `unavailable`; a client MUST NOT infer a reason when none is sent. */
840
1013
  sandboxUnavailableReason?: SandboxUnavailableReason;
@@ -842,7 +1015,7 @@ export interface InitializeResult {
842
1015
  schema: SchemaInfo;
843
1016
  /** Server identification. */
844
1017
  serverInfo: ServerInfo;
845
- /** Whether this host persists its sessions (SS2.13). Optional so the addition is additive under SS1.5.4; a v1 host always sends it, and a client reads absent as `durable` because no server that omits it has the ephemeral profile. */
1018
+ /** Whether this host persists its sessions. Optional so adding it stays backward compatible; a v1 host always sends it, and a client reads absent as `durable` because no server that omits it has the ephemeral profile. */
846
1019
  sessionDurability?: SessionDurability;
847
1020
  /** Exact user-agent string presented to upstream model providers. */
848
1021
  userAgent: string;
@@ -862,6 +1035,8 @@ export interface Item {
862
1035
  background?: boolean;
863
1036
  /** `toolCall`: who backgrounded the task; absent on pre-split records — never inferred (tdd SS4.5.5). */
864
1037
  backgroundInitiator?: BackgroundInitiator;
1038
+ /** `backgroundTerminalCompletion`: the five facts the Finished cell renders (ADR 50041 D4). */
1039
+ backgroundTerminalCompletion?: BackgroundTerminalCompletion;
865
1040
  /** `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`. */
866
1041
  blocking?: boolean;
867
1042
  /** `toolCall`: the provider call id (`call_...`), opaque. */
@@ -894,7 +1069,7 @@ export interface Item {
894
1069
  displayLabel?: ToolDisplayLabel;
895
1070
  /** `userMessage`: presentation form (tdd SS3.2); absent when the client sent none. */
896
1071
  displayText?: string;
897
- /** `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. */
1072
+ /** `userShell`/`subagent`: observed wall-clock duration. `workflow`: the run's wall time from launch to reconciliation, set only on the settling `item/completed` — never a sum of child durations. `toolCall`: the Backgrounded row's duration (ADR 50041 D11) — the open→update record delta in whole ms, served on the `backgroundStatus` re-emission and frozen there; absent otherwise. */
898
1073
  durationMs?: number;
899
1074
  /** `workflow`: launched entry identity. */
900
1075
  entryId?: string;
@@ -998,7 +1173,7 @@ export interface Item {
998
1173
  strategyId?: string;
999
1174
  /** `subagent`: durable child identity (`subagent_id`). */
1000
1175
  subagentId?: string;
1001
- /** `compaction`: opaque provenance string naming the compaction boundary. A compaction-anchored read anchor since D-029 (2026-08-12): accepted by `session/resume` and `view/page` (wire shape and validation are the #208 lane's). Still opaque — clients relay it, never parse it (tdd SS4.5.10). */
1176
+ /** `compaction`: opaque provenance string naming the compaction boundary. Also a compaction-anchored read anchor, accepted by `session/resume` and `view/page`. Still opaque — clients relay it, never parse it. */
1002
1177
  summarizedThrough?: string;
1003
1178
  /** `reasoning`: one entry per summary part; part *n* streams via `item/delta` field `"summary.n"` (part boundary = index change). */
1004
1179
  summary?: string[];
@@ -1059,12 +1234,12 @@ export interface ItemDeltaParams {
1059
1234
  }
1060
1235
 
1061
1236
  /** The eleven v1 item kinds (tdd SS4.5.2–4.5.13) plus post-v1 kinds (tdd SS4.5.14+). Open: a new kind is additive evolution, and clients MUST render unknown kinds generically (tdd SS4.10). */
1062
- export type ItemKind = "userMessage" | "agentMessage" | "reasoning" | "toolCall" | "userShell" | "subagent" | "workflow" | "reminderChild" | "compaction" | "hookRun" | "sideChat" | "webSearch" | "monitorFeed" | "damagedRange" | "scheduledFire" | (string & {});
1237
+ export type ItemKind = "userMessage" | "agentMessage" | "reasoning" | "toolCall" | "userShell" | "subagent" | "workflow" | "reminderChild" | "compaction" | "hookRun" | "sideChat" | "webSearch" | "monitorFeed" | "damagedRange" | "scheduledFire" | "backgroundTerminalCompletion" | "overdueNotice" | (string & {});
1063
1238
 
1064
1239
  /** 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. */
1065
1240
  export type ItemReadOutputEncoding = "utf8" | "base64";
1066
1241
 
1067
- /** `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. */
1242
+ /** `item/readOutput` params: byte-ranged fetch of stored full output that the view truncated, via the item's `outputRef`. Read-only; works on loaded and unloaded sessions; no lease. */
1068
1243
  export interface ItemReadOutputParams {
1069
1244
  /** The item whose stored output is fetched. */
1070
1245
  itemId: string;
@@ -1147,7 +1322,7 @@ export interface MediaUploadParams {
1147
1322
  chunkCount: number;
1148
1323
  /** This chunk's 0-based position. */
1149
1324
  chunkIndex: number;
1150
- /** One per call; SS3.1.1 replay answers the recorded receipt. */
1325
+ /** One per call. While the host runs, replaying it with the same params returns the recorded receipt, and reusing it with different params is refused. After a host restart, start over under a new `uploadId`. */
1151
1326
  commandId: string;
1152
1327
  /** `video/mp4` or `video/quicktime`, matching `VideoInput`. */
1153
1328
  mediaType: string;
@@ -1409,7 +1584,7 @@ export interface PendingApprovalPointer {
1409
1584
  /** The `pendingRequests` discriminator (tdd SS2.5.2). Open enum, v1 values `approval` and `userInput`. */
1410
1585
  export type PendingRequestKind = "approval" | "userInput" | (string & {});
1411
1586
 
1412
- /** A late-joiner pointer at an unsettled server-initiated request (tdd SS2.5.2, SS2.2.1). The full payloads arrive as re-issued server-to-client requests right after a `session/resume` response (tdd SS5.6); `session/read` never re-issues them (tdd SS2.5.5). **A second E4 instance, RULED with E4 (#22785, owner, 2026-08-26): the flat discriminated-object precedent is accepted for this type too, on the `ApprovalSubject` precedent, with the serialized JSON unchanged. A strict union node kind may be funded later; if it is, it must cover both this type and `TurnInputPart`.** SS2.5.2 ratifies two kind-discriminated entry shapes (`{kind: "approval", approvalId, viewCursor}` / `{kind: "userInput", userInputId, viewCursor}`); this is one flat object with both ids optional, so the published schema accepts `{"kind":"approval","userInputId":…}` and an entry carrying no id at all. The v1 model names no object-variant union (the `ApprovalSubject` precedent, followed for `TurnInputPart`), and this instance differs from that one in a way the ruling should see: `kind` here is an OPEN enum, where `TurnInputPart.type` is closed. */
1587
+ /** A late-joiner pointer at an unsettled server-initiated request (tdd SS2.5.2, SS2.2.1). The full payloads arrive as re-issued server-to-client requests right after a `session/resume` response (tdd SS5.6); `session/read` never re-issues them (tdd SS2.5.5). The protocol defines two kind-discriminated entry shapes (`{kind: "approval", approvalId, viewCursor}` / `{kind: "userInput", userInputId, viewCursor}`). This type is one flat object with both ids optional, as for `ApprovalSubject` and `TurnInputPart`, because the v1 model names no object-variant union; the serialized JSON is the same, but the published schema also accepts `{"kind":"approval","userInputId":…}` and an entry carrying no id at all. Unlike `TurnInputPart.type`, `kind` here is an OPEN enum. */
1413
1588
  export interface PendingRequestPointer {
1414
1589
  /** Present on an `approval` entry. */
1415
1590
  approvalId?: string;
@@ -1431,7 +1606,7 @@ export interface PendingUserInputPointer {
1431
1606
  viewCursor: string;
1432
1607
  }
1433
1608
 
1434
- /** The server runtime's platform family (SS1.4.1); may differ from the client's. Closed: SS1.4.1 fixes the value set, so widening it is a deliberate, gate-visible protocol change rather than a silent addition (a later `Closed`→`Open` flip is itself additive, data-model.md §5.2). */
1609
+ /** The server runtime's platform family; may differ from the client's. Closed: the protocol fixes the value set, so widening it is a deliberate, gate-visible protocol change rather than a silent addition (a later `Closed`→`Open` flip is itself additive). */
1435
1610
  export type PlatformFamily = "unix" | "windows";
1436
1611
 
1437
1612
  /** The server's operating system (SS1.4.1). Closed, for the same reason as [`PlatformFamily`]. */
@@ -1681,7 +1856,7 @@ export interface RecapCompletedParams {
1681
1856
  /** `recap/completed` failure reason (tdd SS3.28.2/SS3.28.8): post-ack failures fold to the single initial value. **Open**: later splits stay additive (#22785 E2). */
1682
1857
  export type RecapFailureReason = "providerFailed" | (string & {});
1683
1858
 
1684
- /** `recap/completed` outcome (tdd SS3.28.2): the terminal vocabulary, camelCase per SS1.6. **Open**: a server-produced result vocabulary (#22785 E2). */
1859
+ /** `recap/completed` outcome: the terminal vocabulary, in camelCase. **Open**: a server-produced result vocabulary. */
1685
1860
  export type RecapOutcome = "completed" | "failed" | "cancelled" | "timedOut" | (string & {});
1686
1861
 
1687
1862
  /** `recap/request` params (tdd SS3.28.1): the session plus the client-minted UUIDv7 retry id. No other param; unknown fields are `invalidParams`. */
@@ -1778,7 +1953,7 @@ export interface ServerInfo {
1778
1953
 
1779
1954
  /** The session object every lifecycle method returns or lists (tdd SS2.4). Additive-optional evolution applies: clients must ignore unknown fields. */
1780
1955
  export interface Session {
1781
- /** The `turnId` of the current foreground turn when `status` is `running`, and `null` when the session is idle (tdd SS2.4). **Required-nullable, per the owner ruling on #22946** ("approve required-nullable", review comment `r3863946961`, 2026-08-26). Both production writers hard-code `"activeTurnId": null` (`session/start/commit_load.rs` for `session/start`, `session/snapshot.rs` feeding resume/read/list/fork) and nothing strips it, so this is what the binary emits and what SS2.4's example spells. The optional-absent shape published it as plain `string` and REJECTED every idle `Session` frame the host sent — the #19923 defect class this PR exists to close. E5's original evidence for optional-absent ("every committed transcript shows the omission") was wrong: those transcripts are hand-authored fixtures, not host recordings. They are corrected in the same change under the ruling's SS1.5 `regenerationJustification`. */
1956
+ /** The `turnId` of the current foreground turn when `status` is `running`, and `null` when the session is idle (tdd SS2.4). **Required-nullable.** Every served `Session` carries the member: `null` when the session is idle or not loaded, the turn id when it is running. An optional-absent shape would publish it as plain `string` and reject every idle `Session` frame the host sends. */
1782
1957
  activeTurnId: string | null;
1783
1958
  /** 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). */
1784
1959
  approvalMode?: EffectiveApprovalModeState;
@@ -1895,7 +2070,7 @@ export interface SessionCompactResult {
1895
2070
  status: CompactStatus;
1896
2071
  }
1897
2072
 
1898
- /** 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. */
2073
+ /** The open configuration extension object shared by `session/start` and `session/resume` (ADR 32760 D1). Unknown keys are ignored on the wire, never rejected: the live decoder tolerates them, and no exported bundle carries `additionalProperties: false`. The Rust typed model's `deny_unknown_fields` is internal and never exported — the closedness export applies nowhere, and the `x-msp-closed` opt-in mechanism stays inert. Recognized `mcpServers` values are typed and validated before they leave the wire boundary. */
1899
2074
  export interface SessionConfig {
1900
2075
  /** Native MCP servers added only to this session runtime. */
1901
2076
  mcpServers?: Record<string, SessionMcpServerConfig>;
@@ -1958,6 +2133,8 @@ export interface SessionGoalChangedParams {
1958
2133
 
1959
2134
  /** The `history` envelope shared by `session/resume`, `session/fork`, and `session/read` (tdd SS2.5.2). */
1960
2135
  export interface SessionHistory {
2136
+ /** The checkpoint-prune boundary (spec 13929 amendment FR-50042-1): rows for served items at-or-before `through_item_id` in served order predate the selected checkpoint. Additive-optional; absence is a non-assertion (ADR 50042 D6). */
2137
+ checkpointBoundary?: CheckpointBoundary;
1961
2138
  /** The full folded item array when `mode` is `inline`; `null` otherwise. */
1962
2139
  items: Item[] | null;
1963
2140
  /** What was actually served — never what was asked for (tdd SS2.5.2). */
@@ -1973,10 +2150,15 @@ export type SessionKind = "root" | "subagent" | (string & {});
1973
2150
 
1974
2151
  /** Params of the protected, non-view leave terminal notification. */
1975
2152
  export interface SessionLeaveCompletedParams {
2153
+ /** The leave command's id, matching the `session/leave` request. */
1976
2154
  commandId: string;
2155
+ /** How the leave ended: `released` or `failed`. The set is open, so newer hosts may add outcomes. */
1977
2156
  outcome: SessionLeaveOutcome;
2157
+ /** Why the leave failed. Present when `outcome` is `failed`. */
1978
2158
  reason?: SessionLeaveFailureReason;
2159
+ /** The session the leave was for. */
1979
2160
  sessionId: string;
2161
+ /** The session's view cursor at release: everything up to it was folded before the host let go. Present when `outcome` is `released`. */
1980
2162
  viewCursor?: string;
1981
2163
  }
1982
2164
 
@@ -1998,7 +2180,9 @@ export interface SessionLeaveParams {
1998
2180
 
1999
2181
  /** The admission-only `session/leave` result. */
2000
2182
  export interface SessionLeaveResult {
2183
+ /** The leave command's id. */
2001
2184
  commandId: string;
2185
+ /** The admission status, `accepted` once the leave is admitted. The final result arrives later as `session/leaveCompleted`. Sending the same leave command again returns `accepted` and re-pushes the recorded result if there is one, from the host that ran the leave (for as long as it runs, even after the release) or from a host that has the session loaded (after a host crash, `abandoned` among them). Any other host treats it as a fresh leave: a durable host that has not loaded the session refuses it with `sessionNotLoaded` until it is resumed there. */
2002
2186
  status: CommandAckStatus;
2003
2187
  }
2004
2188
 
@@ -2030,7 +2214,7 @@ export interface SessionListParams {
2030
2214
  cursor?: string | null;
2031
2215
  /** 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. */
2032
2216
  filter?: SessionListFilter;
2033
- /** Page size; default 50, max 200 — the cap is published under #22785 E6c (owner-ruled 2026-08-26). Maximum 200. */
2217
+ /** Page size; default 50, max 200 — the schema publishes the cap. Maximum 200. */
2034
2218
  limit?: number;
2035
2219
  /** Only sessions with log activity after this RFC3339 instant. */
2036
2220
  updatedAfter?: string;
@@ -2139,6 +2323,8 @@ export interface SessionReadParams {
2139
2323
 
2140
2324
  /** `session/read` result (tdd SS2.5.5). The `viewCursor` is the fold head at read time — a point-in-time read, immediately stale if a foreign host is appending. */
2141
2325
  export interface SessionReadResult {
2326
+ /** Same member as `session/resume` (tdd SS2.5.5, ADR 50074 D2). */
2327
+ blockedPrompt?: BlockedPrompt;
2142
2328
  /** The served history. */
2143
2329
  history: SessionHistory;
2144
2330
  /** Same member as `session/resume` (tdd SS2.5.5, ADR 36635 D2). */
@@ -2155,7 +2341,7 @@ export interface SessionReadResult {
2155
2341
 
2156
2342
  /** `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). */
2157
2343
  export interface SessionReasoningEffortChangedParams {
2158
- /** The new session default: the closed eight-string tier vocabulary of tdd SS3.2, spelled identically. */
2344
+ /** The new session default: the same closed eight-string tier vocabulary as `turn/start`. */
2159
2345
  reasoningEffort: ReasoningEffort;
2160
2346
  /** The owning session. */
2161
2347
  sessionId: string;
@@ -2193,7 +2379,7 @@ export interface SessionResumeParams {
2193
2379
  commandId: string;
2194
2380
  /** The same open construction-time extension object as `session/start`. */
2195
2381
  config?: SessionConfig;
2196
- /** 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). */
2382
+ /** A view cursor previously observed by this client — or an observed `summarizedThrough` compaction anchor. When it names an event the server still holds, the server returns only the suffix and `history.mode` is `none`. A cursor the server minted that names no event yet, such as the empty start cursor of a session that had no events, is treated as no cursor: the server serves what a resume without a cursor would. A cursor older than the earliest event the server still holds gets a snapshot, or `-32040` `viewTruncated` when none fits. A cursor this session's view never minted is refused with `-32011` `notFound`, reason `missingAnchor`, and a compaction anchor naming a boundary the server has pruned is refused with `-32042` `boundaryPruned`. Omitted and explicit `null` both mean "no cursor". */
2197
2383
  cursor?: string | null;
2198
2384
  /** Return only session metadata and live resume state; page history separately with `view/page`. Default `false` (tdd SS2.5.2). */
2199
2385
  excludeItems?: boolean;
@@ -2209,6 +2395,8 @@ export interface SessionResumeParams {
2209
2395
 
2210
2396
  /** `session/resume` result (tdd SS2.5.2). */
2211
2397
  export interface SessionResumeResult {
2398
+ /** The recallable blocked prompt's refill text (ADR 50074 D2). **Additive-optional**; absence means no blocked prompt to recall (an unblocked session, or a pre-feature host). Data only, never a rendered row: clients seed cold recall from it (C-p refills `text`) and MUST NOT display it as history. */
2399
+ blockedPrompt?: BlockedPrompt;
2212
2400
  /** The served history. */
2213
2401
  history: SessionHistory;
2214
2402
  /** How the last folded turn ended (tdd SS2.5.2, ADR 36635 D2). **Additive-optional**; absence is a non-assertion. */
@@ -2305,7 +2493,7 @@ export interface SessionStartParams {
2305
2493
  approvalMode?: ApprovalMode | null;
2306
2494
  /** The SS2.5 idempotency handle (UUIDv7). Required; the server never mints one. */
2307
2495
  commandId: string;
2308
- /** Reserved for per-session overrides owned by a future Configuration section. Issue #32760 admits only its `mcpServers` member. */
2496
+ /** Reserved for future per-session overrides; only its `mcpServers` member is admitted. */
2309
2497
  config?: SessionConfig;
2310
2498
  /** Initial model; server default when omitted. */
2311
2499
  modelId?: string;
@@ -2588,7 +2776,7 @@ export interface SnapshotAnchor {
2588
2776
  summarizedThrough: string;
2589
2777
  }
2590
2778
 
2591
- /** The complete folded view at the snapshot cursor (tdd SS4.9.1). Additive-optional evolution applies exactly as everywhere else; unknown members MUST be ignored, and preserved if re-serialized. **One served site does not satisfy this type today, escalated under #22785 (E8).** The genesis snapshot rung serves `state: {"items": [...]}` alone (`tbh-session-view-serve`'s `materialized_fold.rs`, the `select_genesis_history` call), while the anchored rung serves the full folded state. A schema-validating client resuming with `{"history": "snapshot"}` against the real fold therefore sees the other required members missing. The fix is a serving change in the #208/#14653 lane (serialize the `SessionViewState` the genesis path already folds, as the anchored path does) plus its own RED against the real fold; it is not a shape change here, because SS4.9.1 ratifies this shape. */
2779
+ /** The complete folded view at the snapshot cursor (tdd SS4.9.1). Additive-optional evolution applies exactly as everywhere else; unknown members MUST be ignored, and preserved if re-serialized. */
2592
2780
  export interface SnapshotState {
2593
2781
  /** The running foreground turn; `null` when none is running. */
2594
2782
  activeTurn: TurnRef | null;
@@ -2596,7 +2784,7 @@ export interface SnapshotState {
2596
2784
  approvalMode: EffectiveApprovalModeState;
2597
2785
  /** Latest branch observation; `null` when no fact has landed. */
2598
2786
  branch: BranchState | null;
2599
- /** The latest `(windowTokens, usedTokens, pressure)` triple. SS4.9.1 says "`null`/absent" and SS4.9.2's worked example OMITS the member; the binary omits it too, so this is the absent arm — the four siblings above are present-null in the same frame. INV-017 admits one or the other, never both; escalated under #22785. */
2787
+ /** The latest `(windowTokens, usedTokens, pressure)` triple. The protocol allows "`null`/absent" and its worked example OMITS the member; the binary omits it too, so this is the absent arm — the four siblings above are present-null in the same frame. A member is published as one or the other, never both. */
2600
2788
  contextUsage?: ContextUsage;
2601
2789
  /** Latest effective model; `null` when no fact has landed. */
2602
2790
  effectiveModel: EffectiveModel | null;
@@ -2820,10 +3008,17 @@ export interface TaskCommandResult {
2820
3008
  taskId: string;
2821
3009
  }
2822
3010
 
2823
- /** 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. */
3011
+ /** A task row's execution mode (tdd SS3.31, ADR 62268 D2). Open (server-produced result vocabulary, the #22785 enum-openness rule): clients MUST ignore unknown modes. */
3012
+ export type TaskExecutionMode = "foreground" | "background" | (string & {});
3013
+
3014
+ /** One task inventory row (tdd SS3.31). The row is the stable contract: `kind` and `status` stay open so a future state extends them without breaking clients. */
2824
3015
  export interface TaskListEntry {
2825
3016
  /** Who backgrounded the task, mirroring the item field. **Additive-optional**: absent on pre-split records and registry-only rows, never inferred. */
2826
3017
  backgroundInitiator?: BackgroundInitiator;
3018
+ /** The raw command text: the joined `toolCall` item's `command` argument verbatim (ADR 62268 D2). **Additive-optional**: omitted when the row has no item or the item carries no command. Monitors join raw — clients redact (INV-17544-6). */
3019
+ command?: string;
3020
+ /** `"foreground" | "background"` (ADR 62268 D2). **Additive-optional**: absent means `"background"` (only pre-change hosts omit it, and those list background rows only); never guessed. */
3021
+ executionMode?: TaskExecutionMode;
2827
3022
  /** 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. */
2828
3023
  kind: string;
2829
3024
  /** The host-known task start, RFC3339. **Additive-optional**: omitted, never guessed, when the host does not know it. */
@@ -2842,9 +3037,9 @@ export interface TaskListParams {
2842
3037
  sessionId: string;
2843
3038
  }
2844
3039
 
2845
- /** `task/list` result (tdd SS3.31): one row per running background workload in `task/stopAll` reach, oldest first; empty when nothing is running. */
3040
+ /** `task/list` result (tdd SS3.31): one row per live workload, background and foreground (ADR 62268 D1), oldest first; empty when nothing is running. */
2846
3041
  export interface TaskListResult {
2847
- /** The session's live background-task rows. */
3042
+ /** The session's live task rows. */
2848
3043
  tasks: TaskListEntry[];
2849
3044
  }
2850
3045
 
@@ -3015,7 +3210,7 @@ export interface TurnForegroundCompletedParams {
3015
3210
  viewCursor: string;
3016
3211
  }
3017
3212
 
3018
- /** 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`. */
3213
+ /** One ordered content part of a turn submission (tdd SS3.2). File mentions are text, not a part type: write `@relative/path` in a text part. A structured `mention` part is reserved and currently rejected, and an unknown part type is `invalidParams` (tdd SS3.1.2, SS3.2) — which is what closes [`TurnInputPartType`]. Modelled as a discriminated flat object rather than a Rust `enum`, the convention [`crate::view::approval::ApprovalSubject`] already established for a wire union in this crate: the v1 schema model names no object-variant union shape and fails closed on one. The serialized JSON is the same either way; what a flat object cannot express is "`mediaType` is required exactly when `type` is `image`". `height` may only appear together with `width`. `width` may only appear together with `height`. */
3019
3214
  export interface TurnInputPart {
3020
3215
  /** 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). */
3021
3216
  arguments?: string;
@@ -3027,7 +3222,7 @@ export interface TurnInputPart {
3027
3222
  mediaType?: string;
3028
3223
  /** 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. */
3029
3224
  selector?: string;
3030
- /** The picked copy's source, optional on a `skill` part (tdd SS3.22.3; ADR 32471 D12): the D2 catalog-row `source` values. When present the host resolves the exact `(selector, source)` row; when absent D4's bare resolution applies byte-for-byte. Closed: an unknown value is `invalidParams`, never a fall-through. */
3225
+ /** The picked copy's source, optional on a `skill` part: one of the catalog rows' `source` values. When present the host resolves the exact `(selector, source)` row; when absent it resolves the selector, bare or plugin-qualified, against the session's skill catalog, as the TUI shortcut does. Closed: an unknown value is `invalidParams`, never a fall-through. */
3031
3226
  source?: SkillInvocationSource;
3032
3227
  /** User prompt text, on a `text` part. Multiple text parts are joined in order into the turn's prompt. */
3033
3228
  text?: string;
@@ -3035,7 +3230,7 @@ export interface TurnInputPart {
3035
3230
  type: TurnInputPartType;
3036
3231
  /** The upload receipt, required on a `video` part (tdd SS3.2, SS3.33; ADR 45443 D5): the client-minted id `media/upload` echoed. */
3037
3232
  uploadId?: string;
3038
- /** Pixel width; must be provided together with `height` or not at all (tdd SS3.2). Published as a `dependentRequired` pair under #22785 E6c. */
3233
+ /** Pixel width; must be provided together with `height` or not at all. Published as a `dependentRequired` pair. */
3039
3234
  width?: number;
3040
3235
  }
3041
3236
 
@@ -3098,7 +3293,7 @@ export interface TurnRef {
3098
3293
  displayText?: string;
3099
3294
  /** `queuedTurns[]` only: set when `displayText` was cut to the committed-surface budget, mirroring `userMessage.truncated` (tdd SS4.5.2). Absent unless `true`. */
3100
3295
  truncated?: boolean;
3101
- /** The turn's id, pre-minted per tdd SS3.1.4. */
3296
+ /** The turn's id, minted at admission. */
3102
3297
  turnId: string;
3103
3298
  }
3104
3299
 
@@ -3264,7 +3459,7 @@ export interface TurnUserShell {
3264
3459
  commandText: string;
3265
3460
  }
3266
3461
 
3267
- /** One element of a `view/page` result's `events` array: an **unframed view notification** exactly as tdd SS4.2.1 defines it — the nested pair `{"method", "params"}`, which is the live notification minus `jsonrpc` and `emittedAtMs`, with nothing lifted out of `params` and nothing spliced into it. SS4.2.1 is the single normative definition; SS4.7.3 and SS7.4 both cite it, so the two surfaces cannot drift. */
3462
+ /** One element of a `view/page` result's `events` array: an **unframed view notification** — the nested pair `{"method", "params"}`, which is the live notification minus `jsonrpc` and `emittedAtMs`, with nothing lifted out of `params` and nothing spliced into it. `view/page` and `muse exec --json` share this one definition, so the two surfaces cannot drift. */
3268
3463
  export interface UnframedViewNotification {
3269
3464
  /** The event type — the live notification's method name, retained because the type lives only in the notification name and would otherwise be lost (tdd SS4.2.1). */
3270
3465
  method: string;
@@ -3272,7 +3467,7 @@ export interface UnframedViewNotification {
3272
3467
  params: UnframedViewNotificationParams;
3273
3468
  }
3274
3469
 
3275
- /** The `params` of an unframed view notification (tdd SS4.2.1, SS4.2). Declares the SS4.2 base members every view notification carries, and stays **open** for the event-specific fields SS4.5/SS4.6/SS5 add per event type. The v1 schema model names no method-correlated union (the SS4.7.3 `events` element's `params` arm is selected by its sibling `method`), so the per-event arms cannot be expressed here without one; enumerating them as an uncorrelated union would additionally exclude `turn/unqueued`, whose notification row is another lane's ratified deferral (#207/#14407) — a published schema that rejects a real page element is the exact #19923 defect this PR exists to close. Recorded as a Design delta on #22785. `sourceRange` is required here and not optional: `view/page` serves durable-sourced events only (tdd SS4.7.3), and durable-sourced is *defined* as carrying a `sourceRange` — the SS4.2 ephemeral-sourced exemption applies to `item/delta`, which `view/page` never replays. */
3470
+ /** The `params` of an unframed view notification (tdd SS4.2.1, SS4.2). Declares the base members every view notification carries, and stays **open** for the event-specific fields each event type adds. The v1 schema model names no method-correlated union (the `events` element's `params` arm is selected by its sibling `method`), so the per-event arms cannot be expressed here without one, and an uncorrelated union of them could reject a real page element, which a published schema must not do. `sourceRange` is required here and not optional: `view/page` serves durable-sourced events only (tdd SS4.7.3), and durable-sourced is *defined* as carrying a `sourceRange` — the SS4.2 ephemeral-sourced exemption applies to `item/delta`, which `view/page` never replays. */
3276
3471
  export interface UnframedViewNotificationParams {
3277
3472
  /** The owning session (tdd SS4.2). */
3278
3473
  sessionId: string;
@@ -3291,15 +3486,21 @@ export interface UsageReadResult {
3291
3486
  usage?: SubscriptionUsage;
3292
3487
  }
3293
3488
 
3489
+ /** One question's answer, as sent in `userInput/answer` or `userInput/interrupt` and as recorded in `userInput/settled`. */
3294
3490
  export interface UserInputAnswer {
3491
+ /** A free-form answer, at most 500 characters. */
3295
3492
  freeText?: string;
3493
+ /** An optional comment the user adds to the answer, at most 500 characters. */
3296
3494
  note?: string;
3495
+ /** The `id` of the question this answers. */
3297
3496
  questionId: string;
3497
+ /** The label of the chosen option, for a `single` question. */
3298
3498
  selectedLabel?: string;
3499
+ /** The labels of the chosen options for a `multiple` question, within its selection bounds; omitted when empty. */
3299
3500
  selectedLabels?: string[];
3300
3501
  }
3301
3502
 
3302
- /** `userInput/answer` params (tdd SS5.10.2): answer every question. Each answer carries `questionId` then exactly one of `selectedLabel` (single mode), `selectedLabels` (multiple mode, within min/max bounds), or `freeText` (<=500 chars); plus an optional `note` (<=500). Answers that do not match the prompt fail -32057 `userInputAnswerInvalid`. Image `attachments` are a **reserved** field in v1, rejected if sent, because the blob-upload path they reference is reserved in tdd SS3.2. */
3503
+ /** `userInput/answer` params (tdd SS5.10.2): answer every question. Each answer carries `questionId` then exactly one of `selectedLabel` (single mode), `selectedLabels` (multiple mode, within min/max bounds), or `freeText` (<=500 chars); plus an optional `note` (<=500). Answers that do not match the prompt fail -32057 `userInputAnswerInvalid`. Image `attachments` are a **reserved** field in v1, rejected if sent, because the blob-upload path they reference is also reserved. */
3303
3504
  export interface UserInputAnswerParams {
3304
3505
  /** One entry per question. */
3305
3506
  answers: UserInputAnswer[];
@@ -3343,8 +3544,11 @@ export interface UserInputCancelResult {
3343
3544
  userInputId: string;
3344
3545
  }
3345
3546
 
3547
+ /** A free-form reply the user gives instead of choosing from the options; the model reads it and decides again. */
3346
3548
  export interface UserInputClarification {
3549
+ /** The clarification text, at most 500 characters. */
3347
3550
  content: string;
3551
+ /** The content format. `text` is the only value today, and more may be added. */
3348
3552
  format: string;
3349
3553
  }
3350
3554
 
@@ -3400,67 +3604,107 @@ export interface UserInputInterruptResult {
3400
3604
  userInputId: string;
3401
3605
  }
3402
3606
 
3607
+ /** One option offered for a question. */
3403
3608
  export interface UserInputOption {
3609
+ /** An optional longer explanation of the option, at most 240 characters. */
3404
3610
  description?: string;
3611
+ /** The option's text, at most 80 characters and unique within its question; an answer selects the option by this exact label. */
3405
3612
  label: string;
3613
+ /** An optional rich preview of the option, present only on single-select questions. */
3406
3614
  preview?: UserInputOptionPreview;
3407
3615
  }
3408
3616
 
3617
+ /** Rich content a client can show for an option. Only single-select questions carry previews. */
3409
3618
  export interface UserInputOptionPreview {
3619
+ /** The preview content in that format, at most 2000 characters. */
3410
3620
  content: string;
3621
+ /** The content format, for example `markdown`. */
3411
3622
  format: string;
3412
3623
  }
3413
3624
 
3625
+ /** How a user-input prompt settled. More values may be added, so handle values you do not recognize. */
3414
3626
  export type UserInputOutcome = "answered" | "cancelled" | "interrupted" | "clarified" | "timedOut" | "aborted" | (string & {});
3415
3627
 
3628
+ /** One question in a user-input prompt. */
3416
3629
  export interface UserInputQuestion {
3630
+ /** A short title for the question, at most 12 characters. */
3417
3631
  header: string;
3632
+ /** The question's id, unique within the prompt and at most 64 characters. An answer names it in `questionId`. */
3418
3633
  id: string;
3634
+ /** The options offered, two or three, in order. */
3419
3635
  options: UserInputOption[];
3636
+ /** The full question text to show the user. */
3420
3637
  question: string;
3638
+ /** Whether the user picks one option or several. */
3421
3639
  selection: UserInputSelection;
3422
3640
  }
3423
3641
 
3424
3642
  /** Full params shared by `userInput/request` and `userInput/requested`. */
3425
3643
  export interface UserInputRequestParams {
3644
+ /** The auto-resolution time per question, in milliseconds: a prompt nobody engages with settles as `timedOut` after this value times the number of questions. */
3426
3645
  autoResolutionMs?: number;
3646
+ /** The `toolCall` view item of the tool call waiting on this prompt. */
3427
3647
  itemId: string;
3648
+ /** The questions to ask, one to three, in order. */
3428
3649
  questions: UserInputQuestion[];
3650
+ /** The session that owns the prompt. */
3429
3651
  sessionId: string;
3652
+ /** The stored records this prompt was folded from, when sent: an opaque token clients must not interpret. */
3430
3653
  sourceRange?: SourceRange;
3654
+ /** The provider's id for the tool call that opened the prompt. */
3431
3655
  toolCallId: string;
3656
+ /** The name of the tool that opened the prompt. */
3432
3657
  toolName: string;
3658
+ /** The turn whose tool call is waiting on this prompt. */
3433
3659
  turnId: string;
3660
+ /** The prompt's stable id. Pass it to `userInput/answer`, `userInput/cancel`, `userInput/clarify` and `userInput/interrupt`, and use it to match the later `userInput/settled`. */
3434
3661
  userInputId: string;
3662
+ /** The cursor of the `userInput/requested` event for this prompt. A client that missed the request can read the same payload at this cursor with `view/page`. */
3435
3663
  viewCursor: string;
3436
3664
  }
3437
3665
 
3666
+ /** How many options the user may pick for a question. */
3438
3667
  export interface UserInputSelection {
3668
+ /** The most options the user may pick. Sent only in `multiple` mode; when absent the maximum is the number of options. */
3439
3669
  maxSelections?: number;
3670
+ /** The minimum selection count for a `multiple` answer. Sent only in `multiple` mode; when absent the minimum is 1. */
3440
3671
  minSelections?: number;
3672
+ /** `single` or `multiple`: whether an answer selects one option or several. */
3441
3673
  mode: UserInputSelectionMode;
3442
3674
  }
3443
3675
 
3676
+ /** Whether a question takes one option or several. */
3444
3677
  export type UserInputSelectionMode = "single" | "multiple";
3445
3678
 
3446
3679
  /** `userInput/settled` params: the first durable prompt settlement. */
3447
3680
  export interface UserInputSettledParams {
3681
+ /** The recorded answers: one per question for `answered`, any confirmed partial answers for `interrupted`, and empty for every other outcome. */
3448
3682
  answers: UserInputAnswer[];
3683
+ /** The user's free-form clarification when the outcome is `clarified`; `null` otherwise. */
3449
3684
  clarification: UserInputClarification | null;
3450
3685
  /** 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. */
3451
3686
  decidedAt: string | null;
3687
+ /** The `commandId` of the client command that settled the prompt; `null` when no command did, for example after a timeout or an abort. */
3452
3688
  decidedByCommandId: string | null;
3689
+ /** How the prompt ended. */
3453
3690
  outcome: UserInputOutcome;
3691
+ /** The reason, when one applies: the optional reason given with a cancel, or why an `aborted` prompt was closed; `null` otherwise. */
3454
3692
  reason: string | null;
3693
+ /** The session that owns the prompt. */
3455
3694
  sessionId: string;
3695
+ /** The stored records this event was folded from: an opaque token clients must not interpret. */
3456
3696
  sourceRange: SourceRange;
3697
+ /** The prompt that settled. Accept a settlement even for a prompt whose request you never saw. */
3457
3698
  userInputId: string;
3699
+ /** This event's view cursor: opaque, and strictly increasing within the session. */
3458
3700
  viewCursor: string;
3459
3701
  }
3460
3702
 
3461
3703
  /** Winning terminal returned to a late user-input command. */
3462
3704
  export interface UserInputSettlementSummary {
3705
+ /** How the prompt settled, as a `userInput/settled` outcome value such as `answered` or `timedOut`. */
3463
3706
  outcome: string;
3707
+ /** The view cursor of the `userInput/settled` event that recorded the settlement. */
3464
3708
  viewCursor: string;
3465
3709
  }
3466
3710
 
@@ -3477,10 +3721,10 @@ export interface ViewGapParams {
3477
3721
  sessionId: string;
3478
3722
  }
3479
3723
 
3480
- /** The `view/page` request-mode anchor (tdd SS4.7.3). Declared **open**: the tdd spells it "open string enum, v1 value `latestCompaction`". */
3724
+ /** The `view/page` request-mode anchor. Declared **open**: the protocol spells it "open string enum, v1 value `latestCompaction`". */
3481
3725
  export type ViewPageAnchor = "latestCompaction" | (string & {});
3482
3726
 
3483
- /** The `view/page` paging direction (tdd SS4.7.3). Closed: the tdd spells exactly two values and a third would change the paging contract. */
3727
+ /** The `view/page` paging direction. Closed: the protocol spells exactly two values and a third would change the paging contract. */
3484
3728
  export type ViewPageDirection = "forward" | "backward";
3485
3729
 
3486
3730
  /** `view/page` params (tdd SS4.7.3): cursor-paged reads of the session view. */
@@ -3491,7 +3735,7 @@ export interface ViewPageParams {
3491
3735
  cursor?: string;
3492
3736
  /** Paging direction; `forward` when omitted. */
3493
3737
  direction?: ViewPageDirection;
3494
- /** Maximum events to return, 1–1000. The server MAY return fewer (tdd SS4.7.3's short-serve rule). The 1–1000 range is ratified and now **published**: #22785 E6c is owner-ruled, so the model carries the bound and the bundle renders `minimum`/`maximum` instead of a bare `integer`. Range 1–1000 inclusive. */
3738
+ /** Maximum events to return, 1–1000. The server MAY return fewer. The 1–1000 range is ratified and **published**: the model carries the bound and the bundle renders `minimum`/`maximum` instead of a bare `integer`. Range 1–1000 inclusive. */
3495
3739
  limit: number;
3496
3740
  /** The session to page. */
3497
3741
  sessionId: string;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@muse-code/sdk",
3
- "version": "1.4.11",
3
+ "version": "1.4.12",
4
4
  "description": "TypeScript SDK for the Muse Session Protocol (MSP): connect to a Muse Code session, drive turns, and fold the event stream. Zero runtime dependencies.",
5
5
  "license": "MIT",
6
6
  "homepage": "https://github.com/meta-models/muse-code-sdk",