@muse-code/sdk 1.4.15 → 1.4.23

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,12 +35,22 @@
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 { CommandParams, MethodName, MethodParams, ParamsArgument, UnlistedMethod, WireResult } from "../connection/surface.js";
40
+ import type { DeepReadonly } from "../fold/session-fold.js";
41
+ import type { ExitClassification, MuseServeChildOptions, SpawnedMspConnection } from "../connection/spawn.js";
42
+ import type { FoldExtension } from "../fold/extension.js";
40
43
  import type { SessionDurabilityProfile } from "./host-death.js";
41
44
  import type { ApprovalFailureHandler, ApprovalHandler } from "./approval.js";
42
45
  import { Session } from "./session.js";
43
- import type { InitializeParams, InitializeResult, ModelListParams, ModelListResult, MspMethod, SessionListParams, SessionListResult, SessionResumeParams, SessionStartParams, UsageReadResult } from "../msp.js";
46
+ import type { InitializeParams, InitializeResult, Notification, ModelListParams, ModelListResult, SessionListParams, SessionListResult, SessionResumeParams, SessionStartParams, UsageReadResult } from "../msp.js";
47
+ /**
48
+ * Hears one server notification. Read-only: the frame is the one the session
49
+ * folds, possibly after the listener runs.
50
+ */
51
+ export type NotificationObserver = (notification: DeepReadonly<Notification>) => void;
52
+ /** Hears what an `onNotification` listener threw or rejected with, with the notification it was handed. */
53
+ export type NotificationFailureHandler = (error: unknown, notification: DeepReadonly<Notification>) => void;
44
54
  /**
45
55
  * The wire methods whose state the facade owns, refused by `command`
46
56
  * (FR-79107-2). `initialize` is the handshake `spawn` runs; `session/start` and
@@ -54,15 +64,19 @@ import type { InitializeParams, InitializeResult, ModelListParams, ModelListResu
54
64
  */
55
65
  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
66
  type FacadeOwnedMethod = (typeof FACADE_OWNED_METHODS)[number];
67
+ /** The methods `command`/`request` type from the surface's map: every listed one the facade does not own. */
68
+ type RawMethodName = Exclude<MethodName, FacadeOwnedMethod>;
69
+ /** `M` itself when no member of it is facade-owned, else `never`. */
70
+ type NotFacadeOwned<M extends string> = M & ([Extract<M, FacadeOwnedMethod>] extends [never] ? unknown : never);
57
71
  /**
58
72
  * Caller-facing options for `session/start` (tdd SS2.5.1).
59
73
  *
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).
74
+ * `commandId` is excluded because the connection mints it; `previousSessionId`,
75
+ * `clear` and `switchPolicy` because the facade starts root sessions, and
76
+ * `spawnedBy` because the facade does not expose a spawner yet.
77
+ * `config.mcpServers` needs the host's `sessionMcp` grant (FR-79107-3).
64
78
  */
65
- export type StartSessionOptions = Readonly<Omit<SessionStartParams, "commandId" | "previousSessionId" | "switchPolicy" | "spawnedBy"> & {
79
+ export type StartSessionOptions = Readonly<Omit<SessionStartParams, "commandId" | "previousSessionId" | "clear" | "switchPolicy" | "spawnedBy"> & {
66
80
  /**
67
81
  * Require the `permissionProfile` selection (TEST-42624-10): when set,
68
82
  * the client proves the committed selection equals the requested id —
@@ -114,6 +128,12 @@ export interface MuseClientOptions {
114
128
  * is why `close()` falls back to closing just the connection.
115
129
  */
116
130
  readonly host?: SpawnedMspConnection;
131
+ /**
132
+ * Fold extensions (FR-97527-3), consulted for session-less frames here and
133
+ * forwarded to every session this client opens — one registration covers
134
+ * both connection-level state and the per-session fold.
135
+ */
136
+ readonly extensions?: readonly FoldExtension[];
117
137
  }
118
138
  /** What `MuseClient.spawn` needs: FR-018's `{ museBin?, args?, env? }`, plus the handshake. */
119
139
  export interface MuseClientSpawnOptions {
@@ -139,6 +159,38 @@ export interface MuseClientSpawnOptions {
139
159
  readonly onStderr?: (chunk: string) => void;
140
160
  /** See `MuseServeChildOptions.shutdownTimeoutMs`. */
141
161
  readonly shutdownTimeoutMs?: number;
162
+ /**
163
+ * See `MuseServeChildOptions.spawnFn`: lets an embedder run the handshake
164
+ * and its sessions against an in-memory fake host. Host discovery still
165
+ * runs first, so pass `museBin` (any string; it becomes `spawnFn`'s
166
+ * command) when no `muse` is on `PATH`.
167
+ */
168
+ readonly spawnFn?: MuseServeChildOptions["spawnFn"];
169
+ /**
170
+ * See `SpawnMspConnectionOptions.refuseDeclaredBreakingSchema` (ADR 22936
171
+ * D3, default off): refuse the declared-breaking schema tier at connect
172
+ * with a `SchemaCompatibilityError`, the host closed. Off, the connection
173
+ * goes ahead and nothing here warns: read the tier with
174
+ * `classifyServedSchema(client.initializeResult.schema)`.
175
+ */
176
+ readonly refuseDeclaredBreakingSchema?: boolean;
177
+ /**
178
+ * Cancels startup, e.g. `AbortSignal.timeout(ms)`. Aborting before `spawn`
179
+ * resolves closes the host through the usual shutdown ladder, then rejects
180
+ * with an `AbortError` whose `cause` is `signal.reason`; an already-aborted
181
+ * signal spawns nothing. Aborting after `spawn` resolved does nothing: use
182
+ * `close()`. The rejection waits for the host to exit: a host that ignores
183
+ * stdin EOF takes up to `shutdownTimeoutMs` plus the 2 s SIGTERM grace.
184
+ * Unlike `Session.run`, which rejects with `signal.reason`, this
185
+ * follows Node's `child_process.spawn`: check `error.name === "AbortError"`
186
+ * and read `error.cause`.
187
+ */
188
+ readonly signal?: AbortSignal;
189
+ /**
190
+ * Fold extensions (FR-97527-3): connection-level state plus every
191
+ * session this client opens. See `MuseClientOptions.extensions`.
192
+ */
193
+ readonly extensions?: readonly FoldExtension[];
142
194
  }
143
195
  /**
144
196
  * Your entry point to the SDK.
@@ -163,6 +215,9 @@ export declare class MuseClient {
163
215
  * Rejects with {@link MuseHostDiscoveryError} before starting anything when
164
216
  * `museBin` is omitted and no executable `muse` is on `PATH`.
165
217
  *
218
+ * Rejects with an `AbortError` (`cause`: `signal.reason`) when `signal`
219
+ * aborts before the handshake completes, once the host has exited.
220
+ *
166
221
  * Rejects with {@link MuseHostStartError} when the host is lost before the
167
222
  * handshake completes (the binary could not be spawned, or the process
168
223
  * ended first — exit code or signal plus the bounded stderr tail;
@@ -170,7 +225,10 @@ export declare class MuseClient {
170
225
  * that answers with a reply the SDK refuses keeps its own error: an
171
226
  * `MspError` for an SS1.6 refusal, or a `ProtocolError` (with the whole
172
227
  * refused frame on `line`) for a reply the SDK cannot use, such as one with
173
- * no schema fingerprint.
228
+ * no schema fingerprint. With `refuseDeclaredBreakingSchema`, a host whose
229
+ * schema identity is a declared non-additive advance from this SDK's pin
230
+ * is refused with a `SchemaCompatibilityError` (ADR 22936 D3), the host
231
+ * closed.
174
232
  */
175
233
  static spawn(options: MuseClientSpawnOptions): Promise<MuseClient>;
176
234
  /**
@@ -184,6 +242,44 @@ export declare class MuseClient {
184
242
  get initializeResult(): InitializeResult;
185
243
  /** The host's SS2.11 exit row, when this client was built by `spawn`. */
186
244
  get exit(): Promise<ExitClassification>;
245
+ /**
246
+ * Settles when the connection closes for any reason: `close()`, the host
247
+ * hanging up, or a transport failure.
248
+ */
249
+ get closed(): Promise<void>;
250
+ /**
251
+ * Hear every server notification in wire order, including those naming no
252
+ * session (`usage/changed`, `account/loginCompleted`) or a session this
253
+ * client did not open. A frame naming a session this client has opened
254
+ * reaches the listener after that session has applied it: folded, or, while
255
+ * the session fills a gap, buffered and folded when the fill completes. One
256
+ * that arrives while its session's start/resume is still in flight reaches
257
+ * the listener first, and the session folds it before the verb returns.
258
+ * Returns the unsubscribe function.
259
+ *
260
+ * The frame is read-only: it is the one the session folds, which for a held
261
+ * or buffered frame happens after the listener runs. Like a `Connection`
262
+ * handler, the listener runs in the read loop, so it must not block. A throw, or an async listener's rejection, goes to every
263
+ * `onNotificationError` handler; the other listeners still hear the frame
264
+ * and the connection stays open.
265
+ */
266
+ onNotification(listener: NotificationObserver): () => void;
267
+ /**
268
+ * Hear what an `onNotification` listener threw or rejected with. With no
269
+ * handler the failure is dropped; either way the pump keeps running.
270
+ * Returns a function that removes this one subscription.
271
+ */
272
+ onNotificationError(handler: NotificationFailureHandler): () => void;
273
+ /**
274
+ * Hear each framing or correlation violation the connection detects
275
+ * (`Connection.onProtocolError`). The handler's own throw or rejection is
276
+ * swallowed rather than ending the connection; it is already the observer
277
+ * of failures, so there is no one left to tell. The first call takes over
278
+ * `Connection.onProtocolError`, replacing a handler set there directly (and
279
+ * a later direct `connection.onProtocolError(...)` silences these
280
+ * subscribers). Returns a function that removes this one subscription.
281
+ */
282
+ onProtocolError(handler: ProtocolErrorHandler): () => void;
187
283
  /** The durability profile every session this client opens inherits. */
188
284
  get durability(): SessionDurabilityProfile;
189
285
  /** Open a new root session (tdd SS2.5.1). */
@@ -217,22 +313,67 @@ export declare class MuseClient {
217
313
  readUsage(): Promise<UsageReadResult>;
218
314
  /**
219
315
  * Send a wire method directly (FR-79107-2), typically one the facade does
220
- * not wrap, through the
316
+ * not wrap, experimental ones included, through the
221
317
  * same `Connection.command()` the verbs use: the connection mints the
222
318
  * `commandId`, retries a nothing-admitted refusal under the same id, and
223
- * checks the ack's echo. `options` are that seam's own.
319
+ * checks the ack's echo. `options` are that seam's own. A stable method
320
+ * takes and returns its generated map types, without `commandId`; any other
321
+ * name stays sendable untyped. An experimental
322
+ * method needs a client spawned with `capabilities: { experimentalApi: true }`
323
+ * (otherwise the host refuses it with an `MspError` of kind
324
+ * `experimentalRequired`, code -32601) and may change without notice.
224
325
  *
225
326
  * Refused before anything is written, with `MuseFacadeOwnedMethodError`:
226
- * the methods whose state the facade owns (`FACADE_OWNED_METHODS`). Frames
327
+ * the methods whose state the facade owns (`FACADE_OWNED_METHODS`); the
328
+ * experimental host stop is not among them (this package names no
329
+ * experimental-only method), so sent raw it is the caller's own, and the
330
+ * exit it causes reaches your sessions as a host death; `close()` is the
331
+ * orderly stop. Frames
227
332
  * the command causes still reach your sessions through the client's one
228
- * inbound pump; this sends and returns the ack, nothing more. Params and
229
- * ack stay untyped objects: the generated types carry no method-to-params
230
- * map, and restating one here would drift from the schema.
333
+ * inbound pump; this sends and returns the ack, nothing more.
231
334
  *
232
335
  * 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.
336
+ * (FR-45137-1), so prefer `request` for a query you poll.
337
+ */
338
+ command<M extends RawMethodName>(method: M, params: CommandParams<M>, options?: CommandOptions): Promise<WireResult<M>>;
339
+ command<M extends string>(method: UnlistedMethod<MethodName, M>, params: Record<string, unknown>, options?: CommandOptions): Promise<Record<string, unknown>>;
340
+ /**
341
+ * @deprecated Loosely typed params for a listed method: pass the method's
342
+ * generated params type. This overload goes away in a later release
343
+ * (ADR 25304 D3's deprecation path).
344
+ */
345
+ command(method: RawMethodName, params: Record<string, unknown>, options?: CommandOptions): Promise<Record<string, unknown>>;
346
+ /**
347
+ * @deprecated A union mixing listed and unlisted names cannot be checked;
348
+ * it compiles untyped for one release and goes away with the loose
349
+ * overload above. A facade-owned member is still refused, and a generic
350
+ * `M extends string` name does not compile here. Widen the name to
351
+ * `string` (`method as string`) to keep sending it untyped.
352
+ */
353
+ command<M extends string>(method: NotFacadeOwned<M>, params: Record<string, unknown>, options?: CommandOptions): Promise<Record<string, unknown>>;
354
+ /**
355
+ * Send a wire request directly (FR-79107-2), typically a query the facade
356
+ * does not wrap, experimental ones included, through `Connection.request()`:
357
+ * no `commandId`, no retry, and omitted `params` stay off the frame.
358
+ * Refuses the same facade-owned methods as `command`, the same way, and
359
+ * needs the same `experimentalApi` opt-in for an experimental method. Typed
360
+ * like `command`: a stable method takes and returns its map types, any
361
+ * other name stays sendable untyped.
362
+ */
363
+ request<M extends RawMethodName>(method: M, ...params: ParamsArgument<MethodParams<M>>): Promise<WireResult<M>>;
364
+ request<M extends string>(method: UnlistedMethod<MethodName, M>, params?: Record<string, unknown>): Promise<Record<string, unknown>>;
365
+ /**
366
+ * @deprecated Loosely typed params for a listed method: pass the method's
367
+ * generated params type. This overload goes away in a later release
368
+ * (ADR 25304 D3's deprecation path).
369
+ */
370
+ request(method: RawMethodName, params?: Record<string, unknown>): Promise<Record<string, unknown>>;
371
+ /**
372
+ * @deprecated A mixed-union method name cannot be checked; it compiles
373
+ * untyped for one release, as on `command`. Widen the name to `string`
374
+ * (`method as string`) to keep sending it untyped.
234
375
  */
235
- command(method: Exclude<MspMethod, FacadeOwnedMethod>, params: Record<string, unknown>, options?: CommandOptions): Promise<Record<string, unknown>>;
376
+ request<M extends string>(method: NotFacadeOwned<M>, params?: Record<string, unknown>): Promise<Record<string, unknown>>;
236
377
  /**
237
378
  * Shut the host down in an orderly way (SS2.1.2); the shutdown this causes
238
379
  * is not reported to your sessions as a host death.