@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.
- package/README.md +65 -3
- package/dist/src/connection/connection.d.ts +21 -4
- package/dist/src/connection/connection.js +52 -9
- package/dist/src/connection/discovery.d.ts +14 -0
- package/dist/src/connection/discovery.js +39 -0
- package/dist/src/connection/spawn.d.ts +24 -4
- package/dist/src/connection/spawn.js +5 -2
- package/dist/src/errors.d.ts +38 -0
- package/dist/src/errors.js +53 -0
- package/dist/src/facade/client.d.ts +165 -13
- package/dist/src/facade/client.js +325 -28
- package/dist/src/facade/host-death.d.ts +5 -1
- package/dist/src/facade/host-death.js +5 -1
- package/dist/src/facade/run.d.ts +50 -0
- package/dist/src/facade/run.js +132 -0
- package/dist/src/facade/session.d.ts +139 -5
- package/dist/src/facade/session.js +372 -6
- package/dist/src/facade/turn-handle.d.ts +88 -6
- package/dist/src/facade/turn-handle.js +20 -4
- package/dist/src/facade/turn-submit.d.ts +27 -16
- package/dist/src/facade/turn-submit.js +68 -28
- package/dist/src/fingerprint.d.ts +4 -18
- package/dist/src/fingerprint.js +30 -20
- package/dist/src/fingerprint.stamped.d.ts +1 -0
- package/dist/src/fingerprint.stamped.js +6 -0
- 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 +30 -5
- package/dist/src/fold/session-fold.js +86 -1
- package/dist/src/index.d.ts +7 -5
- package/dist/src/index.js +1 -1
- package/dist/src/msp.d.ts +391 -33
- package/package.json +3 -1
|
@@ -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 {
|
|
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
|
-
* `
|
|
48
|
-
*
|
|
49
|
-
*
|
|
50
|
-
*
|
|
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" | "
|
|
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
|
-
/**
|
|
64
|
-
|
|
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
|
|
141
|
+
/** What `MuseClient.spawn` needs: FR-018's `{ museBin?, args?, env? }`, plus the handshake. */
|
|
103
142
|
export interface MuseClientSpawnOptions {
|
|
104
|
-
|
|
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
|
-
/**
|
|
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 {};
|