@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
|
@@ -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
|
-
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
|
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
|
/**
|