@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 +27 -0
- package/dist/src/connection/connection.d.ts +21 -4
- package/dist/src/connection/connection.js +50 -8
- package/dist/src/connection/spawn.d.ts +24 -4
- package/dist/src/connection/spawn.js +5 -2
- package/dist/src/errors.d.ts +6 -5
- package/dist/src/errors.js +7 -6
- package/dist/src/facade/client.d.ts +101 -13
- package/dist/src/facade/client.js +193 -33
- 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 +57 -3
- package/dist/src/facade/session.js +90 -12
- package/dist/src/facade/turn-handle.d.ts +23 -0
- package/dist/src/facade/turn-handle.js +1 -1
- package/dist/src/fingerprint.stamped.d.ts +1 -1
- package/dist/src/fingerprint.stamped.js +1 -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 +3 -2
- package/dist/src/msp.d.ts +41 -8
- package/package.json +1 -1
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
|
-
/**
|
|
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
|
-
*
|
|
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
|
-
/**
|
|
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
|
-
*
|
|
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
|
|
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
|
|
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
|
|
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,
|
|
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
|
-
*
|
|
79
|
-
*
|
|
80
|
-
* `windowsHide` override at the call site fails the
|
|
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);
|
package/dist/src/errors.d.ts
CHANGED
|
@@ -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
|
|
88
|
-
* (FR-79107-2). Sending it raw would bypass that
|
|
89
|
-
* before anything is written; use the facade verb
|
|
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. */
|
package/dist/src/errors.js
CHANGED
|
@@ -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
|
|
98
|
-
* (FR-79107-2). Sending it raw would bypass that
|
|
99
|
-
* before anything is written; use the facade verb
|
|
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
|
|
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 {
|
|
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
|
|
62
|
-
* because the facade does not expose a spawner yet.
|
|
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`)
|
|
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
|
|
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
|
-
|
|
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.
|