@muse-code/sdk 1.4.11 → 1.4.12
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/src/facade/approval.js +6 -0
- package/dist/src/fingerprint.d.ts +1 -1
- package/dist/src/fingerprint.js +1 -1
- package/dist/src/msp.d.ts +293 -49
- package/package.json +1 -1
|
@@ -47,6 +47,7 @@ const REFRESH_FROM_UPDATE = [
|
|
|
47
47
|
];
|
|
48
48
|
const REFRESH_FROM_REQUEST = [
|
|
49
49
|
"approvalId",
|
|
50
|
+
"cuaCardFacts",
|
|
50
51
|
"itemId",
|
|
51
52
|
"judgeEscalated",
|
|
52
53
|
"protectedWrite",
|
|
@@ -184,6 +185,11 @@ export class ApprovalRouter {
|
|
|
184
185
|
// parent's own approvals by contract (#36182 `skip_serializing_if`).
|
|
185
186
|
if (params.subagentOrigin !== undefined)
|
|
186
187
|
refreshed.subagentOrigin = params.subagentOrigin;
|
|
188
|
+
// A Computer Use card's facts belong to the call, so they stay with the
|
|
189
|
+
// retained request across stages; omitted when absent.
|
|
190
|
+
if (requested.cuaCardFacts !== undefined) {
|
|
191
|
+
refreshed.cuaCardFacts = requested.cuaCardFacts;
|
|
192
|
+
}
|
|
187
193
|
const acked = this.#inFlight.get(requested.approvalId);
|
|
188
194
|
if (acked !== undefined)
|
|
189
195
|
return this.#afterAck(acked, refreshed);
|
|
@@ -13,7 +13,7 @@
|
|
|
13
13
|
* (tdd SS1.4.1) — additive-optional evolution means an older SDK keeps
|
|
14
14
|
* working against a newer host.
|
|
15
15
|
*/
|
|
16
|
-
export declare const EXPECTED_SCHEMA_FINGERPRINT = "sha256:
|
|
16
|
+
export declare const EXPECTED_SCHEMA_FINGERPRINT = "sha256:cfdb6d2525601b9bac76584ccb0610ab3a5539b5e4f51141f079b99b39fcb4e0";
|
|
17
17
|
/**
|
|
18
18
|
* What a build-time mismatch MEANS, in the words a human needs at 2am.
|
|
19
19
|
*
|
package/dist/src/fingerprint.js
CHANGED
|
@@ -13,7 +13,7 @@
|
|
|
13
13
|
* (tdd SS1.4.1) — additive-optional evolution means an older SDK keeps
|
|
14
14
|
* working against a newer host.
|
|
15
15
|
*/
|
|
16
|
-
export const EXPECTED_SCHEMA_FINGERPRINT = "sha256:
|
|
16
|
+
export const EXPECTED_SCHEMA_FINGERPRINT = "sha256:cfdb6d2525601b9bac76584ccb0610ab3a5539b5e4f51141f079b99b39fcb4e0";
|
|
17
17
|
/**
|
|
18
18
|
* What a build-time mismatch MEANS, in the words a human needs at 2am.
|
|
19
19
|
*
|
package/dist/src/msp.d.ts
CHANGED
|
@@ -10,35 +10,100 @@
|
|
|
10
10
|
// Generated by tbh-protocol (spec 206) from the same schema model as
|
|
11
11
|
// the JSON Schema bundle (INV-017). Do not edit by hand.
|
|
12
12
|
|
|
13
|
+
/** The policy rule a decision created, in display form; the full rule is not included. */
|
|
13
14
|
export interface ApprovalAmendment {
|
|
15
|
+
/** How long the rule lasts: `session` or `localPersistent`. */
|
|
14
16
|
durability: ApprovalAmendmentDurability;
|
|
17
|
+
/** A human-readable preview of the rule, for display. */
|
|
15
18
|
rulePreview: string;
|
|
16
19
|
}
|
|
17
20
|
|
|
21
|
+
/** How long a rule created by an approval decision lasts. The set is open, so newer hosts may send other values. */
|
|
18
22
|
export type ApprovalAmendmentDurability = "session" | "localPersistent" | (string & {});
|
|
19
23
|
|
|
24
|
+
/** The change an `approval/updated` event reports. `kind` says what happened, and only the fields for that kind are present. */
|
|
20
25
|
export interface ApprovalChange {
|
|
26
|
+
/** The `choiceId` that satisfied the stage. Present only when `kind` is `stageResolved`. */
|
|
21
27
|
choiceId?: string;
|
|
28
|
+
/** The decision the chosen option applied to the stage. Present only when `kind` is `stageResolved`. */
|
|
22
29
|
decision?: ApprovalDecision;
|
|
30
|
+
/** A recovery detail: whether the action could run without a new decision. Present only when `kind` is `restartRecovered`. */
|
|
23
31
|
executable?: boolean;
|
|
32
|
+
/** What happened: for example `stageResolved` (a shell stage was satisfied), `policyPersistence` (saving a rule succeeded or failed), `reviewStarted` or `reviewCompleted` (the automated LLM judge started or finished reviewing), `restartRecovered` (a host restart recovered this approval: either the host first resolves it `abort` and a re-ask comes as a new approval with a new `approvalId`, or it stays pending under the same `approvalId` with refreshed choices) or `alreadyTerminal` (recovery found it already decided). The set is open, so newer hosts may add kinds. */
|
|
24
33
|
kind: string;
|
|
34
|
+
/** Why saving the policy rule failed, as human-readable text. Present only when `kind` is `policyPersistence` and `status` is `failed`. */
|
|
25
35
|
reason?: string;
|
|
36
|
+
/** A recovery detail: whether the command was re-parsed during recovery. Present only when `kind` is `restartRecovered`. */
|
|
26
37
|
reparsed?: boolean;
|
|
38
|
+
/** The stage requirement that was satisfied. Present only when `kind` is `stageResolved`. */
|
|
27
39
|
requirementId?: ApprovalRequirementRef;
|
|
40
|
+
/** Whether saving the policy rule succeeded or failed; present only when `kind` is `policyPersistence`. A failure does not undo the decision; only the saved rule is missing. */
|
|
28
41
|
status?: ApprovalPersistenceStatus;
|
|
29
42
|
}
|
|
30
43
|
|
|
44
|
+
/** One option the server offers for deciding an approval. Clients pick one and send its `choiceId` in `approval/decide`; they never build their own. */
|
|
31
45
|
export interface ApprovalChoice {
|
|
46
|
+
/** `true` when this choice takes optional `feedback` text in `approval/decide`, which reaches the model as guidance. Omitted when `false`. */
|
|
32
47
|
acceptsFeedback?: boolean;
|
|
48
|
+
/** The id to send as `choiceId` in `approval/decide`. The set of ids is open, so show `label` and do not base behavior on specific ids. */
|
|
33
49
|
choiceId: string;
|
|
50
|
+
/** The decision this choice applies, so a client can act on approve or reject without knowing choice ids. */
|
|
34
51
|
decision: ApprovalDecision;
|
|
52
|
+
/** The human-readable label to show for this choice. */
|
|
35
53
|
label: string;
|
|
54
|
+
/** A human-readable preview of what this choice grants, such as the policy rule it would create; show it exactly as given. */
|
|
36
55
|
rulePreview?: string;
|
|
56
|
+
/** The grant duration this choice declares: `once` (this request only), `session` (the rest of the session) or `localPersistent` (saved in the local policy store). */
|
|
37
57
|
scope: ApprovalChoiceScope;
|
|
38
58
|
}
|
|
39
59
|
|
|
60
|
+
/** How long a grant made by a choice lasts. The set is open, so newer hosts may send other values. */
|
|
40
61
|
export type ApprovalChoiceScope = "once" | "session" | "localPersistent" | (string & {});
|
|
41
62
|
|
|
63
|
+
/** One Computer Use card's facts. Empty collections and absent rows are omitted, never `null`. */
|
|
64
|
+
export interface ApprovalCuaCardFacts {
|
|
65
|
+
/** For a browser, the host of the window's current page. */
|
|
66
|
+
page?: ApprovalCuaPage;
|
|
67
|
+
/** Only the consequential steps, in call order. */
|
|
68
|
+
steps?: ApprovalCuaStep[];
|
|
69
|
+
/** The target window's title: the app's own text, which a page can set; a client shows it quoted and as plain text, never as markup or a choice, and may cap it. */
|
|
70
|
+
windowTitle?: string;
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/** The page's full host, no path or query. */
|
|
74
|
+
export interface ApprovalCuaPage {
|
|
75
|
+
/** The host in Unicode. */
|
|
76
|
+
host: string;
|
|
77
|
+
/** The host's `xn--` form; equal to `host` when they don't differ. */
|
|
78
|
+
hostAscii: string;
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/** A point in the model's 0–1000 coordinates. */
|
|
82
|
+
export interface ApprovalCuaPoint {
|
|
83
|
+
x: number;
|
|
84
|
+
y: number;
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/** One consequential step. A client renders "Step N: <action> <roleWord> "<label>" — <effect>"; a key step names its `chord`, and only a step with a `point` (and no label or chord) reads "at x,y". */
|
|
88
|
+
export interface ApprovalCuaStep {
|
|
89
|
+
/** The host's verb phrase, such as `click` or `type into`. */
|
|
90
|
+
action: string;
|
|
91
|
+
/** The chord, for a key step. */
|
|
92
|
+
chord?: string;
|
|
93
|
+
/** The host's trusted sentence for what the step may do. */
|
|
94
|
+
effect: string;
|
|
95
|
+
/** An open tag for styling and tests only (`verb:<class>`, `unresolved`, `unlabeled`); a client that doesn't know a value renders the step from `effect` and its label as usual. */
|
|
96
|
+
kind: string;
|
|
97
|
+
/** The control's label: the app's own text, shown quoted and as plain text; a client may cap it. */
|
|
98
|
+
label?: string;
|
|
99
|
+
/** The step's own 0–1000 model coordinates, only for a point step. */
|
|
100
|
+
point?: ApprovalCuaPoint;
|
|
101
|
+
/** `button`, `link`, `menu item` or `key`; absent for a point step. */
|
|
102
|
+
roleWord?: string;
|
|
103
|
+
/** 1-based, as the batch numbers its steps. */
|
|
104
|
+
step: number;
|
|
105
|
+
}
|
|
106
|
+
|
|
42
107
|
/** `approval/decide` params (tdd SS5.4): the decision. A standard SS3 command — requires the session loaded on this host, requires `commandId`, durable intake before ack, value-identical replay. */
|
|
43
108
|
export interface ApprovalDecideParams {
|
|
44
109
|
/** The approval being decided. */
|
|
@@ -67,6 +132,7 @@ export interface ApprovalDecideResult {
|
|
|
67
132
|
terminal: boolean;
|
|
68
133
|
}
|
|
69
134
|
|
|
135
|
+
/** The kind of decision a choice applies or an approval received. The set is open, so newer hosts may send values this version does not list. */
|
|
70
136
|
export type ApprovalDecision = "approved" | "approvedForSession" | "approvedPolicyAmendment" | "denied" | "deniedPolicyAmendment" | "timedOut" | "abort" | (string & {});
|
|
71
137
|
|
|
72
138
|
/** `approval/listPending` params (tdd SS5.7): the pull dual of the re-issued requests. A log-fold read — no lease, works on loaded and unloaded sessions, never subscribes. */
|
|
@@ -77,9 +143,9 @@ export interface ApprovalListPendingParams {
|
|
|
77
143
|
|
|
78
144
|
/** `approval/listPending` result (tdd SS5.7). Ordering is by opening `viewCursor`; empty arrays when nothing is pending. The result is point-in-time — to act on it race-safely, `approval/decide` carries the `requirementId` guard regardless of how the client learned the state. */
|
|
79
145
|
export interface ApprovalListPendingResult {
|
|
80
|
-
/** Exactly the `approval/request` params
|
|
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;
|
|
@@ -546,11 +719,11 @@ export interface ErrorData {
|
|
|
546
719
|
alignedNextOffset?: number;
|
|
547
720
|
/** The rejected anchor value on `notFound`/`missingAnchor` and the `-32042` boundary arms (SS4.7.3, SS4.11); on `-32042` it is served as an explicit `null` when the request named no concrete anchor (spec 208 FM-005). */
|
|
548
721
|
anchor?: string | null;
|
|
549
|
-
/** Approval
|
|
722
|
+
/** Approval id on approval errors. */
|
|
550
723
|
approvalId?: string;
|
|
551
724
|
/** The stored output's availability on `outputUnavailable` — the durable `ToolOutputAvailability` value, read-time-derived when the durable record still says `available` (SS4.5.5; spec 208 FM-008). */
|
|
552
725
|
availability?: string;
|
|
553
|
-
/** The missing capability, on `capabilityRequired` errors. Typed on the grantable registry, so `rawLog`
|
|
726
|
+
/** The missing capability, on `capabilityRequired` errors. Typed on the grantable registry, so the experimental-only `rawLog` joins the stable domain as an additive open-enum extension when it graduates. */
|
|
554
727
|
capability?: CapabilityName;
|
|
555
728
|
/** The configured command-admission bound, on `backpressured` errors. */
|
|
556
729
|
capacity?: number;
|
|
@@ -560,7 +733,7 @@ export interface ErrorData {
|
|
|
560
733
|
commandId?: string;
|
|
561
734
|
/** Current stage token on `approvalRequirementStale`. */
|
|
562
735
|
currentRequirementId?: ApprovalRequirementRef;
|
|
563
|
-
/**
|
|
736
|
+
/** On `experimentalRequired` errors, the name of the experimental method, field or variant the request used, for example `turn/start.providerRequestOptions`. */
|
|
564
737
|
descriptor?: string;
|
|
565
738
|
/** Free-form additive detail. */
|
|
566
739
|
details?: Record<string, unknown>;
|
|
@@ -604,13 +777,13 @@ export interface ErrorData {
|
|
|
604
777
|
settlement?: UserInputSettlementSummary;
|
|
605
778
|
/** The rejected upload id on `uploadNotFound` (`-32038`, SS3.33). */
|
|
606
779
|
uploadId?: string;
|
|
607
|
-
/**
|
|
780
|
+
/** Prompt identity on user-input errors. */
|
|
608
781
|
userInputId?: string;
|
|
609
782
|
/** The blocked view position on `pageEventTooLarge` errors. */
|
|
610
783
|
viewCursor?: string;
|
|
611
784
|
}
|
|
612
785
|
|
|
613
|
-
/** A stable `error.data.kind` category
|
|
786
|
+
/** A stable `error.data.kind` category: camelCase, the value clients branch on. Open: new kinds are added as their methods land, and a new `kind` is additive only because this domain is declared open. */
|
|
614
787
|
export type ErrorKind = "parseError" | "invalidRequest" | "notInitialized" | "alreadyInitialized" | "methodNotFound" | "invalidParams" | "experimentalRequired" | "internal" | "pageEventTooLarge" | "outputResultTooLarge" | "overloaded" | "inputTooLarge" | "capabilityRequired" | "notFound" | "interrupted" | "cancelled" | "sessionNotFound" | "sessionInUse" | "sessionAmbiguous" | "forkBoundaryInvalid" | "sessionNotLoaded" | "sessionStreamMismatch" | "commandRejected" | "backpressured" | "skillNotFound" | "computerUseUnavailable" | "marketplaceNotFound" | "pluginNotFound" | "marketplaceAlreadyExists" | "pluginMutationsDisabled" | "uploadNotFound" | "viewTruncated" | "outputUnavailable" | "boundaryPruned" | "boundaryUnusable" | "noBoundary" | "approvalNotFound" | "approvalAlreadyResolved" | "approvalChoiceInvalid" | "approvalRequirementStale" | "approvalReviewerUnavailable" | "userInputNotFound" | "userInputAlreadySettled" | "userInputAnswerInvalid" | (string & {});
|
|
615
788
|
|
|
616
789
|
/** The `error` member of an error response (SS1.2 §2.4). */
|
|
@@ -699,7 +872,7 @@ export interface ForkProvenance {
|
|
|
699
872
|
|
|
700
873
|
/** The session goal block (tdd SS4.6.2, mirrors the runtime's goal state, camelCased). `status` and `percentComplete` are carried **verbatim** — out-of-contract status strings and >100 percents pass through; display clamping is the renderer's job. */
|
|
701
874
|
export interface Goal {
|
|
702
|
-
/**
|
|
875
|
+
/** Goal creation time, epoch milliseconds, verbatim from the durable row. Absent on blocks whose producer never carried it (tool-result adoptions, older logs); absence must never render as a fabricated zero. */
|
|
703
876
|
createdAtMs?: number;
|
|
704
877
|
/** Current work description, when present. */
|
|
705
878
|
currentWork?: string;
|
|
@@ -711,7 +884,7 @@ export interface Goal {
|
|
|
711
884
|
percentComplete: number;
|
|
712
885
|
/** Goal status, verbatim from the durable goal state (free string by design: out-of-contract values pass through). */
|
|
713
886
|
status: string;
|
|
714
|
-
/**
|
|
887
|
+
/** Last goal mutation time, epoch milliseconds, verbatim from the durable row. Same absence rule as `createdAtMs`. */
|
|
715
888
|
updatedAtMs?: number;
|
|
716
889
|
}
|
|
717
890
|
|
|
@@ -772,7 +945,7 @@ export interface GoalSetParams {
|
|
|
772
945
|
/** What history a lifecycle result actually served (tdd SS2.5.2). Open on the client side: report-what-was-served means a client treats an unknown mode as "page it yourself". */
|
|
773
946
|
export type HistoryMode = "anchoredSnapshot" | "inline" | "snapshot" | "none" | (string & {});
|
|
774
947
|
|
|
775
|
-
/** Why a result served `history.mode: "none"
|
|
948
|
+
/** Why a result served `history.mode: "none"`: the server's typed reason for serving no history. Open on the client side: an absent (older server) or unknown (newer server) value decodes conservatively as an unknown reason, and `viewCursor` text never substitutes for it. */
|
|
776
949
|
export type HistoryNoneReason = "excluded" | "cursorSuffix" | "historyBudget" | "projectionUnavailable" | "projectionReadLimit" | (string & {});
|
|
777
950
|
|
|
778
951
|
/** The `history` request preference of `session/resume` (tdd SS2.5.2). The forced values downgrade `anchored` → `inline` → `snapshot` → `none`; under `auto` the full rung order is anchoredSnapshot → inline → snapshot → elided snapshot → none. */
|
|
@@ -791,7 +964,7 @@ export interface HookCatalogEntry {
|
|
|
791
964
|
}
|
|
792
965
|
|
|
793
966
|
/** Hook event names (tdd SS3.26.1, ADR 33398 D7 item 2): the lowercase-first-letter spelling of every `HookEventKind::all()` variant. Open (server-produced result vocabulary, the #22785 enum-openness rule): a future event value is additive. */
|
|
794
|
-
export type HookEventName = "sessionStart" | "userPromptSubmit" | "preToolUse" | "permissionRequest" | "postToolUse" | "preCompact" | "postCompact" | "subagentStart" | "subagentStop" | "stop" | "sessionEnd" | "notification" | "postToolUseFailure" | "stopFailure" | "postToolBatch" | "interrupt" | "sessionFork" | "toolUseStart" |
|
|
967
|
+
export type HookEventName = "sessionStart" | "userPromptSubmit" | "preToolUse" | "permissionRequest" | "postToolUse" | "preLLMCall" | "postLLMCall" | "preCompact" | "postCompact" | "subagentStart" | "subagentStop" | "stop" | "sessionEnd" | "notification" | "postToolUseFailure" | "stopFailure" | "postToolBatch" | "interrupt" | "sessionFork" | "toolUseStart" | (string & {});
|
|
795
968
|
|
|
796
969
|
/** A hook row's origin (tdd SS3.26.1, ADR 33398 D7 item 1): the config `HookSourceKind` values plus plugin-contributed. Open (server-produced result vocabulary, the #22785 enum-openness rule): a future origin is additive. */
|
|
797
970
|
export type HookHandlerKind = "managed" | "user" | "project" | "plugin" | (string & {});
|
|
@@ -834,7 +1007,7 @@ export interface InitializeResult {
|
|
|
834
1007
|
platformFamily: PlatformFamily;
|
|
835
1008
|
/** Server operating system. */
|
|
836
1009
|
platformOs: PlatformOs;
|
|
837
|
-
/** Whether this host can enforce the sandbox
|
|
1010
|
+
/** Whether this host can enforce the sandbox. Optional so adding it stays backward compatible; a v1 host always sends it, and a client reads absent as unknown — the host predates the field, so the client falls back to its own probe rather than inventing an answer. */
|
|
838
1011
|
sandboxAvailability?: SandboxAvailability;
|
|
839
1012
|
/** Why enforcement is impossible. Sent only when `sandbox_availability` is `unavailable`; a client MUST NOT infer a reason when none is sent. */
|
|
840
1013
|
sandboxUnavailableReason?: SandboxUnavailableReason;
|
|
@@ -842,7 +1015,7 @@ export interface InitializeResult {
|
|
|
842
1015
|
schema: SchemaInfo;
|
|
843
1016
|
/** Server identification. */
|
|
844
1017
|
serverInfo: ServerInfo;
|
|
845
|
-
/** Whether this host persists its sessions
|
|
1018
|
+
/** Whether this host persists its sessions. Optional so adding it stays backward compatible; a v1 host always sends it, and a client reads absent as `durable` because no server that omits it has the ephemeral profile. */
|
|
846
1019
|
sessionDurability?: SessionDurability;
|
|
847
1020
|
/** Exact user-agent string presented to upstream model providers. */
|
|
848
1021
|
userAgent: string;
|
|
@@ -862,6 +1035,8 @@ export interface Item {
|
|
|
862
1035
|
background?: boolean;
|
|
863
1036
|
/** `toolCall`: who backgrounded the task; absent on pre-split records — never inferred (tdd SS4.5.5). */
|
|
864
1037
|
backgroundInitiator?: BackgroundInitiator;
|
|
1038
|
+
/** `backgroundTerminalCompletion`: the five facts the Finished cell renders (ADR 50041 D4). */
|
|
1039
|
+
backgroundTerminalCompletion?: BackgroundTerminalCompletion;
|
|
865
1040
|
/** `reminderChild`: `true` when this child is a blocking reminder (it holds the turn open until it settles); absent otherwise, never `false` (ADR 41191 D4). The status word stays off the wire; clients name the reminder from `reminderAgentId`. */
|
|
866
1041
|
blocking?: boolean;
|
|
867
1042
|
/** `toolCall`: the provider call id (`call_...`), opaque. */
|
|
@@ -894,7 +1069,7 @@ export interface Item {
|
|
|
894
1069
|
displayLabel?: ToolDisplayLabel;
|
|
895
1070
|
/** `userMessage`: presentation form (tdd SS3.2); absent when the client sent none. */
|
|
896
1071
|
displayText?: string;
|
|
897
|
-
/** `userShell`/`subagent`: observed wall-clock duration. `workflow`: the run's wall time from launch to reconciliation, set only on the settling `item/completed` — never a sum of child durations. */
|
|
1072
|
+
/** `userShell`/`subagent`: observed wall-clock duration. `workflow`: the run's wall time from launch to reconciliation, set only on the settling `item/completed` — never a sum of child durations. `toolCall`: the Backgrounded row's duration (ADR 50041 D11) — the open→update record delta in whole ms, served on the `backgroundStatus` re-emission and frozen there; absent otherwise. */
|
|
898
1073
|
durationMs?: number;
|
|
899
1074
|
/** `workflow`: launched entry identity. */
|
|
900
1075
|
entryId?: string;
|
|
@@ -998,7 +1173,7 @@ export interface Item {
|
|
|
998
1173
|
strategyId?: string;
|
|
999
1174
|
/** `subagent`: durable child identity (`subagent_id`). */
|
|
1000
1175
|
subagentId?: string;
|
|
1001
|
-
/** `compaction`: opaque provenance string naming the compaction boundary.
|
|
1176
|
+
/** `compaction`: opaque provenance string naming the compaction boundary. Also a compaction-anchored read anchor, accepted by `session/resume` and `view/page`. Still opaque — clients relay it, never parse it. */
|
|
1002
1177
|
summarizedThrough?: string;
|
|
1003
1178
|
/** `reasoning`: one entry per summary part; part *n* streams via `item/delta` field `"summary.n"` (part boundary = index change). */
|
|
1004
1179
|
summary?: string[];
|
|
@@ -1059,12 +1234,12 @@ export interface ItemDeltaParams {
|
|
|
1059
1234
|
}
|
|
1060
1235
|
|
|
1061
1236
|
/** The eleven v1 item kinds (tdd SS4.5.2–4.5.13) plus post-v1 kinds (tdd SS4.5.14+). Open: a new kind is additive evolution, and clients MUST render unknown kinds generically (tdd SS4.10). */
|
|
1062
|
-
export type ItemKind = "userMessage" | "agentMessage" | "reasoning" | "toolCall" | "userShell" | "subagent" | "workflow" | "reminderChild" | "compaction" | "hookRun" | "sideChat" | "webSearch" | "monitorFeed" | "damagedRange" | "scheduledFire" | (string & {});
|
|
1237
|
+
export type ItemKind = "userMessage" | "agentMessage" | "reasoning" | "toolCall" | "userShell" | "subagent" | "workflow" | "reminderChild" | "compaction" | "hookRun" | "sideChat" | "webSearch" | "monitorFeed" | "damagedRange" | "scheduledFire" | "backgroundTerminalCompletion" | "overdueNotice" | (string & {});
|
|
1063
1238
|
|
|
1064
1239
|
/** The `item/readOutput` content encoding (tdd SS4.7.4). Closed: text media is ALWAYS `utf8` and binary media `base64`; a third value would change the client's decode contract. */
|
|
1065
1240
|
export type ItemReadOutputEncoding = "utf8" | "base64";
|
|
1066
1241
|
|
|
1067
|
-
/** `item/readOutput` params
|
|
1242
|
+
/** `item/readOutput` params: byte-ranged fetch of stored full output that the view truncated, via the item's `outputRef`. Read-only; works on loaded and unloaded sessions; no lease. */
|
|
1068
1243
|
export interface ItemReadOutputParams {
|
|
1069
1244
|
/** The item whose stored output is fetched. */
|
|
1070
1245
|
itemId: string;
|
|
@@ -1147,7 +1322,7 @@ export interface MediaUploadParams {
|
|
|
1147
1322
|
chunkCount: number;
|
|
1148
1323
|
/** This chunk's 0-based position. */
|
|
1149
1324
|
chunkIndex: number;
|
|
1150
|
-
/** One per call
|
|
1325
|
+
/** One per call. While the host runs, replaying it with the same params returns the recorded receipt, and reusing it with different params is refused. After a host restart, start over under a new `uploadId`. */
|
|
1151
1326
|
commandId: string;
|
|
1152
1327
|
/** `video/mp4` or `video/quicktime`, matching `VideoInput`. */
|
|
1153
1328
|
mediaType: string;
|
|
@@ -1409,7 +1584,7 @@ export interface PendingApprovalPointer {
|
|
|
1409
1584
|
/** The `pendingRequests` discriminator (tdd SS2.5.2). Open enum, v1 values `approval` and `userInput`. */
|
|
1410
1585
|
export type PendingRequestKind = "approval" | "userInput" | (string & {});
|
|
1411
1586
|
|
|
1412
|
-
/** A late-joiner pointer at an unsettled server-initiated request (tdd SS2.5.2, SS2.2.1). The full payloads arrive as re-issued server-to-client requests right after a `session/resume` response (tdd SS5.6); `session/read` never re-issues them (tdd SS2.5.5).
|
|
1587
|
+
/** A late-joiner pointer at an unsettled server-initiated request (tdd SS2.5.2, SS2.2.1). The full payloads arrive as re-issued server-to-client requests right after a `session/resume` response (tdd SS5.6); `session/read` never re-issues them (tdd SS2.5.5). The protocol defines two kind-discriminated entry shapes (`{kind: "approval", approvalId, viewCursor}` / `{kind: "userInput", userInputId, viewCursor}`). This type is one flat object with both ids optional, as for `ApprovalSubject` and `TurnInputPart`, because the v1 model names no object-variant union; the serialized JSON is the same, but the published schema also accepts `{"kind":"approval","userInputId":…}` and an entry carrying no id at all. Unlike `TurnInputPart.type`, `kind` here is an OPEN enum. */
|
|
1413
1588
|
export interface PendingRequestPointer {
|
|
1414
1589
|
/** Present on an `approval` entry. */
|
|
1415
1590
|
approvalId?: string;
|
|
@@ -1431,7 +1606,7 @@ export interface PendingUserInputPointer {
|
|
|
1431
1606
|
viewCursor: string;
|
|
1432
1607
|
}
|
|
1433
1608
|
|
|
1434
|
-
/** The server runtime's platform family
|
|
1609
|
+
/** The server runtime's platform family; may differ from the client's. Closed: the protocol fixes the value set, so widening it is a deliberate, gate-visible protocol change rather than a silent addition (a later `Closed`→`Open` flip is itself additive). */
|
|
1435
1610
|
export type PlatformFamily = "unix" | "windows";
|
|
1436
1611
|
|
|
1437
1612
|
/** The server's operating system (SS1.4.1). Closed, for the same reason as [`PlatformFamily`]. */
|
|
@@ -1681,7 +1856,7 @@ export interface RecapCompletedParams {
|
|
|
1681
1856
|
/** `recap/completed` failure reason (tdd SS3.28.2/SS3.28.8): post-ack failures fold to the single initial value. **Open**: later splits stay additive (#22785 E2). */
|
|
1682
1857
|
export type RecapFailureReason = "providerFailed" | (string & {});
|
|
1683
1858
|
|
|
1684
|
-
/** `recap/completed` outcome
|
|
1859
|
+
/** `recap/completed` outcome: the terminal vocabulary, in camelCase. **Open**: a server-produced result vocabulary. */
|
|
1685
1860
|
export type RecapOutcome = "completed" | "failed" | "cancelled" | "timedOut" | (string & {});
|
|
1686
1861
|
|
|
1687
1862
|
/** `recap/request` params (tdd SS3.28.1): the session plus the client-minted UUIDv7 retry id. No other param; unknown fields are `invalidParams`. */
|
|
@@ -1778,7 +1953,7 @@ export interface ServerInfo {
|
|
|
1778
1953
|
|
|
1779
1954
|
/** The session object every lifecycle method returns or lists (tdd SS2.4). Additive-optional evolution applies: clients must ignore unknown fields. */
|
|
1780
1955
|
export interface Session {
|
|
1781
|
-
/** The `turnId` of the current foreground turn when `status` is `running`, and `null` when the session is idle (tdd SS2.4). **Required-nullable
|
|
1956
|
+
/** The `turnId` of the current foreground turn when `status` is `running`, and `null` when the session is idle (tdd SS2.4). **Required-nullable.** Every served `Session` carries the member: `null` when the session is idle or not loaded, the turn id when it is running. An optional-absent shape would publish it as plain `string` and reject every idle `Session` frame the host sends. */
|
|
1782
1957
|
activeTurnId: string | null;
|
|
1783
1958
|
/** The folded effective approval mode. **Additive-optional**: a Session object that omits it means the host has not folded a mode, which is why the index-derived `session/list` entry may legitimately omit it (tdd SS2.4, SS5.12). */
|
|
1784
1959
|
approvalMode?: EffectiveApprovalModeState;
|
|
@@ -1895,7 +2070,7 @@ export interface SessionCompactResult {
|
|
|
1895
2070
|
status: CompactStatus;
|
|
1896
2071
|
}
|
|
1897
2072
|
|
|
1898
|
-
/** The open configuration extension object shared by `session/start` and `session/resume` (ADR 32760 D1). Unknown keys are ignored on the wire, never rejected
|
|
2073
|
+
/** The open configuration extension object shared by `session/start` and `session/resume` (ADR 32760 D1). Unknown keys are ignored on the wire, never rejected: the live decoder tolerates them, and no exported bundle carries `additionalProperties: false`. The Rust typed model's `deny_unknown_fields` is internal and never exported — the closedness export applies nowhere, and the `x-msp-closed` opt-in mechanism stays inert. Recognized `mcpServers` values are typed and validated before they leave the wire boundary. */
|
|
1899
2074
|
export interface SessionConfig {
|
|
1900
2075
|
/** Native MCP servers added only to this session runtime. */
|
|
1901
2076
|
mcpServers?: Record<string, SessionMcpServerConfig>;
|
|
@@ -1958,6 +2133,8 @@ export interface SessionGoalChangedParams {
|
|
|
1958
2133
|
|
|
1959
2134
|
/** The `history` envelope shared by `session/resume`, `session/fork`, and `session/read` (tdd SS2.5.2). */
|
|
1960
2135
|
export interface SessionHistory {
|
|
2136
|
+
/** The checkpoint-prune boundary (spec 13929 amendment FR-50042-1): rows for served items at-or-before `through_item_id` in served order predate the selected checkpoint. Additive-optional; absence is a non-assertion (ADR 50042 D6). */
|
|
2137
|
+
checkpointBoundary?: CheckpointBoundary;
|
|
1961
2138
|
/** The full folded item array when `mode` is `inline`; `null` otherwise. */
|
|
1962
2139
|
items: Item[] | null;
|
|
1963
2140
|
/** What was actually served — never what was asked for (tdd SS2.5.2). */
|
|
@@ -1973,10 +2150,15 @@ export type SessionKind = "root" | "subagent" | (string & {});
|
|
|
1973
2150
|
|
|
1974
2151
|
/** Params of the protected, non-view leave terminal notification. */
|
|
1975
2152
|
export interface SessionLeaveCompletedParams {
|
|
2153
|
+
/** The leave command's id, matching the `session/leave` request. */
|
|
1976
2154
|
commandId: string;
|
|
2155
|
+
/** How the leave ended: `released` or `failed`. The set is open, so newer hosts may add outcomes. */
|
|
1977
2156
|
outcome: SessionLeaveOutcome;
|
|
2157
|
+
/** Why the leave failed. Present when `outcome` is `failed`. */
|
|
1978
2158
|
reason?: SessionLeaveFailureReason;
|
|
2159
|
+
/** The session the leave was for. */
|
|
1979
2160
|
sessionId: string;
|
|
2161
|
+
/** The session's view cursor at release: everything up to it was folded before the host let go. Present when `outcome` is `released`. */
|
|
1980
2162
|
viewCursor?: string;
|
|
1981
2163
|
}
|
|
1982
2164
|
|
|
@@ -1998,7 +2180,9 @@ export interface SessionLeaveParams {
|
|
|
1998
2180
|
|
|
1999
2181
|
/** The admission-only `session/leave` result. */
|
|
2000
2182
|
export interface SessionLeaveResult {
|
|
2183
|
+
/** The leave command's id. */
|
|
2001
2184
|
commandId: string;
|
|
2185
|
+
/** The admission status, `accepted` once the leave is admitted. The final result arrives later as `session/leaveCompleted`. Sending the same leave command again returns `accepted` and re-pushes the recorded result if there is one, from the host that ran the leave (for as long as it runs, even after the release) or from a host that has the session loaded (after a host crash, `abandoned` among them). Any other host treats it as a fresh leave: a durable host that has not loaded the session refuses it with `sessionNotLoaded` until it is resumed there. */
|
|
2002
2186
|
status: CommandAckStatus;
|
|
2003
2187
|
}
|
|
2004
2188
|
|
|
@@ -2030,7 +2214,7 @@ export interface SessionListParams {
|
|
|
2030
2214
|
cursor?: string | null;
|
|
2031
2215
|
/** Optional structured selection applied inside the bounded index query before paging (#42035, spec 207 FR-42035-1). Present — including `{}` — makes a supporting server echo its canonical form as `appliedFilter`; omitted keeps the pre-#42035 behavior. */
|
|
2032
2216
|
filter?: SessionListFilter;
|
|
2033
|
-
/** Page size; default 50, max 200 — the
|
|
2217
|
+
/** Page size; default 50, max 200 — the schema publishes the cap. Maximum 200. */
|
|
2034
2218
|
limit?: number;
|
|
2035
2219
|
/** Only sessions with log activity after this RFC3339 instant. */
|
|
2036
2220
|
updatedAfter?: string;
|
|
@@ -2139,6 +2323,8 @@ export interface SessionReadParams {
|
|
|
2139
2323
|
|
|
2140
2324
|
/** `session/read` result (tdd SS2.5.5). The `viewCursor` is the fold head at read time — a point-in-time read, immediately stale if a foreign host is appending. */
|
|
2141
2325
|
export interface SessionReadResult {
|
|
2326
|
+
/** Same member as `session/resume` (tdd SS2.5.5, ADR 50074 D2). */
|
|
2327
|
+
blockedPrompt?: BlockedPrompt;
|
|
2142
2328
|
/** The served history. */
|
|
2143
2329
|
history: SessionHistory;
|
|
2144
2330
|
/** Same member as `session/resume` (tdd SS2.5.5, ADR 36635 D2). */
|
|
@@ -2155,7 +2341,7 @@ export interface SessionReadResult {
|
|
|
2155
2341
|
|
|
2156
2342
|
/** `session/reasoningEffortChanged` params (tdd SS4.6.9, ADR 31255 D1): a durable reasoning-effort reconfigure record landed (tdd SS3.21). Replace wholesale, latest wins; the snapshot carries the latest value (SS4.9.1). */
|
|
2157
2343
|
export interface SessionReasoningEffortChangedParams {
|
|
2158
|
-
/** The new session default: the closed eight-string tier vocabulary
|
|
2344
|
+
/** The new session default: the same closed eight-string tier vocabulary as `turn/start`. */
|
|
2159
2345
|
reasoningEffort: ReasoningEffort;
|
|
2160
2346
|
/** The owning session. */
|
|
2161
2347
|
sessionId: string;
|
|
@@ -2193,7 +2379,7 @@ export interface SessionResumeParams {
|
|
|
2193
2379
|
commandId: string;
|
|
2194
2380
|
/** The same open construction-time extension object as `session/start`. */
|
|
2195
2381
|
config?: SessionConfig;
|
|
2196
|
-
/** A view cursor previously observed by this client — or an observed `summarizedThrough` compaction anchor
|
|
2382
|
+
/** A view cursor previously observed by this client — or an observed `summarizedThrough` compaction anchor. When it names an event the server still holds, the server returns only the suffix and `history.mode` is `none`. A cursor the server minted that names no event yet, such as the empty start cursor of a session that had no events, is treated as no cursor: the server serves what a resume without a cursor would. A cursor older than the earliest event the server still holds gets a snapshot, or `-32040` `viewTruncated` when none fits. A cursor this session's view never minted is refused with `-32011` `notFound`, reason `missingAnchor`, and a compaction anchor naming a boundary the server has pruned is refused with `-32042` `boundaryPruned`. Omitted and explicit `null` both mean "no cursor". */
|
|
2197
2383
|
cursor?: string | null;
|
|
2198
2384
|
/** Return only session metadata and live resume state; page history separately with `view/page`. Default `false` (tdd SS2.5.2). */
|
|
2199
2385
|
excludeItems?: boolean;
|
|
@@ -2209,6 +2395,8 @@ export interface SessionResumeParams {
|
|
|
2209
2395
|
|
|
2210
2396
|
/** `session/resume` result (tdd SS2.5.2). */
|
|
2211
2397
|
export interface SessionResumeResult {
|
|
2398
|
+
/** The recallable blocked prompt's refill text (ADR 50074 D2). **Additive-optional**; absence means no blocked prompt to recall (an unblocked session, or a pre-feature host). Data only, never a rendered row: clients seed cold recall from it (C-p refills `text`) and MUST NOT display it as history. */
|
|
2399
|
+
blockedPrompt?: BlockedPrompt;
|
|
2212
2400
|
/** The served history. */
|
|
2213
2401
|
history: SessionHistory;
|
|
2214
2402
|
/** How the last folded turn ended (tdd SS2.5.2, ADR 36635 D2). **Additive-optional**; absence is a non-assertion. */
|
|
@@ -2305,7 +2493,7 @@ export interface SessionStartParams {
|
|
|
2305
2493
|
approvalMode?: ApprovalMode | null;
|
|
2306
2494
|
/** The SS2.5 idempotency handle (UUIDv7). Required; the server never mints one. */
|
|
2307
2495
|
commandId: string;
|
|
2308
|
-
/** Reserved for per-session overrides
|
|
2496
|
+
/** Reserved for future per-session overrides; only its `mcpServers` member is admitted. */
|
|
2309
2497
|
config?: SessionConfig;
|
|
2310
2498
|
/** Initial model; server default when omitted. */
|
|
2311
2499
|
modelId?: string;
|
|
@@ -2588,7 +2776,7 @@ export interface SnapshotAnchor {
|
|
|
2588
2776
|
summarizedThrough: string;
|
|
2589
2777
|
}
|
|
2590
2778
|
|
|
2591
|
-
/** The complete folded view at the snapshot cursor (tdd SS4.9.1). Additive-optional evolution applies exactly as everywhere else; unknown members MUST be ignored, and preserved if re-serialized.
|
|
2779
|
+
/** The complete folded view at the snapshot cursor (tdd SS4.9.1). Additive-optional evolution applies exactly as everywhere else; unknown members MUST be ignored, and preserved if re-serialized. */
|
|
2592
2780
|
export interface SnapshotState {
|
|
2593
2781
|
/** The running foreground turn; `null` when none is running. */
|
|
2594
2782
|
activeTurn: TurnRef | null;
|
|
@@ -2596,7 +2784,7 @@ export interface SnapshotState {
|
|
|
2596
2784
|
approvalMode: EffectiveApprovalModeState;
|
|
2597
2785
|
/** Latest branch observation; `null` when no fact has landed. */
|
|
2598
2786
|
branch: BranchState | null;
|
|
2599
|
-
/** The latest `(windowTokens, usedTokens, pressure)` triple.
|
|
2787
|
+
/** The latest `(windowTokens, usedTokens, pressure)` triple. The protocol allows "`null`/absent" and its worked example OMITS the member; the binary omits it too, so this is the absent arm — the four siblings above are present-null in the same frame. A member is published as one or the other, never both. */
|
|
2600
2788
|
contextUsage?: ContextUsage;
|
|
2601
2789
|
/** Latest effective model; `null` when no fact has landed. */
|
|
2602
2790
|
effectiveModel: EffectiveModel | null;
|
|
@@ -2820,10 +3008,17 @@ export interface TaskCommandResult {
|
|
|
2820
3008
|
taskId: string;
|
|
2821
3009
|
}
|
|
2822
3010
|
|
|
2823
|
-
/**
|
|
3011
|
+
/** A task row's execution mode (tdd SS3.31, ADR 62268 D2). Open (server-produced result vocabulary, the #22785 enum-openness rule): clients MUST ignore unknown modes. */
|
|
3012
|
+
export type TaskExecutionMode = "foreground" | "background" | (string & {});
|
|
3013
|
+
|
|
3014
|
+
/** One task inventory row (tdd SS3.31). The row is the stable contract: `kind` and `status` stay open so a future state extends them without breaking clients. */
|
|
2824
3015
|
export interface TaskListEntry {
|
|
2825
3016
|
/** Who backgrounded the task, mirroring the item field. **Additive-optional**: absent on pre-split records and registry-only rows, never inferred. */
|
|
2826
3017
|
backgroundInitiator?: BackgroundInitiator;
|
|
3018
|
+
/** The raw command text: the joined `toolCall` item's `command` argument verbatim (ADR 62268 D2). **Additive-optional**: omitted when the row has no item or the item carries no command. Monitors join raw — clients redact (INV-17544-6). */
|
|
3019
|
+
command?: string;
|
|
3020
|
+
/** `"foreground" | "background"` (ADR 62268 D2). **Additive-optional**: absent means `"background"` (only pre-change hosts omit it, and those list background rows only); never guessed. */
|
|
3021
|
+
executionMode?: TaskExecutionMode;
|
|
2827
3022
|
/** What the workload is: `"tool"` or `"tool.*"` for item rows (the recorded kind when the registry records one, else `"tool"`); the recorded registry kind string verbatim for registry-only rows. Open vocabulary — clients MUST ignore unknown kinds. A `String`, not an enum: registry kind strings are unbounded. */
|
|
2828
3023
|
kind: string;
|
|
2829
3024
|
/** The host-known task start, RFC3339. **Additive-optional**: omitted, never guessed, when the host does not know it. */
|
|
@@ -2842,9 +3037,9 @@ export interface TaskListParams {
|
|
|
2842
3037
|
sessionId: string;
|
|
2843
3038
|
}
|
|
2844
3039
|
|
|
2845
|
-
/** `task/list` result (tdd SS3.31): one row per
|
|
3040
|
+
/** `task/list` result (tdd SS3.31): one row per live workload, background and foreground (ADR 62268 D1), oldest first; empty when nothing is running. */
|
|
2846
3041
|
export interface TaskListResult {
|
|
2847
|
-
/** The session's live
|
|
3042
|
+
/** The session's live task rows. */
|
|
2848
3043
|
tasks: TaskListEntry[];
|
|
2849
3044
|
}
|
|
2850
3045
|
|
|
@@ -3015,7 +3210,7 @@ export interface TurnForegroundCompletedParams {
|
|
|
3015
3210
|
viewCursor: string;
|
|
3016
3211
|
}
|
|
3017
3212
|
|
|
3018
|
-
/** One ordered content part of a turn submission (tdd SS3.2). File mentions are text, not a part type: write `@relative/path` in a text part. A structured `mention` part is reserved and currently rejected, and an unknown part type is `invalidParams` (tdd SS3.1.2, SS3.2) — which is what closes [`TurnInputPartType`]. Modelled as a discriminated flat object rather than a Rust `enum`, the convention [`crate::view::approval::ApprovalSubject`] already established for a wire union in this crate: the v1 schema model names no object-variant union shape and fails closed on one. The serialized JSON is the
|
|
3213
|
+
/** One ordered content part of a turn submission (tdd SS3.2). File mentions are text, not a part type: write `@relative/path` in a text part. A structured `mention` part is reserved and currently rejected, and an unknown part type is `invalidParams` (tdd SS3.1.2, SS3.2) — which is what closes [`TurnInputPartType`]. Modelled as a discriminated flat object rather than a Rust `enum`, the convention [`crate::view::approval::ApprovalSubject`] already established for a wire union in this crate: the v1 schema model names no object-variant union shape and fails closed on one. The serialized JSON is the same either way; what a flat object cannot express is "`mediaType` is required exactly when `type` is `image`". `height` may only appear together with `width`. `width` may only appear together with `height`. */
|
|
3019
3214
|
export interface TurnInputPart {
|
|
3020
3215
|
/** Free-text skill arguments, optional on a `skill` part — the wire twin of what the TUI accepts after the shortcut token (tdd SS3.22.3). */
|
|
3021
3216
|
arguments?: string;
|
|
@@ -3027,7 +3222,7 @@ export interface TurnInputPart {
|
|
|
3027
3222
|
mediaType?: string;
|
|
3028
3223
|
/** The skill to invoke, required on a `skill` part (tdd SS3.2, SS3.22.3; ADR 32471 D4): a bare or plugin-qualified shortcut token from `skill/list`. The HOST resolves and expands; an unknown selector is the typed `-32032 skillNotFound` request error. */
|
|
3029
3224
|
selector?: string;
|
|
3030
|
-
/** The picked copy's source, optional on a `skill` part
|
|
3225
|
+
/** The picked copy's source, optional on a `skill` part: one of the catalog rows' `source` values. When present the host resolves the exact `(selector, source)` row; when absent it resolves the selector, bare or plugin-qualified, against the session's skill catalog, as the TUI shortcut does. Closed: an unknown value is `invalidParams`, never a fall-through. */
|
|
3031
3226
|
source?: SkillInvocationSource;
|
|
3032
3227
|
/** User prompt text, on a `text` part. Multiple text parts are joined in order into the turn's prompt. */
|
|
3033
3228
|
text?: string;
|
|
@@ -3035,7 +3230,7 @@ export interface TurnInputPart {
|
|
|
3035
3230
|
type: TurnInputPartType;
|
|
3036
3231
|
/** The upload receipt, required on a `video` part (tdd SS3.2, SS3.33; ADR 45443 D5): the client-minted id `media/upload` echoed. */
|
|
3037
3232
|
uploadId?: string;
|
|
3038
|
-
/** Pixel width; must be provided together with `height` or not at all
|
|
3233
|
+
/** Pixel width; must be provided together with `height` or not at all. Published as a `dependentRequired` pair. */
|
|
3039
3234
|
width?: number;
|
|
3040
3235
|
}
|
|
3041
3236
|
|
|
@@ -3098,7 +3293,7 @@ export interface TurnRef {
|
|
|
3098
3293
|
displayText?: string;
|
|
3099
3294
|
/** `queuedTurns[]` only: set when `displayText` was cut to the committed-surface budget, mirroring `userMessage.truncated` (tdd SS4.5.2). Absent unless `true`. */
|
|
3100
3295
|
truncated?: boolean;
|
|
3101
|
-
/** The turn's id,
|
|
3296
|
+
/** The turn's id, minted at admission. */
|
|
3102
3297
|
turnId: string;
|
|
3103
3298
|
}
|
|
3104
3299
|
|
|
@@ -3264,7 +3459,7 @@ export interface TurnUserShell {
|
|
|
3264
3459
|
commandText: string;
|
|
3265
3460
|
}
|
|
3266
3461
|
|
|
3267
|
-
/** One element of a `view/page` result's `events` array: an **unframed view notification**
|
|
3462
|
+
/** One element of a `view/page` result's `events` array: an **unframed view notification** — the nested pair `{"method", "params"}`, which is the live notification minus `jsonrpc` and `emittedAtMs`, with nothing lifted out of `params` and nothing spliced into it. `view/page` and `muse exec --json` share this one definition, so the two surfaces cannot drift. */
|
|
3268
3463
|
export interface UnframedViewNotification {
|
|
3269
3464
|
/** The event type — the live notification's method name, retained because the type lives only in the notification name and would otherwise be lost (tdd SS4.2.1). */
|
|
3270
3465
|
method: string;
|
|
@@ -3272,7 +3467,7 @@ export interface UnframedViewNotification {
|
|
|
3272
3467
|
params: UnframedViewNotificationParams;
|
|
3273
3468
|
}
|
|
3274
3469
|
|
|
3275
|
-
/** The `params` of an unframed view notification (tdd SS4.2.1, SS4.2). Declares the
|
|
3470
|
+
/** The `params` of an unframed view notification (tdd SS4.2.1, SS4.2). Declares the base members every view notification carries, and stays **open** for the event-specific fields each event type adds. The v1 schema model names no method-correlated union (the `events` element's `params` arm is selected by its sibling `method`), so the per-event arms cannot be expressed here without one, and an uncorrelated union of them could reject a real page element, which a published schema must not do. `sourceRange` is required here and not optional: `view/page` serves durable-sourced events only (tdd SS4.7.3), and durable-sourced is *defined* as carrying a `sourceRange` — the SS4.2 ephemeral-sourced exemption applies to `item/delta`, which `view/page` never replays. */
|
|
3276
3471
|
export interface UnframedViewNotificationParams {
|
|
3277
3472
|
/** The owning session (tdd SS4.2). */
|
|
3278
3473
|
sessionId: string;
|
|
@@ -3291,15 +3486,21 @@ export interface UsageReadResult {
|
|
|
3291
3486
|
usage?: SubscriptionUsage;
|
|
3292
3487
|
}
|
|
3293
3488
|
|
|
3489
|
+
/** One question's answer, as sent in `userInput/answer` or `userInput/interrupt` and as recorded in `userInput/settled`. */
|
|
3294
3490
|
export interface UserInputAnswer {
|
|
3491
|
+
/** A free-form answer, at most 500 characters. */
|
|
3295
3492
|
freeText?: string;
|
|
3493
|
+
/** An optional comment the user adds to the answer, at most 500 characters. */
|
|
3296
3494
|
note?: string;
|
|
3495
|
+
/** The `id` of the question this answers. */
|
|
3297
3496
|
questionId: string;
|
|
3497
|
+
/** The label of the chosen option, for a `single` question. */
|
|
3298
3498
|
selectedLabel?: string;
|
|
3499
|
+
/** The labels of the chosen options for a `multiple` question, within its selection bounds; omitted when empty. */
|
|
3299
3500
|
selectedLabels?: string[];
|
|
3300
3501
|
}
|
|
3301
3502
|
|
|
3302
|
-
/** `userInput/answer` params (tdd SS5.10.2): answer every question. Each answer carries `questionId` then exactly one of `selectedLabel` (single mode), `selectedLabels` (multiple mode, within min/max bounds), or `freeText` (<=500 chars); plus an optional `note` (<=500). Answers that do not match the prompt fail -32057 `userInputAnswerInvalid`. Image `attachments` are a **reserved** field in v1, rejected if sent, because the blob-upload path they reference is reserved
|
|
3503
|
+
/** `userInput/answer` params (tdd SS5.10.2): answer every question. Each answer carries `questionId` then exactly one of `selectedLabel` (single mode), `selectedLabels` (multiple mode, within min/max bounds), or `freeText` (<=500 chars); plus an optional `note` (<=500). Answers that do not match the prompt fail -32057 `userInputAnswerInvalid`. Image `attachments` are a **reserved** field in v1, rejected if sent, because the blob-upload path they reference is also reserved. */
|
|
3303
3504
|
export interface UserInputAnswerParams {
|
|
3304
3505
|
/** One entry per question. */
|
|
3305
3506
|
answers: UserInputAnswer[];
|
|
@@ -3343,8 +3544,11 @@ export interface UserInputCancelResult {
|
|
|
3343
3544
|
userInputId: string;
|
|
3344
3545
|
}
|
|
3345
3546
|
|
|
3547
|
+
/** A free-form reply the user gives instead of choosing from the options; the model reads it and decides again. */
|
|
3346
3548
|
export interface UserInputClarification {
|
|
3549
|
+
/** The clarification text, at most 500 characters. */
|
|
3347
3550
|
content: string;
|
|
3551
|
+
/** The content format. `text` is the only value today, and more may be added. */
|
|
3348
3552
|
format: string;
|
|
3349
3553
|
}
|
|
3350
3554
|
|
|
@@ -3400,67 +3604,107 @@ export interface UserInputInterruptResult {
|
|
|
3400
3604
|
userInputId: string;
|
|
3401
3605
|
}
|
|
3402
3606
|
|
|
3607
|
+
/** One option offered for a question. */
|
|
3403
3608
|
export interface UserInputOption {
|
|
3609
|
+
/** An optional longer explanation of the option, at most 240 characters. */
|
|
3404
3610
|
description?: string;
|
|
3611
|
+
/** The option's text, at most 80 characters and unique within its question; an answer selects the option by this exact label. */
|
|
3405
3612
|
label: string;
|
|
3613
|
+
/** An optional rich preview of the option, present only on single-select questions. */
|
|
3406
3614
|
preview?: UserInputOptionPreview;
|
|
3407
3615
|
}
|
|
3408
3616
|
|
|
3617
|
+
/** Rich content a client can show for an option. Only single-select questions carry previews. */
|
|
3409
3618
|
export interface UserInputOptionPreview {
|
|
3619
|
+
/** The preview content in that format, at most 2000 characters. */
|
|
3410
3620
|
content: string;
|
|
3621
|
+
/** The content format, for example `markdown`. */
|
|
3411
3622
|
format: string;
|
|
3412
3623
|
}
|
|
3413
3624
|
|
|
3625
|
+
/** How a user-input prompt settled. More values may be added, so handle values you do not recognize. */
|
|
3414
3626
|
export type UserInputOutcome = "answered" | "cancelled" | "interrupted" | "clarified" | "timedOut" | "aborted" | (string & {});
|
|
3415
3627
|
|
|
3628
|
+
/** One question in a user-input prompt. */
|
|
3416
3629
|
export interface UserInputQuestion {
|
|
3630
|
+
/** A short title for the question, at most 12 characters. */
|
|
3417
3631
|
header: string;
|
|
3632
|
+
/** The question's id, unique within the prompt and at most 64 characters. An answer names it in `questionId`. */
|
|
3418
3633
|
id: string;
|
|
3634
|
+
/** The options offered, two or three, in order. */
|
|
3419
3635
|
options: UserInputOption[];
|
|
3636
|
+
/** The full question text to show the user. */
|
|
3420
3637
|
question: string;
|
|
3638
|
+
/** Whether the user picks one option or several. */
|
|
3421
3639
|
selection: UserInputSelection;
|
|
3422
3640
|
}
|
|
3423
3641
|
|
|
3424
3642
|
/** Full params shared by `userInput/request` and `userInput/requested`. */
|
|
3425
3643
|
export interface UserInputRequestParams {
|
|
3644
|
+
/** The auto-resolution time per question, in milliseconds: a prompt nobody engages with settles as `timedOut` after this value times the number of questions. */
|
|
3426
3645
|
autoResolutionMs?: number;
|
|
3646
|
+
/** The `toolCall` view item of the tool call waiting on this prompt. */
|
|
3427
3647
|
itemId: string;
|
|
3648
|
+
/** The questions to ask, one to three, in order. */
|
|
3428
3649
|
questions: UserInputQuestion[];
|
|
3650
|
+
/** The session that owns the prompt. */
|
|
3429
3651
|
sessionId: string;
|
|
3652
|
+
/** The stored records this prompt was folded from, when sent: an opaque token clients must not interpret. */
|
|
3430
3653
|
sourceRange?: SourceRange;
|
|
3654
|
+
/** The provider's id for the tool call that opened the prompt. */
|
|
3431
3655
|
toolCallId: string;
|
|
3656
|
+
/** The name of the tool that opened the prompt. */
|
|
3432
3657
|
toolName: string;
|
|
3658
|
+
/** The turn whose tool call is waiting on this prompt. */
|
|
3433
3659
|
turnId: string;
|
|
3660
|
+
/** The prompt's stable id. Pass it to `userInput/answer`, `userInput/cancel`, `userInput/clarify` and `userInput/interrupt`, and use it to match the later `userInput/settled`. */
|
|
3434
3661
|
userInputId: string;
|
|
3662
|
+
/** The cursor of the `userInput/requested` event for this prompt. A client that missed the request can read the same payload at this cursor with `view/page`. */
|
|
3435
3663
|
viewCursor: string;
|
|
3436
3664
|
}
|
|
3437
3665
|
|
|
3666
|
+
/** How many options the user may pick for a question. */
|
|
3438
3667
|
export interface UserInputSelection {
|
|
3668
|
+
/** The most options the user may pick. Sent only in `multiple` mode; when absent the maximum is the number of options. */
|
|
3439
3669
|
maxSelections?: number;
|
|
3670
|
+
/** The minimum selection count for a `multiple` answer. Sent only in `multiple` mode; when absent the minimum is 1. */
|
|
3440
3671
|
minSelections?: number;
|
|
3672
|
+
/** `single` or `multiple`: whether an answer selects one option or several. */
|
|
3441
3673
|
mode: UserInputSelectionMode;
|
|
3442
3674
|
}
|
|
3443
3675
|
|
|
3676
|
+
/** Whether a question takes one option or several. */
|
|
3444
3677
|
export type UserInputSelectionMode = "single" | "multiple";
|
|
3445
3678
|
|
|
3446
3679
|
/** `userInput/settled` params: the first durable prompt settlement. */
|
|
3447
3680
|
export interface UserInputSettledParams {
|
|
3681
|
+
/** The recorded answers: one per question for `answered`, any confirmed partial answers for `interrupted`, and empty for every other outcome. */
|
|
3448
3682
|
answers: UserInputAnswer[];
|
|
3683
|
+
/** The user's free-form clarification when the outcome is `clarified`; `null` otherwise. */
|
|
3449
3684
|
clarification: UserInputClarification | null;
|
|
3450
3685
|
/** The decision time as RFC3339, projected from the durable settlement record's own stamp (ADR 45450 D3, ruling 2026-10-01): always present on the wire (schema-required, `null`-able); decoders still tolerate its absence (`default`, never skipped — SS5.10.3 keeps every member present), and current hosts always populate it. */
|
|
3451
3686
|
decidedAt: string | null;
|
|
3687
|
+
/** The `commandId` of the client command that settled the prompt; `null` when no command did, for example after a timeout or an abort. */
|
|
3452
3688
|
decidedByCommandId: string | null;
|
|
3689
|
+
/** How the prompt ended. */
|
|
3453
3690
|
outcome: UserInputOutcome;
|
|
3691
|
+
/** The reason, when one applies: the optional reason given with a cancel, or why an `aborted` prompt was closed; `null` otherwise. */
|
|
3454
3692
|
reason: string | null;
|
|
3693
|
+
/** The session that owns the prompt. */
|
|
3455
3694
|
sessionId: string;
|
|
3695
|
+
/** The stored records this event was folded from: an opaque token clients must not interpret. */
|
|
3456
3696
|
sourceRange: SourceRange;
|
|
3697
|
+
/** The prompt that settled. Accept a settlement even for a prompt whose request you never saw. */
|
|
3457
3698
|
userInputId: string;
|
|
3699
|
+
/** This event's view cursor: opaque, and strictly increasing within the session. */
|
|
3458
3700
|
viewCursor: string;
|
|
3459
3701
|
}
|
|
3460
3702
|
|
|
3461
3703
|
/** Winning terminal returned to a late user-input command. */
|
|
3462
3704
|
export interface UserInputSettlementSummary {
|
|
3705
|
+
/** How the prompt settled, as a `userInput/settled` outcome value such as `answered` or `timedOut`. */
|
|
3463
3706
|
outcome: string;
|
|
3707
|
+
/** The view cursor of the `userInput/settled` event that recorded the settlement. */
|
|
3464
3708
|
viewCursor: string;
|
|
3465
3709
|
}
|
|
3466
3710
|
|
|
@@ -3477,10 +3721,10 @@ export interface ViewGapParams {
|
|
|
3477
3721
|
sessionId: string;
|
|
3478
3722
|
}
|
|
3479
3723
|
|
|
3480
|
-
/** The `view/page` request-mode anchor
|
|
3724
|
+
/** The `view/page` request-mode anchor. Declared **open**: the protocol spells it "open string enum, v1 value `latestCompaction`". */
|
|
3481
3725
|
export type ViewPageAnchor = "latestCompaction" | (string & {});
|
|
3482
3726
|
|
|
3483
|
-
/** The `view/page` paging direction
|
|
3727
|
+
/** The `view/page` paging direction. Closed: the protocol spells exactly two values and a third would change the paging contract. */
|
|
3484
3728
|
export type ViewPageDirection = "forward" | "backward";
|
|
3485
3729
|
|
|
3486
3730
|
/** `view/page` params (tdd SS4.7.3): cursor-paged reads of the session view. */
|
|
@@ -3491,7 +3735,7 @@ export interface ViewPageParams {
|
|
|
3491
3735
|
cursor?: string;
|
|
3492
3736
|
/** Paging direction; `forward` when omitted. */
|
|
3493
3737
|
direction?: ViewPageDirection;
|
|
3494
|
-
/** Maximum events to return, 1–1000. The server MAY return fewer
|
|
3738
|
+
/** Maximum events to return, 1–1000. The server MAY return fewer. The 1–1000 range is ratified and **published**: the model carries the bound and the bundle renders `minimum`/`maximum` instead of a bare `integer`. Range 1–1000 inclusive. */
|
|
3495
3739
|
limit: number;
|
|
3496
3740
|
/** The session to page. */
|
|
3497
3741
|
sessionId: string;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@muse-code/sdk",
|
|
3
|
-
"version": "1.4.
|
|
3
|
+
"version": "1.4.12",
|
|
4
4
|
"description": "TypeScript SDK for the Muse Session Protocol (MSP): connect to a Muse Code session, drive turns, and fold the event stream. Zero runtime dependencies.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"homepage": "https://github.com/meta-models/muse-code-sdk",
|