@robota-sdk/agent-transport 3.0.0-beta.100

package/dist/browser/index.d.ts

@@ -0,0 +1,624 @@
+import { a as decodeFrame, c as IWireHistoryEntry, d as TServerMessage, f as TWireExecutionResult, i as decodeClientMessage, l as TClientMessage, n as MAX_INBOUND_FRAME_BYTES, o as decodeServerMessage, r as TMessageDecodeResult, s as IWireAgentDefinitionSummary, t as isObserverMessageType, u as TSeqServerMessage } from "./observer-messages-4fRQZU2D.js";
+import { ISessionAgentJobs, ISessionBackgroundGroups, ISessionBackgroundTasks, ISessionCommands, ISessionConversationRead, ISessionDirectory, ISessionDriverAttribution, ISessionEvents, ISessionExecutionDetail, ISessionExecutionState, ISessionExecutionWorkspace, ISessionProjectRead, ISessionPromptResolution, ISessionRuntimeTools, ISessionSelfPacedLoopControl, ISessionStatusRead, ISessionToolAppViews, ISessionTurnControl, ISessionTurnSubmission, ISettingsSnapshot, TDriverId, TSettingsPatch } from "@robota-sdk/agent-interface-session";
+import { TToolArgs } from "@robota-sdk/agent-core";
+import { IPersonalUsageReport, IPersonalUsageRequest, IUsageBySourceReport, TUsageSurface } from "@robota-sdk/agent-interface-analytics";
+import { TCommandSurfaceLocality } from "@robota-sdk/agent-interface-command";
+import { IBinaryFrame, IChannelEventFrame, TChannelReceiveResult } from "@robota-sdk/agent-interface-transport";
+import { IHandoffIntegrity, IPeerMessage, IPeerMessageAck, TPeerDeliveryState } from "@robota-sdk/agent-interface-session-mobility";
+//#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 — for the fan-out, the frame a session event was forwarded as (usually, not
+ * always, the event's own name), 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;
+/**
+ * Backpressure budget for a terminal attached to a session on the same host, in either role.
+ *
+ * 1 MiB, tighter than the default: an attached terminal reads a local socket, so a backlog this large
+ * means it stopped reading rather than that a network is slow. Exceeding it closes that connection
+ * only; the session never waits for a reader, so other surfaces keep streaming.
+ */
+declare const ATTACHED_SURFACE_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, ISessionStatusRead, ISessionEvents, ISessionPromptResolution, ISessionConversationRead, ISessionExecutionState, ISessionDriverAttribution, ISessionBackgroundTasks, ISessionBackgroundGroups, ISessionExecutionWorkspace, ISessionExecutionDetail, ISessionSelfPacedLoopControl, ISessionAgentJobs, ISessionRuntimeTools, ISessionToolAppViews {}
+/**
+ * #3282 §4c: a protocol session that ALSO answers the Project panel's reads. `Partial` (not a fourth
+ * mandatory role on {@link IProtocolSession} itself) deliberately: every existing test double and
+ * every other host that builds an `IProtocolSession` keeps type-checking unchanged, and the panel's
+ * three methods are runtime-probed (`typeof session.readProjectStatus === 'function'`) rather than
+ * assumed — `InteractiveSession` (the one production implementation) provides all three, satisfying
+ * this type with no further wiring.
+ */
+type TProjectReadCapableSession = IProtocolSession & Partial<ISessionProjectRead>;
+//#endregion
+//#region src/settings-messages.d.ts
+type TSettingsMessage = Extract<TClientMessage, {
+  type: 'get-settings' | 'update-settings';
+}>;
+declare function isSettingsMessage(msg: TClientMessage): msg is TSettingsMessage;
+/** What applying a patch did: the fresh snapshot, or why nothing was written. */
+type TSettingsUpdateOutcome = {
+  readonly ok: true;
+  readonly settings: ISettingsSnapshot;
+} | {
+  readonly ok: false;
+  readonly code: 'not_available' | 'invalid' | 'refused' | 'update_failed';
+  readonly message: string;
+};
+/**
+ * #3282 §4a: host-owned read/write for the Settings screen, supplied by the composition root the
+ * same way `IUsageQueryReporters` supplies usage reads — this package only correlates the request
+ * and carries the result. `updateSettings` applies through the SAME function the matching slash
+ * command uses (issue #3282 §4: "one code path, so the behavior matches the TUI"), so whatever a
+ * command would refuse on this surface is refused here too.
+ */
+interface ISettingsReporter {
+  getSettings(session: IProtocolSession, locality?: TCommandSurfaceLocality): ISettingsSnapshot | Promise<ISettingsSnapshot>;
+  /**
+   * Applies through the SAME function the matching slash command uses. `locality` (#3282 §4 part
+   * b-2) is forwarded to that command exactly as the transport received it, so a command that
+   * refuses a remote surface (installing a plugin) refuses identically here.
+   */
+  updateSettings(session: IProtocolSession, patch: TSettingsPatch, locality?: TCommandSurfaceLocality): TSettingsUpdateOutcome | Promise<TSettingsUpdateOutcome>;
+}
+declare function handleSettingsMessage(session: IProtocolSession, deliver: TOutboundDeliver, msg: TSettingsMessage, reporter: ISettingsReporter | undefined, locality?: TCommandSurfaceLocality): void;
+//#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 thinking_delta: "non-surface";
+  readonly complete: "forwarded";
+  readonly error: "forwarded";
+  readonly context_update: "forwarded";
+  readonly compact: "forwarded";
+  readonly interrupted: "forwarded";
+  readonly skill_activation: "forwarded";
+  readonly background_task_event: "forwarded";
+  readonly background_job_group_event: "forwarded";
+  readonly execution_workspace_event: "forwarded";
+  readonly user_message: "forwarded";
+  readonly turn_source: "forwarded";
+  readonly context_file_refreshed: "forwarded";
+  readonly memory_event: "forwarded";
+  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";
+  readonly session_switched: "forwarded";
+  readonly status_changed: "forwarded";
+};
+//#endregion
+//#region src/session-message-handler.d.ts
+/**
+ * What a connected surface may do. `drive` sends prompts, answers questions and controls the session.
+ * `observe` is read-only: it follows this session's conversation and state, but never submits, answers,
+ * controls, or reads another session's records, and it never counts as a surface that can answer.
+ */
+type TSessionSurfaceRole = 'drive' | 'observe';
+interface ISessionMessageHandlerOptions {
+  /** IProtocolSession to expose — `Partial<ISessionProjectRead>` is probed, not assumed (#3282 §4c). */
+  session: TProjectReadCapableSession;
+  /**
+   * 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;
+  /** Carrier-decided role of this connection; defaults to `drive`. The client never chooses it here. */
+  role?: TSessionSurfaceRole;
+  /** 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']>;
+  /** Host-owned session directory (#3189): list, start and switch the host's sessions. */
+  sessionDirectory?: ISessionDirectory;
+  /** #3282 §4a: host-owned read/write for the GUI Settings screen. */
+  settingsReporter?: ISettingsReporter;
+  /**
+   * #3282 §4 part b-2: carrier-decided, like `role` — whether THIS carrier's connections are
+   * provably on this machine. The loopback WS carrier is `'local'`; the device-mesh/WebRTC carrier
+   * sets `'remote'`. Absent → `'local'`, forwarded to `executeCommand` and the settings reporter so a
+   * command that runs code from outside the session (installing a plugin) can refuse a remote device.
+   */
+  commandSurfaceLocality?: TCommandSurfaceLocality;
+  /**
+   * The most bytes one frame answering an app tool call or view read may take, for a carrier whose
+   * channel carries less than the inbound limit (a WebRTC data channel). An answer over it is
+   * replaced by a `protocol_error` before it reaches any buffer. Defaults to the inbound limit less
+   * a margin for a carrier that stamps frames afterwards.
+   */
+  maxFrameBytes?: number;
+}
+/**
+ * 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/session-query-messages.d.ts
+/**
+ * #3189: the most serialized history one `history` frame carries. Well under the tightest outbound
+ * budget (an attached terminal's, 1 MiB), so a client reading page after page is never mistaken for
+ * one that stopped reading.
+ */
+declare const HISTORY_PAGE_MAX_BYTES: number;
+//#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'];
+  /** #3282 §4 part b-2: this bridge is the reconnectable WebRTC path, so it is always `'remote'`. */
+  readonly commandSurfaceLocality?: TCommandSurfaceLocality;
+  /** See {@link ISessionMessageHandlerOptions.maxFrameBytes}: the channel's limit, not the inbound one. */
+  readonly maxFrameBytes?: number;
+}
+declare class SessionResumeBridge {
+  private readonly session;
+  private readonly buffer;
+  private driverId?;
+  private readonly reporters;
+  private readonly surface?;
+  private readonly commandSurfaceLocality?;
+  private readonly maxFrameBytes?;
+  /**
+   * Ends with the bridge, not with a channel: a channel drop keeps the session reconnectable, so work
+   * started for a hosted app view (a call waiting on its prompt) survives it and is cancelled only when
+   * the host gives up on the session.
+   */
+  private readonly lifetime;
+  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/permission-summary.d.ts
+/** The call's identifying argument, or `undefined` when it has none worth showing. */
+declare function permissionSummaryArgument(toolArgs: TToolArgs): string | undefined;
+//#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 { ATTACHED_SURFACE_MAX_PENDING_BYTES, CHANNEL_FRAME_MAGIC, CHANNEL_FRAME_VERSION, DEFAULT_MAX_CHUNK_BYTES, DEFAULT_MAX_PENDING_BYTES, DEFAULT_MAX_PENDING_MS, HISTORY_PAGE_MAX_BYTES, 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, type ISettingsReporter, type IWireAgentDefinitionSummary, type IWireHistoryEntry, 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, type TSessionSurfaceRole, type TSettingsUpdateOutcome, type TWireExecutionResult, acknowledgePeerMessage, admitPeerMessage, chunkCountFor, chunkHandoffPayload, createOutboundDelivery, createPeerMessageLedger, createPendingStallClock, createSessionMessageHandler, decodeChannelFrame, decodeClientMessage, decodeFrame, decodeServerMessage, encodeBinaryFrame, encodeChannelEventFrame, forgetPeerOrigin, handleSettingsMessage, isChannelFrame, isObserverMessageType, isOverPendingBudget, isSettingsMessage, permissionSummaryArgument };
+//# sourceMappingURL=index.d.ts.map

package/dist/browser/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/outbound-delivery.ts","../../src/protocol-session.ts","../../src/settings-messages.ts","../../src/usage-messages.ts","../../src/session-events.ts","../../src/session-message-handler.ts","../../src/session-query-messages.ts","../../src/resume-buffer.ts","../../src/channel-frames.ts","../../src/session-resume-bridge.ts","../../src/peer-message-ledger.ts","../../src/permission-summary.ts","../../src/handoff-chunking.ts"],"mappings":"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"}