@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 CHANGED
@@ -14,6 +14,11 @@ agent over the Muse Session Protocol (MSP).
14
14
  - A client-side fold keeps a live, typed view of the session — items, session
15
15
  state, pending commands — with gap recovery after dropped deliveries and
16
16
  safe same-command retry that can never double-submit.
17
+ - Observe the connection itself: `client.onNotification` hears every
18
+ notification the host sends (including ones that name no session, such as
19
+ `usage/changed`), `onProtocolError` hears messages the SDK rejects as
20
+ malformed, and `client.closed` resolves when the connection closes. Each
21
+ `on*` call returns its own unsubscribe function.
17
22
 
18
23
  **Zero runtime dependencies**: pure TypeScript over the Node standard
19
24
  library. The MSP wire declarations are bundled into the package, so nothing
@@ -117,6 +122,28 @@ the resume reply can happen before `resumeSession` returns, so
117
122
  that throws, picks a choice that was not offered, or adds feedback to a choice
118
123
  that takes none (which is then answered with the reject choice).
119
124
 
125
+ To render incrementally, read `session.events()`: every event the session
126
+ folds from then on, with what it changed. Read the current state first, then
127
+ subscribe in the same tick, and nothing is missed, including the events that
128
+ arrived before `startSession` or `resumeSession` returned:
129
+
130
+ ```ts
131
+ const session = await client.startSession();
132
+ renderAll(session.fold); // the state so far
133
+ for await (const { frame, outcome, item } of session.events()) {
134
+ // `item` is the item as of this event; `session.fold` may already be ahead.
135
+ render(frame.method, outcome.fold, item);
136
+ }
137
+ ```
138
+
139
+ Each event arrives once, in order, including events the SDK fetches to fill a
140
+ gap in delivery. `break` (or an `AbortSignal` passed as
141
+ `session.events({ signal })`) stops listening. The stream ends when an
142
+ ephemeral host dies and rejects with `MuseHostDiedError` when a durable one
143
+ does, as `turn.items()` does. Reading it changes nothing else:
144
+ `turn.unqueue()` still returns the queued input it takes back, and that input
145
+ is not repeated on an event.
146
+
120
147
  To answer a question the agent asks, read it from
121
148
  `session.fold.pendingUserInputs()` and answer it with `session.answerUserInput`,
122
149
  one answer per question: `selectedLabel` for a single-select question,
@@ -50,6 +50,14 @@ export declare const submissionTail: unique symbol;
50
50
  * value every other refusal carries (#50588 review).
51
51
  */
52
52
  export declare const requestWithFrame: unique symbol;
53
+ /**
54
+ * Module-private friend seam, like {@link submissionTail}: the owner of the
55
+ * peer process says, once when the connection finishes, why the peer is gone.
56
+ * A promise it returns settles (never rejects) with the `cause` given to
57
+ * every call the connection then fails; `undefined` keeps the bare error and
58
+ * its timing.
59
+ */
60
+ export declare const peerEndCause: unique symbol;
53
61
  /** What {@link requestWithFrame} resolves with: the result and its wire line. */
54
62
  export interface FramedResult {
55
63
  readonly result: Record<string, unknown>;
@@ -92,7 +100,13 @@ export declare class MspError extends Error {
92
100
  readonly retryable: boolean | undefined;
93
101
  constructor(error: ErrorObject);
94
102
  }
95
- /** A local framing/correlation violation, never a server-authored MSP error. */
103
+ /**
104
+ * A local framing/correlation violation, never a server-authored MSP error.
105
+ * When a call fails because a host `MuseClient.spawn` started died, the error
106
+ * it rejects with (usually this class; the transport's own error when a write
107
+ * failed) has a `MuseHostDiedError` `cause` saying how the host ended, so
108
+ * check `cause` alone.
109
+ */
96
110
  export declare class ProtocolError extends Error {
97
111
  /**
98
112
  * The inbound frame (wire line) the violation was detected on, when there
@@ -112,9 +126,10 @@ export declare function createUuidV7Mint(): () => string;
112
126
  * responses, enforces the frame-size limit, and hands inbound notifications
113
127
  * and server requests to the handlers you register. It is transport-agnostic:
114
128
  * pair it with any `DuplexTransport`. Most applications never build one
115
- * directly — `MuseClient.spawn` or `spawnMspConnection` does it for you;
116
- * reach for a bare `Connection` when you need the raw notification feed or
117
- * your own transport.
129
+ * directly — `MuseClient.spawn` or `spawnMspConnection` does it for you, and
130
+ * `MuseClient.onNotification` hears the notification feed. Reach for a bare
131
+ * `Connection` only for your own transport or to handle frames before session
132
+ * routing.
118
133
  */
119
134
  export declare class Connection {
120
135
  #private;
@@ -123,6 +138,8 @@ export declare class Connection {
123
138
  /** See {@link submissionTail}. */
124
139
  [submissionTail](): Promise<void>;
125
140
  request(method: string, params?: Record<string, unknown>): Promise<Record<string, unknown>>;
141
+ /** See {@link peerEndCause}. */
142
+ [peerEndCause](read: () => Promise<unknown> | undefined): void;
126
143
  /** See {@link requestWithFrame}. */
127
144
  [requestWithFrame](method: string, params?: Record<string, unknown>): Promise<FramedResult>;
128
145
  /**
@@ -25,6 +25,14 @@ export const submissionTail = Symbol("Connection.submissionTail");
25
25
  * value every other refusal carries (#50588 review).
26
26
  */
27
27
  export const requestWithFrame = Symbol("Connection.requestWithFrame");
28
+ /**
29
+ * Module-private friend seam, like {@link submissionTail}: the owner of the
30
+ * peer process says, once when the connection finishes, why the peer is gone.
31
+ * A promise it returns settles (never rejects) with the `cause` given to
32
+ * every call the connection then fails; `undefined` keeps the bare error and
33
+ * its timing.
34
+ */
35
+ export const peerEndCause = Symbol("Connection.peerEndCause");
28
36
  /** The one typed error family consumers branch on (INV-012). */
29
37
  export class MspError extends Error {
30
38
  code;
@@ -40,7 +48,13 @@ export class MspError extends Error {
40
48
  this.retryable = error.data?.retryable;
41
49
  }
42
50
  }
43
- /** A local framing/correlation violation, never a server-authored MSP error. */
51
+ /**
52
+ * A local framing/correlation violation, never a server-authored MSP error.
53
+ * When a call fails because a host `MuseClient.spawn` started died, the error
54
+ * it rejects with (usually this class; the transport's own error when a write
55
+ * failed) has a `MuseHostDiedError` `cause` saying how the host ended, so
56
+ * check `cause` alone.
57
+ */
44
58
  export class ProtocolError extends Error {
45
59
  /**
46
60
  * The inbound frame (wire line) the violation was detected on, when there
@@ -147,9 +161,10 @@ function isObject(value) {
147
161
  * responses, enforces the frame-size limit, and hands inbound notifications
148
162
  * and server requests to the handlers you register. It is transport-agnostic:
149
163
  * pair it with any `DuplexTransport`. Most applications never build one
150
- * directly — `MuseClient.spawn` or `spawnMspConnection` does it for you;
151
- * reach for a bare `Connection` when you need the raw notification feed or
152
- * your own transport.
164
+ * directly — `MuseClient.spawn` or `spawnMspConnection` does it for you, and
165
+ * `MuseClient.onNotification` hears the notification feed. Reach for a bare
166
+ * `Connection` only for your own transport or to handle frames before session
167
+ * routing.
153
168
  */
154
169
  export class Connection {
155
170
  #transport;
@@ -162,6 +177,8 @@ export class Connection {
162
177
  #serverRequestHandler;
163
178
  #notificationHandler;
164
179
  #protocolErrorHandler;
180
+ #peerEndCause;
181
+ #endCause;
165
182
  #writeTail = Promise.resolve();
166
183
  // Settles when every accepted frame has been HANDED to the transport, as
167
184
  // opposed to #writeTail, which settles when the peer has taken it.
@@ -202,13 +219,21 @@ export class Connection {
202
219
  request(method, params) {
203
220
  return this.#request(method, params).then((framed) => framed.result);
204
221
  }
222
+ /** See {@link peerEndCause}. */
223
+ [peerEndCause](read) {
224
+ this.#peerEndCause = read;
225
+ // The host can die between the handshake and this registration.
226
+ if (this.#finished && this.#endCause === undefined)
227
+ this.#endCause = read();
228
+ }
205
229
  /** See {@link requestWithFrame}. */
206
230
  [requestWithFrame](method, params) {
207
231
  return this.#request(method, params);
208
232
  }
209
233
  #request(method, params) {
210
- if (this.#finished)
211
- return Promise.reject(new ProtocolError("connection is closed"));
234
+ if (this.#finished) {
235
+ return new Promise((_, reject) => this.#rejectWithEndCause(reject, new ProtocolError("connection is closed")));
236
+ }
212
237
  const id = this.#mintRequestId();
213
238
  if (typeof id !== "string" && (typeof id !== "number" || !Number.isInteger(id))) {
214
239
  return Promise.reject(new ProtocolError("request id must be a string or integer"));
@@ -229,7 +254,7 @@ export class Connection {
229
254
  });
230
255
  void this.#write(request).catch((error) => {
231
256
  this.#pending.delete(requestKey(id));
232
- reject(error);
257
+ this.#rejectWithEndCause(reject, error);
233
258
  });
234
259
  });
235
260
  }
@@ -302,7 +327,10 @@ export class Connection {
302
327
  return ack;
303
328
  }
304
329
  catch (error) {
330
+ // A present data.retryable overrides the code's table default, so an
331
+ // explicit false stops the retry; absent keeps it.
305
332
  const retryableNothingAdmitted = error instanceof MspError &&
333
+ error.retryable !== false &&
306
334
  ((error.code === -32001 && error.kind === "overloaded") ||
307
335
  (error.code === -32031 && error.kind === "backpressured"));
308
336
  if (!retryableNothingAdmitted || attempt === maxAttempts)
@@ -565,6 +593,19 @@ export class Connection {
565
593
  }).catch((writeError) => this.#finish(writeError)); // FM-009
566
594
  }
567
595
  }
596
+ /** Reject with `error`, first giving it the peer's end cause when the owner reported one. */
597
+ #rejectWithEndCause(reject, error) {
598
+ const endCause = this.#endCause;
599
+ if (endCause === undefined || !(error instanceof Error) || error.cause !== undefined) {
600
+ reject(error);
601
+ return;
602
+ }
603
+ void endCause.then((cause) => {
604
+ if (cause !== undefined)
605
+ error.cause = cause;
606
+ reject(error);
607
+ });
608
+ }
568
609
  #protocolError(error) {
569
610
  this.#protocolErrorHandler?.(error);
570
611
  }
@@ -573,8 +614,9 @@ export class Connection {
573
614
  return;
574
615
  this.#finished = true;
575
616
  const error = reason instanceof Error ? reason : new ProtocolError(String(reason));
617
+ this.#endCause = this.#peerEndCause?.();
576
618
  for (const pending of this.#pending.values())
577
- pending.reject(error);
619
+ this.#rejectWithEndCause(pending.reject, error);
578
620
  this.#pending.clear();
579
621
  this.#resolveClosed?.();
580
622
  this.#resolveClosed = undefined;
@@ -8,7 +8,7 @@ import type { FingerprintWarning } from "../fingerprint.js";
8
8
  /**
9
9
  * What `spawnMspConnection` needs to launch a host: the command to run, plus
10
10
  * optional arguments, working directory, environment, connection tuning, a
11
- * stderr tap, and the shutdown drain budget.
11
+ * stderr tap, the shutdown drain budget, and a replacement for the spawn call.
12
12
  */
13
13
  export interface SpawnMspConnectionOptions {
14
14
  readonly command: string;
@@ -20,6 +20,8 @@ export interface SpawnMspConnectionOptions {
20
20
  readonly onStderr?: (chunk: string) => void;
21
21
  /** See {@link MuseServeChildOptions.shutdownTimeoutMs}. */
22
22
  readonly shutdownTimeoutMs?: number;
23
+ /** See {@link MuseServeChildOptions.spawnFn}. */
24
+ readonly spawnFn?: MuseServeChildOptions["spawnFn"];
23
25
  }
24
26
  /**
25
27
  * How the host process ended: its exit code, or the signal that ended it.
@@ -75,12 +77,30 @@ export interface MuseServeChildOptions {
75
77
  */
76
78
  readonly shutdownTimeoutMs?: number;
77
79
  /**
78
- * Deterministic-test seam; production always uses `child_process.spawn`.
79
- * A stub here observes the exact options the call site passes, so a
80
- * `windowsHide` override at the call site fails the pin (FR-45141-1).
80
+ * Replaces `child_process.spawn`, e.g. with an in-memory fake host. It is
81
+ * called once as `spawnFn(museBin, args, options)` with the exact options
82
+ * production passes, so a `windowsHide` override at the call site fails the
83
+ * pin (FR-45141-1).
84
+ *
85
+ * The returned child must provide what the SDK reads from a real one:
86
+ * `stdout` and `stderr` as readable streams, one MSP frame per `stdout`
87
+ * line; `stdin` as a writable stream, which the SDK ends to start shutdown;
88
+ * a `close` event with `(code, signal)` once the host has exited, or an
89
+ * `error` event if it never started; and `kill(signal)`, called with
90
+ * SIGTERM then SIGKILL when the host outlives the drain window. Leave `pid`
91
+ * undefined on an in-memory fake: on POSIX a set `pid` is signalled as a
92
+ * process group (`-pid`), which would reach a real one.
81
93
  */
82
94
  readonly spawnFn?: typeof spawn;
83
95
  }
96
+ /**
97
+ * SIGTERM → SIGKILL grace. Not a knob: by the time it runs the host has
98
+ * already had its whole drain window, so this covers only a signal handler's
99
+ * final flush. Codex's stdio launcher uses the same two seconds. Also bounds
100
+ * how long a call failed by a host death waits for the exit (FR-97948-1).
101
+ * Exported from this module only, never the package barrel.
102
+ */
103
+ export declare const SIGTERM_GRACE_MS = 2000;
84
104
  declare const ownedTransport: unique symbol;
85
105
  declare const adoptFlushSource: unique symbol;
86
106
  /**
@@ -9,9 +9,11 @@ const DEFAULT_SHUTDOWN_TIMEOUT_MS = 30_000;
9
9
  /**
10
10
  * SIGTERM → SIGKILL grace. Not a knob: by the time it runs the host has
11
11
  * already had its whole drain window, so this covers only a signal handler's
12
- * final flush. Codex's stdio launcher uses the same two seconds.
12
+ * final flush. Codex's stdio launcher uses the same two seconds. Also bounds
13
+ * how long a call failed by a host death waits for the exit (FR-97948-1).
14
+ * Exported from this module only, never the package barrel.
13
15
  */
14
- const SIGTERM_GRACE_MS = 2_000;
16
+ export const SIGTERM_GRACE_MS = 2_000;
15
17
  /** Node's own `setTimeout` ceiling; past it a delay silently clamps to 1 ms. */
16
18
  const MAX_SHUTDOWN_TIMEOUT_MS = 2_147_483_647;
17
19
  const ownedTransport = Symbol("MuseServeChild.transport");
@@ -421,6 +423,7 @@ export class MspHandshake {
421
423
  ...(options.shutdownTimeoutMs === undefined
422
424
  ? {}
423
425
  : { shutdownTimeoutMs: options.shutdownTimeoutMs }),
426
+ ...(options.spawnFn === undefined ? {} : { spawnFn: options.spawnFn }),
424
427
  });
425
428
  this.#transport = this.child[ownedTransport]();
426
429
  this.#connection = new Connection(this.#transport, options.connection);
@@ -70,7 +70,7 @@ export declare class PermissionProfileNotApplied extends Error {
70
70
  constructor(requested: string, served: string | null, sessionId: string);
71
71
  }
72
72
  /** The developer-docs compatibility page the host-discovery error cites. */
73
- export declare const COMPATIBILITY_PAGE_URL = "https://meta-models.github.io/muse-code-sdk/compatibility/";
73
+ export declare const COMPATIBILITY_PAGE_URL = "https://meta-models.github.io/muse-code-sdk/latest/compatibility/";
74
74
  /**
75
75
  * No host binary was given and no executable `muse` is on `PATH` (FR-79107-1).
76
76
  * Raised by `MuseClient.spawn` before any process is started. The package does
@@ -80,13 +80,14 @@ export declare class MuseHostDiscoveryError extends Error {
80
80
  /** The spawn option that names an explicit host path. */
81
81
  readonly parameter = "museBin";
82
82
  /** The page listing the host versions this SDK supports. */
83
- readonly compatibilityUrl = "https://meta-models.github.io/muse-code-sdk/compatibility/";
83
+ readonly compatibilityUrl = "https://meta-models.github.io/muse-code-sdk/latest/compatibility/";
84
84
  constructor();
85
85
  }
86
86
  /**
87
- * `MuseClient.command` was asked to send a method whose state the facade owns
88
- * (FR-79107-2). Sending it raw would bypass that state, so it is refused
89
- * before anything is written; use the facade verb instead.
87
+ * `MuseClient.command` or `MuseClient.request` was asked to send a method
88
+ * whose state the facade owns (FR-79107-2). Sending it raw would bypass that
89
+ * state, so it is refused before anything is written; use the facade verb
90
+ * instead.
90
91
  */
91
92
  export declare class MuseFacadeOwnedMethodError extends Error {
92
93
  /** The refused wire method. */
@@ -75,7 +75,7 @@ export class PermissionProfileNotApplied extends Error {
75
75
  }
76
76
  }
77
77
  /** The developer-docs compatibility page the host-discovery error cites. */
78
- export const COMPATIBILITY_PAGE_URL = "https://meta-models.github.io/muse-code-sdk/compatibility/";
78
+ export const COMPATIBILITY_PAGE_URL = "https://meta-models.github.io/muse-code-sdk/latest/compatibility/";
79
79
  /**
80
80
  * No host binary was given and no executable `muse` is on `PATH` (FR-79107-1).
81
81
  * Raised by `MuseClient.spawn` before any process is started. The package does
@@ -94,16 +94,17 @@ export class MuseHostDiscoveryError extends Error {
94
94
  }
95
95
  }
96
96
  /**
97
- * `MuseClient.command` was asked to send a method whose state the facade owns
98
- * (FR-79107-2). Sending it raw would bypass that state, so it is refused
99
- * before anything is written; use the facade verb instead.
97
+ * `MuseClient.command` or `MuseClient.request` was asked to send a method
98
+ * whose state the facade owns (FR-79107-2). Sending it raw would bypass that
99
+ * state, so it is refused before anything is written; use the facade verb
100
+ * instead.
100
101
  */
101
102
  export class MuseFacadeOwnedMethodError extends Error {
102
103
  /** The refused wire method. */
103
104
  method;
104
105
  constructor(method) {
105
- super(`${method} is sent by the facade itself and cannot go through MuseClient.command; ` +
106
- "use the facade verb that owns it");
106
+ super(`${method} is sent by the facade itself and cannot go through ` +
107
+ "MuseClient.command or MuseClient.request; use the facade verb that owns it");
107
108
  this.name = "MuseFacadeOwnedMethodError";
108
109
  this.method = method;
109
110
  }
@@ -35,12 +35,21 @@
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 type { CommandOptions, Connection } from "../connection/connection.js";
39
- import type { ExitClassification, SpawnedMspConnection } from "../connection/spawn.js";
38
+ import type { CommandOptions, Connection, ProtocolErrorHandler } from "../connection/connection.js";
39
+ import type { DeepReadonly } from "../fold/session-fold.js";
40
+ import type { ExitClassification, MuseServeChildOptions, SpawnedMspConnection } from "../connection/spawn.js";
41
+ import type { FoldExtension } from "../fold/extension.js";
40
42
  import type { SessionDurabilityProfile } from "./host-death.js";
41
43
  import type { ApprovalFailureHandler, ApprovalHandler } from "./approval.js";
42
44
  import { Session } from "./session.js";
43
- import type { InitializeParams, InitializeResult, ModelListParams, ModelListResult, MspMethod, SessionListParams, SessionListResult, SessionResumeParams, SessionStartParams, UsageReadResult } from "../msp.js";
45
+ import type { InitializeParams, InitializeResult, Notification, ModelListParams, ModelListResult, MspMethod, SessionListParams, SessionListResult, SessionResumeParams, SessionStartParams, UsageReadResult } from "../msp.js";
46
+ /**
47
+ * Hears one server notification. Read-only: the frame is the one the session
48
+ * folds, possibly after the listener runs.
49
+ */
50
+ export type NotificationObserver = (notification: DeepReadonly<Notification>) => void;
51
+ /** Hears what an `onNotification` listener threw or rejected with, with the notification it was handed. */
52
+ export type NotificationFailureHandler = (error: unknown, notification: DeepReadonly<Notification>) => void;
44
53
  /**
45
54
  * The wire methods whose state the facade owns, refused by `command`
46
55
  * (FR-79107-2). `initialize` is the handshake `spawn` runs; `session/start` and
@@ -54,15 +63,23 @@ import type { InitializeParams, InitializeResult, ModelListParams, ModelListResu
54
63
  */
55
64
  declare const FACADE_OWNED_METHODS: readonly ["initialize", "session/start", "session/resume", "turn/start", "turn/steer", "turn/unqueue", "approval/decide", "userInput/answer", "view/page", "view/subscribe", "view/unsubscribe"];
56
65
  type FacadeOwnedMethod = (typeof FACADE_OWNED_METHODS)[number];
66
+ /**
67
+ * The names `command`/`request` offer: the stable methods the facade does not
68
+ * own, plus any other string, because the generated types this package ships
69
+ * name stable methods only and experimental ones must still go through.
70
+ */
71
+ type RawMethodName = Exclude<MspMethod, FacadeOwnedMethod> | (string & {});
72
+ /** `M`, or `never` when `M` is a facade-owned literal: keeps the compile-time refusal the `string` fallback would lose. */
73
+ type RawMethod<M extends string> = M & (M extends FacadeOwnedMethod ? never : unknown);
57
74
  /**
58
75
  * Caller-facing options for `session/start` (tdd SS2.5.1).
59
76
  *
60
- * `commandId` is excluded because the connection mints it; `previousSessionId`
61
- * and `switchPolicy` because the facade starts root sessions, and `spawnedBy`
62
- * because the facade does not expose a spawner yet. `config.mcpServers` needs
63
- * the host's `sessionMcp` grant (FR-79107-3).
77
+ * `commandId` is excluded because the connection mints it; `previousSessionId`,
78
+ * `clear` and `switchPolicy` because the facade starts root sessions, and
79
+ * `spawnedBy` because the facade does not expose a spawner yet.
80
+ * `config.mcpServers` needs the host's `sessionMcp` grant (FR-79107-3).
64
81
  */
65
- export type StartSessionOptions = Readonly<Omit<SessionStartParams, "commandId" | "previousSessionId" | "switchPolicy" | "spawnedBy"> & {
82
+ export type StartSessionOptions = Readonly<Omit<SessionStartParams, "commandId" | "previousSessionId" | "clear" | "switchPolicy" | "spawnedBy"> & {
66
83
  /**
67
84
  * Require the `permissionProfile` selection (TEST-42624-10): when set,
68
85
  * the client proves the committed selection equals the requested id —
@@ -114,6 +131,12 @@ export interface MuseClientOptions {
114
131
  * is why `close()` falls back to closing just the connection.
115
132
  */
116
133
  readonly host?: SpawnedMspConnection;
134
+ /**
135
+ * Fold extensions (FR-97527-3), consulted for session-less frames here and
136
+ * forwarded to every session this client opens — one registration covers
137
+ * both connection-level state and the per-session fold.
138
+ */
139
+ readonly extensions?: readonly FoldExtension[];
117
140
  }
118
141
  /** What `MuseClient.spawn` needs: FR-018's `{ museBin?, args?, env? }`, plus the handshake. */
119
142
  export interface MuseClientSpawnOptions {
@@ -139,6 +162,18 @@ export interface MuseClientSpawnOptions {
139
162
  readonly onStderr?: (chunk: string) => void;
140
163
  /** See `MuseServeChildOptions.shutdownTimeoutMs`. */
141
164
  readonly shutdownTimeoutMs?: number;
165
+ /**
166
+ * See `MuseServeChildOptions.spawnFn`: lets an embedder run the handshake
167
+ * and its sessions against an in-memory fake host. Host discovery still
168
+ * runs first, so pass `museBin` (any string; it becomes `spawnFn`'s
169
+ * command) when no `muse` is on `PATH`.
170
+ */
171
+ readonly spawnFn?: MuseServeChildOptions["spawnFn"];
172
+ /**
173
+ * Fold extensions (FR-97527-3): connection-level state plus every
174
+ * session this client opens. See `MuseClientOptions.extensions`.
175
+ */
176
+ readonly extensions?: readonly FoldExtension[];
142
177
  }
143
178
  /**
144
179
  * Your entry point to the SDK.
@@ -184,6 +219,44 @@ export declare class MuseClient {
184
219
  get initializeResult(): InitializeResult;
185
220
  /** The host's SS2.11 exit row, when this client was built by `spawn`. */
186
221
  get exit(): Promise<ExitClassification>;
222
+ /**
223
+ * Settles when the connection closes for any reason: `close()`, the host
224
+ * hanging up, or a transport failure.
225
+ */
226
+ get closed(): Promise<void>;
227
+ /**
228
+ * Hear every server notification in wire order, including those naming no
229
+ * session (`usage/changed`, `account/loginCompleted`) or a session this
230
+ * client did not open. A frame naming a session this client has opened
231
+ * reaches the listener after that session has applied it: folded, or, while
232
+ * the session fills a gap, buffered and folded when the fill completes. One
233
+ * that arrives while its session's start/resume is still in flight reaches
234
+ * the listener first, and the session folds it before the verb returns.
235
+ * Returns the unsubscribe function.
236
+ *
237
+ * The frame is read-only: it is the one the session folds, which for a held
238
+ * or buffered frame happens after the listener runs. Like a `Connection`
239
+ * handler, the listener runs in the read loop, so it must not block. A throw, or an async listener's rejection, goes to every
240
+ * `onNotificationError` handler; the other listeners still hear the frame
241
+ * and the connection stays open.
242
+ */
243
+ onNotification(listener: NotificationObserver): () => void;
244
+ /**
245
+ * Hear what an `onNotification` listener threw or rejected with. With no
246
+ * handler the failure is dropped; either way the pump keeps running.
247
+ * Returns a function that removes this one subscription.
248
+ */
249
+ onNotificationError(handler: NotificationFailureHandler): () => void;
250
+ /**
251
+ * Hear each framing or correlation violation the connection detects
252
+ * (`Connection.onProtocolError`). The handler's own throw or rejection is
253
+ * swallowed rather than ending the connection; it is already the observer
254
+ * of failures, so there is no one left to tell. The first call takes over
255
+ * `Connection.onProtocolError`, replacing a handler set there directly (and
256
+ * a later direct `connection.onProtocolError(...)` silences these
257
+ * subscribers). Returns a function that removes this one subscription.
258
+ */
259
+ onProtocolError(handler: ProtocolErrorHandler): () => void;
187
260
  /** The durability profile every session this client opens inherits. */
188
261
  get durability(): SessionDurabilityProfile;
189
262
  /** Open a new root session (tdd SS2.5.1). */
@@ -217,22 +290,37 @@ export declare class MuseClient {
217
290
  readUsage(): Promise<UsageReadResult>;
218
291
  /**
219
292
  * Send a wire method directly (FR-79107-2), typically one the facade does
220
- * not wrap, through the
293
+ * not wrap, experimental ones included, through the
221
294
  * same `Connection.command()` the verbs use: the connection mints the
222
295
  * `commandId`, retries a nothing-admitted refusal under the same id, and
223
- * checks the ack's echo. `options` are that seam's own.
296
+ * checks the ack's echo. `options` are that seam's own. An experimental
297
+ * method needs a client spawned with `capabilities: { experimentalApi: true }`
298
+ * (otherwise the host refuses it with an `MspError` of kind
299
+ * `experimentalRequired`, code -32601) and may change without notice.
224
300
  *
225
301
  * Refused before anything is written, with `MuseFacadeOwnedMethodError`:
226
- * the methods whose state the facade owns (`FACADE_OWNED_METHODS`). Frames
302
+ * the methods whose state the facade owns (`FACADE_OWNED_METHODS`); the
303
+ * experimental host stop is not among them (this package names no
304
+ * experimental-only method), so sent raw it is the caller's own, and the
305
+ * exit it causes reaches your sessions as a host death; `close()` is the
306
+ * orderly stop. Frames
227
307
  * the command causes still reach your sessions through the client's one
228
308
  * inbound pump; this sends and returns the ack, nothing more. Params and
229
309
  * ack stay untyped objects: the generated types carry no method-to-params
230
310
  * map, and restating one here would drift from the schema.
231
311
  *
232
312
  * Each call keeps one fixed-size fingerprint for the connection's lifetime
233
- * (FR-45137-1), so prefer a facade verb for a query you poll.
313
+ * (FR-45137-1), so prefer `request` for a query you poll.
314
+ */
315
+ command<M extends RawMethodName>(method: RawMethod<M>, params: Record<string, unknown>, options?: CommandOptions): Promise<Record<string, unknown>>;
316
+ /**
317
+ * Send a wire request directly (FR-79107-2), typically a query the facade
318
+ * does not wrap, experimental ones included, through `Connection.request()`:
319
+ * no `commandId`, no retry, and omitted `params` stay off the frame.
320
+ * Refuses the same facade-owned methods as `command`, the same way, and
321
+ * needs the same `experimentalApi` opt-in for an experimental method.
234
322
  */
235
- command(method: Exclude<MspMethod, FacadeOwnedMethod>, params: Record<string, unknown>, options?: CommandOptions): Promise<Record<string, unknown>>;
323
+ request<M extends RawMethodName>(method: RawMethod<M>, params?: Record<string, unknown>): Promise<Record<string, unknown>>;
236
324
  /**
237
325
  * Shut the host down in an orderly way (SS2.1.2); the shutdown this causes
238
326
  * is not reported to your sessions as a host death.