@muse-code/sdk 1.4.15 → 1.4.20

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -36,20 +36,39 @@
36
36
  * it is forwarded (or explicitly allow-listed as unforwardable).
37
37
  */
38
38
  import { discoverMuseBin } from "../connection/discovery.js";
39
- import { initializeAnswered, spawnMspConnection } from "../connection/spawn.js";
39
+ import { initializeAnswered, SIGTERM_GRACE_MS, spawnMspConnection } from "../connection/spawn.js";
40
40
  import { MuseCapabilityNotGrantedError, MuseFacadeOwnedMethodError, MuseSessionDiscardedError, PermissionProfileNotApplied, } from "../errors.js";
41
41
  import { DiscardedSessions } from "./discarded.js";
42
- import { isAbnormalHostDeath, readSessionDurability } from "./host-death.js";
43
- import { MspError, ProtocolError } from "../connection/connection.js";
42
+ import { fireExtensions } from "../fold/extension.js";
43
+ import { isAbnormalHostDeath, MuseHostDiedError, readSessionDurability } from "./host-death.js";
44
+ import { MspError, peerEndCause, ProtocolError } from "../connection/connection.js";
44
45
  import { hostStartFailure } from "./host-start.js";
45
46
  import { pumpDropsApplyResults, Session } from "./session.js";
47
+ /**
48
+ * Run a caller's observer so neither its throw nor an async observer's
49
+ * rejection escapes: in the read loop a throw ends the connection every session
50
+ * shares, and an unhandled rejection kills the embedder.
51
+ */
52
+ function observe(call, onFailure) {
53
+ let result;
54
+ try {
55
+ result = call();
56
+ }
57
+ catch (error) {
58
+ onFailure(error);
59
+ return;
60
+ }
61
+ if (typeof result?.then === "function") {
62
+ result.then(undefined, onFailure);
63
+ }
64
+ }
46
65
  /**
47
66
  * Every `StartParams` member `startSession` forwards. `config` is forwarded
48
67
  * only behind the `sessionMcp` grant check (`#forwardConfig`),
49
- * `previousSessionId` is excluded because the facade starts root sessions
50
- * (the predecessor link belongs to a client that switches sessions, as does
51
- * the `switchPolicy` member), and `spawnedBy` because the facade does not
52
- * expose a spawner yet.
68
+ * `previousSessionId` and `clear` are excluded because the facade starts root
69
+ * sessions (the predecessor link and the `/clear` marker belong to a client
70
+ * that switches sessions, as does the `switchPolicy` member), and `spawnedBy`
71
+ * because the facade does not expose a spawner yet.
53
72
  */
54
73
  const START_FORWARDED = [
55
74
  "approvalMode",
@@ -100,6 +119,14 @@ const FACADE_OWNED_METHODS = [
100
119
  "view/subscribe",
101
120
  "view/unsubscribe",
102
121
  ];
122
+ /**
123
+ * The stable facade-owned methods, and only those. The experimental host
124
+ * stop (`host/shutdown`) is the orderly stop `close()` owns too, and the
125
+ * Python twin refuses it, but this package names no experimental-only
126
+ * method: FR-97527-5's leak gate derives that set from the two schema
127
+ * bundles at check time, and a refusal list counts as naming (#99842). A
128
+ * caller that sends it raw owns the host exit that follows.
129
+ */
103
130
  const FACADE_OWNED = new Set(FACADE_OWNED_METHODS);
104
131
  /** Every `SessionListParams` member `listSessions` forwards. */
105
132
  const LIST_FORWARDED = ["cursor", "filter", "limit", "updatedAfter", "workspaceRoot"];
@@ -141,8 +168,18 @@ export class MuseClient {
141
168
  #connection;
142
169
  #durability;
143
170
  #discarded;
171
+ #extensions;
144
172
  /** Sessions this client opened, so one death notification reaches them all. */
145
173
  #sessions = new Set();
174
+ /** `onNotification` subscriptions, one entry each so a function added twice unsubscribes once per call. */
175
+ #listeners = new Set();
176
+ #notificationFailureHandlers = new Set();
177
+ #protocolErrorHandlers = new Set();
178
+ /**
179
+ * Set on the first `onProtocolError`, which then claims the connection's one
180
+ * handler: a client nobody observes leaves the caller's own handler alone.
181
+ */
182
+ #protocolErrorsClaimed = false;
146
183
  /**
147
184
  * Frames naming a session this client has not registered YET, held only
148
185
  * while a `session/start`/`session/resume` is in flight (#49790): the host
@@ -172,6 +209,7 @@ export class MuseClient {
172
209
  // no current consumer spans two clients over one host lineage, so a
173
210
  // sharing knob would be declared-ahead surface (Constitution XI).
174
211
  this.#discarded = new DiscardedSessions();
212
+ this.#extensions = options.extensions ?? [];
175
213
  this.#child = options.host?.child;
176
214
  this.#initializeResult = options.host?.initializeResult;
177
215
  // THE ONE INBOUND PUMP (FR-018/FR-019). `Session.apply` is the only event
@@ -179,9 +217,14 @@ export class MuseClient {
179
217
  // consumer has no way to hear a single view frame: every turn wait hangs
180
218
  // (SS3.1.4) and `onApproval` can never fire. `Connection.onNotification`
181
219
  // holds ONE handler — this client claims it, which is part of what
182
- // "MuseClient owns the connection" means; a consumer that needs the raw
183
- // feed builds around a bare `Connection` and `Session` instead.
184
- this.#connection.onNotification((notification) => this.#route(notification));
220
+ // "MuseClient owns the connection" means; a caller hears the feed through
221
+ // `onNotification`, after `#route` has handed each frame to its session
222
+ // (a frame held while that session's open is in flight is heard first).
223
+ this.#connection.onNotification((notification) => {
224
+ this.#route(notification);
225
+ for (const entry of [...this.#listeners])
226
+ this.#notify(entry.listener, notification);
227
+ });
185
228
  // A question or approval still open at resume is re-sent as a
186
229
  // `userInput/request` or `approval/request` server request (tdd SS5.6,
187
230
  // SS5.10). Each is routed in arrival order and answered with the SS5.3.3
@@ -209,23 +252,31 @@ export class MuseClient {
209
252
  // Registered at construction, not at the first session: an EOF can land
210
253
  // before any session exists, and the flag has to be read at that moment.
211
254
  void this.#connection.closed.then(() => this.#transportClosed());
255
+ // A call the connection fails because the host died says how it ended;
256
+ // read at the EOF, so a close() of ours leaves the bare error.
257
+ this.#connection[peerEndCause](() => this.#hostDeathCause());
212
258
  }
213
259
  /**
214
260
  * Deliver one view notification to the session(s) it names.
215
261
  *
216
- * A frame naming NO session is dropped here rather than fed to every
217
- * session: `Session.apply` already tolerates unknown methods, but only the
218
- * frames that name a `sessionId` have an owner to route to. A frame naming
219
- * an UNKNOWN session is dropped for the same reason — routing it anywhere
220
- * would trip the foreign-frame throw on a session it does not belong to —
221
- * UNLESS an open is in flight, when it may be that open's own session named
222
- * by the server before the awaiting promise has run (#49790): then it is
223
- * held for `#openSession` to fold, or for `#open` to clear.
262
+ * A frame naming NO session goes to the connection extensions (FR-97527-3:
263
+ * host-wide state names no session) rather than to every session:
264
+ * `Session.apply` already tolerates unknown methods, but only the
265
+ * frames that name a `sessionId` have a session owner to route to. A frame
266
+ * naming an UNKNOWN session is dropped for the same reason — routing it
267
+ * anywhere would trip the foreign-frame throw on a session it does not
268
+ * belong to — UNLESS an open is in flight, when it may be that open's own
269
+ * session named by the server before the awaiting promise has run (#49790):
270
+ * then it is held for `#openSession` to fold, or for `#open` to clear.
224
271
  */
225
272
  #route(notification) {
226
273
  const named = notification.params?.sessionId;
227
- if (typeof named !== "string")
274
+ if (typeof named !== "string") {
275
+ // FR-97527-3: connection extensions share the fold's call-and-report
276
+ // loop, objects-only guard included.
277
+ fireExtensions(this.#extensions, notification.method, notification.params);
228
278
  return;
279
+ }
229
280
  let delivered = false;
230
281
  for (const session of this.#sessions) {
231
282
  if (session.sessionId === named) {
@@ -241,6 +292,16 @@ export class MuseClient {
241
292
  else
242
293
  held.push(notification);
243
294
  }
295
+ /** Call one listener, sending its throw or rejection to every `onNotificationError` handler. */
296
+ #notify(listener, notification) {
297
+ observe(() => listener(notification), (error) => {
298
+ // A failure observer failing too is swallowed: like
299
+ // `ApprovalRouter.#report`, there is no one left to tell.
300
+ for (const entry of [...this.#notificationFailureHandlers]) {
301
+ observe(() => entry.handler(error, notification), () => undefined);
302
+ }
303
+ });
304
+ }
244
305
  /**
245
306
  * Spawn an owned host, run the SS1.4 handshake, and hand back a client whose
246
307
  * durability profile came from that handshake (FR-018).
@@ -275,6 +336,7 @@ export class MuseClient {
275
336
  ...(options.shutdownTimeoutMs === undefined
276
337
  ? {}
277
338
  : { shutdownTimeoutMs: options.shutdownTimeoutMs }),
339
+ ...(options.spawnFn === undefined ? {} : { spawnFn: options.spawnFn }),
278
340
  });
279
341
  let spawned;
280
342
  try {
@@ -306,6 +368,7 @@ export class MuseClient {
306
368
  }
307
369
  return new MuseClient(spawned.connection, {
308
370
  durability: readSessionDurability(spawned.initializeResult),
371
+ ...(options.extensions === undefined ? {} : { extensions: options.extensions }),
309
372
  host: spawned,
310
373
  });
311
374
  }
@@ -332,6 +395,72 @@ export class MuseClient {
332
395
  }
333
396
  return this.#child.exit;
334
397
  }
398
+ /**
399
+ * Settles when the connection closes for any reason: `close()`, the host
400
+ * hanging up, or a transport failure.
401
+ */
402
+ get closed() {
403
+ return this.#connection.closed;
404
+ }
405
+ /**
406
+ * Hear every server notification in wire order, including those naming no
407
+ * session (`usage/changed`, `account/loginCompleted`) or a session this
408
+ * client did not open. A frame naming a session this client has opened
409
+ * reaches the listener after that session has applied it: folded, or, while
410
+ * the session fills a gap, buffered and folded when the fill completes. One
411
+ * that arrives while its session's start/resume is still in flight reaches
412
+ * the listener first, and the session folds it before the verb returns.
413
+ * Returns the unsubscribe function.
414
+ *
415
+ * The frame is read-only: it is the one the session folds, which for a held
416
+ * or buffered frame happens after the listener runs. Like a `Connection`
417
+ * handler, the listener runs in the read loop, so it must not block. A throw, or an async listener's rejection, goes to every
418
+ * `onNotificationError` handler; the other listeners still hear the frame
419
+ * and the connection stays open.
420
+ */
421
+ onNotification(listener) {
422
+ const entry = { listener };
423
+ this.#listeners.add(entry);
424
+ return () => {
425
+ this.#listeners.delete(entry);
426
+ };
427
+ }
428
+ /**
429
+ * Hear what an `onNotification` listener threw or rejected with. With no
430
+ * handler the failure is dropped; either way the pump keeps running.
431
+ * Returns a function that removes this one subscription.
432
+ */
433
+ onNotificationError(handler) {
434
+ const entry = { handler };
435
+ this.#notificationFailureHandlers.add(entry);
436
+ return () => {
437
+ this.#notificationFailureHandlers.delete(entry);
438
+ };
439
+ }
440
+ /**
441
+ * Hear each framing or correlation violation the connection detects
442
+ * (`Connection.onProtocolError`). The handler's own throw or rejection is
443
+ * swallowed rather than ending the connection; it is already the observer
444
+ * of failures, so there is no one left to tell. The first call takes over
445
+ * `Connection.onProtocolError`, replacing a handler set there directly (and
446
+ * a later direct `connection.onProtocolError(...)` silences these
447
+ * subscribers). Returns a function that removes this one subscription.
448
+ */
449
+ onProtocolError(handler) {
450
+ if (!this.#protocolErrorsClaimed) {
451
+ this.#protocolErrorsClaimed = true;
452
+ this.#connection.onProtocolError((error) => {
453
+ for (const entry of [...this.#protocolErrorHandlers]) {
454
+ observe(() => entry.handler(error), () => undefined);
455
+ }
456
+ });
457
+ }
458
+ const entry = { handler };
459
+ this.#protocolErrorHandlers.add(entry);
460
+ return () => {
461
+ this.#protocolErrorHandlers.delete(entry);
462
+ };
463
+ }
335
464
  /** The durability profile every session this client opens inherits. */
336
465
  get durability() {
337
466
  return this.#durability;
@@ -445,17 +574,14 @@ export class MuseClient {
445
574
  * (see `Session.listTasks`).
446
575
  */
447
576
  async listSessions(options = {}) {
577
+ // One list drives both the exhaustiveness pin and the forwarding, so a
578
+ // regenerated member cannot compile yet be dropped on the wire (#76737).
448
579
  const params = {};
449
- if (options.cursor != null)
450
- params["cursor"] = options.cursor;
451
- if (options.filter != null)
452
- params["filter"] = options.filter;
453
- if (options.limit != null)
454
- params["limit"] = options.limit;
455
- if (options.updatedAfter != null)
456
- params["updatedAfter"] = options.updatedAfter;
457
- if (options.workspaceRoot != null)
458
- params["workspaceRoot"] = options.workspaceRoot;
580
+ for (const member of LIST_FORWARDED) {
581
+ const value = options[member];
582
+ if (value != null)
583
+ params[member] = value;
584
+ }
459
585
  const ack = await this.#connection.request("session/list", params);
460
586
  return ack;
461
587
  }
@@ -481,20 +607,27 @@ export class MuseClient {
481
607
  }
482
608
  /**
483
609
  * Send a wire method directly (FR-79107-2), typically one the facade does
484
- * not wrap, through the
610
+ * not wrap, experimental ones included, through the
485
611
  * same `Connection.command()` the verbs use: the connection mints the
486
612
  * `commandId`, retries a nothing-admitted refusal under the same id, and
487
- * checks the ack's echo. `options` are that seam's own.
613
+ * checks the ack's echo. `options` are that seam's own. An experimental
614
+ * method needs a client spawned with `capabilities: { experimentalApi: true }`
615
+ * (otherwise the host refuses it with an `MspError` of kind
616
+ * `experimentalRequired`, code -32601) and may change without notice.
488
617
  *
489
618
  * Refused before anything is written, with `MuseFacadeOwnedMethodError`:
490
- * the methods whose state the facade owns (`FACADE_OWNED_METHODS`). Frames
619
+ * the methods whose state the facade owns (`FACADE_OWNED_METHODS`); the
620
+ * experimental host stop is not among them (this package names no
621
+ * experimental-only method), so sent raw it is the caller's own, and the
622
+ * exit it causes reaches your sessions as a host death; `close()` is the
623
+ * orderly stop. Frames
491
624
  * the command causes still reach your sessions through the client's one
492
625
  * inbound pump; this sends and returns the ack, nothing more. Params and
493
626
  * ack stay untyped objects: the generated types carry no method-to-params
494
627
  * map, and restating one here would drift from the schema.
495
628
  *
496
629
  * Each call keeps one fixed-size fingerprint for the connection's lifetime
497
- * (FR-45137-1), so prefer a facade verb for a query you poll.
630
+ * (FR-45137-1), so prefer `request` for a query you poll.
498
631
  */
499
632
  async command(method, params, options) {
500
633
  // The type binds TypeScript callers; this binds plain-JS ones.
@@ -502,6 +635,18 @@ export class MuseClient {
502
635
  throw new MuseFacadeOwnedMethodError(method);
503
636
  return this.#connection.command(method, params, options);
504
637
  }
638
+ /**
639
+ * Send a wire request directly (FR-79107-2), typically a query the facade
640
+ * does not wrap, experimental ones included, through `Connection.request()`:
641
+ * no `commandId`, no retry, and omitted `params` stay off the frame.
642
+ * Refuses the same facade-owned methods as `command`, the same way, and
643
+ * needs the same `experimentalApi` opt-in for an experimental method.
644
+ */
645
+ async request(method, params) {
646
+ if (FACADE_OWNED.has(method))
647
+ throw new MuseFacadeOwnedMethodError(method);
648
+ return this.#connection.request(method, params);
649
+ }
505
650
  /**
506
651
  * Shut the host down in an orderly way (SS2.1.2); the shutdown this causes
507
652
  * is not reported to your sessions as a host death.
@@ -553,6 +698,7 @@ export class MuseClient {
553
698
  connection: this.#connection,
554
699
  discarded: this.#discarded,
555
700
  durability: this.#durability,
701
+ extensions: this.#extensions,
556
702
  opening,
557
703
  sessionId,
558
704
  });
@@ -604,6 +750,20 @@ export class MuseClient {
604
750
  #survivesHostDeath() {
605
751
  return this.#durability.kind === "durable";
606
752
  }
753
+ /**
754
+ * Waits for the exit at most `SIGTERM_GRACE_MS`: a host that closed stdout
755
+ * but keeps running must not hold the failed calls past today's bare error.
756
+ */
757
+ #hostDeathCause() {
758
+ if (this.#closing || this.#child === undefined)
759
+ return undefined;
760
+ const died = this.#child.exit.then((exit) => (isAbnormalHostDeath(exit) ? new MuseHostDiedError(exit) : undefined), () => undefined);
761
+ let timer;
762
+ const grace = new Promise((resolve) => {
763
+ timer = setTimeout(resolve, SIGTERM_GRACE_MS, undefined);
764
+ });
765
+ return Promise.race([died, grace]).finally(() => clearTimeout(timer));
766
+ }
607
767
  /**
608
768
  * The transport reached EOF. If this client did not cause it, that is
609
769
  * SS2.13.3b's second death notification (T030 obligation b) and every session
@@ -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,10 +27,10 @@ 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
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, SubagentOwnerReasonParams, TaskListResult, TurnInputPart, UserInputAnswer, UserInputAnswerResult, WorkflowControlResult, WorkflowResumeResult } from "../msp.js";
35
36
  /**
@@ -80,6 +81,12 @@ export interface SessionOptions {
80
81
  readonly discarded?: DiscardedSessions;
81
82
  /** Set by `MuseClient`; see {@link SessionOpening}. */
82
83
  readonly opening?: SessionOpening;
84
+ /**
85
+ * Fold extensions for this session (FR-97527-3), consulted inside the
86
+ * one apply path. `MuseClient` forwards its own list here for every
87
+ * session it opens, so one registration covers both planes.
88
+ */
89
+ readonly extensions?: readonly FoldExtension[];
83
90
  }
84
91
  /**
85
92
  * The fold as a consumer may READ it.
@@ -196,6 +203,36 @@ export interface SessionApplyOutcome<I> {
196
203
  */
197
204
  readonly io: Promise<readonly PendingRetirement<I>[]>;
198
205
  }
206
+ /**
207
+ * One inbound frame as a session applies it: a view notification, a frame an
208
+ * SS4.8 fill spliced in from a page, or the frame a re-sent server request is
209
+ * folded as (`approval/request` as itself, `userInput/request` as its
210
+ * `userInput/requested` twin).
211
+ */
212
+ export type ViewFrame = WireFrame;
213
+ /**
214
+ * One event a session folded, as `Session.events()` yields it: the event and
215
+ * what folding it changed, self-contained because the loop body may run after
216
+ * later events folded (FR-97336-1). Optional members may be added; a consumer
217
+ * reads the ones it knows.
218
+ */
219
+ export interface SessionEvent<I = unknown> {
220
+ /** The protocol event, as the session applied it. */
221
+ readonly frame: ViewFrame;
222
+ /**
223
+ * What it changed: the value `Session.apply` returned for a live event. An
224
+ * event a gap fill spliced in carries its fold result and no retirements or
225
+ * I/O of its own: those settle on the `view/gap` event's `io`.
226
+ */
227
+ readonly outcome: SessionApplyOutcome<I>;
228
+ /** For an item event that changed the item: the item as it stood after this event. */
229
+ readonly item?: FoldedItem;
230
+ }
231
+ /** Options for `Session.events()`. */
232
+ export interface SessionEventsOptions {
233
+ /** Aborting it ends the stream, as `return()` does. */
234
+ readonly signal?: AbortSignal;
235
+ }
199
236
  /**
200
237
  * One conversation with the agent.
201
238
  *
@@ -231,6 +268,21 @@ export declare class Session<I = unknown> {
231
268
  readonly method: string;
232
269
  readonly params?: unknown;
233
270
  }): SessionApplyOutcome<I>;
271
+ /**
272
+ * Every event this session folds from now on, with what it changed
273
+ * (FR-97336-1). Live from the call, never replayed: read `fold`, then call
274
+ * this in the same tick, and nothing is missed, including the events
275
+ * folded while `startSession`/`resumeSession` was in flight. Each folded
276
+ * event is yielded once, in arrival order; the events a gap fill splices in
277
+ * are yielded when applied, in order. Buffered like `turn.items()`, so a slow
278
+ * reader never holds folding up.
279
+ *
280
+ * `break`, `return()` or `options.signal` ends it. It finishes the way a
281
+ * turn's `items()` does when the host dies: it ends after an ephemeral
282
+ * host's death, and rejects with `MuseHostDiedError` after a durable one's,
283
+ * once the events it already buffered are read.
284
+ */
285
+ events(options?: SessionEventsOptions): AsyncIterableIterator<SessionEvent<I>>;
234
286
  /** Observe SS4.8 fills that did not complete. See `MuseGapFillError`. */
235
287
  onGapError(handler: GapFillFailureHandler): void;
236
288
  /**
@@ -307,7 +359,9 @@ export declare class Session<I = unknown> {
307
359
  * Submit feedback about this session (`feedback/submit`). The host
308
360
  * serves it only when the spawn requested the `feedback` capability
309
361
  * (`requestedCapabilities: ["feedback"]`) and install policy allows
310
- * it; without that grant the host refuses the command.
362
+ * it; without that grant the host refuses the call. Its wire params
363
+ * define no `commandId` (each call is one submit; the wire contract
364
+ * attaches no dedup), so it rides `request()` and mints none.
311
365
  */
312
366
  submitFeedback(input: Omit<FeedbackSubmitParams, "sessionId">): Promise<FeedbackSubmitResult>;
313
367
  /**