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

package/src/channel-frames.ts

@@ -0,0 +1,182 @@
+/**
+ * Payload-agnostic channel frame codec (TRANS-001).
+ *
+ * The single place that knows the channel envelope. Pure and transport-neutral: a WebSocket binary
+ * frame, a WebRTC data-channel message, or any other byte carrier can use it unchanged. It NEVER
+ * interprets a binary body — that is the whole point of the payload-agnostic profile.
+ *
+ * Wire layout (all multi-byte integers big-endian):
+ *
+ * ```
+ *   0..2   magic 'R','B','F'                  ← lets a carrier route a frame without parsing it
+ *   3      version (1)
+ *   4      kind: 0x01 = opaque binary, 0x02 = structured event (UTF-8 JSON body)
+ *   5      channel-name length in bytes (1..255)
+ *   6..    channel name (UTF-8)
+ *   +4     seq (uint32)
+ *   ...    body — opaque bytes (kind 0x01) or UTF-8 JSON `{ "event": string, "payload": … }` (0x02)
+ * ```
+ *
+ * The envelope deliberately carries NO length prefix for the body: the carrier already delimits the
+ * message (a WebSocket frame is a message boundary), so a length field would only be a second source
+ * of truth that can disagree with the first.
+ */
+
+import type {
+  IBinaryFrame,
+  IChannelEventFrame,
+  TChannelReceiveResult,
+} from '@robota-sdk/agent-interface-transport';
+
+/**
+ * The JSON-serializable payload type an event frame carries. Read off the contract (rather than
+ * re-importing `agent-core`'s `TUniversalValue`) so this package keeps its single contract edge.
+ */
+type TEventPayload = IChannelEventFrame['payload'];
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+/** `R`, `B`, `F` — the shared prefix every channel frame starts with. */
+export const CHANNEL_FRAME_MAGIC: Uint8Array = encoder.encode('RBF');
+
+/** Envelope version. Bumped only on an incompatible layout change. */
+export const CHANNEL_FRAME_VERSION = 1;
+
+const KIND_BINARY = 0x01;
+const KIND_EVENT = 0x02;
+
+/** Bytes before the channel name: magic(3) + version(1) + kind(1) + name length(1). */
+const PREFIX_BYTES = 6;
+/** Bytes after the channel name and before the body: seq(4). */
+const SEQ_BYTES = 4;
+
+const MAX_CHANNEL_NAME_BYTES = 255;
+const MAX_SEQ = 0xffff_ffff;
+
+/** Validate the envelope fields both encoders share, then return the encoded channel name. */
+function encodeChannelName(channel: string, seq: number): Uint8Array {
+  const name = encoder.encode(channel);
+  if (name.byteLength === 0 || name.byteLength > MAX_CHANNEL_NAME_BYTES) {
+    throw new Error(
+      `channel name must be 1..${MAX_CHANNEL_NAME_BYTES} UTF-8 bytes (got ${name.byteLength})`,
+    );
+  }
+  if (!Number.isInteger(seq) || seq < 0 || seq > MAX_SEQ) {
+    throw new Error(`seq must be an integer in 0..${MAX_SEQ} (got ${seq})`);
+  }
+  return name;
+}
+
+/** Write the shared header into `out` and return the offset where the body starts. */
+function writeHeader(out: Uint8Array, kind: number, name: Uint8Array, seq: number): number {
+  out.set(CHANNEL_FRAME_MAGIC, 0);
+  out[3] = CHANNEL_FRAME_VERSION;
+  out[4] = kind;
+  out[5] = name.byteLength;
+  out.set(name, PREFIX_BYTES);
+  const seqAt = PREFIX_BYTES + name.byteLength;
+  new DataView(out.buffer, out.byteOffset, out.byteLength).setUint32(seqAt, seq, false);
+  return seqAt + SEQ_BYTES;
+}
+
+/** Encode an opaque binary frame. The payload bytes are copied verbatim. */
+export function encodeBinaryFrame(frame: IBinaryFrame): Uint8Array {
+  const name = encodeChannelName(frame.channel, frame.seq);
+  const out = new Uint8Array(PREFIX_BYTES + name.byteLength + SEQ_BYTES + frame.payload.byteLength);
+  const bodyAt = writeHeader(out, KIND_BINARY, name, frame.seq);
+  out.set(frame.payload, bodyAt);
+  return out;
+}
+
+/** Encode a structured, consumer-declared event frame (UTF-8 JSON body). */
+export function encodeChannelEventFrame(frame: IChannelEventFrame): Uint8Array {
+  const name = encodeChannelName(frame.channel, frame.seq);
+  const body = encoder.encode(JSON.stringify({ event: frame.event, payload: frame.payload }));
+  const out = new Uint8Array(PREFIX_BYTES + name.byteLength + SEQ_BYTES + body.byteLength);
+  const bodyAt = writeHeader(out, KIND_EVENT, name, frame.seq);
+  out.set(body, bodyAt);
+  return out;
+}
+
+/** True when `bytes` starts with the channel-frame magic — a cheap, non-parsing routing check. */
+export function isChannelFrame(bytes: Uint8Array): boolean {
+  if (bytes.byteLength < CHANNEL_FRAME_MAGIC.length) return false;
+  return CHANNEL_FRAME_MAGIC.every((b, i) => bytes[i] === b);
+}
+
+/** The decoded shape of an event frame's JSON body. */
+interface IEventBody {
+  readonly event?: TEventPayload;
+  readonly payload?: TEventPayload;
+}
+
+/** Parse the JSON body of an event frame into its `event` + `payload` fields, or state why not. */
+function parseEventBody(
+  body: Uint8Array,
+): { ok: true; event: string; payload: TEventPayload } | { ok: false; error: string } {
+  const text = decoder.decode(body);
+  let parsed: TEventPayload;
+  try {
+    parsed = JSON.parse(text) as TEventPayload;
+  } catch {
+    // An error RESULT, not a fallback: the caller reports it to the peer as a protocol error.
+    return { ok: false, error: 'channel frame: malformed JSON body' };
+  }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    return { ok: false, error: 'channel frame: event body must be a JSON object' };
+  }
+  const { event, payload } = parsed as IEventBody;
+  if (typeof event !== 'string' || event.length === 0) {
+    return { ok: false, error: 'channel frame: event body is missing a non-empty `event` name' };
+  }
+  return { ok: true, event, payload: payload ?? null };
+}
+
+/**
+ * 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.
+ */
+export function decodeChannelFrame(bytes: Uint8Array): TChannelReceiveResult {
+  if (!isChannelFrame(bytes)) {
+    return { ok: false, error: 'channel frame: bad magic (not a channel frame)' };
+  }
+  if (bytes.byteLength < PREFIX_BYTES) {
+    return { ok: false, error: 'channel frame: truncated header' };
+  }
+  if (bytes[3] !== CHANNEL_FRAME_VERSION) {
+    return { ok: false, error: `channel frame: unsupported version ${String(bytes[3])}` };
+  }
+
+  const kind = bytes[4];
+  const nameLength = bytes[5] ?? 0;
+  if (nameLength === 0) return { ok: false, error: 'channel frame: empty channel name' };
+
+  const seqAt = PREFIX_BYTES + nameLength;
+  const bodyAt = seqAt + SEQ_BYTES;
+  if (bytes.byteLength < bodyAt) {
+    return { ok: false, error: 'channel frame: truncated (header longer than the frame)' };
+  }
+
+  const channel = decoder.decode(bytes.subarray(PREFIX_BYTES, seqAt));
+  const seq = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getUint32(
+    seqAt,
+    false,
+  );
+  const body = bytes.subarray(bodyAt);
+
+  if (kind === KIND_BINARY) {
+    // Copy so the frame does not alias the carrier's (possibly pooled/reused) receive buffer.
+    return { ok: true, frame: { kind: 'binary', channel, seq, payload: Uint8Array.from(body) } };
+  }
+  if (kind === KIND_EVENT) {
+    const parsed = parseEventBody(body);
+    if (!parsed.ok) return { ok: false, error: parsed.error };
+    return {
+      ok: true,
+      frame: { kind: 'event', channel, seq, event: parsed.event, payload: parsed.payload },
+    };
+  }
+  return { ok: false, error: `channel frame: unknown kind ${String(kind)}` };
+}

package/src/client.ts

@@ -0,0 +1,17 @@
+/** Browser-safe protocol surface: wire unions plus runtime frame decoders, with no Node admission code. */
+export {
+  MAX_INBOUND_FRAME_BYTES,
+  decodeClientMessage,
+  decodeFrame,
+  decodeServerMessage,
+} from './message-decoders.js';
+export type { TMessageDecodeResult } from './message-decoders.js';
+// The one list of messages an observer may send: the host refuses the rest, a client sends no others.
+export { isObserverMessageType } from './observer-messages.js';
+export type {
+  IWireHistoryEntry,
+  TClientMessage,
+  TServerMessage,
+  TSeqServerMessage,
+  TWireExecutionResult,
+} from './wire-messages.js';

package/src/handoff-chunking.ts

@@ -0,0 +1,275 @@
+/**
+ * HANDOFF-001 (#1811): moving a session record that does not fit in one frame.
+ *
+ * A data channel has a maximum message size; a session record is a whole conversation. So the
+ * payload travels in pieces, and this owns the two halves of that: cutting it up, and putting it
+ * back together in the face of retries, reordering and a peer that says something inconsistent.
+ *
+ * ## Why the cut is made on BYTES rather than on the string
+ *
+ * The channel's limit is in bytes, and the serialized record is a JavaScript string — UTF-16 code
+ * units, where one character can be one byte or four. Slicing by characters and hoping the pieces
+ * fit means either measuring each slice's encoded length anyway, or shipping frames that overflow
+ * the channel for anyone whose conversation contains an emoji or a non-Latin script.
+ *
+ * Cutting the encoded bytes makes the budget exact. It costs base64's third: a byte slice is not a
+ * valid string on its own — it can end mid-character — so it cannot ride in a JSON frame as text.
+ * That cost is deliberate and is the smaller risk. The alternative works only because
+ * `JSON.stringify` has escaped lone surrogates since ES2019; a transfer whose correctness rests on
+ * that, and which fails as silent corruption when something in the chain does not, is not a trade
+ * worth a third of the bandwidth.
+ *
+ * ## What this does NOT decide
+ *
+ * It does not verify the digest. `verifyHandoffPayload` owns that, and asking the same question in
+ * two places is how the two answers drift. This reports that all the pieces arrived; whether they
+ * are the RIGHT pieces is the next check, and it deliberately runs on the whole reassembled payload
+ * rather than per chunk — a per-chunk digest would say each piece is intact while the set is not the
+ * set that was sent.
+ */
+
+import type { IHandoffIntegrity } from '@robota-sdk/agent-interface-session-mobility';
+
+/**
+ * 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.
+ */
+export 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.
+ */
+export const DEFAULT_MAX_CHUNK_BYTES = 16 * 1024;
+
+// This module is exported from the package root, which also builds for the browser, so it uses the
+// web platform's bytes, text codecs and base64 (`btoa`/`atob`) rather than Node's `Buffer`.
+
+/** How many bytes go through `String.fromCharCode` at once, well under the argument-count limit. */
+const BINARY_STRING_STEP = 0x8000;
+
+function toBase64(bytes: Uint8Array): string {
+  let binary = '';
+  for (let offset = 0; offset < bytes.length; offset += BINARY_STRING_STEP) {
+    binary += String.fromCharCode(...bytes.subarray(offset, offset + BINARY_STRING_STEP));
+  }
+  return btoa(binary);
+}
+
+/** The bytes `data` encodes, or `undefined` when it is not base64 at all. */
+function fromBase64(data: string): Uint8Array | undefined {
+  let binary: string;
+  try {
+    binary = atob(data);
+  } catch {
+    return undefined;
+  }
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+
+function sameBytes(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i += 1) if (a[i] !== b[i]) return false;
+  return true;
+}
+
+/**
+ * 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.
+ */
+export function chunkHandoffPayload(
+  handoffId: string,
+  serialized: string,
+  maxChunkBytes: number = DEFAULT_MAX_CHUNK_BYTES,
+): readonly IHandoffChunk[] {
+  if (!Number.isInteger(maxChunkBytes) || maxChunkBytes < 1) {
+    throw new Error(
+      `handoff chunking: maxChunkBytes must be a positive integer, got ${maxChunkBytes}. ` +
+        'A zero or negative budget produces an infinite sequence of empty chunks, which presents ' +
+        'as a hang rather than as the configuration error it is.',
+    );
+  }
+  const bytes = new TextEncoder().encode(serialized);
+  // An empty payload is still one chunk. Zero chunks would leave the receiver unable to tell a
+  // completed empty transfer from one that never started.
+  const total = Math.max(1, Math.ceil(bytes.byteLength / maxChunkBytes));
+  const chunks: IHandoffChunk[] = [];
+  for (let index = 0; index < total; index += 1) {
+    const slice = bytes.subarray(index * maxChunkBytes, (index + 1) * maxChunkBytes);
+    chunks.push({ handoffId, index, total, data: toBase64(slice) });
+  }
+  return chunks;
+}
+
+/** Why a chunk was not accepted. */
+export 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';
+
+export 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';
+
+export 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.
+ */
+export class HandoffChunkAssembler {
+  private readonly chunks = new Map<number, Uint8Array>();
+  private declaredTotal: number | undefined;
+
+  constructor(private readonly handoffId: string) {}
+
+  get received(): number {
+    return this.chunks.size;
+  }
+
+  get expected(): number | undefined {
+    return this.declaredTotal;
+  }
+
+  /** Take one chunk. Reordering and retries are normal; inconsistency is not. */
+  accept(chunk: IHandoffChunk): IChunkResult {
+    const refuse = (rejection: TChunkRejection): IChunkResult => ({
+      outcome: 'refused',
+      rejection,
+      received: this.chunks.size,
+      ...(this.declaredTotal !== undefined ? { expected: this.declaredTotal } : {}),
+    });
+
+    if (chunk.handoffId !== this.handoffId) return refuse('wrong-handoff');
+    if (!Number.isInteger(chunk.total) || chunk.total < 1) return refuse('inconsistent-total');
+    if (this.declaredTotal !== undefined && chunk.total !== this.declaredTotal) {
+      // A peer that changes its mind about the size has either restarted the transfer under the
+      // same id or is not the peer we started with. Either way the pieces held so far can no longer
+      // be assumed to belong together.
+      return refuse('inconsistent-total');
+    }
+    if (!Number.isInteger(chunk.index) || chunk.index < 0 || chunk.index >= chunk.total) {
+      return refuse('out-of-range');
+    }
+
+    const decoded = fromBase64(chunk.data);
+    // Base64 decoding is lenient — it skips whitespace and accepts non-canonical padding — so a
+    // mangled chunk could silently become a different one and corrupt the payload in a way only the
+    // final digest would catch, after the whole transfer completed. Re-encoding is how the leniency
+    // is detected here instead.
+    if (decoded === undefined || toBase64(decoded) !== chunk.data) return refuse('undecodable');
+
+    this.declaredTotal = chunk.total;
+    const held = this.chunks.get(chunk.index);
+    if (held !== undefined) {
+      // A retry re-sending the same bytes is normal. Different bytes for the same index is the
+      // inconsistent case again, and the same reasoning applies.
+      if (sameBytes(held, decoded)) {
+        return { outcome: 'duplicate', received: this.chunks.size, expected: chunk.total };
+      }
+      return refuse('inconsistent-total');
+    }
+
+    this.chunks.set(chunk.index, decoded);
+    if (this.chunks.size < chunk.total) {
+      return { outcome: 'accepted', received: this.chunks.size, expected: chunk.total };
+    }
+    return {
+      outcome: 'complete',
+      serialized: this.reassemble(chunk.total),
+      received: this.chunks.size,
+      expected: chunk.total,
+    };
+  }
+
+  /** Which indices are still missing, so a caller can ask for them rather than restarting. */
+  missing(): readonly number[] {
+    if (this.declaredTotal === undefined) return [];
+    const gaps: number[] = [];
+    for (let i = 0; i < this.declaredTotal; i += 1) if (!this.chunks.has(i)) gaps.push(i);
+    return gaps;
+  }
+
+  /** Drop everything held. The transfer was abandoned, or its integrity check failed. */
+  discard(): void {
+    this.chunks.clear();
+    this.declaredTotal = undefined;
+  }
+
+  private reassemble(total: number): string {
+    const ordered: Uint8Array[] = [];
+    for (let i = 0; i < total; i += 1) {
+      const part = this.chunks.get(i);
+      if (part === undefined) {
+        // Unreachable: size equalled total and every index was range-checked on the way in. Stated
+        // as an error rather than a non-null assertion, because the assertion would be the thing
+        // that hid it if the invariant ever broke.
+        throw new Error(`handoff chunking: chunk ${i} of ${total} is missing at reassembly.`);
+      }
+      ordered.push(part);
+    }
+    const joined = new Uint8Array(ordered.reduce((size, part) => size + part.length, 0));
+    let offset = 0;
+    for (const part of ordered) {
+      joined.set(part, offset);
+      offset += part.length;
+    }
+    // Keep a leading byte-order mark: it is part of the payload, as it was with `Buffer`.
+    return new TextDecoder('utf-8', { ignoreBOM: true }).decode(joined);
+  }
+}
+
+/**
+ * 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.
+ */
+export function chunkCountFor(
+  integrity: IHandoffIntegrity,
+  maxChunkBytes: number = DEFAULT_MAX_CHUNK_BYTES,
+): number {
+  return Math.max(1, Math.ceil(integrity.byteLength / maxChunkBytes));
+}

package/src/index.ts

@@ -0,0 +1,135 @@
+/**
+ * Browser-safe entry point for `@robota-sdk/agent-transport`.
+ *
+ * ## Why this file exists
+ *
+ * The package's `./node` entry owns `admission.ts` and `handoff-manifest.ts`, the only modules
+ * that import `node:crypto`. Keeping those modules out of this root prevents a browser consumer
+ * from pulling a Node builtin into its bundle.
+ *
+ * ## What is in, and why
+ *
+ * Everything in `src/index.ts` EXCEPT the two modules that touch `node:crypto`. Read off the actual
+ * import graph, not off intent:
+ *
+ *   node:crypto reachers   `admission.ts`, `handoff-manifest.ts` — and nothing inside the package
+ *                          imports either of them, so removing both from this barrel severs the
+ *                          builtin from this entry's graph entirely.
+ *   everything else        `session-message-handler` → {`background-messages`, `message-decoders`,
+ *                          `session-events`}, `session-resume-bridge` → {`outbound-delivery`,
+ *                          `resume-buffer`, `session-message-handler`, `session-events`}, `channel-frames`,
+ *                          `peer-message-ledger`, `handoff-chunking`,
+ *                          `protocol-session`, `wire-messages` — no builtin on any path.
+ *
+ * Handoff authority, offer refusal, and inventory decisions live in
+ * `agent-interface-session-mobility`, outside this wire package.
+ *
+ * The handoff MANIFEST types are omitted along with their functions. Keeping the `export type` lines
+ * would be free at runtime, but it would put `node/handoff-manifest.ts` back on this entry's import graph
+ * — and the `browser-package-node-subpath` scan that guards this file walks EVERY import edge rather
+ * than trying to tell a type edge from a value one. A check that has to be clever about which edges
+ * count is a check that can be fooled; a browser consumer that needs those types is asking for the
+ * Node surface and should say so by importing `./node`.
+ */
+
+export { createSessionMessageHandler } from './session-message-handler.js';
+export type {
+  ISessionMessageHandlerOptions,
+  TSessionSurfaceRole,
+} from './session-message-handler.js';
+// ARCH-030: the connection-scoped outbound delivery boundary every carrier builds and passes down.
+export {
+  ATTACHED_SURFACE_MAX_PENDING_BYTES,
+  createOutboundDelivery,
+  createPendingStallClock,
+  isOverPendingBudget,
+  DEFAULT_MAX_PENDING_BYTES,
+  DEFAULT_MAX_PENDING_MS,
+} from './outbound-delivery.js';
+export type {
+  IPendingStallClock,
+  TDeliveryErrorHandler,
+  TOutboundDeliver,
+} from './outbound-delivery.js';
+export { PROTOCOL_SESSION_EVENT_CLASSIFICATION } from './session-events.js';
+// The one list of messages an observer may send: the host refuses the rest, a client sends no others.
+export { isObserverMessageType } from './observer-messages.js';
+// The most history one frame carries, sized for the tightest channel; a carrier whose channel is
+// small (a WebRTC data channel) bounds an app view's frame by the same number.
+export { HISTORY_PAGE_MAX_BYTES } from './session-query-messages.js';
+export type { TProtocolSessionEventClassification } from './session-events.js';
+export type { IProtocolSession } from './protocol-session.js';
+export type {
+  IWireAgentDefinitionSummary,
+  IWireHistoryEntry,
+  TClientMessage,
+  TServerMessage,
+  TSeqServerMessage,
+  TWireExecutionResult,
+} from './wire-messages.js';
+// Issue #2045: the owner-side runtime decoders; carriers implement `raw → decodeFrame → typed`.
+export {
+  MAX_INBOUND_FRAME_BYTES,
+  decodeClientMessage,
+  decodeFrame,
+  decodeServerMessage,
+} from './message-decoders.js';
+export type { TMessageDecodeResult } from './message-decoders.js';
+export { ResumeBuffer } from './resume-buffer.js';
+export type { IResumeBufferOptions, IBufferedFrame, TResumeTail } from './resume-buffer.js';
+// TRANS-001 — payload-agnostic channel frame codec (transport-neutral, body-opaque).
+export {
+  CHANNEL_FRAME_MAGIC,
+  CHANNEL_FRAME_VERSION,
+  decodeChannelFrame,
+  encodeBinaryFrame,
+  encodeChannelEventFrame,
+  isChannelFrame,
+} from './channel-frames.js';
+export { SessionResumeBridge } from './session-resume-bridge.js';
+export type {
+  ISessionResumeBridgeOptions,
+  TResumeSink,
+  IAttachOptions,
+} from './session-resume-bridge.js';
+// #3282 §4a: the Settings screen's host-owned read/write seam (parallels `IUsageQueryReporters`).
+export { handleSettingsMessage, isSettingsMessage } from './settings-messages.js';
+export type { ISettingsReporter, TSettingsUpdateOutcome } from './settings-messages.js';
+
+// SEC-008 admission is NOT here: `src/node/admission.ts` mints and compares transport tokens with
+// `node:crypto`. A browser never mints one — it presents one it was handed — so the exclusion costs
+// the browser surface nothing it could have used.
+
+// PEER-001 (#1809): the receiver's record of what it has already taken responsibility for. Lives
+// here rather than in a carrier because duplicate, retry and gap are questions about what was SEEN
+// BEFORE, and no socket or frame codec has the memory to answer them.
+export {
+  acknowledgePeerMessage,
+  admitPeerMessage,
+  createPeerMessageLedger,
+  forgetPeerOrigin,
+} from './peer-message-ledger.js';
+export type {
+  IPeerMessageLedger,
+  IPeerMessageRejection,
+  IPeerMessageVerdict,
+} from './peer-message-ledger.js';
+
+// The argument a person recognises a tool call by, shared by every transport that asks a person
+// about a permission in its own wire form, so they name the same call the same way.
+export { permissionSummaryArgument } from './permission-summary.js';
+
+// The handoff integrity helpers (`sealHandoffRecord`, `verifyHandoffPayload`) are NOT
+// here: it hashes with `node:crypto`. Chunking is, because it never hashes anything.
+export {
+  chunkCountFor,
+  chunkHandoffPayload,
+  DEFAULT_MAX_CHUNK_BYTES,
+  HandoffChunkAssembler,
+} from './handoff-chunking.js';
+export type {
+  IChunkResult,
+  IHandoffChunk,
+  TChunkOutcome,
+  TChunkRejection,
+} from './handoff-chunking.js';

package/src/loop-control-messages.ts

@@ -0,0 +1,34 @@
+import type { TOutboundDeliver } from './outbound-delivery.js';
+import type { IProtocolSession } from './protocol-session.js';
+import type { TClientMessage } from './wire-messages.js';
+
+type TLoopControlMessage = Extract<TClientMessage, { type: 'stop-waiting-loop' }>;
+
+export function isLoopControlMessage(msg: TClientMessage): msg is TLoopControlMessage {
+  return msg.type === 'stop-waiting-loop';
+}
+
+/**
+ * Stop the self-paced loop that is waiting for its next wake. The session decides which loop, if
+ * any; the reply carries its outcome, and a session that throws is reported as a failed stop.
+ */
+export function handleLoopControlMessage(
+  session: IProtocolSession,
+  deliver: TOutboundDeliver,
+  msg: TLoopControlMessage,
+): void {
+  const { requestId } = msg;
+  session.stopWaitingSelfPacedLoop().then(
+    (outcome) => deliver({ type: 'waiting_loop_stop', requestId, outcome }),
+    (error: unknown) =>
+      deliver({
+        type: 'waiting_loop_stop',
+        requestId,
+        outcome: { kind: 'failed', message: errorMessage(error) },
+      }),
+  );
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}