@muse-code/sdk 1.4.14 → 1.4.20
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 +65 -3
- package/dist/src/connection/connection.d.ts +21 -4
- package/dist/src/connection/connection.js +52 -9
- package/dist/src/connection/discovery.d.ts +14 -0
- package/dist/src/connection/discovery.js +39 -0
- package/dist/src/connection/spawn.d.ts +24 -4
- package/dist/src/connection/spawn.js +5 -2
- package/dist/src/errors.d.ts +38 -0
- package/dist/src/errors.js +53 -0
- package/dist/src/facade/client.d.ts +165 -13
- package/dist/src/facade/client.js +325 -28
- package/dist/src/facade/host-death.d.ts +5 -1
- package/dist/src/facade/host-death.js +5 -1
- package/dist/src/facade/run.d.ts +50 -0
- package/dist/src/facade/run.js +132 -0
- package/dist/src/facade/session.d.ts +139 -5
- package/dist/src/facade/session.js +372 -6
- package/dist/src/facade/turn-handle.d.ts +88 -6
- package/dist/src/facade/turn-handle.js +20 -4
- package/dist/src/facade/turn-submit.d.ts +27 -16
- package/dist/src/facade/turn-submit.js +68 -28
- package/dist/src/fingerprint.d.ts +4 -18
- package/dist/src/fingerprint.js +30 -20
- package/dist/src/fingerprint.stamped.d.ts +1 -0
- package/dist/src/fingerprint.stamped.js +6 -0
- package/dist/src/fold/extension.d.ts +39 -0
- package/dist/src/fold/extension.js +49 -0
- package/dist/src/fold/session-fold.d.ts +30 -5
- package/dist/src/fold/session-fold.js +86 -1
- package/dist/src/index.d.ts +7 -5
- package/dist/src/index.js +1 -1
- package/dist/src/msp.d.ts +391 -33
- package/package.json +3 -1
|
@@ -35,23 +35,44 @@
|
|
|
35
35
|
* chain close that gap — add a member upstream and the BUILD fails here until
|
|
36
36
|
* it is forwarded (or explicitly allow-listed as unforwardable).
|
|
37
37
|
*/
|
|
38
|
-
import {
|
|
39
|
-
import {
|
|
38
|
+
import { discoverMuseBin } from "../connection/discovery.js";
|
|
39
|
+
import { initializeAnswered, SIGTERM_GRACE_MS, spawnMspConnection } from "../connection/spawn.js";
|
|
40
|
+
import { MuseCapabilityNotGrantedError, MuseFacadeOwnedMethodError, MuseSessionDiscardedError, PermissionProfileNotApplied, } from "../errors.js";
|
|
40
41
|
import { DiscardedSessions } from "./discarded.js";
|
|
41
|
-
import {
|
|
42
|
-
import {
|
|
42
|
+
import { fireExtensions } from "../fold/extension.js";
|
|
43
|
+
import { isAbnormalHostDeath, MuseHostDiedError, readSessionDurability } from "./host-death.js";
|
|
44
|
+
import { MspError, peerEndCause, ProtocolError } from "../connection/connection.js";
|
|
43
45
|
import { hostStartFailure } from "./host-start.js";
|
|
44
|
-
import { Session } from "./session.js";
|
|
46
|
+
import { pumpDropsApplyResults, Session } from "./session.js";
|
|
45
47
|
/**
|
|
46
|
-
*
|
|
47
|
-
*
|
|
48
|
-
*
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
48
|
+
* Run a caller's observer so neither its throw nor an async observer's
|
|
49
|
+
* rejection escapes: in the read loop a throw ends the connection every session
|
|
50
|
+
* shares, and an unhandled rejection kills the embedder.
|
|
51
|
+
*/
|
|
52
|
+
function observe(call, onFailure) {
|
|
53
|
+
let result;
|
|
54
|
+
try {
|
|
55
|
+
result = call();
|
|
56
|
+
}
|
|
57
|
+
catch (error) {
|
|
58
|
+
onFailure(error);
|
|
59
|
+
return;
|
|
60
|
+
}
|
|
61
|
+
if (typeof result?.then === "function") {
|
|
62
|
+
result.then(undefined, onFailure);
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
/**
|
|
66
|
+
* Every `StartParams` member `startSession` forwards. `config` is forwarded
|
|
67
|
+
* only behind the `sessionMcp` grant check (`#forwardConfig`),
|
|
68
|
+
* `previousSessionId` and `clear` are excluded because the facade starts root
|
|
69
|
+
* sessions (the predecessor link and the `/clear` marker belong to a client
|
|
70
|
+
* that switches sessions, as does the `switchPolicy` member), and `spawnedBy`
|
|
71
|
+
* because the facade does not expose a spawner yet.
|
|
52
72
|
*/
|
|
53
73
|
const START_FORWARDED = [
|
|
54
74
|
"approvalMode",
|
|
75
|
+
"config",
|
|
55
76
|
"providerId",
|
|
56
77
|
"sessionId",
|
|
57
78
|
"workspaceRoot",
|
|
@@ -61,10 +82,64 @@ const START_FORWARDED = [
|
|
|
61
82
|
"recoveryMode",
|
|
62
83
|
];
|
|
63
84
|
/**
|
|
64
|
-
* Every `ResumeParams` member `resumeSession` forwards
|
|
65
|
-
*
|
|
85
|
+
* Every `ResumeParams` member `resumeSession` forwards; `config` rides the
|
|
86
|
+
* same `sessionMcp` grant check as the start facade above.
|
|
87
|
+
*/
|
|
88
|
+
const RESUME_FORWARDED = [
|
|
89
|
+
"sessionId",
|
|
90
|
+
"config",
|
|
91
|
+
"cursor",
|
|
92
|
+
"excludeItems",
|
|
93
|
+
"history",
|
|
94
|
+
"modelId",
|
|
95
|
+
"permissionProfile",
|
|
96
|
+
"recoveryMode",
|
|
97
|
+
];
|
|
98
|
+
/**
|
|
99
|
+
* The wire methods whose state the facade owns, refused by `command`
|
|
100
|
+
* (FR-79107-2). `initialize` is the handshake `spawn` runs; `session/start` and
|
|
101
|
+
* `session/resume` register the `Session` the pump routes to; `turn/start`,
|
|
102
|
+
* `turn/steer`, `turn/unqueue`, `approval/decide`, and `userInput/answer`
|
|
103
|
+
* carry the pending-command, approval, and answer state their verbs keep (a
|
|
104
|
+
* steer is a pending submission and an accepted unqueue retires its queued
|
|
105
|
+
* entry); `view/page` is the gap fill's; and
|
|
106
|
+
* `view/subscribe`/`view/unsubscribe` change the subscription set the pump
|
|
107
|
+
* routes by, so a raw unsubscribe would silently starve a live `Session`.
|
|
66
108
|
*/
|
|
67
|
-
const
|
|
109
|
+
const FACADE_OWNED_METHODS = [
|
|
110
|
+
"initialize",
|
|
111
|
+
"session/start",
|
|
112
|
+
"session/resume",
|
|
113
|
+
"turn/start",
|
|
114
|
+
"turn/steer",
|
|
115
|
+
"turn/unqueue",
|
|
116
|
+
"approval/decide",
|
|
117
|
+
"userInput/answer",
|
|
118
|
+
"view/page",
|
|
119
|
+
"view/subscribe",
|
|
120
|
+
"view/unsubscribe",
|
|
121
|
+
];
|
|
122
|
+
/**
|
|
123
|
+
* The stable facade-owned methods, and only those. The experimental host
|
|
124
|
+
* stop (`host/shutdown`) is the orderly stop `close()` owns too, and the
|
|
125
|
+
* Python twin refuses it, but this package names no experimental-only
|
|
126
|
+
* method: FR-97527-5's leak gate derives that set from the two schema
|
|
127
|
+
* bundles at check time, and a refusal list counts as naming (#99842). A
|
|
128
|
+
* caller that sends it raw owns the host exit that follows.
|
|
129
|
+
*/
|
|
130
|
+
const FACADE_OWNED = new Set(FACADE_OWNED_METHODS);
|
|
131
|
+
/** Every `SessionListParams` member `listSessions` forwards. */
|
|
132
|
+
const LIST_FORWARDED = ["cursor", "filter", "limit", "updatedAfter", "workspaceRoot"];
|
|
133
|
+
/**
|
|
134
|
+
* The caller's capability posture with `sessionMcp` added to its requests,
|
|
135
|
+
* each requested name once (ADR 32760 D3: the facade requests the grant its
|
|
136
|
+
* `config` forwarding checks). A host grants only what was requested.
|
|
137
|
+
*/
|
|
138
|
+
function withSessionMcpRequested(capabilities) {
|
|
139
|
+
const requested = new Set(capabilities?.requestedCapabilities ?? []);
|
|
140
|
+
requested.add("sessionMcp");
|
|
141
|
+
return { ...capabilities, requestedCapabilities: [...requested] };
|
|
142
|
+
}
|
|
68
143
|
/**
|
|
69
144
|
* The committed profile id a session snapshot claims, or null when the
|
|
70
145
|
* snapshot is silent (the stable bundle strips the member; absent and null
|
|
@@ -93,8 +168,18 @@ export class MuseClient {
|
|
|
93
168
|
#connection;
|
|
94
169
|
#durability;
|
|
95
170
|
#discarded;
|
|
171
|
+
#extensions;
|
|
96
172
|
/** Sessions this client opened, so one death notification reaches them all. */
|
|
97
173
|
#sessions = new Set();
|
|
174
|
+
/** `onNotification` subscriptions, one entry each so a function added twice unsubscribes once per call. */
|
|
175
|
+
#listeners = new Set();
|
|
176
|
+
#notificationFailureHandlers = new Set();
|
|
177
|
+
#protocolErrorHandlers = new Set();
|
|
178
|
+
/**
|
|
179
|
+
* Set on the first `onProtocolError`, which then claims the connection's one
|
|
180
|
+
* handler: a client nobody observes leaves the caller's own handler alone.
|
|
181
|
+
*/
|
|
182
|
+
#protocolErrorsClaimed = false;
|
|
98
183
|
/**
|
|
99
184
|
* Frames naming a session this client has not registered YET, held only
|
|
100
185
|
* while a `session/start`/`session/resume` is in flight (#49790): the host
|
|
@@ -124,6 +209,7 @@ export class MuseClient {
|
|
|
124
209
|
// no current consumer spans two clients over one host lineage, so a
|
|
125
210
|
// sharing knob would be declared-ahead surface (Constitution XI).
|
|
126
211
|
this.#discarded = new DiscardedSessions();
|
|
212
|
+
this.#extensions = options.extensions ?? [];
|
|
127
213
|
this.#child = options.host?.child;
|
|
128
214
|
this.#initializeResult = options.host?.initializeResult;
|
|
129
215
|
// THE ONE INBOUND PUMP (FR-018/FR-019). `Session.apply` is the only event
|
|
@@ -131,9 +217,14 @@ export class MuseClient {
|
|
|
131
217
|
// consumer has no way to hear a single view frame: every turn wait hangs
|
|
132
218
|
// (SS3.1.4) and `onApproval` can never fire. `Connection.onNotification`
|
|
133
219
|
// holds ONE handler — this client claims it, which is part of what
|
|
134
|
-
// "MuseClient owns the connection" means; a
|
|
135
|
-
//
|
|
136
|
-
|
|
220
|
+
// "MuseClient owns the connection" means; a caller hears the feed through
|
|
221
|
+
// `onNotification`, after `#route` has handed each frame to its session
|
|
222
|
+
// (a frame held while that session's open is in flight is heard first).
|
|
223
|
+
this.#connection.onNotification((notification) => {
|
|
224
|
+
this.#route(notification);
|
|
225
|
+
for (const entry of [...this.#listeners])
|
|
226
|
+
this.#notify(entry.listener, notification);
|
|
227
|
+
});
|
|
137
228
|
// A question or approval still open at resume is re-sent as a
|
|
138
229
|
// `userInput/request` or `approval/request` server request (tdd SS5.6,
|
|
139
230
|
// SS5.10). Each is routed in arrival order and answered with the SS5.3.3
|
|
@@ -161,23 +252,31 @@ export class MuseClient {
|
|
|
161
252
|
// Registered at construction, not at the first session: an EOF can land
|
|
162
253
|
// before any session exists, and the flag has to be read at that moment.
|
|
163
254
|
void this.#connection.closed.then(() => this.#transportClosed());
|
|
255
|
+
// A call the connection fails because the host died says how it ended;
|
|
256
|
+
// read at the EOF, so a close() of ours leaves the bare error.
|
|
257
|
+
this.#connection[peerEndCause](() => this.#hostDeathCause());
|
|
164
258
|
}
|
|
165
259
|
/**
|
|
166
260
|
* Deliver one view notification to the session(s) it names.
|
|
167
261
|
*
|
|
168
|
-
* A frame naming NO session
|
|
169
|
-
*
|
|
170
|
-
*
|
|
171
|
-
*
|
|
172
|
-
*
|
|
173
|
-
*
|
|
174
|
-
*
|
|
175
|
-
*
|
|
262
|
+
* A frame naming NO session goes to the connection extensions (FR-97527-3:
|
|
263
|
+
* host-wide state names no session) rather than to every session:
|
|
264
|
+
* `Session.apply` already tolerates unknown methods, but only the
|
|
265
|
+
* frames that name a `sessionId` have a session owner to route to. A frame
|
|
266
|
+
* naming an UNKNOWN session is dropped for the same reason — routing it
|
|
267
|
+
* anywhere would trip the foreign-frame throw on a session it does not
|
|
268
|
+
* belong to — UNLESS an open is in flight, when it may be that open's own
|
|
269
|
+
* session named by the server before the awaiting promise has run (#49790):
|
|
270
|
+
* then it is held for `#openSession` to fold, or for `#open` to clear.
|
|
176
271
|
*/
|
|
177
272
|
#route(notification) {
|
|
178
273
|
const named = notification.params?.sessionId;
|
|
179
|
-
if (typeof named !== "string")
|
|
274
|
+
if (typeof named !== "string") {
|
|
275
|
+
// FR-97527-3: connection extensions share the fold's call-and-report
|
|
276
|
+
// loop, objects-only guard included.
|
|
277
|
+
fireExtensions(this.#extensions, notification.method, notification.params);
|
|
180
278
|
return;
|
|
279
|
+
}
|
|
181
280
|
let delivered = false;
|
|
182
281
|
for (const session of this.#sessions) {
|
|
183
282
|
if (session.sessionId === named) {
|
|
@@ -193,6 +292,16 @@ export class MuseClient {
|
|
|
193
292
|
else
|
|
194
293
|
held.push(notification);
|
|
195
294
|
}
|
|
295
|
+
/** Call one listener, sending its throw or rejection to every `onNotificationError` handler. */
|
|
296
|
+
#notify(listener, notification) {
|
|
297
|
+
observe(() => listener(notification), (error) => {
|
|
298
|
+
// A failure observer failing too is swallowed: like
|
|
299
|
+
// `ApprovalRouter.#report`, there is no one left to tell.
|
|
300
|
+
for (const entry of [...this.#notificationFailureHandlers]) {
|
|
301
|
+
observe(() => entry.handler(error, notification), () => undefined);
|
|
302
|
+
}
|
|
303
|
+
});
|
|
304
|
+
}
|
|
196
305
|
/**
|
|
197
306
|
* Spawn an owned host, run the SS1.4 handshake, and hand back a client whose
|
|
198
307
|
* durability profile came from that handshake (FR-018).
|
|
@@ -202,6 +311,9 @@ export class MuseClient {
|
|
|
202
311
|
* absent/unrecognized distinction load-bearing, and a caller re-deriving it
|
|
203
312
|
* by hand is a caller that can get it wrong.
|
|
204
313
|
*
|
|
314
|
+
* Rejects with {@link MuseHostDiscoveryError} before starting anything when
|
|
315
|
+
* `museBin` is omitted and no executable `muse` is on `PATH`.
|
|
316
|
+
*
|
|
205
317
|
* Rejects with {@link MuseHostStartError} when the host is lost before the
|
|
206
318
|
* handshake completes (the binary could not be spawned, or the process
|
|
207
319
|
* ended first — exit code or signal plus the bounded stderr tail;
|
|
@@ -212,8 +324,11 @@ export class MuseClient {
|
|
|
212
324
|
* no schema fingerprint.
|
|
213
325
|
*/
|
|
214
326
|
static async spawn(options) {
|
|
327
|
+
// The process's own PATH, never `options.env`'s: the host is found the
|
|
328
|
+
// way the Rust and Python SDKs find it, whatever environment it gets.
|
|
329
|
+
const command = await discoverMuseBin(options.museBin, process.env["PATH"], process.platform);
|
|
215
330
|
const handshake = spawnMspConnection({
|
|
216
|
-
command
|
|
331
|
+
command,
|
|
217
332
|
...(options.args === undefined ? {} : { args: options.args }),
|
|
218
333
|
...(options.cwd === undefined ? {} : { cwd: options.cwd }),
|
|
219
334
|
...(options.env === undefined ? {} : { env: options.env }),
|
|
@@ -221,12 +336,13 @@ export class MuseClient {
|
|
|
221
336
|
...(options.shutdownTimeoutMs === undefined
|
|
222
337
|
? {}
|
|
223
338
|
: { shutdownTimeoutMs: options.shutdownTimeoutMs }),
|
|
339
|
+
...(options.spawnFn === undefined ? {} : { spawnFn: options.spawnFn }),
|
|
224
340
|
});
|
|
225
341
|
let spawned;
|
|
226
342
|
try {
|
|
227
343
|
spawned = await handshake.initialize({
|
|
228
344
|
clientInfo: options.clientInfo,
|
|
229
|
-
|
|
345
|
+
capabilities: withSessionMcpRequested(options.capabilities),
|
|
230
346
|
});
|
|
231
347
|
}
|
|
232
348
|
catch (error) {
|
|
@@ -252,6 +368,7 @@ export class MuseClient {
|
|
|
252
368
|
}
|
|
253
369
|
return new MuseClient(spawned.connection, {
|
|
254
370
|
durability: readSessionDurability(spawned.initializeResult),
|
|
371
|
+
...(options.extensions === undefined ? {} : { extensions: options.extensions }),
|
|
255
372
|
host: spawned,
|
|
256
373
|
});
|
|
257
374
|
}
|
|
@@ -278,6 +395,72 @@ export class MuseClient {
|
|
|
278
395
|
}
|
|
279
396
|
return this.#child.exit;
|
|
280
397
|
}
|
|
398
|
+
/**
|
|
399
|
+
* Settles when the connection closes for any reason: `close()`, the host
|
|
400
|
+
* hanging up, or a transport failure.
|
|
401
|
+
*/
|
|
402
|
+
get closed() {
|
|
403
|
+
return this.#connection.closed;
|
|
404
|
+
}
|
|
405
|
+
/**
|
|
406
|
+
* Hear every server notification in wire order, including those naming no
|
|
407
|
+
* session (`usage/changed`, `account/loginCompleted`) or a session this
|
|
408
|
+
* client did not open. A frame naming a session this client has opened
|
|
409
|
+
* reaches the listener after that session has applied it: folded, or, while
|
|
410
|
+
* the session fills a gap, buffered and folded when the fill completes. One
|
|
411
|
+
* that arrives while its session's start/resume is still in flight reaches
|
|
412
|
+
* the listener first, and the session folds it before the verb returns.
|
|
413
|
+
* Returns the unsubscribe function.
|
|
414
|
+
*
|
|
415
|
+
* The frame is read-only: it is the one the session folds, which for a held
|
|
416
|
+
* or buffered frame happens after the listener runs. Like a `Connection`
|
|
417
|
+
* handler, the listener runs in the read loop, so it must not block. A throw, or an async listener's rejection, goes to every
|
|
418
|
+
* `onNotificationError` handler; the other listeners still hear the frame
|
|
419
|
+
* and the connection stays open.
|
|
420
|
+
*/
|
|
421
|
+
onNotification(listener) {
|
|
422
|
+
const entry = { listener };
|
|
423
|
+
this.#listeners.add(entry);
|
|
424
|
+
return () => {
|
|
425
|
+
this.#listeners.delete(entry);
|
|
426
|
+
};
|
|
427
|
+
}
|
|
428
|
+
/**
|
|
429
|
+
* Hear what an `onNotification` listener threw or rejected with. With no
|
|
430
|
+
* handler the failure is dropped; either way the pump keeps running.
|
|
431
|
+
* Returns a function that removes this one subscription.
|
|
432
|
+
*/
|
|
433
|
+
onNotificationError(handler) {
|
|
434
|
+
const entry = { handler };
|
|
435
|
+
this.#notificationFailureHandlers.add(entry);
|
|
436
|
+
return () => {
|
|
437
|
+
this.#notificationFailureHandlers.delete(entry);
|
|
438
|
+
};
|
|
439
|
+
}
|
|
440
|
+
/**
|
|
441
|
+
* Hear each framing or correlation violation the connection detects
|
|
442
|
+
* (`Connection.onProtocolError`). The handler's own throw or rejection is
|
|
443
|
+
* swallowed rather than ending the connection; it is already the observer
|
|
444
|
+
* of failures, so there is no one left to tell. The first call takes over
|
|
445
|
+
* `Connection.onProtocolError`, replacing a handler set there directly (and
|
|
446
|
+
* a later direct `connection.onProtocolError(...)` silences these
|
|
447
|
+
* subscribers). Returns a function that removes this one subscription.
|
|
448
|
+
*/
|
|
449
|
+
onProtocolError(handler) {
|
|
450
|
+
if (!this.#protocolErrorsClaimed) {
|
|
451
|
+
this.#protocolErrorsClaimed = true;
|
|
452
|
+
this.#connection.onProtocolError((error) => {
|
|
453
|
+
for (const entry of [...this.#protocolErrorHandlers]) {
|
|
454
|
+
observe(() => entry.handler(error), () => undefined);
|
|
455
|
+
}
|
|
456
|
+
});
|
|
457
|
+
}
|
|
458
|
+
const entry = { handler };
|
|
459
|
+
this.#protocolErrorHandlers.add(entry);
|
|
460
|
+
return () => {
|
|
461
|
+
this.#protocolErrorHandlers.delete(entry);
|
|
462
|
+
};
|
|
463
|
+
}
|
|
281
464
|
/** The durability profile every session this client opens inherits. */
|
|
282
465
|
get durability() {
|
|
283
466
|
return this.#durability;
|
|
@@ -303,6 +486,8 @@ export class MuseClient {
|
|
|
303
486
|
// other start members (undefined stays omitted).
|
|
304
487
|
if (options.permissionProfile != null)
|
|
305
488
|
params.permissionProfile = options.permissionProfile;
|
|
489
|
+
if (options.config != null)
|
|
490
|
+
params.config = this.#forwardConfig("session/start", options.config);
|
|
306
491
|
// TEST-42624-10: a caller that requires its selection proves it, never
|
|
307
492
|
// assuming the host default. The flag without the member is API misuse
|
|
308
493
|
// (plain Error, like the other misuse guards here), raised pre-wire.
|
|
@@ -376,11 +561,92 @@ export class MuseClient {
|
|
|
376
561
|
params.recoveryMode = options.recoveryMode;
|
|
377
562
|
if (options.permissionProfile != null)
|
|
378
563
|
params.permissionProfile = options.permissionProfile;
|
|
564
|
+
if (options.config != null)
|
|
565
|
+
params.config = this.#forwardConfig("session/resume", options.config);
|
|
379
566
|
return this.#open("session/resume", params, (raw) => ({
|
|
380
567
|
result: raw,
|
|
381
568
|
verb: "session/resume",
|
|
382
569
|
}), { onApproval: options.onApproval, onApprovalError: options.onApprovalError });
|
|
383
570
|
}
|
|
571
|
+
/**
|
|
572
|
+
* List stored sessions (`session/list`), including text search via
|
|
573
|
+
* `filter.text`. A read-only list: rides `request()`, not `command()`
|
|
574
|
+
* (see `Session.listTasks`).
|
|
575
|
+
*/
|
|
576
|
+
async listSessions(options = {}) {
|
|
577
|
+
// One list drives both the exhaustiveness pin and the forwarding, so a
|
|
578
|
+
// regenerated member cannot compile yet be dropped on the wire (#76737).
|
|
579
|
+
const params = {};
|
|
580
|
+
for (const member of LIST_FORWARDED) {
|
|
581
|
+
const value = options[member];
|
|
582
|
+
if (value != null)
|
|
583
|
+
params[member] = value;
|
|
584
|
+
}
|
|
585
|
+
const ack = await this.#connection.request("session/list", params);
|
|
586
|
+
return ack;
|
|
587
|
+
}
|
|
588
|
+
/**
|
|
589
|
+
* List the models the host accepts in `Session.setModel` (`model/list`).
|
|
590
|
+
* With `sessionId`, that session's current model is flagged `isActive`. A
|
|
591
|
+
* query: rides `request()`, like `listSessions`.
|
|
592
|
+
*/
|
|
593
|
+
async listModels(options = {}) {
|
|
594
|
+
const params = {};
|
|
595
|
+
if (options.sessionId != null)
|
|
596
|
+
params["sessionId"] = options.sessionId;
|
|
597
|
+
const ack = await this.#connection.request("model/list", params);
|
|
598
|
+
return ack;
|
|
599
|
+
}
|
|
600
|
+
/**
|
|
601
|
+
* Read the host's last-observed subscription usage (`usage/read`) without a
|
|
602
|
+
* model call; `usage` is absent when the host has observed nothing.
|
|
603
|
+
*/
|
|
604
|
+
async readUsage() {
|
|
605
|
+
const ack = await this.#connection.request("usage/read");
|
|
606
|
+
return ack;
|
|
607
|
+
}
|
|
608
|
+
/**
|
|
609
|
+
* Send a wire method directly (FR-79107-2), typically one the facade does
|
|
610
|
+
* not wrap, experimental ones included, through the
|
|
611
|
+
* same `Connection.command()` the verbs use: the connection mints the
|
|
612
|
+
* `commandId`, retries a nothing-admitted refusal under the same id, and
|
|
613
|
+
* checks the ack's echo. `options` are that seam's own. An experimental
|
|
614
|
+
* method needs a client spawned with `capabilities: { experimentalApi: true }`
|
|
615
|
+
* (otherwise the host refuses it with an `MspError` of kind
|
|
616
|
+
* `experimentalRequired`, code -32601) and may change without notice.
|
|
617
|
+
*
|
|
618
|
+
* Refused before anything is written, with `MuseFacadeOwnedMethodError`:
|
|
619
|
+
* the methods whose state the facade owns (`FACADE_OWNED_METHODS`); the
|
|
620
|
+
* experimental host stop is not among them (this package names no
|
|
621
|
+
* experimental-only method), so sent raw it is the caller's own, and the
|
|
622
|
+
* exit it causes reaches your sessions as a host death; `close()` is the
|
|
623
|
+
* orderly stop. Frames
|
|
624
|
+
* the command causes still reach your sessions through the client's one
|
|
625
|
+
* inbound pump; this sends and returns the ack, nothing more. Params and
|
|
626
|
+
* ack stay untyped objects: the generated types carry no method-to-params
|
|
627
|
+
* map, and restating one here would drift from the schema.
|
|
628
|
+
*
|
|
629
|
+
* Each call keeps one fixed-size fingerprint for the connection's lifetime
|
|
630
|
+
* (FR-45137-1), so prefer `request` for a query you poll.
|
|
631
|
+
*/
|
|
632
|
+
async command(method, params, options) {
|
|
633
|
+
// The type binds TypeScript callers; this binds plain-JS ones.
|
|
634
|
+
if (FACADE_OWNED.has(method))
|
|
635
|
+
throw new MuseFacadeOwnedMethodError(method);
|
|
636
|
+
return this.#connection.command(method, params, options);
|
|
637
|
+
}
|
|
638
|
+
/**
|
|
639
|
+
* Send a wire request directly (FR-79107-2), typically a query the facade
|
|
640
|
+
* does not wrap, experimental ones included, through `Connection.request()`:
|
|
641
|
+
* no `commandId`, no retry, and omitted `params` stay off the frame.
|
|
642
|
+
* Refuses the same facade-owned methods as `command`, the same way, and
|
|
643
|
+
* needs the same `experimentalApi` opt-in for an experimental method.
|
|
644
|
+
*/
|
|
645
|
+
async request(method, params) {
|
|
646
|
+
if (FACADE_OWNED.has(method))
|
|
647
|
+
throw new MuseFacadeOwnedMethodError(method);
|
|
648
|
+
return this.#connection.request(method, params);
|
|
649
|
+
}
|
|
384
650
|
/**
|
|
385
651
|
* Shut the host down in an orderly way (SS2.1.2); the shutdown this causes
|
|
386
652
|
* is not reported to your sessions as a host death.
|
|
@@ -432,6 +698,7 @@ export class MuseClient {
|
|
|
432
698
|
connection: this.#connection,
|
|
433
699
|
discarded: this.#discarded,
|
|
434
700
|
durability: this.#durability,
|
|
701
|
+
extensions: this.#extensions,
|
|
435
702
|
opening,
|
|
436
703
|
sessionId,
|
|
437
704
|
});
|
|
@@ -441,6 +708,8 @@ export class MuseClient {
|
|
|
441
708
|
session.onApprovalError(approvals.onApprovalError);
|
|
442
709
|
if (approvals.onApproval !== undefined)
|
|
443
710
|
session.onApproval(approvals.onApproval);
|
|
711
|
+
// `#route` drops what `apply` returns (FR-81734-1).
|
|
712
|
+
session[pumpDropsApplyResults]();
|
|
444
713
|
this.#sessions.add(session);
|
|
445
714
|
// The frames that named this session while its verb was in flight fold
|
|
446
715
|
// NOW, in arrival order — synchronously, so nothing the pump routes next
|
|
@@ -453,6 +722,20 @@ export class MuseClient {
|
|
|
453
722
|
}
|
|
454
723
|
return session;
|
|
455
724
|
}
|
|
725
|
+
/**
|
|
726
|
+
* The `config` to forward, or a typed refusal before anything is sent
|
|
727
|
+
* (FR-79107-3). Per-session MCP servers need the `sessionMcp` grant in the
|
|
728
|
+
* handshake this client was built with (`spawn` requests it; a caller's own
|
|
729
|
+
* handshake must request it too); a client given no handshake cannot show
|
|
730
|
+
* it. A config naming no server needs no grant, as on the host (ADR 32760 D3).
|
|
731
|
+
*/
|
|
732
|
+
#forwardConfig(method, config) {
|
|
733
|
+
if (config.mcpServers == null || Object.keys(config.mcpServers).length === 0)
|
|
734
|
+
return config;
|
|
735
|
+
if (this.#initializeResult?.grantedCapabilities.includes("sessionMcp") === true)
|
|
736
|
+
return config;
|
|
737
|
+
throw new MuseCapabilityNotGrantedError("sessionMcp", method, "config.mcpServers needs the sessionMcp grant, which this connection's handshake does not hold (MuseClient.spawn requests it; a host withholds it when per-session MCP is turned off)");
|
|
738
|
+
}
|
|
456
739
|
#assertReattachAllowed(sessionId) {
|
|
457
740
|
// Two facts, both recorded by an ephemeral discharge: THIS session was
|
|
458
741
|
// discarded, or this client's own ephemeral host died (in which case there
|
|
@@ -467,6 +750,20 @@ export class MuseClient {
|
|
|
467
750
|
#survivesHostDeath() {
|
|
468
751
|
return this.#durability.kind === "durable";
|
|
469
752
|
}
|
|
753
|
+
/**
|
|
754
|
+
* Waits for the exit at most `SIGTERM_GRACE_MS`: a host that closed stdout
|
|
755
|
+
* but keeps running must not hold the failed calls past today's bare error.
|
|
756
|
+
*/
|
|
757
|
+
#hostDeathCause() {
|
|
758
|
+
if (this.#closing || this.#child === undefined)
|
|
759
|
+
return undefined;
|
|
760
|
+
const died = this.#child.exit.then((exit) => (isAbnormalHostDeath(exit) ? new MuseHostDiedError(exit) : undefined), () => undefined);
|
|
761
|
+
let timer;
|
|
762
|
+
const grace = new Promise((resolve) => {
|
|
763
|
+
timer = setTimeout(resolve, SIGTERM_GRACE_MS, undefined);
|
|
764
|
+
});
|
|
765
|
+
return Promise.race([died, grace]).finally(() => clearTimeout(timer));
|
|
766
|
+
}
|
|
470
767
|
/**
|
|
471
768
|
* The transport reached EOF. If this client did not cause it, that is
|
|
472
769
|
* SS2.13.3b's second death notification (T030 obligation b) and every session
|
|
@@ -105,7 +105,11 @@ export declare function isItemInProgress(item: Item): boolean;
|
|
|
105
105
|
export type AbnormalExit = Exclude<HostDeathNotification, {
|
|
106
106
|
kind: "cleanShutdown";
|
|
107
107
|
}>;
|
|
108
|
-
/**
|
|
108
|
+
/**
|
|
109
|
+
* The host died abnormally. On a session it means a durable host died and its
|
|
110
|
+
* terminals arrive on resume (FM-001); as the `cause` of a failed call, it
|
|
111
|
+
* reports how any host ended.
|
|
112
|
+
*/
|
|
109
113
|
export declare class MuseHostDiedError extends Error {
|
|
110
114
|
#private;
|
|
111
115
|
readonly exit: AbnormalExit;
|
|
@@ -70,7 +70,11 @@ export function isAbnormalHostDeath(notification) {
|
|
|
70
70
|
export function isItemInProgress(item) {
|
|
71
71
|
return item.status === IN_PROGRESS;
|
|
72
72
|
}
|
|
73
|
-
/**
|
|
73
|
+
/**
|
|
74
|
+
* The host died abnormally. On a session it means a durable host died and its
|
|
75
|
+
* terminals arrive on resume (FM-001); as the `cause` of a failed call, it
|
|
76
|
+
* reports how any host ended.
|
|
77
|
+
*/
|
|
74
78
|
export class MuseHostDiedError extends Error {
|
|
75
79
|
exit;
|
|
76
80
|
// The parameter is narrowed rather than checked: `cleanShutdown` is not a
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `Session.run` — one call from a prompt to the turn's final answer (spec
|
|
3
|
+
* 14990 FR-79108-1).
|
|
4
|
+
*
|
|
5
|
+
* Built only from facade verbs the session already has: `sendUserTurn`, the
|
|
6
|
+
* turn-wait, `items()`, and `unqueue`/`cancel` for an abort; the abort's
|
|
7
|
+
* unqueue goes through the session's internal `resendableUnqueue`, the same
|
|
8
|
+
* control holding one `commandId` across resends. It holds no state
|
|
9
|
+
* of its own and reaches the fold and the pending set only through those verbs
|
|
10
|
+
* and the read-only pending view, so every SS4.13 rule keeps applying exactly
|
|
11
|
+
* as it does for a hand-written `sendUserTurn` loop.
|
|
12
|
+
*/
|
|
13
|
+
import type { TokenUsage, TurnInputPart } from "../msp.js";
|
|
14
|
+
import { type Session } from "./session.js";
|
|
15
|
+
import type { FoldedItem, TurnOutcome } from "./turn-handle.js";
|
|
16
|
+
import type { SendUserTurnOptions } from "./turn-submit.js";
|
|
17
|
+
/**
|
|
18
|
+
* What `run` forwards to `turn/start`, plus the abort signal. Composed from
|
|
19
|
+
* `SendUserTurnOptions`, so a new `turn/start` member reaches `run` with no
|
|
20
|
+
* edit here. `composerInput` is left out: `run` hands back no SS4.13
|
|
21
|
+
* retirement, so there is nothing for it to restore.
|
|
22
|
+
*/
|
|
23
|
+
export type RunOptions = Readonly<Omit<SendUserTurnOptions<unknown>, "input" | "composerInput">> & {
|
|
24
|
+
/**
|
|
25
|
+
* Stops the turn. An already-aborted signal rejects at once and sends
|
|
26
|
+
* nothing. An abort while the turn is queued sends `turn/unqueue`, and
|
|
27
|
+
* `turn/cancel` if the turn launched first; while it runs, `turn/cancel`.
|
|
28
|
+
* `run` then waits for the server to end the turn and rejects with
|
|
29
|
+
* `signal.reason`. An abort once the turn has ended sends nothing.
|
|
30
|
+
*/
|
|
31
|
+
readonly signal?: AbortSignal;
|
|
32
|
+
};
|
|
33
|
+
/** What `run` resolves to once the server has ended the turn. */
|
|
34
|
+
export interface RunResult {
|
|
35
|
+
readonly turnId: string;
|
|
36
|
+
/** The server-authored outcome; a failed or cancelled turn still resolves. */
|
|
37
|
+
readonly outcome: TurnOutcome;
|
|
38
|
+
/**
|
|
39
|
+
* The `text` of the turn's last `agentMessage` item (in first-opened order)
|
|
40
|
+
* that completed and is not `"commentary"`: an absent or unknown
|
|
41
|
+
* `messagePhase` on a completed item reads as `"finalAnswer"`. `undefined`
|
|
42
|
+
* when the turn produced no such item.
|
|
43
|
+
*/
|
|
44
|
+
readonly finalText: string | undefined;
|
|
45
|
+
/** The turn's items as the fold holds them at the end, in first-opened order. */
|
|
46
|
+
readonly items: readonly FoldedItem[];
|
|
47
|
+
/** The turn's token usage from `turn/completed`; absent on other outcomes. */
|
|
48
|
+
readonly usage: TokenUsage | undefined;
|
|
49
|
+
}
|
|
50
|
+
export declare function runTurn<I>(host: Session<I>, input: string | readonly TurnInputPart[], options?: RunOptions): Promise<RunResult>;
|