@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 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
- /** A local framing/correlation violation, never a server-authored MSP error. */
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
- * reach for a bare `Connection` when you need the raw notification feed or
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
- /** A local framing/correlation violation, never a server-authored MSP error. */
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
- async function defaultRetryDelay(attempt) {
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
- * reach for a bare `Connection` when you need the raw notification feed or
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.reject(new ProtocolError("connection is closed"));
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(error);
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(error);
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, and the shutdown drain budget.
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
- * Deterministic-test seam; production always uses `child_process.spawn`.
79
- * A stub here observes the exact options the call site passes, so a
80
- * `windowsHide` override at the call site fails the pin (FR-45141-1).
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);
@@ -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
+ }
@@ -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
+ }