@muse-code/sdk 1.4.11 → 1.4.13

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:7fddaf646dbc317e5fcac0785e135eb04df14fbb0db1863089dfd6da21730e5b";
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:7fddaf646dbc317e5fcac0785e135eb04df14fbb0db1863089dfd6da21730e5b";
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,122 @@
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
+ /** The data the call would send that the card must name; a card with any offers only one-shot choices. */
66
+ data?: ApprovalCuaDataFact[];
67
+ /** For a browser, the host of the window's current page. */
68
+ page?: ApprovalCuaPage;
69
+ /** Only the consequential steps, in call order. */
70
+ steps?: ApprovalCuaStep[];
71
+ /** 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. */
72
+ windowTitle?: string;
73
+ }
74
+
75
+ /** One piece of data the call would send. An open union on `kind` (`secret`, or `other` for a row the host can't word); a client shows `other` and any kind it doesn't know as a generic data row. */
76
+ export interface ApprovalCuaDataFact {
77
+ /** Open discriminator: `secret` or `other`. */
78
+ kind: string;
79
+ /** For `secret`, the parts of it the card may show, never the value. */
80
+ mask?: ApprovalCuaMask;
81
+ /** For `secret`, the scanner's open tag (`github_token`, `secret_named_value` and so on); a client words the tags it knows and shows any other as "a secret". */
82
+ secretKind?: string;
83
+ }
84
+
85
+ /** A secret's mask: a vendor token's prefix and last 4 characters (`ghp_…3f9a`), a named value's name and length (`password=… (12 chars)`), or the length alone; all absent names the kind only. */
86
+ export interface ApprovalCuaMask {
87
+ /** The secret's length in characters. */
88
+ chars?: number;
89
+ /** A vendor token's last 4 characters. */
90
+ last4?: string;
91
+ /** A vendor token's fixed prefix (`ghp_`), or a named value's name and its `=` (`password=`). */
92
+ prefix?: string;
93
+ }
94
+
95
+ /** The page's full host, no path or query. */
96
+ export interface ApprovalCuaPage {
97
+ /** The host in Unicode. */
98
+ host: string;
99
+ /** The host's `xn--` form; equal to `host` when they don't differ. */
100
+ hostAscii: string;
101
+ }
102
+
103
+ /** A point in the model's 0–1000 coordinates. */
104
+ export interface ApprovalCuaPoint {
105
+ x: number;
106
+ y: number;
107
+ }
108
+
109
+ /** 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". */
110
+ export interface ApprovalCuaStep {
111
+ /** The host's verb phrase, such as `click` or `type into`. */
112
+ action: string;
113
+ /** The chord, for a key step. */
114
+ chord?: string;
115
+ /** The host's trusted sentence for what the step may do. */
116
+ effect: string;
117
+ /** 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. */
118
+ kind: string;
119
+ /** The control's label: the app's own text, shown quoted and as plain text; a client may cap it. */
120
+ label?: string;
121
+ /** The step's own 0–1000 model coordinates, only for a point step. */
122
+ point?: ApprovalCuaPoint;
123
+ /** `button`, `link`, `menu item` or `key`; absent for a point step. */
124
+ roleWord?: string;
125
+ /** 1-based, as the batch numbers its steps. */
126
+ step: number;
127
+ }
128
+
42
129
  /** `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
130
  export interface ApprovalDecideParams {
44
131
  /** The approval being decided. */
@@ -67,6 +154,7 @@ export interface ApprovalDecideResult {
67
154
  terminal: boolean;
68
155
  }
69
156
 
157
+ /** 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
158
  export type ApprovalDecision = "approved" | "approvedForSession" | "approvedPolicyAmendment" | "denied" | "deniedPolicyAmendment" | "timedOut" | "abort" | (string & {});
71
159
 
72
160
  /** `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 +165,9 @@ export interface ApprovalListPendingParams {
77
165
 
78
166
  /** `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
167
  export interface ApprovalListPendingResult {
80
- /** Exactly the `approval/request` params of tdd SS5.3, one per pending approval. */
168
+ /** Exactly the `approval/request` params, one per pending approval. */
81
169
  approvals: ApprovalRequestParams[];
82
- /** Exactly the `userInput/request` params of tdd SS5.10, one per pending prompt. */
170
+ /** Exactly the `userInput/request` params, one per pending prompt. */
83
171
  userInputs: UserInputRequestParams[];
84
172
  }
85
173
 
@@ -92,93 +180,152 @@ export type ApprovalModeApplyOutcome = "completed" | "noop" | (string & {});
92
180
  /** How an approval mode took effect (tdd SS5.12, the effective-mode projection's `source` vocabulary). Open. */
93
181
  export type ApprovalModeSource = "startup" | "replay" | "approvalReconfigure" | (string & {});
94
182
 
183
+ /** 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
184
  export interface ApprovalOrigin {
185
+ /** The shell command whose process asked for the action. Present when `kind` is `shellCommand`. */
96
186
  command?: string;
187
+ /** Which kind of origin this is: `shellCommand` or `url`. */
97
188
  kind: string;
189
+ /** The full URL a fetch tool is requesting. Present when `kind` is `url`. */
98
190
  url?: string;
99
191
  }
100
192
 
193
+ /** The result of saving a granted rule to the local policy store. The set is open, so newer hosts may send other values. */
101
194
  export type ApprovalPersistenceStatus = "succeeded" | "failed" | (string & {});
102
195
 
196
+ /** Whether an approval's final decision lets the action run. The set is open, so newer hosts may send other values. */
103
197
  export type ApprovalPolicyResult = "allow" | "deny" | (string & {});
104
198
 
105
199
  /** Full params shared by `approval/request` and `approval/requested`. */
106
200
  export interface ApprovalRequestParams {
201
+ /** 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
202
  approvalId: string;
203
+ /** The choices the server offers for the current requirement. Send the chosen one's `choiceId` in `approval/decide`; clients never build their own. */
108
204
  availableChoices: ApprovalChoice[];
205
+ /** 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. */
206
+ cuaCardFacts?: ApprovalCuaCardFacts;
207
+ /** 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
208
  currentRequirementId: ApprovalRequirementRef;
209
+ /** The `toolCall` view item waiting on this approval. */
110
210
  itemId: string;
211
+ /** `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
212
  judgeEscalated: boolean;
213
+ /** `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
214
  protectedWrite: boolean;
215
+ /** 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
216
  rawArgs: string;
217
+ /** The owning session. For a subagent's approval shown on the parent, this is the parent session. */
114
218
  sessionId: string;
219
+ /** The stored records this event was folded from: an opaque token clients must not interpret. */
115
220
  sourceRange: SourceRange;
116
221
  /** Present only for a child (native subagent) approval projected onto the parent session's plane (ADR 36182); parent-own approvals omit it. */
117
222
  subagentOrigin?: ApprovalSubagentOrigin;
223
+ /** What the approval is for. Show a `kind` you do not recognize generically, and never auto-approve it. */
118
224
  subject: ApprovalSubject;
225
+ /** The id of the task running the tool call. */
119
226
  taskId: string;
227
+ /** The model provider's id for this tool call. */
120
228
  toolCallId: string;
229
+ /** The name of the tool being called. */
121
230
  toolName: string;
231
+ /** The turn whose tool call is waiting on this approval. */
122
232
  turnId: string;
233
+ /** 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
234
  viewCursor: string;
124
235
  }
125
236
 
126
- /** Approval-stage token carried in SS5 params and stale-requirement errors. */
237
+ /** 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
238
  export interface ApprovalRequirementRef {
239
+ /** The approval this requirement belongs to. */
128
240
  approvalId: string;
241
+ /** The requirement's index within the approval, counting from 0; an approval with a single requirement uses 0. */
129
242
  sourceIndex: number;
130
243
  }
131
244
 
132
245
  /** Winning terminal returned to a losing `approval/decide` command. */
133
246
  export interface ApprovalResolutionSummary {
247
+ /** The winning decision, as an `approval/resolved` decision value such as `approved` or `abort`. */
134
248
  decision: string;
249
+ /** Who made the winning decision, such as `user`, `policy` or `llmJudge`. */
135
250
  resolvedBy: string;
251
+ /** The view cursor of the winning `approval/resolved` event. */
136
252
  viewCursor: string;
137
253
  }
138
254
 
255
+ /** Who or what made an approval's final decision. The set is open, so newer hosts may send other values. */
139
256
  export type ApprovalResolvedBy = "user" | "policy" | "llmJudge" | (string & {});
140
257
 
141
258
  /** `approval/resolved` params: the first durable terminal decision. */
142
259
  export interface ApprovalResolvedParams {
260
+ /** The policy rule the decision created. Present only when the decision created one. */
143
261
  amendment?: ApprovalAmendment;
262
+ /** The approval that was decided. */
144
263
  approvalId: string;
145
264
  /** 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
265
  decidedAt?: string;
266
+ /** 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
267
  decidedByCommandId?: string;
268
+ /** The final decision. */
148
269
  decision: ApprovalDecision;
270
+ /** The `toolCall` view item this approval was holding. */
149
271
  itemId: string;
272
+ /** Whether the final decision lets the action run (`allow`) or blocks it (`deny`). */
150
273
  policyResult: ApprovalPolicyResult;
274
+ /** Who or what made the decision: `user`, `policy` or `llmJudge`. */
151
275
  resolvedBy: ApprovalResolvedBy;
276
+ /** The owning session. */
152
277
  sessionId: string;
278
+ /** The stored records this event was folded from: an opaque token clients must not interpret. */
153
279
  sourceRange: SourceRange;
280
+ /** 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
281
  stageEvidence: ApprovalStageEvidence[];
155
282
  /** Present only for a child (native subagent) approval projected onto the parent session's plane (ADR 36182); parent-own approvals omit it. */
156
283
  subagentOrigin?: ApprovalSubagentOrigin;
284
+ /** The turn whose tool call this approval was holding. */
157
285
  turnId: string;
286
+ /** This event's view cursor: opaque, and strictly increasing within the session. */
158
287
  viewCursor: string;
159
288
  }
160
289
 
290
+ /** One stage of a `shell` approval: a single command from the pipeline or command list, approved separately from the others. */
161
291
  export interface ApprovalStage {
292
+ /** The stage's command words as parsed. When `argvComplete` is `false`, this can be a single unparsed piece of the command. */
162
293
  argv: string[];
294
+ /** `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
295
  argvComplete: boolean;
296
+ /** This stage's 1-based position in the command; it equals `requirementId.sourceIndex + 1`. */
164
297
  position: number;
298
+ /** This stage's requirement id. When it equals the approval's `currentRequirementId`, send it as `requirementId` in `approval/decide`. */
165
299
  requirementId: ApprovalRequirementRef;
300
+ /** Whether this stage still needs a decision or, if not, how it was satisfied. */
166
301
  resolution: ApprovalStageResolution;
302
+ /** 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
303
  suggestedPrefix?: ApprovalSuggestedPrefix;
304
+ /** The total number of stages in the command. */
168
305
  totalStages: number;
169
306
  }
170
307
 
308
+ /** How one stage of a `shell` approval was resolved when the decision became final. */
171
309
  export interface ApprovalStageEvidence {
310
+ /** The stage's command words as parsed. */
172
311
  argv: string[];
312
+ /** The stage's 1-based position in the command. */
173
313
  position: number;
314
+ /** The stage's requirement id. */
174
315
  requirementId: ApprovalRequirementRef;
316
+ /** How the stage was resolved at the final decision. */
175
317
  resolution: ApprovalStageResolution;
318
+ /** The total number of stages in the command. */
176
319
  totalStages: number;
177
320
  }
178
321
 
322
+ /** Whether a shell stage still needs a decision, or how it was satisfied. Satisfied stages are included so a client can show progress. */
179
323
  export interface ApprovalStageResolution {
324
+ /** The command prefix saved as an always-allow rule when this stage was approved. Present only when `kind` is `policyAmendment`. */
180
325
  argvPrefix?: string[];
326
+ /** Free-form text naming the rule or mode that allowed the stage, for display or troubleshooting. Present only when `kind` is `policyAllow`. */
181
327
  diagnostic?: string;
328
+ /** One of `unresolved`, `knownSafe`, `policyAllow`, `allowOnce` or `policyAmendment`. The set is open, so newer hosts may add values. */
182
329
  kind: string;
183
330
  }
184
331
 
@@ -194,37 +341,59 @@ export interface ApprovalSubagentOrigin {
194
341
 
195
342
  /** Open approval subject union. Unknown kinds are rendered generically and never auto-approved by clients (tdd SS5.2). */
196
343
  export interface ApprovalSubject {
344
+ /** The access asked for: `read` or `write` for `fileAccess`, `control` for `process`. Absent for other kinds. */
197
345
  access?: string;
346
+ /** The full raw shell command. Present when `kind` is `shell`. */
198
347
  command?: string;
348
+ /** The network host the tool wants to reach. Present when `kind` is `network`. */
199
349
  host?: string;
200
350
  /** Open discriminator: `shell | fileAccess | network | unixSocket | process | tool`. */
201
351
  kind: string;
352
+ /** 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
353
  origin?: ApprovalOrigin;
354
+ /** 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
355
  path?: string;
356
+ /** 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
357
  port?: number;
358
+ /** The network protocol, for example `https`. Present only on `network` subjects that name one. */
205
359
  protocol?: string;
360
+ /** 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
361
  stages?: ApprovalStage[];
362
+ /** Display text naming the process the tool wants to control. Present when `kind` is `process`. */
207
363
  target?: string;
364
+ /** The tool asking for the action. Present for every kind except `shell`. */
208
365
  toolName?: string;
366
+ /** 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
367
  workspaceRoot?: string;
210
368
  }
211
369
 
370
+ /** A suggested always-allow rule for a shell stage: commands starting with `argvPrefix` would run in this workspace without asking. */
212
371
  export interface ApprovalSuggestedPrefix {
372
+ /** The leading command words the rule would allow, for example `["cargo", "test"]`. */
213
373
  argvPrefix: string[];
374
+ /** A human-readable label for the suggestion, ready to show as is. */
214
375
  label: string;
215
376
  }
216
377
 
217
378
  /** `approval/updated` params: the refreshed pending view plus one change. */
218
379
  export interface ApprovalUpdatedParams {
380
+ /** The approval that changed. */
219
381
  approvalId: string;
382
+ /** The refreshed choices for the current requirement. */
220
383
  availableChoices: ApprovalChoice[];
384
+ /** What changed; `change.kind` names the kind of change. */
221
385
  change: ApprovalChange;
386
+ /** The requirement the next decision must target after this change; send it as `requirementId` in `approval/decide`. */
222
387
  currentRequirementId: ApprovalRequirementRef;
388
+ /** The owning session. */
223
389
  sessionId: string;
390
+ /** The stored records this event was folded from: an opaque token clients must not interpret. */
224
391
  sourceRange: SourceRange;
225
392
  /** Present only for a child (native subagent) approval projected onto the parent session's plane (ADR 36182); parent-own approvals omit it. */
226
393
  subagentOrigin?: ApprovalSubagentOrigin;
394
+ /** The approval's subject, with `stages` refreshed for this change. */
227
395
  subject: ApprovalSubject;
396
+ /** This event's view cursor: opaque, and strictly increasing within the session. */
228
397
  viewCursor: string;
229
398
  }
230
399
 
@@ -234,6 +403,26 @@ export type AttentionFlag = "approvalPending" | "inputPending" | (string & {});
234
403
  /** Who durably backgrounded a task (tdd SS4.5.5, `TaskBackgroundedInitiator`). Open — runtime vocabulary. */
235
404
  export type BackgroundInitiator = "user" | "timeout" | (string & {});
236
405
 
406
+ /** `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). */
407
+ export interface BackgroundTerminalCompletion {
408
+ /** The title text gate-off shows for the backgrounded command. */
409
+ command: string;
410
+ /** The completion text; empty when the terminal carries none. */
411
+ output: string;
412
+ /** True when `output` is a prefix of the terminal text. */
413
+ outputTruncated: boolean;
414
+ /** One of `completed`, `failed`, `cancelled`, `timedOut`, `rejected` (the ItemStatus wire vocabulary, tdd SS4.4.1). */
415
+ terminalStatus: string;
416
+ /** The backgrounded call's call id: the live/history correlation key behind the skip-when-minted rule (ADR 50041 D6). */
417
+ toolCallId: string;
418
+ }
419
+
420
+ /** 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. */
421
+ export interface BlockedPrompt {
422
+ /** The exact submitted prompt, verbatim — no truncation, no normalization; recall fidelity requires exactness. */
423
+ text: string;
424
+ }
425
+
237
426
  /** The latest branch observation in the snapshot (tdd SS4.6.4, SS4.9.1). */
238
427
  export interface BranchState {
239
428
  /** The observed branch; `null` on a detached-HEAD observation. */
@@ -244,9 +433,15 @@ export interface BranchState {
244
433
  workspaceRoot: string;
245
434
  }
246
435
 
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. */
436
+ /** 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
437
  export type CapabilityName = "userShell" | "sessionMcp" | "sessionListStream" | "feedback" | "computerUseSetup" | "computerUseHostSetup" | "sessionRename" | (string & {});
249
438
 
439
+ /** 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. */
440
+ export interface CheckpointBoundary {
441
+ /** The last pre-boundary item's id, in served (first-opened) order. */
442
+ throughItemId: string;
443
+ }
444
+
250
445
  /** The client's requested capability posture (SS1.4.1). Every member defaults; an absent `capabilities` object means all defaults. */
251
446
  export interface ClientCapabilities {
252
447
  /** Opt into experimental methods, fields, and variants (default `false`). */
@@ -305,7 +500,7 @@ export interface CommandAcceptedResult {
305
500
  status: CommandAckStatus;
306
501
  }
307
502
 
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. */
503
+ /** 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
504
  export type CommandAckStatus = "accepted" | "noop";
310
505
 
311
506
  /** 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 +659,9 @@ export interface ContextUsage {
464
659
  windowTokens?: number;
465
660
  }
466
661
 
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. */
662
+ /** 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
663
  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. */
664
+ /** 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
665
  jobId?: string;
471
666
  /** Cron `list`: the served jobs in server order, `active` and `firing` rows only. */
472
667
  jobs?: CronReceiptJob[];
@@ -474,7 +669,7 @@ export interface CronReceipt {
474
669
  nextFireAtMs?: number;
475
670
  }
476
671
 
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. */
672
+ /** 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
673
  export interface CronReceiptJob {
479
674
  /** The job's server-owned id. */
480
675
  jobId: string;
@@ -490,7 +685,7 @@ export interface CumulativeCost {
490
685
  usd: number;
491
686
  }
492
687
 
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. */
688
+ /** 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
689
  export interface CumulativeTokenUsage {
495
690
  /** 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
691
  cacheReadTokens?: number;
@@ -546,11 +741,11 @@ export interface ErrorData {
546
741
  alignedNextOffset?: number;
547
742
  /** 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
743
  anchor?: string | null;
549
- /** Approval identity on SS5 errors. */
744
+ /** Approval id on approval errors. */
550
745
  approvalId?: string;
551
746
  /** 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
747
  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). */
748
+ /** 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
749
  capability?: CapabilityName;
555
750
  /** The configured command-admission bound, on `backpressured` errors. */
556
751
  capacity?: number;
@@ -560,7 +755,7 @@ export interface ErrorData {
560
755
  commandId?: string;
561
756
  /** Current stage token on `approvalRequirementStale`. */
562
757
  currentRequirementId?: ApprovalRequirementRef;
563
- /** SS1.5.1 descriptor, on `experimentalRequired` errors. */
758
+ /** On `experimentalRequired` errors, the name of the experimental method, field or variant the request used, for example `turn/start.providerRequestOptions`. */
564
759
  descriptor?: string;
565
760
  /** Free-form additive detail. */
566
761
  details?: Record<string, unknown>;
@@ -604,13 +799,13 @@ export interface ErrorData {
604
799
  settlement?: UserInputSettlementSummary;
605
800
  /** The rejected upload id on `uploadNotFound` (`-32038`, SS3.33). */
606
801
  uploadId?: string;
607
- /** User-input prompt identity on SS5.10 errors. */
802
+ /** Prompt identity on user-input errors. */
608
803
  userInputId?: string;
609
804
  /** The blocked view position on `pageEventTooLarge` errors. */
610
805
  viewCursor?: string;
611
806
  }
612
807
 
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. */
808
+ /** 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
809
  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
810
 
616
811
  /** The `error` member of an error response (SS1.2 §2.4). */
@@ -699,7 +894,7 @@ export interface ForkProvenance {
699
894
 
700
895
  /** 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
896
  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. */
897
+ /** 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
898
  createdAtMs?: number;
704
899
  /** Current work description, when present. */
705
900
  currentWork?: string;
@@ -711,7 +906,7 @@ export interface Goal {
711
906
  percentComplete: number;
712
907
  /** Goal status, verbatim from the durable goal state (free string by design: out-of-contract values pass through). */
713
908
  status: string;
714
- /** ADR 50064 D2 (pick-4): last goal mutation time, epoch milliseconds, verbatim from the durable row. Same absence rule as `createdAtMs`. */
909
+ /** Last goal mutation time, epoch milliseconds, verbatim from the durable row. Same absence rule as `createdAtMs`. */
715
910
  updatedAtMs?: number;
716
911
  }
717
912
 
@@ -772,7 +967,7 @@ export interface GoalSetParams {
772
967
  /** 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
968
  export type HistoryMode = "anchoredSnapshot" | "inline" | "snapshot" | "none" | (string & {});
774
969
 
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). */
970
+ /** 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
971
  export type HistoryNoneReason = "excluded" | "cursorSuffix" | "historyBudget" | "projectionUnavailable" | "projectionReadLimit" | (string & {});
777
972
 
778
973
  /** 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 +986,7 @@ export interface HookCatalogEntry {
791
986
  }
792
987
 
793
988
  /** 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 & {});
989
+ 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
990
 
796
991
  /** 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
992
  export type HookHandlerKind = "managed" | "user" | "project" | "plugin" | (string & {});
@@ -834,7 +1029,7 @@ export interface InitializeResult {
834
1029
  platformFamily: PlatformFamily;
835
1030
  /** Server operating system. */
836
1031
  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. */
1032
+ /** 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
1033
  sandboxAvailability?: SandboxAvailability;
839
1034
  /** Why enforcement is impossible. Sent only when `sandbox_availability` is `unavailable`; a client MUST NOT infer a reason when none is sent. */
840
1035
  sandboxUnavailableReason?: SandboxUnavailableReason;
@@ -842,7 +1037,7 @@ export interface InitializeResult {
842
1037
  schema: SchemaInfo;
843
1038
  /** Server identification. */
844
1039
  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. */
1040
+ /** 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
1041
  sessionDurability?: SessionDurability;
847
1042
  /** Exact user-agent string presented to upstream model providers. */
848
1043
  userAgent: string;
@@ -862,6 +1057,8 @@ export interface Item {
862
1057
  background?: boolean;
863
1058
  /** `toolCall`: who backgrounded the task; absent on pre-split records — never inferred (tdd SS4.5.5). */
864
1059
  backgroundInitiator?: BackgroundInitiator;
1060
+ /** `backgroundTerminalCompletion`: the five facts the Finished cell renders (ADR 50041 D4). */
1061
+ backgroundTerminalCompletion?: BackgroundTerminalCompletion;
865
1062
  /** `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
1063
  blocking?: boolean;
867
1064
  /** `toolCall`: the provider call id (`call_...`), opaque. */
@@ -894,7 +1091,7 @@ export interface Item {
894
1091
  displayLabel?: ToolDisplayLabel;
895
1092
  /** `userMessage`: presentation form (tdd SS3.2); absent when the client sent none. */
896
1093
  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. */
1094
+ /** `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
1095
  durationMs?: number;
899
1096
  /** `workflow`: launched entry identity. */
900
1097
  entryId?: string;
@@ -956,6 +1153,8 @@ export interface Item {
956
1153
  recordedAt?: string;
957
1154
  /** `reminderChild`: the reminder agent's id. */
958
1155
  reminderAgentId?: string;
1156
+ /** Monitor `toolCall`: the D26 hint verdict plus anchor (`ReplayHint`); absent means no hint. */
1157
+ replayHint?: ReplayHint;
959
1158
  /** `subagent`: the result envelope from `ResultReady` (tdd SS4.5.7). */
960
1159
  result?: SubagentResult;
961
1160
  /** `workflow`: set on resumed launches. */
@@ -998,12 +1197,14 @@ export interface Item {
998
1197
  strategyId?: string;
999
1198
  /** `subagent`: durable child identity (`subagent_id`). */
1000
1199
  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). */
1200
+ /** `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
1201
  summarizedThrough?: string;
1003
1202
  /** `reasoning`: one entry per summary part; part *n* streams via `item/delta` field `"summary.n"` (part boundary = index change). */
1004
1203
  summary?: string[];
1005
1204
  /** `reminderChild`: the linked task id. */
1006
1205
  taskId?: string;
1206
+ /** Terminal `toolCall`: the item after whose rows the terminal row renders (tdd SS4.5.21, ADR 56496 D2/D3). */
1207
+ terminalRowAfterItemId?: string;
1007
1208
  /** `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). */
1008
1209
  text?: string;
1009
1210
  /** `workflow`: the run's launch token budget, set from the launch fact (tdd SS4.5.8, #45449); absent when the launch carried none. */
@@ -1028,6 +1229,8 @@ export interface Item {
1028
1229
  usage?: TokenUsage;
1029
1230
  /** `toolCall`/`userShell`: bounded transcript-visible result text (budget per tdd SS4.5.4); streams via `item/delta` field `"output"`. */
1030
1231
  visibleOutput?: string;
1232
+ /** `toolCall`: the task's registered Work ID, verbatim (`work.v2.managed_bash.sha256.…`); present only when the task registered a ManagedBash id, absent otherwise (tdd SS4.5.5, ADR 50041 D20). Stable from day one: no `x-msp-stability` marker. The host serves it at the later of the task terminal and the inbox admission (D21); absence keeps the client's v1 derivation. */
1233
+ workId?: string;
1031
1234
  /** `subagent`/`workflow`: the owning durable workflow run id (opaque string — not a UUID family). */
1032
1235
  workflowRunId?: string;
1033
1236
  }
@@ -1059,12 +1262,12 @@ export interface ItemDeltaParams {
1059
1262
  }
1060
1263
 
1061
1264
  /** 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 & {});
1265
+ export type ItemKind = "userMessage" | "agentMessage" | "reasoning" | "toolCall" | "userShell" | "subagent" | "workflow" | "reminderChild" | "compaction" | "hookRun" | "sideChat" | "webSearch" | "monitorFeed" | "damagedRange" | "scheduledFire" | "backgroundTerminalCompletion" | "overdueNotice" | (string & {});
1063
1266
 
1064
1267
  /** 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
1268
  export type ItemReadOutputEncoding = "utf8" | "base64";
1066
1269
 
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. */
1270
+ /** `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
1271
  export interface ItemReadOutputParams {
1069
1272
  /** The item whose stored output is fetched. */
1070
1273
  itemId: string;
@@ -1147,7 +1350,7 @@ export interface MediaUploadParams {
1147
1350
  chunkCount: number;
1148
1351
  /** This chunk's 0-based position. */
1149
1352
  chunkIndex: number;
1150
- /** One per call; SS3.1.1 replay answers the recorded receipt. */
1353
+ /** 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
1354
  commandId: string;
1152
1355
  /** `video/mp4` or `video/quicktime`, matching `VideoInput`. */
1153
1356
  mediaType: string;
@@ -1409,7 +1612,7 @@ export interface PendingApprovalPointer {
1409
1612
  /** The `pendingRequests` discriminator (tdd SS2.5.2). Open enum, v1 values `approval` and `userInput`. */
1410
1613
  export type PendingRequestKind = "approval" | "userInput" | (string & {});
1411
1614
 
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. */
1615
+ /** 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
1616
  export interface PendingRequestPointer {
1414
1617
  /** Present on an `approval` entry. */
1415
1618
  approvalId?: string;
@@ -1431,7 +1634,7 @@ export interface PendingUserInputPointer {
1431
1634
  viewCursor: string;
1432
1635
  }
1433
1636
 
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). */
1637
+ /** 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
1638
  export type PlatformFamily = "unix" | "windows";
1436
1639
 
1437
1640
  /** The server's operating system (SS1.4.1). Closed, for the same reason as [`PlatformFamily`]. */
@@ -1624,6 +1827,18 @@ export interface PluginMarketplaceUpdateParams {
1624
1827
  /** 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. */
1625
1828
  export type PluginSource = "curated" | "marketplaceUserAdded" | "foreignImport" | "nativeLocal" | (string & {});
1626
1829
 
1830
+ /** One input still queued for delivery to a session (tdd SS2.5.5, ADR 63254-queued-inputs-on-read D2): the full message body plus its log record sequence, the delivery-order and re-read dedupe key, plus the run-log record id clients join served entries against record-seeded rows by. */
1831
+ export interface QueuedInput {
1832
+ /** The queued record's log sequence: delivery order, and the key clients deduplicate re-reads by. */
1833
+ sequence: number;
1834
+ /** The `SubagentInput` record's model-authored command id: the key wire-twin rows join by in either order (the twin reads the same string from the verbatim wire args). Absent for root own-queue members, which are never `SubagentInput`. */
1835
+ sourceCommandId?: string;
1836
+ /** The run-log record id the served mirror was taken from: the key clients join served entries against record-seeded rows by, so an already-rendered input never mints a second row under diverged sequences. Absent when the host's record carries no mirror metadata (a pre-feature host), which falls back to sequence-key dedup only. */
1837
+ sourceRunRecordId?: string;
1838
+ /** The full message body, verbatim (never truncated, never a summary). */
1839
+ text: string;
1840
+ }
1841
+
1627
1842
  /** Typed quota-exhaustion detail (tdd SS4.5.1, ADR 50047 D2): the limit kind plus the provider's reset instant. */
1628
1843
  export interface QuotaDetail {
1629
1844
  /** Which quota was exhausted (open enum; unknown values fall back). */
@@ -1681,7 +1896,7 @@ export interface RecapCompletedParams {
1681
1896
  /** `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
1897
  export type RecapFailureReason = "providerFailed" | (string & {});
1683
1898
 
1684
- /** `recap/completed` outcome (tdd SS3.28.2): the terminal vocabulary, camelCase per SS1.6. **Open**: a server-produced result vocabulary (#22785 E2). */
1899
+ /** `recap/completed` outcome: the terminal vocabulary, in camelCase. **Open**: a server-produced result vocabulary. */
1685
1900
  export type RecapOutcome = "completed" | "failed" | "cancelled" | "timedOut" | (string & {});
1686
1901
 
1687
1902
  /** `recap/request` params (tdd SS3.28.1): the session plus the client-minted UUIDv7 retry id. No other param; unknown fields are `invalidParams`. */
@@ -1730,6 +1945,12 @@ export type RecoveryObservedMode = "on" | "off" | "unknown" | (string & {});
1730
1945
  /** This construction's assessment, never an operation acceptance receipt. */
1731
1946
  export type RecoveryQualification = "qualified" | "unavailable" | "notRequired" | "unknown" | (string & {});
1732
1947
 
1948
+ /** The D26 first-tree-transition hint verdict plus anchor (tdd SS4.5.21, ADR 56496 D3): `rowKinds` is the open lowercase row-kind vocabulary the client formats through its shared kind-noun constructor; `afterItemId` is the item id after whose rows the hint renders. Both members always ride when the object does. */
1949
+ export interface ReplayHint {
1950
+ afterItemId: string;
1951
+ rowKinds: string[];
1952
+ }
1953
+
1733
1954
  /** A request frame, either direction (SS1.2 §2.1). */
1734
1955
  export interface Request {
1735
1956
  /** Client-chosen id, unique among that client's in-flight requests. */
@@ -1778,7 +1999,7 @@ export interface ServerInfo {
1778
1999
 
1779
2000
  /** The session object every lifecycle method returns or lists (tdd SS2.4). Additive-optional evolution applies: clients must ignore unknown fields. */
1780
2001
  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`. */
2002
+ /** 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
2003
  activeTurnId: string | null;
1783
2004
  /** 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
2005
  approvalMode?: EffectiveApprovalModeState;
@@ -1895,7 +2116,7 @@ export interface SessionCompactResult {
1895
2116
  status: CompactStatus;
1896
2117
  }
1897
2118
 
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. */
2119
+ /** 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
2120
  export interface SessionConfig {
1900
2121
  /** Native MCP servers added only to this session runtime. */
1901
2122
  mcpServers?: Record<string, SessionMcpServerConfig>;
@@ -1958,6 +2179,8 @@ export interface SessionGoalChangedParams {
1958
2179
 
1959
2180
  /** The `history` envelope shared by `session/resume`, `session/fork`, and `session/read` (tdd SS2.5.2). */
1960
2181
  export interface SessionHistory {
2182
+ /** 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). */
2183
+ checkpointBoundary?: CheckpointBoundary;
1961
2184
  /** The full folded item array when `mode` is `inline`; `null` otherwise. */
1962
2185
  items: Item[] | null;
1963
2186
  /** What was actually served — never what was asked for (tdd SS2.5.2). */
@@ -1973,10 +2196,15 @@ export type SessionKind = "root" | "subagent" | (string & {});
1973
2196
 
1974
2197
  /** Params of the protected, non-view leave terminal notification. */
1975
2198
  export interface SessionLeaveCompletedParams {
2199
+ /** The leave command's id, matching the `session/leave` request. */
1976
2200
  commandId: string;
2201
+ /** How the leave ended: `released` or `failed`. The set is open, so newer hosts may add outcomes. */
1977
2202
  outcome: SessionLeaveOutcome;
2203
+ /** Why the leave failed. Present when `outcome` is `failed`. */
1978
2204
  reason?: SessionLeaveFailureReason;
2205
+ /** The session the leave was for. */
1979
2206
  sessionId: string;
2207
+ /** The session's view cursor at release: everything up to it was folded before the host let go. Present when `outcome` is `released`. */
1980
2208
  viewCursor?: string;
1981
2209
  }
1982
2210
 
@@ -1998,7 +2226,9 @@ export interface SessionLeaveParams {
1998
2226
 
1999
2227
  /** The admission-only `session/leave` result. */
2000
2228
  export interface SessionLeaveResult {
2229
+ /** The leave command's id. */
2001
2230
  commandId: string;
2231
+ /** 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
2232
  status: CommandAckStatus;
2003
2233
  }
2004
2234
 
@@ -2030,7 +2260,7 @@ export interface SessionListParams {
2030
2260
  cursor?: string | null;
2031
2261
  /** 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
2262
  filter?: SessionListFilter;
2033
- /** Page size; default 50, max 200 — the cap is published under #22785 E6c (owner-ruled 2026-08-26). Maximum 200. */
2263
+ /** Page size; default 50, max 200 — the schema publishes the cap. Maximum 200. */
2034
2264
  limit?: number;
2035
2265
  /** Only sessions with log activity after this RFC3339 instant. */
2036
2266
  updatedAfter?: string;
@@ -2139,12 +2369,16 @@ export interface SessionReadParams {
2139
2369
 
2140
2370
  /** `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
2371
  export interface SessionReadResult {
2372
+ /** Same member as `session/resume` (tdd SS2.5.5, ADR 50074 D2). */
2373
+ blockedPrompt?: BlockedPrompt;
2142
2374
  /** The served history. */
2143
2375
  history: SessionHistory;
2144
2376
  /** Same member as `session/resume` (tdd SS2.5.5, ADR 36635 D2). */
2145
2377
  lastTurn?: LastTurn;
2146
2378
  /** 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). */
2147
2379
  pendingRequests: PendingRequestPointer[];
2380
+ /** The inputs still queued for delivery to the read session (tdd SS2.5.5, ADR 63254-queued-inputs-on-read D2). Absent-when-empty: a missing member means nothing queued, never an error. */
2381
+ queuedInputs?: QueuedInput[];
2148
2382
  /** Current local construction only; never inferred from retained history. Absence establishes neither a choice nor supported recovery. */
2149
2383
  recoveryObservation?: RecoveryObservation;
2150
2384
  /** The session as folded point-in-time. */
@@ -2155,7 +2389,7 @@ export interface SessionReadResult {
2155
2389
 
2156
2390
  /** `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
2391
  export interface SessionReasoningEffortChangedParams {
2158
- /** The new session default: the closed eight-string tier vocabulary of tdd SS3.2, spelled identically. */
2392
+ /** The new session default: the same closed eight-string tier vocabulary as `turn/start`. */
2159
2393
  reasoningEffort: ReasoningEffort;
2160
2394
  /** The owning session. */
2161
2395
  sessionId: string;
@@ -2193,13 +2427,13 @@ export interface SessionResumeParams {
2193
2427
  commandId: string;
2194
2428
  /** The same open construction-time extension object as `session/start`. */
2195
2429
  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). */
2430
+ /** 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
2431
  cursor?: string | null;
2198
2432
  /** Return only session metadata and live resume state; page history separately with `view/page`. Default `false` (tdd SS2.5.2). */
2199
2433
  excludeItems?: boolean;
2200
2434
  /** History mode preference, default `auto`. A PREFERENCE, not a budget override: when the requested mode does not fit the history budget the server downgrades it and `history.mode` reports what was actually served (tdd SS2.5.2). Ignored when `cursor` or `excludeItems` makes it moot. */
2201
2435
  history?: HistoryPreference;
2202
- /** The launch permission-profile pick (amendment 42624 FR-42624-1, #50054): a profile id the host catalog already admits. Select, never create. Omitted means today's behavior: restore retained authority only, no override. The host restores first, then applies the pick in the same pre-marker step; a pick that fails admission refuses the resume `commandRejected` (-32030; `permission_profile_unknown` / `permission_profile_unavailable`) before any durable byte. Explicit `null` is invalid params (the same closed null-tolerant set as at start). */
2436
+ /** The launch permission-profile pick (amendment 42624 FR-42624-1, #50054): a profile id the host catalog already admits. Select, never create. Omitted restores retained authority only, with no override. The host restores first, then applies the pick in the same pre-marker step; over a declared lost record the restore is the never-wider reset, committed before the pick, and where the reset cannot commit the pick is committed alone as that reset (spec 11237 FR-57059-4). A pick that fails admission refuses the resume `commandRejected` (-32030; `permission_profile_unknown` / `permission_profile_unavailable`) before any durable byte. Explicit `null` is invalid params (the same closed null-tolerant set as at start). */
2203
2437
  permissionProfile?: string;
2204
2438
  /** Cold-resume replacement choice; omission preserves the retained choice. A warm attach rejects a different or unestablished choice as invalidParams. Explicit null is invalid. */
2205
2439
  recoveryMode?: RecoveryMode;
@@ -2209,6 +2443,8 @@ export interface SessionResumeParams {
2209
2443
 
2210
2444
  /** `session/resume` result (tdd SS2.5.2). */
2211
2445
  export interface SessionResumeResult {
2446
+ /** 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. */
2447
+ blockedPrompt?: BlockedPrompt;
2212
2448
  /** The served history. */
2213
2449
  history: SessionHistory;
2214
2450
  /** How the last folded turn ended (tdd SS2.5.2, ADR 36635 D2). **Additive-optional**; absence is a non-assertion. */
@@ -2305,7 +2541,7 @@ export interface SessionStartParams {
2305
2541
  approvalMode?: ApprovalMode | null;
2306
2542
  /** The SS2.5 idempotency handle (UUIDv7). Required; the server never mints one. */
2307
2543
  commandId: string;
2308
- /** Reserved for per-session overrides owned by a future Configuration section. Issue #32760 admits only its `mcpServers` member. */
2544
+ /** Reserved for future per-session overrides; only its `mcpServers` member is admitted. */
2309
2545
  config?: SessionConfig;
2310
2546
  /** Initial model; server default when omitted. */
2311
2547
  modelId?: string;
@@ -2588,7 +2824,7 @@ export interface SnapshotAnchor {
2588
2824
  summarizedThrough: string;
2589
2825
  }
2590
2826
 
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. */
2827
+ /** 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
2828
  export interface SnapshotState {
2593
2829
  /** The running foreground turn; `null` when none is running. */
2594
2830
  activeTurn: TurnRef | null;
@@ -2596,7 +2832,7 @@ export interface SnapshotState {
2596
2832
  approvalMode: EffectiveApprovalModeState;
2597
2833
  /** Latest branch observation; `null` when no fact has landed. */
2598
2834
  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. */
2835
+ /** 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
2836
  contextUsage?: ContextUsage;
2601
2837
  /** Latest effective model; `null` when no fact has landed. */
2602
2838
  effectiveModel: EffectiveModel | null;
@@ -2820,10 +3056,17 @@ export interface TaskCommandResult {
2820
3056
  taskId: string;
2821
3057
  }
2822
3058
 
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. */
3059
+ /** 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. */
3060
+ export type TaskExecutionMode = "foreground" | "background" | (string & {});
3061
+
3062
+ /** 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
3063
  export interface TaskListEntry {
2825
3064
  /** Who backgrounded the task, mirroring the item field. **Additive-optional**: absent on pre-split records and registry-only rows, never inferred. */
2826
3065
  backgroundInitiator?: BackgroundInitiator;
3066
+ /** 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). */
3067
+ command?: string;
3068
+ /** `"foreground" | "background"` (ADR 62268 D2). **Additive-optional**: absent means `"background"` (only pre-change hosts omit it, and those list background rows only); never guessed. */
3069
+ executionMode?: TaskExecutionMode;
2827
3070
  /** 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
3071
  kind: string;
2829
3072
  /** The host-known task start, RFC3339. **Additive-optional**: omitted, never guessed, when the host does not know it. */
@@ -2842,9 +3085,9 @@ export interface TaskListParams {
2842
3085
  sessionId: string;
2843
3086
  }
2844
3087
 
2845
- /** `task/list` result (tdd SS3.31): one row per running background workload in `task/stopAll` reach, oldest first; empty when nothing is running. */
3088
+ /** `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
3089
  export interface TaskListResult {
2847
- /** The session's live background-task rows. */
3090
+ /** The session's live task rows. */
2848
3091
  tasks: TaskListEntry[];
2849
3092
  }
2850
3093
 
@@ -3015,7 +3258,7 @@ export interface TurnForegroundCompletedParams {
3015
3258
  viewCursor: string;
3016
3259
  }
3017
3260
 
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`. */
3261
+ /** 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
3262
  export interface TurnInputPart {
3020
3263
  /** 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
3264
  arguments?: string;
@@ -3027,7 +3270,7 @@ export interface TurnInputPart {
3027
3270
  mediaType?: string;
3028
3271
  /** 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
3272
  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. */
3273
+ /** 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
3274
  source?: SkillInvocationSource;
3032
3275
  /** User prompt text, on a `text` part. Multiple text parts are joined in order into the turn's prompt. */
3033
3276
  text?: string;
@@ -3035,7 +3278,7 @@ export interface TurnInputPart {
3035
3278
  type: TurnInputPartType;
3036
3279
  /** The upload receipt, required on a `video` part (tdd SS3.2, SS3.33; ADR 45443 D5): the client-minted id `media/upload` echoed. */
3037
3280
  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. */
3281
+ /** Pixel width; must be provided together with `height` or not at all. Published as a `dependentRequired` pair. */
3039
3282
  width?: number;
3040
3283
  }
3041
3284
 
@@ -3098,7 +3341,7 @@ export interface TurnRef {
3098
3341
  displayText?: string;
3099
3342
  /** `queuedTurns[]` only: set when `displayText` was cut to the committed-surface budget, mirroring `userMessage.truncated` (tdd SS4.5.2). Absent unless `true`. */
3100
3343
  truncated?: boolean;
3101
- /** The turn's id, pre-minted per tdd SS3.1.4. */
3344
+ /** The turn's id, minted at admission. */
3102
3345
  turnId: string;
3103
3346
  }
3104
3347
 
@@ -3264,7 +3507,7 @@ export interface TurnUserShell {
3264
3507
  commandText: string;
3265
3508
  }
3266
3509
 
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. */
3510
+ /** 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
3511
  export interface UnframedViewNotification {
3269
3512
  /** 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
3513
  method: string;
@@ -3272,7 +3515,7 @@ export interface UnframedViewNotification {
3272
3515
  params: UnframedViewNotificationParams;
3273
3516
  }
3274
3517
 
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. */
3518
+ /** 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
3519
  export interface UnframedViewNotificationParams {
3277
3520
  /** The owning session (tdd SS4.2). */
3278
3521
  sessionId: string;
@@ -3291,15 +3534,21 @@ export interface UsageReadResult {
3291
3534
  usage?: SubscriptionUsage;
3292
3535
  }
3293
3536
 
3537
+ /** One question's answer, as sent in `userInput/answer` or `userInput/interrupt` and as recorded in `userInput/settled`. */
3294
3538
  export interface UserInputAnswer {
3539
+ /** A free-form answer, at most 500 characters. */
3295
3540
  freeText?: string;
3541
+ /** An optional comment the user adds to the answer, at most 500 characters. */
3296
3542
  note?: string;
3543
+ /** The `id` of the question this answers. */
3297
3544
  questionId: string;
3545
+ /** The label of the chosen option, for a `single` question. */
3298
3546
  selectedLabel?: string;
3547
+ /** The labels of the chosen options for a `multiple` question, within its selection bounds; omitted when empty. */
3299
3548
  selectedLabels?: string[];
3300
3549
  }
3301
3550
 
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. */
3551
+ /** `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
3552
  export interface UserInputAnswerParams {
3304
3553
  /** One entry per question. */
3305
3554
  answers: UserInputAnswer[];
@@ -3343,8 +3592,11 @@ export interface UserInputCancelResult {
3343
3592
  userInputId: string;
3344
3593
  }
3345
3594
 
3595
+ /** A free-form reply the user gives instead of choosing from the options; the model reads it and decides again. */
3346
3596
  export interface UserInputClarification {
3597
+ /** The clarification text, at most 500 characters. */
3347
3598
  content: string;
3599
+ /** The content format. `text` is the only value today, and more may be added. */
3348
3600
  format: string;
3349
3601
  }
3350
3602
 
@@ -3400,67 +3652,107 @@ export interface UserInputInterruptResult {
3400
3652
  userInputId: string;
3401
3653
  }
3402
3654
 
3655
+ /** One option offered for a question. */
3403
3656
  export interface UserInputOption {
3657
+ /** An optional longer explanation of the option, at most 240 characters. */
3404
3658
  description?: string;
3659
+ /** The option's text, at most 80 characters and unique within its question; an answer selects the option by this exact label. */
3405
3660
  label: string;
3661
+ /** An optional rich preview of the option, present only on single-select questions. */
3406
3662
  preview?: UserInputOptionPreview;
3407
3663
  }
3408
3664
 
3665
+ /** Rich content a client can show for an option. Only single-select questions carry previews. */
3409
3666
  export interface UserInputOptionPreview {
3667
+ /** The preview content in that format, at most 2000 characters. */
3410
3668
  content: string;
3669
+ /** The content format, for example `markdown`. */
3411
3670
  format: string;
3412
3671
  }
3413
3672
 
3673
+ /** How a user-input prompt settled. More values may be added, so handle values you do not recognize. */
3414
3674
  export type UserInputOutcome = "answered" | "cancelled" | "interrupted" | "clarified" | "timedOut" | "aborted" | (string & {});
3415
3675
 
3676
+ /** One question in a user-input prompt. */
3416
3677
  export interface UserInputQuestion {
3678
+ /** A short title for the question, at most 12 characters. */
3417
3679
  header: string;
3680
+ /** The question's id, unique within the prompt and at most 64 characters. An answer names it in `questionId`. */
3418
3681
  id: string;
3682
+ /** The options offered, two or three, in order. */
3419
3683
  options: UserInputOption[];
3684
+ /** The full question text to show the user. */
3420
3685
  question: string;
3686
+ /** Whether the user picks one option or several. */
3421
3687
  selection: UserInputSelection;
3422
3688
  }
3423
3689
 
3424
3690
  /** Full params shared by `userInput/request` and `userInput/requested`. */
3425
3691
  export interface UserInputRequestParams {
3692
+ /** 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
3693
  autoResolutionMs?: number;
3694
+ /** The `toolCall` view item of the tool call waiting on this prompt. */
3427
3695
  itemId: string;
3696
+ /** The questions to ask, one to three, in order. */
3428
3697
  questions: UserInputQuestion[];
3698
+ /** The session that owns the prompt. */
3429
3699
  sessionId: string;
3700
+ /** The stored records this prompt was folded from, when sent: an opaque token clients must not interpret. */
3430
3701
  sourceRange?: SourceRange;
3702
+ /** The provider's id for the tool call that opened the prompt. */
3431
3703
  toolCallId: string;
3704
+ /** The name of the tool that opened the prompt. */
3432
3705
  toolName: string;
3706
+ /** The turn whose tool call is waiting on this prompt. */
3433
3707
  turnId: string;
3708
+ /** 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
3709
  userInputId: string;
3710
+ /** 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
3711
  viewCursor: string;
3436
3712
  }
3437
3713
 
3714
+ /** How many options the user may pick for a question. */
3438
3715
  export interface UserInputSelection {
3716
+ /** The most options the user may pick. Sent only in `multiple` mode; when absent the maximum is the number of options. */
3439
3717
  maxSelections?: number;
3718
+ /** The minimum selection count for a `multiple` answer. Sent only in `multiple` mode; when absent the minimum is 1. */
3440
3719
  minSelections?: number;
3720
+ /** `single` or `multiple`: whether an answer selects one option or several. */
3441
3721
  mode: UserInputSelectionMode;
3442
3722
  }
3443
3723
 
3724
+ /** Whether a question takes one option or several. */
3444
3725
  export type UserInputSelectionMode = "single" | "multiple";
3445
3726
 
3446
3727
  /** `userInput/settled` params: the first durable prompt settlement. */
3447
3728
  export interface UserInputSettledParams {
3729
+ /** The recorded answers: one per question for `answered`, any confirmed partial answers for `interrupted`, and empty for every other outcome. */
3448
3730
  answers: UserInputAnswer[];
3731
+ /** The user's free-form clarification when the outcome is `clarified`; `null` otherwise. */
3449
3732
  clarification: UserInputClarification | null;
3450
3733
  /** 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
3734
  decidedAt: string | null;
3735
+ /** The `commandId` of the client command that settled the prompt; `null` when no command did, for example after a timeout or an abort. */
3452
3736
  decidedByCommandId: string | null;
3737
+ /** How the prompt ended. */
3453
3738
  outcome: UserInputOutcome;
3739
+ /** The reason, when one applies: the optional reason given with a cancel, or why an `aborted` prompt was closed; `null` otherwise. */
3454
3740
  reason: string | null;
3741
+ /** The session that owns the prompt. */
3455
3742
  sessionId: string;
3743
+ /** The stored records this event was folded from: an opaque token clients must not interpret. */
3456
3744
  sourceRange: SourceRange;
3745
+ /** The prompt that settled. Accept a settlement even for a prompt whose request you never saw. */
3457
3746
  userInputId: string;
3747
+ /** This event's view cursor: opaque, and strictly increasing within the session. */
3458
3748
  viewCursor: string;
3459
3749
  }
3460
3750
 
3461
3751
  /** Winning terminal returned to a late user-input command. */
3462
3752
  export interface UserInputSettlementSummary {
3753
+ /** How the prompt settled, as a `userInput/settled` outcome value such as `answered` or `timedOut`. */
3463
3754
  outcome: string;
3755
+ /** The view cursor of the `userInput/settled` event that recorded the settlement. */
3464
3756
  viewCursor: string;
3465
3757
  }
3466
3758
 
@@ -3477,10 +3769,10 @@ export interface ViewGapParams {
3477
3769
  sessionId: string;
3478
3770
  }
3479
3771
 
3480
- /** The `view/page` request-mode anchor (tdd SS4.7.3). Declared **open**: the tdd spells it "open string enum, v1 value `latestCompaction`". */
3772
+ /** The `view/page` request-mode anchor. Declared **open**: the protocol spells it "open string enum, v1 value `latestCompaction`". */
3481
3773
  export type ViewPageAnchor = "latestCompaction" | (string & {});
3482
3774
 
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. */
3775
+ /** The `view/page` paging direction. Closed: the protocol spells exactly two values and a third would change the paging contract. */
3484
3776
  export type ViewPageDirection = "forward" | "backward";
3485
3777
 
3486
3778
  /** `view/page` params (tdd SS4.7.3): cursor-paged reads of the session view. */
@@ -3491,7 +3783,7 @@ export interface ViewPageParams {
3491
3783
  cursor?: string;
3492
3784
  /** Paging direction; `forward` when omitted. */
3493
3785
  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. */
3786
+ /** 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
3787
  limit: number;
3496
3788
  /** The session to page. */
3497
3789
  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.13",
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",