@robota-sdk/agent-transport 3.0.0-beta.78 → 3.0.0-beta.81

package/src/background-messages.ts

@@ -0,0 +1,169 @@
+import type { TOutboundDeliver } from './outbound-delivery.js';
+import type { IProtocolSession } from './protocol-session.js';
+import type { TBackgroundControlAction, TClientMessage } from './wire-messages.js';
+
+export function handleBackgroundQueryMessage(
+  session: IProtocolSession,
+  deliver: TOutboundDeliver,
+  msg: Extract<
+    TClientMessage,
+    | { type: 'get-background-tasks' | 'get-background-task' | 'read-background-task-log' }
+    | {
+        type:
+          'get-background-job-groups' | 'get-background-job-group' | 'wait-background-job-group';
+      }
+  >,
+): void {
+  if (msg.type === 'get-background-tasks') {
+    deliver({ type: 'background_tasks', tasks: session.listBackgroundTasks(msg.filter) });
+    return;
+  }
+  if (msg.type === 'get-background-task') {
+    sendBackgroundTaskSnapshot(session, deliver, msg);
+    return;
+  }
+  if (msg.type === 'get-background-job-groups') {
+    deliver({ type: 'background_job_groups', groups: session.listBackgroundJobGroups() });
+    return;
+  }
+  if (msg.type === 'get-background-job-group') {
+    sendBackgroundJobGroupSnapshot(session, deliver, msg);
+    return;
+  }
+  if (msg.type === 'wait-background-job-group') {
+    sendBackgroundJobGroupWaitResult(session, deliver, msg);
+    return;
+  }
+  sendBackgroundTaskLogPage(session, deliver, msg);
+}
+
+export function handleBackgroundControlMessage(
+  session: IProtocolSession,
+  deliver: TOutboundDeliver,
+  msg: Extract<
+    TClientMessage,
+    { type: 'cancel-background-task' | 'close-background-task' | 'send-background-task' }
+  >,
+): void {
+  if (!msg.taskId) {
+    deliver({ type: 'protocol_error', message: 'taskId is required' });
+    return;
+  }
+  if (msg.type === 'cancel-background-task') {
+    sendBackgroundTaskControlResult(
+      deliver,
+      'cancel',
+      msg.taskId,
+      session.cancelBackgroundTask(msg.taskId, msg.reason),
+    );
+    return;
+  }
+  if (msg.type === 'close-background-task') {
+    sendBackgroundTaskControlResult(
+      deliver,
+      'close',
+      msg.taskId,
+      session.closeBackgroundTask(msg.taskId),
+    );
+    return;
+  }
+  sendBackgroundTaskInput(session, deliver, msg);
+}
+
+function sendBackgroundTaskSnapshot(
+  session: IProtocolSession,
+  deliver: TOutboundDeliver,
+  msg: Extract<TClientMessage, { type: 'get-background-task' }>,
+): void {
+  if (!msg.taskId) {
+    deliver({ type: 'protocol_error', message: 'taskId is required' });
+    return;
+  }
+  deliver({
+    type: 'background_task',
+    taskId: msg.taskId,
+    task: session.getBackgroundTask(msg.taskId) ?? null,
+  });
+}
+
+function sendBackgroundTaskLogPage(
+  session: IProtocolSession,
+  deliver: TOutboundDeliver,
+  msg: Extract<TClientMessage, { type: 'read-background-task-log' }>,
+): void {
+  if (!msg.taskId) {
+    deliver({ type: 'protocol_error', message: 'taskId is required' });
+    return;
+  }
+  session.readBackgroundTaskLog(msg.taskId, msg.cursor).then(
+    (page) => deliver({ type: 'background_task_log', taskId: msg.taskId, page }),
+    (error: Error) => deliver({ type: 'protocol_error', message: error.message }),
+  );
+}
+
+function sendBackgroundJobGroupSnapshot(
+  session: IProtocolSession,
+  deliver: TOutboundDeliver,
+  msg: Extract<TClientMessage, { type: 'get-background-job-group' }>,
+): void {
+  if (!msg.groupId) {
+    deliver({ type: 'protocol_error', message: 'groupId is required' });
+    return;
+  }
+  deliver({
+    type: 'background_job_group',
+    groupId: msg.groupId,
+    group: session.getBackgroundJobGroup(msg.groupId) ?? null,
+  });
+}
+
+function sendBackgroundJobGroupWaitResult(
+  session: IProtocolSession,
+  deliver: TOutboundDeliver,
+  msg: Extract<TClientMessage, { type: 'wait-background-job-group' }>,
+): void {
+  if (!msg.groupId) {
+    deliver({ type: 'protocol_error', message: 'groupId is required' });
+    return;
+  }
+  session.waitBackgroundJobGroup(msg.groupId).then(
+    (group) => deliver({ type: 'background_job_group', groupId: msg.groupId, group }),
+    (error: Error) => deliver({ type: 'protocol_error', message: error.message }),
+  );
+}
+
+function sendBackgroundTaskInput(
+  session: IProtocolSession,
+  deliver: TOutboundDeliver,
+  msg: Extract<TClientMessage, { type: 'send-background-task' }>,
+): void {
+  if (!msg.input) {
+    deliver({ type: 'protocol_error', message: 'input is required' });
+    return;
+  }
+  sendBackgroundTaskControlResult(
+    deliver,
+    'send',
+    msg.taskId,
+    session.sendBackgroundTask(msg.taskId, msg.input),
+  );
+}
+
+function sendBackgroundTaskControlResult(
+  deliver: TOutboundDeliver,
+  action: TBackgroundControlAction,
+  taskId: string,
+  operation: Promise<void>,
+): void {
+  operation.then(
+    () => deliver({ type: 'background_task_control_result', action, taskId, success: true }),
+    (error: Error) =>
+      deliver({
+        type: 'background_task_control_result',
+        action,
+        taskId,
+        success: false,
+        message: error.message,
+      }),
+  );
+}

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,9 @@
+/** 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';
+export type { TClientMessage, TServerMessage, TSeqServerMessage } from './wire-messages.js';

package/src/handoff-chunking.ts

@@ -0,0 +1,235 @@
+/**
+ * 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;
+
+/**
+ * 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 = Buffer.from(serialized, 'utf8');
+  // 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: slice.toString('base64') });
+  }
+  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, Buffer>();
+  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 = Buffer.from(chunk.data, 'base64');
+    // Buffer.from is lenient — it drops what it cannot parse rather than throwing, so a mangled
+    // chunk would silently become a shorter 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.toString('base64') !== 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 (held.equals(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: Buffer[] = [];
+    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);
+    }
+    return Buffer.concat(ordered).toString('utf8');
+  }
+}
+
+/**
+ * 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));
+}