@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.
- package/README.md +78 -2
- package/dist/src/connection/connection.d.ts +83 -6
- package/dist/src/connection/connection.js +113 -14
- package/dist/src/connection/spawn.d.ts +50 -4
- package/dist/src/connection/spawn.js +161 -33
- package/dist/src/connection/surface.d.ts +49 -0
- package/dist/src/connection/surface.js +8 -0
- package/dist/src/errors.d.ts +6 -5
- package/dist/src/errors.js +7 -6
- package/dist/src/facade/approval.js +1 -1
- package/dist/src/facade/client.d.ts +158 -17
- package/dist/src/facade/client.js +370 -74
- package/dist/src/facade/gap-fill.d.ts +2 -0
- package/dist/src/facade/gap-fill.js +11 -2
- 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 +133 -5
- package/dist/src/facade/session.js +419 -13
- package/dist/src/facade/turn-handle.d.ts +23 -0
- package/dist/src/facade/turn-handle.js +1 -1
- package/dist/src/fingerprint.d.ts +79 -4
- package/dist/src/fingerprint.js +110 -11
- package/dist/src/fingerprint.stamped.d.ts +2 -1
- package/dist/src/fingerprint.stamped.js +2 -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 +6 -5
- package/dist/src/index.js +1 -1
- package/dist/src/msp.d.ts +319 -10
- package/package.json +1 -1
|
@@ -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 {
|
|
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,
|
|
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
|
|
62
|
-
* because the facade does not expose a spawner yet.
|
|
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`)
|
|
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.
|
|
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
|
|
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
|
-
|
|
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.
|