@muse-code/sdk 1.4.15 → 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.
@@ -19,6 +19,7 @@
19
19
  * composition every earlier arm builds — stays valid and refuses the submit
20
20
  * verbs loudly rather than dropping a caller's input on the floor.
21
21
  */
22
+ var _a;
22
23
  import { SessionFold } from "../fold/session-fold.js";
23
24
  import { PendingCommandSet } from "../pending/pending-command-set.js";
24
25
  import { ProtocolError } from "../connection/connection.js";
@@ -27,7 +28,7 @@ import { TurnSubmitter } from "./turn-submit.js";
27
28
  import { GapFiller } from "./gap-fill.js";
28
29
  import { isAbnormalHostDeath, isItemInProgress, MuseHostDiedError, survivesHostDeath, } from "./host-death.js";
29
30
  import { MuseForeignSessionError, MuseSessionDiscardedError } from "../errors.js";
30
- import { TurnHandle } from "./turn-handle.js";
31
+ import { PushStream, TurnHandle } from "./turn-handle.js";
31
32
  import { runTurn } from "./run.js";
32
33
  /**
33
34
  * True when a routed `approval/request` carries every member the approval
@@ -97,7 +98,7 @@ export class Session {
97
98
  #approvals;
98
99
  /** The FR-020 splice-fill (`gap-fill.ts`). */
99
100
  #gaps;
100
- #fold = new SessionFold();
101
+ #fold;
101
102
  /**
102
103
  * Approvals the fold holds a durable terminal for. Read by a re-sent
103
104
  * `approval/request`, which skips the fold, so it authors nothing for an
@@ -120,6 +121,8 @@ export class Session {
120
121
  * durable `item/completed` always lands the item.
121
122
  */
122
123
  #unattributedDeltas = new Map();
124
+ /** The live `events()` streams, fed by every folded event. */
125
+ #eventStreams = new Set();
123
126
  /** Set through {@link pumpDropsApplyResults} by `MuseClient`. */
124
127
  #applyResultsDropped = false;
125
128
  /** This session's own `unqueue()` calls awaiting their ack, counted per turn id. */
@@ -177,6 +180,28 @@ export class Session {
177
180
  [pumpDropsApplyResults]() {
178
181
  this.#applyResultsDropped = true;
179
182
  }
183
+ /** Yield one folded event to every live `events()` stream. */
184
+ #emit(frame, outcome) {
185
+ if (this.#eventStreams.size === 0)
186
+ return;
187
+ const fold = outcome.fold;
188
+ // The item as of THIS event: the store keeps one object per revision, so
189
+ // a later revision folding before the consumer reads cannot change it.
190
+ const item = fold.kind === "item" && fold.outcome.kind !== "ignoredStaleRevision"
191
+ ? this.#fold.items.get(fold.outcome.itemId)
192
+ : undefined;
193
+ const event = item === undefined ? { frame, outcome } : { frame, item, outcome };
194
+ for (const stream of this.#eventStreams)
195
+ stream.push(event);
196
+ }
197
+ /**
198
+ * Fold one frame an SS4.8 fill splices in, and yield it. Its retirements
199
+ * and I/O settle on the gap frame's `io`, so the event carries none.
200
+ */
201
+ #spliced(frame, into) {
202
+ const fold = this.#foldAndRoute(frame, into);
203
+ this.#emit(frame, { fold, io: NO_IO, retirements: [] });
204
+ }
180
205
  /** @internal See {@link resendableUnqueue}: each call of the result sends the same reclaim. */
181
206
  [resendableUnqueue](turnId) {
182
207
  const commandId = this.#requireLiveConnection("unqueue").mintCommandId();
@@ -197,6 +222,7 @@ export class Session {
197
222
  constructor(options) {
198
223
  this.sessionId = options.sessionId;
199
224
  this.#durability = options.durability;
225
+ this.#fold = new SessionFold(options.extensions);
200
226
  this.#discarded = options.discarded;
201
227
  this.opening = options.opening;
202
228
  this.#pending = new PendingCommandSet(options.discarded === undefined
@@ -205,7 +231,7 @@ export class Session {
205
231
  this.#submit = new TurnSubmitter(options.sessionId, options.connection, this.#pending);
206
232
  this.#approvals = new ApprovalRouter(options.sessionId, options.connection);
207
233
  this.#gaps = new GapFiller({
208
- apply: (frame, into) => this.#foldAndRoute(frame, into),
234
+ apply: (frame, into) => this.#spliced(frame, into),
209
235
  connection: options.connection,
210
236
  discarded: () => this.#discharge?.kind === "discharged",
211
237
  fold: this.#fold,
@@ -240,6 +266,45 @@ export class Session {
240
266
  return this.#turns.size;
241
267
  }
242
268
  apply(event) {
269
+ const outcome = this.#applyLive(event);
270
+ // A frame held for a fill is yielded when the fill splices it in.
271
+ if (outcome.fold.kind !== "bufferedDuringGap")
272
+ this.#emit(event, outcome);
273
+ return outcome;
274
+ }
275
+ /**
276
+ * Every event this session folds from now on, with what it changed
277
+ * (FR-97336-1). Live from the call, never replayed: read `fold`, then call
278
+ * this in the same tick, and nothing is missed, including the events
279
+ * folded while `startSession`/`resumeSession` was in flight. Each folded
280
+ * event is yielded once, in arrival order; the events a gap fill splices in
281
+ * are yielded when applied, in order. Buffered like `turn.items()`, so a slow
282
+ * reader never holds folding up.
283
+ *
284
+ * `break`, `return()` or `options.signal` ends it. It finishes the way a
285
+ * turn's `items()` does when the host dies: it ends after an ephemeral
286
+ * host's death, and rejects with `MuseHostDiedError` after a durable one's,
287
+ * once the events it already buffered are read.
288
+ */
289
+ events(options = {}) {
290
+ const stream = new PushStream(() => {
291
+ this.#eventStreams.delete(stream);
292
+ options.signal?.removeEventListener("abort", onAbort);
293
+ });
294
+ const onAbort = () => void stream.return();
295
+ if (options.signal?.aborted === true)
296
+ stream.end();
297
+ else if (this.#deathError !== undefined)
298
+ stream.fail(this.#deathError);
299
+ else if (this.#discharge?.kind === "discharged")
300
+ stream.end();
301
+ else {
302
+ this.#eventStreams.add(stream);
303
+ options.signal?.addEventListener("abort", onAbort, { once: true });
304
+ }
305
+ return stream;
306
+ }
307
+ #applyLive(event) {
243
308
  // Only enforce when the frame actually NAMES a session. `ViewEvent`'s
244
309
  // members all declare `sessionId`, but a newer host's unknown notification
245
310
  // reaches this method at runtime and SS1.5.4 says it is tolerated
@@ -309,7 +374,7 @@ export class Session {
309
374
  }
310
375
  return {
311
376
  fold: outcome,
312
- io: Session.#settleIo(sink.tasks),
377
+ io: _a.#settleIo(sink.tasks),
313
378
  retirements: sink.retirements,
314
379
  };
315
380
  }
@@ -384,13 +449,17 @@ export class Session {
384
449
  // later be retired `terminalUnknown` by a discharge, which would be a
385
450
  // fabricated annotation about a command whose fate is known.
386
451
  const reclaimed = this.#pending.observedReclaim(known.params.commandId);
387
- if (reclaimed !== undefined) {
452
+ if (reclaimed === undefined)
453
+ break;
454
+ // FR-81734-1: under `MuseClient` this session's own in-flight unqueue
455
+ // for the turn is where it lands. Held INSTEAD of returned, so no
456
+ // outcome, live or spliced into a gap's `io`, carries it a second time.
457
+ if (this.#applyResultsDropped && this.#unqueuesInFlight.has(known.params.turnId)) {
458
+ this.#submit.forgetRetired([reclaimed]);
459
+ this.#heldReclaims.set(known.params.turnId, reclaimed);
460
+ }
461
+ else {
388
462
  retirements.push(reclaimed);
389
- // FR-81734-1: nobody reads this return under `MuseClient`, so this
390
- // session's own in-flight unqueue for the turn is where it can land.
391
- if (this.#applyResultsDropped && this.#unqueuesInFlight.has(known.params.turnId)) {
392
- this.#heldReclaims.set(known.params.turnId, reclaimed);
393
- }
394
463
  }
395
464
  break;
396
465
  }
@@ -571,6 +640,9 @@ export class Session {
571
640
  this.#deathError = died;
572
641
  for (const handle of this.#turns.values())
573
642
  handle.fail(died);
643
+ for (const stream of this.#eventStreams)
644
+ stream.fail(died);
645
+ this.#eventStreams.clear();
574
646
  this.#discharge = { exit, kind: "durableDeath", profile };
575
647
  return this.#discharge;
576
648
  }
@@ -578,6 +650,9 @@ export class Session {
578
650
  const terminalUnknownItems = this.#fold.markEphemeralHostDeath(isItemInProgress);
579
651
  for (const handle of this.#turns.values())
580
652
  handle.settleTerminalUnknown();
653
+ for (const stream of this.#eventStreams)
654
+ stream.end();
655
+ this.#eventStreams.clear();
581
656
  // SS2.13.3b "do not attempt to reattach". `discardEphemeral` already wrote
582
657
  // the commandIds into the shared set (it holds it by reference); the
583
658
  // sessionId is this layer's to record, because the pending set does not
@@ -733,10 +808,12 @@ export class Session {
733
808
  * Submit feedback about this session (`feedback/submit`). The host
734
809
  * serves it only when the spawn requested the `feedback` capability
735
810
  * (`requestedCapabilities: ["feedback"]`) and install policy allows
736
- * it; without that grant the host refuses the command.
811
+ * it; without that grant the host refuses the call. Its wire params
812
+ * define no `commandId` (each call is one submit; the wire contract
813
+ * attaches no dedup), so it rides `request()` and mints none.
737
814
  */
738
815
  async submitFeedback(input) {
739
- const ack = await this.#requireLiveConnection("submitFeedback").command("feedback/submit", {
816
+ const ack = await this.#requireLiveConnection("submitFeedback").request("feedback/submit", {
740
817
  ...input,
741
818
  sessionId: this.sessionId,
742
819
  });
@@ -1024,3 +1101,4 @@ export class Session {
1024
1101
  this.#handle(held.turnId).pushDelta(params);
1025
1102
  }
1026
1103
  }
1104
+ _a = Session;
@@ -86,6 +86,29 @@ export type TurnOutcome = {
86
86
  * listening when the turn started is not looking at a launch failure.
87
87
  */
88
88
  export declare function isLaunchFailure(outcome: TurnOutcome): boolean;
89
+ /**
90
+ * A single-consumer push stream. Buffers when nobody is awaiting and hands the
91
+ * buffer over before reporting an end or a failure, so a consumer never loses
92
+ * events it was already owed.
93
+ */
94
+ export declare class PushStream<T> implements AsyncIterableIterator<T> {
95
+ #private;
96
+ /**
97
+ * `onFinished` deregisters this stream from its owner. Without it a consumer
98
+ * that `break`s out of a `for await` — or simply drops the iterator — stays
99
+ * in the fan-out set for the rest of the turn, so every later event is
100
+ * pushed into a stream nobody reads. A render loop that re-attaches per
101
+ * frame would grow one dead stream per frame.
102
+ */
103
+ constructor(onFinished: () => void);
104
+ push(value: T): void;
105
+ end(): void;
106
+ fail(error: unknown): void;
107
+ next(): Promise<IteratorResult<T>>;
108
+ /** `break`/`return` inside a `for await`: drop the backlog and finish. */
109
+ return(): Promise<IteratorResult<T>>;
110
+ [Symbol.asyncIterator](): AsyncIterableIterator<T>;
111
+ }
89
112
  /** The turn's replayable backlog, supplied by `Session` from the fold. */
90
113
  export type ItemReplay = () => readonly FoldedItem[];
91
114
  /** What `interrupt` forwards: the SS3.4 retract pairing. */
@@ -42,7 +42,7 @@ export function isLaunchFailure(outcome) {
42
42
  * buffer over before reporting an end or a failure, so a consumer never loses
43
43
  * events it was already owed.
44
44
  */
45
- class PushStream {
45
+ export class PushStream {
46
46
  #buffer = [];
47
47
  #onFinished;
48
48
  /**
@@ -1 +1 @@
1
- export declare const STAMPED_SCHEMA_FINGERPRINT = "sha256:ef311d2dbf051ed9114556e14ad3980eb515104baa3409306a6817082a61d8cd";
1
+ export declare const STAMPED_SCHEMA_FINGERPRINT = "sha256:283b1b125dcc9172928fb5d6711a92a353796d030a7c186988ed527a13cf07f0";
@@ -3,4 +3,4 @@
3
3
  // schema/msp/stable/msp.schema.json through the port in
4
4
  // scripts/msp-fingerprint.mjs. A schema advance moves this value at the
5
5
  // next build; the file itself is gitignored and never committed.
6
- export const STAMPED_SCHEMA_FINGERPRINT = "sha256:ef311d2dbf051ed9114556e14ad3980eb515104baa3409306a6817082a61d8cd";
6
+ export const STAMPED_SCHEMA_FINGERPRINT = "sha256:283b1b125dcc9172928fb5d6711a92a353796d030a7c186988ed527a13cf07f0";
@@ -0,0 +1,39 @@
1
+ /**
2
+ * The one fold extension hook (FR-97527-3): a neutral, method-name-keyed
3
+ * registration consulted for BOTH connection-level state and the
4
+ * per-session fold.
5
+ *
6
+ * An extension runs INSIDE the single apply path — never a second pump —
7
+ * so gap buffering, twin-claiming and resume behave exactly as today. The
8
+ * hook names no experimental feature: it matches on the method string, and
9
+ * the extension keeps its own state in its own instance.
10
+ *
11
+ * A throw never escapes: both loops catch an extension's throw and report
12
+ * it to that extension's `onError` (the `ApprovalFailure` "reported, not
13
+ * thrown" rule — the call site is a notification pump with nothing to
14
+ * catch it). Without an `onError` the failure is swallowed, deliberately:
15
+ * one bad add-on must not drop every session. An `onError` that itself
16
+ * throws is swallowed too, for the same reason the approval observer's is.
17
+ */
18
+ export interface FoldExtension {
19
+ /** The exact notification method this extension handles. */
20
+ readonly method: string;
21
+ /**
22
+ * Fold one frame's params. Called in registration order with the other
23
+ * extensions for the same method, before the fold's own arm for that
24
+ * method runs.
25
+ */
26
+ apply(params: unknown): void;
27
+ /** Receives this extension's throws; absent means swallow. */
28
+ readonly onError?: (error: unknown) => void;
29
+ }
30
+ /**
31
+ * Run every extension registered for `method`, in registration order.
32
+ *
33
+ * The ONE call-and-report loop both planes share (fold + client `#route`),
34
+ * so guard and reporting changes land once. Objects only — a frame without
35
+ * usable params has nothing to fold. A throw is reported to that
36
+ * extension's `onError` (absent means swallow); an `onError` that itself
37
+ * throws is swallowed too. Returns how many extensions fired.
38
+ */
39
+ export declare function fireExtensions(extensions: readonly FoldExtension[], method: string, params: unknown): number;
@@ -0,0 +1,49 @@
1
+ /**
2
+ * The one fold extension hook (FR-97527-3): a neutral, method-name-keyed
3
+ * registration consulted for BOTH connection-level state and the
4
+ * per-session fold.
5
+ *
6
+ * An extension runs INSIDE the single apply path — never a second pump —
7
+ * so gap buffering, twin-claiming and resume behave exactly as today. The
8
+ * hook names no experimental feature: it matches on the method string, and
9
+ * the extension keeps its own state in its own instance.
10
+ *
11
+ * A throw never escapes: both loops catch an extension's throw and report
12
+ * it to that extension's `onError` (the `ApprovalFailure` "reported, not
13
+ * thrown" rule — the call site is a notification pump with nothing to
14
+ * catch it). Without an `onError` the failure is swallowed, deliberately:
15
+ * one bad add-on must not drop every session. An `onError` that itself
16
+ * throws is swallowed too, for the same reason the approval observer's is.
17
+ */
18
+ /**
19
+ * Run every extension registered for `method`, in registration order.
20
+ *
21
+ * The ONE call-and-report loop both planes share (fold + client `#route`),
22
+ * so guard and reporting changes land once. Objects only — a frame without
23
+ * usable params has nothing to fold. A throw is reported to that
24
+ * extension's `onError` (absent means swallow); an `onError` that itself
25
+ * throws is swallowed too. Returns how many extensions fired.
26
+ */
27
+ export function fireExtensions(extensions, method, params) {
28
+ if (params === null || typeof params !== "object" || Array.isArray(params))
29
+ return 0;
30
+ let fired = 0;
31
+ for (const extension of extensions) {
32
+ if (extension.method !== method)
33
+ continue;
34
+ fired += 1;
35
+ try {
36
+ extension.apply(params);
37
+ }
38
+ catch (error) {
39
+ try {
40
+ extension.onError?.(error);
41
+ }
42
+ catch {
43
+ // The failure observer threw. Swallowed, deliberately — same rule
44
+ // as the approval observer: there is no one left to tell.
45
+ }
46
+ }
47
+ }
48
+ return fired;
49
+ }
@@ -29,6 +29,7 @@
29
29
  * displaces the first durable one.
30
30
  */
31
31
  import type { ApprovalRequestParams, ApprovalResolvedParams, ApprovalUpdatedParams, Item, ItemCompletedParams, ItemDeltaParams, ItemStartedParams, ItemUpdatedParams, MonitorInboxItemAdmittedParams, MonitorInboxItemDrainedParams, MonitorInboxItemVoidedParams, MspNotification, SessionApprovalModeChangedParams, SessionBranchChangedParams, SessionContextUsageParams, SessionGoalChangedParams, SessionModelChangedParams, SessionModelRouteUnservedParams, SessionNameChangedParams, SessionReasoningEffortChangedParams, SessionTodoListChangedParams, SessionTokenUsageParams, TurnCompletedParams, TurnError, TurnForegroundCompletedParams, TurnModelAttemptStartedParams, TurnModelRetryScheduledParams, TurnRetractedParams, TurnRetryScheduledParams, TurnStartedParams, TurnTerminal, TurnUnqueuedParams, UserInputRequestParams, UserInputSettledParams, ViewGapParams } from "../msp.js";
32
+ import type { FoldExtension } from "./extension.js";
32
33
  import type { DeltaApplyOutcome, ItemApplyOutcome, TerminalUnknownItemAnnotation } from "./item-store.js";
33
34
  import type { StateApplyOutcome, StateValue } from "./state-store.js";
34
35
  /** The session-state families, each keyed in the store by its method name. */
@@ -395,6 +396,15 @@ export type FoldOutcome = {
395
396
  } | {
396
397
  readonly kind: "ignoredUnrecognizedMethod";
397
398
  readonly method: string;
399
+ }
400
+ /**
401
+ * An otherwise-unrecognized method a registered extension handled
402
+ * (FR-97527-3). Ids only, like its ignored twin: the extension keeps
403
+ * its own state in its own instance, so nothing here needs sealing.
404
+ */
405
+ | {
406
+ readonly kind: "extension";
407
+ readonly method: string;
398
408
  } | {
399
409
  /**
400
410
  * A frame that carried no `params`. The generated `Notification`
@@ -504,6 +514,7 @@ export interface FoldSessionState {
504
514
  */
505
515
  export declare class SessionFold {
506
516
  #private;
517
+ constructor(extensions?: readonly FoldExtension[]);
507
518
  /** Items, snapshot-only: the mutators are `apply()`'s, not the consumer's. */
508
519
  get items(): FoldItems;
509
520
  /**
@@ -28,6 +28,7 @@
28
28
  * unrecognized `TurnTerminal` is kept verbatim, and a second resolution never
29
29
  * displaces the first durable one.
30
30
  */
31
+ import { fireExtensions } from "./extension.js";
31
32
  import { ItemStore } from "./item-store.js";
32
33
  import { SessionStateStore } from "./state-store.js";
33
34
  /**
@@ -37,6 +38,10 @@ import { SessionStateStore } from "./state-store.js";
37
38
  export class SessionFold {
38
39
  #itemStore = new ItemStore();
39
40
  #sessionStateStore = new SessionStateStore();
41
+ #extensions;
42
+ constructor(extensions = []) {
43
+ this.#extensions = extensions;
44
+ }
40
45
  /** Items, snapshot-only: the mutators are `apply()`'s, not the consumer's. */
41
46
  get items() {
42
47
  return this.#itemStore;
@@ -151,6 +156,12 @@ export class SessionFold {
151
156
  if (event.params === null || typeof event.params !== "object" || Array.isArray(event.params)) {
152
157
  return { kind: "ignoredMissingParams", method: event.method };
153
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);
154
165
  const typed = event;
155
166
  switch (typed.method) {
156
167
  case "item/started":
@@ -213,6 +224,8 @@ export class SessionFold {
213
224
  };
214
225
  default: {
215
226
  const unrecognized = event;
227
+ if (extensionsFired > 0)
228
+ return { kind: "extension", method: unrecognized.method };
216
229
  return { kind: "ignoredUnrecognizedMethod", method: unrecognized.method };
217
230
  }
218
231
  }
@@ -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,7 +48,7 @@ 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
54
  export { MuseCapabilityNotGrantedError, MuseFacadeOwnedMethodError, MuseForeignSessionError, MuseGapFillError, MuseHostDiscoveryError, MuseSessionDiscardedError, PermissionProfileNotApplied, } from "./errors.js";
@@ -58,7 +59,7 @@ 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, SubagentReasonOptions, } 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
64
  export type { SendUserTurnOptions, SteerTurnOptions } from "./facade/turn-submit.js";
64
65
  export type { RunOptions, RunResult } from "./facade/run.js";
package/dist/src/msp.d.ts CHANGED
@@ -445,6 +445,23 @@ export interface BlockedPrompt {
445
445
  text: string;
446
446
  }
447
447
 
448
+ /** Whether the origin call join held at delivery. */
449
+ export type BodyCompletionCorrelation = "resolved" | "unresolved" | (string & {});
450
+
451
+ /** `bodyCompletion`: the facts one receipt row renders (ADR 87062 D2). The fold reads them from the inbox terminal record and the backgrounded call it names. `status`, `result_summary`, and `correlation` are required; `origin_call_id` is absent exactly when the join is unresolved. */
452
+ export interface BodyCompletionMembers {
453
+ /** Whether the origin call join held at delivery. */
454
+ correlation: BodyCompletionCorrelation;
455
+ /** The originating call's provider call id, opaque — the join key back to the original row. Absent when the join is unresolved (compaction). */
456
+ originCallId?: string;
457
+ /** True for the Manual semantic receipt (`◆`); false for the ordinary completion row. */
458
+ receipt: boolean;
459
+ /** Bounded transcript-visible result text; empty when the terminal carries none. Full bytes stay behind outputRef. */
460
+ resultSummary: string;
461
+ /** One fixed wire word per Task terminal (`completed`, `failed`, `cancelled`, `timedOut`, `rejected`) — never display text; gate-off display words derive client-side. */
462
+ status: string;
463
+ }
464
+
448
465
  /** The latest branch observation in the snapshot (tdd SS4.6.4, SS4.9.1). */
449
466
  export interface BranchState {
450
467
  /** The observed branch; `null` on a detached-HEAD observation. */
@@ -859,6 +876,8 @@ export interface ErrorData {
859
876
  sessionId?: string;
860
877
  /** Winning settlement on `userInputAlreadySettled`. */
861
878
  settlement?: UserInputSettlementSummary;
879
+ /** The stop's refusal kind on a `workflow/cancel` `commandRejected` whose stop was refused or whose settlement read failed (SS3.19, spec 14410 FR-92884-1): `stale_revision`, `policy_rejected`, `actor_authority_mismatch`, `authority_index_conflict`, `admission_failed`, `persistence_failed`, `control_not_signalled`, `post_marker_not_cancellable`, `control_outcome_uncertain`, `adapter_contract_violation`, `transport_lost` or `reply_lost`. */
880
+ stopRefusal?: string;
862
881
  /** The rejected upload id on `uploadNotFound` (`-32038`, SS3.33). */
863
882
  uploadId?: string;
864
883
  /** Prompt identity on user-input errors. */
@@ -1134,8 +1153,12 @@ export interface Item {
1134
1153
  backgroundTarget?: BackgroundTarget;
1135
1154
  /** `backgroundTerminalCompletion`: the five facts the Finished cell renders (ADR 50041 D4). */
1136
1155
  backgroundTerminalCompletion?: BackgroundTerminalCompletion;
1156
+ /** `toolCall`: the call's Bash Title — its `description` argument through the shared Bash Title normalizer, for a managed Bash call, served only while the host's `bash_titles` gate is on. The host adds it when it serves the item and never stores it; absent for any other call (tdd SS4.5.5; ADR 31406 D26). Old clients ignore it. */
1157
+ bashTitle?: string;
1137
1158
  /** `reminderChild`: `true` when this child is a blocking reminder (it holds the turn open until it settles); absent otherwise, never `false` (ADR 41191 D4). The status word stays off the wire; clients name the reminder from `reminderAgentId`. */
1138
1159
  blocking?: boolean;
1160
+ /** `bodyCompletion`: the facts one receipt row renders (ADR 87062 D2, accepted names). */
1161
+ bodyCompletion?: BodyCompletionMembers;
1139
1162
  /** `toolCall`: the provider call id (`call_...`), opaque. */
1140
1163
  callId?: string;
1141
1164
  /** `workflow`: one `outputRef`-shaped link per recorded child spawn with an objective (`kind: "workflow_child_prompt"`), fetched via `item/readOutput` (tdd SS4.5.8/SS4.7.4, #45449). */
@@ -1300,7 +1323,7 @@ export interface Item {
1300
1323
  summarizedThrough?: string;
1301
1324
  /** `reasoning`: one entry per summary part; part *n* streams via `item/delta` field `"summary.n"` (part boundary = index change). */
1302
1325
  summary?: string[];
1303
- /** `reminderChild`: the linked task id. */
1326
+ /** `reminderChild`: the linked task id. Unresolved `bodyCompletion` items also set it (FR-87062-1: the diagnostic names the task whose join did not hold). */
1304
1327
  taskId?: string;
1305
1328
  /** Terminal `toolCall`, or a `subagent` whose result drained (#70249): the item after whose rows the terminal row renders (tdd SS4.5.21, ADR 56496 D2/D3). */
1306
1329
  terminalRowAfterItemId?: string;
@@ -1363,7 +1386,7 @@ export interface ItemDeltaParams {
1363
1386
  }
1364
1387
 
1365
1388
  /** The eleven v1 item kinds (tdd SS4.5.2–4.5.13) plus post-v1 kinds (tdd SS4.5.14+). Open: a new kind is additive evolution, and clients MUST render unknown kinds generically (tdd SS4.10). */
1366
- export type ItemKind = "userMessage" | "agentMessage" | "reasoning" | "toolCall" | "userShell" | "subagent" | "workflow" | "reminderChild" | "compaction" | "hookRun" | "sideChat" | "webSearch" | "monitorFeed" | "damagedRange" | "scheduledFire" | "backgroundTerminalCompletion" | "overdueNotice" | "earlierHistory" | "peerMessage" | "subagentInput" | "subagentResult" | "systemNotice" | (string & {});
1389
+ export type ItemKind = "userMessage" | "agentMessage" | "reasoning" | "toolCall" | "userShell" | "subagent" | "workflow" | "reminderChild" | "compaction" | "hookRun" | "sideChat" | "webSearch" | "monitorFeed" | "damagedRange" | "scheduledFire" | "backgroundTerminalCompletion" | "overdueNotice" | "earlierHistory" | "peerMessage" | "subagentInput" | "subagentResult" | "systemNotice" | "bodyCompletion" | (string & {});
1367
1390
 
1368
1391
  /** The `item/readOutput` content encoding (tdd SS4.7.4). Closed: text media is ALWAYS `utf8` and binary media `base64`; a third value would change the client's decode contract. */
1369
1392
  export type ItemReadOutputEncoding = "utf8" | "base64";
@@ -1756,8 +1779,8 @@ export interface MonitorInboxSnapshotEntry {
1756
1779
  voidedAt?: string;
1757
1780
  }
1758
1781
 
1759
- /** `systemNotice`: the producing family, so a client routes a notice without parsing its text (tdd SS4.5.23). Open. The v1 vocabulary is the Monitor notice and the three system-chrome producers (ADR 42729 D1) plus the hook-run producer (ADR 75121 D2) and the paused-Workflow checkpoint producer (ADR 39490 D5); absent means the server named no origin, and a client never infers one. */
1760
- export type NoticeOrigin = "monitor" | "skillsStartup" | "scheduledFire" | "incompleteGeneration" | "hook" | "workflowCheckpoint" | (string & {});
1782
+ /** `systemNotice`: the producing family, so a client routes a notice without parsing its text (tdd SS4.5.23). Open. The v1 vocabulary is the Monitor notice and the three system-chrome producers (ADR 42729 D1) plus the hook-run producer (ADR 75121 D2), the paused-Workflow checkpoint producer (ADR 39490 D5) and the continued-child tools producer (ADR 42729 D5); absent means the server named no origin, and a client never infers one. */
1783
+ export type NoticeOrigin = "monitor" | "skillsStartup" | "scheduledFire" | "incompleteGeneration" | "hook" | "workflowCheckpoint" | "continuedChildTools" | (string & {});
1761
1784
 
1762
1785
  /** `systemNotice`: the notice's level (tdd SS4.5.23). Open; an unknown value is an unknown-but-present level, rendered generically (SS4.10). */
1763
1786
  export type NoticeSeverity = "info" | "warning" | "error" | (string & {});
@@ -2258,6 +2281,8 @@ export type SandboxUnavailableReason = "userNamespacesDenied" | "bubblewrapUnava
2258
2281
 
2259
2282
  /** The `schema` pair in [`InitializeResult`] (SS1.4.1, SS1.5.3). `version` is the wire **envelope** schema version — distinct from the session-view `schemaVersion`, the raw-log `schema_version`, and the 0.x/1.0 stability posture, which is not on the wire at all (INV-006a). */
2260
2283
  export interface SchemaInfo {
2284
+ /** `sha256:<64 lower hex>` content hash of this server binary's experimental-surface bundle (ADR 97527 D5). Additive-optional: a host that predates the member omits it, and the reader treats absence as unknown — never a guessed value (SS1.5.4). */
2285
+ experimentalFingerprint?: string;
2261
2286
  /** `sha256:<64 lower hex>` content hash of this server binary's stable-surface bundle (INV-003). A mismatch is a warning condition, not an error (SS1.4.1). */
2262
2287
  fingerprint: string;
2263
2288
  /** Envelope schema version; `1` in v1, expected to stay `1` for a long time (SS1.4.1). */
@@ -2274,7 +2299,7 @@ export interface ServerInfo {
2274
2299
 
2275
2300
  /** The session object every lifecycle method returns or lists (tdd SS2.4). Additive-optional evolution applies: clients must ignore unknown fields. */
2276
2301
  export interface Session {
2277
- /** The `turnId` of the current foreground turn when `status` is `running`, and `null` when the session is idle (tdd SS2.4). **Required-nullable.** Every served `Session` carries the member: `null` when the session is idle or not loaded, the turn id when it is running. An optional-absent shape would publish it as plain `string` and reject every idle `Session` frame the host sends. */
2302
+ /** The `turnId` of the current foreground turn when a turn is in flight (parked under `needsInput` included), and `null` otherwise (tdd SS2.4, ADR 95605 D1). **Required-nullable.** Every served `Session` carries the member: `null` when no turn is in flight or the session is not loaded, the turn id when one is. An optional-absent shape would publish it as plain `string` and reject every idle `Session` frame the host sends. */
2278
2303
  activeTurnId: string | null;
2279
2304
  /** The folded effective approval mode. **Additive-optional**: a Session object that omits it means the host has not folded a mode, which is why the index-derived `session/list` entry may legitimately omit it (tdd SS2.4, SS5.12). */
2280
2305
  approvalMode?: EffectiveApprovalModeState;
@@ -2419,6 +2444,8 @@ export interface SessionCompactResult {
2419
2444
 
2420
2445
  /** The open configuration extension object shared by `session/start` and `session/resume` (ADR 32760 D1). Unknown keys are ignored on the wire, never rejected: the live decoder tolerates them, and no exported bundle carries `additionalProperties: false`. The Rust typed model's `deny_unknown_fields` is internal and never exported — the closedness export applies nowhere, and the `x-msp-closed` opt-in mechanism stays inert. Recognized `mcpServers` values are typed and validated before they leave the wire boundary. */
2421
2446
  export interface SessionConfig {
2447
+ /** Developer instructions for this session only (ADR 32029 D38, stable from switch piece F2), on `session/start` and `session/resume`. The text is trimmed. A nonblank value replaces the settings-derived developer instructions; an omitted member is no override and keeps the full developer context. Explicit `null` and blank text are the explicit clear (the Rust value is an empty string): no override, and on a host that serves developer instructions they also turn off the session's suppressible developer context (the agent catalog and the memory snapshot). Any other type fails the decode. A host that does not serve developer instructions ignores a valid member. */
2448
+ developerPrompt?: string | null;
2422
2449
  /** Native MCP servers added only to this session runtime. */
2423
2450
  mcpServers?: Record<string, SessionMcpServerConfig>;
2424
2451
  }
@@ -2694,6 +2721,8 @@ export interface SessionReadResult {
2694
2721
  history: SessionHistory;
2695
2722
  /** Same member as `session/resume` (tdd SS2.5.5, ADR 36635 D2). */
2696
2723
  lastTurn?: LastTurn;
2724
+ /** Whether a native child read session's model turn runs (tdd SS2.5.5, ADR 89202 D1): served on a read of a `subagent` session whose containing session this host holds loaded, from that session's runtime at serve time. Absent for every other read and when the runtime cannot answer; absence asserts nothing. */
2725
+ modelTurnRunning?: boolean;
2697
2726
  /** The same pointer shape as `session/resume`. Because `session/read` never subscribes this is a point-in-time log read only: no requests are re-issued after it (tdd SS2.5.5). */
2698
2727
  pendingRequests: PendingRequestPointer[];
2699
2728
  /** One short record per child session the checkpoint boundary pruned (tdd SS2.5.5, ADR 71910 D8). Absent-when-empty: a missing member means the view is uncompacted or nothing pruned, never an error. */
@@ -2876,6 +2905,8 @@ export interface SessionSpawnedBy {
2876
2905
  export interface SessionStartParams {
2877
2906
  /** The session's starting approval mode; server default when omitted or explicit `null` — both spellings select the default (#23468). Select, never create — the value names a mode the host's configuration already defines (tdd SS2.5.1, SS5.12). This is the only surface that declares a non-interactive run's policy (tdd SS5.11, D-008). */
2878
2907
  approvalMode?: ApprovalMode | null;
2908
+ /** Marks this start as a `/clear` (spec 207 amendment 93195, FR-93195-1, ADR 93195 D1): `true` starts the new session as a clear, so its `SessionStart` hooks get source `clear` instead of `startup`. `false` and omitted are the same plain start (source `startup`). It neither needs nor implies `previousSessionId`. Explicit `null` is invalid params. */
2909
+ clear?: boolean;
2879
2910
  /** The SS2.5 idempotency handle (UUIDv7). Required; the server never mints one. */
2880
2911
  commandId: string;
2881
2912
  /** Reserved for future per-session overrides; only its `mcpServers` member is admitted. */
@@ -2917,13 +2948,13 @@ export interface SessionStartedParams {
2917
2948
  /** A session's load state (tdd SS2.4). */
2918
2949
  export type SessionStatus = "notLoaded" | "idle" | "running" | (string & {});
2919
2950
 
2920
- /** `session/statusChanged` params (tdd SS4.6.10, ADR 31983 D2): a loaded session's projected `(status, attention)` value flipped. A command-plane broadcast — delivered to every connection regardless of its view subscription set, never gated, no `sourceRange`; the same facts live on the Session object, which is how a client seeds its table (no initial burst on connect). */
2951
+ /** `session/statusChanged` params (tdd SS4.6.10, ADR 31983 D2): a loaded session's projected `(status, attention, needsInputReasons)` value flipped. A command-plane broadcast — delivered to every connection regardless of its view subscription set, never gated, no `sourceRange`; the same facts live on the Session object, which is how a client seeds its table (no initial burst on connect). */
2921
2952
  export interface SessionStatusChangedParams {
2922
2953
  /** Attention flags after the transition; present only when at least one flag is set (tdd SS2.4, ADR 31983 D3). */
2923
2954
  attention?: AttentionFlag[];
2924
2955
  /** The owning session. */
2925
2956
  sessionId: string;
2926
- /** Load state after the transition (the closed SS2.4 enum, unchanged). */
2957
+ /** Load state after the transition (the open SS2.4 enum, including `needsInput` since ADR 95605 D1/D4). */
2927
2958
  status: SessionStatus;
2928
2959
  /** The causing record's view cursor (ADR 31983 D4). Required-nullable: `null` exactly when the paired `session/closed`'s cursor is `null` (the unload fold-failure arm); a definite cursor everywhere else. */
2929
2960
  viewCursor: string | null;
@@ -3340,6 +3371,8 @@ export interface SubagentResult {
3340
3371
  structuredData?: Record<string, unknown>;
3341
3372
  /** Result summary, bounded on the wire at the 64 KiB retained-text budget (tdd SS4.5.4 and SS4.5.7, ADR 35691 D9); a cut sets the item's `truncated`. The durable record stays verbatim. */
3342
3373
  summary: string;
3374
+ /** `true` once a newer attempt of the child started after this result (ADR 92325 D1): the result stays, and a client takes the child's status from `controlStatus`. Absent, it asserts nothing (a host before this member, or a fold state saved before it, never sets it); a newer result replaces the whole result, so it carries no mark. */
3375
+ superseded?: boolean;
3343
3376
  /** Result text, when present, bounded on the wire at the same 64 KiB budget (ADR 35691 D9); a cut sets the item's `truncated`. */
3344
3377
  text?: string;
3345
3378
  }
@@ -3639,7 +3672,7 @@ export interface TurnError {
3639
3672
  }
3640
3673
 
3641
3674
  /** Turn failure classes (tdd SS4.5.1, `TerminalErrorKind` plus the model-task failure class). Open. */
3642
- export type TurnErrorKind = "stepLimit" | "configError" | "projectionError" | "logError" | "workflowLaunchError" | "environmentError" | "modelError" | "launchError" | "authRequired" | "mcpLinkError" | (string & {});
3675
+ export type TurnErrorKind = "stepLimit" | "configError" | "projectionError" | "logError" | "workflowLaunchError" | "environmentError" | "modelError" | "launchError" | "authRequired" | "mcpLinkError" | "reasoningReplayRefused" | "contextOverflow" | (string & {});
3643
3676
 
3644
3677
  /** `turn/foregroundCompleted` params (tdd SS4.5.12): the turn's foreground work is done and named background reminder checks hold the turn open. Explicitly non-terminal: the turn ends only at `turn/completed` / `turn/unqueued`. */
3645
3678
  export interface TurnForegroundCompletedParams {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@muse-code/sdk",
3
- "version": "1.4.15",
3
+ "version": "1.4.20",
4
4
  "description": "TypeScript SDK for the Muse Session Protocol (MSP): connect to a Muse Code session, drive turns, and fold the event stream. Zero runtime dependencies.",
5
5
  "license": "MIT",
6
6
  "homepage": "https://github.com/meta-models/muse-code-sdk",