@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.
@@ -68,6 +68,8 @@ export declare class GapFiller<I> {
68
68
  onError(handler: GapFillFailureHandler): void;
69
69
  /** Hold one live frame until the paged prefix is in. */
70
70
  hold(frame: WireFrame): void;
71
+ /** The cursors of the live frames held for the running fill, in arrival order. */
72
+ heldCursors(): string[];
71
73
  /**
72
74
  * Recover the fold's outstanding hole.
73
75
  *
@@ -104,6 +104,16 @@ export class GapFiller {
104
104
  hold(frame) {
105
105
  this.#buffer.push(frame);
106
106
  }
107
+ /** The cursors of the live frames held for the running fill, in arrival order. */
108
+ heldCursors() {
109
+ const cursors = [];
110
+ for (const frame of this.#buffer) {
111
+ const cursor = _a.#viewCursorOf(frame);
112
+ if (cursor !== undefined)
113
+ cursors.push(cursor);
114
+ }
115
+ return cursors;
116
+ }
107
117
  /**
108
118
  * Recover the fold's outstanding hole.
109
119
  *
@@ -280,8 +290,7 @@ export class GapFiller {
280
290
  limit: PAGE_LIMIT,
281
291
  sessionId: this.#options.sessionId,
282
292
  };
283
- const raw = await connection.request("view/page", params);
284
- return raw;
293
+ return await connection.request("view/page", params);
285
294
  }
286
295
  /**
287
296
  * A page that serves another session's events aborts the fill.
@@ -105,7 +105,11 @@ export declare function isItemInProgress(item: Item): boolean;
105
105
  export type AbnormalExit = Exclude<HostDeathNotification, {
106
106
  kind: "cleanShutdown";
107
107
  }>;
108
- /** A durable host died abnormally: its terminals arrive on resume (FM-001). */
108
+ /**
109
+ * The host died abnormally. On a session it means a durable host died and its
110
+ * terminals arrive on resume (FM-001); as the `cause` of a failed call, it
111
+ * reports how any host ended.
112
+ */
109
113
  export declare class MuseHostDiedError extends Error {
110
114
  #private;
111
115
  readonly exit: AbnormalExit;
@@ -70,7 +70,11 @@ export function isAbnormalHostDeath(notification) {
70
70
  export function isItemInProgress(item) {
71
71
  return item.status === IN_PROGRESS;
72
72
  }
73
- /** A durable host died abnormally: its terminals arrive on resume (FM-001). */
73
+ /**
74
+ * The host died abnormally. On a session it means a durable host died and its
75
+ * terminals arrive on resume (FM-001); as the `cause` of a failed call, it
76
+ * reports how any host ended.
77
+ */
74
78
  export class MuseHostDiedError extends Error {
75
79
  exit;
76
80
  // The parameter is narrowed rather than checked: `cleanShutdown` is not a
@@ -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
+ import type { FoldExtension } from "../fold/extension.js";
22
23
  import { SessionFold } from "../fold/session-fold.js";
23
24
  import type { FoldOutcome, ViewEvent } from "../fold/session-fold.js";
24
25
  import { PendingCommandSet } from "../pending/pending-command-set.js";
@@ -26,12 +27,12 @@ import type { PendingRetirement, ReplayAnswer, SnapshotJoinFacts } from "../pend
26
27
  import type { Connection } from "../connection/connection.js";
27
28
  import type { ApprovalFailureHandler, ApprovalHandler } from "./approval.js";
28
29
  import type { SendUserTurnOptions } from "./turn-submit.js";
29
- import type { GapFillFailureHandler } from "./gap-fill.js";
30
+ import type { GapFillFailureHandler, WireFrame } from "./gap-fill.js";
30
31
  import type { DiscardedSessions } from "./discarded.js";
31
32
  import type { HostDeathDischarge, HostDeathNotification, SessionDurabilityProfile } from "./host-death.js";
32
- import type { Turn } from "./turn-handle.js";
33
+ import type { FoldedItem, Turn } from "./turn-handle.js";
33
34
  import type { RunOptions, RunResult } from "./run.js";
34
- import type { ApprovalMode, CommandAcceptedResult, FeedbackSubmitParams, FeedbackSubmitResult, HookListResult, ModelSelection, PluginInstallResult, PluginInstallTarget, PluginListResult, ReasoningEffort, RecapRequestResult, SessionCompactParams, SessionCompactResult, SessionForkParams, SessionForkResult, SessionLeaveParams, SessionLeaveResult, SessionRenameResult, SessionResumeResult, SessionSetApprovalModeResult, SessionSetModelResult, SessionSetReasoningEffortResult, SessionSideChatResult, SessionStartResult, SkillListResult, SkillSetActivationParams, SkillSetActivationResult, SubagentOwnerReasonParams, TaskListResult, TurnInputPart, UserInputAnswer, UserInputAnswerResult, WorkflowControlResult, WorkflowResumeResult } from "../msp.js";
35
+ import type { ApprovalMode, CommandAcceptedResult, FeedbackSubmitParams, FeedbackSubmitResult, HookListResult, ModelSelection, PluginInstallResult, PluginInstallTarget, PluginListResult, ReasoningEffort, RecapRequestResult, SessionCompactParams, SessionCompactResult, SessionForkParams, SessionForkResult, SessionLeaveParams, SessionLeaveResult, SessionRenameResult, SessionResumeResult, SessionSetApprovalModeResult, SessionSetModelResult, SessionSetReasoningEffortResult, SessionSideChatResult, SessionStartResult, SkillListResult, SkillSetActivationParams, SkillSetActivationResult, SessionResumeParams, SubagentOwnerReasonParams, TaskListResult, TurnInputPart, UserInputAnswer, UserInputAnswerResult, WorkflowControlResult, WorkflowResumeResult } from "../msp.js";
35
36
  /**
36
37
  * Which verb opened this session, and what it answered.
37
38
  *
@@ -50,6 +51,13 @@ export type SessionOpening = {
50
51
  };
51
52
  /** The optional reason `interruptSubagent`/`stopSubagent`/`closeSubagent` record. */
52
53
  export type SubagentReasonOptions = Readonly<Pick<SubagentOwnerReasonParams, "reason">>;
54
+ /**
55
+ * Options for `reload()`. `config` is forwarded on the `session/resume` it
56
+ * sends, behind the same `sessionMcp` grant check as `resumeSession`'s
57
+ * (FR-79107-3). Explicit: after an idle unload the caller supplies its
58
+ * additions again (ADR 32760), and the opening's config is never re-sent for it.
59
+ */
60
+ export type ReloadOptions = Readonly<Pick<SessionResumeParams, "config">>;
53
61
  /**
54
62
  * Options for constructing a `Session` directly. Sessions opened through
55
63
  * `MuseClient` are configured for you; build one yourself when you manage
@@ -80,6 +88,12 @@ export interface SessionOptions {
80
88
  readonly discarded?: DiscardedSessions;
81
89
  /** Set by `MuseClient`; see {@link SessionOpening}. */
82
90
  readonly opening?: SessionOpening;
91
+ /**
92
+ * Fold extensions for this session (FR-97527-3), consulted inside the
93
+ * one apply path. `MuseClient` forwards its own list here for every
94
+ * session it opens, so one registration covers both planes.
95
+ */
96
+ readonly extensions?: readonly FoldExtension[];
83
97
  }
84
98
  /**
85
99
  * The fold as a consumer may READ it.
@@ -147,6 +161,17 @@ export interface SessionGapOverlap {
147
161
  readonly method: string;
148
162
  readonly viewCursor: string;
149
163
  }
164
+ /**
165
+ * A frame `reload()`'s replay repeats (#97920): its cursor already reached
166
+ * this session during the reload, from the replay or the live stream. Refused
167
+ * by cursor equality, because folding it again would append an `item/delta`
168
+ * twice.
169
+ */
170
+ export interface SessionReplayDuplicate {
171
+ readonly kind: "ignoredReplayDuplicate";
172
+ readonly method: string;
173
+ readonly viewCursor: string;
174
+ }
150
175
  /**
151
176
  * What one `Session.apply` did: the fold's own outcome, plus any SS4.13
152
177
  * pending-command retirements the event triggered.
@@ -174,7 +199,7 @@ export interface SessionGapOverlap {
174
199
  * restarted walk's work settles on this frame's `io`.
175
200
  */
176
201
  export interface SessionApplyOutcome<I> {
177
- readonly fold: FoldOutcome | SessionApplyRefusal | SessionGapBuffered | SessionGapOverlap;
202
+ readonly fold: FoldOutcome | SessionApplyRefusal | SessionGapBuffered | SessionGapOverlap | SessionReplayDuplicate;
178
203
  readonly retirements: readonly PendingRetirement<I>[];
179
204
  /**
180
205
  * The client->server I/O this event triggered, settled — the SS4.13 replays
@@ -196,6 +221,62 @@ export interface SessionApplyOutcome<I> {
196
221
  */
197
222
  readonly io: Promise<readonly PendingRetirement<I>[]>;
198
223
  }
224
+ /**
225
+ * One inbound frame as a session applies it: a view notification, a frame an
226
+ * SS4.8 fill spliced in from a page, or the frame a re-sent server request is
227
+ * folded as (`approval/request` as itself, `userInput/request` as its
228
+ * `userInput/requested` twin).
229
+ */
230
+ export type ViewFrame = WireFrame;
231
+ /**
232
+ * One event a session folded, as `Session.events()` yields it: the event and
233
+ * what folding it changed, self-contained because the loop body may run after
234
+ * later events folded (FR-97336-1). Optional members may be added; a consumer
235
+ * reads the ones it knows.
236
+ */
237
+ export interface SessionEvent<I = unknown> {
238
+ /** The protocol event, as the session applied it. */
239
+ readonly frame: ViewFrame;
240
+ /**
241
+ * What it changed: the value `Session.apply` returned for a live event. An
242
+ * event a gap fill spliced in carries its fold result and no retirements or
243
+ * I/O of its own: those settle on the `view/gap` event's `io`.
244
+ */
245
+ readonly outcome: SessionApplyOutcome<I>;
246
+ /** For an item event that changed the item: the item as it stood after this event. */
247
+ readonly item?: FoldedItem;
248
+ /**
249
+ * Set on a sub-agent's event, yielded by `events({ subagents: true })`: the
250
+ * sub-agent it belongs to. Its `frame`, `outcome` and `item` are the
251
+ * sub-agent's own.
252
+ */
253
+ readonly subagent?: SessionEventSubagent;
254
+ }
255
+ /** The sub-agent a `SessionEvent` belongs to. */
256
+ export interface SessionEventSubagent {
257
+ /** The parent session's `subagent` item for it. */
258
+ readonly itemId: string;
259
+ /** The sub-agent's durable id, which the `subagent/*` control verbs take. */
260
+ readonly subagentId: string;
261
+ /** The sub-agent's own session, which the event came from. */
262
+ readonly childSessionId: string;
263
+ }
264
+ /** Options for `Session.events()`. */
265
+ export interface SessionEventsOptions {
266
+ /** Aborting it ends the stream, as `return()` does. */
267
+ readonly signal?: AbortSignal;
268
+ /**
269
+ * Also yield each running sub-agent's events, tagged with `subagent`, in
270
+ * arrival order with this session's own. The client follows each
271
+ * sub-agent's session while such a stream is open. Needs a session
272
+ * `MuseClient` opened. Known limitation: if the host refuses the
273
+ * subscription to a sub-agent (usually because it already finished), its
274
+ * steps do not arrive and no reason is given; its start and result still
275
+ * arrive on the session. A sub-agent resumed after it finished a turn is
276
+ * not subscribed again.
277
+ */
278
+ readonly subagents?: boolean;
279
+ }
199
280
  /**
200
281
  * One conversation with the agent.
201
282
  *
@@ -231,6 +312,51 @@ export declare class Session<I = unknown> {
231
312
  readonly method: string;
232
313
  readonly params?: unknown;
233
314
  }): SessionApplyOutcome<I>;
315
+ /**
316
+ * Every event this session folds from now on, with what it changed
317
+ * (FR-97336-1). Live from the call, never replayed: read `fold`, then call
318
+ * this in the same tick, and nothing is missed, including the events
319
+ * folded while `startSession`/`resumeSession` was in flight. Each folded
320
+ * event is yielded once, in arrival order; the events a gap fill splices in
321
+ * are yielded when applied, in order. Buffered like `turn.items()`, so a slow
322
+ * reader never holds folding up.
323
+ *
324
+ * With `{ subagents: true }` on a session `MuseClient` did not open it
325
+ * throws a plain `Error`.
326
+ *
327
+ * `break`, `return()` or `options.signal` ends it, and so does an orderly
328
+ * `MuseClient.close()` (a stream created afterwards ends at once). It finishes the way a
329
+ * turn's `items()` does when the host dies: it ends after an ephemeral
330
+ * host's death, and rejects with `MuseHostDiedError` after a durable one's,
331
+ * once the events it already buffered are read.
332
+ */
333
+ events(options?: SessionEventsOptions): AsyncIterableIterator<SessionEvent<I>>;
334
+ /**
335
+ * Catch this session up in place (#97920): send `session/resume` with the
336
+ * cursor of the last view notification it folded, so the host loads the
337
+ * session if it was unloaded, re-attaches this connection, and streams the
338
+ * suffix after that cursor into THIS session. Its fold, handlers and
339
+ * pending turns stay; a frame the suffix repeats is dropped
340
+ * (`ignoredReplayDuplicate`). Resolves to the resume result once the host
341
+ * replies. Concurrent calls share one resume; a call with `config` while
342
+ * one is in flight is refused (plain `Error`) rather than dropped. `opening`
343
+ * still holds the original open's result. See {@link ReloadOptions}.
344
+ *
345
+ * The fold is caught up only when `result.history.noneReason` is
346
+ * `"cursorSuffix"`. Any other reply (a snapshot for a cursor older than the
347
+ * host keeps, a history budget) means the host served history instead of
348
+ * the missed events, and what streams after it folds over that gap; later
349
+ * reloads then refuse (plain `Error`) before sending: `resumeSession` it
350
+ * instead, for a new `Session` with a fresh fold.
351
+ *
352
+ * Use it before the next command on a session the host may have unloaded
353
+ * (`session/closed`). Refused before anything is sent when the session has
354
+ * folded no cursor yet (plain `Error`): a resume without one would not
355
+ * catch the fold up. A discarded session refuses as every verb does. A
356
+ * refused or failed reload leaves the fold, the other verbs and later
357
+ * reloads usable, except after a reply that was not a cursor suffix (above).
358
+ */
359
+ reload(options?: ReloadOptions): Promise<SessionResumeResult>;
234
360
  /** Observe SS4.8 fills that did not complete. See `MuseGapFillError`. */
235
361
  onGapError(handler: GapFillFailureHandler): void;
236
362
  /**
@@ -307,7 +433,9 @@ export declare class Session<I = unknown> {
307
433
  * Submit feedback about this session (`feedback/submit`). The host
308
434
  * serves it only when the spawn requested the `feedback` capability
309
435
  * (`requestedCapabilities: ["feedback"]`) and install policy allows
310
- * it; without that grant the host refuses the command.
436
+ * it; without that grant the host refuses the call. Its wire params
437
+ * define no `commandId` (each call is one submit; the wire contract
438
+ * attaches no dedup), so it rides `request()` and mints none.
311
439
  */
312
440
  submitFeedback(input: Omit<FeedbackSubmitParams, "sessionId">): Promise<FeedbackSubmitResult>;
313
441
  /**