@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,21 +35,51 @@
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 { 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, SessionResumeParams, SessionStartParams } 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;
53
+ /**
54
+ * The wire methods whose state the facade owns, refused by `command`
55
+ * (FR-79107-2). `initialize` is the handshake `spawn` runs; `session/start` and
56
+ * `session/resume` register the `Session` the pump routes to; `turn/start`,
57
+ * `turn/steer`, `turn/unqueue`, `approval/decide`, and `userInput/answer`
58
+ * carry the pending-command, approval, and answer state their verbs keep (a
59
+ * steer is a pending submission and an accepted unqueue retires its queued
60
+ * entry); `view/page` is the gap fill's; and
61
+ * `view/subscribe`/`view/unsubscribe` change the subscription set the pump
62
+ * routes by, so a raw unsubscribe would silently starve a live `Session`.
63
+ */
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"];
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);
44
74
  /**
45
75
  * Caller-facing options for `session/start` (tdd SS2.5.1).
46
76
  *
47
- * `config` is excluded as well as `commandId` until the facade implements the
48
- * required `sessionMcp` grant check and forwarding; `previousSessionId` is
49
- * excluded because the facade starts root sessions, and `spawnedBy` because
50
- * the facade does not expose a spawner yet.
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).
51
81
  */
52
- export type StartSessionOptions = Readonly<Omit<SessionStartParams, "commandId" | "config" | "previousSessionId" | "spawnedBy"> & {
82
+ export type StartSessionOptions = Readonly<Omit<SessionStartParams, "commandId" | "previousSessionId" | "clear" | "switchPolicy" | "spawnedBy"> & {
53
83
  /**
54
84
  * Require the `permissionProfile` selection (TEST-42624-10): when set,
55
85
  * the client proves the committed selection equals the requested id —
@@ -60,8 +90,11 @@ export type StartSessionOptions = Readonly<Omit<SessionStartParams, "commandId"
60
90
  */
61
91
  requirePermissionProfile?: boolean;
62
92
  }>;
63
- /** Caller-facing options for `session/resume` (tdd SS2.5.2). */
64
- export type ResumeSessionOptions = Readonly<Omit<SessionResumeParams, "commandId" | "config"> & {
93
+ /**
94
+ * Caller-facing options for `session/resume` (tdd SS2.5.2). `config.mcpServers`
95
+ * needs the host's `sessionMcp` grant, as at start (FR-79107-3).
96
+ */
97
+ export type ResumeSessionOptions = Readonly<Omit<SessionResumeParams, "commandId"> & {
65
98
  /**
66
99
  * Answers this session's approvals from its first frame, so an approval
67
100
  * the host re-sends right after the resume reply reaches it. The same
@@ -98,22 +131,49 @@ export interface MuseClientOptions {
98
131
  * is why `close()` falls back to closing just the connection.
99
132
  */
100
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[];
101
140
  }
102
- /** What `MuseClient.spawn` needs: FR-018's `{ museBin, args?, env? }`, plus the handshake. */
141
+ /** What `MuseClient.spawn` needs: FR-018's `{ museBin?, args?, env? }`, plus the handshake. */
103
142
  export interface MuseClientSpawnOptions {
104
- readonly museBin: string;
143
+ /**
144
+ * The host binary. Omitted means the first executable `muse` on the
145
+ * process's `PATH` (FR-79107-1); with neither, `spawn` rejects with
146
+ * `MuseHostDiscoveryError` before starting anything.
147
+ */
148
+ readonly museBin?: string;
105
149
  readonly args?: readonly string[];
106
150
  readonly cwd?: string;
107
151
  /** REPLACES the child's environment (PATH included) — spread `process.env` to extend it. */
108
152
  readonly env?: NodeJS.ProcessEnv;
109
153
  /** Client identification, forwarded verbatim into `initialize` (SS1.4). */
110
154
  readonly clientInfo: InitializeParams["clientInfo"];
111
- /** Capability posture; absent means all defaults. */
155
+ /**
156
+ * Capability posture; absent means all defaults. `spawn` adds `sessionMcp`
157
+ * to `requestedCapabilities` (keeping yours) so per-session MCP servers can
158
+ * be granted (ADR 32760 D3).
159
+ */
112
160
  readonly capabilities?: InitializeParams["capabilities"];
113
161
  /** Raw stderr chunks, drained from process birth and never parsed (INV-010). */
114
162
  readonly onStderr?: (chunk: string) => void;
115
163
  /** See `MuseServeChildOptions.shutdownTimeoutMs`. */
116
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[];
117
177
  }
118
178
  /**
119
179
  * Your entry point to the SDK.
@@ -135,6 +195,9 @@ export declare class MuseClient {
135
195
  * absent/unrecognized distinction load-bearing, and a caller re-deriving it
136
196
  * by hand is a caller that can get it wrong.
137
197
  *
198
+ * Rejects with {@link MuseHostDiscoveryError} before starting anything when
199
+ * `museBin` is omitted and no executable `muse` is on `PATH`.
200
+ *
138
201
  * Rejects with {@link MuseHostStartError} when the host is lost before the
139
202
  * handshake completes (the binary could not be spawned, or the process
140
203
  * ended first — exit code or signal plus the bounded stderr tail;
@@ -156,6 +219,44 @@ export declare class MuseClient {
156
219
  get initializeResult(): InitializeResult;
157
220
  /** The host's SS2.11 exit row, when this client was built by `spawn`. */
158
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;
159
260
  /** The durability profile every session this client opens inherits. */
160
261
  get durability(): SessionDurabilityProfile;
161
262
  /** Open a new root session (tdd SS2.5.1). */
@@ -170,6 +271,56 @@ export declare class MuseClient {
170
271
  * server answers.
171
272
  */
172
273
  resumeSession(options: ResumeSessionOptions): Promise<Session>;
274
+ /**
275
+ * List stored sessions (`session/list`), including text search via
276
+ * `filter.text`. A read-only list: rides `request()`, not `command()`
277
+ * (see `Session.listTasks`).
278
+ */
279
+ listSessions(options?: SessionListParams): Promise<SessionListResult>;
280
+ /**
281
+ * List the models the host accepts in `Session.setModel` (`model/list`).
282
+ * With `sessionId`, that session's current model is flagged `isActive`. A
283
+ * query: rides `request()`, like `listSessions`.
284
+ */
285
+ listModels(options?: ModelListParams): Promise<ModelListResult>;
286
+ /**
287
+ * Read the host's last-observed subscription usage (`usage/read`) without a
288
+ * model call; `usage` is absent when the host has observed nothing.
289
+ */
290
+ readUsage(): Promise<UsageReadResult>;
291
+ /**
292
+ * Send a wire method directly (FR-79107-2), typically one the facade does
293
+ * not wrap, experimental ones included, through the
294
+ * same `Connection.command()` the verbs use: the connection mints the
295
+ * `commandId`, retries a nothing-admitted refusal under the same id, and
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.
300
+ *
301
+ * Refused before anything is written, with `MuseFacadeOwnedMethodError`:
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
307
+ * the command causes still reach your sessions through the client's one
308
+ * inbound pump; this sends and returns the ack, nothing more. Params and
309
+ * ack stay untyped objects: the generated types carry no method-to-params
310
+ * map, and restating one here would drift from the schema.
311
+ *
312
+ * Each call keeps one fixed-size fingerprint for the connection's lifetime
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.
322
+ */
323
+ request<M extends RawMethodName>(method: RawMethod<M>, params?: Record<string, unknown>): Promise<Record<string, unknown>>;
173
324
  /**
174
325
  * Shut the host down in an orderly way (SS2.1.2); the shutdown this causes
175
326
  * is not reported to your sessions as a host death.
@@ -187,3 +338,4 @@ export declare class MuseClient {
187
338
  */
188
339
  close(): Promise<void>;
189
340
  }
341
+ export {};