@muse-code/sdk 1.4.11 → 1.4.13
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- 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 +342 -50
- 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:7fddaf646dbc317e5fcac0785e135eb04df14fbb0db1863089dfd6da21730e5b";
|
|
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:7fddaf646dbc317e5fcac0785e135eb04df14fbb0db1863089dfd6da21730e5b";
|
|
17
17
|
/**
|
|
18
18
|
* What a build-time mismatch MEANS, in the words a human needs at 2am.
|
|
19
19
|
*
|
package/dist/src/msp.d.ts
CHANGED
|
@@ -10,35 +10,122 @@
|
|
|
10
10
|
// Generated by tbh-protocol (spec 206) from the same schema model as
|
|
11
11
|
// the JSON Schema bundle (INV-017). Do not edit by hand.
|
|
12
12
|
|
|
13
|
+
/** The policy rule a decision created, in display form; the full rule is not included. */
|
|
13
14
|
export interface ApprovalAmendment {
|
|
15
|
+
/** How long the rule lasts: `session` or `localPersistent`. */
|
|
14
16
|
durability: ApprovalAmendmentDurability;
|
|
17
|
+
/** A human-readable preview of the rule, for display. */
|
|
15
18
|
rulePreview: string;
|
|
16
19
|
}
|
|
17
20
|
|
|
21
|
+
/** How long a rule created by an approval decision lasts. The set is open, so newer hosts may send other values. */
|
|
18
22
|
export type ApprovalAmendmentDurability = "session" | "localPersistent" | (string & {});
|
|
19
23
|
|
|
24
|
+
/** The change an `approval/updated` event reports. `kind` says what happened, and only the fields for that kind are present. */
|
|
20
25
|
export interface ApprovalChange {
|
|
26
|
+
/** The `choiceId` that satisfied the stage. Present only when `kind` is `stageResolved`. */
|
|
21
27
|
choiceId?: string;
|
|
28
|
+
/** The decision the chosen option applied to the stage. Present only when `kind` is `stageResolved`. */
|
|
22
29
|
decision?: ApprovalDecision;
|
|
30
|
+
/** A recovery detail: whether the action could run without a new decision. Present only when `kind` is `restartRecovered`. */
|
|
23
31
|
executable?: boolean;
|
|
32
|
+
/** What happened: for example `stageResolved` (a shell stage was satisfied), `policyPersistence` (saving a rule succeeded or failed), `reviewStarted` or `reviewCompleted` (the automated LLM judge started or finished reviewing), `restartRecovered` (a host restart recovered this approval: either the host first resolves it `abort` and a re-ask comes as a new approval with a new `approvalId`, or it stays pending under the same `approvalId` with refreshed choices) or `alreadyTerminal` (recovery found it already decided). The set is open, so newer hosts may add kinds. */
|
|
24
33
|
kind: string;
|
|
34
|
+
/** Why saving the policy rule failed, as human-readable text. Present only when `kind` is `policyPersistence` and `status` is `failed`. */
|
|
25
35
|
reason?: string;
|
|
36
|
+
/** A recovery detail: whether the command was re-parsed during recovery. Present only when `kind` is `restartRecovered`. */
|
|
26
37
|
reparsed?: boolean;
|
|
38
|
+
/** The stage requirement that was satisfied. Present only when `kind` is `stageResolved`. */
|
|
27
39
|
requirementId?: ApprovalRequirementRef;
|
|
40
|
+
/** Whether saving the policy rule succeeded or failed; present only when `kind` is `policyPersistence`. A failure does not undo the decision; only the saved rule is missing. */
|
|
28
41
|
status?: ApprovalPersistenceStatus;
|
|
29
42
|
}
|
|
30
43
|
|
|
44
|
+
/** One option the server offers for deciding an approval. Clients pick one and send its `choiceId` in `approval/decide`; they never build their own. */
|
|
31
45
|
export interface ApprovalChoice {
|
|
46
|
+
/** `true` when this choice takes optional `feedback` text in `approval/decide`, which reaches the model as guidance. Omitted when `false`. */
|
|
32
47
|
acceptsFeedback?: boolean;
|
|
48
|
+
/** The id to send as `choiceId` in `approval/decide`. The set of ids is open, so show `label` and do not base behavior on specific ids. */
|
|
33
49
|
choiceId: string;
|
|
50
|
+
/** The decision this choice applies, so a client can act on approve or reject without knowing choice ids. */
|
|
34
51
|
decision: ApprovalDecision;
|
|
52
|
+
/** The human-readable label to show for this choice. */
|
|
35
53
|
label: string;
|
|
54
|
+
/** A human-readable preview of what this choice grants, such as the policy rule it would create; show it exactly as given. */
|
|
36
55
|
rulePreview?: string;
|
|
56
|
+
/** The grant duration this choice declares: `once` (this request only), `session` (the rest of the session) or `localPersistent` (saved in the local policy store). */
|
|
37
57
|
scope: ApprovalChoiceScope;
|
|
38
58
|
}
|
|
39
59
|
|
|
60
|
+
/** How long a grant made by a choice lasts. The set is open, so newer hosts may send other values. */
|
|
40
61
|
export type ApprovalChoiceScope = "once" | "session" | "localPersistent" | (string & {});
|
|
41
62
|
|
|
63
|
+
/** One Computer Use card's facts. Empty collections and absent rows are omitted, never `null`. */
|
|
64
|
+
export interface ApprovalCuaCardFacts {
|
|
65
|
+
/** The data the call would send that the card must name; a card with any offers only one-shot choices. */
|
|
66
|
+
data?: ApprovalCuaDataFact[];
|
|
67
|
+
/** For a browser, the host of the window's current page. */
|
|
68
|
+
page?: ApprovalCuaPage;
|
|
69
|
+
/** Only the consequential steps, in call order. */
|
|
70
|
+
steps?: ApprovalCuaStep[];
|
|
71
|
+
/** The target window's title: the app's own text, which a page can set; a client shows it quoted and as plain text, never as markup or a choice, and may cap it. */
|
|
72
|
+
windowTitle?: string;
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
/** One piece of data the call would send. An open union on `kind` (`secret`, or `other` for a row the host can't word); a client shows `other` and any kind it doesn't know as a generic data row. */
|
|
76
|
+
export interface ApprovalCuaDataFact {
|
|
77
|
+
/** Open discriminator: `secret` or `other`. */
|
|
78
|
+
kind: string;
|
|
79
|
+
/** For `secret`, the parts of it the card may show, never the value. */
|
|
80
|
+
mask?: ApprovalCuaMask;
|
|
81
|
+
/** For `secret`, the scanner's open tag (`github_token`, `secret_named_value` and so on); a client words the tags it knows and shows any other as "a secret". */
|
|
82
|
+
secretKind?: string;
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
/** A secret's mask: a vendor token's prefix and last 4 characters (`ghp_…3f9a`), a named value's name and length (`password=… (12 chars)`), or the length alone; all absent names the kind only. */
|
|
86
|
+
export interface ApprovalCuaMask {
|
|
87
|
+
/** The secret's length in characters. */
|
|
88
|
+
chars?: number;
|
|
89
|
+
/** A vendor token's last 4 characters. */
|
|
90
|
+
last4?: string;
|
|
91
|
+
/** A vendor token's fixed prefix (`ghp_`), or a named value's name and its `=` (`password=`). */
|
|
92
|
+
prefix?: string;
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
/** The page's full host, no path or query. */
|
|
96
|
+
export interface ApprovalCuaPage {
|
|
97
|
+
/** The host in Unicode. */
|
|
98
|
+
host: string;
|
|
99
|
+
/** The host's `xn--` form; equal to `host` when they don't differ. */
|
|
100
|
+
hostAscii: string;
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
/** A point in the model's 0–1000 coordinates. */
|
|
104
|
+
export interface ApprovalCuaPoint {
|
|
105
|
+
x: number;
|
|
106
|
+
y: number;
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
/** One consequential step. A client renders "Step N: <action> <roleWord> "<label>" — <effect>"; a key step names its `chord`, and only a step with a `point` (and no label or chord) reads "at x,y". */
|
|
110
|
+
export interface ApprovalCuaStep {
|
|
111
|
+
/** The host's verb phrase, such as `click` or `type into`. */
|
|
112
|
+
action: string;
|
|
113
|
+
/** The chord, for a key step. */
|
|
114
|
+
chord?: string;
|
|
115
|
+
/** The host's trusted sentence for what the step may do. */
|
|
116
|
+
effect: string;
|
|
117
|
+
/** An open tag for styling and tests only (`verb:<class>`, `unresolved`, `unlabeled`); a client that doesn't know a value renders the step from `effect` and its label as usual. */
|
|
118
|
+
kind: string;
|
|
119
|
+
/** The control's label: the app's own text, shown quoted and as plain text; a client may cap it. */
|
|
120
|
+
label?: string;
|
|
121
|
+
/** The step's own 0–1000 model coordinates, only for a point step. */
|
|
122
|
+
point?: ApprovalCuaPoint;
|
|
123
|
+
/** `button`, `link`, `menu item` or `key`; absent for a point step. */
|
|
124
|
+
roleWord?: string;
|
|
125
|
+
/** 1-based, as the batch numbers its steps. */
|
|
126
|
+
step: number;
|
|
127
|
+
}
|
|
128
|
+
|
|
42
129
|
/** `approval/decide` params (tdd SS5.4): the decision. A standard SS3 command — requires the session loaded on this host, requires `commandId`, durable intake before ack, value-identical replay. */
|
|
43
130
|
export interface ApprovalDecideParams {
|
|
44
131
|
/** The approval being decided. */
|
|
@@ -67,6 +154,7 @@ export interface ApprovalDecideResult {
|
|
|
67
154
|
terminal: boolean;
|
|
68
155
|
}
|
|
69
156
|
|
|
157
|
+
/** The kind of decision a choice applies or an approval received. The set is open, so newer hosts may send values this version does not list. */
|
|
70
158
|
export type ApprovalDecision = "approved" | "approvedForSession" | "approvedPolicyAmendment" | "denied" | "deniedPolicyAmendment" | "timedOut" | "abort" | (string & {});
|
|
71
159
|
|
|
72
160
|
/** `approval/listPending` params (tdd SS5.7): the pull dual of the re-issued requests. A log-fold read — no lease, works on loaded and unloaded sessions, never subscribes. */
|
|
@@ -77,9 +165,9 @@ export interface ApprovalListPendingParams {
|
|
|
77
165
|
|
|
78
166
|
/** `approval/listPending` result (tdd SS5.7). Ordering is by opening `viewCursor`; empty arrays when nothing is pending. The result is point-in-time — to act on it race-safely, `approval/decide` carries the `requirementId` guard regardless of how the client learned the state. */
|
|
79
167
|
export interface ApprovalListPendingResult {
|
|
80
|
-
/** Exactly the `approval/request` params
|
|
168
|
+
/** Exactly the `approval/request` params, one per pending approval. */
|
|
81
169
|
approvals: ApprovalRequestParams[];
|
|
82
|
-
/** Exactly the `userInput/request` params
|
|
170
|
+
/** Exactly the `userInput/request` params, one per pending prompt. */
|
|
83
171
|
userInputs: UserInputRequestParams[];
|
|
84
172
|
}
|
|
85
173
|
|
|
@@ -92,93 +180,152 @@ export type ApprovalModeApplyOutcome = "completed" | "noop" | (string & {});
|
|
|
92
180
|
/** How an approval mode took effect (tdd SS5.12, the effective-mode projection's `source` vocabulary). Open. */
|
|
93
181
|
export type ApprovalModeSource = "startup" | "replay" | "approvalReconfigure" | (string & {});
|
|
94
182
|
|
|
183
|
+
/** What triggered a tool action, shown so the user can judge it. It is display-only and untrusted, and policy rules never match on it. */
|
|
95
184
|
export interface ApprovalOrigin {
|
|
185
|
+
/** The shell command whose process asked for the action. Present when `kind` is `shellCommand`. */
|
|
96
186
|
command?: string;
|
|
187
|
+
/** Which kind of origin this is: `shellCommand` or `url`. */
|
|
97
188
|
kind: string;
|
|
189
|
+
/** The full URL a fetch tool is requesting. Present when `kind` is `url`. */
|
|
98
190
|
url?: string;
|
|
99
191
|
}
|
|
100
192
|
|
|
193
|
+
/** The result of saving a granted rule to the local policy store. The set is open, so newer hosts may send other values. */
|
|
101
194
|
export type ApprovalPersistenceStatus = "succeeded" | "failed" | (string & {});
|
|
102
195
|
|
|
196
|
+
/** Whether an approval's final decision lets the action run. The set is open, so newer hosts may send other values. */
|
|
103
197
|
export type ApprovalPolicyResult = "allow" | "deny" | (string & {});
|
|
104
198
|
|
|
105
199
|
/** Full params shared by `approval/request` and `approval/requested`. */
|
|
106
200
|
export interface ApprovalRequestParams {
|
|
201
|
+
/** The approval's stable id. Match `approval/decide`, `approval/updated` and `approval/resolved` by it, never by the JSON-RPC request id, which belongs to one connection. */
|
|
107
202
|
approvalId: string;
|
|
203
|
+
/** The choices the server offers for the current requirement. Send the chosen one's `choiceId` in `approval/decide`; clients never build their own. */
|
|
108
204
|
availableChoices: ApprovalChoice[];
|
|
205
|
+
/** A Computer Use card's facts: the page, the window and each step that may have an effect, in the host's words; absent on every other approval. */
|
|
206
|
+
cuaCardFacts?: ApprovalCuaCardFacts;
|
|
207
|
+
/** The requirement the next decision must target; send it unchanged as `requirementId` in `approval/decide`. For `shell` it names the first stage still needing a decision; for other kinds its `sourceIndex` is 0. */
|
|
109
208
|
currentRequirementId: ApprovalRequirementRef;
|
|
209
|
+
/** The `toolCall` view item waiting on this approval. */
|
|
110
210
|
itemId: string;
|
|
211
|
+
/** `true` when the automated LLM judge saw this request first and handed it to a person without deciding. A display hint only. The host sends it as `false` when it re-issues the request after a restart or on `session/resume`; a re-send for a later stage keeps it. */
|
|
111
212
|
judgeEscalated: boolean;
|
|
213
|
+
/** `true` when this approval guards a write to a protected file. Only allow-once and reject choices are offered, and a decision is accepted only while at least one client is subscribed to the session. */
|
|
112
214
|
protectedWrite: boolean;
|
|
215
|
+
/** The tool call's arguments as a string, usually JSON. With `toolName`, it lets a client show a subject whose `kind` it does not recognize. */
|
|
113
216
|
rawArgs: string;
|
|
217
|
+
/** The owning session. For a subagent's approval shown on the parent, this is the parent session. */
|
|
114
218
|
sessionId: string;
|
|
219
|
+
/** The stored records this event was folded from: an opaque token clients must not interpret. */
|
|
115
220
|
sourceRange: SourceRange;
|
|
116
221
|
/** Present only for a child (native subagent) approval projected onto the parent session's plane (ADR 36182); parent-own approvals omit it. */
|
|
117
222
|
subagentOrigin?: ApprovalSubagentOrigin;
|
|
223
|
+
/** What the approval is for. Show a `kind` you do not recognize generically, and never auto-approve it. */
|
|
118
224
|
subject: ApprovalSubject;
|
|
225
|
+
/** The id of the task running the tool call. */
|
|
119
226
|
taskId: string;
|
|
227
|
+
/** The model provider's id for this tool call. */
|
|
120
228
|
toolCallId: string;
|
|
229
|
+
/** The name of the tool being called. */
|
|
121
230
|
toolName: string;
|
|
231
|
+
/** The turn whose tool call is waiting on this approval. */
|
|
122
232
|
turnId: string;
|
|
233
|
+
/** The cursor of the `approval/requested` event that opened this request. A re-send for a later stage keeps this cursor, so `view/page` at it returns the opening stage, which may be older than this payload. */
|
|
123
234
|
viewCursor: string;
|
|
124
235
|
}
|
|
125
236
|
|
|
126
|
-
/**
|
|
237
|
+
/** Identifies one requirement of an approval: for a `shell` approval, one stage. A client sends it back as `requirementId` in `approval/decide`, and a stale-requirement error names the current one. */
|
|
127
238
|
export interface ApprovalRequirementRef {
|
|
239
|
+
/** The approval this requirement belongs to. */
|
|
128
240
|
approvalId: string;
|
|
241
|
+
/** The requirement's index within the approval, counting from 0; an approval with a single requirement uses 0. */
|
|
129
242
|
sourceIndex: number;
|
|
130
243
|
}
|
|
131
244
|
|
|
132
245
|
/** Winning terminal returned to a losing `approval/decide` command. */
|
|
133
246
|
export interface ApprovalResolutionSummary {
|
|
247
|
+
/** The winning decision, as an `approval/resolved` decision value such as `approved` or `abort`. */
|
|
134
248
|
decision: string;
|
|
249
|
+
/** Who made the winning decision, such as `user`, `policy` or `llmJudge`. */
|
|
135
250
|
resolvedBy: string;
|
|
251
|
+
/** The view cursor of the winning `approval/resolved` event. */
|
|
136
252
|
viewCursor: string;
|
|
137
253
|
}
|
|
138
254
|
|
|
255
|
+
/** Who or what made an approval's final decision. The set is open, so newer hosts may send other values. */
|
|
139
256
|
export type ApprovalResolvedBy = "user" | "policy" | "llmJudge" | (string & {});
|
|
140
257
|
|
|
141
258
|
/** `approval/resolved` params: the first durable terminal decision. */
|
|
142
259
|
export interface ApprovalResolvedParams {
|
|
260
|
+
/** The policy rule the decision created. Present only when the decision created one. */
|
|
143
261
|
amendment?: ApprovalAmendment;
|
|
262
|
+
/** The approval that was decided. */
|
|
144
263
|
approvalId: string;
|
|
145
264
|
/** The decision time as RFC3339, projected from the durable `DecisionApplied` record's own stamp (ADR 45450 D3): optional on the wire so decoders tolerate its absence, always populated by current hosts. */
|
|
146
265
|
decidedAt?: string;
|
|
266
|
+
/** The `commandId` of the `approval/decide` command that won. Absent when no such command made the decision, for example a policy or LLM judge decision. */
|
|
147
267
|
decidedByCommandId?: string;
|
|
268
|
+
/** The final decision. */
|
|
148
269
|
decision: ApprovalDecision;
|
|
270
|
+
/** The `toolCall` view item this approval was holding. */
|
|
149
271
|
itemId: string;
|
|
272
|
+
/** Whether the final decision lets the action run (`allow`) or blocks it (`deny`). */
|
|
150
273
|
policyResult: ApprovalPolicyResult;
|
|
274
|
+
/** Who or what made the decision: `user`, `policy` or `llmJudge`. */
|
|
151
275
|
resolvedBy: ApprovalResolvedBy;
|
|
276
|
+
/** The owning session. */
|
|
152
277
|
sessionId: string;
|
|
278
|
+
/** The stored records this event was folded from: an opaque token clients must not interpret. */
|
|
153
279
|
sourceRange: SourceRange;
|
|
280
|
+
/** For a `shell` approval, how each stage was resolved when the decision became final. Empty for other subject kinds, and it can be empty for `shell` too. */
|
|
154
281
|
stageEvidence: ApprovalStageEvidence[];
|
|
155
282
|
/** Present only for a child (native subagent) approval projected onto the parent session's plane (ADR 36182); parent-own approvals omit it. */
|
|
156
283
|
subagentOrigin?: ApprovalSubagentOrigin;
|
|
284
|
+
/** The turn whose tool call this approval was holding. */
|
|
157
285
|
turnId: string;
|
|
286
|
+
/** This event's view cursor: opaque, and strictly increasing within the session. */
|
|
158
287
|
viewCursor: string;
|
|
159
288
|
}
|
|
160
289
|
|
|
290
|
+
/** One stage of a `shell` approval: a single command from the pipeline or command list, approved separately from the others. */
|
|
161
291
|
export interface ApprovalStage {
|
|
292
|
+
/** The stage's command words as parsed. When `argvComplete` is `false`, this can be a single unparsed piece of the command. */
|
|
162
293
|
argv: string[];
|
|
294
|
+
/** `true` when `argv` is the stage's complete command, known before it runs; `false` when part of it cannot be resolved ahead of time (for example a command substitution). A stage with `false` never has a `suggestedPrefix`. */
|
|
163
295
|
argvComplete: boolean;
|
|
296
|
+
/** This stage's 1-based position in the command; it equals `requirementId.sourceIndex + 1`. */
|
|
164
297
|
position: number;
|
|
298
|
+
/** This stage's requirement id. When it equals the approval's `currentRequirementId`, send it as `requirementId` in `approval/decide`. */
|
|
165
299
|
requirementId: ApprovalRequirementRef;
|
|
300
|
+
/** Whether this stage still needs a decision or, if not, how it was satisfied. */
|
|
166
301
|
resolution: ApprovalStageResolution;
|
|
302
|
+
/** A command prefix the host suggests always allowing in this workspace, present only when one can be taken from a fully parsed stage. `availableChoices` shows whether that grant is offered. */
|
|
167
303
|
suggestedPrefix?: ApprovalSuggestedPrefix;
|
|
304
|
+
/** The total number of stages in the command. */
|
|
168
305
|
totalStages: number;
|
|
169
306
|
}
|
|
170
307
|
|
|
308
|
+
/** How one stage of a `shell` approval was resolved when the decision became final. */
|
|
171
309
|
export interface ApprovalStageEvidence {
|
|
310
|
+
/** The stage's command words as parsed. */
|
|
172
311
|
argv: string[];
|
|
312
|
+
/** The stage's 1-based position in the command. */
|
|
173
313
|
position: number;
|
|
314
|
+
/** The stage's requirement id. */
|
|
174
315
|
requirementId: ApprovalRequirementRef;
|
|
316
|
+
/** How the stage was resolved at the final decision. */
|
|
175
317
|
resolution: ApprovalStageResolution;
|
|
318
|
+
/** The total number of stages in the command. */
|
|
176
319
|
totalStages: number;
|
|
177
320
|
}
|
|
178
321
|
|
|
322
|
+
/** Whether a shell stage still needs a decision, or how it was satisfied. Satisfied stages are included so a client can show progress. */
|
|
179
323
|
export interface ApprovalStageResolution {
|
|
324
|
+
/** The command prefix saved as an always-allow rule when this stage was approved. Present only when `kind` is `policyAmendment`. */
|
|
180
325
|
argvPrefix?: string[];
|
|
326
|
+
/** Free-form text naming the rule or mode that allowed the stage, for display or troubleshooting. Present only when `kind` is `policyAllow`. */
|
|
181
327
|
diagnostic?: string;
|
|
328
|
+
/** One of `unresolved`, `knownSafe`, `policyAllow`, `allowOnce` or `policyAmendment`. The set is open, so newer hosts may add values. */
|
|
182
329
|
kind: string;
|
|
183
330
|
}
|
|
184
331
|
|
|
@@ -194,37 +341,59 @@ export interface ApprovalSubagentOrigin {
|
|
|
194
341
|
|
|
195
342
|
/** Open approval subject union. Unknown kinds are rendered generically and never auto-approved by clients (tdd SS5.2). */
|
|
196
343
|
export interface ApprovalSubject {
|
|
344
|
+
/** The access asked for: `read` or `write` for `fileAccess`, `control` for `process`. Absent for other kinds. */
|
|
197
345
|
access?: string;
|
|
346
|
+
/** The full raw shell command. Present when `kind` is `shell`. */
|
|
198
347
|
command?: string;
|
|
348
|
+
/** The network host the tool wants to reach. Present when `kind` is `network`. */
|
|
199
349
|
host?: string;
|
|
200
350
|
/** Open discriminator: `shell | fileAccess | network | unixSocket | process | tool`. */
|
|
201
351
|
kind: string;
|
|
352
|
+
/** What triggered the action (a shell command or a URL), for display only and untrusted. It is not sent on `shell` subjects, and policy rules never match on it. */
|
|
202
353
|
origin?: ApprovalOrigin;
|
|
354
|
+
/** For `fileAccess`, the path the tool asked to access, normalized by the host (workspace-relative inside the workspace); for `unixSocket`, the exact resolved socket path, sent unescaped, so escape it before display. */
|
|
203
355
|
path?: string;
|
|
356
|
+
/** The network port, present only on `network` subjects that name one. A session grant made from a subject without a port covers every port. */
|
|
204
357
|
port?: number;
|
|
358
|
+
/** The network protocol, for example `https`. Present only on `network` subjects that name one. */
|
|
205
359
|
protocol?: string;
|
|
360
|
+
/** The shell command split into stages that are approved separately (the commands of a pipeline or command list), in order. Present on `shell` subjects; it may be empty. */
|
|
206
361
|
stages?: ApprovalStage[];
|
|
362
|
+
/** Display text naming the process the tool wants to control. Present when `kind` is `process`. */
|
|
207
363
|
target?: string;
|
|
364
|
+
/** The tool asking for the action. Present for every kind except `shell`. */
|
|
208
365
|
toolName?: string;
|
|
366
|
+
/** The canonical workspace root the shell command runs in, present on `shell` subjects when the host knows it. Saved command-prefix rules apply only within this root. */
|
|
209
367
|
workspaceRoot?: string;
|
|
210
368
|
}
|
|
211
369
|
|
|
370
|
+
/** A suggested always-allow rule for a shell stage: commands starting with `argvPrefix` would run in this workspace without asking. */
|
|
212
371
|
export interface ApprovalSuggestedPrefix {
|
|
372
|
+
/** The leading command words the rule would allow, for example `["cargo", "test"]`. */
|
|
213
373
|
argvPrefix: string[];
|
|
374
|
+
/** A human-readable label for the suggestion, ready to show as is. */
|
|
214
375
|
label: string;
|
|
215
376
|
}
|
|
216
377
|
|
|
217
378
|
/** `approval/updated` params: the refreshed pending view plus one change. */
|
|
218
379
|
export interface ApprovalUpdatedParams {
|
|
380
|
+
/** The approval that changed. */
|
|
219
381
|
approvalId: string;
|
|
382
|
+
/** The refreshed choices for the current requirement. */
|
|
220
383
|
availableChoices: ApprovalChoice[];
|
|
384
|
+
/** What changed; `change.kind` names the kind of change. */
|
|
221
385
|
change: ApprovalChange;
|
|
386
|
+
/** The requirement the next decision must target after this change; send it as `requirementId` in `approval/decide`. */
|
|
222
387
|
currentRequirementId: ApprovalRequirementRef;
|
|
388
|
+
/** The owning session. */
|
|
223
389
|
sessionId: string;
|
|
390
|
+
/** The stored records this event was folded from: an opaque token clients must not interpret. */
|
|
224
391
|
sourceRange: SourceRange;
|
|
225
392
|
/** Present only for a child (native subagent) approval projected onto the parent session's plane (ADR 36182); parent-own approvals omit it. */
|
|
226
393
|
subagentOrigin?: ApprovalSubagentOrigin;
|
|
394
|
+
/** The approval's subject, with `stages` refreshed for this change. */
|
|
227
395
|
subject: ApprovalSubject;
|
|
396
|
+
/** This event's view cursor: opaque, and strictly increasing within the session. */
|
|
228
397
|
viewCursor: string;
|
|
229
398
|
}
|
|
230
399
|
|
|
@@ -234,6 +403,26 @@ export type AttentionFlag = "approvalPending" | "inputPending" | (string & {});
|
|
|
234
403
|
/** Who durably backgrounded a task (tdd SS4.5.5, `TaskBackgroundedInitiator`). Open — runtime vocabulary. */
|
|
235
404
|
export type BackgroundInitiator = "user" | "timeout" | (string & {});
|
|
236
405
|
|
|
406
|
+
/** `backgroundTerminalCompletion`: the five facts the Finished cell renders (ADR 50041 D3/D4). The fold reads them from the inbox terminal record and the backgrounded call it names; every member is required (empty output serializes as `""`, never absent). */
|
|
407
|
+
export interface BackgroundTerminalCompletion {
|
|
408
|
+
/** The title text gate-off shows for the backgrounded command. */
|
|
409
|
+
command: string;
|
|
410
|
+
/** The completion text; empty when the terminal carries none. */
|
|
411
|
+
output: string;
|
|
412
|
+
/** True when `output` is a prefix of the terminal text. */
|
|
413
|
+
outputTruncated: boolean;
|
|
414
|
+
/** One of `completed`, `failed`, `cancelled`, `timedOut`, `rejected` (the ItemStatus wire vocabulary, tdd SS4.4.1). */
|
|
415
|
+
terminalStatus: string;
|
|
416
|
+
/** The backgrounded call's call id: the live/history correlation key behind the skip-when-minted rule (ADR 50041 D6). */
|
|
417
|
+
toolCallId: string;
|
|
418
|
+
}
|
|
419
|
+
|
|
420
|
+
/** The cold recall seed on `session/resume` and `session/read` results (ADR 50074 D2): at most one, the latest blocked Main prompt — exactly the host's mirror of `prompt_recovery::replay::ReplayInput`'s choice. */
|
|
421
|
+
export interface BlockedPrompt {
|
|
422
|
+
/** The exact submitted prompt, verbatim — no truncation, no normalization; recall fidelity requires exactness. */
|
|
423
|
+
text: string;
|
|
424
|
+
}
|
|
425
|
+
|
|
237
426
|
/** The latest branch observation in the snapshot (tdd SS4.6.4, SS4.9.1). */
|
|
238
427
|
export interface BranchState {
|
|
239
428
|
/** The observed branch; `null` on a detached-HEAD observation. */
|
|
@@ -244,9 +433,15 @@ export interface BranchState {
|
|
|
244
433
|
workspaceRoot: string;
|
|
245
434
|
}
|
|
246
435
|
|
|
247
|
-
/** A grantable capability name
|
|
436
|
+
/** A grantable capability name. Open: the experimental-only `rawLog` entry joins the stable domain as an additive open-enum extension when it graduates — closed would make that a retype. */
|
|
248
437
|
export type CapabilityName = "userShell" | "sessionMcp" | "sessionListStream" | "feedback" | "computerUseSetup" | "computerUseHostSetup" | "sessionRename" | (string & {});
|
|
249
438
|
|
|
439
|
+
/** A served checkpoint-prune boundary (spec 13929 amendment FR-50042-1; ADR 50042 D3): `through_item_id` names the last first-opened item that opened strictly before the boundary checkpoint event. */
|
|
440
|
+
export interface CheckpointBoundary {
|
|
441
|
+
/** The last pre-boundary item's id, in served (first-opened) order. */
|
|
442
|
+
throughItemId: string;
|
|
443
|
+
}
|
|
444
|
+
|
|
250
445
|
/** The client's requested capability posture (SS1.4.1). Every member defaults; an absent `capabilities` object means all defaults. */
|
|
251
446
|
export interface ClientCapabilities {
|
|
252
447
|
/** Opt into experimental methods, fields, and variants (default `false`). */
|
|
@@ -305,7 +500,7 @@ export interface CommandAcceptedResult {
|
|
|
305
500
|
status: CommandAckStatus;
|
|
306
501
|
}
|
|
307
502
|
|
|
308
|
-
/** The ack-status vocabulary
|
|
503
|
+
/** The ack-status vocabulary: `"accepted"` for every admitted command; `session/compact` alone may answer `"noop"`. Closed: the protocol defines exactly these two values, so SDK clients get a discriminated type and validation catches a wrong status — and a client that received a third value would have been told nothing it can act on, unlike [`TurnStartDisposition`], where "acked, not otherwise classified" is a usable reading. */
|
|
309
504
|
export type CommandAckStatus = "accepted" | "noop";
|
|
310
505
|
|
|
311
506
|
/** The SS3.1.2 ack `status`: `accepted` for every admitted command. `session/compact` is the one method that may additionally answer `noop` ([`crate::method::runtime::CompactStatus`]); no other command uses another status (tdd SS3.1.2). */
|
|
@@ -464,9 +659,9 @@ export interface ContextUsage {
|
|
|
464
659
|
windowTokens?: number;
|
|
465
660
|
}
|
|
466
661
|
|
|
467
|
-
/** Cron's `details` payload (ADR 42728 D2, thirteenth directive). Every field a family owns lives here, under the container's one `details` key, rather than flat beside the discriminators
|
|
662
|
+
/** Cron's `details` payload (ADR 42728 D2, thirteenth directive). Every field a family owns lives here, under the container's one `details` key, rather than flat beside the discriminators. Each is a **bounded machine fact**: scalars, short identifiers and a small fixed-shape array of those. */
|
|
468
663
|
export interface CronReceipt {
|
|
469
|
-
/** Cron `create` and `delete`: the job id. On `delete`'s `missing` arm this is the caller's own id echoed back
|
|
664
|
+
/** Cron `create` and `delete`: the job id. On `delete`'s `missing` arm this is the caller's own id echoed back — that arm has no server-side subject to name. On the `created` + `cancelled` pairing, this field also conveys the hidden fact: a job row was committed and will fire. */
|
|
470
665
|
jobId?: string;
|
|
471
666
|
/** Cron `list`: the served jobs in server order, `active` and `firing` rows only. */
|
|
472
667
|
jobs?: CronReceiptJob[];
|
|
@@ -474,7 +669,7 @@ export interface CronReceipt {
|
|
|
474
669
|
nextFireAtMs?: number;
|
|
475
670
|
}
|
|
476
671
|
|
|
477
|
-
/** One row of the Cron `list` receipt's `jobs` array (ADR 42728 D2). Server order, and **`active` + `firing` rows only
|
|
672
|
+
/** One row of the Cron `list` receipt's `jobs` array (ADR 42728 D2). Server order, and **`active` + `firing` rows only**. A small fixed-shape array of scalars, which is what keeps it a bounded machine fact. */
|
|
478
673
|
export interface CronReceiptJob {
|
|
479
674
|
/** The job's server-owned id. */
|
|
480
675
|
jobId: string;
|
|
@@ -490,7 +685,7 @@ export interface CumulativeCost {
|
|
|
490
685
|
usd: number;
|
|
491
686
|
}
|
|
492
687
|
|
|
493
|
-
/** Session running totals of counted-once usage (tdd SS4.6.5).
|
|
688
|
+
/** Session running totals of counted-once usage (tdd SS4.6.5). The cache splits and server-computed `cost` join the counters. The counters stay accumulate-only; `cost` is the documented exception — it may move either way on price re-adoption and is labeled estimate. `Copy` was dropped for the `cost` member. */
|
|
494
689
|
export interface CumulativeTokenUsage {
|
|
495
690
|
/** Cache-read tokens, session total (FR-41610-1): saturating sum of the per-completion splits; an absent split contributes 0. Additive-optional: absent on the wire reads as 0 and zero totals are omitted, so pre-feature bytes decode and re-encode identically. */
|
|
496
691
|
cacheReadTokens?: number;
|
|
@@ -546,11 +741,11 @@ export interface ErrorData {
|
|
|
546
741
|
alignedNextOffset?: number;
|
|
547
742
|
/** The rejected anchor value on `notFound`/`missingAnchor` and the `-32042` boundary arms (SS4.7.3, SS4.11); on `-32042` it is served as an explicit `null` when the request named no concrete anchor (spec 208 FM-005). */
|
|
548
743
|
anchor?: string | null;
|
|
549
|
-
/** Approval
|
|
744
|
+
/** Approval id on approval errors. */
|
|
550
745
|
approvalId?: string;
|
|
551
746
|
/** The stored output's availability on `outputUnavailable` — the durable `ToolOutputAvailability` value, read-time-derived when the durable record still says `available` (SS4.5.5; spec 208 FM-008). */
|
|
552
747
|
availability?: string;
|
|
553
|
-
/** The missing capability, on `capabilityRequired` errors. Typed on the grantable registry, so `rawLog`
|
|
748
|
+
/** The missing capability, on `capabilityRequired` errors. Typed on the grantable registry, so the experimental-only `rawLog` joins the stable domain as an additive open-enum extension when it graduates. */
|
|
554
749
|
capability?: CapabilityName;
|
|
555
750
|
/** The configured command-admission bound, on `backpressured` errors. */
|
|
556
751
|
capacity?: number;
|
|
@@ -560,7 +755,7 @@ export interface ErrorData {
|
|
|
560
755
|
commandId?: string;
|
|
561
756
|
/** Current stage token on `approvalRequirementStale`. */
|
|
562
757
|
currentRequirementId?: ApprovalRequirementRef;
|
|
563
|
-
/**
|
|
758
|
+
/** On `experimentalRequired` errors, the name of the experimental method, field or variant the request used, for example `turn/start.providerRequestOptions`. */
|
|
564
759
|
descriptor?: string;
|
|
565
760
|
/** Free-form additive detail. */
|
|
566
761
|
details?: Record<string, unknown>;
|
|
@@ -604,13 +799,13 @@ export interface ErrorData {
|
|
|
604
799
|
settlement?: UserInputSettlementSummary;
|
|
605
800
|
/** The rejected upload id on `uploadNotFound` (`-32038`, SS3.33). */
|
|
606
801
|
uploadId?: string;
|
|
607
|
-
/**
|
|
802
|
+
/** Prompt identity on user-input errors. */
|
|
608
803
|
userInputId?: string;
|
|
609
804
|
/** The blocked view position on `pageEventTooLarge` errors. */
|
|
610
805
|
viewCursor?: string;
|
|
611
806
|
}
|
|
612
807
|
|
|
613
|
-
/** A stable `error.data.kind` category
|
|
808
|
+
/** A stable `error.data.kind` category: camelCase, the value clients branch on. Open: new kinds are added as their methods land, and a new `kind` is additive only because this domain is declared open. */
|
|
614
809
|
export type ErrorKind = "parseError" | "invalidRequest" | "notInitialized" | "alreadyInitialized" | "methodNotFound" | "invalidParams" | "experimentalRequired" | "internal" | "pageEventTooLarge" | "outputResultTooLarge" | "overloaded" | "inputTooLarge" | "capabilityRequired" | "notFound" | "interrupted" | "cancelled" | "sessionNotFound" | "sessionInUse" | "sessionAmbiguous" | "forkBoundaryInvalid" | "sessionNotLoaded" | "sessionStreamMismatch" | "commandRejected" | "backpressured" | "skillNotFound" | "computerUseUnavailable" | "marketplaceNotFound" | "pluginNotFound" | "marketplaceAlreadyExists" | "pluginMutationsDisabled" | "uploadNotFound" | "viewTruncated" | "outputUnavailable" | "boundaryPruned" | "boundaryUnusable" | "noBoundary" | "approvalNotFound" | "approvalAlreadyResolved" | "approvalChoiceInvalid" | "approvalRequirementStale" | "approvalReviewerUnavailable" | "userInputNotFound" | "userInputAlreadySettled" | "userInputAnswerInvalid" | (string & {});
|
|
615
810
|
|
|
616
811
|
/** The `error` member of an error response (SS1.2 §2.4). */
|
|
@@ -699,7 +894,7 @@ export interface ForkProvenance {
|
|
|
699
894
|
|
|
700
895
|
/** The session goal block (tdd SS4.6.2, mirrors the runtime's goal state, camelCased). `status` and `percentComplete` are carried **verbatim** — out-of-contract status strings and >100 percents pass through; display clamping is the renderer's job. */
|
|
701
896
|
export interface Goal {
|
|
702
|
-
/**
|
|
897
|
+
/** Goal creation time, epoch milliseconds, verbatim from the durable row. Absent on blocks whose producer never carried it (tool-result adoptions, older logs); absence must never render as a fabricated zero. */
|
|
703
898
|
createdAtMs?: number;
|
|
704
899
|
/** Current work description, when present. */
|
|
705
900
|
currentWork?: string;
|
|
@@ -711,7 +906,7 @@ export interface Goal {
|
|
|
711
906
|
percentComplete: number;
|
|
712
907
|
/** Goal status, verbatim from the durable goal state (free string by design: out-of-contract values pass through). */
|
|
713
908
|
status: string;
|
|
714
|
-
/**
|
|
909
|
+
/** Last goal mutation time, epoch milliseconds, verbatim from the durable row. Same absence rule as `createdAtMs`. */
|
|
715
910
|
updatedAtMs?: number;
|
|
716
911
|
}
|
|
717
912
|
|
|
@@ -772,7 +967,7 @@ export interface GoalSetParams {
|
|
|
772
967
|
/** What history a lifecycle result actually served (tdd SS2.5.2). Open on the client side: report-what-was-served means a client treats an unknown mode as "page it yourself". */
|
|
773
968
|
export type HistoryMode = "anchoredSnapshot" | "inline" | "snapshot" | "none" | (string & {});
|
|
774
969
|
|
|
775
|
-
/** Why a result served `history.mode: "none"
|
|
970
|
+
/** Why a result served `history.mode: "none"`: the server's typed reason for serving no history. Open on the client side: an absent (older server) or unknown (newer server) value decodes conservatively as an unknown reason, and `viewCursor` text never substitutes for it. */
|
|
776
971
|
export type HistoryNoneReason = "excluded" | "cursorSuffix" | "historyBudget" | "projectionUnavailable" | "projectionReadLimit" | (string & {});
|
|
777
972
|
|
|
778
973
|
/** The `history` request preference of `session/resume` (tdd SS2.5.2). The forced values downgrade `anchored` → `inline` → `snapshot` → `none`; under `auto` the full rung order is anchoredSnapshot → inline → snapshot → elided snapshot → none. */
|
|
@@ -791,7 +986,7 @@ export interface HookCatalogEntry {
|
|
|
791
986
|
}
|
|
792
987
|
|
|
793
988
|
/** Hook event names (tdd SS3.26.1, ADR 33398 D7 item 2): the lowercase-first-letter spelling of every `HookEventKind::all()` variant. Open (server-produced result vocabulary, the #22785 enum-openness rule): a future event value is additive. */
|
|
794
|
-
export type HookEventName = "sessionStart" | "userPromptSubmit" | "preToolUse" | "permissionRequest" | "postToolUse" | "preCompact" | "postCompact" | "subagentStart" | "subagentStop" | "stop" | "sessionEnd" | "notification" | "postToolUseFailure" | "stopFailure" | "postToolBatch" | "interrupt" | "sessionFork" | "toolUseStart" |
|
|
989
|
+
export type HookEventName = "sessionStart" | "userPromptSubmit" | "preToolUse" | "permissionRequest" | "postToolUse" | "preLLMCall" | "postLLMCall" | "preCompact" | "postCompact" | "subagentStart" | "subagentStop" | "stop" | "sessionEnd" | "notification" | "postToolUseFailure" | "stopFailure" | "postToolBatch" | "interrupt" | "sessionFork" | "toolUseStart" | (string & {});
|
|
795
990
|
|
|
796
991
|
/** A hook row's origin (tdd SS3.26.1, ADR 33398 D7 item 1): the config `HookSourceKind` values plus plugin-contributed. Open (server-produced result vocabulary, the #22785 enum-openness rule): a future origin is additive. */
|
|
797
992
|
export type HookHandlerKind = "managed" | "user" | "project" | "plugin" | (string & {});
|
|
@@ -834,7 +1029,7 @@ export interface InitializeResult {
|
|
|
834
1029
|
platformFamily: PlatformFamily;
|
|
835
1030
|
/** Server operating system. */
|
|
836
1031
|
platformOs: PlatformOs;
|
|
837
|
-
/** Whether this host can enforce the sandbox
|
|
1032
|
+
/** Whether this host can enforce the sandbox. Optional so adding it stays backward compatible; a v1 host always sends it, and a client reads absent as unknown — the host predates the field, so the client falls back to its own probe rather than inventing an answer. */
|
|
838
1033
|
sandboxAvailability?: SandboxAvailability;
|
|
839
1034
|
/** Why enforcement is impossible. Sent only when `sandbox_availability` is `unavailable`; a client MUST NOT infer a reason when none is sent. */
|
|
840
1035
|
sandboxUnavailableReason?: SandboxUnavailableReason;
|
|
@@ -842,7 +1037,7 @@ export interface InitializeResult {
|
|
|
842
1037
|
schema: SchemaInfo;
|
|
843
1038
|
/** Server identification. */
|
|
844
1039
|
serverInfo: ServerInfo;
|
|
845
|
-
/** Whether this host persists its sessions
|
|
1040
|
+
/** Whether this host persists its sessions. Optional so adding it stays backward compatible; a v1 host always sends it, and a client reads absent as `durable` because no server that omits it has the ephemeral profile. */
|
|
846
1041
|
sessionDurability?: SessionDurability;
|
|
847
1042
|
/** Exact user-agent string presented to upstream model providers. */
|
|
848
1043
|
userAgent: string;
|
|
@@ -862,6 +1057,8 @@ export interface Item {
|
|
|
862
1057
|
background?: boolean;
|
|
863
1058
|
/** `toolCall`: who backgrounded the task; absent on pre-split records — never inferred (tdd SS4.5.5). */
|
|
864
1059
|
backgroundInitiator?: BackgroundInitiator;
|
|
1060
|
+
/** `backgroundTerminalCompletion`: the five facts the Finished cell renders (ADR 50041 D4). */
|
|
1061
|
+
backgroundTerminalCompletion?: BackgroundTerminalCompletion;
|
|
865
1062
|
/** `reminderChild`: `true` when this child is a blocking reminder (it holds the turn open until it settles); absent otherwise, never `false` (ADR 41191 D4). The status word stays off the wire; clients name the reminder from `reminderAgentId`. */
|
|
866
1063
|
blocking?: boolean;
|
|
867
1064
|
/** `toolCall`: the provider call id (`call_...`), opaque. */
|
|
@@ -894,7 +1091,7 @@ export interface Item {
|
|
|
894
1091
|
displayLabel?: ToolDisplayLabel;
|
|
895
1092
|
/** `userMessage`: presentation form (tdd SS3.2); absent when the client sent none. */
|
|
896
1093
|
displayText?: string;
|
|
897
|
-
/** `userShell`/`subagent`: observed wall-clock duration. `workflow`: the run's wall time from launch to reconciliation, set only on the settling `item/completed` — never a sum of child durations. */
|
|
1094
|
+
/** `userShell`/`subagent`: observed wall-clock duration. `workflow`: the run's wall time from launch to reconciliation, set only on the settling `item/completed` — never a sum of child durations. `toolCall`: the Backgrounded row's duration (ADR 50041 D11) — the open→update record delta in whole ms, served on the `backgroundStatus` re-emission and frozen there; absent otherwise. */
|
|
898
1095
|
durationMs?: number;
|
|
899
1096
|
/** `workflow`: launched entry identity. */
|
|
900
1097
|
entryId?: string;
|
|
@@ -956,6 +1153,8 @@ export interface Item {
|
|
|
956
1153
|
recordedAt?: string;
|
|
957
1154
|
/** `reminderChild`: the reminder agent's id. */
|
|
958
1155
|
reminderAgentId?: string;
|
|
1156
|
+
/** Monitor `toolCall`: the D26 hint verdict plus anchor (`ReplayHint`); absent means no hint. */
|
|
1157
|
+
replayHint?: ReplayHint;
|
|
959
1158
|
/** `subagent`: the result envelope from `ResultReady` (tdd SS4.5.7). */
|
|
960
1159
|
result?: SubagentResult;
|
|
961
1160
|
/** `workflow`: set on resumed launches. */
|
|
@@ -998,12 +1197,14 @@ export interface Item {
|
|
|
998
1197
|
strategyId?: string;
|
|
999
1198
|
/** `subagent`: durable child identity (`subagent_id`). */
|
|
1000
1199
|
subagentId?: string;
|
|
1001
|
-
/** `compaction`: opaque provenance string naming the compaction boundary.
|
|
1200
|
+
/** `compaction`: opaque provenance string naming the compaction boundary. Also a compaction-anchored read anchor, accepted by `session/resume` and `view/page`. Still opaque — clients relay it, never parse it. */
|
|
1002
1201
|
summarizedThrough?: string;
|
|
1003
1202
|
/** `reasoning`: one entry per summary part; part *n* streams via `item/delta` field `"summary.n"` (part boundary = index change). */
|
|
1004
1203
|
summary?: string[];
|
|
1005
1204
|
/** `reminderChild`: the linked task id. */
|
|
1006
1205
|
taskId?: string;
|
|
1206
|
+
/** Terminal `toolCall`: the item after whose rows the terminal row renders (tdd SS4.5.21, ADR 56496 D2/D3). */
|
|
1207
|
+
terminalRowAfterItemId?: string;
|
|
1007
1208
|
/** `userMessage`: the prompt text as submitted. `agentMessage`: the accumulated reply, streamed via `item/delta` field `"text"`. `reasoning`: raw committed reasoning text where the provider exposes it (never streamed in v1, tdd SS4.5.4). */
|
|
1008
1209
|
text?: string;
|
|
1009
1210
|
/** `workflow`: the run's launch token budget, set from the launch fact (tdd SS4.5.8, #45449); absent when the launch carried none. */
|
|
@@ -1028,6 +1229,8 @@ export interface Item {
|
|
|
1028
1229
|
usage?: TokenUsage;
|
|
1029
1230
|
/** `toolCall`/`userShell`: bounded transcript-visible result text (budget per tdd SS4.5.4); streams via `item/delta` field `"output"`. */
|
|
1030
1231
|
visibleOutput?: string;
|
|
1232
|
+
/** `toolCall`: the task's registered Work ID, verbatim (`work.v2.managed_bash.sha256.…`); present only when the task registered a ManagedBash id, absent otherwise (tdd SS4.5.5, ADR 50041 D20). Stable from day one: no `x-msp-stability` marker. The host serves it at the later of the task terminal and the inbox admission (D21); absence keeps the client's v1 derivation. */
|
|
1233
|
+
workId?: string;
|
|
1031
1234
|
/** `subagent`/`workflow`: the owning durable workflow run id (opaque string — not a UUID family). */
|
|
1032
1235
|
workflowRunId?: string;
|
|
1033
1236
|
}
|
|
@@ -1059,12 +1262,12 @@ export interface ItemDeltaParams {
|
|
|
1059
1262
|
}
|
|
1060
1263
|
|
|
1061
1264
|
/** The eleven v1 item kinds (tdd SS4.5.2–4.5.13) plus post-v1 kinds (tdd SS4.5.14+). Open: a new kind is additive evolution, and clients MUST render unknown kinds generically (tdd SS4.10). */
|
|
1062
|
-
export type ItemKind = "userMessage" | "agentMessage" | "reasoning" | "toolCall" | "userShell" | "subagent" | "workflow" | "reminderChild" | "compaction" | "hookRun" | "sideChat" | "webSearch" | "monitorFeed" | "damagedRange" | "scheduledFire" | (string & {});
|
|
1265
|
+
export type ItemKind = "userMessage" | "agentMessage" | "reasoning" | "toolCall" | "userShell" | "subagent" | "workflow" | "reminderChild" | "compaction" | "hookRun" | "sideChat" | "webSearch" | "monitorFeed" | "damagedRange" | "scheduledFire" | "backgroundTerminalCompletion" | "overdueNotice" | (string & {});
|
|
1063
1266
|
|
|
1064
1267
|
/** The `item/readOutput` content encoding (tdd SS4.7.4). Closed: text media is ALWAYS `utf8` and binary media `base64`; a third value would change the client's decode contract. */
|
|
1065
1268
|
export type ItemReadOutputEncoding = "utf8" | "base64";
|
|
1066
1269
|
|
|
1067
|
-
/** `item/readOutput` params
|
|
1270
|
+
/** `item/readOutput` params: byte-ranged fetch of stored full output that the view truncated, via the item's `outputRef`. Read-only; works on loaded and unloaded sessions; no lease. */
|
|
1068
1271
|
export interface ItemReadOutputParams {
|
|
1069
1272
|
/** The item whose stored output is fetched. */
|
|
1070
1273
|
itemId: string;
|
|
@@ -1147,7 +1350,7 @@ export interface MediaUploadParams {
|
|
|
1147
1350
|
chunkCount: number;
|
|
1148
1351
|
/** This chunk's 0-based position. */
|
|
1149
1352
|
chunkIndex: number;
|
|
1150
|
-
/** One per call
|
|
1353
|
+
/** One per call. While the host runs, replaying it with the same params returns the recorded receipt, and reusing it with different params is refused. After a host restart, start over under a new `uploadId`. */
|
|
1151
1354
|
commandId: string;
|
|
1152
1355
|
/** `video/mp4` or `video/quicktime`, matching `VideoInput`. */
|
|
1153
1356
|
mediaType: string;
|
|
@@ -1409,7 +1612,7 @@ export interface PendingApprovalPointer {
|
|
|
1409
1612
|
/** The `pendingRequests` discriminator (tdd SS2.5.2). Open enum, v1 values `approval` and `userInput`. */
|
|
1410
1613
|
export type PendingRequestKind = "approval" | "userInput" | (string & {});
|
|
1411
1614
|
|
|
1412
|
-
/** A late-joiner pointer at an unsettled server-initiated request (tdd SS2.5.2, SS2.2.1). The full payloads arrive as re-issued server-to-client requests right after a `session/resume` response (tdd SS5.6); `session/read` never re-issues them (tdd SS2.5.5).
|
|
1615
|
+
/** A late-joiner pointer at an unsettled server-initiated request (tdd SS2.5.2, SS2.2.1). The full payloads arrive as re-issued server-to-client requests right after a `session/resume` response (tdd SS5.6); `session/read` never re-issues them (tdd SS2.5.5). The protocol defines two kind-discriminated entry shapes (`{kind: "approval", approvalId, viewCursor}` / `{kind: "userInput", userInputId, viewCursor}`). This type is one flat object with both ids optional, as for `ApprovalSubject` and `TurnInputPart`, because the v1 model names no object-variant union; the serialized JSON is the same, but the published schema also accepts `{"kind":"approval","userInputId":…}` and an entry carrying no id at all. Unlike `TurnInputPart.type`, `kind` here is an OPEN enum. */
|
|
1413
1616
|
export interface PendingRequestPointer {
|
|
1414
1617
|
/** Present on an `approval` entry. */
|
|
1415
1618
|
approvalId?: string;
|
|
@@ -1431,7 +1634,7 @@ export interface PendingUserInputPointer {
|
|
|
1431
1634
|
viewCursor: string;
|
|
1432
1635
|
}
|
|
1433
1636
|
|
|
1434
|
-
/** The server runtime's platform family
|
|
1637
|
+
/** The server runtime's platform family; may differ from the client's. Closed: the protocol fixes the value set, so widening it is a deliberate, gate-visible protocol change rather than a silent addition (a later `Closed`→`Open` flip is itself additive). */
|
|
1435
1638
|
export type PlatformFamily = "unix" | "windows";
|
|
1436
1639
|
|
|
1437
1640
|
/** The server's operating system (SS1.4.1). Closed, for the same reason as [`PlatformFamily`]. */
|
|
@@ -1624,6 +1827,18 @@ export interface PluginMarketplaceUpdateParams {
|
|
|
1624
1827
|
/** A plugin row's source provenance (tdd SS3.26.2, ADR 33398 D7 item 3): camelCase of `PluginSourceProvenance`. Open (server-produced result vocabulary, the #22785 enum-openness rule): a future provenance is additive. */
|
|
1625
1828
|
export type PluginSource = "curated" | "marketplaceUserAdded" | "foreignImport" | "nativeLocal" | (string & {});
|
|
1626
1829
|
|
|
1830
|
+
/** One input still queued for delivery to a session (tdd SS2.5.5, ADR 63254-queued-inputs-on-read D2): the full message body plus its log record sequence, the delivery-order and re-read dedupe key, plus the run-log record id clients join served entries against record-seeded rows by. */
|
|
1831
|
+
export interface QueuedInput {
|
|
1832
|
+
/** The queued record's log sequence: delivery order, and the key clients deduplicate re-reads by. */
|
|
1833
|
+
sequence: number;
|
|
1834
|
+
/** The `SubagentInput` record's model-authored command id: the key wire-twin rows join by in either order (the twin reads the same string from the verbatim wire args). Absent for root own-queue members, which are never `SubagentInput`. */
|
|
1835
|
+
sourceCommandId?: string;
|
|
1836
|
+
/** The run-log record id the served mirror was taken from: the key clients join served entries against record-seeded rows by, so an already-rendered input never mints a second row under diverged sequences. Absent when the host's record carries no mirror metadata (a pre-feature host), which falls back to sequence-key dedup only. */
|
|
1837
|
+
sourceRunRecordId?: string;
|
|
1838
|
+
/** The full message body, verbatim (never truncated, never a summary). */
|
|
1839
|
+
text: string;
|
|
1840
|
+
}
|
|
1841
|
+
|
|
1627
1842
|
/** Typed quota-exhaustion detail (tdd SS4.5.1, ADR 50047 D2): the limit kind plus the provider's reset instant. */
|
|
1628
1843
|
export interface QuotaDetail {
|
|
1629
1844
|
/** Which quota was exhausted (open enum; unknown values fall back). */
|
|
@@ -1681,7 +1896,7 @@ export interface RecapCompletedParams {
|
|
|
1681
1896
|
/** `recap/completed` failure reason (tdd SS3.28.2/SS3.28.8): post-ack failures fold to the single initial value. **Open**: later splits stay additive (#22785 E2). */
|
|
1682
1897
|
export type RecapFailureReason = "providerFailed" | (string & {});
|
|
1683
1898
|
|
|
1684
|
-
/** `recap/completed` outcome
|
|
1899
|
+
/** `recap/completed` outcome: the terminal vocabulary, in camelCase. **Open**: a server-produced result vocabulary. */
|
|
1685
1900
|
export type RecapOutcome = "completed" | "failed" | "cancelled" | "timedOut" | (string & {});
|
|
1686
1901
|
|
|
1687
1902
|
/** `recap/request` params (tdd SS3.28.1): the session plus the client-minted UUIDv7 retry id. No other param; unknown fields are `invalidParams`. */
|
|
@@ -1730,6 +1945,12 @@ export type RecoveryObservedMode = "on" | "off" | "unknown" | (string & {});
|
|
|
1730
1945
|
/** This construction's assessment, never an operation acceptance receipt. */
|
|
1731
1946
|
export type RecoveryQualification = "qualified" | "unavailable" | "notRequired" | "unknown" | (string & {});
|
|
1732
1947
|
|
|
1948
|
+
/** The D26 first-tree-transition hint verdict plus anchor (tdd SS4.5.21, ADR 56496 D3): `rowKinds` is the open lowercase row-kind vocabulary the client formats through its shared kind-noun constructor; `afterItemId` is the item id after whose rows the hint renders. Both members always ride when the object does. */
|
|
1949
|
+
export interface ReplayHint {
|
|
1950
|
+
afterItemId: string;
|
|
1951
|
+
rowKinds: string[];
|
|
1952
|
+
}
|
|
1953
|
+
|
|
1733
1954
|
/** A request frame, either direction (SS1.2 §2.1). */
|
|
1734
1955
|
export interface Request {
|
|
1735
1956
|
/** Client-chosen id, unique among that client's in-flight requests. */
|
|
@@ -1778,7 +1999,7 @@ export interface ServerInfo {
|
|
|
1778
1999
|
|
|
1779
2000
|
/** The session object every lifecycle method returns or lists (tdd SS2.4). Additive-optional evolution applies: clients must ignore unknown fields. */
|
|
1780
2001
|
export interface Session {
|
|
1781
|
-
/** The `turnId` of the current foreground turn when `status` is `running`, and `null` when the session is idle (tdd SS2.4). **Required-nullable
|
|
2002
|
+
/** The `turnId` of the current foreground turn when `status` is `running`, and `null` when the session is idle (tdd SS2.4). **Required-nullable.** Every served `Session` carries the member: `null` when the session is idle or not loaded, the turn id when it is running. An optional-absent shape would publish it as plain `string` and reject every idle `Session` frame the host sends. */
|
|
1782
2003
|
activeTurnId: string | null;
|
|
1783
2004
|
/** The folded effective approval mode. **Additive-optional**: a Session object that omits it means the host has not folded a mode, which is why the index-derived `session/list` entry may legitimately omit it (tdd SS2.4, SS5.12). */
|
|
1784
2005
|
approvalMode?: EffectiveApprovalModeState;
|
|
@@ -1895,7 +2116,7 @@ export interface SessionCompactResult {
|
|
|
1895
2116
|
status: CompactStatus;
|
|
1896
2117
|
}
|
|
1897
2118
|
|
|
1898
|
-
/** The open configuration extension object shared by `session/start` and `session/resume` (ADR 32760 D1). Unknown keys are ignored on the wire, never rejected
|
|
2119
|
+
/** The open configuration extension object shared by `session/start` and `session/resume` (ADR 32760 D1). Unknown keys are ignored on the wire, never rejected: the live decoder tolerates them, and no exported bundle carries `additionalProperties: false`. The Rust typed model's `deny_unknown_fields` is internal and never exported — the closedness export applies nowhere, and the `x-msp-closed` opt-in mechanism stays inert. Recognized `mcpServers` values are typed and validated before they leave the wire boundary. */
|
|
1899
2120
|
export interface SessionConfig {
|
|
1900
2121
|
/** Native MCP servers added only to this session runtime. */
|
|
1901
2122
|
mcpServers?: Record<string, SessionMcpServerConfig>;
|
|
@@ -1958,6 +2179,8 @@ export interface SessionGoalChangedParams {
|
|
|
1958
2179
|
|
|
1959
2180
|
/** The `history` envelope shared by `session/resume`, `session/fork`, and `session/read` (tdd SS2.5.2). */
|
|
1960
2181
|
export interface SessionHistory {
|
|
2182
|
+
/** The checkpoint-prune boundary (spec 13929 amendment FR-50042-1): rows for served items at-or-before `through_item_id` in served order predate the selected checkpoint. Additive-optional; absence is a non-assertion (ADR 50042 D6). */
|
|
2183
|
+
checkpointBoundary?: CheckpointBoundary;
|
|
1961
2184
|
/** The full folded item array when `mode` is `inline`; `null` otherwise. */
|
|
1962
2185
|
items: Item[] | null;
|
|
1963
2186
|
/** What was actually served — never what was asked for (tdd SS2.5.2). */
|
|
@@ -1973,10 +2196,15 @@ export type SessionKind = "root" | "subagent" | (string & {});
|
|
|
1973
2196
|
|
|
1974
2197
|
/** Params of the protected, non-view leave terminal notification. */
|
|
1975
2198
|
export interface SessionLeaveCompletedParams {
|
|
2199
|
+
/** The leave command's id, matching the `session/leave` request. */
|
|
1976
2200
|
commandId: string;
|
|
2201
|
+
/** How the leave ended: `released` or `failed`. The set is open, so newer hosts may add outcomes. */
|
|
1977
2202
|
outcome: SessionLeaveOutcome;
|
|
2203
|
+
/** Why the leave failed. Present when `outcome` is `failed`. */
|
|
1978
2204
|
reason?: SessionLeaveFailureReason;
|
|
2205
|
+
/** The session the leave was for. */
|
|
1979
2206
|
sessionId: string;
|
|
2207
|
+
/** The session's view cursor at release: everything up to it was folded before the host let go. Present when `outcome` is `released`. */
|
|
1980
2208
|
viewCursor?: string;
|
|
1981
2209
|
}
|
|
1982
2210
|
|
|
@@ -1998,7 +2226,9 @@ export interface SessionLeaveParams {
|
|
|
1998
2226
|
|
|
1999
2227
|
/** The admission-only `session/leave` result. */
|
|
2000
2228
|
export interface SessionLeaveResult {
|
|
2229
|
+
/** The leave command's id. */
|
|
2001
2230
|
commandId: string;
|
|
2231
|
+
/** The admission status, `accepted` once the leave is admitted. The final result arrives later as `session/leaveCompleted`. Sending the same leave command again returns `accepted` and re-pushes the recorded result if there is one, from the host that ran the leave (for as long as it runs, even after the release) or from a host that has the session loaded (after a host crash, `abandoned` among them). Any other host treats it as a fresh leave: a durable host that has not loaded the session refuses it with `sessionNotLoaded` until it is resumed there. */
|
|
2002
2232
|
status: CommandAckStatus;
|
|
2003
2233
|
}
|
|
2004
2234
|
|
|
@@ -2030,7 +2260,7 @@ export interface SessionListParams {
|
|
|
2030
2260
|
cursor?: string | null;
|
|
2031
2261
|
/** Optional structured selection applied inside the bounded index query before paging (#42035, spec 207 FR-42035-1). Present — including `{}` — makes a supporting server echo its canonical form as `appliedFilter`; omitted keeps the pre-#42035 behavior. */
|
|
2032
2262
|
filter?: SessionListFilter;
|
|
2033
|
-
/** Page size; default 50, max 200 — the
|
|
2263
|
+
/** Page size; default 50, max 200 — the schema publishes the cap. Maximum 200. */
|
|
2034
2264
|
limit?: number;
|
|
2035
2265
|
/** Only sessions with log activity after this RFC3339 instant. */
|
|
2036
2266
|
updatedAfter?: string;
|
|
@@ -2139,12 +2369,16 @@ export interface SessionReadParams {
|
|
|
2139
2369
|
|
|
2140
2370
|
/** `session/read` result (tdd SS2.5.5). The `viewCursor` is the fold head at read time — a point-in-time read, immediately stale if a foreign host is appending. */
|
|
2141
2371
|
export interface SessionReadResult {
|
|
2372
|
+
/** Same member as `session/resume` (tdd SS2.5.5, ADR 50074 D2). */
|
|
2373
|
+
blockedPrompt?: BlockedPrompt;
|
|
2142
2374
|
/** The served history. */
|
|
2143
2375
|
history: SessionHistory;
|
|
2144
2376
|
/** Same member as `session/resume` (tdd SS2.5.5, ADR 36635 D2). */
|
|
2145
2377
|
lastTurn?: LastTurn;
|
|
2146
2378
|
/** The same pointer shape as `session/resume`. Because `session/read` never subscribes this is a point-in-time log read only: no requests are re-issued after it (tdd SS2.5.5). */
|
|
2147
2379
|
pendingRequests: PendingRequestPointer[];
|
|
2380
|
+
/** The inputs still queued for delivery to the read session (tdd SS2.5.5, ADR 63254-queued-inputs-on-read D2). Absent-when-empty: a missing member means nothing queued, never an error. */
|
|
2381
|
+
queuedInputs?: QueuedInput[];
|
|
2148
2382
|
/** Current local construction only; never inferred from retained history. Absence establishes neither a choice nor supported recovery. */
|
|
2149
2383
|
recoveryObservation?: RecoveryObservation;
|
|
2150
2384
|
/** The session as folded point-in-time. */
|
|
@@ -2155,7 +2389,7 @@ export interface SessionReadResult {
|
|
|
2155
2389
|
|
|
2156
2390
|
/** `session/reasoningEffortChanged` params (tdd SS4.6.9, ADR 31255 D1): a durable reasoning-effort reconfigure record landed (tdd SS3.21). Replace wholesale, latest wins; the snapshot carries the latest value (SS4.9.1). */
|
|
2157
2391
|
export interface SessionReasoningEffortChangedParams {
|
|
2158
|
-
/** The new session default: the closed eight-string tier vocabulary
|
|
2392
|
+
/** The new session default: the same closed eight-string tier vocabulary as `turn/start`. */
|
|
2159
2393
|
reasoningEffort: ReasoningEffort;
|
|
2160
2394
|
/** The owning session. */
|
|
2161
2395
|
sessionId: string;
|
|
@@ -2193,13 +2427,13 @@ export interface SessionResumeParams {
|
|
|
2193
2427
|
commandId: string;
|
|
2194
2428
|
/** The same open construction-time extension object as `session/start`. */
|
|
2195
2429
|
config?: SessionConfig;
|
|
2196
|
-
/** A view cursor previously observed by this client — or an observed `summarizedThrough` compaction anchor
|
|
2430
|
+
/** A view cursor previously observed by this client — or an observed `summarizedThrough` compaction anchor. When it names an event the server still holds, the server returns only the suffix and `history.mode` is `none`. A cursor the server minted that names no event yet, such as the empty start cursor of a session that had no events, is treated as no cursor: the server serves what a resume without a cursor would. A cursor older than the earliest event the server still holds gets a snapshot, or `-32040` `viewTruncated` when none fits. A cursor this session's view never minted is refused with `-32011` `notFound`, reason `missingAnchor`, and a compaction anchor naming a boundary the server has pruned is refused with `-32042` `boundaryPruned`. Omitted and explicit `null` both mean "no cursor". */
|
|
2197
2431
|
cursor?: string | null;
|
|
2198
2432
|
/** Return only session metadata and live resume state; page history separately with `view/page`. Default `false` (tdd SS2.5.2). */
|
|
2199
2433
|
excludeItems?: boolean;
|
|
2200
2434
|
/** History mode preference, default `auto`. A PREFERENCE, not a budget override: when the requested mode does not fit the history budget the server downgrades it and `history.mode` reports what was actually served (tdd SS2.5.2). Ignored when `cursor` or `excludeItems` makes it moot. */
|
|
2201
2435
|
history?: HistoryPreference;
|
|
2202
|
-
/** The launch permission-profile pick (amendment 42624 FR-42624-1, #50054): a profile id the host catalog already admits. Select, never create. Omitted
|
|
2436
|
+
/** The launch permission-profile pick (amendment 42624 FR-42624-1, #50054): a profile id the host catalog already admits. Select, never create. Omitted restores retained authority only, with no override. The host restores first, then applies the pick in the same pre-marker step; over a declared lost record the restore is the never-wider reset, committed before the pick, and where the reset cannot commit the pick is committed alone as that reset (spec 11237 FR-57059-4). A pick that fails admission refuses the resume `commandRejected` (-32030; `permission_profile_unknown` / `permission_profile_unavailable`) before any durable byte. Explicit `null` is invalid params (the same closed null-tolerant set as at start). */
|
|
2203
2437
|
permissionProfile?: string;
|
|
2204
2438
|
/** Cold-resume replacement choice; omission preserves the retained choice. A warm attach rejects a different or unestablished choice as invalidParams. Explicit null is invalid. */
|
|
2205
2439
|
recoveryMode?: RecoveryMode;
|
|
@@ -2209,6 +2443,8 @@ export interface SessionResumeParams {
|
|
|
2209
2443
|
|
|
2210
2444
|
/** `session/resume` result (tdd SS2.5.2). */
|
|
2211
2445
|
export interface SessionResumeResult {
|
|
2446
|
+
/** The recallable blocked prompt's refill text (ADR 50074 D2). **Additive-optional**; absence means no blocked prompt to recall (an unblocked session, or a pre-feature host). Data only, never a rendered row: clients seed cold recall from it (C-p refills `text`) and MUST NOT display it as history. */
|
|
2447
|
+
blockedPrompt?: BlockedPrompt;
|
|
2212
2448
|
/** The served history. */
|
|
2213
2449
|
history: SessionHistory;
|
|
2214
2450
|
/** How the last folded turn ended (tdd SS2.5.2, ADR 36635 D2). **Additive-optional**; absence is a non-assertion. */
|
|
@@ -2305,7 +2541,7 @@ export interface SessionStartParams {
|
|
|
2305
2541
|
approvalMode?: ApprovalMode | null;
|
|
2306
2542
|
/** The SS2.5 idempotency handle (UUIDv7). Required; the server never mints one. */
|
|
2307
2543
|
commandId: string;
|
|
2308
|
-
/** Reserved for per-session overrides
|
|
2544
|
+
/** Reserved for future per-session overrides; only its `mcpServers` member is admitted. */
|
|
2309
2545
|
config?: SessionConfig;
|
|
2310
2546
|
/** Initial model; server default when omitted. */
|
|
2311
2547
|
modelId?: string;
|
|
@@ -2588,7 +2824,7 @@ export interface SnapshotAnchor {
|
|
|
2588
2824
|
summarizedThrough: string;
|
|
2589
2825
|
}
|
|
2590
2826
|
|
|
2591
|
-
/** The complete folded view at the snapshot cursor (tdd SS4.9.1). Additive-optional evolution applies exactly as everywhere else; unknown members MUST be ignored, and preserved if re-serialized.
|
|
2827
|
+
/** The complete folded view at the snapshot cursor (tdd SS4.9.1). Additive-optional evolution applies exactly as everywhere else; unknown members MUST be ignored, and preserved if re-serialized. */
|
|
2592
2828
|
export interface SnapshotState {
|
|
2593
2829
|
/** The running foreground turn; `null` when none is running. */
|
|
2594
2830
|
activeTurn: TurnRef | null;
|
|
@@ -2596,7 +2832,7 @@ export interface SnapshotState {
|
|
|
2596
2832
|
approvalMode: EffectiveApprovalModeState;
|
|
2597
2833
|
/** Latest branch observation; `null` when no fact has landed. */
|
|
2598
2834
|
branch: BranchState | null;
|
|
2599
|
-
/** The latest `(windowTokens, usedTokens, pressure)` triple.
|
|
2835
|
+
/** The latest `(windowTokens, usedTokens, pressure)` triple. The protocol allows "`null`/absent" and its worked example OMITS the member; the binary omits it too, so this is the absent arm — the four siblings above are present-null in the same frame. A member is published as one or the other, never both. */
|
|
2600
2836
|
contextUsage?: ContextUsage;
|
|
2601
2837
|
/** Latest effective model; `null` when no fact has landed. */
|
|
2602
2838
|
effectiveModel: EffectiveModel | null;
|
|
@@ -2820,10 +3056,17 @@ export interface TaskCommandResult {
|
|
|
2820
3056
|
taskId: string;
|
|
2821
3057
|
}
|
|
2822
3058
|
|
|
2823
|
-
/**
|
|
3059
|
+
/** A task row's execution mode (tdd SS3.31, ADR 62268 D2). Open (server-produced result vocabulary, the #22785 enum-openness rule): clients MUST ignore unknown modes. */
|
|
3060
|
+
export type TaskExecutionMode = "foreground" | "background" | (string & {});
|
|
3061
|
+
|
|
3062
|
+
/** One task inventory row (tdd SS3.31). The row is the stable contract: `kind` and `status` stay open so a future state extends them without breaking clients. */
|
|
2824
3063
|
export interface TaskListEntry {
|
|
2825
3064
|
/** Who backgrounded the task, mirroring the item field. **Additive-optional**: absent on pre-split records and registry-only rows, never inferred. */
|
|
2826
3065
|
backgroundInitiator?: BackgroundInitiator;
|
|
3066
|
+
/** The raw command text: the joined `toolCall` item's `command` argument verbatim (ADR 62268 D2). **Additive-optional**: omitted when the row has no item or the item carries no command. Monitors join raw — clients redact (INV-17544-6). */
|
|
3067
|
+
command?: string;
|
|
3068
|
+
/** `"foreground" | "background"` (ADR 62268 D2). **Additive-optional**: absent means `"background"` (only pre-change hosts omit it, and those list background rows only); never guessed. */
|
|
3069
|
+
executionMode?: TaskExecutionMode;
|
|
2827
3070
|
/** What the workload is: `"tool"` or `"tool.*"` for item rows (the recorded kind when the registry records one, else `"tool"`); the recorded registry kind string verbatim for registry-only rows. Open vocabulary — clients MUST ignore unknown kinds. A `String`, not an enum: registry kind strings are unbounded. */
|
|
2828
3071
|
kind: string;
|
|
2829
3072
|
/** The host-known task start, RFC3339. **Additive-optional**: omitted, never guessed, when the host does not know it. */
|
|
@@ -2842,9 +3085,9 @@ export interface TaskListParams {
|
|
|
2842
3085
|
sessionId: string;
|
|
2843
3086
|
}
|
|
2844
3087
|
|
|
2845
|
-
/** `task/list` result (tdd SS3.31): one row per
|
|
3088
|
+
/** `task/list` result (tdd SS3.31): one row per live workload, background and foreground (ADR 62268 D1), oldest first; empty when nothing is running. */
|
|
2846
3089
|
export interface TaskListResult {
|
|
2847
|
-
/** The session's live
|
|
3090
|
+
/** The session's live task rows. */
|
|
2848
3091
|
tasks: TaskListEntry[];
|
|
2849
3092
|
}
|
|
2850
3093
|
|
|
@@ -3015,7 +3258,7 @@ export interface TurnForegroundCompletedParams {
|
|
|
3015
3258
|
viewCursor: string;
|
|
3016
3259
|
}
|
|
3017
3260
|
|
|
3018
|
-
/** One ordered content part of a turn submission (tdd SS3.2). File mentions are text, not a part type: write `@relative/path` in a text part. A structured `mention` part is reserved and currently rejected, and an unknown part type is `invalidParams` (tdd SS3.1.2, SS3.2) — which is what closes [`TurnInputPartType`]. Modelled as a discriminated flat object rather than a Rust `enum`, the convention [`crate::view::approval::ApprovalSubject`] already established for a wire union in this crate: the v1 schema model names no object-variant union shape and fails closed on one. The serialized JSON is the
|
|
3261
|
+
/** One ordered content part of a turn submission (tdd SS3.2). File mentions are text, not a part type: write `@relative/path` in a text part. A structured `mention` part is reserved and currently rejected, and an unknown part type is `invalidParams` (tdd SS3.1.2, SS3.2) — which is what closes [`TurnInputPartType`]. Modelled as a discriminated flat object rather than a Rust `enum`, the convention [`crate::view::approval::ApprovalSubject`] already established for a wire union in this crate: the v1 schema model names no object-variant union shape and fails closed on one. The serialized JSON is the same either way; what a flat object cannot express is "`mediaType` is required exactly when `type` is `image`". `height` may only appear together with `width`. `width` may only appear together with `height`. */
|
|
3019
3262
|
export interface TurnInputPart {
|
|
3020
3263
|
/** Free-text skill arguments, optional on a `skill` part — the wire twin of what the TUI accepts after the shortcut token (tdd SS3.22.3). */
|
|
3021
3264
|
arguments?: string;
|
|
@@ -3027,7 +3270,7 @@ export interface TurnInputPart {
|
|
|
3027
3270
|
mediaType?: string;
|
|
3028
3271
|
/** The skill to invoke, required on a `skill` part (tdd SS3.2, SS3.22.3; ADR 32471 D4): a bare or plugin-qualified shortcut token from `skill/list`. The HOST resolves and expands; an unknown selector is the typed `-32032 skillNotFound` request error. */
|
|
3029
3272
|
selector?: string;
|
|
3030
|
-
/** The picked copy's source, optional on a `skill` part
|
|
3273
|
+
/** The picked copy's source, optional on a `skill` part: one of the catalog rows' `source` values. When present the host resolves the exact `(selector, source)` row; when absent it resolves the selector, bare or plugin-qualified, against the session's skill catalog, as the TUI shortcut does. Closed: an unknown value is `invalidParams`, never a fall-through. */
|
|
3031
3274
|
source?: SkillInvocationSource;
|
|
3032
3275
|
/** User prompt text, on a `text` part. Multiple text parts are joined in order into the turn's prompt. */
|
|
3033
3276
|
text?: string;
|
|
@@ -3035,7 +3278,7 @@ export interface TurnInputPart {
|
|
|
3035
3278
|
type: TurnInputPartType;
|
|
3036
3279
|
/** The upload receipt, required on a `video` part (tdd SS3.2, SS3.33; ADR 45443 D5): the client-minted id `media/upload` echoed. */
|
|
3037
3280
|
uploadId?: string;
|
|
3038
|
-
/** Pixel width; must be provided together with `height` or not at all
|
|
3281
|
+
/** Pixel width; must be provided together with `height` or not at all. Published as a `dependentRequired` pair. */
|
|
3039
3282
|
width?: number;
|
|
3040
3283
|
}
|
|
3041
3284
|
|
|
@@ -3098,7 +3341,7 @@ export interface TurnRef {
|
|
|
3098
3341
|
displayText?: string;
|
|
3099
3342
|
/** `queuedTurns[]` only: set when `displayText` was cut to the committed-surface budget, mirroring `userMessage.truncated` (tdd SS4.5.2). Absent unless `true`. */
|
|
3100
3343
|
truncated?: boolean;
|
|
3101
|
-
/** The turn's id,
|
|
3344
|
+
/** The turn's id, minted at admission. */
|
|
3102
3345
|
turnId: string;
|
|
3103
3346
|
}
|
|
3104
3347
|
|
|
@@ -3264,7 +3507,7 @@ export interface TurnUserShell {
|
|
|
3264
3507
|
commandText: string;
|
|
3265
3508
|
}
|
|
3266
3509
|
|
|
3267
|
-
/** One element of a `view/page` result's `events` array: an **unframed view notification**
|
|
3510
|
+
/** One element of a `view/page` result's `events` array: an **unframed view notification** — the nested pair `{"method", "params"}`, which is the live notification minus `jsonrpc` and `emittedAtMs`, with nothing lifted out of `params` and nothing spliced into it. `view/page` and `muse exec --json` share this one definition, so the two surfaces cannot drift. */
|
|
3268
3511
|
export interface UnframedViewNotification {
|
|
3269
3512
|
/** The event type — the live notification's method name, retained because the type lives only in the notification name and would otherwise be lost (tdd SS4.2.1). */
|
|
3270
3513
|
method: string;
|
|
@@ -3272,7 +3515,7 @@ export interface UnframedViewNotification {
|
|
|
3272
3515
|
params: UnframedViewNotificationParams;
|
|
3273
3516
|
}
|
|
3274
3517
|
|
|
3275
|
-
/** The `params` of an unframed view notification (tdd SS4.2.1, SS4.2). Declares the
|
|
3518
|
+
/** The `params` of an unframed view notification (tdd SS4.2.1, SS4.2). Declares the base members every view notification carries, and stays **open** for the event-specific fields each event type adds. The v1 schema model names no method-correlated union (the `events` element's `params` arm is selected by its sibling `method`), so the per-event arms cannot be expressed here without one, and an uncorrelated union of them could reject a real page element, which a published schema must not do. `sourceRange` is required here and not optional: `view/page` serves durable-sourced events only (tdd SS4.7.3), and durable-sourced is *defined* as carrying a `sourceRange` — the SS4.2 ephemeral-sourced exemption applies to `item/delta`, which `view/page` never replays. */
|
|
3276
3519
|
export interface UnframedViewNotificationParams {
|
|
3277
3520
|
/** The owning session (tdd SS4.2). */
|
|
3278
3521
|
sessionId: string;
|
|
@@ -3291,15 +3534,21 @@ export interface UsageReadResult {
|
|
|
3291
3534
|
usage?: SubscriptionUsage;
|
|
3292
3535
|
}
|
|
3293
3536
|
|
|
3537
|
+
/** One question's answer, as sent in `userInput/answer` or `userInput/interrupt` and as recorded in `userInput/settled`. */
|
|
3294
3538
|
export interface UserInputAnswer {
|
|
3539
|
+
/** A free-form answer, at most 500 characters. */
|
|
3295
3540
|
freeText?: string;
|
|
3541
|
+
/** An optional comment the user adds to the answer, at most 500 characters. */
|
|
3296
3542
|
note?: string;
|
|
3543
|
+
/** The `id` of the question this answers. */
|
|
3297
3544
|
questionId: string;
|
|
3545
|
+
/** The label of the chosen option, for a `single` question. */
|
|
3298
3546
|
selectedLabel?: string;
|
|
3547
|
+
/** The labels of the chosen options for a `multiple` question, within its selection bounds; omitted when empty. */
|
|
3299
3548
|
selectedLabels?: string[];
|
|
3300
3549
|
}
|
|
3301
3550
|
|
|
3302
|
-
/** `userInput/answer` params (tdd SS5.10.2): answer every question. Each answer carries `questionId` then exactly one of `selectedLabel` (single mode), `selectedLabels` (multiple mode, within min/max bounds), or `freeText` (<=500 chars); plus an optional `note` (<=500). Answers that do not match the prompt fail -32057 `userInputAnswerInvalid`. Image `attachments` are a **reserved** field in v1, rejected if sent, because the blob-upload path they reference is reserved
|
|
3551
|
+
/** `userInput/answer` params (tdd SS5.10.2): answer every question. Each answer carries `questionId` then exactly one of `selectedLabel` (single mode), `selectedLabels` (multiple mode, within min/max bounds), or `freeText` (<=500 chars); plus an optional `note` (<=500). Answers that do not match the prompt fail -32057 `userInputAnswerInvalid`. Image `attachments` are a **reserved** field in v1, rejected if sent, because the blob-upload path they reference is also reserved. */
|
|
3303
3552
|
export interface UserInputAnswerParams {
|
|
3304
3553
|
/** One entry per question. */
|
|
3305
3554
|
answers: UserInputAnswer[];
|
|
@@ -3343,8 +3592,11 @@ export interface UserInputCancelResult {
|
|
|
3343
3592
|
userInputId: string;
|
|
3344
3593
|
}
|
|
3345
3594
|
|
|
3595
|
+
/** A free-form reply the user gives instead of choosing from the options; the model reads it and decides again. */
|
|
3346
3596
|
export interface UserInputClarification {
|
|
3597
|
+
/** The clarification text, at most 500 characters. */
|
|
3347
3598
|
content: string;
|
|
3599
|
+
/** The content format. `text` is the only value today, and more may be added. */
|
|
3348
3600
|
format: string;
|
|
3349
3601
|
}
|
|
3350
3602
|
|
|
@@ -3400,67 +3652,107 @@ export interface UserInputInterruptResult {
|
|
|
3400
3652
|
userInputId: string;
|
|
3401
3653
|
}
|
|
3402
3654
|
|
|
3655
|
+
/** One option offered for a question. */
|
|
3403
3656
|
export interface UserInputOption {
|
|
3657
|
+
/** An optional longer explanation of the option, at most 240 characters. */
|
|
3404
3658
|
description?: string;
|
|
3659
|
+
/** The option's text, at most 80 characters and unique within its question; an answer selects the option by this exact label. */
|
|
3405
3660
|
label: string;
|
|
3661
|
+
/** An optional rich preview of the option, present only on single-select questions. */
|
|
3406
3662
|
preview?: UserInputOptionPreview;
|
|
3407
3663
|
}
|
|
3408
3664
|
|
|
3665
|
+
/** Rich content a client can show for an option. Only single-select questions carry previews. */
|
|
3409
3666
|
export interface UserInputOptionPreview {
|
|
3667
|
+
/** The preview content in that format, at most 2000 characters. */
|
|
3410
3668
|
content: string;
|
|
3669
|
+
/** The content format, for example `markdown`. */
|
|
3411
3670
|
format: string;
|
|
3412
3671
|
}
|
|
3413
3672
|
|
|
3673
|
+
/** How a user-input prompt settled. More values may be added, so handle values you do not recognize. */
|
|
3414
3674
|
export type UserInputOutcome = "answered" | "cancelled" | "interrupted" | "clarified" | "timedOut" | "aborted" | (string & {});
|
|
3415
3675
|
|
|
3676
|
+
/** One question in a user-input prompt. */
|
|
3416
3677
|
export interface UserInputQuestion {
|
|
3678
|
+
/** A short title for the question, at most 12 characters. */
|
|
3417
3679
|
header: string;
|
|
3680
|
+
/** The question's id, unique within the prompt and at most 64 characters. An answer names it in `questionId`. */
|
|
3418
3681
|
id: string;
|
|
3682
|
+
/** The options offered, two or three, in order. */
|
|
3419
3683
|
options: UserInputOption[];
|
|
3684
|
+
/** The full question text to show the user. */
|
|
3420
3685
|
question: string;
|
|
3686
|
+
/** Whether the user picks one option or several. */
|
|
3421
3687
|
selection: UserInputSelection;
|
|
3422
3688
|
}
|
|
3423
3689
|
|
|
3424
3690
|
/** Full params shared by `userInput/request` and `userInput/requested`. */
|
|
3425
3691
|
export interface UserInputRequestParams {
|
|
3692
|
+
/** The auto-resolution time per question, in milliseconds: a prompt nobody engages with settles as `timedOut` after this value times the number of questions. */
|
|
3426
3693
|
autoResolutionMs?: number;
|
|
3694
|
+
/** The `toolCall` view item of the tool call waiting on this prompt. */
|
|
3427
3695
|
itemId: string;
|
|
3696
|
+
/** The questions to ask, one to three, in order. */
|
|
3428
3697
|
questions: UserInputQuestion[];
|
|
3698
|
+
/** The session that owns the prompt. */
|
|
3429
3699
|
sessionId: string;
|
|
3700
|
+
/** The stored records this prompt was folded from, when sent: an opaque token clients must not interpret. */
|
|
3430
3701
|
sourceRange?: SourceRange;
|
|
3702
|
+
/** The provider's id for the tool call that opened the prompt. */
|
|
3431
3703
|
toolCallId: string;
|
|
3704
|
+
/** The name of the tool that opened the prompt. */
|
|
3432
3705
|
toolName: string;
|
|
3706
|
+
/** The turn whose tool call is waiting on this prompt. */
|
|
3433
3707
|
turnId: string;
|
|
3708
|
+
/** The prompt's stable id. Pass it to `userInput/answer`, `userInput/cancel`, `userInput/clarify` and `userInput/interrupt`, and use it to match the later `userInput/settled`. */
|
|
3434
3709
|
userInputId: string;
|
|
3710
|
+
/** The cursor of the `userInput/requested` event for this prompt. A client that missed the request can read the same payload at this cursor with `view/page`. */
|
|
3435
3711
|
viewCursor: string;
|
|
3436
3712
|
}
|
|
3437
3713
|
|
|
3714
|
+
/** How many options the user may pick for a question. */
|
|
3438
3715
|
export interface UserInputSelection {
|
|
3716
|
+
/** The most options the user may pick. Sent only in `multiple` mode; when absent the maximum is the number of options. */
|
|
3439
3717
|
maxSelections?: number;
|
|
3718
|
+
/** The minimum selection count for a `multiple` answer. Sent only in `multiple` mode; when absent the minimum is 1. */
|
|
3440
3719
|
minSelections?: number;
|
|
3720
|
+
/** `single` or `multiple`: whether an answer selects one option or several. */
|
|
3441
3721
|
mode: UserInputSelectionMode;
|
|
3442
3722
|
}
|
|
3443
3723
|
|
|
3724
|
+
/** Whether a question takes one option or several. */
|
|
3444
3725
|
export type UserInputSelectionMode = "single" | "multiple";
|
|
3445
3726
|
|
|
3446
3727
|
/** `userInput/settled` params: the first durable prompt settlement. */
|
|
3447
3728
|
export interface UserInputSettledParams {
|
|
3729
|
+
/** The recorded answers: one per question for `answered`, any confirmed partial answers for `interrupted`, and empty for every other outcome. */
|
|
3448
3730
|
answers: UserInputAnswer[];
|
|
3731
|
+
/** The user's free-form clarification when the outcome is `clarified`; `null` otherwise. */
|
|
3449
3732
|
clarification: UserInputClarification | null;
|
|
3450
3733
|
/** The decision time as RFC3339, projected from the durable settlement record's own stamp (ADR 45450 D3, ruling 2026-10-01): always present on the wire (schema-required, `null`-able); decoders still tolerate its absence (`default`, never skipped — SS5.10.3 keeps every member present), and current hosts always populate it. */
|
|
3451
3734
|
decidedAt: string | null;
|
|
3735
|
+
/** The `commandId` of the client command that settled the prompt; `null` when no command did, for example after a timeout or an abort. */
|
|
3452
3736
|
decidedByCommandId: string | null;
|
|
3737
|
+
/** How the prompt ended. */
|
|
3453
3738
|
outcome: UserInputOutcome;
|
|
3739
|
+
/** The reason, when one applies: the optional reason given with a cancel, or why an `aborted` prompt was closed; `null` otherwise. */
|
|
3454
3740
|
reason: string | null;
|
|
3741
|
+
/** The session that owns the prompt. */
|
|
3455
3742
|
sessionId: string;
|
|
3743
|
+
/** The stored records this event was folded from: an opaque token clients must not interpret. */
|
|
3456
3744
|
sourceRange: SourceRange;
|
|
3745
|
+
/** The prompt that settled. Accept a settlement even for a prompt whose request you never saw. */
|
|
3457
3746
|
userInputId: string;
|
|
3747
|
+
/** This event's view cursor: opaque, and strictly increasing within the session. */
|
|
3458
3748
|
viewCursor: string;
|
|
3459
3749
|
}
|
|
3460
3750
|
|
|
3461
3751
|
/** Winning terminal returned to a late user-input command. */
|
|
3462
3752
|
export interface UserInputSettlementSummary {
|
|
3753
|
+
/** How the prompt settled, as a `userInput/settled` outcome value such as `answered` or `timedOut`. */
|
|
3463
3754
|
outcome: string;
|
|
3755
|
+
/** The view cursor of the `userInput/settled` event that recorded the settlement. */
|
|
3464
3756
|
viewCursor: string;
|
|
3465
3757
|
}
|
|
3466
3758
|
|
|
@@ -3477,10 +3769,10 @@ export interface ViewGapParams {
|
|
|
3477
3769
|
sessionId: string;
|
|
3478
3770
|
}
|
|
3479
3771
|
|
|
3480
|
-
/** The `view/page` request-mode anchor
|
|
3772
|
+
/** The `view/page` request-mode anchor. Declared **open**: the protocol spells it "open string enum, v1 value `latestCompaction`". */
|
|
3481
3773
|
export type ViewPageAnchor = "latestCompaction" | (string & {});
|
|
3482
3774
|
|
|
3483
|
-
/** The `view/page` paging direction
|
|
3775
|
+
/** The `view/page` paging direction. Closed: the protocol spells exactly two values and a third would change the paging contract. */
|
|
3484
3776
|
export type ViewPageDirection = "forward" | "backward";
|
|
3485
3777
|
|
|
3486
3778
|
/** `view/page` params (tdd SS4.7.3): cursor-paged reads of the session view. */
|
|
@@ -3491,7 +3783,7 @@ export interface ViewPageParams {
|
|
|
3491
3783
|
cursor?: string;
|
|
3492
3784
|
/** Paging direction; `forward` when omitted. */
|
|
3493
3785
|
direction?: ViewPageDirection;
|
|
3494
|
-
/** Maximum events to return, 1–1000. The server MAY return fewer
|
|
3786
|
+
/** Maximum events to return, 1–1000. The server MAY return fewer. The 1–1000 range is ratified and **published**: the model carries the bound and the bundle renders `minimum`/`maximum` instead of a bare `integer`. Range 1–1000 inclusive. */
|
|
3495
3787
|
limit: number;
|
|
3496
3788
|
/** The session to page. */
|
|
3497
3789
|
sessionId: string;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@muse-code/sdk",
|
|
3
|
-
"version": "1.4.
|
|
3
|
+
"version": "1.4.13",
|
|
4
4
|
"description": "TypeScript SDK for the Muse Session Protocol (MSP): connect to a Muse Code session, drive turns, and fold the event stream. Zero runtime dependencies.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"homepage": "https://github.com/meta-models/muse-code-sdk",
|