@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.
@@ -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 { initializeAnswered, spawnMspConnection } from "../connection/spawn.js";
39
- import { MuseSessionDiscardedError, PermissionProfileNotApplied } from "../errors.js";
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 { isAbnormalHostDeath, readSessionDurability } from "./host-death.js";
42
- import { MspError, ProtocolError } from "../connection/connection.js";
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
- * Every `StartParams` member `startSession` forwards. `config` is temporarily
47
- * excluded until the facade can pair forwarding with the required
48
- * `sessionMcp` grant check, `previousSessionId` is excluded because the
49
- * facade starts root sessions (the predecessor link belongs to a client that
50
- * switches sessions), and `spawnedBy` because the facade does not expose a
51
- * spawner yet.
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. `config` has the same
65
- * temporary capability-check boundary as the start facade above.
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 RESUME_FORWARDED = ["sessionId", "cursor", "excludeItems", "history", "modelId", "permissionProfile", "recoveryMode"];
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 consumer that needs the raw
135
- // feed builds around a bare `Connection` and `Session` instead.
136
- this.#connection.onNotification((notification) => this.#route(notification));
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 is dropped here rather than fed to every
169
- * session: `Session.apply` already tolerates unknown methods, but only the
170
- * frames that name a `sessionId` have an owner to route to. A frame naming
171
- * an UNKNOWN session is dropped for the same reason — routing it anywhere
172
- * would trip the foreign-frame throw on a session it does not belong to —
173
- * UNLESS an open is in flight, when it may be that open's own session named
174
- * by the server before the awaiting promise has run (#49790): then it is
175
- * held for `#openSession` to fold, or for `#open` to clear.
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: options.museBin,
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
- ...(options.capabilities === undefined ? {} : { capabilities: options.capabilities }),
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
- /** A durable host died abnormally: its terminals arrive on resume (FM-001). */
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
- /** A durable host died abnormally: its terminals arrive on resume (FM-001). */
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>;