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

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-binder.test.ts

@@ -0,0 +1,271 @@
+/**
+ * #3189: with a session binder, each WebSocket connection is bound to a session of its own. One
+ * connection's switch — and every event after it — stays on that connection, and the binding is
+ * released when the connection closes. Without a binder every connection shares the attached session.
+ */
+
+import { createTestInteractiveSession } from '@robota-sdk/agent-interface-session/testing';
+import { WebSocket } from 'ws';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { WsTransport } from '../ws-transport-configurable.js';
+
+import type { IWsTransportConfig } from '../ws-transport-config.js';
+import type {
+  IInteractiveSession,
+  ISessionBinder,
+  ISessionBinding,
+  ISessionDirectory,
+  TSessionBindingRole,
+} from '@robota-sdk/agent-interface-session';
+import type { IProtocolSession, TServerMessage } from '@robota-sdk/agent-transport';
+
+type TListener = (...args: unknown[]) => void;
+
+interface IEmittingSession extends IInteractiveSession {
+  emit(event: string, payload?: unknown): void;
+  listenerCount(): number;
+}
+
+function emittingSession(label: string): IEmittingSession {
+  const listeners = new Map<string, Set<TListener>>();
+  const session = createTestInteractiveSession({
+    getMessages: () => [{ role: 'user', content: label }] as never,
+    getExecutionWorkspaceSnapshot: () => ({ entries: [] }) as never,
+    on: ((event: string, handler: TListener) => {
+      if (!listeners.has(event)) listeners.set(event, new Set());
+      listeners.get(event)!.add(handler);
+    }) as IInteractiveSession['on'],
+    off: ((event: string, handler: TListener) => {
+      listeners.get(event)?.delete(handler);
+    }) as IInteractiveSession['off'],
+  });
+  return Object.assign(session, {
+    emit: (event: string, payload?: unknown) =>
+      listeners.get(event)?.forEach((handler) => handler(payload)),
+    listenerCount: () => [...listeners.values()].reduce((sum, set) => sum + set.size, 0),
+  });
+}
+
+interface IFakeBinding extends ISessionBinding<IProtocolSession> {
+  readonly session: IEmittingSession;
+  readonly role: TSessionBindingRole;
+  readonly release: ReturnType<typeof vi.fn>;
+  /** Listeners on the session when `release` ran: the handler must have unsubscribed first. */
+  listenersAtRelease?: number;
+}
+
+/** A binder like the host's: its own session per connection, and a switch that moves only that one. */
+function fakeBinder(overrides: Partial<ISessionDirectory> = {}): {
+  binder: ISessionBinder<IProtocolSession>;
+  bindings: IFakeBinding[];
+} {
+  const bindings: IFakeBinding[] = [];
+  const binder: ISessionBinder<IProtocolSession> = {
+    bind: (role) => {
+      const session = emittingSession(`connection-${bindings.length + 1}`);
+      const directory: ISessionDirectory = {
+        listSessions: () => ({ currentSessionId: 's', sessions: [], unreadableSessionIds: [] }),
+        switchSession: async (sessionId) => session.emit('session_switched', { sessionId }),
+        newSession: async () => session.emit('session_switched', { sessionId: 'new' }),
+        renameSession: async () => undefined,
+        deleteSession: async () => undefined,
+        ...overrides,
+      };
+      const binding: IFakeBinding = {
+        session,
+        directory,
+        role,
+        release: vi.fn(() => {
+          binding.listenersAtRelease = session.listenerCount();
+        }),
+      };
+      bindings.push(binding);
+      return binding;
+    },
+  };
+  return { binder, bindings };
+}
+
+const started: WsTransport[] = [];
+afterEach(async () => {
+  while (started.length) await started.pop()!.stop();
+});
+
+async function startTransport(
+  config: IWsTransportConfig,
+  attached: IProtocolSession = emittingSession('attached'),
+): Promise<WsTransport> {
+  const transport = new WsTransport({
+    port: 17760,
+    maxRetries: 30,
+    open: true,
+    openReason: 'session-binder regression test',
+    ...config,
+  });
+  transport.attach(attached);
+  await transport.start();
+  started.push(transport);
+  return transport;
+}
+
+interface IClient {
+  ws: WebSocket;
+  received: TServerMessage[];
+  send(message: object): void;
+  close(): Promise<void>;
+}
+
+async function connect(transport: WsTransport): Promise<IClient> {
+  const ws = new WebSocket(`ws://127.0.0.1:${transport.boundPort}`);
+  const received: TServerMessage[] = [];
+  ws.on('message', (data) => received.push(JSON.parse(String(data)) as TServerMessage));
+  await new Promise<void>((resolve, reject) => {
+    ws.on('open', resolve);
+    ws.on('error', reject);
+  });
+  // The connection's initial frames arrive before anything the test does.
+  await vi.waitFor(() => expect(received.some((m) => m.type === 'messages')).toBe(true));
+  return {
+    ws,
+    received,
+    send: (message) => ws.send(JSON.stringify(message)),
+    close: async () => {
+      const closed = new Promise<void>((resolve) => ws.once('close', () => resolve()));
+      ws.close();
+      await closed;
+    },
+  };
+}
+
+const ofType = <T extends TServerMessage['type']>(
+  client: IClient,
+  type: T,
+): Array<Extract<TServerMessage, { type: T }>> =>
+  client.received.filter((m): m is Extract<TServerMessage, { type: T }> => m.type === type);
+
+/** Frames already in flight have landed: a round trip on the same socket answers after them. */
+async function settle(client: IClient, requestId: string): Promise<void> {
+  client.send({ type: 'list-sessions', requestId });
+  await vi.waitFor(() =>
+    expect(client.received.some((m) => 'requestId' in m && m.requestId === requestId)).toBe(true),
+  );
+}
+
+describe('WsTransport session binder (#3189)', () => {
+  it('binds each connection to its own session and keeps a switch on the connection that made it', async () => {
+    const { binder, bindings } = fakeBinder();
+    const transport = await startTransport({ sessionBinder: binder });
+    const a = await connect(transport);
+    const b = await connect(transport);
+
+    expect(bindings.map((binding) => binding.role)).toEqual(['drive', 'drive']);
+    expect(ofType(a, 'messages')[0]?.messages).toEqual([{ role: 'user', content: 'connection-1' }]);
+    expect(ofType(b, 'messages')[0]?.messages).toEqual([{ role: 'user', content: 'connection-2' }]);
+
+    a.send({ type: 'switch-session', sessionId: 'session-2', requestId: 'switch-1' });
+    await vi.waitFor(() =>
+      expect(ofType(a, 'session_switched')).toEqual([
+        { type: 'session_switched', event: { sessionId: 'session-2' } },
+      ]),
+    );
+    bindings[0]!.session.emit('text_delta', 'only for a');
+    await vi.waitFor(() =>
+      expect(ofType(a, 'text_delta')).toEqual([{ type: 'text_delta', delta: 'only for a' }]),
+    );
+
+    await settle(b, 'b-settled');
+    expect(ofType(b, 'session_switched')).toEqual([]);
+    expect(ofType(b, 'text_delta')).toEqual([]);
+
+    await a.close();
+    await b.close();
+  });
+
+  it('releases the binding when its connection closes, after the handler unsubscribed', async () => {
+    const { binder, bindings } = fakeBinder();
+    const transport = await startTransport({ sessionBinder: binder });
+    const a = await connect(transport);
+    const b = await connect(transport);
+
+    await a.close();
+    await vi.waitFor(() => expect(bindings[0]!.release).toHaveBeenCalledTimes(1));
+    expect(bindings[0]!.listenersAtRelease).toBe(0);
+    expect(bindings[1]!.release).not.toHaveBeenCalled();
+
+    await b.close();
+    await vi.waitFor(() => expect(bindings[1]!.release).toHaveBeenCalledTimes(1));
+  });
+
+  it('answers a refusal from the binding directory with session_change_failed and the requestId', async () => {
+    const { binder } = fakeBinder({
+      switchSession: async () => {
+        throw Object.assign(new Error('Answer the pending prompt first.'), {
+          name: 'SessionChangeRefusal',
+          code: 'prompt_pending',
+        });
+      },
+    });
+    const transport = await startTransport({ sessionBinder: binder });
+    const a = await connect(transport);
+
+    a.send({ type: 'switch-session', sessionId: 'session-2', requestId: 'switch-1' });
+    await vi.waitFor(() =>
+      expect(ofType(a, 'session_change_failed')).toEqual([
+        {
+          type: 'session_change_failed',
+          code: 'prompt_pending',
+          message: 'Answer the pending prompt first.',
+          requestId: 'switch-1',
+        },
+      ]),
+    );
+    await a.close();
+  });
+
+  it('closes the connection before any session data when the host will not bind it', async () => {
+    const binder: ISessionBinder<IProtocolSession> = {
+      bind: () => {
+        throw new Error('host is stopping');
+      },
+    };
+    const transport = await startTransport({ sessionBinder: binder });
+    const ws = new WebSocket(`ws://127.0.0.1:${transport.boundPort}`);
+    const received: string[] = [];
+    ws.on('message', (data) => received.push(String(data)));
+    const code = await new Promise<number>((resolve) => ws.once('close', resolve));
+    expect(code).toBe(1013);
+    expect(received).toEqual([]);
+  });
+
+  it('without a binder, every connection shares the attached session and hears its switch', async () => {
+    const attached = emittingSession('attached');
+    const transport = await startTransport({}, attached);
+    const a = await connect(transport);
+    const b = await connect(transport);
+
+    expect(ofType(a, 'messages')[0]?.messages).toEqual([{ role: 'user', content: 'attached' }]);
+    attached.emit('session_switched', { sessionId: 'session-2' });
+    for (const client of [a, b]) {
+      await vi.waitFor(() =>
+        expect(ofType(client, 'session_switched')).toEqual([
+          { type: 'session_switched', event: { sessionId: 'session-2' } },
+        ]),
+      );
+    }
+    // No directory either: a switch is answered, not dropped.
+    a.send({ type: 'switch-session', sessionId: 'session-3', requestId: 'switch-1' });
+    await vi.waitFor(() =>
+      expect(ofType(a, 'session_change_failed')).toEqual([
+        {
+          type: 'session_change_failed',
+          code: 'not_available',
+          message: 'Sessions cannot be switched on this host.',
+          requestId: 'switch-1',
+        },
+      ]),
+    );
+    await a.close();
+    await b.close();
+  });
+});

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');
+  });
+});