@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
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
|
|
@@ -48,20 +53,40 @@ exact version, and read the changelog before moving off it.
|
|
|
48
53
|
import { MuseClient } from "@muse-code/sdk";
|
|
49
54
|
|
|
50
55
|
const client = await MuseClient.spawn({
|
|
51
|
-
museBin: "muse",
|
|
52
56
|
args: ["serve"],
|
|
53
57
|
clientInfo: { name: "my-app", version: "1.0.0" },
|
|
54
58
|
});
|
|
55
59
|
|
|
56
60
|
const session = await client.startSession({ workspaceRoot: process.cwd() });
|
|
57
61
|
|
|
62
|
+
const result = await session.run("Summarize this repository.");
|
|
63
|
+
console.log(result.finalText);
|
|
64
|
+
|
|
65
|
+
await client.close();
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
`session.run` sends one turn and resolves when the turn has ended, with the
|
|
69
|
+
outcome, the final answer text, the turn's items, and its token usage. A turn
|
|
70
|
+
that failed or was cancelled still resolves; read `result.outcome` to tell.
|
|
71
|
+
The final answer is the last completed agent message that is not commentary.
|
|
72
|
+
Pass input parts instead of a string, and the turn options as the second
|
|
73
|
+
argument:
|
|
74
|
+
`session.run(parts, { reasoningEffort: "high" })`.
|
|
75
|
+
|
|
76
|
+
To stop it, pass an `AbortSignal`, for example
|
|
77
|
+
`session.run(prompt, { signal: AbortSignal.timeout(60_000) })`. A turn still
|
|
78
|
+
waiting in the queue is taken back, and a running turn is cancelled. `run`
|
|
79
|
+
then waits for the turn to end and rejects with the signal's reason. An
|
|
80
|
+
already-aborted signal sends nothing.
|
|
81
|
+
|
|
82
|
+
To follow a turn as it runs, send it yourself and read its items:
|
|
83
|
+
|
|
84
|
+
```ts
|
|
58
85
|
const turn = await session.sendUserTurn({
|
|
59
86
|
input: [{ type: "text", text: "Summarize this repository." }],
|
|
60
87
|
});
|
|
61
88
|
for await (const item of turn.items()) console.log(item);
|
|
62
89
|
await turn.completed;
|
|
63
|
-
|
|
64
|
-
await client.close();
|
|
65
90
|
```
|
|
66
91
|
|
|
67
92
|
`turn.items()` replays what the session already holds before its live tail;
|
|
@@ -97,6 +122,28 @@ the resume reply can happen before `resumeSession` returns, so
|
|
|
97
122
|
that throws, picks a choice that was not offered, or adds feedback to a choice
|
|
98
123
|
that takes none (which is then answered with the reject choice).
|
|
99
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
|
+
|
|
100
147
|
To answer a question the agent asks, read it from
|
|
101
148
|
`session.fold.pendingUserInputs()` and answer it with `session.answerUserInput`,
|
|
102
149
|
one answer per question: `selectedLabel` for a single-select question,
|
|
@@ -113,10 +160,25 @@ if (prompt !== undefined && question !== undefined) {
|
|
|
113
160
|
}
|
|
114
161
|
```
|
|
115
162
|
|
|
163
|
+
To stop a running turn, call `turn.interrupt()` (the stop gesture; pass
|
|
164
|
+
`{ retract: true }` to also take the prompt back) or `turn.cancel()`. Both are
|
|
165
|
+
requests: the turn is over when `turn.completed` settles. `turn.steer({ input })`
|
|
166
|
+
adds input to the running turn, and `turn.unqueue()` takes back a queued one.
|
|
167
|
+
The session itself can `fork`, `compact`, `rename`, and `leave`, and switch its
|
|
168
|
+
model, reasoning effort, or approval mode (`setModel`, `setReasoningEffort`,
|
|
169
|
+
`setApprovalMode`); `client.listModels()` lists the models it accepts.
|
|
170
|
+
|
|
116
171
|
Status: developer preview. The facade — spawn, session open/resume, turns,
|
|
117
172
|
approvals, questions, and recovery after dropped deliveries — is complete and covered by
|
|
118
173
|
the conformance suites in the source repository.
|
|
119
174
|
|
|
175
|
+
## Not yet available
|
|
176
|
+
|
|
177
|
+
`@muse-code/acp` is not published on npm and is not part of this public
|
|
178
|
+
repository. There is no supported ACP adapter to install today; please do not
|
|
179
|
+
depend on that package name. If an ACP adapter ships, it will be announced in
|
|
180
|
+
a public release.
|
|
181
|
+
|
|
120
182
|
## Documentation
|
|
121
183
|
|
|
122
184
|
- Guides, cookbook recipes, and the protocol reference:
|
|
@@ -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
|
|
@@ -131,7 +145,8 @@ export function createUuidV7Mint() {
|
|
|
131
145
|
return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
|
|
132
146
|
};
|
|
133
147
|
}
|
|
134
|
-
|
|
148
|
+
/** @internal The jittered backoff `command` retries with; `Session.run` reuses it. */
|
|
149
|
+
export async function defaultRetryDelay(attempt) {
|
|
135
150
|
const ceilingMs = Math.min(2_000, 50 * 2 ** Math.max(0, attempt - 1));
|
|
136
151
|
const delayMs = Math.floor(Math.random() * (ceilingMs + 1));
|
|
137
152
|
await new Promise((resolve) => setTimeout(resolve, delayMs));
|
|
@@ -146,9 +161,10 @@ function isObject(value) {
|
|
|
146
161
|
* responses, enforces the frame-size limit, and hands inbound notifications
|
|
147
162
|
* and server requests to the handlers you register. It is transport-agnostic:
|
|
148
163
|
* pair it with any `DuplexTransport`. Most applications never build one
|
|
149
|
-
* directly — `MuseClient.spawn` or `spawnMspConnection` does it for you
|
|
150
|
-
*
|
|
151
|
-
* 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.
|
|
152
168
|
*/
|
|
153
169
|
export class Connection {
|
|
154
170
|
#transport;
|
|
@@ -161,6 +177,8 @@ export class Connection {
|
|
|
161
177
|
#serverRequestHandler;
|
|
162
178
|
#notificationHandler;
|
|
163
179
|
#protocolErrorHandler;
|
|
180
|
+
#peerEndCause;
|
|
181
|
+
#endCause;
|
|
164
182
|
#writeTail = Promise.resolve();
|
|
165
183
|
// Settles when every accepted frame has been HANDED to the transport, as
|
|
166
184
|
// opposed to #writeTail, which settles when the peer has taken it.
|
|
@@ -201,13 +219,21 @@ export class Connection {
|
|
|
201
219
|
request(method, params) {
|
|
202
220
|
return this.#request(method, params).then((framed) => framed.result);
|
|
203
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
|
+
}
|
|
204
229
|
/** See {@link requestWithFrame}. */
|
|
205
230
|
[requestWithFrame](method, params) {
|
|
206
231
|
return this.#request(method, params);
|
|
207
232
|
}
|
|
208
233
|
#request(method, params) {
|
|
209
|
-
if (this.#finished)
|
|
210
|
-
return Promise
|
|
234
|
+
if (this.#finished) {
|
|
235
|
+
return new Promise((_, reject) => this.#rejectWithEndCause(reject, new ProtocolError("connection is closed")));
|
|
236
|
+
}
|
|
211
237
|
const id = this.#mintRequestId();
|
|
212
238
|
if (typeof id !== "string" && (typeof id !== "number" || !Number.isInteger(id))) {
|
|
213
239
|
return Promise.reject(new ProtocolError("request id must be a string or integer"));
|
|
@@ -228,7 +254,7 @@ export class Connection {
|
|
|
228
254
|
});
|
|
229
255
|
void this.#write(request).catch((error) => {
|
|
230
256
|
this.#pending.delete(requestKey(id));
|
|
231
|
-
reject
|
|
257
|
+
this.#rejectWithEndCause(reject, error);
|
|
232
258
|
});
|
|
233
259
|
});
|
|
234
260
|
}
|
|
@@ -301,7 +327,10 @@ export class Connection {
|
|
|
301
327
|
return ack;
|
|
302
328
|
}
|
|
303
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.
|
|
304
332
|
const retryableNothingAdmitted = error instanceof MspError &&
|
|
333
|
+
error.retryable !== false &&
|
|
305
334
|
((error.code === -32001 && error.kind === "overloaded") ||
|
|
306
335
|
(error.code === -32031 && error.kind === "backpressured"));
|
|
307
336
|
if (!retryableNothingAdmitted || attempt === maxAttempts)
|
|
@@ -564,6 +593,19 @@ export class Connection {
|
|
|
564
593
|
}).catch((writeError) => this.#finish(writeError)); // FM-009
|
|
565
594
|
}
|
|
566
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
|
+
}
|
|
567
609
|
#protocolError(error) {
|
|
568
610
|
this.#protocolErrorHandler?.(error);
|
|
569
611
|
}
|
|
@@ -572,8 +614,9 @@ export class Connection {
|
|
|
572
614
|
return;
|
|
573
615
|
this.#finished = true;
|
|
574
616
|
const error = reason instanceof Error ? reason : new ProtocolError(String(reason));
|
|
617
|
+
this.#endCause = this.#peerEndCause?.();
|
|
575
618
|
for (const pending of this.#pending.values())
|
|
576
|
-
pending.reject
|
|
619
|
+
this.#rejectWithEndCause(pending.reject, error);
|
|
577
620
|
this.#pending.clear();
|
|
578
621
|
this.#resolveClosed?.();
|
|
579
622
|
this.#resolveClosed = undefined;
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Host discovery for `MuseClient.spawn` (FR-79107-1), mirroring the Rust SDK's
|
|
3
|
+
* `discover_muse_bin` and the Python SDK's: an explicit `museBin` wins and is
|
|
4
|
+
* returned verbatim (existence is the spawn's to prove), else the first
|
|
5
|
+
* executable `muse` on the process `PATH` — `muse.exe` on Windows, as in Rust.
|
|
6
|
+
* The package does not bundle a host, so no host is a typed error raised
|
|
7
|
+
* before any process is started.
|
|
8
|
+
*/
|
|
9
|
+
/**
|
|
10
|
+
* Resolve the host binary. `path` and `platform` are parameters, not reads, so
|
|
11
|
+
* tests drive them; `MuseClient.spawn` passes the process's own. An empty
|
|
12
|
+
* `PATH` entry is skipped rather than read as the working directory.
|
|
13
|
+
*/
|
|
14
|
+
export declare function discoverMuseBin(museBin: string | undefined, path: string | undefined, platform: NodeJS.Platform): Promise<string>;
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Host discovery for `MuseClient.spawn` (FR-79107-1), mirroring the Rust SDK's
|
|
3
|
+
* `discover_muse_bin` and the Python SDK's: an explicit `museBin` wins and is
|
|
4
|
+
* returned verbatim (existence is the spawn's to prove), else the first
|
|
5
|
+
* executable `muse` on the process `PATH` — `muse.exe` on Windows, as in Rust.
|
|
6
|
+
* The package does not bundle a host, so no host is a typed error raised
|
|
7
|
+
* before any process is started.
|
|
8
|
+
*/
|
|
9
|
+
import { stat } from "node:fs/promises";
|
|
10
|
+
import { join } from "node:path";
|
|
11
|
+
import { MuseHostDiscoveryError } from "../errors.js";
|
|
12
|
+
/**
|
|
13
|
+
* Resolve the host binary. `path` and `platform` are parameters, not reads, so
|
|
14
|
+
* tests drive them; `MuseClient.spawn` passes the process's own. An empty
|
|
15
|
+
* `PATH` entry is skipped rather than read as the working directory.
|
|
16
|
+
*/
|
|
17
|
+
export async function discoverMuseBin(museBin, path, platform) {
|
|
18
|
+
if (museBin !== undefined)
|
|
19
|
+
return museBin;
|
|
20
|
+
const windows = platform === "win32";
|
|
21
|
+
const name = windows ? "muse.exe" : "muse";
|
|
22
|
+
for (const directory of (path ?? "").split(windows ? ";" : ":")) {
|
|
23
|
+
if (directory === "")
|
|
24
|
+
continue;
|
|
25
|
+
const candidate = join(directory, name);
|
|
26
|
+
if (await isExecutable(candidate, windows))
|
|
27
|
+
return candidate;
|
|
28
|
+
}
|
|
29
|
+
throw new MuseHostDiscoveryError();
|
|
30
|
+
}
|
|
31
|
+
async function isExecutable(candidate, windows) {
|
|
32
|
+
try {
|
|
33
|
+
const found = await stat(candidate);
|
|
34
|
+
return found.isFile() && (windows || (found.mode & 0o111) !== 0);
|
|
35
|
+
}
|
|
36
|
+
catch {
|
|
37
|
+
return false;
|
|
38
|
+
}
|
|
39
|
+
}
|
|
@@ -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
|
@@ -69,3 +69,41 @@ export declare class PermissionProfileNotApplied extends Error {
|
|
|
69
69
|
readonly sessionId: string;
|
|
70
70
|
constructor(requested: string, served: string | null, sessionId: string);
|
|
71
71
|
}
|
|
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/latest/compatibility/";
|
|
74
|
+
/**
|
|
75
|
+
* No host binary was given and no executable `muse` is on `PATH` (FR-79107-1).
|
|
76
|
+
* Raised by `MuseClient.spawn` before any process is started. The package does
|
|
77
|
+
* not bundle a host; install Muse Code or pass `museBin`.
|
|
78
|
+
*/
|
|
79
|
+
export declare class MuseHostDiscoveryError extends Error {
|
|
80
|
+
/** The spawn option that names an explicit host path. */
|
|
81
|
+
readonly parameter = "museBin";
|
|
82
|
+
/** The page listing the host versions this SDK supports. */
|
|
83
|
+
readonly compatibilityUrl = "https://meta-models.github.io/muse-code-sdk/latest/compatibility/";
|
|
84
|
+
constructor();
|
|
85
|
+
}
|
|
86
|
+
/**
|
|
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.
|
|
91
|
+
*/
|
|
92
|
+
export declare class MuseFacadeOwnedMethodError extends Error {
|
|
93
|
+
/** The refused wire method. */
|
|
94
|
+
readonly method: string;
|
|
95
|
+
constructor(method: string);
|
|
96
|
+
}
|
|
97
|
+
/**
|
|
98
|
+
* A session open asked for something the host did not grant on this
|
|
99
|
+
* connection (FR-79107-3): today, per-session MCP servers (`config.mcpServers`)
|
|
100
|
+
* without the `sessionMcp` capability. Refused before anything is sent; the
|
|
101
|
+
* client stays usable, and an open without that request still goes through.
|
|
102
|
+
*/
|
|
103
|
+
export declare class MuseCapabilityNotGrantedError extends Error {
|
|
104
|
+
/** The capability the request needs. */
|
|
105
|
+
readonly capability: string;
|
|
106
|
+
/** The wire method that was refused. */
|
|
107
|
+
readonly method: string;
|
|
108
|
+
constructor(capability: string, method: string, reason: string);
|
|
109
|
+
}
|
package/dist/src/errors.js
CHANGED
|
@@ -74,3 +74,56 @@ export class PermissionProfileNotApplied extends Error {
|
|
|
74
74
|
this.sessionId = sessionId;
|
|
75
75
|
}
|
|
76
76
|
}
|
|
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/latest/compatibility/";
|
|
79
|
+
/**
|
|
80
|
+
* No host binary was given and no executable `muse` is on `PATH` (FR-79107-1).
|
|
81
|
+
* Raised by `MuseClient.spawn` before any process is started. The package does
|
|
82
|
+
* not bundle a host; install Muse Code or pass `museBin`.
|
|
83
|
+
*/
|
|
84
|
+
export class MuseHostDiscoveryError extends Error {
|
|
85
|
+
/** The spawn option that names an explicit host path. */
|
|
86
|
+
parameter = "museBin";
|
|
87
|
+
/** The page listing the host versions this SDK supports. */
|
|
88
|
+
compatibilityUrl = COMPATIBILITY_PAGE_URL;
|
|
89
|
+
constructor() {
|
|
90
|
+
super("no muse host found: pass museBin=<path to a muse binary> or put `muse` on PATH. " +
|
|
91
|
+
"The package does not bundle a host; supported host versions are listed on the " +
|
|
92
|
+
`compatibility page's TypeScript row: ${COMPATIBILITY_PAGE_URL}`);
|
|
93
|
+
this.name = "MuseHostDiscoveryError";
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
/**
|
|
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.
|
|
101
|
+
*/
|
|
102
|
+
export class MuseFacadeOwnedMethodError extends Error {
|
|
103
|
+
/** The refused wire method. */
|
|
104
|
+
method;
|
|
105
|
+
constructor(method) {
|
|
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");
|
|
108
|
+
this.name = "MuseFacadeOwnedMethodError";
|
|
109
|
+
this.method = method;
|
|
110
|
+
}
|
|
111
|
+
}
|
|
112
|
+
/**
|
|
113
|
+
* A session open asked for something the host did not grant on this
|
|
114
|
+
* connection (FR-79107-3): today, per-session MCP servers (`config.mcpServers`)
|
|
115
|
+
* without the `sessionMcp` capability. Refused before anything is sent; the
|
|
116
|
+
* client stays usable, and an open without that request still goes through.
|
|
117
|
+
*/
|
|
118
|
+
export class MuseCapabilityNotGrantedError extends Error {
|
|
119
|
+
/** The capability the request needs. */
|
|
120
|
+
capability;
|
|
121
|
+
/** The wire method that was refused. */
|
|
122
|
+
method;
|
|
123
|
+
constructor(capability, method, reason) {
|
|
124
|
+
super(`${method} was not sent: ${reason}`);
|
|
125
|
+
this.name = "MuseCapabilityNotGrantedError";
|
|
126
|
+
this.capability = capability;
|
|
127
|
+
this.method = method;
|
|
128
|
+
}
|
|
129
|
+
}
|