@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.
@@ -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`, and `turn/foregroundCompleted`;
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)
@@ -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