@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.
- package/README.md +78 -2
- package/dist/src/connection/connection.d.ts +83 -6
- package/dist/src/connection/connection.js +113 -14
- package/dist/src/connection/spawn.d.ts +50 -4
- package/dist/src/connection/spawn.js +161 -33
- package/dist/src/connection/surface.d.ts +49 -0
- package/dist/src/connection/surface.js +8 -0
- package/dist/src/errors.d.ts +6 -5
- package/dist/src/errors.js +7 -6
- package/dist/src/facade/approval.js +1 -1
- package/dist/src/facade/client.d.ts +158 -17
- package/dist/src/facade/client.js +370 -74
- package/dist/src/facade/gap-fill.d.ts +2 -0
- package/dist/src/facade/gap-fill.js +11 -2
- package/dist/src/facade/host-death.d.ts +5 -1
- package/dist/src/facade/host-death.js +5 -1
- package/dist/src/facade/session.d.ts +133 -5
- package/dist/src/facade/session.js +419 -13
- package/dist/src/facade/turn-handle.d.ts +23 -0
- package/dist/src/facade/turn-handle.js +1 -1
- package/dist/src/fingerprint.d.ts +79 -4
- package/dist/src/fingerprint.js +110 -11
- package/dist/src/fingerprint.stamped.d.ts +2 -1
- package/dist/src/fingerprint.stamped.js +2 -1
- package/dist/src/fold/extension.d.ts +39 -0
- package/dist/src/fold/extension.js +49 -0
- package/dist/src/fold/session-fold.d.ts +11 -0
- package/dist/src/fold/session-fold.js +13 -0
- package/dist/src/index.d.ts +6 -5
- package/dist/src/index.js +1 -1
- package/dist/src/msp.d.ts +319 -10
- package/package.json +1 -1
|
@@ -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
|
|
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.#
|
|
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:
|
|
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
|
|
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
|
|
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").
|
|
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. */
|