@muse-code/sdk 1.4.10 → 1.4.11
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +39 -1
- package/dist/src/facade/approval.d.ts +36 -16
- package/dist/src/facade/approval.js +39 -14
- package/dist/src/facade/client.d.ts +17 -1
- package/dist/src/facade/client.js +40 -5
- package/dist/src/facade/gap-fill.js +7 -2
- package/dist/src/facade/session.d.ts +12 -2
- package/dist/src/facade/session.js +86 -4
- package/dist/src/fingerprint.d.ts +1 -1
- package/dist/src/fingerprint.js +1 -1
- package/dist/src/fold/session-fold.d.ts +37 -4
- package/dist/src/fold/session-fold.js +18 -0
- package/dist/src/msp.d.ts +165 -7
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -8,6 +8,9 @@ agent over the Muse Session Protocol (MSP).
|
|
|
8
8
|
server-authored outcome.
|
|
9
9
|
- Answer tool-approval requests with a handler you register — or register
|
|
10
10
|
none and run under the server's own default-deny.
|
|
11
|
+
- Answer the agent's questions: list them with
|
|
12
|
+
`session.fold.pendingUserInputs()` and answer with
|
|
13
|
+
`session.answerUserInput`.
|
|
11
14
|
- A client-side fold keeps a live, typed view of the session — items, session
|
|
12
15
|
state, pending commands — with gap recovery after dropped deliveries and
|
|
13
16
|
safe same-command retry that can never double-submit.
|
|
@@ -75,8 +78,43 @@ session.onApproval(async (request) => ({
|
|
|
75
78
|
}));
|
|
76
79
|
```
|
|
77
80
|
|
|
81
|
+
An approval still pending when you resume a session arrives right after the
|
|
82
|
+
resume reply, so pass the handler to `resumeSession` itself:
|
|
83
|
+
|
|
84
|
+
```ts
|
|
85
|
+
const session = await client.resumeSession({
|
|
86
|
+
sessionId,
|
|
87
|
+
onApproval: async (request) => ({
|
|
88
|
+
choiceId: request.availableChoices[0].choiceId,
|
|
89
|
+
}),
|
|
90
|
+
onApprovalError: (failure) => console.error(failure.kind, failure.approvalId),
|
|
91
|
+
});
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Pass `onApprovalError` there too: a failure for an approval that arrived with
|
|
95
|
+
the resume reply can happen before `resumeSession` returns, so
|
|
96
|
+
`session.onApprovalError` would be too late to hear it. That covers a handler
|
|
97
|
+
that throws, picks a choice that was not offered, or adds feedback to a choice
|
|
98
|
+
that takes none (which is then answered with the reject choice).
|
|
99
|
+
|
|
100
|
+
To answer a question the agent asks, read it from
|
|
101
|
+
`session.fold.pendingUserInputs()` and answer it with `session.answerUserInput`,
|
|
102
|
+
one answer per question: `selectedLabel` for a single-select question,
|
|
103
|
+
`selectedLabels` for a multiple-select one, or `freeText`. The question leaves
|
|
104
|
+
the list when the server settles it:
|
|
105
|
+
|
|
106
|
+
```ts
|
|
107
|
+
const [prompt] = session.fold.pendingUserInputs();
|
|
108
|
+
const [question] = prompt?.questions ?? [];
|
|
109
|
+
if (prompt !== undefined && question !== undefined) {
|
|
110
|
+
await session.answerUserInput(prompt.userInputId, [
|
|
111
|
+
{ questionId: question.id, selectedLabel: "Yes" },
|
|
112
|
+
]);
|
|
113
|
+
}
|
|
114
|
+
```
|
|
115
|
+
|
|
78
116
|
Status: developer preview. The facade — spawn, session open/resume, turns,
|
|
79
|
-
approvals, and recovery after dropped deliveries — is complete and covered by
|
|
117
|
+
approvals, questions, and recovery after dropped deliveries — is complete and covered by
|
|
80
118
|
the conformance suites in the source repository.
|
|
81
119
|
|
|
82
120
|
## Documentation
|
|
@@ -1,16 +1,18 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* The FR-019 approval round trip: inbound `approval/requested`
|
|
3
|
-
* handler → outbound `approval/decide`
|
|
2
|
+
* The FR-019 approval round trip: inbound `approval/requested` or
|
|
3
|
+
* `approval/request` → the consumer's handler → outbound `approval/decide`
|
|
4
|
+
* (spec 14990 T031, FR-53910-1, tdd SS5.4).
|
|
4
5
|
*
|
|
5
6
|
* Split out of `session.ts` rather than added to it: the router owns a handler,
|
|
6
7
|
* a per-stage latch, and a decision-shaping guard chain that have nothing to do
|
|
7
8
|
* with folding a view, and `Session` was already the package's largest module.
|
|
8
9
|
*
|
|
9
|
-
*
|
|
10
|
-
*
|
|
11
|
-
*
|
|
12
|
-
*
|
|
13
|
-
*
|
|
10
|
+
* Two frames carry a request in: the `approval/requested` notification and the
|
|
11
|
+
* enrolled `approval/request` server request (`RequestReceipt`), which the host
|
|
12
|
+
* sends beside it and re-sends after a resume (tdd SS5.6). A client-owned
|
|
13
|
+
* connection routes both here (ADR 42116 D18), and the per-stage latch decides
|
|
14
|
+
* each stage once, whichever arrives first. The decision goes out as the
|
|
15
|
+
* `approval/decide` command FR-019 names.
|
|
14
16
|
*/
|
|
15
17
|
import type { Connection } from "../connection/connection.js";
|
|
16
18
|
import type { DeepReadonly } from "../fold/session-fold.js";
|
|
@@ -32,15 +34,31 @@ export type ApprovalHandler = (request: ApprovalRequestParams) => ApprovalDecisi
|
|
|
32
34
|
*
|
|
33
35
|
* REPORTED, not thrown: the trip is driven from a notification, so a throw
|
|
34
36
|
* would escape into the consumer's pump with nothing to catch it — the same
|
|
35
|
-
* hazard `Session.apply` already refuses a malformed frame for. Each
|
|
36
|
-
*
|
|
37
|
-
* because the repair
|
|
37
|
+
* hazard `Session.apply` already refuses a malformed frame for. Each kind names
|
|
38
|
+
* whose repair it is (the consumer's handler; the consumer's choice, for
|
|
39
|
+
* `unofferedChoice` and `feedbackNotAccepted`; the host), because the repair
|
|
40
|
+
* differs.
|
|
38
41
|
*/
|
|
39
42
|
export type ApprovalFailure = {
|
|
40
43
|
readonly kind: "unofferedChoice";
|
|
41
44
|
readonly approvalId: string;
|
|
42
45
|
readonly choiceId: string;
|
|
43
46
|
readonly availableChoiceIds: readonly string[];
|
|
47
|
+
}
|
|
48
|
+
/**
|
|
49
|
+
* The handler attached `feedback` to a choice whose `acceptsFeedback` is not
|
|
50
|
+
* true. The host would refuse that decision, so it is not sent; the offered
|
|
51
|
+
* reject (the `denied` choice, else the `abort` one) is sent next, so the
|
|
52
|
+
* approval closes. With neither offered, nothing is sent and the approval
|
|
53
|
+
* stays open; a failure to send the reject is reported as `submitFailed`.
|
|
54
|
+
* Next time, answer without feedback, or pick one of `feedbackChoiceIds`, the
|
|
55
|
+
* offered choices that accept it.
|
|
56
|
+
*/
|
|
57
|
+
| {
|
|
58
|
+
readonly kind: "feedbackNotAccepted";
|
|
59
|
+
readonly approvalId: string;
|
|
60
|
+
readonly choiceId: string;
|
|
61
|
+
readonly feedbackChoiceIds: readonly string[];
|
|
44
62
|
} | {
|
|
45
63
|
readonly kind: "handlerThrew";
|
|
46
64
|
readonly approvalId: string;
|
|
@@ -66,8 +84,9 @@ export declare class ApprovalRouter {
|
|
|
66
84
|
/** Observe round trips that did not complete. See {@link ApprovalFailure}. */
|
|
67
85
|
onApprovalError(handler: ApprovalFailureHandler): void;
|
|
68
86
|
/**
|
|
69
|
-
* An `approval/requested`
|
|
70
|
-
*
|
|
87
|
+
* An `approval/requested` the fold kept pending, or a routed `approval/request`
|
|
88
|
+
* (FR-53910-1). Returns the decision round trip to await, or `undefined` when
|
|
89
|
+
* this client authors nothing for it.
|
|
71
90
|
*
|
|
72
91
|
* No handler at all is the supported default posture, NOT a degraded one
|
|
73
92
|
* (D-008): the client runs under the server's own default-deny, and this SDK
|
|
@@ -79,10 +98,11 @@ export declare class ApprovalRouter {
|
|
|
79
98
|
*
|
|
80
99
|
* A multi-stage approval advances `currentRequirementId` through this frame
|
|
81
100
|
* ALONE on the notification plane — the SS5.6 item-3 re-issue on stage
|
|
82
|
-
* advance is the
|
|
83
|
-
*
|
|
84
|
-
* `
|
|
85
|
-
*
|
|
101
|
+
* advance is the `approval/request` server request, which reaches this
|
|
102
|
+
* router only through `Session.apply` (a `MuseClient`-owned connection
|
|
103
|
+
* delivers it; a bare `Connection` answers it `-32601`) — so waiting for a
|
|
104
|
+
* re-issued `approval/requested` notification leaves the new stage undecided
|
|
105
|
+
* and the turn pending forever.
|
|
86
106
|
*
|
|
87
107
|
* The update alone carries none of the request-shape members the handler is
|
|
88
108
|
* typed on, but the fold retains the original request and every identity
|
|
@@ -1,16 +1,18 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* The FR-019 approval round trip: inbound `approval/requested`
|
|
3
|
-
* handler → outbound `approval/decide`
|
|
2
|
+
* The FR-019 approval round trip: inbound `approval/requested` or
|
|
3
|
+
* `approval/request` → the consumer's handler → outbound `approval/decide`
|
|
4
|
+
* (spec 14990 T031, FR-53910-1, tdd SS5.4).
|
|
4
5
|
*
|
|
5
6
|
* Split out of `session.ts` rather than added to it: the router owns a handler,
|
|
6
7
|
* a per-stage latch, and a decision-shaping guard chain that have nothing to do
|
|
7
8
|
* with folding a view, and `Session` was already the package's largest module.
|
|
8
9
|
*
|
|
9
|
-
*
|
|
10
|
-
*
|
|
11
|
-
*
|
|
12
|
-
*
|
|
13
|
-
*
|
|
10
|
+
* Two frames carry a request in: the `approval/requested` notification and the
|
|
11
|
+
* enrolled `approval/request` server request (`RequestReceipt`), which the host
|
|
12
|
+
* sends beside it and re-sends after a resume (tdd SS5.6). A client-owned
|
|
13
|
+
* connection routes both here (ADR 42116 D18), and the per-stage latch decides
|
|
14
|
+
* each stage once, whichever arrives first. The decision goes out as the
|
|
15
|
+
* `approval/decide` command FR-019 names.
|
|
14
16
|
*/
|
|
15
17
|
/**
|
|
16
18
|
* Every `DecideParams` member the guard chain below forwards. Composition alone
|
|
@@ -108,8 +110,9 @@ export class ApprovalRouter {
|
|
|
108
110
|
this.#onFailure = handler;
|
|
109
111
|
}
|
|
110
112
|
/**
|
|
111
|
-
* An `approval/requested`
|
|
112
|
-
*
|
|
113
|
+
* An `approval/requested` the fold kept pending, or a routed `approval/request`
|
|
114
|
+
* (FR-53910-1). Returns the decision round trip to await, or `undefined` when
|
|
115
|
+
* this client authors nothing for it.
|
|
113
116
|
*
|
|
114
117
|
* No handler at all is the supported default posture, NOT a degraded one
|
|
115
118
|
* (D-008): the client runs under the server's own default-deny, and this SDK
|
|
@@ -133,10 +136,11 @@ export class ApprovalRouter {
|
|
|
133
136
|
*
|
|
134
137
|
* A multi-stage approval advances `currentRequirementId` through this frame
|
|
135
138
|
* ALONE on the notification plane — the SS5.6 item-3 re-issue on stage
|
|
136
|
-
* advance is the
|
|
137
|
-
*
|
|
138
|
-
* `
|
|
139
|
-
*
|
|
139
|
+
* advance is the `approval/request` server request, which reaches this
|
|
140
|
+
* router only through `Session.apply` (a `MuseClient`-owned connection
|
|
141
|
+
* delivers it; a bare `Connection` answers it `-32601`) — so waiting for a
|
|
142
|
+
* re-issued `approval/requested` notification leaves the new stage undecided
|
|
143
|
+
* and the turn pending forever.
|
|
140
144
|
*
|
|
141
145
|
* The update alone carries none of the request-shape members the handler is
|
|
142
146
|
* typed on, but the fold retains the original request and every identity
|
|
@@ -223,7 +227,8 @@ export class ApprovalRouter {
|
|
|
223
227
|
return;
|
|
224
228
|
}
|
|
225
229
|
const availableChoiceIds = params.availableChoices.map((choice) => choice.choiceId);
|
|
226
|
-
|
|
230
|
+
const chosen = params.availableChoices.find((choice) => choice.choiceId === decision.choiceId);
|
|
231
|
+
if (chosen === undefined) {
|
|
227
232
|
// D-006 select-never-create, enforced on THIS side of the transport. An
|
|
228
233
|
// invented choice bounces -32052 a round trip later, by which time the
|
|
229
234
|
// stage may have advanced — so the diagnosis a consumer would actually
|
|
@@ -237,6 +242,26 @@ export class ApprovalRouter {
|
|
|
237
242
|
});
|
|
238
243
|
return;
|
|
239
244
|
}
|
|
245
|
+
if (decision.feedback != null && chosen.acceptsFeedback !== true) {
|
|
246
|
+
// The host refuses feedback on any other choice (-32052) and keeps its
|
|
247
|
+
// approval open, so refuse it here and answer with the offered reject
|
|
248
|
+
// instead, the choice the Rust SDK sends too: the approval closes and
|
|
249
|
+
// the host's turn goes on. With neither a `denied` nor an `abort`
|
|
250
|
+
// choice, nothing is sent.
|
|
251
|
+
this.#report({
|
|
252
|
+
approvalId: params.approvalId,
|
|
253
|
+
choiceId: decision.choiceId,
|
|
254
|
+
feedbackChoiceIds: params.availableChoices
|
|
255
|
+
.filter((choice) => choice.acceptsFeedback === true)
|
|
256
|
+
.map((choice) => choice.choiceId),
|
|
257
|
+
kind: "feedbackNotAccepted",
|
|
258
|
+
});
|
|
259
|
+
const reject = params.availableChoices.find((choice) => choice.decision === "denied") ??
|
|
260
|
+
params.availableChoices.find((choice) => choice.decision === "abort");
|
|
261
|
+
if (reject === undefined)
|
|
262
|
+
return;
|
|
263
|
+
decision = { choiceId: reject.choiceId };
|
|
264
|
+
}
|
|
240
265
|
const decideParams = {
|
|
241
266
|
approvalId: params.approvalId,
|
|
242
267
|
choiceId: decision.choiceId,
|
|
@@ -38,6 +38,7 @@
|
|
|
38
38
|
import type { Connection } from "../connection/connection.js";
|
|
39
39
|
import type { ExitClassification, SpawnedMspConnection } from "../connection/spawn.js";
|
|
40
40
|
import type { SessionDurabilityProfile } from "./host-death.js";
|
|
41
|
+
import type { ApprovalFailureHandler, ApprovalHandler } from "./approval.js";
|
|
41
42
|
import { Session } from "./session.js";
|
|
42
43
|
import type { InitializeParams, InitializeResult, SessionResumeParams, SessionStartParams } from "../msp.js";
|
|
43
44
|
/**
|
|
@@ -58,7 +59,22 @@ export type StartSessionOptions = Readonly<Omit<SessionStartParams, "commandId"
|
|
|
58
59
|
requirePermissionProfile?: boolean;
|
|
59
60
|
}>;
|
|
60
61
|
/** Caller-facing options for `session/resume` (tdd SS2.5.2). */
|
|
61
|
-
export type ResumeSessionOptions = Readonly<Omit<SessionResumeParams, "commandId" | "config"
|
|
62
|
+
export type ResumeSessionOptions = Readonly<Omit<SessionResumeParams, "commandId" | "config"> & {
|
|
63
|
+
/**
|
|
64
|
+
* Answers this session's approvals from its first frame, so an approval
|
|
65
|
+
* the host re-sends right after the resume reply reaches it. The same
|
|
66
|
+
* contract as `session.onApproval`, installed before the frames that
|
|
67
|
+
* arrived with the reply are applied.
|
|
68
|
+
*/
|
|
69
|
+
onApproval?: ApprovalHandler;
|
|
70
|
+
/**
|
|
71
|
+
* Hears this session's approval failures from its first frame, as
|
|
72
|
+
* `session.onApprovalError` does later. A failure for an approval that
|
|
73
|
+
* arrived with the resume reply can happen before `resumeSession` returns,
|
|
74
|
+
* so only this option is sure to hear it.
|
|
75
|
+
*/
|
|
76
|
+
onApprovalError?: ApprovalFailureHandler;
|
|
77
|
+
}>;
|
|
62
78
|
/**
|
|
63
79
|
* Options for building a `MuseClient` around a connection you already own.
|
|
64
80
|
* `MuseClient.spawn` fills these in for you; supply them yourself only when
|
|
@@ -55,12 +55,13 @@ const START_FORWARDED = [
|
|
|
55
55
|
"workspaceRoots",
|
|
56
56
|
"modelId",
|
|
57
57
|
"permissionProfile",
|
|
58
|
+
"recoveryMode",
|
|
58
59
|
];
|
|
59
60
|
/**
|
|
60
61
|
* Every `ResumeParams` member `resumeSession` forwards. `config` has the same
|
|
61
62
|
* temporary capability-check boundary as the start facade above.
|
|
62
63
|
*/
|
|
63
|
-
const RESUME_FORWARDED = ["sessionId", "cursor", "excludeItems", "history", "permissionProfile"];
|
|
64
|
+
const RESUME_FORWARDED = ["sessionId", "cursor", "excludeItems", "history", "permissionProfile", "recoveryMode"];
|
|
64
65
|
/**
|
|
65
66
|
* The committed profile id a session snapshot claims, or null when the
|
|
66
67
|
* snapshot is silent (the stable bundle strips the member; absent and null
|
|
@@ -130,6 +131,30 @@ export class MuseClient {
|
|
|
130
131
|
// "MuseClient owns the connection" means; a consumer that needs the raw
|
|
131
132
|
// feed builds around a bare `Connection` and `Session` instead.
|
|
132
133
|
this.#connection.onNotification((notification) => this.#route(notification));
|
|
134
|
+
// A question or approval still open at resume is re-sent as a
|
|
135
|
+
// `userInput/request` or `approval/request` server request (tdd SS5.6,
|
|
136
|
+
// SS5.10). Each is routed in arrival order and answered with the SS5.3.3
|
|
137
|
+
// receipt `{}`: a question as the `userInput/requested` twin it shares
|
|
138
|
+
// params with, so its session lists it, and an approval as itself, which
|
|
139
|
+
// the session routes to its approval handler. The receipt does not wait on
|
|
140
|
+
// `#route` finding the session: a request read during an open is held
|
|
141
|
+
// before that session exists. Every other server-request method keeps the
|
|
142
|
+
// `-32601` a bare `Connection` answers.
|
|
143
|
+
this.#connection.onServerRequest(async (request) => {
|
|
144
|
+
if (request.method === "userInput/request") {
|
|
145
|
+
this.#route({ method: "userInput/requested", params: request.params });
|
|
146
|
+
return {};
|
|
147
|
+
}
|
|
148
|
+
if (request.method === "approval/request") {
|
|
149
|
+
this.#route({ method: request.method, params: request.params });
|
|
150
|
+
return {};
|
|
151
|
+
}
|
|
152
|
+
throw new MspError({
|
|
153
|
+
code: -32601,
|
|
154
|
+
message: `method not found: ${request.method}`,
|
|
155
|
+
data: { kind: "methodNotFound", retryable: false },
|
|
156
|
+
});
|
|
157
|
+
});
|
|
133
158
|
// Registered at construction, not at the first session: an EOF can land
|
|
134
159
|
// before any session exists, and the flag has to be read at that moment.
|
|
135
160
|
void this.#connection.closed.then(() => this.#transportClosed());
|
|
@@ -269,6 +294,8 @@ export class MuseClient {
|
|
|
269
294
|
params.workspaceRoots = options.workspaceRoots;
|
|
270
295
|
if (options.modelId != null)
|
|
271
296
|
params.modelId = options.modelId;
|
|
297
|
+
if (options.recoveryMode != null)
|
|
298
|
+
params.recoveryMode = options.recoveryMode;
|
|
272
299
|
// The initial permission-profile selection, forwarded verbatim like the
|
|
273
300
|
// other start members (undefined stays omitted).
|
|
274
301
|
if (options.permissionProfile != null)
|
|
@@ -340,12 +367,14 @@ export class MuseClient {
|
|
|
340
367
|
params.excludeItems = options.excludeItems;
|
|
341
368
|
if (options.history != null)
|
|
342
369
|
params.history = options.history;
|
|
370
|
+
if (options.recoveryMode != null)
|
|
371
|
+
params.recoveryMode = options.recoveryMode;
|
|
343
372
|
if (options.permissionProfile != null)
|
|
344
373
|
params.permissionProfile = options.permissionProfile;
|
|
345
374
|
return this.#open("session/resume", params, (raw) => ({
|
|
346
375
|
result: raw,
|
|
347
376
|
verb: "session/resume",
|
|
348
|
-
}));
|
|
377
|
+
}), { onApproval: options.onApproval, onApprovalError: options.onApprovalError });
|
|
349
378
|
}
|
|
350
379
|
/**
|
|
351
380
|
* Shut the host down in an orderly way (SS2.1.2); the shutdown this causes
|
|
@@ -381,11 +410,11 @@ export class MuseClient {
|
|
|
381
410
|
* named no session this client opened is held no longer than the open it
|
|
382
411
|
* rode in with (#49790).
|
|
383
412
|
*/
|
|
384
|
-
async #open(verb, params, opening) {
|
|
413
|
+
async #open(verb, params, opening, approvals = {}) {
|
|
385
414
|
this.#opening += 1;
|
|
386
415
|
try {
|
|
387
416
|
const opened = opening(await this.#connection.command(verb, params));
|
|
388
|
-
return this.#openSession(opened.result.session.sessionId, opened);
|
|
417
|
+
return this.#openSession(opened.result.session.sessionId, opened, approvals);
|
|
389
418
|
}
|
|
390
419
|
finally {
|
|
391
420
|
this.#opening -= 1;
|
|
@@ -393,7 +422,7 @@ export class MuseClient {
|
|
|
393
422
|
this.#held.clear();
|
|
394
423
|
}
|
|
395
424
|
}
|
|
396
|
-
#openSession(sessionId, opening) {
|
|
425
|
+
#openSession(sessionId, opening, approvals) {
|
|
397
426
|
const session = new Session({
|
|
398
427
|
connection: this.#connection,
|
|
399
428
|
discarded: this.#discarded,
|
|
@@ -401,6 +430,12 @@ export class MuseClient {
|
|
|
401
430
|
opening,
|
|
402
431
|
sessionId,
|
|
403
432
|
});
|
|
433
|
+
// Before the held frames below: an approval re-sent with the resume reply
|
|
434
|
+
// must find the handler, and its failure the observer.
|
|
435
|
+
if (approvals.onApprovalError !== undefined)
|
|
436
|
+
session.onApprovalError(approvals.onApprovalError);
|
|
437
|
+
if (approvals.onApproval !== undefined)
|
|
438
|
+
session.onApproval(approvals.onApproval);
|
|
404
439
|
this.#sessions.add(session);
|
|
405
440
|
// The frames that named this session while its verb was in flight fold
|
|
406
441
|
// NOW, in arrival order — synchronously, so nothing the pump routes next
|
|
@@ -114,8 +114,9 @@ export class GapFiller {
|
|
|
114
114
|
*/
|
|
115
115
|
start() {
|
|
116
116
|
const gap = this.#options.fold.pendingGap;
|
|
117
|
-
// Only reachable if a caller invokes this with nothing outstanding
|
|
118
|
-
//
|
|
117
|
+
// Only reachable if a caller invokes this with nothing outstanding:
|
|
118
|
+
// `Session.apply` folds the marker first (which sets it, or a stale repeat
|
|
119
|
+
// finds it already set), and `#run` checks it before it restarts itself.
|
|
119
120
|
if (gap === undefined)
|
|
120
121
|
return NO_RETIREMENTS;
|
|
121
122
|
if (this.#filling)
|
|
@@ -357,6 +358,10 @@ export class GapFiller {
|
|
|
357
358
|
return Promise.all(sink.tasks).then((batches) => [...sink.retirements, ...batches.flat()]);
|
|
358
359
|
}
|
|
359
360
|
static #viewCursorOf(frame) {
|
|
361
|
+
// A routed `approval/request` carries its notification's cursor but is not
|
|
362
|
+
// that event: matching it would spend the twin's overlap slot.
|
|
363
|
+
if (frame.method === "approval/request")
|
|
364
|
+
return undefined;
|
|
360
365
|
const cursor = frame.params?.viewCursor;
|
|
361
366
|
return typeof cursor === "string" ? cursor : undefined;
|
|
362
367
|
}
|
|
@@ -30,7 +30,7 @@ import type { GapFillFailureHandler } from "./gap-fill.js";
|
|
|
30
30
|
import type { DiscardedSessions } from "./discarded.js";
|
|
31
31
|
import type { HostDeathDischarge, HostDeathNotification, SessionDurabilityProfile } from "./host-death.js";
|
|
32
32
|
import type { Turn } from "./turn-handle.js";
|
|
33
|
-
import type { SessionResumeResult, SessionStartResult } from "../msp.js";
|
|
33
|
+
import type { SessionResumeResult, SessionStartResult, UserInputAnswer, UserInputAnswerResult } from "../msp.js";
|
|
34
34
|
/**
|
|
35
35
|
* Which verb opened this session, and what it answered.
|
|
36
36
|
*
|
|
@@ -165,7 +165,10 @@ export interface SessionGapOverlap {
|
|
|
165
165
|
* A SECOND `view/gap` that lands while a fill is running rides the same
|
|
166
166
|
* channel for the same reason: it extends the running walk instead of starting
|
|
167
167
|
* its own, so its apply reports `deliveryGap` with an already-settled empty
|
|
168
|
-
* `io`, and the work it caused settles on the FIRST gap frame's.
|
|
168
|
+
* `io`, and the work it caused settles on the FIRST gap frame's. A repeat of a
|
|
169
|
+
* `next` already named while the hole is open folds as `ignoredStaleFrame` and
|
|
170
|
+
* extends nothing; after a failed fill it still restarts that fill, and the
|
|
171
|
+
* restarted walk's work settles on this frame's `io`.
|
|
169
172
|
*/
|
|
170
173
|
export interface SessionApplyOutcome<I> {
|
|
171
174
|
readonly fold: FoldOutcome | SessionApplyRefusal | SessionGapBuffered | SessionGapOverlap;
|
|
@@ -270,6 +273,13 @@ export declare class Session<I = unknown> {
|
|
|
270
273
|
onApproval(handler: ApprovalHandler): void;
|
|
271
274
|
/** Observe round trips that did not complete. See `ApprovalFailure`. */
|
|
272
275
|
onApprovalError(handler: ApprovalFailureHandler): void;
|
|
276
|
+
/**
|
|
277
|
+
* Answer a question this session lists in `fold.pendingUserInputs()` (tdd
|
|
278
|
+
* SS5.10.2): sends `userInput/answer` with one answer per question and
|
|
279
|
+
* resolves with the host's admission. The question leaves the pending list
|
|
280
|
+
* only when the server's `userInput/settled` arrives.
|
|
281
|
+
*/
|
|
282
|
+
answerUserInput(userInputId: string, answers: readonly UserInputAnswer[]): Promise<UserInputAnswerResult>;
|
|
273
283
|
/**
|
|
274
284
|
* Stop the SS3.1.1 retry loop for one entry and take its input back
|
|
275
285
|
* (SS4.13 "Abandoned").
|
|
@@ -21,12 +21,30 @@
|
|
|
21
21
|
*/
|
|
22
22
|
import { SessionFold } from "../fold/session-fold.js";
|
|
23
23
|
import { PendingCommandSet } from "../pending/pending-command-set.js";
|
|
24
|
+
import { ProtocolError } from "../connection/connection.js";
|
|
24
25
|
import { ApprovalRouter } from "./approval.js";
|
|
25
26
|
import { TurnSubmitter } from "./turn-submit.js";
|
|
26
27
|
import { GapFiller } from "./gap-fill.js";
|
|
27
28
|
import { isAbnormalHostDeath, isItemInProgress, MuseHostDiedError, survivesHostDeath, } from "./host-death.js";
|
|
28
|
-
import { MuseForeignSessionError } from "../errors.js";
|
|
29
|
+
import { MuseForeignSessionError, MuseSessionDiscardedError } from "../errors.js";
|
|
29
30
|
import { TurnHandle } from "./turn-handle.js";
|
|
31
|
+
/**
|
|
32
|
+
* True when a routed `approval/request` carries every member the approval
|
|
33
|
+
* router reads: its `approvalId`, the requirement's `approvalId` and
|
|
34
|
+
* `sourceIndex`, and each offered choice's `choiceId`.
|
|
35
|
+
*/
|
|
36
|
+
function isRoutableApprovalRequest(params) {
|
|
37
|
+
const { approvalId, currentRequirementId, availableChoices } = params;
|
|
38
|
+
return (typeof approvalId === "string" &&
|
|
39
|
+
isRecord(currentRequirementId) &&
|
|
40
|
+
typeof currentRequirementId["approvalId"] === "string" &&
|
|
41
|
+
Number.isInteger(currentRequirementId["sourceIndex"]) &&
|
|
42
|
+
Array.isArray(availableChoices) &&
|
|
43
|
+
availableChoices.every((choice) => isRecord(choice) && typeof choice["choiceId"] === "string"));
|
|
44
|
+
}
|
|
45
|
+
function isRecord(value) {
|
|
46
|
+
return value !== null && typeof value === "object" && !Array.isArray(value);
|
|
47
|
+
}
|
|
30
48
|
/** Bound to the generated vocabulary so a misspelling fails `tsc`. */
|
|
31
49
|
const USER_MESSAGE = "userMessage";
|
|
32
50
|
/**
|
|
@@ -59,6 +77,12 @@ export class Session {
|
|
|
59
77
|
/** The FR-020 splice-fill (`gap-fill.ts`). */
|
|
60
78
|
#gaps;
|
|
61
79
|
#fold = new SessionFold();
|
|
80
|
+
/**
|
|
81
|
+
* Approvals the fold holds a durable terminal for. Read by a re-sent
|
|
82
|
+
* `approval/request`, which skips the fold, so it authors nothing for an
|
|
83
|
+
* approval already resolved; mirrors the fold's own record, keyed for O(1).
|
|
84
|
+
*/
|
|
85
|
+
#resolvedApprovalIds = new Set();
|
|
62
86
|
#durability;
|
|
63
87
|
/** The first discharge, replayed verbatim on every later call. */
|
|
64
88
|
#discharge;
|
|
@@ -181,8 +205,13 @@ export class Session {
|
|
|
181
205
|
// HERE rather than inside the routing switch because it is the one arm
|
|
182
206
|
// that authors client→server I/O off a notification, and `io` is the
|
|
183
207
|
// channel that carries it.
|
|
184
|
-
|
|
208
|
+
// A stale repeat of an earlier gap still restarts a failed fill, as every
|
|
209
|
+
// folded `view/gap` (a `deliveryGap` or a stale repeat) reaches `start()`
|
|
210
|
+
// (a no-op while a fill runs).
|
|
211
|
+
if (outcome.kind === "deliveryGap" ||
|
|
212
|
+
(outcome.kind === "ignoredStaleFrame" && outcome.method === "view/gap")) {
|
|
185
213
|
sink.tasks.push(this.#gaps.start());
|
|
214
|
+
}
|
|
186
215
|
return {
|
|
187
216
|
fold: outcome,
|
|
188
217
|
io: Session.#settleIo(sink.tasks),
|
|
@@ -204,7 +233,26 @@ export class Session {
|
|
|
204
233
|
#foldAndRoute(event, sink) {
|
|
205
234
|
const retirements = [];
|
|
206
235
|
const tasks = sink.tasks;
|
|
236
|
+
// A re-sent `approval/request` server request skips the fold, which lists
|
|
237
|
+
// only the `approval/requested` notification, and reaches approval routing
|
|
238
|
+
// like that notification: the per-stage latch decides each stage once, and
|
|
239
|
+
// an approval already resolved authors nothing.
|
|
240
|
+
// A request missing the members the router reads is dropped, never thrown
|
|
241
|
+
// on (SS1.5.4), whichever path applies it: a held frame replayed inside
|
|
242
|
+
// `resumeSession` included. A routed or dropped request reports
|
|
243
|
+
// `ignoredUnrecognizedMethod`, a sanctioned interim like `session/started`'s
|
|
244
|
+
// (#62835 owns a dedicated outcome); one with no params object falls through
|
|
245
|
+
// to the fold's `ignoredMissingParams`, like every other frame.
|
|
246
|
+
if (event.method === "approval/request" && isRecord(event.params)) {
|
|
247
|
+
const params = event.params;
|
|
248
|
+
if (isRoutableApprovalRequest(params) && !this.#resolvedApprovalIds.has(params.approvalId)) {
|
|
249
|
+
this.#approvalRequested(params, tasks);
|
|
250
|
+
}
|
|
251
|
+
return { kind: "ignoredUnrecognizedMethod", method: event.method };
|
|
252
|
+
}
|
|
207
253
|
const outcome = this.#fold.apply(event);
|
|
254
|
+
if (outcome.kind === "approvalResolved")
|
|
255
|
+
this.#resolvedApprovalIds.add(outcome.approvalId);
|
|
208
256
|
// The fold drops a frame with no `params` as `ignoredMissingParams`
|
|
209
257
|
// (SS1.5.4: drop, never throw). The switch below reads `event.params` on
|
|
210
258
|
// the turn and delta arms, so without this early return a single
|
|
@@ -272,8 +320,9 @@ export class Session {
|
|
|
272
320
|
//
|
|
273
321
|
// `view/gap` is here because it routes to no turn: it names a hole in
|
|
274
322
|
// DELIVERY, so what it moves is the fold's currency, and the recovery
|
|
275
|
-
// it triggers is started by `apply` off the `deliveryGap` verdict
|
|
276
|
-
// than from this switch
|
|
323
|
+
// it triggers is started by `apply` off the `deliveryGap` verdict, or off
|
|
324
|
+
// a stale `view/gap`'s `ignoredStaleFrame`, rather than from this switch
|
|
325
|
+
// (FR-020 / T032).
|
|
277
326
|
case "view/gap":
|
|
278
327
|
case "turn/retracted": // the turn still reaches its own terminal
|
|
279
328
|
case "turn/retryScheduled": // non-terminal by contract (SS4.5.1)
|
|
@@ -293,6 +342,12 @@ export class Session {
|
|
|
293
342
|
case "session/approvalModeChanged":
|
|
294
343
|
case "session/modelRouteUnserved":
|
|
295
344
|
case "session/nameChanged":
|
|
345
|
+
// The monitor-inbox trio (SS4.5.18): consumer-folded notices, never
|
|
346
|
+
// turn-handle traffic — the fold surfaces their facts on the
|
|
347
|
+
// `monitorInbox` outcome and seeds no store.
|
|
348
|
+
case "monitor/inboxItemAdmitted":
|
|
349
|
+
case "monitor/inboxItemDrained":
|
|
350
|
+
case "monitor/inboxItemVoided":
|
|
296
351
|
break;
|
|
297
352
|
default: {
|
|
298
353
|
// Compile-time exhaustiveness. Runtime tolerance of a newer host's
|
|
@@ -480,6 +535,33 @@ export class Session {
|
|
|
480
535
|
onApprovalError(handler) {
|
|
481
536
|
this.#approvals.onApprovalError(handler);
|
|
482
537
|
}
|
|
538
|
+
// ---- user-input answers (ADR 42116 D18) ----------------------------------
|
|
539
|
+
/**
|
|
540
|
+
* Answer a question this session lists in `fold.pendingUserInputs()` (tdd
|
|
541
|
+
* SS5.10.2): sends `userInput/answer` with one answer per question and
|
|
542
|
+
* resolves with the host's admission. The question leaves the pending list
|
|
543
|
+
* only when the server's `userInput/settled` arrives.
|
|
544
|
+
*/
|
|
545
|
+
async answerUserInput(userInputId, answers) {
|
|
546
|
+
// Refused before anything is sent, as `sendUserTurn` is: SS2.13.3b
|
|
547
|
+
// forbids reattaching a discarded session.
|
|
548
|
+
if (this.#discharge?.kind === "discharged") {
|
|
549
|
+
throw new MuseSessionDiscardedError(`session ${this.sessionId} was discarded after an ephemeral host death; it cannot answer a question`);
|
|
550
|
+
}
|
|
551
|
+
const connection = this.#submit.requireConnection("answerUserInput");
|
|
552
|
+
// No explicit `commandId`: `Connection.command()` mints and stamps it, and
|
|
553
|
+
// refuses an ack that echoes a different one. An ack with none is refused
|
|
554
|
+
// here, with one naming another question.
|
|
555
|
+
const ack = await connection.command("userInput/answer", {
|
|
556
|
+
sessionId: this.sessionId,
|
|
557
|
+
userInputId,
|
|
558
|
+
answers: [...answers],
|
|
559
|
+
});
|
|
560
|
+
if (typeof ack["commandId"] !== "string" || ack["userInputId"] !== userInputId) {
|
|
561
|
+
throw new ProtocolError(`userInput/answer acknowledged command ${String(ack["commandId"])} for question ${String(ack["userInputId"])}, expected question ${userInputId}`);
|
|
562
|
+
}
|
|
563
|
+
return ack;
|
|
564
|
+
}
|
|
483
565
|
// ---- consumer-driven SS4.13 retirement verbs ----------------------------
|
|
484
566
|
/**
|
|
485
567
|
* Stop the SS3.1.1 retry loop for one entry and take its input back
|
|
@@ -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:f282ad16e21520d0cda68cb190149b86e2b062eef1dd282749360c05aa3d1082";
|
|
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:f282ad16e21520d0cda68cb190149b86e2b062eef1dd282749360c05aa3d1082";
|
|
17
17
|
/**
|
|
18
18
|
* What a build-time mismatch MEANS, in the words a human needs at 2am.
|
|
19
19
|
*
|
|
@@ -27,7 +27,7 @@
|
|
|
27
27
|
* unrecognized `TurnTerminal` is kept verbatim, and a second resolution never
|
|
28
28
|
* displaces the first durable one.
|
|
29
29
|
*/
|
|
30
|
-
import type { ApprovalRequestParams, ApprovalResolvedParams, ApprovalUpdatedParams, Item, ItemCompletedParams, ItemDeltaParams, ItemStartedParams, ItemUpdatedParams, MspNotification, SessionApprovalModeChangedParams, SessionBranchChangedParams, SessionContextUsageParams, SessionGoalChangedParams, SessionModelChangedParams, SessionModelRouteUnservedParams, SessionNameChangedParams, SessionReasoningEffortChangedParams, SessionTodoListChangedParams, SessionTokenUsageParams, TurnCompletedParams, TurnError, TurnForegroundCompletedParams, TurnModelRetryScheduledParams, TurnRetractedParams, TurnRetryScheduledParams, TurnStartedParams, TurnTerminal, TurnUnqueuedParams, UserInputRequestParams, UserInputSettledParams, ViewGapParams } from "../msp.js";
|
|
30
|
+
import type { ApprovalRequestParams, ApprovalResolvedParams, ApprovalUpdatedParams, Item, ItemCompletedParams, ItemDeltaParams, ItemStartedParams, ItemUpdatedParams, MonitorInboxItemAdmittedParams, MonitorInboxItemDrainedParams, MonitorInboxItemVoidedParams, MspNotification, SessionApprovalModeChangedParams, SessionBranchChangedParams, SessionContextUsageParams, SessionGoalChangedParams, SessionModelChangedParams, SessionModelRouteUnservedParams, SessionNameChangedParams, SessionReasoningEffortChangedParams, SessionTodoListChangedParams, SessionTokenUsageParams, TurnCompletedParams, TurnError, TurnForegroundCompletedParams, TurnModelRetryScheduledParams, TurnRetractedParams, TurnRetryScheduledParams, TurnStartedParams, TurnTerminal, TurnUnqueuedParams, UserInputRequestParams, UserInputSettledParams, ViewGapParams } from "../msp.js";
|
|
31
31
|
import type { DeltaApplyOutcome, ItemApplyOutcome, TerminalUnknownItemAnnotation } from "./item-store.js";
|
|
32
32
|
import type { StateApplyOutcome, StateValue } from "./state-store.js";
|
|
33
33
|
/** The session-state families, each keyed in the store by its method name. */
|
|
@@ -140,6 +140,23 @@ export type ViewEvent = {
|
|
|
140
140
|
| {
|
|
141
141
|
readonly method: "view/gap";
|
|
142
142
|
readonly params: ViewGapParams;
|
|
143
|
+
}
|
|
144
|
+
/**
|
|
145
|
+
* The monitor-inbox trio: per-monitor inbox admissions, drains, and
|
|
146
|
+
* wake-missed voids. A NOTICE, never sticky state — the SDK holds no
|
|
147
|
+
* inbox store, so the per-task projection (tails, badges, counts,
|
|
148
|
+
* retirement) is consumer-folded from the facts on the outcome. The
|
|
149
|
+
* params ride the outcome verbatim for the consumer to fold once.
|
|
150
|
+
*/
|
|
151
|
+
| {
|
|
152
|
+
readonly method: "monitor/inboxItemAdmitted";
|
|
153
|
+
readonly params: MonitorInboxItemAdmittedParams;
|
|
154
|
+
} | {
|
|
155
|
+
readonly method: "monitor/inboxItemDrained";
|
|
156
|
+
readonly params: MonitorInboxItemDrainedParams;
|
|
157
|
+
} | {
|
|
158
|
+
readonly method: "monitor/inboxItemVoided";
|
|
159
|
+
readonly params: MonitorInboxItemVoidedParams;
|
|
143
160
|
};
|
|
144
161
|
/**
|
|
145
162
|
* Compile-time coverage: every `MspNotification` except the handshake's
|
|
@@ -178,7 +195,7 @@ export type ViewEvent = {
|
|
|
178
195
|
type AssertNever<T extends never> = T;
|
|
179
196
|
type LiveHostStateProjection = "skill/changed" | "usage/changed" | "session/statusChanged" | "session/listChanged" | "plugin/changed" | "plugin/marketplaceChanged" | "computerUseSetup/changed";
|
|
180
197
|
type SessionLifecycleBroadcast = "session/started" | "session/closed";
|
|
181
|
-
type NonFoldNotification = "initialized" | "userInput/engaged" | "session/viewHealthChanged" | "recap/completed" | SessionLifecycleBroadcast | LiveHostStateProjection;
|
|
198
|
+
type NonFoldNotification = "initialized" | "userInput/engaged" | "session/viewHealthChanged" | "session/leaveCompleted" | "recap/completed" | SessionLifecycleBroadcast | LiveHostStateProjection;
|
|
182
199
|
type UnfoldedViewNotification = Exclude<MspNotification, NonFoldNotification | ViewEvent["method"]>;
|
|
183
200
|
export type EveryViewNotificationIsFolded = AssertNever<UnfoldedViewNotification>;
|
|
184
201
|
/**
|
|
@@ -224,7 +241,7 @@ export type SessionStateMethod = ViewEvent["method"] & `session/${string}`;
|
|
|
224
241
|
* and could never match exhaustively. A future arm that starts dropping
|
|
225
242
|
* widens this deliberately (PR #23087 review round).
|
|
226
243
|
*/
|
|
227
|
-
export type StaleDroppableMethod = "turn/started" | "turn/completed" | "turn/retracted" | "turn/foregroundCompleted" | "turn/retryScheduled" | "turn/modelRetryScheduled" | "approval/requested" | "approval/updated" | "userInput/requested";
|
|
244
|
+
export type StaleDroppableMethod = "turn/started" | "turn/completed" | "turn/retracted" | "turn/foregroundCompleted" | "turn/retryScheduled" | "turn/modelRetryScheduled" | "approval/requested" | "approval/updated" | "userInput/requested" | "view/gap";
|
|
228
245
|
/**
|
|
229
246
|
* The `NoStaleViewArm` sibling for the union above: these are hand-typed
|
|
230
247
|
* literals, so without this pin a typo'd or later-retired member compiles
|
|
@@ -353,6 +370,17 @@ export type FoldOutcome = {
|
|
|
353
370
|
| {
|
|
354
371
|
readonly kind: "modelRouteUnserved";
|
|
355
372
|
readonly params: SessionModelRouteUnservedParams;
|
|
373
|
+
}
|
|
374
|
+
/**
|
|
375
|
+
* One monitor-inbox trio fact, surfaced verbatim (see the `ViewEvent`
|
|
376
|
+
* arms above): the method names which of the three arrived, and the
|
|
377
|
+
* params carry that event's fact members for the consumer's own fold.
|
|
378
|
+
* Fresh wire objects, never store handles, so no D-14 seal applies.
|
|
379
|
+
*/
|
|
380
|
+
| {
|
|
381
|
+
readonly kind: "monitorInbox";
|
|
382
|
+
readonly method: "monitor/inboxItemAdmitted" | "monitor/inboxItemDrained" | "monitor/inboxItemVoided";
|
|
383
|
+
readonly params: MonitorInboxItemAdmittedParams | MonitorInboxItemDrainedParams | MonitorInboxItemVoidedParams;
|
|
356
384
|
} | {
|
|
357
385
|
readonly kind: "ignoredUnrecognizedMethod";
|
|
358
386
|
readonly method: string;
|
|
@@ -379,7 +407,9 @@ export type FoldOutcome = {
|
|
|
379
407
|
* not seen; an `approval/updated` for an approval it never saw
|
|
380
408
|
* requested (or whose entry a resolution already deleted); or a
|
|
381
409
|
* redelivered `approval/requested` / `userInput/requested` for an
|
|
382
|
-
* approval/prompt that already has its durable terminal
|
|
410
|
+
* approval/prompt that already has its durable terminal; or a
|
|
411
|
+
* `view/gap` whose `next` an earlier frame already named while the
|
|
412
|
+
* hole is open (`id` is that `next`, #62032). Truthful by
|
|
383
413
|
* contract: a "pending" kind here would make a renderer show an entry
|
|
384
414
|
* the fold does not hold (PR #23087 review round).
|
|
385
415
|
*
|
|
@@ -494,6 +524,9 @@ export declare class SessionFold {
|
|
|
494
524
|
* own D-16487-1 bracket rule. A recovery walks `(after, next)` and calls
|
|
495
525
|
* `gapFilled(next)` with the target it actually reached, so a hole that grew
|
|
496
526
|
* while the walk was in flight cannot be reported filled.
|
|
527
|
+
*
|
|
528
|
+
* A later frame moves `next` to its own, but one repeating a `next` already
|
|
529
|
+
* named while the hole is open is stale and changes nothing (#62032).
|
|
497
530
|
*/
|
|
498
531
|
get pendingGap(): DeepReadonly<ViewGapParams> | undefined;
|
|
499
532
|
/**
|
|
@@ -78,6 +78,8 @@ export class SessionFold {
|
|
|
78
78
|
#settledUserInputs = new Map();
|
|
79
79
|
#activeTurnId;
|
|
80
80
|
#pendingGap;
|
|
81
|
+
/** Every `next` a `view/gap` named while `#pendingGap` is open; `gapFilled` empties it. */
|
|
82
|
+
#gapTargets = new Set();
|
|
81
83
|
/** The turn currently running, if one is. */
|
|
82
84
|
get activeTurnId() {
|
|
83
85
|
return this.#activeTurnId;
|
|
@@ -91,6 +93,9 @@ export class SessionFold {
|
|
|
91
93
|
* own D-16487-1 bracket rule. A recovery walks `(after, next)` and calls
|
|
92
94
|
* `gapFilled(next)` with the target it actually reached, so a hole that grew
|
|
93
95
|
* while the walk was in flight cannot be reported filled.
|
|
96
|
+
*
|
|
97
|
+
* A later frame moves `next` to its own, but one repeating a `next` already
|
|
98
|
+
* named while the hole is open is stale and changes nothing (#62032).
|
|
94
99
|
*/
|
|
95
100
|
get pendingGap() {
|
|
96
101
|
return this.#pendingGap;
|
|
@@ -123,6 +128,7 @@ export class SessionFold {
|
|
|
123
128
|
if (this.#pendingGap?.next !== next)
|
|
124
129
|
return false;
|
|
125
130
|
this.#pendingGap = undefined;
|
|
131
|
+
this.#gapTargets.clear();
|
|
126
132
|
return true;
|
|
127
133
|
}
|
|
128
134
|
apply(event) {
|
|
@@ -181,6 +187,10 @@ export class SessionFold {
|
|
|
181
187
|
return this.#userInputSettled(typed.params);
|
|
182
188
|
case "view/gap":
|
|
183
189
|
return this.#deliveryGap(typed.params);
|
|
190
|
+
case "monitor/inboxItemAdmitted":
|
|
191
|
+
case "monitor/inboxItemDrained":
|
|
192
|
+
case "monitor/inboxItemVoided":
|
|
193
|
+
return { kind: "monitorInbox", method: typed.method, params: typed.params };
|
|
184
194
|
case "session/modelRouteUnserved":
|
|
185
195
|
return { kind: "modelRouteUnserved", params: typed.params };
|
|
186
196
|
case "session/modelChanged":
|
|
@@ -387,6 +397,14 @@ export class SessionFold {
|
|
|
387
397
|
}
|
|
388
398
|
// ---- the delivery-plane marker ------------------------------------------
|
|
389
399
|
#deliveryGap(params) {
|
|
400
|
+
// A `next` already named while this hole is open is a stale repeat of an
|
|
401
|
+
// earlier frame: taking it would move the target back, so a walk would
|
|
402
|
+
// stop short and the fold report current over an unfilled hole. It
|
|
403
|
+
// changes nothing, as in the Rust SDK's gap walk (ADR 42116 D1, #62032).
|
|
404
|
+
if (this.#gapTargets.has(params.next)) {
|
|
405
|
+
return { id: params.next, kind: "ignoredStaleFrame", method: "view/gap" };
|
|
406
|
+
}
|
|
407
|
+
this.#gapTargets.add(params.next);
|
|
390
408
|
// Coalesced on the FIRST `after`: a second overflow while the first hole
|
|
391
409
|
// is still open extends the range rather than replacing it. Replacing it
|
|
392
410
|
// would move the lower bound past events that were never delivered, so a
|
package/dist/src/msp.d.ts
CHANGED
|
@@ -506,6 +506,20 @@ export interface CumulativeTokenUsage {
|
|
|
506
506
|
totalTokens: number;
|
|
507
507
|
}
|
|
508
508
|
|
|
509
|
+
/** `damagedRange`: what one damaged range of the session log cost (ADR 60914 D1/D2). The reader finds the range in the log bytes; no log record is written for it, so every member is derived from the readable records around it. */
|
|
510
|
+
export interface DamagedRange {
|
|
511
|
+
/** The last finished turn before the first damaged range, when one exists: the safe `session/fork` cut (ADR 60914 D1 "Fork cuts", D4). */
|
|
512
|
+
lastGoodTurnId?: string;
|
|
513
|
+
/** Records the log proves missing (session-stream sequence numbers no readable record or unreadable line accounts for). */
|
|
514
|
+
missingRecords: number;
|
|
515
|
+
/** RFC3339 `recordedAt` of the first readable record after the range; always present, since a range is read past only when readable records follow it (ADR 60914 D1). */
|
|
516
|
+
readableAfterAt: string;
|
|
517
|
+
/** RFC3339 `recordedAt` of the last readable record before the range; absent when the range starts the log. */
|
|
518
|
+
readableBeforeAt?: string;
|
|
519
|
+
/** Physical log lines in the range that are not a readable record. */
|
|
520
|
+
unreadableLines: number;
|
|
521
|
+
}
|
|
522
|
+
|
|
509
523
|
/** The effective approval-mode projection (`EffectiveApprovalModeState`, tdd SS5.12): the same object `session/setApprovalMode` returns as `effectiveMode` and the `Session` object carries as `approvalMode`. */
|
|
510
524
|
export interface EffectiveApprovalModeState {
|
|
511
525
|
/** The command that last set it; `null` when no command did. */
|
|
@@ -572,6 +586,8 @@ export interface ErrorData {
|
|
|
572
586
|
paths?: string[];
|
|
573
587
|
/** Failure detail vocabulary (e.g. `"missingAnchor"` on `notFound` for a missing view-cursor anchor). */
|
|
574
588
|
reason?: string;
|
|
589
|
+
/** The original recovery-dependent construction's coherent observation. An absent or unusable observation establishes no supported recovery. */
|
|
590
|
+
recoveryObservation?: RecoveryObservation;
|
|
575
591
|
/** Winning resolution on `approvalAlreadyResolved`. */
|
|
576
592
|
resolution?: ApprovalResolutionSummary;
|
|
577
593
|
/** Whether retrying can succeed (e.g. `overloaded`). When present, overrides the error table row's `retryable` default for this code. */
|
|
@@ -683,6 +699,8 @@ export interface ForkProvenance {
|
|
|
683
699
|
|
|
684
700
|
/** The session goal block (tdd SS4.6.2, mirrors the runtime's goal state, camelCased). `status` and `percentComplete` are carried **verbatim** — out-of-contract status strings and >100 percents pass through; display clamping is the renderer's job. */
|
|
685
701
|
export interface Goal {
|
|
702
|
+
/** ADR 50064 D2 (pick-4): goal creation time, epoch milliseconds, verbatim from the durable row. Absent on blocks whose producer never carried it (tool-result adoptions, pre-pick-4 logs); absence must never render as a fabricated zero. */
|
|
703
|
+
createdAtMs?: number;
|
|
686
704
|
/** Current work description, when present. */
|
|
687
705
|
currentWork?: string;
|
|
688
706
|
/** Next work description, when present. */
|
|
@@ -693,6 +711,8 @@ export interface Goal {
|
|
|
693
711
|
percentComplete: number;
|
|
694
712
|
/** Goal status, verbatim from the durable goal state (free string by design: out-of-contract values pass through). */
|
|
695
713
|
status: string;
|
|
714
|
+
/** ADR 50064 D2 (pick-4): last goal mutation time, epoch milliseconds, verbatim from the durable row. Same absence rule as `createdAtMs`. */
|
|
715
|
+
updatedAtMs?: number;
|
|
696
716
|
}
|
|
697
717
|
|
|
698
718
|
/** `goal/clear` params (tdd SS3.18). An `objective` here is an unknown field and rejects `-32602 invalidParams` — the bare verbs carry exactly this pair. */
|
|
@@ -862,8 +882,12 @@ export interface Item {
|
|
|
862
882
|
controlStatus?: SubagentControlStatus;
|
|
863
883
|
/** `agentMessage`: `true` when the provider stream died mid-reply and the run failed with this partial text committed (ADR 50063 D2) — the wire mark for the gate-off "incomplete response" rule (#13328). Absent otherwise; never cleared once set. */
|
|
864
884
|
cutOff?: boolean;
|
|
885
|
+
/** `damagedRange`: what the damaged range cost (ADR 60914 D2). */
|
|
886
|
+
damagedRange?: DamagedRange;
|
|
865
887
|
/** `workflow`: the run-level declared-phase label — the last `Phase` detail-row label of the reconciled projection; terminal-only, absent while live (tdd SS4.5.8, #45449). */
|
|
866
888
|
declaredPhase?: string;
|
|
889
|
+
/** `scheduledFire`: the occurrence number within the job's history, present with occurrence metadata (tdd SS4.5.17; ADR 45446 D2). */
|
|
890
|
+
deliveryNumber?: number;
|
|
867
891
|
/** `subagent`: nesting depth. */
|
|
868
892
|
depth?: number;
|
|
869
893
|
/** `toolCall`: the tool's own words for this call; absent = none (tdd SS4.5.5). */
|
|
@@ -892,8 +916,10 @@ export interface Item {
|
|
|
892
916
|
generationId?: number;
|
|
893
917
|
/** `hookRun`: the durable `hook_key` (tdd SS4.5.11). */
|
|
894
918
|
hookKey?: string;
|
|
895
|
-
/** Bare UUIDv7; the item's identity across its whole lifecycle. Identity rule (tdd SS4.4.1): the task id for task-backed kinds (`toolCall`, `subagent`), the pre-minted commit `message_id` for delta-streamed kinds (`agentMessage`, `reasoning`), and the opening durable record's event id for everything else. Opaque to clients. */
|
|
919
|
+
/** Bare UUIDv7; the item's identity across its whole lifecycle. Identity rule (tdd SS4.4.1): the task id for task-backed kinds (`toolCall`, `subagent`), the pre-minted commit `message_id` for delta-streamed kinds (`agentMessage`, `reasoning`), `EventId::derive` over the session id and the range's starting sequence number for `damagedRange` (no record carries it, SS4.5.16), and the opening durable record's event id for everything else. Opaque to clients. */
|
|
896
920
|
itemId: string;
|
|
921
|
+
/** `scheduledFire`: the cron job id that fired (tdd SS4.5.17; ADR 45446 D2, spec 13929 amendment #62595 FR-62595-1). */
|
|
922
|
+
jobId?: string;
|
|
897
923
|
/** The item kind (open enum): clients MUST render unknown kinds generically — kind name plus `status` plus `fallbackText` (tdd SS4.10). */
|
|
898
924
|
kind: ItemKind;
|
|
899
925
|
/** `hookRun`: capped display label (tdd SS4.5.11). */
|
|
@@ -908,6 +934,8 @@ export interface Item {
|
|
|
908
934
|
monitorDescription?: string;
|
|
909
935
|
/** `monitorFeed`: the monitor task id — the same value as that monitor's `toolCall` `itemId` (ADR 50058-monitor-feed-wire D1). */
|
|
910
936
|
monitorId?: string;
|
|
937
|
+
/** `scheduledFire`: the next scheduled epoch in milliseconds; absent on a final delivery (tdd SS4.5.17; ADR 45446 D2). */
|
|
938
|
+
nextFireAtMs?: number;
|
|
911
939
|
/** `subagent`: objective as spawned, bounded on the wire at the 64 KiB retained-text budget (tdd SS4.5.4, ADR 35691 D9); a cut sets `truncated`. The durable record stays verbatim. */
|
|
912
940
|
objective?: string;
|
|
913
941
|
/** `compaction`: terminal only — folds installed/fallback status. */
|
|
@@ -940,6 +968,8 @@ export interface Item {
|
|
|
940
968
|
role?: string;
|
|
941
969
|
/** `hookRun`: terminal-only durable outcome; stays `blocked` when the item settles `rejected` (tdd SS4.5.11). */
|
|
942
970
|
runStatus?: HookRunStatus;
|
|
971
|
+
/** `scheduledFire`: the fire's scheduled epoch in milliseconds (tdd SS4.5.17; ADR 45446 D2). */
|
|
972
|
+
scheduledFireAtMs?: number;
|
|
943
973
|
/** `workflow`: launched script identity. */
|
|
944
974
|
scriptId?: string;
|
|
945
975
|
/** `sideChat`: the side's own session id, readable via `session/read`/`view/page` — drill-down without a second protocol (tdd SS4.5.13; ADR 45435 D3). */
|
|
@@ -992,7 +1022,7 @@ export interface Item {
|
|
|
992
1022
|
triggerSource?: string;
|
|
993
1023
|
/** `true` when the server's per-surface text budget saturated a streamed surface (`agentMessage.text`, `reasoning.summary[*]`, `toolCall.visibleOutput`, `userShell.visibleOutput`), cut a `subagent` surface (`objective`, `fallbackText`, `result.summary`, `result.text`), or cut a `monitorFeed` surface (`text`, `fallbackText`, `monitorDescription`) (ADR 50058-monitor-feed-wire D3). On a `subagent` item the flag is item-level and never cleared: once any of those four is cut, every later update keeps it, even when `result.text` arrives whole (ADR 35691 D9). The durable full text remains in the log (tdd SS4.5.4). */
|
|
994
1024
|
truncated?: boolean;
|
|
995
|
-
/** The owning turn (== the submitting `commandId` for fresh turns, tdd SS3.1.4). `null` for the kinds outside a turn: `userShell` always (tdd SS4.5.6), `hookRun` for session-boundary runs, `monitorFeed` always (ADR 50058-monitor-feed-wire D1). */
|
|
1025
|
+
/** The owning turn (== the submitting `commandId` for fresh turns, tdd SS3.1.4). `null` for the kinds outside a turn: `userShell` always (tdd SS4.5.6), `hookRun` for session-boundary runs, `monitorFeed` always (ADR 50058-monitor-feed-wire D1), `sideChat` always (SS4.5.13), `damagedRange` always (ADR 60914 D2). */
|
|
996
1026
|
turnId?: string | null;
|
|
997
1027
|
/** `subagent`: **transitive** observed usage — the child and its own descendants; updated in place, absent until first observation; never folded into `session/tokenUsage.cumulative` (tdd SS4.6.5). */
|
|
998
1028
|
usage?: TokenUsage;
|
|
@@ -1029,7 +1059,7 @@ export interface ItemDeltaParams {
|
|
|
1029
1059
|
}
|
|
1030
1060
|
|
|
1031
1061
|
/** The eleven v1 item kinds (tdd SS4.5.2–4.5.13) plus post-v1 kinds (tdd SS4.5.14+). Open: a new kind is additive evolution, and clients MUST render unknown kinds generically (tdd SS4.10). */
|
|
1032
|
-
export type ItemKind = "userMessage" | "agentMessage" | "reasoning" | "toolCall" | "userShell" | "subagent" | "workflow" | "reminderChild" | "compaction" | "hookRun" | "sideChat" | "webSearch" | "monitorFeed" | (string & {});
|
|
1062
|
+
export type ItemKind = "userMessage" | "agentMessage" | "reasoning" | "toolCall" | "userShell" | "subagent" | "workflow" | "reminderChild" | "compaction" | "hookRun" | "sideChat" | "webSearch" | "monitorFeed" | "damagedRange" | "scheduledFire" | (string & {});
|
|
1033
1063
|
|
|
1034
1064
|
/** The `item/readOutput` content encoding (tdd SS4.7.4). Closed: text media is ALWAYS `utf8` and binary media `base64`; a third value would change the client's decode contract. */
|
|
1035
1065
|
export type ItemReadOutputEncoding = "utf8" | "base64";
|
|
@@ -1259,6 +1289,68 @@ export interface ModelVisibleContent {
|
|
|
1259
1289
|
width?: number;
|
|
1260
1290
|
}
|
|
1261
1291
|
|
|
1292
|
+
/** `monitor/inboxItemAdmitted` params (tdd SS4.5.18): one monitor inbox admission — the fold keys gate-off consumes. */
|
|
1293
|
+
export interface MonitorInboxItemAdmittedParams {
|
|
1294
|
+
/** The model-facing delivery text. */
|
|
1295
|
+
body: string;
|
|
1296
|
+
/** The producer-recorded pre-augmentation content; absent on pre-#24686 records. */
|
|
1297
|
+
displayBody?: string;
|
|
1298
|
+
/** Per-task event order key (with `line_index`). */
|
|
1299
|
+
eventIndex: number;
|
|
1300
|
+
/** Monitor event kind, snake_case, open vocabulary — clients ignore unknown kinds. */
|
|
1301
|
+
eventKind: string;
|
|
1302
|
+
/** The inbox item id (dedupe key). */
|
|
1303
|
+
itemId: string;
|
|
1304
|
+
/** Line order key; absent when the event has no line. */
|
|
1305
|
+
lineIndex?: number;
|
|
1306
|
+
/** Admission stamp (RFC3339); consumed by the pending sort. */
|
|
1307
|
+
queuedAt: string;
|
|
1308
|
+
/** The owning session. */
|
|
1309
|
+
sessionId: string;
|
|
1310
|
+
/** Whether the event carries displayable lines. */
|
|
1311
|
+
showLines: boolean;
|
|
1312
|
+
/** The durable records this event folded from. */
|
|
1313
|
+
sourceRange: SourceRange;
|
|
1314
|
+
/** The notice-text summary. */
|
|
1315
|
+
summary: string;
|
|
1316
|
+
/** The owning monitor task id (per-task set key). */
|
|
1317
|
+
taskId: string;
|
|
1318
|
+
/** Opaque, strictly monotonic view cursor (tdd SS4.1). */
|
|
1319
|
+
viewCursor: string;
|
|
1320
|
+
}
|
|
1321
|
+
|
|
1322
|
+
/** `monitor/inboxItemDrained` params (tdd SS4.5.18): one monitor inbox drain — a consumption marker with its recorded stamp. */
|
|
1323
|
+
export interface MonitorInboxItemDrainedParams {
|
|
1324
|
+
/** False is a local claim-only recall: no delivery row or recovery consequence, but the drain still stamps the awaiting verdict. */
|
|
1325
|
+
deliveryVisible: boolean;
|
|
1326
|
+
/** The draining run stream (`StreamRef`), absent means the current draining run. */
|
|
1327
|
+
drainTargetRunStream?: StreamRef;
|
|
1328
|
+
/** The drain record's recorded stamp (RFC3339), the drain-side operand of drain-vs-void latest-wins. */
|
|
1329
|
+
drainedAt: string;
|
|
1330
|
+
/** The drained inbox item id. */
|
|
1331
|
+
itemId: string;
|
|
1332
|
+
/** The owning session. */
|
|
1333
|
+
sessionId: string;
|
|
1334
|
+
/** The durable records this event folded from. */
|
|
1335
|
+
sourceRange: SourceRange;
|
|
1336
|
+
/** Opaque, strictly monotonic view cursor (tdd SS4.1). */
|
|
1337
|
+
viewCursor: string;
|
|
1338
|
+
}
|
|
1339
|
+
|
|
1340
|
+
/** `monitor/inboxItemVoided` params (tdd SS4.5.18): one wake-missed void — count-only, no transcript row (spec 9627 D15). */
|
|
1341
|
+
export interface MonitorInboxItemVoidedParams {
|
|
1342
|
+
/** The voided inbox item id. */
|
|
1343
|
+
itemId: string;
|
|
1344
|
+
/** The owning session. */
|
|
1345
|
+
sessionId: string;
|
|
1346
|
+
/** The durable records this event folded from. */
|
|
1347
|
+
sourceRange: SourceRange;
|
|
1348
|
+
/** Opaque, strictly monotonic view cursor (tdd SS4.1). */
|
|
1349
|
+
viewCursor: string;
|
|
1350
|
+
/** The anomaly's recorded stamp (RFC3339), the void-side operand of drain-vs-void latest-wins. */
|
|
1351
|
+
voidedAt: string;
|
|
1352
|
+
}
|
|
1353
|
+
|
|
1262
1354
|
/** A notification frame, either direction (SS1.2 §2.2). No `id`; a notification is never answered. */
|
|
1263
1355
|
export interface Notification {
|
|
1264
1356
|
/** Emission time in Unix milliseconds, recorded once at emission; server→client notifications only (SS1.2.5). Optional on the wire so decoders tolerate older servers. */
|
|
@@ -1616,6 +1708,28 @@ export interface RecordPosition {
|
|
|
1616
1708
|
sequence: number;
|
|
1617
1709
|
}
|
|
1618
1710
|
|
|
1711
|
+
/** Proven effective-choice provenance, independently of input presence. */
|
|
1712
|
+
export type RecoveryEffectiveSource = "request" | "retained" | "legacyOmission" | "hostPolicy" | "unknown" | (string & {});
|
|
1713
|
+
|
|
1714
|
+
/** A requested construction choice; omission is distinct from explicit OFF. */
|
|
1715
|
+
export type RecoveryMode = "on" | "off";
|
|
1716
|
+
|
|
1717
|
+
/** One coherent producer snapshot; all members are required and non-null. */
|
|
1718
|
+
export interface RecoveryObservation {
|
|
1719
|
+
constructionId: string;
|
|
1720
|
+
effectiveMode: RecoveryObservedMode;
|
|
1721
|
+
effectiveSource: RecoveryEffectiveSource;
|
|
1722
|
+
qualification: RecoveryQualification;
|
|
1723
|
+
requestedMode: RecoveryObservedMode;
|
|
1724
|
+
sessionId: string;
|
|
1725
|
+
}
|
|
1726
|
+
|
|
1727
|
+
/** A proven mode or unknown; future strings cannot establish OFF. */
|
|
1728
|
+
export type RecoveryObservedMode = "on" | "off" | "unknown" | (string & {});
|
|
1729
|
+
|
|
1730
|
+
/** This construction's assessment, never an operation acceptance receipt. */
|
|
1731
|
+
export type RecoveryQualification = "qualified" | "unavailable" | "notRequired" | "unknown" | (string & {});
|
|
1732
|
+
|
|
1619
1733
|
/** A request frame, either direction (SS1.2 §2.1). */
|
|
1620
1734
|
export interface Request {
|
|
1621
1735
|
/** Client-chosen id, unique among that client's in-flight requests. */
|
|
@@ -1748,7 +1862,7 @@ export interface SessionBranchChangedParams {
|
|
|
1748
1862
|
workspaceRoot: string;
|
|
1749
1863
|
}
|
|
1750
1864
|
|
|
1751
|
-
/** `session/closed` params (tdd SS2.6.2; enrolled by #33065): a loaded session was unloaded from this host, broadcast to every initialized connection. After it, the session is `notLoaded`; the log remains on disk and `session/resume` reloads it. A crash emits nothing — only the
|
|
1865
|
+
/** `session/closed` params (tdd SS2.6.2; enrolled by #33065): a loaded session was unloaded from this host, broadcast to every initialized connection. After it, the session is `notLoaded`; the log remains on disk and `session/resume` reloads it. A crash emits nothing — only the orderly unload paths do (idle unload, host shutdown and a released `session/leave`), and each writes the durable `SessionEnd` record first. */
|
|
1752
1866
|
export interface SessionClosedParams {
|
|
1753
1867
|
/** Which orderly unload path fired. */
|
|
1754
1868
|
reason: SessionClosedReason;
|
|
@@ -1759,7 +1873,7 @@ export interface SessionClosedParams {
|
|
|
1759
1873
|
}
|
|
1760
1874
|
|
|
1761
1875
|
/** The SS2.6.2 closed-reason vocabulary. Server-produced and published OPEN by owner ruling — the #33065 menu-B pick (PR #33201 comment 5638727249, recorded in the enrollment decision record), which settles that this notification reason enum publishes open rather than resting on E2's result-vocabulary rule by analogy. A crash is deliberately not a reason, because a crash emits no notification at all. */
|
|
1762
|
-
export type SessionClosedReason = "idle" | "hostShutdown" | (string & {});
|
|
1876
|
+
export type SessionClosedReason = "idle" | "hostShutdown" | "leave" | (string & {});
|
|
1763
1877
|
|
|
1764
1878
|
/** `session/compact` params (tdd SS3.7): manually compact the session's conversation context — the `/compact` gesture. Compaction runs asynchronously; the ack is admission only. */
|
|
1765
1879
|
export interface SessionCompactParams {
|
|
@@ -1857,6 +1971,37 @@ export interface SessionHistory {
|
|
|
1857
1971
|
/** What kind of session this is (spec 42713 FR-001/FR-005, ADR 42713 D1/D4). **Open**: a new kind is additive evolution, and a client MUST render an unknown value as an unknown-but-present kind rather than rejecting the row. Both v1 values are terms the tree already uses — the child log directory is `subagent` and `ItemKind` already carries a `subagent` variant — so no new vocabulary is minted. */
|
|
1858
1972
|
export type SessionKind = "root" | "subagent" | (string & {});
|
|
1859
1973
|
|
|
1974
|
+
/** Params of the protected, non-view leave terminal notification. */
|
|
1975
|
+
export interface SessionLeaveCompletedParams {
|
|
1976
|
+
commandId: string;
|
|
1977
|
+
outcome: SessionLeaveOutcome;
|
|
1978
|
+
reason?: SessionLeaveFailureReason;
|
|
1979
|
+
sessionId: string;
|
|
1980
|
+
viewCursor?: string;
|
|
1981
|
+
}
|
|
1982
|
+
|
|
1983
|
+
/** Current producer failure reasons for `session/leaveCompleted`; receiver-open for additive future reasons. */
|
|
1984
|
+
export type SessionLeaveFailureReason = "timeout" | "responseUndelivered" | "persistenceFailed" | "runtimeFailed" | "abandoned" | (string & {});
|
|
1985
|
+
|
|
1986
|
+
/** Current producer outcomes for `session/leaveCompleted`; receiver-open. */
|
|
1987
|
+
export type SessionLeaveOutcome = "released" | "failed" | (string & {});
|
|
1988
|
+
|
|
1989
|
+
/** `session/leave` params (tdd SS2.15, ADR 31741 D2/D8). */
|
|
1990
|
+
export interface SessionLeaveParams {
|
|
1991
|
+
/** Client-minted UUIDv7 command identity. */
|
|
1992
|
+
commandId: string;
|
|
1993
|
+
/** The exact loaded session whose ownership is to be released. */
|
|
1994
|
+
sessionId: string;
|
|
1995
|
+
/** Explicitly cancel unfinished work before leaving. Omitted is `false`. */
|
|
1996
|
+
stop?: boolean;
|
|
1997
|
+
}
|
|
1998
|
+
|
|
1999
|
+
/** The admission-only `session/leave` result. */
|
|
2000
|
+
export interface SessionLeaveResult {
|
|
2001
|
+
commandId: string;
|
|
2002
|
+
status: CommandAckStatus;
|
|
2003
|
+
}
|
|
2004
|
+
|
|
1860
2005
|
/** Exact branch selection (#42035 FR-42035-2). */
|
|
1861
2006
|
export interface SessionListBranchFilter {
|
|
1862
2007
|
/** 1–32 nonempty branch names, each 1–256 UTF-8 bytes, counted before deduplication; `null` selects sessions with no branch. */
|
|
@@ -2000,6 +2145,8 @@ export interface SessionReadResult {
|
|
|
2000
2145
|
lastTurn?: LastTurn;
|
|
2001
2146
|
/** The same pointer shape as `session/resume`. Because `session/read` never subscribes this is a point-in-time log read only: no requests are re-issued after it (tdd SS2.5.5). */
|
|
2002
2147
|
pendingRequests: PendingRequestPointer[];
|
|
2148
|
+
/** Current local construction only; never inferred from retained history. Absence establishes neither a choice nor supported recovery. */
|
|
2149
|
+
recoveryObservation?: RecoveryObservation;
|
|
2003
2150
|
/** The session as folded point-in-time. */
|
|
2004
2151
|
session: Session;
|
|
2005
2152
|
/** The fold head at read time. */
|
|
@@ -2054,6 +2201,8 @@ export interface SessionResumeParams {
|
|
|
2054
2201
|
history?: HistoryPreference;
|
|
2055
2202
|
/** The launch permission-profile pick (amendment 42624 FR-42624-1, #50054): a profile id the host catalog already admits. Select, never create. Omitted means today's behavior: restore retained authority only, no override. The host restores first, then applies the pick in the same pre-marker step; a pick that fails admission refuses the resume `commandRejected` (-32030; `permission_profile_unknown` / `permission_profile_unavailable`) before any durable byte. Explicit `null` is invalid params (the same closed null-tolerant set as at start). */
|
|
2056
2203
|
permissionProfile?: string;
|
|
2204
|
+
/** 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
|
+
recoveryMode?: RecoveryMode;
|
|
2057
2206
|
/** The session to load. */
|
|
2058
2207
|
sessionId: string;
|
|
2059
2208
|
}
|
|
@@ -2164,6 +2313,8 @@ export interface SessionStartParams {
|
|
|
2164
2313
|
permissionProfile?: string;
|
|
2165
2314
|
/** Initial provider routing; server default when omitted or explicit `null` — both spellings select the default (#23468). */
|
|
2166
2315
|
providerId?: string | null;
|
|
2316
|
+
/** Recovery choice for this construction; omission keeps legacy behavior. Explicit null is invalid. */
|
|
2317
|
+
recoveryMode?: RecoveryMode;
|
|
2167
2318
|
/** Exact identity for this new root session. When omitted the server mints a UUIDv7. This field never selects an existing session: a retained or reserved id is rejected `commandRejected` with reason `session_id_conflict` (tdd SS2.5.1). */
|
|
2168
2319
|
sessionId?: string;
|
|
2169
2320
|
/** Absolute path, folded into the first metadata record. */
|
|
@@ -2381,6 +2532,9 @@ export interface SkillImportResult {
|
|
|
2381
2532
|
/** `skill/import` foreign ecosystem (tdd SS3.30.2). **Closed**: a client-selected write vocabulary (ADR 45433 D2) — a write must fail an ecosystem the host does not implement rather than import from an unknown dir. The host resolves its own foreign dir (the `foreign_skills_sources` derivation); no client paths cross the wire. */
|
|
2382
2533
|
export type SkillImportSource = "claude" | "codex";
|
|
2383
2534
|
|
|
2535
|
+
/** A `skill` input part's picked-copy source (tdd SS3.22.3; ADR 32471 D12): the D2 catalog-row `source` enum values, sent by the TUI on every skill submit so the host resolves the exact `(selector, source)` row. **Closed**: a client-selected write vocabulary (ADR 45433 D2) — an unknown value is `invalidParams`, never a fall-through to the bare row. Contrast the open read-side [`SkillSource`]. */
|
|
2536
|
+
export type SkillInvocationSource = "bundled" | "user" | "project" | "plugin";
|
|
2537
|
+
|
|
2384
2538
|
/** `skill/list` params (tdd SS3.22.1, SS3.30.3). Per-session because skill scope follows the session's workspace and plugin state. */
|
|
2385
2539
|
export interface SkillListParams {
|
|
2386
2540
|
/** The target session. */
|
|
@@ -2582,6 +2736,8 @@ export interface SubagentOwnerReasonParams {
|
|
|
2582
2736
|
export interface SubagentResult {
|
|
2583
2737
|
/** Artifact references, verbatim. */
|
|
2584
2738
|
artifactRefs: string[];
|
|
2739
|
+
/** `true` once the parent consumed the result (the inbox join fact the gate-off drain arm folds into the `Finished` marker — tdd SS4.5.7). Absent otherwise; never cleared once set. Clients mint the `Finished` marker off this flag instead of re-deriving the join. */
|
|
2740
|
+
drained?: boolean;
|
|
2585
2741
|
/** Error kind, verbatim durable vocabulary, when the child failed. */
|
|
2586
2742
|
errorKind?: string;
|
|
2587
2743
|
/** Evidence references, verbatim. */
|
|
@@ -2871,6 +3027,8 @@ export interface TurnInputPart {
|
|
|
2871
3027
|
mediaType?: string;
|
|
2872
3028
|
/** The skill to invoke, required on a `skill` part (tdd SS3.2, SS3.22.3; ADR 32471 D4): a bare or plugin-qualified shortcut token from `skill/list`. The HOST resolves and expands; an unknown selector is the typed `-32032 skillNotFound` request error. */
|
|
2873
3029
|
selector?: string;
|
|
3030
|
+
/** The picked copy's source, optional on a `skill` part (tdd SS3.22.3; ADR 32471 D12): the D2 catalog-row `source` values. When present the host resolves the exact `(selector, source)` row; when absent D4's bare resolution applies byte-for-byte. Closed: an unknown value is `invalidParams`, never a fall-through. */
|
|
3031
|
+
source?: SkillInvocationSource;
|
|
2874
3032
|
/** User prompt text, on a `text` part. Multiple text parts are joined in order into the turn's prompt. */
|
|
2875
3033
|
text?: string;
|
|
2876
3034
|
/** The part type. */
|
|
@@ -3491,9 +3649,9 @@ export interface WorkflowTokenBudget {
|
|
|
3491
3649
|
}
|
|
3492
3650
|
|
|
3493
3651
|
/** Every wire method in this schema (SS1.9 index). */
|
|
3494
|
-
export type MspMethod = "initialize" | "subagent/sendMessage" | "subagent/followupTask" | "subagent/interrupt" | "subagent/stop" | "subagent/resume" | "subagent/reopen" | "subagent/close" | "subagent/readResult" | "session/start" | "session/resume" | "session/fork" | "session/list" | "session/read" | "session/sideChat" | "turn/start" | "turn/steer" | "turn/interrupt" | "turn/cancel" | "turn/unqueue" | "session/compact" | "session/setModel" | "session/rename" | "session/setReasoningEffort" | "session/userShell" | "model/list" | "skill/list" | "skill/setActivation" | "skill/import" | "hook/list" | "plugin/list" | "plugin/install" | "plugin/marketplaceAdd" | "plugin/marketplaceUpdate" | "plugin/marketplaceRemove" | "task/background" | "task/stop" | "task/stopAll" | "task/list" | "goal/set" | "goal/edit" | "goal/clear" | "goal/pause" | "goal/resume" | "workflow/cancel" | "workflow/childControl" | "workflow/pause" | "workflow/resume" | "media/upload" | "view/subscribe" | "view/unsubscribe" | "view/page" | "item/readOutput" | "approval/decide" | "approval/listPending" | "session/setApprovalMode" | "userInput/answer" | "userInput/cancel" | "userInput/clarify" | "userInput/interrupt" | "usage/read" | "feedback/submit" | "recap/request" | "recap/cancel" | "computerUseSettings/read" | "computerUseSettings/update" | "computerUseSetup/read" | "computerUseSetup/start" | "computerUseSetup/check";
|
|
3652
|
+
export type MspMethod = "initialize" | "subagent/sendMessage" | "subagent/followupTask" | "subagent/interrupt" | "subagent/stop" | "subagent/resume" | "subagent/reopen" | "subagent/close" | "subagent/readResult" | "session/start" | "session/resume" | "session/fork" | "session/leave" | "session/list" | "session/read" | "session/sideChat" | "turn/start" | "turn/steer" | "turn/interrupt" | "turn/cancel" | "turn/unqueue" | "session/compact" | "session/setModel" | "session/rename" | "session/setReasoningEffort" | "session/userShell" | "model/list" | "skill/list" | "skill/setActivation" | "skill/import" | "hook/list" | "plugin/list" | "plugin/install" | "plugin/marketplaceAdd" | "plugin/marketplaceUpdate" | "plugin/marketplaceRemove" | "task/background" | "task/stop" | "task/stopAll" | "task/list" | "goal/set" | "goal/edit" | "goal/clear" | "goal/pause" | "goal/resume" | "workflow/cancel" | "workflow/childControl" | "workflow/pause" | "workflow/resume" | "media/upload" | "view/subscribe" | "view/unsubscribe" | "view/page" | "item/readOutput" | "approval/decide" | "approval/listPending" | "session/setApprovalMode" | "userInput/answer" | "userInput/cancel" | "userInput/clarify" | "userInput/interrupt" | "usage/read" | "feedback/submit" | "recap/request" | "recap/cancel" | "computerUseSettings/read" | "computerUseSettings/update" | "computerUseSetup/read" | "computerUseSetup/start" | "computerUseSetup/check";
|
|
3495
3653
|
/** Every wire notification in this schema (SS1.9 index). */
|
|
3496
|
-
export type MspNotification = "initialized" | "session/started" | "session/closed" | "skill/changed" | "turn/started" | "turn/completed" | "turn/retracted" | "turn/retryScheduled" | "turn/modelRetryScheduled" | "turn/unqueued" | "turn/foregroundCompleted" | "item/started" | "item/updated" | "item/delta" | "item/completed" | "view/gap" | "approval/requested" | "approval/updated" | "approval/reviewing" | "approval/resolved" | "userInput/requested" | "userInput/settled" | "userInput/engaged" | "session/modelChanged" | "session/reasoningEffortChanged" | "session/statusChanged" | "session/goalChanged" | "session/todoListChanged" | "session/branchChanged" | "session/tokenUsage" | "session/contextUsage" | "session/approvalModeChanged" | "recap/completed" | "session/modelRouteUnserved" | "session/nameChanged" | "session/viewHealthChanged" | "session/listChanged" | "usage/changed" | "computerUseSetup/changed" | "plugin/changed" | "plugin/marketplaceChanged";
|
|
3654
|
+
export type MspNotification = "initialized" | "session/started" | "session/closed" | "session/leaveCompleted" | "skill/changed" | "turn/started" | "turn/completed" | "turn/retracted" | "turn/retryScheduled" | "turn/modelRetryScheduled" | "turn/unqueued" | "turn/foregroundCompleted" | "item/started" | "item/updated" | "item/delta" | "item/completed" | "view/gap" | "approval/requested" | "approval/updated" | "approval/reviewing" | "approval/resolved" | "userInput/requested" | "userInput/settled" | "userInput/engaged" | "session/modelChanged" | "session/reasoningEffortChanged" | "session/statusChanged" | "session/goalChanged" | "session/todoListChanged" | "session/branchChanged" | "session/tokenUsage" | "session/contextUsage" | "session/approvalModeChanged" | "recap/completed" | "session/modelRouteUnserved" | "session/nameChanged" | "session/viewHealthChanged" | "session/listChanged" | "usage/changed" | "computerUseSetup/changed" | "plugin/changed" | "plugin/marketplaceChanged" | "monitor/inboxItemAdmitted" | "monitor/inboxItemDrained" | "monitor/inboxItemVoided";
|
|
3497
3655
|
/** Every server-initiated wire request in this schema (SS5.3/SS5.10.1 index). */
|
|
3498
3656
|
export type MspServerRequest = "approval/request" | "userInput/request";
|
|
3499
3657
|
/** Every error `data.kind` in this schema's error table (SS1.6) — each code's primary kind plus its override kinds. */
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@muse-code/sdk",
|
|
3
|
-
"version": "1.4.
|
|
3
|
+
"version": "1.4.11",
|
|
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",
|