@muse-code/sdk 1.4.10 → 1.4.12
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +39 -1
- package/dist/src/facade/approval.d.ts +36 -16
- package/dist/src/facade/approval.js +45 -14
- package/dist/src/facade/client.d.ts +17 -1
- package/dist/src/facade/client.js +40 -5
- package/dist/src/facade/gap-fill.js +7 -2
- package/dist/src/facade/session.d.ts +12 -2
- package/dist/src/facade/session.js +86 -4
- package/dist/src/fingerprint.d.ts +1 -1
- package/dist/src/fingerprint.js +1 -1
- package/dist/src/fold/session-fold.d.ts +37 -4
- package/dist/src/fold/session-fold.js +18 -0
- package/dist/src/msp.d.ts +454 -52
- package/package.json +1 -1
package/dist/src/msp.d.ts
CHANGED
|
@@ -10,35 +10,100 @@
|
|
|
10
10
|
// Generated by tbh-protocol (spec 206) from the same schema model as
|
|
11
11
|
// the JSON Schema bundle (INV-017). Do not edit by hand.
|
|
12
12
|
|
|
13
|
+
/** The policy rule a decision created, in display form; the full rule is not included. */
|
|
13
14
|
export interface ApprovalAmendment {
|
|
15
|
+
/** How long the rule lasts: `session` or `localPersistent`. */
|
|
14
16
|
durability: ApprovalAmendmentDurability;
|
|
17
|
+
/** A human-readable preview of the rule, for display. */
|
|
15
18
|
rulePreview: string;
|
|
16
19
|
}
|
|
17
20
|
|
|
21
|
+
/** How long a rule created by an approval decision lasts. The set is open, so newer hosts may send other values. */
|
|
18
22
|
export type ApprovalAmendmentDurability = "session" | "localPersistent" | (string & {});
|
|
19
23
|
|
|
24
|
+
/** The change an `approval/updated` event reports. `kind` says what happened, and only the fields for that kind are present. */
|
|
20
25
|
export interface ApprovalChange {
|
|
26
|
+
/** The `choiceId` that satisfied the stage. Present only when `kind` is `stageResolved`. */
|
|
21
27
|
choiceId?: string;
|
|
28
|
+
/** The decision the chosen option applied to the stage. Present only when `kind` is `stageResolved`. */
|
|
22
29
|
decision?: ApprovalDecision;
|
|
30
|
+
/** A recovery detail: whether the action could run without a new decision. Present only when `kind` is `restartRecovered`. */
|
|
23
31
|
executable?: boolean;
|
|
32
|
+
/** What happened: for example `stageResolved` (a shell stage was satisfied), `policyPersistence` (saving a rule succeeded or failed), `reviewStarted` or `reviewCompleted` (the automated LLM judge started or finished reviewing), `restartRecovered` (a host restart recovered this approval: either the host first resolves it `abort` and a re-ask comes as a new approval with a new `approvalId`, or it stays pending under the same `approvalId` with refreshed choices) or `alreadyTerminal` (recovery found it already decided). The set is open, so newer hosts may add kinds. */
|
|
24
33
|
kind: string;
|
|
34
|
+
/** Why saving the policy rule failed, as human-readable text. Present only when `kind` is `policyPersistence` and `status` is `failed`. */
|
|
25
35
|
reason?: string;
|
|
36
|
+
/** A recovery detail: whether the command was re-parsed during recovery. Present only when `kind` is `restartRecovered`. */
|
|
26
37
|
reparsed?: boolean;
|
|
38
|
+
/** The stage requirement that was satisfied. Present only when `kind` is `stageResolved`. */
|
|
27
39
|
requirementId?: ApprovalRequirementRef;
|
|
40
|
+
/** Whether saving the policy rule succeeded or failed; present only when `kind` is `policyPersistence`. A failure does not undo the decision; only the saved rule is missing. */
|
|
28
41
|
status?: ApprovalPersistenceStatus;
|
|
29
42
|
}
|
|
30
43
|
|
|
44
|
+
/** One option the server offers for deciding an approval. Clients pick one and send its `choiceId` in `approval/decide`; they never build their own. */
|
|
31
45
|
export interface ApprovalChoice {
|
|
46
|
+
/** `true` when this choice takes optional `feedback` text in `approval/decide`, which reaches the model as guidance. Omitted when `false`. */
|
|
32
47
|
acceptsFeedback?: boolean;
|
|
48
|
+
/** The id to send as `choiceId` in `approval/decide`. The set of ids is open, so show `label` and do not base behavior on specific ids. */
|
|
33
49
|
choiceId: string;
|
|
50
|
+
/** The decision this choice applies, so a client can act on approve or reject without knowing choice ids. */
|
|
34
51
|
decision: ApprovalDecision;
|
|
52
|
+
/** The human-readable label to show for this choice. */
|
|
35
53
|
label: string;
|
|
54
|
+
/** A human-readable preview of what this choice grants, such as the policy rule it would create; show it exactly as given. */
|
|
36
55
|
rulePreview?: string;
|
|
56
|
+
/** The grant duration this choice declares: `once` (this request only), `session` (the rest of the session) or `localPersistent` (saved in the local policy store). */
|
|
37
57
|
scope: ApprovalChoiceScope;
|
|
38
58
|
}
|
|
39
59
|
|
|
60
|
+
/** How long a grant made by a choice lasts. The set is open, so newer hosts may send other values. */
|
|
40
61
|
export type ApprovalChoiceScope = "once" | "session" | "localPersistent" | (string & {});
|
|
41
62
|
|
|
63
|
+
/** One Computer Use card's facts. Empty collections and absent rows are omitted, never `null`. */
|
|
64
|
+
export interface ApprovalCuaCardFacts {
|
|
65
|
+
/** For a browser, the host of the window's current page. */
|
|
66
|
+
page?: ApprovalCuaPage;
|
|
67
|
+
/** Only the consequential steps, in call order. */
|
|
68
|
+
steps?: ApprovalCuaStep[];
|
|
69
|
+
/** The target window's title: the app's own text, which a page can set; a client shows it quoted and as plain text, never as markup or a choice, and may cap it. */
|
|
70
|
+
windowTitle?: string;
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/** The page's full host, no path or query. */
|
|
74
|
+
export interface ApprovalCuaPage {
|
|
75
|
+
/** The host in Unicode. */
|
|
76
|
+
host: string;
|
|
77
|
+
/** The host's `xn--` form; equal to `host` when they don't differ. */
|
|
78
|
+
hostAscii: string;
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/** A point in the model's 0–1000 coordinates. */
|
|
82
|
+
export interface ApprovalCuaPoint {
|
|
83
|
+
x: number;
|
|
84
|
+
y: number;
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/** One consequential step. A client renders "Step N: <action> <roleWord> "<label>" — <effect>"; a key step names its `chord`, and only a step with a `point` (and no label or chord) reads "at x,y". */
|
|
88
|
+
export interface ApprovalCuaStep {
|
|
89
|
+
/** The host's verb phrase, such as `click` or `type into`. */
|
|
90
|
+
action: string;
|
|
91
|
+
/** The chord, for a key step. */
|
|
92
|
+
chord?: string;
|
|
93
|
+
/** The host's trusted sentence for what the step may do. */
|
|
94
|
+
effect: string;
|
|
95
|
+
/** An open tag for styling and tests only (`verb:<class>`, `unresolved`, `unlabeled`); a client that doesn't know a value renders the step from `effect` and its label as usual. */
|
|
96
|
+
kind: string;
|
|
97
|
+
/** The control's label: the app's own text, shown quoted and as plain text; a client may cap it. */
|
|
98
|
+
label?: string;
|
|
99
|
+
/** The step's own 0–1000 model coordinates, only for a point step. */
|
|
100
|
+
point?: ApprovalCuaPoint;
|
|
101
|
+
/** `button`, `link`, `menu item` or `key`; absent for a point step. */
|
|
102
|
+
roleWord?: string;
|
|
103
|
+
/** 1-based, as the batch numbers its steps. */
|
|
104
|
+
step: number;
|
|
105
|
+
}
|
|
106
|
+
|
|
42
107
|
/** `approval/decide` params (tdd SS5.4): the decision. A standard SS3 command — requires the session loaded on this host, requires `commandId`, durable intake before ack, value-identical replay. */
|
|
43
108
|
export interface ApprovalDecideParams {
|
|
44
109
|
/** The approval being decided. */
|
|
@@ -67,6 +132,7 @@ export interface ApprovalDecideResult {
|
|
|
67
132
|
terminal: boolean;
|
|
68
133
|
}
|
|
69
134
|
|
|
135
|
+
/** The kind of decision a choice applies or an approval received. The set is open, so newer hosts may send values this version does not list. */
|
|
70
136
|
export type ApprovalDecision = "approved" | "approvedForSession" | "approvedPolicyAmendment" | "denied" | "deniedPolicyAmendment" | "timedOut" | "abort" | (string & {});
|
|
71
137
|
|
|
72
138
|
/** `approval/listPending` params (tdd SS5.7): the pull dual of the re-issued requests. A log-fold read — no lease, works on loaded and unloaded sessions, never subscribes. */
|
|
@@ -77,9 +143,9 @@ export interface ApprovalListPendingParams {
|
|
|
77
143
|
|
|
78
144
|
/** `approval/listPending` result (tdd SS5.7). Ordering is by opening `viewCursor`; empty arrays when nothing is pending. The result is point-in-time — to act on it race-safely, `approval/decide` carries the `requirementId` guard regardless of how the client learned the state. */
|
|
79
145
|
export interface ApprovalListPendingResult {
|
|
80
|
-
/** Exactly the `approval/request` params
|
|
146
|
+
/** Exactly the `approval/request` params, one per pending approval. */
|
|
81
147
|
approvals: ApprovalRequestParams[];
|
|
82
|
-
/** Exactly the `userInput/request` params
|
|
148
|
+
/** Exactly the `userInput/request` params, one per pending prompt. */
|
|
83
149
|
userInputs: UserInputRequestParams[];
|
|
84
150
|
}
|
|
85
151
|
|
|
@@ -92,93 +158,152 @@ export type ApprovalModeApplyOutcome = "completed" | "noop" | (string & {});
|
|
|
92
158
|
/** How an approval mode took effect (tdd SS5.12, the effective-mode projection's `source` vocabulary). Open. */
|
|
93
159
|
export type ApprovalModeSource = "startup" | "replay" | "approvalReconfigure" | (string & {});
|
|
94
160
|
|
|
161
|
+
/** What triggered a tool action, shown so the user can judge it. It is display-only and untrusted, and policy rules never match on it. */
|
|
95
162
|
export interface ApprovalOrigin {
|
|
163
|
+
/** The shell command whose process asked for the action. Present when `kind` is `shellCommand`. */
|
|
96
164
|
command?: string;
|
|
165
|
+
/** Which kind of origin this is: `shellCommand` or `url`. */
|
|
97
166
|
kind: string;
|
|
167
|
+
/** The full URL a fetch tool is requesting. Present when `kind` is `url`. */
|
|
98
168
|
url?: string;
|
|
99
169
|
}
|
|
100
170
|
|
|
171
|
+
/** The result of saving a granted rule to the local policy store. The set is open, so newer hosts may send other values. */
|
|
101
172
|
export type ApprovalPersistenceStatus = "succeeded" | "failed" | (string & {});
|
|
102
173
|
|
|
174
|
+
/** Whether an approval's final decision lets the action run. The set is open, so newer hosts may send other values. */
|
|
103
175
|
export type ApprovalPolicyResult = "allow" | "deny" | (string & {});
|
|
104
176
|
|
|
105
177
|
/** Full params shared by `approval/request` and `approval/requested`. */
|
|
106
178
|
export interface ApprovalRequestParams {
|
|
179
|
+
/** The approval's stable id. Match `approval/decide`, `approval/updated` and `approval/resolved` by it, never by the JSON-RPC request id, which belongs to one connection. */
|
|
107
180
|
approvalId: string;
|
|
181
|
+
/** The choices the server offers for the current requirement. Send the chosen one's `choiceId` in `approval/decide`; clients never build their own. */
|
|
108
182
|
availableChoices: ApprovalChoice[];
|
|
183
|
+
/** A Computer Use card's facts: the page, the window and each step that may have an effect, in the host's words; absent on every other approval. */
|
|
184
|
+
cuaCardFacts?: ApprovalCuaCardFacts;
|
|
185
|
+
/** The requirement the next decision must target; send it unchanged as `requirementId` in `approval/decide`. For `shell` it names the first stage still needing a decision; for other kinds its `sourceIndex` is 0. */
|
|
109
186
|
currentRequirementId: ApprovalRequirementRef;
|
|
187
|
+
/** The `toolCall` view item waiting on this approval. */
|
|
110
188
|
itemId: string;
|
|
189
|
+
/** `true` when the automated LLM judge saw this request first and handed it to a person without deciding. A display hint only. The host sends it as `false` when it re-issues the request after a restart or on `session/resume`; a re-send for a later stage keeps it. */
|
|
111
190
|
judgeEscalated: boolean;
|
|
191
|
+
/** `true` when this approval guards a write to a protected file. Only allow-once and reject choices are offered, and a decision is accepted only while at least one client is subscribed to the session. */
|
|
112
192
|
protectedWrite: boolean;
|
|
193
|
+
/** The tool call's arguments as a string, usually JSON. With `toolName`, it lets a client show a subject whose `kind` it does not recognize. */
|
|
113
194
|
rawArgs: string;
|
|
195
|
+
/** The owning session. For a subagent's approval shown on the parent, this is the parent session. */
|
|
114
196
|
sessionId: string;
|
|
197
|
+
/** The stored records this event was folded from: an opaque token clients must not interpret. */
|
|
115
198
|
sourceRange: SourceRange;
|
|
116
199
|
/** Present only for a child (native subagent) approval projected onto the parent session's plane (ADR 36182); parent-own approvals omit it. */
|
|
117
200
|
subagentOrigin?: ApprovalSubagentOrigin;
|
|
201
|
+
/** What the approval is for. Show a `kind` you do not recognize generically, and never auto-approve it. */
|
|
118
202
|
subject: ApprovalSubject;
|
|
203
|
+
/** The id of the task running the tool call. */
|
|
119
204
|
taskId: string;
|
|
205
|
+
/** The model provider's id for this tool call. */
|
|
120
206
|
toolCallId: string;
|
|
207
|
+
/** The name of the tool being called. */
|
|
121
208
|
toolName: string;
|
|
209
|
+
/** The turn whose tool call is waiting on this approval. */
|
|
122
210
|
turnId: string;
|
|
211
|
+
/** The cursor of the `approval/requested` event that opened this request. A re-send for a later stage keeps this cursor, so `view/page` at it returns the opening stage, which may be older than this payload. */
|
|
123
212
|
viewCursor: string;
|
|
124
213
|
}
|
|
125
214
|
|
|
126
|
-
/**
|
|
215
|
+
/** Identifies one requirement of an approval: for a `shell` approval, one stage. A client sends it back as `requirementId` in `approval/decide`, and a stale-requirement error names the current one. */
|
|
127
216
|
export interface ApprovalRequirementRef {
|
|
217
|
+
/** The approval this requirement belongs to. */
|
|
128
218
|
approvalId: string;
|
|
219
|
+
/** The requirement's index within the approval, counting from 0; an approval with a single requirement uses 0. */
|
|
129
220
|
sourceIndex: number;
|
|
130
221
|
}
|
|
131
222
|
|
|
132
223
|
/** Winning terminal returned to a losing `approval/decide` command. */
|
|
133
224
|
export interface ApprovalResolutionSummary {
|
|
225
|
+
/** The winning decision, as an `approval/resolved` decision value such as `approved` or `abort`. */
|
|
134
226
|
decision: string;
|
|
227
|
+
/** Who made the winning decision, such as `user`, `policy` or `llmJudge`. */
|
|
135
228
|
resolvedBy: string;
|
|
229
|
+
/** The view cursor of the winning `approval/resolved` event. */
|
|
136
230
|
viewCursor: string;
|
|
137
231
|
}
|
|
138
232
|
|
|
233
|
+
/** Who or what made an approval's final decision. The set is open, so newer hosts may send other values. */
|
|
139
234
|
export type ApprovalResolvedBy = "user" | "policy" | "llmJudge" | (string & {});
|
|
140
235
|
|
|
141
236
|
/** `approval/resolved` params: the first durable terminal decision. */
|
|
142
237
|
export interface ApprovalResolvedParams {
|
|
238
|
+
/** The policy rule the decision created. Present only when the decision created one. */
|
|
143
239
|
amendment?: ApprovalAmendment;
|
|
240
|
+
/** The approval that was decided. */
|
|
144
241
|
approvalId: string;
|
|
145
242
|
/** The decision time as RFC3339, projected from the durable `DecisionApplied` record's own stamp (ADR 45450 D3): optional on the wire so decoders tolerate its absence, always populated by current hosts. */
|
|
146
243
|
decidedAt?: string;
|
|
244
|
+
/** The `commandId` of the `approval/decide` command that won. Absent when no such command made the decision, for example a policy or LLM judge decision. */
|
|
147
245
|
decidedByCommandId?: string;
|
|
246
|
+
/** The final decision. */
|
|
148
247
|
decision: ApprovalDecision;
|
|
248
|
+
/** The `toolCall` view item this approval was holding. */
|
|
149
249
|
itemId: string;
|
|
250
|
+
/** Whether the final decision lets the action run (`allow`) or blocks it (`deny`). */
|
|
150
251
|
policyResult: ApprovalPolicyResult;
|
|
252
|
+
/** Who or what made the decision: `user`, `policy` or `llmJudge`. */
|
|
151
253
|
resolvedBy: ApprovalResolvedBy;
|
|
254
|
+
/** The owning session. */
|
|
152
255
|
sessionId: string;
|
|
256
|
+
/** The stored records this event was folded from: an opaque token clients must not interpret. */
|
|
153
257
|
sourceRange: SourceRange;
|
|
258
|
+
/** For a `shell` approval, how each stage was resolved when the decision became final. Empty for other subject kinds, and it can be empty for `shell` too. */
|
|
154
259
|
stageEvidence: ApprovalStageEvidence[];
|
|
155
260
|
/** Present only for a child (native subagent) approval projected onto the parent session's plane (ADR 36182); parent-own approvals omit it. */
|
|
156
261
|
subagentOrigin?: ApprovalSubagentOrigin;
|
|
262
|
+
/** The turn whose tool call this approval was holding. */
|
|
157
263
|
turnId: string;
|
|
264
|
+
/** This event's view cursor: opaque, and strictly increasing within the session. */
|
|
158
265
|
viewCursor: string;
|
|
159
266
|
}
|
|
160
267
|
|
|
268
|
+
/** One stage of a `shell` approval: a single command from the pipeline or command list, approved separately from the others. */
|
|
161
269
|
export interface ApprovalStage {
|
|
270
|
+
/** The stage's command words as parsed. When `argvComplete` is `false`, this can be a single unparsed piece of the command. */
|
|
162
271
|
argv: string[];
|
|
272
|
+
/** `true` when `argv` is the stage's complete command, known before it runs; `false` when part of it cannot be resolved ahead of time (for example a command substitution). A stage with `false` never has a `suggestedPrefix`. */
|
|
163
273
|
argvComplete: boolean;
|
|
274
|
+
/** This stage's 1-based position in the command; it equals `requirementId.sourceIndex + 1`. */
|
|
164
275
|
position: number;
|
|
276
|
+
/** This stage's requirement id. When it equals the approval's `currentRequirementId`, send it as `requirementId` in `approval/decide`. */
|
|
165
277
|
requirementId: ApprovalRequirementRef;
|
|
278
|
+
/** Whether this stage still needs a decision or, if not, how it was satisfied. */
|
|
166
279
|
resolution: ApprovalStageResolution;
|
|
280
|
+
/** A command prefix the host suggests always allowing in this workspace, present only when one can be taken from a fully parsed stage. `availableChoices` shows whether that grant is offered. */
|
|
167
281
|
suggestedPrefix?: ApprovalSuggestedPrefix;
|
|
282
|
+
/** The total number of stages in the command. */
|
|
168
283
|
totalStages: number;
|
|
169
284
|
}
|
|
170
285
|
|
|
286
|
+
/** How one stage of a `shell` approval was resolved when the decision became final. */
|
|
171
287
|
export interface ApprovalStageEvidence {
|
|
288
|
+
/** The stage's command words as parsed. */
|
|
172
289
|
argv: string[];
|
|
290
|
+
/** The stage's 1-based position in the command. */
|
|
173
291
|
position: number;
|
|
292
|
+
/** The stage's requirement id. */
|
|
174
293
|
requirementId: ApprovalRequirementRef;
|
|
294
|
+
/** How the stage was resolved at the final decision. */
|
|
175
295
|
resolution: ApprovalStageResolution;
|
|
296
|
+
/** The total number of stages in the command. */
|
|
176
297
|
totalStages: number;
|
|
177
298
|
}
|
|
178
299
|
|
|
300
|
+
/** Whether a shell stage still needs a decision, or how it was satisfied. Satisfied stages are included so a client can show progress. */
|
|
179
301
|
export interface ApprovalStageResolution {
|
|
302
|
+
/** The command prefix saved as an always-allow rule when this stage was approved. Present only when `kind` is `policyAmendment`. */
|
|
180
303
|
argvPrefix?: string[];
|
|
304
|
+
/** Free-form text naming the rule or mode that allowed the stage, for display or troubleshooting. Present only when `kind` is `policyAllow`. */
|
|
181
305
|
diagnostic?: string;
|
|
306
|
+
/** One of `unresolved`, `knownSafe`, `policyAllow`, `allowOnce` or `policyAmendment`. The set is open, so newer hosts may add values. */
|
|
182
307
|
kind: string;
|
|
183
308
|
}
|
|
184
309
|
|
|
@@ -194,37 +319,59 @@ export interface ApprovalSubagentOrigin {
|
|
|
194
319
|
|
|
195
320
|
/** Open approval subject union. Unknown kinds are rendered generically and never auto-approved by clients (tdd SS5.2). */
|
|
196
321
|
export interface ApprovalSubject {
|
|
322
|
+
/** The access asked for: `read` or `write` for `fileAccess`, `control` for `process`. Absent for other kinds. */
|
|
197
323
|
access?: string;
|
|
324
|
+
/** The full raw shell command. Present when `kind` is `shell`. */
|
|
198
325
|
command?: string;
|
|
326
|
+
/** The network host the tool wants to reach. Present when `kind` is `network`. */
|
|
199
327
|
host?: string;
|
|
200
328
|
/** Open discriminator: `shell | fileAccess | network | unixSocket | process | tool`. */
|
|
201
329
|
kind: string;
|
|
330
|
+
/** What triggered the action (a shell command or a URL), for display only and untrusted. It is not sent on `shell` subjects, and policy rules never match on it. */
|
|
202
331
|
origin?: ApprovalOrigin;
|
|
332
|
+
/** For `fileAccess`, the path the tool asked to access, normalized by the host (workspace-relative inside the workspace); for `unixSocket`, the exact resolved socket path, sent unescaped, so escape it before display. */
|
|
203
333
|
path?: string;
|
|
334
|
+
/** The network port, present only on `network` subjects that name one. A session grant made from a subject without a port covers every port. */
|
|
204
335
|
port?: number;
|
|
336
|
+
/** The network protocol, for example `https`. Present only on `network` subjects that name one. */
|
|
205
337
|
protocol?: string;
|
|
338
|
+
/** The shell command split into stages that are approved separately (the commands of a pipeline or command list), in order. Present on `shell` subjects; it may be empty. */
|
|
206
339
|
stages?: ApprovalStage[];
|
|
340
|
+
/** Display text naming the process the tool wants to control. Present when `kind` is `process`. */
|
|
207
341
|
target?: string;
|
|
342
|
+
/** The tool asking for the action. Present for every kind except `shell`. */
|
|
208
343
|
toolName?: string;
|
|
344
|
+
/** The canonical workspace root the shell command runs in, present on `shell` subjects when the host knows it. Saved command-prefix rules apply only within this root. */
|
|
209
345
|
workspaceRoot?: string;
|
|
210
346
|
}
|
|
211
347
|
|
|
348
|
+
/** A suggested always-allow rule for a shell stage: commands starting with `argvPrefix` would run in this workspace without asking. */
|
|
212
349
|
export interface ApprovalSuggestedPrefix {
|
|
350
|
+
/** The leading command words the rule would allow, for example `["cargo", "test"]`. */
|
|
213
351
|
argvPrefix: string[];
|
|
352
|
+
/** A human-readable label for the suggestion, ready to show as is. */
|
|
214
353
|
label: string;
|
|
215
354
|
}
|
|
216
355
|
|
|
217
356
|
/** `approval/updated` params: the refreshed pending view plus one change. */
|
|
218
357
|
export interface ApprovalUpdatedParams {
|
|
358
|
+
/** The approval that changed. */
|
|
219
359
|
approvalId: string;
|
|
360
|
+
/** The refreshed choices for the current requirement. */
|
|
220
361
|
availableChoices: ApprovalChoice[];
|
|
362
|
+
/** What changed; `change.kind` names the kind of change. */
|
|
221
363
|
change: ApprovalChange;
|
|
364
|
+
/** The requirement the next decision must target after this change; send it as `requirementId` in `approval/decide`. */
|
|
222
365
|
currentRequirementId: ApprovalRequirementRef;
|
|
366
|
+
/** The owning session. */
|
|
223
367
|
sessionId: string;
|
|
368
|
+
/** The stored records this event was folded from: an opaque token clients must not interpret. */
|
|
224
369
|
sourceRange: SourceRange;
|
|
225
370
|
/** Present only for a child (native subagent) approval projected onto the parent session's plane (ADR 36182); parent-own approvals omit it. */
|
|
226
371
|
subagentOrigin?: ApprovalSubagentOrigin;
|
|
372
|
+
/** The approval's subject, with `stages` refreshed for this change. */
|
|
227
373
|
subject: ApprovalSubject;
|
|
374
|
+
/** This event's view cursor: opaque, and strictly increasing within the session. */
|
|
228
375
|
viewCursor: string;
|
|
229
376
|
}
|
|
230
377
|
|
|
@@ -234,6 +381,26 @@ export type AttentionFlag = "approvalPending" | "inputPending" | (string & {});
|
|
|
234
381
|
/** Who durably backgrounded a task (tdd SS4.5.5, `TaskBackgroundedInitiator`). Open — runtime vocabulary. */
|
|
235
382
|
export type BackgroundInitiator = "user" | "timeout" | (string & {});
|
|
236
383
|
|
|
384
|
+
/** `backgroundTerminalCompletion`: the five facts the Finished cell renders (ADR 50041 D3/D4). The fold reads them from the inbox terminal record and the backgrounded call it names; every member is required (empty output serializes as `""`, never absent). */
|
|
385
|
+
export interface BackgroundTerminalCompletion {
|
|
386
|
+
/** The title text gate-off shows for the backgrounded command. */
|
|
387
|
+
command: string;
|
|
388
|
+
/** The completion text; empty when the terminal carries none. */
|
|
389
|
+
output: string;
|
|
390
|
+
/** True when `output` is a prefix of the terminal text. */
|
|
391
|
+
outputTruncated: boolean;
|
|
392
|
+
/** One of `completed`, `failed`, `cancelled`, `timedOut`, `rejected` (the ItemStatus wire vocabulary, tdd SS4.4.1). */
|
|
393
|
+
terminalStatus: string;
|
|
394
|
+
/** The backgrounded call's call id: the live/history correlation key behind the skip-when-minted rule (ADR 50041 D6). */
|
|
395
|
+
toolCallId: string;
|
|
396
|
+
}
|
|
397
|
+
|
|
398
|
+
/** The cold recall seed on `session/resume` and `session/read` results (ADR 50074 D2): at most one, the latest blocked Main prompt — exactly the host's mirror of `prompt_recovery::replay::ReplayInput`'s choice. */
|
|
399
|
+
export interface BlockedPrompt {
|
|
400
|
+
/** The exact submitted prompt, verbatim — no truncation, no normalization; recall fidelity requires exactness. */
|
|
401
|
+
text: string;
|
|
402
|
+
}
|
|
403
|
+
|
|
237
404
|
/** The latest branch observation in the snapshot (tdd SS4.6.4, SS4.9.1). */
|
|
238
405
|
export interface BranchState {
|
|
239
406
|
/** The observed branch; `null` on a detached-HEAD observation. */
|
|
@@ -244,9 +411,15 @@ export interface BranchState {
|
|
|
244
411
|
workspaceRoot: string;
|
|
245
412
|
}
|
|
246
413
|
|
|
247
|
-
/** A grantable capability name
|
|
414
|
+
/** A grantable capability name. Open: the experimental-only `rawLog` entry joins the stable domain as an additive open-enum extension when it graduates — closed would make that a retype. */
|
|
248
415
|
export type CapabilityName = "userShell" | "sessionMcp" | "sessionListStream" | "feedback" | "computerUseSetup" | "computerUseHostSetup" | "sessionRename" | (string & {});
|
|
249
416
|
|
|
417
|
+
/** A served checkpoint-prune boundary (spec 13929 amendment FR-50042-1; ADR 50042 D3): `through_item_id` names the last first-opened item that opened strictly before the boundary checkpoint event. */
|
|
418
|
+
export interface CheckpointBoundary {
|
|
419
|
+
/** The last pre-boundary item's id, in served (first-opened) order. */
|
|
420
|
+
throughItemId: string;
|
|
421
|
+
}
|
|
422
|
+
|
|
250
423
|
/** The client's requested capability posture (SS1.4.1). Every member defaults; an absent `capabilities` object means all defaults. */
|
|
251
424
|
export interface ClientCapabilities {
|
|
252
425
|
/** Opt into experimental methods, fields, and variants (default `false`). */
|
|
@@ -305,7 +478,7 @@ export interface CommandAcceptedResult {
|
|
|
305
478
|
status: CommandAckStatus;
|
|
306
479
|
}
|
|
307
480
|
|
|
308
|
-
/** The ack-status vocabulary
|
|
481
|
+
/** The ack-status vocabulary: `"accepted"` for every admitted command; `session/compact` alone may answer `"noop"`. Closed: the protocol defines exactly these two values, so SDK clients get a discriminated type and validation catches a wrong status — and a client that received a third value would have been told nothing it can act on, unlike [`TurnStartDisposition`], where "acked, not otherwise classified" is a usable reading. */
|
|
309
482
|
export type CommandAckStatus = "accepted" | "noop";
|
|
310
483
|
|
|
311
484
|
/** The SS3.1.2 ack `status`: `accepted` for every admitted command. `session/compact` is the one method that may additionally answer `noop` ([`crate::method::runtime::CompactStatus`]); no other command uses another status (tdd SS3.1.2). */
|
|
@@ -464,9 +637,9 @@ export interface ContextUsage {
|
|
|
464
637
|
windowTokens?: number;
|
|
465
638
|
}
|
|
466
639
|
|
|
467
|
-
/** Cron's `details` payload (ADR 42728 D2, thirteenth directive). Every field a family owns lives here, under the container's one `details` key, rather than flat beside the discriminators
|
|
640
|
+
/** Cron's `details` payload (ADR 42728 D2, thirteenth directive). Every field a family owns lives here, under the container's one `details` key, rather than flat beside the discriminators. Each is a **bounded machine fact**: scalars, short identifiers and a small fixed-shape array of those. */
|
|
468
641
|
export interface CronReceipt {
|
|
469
|
-
/** Cron `create` and `delete`: the job id. On `delete`'s `missing` arm this is the caller's own id echoed back
|
|
642
|
+
/** Cron `create` and `delete`: the job id. On `delete`'s `missing` arm this is the caller's own id echoed back — that arm has no server-side subject to name. On the `created` + `cancelled` pairing, this field also conveys the hidden fact: a job row was committed and will fire. */
|
|
470
643
|
jobId?: string;
|
|
471
644
|
/** Cron `list`: the served jobs in server order, `active` and `firing` rows only. */
|
|
472
645
|
jobs?: CronReceiptJob[];
|
|
@@ -474,7 +647,7 @@ export interface CronReceipt {
|
|
|
474
647
|
nextFireAtMs?: number;
|
|
475
648
|
}
|
|
476
649
|
|
|
477
|
-
/** One row of the Cron `list` receipt's `jobs` array (ADR 42728 D2). Server order, and **`active` + `firing` rows only
|
|
650
|
+
/** One row of the Cron `list` receipt's `jobs` array (ADR 42728 D2). Server order, and **`active` + `firing` rows only**. A small fixed-shape array of scalars, which is what keeps it a bounded machine fact. */
|
|
478
651
|
export interface CronReceiptJob {
|
|
479
652
|
/** The job's server-owned id. */
|
|
480
653
|
jobId: string;
|
|
@@ -490,7 +663,7 @@ export interface CumulativeCost {
|
|
|
490
663
|
usd: number;
|
|
491
664
|
}
|
|
492
665
|
|
|
493
|
-
/** Session running totals of counted-once usage (tdd SS4.6.5).
|
|
666
|
+
/** Session running totals of counted-once usage (tdd SS4.6.5). The cache splits and server-computed `cost` join the counters. The counters stay accumulate-only; `cost` is the documented exception — it may move either way on price re-adoption and is labeled estimate. `Copy` was dropped for the `cost` member. */
|
|
494
667
|
export interface CumulativeTokenUsage {
|
|
495
668
|
/** Cache-read tokens, session total (FR-41610-1): saturating sum of the per-completion splits; an absent split contributes 0. Additive-optional: absent on the wire reads as 0 and zero totals are omitted, so pre-feature bytes decode and re-encode identically. */
|
|
496
669
|
cacheReadTokens?: number;
|
|
@@ -506,6 +679,20 @@ export interface CumulativeTokenUsage {
|
|
|
506
679
|
totalTokens: number;
|
|
507
680
|
}
|
|
508
681
|
|
|
682
|
+
/** `damagedRange`: what one damaged range of the session log cost (ADR 60914 D1/D2). The reader finds the range in the log bytes; no log record is written for it, so every member is derived from the readable records around it. */
|
|
683
|
+
export interface DamagedRange {
|
|
684
|
+
/** The last finished turn before the first damaged range, when one exists: the safe `session/fork` cut (ADR 60914 D1 "Fork cuts", D4). */
|
|
685
|
+
lastGoodTurnId?: string;
|
|
686
|
+
/** Records the log proves missing (session-stream sequence numbers no readable record or unreadable line accounts for). */
|
|
687
|
+
missingRecords: number;
|
|
688
|
+
/** RFC3339 `recordedAt` of the first readable record after the range; always present, since a range is read past only when readable records follow it (ADR 60914 D1). */
|
|
689
|
+
readableAfterAt: string;
|
|
690
|
+
/** RFC3339 `recordedAt` of the last readable record before the range; absent when the range starts the log. */
|
|
691
|
+
readableBeforeAt?: string;
|
|
692
|
+
/** Physical log lines in the range that are not a readable record. */
|
|
693
|
+
unreadableLines: number;
|
|
694
|
+
}
|
|
695
|
+
|
|
509
696
|
/** The effective approval-mode projection (`EffectiveApprovalModeState`, tdd SS5.12): the same object `session/setApprovalMode` returns as `effectiveMode` and the `Session` object carries as `approvalMode`. */
|
|
510
697
|
export interface EffectiveApprovalModeState {
|
|
511
698
|
/** The command that last set it; `null` when no command did. */
|
|
@@ -532,11 +719,11 @@ export interface ErrorData {
|
|
|
532
719
|
alignedNextOffset?: number;
|
|
533
720
|
/** The rejected anchor value on `notFound`/`missingAnchor` and the `-32042` boundary arms (SS4.7.3, SS4.11); on `-32042` it is served as an explicit `null` when the request named no concrete anchor (spec 208 FM-005). */
|
|
534
721
|
anchor?: string | null;
|
|
535
|
-
/** Approval
|
|
722
|
+
/** Approval id on approval errors. */
|
|
536
723
|
approvalId?: string;
|
|
537
724
|
/** The stored output's availability on `outputUnavailable` — the durable `ToolOutputAvailability` value, read-time-derived when the durable record still says `available` (SS4.5.5; spec 208 FM-008). */
|
|
538
725
|
availability?: string;
|
|
539
|
-
/** The missing capability, on `capabilityRequired` errors. Typed on the grantable registry, so `rawLog`
|
|
726
|
+
/** The missing capability, on `capabilityRequired` errors. Typed on the grantable registry, so the experimental-only `rawLog` joins the stable domain as an additive open-enum extension when it graduates. */
|
|
540
727
|
capability?: CapabilityName;
|
|
541
728
|
/** The configured command-admission bound, on `backpressured` errors. */
|
|
542
729
|
capacity?: number;
|
|
@@ -546,7 +733,7 @@ export interface ErrorData {
|
|
|
546
733
|
commandId?: string;
|
|
547
734
|
/** Current stage token on `approvalRequirementStale`. */
|
|
548
735
|
currentRequirementId?: ApprovalRequirementRef;
|
|
549
|
-
/**
|
|
736
|
+
/** On `experimentalRequired` errors, the name of the experimental method, field or variant the request used, for example `turn/start.providerRequestOptions`. */
|
|
550
737
|
descriptor?: string;
|
|
551
738
|
/** Free-form additive detail. */
|
|
552
739
|
details?: Record<string, unknown>;
|
|
@@ -572,6 +759,8 @@ export interface ErrorData {
|
|
|
572
759
|
paths?: string[];
|
|
573
760
|
/** Failure detail vocabulary (e.g. `"missingAnchor"` on `notFound` for a missing view-cursor anchor). */
|
|
574
761
|
reason?: string;
|
|
762
|
+
/** The original recovery-dependent construction's coherent observation. An absent or unusable observation establishes no supported recovery. */
|
|
763
|
+
recoveryObservation?: RecoveryObservation;
|
|
575
764
|
/** Winning resolution on `approvalAlreadyResolved`. */
|
|
576
765
|
resolution?: ApprovalResolutionSummary;
|
|
577
766
|
/** Whether retrying can succeed (e.g. `overloaded`). When present, overrides the error table row's `retryable` default for this code. */
|
|
@@ -588,13 +777,13 @@ export interface ErrorData {
|
|
|
588
777
|
settlement?: UserInputSettlementSummary;
|
|
589
778
|
/** The rejected upload id on `uploadNotFound` (`-32038`, SS3.33). */
|
|
590
779
|
uploadId?: string;
|
|
591
|
-
/**
|
|
780
|
+
/** Prompt identity on user-input errors. */
|
|
592
781
|
userInputId?: string;
|
|
593
782
|
/** The blocked view position on `pageEventTooLarge` errors. */
|
|
594
783
|
viewCursor?: string;
|
|
595
784
|
}
|
|
596
785
|
|
|
597
|
-
/** A stable `error.data.kind` category
|
|
786
|
+
/** A stable `error.data.kind` category: camelCase, the value clients branch on. Open: new kinds are added as their methods land, and a new `kind` is additive only because this domain is declared open. */
|
|
598
787
|
export type ErrorKind = "parseError" | "invalidRequest" | "notInitialized" | "alreadyInitialized" | "methodNotFound" | "invalidParams" | "experimentalRequired" | "internal" | "pageEventTooLarge" | "outputResultTooLarge" | "overloaded" | "inputTooLarge" | "capabilityRequired" | "notFound" | "interrupted" | "cancelled" | "sessionNotFound" | "sessionInUse" | "sessionAmbiguous" | "forkBoundaryInvalid" | "sessionNotLoaded" | "sessionStreamMismatch" | "commandRejected" | "backpressured" | "skillNotFound" | "computerUseUnavailable" | "marketplaceNotFound" | "pluginNotFound" | "marketplaceAlreadyExists" | "pluginMutationsDisabled" | "uploadNotFound" | "viewTruncated" | "outputUnavailable" | "boundaryPruned" | "boundaryUnusable" | "noBoundary" | "approvalNotFound" | "approvalAlreadyResolved" | "approvalChoiceInvalid" | "approvalRequirementStale" | "approvalReviewerUnavailable" | "userInputNotFound" | "userInputAlreadySettled" | "userInputAnswerInvalid" | (string & {});
|
|
599
788
|
|
|
600
789
|
/** The `error` member of an error response (SS1.2 §2.4). */
|
|
@@ -683,6 +872,8 @@ export interface ForkProvenance {
|
|
|
683
872
|
|
|
684
873
|
/** The session goal block (tdd SS4.6.2, mirrors the runtime's goal state, camelCased). `status` and `percentComplete` are carried **verbatim** — out-of-contract status strings and >100 percents pass through; display clamping is the renderer's job. */
|
|
685
874
|
export interface Goal {
|
|
875
|
+
/** Goal creation time, epoch milliseconds, verbatim from the durable row. Absent on blocks whose producer never carried it (tool-result adoptions, older logs); absence must never render as a fabricated zero. */
|
|
876
|
+
createdAtMs?: number;
|
|
686
877
|
/** Current work description, when present. */
|
|
687
878
|
currentWork?: string;
|
|
688
879
|
/** Next work description, when present. */
|
|
@@ -693,6 +884,8 @@ export interface Goal {
|
|
|
693
884
|
percentComplete: number;
|
|
694
885
|
/** Goal status, verbatim from the durable goal state (free string by design: out-of-contract values pass through). */
|
|
695
886
|
status: string;
|
|
887
|
+
/** Last goal mutation time, epoch milliseconds, verbatim from the durable row. Same absence rule as `createdAtMs`. */
|
|
888
|
+
updatedAtMs?: number;
|
|
696
889
|
}
|
|
697
890
|
|
|
698
891
|
/** `goal/clear` params (tdd SS3.18). An `objective` here is an unknown field and rejects `-32602 invalidParams` — the bare verbs carry exactly this pair. */
|
|
@@ -752,7 +945,7 @@ export interface GoalSetParams {
|
|
|
752
945
|
/** What history a lifecycle result actually served (tdd SS2.5.2). Open on the client side: report-what-was-served means a client treats an unknown mode as "page it yourself". */
|
|
753
946
|
export type HistoryMode = "anchoredSnapshot" | "inline" | "snapshot" | "none" | (string & {});
|
|
754
947
|
|
|
755
|
-
/** Why a result served `history.mode: "none"
|
|
948
|
+
/** Why a result served `history.mode: "none"`: the server's typed reason for serving no history. Open on the client side: an absent (older server) or unknown (newer server) value decodes conservatively as an unknown reason, and `viewCursor` text never substitutes for it. */
|
|
756
949
|
export type HistoryNoneReason = "excluded" | "cursorSuffix" | "historyBudget" | "projectionUnavailable" | "projectionReadLimit" | (string & {});
|
|
757
950
|
|
|
758
951
|
/** The `history` request preference of `session/resume` (tdd SS2.5.2). The forced values downgrade `anchored` → `inline` → `snapshot` → `none`; under `auto` the full rung order is anchoredSnapshot → inline → snapshot → elided snapshot → none. */
|
|
@@ -771,7 +964,7 @@ export interface HookCatalogEntry {
|
|
|
771
964
|
}
|
|
772
965
|
|
|
773
966
|
/** Hook event names (tdd SS3.26.1, ADR 33398 D7 item 2): the lowercase-first-letter spelling of every `HookEventKind::all()` variant. Open (server-produced result vocabulary, the #22785 enum-openness rule): a future event value is additive. */
|
|
774
|
-
export type HookEventName = "sessionStart" | "userPromptSubmit" | "preToolUse" | "permissionRequest" | "postToolUse" | "preCompact" | "postCompact" | "subagentStart" | "subagentStop" | "stop" | "sessionEnd" | "notification" | "postToolUseFailure" | "stopFailure" | "postToolBatch" | "interrupt" | "sessionFork" | "toolUseStart" |
|
|
967
|
+
export type HookEventName = "sessionStart" | "userPromptSubmit" | "preToolUse" | "permissionRequest" | "postToolUse" | "preLLMCall" | "postLLMCall" | "preCompact" | "postCompact" | "subagentStart" | "subagentStop" | "stop" | "sessionEnd" | "notification" | "postToolUseFailure" | "stopFailure" | "postToolBatch" | "interrupt" | "sessionFork" | "toolUseStart" | (string & {});
|
|
775
968
|
|
|
776
969
|
/** A hook row's origin (tdd SS3.26.1, ADR 33398 D7 item 1): the config `HookSourceKind` values plus plugin-contributed. Open (server-produced result vocabulary, the #22785 enum-openness rule): a future origin is additive. */
|
|
777
970
|
export type HookHandlerKind = "managed" | "user" | "project" | "plugin" | (string & {});
|
|
@@ -814,7 +1007,7 @@ export interface InitializeResult {
|
|
|
814
1007
|
platformFamily: PlatformFamily;
|
|
815
1008
|
/** Server operating system. */
|
|
816
1009
|
platformOs: PlatformOs;
|
|
817
|
-
/** Whether this host can enforce the sandbox
|
|
1010
|
+
/** Whether this host can enforce the sandbox. Optional so adding it stays backward compatible; a v1 host always sends it, and a client reads absent as unknown — the host predates the field, so the client falls back to its own probe rather than inventing an answer. */
|
|
818
1011
|
sandboxAvailability?: SandboxAvailability;
|
|
819
1012
|
/** Why enforcement is impossible. Sent only when `sandbox_availability` is `unavailable`; a client MUST NOT infer a reason when none is sent. */
|
|
820
1013
|
sandboxUnavailableReason?: SandboxUnavailableReason;
|
|
@@ -822,7 +1015,7 @@ export interface InitializeResult {
|
|
|
822
1015
|
schema: SchemaInfo;
|
|
823
1016
|
/** Server identification. */
|
|
824
1017
|
serverInfo: ServerInfo;
|
|
825
|
-
/** Whether this host persists its sessions
|
|
1018
|
+
/** Whether this host persists its sessions. Optional so adding it stays backward compatible; a v1 host always sends it, and a client reads absent as `durable` because no server that omits it has the ephemeral profile. */
|
|
826
1019
|
sessionDurability?: SessionDurability;
|
|
827
1020
|
/** Exact user-agent string presented to upstream model providers. */
|
|
828
1021
|
userAgent: string;
|
|
@@ -842,6 +1035,8 @@ export interface Item {
|
|
|
842
1035
|
background?: boolean;
|
|
843
1036
|
/** `toolCall`: who backgrounded the task; absent on pre-split records — never inferred (tdd SS4.5.5). */
|
|
844
1037
|
backgroundInitiator?: BackgroundInitiator;
|
|
1038
|
+
/** `backgroundTerminalCompletion`: the five facts the Finished cell renders (ADR 50041 D4). */
|
|
1039
|
+
backgroundTerminalCompletion?: BackgroundTerminalCompletion;
|
|
845
1040
|
/** `reminderChild`: `true` when this child is a blocking reminder (it holds the turn open until it settles); absent otherwise, never `false` (ADR 41191 D4). The status word stays off the wire; clients name the reminder from `reminderAgentId`. */
|
|
846
1041
|
blocking?: boolean;
|
|
847
1042
|
/** `toolCall`: the provider call id (`call_...`), opaque. */
|
|
@@ -862,15 +1057,19 @@ export interface Item {
|
|
|
862
1057
|
controlStatus?: SubagentControlStatus;
|
|
863
1058
|
/** `agentMessage`: `true` when the provider stream died mid-reply and the run failed with this partial text committed (ADR 50063 D2) — the wire mark for the gate-off "incomplete response" rule (#13328). Absent otherwise; never cleared once set. */
|
|
864
1059
|
cutOff?: boolean;
|
|
1060
|
+
/** `damagedRange`: what the damaged range cost (ADR 60914 D2). */
|
|
1061
|
+
damagedRange?: DamagedRange;
|
|
865
1062
|
/** `workflow`: the run-level declared-phase label — the last `Phase` detail-row label of the reconciled projection; terminal-only, absent while live (tdd SS4.5.8, #45449). */
|
|
866
1063
|
declaredPhase?: string;
|
|
1064
|
+
/** `scheduledFire`: the occurrence number within the job's history, present with occurrence metadata (tdd SS4.5.17; ADR 45446 D2). */
|
|
1065
|
+
deliveryNumber?: number;
|
|
867
1066
|
/** `subagent`: nesting depth. */
|
|
868
1067
|
depth?: number;
|
|
869
1068
|
/** `toolCall`: the tool's own words for this call; absent = none (tdd SS4.5.5). */
|
|
870
1069
|
displayLabel?: ToolDisplayLabel;
|
|
871
1070
|
/** `userMessage`: presentation form (tdd SS3.2); absent when the client sent none. */
|
|
872
1071
|
displayText?: string;
|
|
873
|
-
/** `userShell`/`subagent`: observed wall-clock duration. `workflow`: the run's wall time from launch to reconciliation, set only on the settling `item/completed` — never a sum of child durations. */
|
|
1072
|
+
/** `userShell`/`subagent`: observed wall-clock duration. `workflow`: the run's wall time from launch to reconciliation, set only on the settling `item/completed` — never a sum of child durations. `toolCall`: the Backgrounded row's duration (ADR 50041 D11) — the open→update record delta in whole ms, served on the `backgroundStatus` re-emission and frozen there; absent otherwise. */
|
|
874
1073
|
durationMs?: number;
|
|
875
1074
|
/** `workflow`: launched entry identity. */
|
|
876
1075
|
entryId?: string;
|
|
@@ -892,8 +1091,10 @@ export interface Item {
|
|
|
892
1091
|
generationId?: number;
|
|
893
1092
|
/** `hookRun`: the durable `hook_key` (tdd SS4.5.11). */
|
|
894
1093
|
hookKey?: string;
|
|
895
|
-
/** Bare UUIDv7; the item's identity across its whole lifecycle. Identity rule (tdd SS4.4.1): the task id for task-backed kinds (`toolCall`, `subagent`), the pre-minted commit `message_id` for delta-streamed kinds (`agentMessage`, `reasoning`), and the opening durable record's event id for everything else. Opaque to clients. */
|
|
1094
|
+
/** Bare UUIDv7; the item's identity across its whole lifecycle. Identity rule (tdd SS4.4.1): the task id for task-backed kinds (`toolCall`, `subagent`), the pre-minted commit `message_id` for delta-streamed kinds (`agentMessage`, `reasoning`), `EventId::derive` over the session id and the range's starting sequence number for `damagedRange` (no record carries it, SS4.5.16), and the opening durable record's event id for everything else. Opaque to clients. */
|
|
896
1095
|
itemId: string;
|
|
1096
|
+
/** `scheduledFire`: the cron job id that fired (tdd SS4.5.17; ADR 45446 D2, spec 13929 amendment #62595 FR-62595-1). */
|
|
1097
|
+
jobId?: string;
|
|
897
1098
|
/** The item kind (open enum): clients MUST render unknown kinds generically — kind name plus `status` plus `fallbackText` (tdd SS4.10). */
|
|
898
1099
|
kind: ItemKind;
|
|
899
1100
|
/** `hookRun`: capped display label (tdd SS4.5.11). */
|
|
@@ -908,6 +1109,8 @@ export interface Item {
|
|
|
908
1109
|
monitorDescription?: string;
|
|
909
1110
|
/** `monitorFeed`: the monitor task id — the same value as that monitor's `toolCall` `itemId` (ADR 50058-monitor-feed-wire D1). */
|
|
910
1111
|
monitorId?: string;
|
|
1112
|
+
/** `scheduledFire`: the next scheduled epoch in milliseconds; absent on a final delivery (tdd SS4.5.17; ADR 45446 D2). */
|
|
1113
|
+
nextFireAtMs?: number;
|
|
911
1114
|
/** `subagent`: objective as spawned, bounded on the wire at the 64 KiB retained-text budget (tdd SS4.5.4, ADR 35691 D9); a cut sets `truncated`. The durable record stays verbatim. */
|
|
912
1115
|
objective?: string;
|
|
913
1116
|
/** `compaction`: terminal only — folds installed/fallback status. */
|
|
@@ -940,6 +1143,8 @@ export interface Item {
|
|
|
940
1143
|
role?: string;
|
|
941
1144
|
/** `hookRun`: terminal-only durable outcome; stays `blocked` when the item settles `rejected` (tdd SS4.5.11). */
|
|
942
1145
|
runStatus?: HookRunStatus;
|
|
1146
|
+
/** `scheduledFire`: the fire's scheduled epoch in milliseconds (tdd SS4.5.17; ADR 45446 D2). */
|
|
1147
|
+
scheduledFireAtMs?: number;
|
|
943
1148
|
/** `workflow`: launched script identity. */
|
|
944
1149
|
scriptId?: string;
|
|
945
1150
|
/** `sideChat`: the side's own session id, readable via `session/read`/`view/page` — drill-down without a second protocol (tdd SS4.5.13; ADR 45435 D3). */
|
|
@@ -968,7 +1173,7 @@ export interface Item {
|
|
|
968
1173
|
strategyId?: string;
|
|
969
1174
|
/** `subagent`: durable child identity (`subagent_id`). */
|
|
970
1175
|
subagentId?: string;
|
|
971
|
-
/** `compaction`: opaque provenance string naming the compaction boundary.
|
|
1176
|
+
/** `compaction`: opaque provenance string naming the compaction boundary. Also a compaction-anchored read anchor, accepted by `session/resume` and `view/page`. Still opaque — clients relay it, never parse it. */
|
|
972
1177
|
summarizedThrough?: string;
|
|
973
1178
|
/** `reasoning`: one entry per summary part; part *n* streams via `item/delta` field `"summary.n"` (part boundary = index change). */
|
|
974
1179
|
summary?: string[];
|
|
@@ -992,7 +1197,7 @@ export interface Item {
|
|
|
992
1197
|
triggerSource?: string;
|
|
993
1198
|
/** `true` when the server's per-surface text budget saturated a streamed surface (`agentMessage.text`, `reasoning.summary[*]`, `toolCall.visibleOutput`, `userShell.visibleOutput`), cut a `subagent` surface (`objective`, `fallbackText`, `result.summary`, `result.text`), or cut a `monitorFeed` surface (`text`, `fallbackText`, `monitorDescription`) (ADR 50058-monitor-feed-wire D3). On a `subagent` item the flag is item-level and never cleared: once any of those four is cut, every later update keeps it, even when `result.text` arrives whole (ADR 35691 D9). The durable full text remains in the log (tdd SS4.5.4). */
|
|
994
1199
|
truncated?: boolean;
|
|
995
|
-
/** The owning turn (== the submitting `commandId` for fresh turns, tdd SS3.1.4). `null` for the kinds outside a turn: `userShell` always (tdd SS4.5.6), `hookRun` for session-boundary runs, `monitorFeed` always (ADR 50058-monitor-feed-wire D1). */
|
|
1200
|
+
/** The owning turn (== the submitting `commandId` for fresh turns, tdd SS3.1.4). `null` for the kinds outside a turn: `userShell` always (tdd SS4.5.6), `hookRun` for session-boundary runs, `monitorFeed` always (ADR 50058-monitor-feed-wire D1), `sideChat` always (SS4.5.13), `damagedRange` always (ADR 60914 D2). */
|
|
996
1201
|
turnId?: string | null;
|
|
997
1202
|
/** `subagent`: **transitive** observed usage — the child and its own descendants; updated in place, absent until first observation; never folded into `session/tokenUsage.cumulative` (tdd SS4.6.5). */
|
|
998
1203
|
usage?: TokenUsage;
|
|
@@ -1029,12 +1234,12 @@ export interface ItemDeltaParams {
|
|
|
1029
1234
|
}
|
|
1030
1235
|
|
|
1031
1236
|
/** The eleven v1 item kinds (tdd SS4.5.2–4.5.13) plus post-v1 kinds (tdd SS4.5.14+). Open: a new kind is additive evolution, and clients MUST render unknown kinds generically (tdd SS4.10). */
|
|
1032
|
-
export type ItemKind = "userMessage" | "agentMessage" | "reasoning" | "toolCall" | "userShell" | "subagent" | "workflow" | "reminderChild" | "compaction" | "hookRun" | "sideChat" | "webSearch" | "monitorFeed" | (string & {});
|
|
1237
|
+
export type ItemKind = "userMessage" | "agentMessage" | "reasoning" | "toolCall" | "userShell" | "subagent" | "workflow" | "reminderChild" | "compaction" | "hookRun" | "sideChat" | "webSearch" | "monitorFeed" | "damagedRange" | "scheduledFire" | "backgroundTerminalCompletion" | "overdueNotice" | (string & {});
|
|
1033
1238
|
|
|
1034
1239
|
/** The `item/readOutput` content encoding (tdd SS4.7.4). Closed: text media is ALWAYS `utf8` and binary media `base64`; a third value would change the client's decode contract. */
|
|
1035
1240
|
export type ItemReadOutputEncoding = "utf8" | "base64";
|
|
1036
1241
|
|
|
1037
|
-
/** `item/readOutput` params
|
|
1242
|
+
/** `item/readOutput` params: byte-ranged fetch of stored full output that the view truncated, via the item's `outputRef`. Read-only; works on loaded and unloaded sessions; no lease. */
|
|
1038
1243
|
export interface ItemReadOutputParams {
|
|
1039
1244
|
/** The item whose stored output is fetched. */
|
|
1040
1245
|
itemId: string;
|
|
@@ -1117,7 +1322,7 @@ export interface MediaUploadParams {
|
|
|
1117
1322
|
chunkCount: number;
|
|
1118
1323
|
/** This chunk's 0-based position. */
|
|
1119
1324
|
chunkIndex: number;
|
|
1120
|
-
/** One per call
|
|
1325
|
+
/** One per call. While the host runs, replaying it with the same params returns the recorded receipt, and reusing it with different params is refused. After a host restart, start over under a new `uploadId`. */
|
|
1121
1326
|
commandId: string;
|
|
1122
1327
|
/** `video/mp4` or `video/quicktime`, matching `VideoInput`. */
|
|
1123
1328
|
mediaType: string;
|
|
@@ -1259,6 +1464,68 @@ export interface ModelVisibleContent {
|
|
|
1259
1464
|
width?: number;
|
|
1260
1465
|
}
|
|
1261
1466
|
|
|
1467
|
+
/** `monitor/inboxItemAdmitted` params (tdd SS4.5.18): one monitor inbox admission — the fold keys gate-off consumes. */
|
|
1468
|
+
export interface MonitorInboxItemAdmittedParams {
|
|
1469
|
+
/** The model-facing delivery text. */
|
|
1470
|
+
body: string;
|
|
1471
|
+
/** The producer-recorded pre-augmentation content; absent on pre-#24686 records. */
|
|
1472
|
+
displayBody?: string;
|
|
1473
|
+
/** Per-task event order key (with `line_index`). */
|
|
1474
|
+
eventIndex: number;
|
|
1475
|
+
/** Monitor event kind, snake_case, open vocabulary — clients ignore unknown kinds. */
|
|
1476
|
+
eventKind: string;
|
|
1477
|
+
/** The inbox item id (dedupe key). */
|
|
1478
|
+
itemId: string;
|
|
1479
|
+
/** Line order key; absent when the event has no line. */
|
|
1480
|
+
lineIndex?: number;
|
|
1481
|
+
/** Admission stamp (RFC3339); consumed by the pending sort. */
|
|
1482
|
+
queuedAt: string;
|
|
1483
|
+
/** The owning session. */
|
|
1484
|
+
sessionId: string;
|
|
1485
|
+
/** Whether the event carries displayable lines. */
|
|
1486
|
+
showLines: boolean;
|
|
1487
|
+
/** The durable records this event folded from. */
|
|
1488
|
+
sourceRange: SourceRange;
|
|
1489
|
+
/** The notice-text summary. */
|
|
1490
|
+
summary: string;
|
|
1491
|
+
/** The owning monitor task id (per-task set key). */
|
|
1492
|
+
taskId: string;
|
|
1493
|
+
/** Opaque, strictly monotonic view cursor (tdd SS4.1). */
|
|
1494
|
+
viewCursor: string;
|
|
1495
|
+
}
|
|
1496
|
+
|
|
1497
|
+
/** `monitor/inboxItemDrained` params (tdd SS4.5.18): one monitor inbox drain — a consumption marker with its recorded stamp. */
|
|
1498
|
+
export interface MonitorInboxItemDrainedParams {
|
|
1499
|
+
/** False is a local claim-only recall: no delivery row or recovery consequence, but the drain still stamps the awaiting verdict. */
|
|
1500
|
+
deliveryVisible: boolean;
|
|
1501
|
+
/** The draining run stream (`StreamRef`), absent means the current draining run. */
|
|
1502
|
+
drainTargetRunStream?: StreamRef;
|
|
1503
|
+
/** The drain record's recorded stamp (RFC3339), the drain-side operand of drain-vs-void latest-wins. */
|
|
1504
|
+
drainedAt: string;
|
|
1505
|
+
/** The drained inbox item id. */
|
|
1506
|
+
itemId: string;
|
|
1507
|
+
/** The owning session. */
|
|
1508
|
+
sessionId: string;
|
|
1509
|
+
/** The durable records this event folded from. */
|
|
1510
|
+
sourceRange: SourceRange;
|
|
1511
|
+
/** Opaque, strictly monotonic view cursor (tdd SS4.1). */
|
|
1512
|
+
viewCursor: string;
|
|
1513
|
+
}
|
|
1514
|
+
|
|
1515
|
+
/** `monitor/inboxItemVoided` params (tdd SS4.5.18): one wake-missed void — count-only, no transcript row (spec 9627 D15). */
|
|
1516
|
+
export interface MonitorInboxItemVoidedParams {
|
|
1517
|
+
/** The voided inbox item id. */
|
|
1518
|
+
itemId: string;
|
|
1519
|
+
/** The owning session. */
|
|
1520
|
+
sessionId: string;
|
|
1521
|
+
/** The durable records this event folded from. */
|
|
1522
|
+
sourceRange: SourceRange;
|
|
1523
|
+
/** Opaque, strictly monotonic view cursor (tdd SS4.1). */
|
|
1524
|
+
viewCursor: string;
|
|
1525
|
+
/** The anomaly's recorded stamp (RFC3339), the void-side operand of drain-vs-void latest-wins. */
|
|
1526
|
+
voidedAt: string;
|
|
1527
|
+
}
|
|
1528
|
+
|
|
1262
1529
|
/** A notification frame, either direction (SS1.2 §2.2). No `id`; a notification is never answered. */
|
|
1263
1530
|
export interface Notification {
|
|
1264
1531
|
/** Emission time in Unix milliseconds, recorded once at emission; server→client notifications only (SS1.2.5). Optional on the wire so decoders tolerate older servers. */
|
|
@@ -1317,7 +1584,7 @@ export interface PendingApprovalPointer {
|
|
|
1317
1584
|
/** The `pendingRequests` discriminator (tdd SS2.5.2). Open enum, v1 values `approval` and `userInput`. */
|
|
1318
1585
|
export type PendingRequestKind = "approval" | "userInput" | (string & {});
|
|
1319
1586
|
|
|
1320
|
-
/** 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).
|
|
1587
|
+
/** A late-joiner pointer at an unsettled server-initiated request (tdd SS2.5.2, SS2.2.1). The full payloads arrive as re-issued server-to-client requests right after a `session/resume` response (tdd SS5.6); `session/read` never re-issues them (tdd SS2.5.5). The protocol defines two kind-discriminated entry shapes (`{kind: "approval", approvalId, viewCursor}` / `{kind: "userInput", userInputId, viewCursor}`). This type is one flat object with both ids optional, as for `ApprovalSubject` and `TurnInputPart`, because the v1 model names no object-variant union; the serialized JSON is the same, but the published schema also accepts `{"kind":"approval","userInputId":…}` and an entry carrying no id at all. Unlike `TurnInputPart.type`, `kind` here is an OPEN enum. */
|
|
1321
1588
|
export interface PendingRequestPointer {
|
|
1322
1589
|
/** Present on an `approval` entry. */
|
|
1323
1590
|
approvalId?: string;
|
|
@@ -1339,7 +1606,7 @@ export interface PendingUserInputPointer {
|
|
|
1339
1606
|
viewCursor: string;
|
|
1340
1607
|
}
|
|
1341
1608
|
|
|
1342
|
-
/** The server runtime's platform family
|
|
1609
|
+
/** The server runtime's platform family; may differ from the client's. Closed: the protocol fixes the value set, so widening it is a deliberate, gate-visible protocol change rather than a silent addition (a later `Closed`→`Open` flip is itself additive). */
|
|
1343
1610
|
export type PlatformFamily = "unix" | "windows";
|
|
1344
1611
|
|
|
1345
1612
|
/** The server's operating system (SS1.4.1). Closed, for the same reason as [`PlatformFamily`]. */
|
|
@@ -1589,7 +1856,7 @@ export interface RecapCompletedParams {
|
|
|
1589
1856
|
/** `recap/completed` failure reason (tdd SS3.28.2/SS3.28.8): post-ack failures fold to the single initial value. **Open**: later splits stay additive (#22785 E2). */
|
|
1590
1857
|
export type RecapFailureReason = "providerFailed" | (string & {});
|
|
1591
1858
|
|
|
1592
|
-
/** `recap/completed` outcome
|
|
1859
|
+
/** `recap/completed` outcome: the terminal vocabulary, in camelCase. **Open**: a server-produced result vocabulary. */
|
|
1593
1860
|
export type RecapOutcome = "completed" | "failed" | "cancelled" | "timedOut" | (string & {});
|
|
1594
1861
|
|
|
1595
1862
|
/** `recap/request` params (tdd SS3.28.1): the session plus the client-minted UUIDv7 retry id. No other param; unknown fields are `invalidParams`. */
|
|
@@ -1616,6 +1883,28 @@ export interface RecordPosition {
|
|
|
1616
1883
|
sequence: number;
|
|
1617
1884
|
}
|
|
1618
1885
|
|
|
1886
|
+
/** Proven effective-choice provenance, independently of input presence. */
|
|
1887
|
+
export type RecoveryEffectiveSource = "request" | "retained" | "legacyOmission" | "hostPolicy" | "unknown" | (string & {});
|
|
1888
|
+
|
|
1889
|
+
/** A requested construction choice; omission is distinct from explicit OFF. */
|
|
1890
|
+
export type RecoveryMode = "on" | "off";
|
|
1891
|
+
|
|
1892
|
+
/** One coherent producer snapshot; all members are required and non-null. */
|
|
1893
|
+
export interface RecoveryObservation {
|
|
1894
|
+
constructionId: string;
|
|
1895
|
+
effectiveMode: RecoveryObservedMode;
|
|
1896
|
+
effectiveSource: RecoveryEffectiveSource;
|
|
1897
|
+
qualification: RecoveryQualification;
|
|
1898
|
+
requestedMode: RecoveryObservedMode;
|
|
1899
|
+
sessionId: string;
|
|
1900
|
+
}
|
|
1901
|
+
|
|
1902
|
+
/** A proven mode or unknown; future strings cannot establish OFF. */
|
|
1903
|
+
export type RecoveryObservedMode = "on" | "off" | "unknown" | (string & {});
|
|
1904
|
+
|
|
1905
|
+
/** This construction's assessment, never an operation acceptance receipt. */
|
|
1906
|
+
export type RecoveryQualification = "qualified" | "unavailable" | "notRequired" | "unknown" | (string & {});
|
|
1907
|
+
|
|
1619
1908
|
/** A request frame, either direction (SS1.2 §2.1). */
|
|
1620
1909
|
export interface Request {
|
|
1621
1910
|
/** Client-chosen id, unique among that client's in-flight requests. */
|
|
@@ -1664,7 +1953,7 @@ export interface ServerInfo {
|
|
|
1664
1953
|
|
|
1665
1954
|
/** The session object every lifecycle method returns or lists (tdd SS2.4). Additive-optional evolution applies: clients must ignore unknown fields. */
|
|
1666
1955
|
export interface Session {
|
|
1667
|
-
/** The `turnId` of the current foreground turn when `status` is `running`, and `null` when the session is idle (tdd SS2.4). **Required-nullable
|
|
1956
|
+
/** The `turnId` of the current foreground turn when `status` is `running`, and `null` when the session is idle (tdd SS2.4). **Required-nullable.** Every served `Session` carries the member: `null` when the session is idle or not loaded, the turn id when it is running. An optional-absent shape would publish it as plain `string` and reject every idle `Session` frame the host sends. */
|
|
1668
1957
|
activeTurnId: string | null;
|
|
1669
1958
|
/** The folded effective approval mode. **Additive-optional**: a Session object that omits it means the host has not folded a mode, which is why the index-derived `session/list` entry may legitimately omit it (tdd SS2.4, SS5.12). */
|
|
1670
1959
|
approvalMode?: EffectiveApprovalModeState;
|
|
@@ -1748,7 +2037,7 @@ export interface SessionBranchChangedParams {
|
|
|
1748
2037
|
workspaceRoot: string;
|
|
1749
2038
|
}
|
|
1750
2039
|
|
|
1751
|
-
/** `session/closed` params (tdd SS2.6.2; enrolled by #33065): a loaded session was unloaded from this host, broadcast to every initialized connection. After it, the session is `notLoaded`; the log remains on disk and `session/resume` reloads it. A crash emits nothing — only the
|
|
2040
|
+
/** `session/closed` params (tdd SS2.6.2; enrolled by #33065): a loaded session was unloaded from this host, broadcast to every initialized connection. After it, the session is `notLoaded`; the log remains on disk and `session/resume` reloads it. A crash emits nothing — only the orderly unload paths do (idle unload, host shutdown and a released `session/leave`), and each writes the durable `SessionEnd` record first. */
|
|
1752
2041
|
export interface SessionClosedParams {
|
|
1753
2042
|
/** Which orderly unload path fired. */
|
|
1754
2043
|
reason: SessionClosedReason;
|
|
@@ -1759,7 +2048,7 @@ export interface SessionClosedParams {
|
|
|
1759
2048
|
}
|
|
1760
2049
|
|
|
1761
2050
|
/** The SS2.6.2 closed-reason vocabulary. Server-produced and published OPEN by owner ruling — the #33065 menu-B pick (PR #33201 comment 5638727249, recorded in the enrollment decision record), which settles that this notification reason enum publishes open rather than resting on E2's result-vocabulary rule by analogy. A crash is deliberately not a reason, because a crash emits no notification at all. */
|
|
1762
|
-
export type SessionClosedReason = "idle" | "hostShutdown" | (string & {});
|
|
2051
|
+
export type SessionClosedReason = "idle" | "hostShutdown" | "leave" | (string & {});
|
|
1763
2052
|
|
|
1764
2053
|
/** `session/compact` params (tdd SS3.7): manually compact the session's conversation context — the `/compact` gesture. Compaction runs asynchronously; the ack is admission only. */
|
|
1765
2054
|
export interface SessionCompactParams {
|
|
@@ -1781,7 +2070,7 @@ export interface SessionCompactResult {
|
|
|
1781
2070
|
status: CompactStatus;
|
|
1782
2071
|
}
|
|
1783
2072
|
|
|
1784
|
-
/** The open configuration extension object shared by `session/start` and `session/resume` (ADR 32760 D1). Unknown keys are ignored on the wire, never rejected
|
|
2073
|
+
/** The open configuration extension object shared by `session/start` and `session/resume` (ADR 32760 D1). Unknown keys are ignored on the wire, never rejected: the live decoder tolerates them, and no exported bundle carries `additionalProperties: false`. The Rust typed model's `deny_unknown_fields` is internal and never exported — the closedness export applies nowhere, and the `x-msp-closed` opt-in mechanism stays inert. Recognized `mcpServers` values are typed and validated before they leave the wire boundary. */
|
|
1785
2074
|
export interface SessionConfig {
|
|
1786
2075
|
/** Native MCP servers added only to this session runtime. */
|
|
1787
2076
|
mcpServers?: Record<string, SessionMcpServerConfig>;
|
|
@@ -1844,6 +2133,8 @@ export interface SessionGoalChangedParams {
|
|
|
1844
2133
|
|
|
1845
2134
|
/** The `history` envelope shared by `session/resume`, `session/fork`, and `session/read` (tdd SS2.5.2). */
|
|
1846
2135
|
export interface SessionHistory {
|
|
2136
|
+
/** The checkpoint-prune boundary (spec 13929 amendment FR-50042-1): rows for served items at-or-before `through_item_id` in served order predate the selected checkpoint. Additive-optional; absence is a non-assertion (ADR 50042 D6). */
|
|
2137
|
+
checkpointBoundary?: CheckpointBoundary;
|
|
1847
2138
|
/** The full folded item array when `mode` is `inline`; `null` otherwise. */
|
|
1848
2139
|
items: Item[] | null;
|
|
1849
2140
|
/** What was actually served — never what was asked for (tdd SS2.5.2). */
|
|
@@ -1857,6 +2148,44 @@ export interface SessionHistory {
|
|
|
1857
2148
|
/** What kind of session this is (spec 42713 FR-001/FR-005, ADR 42713 D1/D4). **Open**: a new kind is additive evolution, and a client MUST render an unknown value as an unknown-but-present kind rather than rejecting the row. Both v1 values are terms the tree already uses — the child log directory is `subagent` and `ItemKind` already carries a `subagent` variant — so no new vocabulary is minted. */
|
|
1858
2149
|
export type SessionKind = "root" | "subagent" | (string & {});
|
|
1859
2150
|
|
|
2151
|
+
/** Params of the protected, non-view leave terminal notification. */
|
|
2152
|
+
export interface SessionLeaveCompletedParams {
|
|
2153
|
+
/** The leave command's id, matching the `session/leave` request. */
|
|
2154
|
+
commandId: string;
|
|
2155
|
+
/** How the leave ended: `released` or `failed`. The set is open, so newer hosts may add outcomes. */
|
|
2156
|
+
outcome: SessionLeaveOutcome;
|
|
2157
|
+
/** Why the leave failed. Present when `outcome` is `failed`. */
|
|
2158
|
+
reason?: SessionLeaveFailureReason;
|
|
2159
|
+
/** The session the leave was for. */
|
|
2160
|
+
sessionId: string;
|
|
2161
|
+
/** The session's view cursor at release: everything up to it was folded before the host let go. Present when `outcome` is `released`. */
|
|
2162
|
+
viewCursor?: string;
|
|
2163
|
+
}
|
|
2164
|
+
|
|
2165
|
+
/** Current producer failure reasons for `session/leaveCompleted`; receiver-open for additive future reasons. */
|
|
2166
|
+
export type SessionLeaveFailureReason = "timeout" | "responseUndelivered" | "persistenceFailed" | "runtimeFailed" | "abandoned" | (string & {});
|
|
2167
|
+
|
|
2168
|
+
/** Current producer outcomes for `session/leaveCompleted`; receiver-open. */
|
|
2169
|
+
export type SessionLeaveOutcome = "released" | "failed" | (string & {});
|
|
2170
|
+
|
|
2171
|
+
/** `session/leave` params (tdd SS2.15, ADR 31741 D2/D8). */
|
|
2172
|
+
export interface SessionLeaveParams {
|
|
2173
|
+
/** Client-minted UUIDv7 command identity. */
|
|
2174
|
+
commandId: string;
|
|
2175
|
+
/** The exact loaded session whose ownership is to be released. */
|
|
2176
|
+
sessionId: string;
|
|
2177
|
+
/** Explicitly cancel unfinished work before leaving. Omitted is `false`. */
|
|
2178
|
+
stop?: boolean;
|
|
2179
|
+
}
|
|
2180
|
+
|
|
2181
|
+
/** The admission-only `session/leave` result. */
|
|
2182
|
+
export interface SessionLeaveResult {
|
|
2183
|
+
/** The leave command's id. */
|
|
2184
|
+
commandId: string;
|
|
2185
|
+
/** The admission status, `accepted` once the leave is admitted. The final result arrives later as `session/leaveCompleted`. Sending the same leave command again returns `accepted` and re-pushes the recorded result if there is one, from the host that ran the leave (for as long as it runs, even after the release) or from a host that has the session loaded (after a host crash, `abandoned` among them). Any other host treats it as a fresh leave: a durable host that has not loaded the session refuses it with `sessionNotLoaded` until it is resumed there. */
|
|
2186
|
+
status: CommandAckStatus;
|
|
2187
|
+
}
|
|
2188
|
+
|
|
1860
2189
|
/** Exact branch selection (#42035 FR-42035-2). */
|
|
1861
2190
|
export interface SessionListBranchFilter {
|
|
1862
2191
|
/** 1–32 nonempty branch names, each 1–256 UTF-8 bytes, counted before deduplication; `null` selects sessions with no branch. */
|
|
@@ -1885,7 +2214,7 @@ export interface SessionListParams {
|
|
|
1885
2214
|
cursor?: string | null;
|
|
1886
2215
|
/** Optional structured selection applied inside the bounded index query before paging (#42035, spec 207 FR-42035-1). Present — including `{}` — makes a supporting server echo its canonical form as `appliedFilter`; omitted keeps the pre-#42035 behavior. */
|
|
1887
2216
|
filter?: SessionListFilter;
|
|
1888
|
-
/** Page size; default 50, max 200 — the
|
|
2217
|
+
/** Page size; default 50, max 200 — the schema publishes the cap. Maximum 200. */
|
|
1889
2218
|
limit?: number;
|
|
1890
2219
|
/** Only sessions with log activity after this RFC3339 instant. */
|
|
1891
2220
|
updatedAfter?: string;
|
|
@@ -1994,12 +2323,16 @@ export interface SessionReadParams {
|
|
|
1994
2323
|
|
|
1995
2324
|
/** `session/read` result (tdd SS2.5.5). The `viewCursor` is the fold head at read time — a point-in-time read, immediately stale if a foreign host is appending. */
|
|
1996
2325
|
export interface SessionReadResult {
|
|
2326
|
+
/** Same member as `session/resume` (tdd SS2.5.5, ADR 50074 D2). */
|
|
2327
|
+
blockedPrompt?: BlockedPrompt;
|
|
1997
2328
|
/** The served history. */
|
|
1998
2329
|
history: SessionHistory;
|
|
1999
2330
|
/** Same member as `session/resume` (tdd SS2.5.5, ADR 36635 D2). */
|
|
2000
2331
|
lastTurn?: LastTurn;
|
|
2001
2332
|
/** 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). */
|
|
2002
2333
|
pendingRequests: PendingRequestPointer[];
|
|
2334
|
+
/** Current local construction only; never inferred from retained history. Absence establishes neither a choice nor supported recovery. */
|
|
2335
|
+
recoveryObservation?: RecoveryObservation;
|
|
2003
2336
|
/** The session as folded point-in-time. */
|
|
2004
2337
|
session: Session;
|
|
2005
2338
|
/** The fold head at read time. */
|
|
@@ -2008,7 +2341,7 @@ export interface SessionReadResult {
|
|
|
2008
2341
|
|
|
2009
2342
|
/** `session/reasoningEffortChanged` params (tdd SS4.6.9, ADR 31255 D1): a durable reasoning-effort reconfigure record landed (tdd SS3.21). Replace wholesale, latest wins; the snapshot carries the latest value (SS4.9.1). */
|
|
2010
2343
|
export interface SessionReasoningEffortChangedParams {
|
|
2011
|
-
/** The new session default: the closed eight-string tier vocabulary
|
|
2344
|
+
/** The new session default: the same closed eight-string tier vocabulary as `turn/start`. */
|
|
2012
2345
|
reasoningEffort: ReasoningEffort;
|
|
2013
2346
|
/** The owning session. */
|
|
2014
2347
|
sessionId: string;
|
|
@@ -2046,7 +2379,7 @@ export interface SessionResumeParams {
|
|
|
2046
2379
|
commandId: string;
|
|
2047
2380
|
/** The same open construction-time extension object as `session/start`. */
|
|
2048
2381
|
config?: SessionConfig;
|
|
2049
|
-
/** A view cursor previously observed by this client — or an observed `summarizedThrough` compaction anchor
|
|
2382
|
+
/** A view cursor previously observed by this client — or an observed `summarizedThrough` compaction anchor. When it names an event the server still holds, the server returns only the suffix and `history.mode` is `none`. A cursor the server minted that names no event yet, such as the empty start cursor of a session that had no events, is treated as no cursor: the server serves what a resume without a cursor would. A cursor older than the earliest event the server still holds gets a snapshot, or `-32040` `viewTruncated` when none fits. A cursor this session's view never minted is refused with `-32011` `notFound`, reason `missingAnchor`, and a compaction anchor naming a boundary the server has pruned is refused with `-32042` `boundaryPruned`. Omitted and explicit `null` both mean "no cursor". */
|
|
2050
2383
|
cursor?: string | null;
|
|
2051
2384
|
/** Return only session metadata and live resume state; page history separately with `view/page`. Default `false` (tdd SS2.5.2). */
|
|
2052
2385
|
excludeItems?: boolean;
|
|
@@ -2054,12 +2387,16 @@ export interface SessionResumeParams {
|
|
|
2054
2387
|
history?: HistoryPreference;
|
|
2055
2388
|
/** 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). */
|
|
2056
2389
|
permissionProfile?: string;
|
|
2390
|
+
/** Cold-resume replacement choice; omission preserves the retained choice. A warm attach rejects a different or unestablished choice as invalidParams. Explicit null is invalid. */
|
|
2391
|
+
recoveryMode?: RecoveryMode;
|
|
2057
2392
|
/** The session to load. */
|
|
2058
2393
|
sessionId: string;
|
|
2059
2394
|
}
|
|
2060
2395
|
|
|
2061
2396
|
/** `session/resume` result (tdd SS2.5.2). */
|
|
2062
2397
|
export interface SessionResumeResult {
|
|
2398
|
+
/** The recallable blocked prompt's refill text (ADR 50074 D2). **Additive-optional**; absence means no blocked prompt to recall (an unblocked session, or a pre-feature host). Data only, never a rendered row: clients seed cold recall from it (C-p refills `text`) and MUST NOT display it as history. */
|
|
2399
|
+
blockedPrompt?: BlockedPrompt;
|
|
2063
2400
|
/** The served history. */
|
|
2064
2401
|
history: SessionHistory;
|
|
2065
2402
|
/** How the last folded turn ended (tdd SS2.5.2, ADR 36635 D2). **Additive-optional**; absence is a non-assertion. */
|
|
@@ -2156,7 +2493,7 @@ export interface SessionStartParams {
|
|
|
2156
2493
|
approvalMode?: ApprovalMode | null;
|
|
2157
2494
|
/** The SS2.5 idempotency handle (UUIDv7). Required; the server never mints one. */
|
|
2158
2495
|
commandId: string;
|
|
2159
|
-
/** Reserved for per-session overrides
|
|
2496
|
+
/** Reserved for future per-session overrides; only its `mcpServers` member is admitted. */
|
|
2160
2497
|
config?: SessionConfig;
|
|
2161
2498
|
/** Initial model; server default when omitted. */
|
|
2162
2499
|
modelId?: string;
|
|
@@ -2164,6 +2501,8 @@ export interface SessionStartParams {
|
|
|
2164
2501
|
permissionProfile?: string;
|
|
2165
2502
|
/** Initial provider routing; server default when omitted or explicit `null` — both spellings select the default (#23468). */
|
|
2166
2503
|
providerId?: string | null;
|
|
2504
|
+
/** Recovery choice for this construction; omission keeps legacy behavior. Explicit null is invalid. */
|
|
2505
|
+
recoveryMode?: RecoveryMode;
|
|
2167
2506
|
/** Exact identity for this new root session. When omitted the server mints a UUIDv7. This field never selects an existing session: a retained or reserved id is rejected `commandRejected` with reason `session_id_conflict` (tdd SS2.5.1). */
|
|
2168
2507
|
sessionId?: string;
|
|
2169
2508
|
/** Absolute path, folded into the first metadata record. */
|
|
@@ -2381,6 +2720,9 @@ export interface SkillImportResult {
|
|
|
2381
2720
|
/** `skill/import` foreign ecosystem (tdd SS3.30.2). **Closed**: a client-selected write vocabulary (ADR 45433 D2) — a write must fail an ecosystem the host does not implement rather than import from an unknown dir. The host resolves its own foreign dir (the `foreign_skills_sources` derivation); no client paths cross the wire. */
|
|
2382
2721
|
export type SkillImportSource = "claude" | "codex";
|
|
2383
2722
|
|
|
2723
|
+
/** A `skill` input part's picked-copy source (tdd SS3.22.3; ADR 32471 D12): the D2 catalog-row `source` enum values, sent by the TUI on every skill submit so the host resolves the exact `(selector, source)` row. **Closed**: a client-selected write vocabulary (ADR 45433 D2) — an unknown value is `invalidParams`, never a fall-through to the bare row. Contrast the open read-side [`SkillSource`]. */
|
|
2724
|
+
export type SkillInvocationSource = "bundled" | "user" | "project" | "plugin";
|
|
2725
|
+
|
|
2384
2726
|
/** `skill/list` params (tdd SS3.22.1, SS3.30.3). Per-session because skill scope follows the session's workspace and plugin state. */
|
|
2385
2727
|
export interface SkillListParams {
|
|
2386
2728
|
/** The target session. */
|
|
@@ -2434,7 +2776,7 @@ export interface SnapshotAnchor {
|
|
|
2434
2776
|
summarizedThrough: string;
|
|
2435
2777
|
}
|
|
2436
2778
|
|
|
2437
|
-
/** 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.
|
|
2779
|
+
/** The complete folded view at the snapshot cursor (tdd SS4.9.1). Additive-optional evolution applies exactly as everywhere else; unknown members MUST be ignored, and preserved if re-serialized. */
|
|
2438
2780
|
export interface SnapshotState {
|
|
2439
2781
|
/** The running foreground turn; `null` when none is running. */
|
|
2440
2782
|
activeTurn: TurnRef | null;
|
|
@@ -2442,7 +2784,7 @@ export interface SnapshotState {
|
|
|
2442
2784
|
approvalMode: EffectiveApprovalModeState;
|
|
2443
2785
|
/** Latest branch observation; `null` when no fact has landed. */
|
|
2444
2786
|
branch: BranchState | null;
|
|
2445
|
-
/** The latest `(windowTokens, usedTokens, pressure)` triple.
|
|
2787
|
+
/** The latest `(windowTokens, usedTokens, pressure)` triple. The protocol allows "`null`/absent" and its worked example OMITS the member; the binary omits it too, so this is the absent arm — the four siblings above are present-null in the same frame. A member is published as one or the other, never both. */
|
|
2446
2788
|
contextUsage?: ContextUsage;
|
|
2447
2789
|
/** Latest effective model; `null` when no fact has landed. */
|
|
2448
2790
|
effectiveModel: EffectiveModel | null;
|
|
@@ -2582,6 +2924,8 @@ export interface SubagentOwnerReasonParams {
|
|
|
2582
2924
|
export interface SubagentResult {
|
|
2583
2925
|
/** Artifact references, verbatim. */
|
|
2584
2926
|
artifactRefs: string[];
|
|
2927
|
+
/** `true` once the parent consumed the result (the inbox join fact the gate-off drain arm folds into the `Finished` marker — tdd SS4.5.7). Absent otherwise; never cleared once set. Clients mint the `Finished` marker off this flag instead of re-deriving the join. */
|
|
2928
|
+
drained?: boolean;
|
|
2585
2929
|
/** Error kind, verbatim durable vocabulary, when the child failed. */
|
|
2586
2930
|
errorKind?: string;
|
|
2587
2931
|
/** Evidence references, verbatim. */
|
|
@@ -2664,10 +3008,17 @@ export interface TaskCommandResult {
|
|
|
2664
3008
|
taskId: string;
|
|
2665
3009
|
}
|
|
2666
3010
|
|
|
2667
|
-
/**
|
|
3011
|
+
/** A task row's execution mode (tdd SS3.31, ADR 62268 D2). Open (server-produced result vocabulary, the #22785 enum-openness rule): clients MUST ignore unknown modes. */
|
|
3012
|
+
export type TaskExecutionMode = "foreground" | "background" | (string & {});
|
|
3013
|
+
|
|
3014
|
+
/** One task inventory row (tdd SS3.31). The row is the stable contract: `kind` and `status` stay open so a future state extends them without breaking clients. */
|
|
2668
3015
|
export interface TaskListEntry {
|
|
2669
3016
|
/** Who backgrounded the task, mirroring the item field. **Additive-optional**: absent on pre-split records and registry-only rows, never inferred. */
|
|
2670
3017
|
backgroundInitiator?: BackgroundInitiator;
|
|
3018
|
+
/** The raw command text: the joined `toolCall` item's `command` argument verbatim (ADR 62268 D2). **Additive-optional**: omitted when the row has no item or the item carries no command. Monitors join raw — clients redact (INV-17544-6). */
|
|
3019
|
+
command?: string;
|
|
3020
|
+
/** `"foreground" | "background"` (ADR 62268 D2). **Additive-optional**: absent means `"background"` (only pre-change hosts omit it, and those list background rows only); never guessed. */
|
|
3021
|
+
executionMode?: TaskExecutionMode;
|
|
2671
3022
|
/** What the workload is: `"tool"` or `"tool.*"` for item rows (the recorded kind when the registry records one, else `"tool"`); the recorded registry kind string verbatim for registry-only rows. Open vocabulary — clients MUST ignore unknown kinds. A `String`, not an enum: registry kind strings are unbounded. */
|
|
2672
3023
|
kind: string;
|
|
2673
3024
|
/** The host-known task start, RFC3339. **Additive-optional**: omitted, never guessed, when the host does not know it. */
|
|
@@ -2686,9 +3037,9 @@ export interface TaskListParams {
|
|
|
2686
3037
|
sessionId: string;
|
|
2687
3038
|
}
|
|
2688
3039
|
|
|
2689
|
-
/** `task/list` result (tdd SS3.31): one row per
|
|
3040
|
+
/** `task/list` result (tdd SS3.31): one row per live workload, background and foreground (ADR 62268 D1), oldest first; empty when nothing is running. */
|
|
2690
3041
|
export interface TaskListResult {
|
|
2691
|
-
/** The session's live
|
|
3042
|
+
/** The session's live task rows. */
|
|
2692
3043
|
tasks: TaskListEntry[];
|
|
2693
3044
|
}
|
|
2694
3045
|
|
|
@@ -2859,7 +3210,7 @@ export interface TurnForegroundCompletedParams {
|
|
|
2859
3210
|
viewCursor: string;
|
|
2860
3211
|
}
|
|
2861
3212
|
|
|
2862
|
-
/** 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
|
|
3213
|
+
/** One ordered content part of a turn submission (tdd SS3.2). File mentions are text, not a part type: write `@relative/path` in a text part. A structured `mention` part is reserved and currently rejected, and an unknown part type is `invalidParams` (tdd SS3.1.2, SS3.2) — which is what closes [`TurnInputPartType`]. Modelled as a discriminated flat object rather than a Rust `enum`, the convention [`crate::view::approval::ApprovalSubject`] already established for a wire union in this crate: the v1 schema model names no object-variant union shape and fails closed on one. The serialized JSON is the same either way; what a flat object cannot express is "`mediaType` is required exactly when `type` is `image`". `height` may only appear together with `width`. `width` may only appear together with `height`. */
|
|
2863
3214
|
export interface TurnInputPart {
|
|
2864
3215
|
/** Free-text skill arguments, optional on a `skill` part — the wire twin of what the TUI accepts after the shortcut token (tdd SS3.22.3). */
|
|
2865
3216
|
arguments?: string;
|
|
@@ -2871,13 +3222,15 @@ export interface TurnInputPart {
|
|
|
2871
3222
|
mediaType?: string;
|
|
2872
3223
|
/** The skill to invoke, required on a `skill` part (tdd SS3.2, SS3.22.3; ADR 32471 D4): a bare or plugin-qualified shortcut token from `skill/list`. The HOST resolves and expands; an unknown selector is the typed `-32032 skillNotFound` request error. */
|
|
2873
3224
|
selector?: string;
|
|
3225
|
+
/** The picked copy's source, optional on a `skill` part: one of the catalog rows' `source` values. When present the host resolves the exact `(selector, source)` row; when absent it resolves the selector, bare or plugin-qualified, against the session's skill catalog, as the TUI shortcut does. Closed: an unknown value is `invalidParams`, never a fall-through. */
|
|
3226
|
+
source?: SkillInvocationSource;
|
|
2874
3227
|
/** User prompt text, on a `text` part. Multiple text parts are joined in order into the turn's prompt. */
|
|
2875
3228
|
text?: string;
|
|
2876
3229
|
/** The part type. */
|
|
2877
3230
|
type: TurnInputPartType;
|
|
2878
3231
|
/** The upload receipt, required on a `video` part (tdd SS3.2, SS3.33; ADR 45443 D5): the client-minted id `media/upload` echoed. */
|
|
2879
3232
|
uploadId?: string;
|
|
2880
|
-
/** Pixel width; must be provided together with `height` or not at all
|
|
3233
|
+
/** Pixel width; must be provided together with `height` or not at all. Published as a `dependentRequired` pair. */
|
|
2881
3234
|
width?: number;
|
|
2882
3235
|
}
|
|
2883
3236
|
|
|
@@ -2940,7 +3293,7 @@ export interface TurnRef {
|
|
|
2940
3293
|
displayText?: string;
|
|
2941
3294
|
/** `queuedTurns[]` only: set when `displayText` was cut to the committed-surface budget, mirroring `userMessage.truncated` (tdd SS4.5.2). Absent unless `true`. */
|
|
2942
3295
|
truncated?: boolean;
|
|
2943
|
-
/** The turn's id,
|
|
3296
|
+
/** The turn's id, minted at admission. */
|
|
2944
3297
|
turnId: string;
|
|
2945
3298
|
}
|
|
2946
3299
|
|
|
@@ -3106,7 +3459,7 @@ export interface TurnUserShell {
|
|
|
3106
3459
|
commandText: string;
|
|
3107
3460
|
}
|
|
3108
3461
|
|
|
3109
|
-
/** One element of a `view/page` result's `events` array: an **unframed view notification**
|
|
3462
|
+
/** One element of a `view/page` result's `events` array: an **unframed view notification** — the nested pair `{"method", "params"}`, which is the live notification minus `jsonrpc` and `emittedAtMs`, with nothing lifted out of `params` and nothing spliced into it. `view/page` and `muse exec --json` share this one definition, so the two surfaces cannot drift. */
|
|
3110
3463
|
export interface UnframedViewNotification {
|
|
3111
3464
|
/** The event type — the live notification's method name, retained because the type lives only in the notification name and would otherwise be lost (tdd SS4.2.1). */
|
|
3112
3465
|
method: string;
|
|
@@ -3114,7 +3467,7 @@ export interface UnframedViewNotification {
|
|
|
3114
3467
|
params: UnframedViewNotificationParams;
|
|
3115
3468
|
}
|
|
3116
3469
|
|
|
3117
|
-
/** The `params` of an unframed view notification (tdd SS4.2.1, SS4.2). Declares the
|
|
3470
|
+
/** The `params` of an unframed view notification (tdd SS4.2.1, SS4.2). Declares the base members every view notification carries, and stays **open** for the event-specific fields each event type adds. The v1 schema model names no method-correlated union (the `events` element's `params` arm is selected by its sibling `method`), so the per-event arms cannot be expressed here without one, and an uncorrelated union of them could reject a real page element, which a published schema must not do. `sourceRange` is required here and not optional: `view/page` serves durable-sourced events only (tdd SS4.7.3), and durable-sourced is *defined* as carrying a `sourceRange` — the SS4.2 ephemeral-sourced exemption applies to `item/delta`, which `view/page` never replays. */
|
|
3118
3471
|
export interface UnframedViewNotificationParams {
|
|
3119
3472
|
/** The owning session (tdd SS4.2). */
|
|
3120
3473
|
sessionId: string;
|
|
@@ -3133,15 +3486,21 @@ export interface UsageReadResult {
|
|
|
3133
3486
|
usage?: SubscriptionUsage;
|
|
3134
3487
|
}
|
|
3135
3488
|
|
|
3489
|
+
/** One question's answer, as sent in `userInput/answer` or `userInput/interrupt` and as recorded in `userInput/settled`. */
|
|
3136
3490
|
export interface UserInputAnswer {
|
|
3491
|
+
/** A free-form answer, at most 500 characters. */
|
|
3137
3492
|
freeText?: string;
|
|
3493
|
+
/** An optional comment the user adds to the answer, at most 500 characters. */
|
|
3138
3494
|
note?: string;
|
|
3495
|
+
/** The `id` of the question this answers. */
|
|
3139
3496
|
questionId: string;
|
|
3497
|
+
/** The label of the chosen option, for a `single` question. */
|
|
3140
3498
|
selectedLabel?: string;
|
|
3499
|
+
/** The labels of the chosen options for a `multiple` question, within its selection bounds; omitted when empty. */
|
|
3141
3500
|
selectedLabels?: string[];
|
|
3142
3501
|
}
|
|
3143
3502
|
|
|
3144
|
-
/** `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
|
|
3503
|
+
/** `userInput/answer` params (tdd SS5.10.2): answer every question. Each answer carries `questionId` then exactly one of `selectedLabel` (single mode), `selectedLabels` (multiple mode, within min/max bounds), or `freeText` (<=500 chars); plus an optional `note` (<=500). Answers that do not match the prompt fail -32057 `userInputAnswerInvalid`. Image `attachments` are a **reserved** field in v1, rejected if sent, because the blob-upload path they reference is also reserved. */
|
|
3145
3504
|
export interface UserInputAnswerParams {
|
|
3146
3505
|
/** One entry per question. */
|
|
3147
3506
|
answers: UserInputAnswer[];
|
|
@@ -3185,8 +3544,11 @@ export interface UserInputCancelResult {
|
|
|
3185
3544
|
userInputId: string;
|
|
3186
3545
|
}
|
|
3187
3546
|
|
|
3547
|
+
/** A free-form reply the user gives instead of choosing from the options; the model reads it and decides again. */
|
|
3188
3548
|
export interface UserInputClarification {
|
|
3549
|
+
/** The clarification text, at most 500 characters. */
|
|
3189
3550
|
content: string;
|
|
3551
|
+
/** The content format. `text` is the only value today, and more may be added. */
|
|
3190
3552
|
format: string;
|
|
3191
3553
|
}
|
|
3192
3554
|
|
|
@@ -3242,67 +3604,107 @@ export interface UserInputInterruptResult {
|
|
|
3242
3604
|
userInputId: string;
|
|
3243
3605
|
}
|
|
3244
3606
|
|
|
3607
|
+
/** One option offered for a question. */
|
|
3245
3608
|
export interface UserInputOption {
|
|
3609
|
+
/** An optional longer explanation of the option, at most 240 characters. */
|
|
3246
3610
|
description?: string;
|
|
3611
|
+
/** The option's text, at most 80 characters and unique within its question; an answer selects the option by this exact label. */
|
|
3247
3612
|
label: string;
|
|
3613
|
+
/** An optional rich preview of the option, present only on single-select questions. */
|
|
3248
3614
|
preview?: UserInputOptionPreview;
|
|
3249
3615
|
}
|
|
3250
3616
|
|
|
3617
|
+
/** Rich content a client can show for an option. Only single-select questions carry previews. */
|
|
3251
3618
|
export interface UserInputOptionPreview {
|
|
3619
|
+
/** The preview content in that format, at most 2000 characters. */
|
|
3252
3620
|
content: string;
|
|
3621
|
+
/** The content format, for example `markdown`. */
|
|
3253
3622
|
format: string;
|
|
3254
3623
|
}
|
|
3255
3624
|
|
|
3625
|
+
/** How a user-input prompt settled. More values may be added, so handle values you do not recognize. */
|
|
3256
3626
|
export type UserInputOutcome = "answered" | "cancelled" | "interrupted" | "clarified" | "timedOut" | "aborted" | (string & {});
|
|
3257
3627
|
|
|
3628
|
+
/** One question in a user-input prompt. */
|
|
3258
3629
|
export interface UserInputQuestion {
|
|
3630
|
+
/** A short title for the question, at most 12 characters. */
|
|
3259
3631
|
header: string;
|
|
3632
|
+
/** The question's id, unique within the prompt and at most 64 characters. An answer names it in `questionId`. */
|
|
3260
3633
|
id: string;
|
|
3634
|
+
/** The options offered, two or three, in order. */
|
|
3261
3635
|
options: UserInputOption[];
|
|
3636
|
+
/** The full question text to show the user. */
|
|
3262
3637
|
question: string;
|
|
3638
|
+
/** Whether the user picks one option or several. */
|
|
3263
3639
|
selection: UserInputSelection;
|
|
3264
3640
|
}
|
|
3265
3641
|
|
|
3266
3642
|
/** Full params shared by `userInput/request` and `userInput/requested`. */
|
|
3267
3643
|
export interface UserInputRequestParams {
|
|
3644
|
+
/** The auto-resolution time per question, in milliseconds: a prompt nobody engages with settles as `timedOut` after this value times the number of questions. */
|
|
3268
3645
|
autoResolutionMs?: number;
|
|
3646
|
+
/** The `toolCall` view item of the tool call waiting on this prompt. */
|
|
3269
3647
|
itemId: string;
|
|
3648
|
+
/** The questions to ask, one to three, in order. */
|
|
3270
3649
|
questions: UserInputQuestion[];
|
|
3650
|
+
/** The session that owns the prompt. */
|
|
3271
3651
|
sessionId: string;
|
|
3652
|
+
/** The stored records this prompt was folded from, when sent: an opaque token clients must not interpret. */
|
|
3272
3653
|
sourceRange?: SourceRange;
|
|
3654
|
+
/** The provider's id for the tool call that opened the prompt. */
|
|
3273
3655
|
toolCallId: string;
|
|
3656
|
+
/** The name of the tool that opened the prompt. */
|
|
3274
3657
|
toolName: string;
|
|
3658
|
+
/** The turn whose tool call is waiting on this prompt. */
|
|
3275
3659
|
turnId: string;
|
|
3660
|
+
/** The prompt's stable id. Pass it to `userInput/answer`, `userInput/cancel`, `userInput/clarify` and `userInput/interrupt`, and use it to match the later `userInput/settled`. */
|
|
3276
3661
|
userInputId: string;
|
|
3662
|
+
/** The cursor of the `userInput/requested` event for this prompt. A client that missed the request can read the same payload at this cursor with `view/page`. */
|
|
3277
3663
|
viewCursor: string;
|
|
3278
3664
|
}
|
|
3279
3665
|
|
|
3666
|
+
/** How many options the user may pick for a question. */
|
|
3280
3667
|
export interface UserInputSelection {
|
|
3668
|
+
/** The most options the user may pick. Sent only in `multiple` mode; when absent the maximum is the number of options. */
|
|
3281
3669
|
maxSelections?: number;
|
|
3670
|
+
/** The minimum selection count for a `multiple` answer. Sent only in `multiple` mode; when absent the minimum is 1. */
|
|
3282
3671
|
minSelections?: number;
|
|
3672
|
+
/** `single` or `multiple`: whether an answer selects one option or several. */
|
|
3283
3673
|
mode: UserInputSelectionMode;
|
|
3284
3674
|
}
|
|
3285
3675
|
|
|
3676
|
+
/** Whether a question takes one option or several. */
|
|
3286
3677
|
export type UserInputSelectionMode = "single" | "multiple";
|
|
3287
3678
|
|
|
3288
3679
|
/** `userInput/settled` params: the first durable prompt settlement. */
|
|
3289
3680
|
export interface UserInputSettledParams {
|
|
3681
|
+
/** The recorded answers: one per question for `answered`, any confirmed partial answers for `interrupted`, and empty for every other outcome. */
|
|
3290
3682
|
answers: UserInputAnswer[];
|
|
3683
|
+
/** The user's free-form clarification when the outcome is `clarified`; `null` otherwise. */
|
|
3291
3684
|
clarification: UserInputClarification | null;
|
|
3292
3685
|
/** The decision time as RFC3339, projected from the durable settlement record's own stamp (ADR 45450 D3, ruling 2026-10-01): always present on the wire (schema-required, `null`-able); decoders still tolerate its absence (`default`, never skipped — SS5.10.3 keeps every member present), and current hosts always populate it. */
|
|
3293
3686
|
decidedAt: string | null;
|
|
3687
|
+
/** The `commandId` of the client command that settled the prompt; `null` when no command did, for example after a timeout or an abort. */
|
|
3294
3688
|
decidedByCommandId: string | null;
|
|
3689
|
+
/** How the prompt ended. */
|
|
3295
3690
|
outcome: UserInputOutcome;
|
|
3691
|
+
/** The reason, when one applies: the optional reason given with a cancel, or why an `aborted` prompt was closed; `null` otherwise. */
|
|
3296
3692
|
reason: string | null;
|
|
3693
|
+
/** The session that owns the prompt. */
|
|
3297
3694
|
sessionId: string;
|
|
3695
|
+
/** The stored records this event was folded from: an opaque token clients must not interpret. */
|
|
3298
3696
|
sourceRange: SourceRange;
|
|
3697
|
+
/** The prompt that settled. Accept a settlement even for a prompt whose request you never saw. */
|
|
3299
3698
|
userInputId: string;
|
|
3699
|
+
/** This event's view cursor: opaque, and strictly increasing within the session. */
|
|
3300
3700
|
viewCursor: string;
|
|
3301
3701
|
}
|
|
3302
3702
|
|
|
3303
3703
|
/** Winning terminal returned to a late user-input command. */
|
|
3304
3704
|
export interface UserInputSettlementSummary {
|
|
3705
|
+
/** How the prompt settled, as a `userInput/settled` outcome value such as `answered` or `timedOut`. */
|
|
3305
3706
|
outcome: string;
|
|
3707
|
+
/** The view cursor of the `userInput/settled` event that recorded the settlement. */
|
|
3306
3708
|
viewCursor: string;
|
|
3307
3709
|
}
|
|
3308
3710
|
|
|
@@ -3319,10 +3721,10 @@ export interface ViewGapParams {
|
|
|
3319
3721
|
sessionId: string;
|
|
3320
3722
|
}
|
|
3321
3723
|
|
|
3322
|
-
/** The `view/page` request-mode anchor
|
|
3724
|
+
/** The `view/page` request-mode anchor. Declared **open**: the protocol spells it "open string enum, v1 value `latestCompaction`". */
|
|
3323
3725
|
export type ViewPageAnchor = "latestCompaction" | (string & {});
|
|
3324
3726
|
|
|
3325
|
-
/** The `view/page` paging direction
|
|
3727
|
+
/** The `view/page` paging direction. Closed: the protocol spells exactly two values and a third would change the paging contract. */
|
|
3326
3728
|
export type ViewPageDirection = "forward" | "backward";
|
|
3327
3729
|
|
|
3328
3730
|
/** `view/page` params (tdd SS4.7.3): cursor-paged reads of the session view. */
|
|
@@ -3333,7 +3735,7 @@ export interface ViewPageParams {
|
|
|
3333
3735
|
cursor?: string;
|
|
3334
3736
|
/** Paging direction; `forward` when omitted. */
|
|
3335
3737
|
direction?: ViewPageDirection;
|
|
3336
|
-
/** Maximum events to return, 1–1000. The server MAY return fewer
|
|
3738
|
+
/** Maximum events to return, 1–1000. The server MAY return fewer. The 1–1000 range is ratified and **published**: the model carries the bound and the bundle renders `minimum`/`maximum` instead of a bare `integer`. Range 1–1000 inclusive. */
|
|
3337
3739
|
limit: number;
|
|
3338
3740
|
/** The session to page. */
|
|
3339
3741
|
sessionId: string;
|
|
@@ -3491,9 +3893,9 @@ export interface WorkflowTokenBudget {
|
|
|
3491
3893
|
}
|
|
3492
3894
|
|
|
3493
3895
|
/** Every wire method in this schema (SS1.9 index). */
|
|
3494
|
-
export type MspMethod = "initialize" | "subagent/sendMessage" | "subagent/followupTask" | "subagent/interrupt" | "subagent/stop" | "subagent/resume" | "subagent/reopen" | "subagent/close" | "subagent/readResult" | "session/start" | "session/resume" | "session/fork" | "session/list" | "session/read" | "session/sideChat" | "turn/start" | "turn/steer" | "turn/interrupt" | "turn/cancel" | "turn/unqueue" | "session/compact" | "session/setModel" | "session/rename" | "session/setReasoningEffort" | "session/userShell" | "model/list" | "skill/list" | "skill/setActivation" | "skill/import" | "hook/list" | "plugin/list" | "plugin/install" | "plugin/marketplaceAdd" | "plugin/marketplaceUpdate" | "plugin/marketplaceRemove" | "task/background" | "task/stop" | "task/stopAll" | "task/list" | "goal/set" | "goal/edit" | "goal/clear" | "goal/pause" | "goal/resume" | "workflow/cancel" | "workflow/childControl" | "workflow/pause" | "workflow/resume" | "media/upload" | "view/subscribe" | "view/unsubscribe" | "view/page" | "item/readOutput" | "approval/decide" | "approval/listPending" | "session/setApprovalMode" | "userInput/answer" | "userInput/cancel" | "userInput/clarify" | "userInput/interrupt" | "usage/read" | "feedback/submit" | "recap/request" | "recap/cancel" | "computerUseSettings/read" | "computerUseSettings/update" | "computerUseSetup/read" | "computerUseSetup/start" | "computerUseSetup/check";
|
|
3896
|
+
export type MspMethod = "initialize" | "subagent/sendMessage" | "subagent/followupTask" | "subagent/interrupt" | "subagent/stop" | "subagent/resume" | "subagent/reopen" | "subagent/close" | "subagent/readResult" | "session/start" | "session/resume" | "session/fork" | "session/leave" | "session/list" | "session/read" | "session/sideChat" | "turn/start" | "turn/steer" | "turn/interrupt" | "turn/cancel" | "turn/unqueue" | "session/compact" | "session/setModel" | "session/rename" | "session/setReasoningEffort" | "session/userShell" | "model/list" | "skill/list" | "skill/setActivation" | "skill/import" | "hook/list" | "plugin/list" | "plugin/install" | "plugin/marketplaceAdd" | "plugin/marketplaceUpdate" | "plugin/marketplaceRemove" | "task/background" | "task/stop" | "task/stopAll" | "task/list" | "goal/set" | "goal/edit" | "goal/clear" | "goal/pause" | "goal/resume" | "workflow/cancel" | "workflow/childControl" | "workflow/pause" | "workflow/resume" | "media/upload" | "view/subscribe" | "view/unsubscribe" | "view/page" | "item/readOutput" | "approval/decide" | "approval/listPending" | "session/setApprovalMode" | "userInput/answer" | "userInput/cancel" | "userInput/clarify" | "userInput/interrupt" | "usage/read" | "feedback/submit" | "recap/request" | "recap/cancel" | "computerUseSettings/read" | "computerUseSettings/update" | "computerUseSetup/read" | "computerUseSetup/start" | "computerUseSetup/check";
|
|
3495
3897
|
/** Every wire notification in this schema (SS1.9 index). */
|
|
3496
|
-
export type MspNotification = "initialized" | "session/started" | "session/closed" | "skill/changed" | "turn/started" | "turn/completed" | "turn/retracted" | "turn/retryScheduled" | "turn/modelRetryScheduled" | "turn/unqueued" | "turn/foregroundCompleted" | "item/started" | "item/updated" | "item/delta" | "item/completed" | "view/gap" | "approval/requested" | "approval/updated" | "approval/reviewing" | "approval/resolved" | "userInput/requested" | "userInput/settled" | "userInput/engaged" | "session/modelChanged" | "session/reasoningEffortChanged" | "session/statusChanged" | "session/goalChanged" | "session/todoListChanged" | "session/branchChanged" | "session/tokenUsage" | "session/contextUsage" | "session/approvalModeChanged" | "recap/completed" | "session/modelRouteUnserved" | "session/nameChanged" | "session/viewHealthChanged" | "session/listChanged" | "usage/changed" | "computerUseSetup/changed" | "plugin/changed" | "plugin/marketplaceChanged";
|
|
3898
|
+
export type MspNotification = "initialized" | "session/started" | "session/closed" | "session/leaveCompleted" | "skill/changed" | "turn/started" | "turn/completed" | "turn/retracted" | "turn/retryScheduled" | "turn/modelRetryScheduled" | "turn/unqueued" | "turn/foregroundCompleted" | "item/started" | "item/updated" | "item/delta" | "item/completed" | "view/gap" | "approval/requested" | "approval/updated" | "approval/reviewing" | "approval/resolved" | "userInput/requested" | "userInput/settled" | "userInput/engaged" | "session/modelChanged" | "session/reasoningEffortChanged" | "session/statusChanged" | "session/goalChanged" | "session/todoListChanged" | "session/branchChanged" | "session/tokenUsage" | "session/contextUsage" | "session/approvalModeChanged" | "recap/completed" | "session/modelRouteUnserved" | "session/nameChanged" | "session/viewHealthChanged" | "session/listChanged" | "usage/changed" | "computerUseSetup/changed" | "plugin/changed" | "plugin/marketplaceChanged" | "monitor/inboxItemAdmitted" | "monitor/inboxItemDrained" | "monitor/inboxItemVoided";
|
|
3497
3899
|
/** Every server-initiated wire request in this schema (SS5.3/SS5.10.1 index). */
|
|
3498
3900
|
export type MspServerRequest = "approval/request" | "userInput/request";
|
|
3499
3901
|
/** Every error `data.kind` in this schema's error table (SS1.6) — each code's primary kind plus its override kinds. */
|