@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
|
@@ -14,7 +14,8 @@
|
|
|
14
14
|
*
|
|
15
15
|
* - the TURN LIFECYCLE — `turn/started`, `turn/completed`, `turn/retracted`,
|
|
16
16
|
* `turn/unqueued`, and the non-terminal `turn/retryScheduled`,
|
|
17
|
-
* `turn/modelRetryScheduled`,
|
|
17
|
+
* `turn/modelRetryScheduled`, `turn/modelAttemptStarted`, and
|
|
18
|
+
* `turn/foregroundCompleted`;
|
|
18
19
|
* - the APPROVAL and USER-INPUT view events as fold INPUTS — the pending
|
|
19
20
|
* sets and their first durable terminal. The decision flow (choosing and
|
|
20
21
|
* sending a resolution) is the facade's, not the fold's;
|
|
@@ -27,6 +28,7 @@
|
|
|
27
28
|
* unrecognized `TurnTerminal` is kept verbatim, and a second resolution never
|
|
28
29
|
* displaces the first durable one.
|
|
29
30
|
*/
|
|
31
|
+
import { fireExtensions } from "./extension.js";
|
|
30
32
|
import { ItemStore } from "./item-store.js";
|
|
31
33
|
import { SessionStateStore } from "./state-store.js";
|
|
32
34
|
/**
|
|
@@ -36,6 +38,10 @@ import { SessionStateStore } from "./state-store.js";
|
|
|
36
38
|
export class SessionFold {
|
|
37
39
|
#itemStore = new ItemStore();
|
|
38
40
|
#sessionStateStore = new SessionStateStore();
|
|
41
|
+
#extensions;
|
|
42
|
+
constructor(extensions = []) {
|
|
43
|
+
this.#extensions = extensions;
|
|
44
|
+
}
|
|
39
45
|
/** Items, snapshot-only: the mutators are `apply()`'s, not the consumer's. */
|
|
40
46
|
get items() {
|
|
41
47
|
return this.#itemStore;
|
|
@@ -75,6 +81,8 @@ export class SessionFold {
|
|
|
75
81
|
#pendingApprovals = new Map();
|
|
76
82
|
#resolvedApprovals = new Map();
|
|
77
83
|
#pendingUserInputs = new Map();
|
|
84
|
+
/** Pending prompt ids by turn, so retiring a turn's prompts costs that turn's count, not every pending prompt. */
|
|
85
|
+
#pendingUserInputIdsByTurn = new Map();
|
|
78
86
|
#settledUserInputs = new Map();
|
|
79
87
|
#activeTurnId;
|
|
80
88
|
#pendingGap;
|
|
@@ -148,6 +156,12 @@ export class SessionFold {
|
|
|
148
156
|
if (event.params === null || typeof event.params !== "object" || Array.isArray(event.params)) {
|
|
149
157
|
return { kind: "ignoredMissingParams", method: event.method };
|
|
150
158
|
}
|
|
159
|
+
// FR-97527-3: extensions registered for this frame's method run first,
|
|
160
|
+
// in registration order — for known methods they observe alongside the
|
|
161
|
+
// stable arm below (experimental fields ride here); for unknown methods
|
|
162
|
+
// they are the only handler. Inside this one apply path, never a second
|
|
163
|
+
// pump, so gap buffering and resume behave exactly as today.
|
|
164
|
+
const extensionsFired = fireExtensions(this.#extensions, event.method, event.params);
|
|
151
165
|
const typed = event;
|
|
152
166
|
switch (typed.method) {
|
|
153
167
|
case "item/started":
|
|
@@ -171,6 +185,8 @@ export class SessionFold {
|
|
|
171
185
|
return this.#turnRetryScheduled(typed.params);
|
|
172
186
|
case "turn/modelRetryScheduled":
|
|
173
187
|
return this.#turnModelRetryScheduled(typed.params);
|
|
188
|
+
case "turn/modelAttemptStarted":
|
|
189
|
+
return this.#turnModelAttemptStarted(typed.params);
|
|
174
190
|
case "turn/foregroundCompleted":
|
|
175
191
|
return this.#turnForegroundCompleted(typed.params);
|
|
176
192
|
case "approval/requested":
|
|
@@ -208,6 +224,8 @@ export class SessionFold {
|
|
|
208
224
|
};
|
|
209
225
|
default: {
|
|
210
226
|
const unrecognized = event;
|
|
227
|
+
if (extensionsFired > 0)
|
|
228
|
+
return { kind: "extension", method: unrecognized.method };
|
|
211
229
|
return { kind: "ignoredUnrecognizedMethod", method: unrecognized.method };
|
|
212
230
|
}
|
|
213
231
|
}
|
|
@@ -285,10 +303,14 @@ export class SessionFold {
|
|
|
285
303
|
// Same for the provider-backoff hint: a finished turn is not waiting
|
|
286
304
|
// out a backoff (tdd SS4.5.1).
|
|
287
305
|
turn.modelRetryScheduled = undefined;
|
|
306
|
+
// Same for the attempt hint: a finished turn's model is not working
|
|
307
|
+
// (tdd SS4.5.1).
|
|
308
|
+
turn.modelAttemptStarted = undefined;
|
|
288
309
|
// Same for the foreground hint: a finished turn is not background-waiting
|
|
289
310
|
// (tdd SS4.5.12).
|
|
290
311
|
turn.foregroundCompleted = undefined;
|
|
291
312
|
this.#clearActive(params.turnId);
|
|
313
|
+
this.#retirePendingUserInputsFor(params.turnId);
|
|
292
314
|
return { kind: "turn", turnId: params.turnId, state: turn.state };
|
|
293
315
|
}
|
|
294
316
|
#turnRetracted(params) {
|
|
@@ -315,6 +337,7 @@ export class SessionFold {
|
|
|
315
337
|
// `item/updated` with `retracted: true`, which the item half folds.
|
|
316
338
|
turn.state = "retracted";
|
|
317
339
|
this.#clearActive(params.turnId);
|
|
340
|
+
this.#retirePendingUserInputsFor(params.turnId);
|
|
318
341
|
return { kind: "turn", turnId: params.turnId, state: turn.state };
|
|
319
342
|
}
|
|
320
343
|
#turnUnqueued(params) {
|
|
@@ -326,6 +349,7 @@ export class SessionFold {
|
|
|
326
349
|
turn.commandId = params.commandId;
|
|
327
350
|
turn.state = "unqueued";
|
|
328
351
|
this.#clearActive(params.turnId);
|
|
352
|
+
this.#retirePendingUserInputsFor(params.turnId);
|
|
329
353
|
return { kind: "turn", turnId: params.turnId, state: turn.state };
|
|
330
354
|
}
|
|
331
355
|
#turnRetryScheduled(params) {
|
|
@@ -355,6 +379,18 @@ export class SessionFold {
|
|
|
355
379
|
turn.modelRetryScheduled = params;
|
|
356
380
|
return { kind: "turn", turnId: params.turnId, state: turn.state };
|
|
357
381
|
}
|
|
382
|
+
#turnModelAttemptStarted(params) {
|
|
383
|
+
// Non-terminal by contract: it never resolves a turn-wait (tdd SS4.5.1).
|
|
384
|
+
const turn = this.#turnFor(params.turnId);
|
|
385
|
+
// …but it is still a turn frame, so it takes the same redelivery guard
|
|
386
|
+
// as the retry hint: a replayed page must not re-plant the attempt hint
|
|
387
|
+
// on a turn that already left `running`.
|
|
388
|
+
if (turn.state !== "running") {
|
|
389
|
+
return { kind: "ignoredStaleFrame", method: "turn/modelAttemptStarted", id: params.turnId };
|
|
390
|
+
}
|
|
391
|
+
turn.modelAttemptStarted = params;
|
|
392
|
+
return { kind: "turn", turnId: params.turnId, state: turn.state };
|
|
393
|
+
}
|
|
358
394
|
#turnForegroundCompleted(params) {
|
|
359
395
|
// Non-terminal by contract: it never resolves a turn-wait (tdd SS4.5.12).
|
|
360
396
|
const turn = this.#turnFor(params.turnId);
|
|
@@ -379,6 +415,39 @@ export class SessionFold {
|
|
|
379
415
|
if (this.#activeTurnId === turnId)
|
|
380
416
|
this.#activeTurnId = undefined;
|
|
381
417
|
}
|
|
418
|
+
// A prompt listed while its turn ran retires when that turn leaves
|
|
419
|
+
// `running`: no answer can settle it afterwards, so keeping it listed
|
|
420
|
+
// pends it forever (the reported started→requested→completed order).
|
|
421
|
+
// Retiring records no settlement — the prompt was never answered.
|
|
422
|
+
// Cost is the ending turn's own prompt count via the by-turn index,
|
|
423
|
+
// never a scan over every pending prompt.
|
|
424
|
+
#retirePendingUserInputsFor(turnId) {
|
|
425
|
+
const ids = this.#pendingUserInputIdsByTurn.get(turnId);
|
|
426
|
+
if (ids === undefined)
|
|
427
|
+
return;
|
|
428
|
+
for (const userInputId of ids)
|
|
429
|
+
this.#pendingUserInputs.delete(userInputId);
|
|
430
|
+
this.#pendingUserInputIdsByTurn.delete(turnId);
|
|
431
|
+
}
|
|
432
|
+
#indexPendingUserInput(params) {
|
|
433
|
+
let ids = this.#pendingUserInputIdsByTurn.get(params.turnId);
|
|
434
|
+
if (ids === undefined) {
|
|
435
|
+
ids = new Set();
|
|
436
|
+
this.#pendingUserInputIdsByTurn.set(params.turnId, ids);
|
|
437
|
+
}
|
|
438
|
+
ids.add(params.userInputId);
|
|
439
|
+
}
|
|
440
|
+
#unindexPendingUserInput(userInputId) {
|
|
441
|
+
const params = this.#pendingUserInputs.get(userInputId);
|
|
442
|
+
if (params === undefined)
|
|
443
|
+
return;
|
|
444
|
+
const ids = this.#pendingUserInputIdsByTurn.get(params.turnId);
|
|
445
|
+
if (ids === undefined)
|
|
446
|
+
return;
|
|
447
|
+
ids.delete(userInputId);
|
|
448
|
+
if (ids.size === 0)
|
|
449
|
+
this.#pendingUserInputIdsByTurn.delete(params.turnId);
|
|
450
|
+
}
|
|
382
451
|
static #turnSnapshot(turn) {
|
|
383
452
|
return {
|
|
384
453
|
turnId: turn.turnId,
|
|
@@ -390,6 +459,9 @@ export class SessionFold {
|
|
|
390
459
|
...(turn.modelRetryScheduled !== undefined
|
|
391
460
|
? { modelRetryScheduled: turn.modelRetryScheduled }
|
|
392
461
|
: {}),
|
|
462
|
+
...(turn.modelAttemptStarted !== undefined
|
|
463
|
+
? { modelAttemptStarted: turn.modelAttemptStarted }
|
|
464
|
+
: {}),
|
|
393
465
|
...(turn.foregroundCompleted !== undefined
|
|
394
466
|
? { foregroundCompleted: turn.foregroundCompleted }
|
|
395
467
|
: {}),
|
|
@@ -476,10 +548,23 @@ export class SessionFold {
|
|
|
476
548
|
if (this.#settledUserInputs.has(params.userInputId)) {
|
|
477
549
|
return { kind: "ignoredStaleFrame", method: "userInput/requested", id: params.userInputId };
|
|
478
550
|
}
|
|
551
|
+
// A prompt for a turn this fold has already seen leave `running` is an
|
|
552
|
+
// orphan: no answer can settle it, so listing it would pend forever and
|
|
553
|
+
// an answer attempt would only bounce off the host. Guarded to KNOWN
|
|
554
|
+
// dead turns only — a prompt naming a turn the fold has never seen
|
|
555
|
+
// (a fresh resume re-sending a still-open question) still lists, since
|
|
556
|
+
// this fold cannot prove that turn dead.
|
|
557
|
+
const turn = this.#turns.get(params.turnId);
|
|
558
|
+
if (turn !== undefined && turn.state !== "running") {
|
|
559
|
+
return { kind: "ignoredStaleFrame", method: "userInput/requested", id: params.userInputId };
|
|
560
|
+
}
|
|
561
|
+
this.#unindexPendingUserInput(params.userInputId);
|
|
479
562
|
this.#pendingUserInputs.set(params.userInputId, params);
|
|
563
|
+
this.#indexPendingUserInput(params);
|
|
480
564
|
return { kind: "userInputPending", userInputId: params.userInputId };
|
|
481
565
|
}
|
|
482
566
|
#userInputSettled(params) {
|
|
567
|
+
this.#unindexPendingUserInput(params.userInputId);
|
|
483
568
|
this.#pendingUserInputs.delete(params.userInputId);
|
|
484
569
|
const firstSettlement = !this.#settledUserInputs.has(params.userInputId);
|
|
485
570
|
if (firstSettlement)
|
package/dist/src/index.d.ts
CHANGED
|
@@ -32,6 +32,7 @@ export { ItemStore } from "./fold/item-store.js";
|
|
|
32
32
|
export type { DeltaApplyOutcome, ItemApplyOutcome, RevisionedItem, TerminalUnknownItemAnnotation, } from "./fold/item-store.js";
|
|
33
33
|
export { SessionStateStore } from "./fold/state-store.js";
|
|
34
34
|
export type { StateApplyOutcome, StateValue } from "./fold/state-store.js";
|
|
35
|
+
export type { FoldExtension } from "./fold/extension.js";
|
|
35
36
|
export { SessionFold } from "./fold/session-fold.js";
|
|
36
37
|
export type {
|
|
37
38
|
/**
|
|
@@ -47,10 +48,10 @@ export { Connection, createUuidV7Mint, MspError, ProtocolError, } from "./connec
|
|
|
47
48
|
export type { CommandOptions, ConnectionOptions, DuplexTransport, NotificationHandler, ProtocolErrorHandler, ServerRequestHandler, } from "./connection/connection.js";
|
|
48
49
|
export { MspHandshake, MuseServeChild, SpawnedMspConnection, spawnMspConnection, } from "./connection/spawn.js";
|
|
49
50
|
export { MuseClient } from "./facade/client.js";
|
|
50
|
-
export type { MuseClientOptions, MuseClientSpawnOptions, ResumeSessionOptions, StartSessionOptions, } from "./facade/client.js";
|
|
51
|
+
export type { MuseClientOptions, MuseClientSpawnOptions, NotificationFailureHandler, NotificationObserver, ResumeSessionOptions, StartSessionOptions, } from "./facade/client.js";
|
|
51
52
|
export type { ExitClassification, MuseServeChildOptions, ProcessExit, SpawnMspConnectionOptions, } from "./connection/spawn.js";
|
|
52
53
|
export { DiscardedSessions } from "./facade/discarded.js";
|
|
53
|
-
export { MuseForeignSessionError, MuseGapFillError, MuseSessionDiscardedError, PermissionProfileNotApplied, } from "./errors.js";
|
|
54
|
+
export { MuseCapabilityNotGrantedError, MuseFacadeOwnedMethodError, MuseForeignSessionError, MuseGapFillError, MuseHostDiscoveryError, MuseSessionDiscardedError, PermissionProfileNotApplied, } from "./errors.js";
|
|
54
55
|
export type { GapFillFailureReason } from "./errors.js";
|
|
55
56
|
export type { GapFillFailureHandler } from "./facade/gap-fill.js";
|
|
56
57
|
export { MuseHostDiedError, readSessionDurability } from "./facade/host-death.js";
|
|
@@ -58,8 +59,9 @@ export { MuseHostStartError } from "./facade/host-start.js";
|
|
|
58
59
|
export type { HostStartFailure } from "./facade/host-start.js";
|
|
59
60
|
export type { AbnormalExit, HostDeathDischarge, HostDeathNotification, SessionDurabilityProfile, TransportEof, } from "./facade/host-death.js";
|
|
60
61
|
export { Session } from "./facade/session.js";
|
|
61
|
-
export type { PendingCommandView, SessionApplyOutcome, SessionApplyRefusal, SessionFoldView, SessionGapBuffered, SessionGapOverlap, SessionOpening, SessionOptions, } from "./facade/session.js";
|
|
62
|
+
export type { PendingCommandView, SessionApplyOutcome, SessionApplyRefusal, SessionEvent, SessionEventsOptions, SessionFoldView, SessionGapBuffered, SessionGapOverlap, SessionOpening, SessionOptions, SubagentReasonOptions, ViewFrame, } from "./facade/session.js";
|
|
62
63
|
export type { ApprovalDecisionInput, ApprovalFailure, ApprovalFailureHandler, ApprovalHandler, } from "./facade/approval.js";
|
|
63
|
-
export type { SendUserTurnOptions } from "./facade/turn-submit.js";
|
|
64
|
+
export type { SendUserTurnOptions, SteerTurnOptions } from "./facade/turn-submit.js";
|
|
65
|
+
export type { RunOptions, RunResult } from "./facade/run.js";
|
|
64
66
|
export { isLaunchFailure } from "./facade/turn-handle.js";
|
|
65
|
-
export type { FoldedItem, Turn, TurnOutcome } from "./facade/turn-handle.js";
|
|
67
|
+
export type { FoldedItem, InterruptTurnOptions, Turn, TurnOutcome, TurnUnqueueOutcome, } from "./facade/turn-handle.js";
|
package/dist/src/index.js
CHANGED
|
@@ -40,7 +40,7 @@ export { MuseClient } from "./facade/client.js";
|
|
|
40
40
|
// none — the cross-client sharing knob was declined (Constitution XI; see the
|
|
41
41
|
// constructor note in `facade/client.ts`).
|
|
42
42
|
export { DiscardedSessions } from "./facade/discarded.js";
|
|
43
|
-
export { MuseForeignSessionError, MuseGapFillError, MuseSessionDiscardedError, PermissionProfileNotApplied, } from "./errors.js";
|
|
43
|
+
export { MuseCapabilityNotGrantedError, MuseFacadeOwnedMethodError, MuseForeignSessionError, MuseGapFillError, MuseHostDiscoveryError, MuseSessionDiscardedError, PermissionProfileNotApplied, } from "./errors.js";
|
|
44
44
|
// Trimmed deliberately (Constitution XI): `isAbnormalHostDeath`,
|
|
45
45
|
// `isItemInProgress`, and `survivesHostDeath` are `Session`'s own internals
|
|
46
46
|
// with no consumer, and a barrel export would freeze them into `@muse-code/sdk`'s
|