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

package/src/__tests__/payload-channels.test.ts

@@ -0,0 +1,233 @@
+import {
+  decodeChannelFrame,
+  encodeBinaryFrame,
+  encodeChannelEventFrame,
+} from '@robota-sdk/agent-transport';
+import { describe, it, expect, vi } from 'vitest';
+
+import { PayloadChannelRegistry } from '../payload-channels.js';
+
+import type { IBinaryFrame } from '@robota-sdk/agent-interface-transport';
+
+/**
+ * TRANS-001 — consumer-declared channels on the payload-agnostic carrier.
+ *
+ * The registry is the transport-side half of `IPayloadChannelHost`: consumers declare a channel
+ * (its name, its event types, whether it carries opaque bytes) and get a typed handle. Undeclared
+ * traffic is an explicit protocol error in BOTH directions — never a silent pass-through.
+ */
+
+/** A remote peer's outbound binary frame, built through the shared codec (never re-implemented here). */
+function peerBinary(channel: string, seq: number, payload: Uint8Array): Uint8Array {
+  return encodeBinaryFrame({ kind: 'binary', channel, seq, payload });
+}
+
+/** A remote peer's outbound event frame — including event names the local channel never declared. */
+function peerEvent(channel: string, seq: number, event: string, payload: unknown): Uint8Array {
+  return encodeChannelEventFrame({
+    kind: 'event',
+    channel,
+    seq,
+    event,
+    payload: payload as never,
+  });
+}
+
+describe('PayloadChannelRegistry (TRANS-001)', () => {
+  it('fans a declared event out to every attached sink as an encoded frame', () => {
+    const registry = new PayloadChannelRegistry();
+    const channel = registry.registerChannel<{ caption: { text: string } }>({
+      name: 'captions',
+      events: ['caption'],
+    });
+
+    const sinkA: Uint8Array[] = [];
+    const sinkB: Uint8Array[] = [];
+    registry.addSink((b) => sinkA.push(b));
+    registry.addSink((b) => sinkB.push(b));
+
+    channel.sendEvent('caption', { text: 'hi' });
+
+    expect(sinkA).toHaveLength(1);
+    expect(sinkB).toHaveLength(1);
+    const decoded = decodeChannelFrame(sinkA[0]!);
+    expect(decoded.ok).toBe(true);
+    if (!decoded.ok) return;
+    expect(decoded.frame.kind).toBe('event');
+    expect(decoded.frame.channel).toBe('captions');
+  });
+
+  it('assigns a monotonic per-channel seq across interleaved binary and event frames', () => {
+    const registry = new PayloadChannelRegistry();
+    const channel = registry.registerChannel<{ mark: { at: number } }>({
+      name: 'mixed',
+      events: ['mark'],
+      binary: true,
+    });
+    const wire: Uint8Array[] = [];
+    registry.addSink((b) => wire.push(b));
+
+    channel.sendBinary(Uint8Array.from([1]));
+    channel.sendEvent('mark', { at: 1 });
+    channel.sendBinary(Uint8Array.from([2]));
+
+    const seqs = wire.map((b) => {
+      const d = decodeChannelFrame(b);
+      return d.ok ? d.frame.seq : -1;
+    });
+    expect(seqs).toEqual([0, 1, 2]);
+  });
+
+  it('keeps each channel on its own independent seq counter', () => {
+    const registry = new PayloadChannelRegistry();
+    const a = registry.registerChannel({ name: 'a', events: [], binary: true });
+    const b = registry.registerChannel({ name: 'b', events: [], binary: true });
+    const wire: Uint8Array[] = [];
+    registry.addSink((x) => wire.push(x));
+
+    a.sendBinary(Uint8Array.from([1]));
+    b.sendBinary(Uint8Array.from([1]));
+    a.sendBinary(Uint8Array.from([2]));
+
+    const pairs = wire.map((x) => {
+      const d = decodeChannelFrame(x);
+      return d.ok ? `${d.frame.channel}:${d.frame.seq}` : 'bad';
+    });
+    expect(pairs).toEqual(['a:0', 'b:0', 'a:1']);
+  });
+
+  it('dispatches an inbound binary frame to that channel only', () => {
+    const registry = new PayloadChannelRegistry();
+    const audio = registry.registerChannel({ name: 'audio', events: [], binary: true });
+    const other = registry.registerChannel({ name: 'other', events: [], binary: true });
+
+    const audioFrames: IBinaryFrame[] = [];
+    const otherFrames: IBinaryFrame[] = [];
+    audio.onBinary((f) => audioFrames.push(f));
+    other.onBinary((f) => otherFrames.push(f));
+
+    const result = registry.receive(peerBinary('audio', 4, Uint8Array.from([7, 8, 9])));
+
+    expect(result.ok).toBe(true);
+    expect(otherFrames).toHaveLength(0);
+    expect(audioFrames).toHaveLength(1);
+    expect(audioFrames[0]!.seq).toBe(4);
+    expect(Array.from(audioFrames[0]!.payload)).toEqual([7, 8, 9]);
+  });
+
+  it('dispatches an inbound event only to handlers registered for that event name', () => {
+    const registry = new PayloadChannelRegistry();
+    const channel = registry.registerChannel<{
+      caption: { text: string };
+      speaker: { id: string };
+    }>({ name: 'app', events: ['caption', 'speaker'] });
+    const onCaption = vi.fn();
+    const onSpeaker = vi.fn();
+    channel.onEvent('caption', onCaption);
+    channel.onEvent('speaker', onSpeaker);
+
+    const result = registry.receive(peerEvent('app', 0, 'caption', { text: 'x' }));
+
+    expect(result.ok).toBe(true);
+    // The handler receives the payload plus the full frame (channel/seq envelope).
+    expect(onCaption).toHaveBeenCalledWith(
+      { text: 'x' },
+      expect.objectContaining({ kind: 'event', channel: 'app', event: 'caption', seq: 0 }),
+    );
+    expect(onSpeaker).not.toHaveBeenCalled();
+  });
+
+  it('unsubscribes a handler through the returned disposer', () => {
+    const registry = new PayloadChannelRegistry();
+    const channel = registry.registerChannel({ name: 'c', events: [], binary: true });
+    const handler = vi.fn();
+    const off = channel.onBinary(handler);
+
+    registry.receive(peerBinary('c', 0, Uint8Array.from([1])));
+    off();
+    registry.receive(peerBinary('c', 1, Uint8Array.from([2])));
+
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
+
+  it('returns an error result for a frame addressed to an unregistered channel', () => {
+    const registry = new PayloadChannelRegistry();
+    const result = registry.receive(peerBinary('ghost', 0, Uint8Array.from([1])));
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error).toMatch(/ghost/);
+  });
+
+  it('returns an error result for an event the channel never declared', () => {
+    const registry = new PayloadChannelRegistry();
+    registry.registerChannel<{ caption: { text: string } }>({ name: 'app', events: ['caption'] });
+    const result = registry.receive(peerEvent('app', 0, 'not-declared', { a: 1 }));
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error).toMatch(/not-declared/);
+  });
+
+  it('returns an error result for binary traffic on a non-binary channel', () => {
+    const registry = new PayloadChannelRegistry();
+    registry.registerChannel({ name: 'text-only', events: [] });
+    const result = registry.receive(peerBinary('text-only', 0, Uint8Array.from([1])));
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error).toMatch(/binary/i);
+  });
+
+  it('surfaces a malformed frame as an error result', () => {
+    const registry = new PayloadChannelRegistry();
+    const result = registry.receive(Uint8Array.from([1, 2, 3]));
+    expect(result.ok).toBe(false);
+  });
+
+  it('rejects a duplicate channel registration', () => {
+    const registry = new PayloadChannelRegistry();
+    registry.registerChannel({ name: 'dup', events: [] });
+    expect(() => registry.registerChannel({ name: 'dup', events: [] })).toThrow(/already/i);
+  });
+
+  it('rejects sending an undeclared event name', () => {
+    const registry = new PayloadChannelRegistry();
+    const channel = registry.registerChannel<{ known: { a: number } }>({
+      name: 'app',
+      events: ['known'],
+    });
+    // Cast: the compiler already rejects this call; the runtime guard is the wire-level contract.
+    const untyped = channel as unknown as { sendEvent: (e: string, p: unknown) => void };
+    expect(() => untyped.sendEvent('nope', {})).toThrow(/nope/);
+  });
+
+  it('rejects sending binary on a channel that did not opt into binary', () => {
+    const registry = new PayloadChannelRegistry();
+    const channel = registry.registerChannel({ name: 'text-only', events: [] });
+    expect(() => channel.sendBinary(Uint8Array.from([1]))).toThrow(/binary/i);
+  });
+
+  it('stops delivering to a closed channel and frees the name', () => {
+    const registry = new PayloadChannelRegistry();
+    const channel = registry.registerChannel({ name: 'temp', events: [], binary: true });
+    const handler = vi.fn();
+    channel.onBinary(handler);
+    channel.close();
+
+    const result = registry.receive(peerBinary('temp', 0, Uint8Array.from([1])));
+    expect(result.ok).toBe(false);
+    expect(handler).not.toHaveBeenCalled();
+    expect(() => registry.registerChannel({ name: 'temp', events: [] })).not.toThrow();
+  });
+
+  it('drops a detached sink', () => {
+    const registry = new PayloadChannelRegistry();
+    const channel = registry.registerChannel({ name: 'c', events: [], binary: true });
+    const seen: Uint8Array[] = [];
+    const detach = registry.addSink((b) => seen.push(b));
+
+    channel.sendBinary(Uint8Array.from([1]));
+    detach();
+    channel.sendBinary(Uint8Array.from([2]));
+
+    expect(seen).toHaveLength(1);
+  });
+});

package/src/__tests__/ws-payload-channel.e2e.test.ts

@@ -0,0 +1,255 @@
+import { randomBytes } from 'node:crypto';
+
+import { createTestInteractiveSession } from '@robota-sdk/agent-interface-session/testing';
+import { decodeChannelFrame, encodeBinaryFrame } from '@robota-sdk/agent-transport';
+import { WebSocket } from 'ws';
+import { describe, it, expect, afterEach, vi } from 'vitest';
+
+import { WsTransport } from '../ws-transport-configurable.js';
+
+import type { IBinaryFrame } from '@robota-sdk/agent-interface-transport';
+import type { IInteractiveSession } from '@robota-sdk/agent-interface-session';
+import type { TServerMessage } from '@robota-sdk/agent-transport';
+
+/**
+ * TRANS-001 functional / user-execution test.
+ *
+ * One WebSocket connection carries THREE things at once: the existing text-agent protocol
+ * (`text_delta` …), opaque binary frames the transport never interprets, and a consumer-declared
+ * custom event. The receiver must reassemble the bytes byte-identically and in order, while the
+ * text-delta profile keeps working unchanged.
+ */
+
+type TListener = (...args: unknown[]) => void;
+
+/** Minimal session double with a REAL emitter, so `text_delta` genuinely flows over the wire. */
+function emittingSession(): IInteractiveSession & { emit: (event: string, arg: unknown) => void } {
+  const listeners = new Map<string, Set<TListener>>();
+  // ARCH-012: the conformant double plus a real emitter. The hand-rolled partial this replaces was
+  // `as unknown as IInteractiveSession` over nine members — a cast that let the double omit the rest,
+  // including the ones the contract now requires, so this suite ran against a session shape no
+  // implementation could actually have.
+  const session = createTestInteractiveSession({
+    // A spy, because a case below asserts on its calls. The double's default is a real no-op, which
+    // is the right default and the wrong thing to assert against.
+    submit: vi.fn().mockResolvedValue(undefined),
+    getExecutionWorkspaceSnapshot: vi.fn().mockReturnValue({ entries: [] }),
+    getContextState: vi.fn().mockReturnValue({ usedPercentage: 0, usedTokens: 0, maxTokens: 1 }),
+    on: ((event: string, fn: TListener) => {
+      const set = listeners.get(event) ?? new Set<TListener>();
+      set.add(fn);
+      listeners.set(event, set);
+    }) as IInteractiveSession['on'],
+    off: ((event: string, fn: TListener) => {
+      listeners.get(event)?.delete(fn);
+    }) as IInteractiveSession['off'],
+  });
+  return Object.assign(session, {
+    emit: (event: string, arg: unknown) => {
+      for (const fn of listeners.get(event) ?? []) fn(arg);
+    },
+  });
+}
+
+const started: WsTransport[] = [];
+const clients: WebSocket[] = [];
+afterEach(async () => {
+  while (clients.length) clients.pop()!.close();
+  while (started.length) await started.pop()!.stop();
+});
+
+/**
+ * Connect and attach the message listener BEFORE the socket opens — the server sends its
+ * handshake frames (`messages`, `execution_workspace_event`) the instant the connection lands, so a
+ * listener attached after `open` would race them.
+ */
+async function connect(
+  port: number,
+  onMessage: (data: Buffer, isBinary: boolean) => void,
+): Promise<WebSocket> {
+  const ws = new WebSocket(`ws://127.0.0.1:${port}`);
+  ws.binaryType = 'nodebuffer';
+  clients.push(ws);
+  ws.on('message', onMessage);
+  await new Promise<void>((resolve, reject) => {
+    ws.on('open', () => resolve());
+    ws.on('error', reject);
+  });
+  return ws;
+}
+
+/** Resolve once `predicate` holds, or reject at the deadline (no arbitrary sleeps). */
+async function until(predicate: () => boolean, label: string, timeoutMs = 5000): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (!predicate()) {
+    if (Date.now() > deadline) throw new Error(`timed out waiting for ${label}`);
+    await new Promise((r) => setTimeout(r, 10));
+  }
+}
+
+describe('WsTransport payload-agnostic channels (TRANS-001 e2e)', () => {
+  it('carries interleaved text deltas, opaque binary frames, and a custom event on one connection', async () => {
+    const transport = new WsTransport({
+      port: 17840,
+      maxRetries: 40,
+      open: true,
+      openReason: 'SEC-008: this case is about payload channels, not admission',
+    });
+    const channel = transport.registerChannel<{ manifest: { name: string; size: number } }>({
+      name: 'file',
+      events: ['manifest'],
+      binary: true,
+    });
+    const session = emittingSession();
+    transport.attach(session);
+    await transport.start();
+    started.push(transport);
+
+    // Receiver side: split text (agent protocol) from binary (payload-agnostic carrier).
+    const serverMessages: TServerMessage[] = [];
+    const received: IBinaryFrame[] = [];
+    const customEvents: { name: string; size: number }[] = [];
+    await connect(transport.boundPort!, (data, isBinary) => {
+      if (!isBinary) {
+        serverMessages.push(JSON.parse(data.toString('utf8')) as TServerMessage);
+        return;
+      }
+      const decoded = decodeChannelFrame(new Uint8Array(data));
+      if (!decoded.ok) throw new Error(decoded.error);
+      if (decoded.frame.kind === 'binary') received.push(decoded.frame);
+      else customEvents.push(decoded.frame.payload as { name: string; size: number });
+    });
+
+    // A payload the transport must NOT understand: random bytes, invalid UTF-8, JSON-hostile.
+    const blob = randomBytes(64 * 1024);
+    const CHUNK = 4096;
+
+    channel.sendEvent('manifest', { name: 'payload.bin', size: blob.byteLength });
+    for (let offset = 0; offset < blob.byteLength; offset += CHUNK) {
+      channel.sendBinary(new Uint8Array(blob.subarray(offset, offset + CHUNK)));
+      // Interleave the text-agent profile on the SAME connection.
+      session.emit('text_delta', `chunk@${offset} `);
+    }
+
+    const expectedChunks = Math.ceil(blob.byteLength / CHUNK);
+    await until(() => received.length === expectedChunks, 'all binary chunks');
+    await until(
+      () => serverMessages.filter((m) => m.type === 'text_delta').length === expectedChunks,
+      'all text deltas',
+    );
+
+    // 1. Custom (consumer-declared) event arrived.
+    expect(customEvents).toEqual([{ name: 'payload.bin', size: blob.byteLength }]);
+
+    // 2. Frames arrived in order (WS preserves per-connection frame order) and seq is monotonic.
+    expect(received.map((f) => f.seq)).toEqual(
+      Array.from({ length: expectedChunks }, (_, i) => i + 1), // seq 0 was the manifest event
+    );
+
+    // 3. Byte-identical reassembly.
+    const reassembled = Buffer.concat(received.map((f) => Buffer.from(f.payload)));
+    expect(reassembled.byteLength).toBe(blob.byteLength);
+    expect(reassembled.equals(blob)).toBe(true);
+
+    // 4. The text-agent profile is untouched: the connect handshake + every delta came through.
+    expect(serverMessages[0]?.type).toBe('messages');
+    expect(serverMessages.filter((m) => m.type === 'text_delta')).toHaveLength(expectedChunks);
+  });
+
+  it('reassembles an opaque upload sent by the client, byte-identically and in order', async () => {
+    const transport = new WsTransport({
+      port: 17860,
+      maxRetries: 40,
+      open: true,
+      openReason: 'SEC-008: this case is about payload channels, not admission',
+    });
+    const channel = transport.registerChannel({ name: 'upload', events: [], binary: true });
+    transport.attach(emittingSession());
+    await transport.start();
+    started.push(transport);
+
+    const inbound: IBinaryFrame[] = [];
+    channel.onBinary((frame) => inbound.push(frame));
+
+    const ws = await connect(transport.boundPort!, () => {});
+    const blob = randomBytes(20_000);
+    const CHUNK = 3000;
+    const expectedChunks = Math.ceil(blob.byteLength / CHUNK);
+    for (let offset = 0, seq = 0; offset < blob.byteLength; offset += CHUNK, seq += 1) {
+      ws.send(
+        encodeBinaryFrame({
+          kind: 'binary',
+          channel: 'upload',
+          seq,
+          payload: new Uint8Array(blob.subarray(offset, offset + CHUNK)),
+        }),
+        { binary: true },
+      );
+    }
+
+    await until(() => inbound.length === expectedChunks, 'all uploaded chunks');
+    expect(inbound.map((f) => f.seq)).toEqual(Array.from({ length: expectedChunks }, (_, i) => i));
+    const reassembled = Buffer.concat(inbound.map((f) => Buffer.from(f.payload)));
+    expect(reassembled.equals(blob)).toBe(true);
+  });
+
+  it('answers an unroutable inbound frame with a protocol_error instead of dropping it', async () => {
+    const transport = new WsTransport({
+      port: 17880,
+      maxRetries: 40,
+      open: true,
+      openReason: 'SEC-008: this case is about payload channels, not admission',
+    });
+    transport.attach(emittingSession());
+    await transport.start();
+    started.push(transport);
+
+    const errors: TServerMessage[] = [];
+    const ws = await connect(transport.boundPort!, (data, isBinary) => {
+      if (isBinary) return;
+      const msg = JSON.parse(data.toString('utf8')) as TServerMessage;
+      if (msg.type === 'protocol_error') errors.push(msg);
+    });
+
+    ws.send(
+      encodeBinaryFrame({
+        kind: 'binary',
+        channel: 'never-registered',
+        seq: 0,
+        payload: Uint8Array.from([1, 2, 3]),
+      }),
+      { binary: true },
+    );
+
+    await until(() => errors.length === 1, 'a protocol_error for the unknown channel');
+    expect((errors[0] as { message: string }).message).toMatch(/never-registered/);
+  });
+
+  it('keeps the text-agent profile working when no channel is registered at all', async () => {
+    const transport = new WsTransport({
+      port: 17900,
+      maxRetries: 40,
+      open: true,
+      openReason: 'SEC-008: this case is about payload channels, not admission',
+    });
+    const session = emittingSession();
+    transport.attach(session);
+    await transport.start();
+    started.push(transport);
+
+    const messages: TServerMessage[] = [];
+    const ws = await connect(transport.boundPort!, (data, isBinary) => {
+      if (!isBinary) messages.push(JSON.parse(data.toString('utf8')) as TServerMessage);
+    });
+
+    ws.send(JSON.stringify({ type: 'submit', prompt: 'hello' }));
+    await until(
+      () => (session.submit as ReturnType<typeof vi.fn>).mock.calls.length === 1,
+      'submit',
+    );
+    session.emit('text_delta', 'hi');
+    await until(() => messages.some((m) => m.type === 'text_delta'), 'a text delta');
+
+    expect(messages[0]?.type).toBe('messages');
+  });
+});

package/src/__tests__/ws-session-delivery.test.ts

@@ -0,0 +1,86 @@
+import { createTestInteractiveSession } from '@robota-sdk/agent-interface-session/testing';
+import { createSessionMessageHandler } from '@robota-sdk/agent-transport';
+import { describe, expect, it, vi } from 'vitest';
+import { WebSocket } from 'ws';
+
+import { WsSessionDelivery } from '../ws-session-delivery.js';
+
+import type { IInteractiveSession } from '@robota-sdk/agent-interface-session';
+
+function createSessionHarness(): {
+  session: IInteractiveSession;
+  fireBranchEvent: () => void;
+  handlers: Map<string, (value: unknown) => void>;
+} {
+  const handlers = new Map<string, (value: unknown) => void>();
+  const session = createTestInteractiveSession({
+    on: ((event: string, handler: (value: unknown) => void) => {
+      handlers.set(event, handler);
+    }) as IInteractiveSession['on'],
+    off: ((event: string) => {
+      handlers.delete(event);
+    }) as IInteractiveSession['off'],
+  });
+  return {
+    session,
+    handlers,
+    fireBranchEvent: () =>
+      handlers.get('branch_event')?.({
+        kind: 'checkpoint_created',
+        checkpointId: 'turn-0001',
+        branchId: 'main',
+      }),
+  };
+}
+
+describe('WsSessionDelivery', () => {
+  it('routes a non-open synchronous send through one protocol and sink cleanup', () => {
+    const socket = {
+      readyState: WebSocket.CLOSED,
+      send: vi.fn(),
+      close: vi.fn(),
+    } as unknown as WebSocket;
+    const delivery = new WsSessionDelivery(socket);
+    const detachSink = vi.fn();
+    delivery.bindSinkDetach(detachSink);
+    const harness = createSessionHarness();
+    // ARCH-030: the carrier's own boundary is what the handler receives — there is no raw sink to pass.
+    const handler = createSessionMessageHandler({
+      session: harness.session,
+      deliver: delivery.deliver,
+    });
+    delivery.bindProtocolCleanup(handler.cleanup);
+
+    expect(harness.fireBranchEvent).not.toThrow();
+    expect(detachSink).toHaveBeenCalledTimes(1);
+    expect(harness.handlers.size).toBe(0);
+    expect(socket.close).not.toHaveBeenCalled();
+    delivery.close();
+    expect(detachSink).toHaveBeenCalledTimes(1);
+  });
+
+  it('routes an asynchronous ws.send callback error through the same idempotent cleanup', () => {
+    let sendCallback: ((error?: Error) => void) | undefined;
+    const socket = {
+      readyState: WebSocket.OPEN,
+      send: vi.fn((_data: string, callback: (error?: Error) => void) => {
+        sendCallback = callback;
+      }),
+      close: vi.fn(),
+    } as unknown as WebSocket;
+    const delivery = new WsSessionDelivery(socket);
+    const cleanup = vi.fn();
+    const detachSink = vi.fn();
+    delivery.bindProtocolCleanup(cleanup);
+    delivery.bindSinkDetach(detachSink);
+
+    delivery.deliver({ type: 'history_cleared' });
+    expect(sendCallback).toBeDefined();
+    sendCallback?.(new Error('asynchronous send failed'));
+    sendCallback?.(new Error('duplicate callback'));
+    expect(cleanup).toHaveBeenCalledTimes(1);
+    expect(detachSink).toHaveBeenCalledTimes(1);
+    expect(socket.close).toHaveBeenCalledTimes(1);
+    expect(socket.close).toHaveBeenCalledWith(1011, 'session event delivery failed');
+  });
+});