@muse-code/sdk 1.4.20 → 1.4.24

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.
@@ -1,7 +1,7 @@
1
1
  /** Node stdio binding and type-state handshake for the MSP connection. */
2
2
  import { spawn } from "node:child_process";
3
3
  import { Connection, ProtocolError, requestWithFrame, submissionTail, } from "./connection.js";
4
- import { checkServedFingerprint } from "../fingerprint.js";
4
+ import { SchemaCompatibilityError, classifyServedSchema, isWellFormedEpoch } from "../fingerprint.js";
5
5
  const DEFAULT_STDERR_MAX_BYTES = 8 * 1024;
6
6
  const DEFAULT_STDERR_MAX_LINES = 100;
7
7
  /** SS2.1.2's default host drain timeout: the whole EOF sequence's budget. */
@@ -14,6 +14,12 @@ const DEFAULT_SHUTDOWN_TIMEOUT_MS = 30_000;
14
14
  * Exported from this module only, never the package barrel.
15
15
  */
16
16
  export const SIGTERM_GRACE_MS = 2_000;
17
+ /**
18
+ * How long the pipes may keep draining after the child's `exit` before the
19
+ * transport drops its own ends. A process the host started can hold the other
20
+ * ends for good, and Node fires `close` only once every holder lets go.
21
+ */
22
+ const POST_EXIT_DRAIN_MS = 1_000;
17
23
  /** Node's own `setTimeout` ceiling; past it a delay silently clamps to 1 ms. */
18
24
  const MAX_SHUTDOWN_TIMEOUT_MS = 2_147_483_647;
19
25
  const ownedTransport = Symbol("MuseServeChild.transport");
@@ -25,6 +31,16 @@ const adoptFlushSource = Symbol("ChildStdioTransport.adoptFlushSource");
25
31
  * (#49912) without a new public member on `MspHandshake`.
26
32
  */
27
33
  export const initializeAnswered = Symbol("MspHandshake.initializeAnswered");
34
+ /**
35
+ * Node's abort shape (`child_process.spawn({ signal })`): callers branch on
36
+ * `name`. Exported from this MODULE only (never the package barrel) so the
37
+ * facade raises the same error before host discovery.
38
+ */
39
+ export function abortError(reason) {
40
+ const error = new Error("The operation was aborted", { cause: reason });
41
+ error.name = "AbortError";
42
+ return error;
43
+ }
28
44
  function makeShutdownDeadline(budgetMs) {
29
45
  let timer;
30
46
  const expired = new Promise((resolve) => {
@@ -166,6 +182,13 @@ export class ChildStdioTransport {
166
182
  // behaved identically, and `#closing ??=` let whichever call won the race
167
183
  // discard the other's submission promise (PR #22819 round 4).
168
184
  #defaultFlushed;
185
+ // Set when the transport dropped its pipe ends after the post-exit drain,
186
+ // so the stdout iterator reads the resulting premature close as EOF.
187
+ #droppedPipes = false;
188
+ // Whether the owned group still had members when the pipes were dropped;
189
+ // only then may close() signal it, so a group already empty at the drop is
190
+ // never signalled (one that empties later and is reused is not covered).
191
+ #leftoverGroup = false;
169
192
  constructor(child, onStderr, shutdownTimeoutMs = DEFAULT_SHUTDOWN_TIMEOUT_MS, ownsProcessGroup = false,
170
193
  /** Deterministic-test seam; production always uses `makeShutdownDeadline`. */
171
194
  deadlineFactory = makeShutdownDeadline) {
@@ -187,6 +210,14 @@ export class ChildStdioTransport {
187
210
  this.child.once("error", reject);
188
211
  this.child.once("close", (code, signal) => resolve({ code, signal }));
189
212
  });
213
+ this.child.once("exit", () => {
214
+ const drain = setTimeout(() => this.#dropPipes(), POST_EXIT_DRAIN_MS);
215
+ // Unref'd: a held pipe keeps the loop alive until the drain fires, and
216
+ // with nothing else waiting the embedder may exit without it.
217
+ drain.unref();
218
+ const clear = () => clearTimeout(drain);
219
+ void this.exited.then(clear, clear);
220
+ });
190
221
  // Mark handled at birth: a spawn failure (e.g. ENOENT) rejects `exited`
191
222
  // before anyone can await it, and the default unhandled-rejection policy
192
223
  // would kill the consumer. Later awaiters still receive the rejection.
@@ -266,11 +297,28 @@ export class ChildStdioTransport {
266
297
  * way to reach an exit, never a substitute for observing one.
267
298
  */
268
299
  async #awaitExitOrTerminate(deadline) {
269
- if (await this.#beforeDeadline(this.#settled(), deadline))
300
+ if (await this.#beforeDeadline(this.#settled(), deadline)) {
301
+ await this.#endLeftoverGroup();
270
302
  return;
303
+ }
271
304
  this.#signal("SIGTERM");
272
- if (await this.#settledWithin(SIGTERM_GRACE_MS))
273
- return;
305
+ // Deliberately ambient (NOT this.#makeShutdownDeadline): the SIGTERM grace
306
+ // window is outside the one shared shutdown budget the injected seam models.
307
+ const grace = makeShutdownDeadline(SIGTERM_GRACE_MS);
308
+ try {
309
+ if (await this.#beforeDeadline(this.#settled(), grace.expired)) {
310
+ // The drain can settle `exited` inside the grace while a group member
311
+ // that traps SIGTERM still runs: SIGKILL it when this same grace ends.
312
+ if (this.#leftoverGroup && this.#signalGroup(0)) {
313
+ await grace.expired;
314
+ this.#signalGroup("SIGKILL");
315
+ }
316
+ return;
317
+ }
318
+ }
319
+ finally {
320
+ grace.clear();
321
+ }
274
322
  // Past SIGTERM, drop our end of the pipe ourselves (PR #22819 round 3).
275
323
  // Nothing else does, so a write the host never drained keeps `stdin`
276
324
  // open — and the child's `close` event, which `exited` and the trailing
@@ -292,21 +340,36 @@ export class ChildStdioTransport {
292
340
  * an exited child — the ladder must never rethrow out of a stage.
293
341
  */
294
342
  #signal(signal) {
343
+ // A failed group signal falls through to the direct-child path, safe on
344
+ // every failure here.
345
+ if (this.#signalGroup(signal))
346
+ return;
347
+ this.child.kill(signal);
348
+ }
349
+ /** True only when the owned group existed and took the signal (`0` probes). */
350
+ #signalGroup(signal) {
295
351
  const pid = this.child.pid;
296
- if (this.#ownsProcessGroup && pid !== undefined) {
297
- try {
298
- process.kill(-pid, signal);
299
- return;
300
- }
301
- catch {
302
- // Fall through to the direct-child path, safe on every failure here.
303
- }
352
+ if (!this.#ownsProcessGroup || pid === undefined)
353
+ return false;
354
+ try {
355
+ process.kill(-pid, signal);
356
+ return true;
357
+ }
358
+ catch {
359
+ return false;
304
360
  }
305
- this.child.kill(signal);
306
361
  }
307
- /** True once `exited` settles either way — a rejection means no live child. */
308
- async #settledWithin(budgetMs) {
309
- return await this.#within(this.#settled(), budgetMs);
362
+ /**
363
+ * When the post-exit drain settled `exited` before the deadline, the ladder
364
+ * never ran, but what the host left in its own group must still end with it
365
+ * (FR-017b). A holder outside the group is left alone, and a group empty at
366
+ * the drop, or now (`ESRCH`), ends the stage at once.
367
+ */
368
+ async #endLeftoverGroup() {
369
+ if (!this.#leftoverGroup || !this.#signalGroup("SIGTERM"))
370
+ return;
371
+ await makeShutdownDeadline(SIGTERM_GRACE_MS).expired;
372
+ this.#signalGroup("SIGKILL");
310
373
  }
311
374
  /** True if `work` settles before the one shared shutdown deadline fires. */
312
375
  async #beforeDeadline(work, deadline) {
@@ -315,18 +378,6 @@ export class ChildStdioTransport {
315
378
  deadline.then(() => false),
316
379
  ]);
317
380
  }
318
- /** True if `work` settles inside `budgetMs`; false when the budget expires. */
319
- async #within(work, budgetMs) {
320
- // Deliberately ambient (NOT this.#makeShutdownDeadline): the SIGTERM grace
321
- // window is outside the one shared shutdown budget the injected seam models.
322
- const deadline = makeShutdownDeadline(budgetMs);
323
- try {
324
- return await this.#beforeDeadline(work, deadline.expired);
325
- }
326
- finally {
327
- deadline.clear();
328
- }
329
- }
330
381
  /**
331
382
  * `exited` REJECTS when the spawn itself failed (ENOENT). There is no
332
383
  * process to end and no exit to observe, so shutdown is complete; the
@@ -336,9 +387,27 @@ export class ChildStdioTransport {
336
387
  async #settled() {
337
388
  await this.exited.catch(() => { });
338
389
  }
390
+ /**
391
+ * Let go of our ends only: this sends no signal, but a holder's later writes
392
+ * fail (SIGPIPE/EPIPE) and its stdin reads EOF. `close` then fires, so
393
+ * `exited` reports the exit `exit` already saw.
394
+ */
395
+ #dropPipes() {
396
+ this.#droppedPipes = true;
397
+ this.#leftoverGroup = this.#signalGroup(0);
398
+ this.child.stdin.destroy();
399
+ this.child.stdout.destroy();
400
+ this.child.stderr.destroy();
401
+ }
339
402
  async *#stdoutChunks() {
340
- for await (const chunk of this.child.stdout)
341
- yield String(chunk);
403
+ try {
404
+ for await (const chunk of this.child.stdout)
405
+ yield String(chunk);
406
+ }
407
+ catch (error) {
408
+ if (!this.#droppedPipes)
409
+ throw error;
410
+ }
342
411
  }
343
412
  }
344
413
  /**
@@ -413,7 +482,13 @@ export class MspHandshake {
413
482
  #transport;
414
483
  #started = false;
415
484
  #answered = false;
485
+ #refuseDeclaredBreaking;
486
+ #signal;
487
+ #onAbort = () => void this.close().catch(() => undefined);
416
488
  constructor(options) {
489
+ // A handshake cancelled before it starts never starts a host to kill.
490
+ if (options.signal?.aborted)
491
+ throw abortError(options.signal.reason);
417
492
  this.child = MuseServeChild.spawn({
418
493
  museBin: options.command,
419
494
  ...(options.args === undefined ? {} : { args: options.args }),
@@ -432,6 +507,9 @@ export class MspHandshake {
432
507
  // this they ended the host's input while a just-accepted frame was still
433
508
  // queued on a microtask (PR #22819 round 4).
434
509
  this.#transport[adoptFlushSource](() => this.#connection[submissionTail]());
510
+ this.#refuseDeclaredBreaking = options.refuseDeclaredBreakingSchema === true;
511
+ this.#signal = options.signal;
512
+ this.#signal?.addEventListener("abort", this.#onAbort, { once: true });
435
513
  }
436
514
  get exited() {
437
515
  return this.#transport.exited;
@@ -446,6 +524,7 @@ export class MspHandshake {
446
524
  this.#connection.onProtocolError(handler);
447
525
  }
448
526
  async close() {
527
+ this.#signal?.removeEventListener("abort", this.#onAbort);
449
528
  await this.#connection.close();
450
529
  return await this.#transport.exited;
451
530
  }
@@ -454,9 +533,31 @@ export class MspHandshake {
454
533
  return this.#answered;
455
534
  }
456
535
  async initialize(params) {
536
+ // Checked here, not in the try: a refused second call must leave the
537
+ // first call's abort listener in place.
457
538
  if (this.#started)
458
539
  throw new ProtocolError("initialize may be sent only once per connection");
459
540
  this.#started = true;
541
+ const signal = this.#signal;
542
+ try {
543
+ const spawned = await this.#initialize(params);
544
+ if (!signal?.aborted)
545
+ return spawned;
546
+ }
547
+ catch (error) {
548
+ if (!signal?.aborted)
549
+ throw error;
550
+ }
551
+ finally {
552
+ // Settled either way: a later abort must not close anything.
553
+ signal?.removeEventListener("abort", this.#onAbort);
554
+ }
555
+ // Aborted before the handshake completed: the abort listener already
556
+ // started the shutdown ladder; reject only once the host is gone.
557
+ await this.close().catch(() => undefined);
558
+ throw abortError(signal?.reason);
559
+ }
560
+ async #initialize(params) {
460
561
  const { result: raw, line } = await this.#connection[requestWithFrame]("initialize", params);
461
562
  this.#answered = true;
462
563
  const result = raw;
@@ -466,7 +567,31 @@ export class MspHandshake {
466
567
  // and the facade tells the two apart by it (#49912, #50588 review).
467
568
  throw new ProtocolError("initialize result has no schema fingerprint", line);
468
569
  }
469
- const fingerprintWarning = checkServedFingerprint(result.schema.fingerprint);
570
+ const rawEpoch = result.schema.compatibilityEpoch;
571
+ const wellFormed = isWellFormedEpoch(rawEpoch);
572
+ if (!wellFormed && this.#refuseDeclaredBreaking) {
573
+ // The member is an optional unsigned integer (FR-22936-2). With the
574
+ // refusal on, the tier it asks for cannot be read from this answer, so
575
+ // the arm fails closed like a result with no fingerprint (FR-22936-8).
576
+ throw new ProtocolError("initialize result has a schema compatibilityEpoch that is not a non-negative integer " +
577
+ "(FR-22936-8); the host is not a conforming MSP server: point `museBin` at a current " +
578
+ "`muse` build or reinstall it", line);
579
+ }
580
+ // With the refusal off a malformed member is read as absent (FR-22936-8):
581
+ // the published behaviour does not change until the owner enables the
582
+ // setting (ADR 22936 D3). The classifier applies that reading itself, so
583
+ // `classifyServedSchema(initializeResult.schema)` reports this same tier.
584
+ const fingerprintWarning = classifyServedSchema({
585
+ fingerprint: result.schema.fingerprint,
586
+ compatibilityEpoch: rawEpoch,
587
+ });
588
+ if (this.#refuseDeclaredBreaking && fingerprintWarning?.tier === "declaredBreaking") {
589
+ // ADR 22936 D3: refuse at connect. The host is closed first (stdin EOF,
590
+ // then the usual shutdown ladder) so a refusal orphans nothing, and
591
+ // `initialized` is never sent: the host saw a handshake that ended.
592
+ await this.close().catch(() => undefined);
593
+ throw new SchemaCompatibilityError(fingerprintWarning);
594
+ }
470
595
  this.#connection.notify("initialized");
471
596
  await this.#connection.flush();
472
597
  return new SpawnedMspConnection(this.#connection, this.#transport, this.child, result, fingerprintWarning);
@@ -0,0 +1,49 @@
1
+ /**
2
+ * The types a typed `Connection` checks calls against (FR-100032-3).
3
+ *
4
+ * Every type here is computed from the generated stable method → type maps,
5
+ * so no params or result shape is restated by hand and none can drift from
6
+ * the schema. Internal: the package does not export these helpers.
7
+ */
8
+ import type { MspMethodMap, MspNotificationMap } from "../msp.js";
9
+ /** Every client-to-server method the stable map names. */
10
+ export type MethodName = keyof MspMethodMap & string;
11
+ /** A method's `params` type; `undefined` for a method that takes none. */
12
+ export type MethodParams<M extends MethodName> = MspMethodMap[M] extends {
13
+ params: infer P;
14
+ } ? P : never;
15
+ /** A method's `result` type. */
16
+ export type MethodResult<M extends MethodName> = MspMethodMap[M] extends {
17
+ result: infer R;
18
+ } ? R : never;
19
+ /**
20
+ * What a typed `request()`/`command()` resolves with: the method's result
21
+ * type, still open to members a newer host adds (the wire evolves
22
+ * additively), so it also stays assignable where `Record<string, unknown>`
23
+ * was expected before these types existed.
24
+ */
25
+ export type WireResult<M extends MethodName> = MethodResult<M> & Record<string, unknown>;
26
+ /**
27
+ * The params a caller passes to `command()`: the method's params without
28
+ * `commandId`, which the connection mints (INV-013).
29
+ */
30
+ export type CommandParams<M extends MethodName> = MethodParams<M> extends infer P ? (P extends object ? Omit<P, "commandId"> : Record<string, never>) : never;
31
+ /**
32
+ * The trailing `params` argument of a typed call: absent for a method that
33
+ * takes none, optional when every member is optional, required otherwise.
34
+ */
35
+ export type ParamsArgument<P> = [P] extends [undefined] ? [] : Record<string, never> extends P ? [params?: P] : [params: P];
36
+ /**
37
+ * Every notification the stable map names. The map also lists the two
38
+ * client-sent ones (`initialized`, `userInput/engaged`); a listener on either
39
+ * compiles but never runs, since the host does not send them.
40
+ */
41
+ export type NotificationName = keyof MspNotificationMap & string;
42
+ /** A notification's `params` type; `undefined` for one that carries none. */
43
+ export type NotificationParams<M extends NotificationName> = MspNotificationMap[M];
44
+ /**
45
+ * A method name the given names do NOT include. A listed method never
46
+ * matches, so the untyped fallback cannot accept a mistyped call to a typed
47
+ * method.
48
+ */
49
+ export type UnlistedMethod<Names extends string, M extends string> = M extends Names ? never : M;
@@ -0,0 +1,8 @@
1
+ /**
2
+ * The types a typed `Connection` checks calls against (FR-100032-3).
3
+ *
4
+ * Every type here is computed from the generated stable method → type maps,
5
+ * so no params or result shape is restated by hand and none can drift from
6
+ * the schema. Internal: the package does not export these helpers.
7
+ */
8
+ export {};
@@ -302,7 +302,7 @@ export class ApprovalRouter {
302
302
  const ack = await connection.command("approval/decide", decideParams);
303
303
  // A `terminal: true` ack closed the WHOLE approval; remember it so the
304
304
  // trailing stale-frontier update #37538 permits cannot re-prompt.
305
- if (ack["terminal"] === true)
305
+ if (ack.terminal === true)
306
306
  this.#terminalApprovals.add(approvalId);
307
307
  }
308
308
  catch (error) {
@@ -36,13 +36,14 @@
36
36
  * it is forwarded (or explicitly allow-listed as unforwardable).
37
37
  */
38
38
  import type { CommandOptions, Connection, ProtocolErrorHandler } from "../connection/connection.js";
39
+ import type { CommandParams, MethodName, MethodParams, ParamsArgument, UnlistedMethod, WireResult } from "../connection/surface.js";
39
40
  import type { DeepReadonly } from "../fold/session-fold.js";
40
41
  import type { ExitClassification, MuseServeChildOptions, SpawnedMspConnection } from "../connection/spawn.js";
41
42
  import type { FoldExtension } from "../fold/extension.js";
42
43
  import type { SessionDurabilityProfile } from "./host-death.js";
43
44
  import type { ApprovalFailureHandler, ApprovalHandler } from "./approval.js";
44
45
  import { Session } from "./session.js";
45
- import type { InitializeParams, InitializeResult, Notification, ModelListParams, ModelListResult, MspMethod, SessionListParams, SessionListResult, SessionResumeParams, SessionStartParams, UsageReadResult } from "../msp.js";
46
+ import type { InitializeParams, InitializeResult, Notification, ModelListParams, ModelListResult, SessionListParams, SessionListResult, SessionResumeParams, SessionStartParams, UsageReadResult } from "../msp.js";
46
47
  /**
47
48
  * Hears one server notification. Read-only: the frame is the one the session
48
49
  * folds, possibly after the listener runs.
@@ -63,14 +64,10 @@ export type NotificationFailureHandler = (error: unknown, notification: DeepRead
63
64
  */
64
65
  declare const FACADE_OWNED_METHODS: readonly ["initialize", "session/start", "session/resume", "turn/start", "turn/steer", "turn/unqueue", "approval/decide", "userInput/answer", "view/page", "view/subscribe", "view/unsubscribe"];
65
66
  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);
67
+ /** The methods `command`/`request` type from the surface's map: every listed one the facade does not own. */
68
+ type RawMethodName = Exclude<MethodName, FacadeOwnedMethod>;
69
+ /** `M` itself when no member of it is facade-owned, else `never`. */
70
+ type NotFacadeOwned<M extends string> = M & ([Extract<M, FacadeOwnedMethod>] extends [never] ? unknown : never);
74
71
  /**
75
72
  * Caller-facing options for `session/start` (tdd SS2.5.1).
76
73
  *
@@ -169,6 +166,26 @@ export interface MuseClientSpawnOptions {
169
166
  * command) when no `muse` is on `PATH`.
170
167
  */
171
168
  readonly spawnFn?: MuseServeChildOptions["spawnFn"];
169
+ /**
170
+ * See `SpawnMspConnectionOptions.refuseDeclaredBreakingSchema` (ADR 22936
171
+ * D3, default off): refuse the declared-breaking schema tier at connect
172
+ * with a `SchemaCompatibilityError`, the host closed. Off, the connection
173
+ * goes ahead and nothing here warns: read the tier with
174
+ * `classifyServedSchema(client.initializeResult.schema)`.
175
+ */
176
+ readonly refuseDeclaredBreakingSchema?: boolean;
177
+ /**
178
+ * Cancels startup, e.g. `AbortSignal.timeout(ms)`. Aborting before `spawn`
179
+ * resolves closes the host through the usual shutdown ladder, then rejects
180
+ * with an `AbortError` whose `cause` is `signal.reason`; an already-aborted
181
+ * signal spawns nothing. Aborting after `spawn` resolved does nothing: use
182
+ * `close()`. The rejection waits for the host to exit: a host that ignores
183
+ * stdin EOF takes up to `shutdownTimeoutMs` plus the 2 s SIGTERM grace.
184
+ * Unlike `Session.run`, which rejects with `signal.reason`, this
185
+ * follows Node's `child_process.spawn`: check `error.name === "AbortError"`
186
+ * and read `error.cause`.
187
+ */
188
+ readonly signal?: AbortSignal;
172
189
  /**
173
190
  * Fold extensions (FR-97527-3): connection-level state plus every
174
191
  * session this client opens. See `MuseClientOptions.extensions`.
@@ -198,6 +215,9 @@ export declare class MuseClient {
198
215
  * Rejects with {@link MuseHostDiscoveryError} before starting anything when
199
216
  * `museBin` is omitted and no executable `muse` is on `PATH`.
200
217
  *
218
+ * Rejects with an `AbortError` (`cause`: `signal.reason`) when `signal`
219
+ * aborts before the handshake completes, once the host has exited.
220
+ *
201
221
  * Rejects with {@link MuseHostStartError} when the host is lost before the
202
222
  * handshake completes (the binary could not be spawned, or the process
203
223
  * ended first — exit code or signal plus the bounded stderr tail;
@@ -205,7 +225,10 @@ export declare class MuseClient {
205
225
  * that answers with a reply the SDK refuses keeps its own error: an
206
226
  * `MspError` for an SS1.6 refusal, or a `ProtocolError` (with the whole
207
227
  * refused frame on `line`) for a reply the SDK cannot use, such as one with
208
- * no schema fingerprint.
228
+ * no schema fingerprint. With `refuseDeclaredBreakingSchema`, a host whose
229
+ * schema identity is a declared non-additive advance from this SDK's pin
230
+ * is refused with a `SchemaCompatibilityError` (ADR 22936 D3), the host
231
+ * closed.
209
232
  */
210
233
  static spawn(options: MuseClientSpawnOptions): Promise<MuseClient>;
211
234
  /**
@@ -293,7 +316,9 @@ export declare class MuseClient {
293
316
  * not wrap, experimental ones included, through the
294
317
  * same `Connection.command()` the verbs use: the connection mints the
295
318
  * `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
319
+ * checks the ack's echo. `options` are that seam's own. A stable method
320
+ * takes and returns its generated map types, without `commandId`; any other
321
+ * name stays sendable untyped. An experimental
297
322
  * method needs a client spawned with `capabilities: { experimentalApi: true }`
298
323
  * (otherwise the host refuses it with an `MspError` of kind
299
324
  * `experimentalRequired`, code -32601) and may change without notice.
@@ -305,22 +330,50 @@ export declare class MuseClient {
305
330
  * exit it causes reaches your sessions as a host death; `close()` is the
306
331
  * orderly stop. Frames
307
332
  * 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.
333
+ * inbound pump; this sends and returns the ack, nothing more.
311
334
  *
312
335
  * Each call keeps one fixed-size fingerprint for the connection's lifetime
313
336
  * (FR-45137-1), so prefer `request` for a query you poll.
314
337
  */
315
- command<M extends RawMethodName>(method: RawMethod<M>, params: Record<string, unknown>, options?: CommandOptions): Promise<Record<string, unknown>>;
338
+ command<M extends RawMethodName>(method: M, params: CommandParams<M>, options?: CommandOptions): Promise<WireResult<M>>;
339
+ command<M extends string>(method: UnlistedMethod<MethodName, M>, params: Record<string, unknown>, options?: CommandOptions): Promise<Record<string, unknown>>;
340
+ /**
341
+ * @deprecated Loosely typed params for a listed method: pass the method's
342
+ * generated params type. This overload goes away in a later release
343
+ * (ADR 25304 D3's deprecation path).
344
+ */
345
+ command(method: RawMethodName, params: Record<string, unknown>, options?: CommandOptions): Promise<Record<string, unknown>>;
346
+ /**
347
+ * @deprecated A union mixing listed and unlisted names cannot be checked;
348
+ * it compiles untyped for one release and goes away with the loose
349
+ * overload above. A facade-owned member is still refused, and a generic
350
+ * `M extends string` name does not compile here. Widen the name to
351
+ * `string` (`method as string`) to keep sending it untyped.
352
+ */
353
+ command<M extends string>(method: NotFacadeOwned<M>, params: Record<string, unknown>, options?: CommandOptions): Promise<Record<string, unknown>>;
316
354
  /**
317
355
  * Send a wire request directly (FR-79107-2), typically a query the facade
318
356
  * does not wrap, experimental ones included, through `Connection.request()`:
319
357
  * no `commandId`, no retry, and omitted `params` stay off the frame.
320
358
  * Refuses the same facade-owned methods as `command`, the same way, and
321
- * needs the same `experimentalApi` opt-in for an experimental method.
359
+ * needs the same `experimentalApi` opt-in for an experimental method. Typed
360
+ * like `command`: a stable method takes and returns its map types, any
361
+ * other name stays sendable untyped.
362
+ */
363
+ request<M extends RawMethodName>(method: M, ...params: ParamsArgument<MethodParams<M>>): Promise<WireResult<M>>;
364
+ request<M extends string>(method: UnlistedMethod<MethodName, M>, params?: Record<string, unknown>): Promise<Record<string, unknown>>;
365
+ /**
366
+ * @deprecated Loosely typed params for a listed method: pass the method's
367
+ * generated params type. This overload goes away in a later release
368
+ * (ADR 25304 D3's deprecation path).
369
+ */
370
+ request(method: RawMethodName, params?: Record<string, unknown>): Promise<Record<string, unknown>>;
371
+ /**
372
+ * @deprecated A mixed-union method name cannot be checked; it compiles
373
+ * untyped for one release, as on `command`. Widen the name to `string`
374
+ * (`method as string`) to keep sending it untyped.
322
375
  */
323
- request<M extends RawMethodName>(method: RawMethod<M>, params?: Record<string, unknown>): Promise<Record<string, unknown>>;
376
+ request<M extends string>(method: NotFacadeOwned<M>, params?: Record<string, unknown>): Promise<Record<string, unknown>>;
324
377
  /**
325
378
  * Shut the host down in an orderly way (SS2.1.2); the shutdown this causes
326
379
  * is not reported to your sessions as a host death.