@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.
- package/README.md +54 -5
- package/dist/src/connection/connection.d.ts +67 -7
- package/dist/src/connection/connection.js +68 -11
- package/dist/src/connection/spawn.d.ts +26 -0
- package/dist/src/connection/spawn.js +156 -31
- package/dist/src/connection/surface.d.ts +49 -0
- package/dist/src/connection/surface.js +8 -0
- package/dist/src/facade/approval.js +1 -1
- package/dist/src/facade/client.d.ts +70 -17
- package/dist/src/facade/client.js +198 -62
- package/dist/src/facade/gap-fill.d.ts +2 -0
- package/dist/src/facade/gap-fill.js +11 -2
- package/dist/src/facade/session.d.ts +77 -3
- package/dist/src/facade/session.js +344 -16
- package/dist/src/fingerprint.d.ts +79 -4
- package/dist/src/fingerprint.js +110 -11
- package/dist/src/fingerprint.stamped.d.ts +2 -1
- package/dist/src/fingerprint.stamped.js +2 -1
- package/dist/src/index.d.ts +4 -4
- package/dist/src/index.js +1 -1
- package/dist/src/msp.d.ts +278 -2
- package/package.json +1 -1
|
@@ -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 {
|
|
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
|
-
|
|
273
|
-
|
|
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
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
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
|
-
/**
|
|
308
|
-
|
|
309
|
-
|
|
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
|
-
|
|
341
|
-
|
|
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
|
|
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
|
|
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,
|
|
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
|
-
|
|
68
|
-
|
|
69
|
-
|
|
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.
|
|
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.
|
|
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:
|
|
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
|
|
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.
|