@muse-code/sdk 1.4.15 → 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 +27 -0
- package/dist/src/connection/connection.d.ts +21 -4
- package/dist/src/connection/connection.js +50 -8
- package/dist/src/connection/spawn.d.ts +24 -4
- package/dist/src/connection/spawn.js +5 -2
- package/dist/src/errors.d.ts +6 -5
- package/dist/src/errors.js +7 -6
- package/dist/src/facade/client.d.ts +101 -13
- package/dist/src/facade/client.js +193 -33
- package/dist/src/facade/host-death.d.ts +5 -1
- package/dist/src/facade/host-death.js +5 -1
- package/dist/src/facade/session.d.ts +57 -3
- package/dist/src/facade/session.js +90 -12
- package/dist/src/facade/turn-handle.d.ts +23 -0
- package/dist/src/facade/turn-handle.js +1 -1
- package/dist/src/fingerprint.stamped.d.ts +1 -1
- package/dist/src/fingerprint.stamped.js +1 -1
- 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 +11 -0
- package/dist/src/fold/session-fold.js +13 -0
- package/dist/src/index.d.ts +3 -2
- package/dist/src/msp.d.ts +41 -8
- package/package.json +1 -1
|
@@ -36,20 +36,39 @@
|
|
|
36
36
|
* it is forwarded (or explicitly allow-listed as unforwardable).
|
|
37
37
|
*/
|
|
38
38
|
import { discoverMuseBin } from "../connection/discovery.js";
|
|
39
|
-
import { initializeAnswered, spawnMspConnection } from "../connection/spawn.js";
|
|
39
|
+
import { initializeAnswered, SIGTERM_GRACE_MS, spawnMspConnection } from "../connection/spawn.js";
|
|
40
40
|
import { MuseCapabilityNotGrantedError, MuseFacadeOwnedMethodError, MuseSessionDiscardedError, PermissionProfileNotApplied, } from "../errors.js";
|
|
41
41
|
import { DiscardedSessions } from "./discarded.js";
|
|
42
|
-
import {
|
|
43
|
-
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";
|
|
44
45
|
import { hostStartFailure } from "./host-start.js";
|
|
45
46
|
import { pumpDropsApplyResults, Session } from "./session.js";
|
|
47
|
+
/**
|
|
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
|
+
}
|
|
46
65
|
/**
|
|
47
66
|
* Every `StartParams` member `startSession` forwards. `config` is forwarded
|
|
48
67
|
* only behind the `sessionMcp` grant check (`#forwardConfig`),
|
|
49
|
-
* `previousSessionId`
|
|
50
|
-
* (the predecessor link
|
|
51
|
-
* the `switchPolicy` member), and `spawnedBy`
|
|
52
|
-
* expose a spawner yet.
|
|
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.
|
|
53
72
|
*/
|
|
54
73
|
const START_FORWARDED = [
|
|
55
74
|
"approvalMode",
|
|
@@ -100,6 +119,14 @@ const FACADE_OWNED_METHODS = [
|
|
|
100
119
|
"view/subscribe",
|
|
101
120
|
"view/unsubscribe",
|
|
102
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
|
+
*/
|
|
103
130
|
const FACADE_OWNED = new Set(FACADE_OWNED_METHODS);
|
|
104
131
|
/** Every `SessionListParams` member `listSessions` forwards. */
|
|
105
132
|
const LIST_FORWARDED = ["cursor", "filter", "limit", "updatedAfter", "workspaceRoot"];
|
|
@@ -141,8 +168,18 @@ export class MuseClient {
|
|
|
141
168
|
#connection;
|
|
142
169
|
#durability;
|
|
143
170
|
#discarded;
|
|
171
|
+
#extensions;
|
|
144
172
|
/** Sessions this client opened, so one death notification reaches them all. */
|
|
145
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;
|
|
146
183
|
/**
|
|
147
184
|
* Frames naming a session this client has not registered YET, held only
|
|
148
185
|
* while a `session/start`/`session/resume` is in flight (#49790): the host
|
|
@@ -172,6 +209,7 @@ export class MuseClient {
|
|
|
172
209
|
// no current consumer spans two clients over one host lineage, so a
|
|
173
210
|
// sharing knob would be declared-ahead surface (Constitution XI).
|
|
174
211
|
this.#discarded = new DiscardedSessions();
|
|
212
|
+
this.#extensions = options.extensions ?? [];
|
|
175
213
|
this.#child = options.host?.child;
|
|
176
214
|
this.#initializeResult = options.host?.initializeResult;
|
|
177
215
|
// THE ONE INBOUND PUMP (FR-018/FR-019). `Session.apply` is the only event
|
|
@@ -179,9 +217,14 @@ export class MuseClient {
|
|
|
179
217
|
// consumer has no way to hear a single view frame: every turn wait hangs
|
|
180
218
|
// (SS3.1.4) and `onApproval` can never fire. `Connection.onNotification`
|
|
181
219
|
// holds ONE handler — this client claims it, which is part of what
|
|
182
|
-
// "MuseClient owns the connection" means; a
|
|
183
|
-
//
|
|
184
|
-
|
|
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
|
+
});
|
|
185
228
|
// A question or approval still open at resume is re-sent as a
|
|
186
229
|
// `userInput/request` or `approval/request` server request (tdd SS5.6,
|
|
187
230
|
// SS5.10). Each is routed in arrival order and answered with the SS5.3.3
|
|
@@ -209,23 +252,31 @@ export class MuseClient {
|
|
|
209
252
|
// Registered at construction, not at the first session: an EOF can land
|
|
210
253
|
// before any session exists, and the flag has to be read at that moment.
|
|
211
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());
|
|
212
258
|
}
|
|
213
259
|
/**
|
|
214
260
|
* Deliver one view notification to the session(s) it names.
|
|
215
261
|
*
|
|
216
|
-
* A frame naming NO session
|
|
217
|
-
*
|
|
218
|
-
*
|
|
219
|
-
*
|
|
220
|
-
*
|
|
221
|
-
*
|
|
222
|
-
*
|
|
223
|
-
*
|
|
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.
|
|
224
271
|
*/
|
|
225
272
|
#route(notification) {
|
|
226
273
|
const named = notification.params?.sessionId;
|
|
227
|
-
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);
|
|
228
278
|
return;
|
|
279
|
+
}
|
|
229
280
|
let delivered = false;
|
|
230
281
|
for (const session of this.#sessions) {
|
|
231
282
|
if (session.sessionId === named) {
|
|
@@ -241,6 +292,16 @@ export class MuseClient {
|
|
|
241
292
|
else
|
|
242
293
|
held.push(notification);
|
|
243
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
|
+
}
|
|
244
305
|
/**
|
|
245
306
|
* Spawn an owned host, run the SS1.4 handshake, and hand back a client whose
|
|
246
307
|
* durability profile came from that handshake (FR-018).
|
|
@@ -275,6 +336,7 @@ export class MuseClient {
|
|
|
275
336
|
...(options.shutdownTimeoutMs === undefined
|
|
276
337
|
? {}
|
|
277
338
|
: { shutdownTimeoutMs: options.shutdownTimeoutMs }),
|
|
339
|
+
...(options.spawnFn === undefined ? {} : { spawnFn: options.spawnFn }),
|
|
278
340
|
});
|
|
279
341
|
let spawned;
|
|
280
342
|
try {
|
|
@@ -306,6 +368,7 @@ export class MuseClient {
|
|
|
306
368
|
}
|
|
307
369
|
return new MuseClient(spawned.connection, {
|
|
308
370
|
durability: readSessionDurability(spawned.initializeResult),
|
|
371
|
+
...(options.extensions === undefined ? {} : { extensions: options.extensions }),
|
|
309
372
|
host: spawned,
|
|
310
373
|
});
|
|
311
374
|
}
|
|
@@ -332,6 +395,72 @@ export class MuseClient {
|
|
|
332
395
|
}
|
|
333
396
|
return this.#child.exit;
|
|
334
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
|
+
}
|
|
335
464
|
/** The durability profile every session this client opens inherits. */
|
|
336
465
|
get durability() {
|
|
337
466
|
return this.#durability;
|
|
@@ -445,17 +574,14 @@ export class MuseClient {
|
|
|
445
574
|
* (see `Session.listTasks`).
|
|
446
575
|
*/
|
|
447
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).
|
|
448
579
|
const params = {};
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
params["limit"] = options.limit;
|
|
455
|
-
if (options.updatedAfter != null)
|
|
456
|
-
params["updatedAfter"] = options.updatedAfter;
|
|
457
|
-
if (options.workspaceRoot != null)
|
|
458
|
-
params["workspaceRoot"] = options.workspaceRoot;
|
|
580
|
+
for (const member of LIST_FORWARDED) {
|
|
581
|
+
const value = options[member];
|
|
582
|
+
if (value != null)
|
|
583
|
+
params[member] = value;
|
|
584
|
+
}
|
|
459
585
|
const ack = await this.#connection.request("session/list", params);
|
|
460
586
|
return ack;
|
|
461
587
|
}
|
|
@@ -481,20 +607,27 @@ export class MuseClient {
|
|
|
481
607
|
}
|
|
482
608
|
/**
|
|
483
609
|
* Send a wire method directly (FR-79107-2), typically one the facade does
|
|
484
|
-
* not wrap, through the
|
|
610
|
+
* not wrap, experimental ones included, through the
|
|
485
611
|
* same `Connection.command()` the verbs use: the connection mints the
|
|
486
612
|
* `commandId`, retries a nothing-admitted refusal under the same id, and
|
|
487
|
-
* checks the ack's echo. `options` are that seam's own.
|
|
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.
|
|
488
617
|
*
|
|
489
618
|
* Refused before anything is written, with `MuseFacadeOwnedMethodError`:
|
|
490
|
-
* the methods whose state the facade owns (`FACADE_OWNED_METHODS`)
|
|
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
|
|
491
624
|
* the command causes still reach your sessions through the client's one
|
|
492
625
|
* inbound pump; this sends and returns the ack, nothing more. Params and
|
|
493
626
|
* ack stay untyped objects: the generated types carry no method-to-params
|
|
494
627
|
* map, and restating one here would drift from the schema.
|
|
495
628
|
*
|
|
496
629
|
* Each call keeps one fixed-size fingerprint for the connection's lifetime
|
|
497
|
-
* (FR-45137-1), so prefer
|
|
630
|
+
* (FR-45137-1), so prefer `request` for a query you poll.
|
|
498
631
|
*/
|
|
499
632
|
async command(method, params, options) {
|
|
500
633
|
// The type binds TypeScript callers; this binds plain-JS ones.
|
|
@@ -502,6 +635,18 @@ export class MuseClient {
|
|
|
502
635
|
throw new MuseFacadeOwnedMethodError(method);
|
|
503
636
|
return this.#connection.command(method, params, options);
|
|
504
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
|
+
}
|
|
505
650
|
/**
|
|
506
651
|
* Shut the host down in an orderly way (SS2.1.2); the shutdown this causes
|
|
507
652
|
* is not reported to your sessions as a host death.
|
|
@@ -553,6 +698,7 @@ export class MuseClient {
|
|
|
553
698
|
connection: this.#connection,
|
|
554
699
|
discarded: this.#discarded,
|
|
555
700
|
durability: this.#durability,
|
|
701
|
+
extensions: this.#extensions,
|
|
556
702
|
opening,
|
|
557
703
|
sessionId,
|
|
558
704
|
});
|
|
@@ -604,6 +750,20 @@ export class MuseClient {
|
|
|
604
750
|
#survivesHostDeath() {
|
|
605
751
|
return this.#durability.kind === "durable";
|
|
606
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
|
+
}
|
|
607
767
|
/**
|
|
608
768
|
* The transport reached EOF. If this client did not cause it, that is
|
|
609
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
|
|
@@ -19,6 +19,7 @@
|
|
|
19
19
|
* composition every earlier arm builds — stays valid and refuses the submit
|
|
20
20
|
* verbs loudly rather than dropping a caller's input on the floor.
|
|
21
21
|
*/
|
|
22
|
+
import type { FoldExtension } from "../fold/extension.js";
|
|
22
23
|
import { SessionFold } from "../fold/session-fold.js";
|
|
23
24
|
import type { FoldOutcome, ViewEvent } from "../fold/session-fold.js";
|
|
24
25
|
import { PendingCommandSet } from "../pending/pending-command-set.js";
|
|
@@ -26,10 +27,10 @@ import type { PendingRetirement, ReplayAnswer, SnapshotJoinFacts } from "../pend
|
|
|
26
27
|
import type { Connection } from "../connection/connection.js";
|
|
27
28
|
import type { ApprovalFailureHandler, ApprovalHandler } from "./approval.js";
|
|
28
29
|
import type { SendUserTurnOptions } from "./turn-submit.js";
|
|
29
|
-
import type { GapFillFailureHandler } from "./gap-fill.js";
|
|
30
|
+
import type { GapFillFailureHandler, WireFrame } from "./gap-fill.js";
|
|
30
31
|
import type { DiscardedSessions } from "./discarded.js";
|
|
31
32
|
import type { HostDeathDischarge, HostDeathNotification, SessionDurabilityProfile } from "./host-death.js";
|
|
32
|
-
import type { Turn } from "./turn-handle.js";
|
|
33
|
+
import type { FoldedItem, Turn } from "./turn-handle.js";
|
|
33
34
|
import type { RunOptions, RunResult } from "./run.js";
|
|
34
35
|
import type { ApprovalMode, CommandAcceptedResult, FeedbackSubmitParams, FeedbackSubmitResult, HookListResult, ModelSelection, PluginInstallResult, PluginInstallTarget, PluginListResult, ReasoningEffort, RecapRequestResult, SessionCompactParams, SessionCompactResult, SessionForkParams, SessionForkResult, SessionLeaveParams, SessionLeaveResult, SessionRenameResult, SessionResumeResult, SessionSetApprovalModeResult, SessionSetModelResult, SessionSetReasoningEffortResult, SessionSideChatResult, SessionStartResult, SkillListResult, SkillSetActivationParams, SkillSetActivationResult, SubagentOwnerReasonParams, TaskListResult, TurnInputPart, UserInputAnswer, UserInputAnswerResult, WorkflowControlResult, WorkflowResumeResult } from "../msp.js";
|
|
35
36
|
/**
|
|
@@ -80,6 +81,12 @@ export interface SessionOptions {
|
|
|
80
81
|
readonly discarded?: DiscardedSessions;
|
|
81
82
|
/** Set by `MuseClient`; see {@link SessionOpening}. */
|
|
82
83
|
readonly opening?: SessionOpening;
|
|
84
|
+
/**
|
|
85
|
+
* Fold extensions for this session (FR-97527-3), consulted inside the
|
|
86
|
+
* one apply path. `MuseClient` forwards its own list here for every
|
|
87
|
+
* session it opens, so one registration covers both planes.
|
|
88
|
+
*/
|
|
89
|
+
readonly extensions?: readonly FoldExtension[];
|
|
83
90
|
}
|
|
84
91
|
/**
|
|
85
92
|
* The fold as a consumer may READ it.
|
|
@@ -196,6 +203,36 @@ export interface SessionApplyOutcome<I> {
|
|
|
196
203
|
*/
|
|
197
204
|
readonly io: Promise<readonly PendingRetirement<I>[]>;
|
|
198
205
|
}
|
|
206
|
+
/**
|
|
207
|
+
* One inbound frame as a session applies it: a view notification, a frame an
|
|
208
|
+
* SS4.8 fill spliced in from a page, or the frame a re-sent server request is
|
|
209
|
+
* folded as (`approval/request` as itself, `userInput/request` as its
|
|
210
|
+
* `userInput/requested` twin).
|
|
211
|
+
*/
|
|
212
|
+
export type ViewFrame = WireFrame;
|
|
213
|
+
/**
|
|
214
|
+
* One event a session folded, as `Session.events()` yields it: the event and
|
|
215
|
+
* what folding it changed, self-contained because the loop body may run after
|
|
216
|
+
* later events folded (FR-97336-1). Optional members may be added; a consumer
|
|
217
|
+
* reads the ones it knows.
|
|
218
|
+
*/
|
|
219
|
+
export interface SessionEvent<I = unknown> {
|
|
220
|
+
/** The protocol event, as the session applied it. */
|
|
221
|
+
readonly frame: ViewFrame;
|
|
222
|
+
/**
|
|
223
|
+
* What it changed: the value `Session.apply` returned for a live event. An
|
|
224
|
+
* event a gap fill spliced in carries its fold result and no retirements or
|
|
225
|
+
* I/O of its own: those settle on the `view/gap` event's `io`.
|
|
226
|
+
*/
|
|
227
|
+
readonly outcome: SessionApplyOutcome<I>;
|
|
228
|
+
/** For an item event that changed the item: the item as it stood after this event. */
|
|
229
|
+
readonly item?: FoldedItem;
|
|
230
|
+
}
|
|
231
|
+
/** Options for `Session.events()`. */
|
|
232
|
+
export interface SessionEventsOptions {
|
|
233
|
+
/** Aborting it ends the stream, as `return()` does. */
|
|
234
|
+
readonly signal?: AbortSignal;
|
|
235
|
+
}
|
|
199
236
|
/**
|
|
200
237
|
* One conversation with the agent.
|
|
201
238
|
*
|
|
@@ -231,6 +268,21 @@ export declare class Session<I = unknown> {
|
|
|
231
268
|
readonly method: string;
|
|
232
269
|
readonly params?: unknown;
|
|
233
270
|
}): SessionApplyOutcome<I>;
|
|
271
|
+
/**
|
|
272
|
+
* Every event this session folds from now on, with what it changed
|
|
273
|
+
* (FR-97336-1). Live from the call, never replayed: read `fold`, then call
|
|
274
|
+
* this in the same tick, and nothing is missed, including the events
|
|
275
|
+
* folded while `startSession`/`resumeSession` was in flight. Each folded
|
|
276
|
+
* event is yielded once, in arrival order; the events a gap fill splices in
|
|
277
|
+
* are yielded when applied, in order. Buffered like `turn.items()`, so a slow
|
|
278
|
+
* reader never holds folding up.
|
|
279
|
+
*
|
|
280
|
+
* `break`, `return()` or `options.signal` ends it. It finishes the way a
|
|
281
|
+
* turn's `items()` does when the host dies: it ends after an ephemeral
|
|
282
|
+
* host's death, and rejects with `MuseHostDiedError` after a durable one's,
|
|
283
|
+
* once the events it already buffered are read.
|
|
284
|
+
*/
|
|
285
|
+
events(options?: SessionEventsOptions): AsyncIterableIterator<SessionEvent<I>>;
|
|
234
286
|
/** Observe SS4.8 fills that did not complete. See `MuseGapFillError`. */
|
|
235
287
|
onGapError(handler: GapFillFailureHandler): void;
|
|
236
288
|
/**
|
|
@@ -307,7 +359,9 @@ export declare class Session<I = unknown> {
|
|
|
307
359
|
* Submit feedback about this session (`feedback/submit`). The host
|
|
308
360
|
* serves it only when the spawn requested the `feedback` capability
|
|
309
361
|
* (`requestedCapabilities: ["feedback"]`) and install policy allows
|
|
310
|
-
* it; without that grant the host refuses the
|
|
362
|
+
* it; without that grant the host refuses the call. Its wire params
|
|
363
|
+
* define no `commandId` (each call is one submit; the wire contract
|
|
364
|
+
* attaches no dedup), so it rides `request()` and mints none.
|
|
311
365
|
*/
|
|
312
366
|
submitFeedback(input: Omit<FeedbackSubmitParams, "sessionId">): Promise<FeedbackSubmitResult>;
|
|
313
367
|
/**
|