@muse-code/sdk 1.4.15 → 1.4.23

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";
@@ -26,8 +27,8 @@ import { ApprovalRouter } from "./approval.js";
26
27
  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
- import { MuseForeignSessionError, MuseSessionDiscardedError } from "../errors.js";
30
- import { TurnHandle } from "./turn-handle.js";
30
+ import { MuseCapabilityNotGrantedError, MuseForeignSessionError, MuseSessionDiscardedError, } from "../errors.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
@@ -68,6 +69,69 @@ const NO_IO = Promise.resolve([]);
68
69
  * @internal
69
70
  */
70
71
  export const pumpDropsApplyResults = Symbol("Session.pumpDropsApplyResults");
72
+ /**
73
+ * Frames `MuseClient` builds from a re-sent server request (`approval/request`,
74
+ * `userInput/request`). They carry the cursor of the event that OPENED the
75
+ * request, older than what the session has folded, so they never move the
76
+ * cursor `reload()` resumes from.
77
+ */
78
+ const serverRequestFrames = new WeakSet();
79
+ /** @internal Mark `frame` as built from a re-sent server request; see {@link serverRequestFrames}. */
80
+ export function serverRequestFrame(frame) {
81
+ serverRequestFrames.add(frame);
82
+ return frame;
83
+ }
84
+ /**
85
+ * Module-private friend seam (never on the package barrel): `MuseClient`
86
+ * hands each session its handshake's grants, which `reload()`'s `config` is
87
+ * checked against (FR-79107-3). A session given none has no handshake on
88
+ * record and refuses a config naming servers, as such a client does.
89
+ *
90
+ * @internal
91
+ */
92
+ export const grantedCapabilities = Symbol("Session.grantedCapabilities");
93
+ /**
94
+ * The `config` to forward, or a typed refusal before anything is sent
95
+ * (FR-79107-3). Per-session MCP servers need the `sessionMcp` grant in the
96
+ * handshake (`spawn` requests it; a caller's own handshake must request it
97
+ * too); with no handshake on record it cannot be shown. A config naming no
98
+ * server needs no grant, as on the host (ADR 32760 D3).
99
+ *
100
+ * @internal Shared with `MuseClient`'s open verbs.
101
+ */
102
+ export function forwardedConfig(method, config, granted) {
103
+ if (config.mcpServers == null || Object.keys(config.mcpServers).length === 0)
104
+ return config;
105
+ if (granted?.includes("sessionMcp") === true)
106
+ return config;
107
+ throw new MuseCapabilityNotGrantedError("sessionMcp", method, "config.mcpServers needs the sessionMcp grant, which this connection's handshake does not hold (MuseClient.spawn requests it; a host withholds it when per-session MCP is turned off)");
108
+ }
109
+ /**
110
+ * The resume cursor a frame carries, if any: a view notification's
111
+ * `viewCursor`. A frame built from a re-sent server request carries the
112
+ * older cursor that opened it, and `session/statusChanged`'s cursor is not a
113
+ * resume cursor (tdd SS4.6.10), so neither moves where `reload()` resumes.
114
+ */
115
+ function resumeCursorOf(frame) {
116
+ if (serverRequestFrames.has(frame) || frame.method === "session/statusChanged") {
117
+ return undefined;
118
+ }
119
+ const cursor = frame.params?.viewCursor;
120
+ return typeof cursor === "string" ? cursor : undefined;
121
+ }
122
+ /**
123
+ * The resume result, or a `ProtocolError` when the reply names no session: a
124
+ * reply the SDK cannot use (#97920), not a `TypeError` from reading it.
125
+ *
126
+ * @internal Shared with `MuseClient`'s open path.
127
+ */
128
+ export function resumeResultOf(raw) {
129
+ const session = raw.session;
130
+ if (typeof session?.sessionId !== "string") {
131
+ throw new ProtocolError("session/resume replied without a session");
132
+ }
133
+ return raw;
134
+ }
71
135
  /**
72
136
  * Module-private friend seam (never on the package barrel): `Session.run`'s
73
137
  * abort takes a queued turn back under one `commandId` and sends that same
@@ -76,6 +140,36 @@ export const pumpDropsApplyResults = Symbol("Session.pumpDropsApplyResults");
76
140
  * @internal
77
141
  */
78
142
  export const resendableUnqueue = Symbol("Session.resendableUnqueue");
143
+ /**
144
+ * Module-private friend seam (never on the package barrel): `MuseClient`
145
+ * calls it once its orderly `close()` has shut the host down, which reports
146
+ * no death to the session, so the `events()` streams end here instead.
147
+ *
148
+ * @internal
149
+ */
150
+ export const endEventStreams = Symbol("Session.endEventStreams");
151
+ /**
152
+ * Module-private friend seam (never on the package barrel): `MuseClient`
153
+ * installs how a session follows a sub-agent's session. Following routes the
154
+ * child session's events to `forward` and returns how to stop.
155
+ *
156
+ * @internal
157
+ */
158
+ export const followsSubagents = Symbol("Session.followsSubagents");
159
+ /**
160
+ * Module-private test seam: how many sub-agent follows this session holds,
161
+ * so a test can prove a stopped follow keeps no child fold alive.
162
+ *
163
+ * @internal
164
+ */
165
+ export const followedSubagentCount = Symbol("Session.followedSubagentCount");
166
+ /**
167
+ * Module-private friend seam: `MuseClient` marks the internal session that
168
+ * folds a followed sub-agent's events, handing each one to the parent.
169
+ *
170
+ * @internal
171
+ */
172
+ export const forwardsEvents = Symbol("Session.forwardsEvents");
79
173
  /**
80
174
  * One conversation with the agent.
81
175
  *
@@ -97,7 +191,7 @@ export class Session {
97
191
  #approvals;
98
192
  /** The FR-020 splice-fill (`gap-fill.ts`). */
99
193
  #gaps;
100
- #fold = new SessionFold();
194
+ #fold;
101
195
  /**
102
196
  * Approvals the fold holds a durable terminal for. Read by a re-sent
103
197
  * `approval/request`, which skips the fold, so it authors nothing for an
@@ -109,6 +203,27 @@ export class Session {
109
203
  #discharge;
110
204
  /** Set on a durable abnormal death, so late handles inherit the rejection. */
111
205
  #deathError;
206
+ /** The cursor of the last view notification folded, else the opening's head: where `reload()` resumes. */
207
+ #viewCursor;
208
+ /** The in-flight `reload()`, shared by concurrent calls. */
209
+ #reloading;
210
+ /** Set through {@link grantedCapabilities} by `MuseClient`. */
211
+ #granted;
212
+ /**
213
+ * Cursors that reached this session since `reload()` sent its resume, so a
214
+ * repeat is dropped: seeded with the frames a running gap fill holds, then
215
+ * every frame applied, held or folded (a page's included). Cleared by the
216
+ * first new cursor after the reply: the repeats (the replay, then the live
217
+ * stream's copy of the same window) come before it. Bounded by the replay
218
+ * and the fill.
219
+ */
220
+ #replayed;
221
+ #replayAnswered = false;
222
+ /**
223
+ * Set when a reload's reply was not a cursor suffix: the host then streams
224
+ * from a newer head, so the fold has a gap no later reload can fill.
225
+ */
226
+ #reloadGap = false;
112
227
  #turns = new Map();
113
228
  /**
114
229
  * `item/delta` frames whose item the fold does not hold yet. The store
@@ -120,6 +235,18 @@ export class Session {
120
235
  * durable `item/completed` always lands the item.
121
236
  */
122
237
  #unattributedDeltas = new Map();
238
+ /** The live `events()` streams, fed by every folded event. */
239
+ #eventStreams = new Map();
240
+ /** Set by {@link endEventStreams}: the client closed, so a later stream ends at once. */
241
+ #eventsEnded = false;
242
+ /** The `events({ subagents: true })` streams among them, also fed each followed sub-agent's events. */
243
+ #subagentStreams = new Set();
244
+ /** Set through {@link followsSubagents} by `MuseClient`. */
245
+ #subagentFollower;
246
+ /** How to stop following each sub-agent, keyed by its `subagent` item id. */
247
+ #followedSubagents = new Map();
248
+ /** Set through {@link forwardsEvents} on a sub-agent's internal session. */
249
+ #forwardEvents;
123
250
  /** Set through {@link pumpDropsApplyResults} by `MuseClient`. */
124
251
  #applyResultsDropped = false;
125
252
  /** This session's own `unqueue()` calls awaiting their ack, counted per turn id. */
@@ -177,6 +304,104 @@ export class Session {
177
304
  [pumpDropsApplyResults]() {
178
305
  this.#applyResultsDropped = true;
179
306
  }
307
+ /** @internal See {@link followsSubagents}. */
308
+ [followsSubagents](follower) {
309
+ this.#subagentFollower = follower;
310
+ }
311
+ /** @internal See {@link followedSubagentCount}. */
312
+ [followedSubagentCount]() {
313
+ return this.#followedSubagents.size;
314
+ }
315
+ /** @internal See {@link forwardsEvents}. */
316
+ [forwardsEvents](forward) {
317
+ this.#forwardEvents = forward;
318
+ }
319
+ /** Yield one folded event to every live `events()` stream. */
320
+ #emit(frame, outcome) {
321
+ if (this.#eventStreams.size === 0 && this.#forwardEvents === undefined)
322
+ return;
323
+ const fold = outcome.fold;
324
+ // The item as of THIS event: the store keeps one object per revision, so
325
+ // a later revision folding before the consumer reads cannot change it.
326
+ const item = fold.kind === "item" && fold.outcome.kind !== "ignoredStaleRevision"
327
+ ? this.#fold.items.get(fold.outcome.itemId)
328
+ : undefined;
329
+ const event = item === undefined ? { frame, outcome } : { frame, item, outcome };
330
+ for (const stream of this.#eventStreams.keys())
331
+ stream.push(event);
332
+ this.#forwardEvents?.(event);
333
+ if (item?.kind === "subagent" && this.#subagentStreams.size > 0)
334
+ this.#followSubagent(item);
335
+ }
336
+ /**
337
+ * Follow a `subagent` item's session while it runs, stop when it ends. It
338
+ * runs while `inProgress` with a `childSessionId` (present once the child's
339
+ * start is attested); nested sub-agents' items are on this view too.
340
+ */
341
+ #followSubagent(item) {
342
+ const followed = this.#followedSubagents.get(item.itemId);
343
+ const child = item.status === "inProgress" ? item.childSessionId : undefined;
344
+ if (child == null || item.subagentId == null) {
345
+ // Finish, not stop: each session drains to the connection on its own, so
346
+ // the child's last steps can arrive after its item ended. Kept in the
347
+ // map so the last stream closing or a host death still stops it now.
348
+ followed?.finish();
349
+ return;
350
+ }
351
+ if (followed !== undefined || this.#subagentFollower === undefined)
352
+ return;
353
+ const tag = { itemId: item.itemId, subagentId: item.subagentId, childSessionId: child };
354
+ const itemId = item.itemId;
355
+ const follow = this.#subagentFollower(child, (event) => {
356
+ const tagged = { ...event, subagent: tag };
357
+ for (const stream of this.#subagentStreams)
358
+ stream.push(tagged);
359
+ },
360
+ // A stopped follow leaves the map, so its child fold is not kept alive.
361
+ () => {
362
+ if (this.#followedSubagents.get(itemId) === follow)
363
+ this.#followedSubagents.delete(itemId);
364
+ });
365
+ this.#followedSubagents.set(itemId, follow);
366
+ }
367
+ #unfollowSubagents() {
368
+ const follows = [...this.#followedSubagents.values()];
369
+ this.#followedSubagents.clear();
370
+ for (const follow of follows)
371
+ follow.stop();
372
+ }
373
+ /**
374
+ * Fold one frame an SS4.8 fill splices in, and yield it. Its retirements
375
+ * and I/O settle on the gap frame's `io`, so the event carries none.
376
+ */
377
+ #spliced(frame, into) {
378
+ const fold = this.#foldAndRoute(frame, into);
379
+ this.#emit(frame, { fold, io: NO_IO, retirements: [] });
380
+ }
381
+ /** @internal See {@link grantedCapabilities}. */
382
+ [grantedCapabilities](granted) {
383
+ this.#granted = granted;
384
+ }
385
+ /** @internal See {@link endEventStreams}. */
386
+ [endEventStreams]() {
387
+ this.#eventsEnded = true;
388
+ this.#finishEventStreams((stream) => stream.end());
389
+ }
390
+ /**
391
+ * End or fail every live stream, drop its abort listener and stop following
392
+ * sub-agents: `end()` and `fail()` skip the stream's own cleanup, which only
393
+ * `return()` runs, and a listener left on a long-lived signal would keep this
394
+ * session alive.
395
+ */
396
+ #finishEventStreams(finish) {
397
+ for (const [stream, unlisten] of this.#eventStreams) {
398
+ finish(stream);
399
+ unlisten();
400
+ }
401
+ this.#eventStreams.clear();
402
+ this.#subagentStreams.clear();
403
+ this.#unfollowSubagents();
404
+ }
180
405
  /** @internal See {@link resendableUnqueue}: each call of the result sends the same reclaim. */
181
406
  [resendableUnqueue](turnId) {
182
407
  const commandId = this.#requireLiveConnection("unqueue").mintCommandId();
@@ -197,15 +422,17 @@ export class Session {
197
422
  constructor(options) {
198
423
  this.sessionId = options.sessionId;
199
424
  this.#durability = options.durability;
425
+ this.#fold = new SessionFold(options.extensions);
200
426
  this.#discarded = options.discarded;
201
427
  this.opening = options.opening;
428
+ this.#viewCursor = options.opening?.result.viewCursor;
202
429
  this.#pending = new PendingCommandSet(options.discarded === undefined
203
430
  ? undefined
204
431
  : { discardedCommandIds: options.discarded.commandIds });
205
432
  this.#submit = new TurnSubmitter(options.sessionId, options.connection, this.#pending);
206
433
  this.#approvals = new ApprovalRouter(options.sessionId, options.connection);
207
434
  this.#gaps = new GapFiller({
208
- apply: (frame, into) => this.#foldAndRoute(frame, into),
435
+ apply: (frame, into) => this.#spliced(frame, into),
209
436
  connection: options.connection,
210
437
  discarded: () => this.#discharge?.kind === "discharged",
211
438
  fold: this.#fold,
@@ -239,7 +466,81 @@ export class Session {
239
466
  get knownTurnCount() {
240
467
  return this.#turns.size;
241
468
  }
469
+ /**
470
+ * How many `events()` streams this session still feeds: a stream ended by
471
+ * `break`, `return()`, its signal or the client's close must leave this set.
472
+ *
473
+ * @internal Test observability, stripped from the published declarations,
474
+ * like {@link knownTurnCount}.
475
+ */
476
+ get liveEventStreamCount() {
477
+ return this.#eventStreams.size;
478
+ }
242
479
  apply(event) {
480
+ const outcome = this.#applyLive(event);
481
+ // A frame held for a fill is yielded when the fill splices it in, and the
482
+ // live twin of a frame the fill already spliced in (or a reload's repeat of
483
+ // one already folded) was yielded then.
484
+ const kind = outcome.fold.kind;
485
+ if (kind !== "bufferedDuringGap" && kind !== "ignoredGapOverlap" && kind !== "ignoredReplayDuplicate") {
486
+ this.#emit(event, outcome);
487
+ }
488
+ return outcome;
489
+ }
490
+ /**
491
+ * Every event this session folds from now on, with what it changed
492
+ * (FR-97336-1). Live from the call, never replayed: read `fold`, then call
493
+ * this in the same tick, and nothing is missed, including the events
494
+ * folded while `startSession`/`resumeSession` was in flight. Each folded
495
+ * event is yielded once, in arrival order; the events a gap fill splices in
496
+ * are yielded when applied, in order. Buffered like `turn.items()`, so a slow
497
+ * reader never holds folding up.
498
+ *
499
+ * With `{ subagents: true }` on a session `MuseClient` did not open it
500
+ * throws a plain `Error`.
501
+ *
502
+ * `break`, `return()` or `options.signal` ends it, and so does an orderly
503
+ * `MuseClient.close()` (a stream created afterwards ends at once). It finishes the way a
504
+ * turn's `items()` does when the host dies: it ends after an ephemeral
505
+ * host's death, and rejects with `MuseHostDiedError` after a durable one's,
506
+ * once the events it already buffered are read.
507
+ */
508
+ events(options = {}) {
509
+ const subagents = options.subagents === true;
510
+ if (subagents && this.#subagentFollower === undefined) {
511
+ // Plain `Error`: API misuse. Only the client can subscribe to a sub-agent's session.
512
+ throw new Error("events({ subagents: true }) needs a session MuseClient opened");
513
+ }
514
+ const unlisten = () => options.signal?.removeEventListener("abort", onAbort);
515
+ const stream = new PushStream(() => {
516
+ this.#eventStreams.delete(stream);
517
+ if (this.#subagentStreams.delete(stream) && this.#subagentStreams.size === 0)
518
+ this.#unfollowSubagents();
519
+ unlisten();
520
+ });
521
+ const onAbort = () => void stream.return();
522
+ if (options.signal?.aborted === true)
523
+ stream.end();
524
+ else if (this.#deathError !== undefined)
525
+ stream.fail(this.#deathError);
526
+ else if (this.#discharge?.kind === "discharged" || this.#eventsEnded)
527
+ stream.end();
528
+ else {
529
+ this.#eventStreams.set(stream, unlisten);
530
+ options.signal?.addEventListener("abort", onAbort, { once: true });
531
+ if (subagents) {
532
+ this.#subagentStreams.add(stream);
533
+ // The first such stream follows the sub-agents already running.
534
+ if (this.#subagentStreams.size === 1) {
535
+ for (const item of this.#fold.items.list())
536
+ if (item.kind === "subagent")
537
+ this.#followSubagent(item);
538
+ }
539
+ }
540
+ }
541
+ return stream;
542
+ }
543
+ #applyLive(event) {
243
544
  // Only enforce when the frame actually NAMES a session. `ViewEvent`'s
244
545
  // members all declare `sessionId`, but a newer host's unknown notification
245
546
  // reaches this method at runtime and SS1.5.4 says it is tolerated
@@ -266,6 +567,14 @@ export class Session {
266
567
  if (this.#discharge?.kind === "discharged") {
267
568
  return { fold: { kind: "refusedSessionDiscarded" }, io: NO_IO, retirements: [] };
268
569
  }
570
+ const repeated = this.#replayRepeat(event);
571
+ if (repeated !== undefined) {
572
+ return {
573
+ fold: { kind: "ignoredReplayDuplicate", method: event.method, viewCursor: repeated },
574
+ io: NO_IO,
575
+ retirements: [],
576
+ };
577
+ }
269
578
  // An SS4.8 fill is in flight, so the live tail waits for the paged prefix
270
579
  // (tdd SS4.8's "buffer live events … splice the buffer after the paged
271
580
  // prefix"). Folding it now would run the fold backwards when the older
@@ -309,10 +618,93 @@ export class Session {
309
618
  }
310
619
  return {
311
620
  fold: outcome,
312
- io: Session.#settleIo(sink.tasks),
621
+ io: _a.#settleIo(sink.tasks),
313
622
  retirements: sink.retirements,
314
623
  };
315
624
  }
625
+ /** `reload()`'s repeat, by cursor equality: the repeated cursor, else undefined. */
626
+ #replayRepeat(event) {
627
+ if (this.#replayed === undefined)
628
+ return undefined;
629
+ const cursor = resumeCursorOf(event);
630
+ // `session/closed` names the final view head, often the last replayed
631
+ // cursor: it is the unload notice, never a repeat (tdd SS2.6.2).
632
+ if (cursor === undefined || event.method === "session/closed")
633
+ return undefined;
634
+ if (this.#replayed.has(cursor))
635
+ return cursor;
636
+ if (this.#replayAnswered)
637
+ this.#replayed = undefined;
638
+ else
639
+ this.#replayed.add(cursor);
640
+ return undefined;
641
+ }
642
+ /**
643
+ * Catch this session up in place (#97920): send `session/resume` with the
644
+ * cursor of the last view notification it folded, so the host loads the
645
+ * session if it was unloaded, re-attaches this connection, and streams the
646
+ * suffix after that cursor into THIS session. Its fold, handlers and
647
+ * pending turns stay; a frame the suffix repeats is dropped
648
+ * (`ignoredReplayDuplicate`). Resolves to the resume result once the host
649
+ * replies. Concurrent calls share one resume; a call with `config` while
650
+ * one is in flight is refused (plain `Error`) rather than dropped. `opening`
651
+ * still holds the original open's result. See {@link ReloadOptions}.
652
+ *
653
+ * The fold is caught up only when `result.history.noneReason` is
654
+ * `"cursorSuffix"`. Any other reply (a snapshot for a cursor older than the
655
+ * host keeps, a history budget) means the host served history instead of
656
+ * the missed events, and what streams after it folds over that gap; later
657
+ * reloads then refuse (plain `Error`) before sending: `resumeSession` it
658
+ * instead, for a new `Session` with a fresh fold.
659
+ *
660
+ * Use it before the next command on a session the host may have unloaded
661
+ * (`session/closed`). Refused before anything is sent when the session has
662
+ * folded no cursor yet (plain `Error`): a resume without one would not
663
+ * catch the fold up. A discarded session refuses as every verb does. A
664
+ * refused or failed reload leaves the fold, the other verbs and later
665
+ * reloads usable, except after a reply that was not a cursor suffix (above).
666
+ */
667
+ reload(options = {}) {
668
+ if (this.#reloading === undefined) {
669
+ this.#reloading = this.#reload(options).finally(() => (this.#reloading = undefined));
670
+ return this.#reloading;
671
+ }
672
+ // Sharing the in-flight resume would drop this call's config without a word.
673
+ if (options.config != null) {
674
+ return Promise.reject(new Error(`a reload of session ${this.sessionId} is already in flight; await it, then reload with config`));
675
+ }
676
+ return this.#reloading;
677
+ }
678
+ async #reload(options) {
679
+ const connection = this.#requireLiveConnection("reload");
680
+ if (this.#reloadGap) {
681
+ throw new Error(`session ${this.sessionId} has a gap an earlier reload could not fill (the host served history, not the missed events); resumeSession it instead`);
682
+ }
683
+ const cursor = this.#viewCursor;
684
+ if (cursor === undefined) {
685
+ throw new Error(`session ${this.sessionId} has folded no view cursor to reload from; resumeSession it instead`);
686
+ }
687
+ const config = options.config == null ? undefined : forwardedConfig("session/resume", options.config, this.#granted);
688
+ // A running fill holds live frames the replay will repeat.
689
+ this.#replayed = new Set(this.#gaps.heldCursors());
690
+ this.#replayAnswered = false;
691
+ try {
692
+ const raw = await connection.command("session/resume", {
693
+ sessionId: this.sessionId,
694
+ cursor,
695
+ ...(config === undefined ? {} : { config }),
696
+ });
697
+ const result = resumeResultOf(raw);
698
+ this.#replayAnswered = true;
699
+ if (result.history.noneReason !== "cursorSuffix")
700
+ this.#reloadGap = true;
701
+ return result;
702
+ }
703
+ catch (error) {
704
+ this.#replayed = undefined;
705
+ throw error;
706
+ }
707
+ }
316
708
  /** Observe SS4.8 fills that did not complete. See `MuseGapFillError`. */
317
709
  onGapError(handler) {
318
710
  this.#gaps.onError(handler);
@@ -326,6 +718,11 @@ export class Session {
326
718
  * downstream — the fold, the iterators, and the SS4.13 retirements.
327
719
  */
328
720
  #foldAndRoute(event, sink) {
721
+ const cursor = resumeCursorOf(event);
722
+ if (cursor !== undefined) {
723
+ this.#viewCursor = cursor;
724
+ this.#replayed?.add(cursor);
725
+ }
329
726
  const retirements = [];
330
727
  const tasks = sink.tasks;
331
728
  // A re-sent `approval/request` server request skips the fold, which lists
@@ -384,13 +781,17 @@ export class Session {
384
781
  // later be retired `terminalUnknown` by a discharge, which would be a
385
782
  // fabricated annotation about a command whose fate is known.
386
783
  const reclaimed = this.#pending.observedReclaim(known.params.commandId);
387
- if (reclaimed !== undefined) {
784
+ if (reclaimed === undefined)
785
+ break;
786
+ // FR-81734-1: under `MuseClient` this session's own in-flight unqueue
787
+ // for the turn is where it lands. Held INSTEAD of returned, so no
788
+ // outcome, live or spliced into a gap's `io`, carries it a second time.
789
+ if (this.#applyResultsDropped && this.#unqueuesInFlight.has(known.params.turnId)) {
790
+ this.#submit.forgetRetired([reclaimed]);
791
+ this.#heldReclaims.set(known.params.turnId, reclaimed);
792
+ }
793
+ else {
388
794
  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
795
  }
395
796
  break;
396
797
  }
@@ -571,6 +972,7 @@ export class Session {
571
972
  this.#deathError = died;
572
973
  for (const handle of this.#turns.values())
573
974
  handle.fail(died);
975
+ this.#finishEventStreams((stream) => stream.fail(died));
574
976
  this.#discharge = { exit, kind: "durableDeath", profile };
575
977
  return this.#discharge;
576
978
  }
@@ -578,6 +980,7 @@ export class Session {
578
980
  const terminalUnknownItems = this.#fold.markEphemeralHostDeath(isItemInProgress);
579
981
  for (const handle of this.#turns.values())
580
982
  handle.settleTerminalUnknown();
983
+ this.#finishEventStreams((stream) => stream.end());
581
984
  // SS2.13.3b "do not attempt to reattach". `discardEphemeral` already wrote
582
985
  // the commandIds into the shared set (it holds it by reference); the
583
986
  // sessionId is this layer's to record, because the pending set does not
@@ -733,10 +1136,12 @@ export class Session {
733
1136
  * Submit feedback about this session (`feedback/submit`). The host
734
1137
  * serves it only when the spawn requested the `feedback` capability
735
1138
  * (`requestedCapabilities: ["feedback"]`) and install policy allows
736
- * it; without that grant the host refuses the command.
1139
+ * it; without that grant the host refuses the call. Its wire params
1140
+ * define no `commandId` (each call is one submit; the wire contract
1141
+ * attaches no dedup), so it rides `request()` and mints none.
737
1142
  */
738
1143
  async submitFeedback(input) {
739
- const ack = await this.#requireLiveConnection("submitFeedback").command("feedback/submit", {
1144
+ const ack = await this.#requireLiveConnection("submitFeedback").request("feedback/submit", {
740
1145
  ...input,
741
1146
  sessionId: this.sessionId,
742
1147
  });
@@ -1024,3 +1429,4 @@ export class Session {
1024
1429
  this.#handle(held.turnId).pushDelta(params);
1025
1430
  }
1026
1431
  }
1432
+ _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
  /**