@robota-sdk/agent-transport 3.0.0-beta.79 → 3.0.0-beta.82

package/dist/node/index.d.ts

@@ -1,28 +1,766 @@
-import { a as IHeadlessRunnerOptions, c as promptInput, i as createHeadlessTransport, l as PrintTerminal, n as IHeadlessInteractionChannelOptions, o as TOutputFormat, r as IHeadlessTransportOptions, s as createHeadlessRunner, t as HeadlessInteractionChannel } from "./index-JTD_xtEQ.js";
-import { n as createProgrammaticAgent, r as ProgrammaticInteractionChannel, t as ICreateProgrammaticAgentOptions } from "./index-y_HBOfzO.js";
-import { IDestroyResult, TUniversalValue } from "@robota-sdk/agent-core";
-import { IConfigurableTransport, IInteractiveSession, ITransportEntry } from "@robota-sdk/agent-interface-transport";
-
-//#region src/transport-registry.d.ts
-declare class TransportRegistry {
-  private readonly entries;
-  private readonly settingsPath;
-  constructor(settingsPath: string);
-  register(transport: IConfigurableTransport<IInteractiveSession>): void;
-  getAll(): ITransportEntry<IInteractiveSession>[];
-  getEnabled(): IConfigurableTransport<IInteractiveSession>[];
-  setEnabled(name: string, enabled: boolean): Promise<void>;
-  setOptions(name: string, options: Record<string, TUniversalValue>): Promise<void>;
-  startAll(session: IInteractiveSession): Promise<void>;
-  /**
-   * Stop every registered transport — **best-effort** (CORE-013 disposal convention): one
-   * transport's stop failure must not skip the others or reject a fire-and-forget caller.
-   * Failures are collected into the returned result.
-   */
-  stopAll(): Promise<IDestroyResult>;
-  private resolveConfig;
-  private readTransportSettings;
-}
-//#endregion
-export { HeadlessInteractionChannel, type ICreateProgrammaticAgentOptions, type IHeadlessInteractionChannelOptions, type IHeadlessRunnerOptions, type IHeadlessTransportOptions, PrintTerminal, ProgrammaticInteractionChannel, type TOutputFormat, TransportRegistry, createHeadlessRunner, createHeadlessTransport, createProgrammaticAgent, promptInput };
+import { IPersonalUsageReport, IPersonalUsageRequest, IUsageBySourceReport, TUsageSurface } from "@robota-sdk/agent-interface-analytics";
+import { ICommandResult } from "@robota-sdk/agent-interface-command";
+import { IBackgroundJobGroupState, IBackgroundTaskInput, IBackgroundTaskListFilter, IBackgroundTaskLogCursor, IBackgroundTaskLogPage, IBackgroundTaskState, IExecutionWorkspaceSnapshot, TBackgroundJobGroupEvent, TBackgroundTaskEvent } from "@robota-sdk/agent-interface-execution";
+import { IAskRequestEvent, IBranchEvent, IContextFileRefreshedEvent, IExecutionResult, IPermissionRequestEvent, IPlanApprovalEvent, IPromptResolvedEvent, ISessionBackgroundGroups, ISessionBackgroundTasks, ISessionCommands, ISessionConversationRead, ISessionDriverAttribution, ISessionEvents, ISessionExecutionState, ISessionExecutionWorkspace, ISessionPromptResolution, ISessionRenamedEvent, ISessionTurnControl, ISessionTurnSubmission, IToolState, IUiIntentEvent, TDriverId, TPermissionResultValue } from "@robota-sdk/agent-interface-session";
+import { IBinaryFrame, IChannelEventFrame, TActionResponse, TChannelReceiveResult } from "@robota-sdk/agent-interface-transport";
+import { IHandoffIntegrity, IPeerMessage, IPeerMessageAck, TPeerDeliveryState } from "@robota-sdk/agent-interface-session-mobility";
+//#region src/wire-messages.d.ts
+type TBackgroundControlAction = 'cancel' | 'close' | 'send';
+/** Inbound message from client to server. */
+type TClientMessage = {
+  type: 'submit';
+  prompt: string;
+} | {
+  type: 'command';
+  name: string;
+  args?: string;
+} | {
+  type: 'abort';
+} | {
+  type: 'cancel-queue';
+} | {
+  type: 'get-messages';
+} | {
+  type: 'get-context';
+} | {
+  type: 'get-usage-report';
+} | {
+  type: 'get-personal-usage-report';
+  requestId: string;
+  period: IPersonalUsageRequest['period'];
+  timezone: string;
+} | {
+  type: 'get-stored-session-usage-report';
+  requestId: string;
+  sessionId: string;
+} | {
+  type: 'get-executing';
+} | {
+  type: 'get-pending';
+} | {
+  type: 'get-execution-workspace';
+} | {
+  type: 'get-background-tasks';
+  filter?: IBackgroundTaskListFilter;
+} | {
+  type: 'get-background-task';
+  taskId: string;
+} | {
+  type: 'get-background-job-groups';
+} | {
+  type: 'get-background-job-group';
+  groupId: string;
+} | {
+  type: 'wait-background-job-group';
+  groupId: string;
+} | {
+  type: 'cancel-background-task';
+  taskId: string;
+  reason?: string;
+} | {
+  type: 'close-background-task';
+  taskId: string;
+} | {
+  type: 'send-background-task';
+  taskId: string;
+  input: IBackgroundTaskInput;
+} | {
+  type: 'read-background-task-log';
+  taskId: string;
+  cursor?: IBackgroundTaskLogCursor;
+} | {
+  type: 'permission-response';
+  id: string;
+  result: TPermissionResultValue;
+} | {
+  type: 'ask-response';
+  id: string;
+  response: TActionResponse;
+} | {
+  type: 'resume';
+  lastSeq: number;
+} | {
+  type: 'ack';
+  seq: number;
+};
+/** Outbound message from server to client. */
+type TServerMessage = {
+  type: 'text_delta';
+  delta: string;
+  driverId?: TDriverId;
+} | {
+  type: 'user_message';
+  content: string;
+  driverId?: TDriverId;
+} | {
+  type: 'tool_start';
+  state: IToolState;
+  driverId?: TDriverId;
+} | {
+  type: 'tool_end';
+  state: IToolState;
+  driverId?: TDriverId;
+} | {
+  type: 'thinking';
+  isThinking: boolean;
+  driverId?: TDriverId;
+} | {
+  type: 'complete';
+  result: IExecutionResult;
+  driverId?: TDriverId;
+} | {
+  type: 'interrupted';
+  result: IExecutionResult;
+  driverId?: TDriverId;
+} | {
+  type: 'error';
+  message: string;
+  driverId?: TDriverId;
+} | {
+  type: 'command_result';
+  name: string;
+  message: string;
+  success: boolean;
+  data?: ICommandResult['data'];
+} | {
+  type: 'messages';
+  messages: ReturnType<ISessionConversationRead['getMessages']>;
+} | {
+  type: 'context';
+  state: ReturnType<ISessionConversationRead['getContextState']>;
+} | {
+  type: 'usage_report';
+  report: IUsageBySourceReport;
+} | {
+  type: 'personal_usage_report';
+  requestId: string;
+  report: IPersonalUsageReport;
+} | {
+  type: 'personal_usage_report_error';
+  requestId: string;
+  code: 'not_available' | 'report_failed';
+  message: string;
+} | {
+  type: 'stored_session_usage_report';
+  requestId: string;
+  sessionId: string;
+  report: IUsageBySourceReport;
+} | {
+  type: 'stored_session_usage_report_error';
+  requestId: string;
+  sessionId: string;
+  code: 'not_available' | 'report_failed';
+  message: string;
+} | {
+  type: 'executing';
+  executing: boolean;
+} | {
+  type: 'pending';
+  pending: string | null;
+} | {
+  type: 'execution_workspace_event';
+  snapshot: IExecutionWorkspaceSnapshot;
+} | {
+  type: 'background_task_event';
+  event: TBackgroundTaskEvent;
+} | {
+  type: 'background_job_group_event';
+  event: TBackgroundJobGroupEvent;
+} | {
+  type: 'plan_event';
+  event: IPlanApprovalEvent;
+} | {
+  type: 'context_file_refreshed';
+  event: IContextFileRefreshedEvent;
+} | {
+  type: 'branch_event';
+  event: IBranchEvent;
+} | {
+  type: 'background_tasks';
+  tasks: IBackgroundTaskState[];
+} | {
+  type: 'background_task';
+  taskId: string;
+  task: IBackgroundTaskState | null;
+} | {
+  type: 'background_job_groups';
+  groups: IBackgroundJobGroupState[];
+} | {
+  type: 'background_job_group';
+  groupId: string;
+  group: IBackgroundJobGroupState | null;
+} | {
+  type: 'background_task_log';
+  taskId: string;
+  page: IBackgroundTaskLogPage;
+} | {
+  type: 'permission_request';
+  event: IPermissionRequestEvent;
+} | {
+  type: 'ask_request';
+  event: IAskRequestEvent;
+} | {
+  type: 'prompt_resolved';
+  event: IPromptResolvedEvent;
+} | {
+  type: 'ui_intent';
+  event: IUiIntentEvent;
+} | {
+  type: 'session_renamed';
+  event: ISessionRenamedEvent;
+} | {
+  type: 'history_cleared';
+} | {
+  type: 'background_task_control_result';
+  action: TBackgroundControlAction;
+  taskId: string;
+  success: boolean;
+  message?: string;
+} | {
+  type: 'protocol_error';
+  message: string;
+} | {
+  type: 'resume_gap';
+};
+/**
+ * REMOTE-013 E4: a server message stamped with its monotonic session sequence number (added by the
+ * {@link SessionResumeBridge} on the reconnectable WebRTC path). Intersecting over the union distributes the
+ * `seq` field onto every variant. The WS localhost path never stamps it (a `type`-dispatching client ignores
+ * an absent/extra `seq`).
+ */
+type TSeqServerMessage = TServerMessage & {
+  seq: number;
+};
+//#endregion
+//#region src/outbound-delivery.d.ts
+declare const outboundDeliveryBrand: unique symbol;
+/**
+ * Deliver one outbound frame on a connection. A carrier failure is REPORTED through the boundary's
+ * error handler, never thrown at the caller — so a reply resolving after a disconnect cannot escape as
+ * an unhandled rejection or out of the carrier's inbound listener.
+ *
+ * Only {@link createOutboundDelivery} produces one. The brand is the mechanism, not decoration: it is
+ * what makes a raw carrier `send` unusable where a boundary is required.
+ */
+type TOutboundDeliver = ((message: TServerMessage) => void) & {
+  readonly [outboundDeliveryBrand]: true;
+  /**
+   * Bytes this carrier has ACCEPTED and not yet written to the peer — or `undefined` when it cannot
+   * say.
+   *
+   * `deliver` returning is not delivery. Both carriers hand this boundary a fire-and-forget sink, so
+   * a frame that has "been sent" may be sitting in a socket buffer the boundary cannot see. Anything
+   * this boundary counted itself would be a count of what it HANDED OVER, which is a different
+   * quantity from what the peer has not read — and a budget over the wrong quantity reports a
+   * healthy connection for a peer that stopped reading (ARCH-030 / issue #1734).
+   *
+   * `undefined` is deliberately not `0`. A carrier that cannot report backpressure and a carrier with
+   * nothing pending are different states, and collapsing them would let "unknown" satisfy any
+   * threshold placed on this number.
+   */
+  readonly pendingBytes: () => number | undefined;
+};
+/**
+ * Observe THIS connection's first outbound delivery failure. `event` is the `type` of the frame that
+ * could not be delivered — a session event's own name for the fan-out (they are identical), and the
+ * reply's type for a reply (`command_result`, `protocol_error`, …).
+ *
+ * Required, never optional: a carrier that could opt out of observing its own delivery failures is the
+ * silent-failure shape this boundary exists to remove.
+ */
+type TDeliveryErrorHandler = (error: Error, event: TServerMessage['type']) => void;
+declare const DEFAULT_MAX_PENDING_BYTES: number;
+/**
+ * Is this carrier holding more than the budget allows?
+ *
+ * Exported because a WebSocket carries TWO kinds of outbound frame over one socket — the text
+ * protocol and TRANS-001's payload channels — and only one of them goes through
+ * {@link createOutboundDelivery}. A budget the binary path re-implemented would be a second opinion
+ * about one socket's backpressure; a budget it skipped would leave the same non-reading peer
+ * unbounded on the other half of the connection.
+ *
+ * `undefined` is unknown, not zero: a carrier that cannot report backpressure is never over budget.
+ */
+declare function isOverPendingBudget(pending: number | undefined, limit?: number): boolean;
+/**
+ * Default outbound DRAIN budget (issue #2306): how long a carrier may stay non-empty before the peer
+ * is treated as not reading.
+ *
+ * 120 seconds. The byte budget bounds HOW MUCH a peer holds; it cannot bound HOW LONG, because
+ * `bufferedAmount` is a quantity with no history — a peer draining just enough to stay under 8 MiB
+ * forever is never over it. The figure is generous on purpose: a legitimately slow link drains to
+ * zero between bursts, so the clock resets, whereas a peer that keeps SOMETHING pending for two
+ * minutes straight is holding a session, its resume buffer, and a socket it does not intend to read.
+ * A badly chosen figure here disconnects real users, which is why it is one named constant and an
+ * argument, never an inline number. `Infinity` disables the budget.
+ */
+declare const DEFAULT_MAX_PENDING_MS: number;
+/**
+ * The drain clock the boundary keeps for a carrier (issue #2306). One timestamp, not per-frame
+ * bookkeeping: it starts on the first reading that finds the carrier non-empty, RESETS only when a
+ * reading finds it empty (a peer that drains to one byte and stalls again has not drained), and is
+ * consulted synchronously at each send — the boundary has no timer and gains none here.
+ */
+interface IPendingStallClock {
+  readonly maxPendingMs: number;
+  /**
+   * Record one reading of the carrier's pending bytes. Returns how long the carrier has been
+   * continuously non-empty when that exceeds the budget; `undefined` otherwise. An `undefined`
+   * reading is unknown, not zero: it neither starts nor resets the clock.
+   */
+  observe: (pending: number | undefined) => number | undefined;
+}
+declare function createPendingStallClock(maxPendingMs?: number, now?: () => number): IPendingStallClock;
+declare function createOutboundDelivery(send: (message: TServerMessage) => void, onDeliveryError: TDeliveryErrorHandler, pendingBytes?: () => number | undefined, maxPendingBytes?: number, stallClock?: IPendingStallClock): TOutboundDeliver;
+//#endregion
+//#region src/protocol-session.d.ts
+/** Session roles required by the shared WebSocket/WebRTC protocol. */
+interface IProtocolSession extends ISessionTurnSubmission, ISessionTurnControl, ISessionCommands, ISessionEvents, ISessionPromptResolution, ISessionConversationRead, ISessionExecutionState, ISessionDriverAttribution, ISessionBackgroundTasks, ISessionBackgroundGroups, ISessionExecutionWorkspace {}
+//#endregion
+//#region src/usage-messages.d.ts
+interface IUsageQueryReporters {
+  readonly personalUsageReporter: ((request: IPersonalUsageRequest) => IPersonalUsageReport | Promise<IPersonalUsageReport>) | undefined;
+  readonly usageReporter: ((session: IProtocolSession) => IUsageBySourceReport | Promise<IUsageBySourceReport>) | undefined;
+  readonly storedSessionUsageReporter: ((sessionId: string) => IUsageBySourceReport | Promise<IUsageBySourceReport>) | undefined;
+}
+//#endregion
+//#region src/session-events.d.ts
+type TProtocolSessionEventClassification = 'forwarded' | 'requester-routed' | 'non-surface';
+/** Exhaustive protocol-owner policy over the shared session-event vocabulary. */
+declare const PROTOCOL_SESSION_EVENT_CLASSIFICATION: {
+  readonly text_delta: "forwarded";
+  readonly tool_start: "forwarded";
+  readonly tool_end: "forwarded";
+  readonly thinking: "forwarded";
+  readonly complete: "forwarded";
+  readonly error: "forwarded";
+  readonly context_update: "non-surface";
+  readonly compact: "non-surface";
+  readonly interrupted: "forwarded";
+  readonly skill_activation: "non-surface";
+  readonly background_task_event: "forwarded";
+  readonly background_job_group_event: "forwarded";
+  readonly execution_workspace_event: "forwarded";
+  readonly user_message: "forwarded";
+  readonly turn_source: "non-surface";
+  readonly context_file_refreshed: "forwarded";
+  readonly memory_event: "non-surface";
+  readonly goal_event: "non-surface";
+  readonly plan_event: "forwarded";
+  readonly branch_event: "forwarded";
+  readonly permission_request: "forwarded";
+  readonly ask_request: "forwarded";
+  readonly prompt_resolved: "forwarded";
+  readonly ui_intent: "requester-routed";
+  readonly session_renamed: "forwarded";
+  readonly history_cleared: "forwarded";
+};
+//#endregion
+//#region src/session-message-handler.d.ts
+interface ISessionMessageHandlerOptions {
+  /** IProtocolSession to expose. */
+  session: IProtocolSession;
+  /**
+   * ARCH-030: the CARRIER's connection-scoped outbound delivery boundary — not a raw `send`, and not a
+   * `send` plus an error callback for this handler to assemble into one. The carrier owns both the sink
+   * and the "what does a failed send mean for this connection" policy, so it builds the boundary and
+   * passes it down; the raw sink never crosses this parameter, which is what stops a future reply family
+   * from reaching the wire unguarded.
+   */
+  deliver: TOutboundDeliver;
+  /**
+   * REMOTE-014 E5: the SERVER-ASSIGNED driver id for THIS remote surface (the E3 `deviceId`). Injected into
+   * every inbound `submit`/`command`/prompt-response so a co-drive turn/answer is attributed to this driver —
+   * a client-supplied driver id is NEVER trusted. Absent → unattributed (the session defaults to the owner).
+   */
+  driverId?: TDriverId;
+  /** Trusted carrier-owned product surface, kept separate from driver identity. */
+  surface?: TUsageSurface;
+  /** Host-owned cross-session read model. The protocol only correlates and carries its result. */
+  personalUsageReporter?: NonNullable<IUsageQueryReporters['personalUsageReporter']>;
+  /** Host-owned current-session trace/cost producer for the pre-existing message family. */
+  usageReporter?: NonNullable<IUsageQueryReporters['usageReporter']>;
+  /** Host-owned stored-session producer used by cross-session drill-down. */
+  storedSessionUsageReporter?: NonNullable<IUsageQueryReporters['storedSessionUsageReporter']>;
+}
+/**
+ * Create a carrier-neutral message handler for an IProtocolSession.
+ *
+ * Returns:
+ * - `onMessage(data)`: call this when the WebSocket receives a message
+ * - `cleanup()`: call this when the WebSocket disconnects
+ *
+ * Usage:
+ * ```typescript
+ * const delivery = createOutboundDelivery(
+ *   (msg) => ws.send(JSON.stringify(msg)),
+ *   (error) => ws.close(1011, error.message),
+ * );
+ * const { onMessage, cleanup } = createSessionMessageHandler({ session: interactiveSession, deliver: delivery });
+ *
+ * ws.on('message', (data) => onMessage(String(data)));
+ * ws.on('close', cleanup);
+ * ```
+ */
+declare function createSessionMessageHandler(options: ISessionMessageHandlerOptions): {
+  onMessage: (data: string) => void;
+  cleanup: () => void;
+};
+//#endregion
+//#region src/message-decoders.d.ts
+type TMessageDecodeResult<TMessage> = {
+  readonly ok: true;
+  readonly message: TMessage;
+} | {
+  readonly ok: false;
+  readonly reason: string;
+};
+/** Serialized frames larger than this are refused before any parse (a bounded inbound budget). */
+declare const MAX_INBOUND_FRAME_BYTES: number;
+/** Total decode of a parsed client frame. */
+declare function decodeClientMessage(value: unknown): TMessageDecodeResult<TClientMessage>;
+/** Variant-level decode of a parsed server frame (foreign-owned payloads as records, see header). */
+declare function decodeServerMessage(value: unknown): TMessageDecodeResult<TServerMessage>;
+/** `raw string → JSON → owner decoder`, the one path a carrier implements. */
+declare function decodeFrame<TMessage>(data: string, decode: (value: unknown) => TMessageDecodeResult<TMessage>): TMessageDecodeResult<TMessage>;
+//#endregion
+//#region src/resume-buffer.d.ts
+/** One retained frame: its sequence number and the message. */
+interface IBufferedFrame {
+  readonly seq: number;
+  readonly message: TServerMessage;
+}
+/** The result of a `tailAfter` — either the ordered replay slice, or an overrun (client must full-refresh). */
+type TResumeTail = {
+  readonly kind: 'tail';
+  readonly frames: readonly IBufferedFrame[];
+} | {
+  readonly kind: 'overrun';
+};
+interface IResumeBufferOptions {
+  /** Max retained frames (drop-oldest beyond this). Default 512. */
+  readonly maxFrames?: number;
+  /** Max retained bytes across frames (drop-oldest beyond this). Default 4 MiB. */
+  readonly maxBytes?: number;
+  /** Serialized size of a message (for the byte budget). Default: JSON length. Injectable for tests. */
+  readonly sizeOf?: (message: TServerMessage) => number;
+}
+/**
+ * A monotonic, bounded ring of un-acked frames. Sequence numbers are assigned by {@link append} and never
+ * reused; `tailAfter` / `ackThrough` operate over the retained window.
+ */
+declare class ResumeBuffer {
+  private readonly frames;
+  private readonly sizes;
+  private nextSeq;
+  private bytes;
+  private readonly maxFrames;
+  private readonly maxBytes;
+  private readonly sizeOf;
+  constructor(options?: IResumeBufferOptions);
+  /** Append a message, assign + return its monotonic seq, and evict oldest frames beyond the bounds. */
+  append(message: TServerMessage): number;
+  /** Drop all retained frames with `seq <= throughSeq` (the client confirmed receipt up to there). */
+  ackThrough(throughSeq: number): void;
+  /**
+   * The ordered frames with `seq > lastSeq`. Returns an `overrun` marker when `lastSeq` is older than the
+   * oldest retained frame (i.e. some frame after `lastSeq` was already evicted) — the client must full-refresh.
+   * `lastSeq` at or beyond the newest seq yields an empty tail (nothing to replay).
+   */
+  tailAfter(lastSeq: number): TResumeTail;
+  /** The last seq assigned (0 when nothing has been appended). */
+  get lastSeq(): number;
+  /** Retained frame count (diagnostics/tests). */
+  get size(): number;
+  private evict;
+  /** The single place that mutates `frames`/`sizes`/`bytes` for removal, so byte accounting can't drift. */
+  private removeOldest;
+}
+//#endregion
+//#region src/channel-frames.d.ts
+/** `R`, `B`, `F` — the shared prefix every channel frame starts with. */
+declare const CHANNEL_FRAME_MAGIC: Uint8Array;
+/** Envelope version. Bumped only on an incompatible layout change. */
+declare const CHANNEL_FRAME_VERSION = 1;
+/** Encode an opaque binary frame. The payload bytes are copied verbatim. */
+declare function encodeBinaryFrame(frame: IBinaryFrame): Uint8Array;
+/** Encode a structured, consumer-declared event frame (UTF-8 JSON body). */
+declare function encodeChannelEventFrame(frame: IChannelEventFrame): Uint8Array;
+/** True when `bytes` starts with the channel-frame magic — a cheap, non-parsing routing check. */
+declare function isChannelFrame(bytes: Uint8Array): boolean;
+/**
+ * Decode a channel frame. Returns an explicit result union — a non-channel, truncated, or malformed
+ * input is a stated error the carrier reports to the peer, never a thrown exception on the hot path
+ * and never a silently dropped frame.
+ */
+declare function decodeChannelFrame(bytes: Uint8Array): TChannelReceiveResult;
+//#endregion
+//#region src/session-resume-bridge.d.ts
+/** The current channel sink — receives a serialized JSON frame to put on the wire. */
+type TResumeSink = (data: string) => void;
+/** Options for {@link SessionResumeBridge.attach}. */
+interface IAttachOptions {
+  /**
+   * REMOTE-013 E4: on a RECONNECT, HOLD live sink-forwarding until the client's `resume` has replayed the
+   * buffered tail — otherwise a live frame emitted between attach and the inbound `resume` would leapfrog the
+   * gap frames on the wire, and the client's seq-dedup would then discard the (older, lower-seq) gap. Every
+   * live event is already appended to the buffer, so holding loses nothing; `replay()` flushes in order and
+   * un-holds. First-pair attach does NOT hold (the client starts at seq 0, frames arrive in order).
+   */
+  readonly awaitResume?: boolean;
+  /** Sink/carrier-owned failure lifecycle for this attachment only. */
+  readonly onDeliveryError: (error: Error, event: string) => void;
+  /**
+   * ARCH-030: this attachment's carrier backpressure reading, if it has one.
+   *
+   * Threaded through because the replay path is the burst this budget exists for — a reconnecting
+   * peer is handed the whole retained tail at once, and without a reading the boundary here would
+   * have no budget at all while the per-channel boundary did.
+   */
+  readonly pendingBytes?: () => number | undefined;
+}
+interface ISessionResumeBridgeOptions {
+  readonly session: IProtocolSession;
+  readonly buffer?: IResumeBufferOptions;
+  /** REMOTE-014 E5: the SERVER-ASSIGNED driver id for this surface, injected into inbound submit/command/prompt-response. */
+  readonly driverId?: TDriverId;
+  readonly surface?: TUsageSurface;
+  readonly personalUsageReporter?: IUsageQueryReporters['personalUsageReporter'];
+  readonly usageReporter?: IUsageQueryReporters['usageReporter'];
+  readonly storedSessionUsageReporter?: IUsageQueryReporters['storedSessionUsageReporter'];
+}
+declare class SessionResumeBridge {
+  private readonly session;
+  private readonly buffer;
+  private driverId?;
+  private readonly reporters;
+  private readonly surface?;
+  private readonly unsubscribe;
+  private onDeliveryError?;
+  /**
+   * ARCH-030: the attachment's outbound boundary — and the only reference this class keeps to the current
+   * channel, which is why `dispose()` goes through `detach()` rather than clearing a separate field.
+   * Built per `attach` because a boundary LATCHES on its first failure, so a fresh one is exactly what
+   * un-latches the session for the next channel. It holds the only try/catch on the frame path.
+   */
+  private outbound?;
+  /**
+   * The session-lifetime entry every frame takes — event fan-out AND every reply to an inbound frame —
+   * before it is seq-stamped and buffered by {@link emit}. Distinct from {@link outbound}, which is the
+   * per-attachment exit to the current channel; this one outlives channels because the subscription does.
+   *
+   * It guards the BUFFERING step, not a carrier, and it latches for the life of the session on purpose:
+   * the failure it is placed against is the buffer refusing a frame on capacity, and a resume buffer that
+   * cannot accept frames cannot honour a later `resume` either, so there is nothing a reconnect recovers.
+   * That is the opposite of {@link outbound}, where the next channel IS the recovery — the two scopes
+   * differ because the failures do. (A per-frame serialization failure would leave the buffer intact, but
+   * such a frame is undeliverable on every carrier, since each one stringifies it too; it is reported and
+   * the carrier torn down, never silently dropped.)
+   */
+  private readonly emitBoundary;
+  private disposed;
+  /** REMOTE-013 E4: while true, live emits are buffered but NOT forwarded — released by `replay()` on reconnect. */
+  private holding;
+  constructor(options: ISessionResumeBridgeOptions);
+  /** Set the current channel sink (on connect / reconnect). Live messages reach the client; replay is `resume`-driven. */
+  attach(sink: TResumeSink, options: IAttachOptions): void;
+  /** Clear the sink (channel drop). Buffering continues so gap output is retained for the next `resume`. */
+  detach(): void;
+  /**
+   * REMOTE-014 E5: bind the SERVER-ASSIGNED driver id (the E3 `deviceId`) once the peer pairs — the bridge
+   * injects it into every subsequent inbound submit/command/prompt-response for co-drive attribution.
+   */
+  setDriverId(driverId: TDriverId): void;
+  /** Route one inbound channel frame: `resume`/`ack` handled here; everything else → the session. */
+  onClientMessage(data: string): void;
+  /** Unsubscribe from the session (host reconnect-window ceiling / teardown). Idempotent. */
+  dispose(): void;
+  /** Diagnostics/tests: the last seq assigned. */
+  get lastSeq(): number;
+  /**
+   * Stamp a seq, retain in the buffer, and forward to the current sink — UNLESS holding for a reconnect replay.
+   *
+   * ARCH-030: the `buffer.append` happens BEFORE the boundary, deliberately. The boundary latches on its
+   * first failure and drops everything after it, so a frame appended afterwards would be lost — appending
+   * first means a dropped frame is still in the un-acked tail and still replays on the next `resume`.
+   */
+  private emit;
+  /**
+   * Replay the buffered tail after `lastSeq` (or `resume_gap` on overrun), then RELEASE the reconnect hold so
+   * subsequent live frames flow in order behind the flushed gap.
+   *
+   * A failing sink reports ONCE across the whole tail: the boundary latches on the first failure and every
+   * remaining frame is dropped silently. Those frames stay un-acked in the buffer and replay on the next
+   * attachment. Before ARCH-030 the single report was a side effect of `detach()` running mid-loop; now it
+   * is the boundary's stated contract.
+   */
+  private replay;
+  /** The ONE outbound exit from this class. No frame reaches the sink except through the attachment's boundary. */
+  private deliverFrame;
+  /** Detach the failed sink but retain the frame, then notify its attachment owner. */
+  private reportDeliveryError;
+}
+//#endregion
+//#region src/peer-message-ledger.d.ts
+/**
+ * What the receiver has seen from one origin.
+ *
+ * `delivered` is a SET, not just a high-water mark, and that distinction is the whole of review
+ * finding #1. A high-water mark cannot tell "sequence 2 was already used" from "sequence 2 is the
+ * gap we reported and it has just arrived" — and answering the second as if it were the first
+ * refuses a message that was never delivered, permanently. `highestSequence` is kept alongside it
+ * because reporting a gap needs the frontier, not the membership.
+ *
+ * Exported because it is reachable from `IPeerMessageLedger`. A public interface whose field type is
+ * unexported is a name a consumer cannot write down (review finding #2). Measured: `tsdown` inlines
+ * it into the bundled declaration so no TS4033 is raised today — the finding's build-breakage claim
+ * does not reproduce — but a type nobody can name is still a bad public surface.
+ */
+interface IOriginRecord {
+  /** The highest sequence delivered from this origin — the frontier a gap is measured against. */
+  highestSequence: number;
+  /** Every sequence actually delivered. Membership, not a range: gaps get filled out of order. */
+  delivered: Set<number>;
+  /** Acks already issued, by message id, so a retry gets the original answer back. */
+  issued: Map<string, IPeerMessageAck>;
+}
+/** Per-connection receive state. Created empty; discarded when the connection ends. */
+interface IPeerMessageLedger {
+  readonly origins: Map<string, IOriginRecord>;
+}
+declare function createPeerMessageLedger(): IPeerMessageLedger;
+/** Why a message was not accepted, when it was not. */
+interface IPeerMessageRejection {
+  readonly state: Extract<TPeerDeliveryState, 'refused' | 'failed'>;
+  readonly reason: string;
+}
+interface IPeerMessageVerdict {
+  readonly ack: IPeerMessageAck;
+  /**
+   * Should the session deliver this to the agent?
+   *
+   * False for a duplicate and for a refusal. Separate from `ack.state` because a caller that
+   * re-derived it from the state string would have to re-list which states mean "deliver", and that
+   * list is exactly what drifts.
+   */
+  readonly deliver: boolean;
+  /**
+   * Set when this message's sequence is ahead of the last one delivered from its origin.
+   *
+   * Reported, not resolved. The session layer decides whether a gap is worth waiting for; the
+   * ledger's job is to make sure it is never invisible.
+   */
+  readonly gapBefore?: number;
+}
+/**
+ * Record a message and say what should happen to it.
+ *
+ * Pure with respect to its inputs except for the ledger it is handed, which it updates in place —
+ * the caller owns the ledger's lifetime, so a connection ending is a reference going away rather
+ * than a cleanup step someone can forget.
+ */
+declare function admitPeerMessage(ledger: IPeerMessageLedger, message: IPeerMessage, rejection?: IPeerMessageRejection): IPeerMessageVerdict;
+/**
+ * Mark a delivered message as acknowledged by the agent side.
+ *
+ * Separate from `admitPeerMessage` because delivery and acknowledgement answer different questions —
+ * "did the receiver take it" versus "did the agent act on it" — and a sender waiting for the second
+ * must not be told the first.
+ */
+declare function acknowledgePeerMessage(ledger: IPeerMessageLedger, originSessionId: string, id: string): IPeerMessageAck | undefined;
+/** Forget one origin — used when a peer disconnects and its sequence space is no longer meaningful. */
+declare function forgetPeerOrigin(ledger: IPeerMessageLedger, originSessionId: string): void;
+//#endregion
+//#region src/handoff-chunking.d.ts
+/**
+ * One piece of a payload in flight.
+ *
+ * `total` travels on every chunk rather than in a separate header frame: a header can be the frame
+ * that gets lost, and a receiver that learned the count from a message it never got would wait
+ * forever for a number it cannot ask for again.
+ */
+interface IHandoffChunk {
+  readonly handoffId: string;
+  /** 0-based position in the sequence. */
+  readonly index: number;
+  /** How many chunks make up the whole payload. */
+  readonly total: number;
+  /** base64 of this slice of the UTF-8 encoded payload. */
+  readonly data: string;
+}
+/**
+ * Default frame budget, in bytes of encoded chunk data.
+ *
+ * 16 KiB because that is the size every SCTP implementation carries without negotiation. Larger
+ * works between two peers that both support it and fails between two that do not — and it fails at
+ * transfer time, on the user's session, not in a test.
+ */
+declare const DEFAULT_MAX_CHUNK_BYTES: number;
+/**
+ * Cut a sealed payload into chunks.
+ *
+ * Takes the serialized string the seal produced, not the record — the digest is over those exact
+ * bytes, and re-serializing here would let a chunked payload differ from the one the manifest
+ * describes.
+ */
+declare function chunkHandoffPayload(handoffId: string, serialized: string, maxChunkBytes?: number): readonly IHandoffChunk[];
+/** Why a chunk was not accepted. */
+type TChunkRejection =
+/** Belongs to a different transfer. */
+'wrong-handoff' |
+/** `index` is negative, or beyond the declared `total`. */
+'out-of-range' |
+/** Its `total` disagrees with what earlier chunks declared. */
+'inconsistent-total' |
+/** Its `data` is not decodable base64. */
+'undecodable';
+type TChunkOutcome =
+/** Stored; more are still needed. */
+'accepted' |
+/** Already had this index, and it matched. A retry, not a problem. */
+'duplicate' |
+/** Stored, and that was the last one missing. */
+'complete' | 'refused';
+interface IChunkResult {
+  readonly outcome: TChunkOutcome;
+  readonly rejection?: TChunkRejection;
+  /** Present when complete: the reassembled payload, ready for the integrity check. */
+  readonly serialized?: string;
+  /** How many distinct chunks are held. */
+  readonly received: number;
+  /** How many are expected, once anything has declared it. */
+  readonly expected?: number;
+}
+/**
+ * Collects the chunks of ONE transfer.
+ *
+ * One assembler per `handoffId`, because a shared one would have to key everything by transfer and
+ * would then be a place where two transfers can be confused for each other. A chunk naming a
+ * different transfer is refused rather than routed — routing is the caller's job and doing it here
+ * would make this a dispatcher as well as a buffer.
+ */
+declare class HandoffChunkAssembler {
+  private readonly handoffId;
+  private readonly chunks;
+  private declaredTotal;
+  constructor(handoffId: string);
+  get received(): number;
+  get expected(): number | undefined;
+  /** Take one chunk. Reordering and retries are normal; inconsistency is not. */
+  accept(chunk: IHandoffChunk): IChunkResult;
+  /** Which indices are still missing, so a caller can ask for them rather than restarting. */
+  missing(): readonly number[];
+  /** Drop everything held. The transfer was abandoned, or its integrity check failed. */
+  discard(): void;
+  private reassemble;
+}
+/**
+ * How many chunks a payload of this size will take, without building them.
+ *
+ * For a progress indicator at the sending end, and for a receiver deciding whether it is willing to
+ * hold that much before the first chunk arrives.
+ */
+declare function chunkCountFor(integrity: IHandoffIntegrity, maxChunkBytes?: number): number;
+//#endregion
+export { CHANNEL_FRAME_MAGIC, CHANNEL_FRAME_VERSION, DEFAULT_MAX_CHUNK_BYTES, DEFAULT_MAX_PENDING_BYTES, DEFAULT_MAX_PENDING_MS, HandoffChunkAssembler, type IAttachOptions, type IBufferedFrame, type IChunkResult, type IHandoffChunk, type IPeerMessageLedger, type IPeerMessageRejection, type IPeerMessageVerdict, type IPendingStallClock, type IProtocolSession, type IResumeBufferOptions, type ISessionMessageHandlerOptions, type ISessionResumeBridgeOptions, MAX_INBOUND_FRAME_BYTES, PROTOCOL_SESSION_EVENT_CLASSIFICATION, ResumeBuffer, SessionResumeBridge, type TChunkOutcome, type TChunkRejection, type TClientMessage, type TDeliveryErrorHandler, type TMessageDecodeResult, type TOutboundDeliver, type TProtocolSessionEventClassification, type TResumeSink, type TResumeTail, type TSeqServerMessage, type TServerMessage, acknowledgePeerMessage, admitPeerMessage, chunkCountFor, chunkHandoffPayload, createOutboundDelivery, createPeerMessageLedger, createPendingStallClock, createSessionMessageHandler, decodeChannelFrame, decodeClientMessage, decodeFrame, decodeServerMessage, encodeBinaryFrame, encodeChannelEventFrame, forgetPeerOrigin, isChannelFrame, isOverPendingBudget };
 //# sourceMappingURL=index.d.ts.map