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

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

@@ -0,0 +1,97 @@
+/**
+ * #3189: the host hands its session directory to the WebSocket carrier once, and every connection can
+ * list, start and switch the host's sessions through it.
+ */
+
+import { createTestInteractiveSession } from '@robota-sdk/agent-interface-session/testing';
+import { WebSocket } from 'ws';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { createWsTransport } from '../ws-transport.js';
+import { WsTransport } from '../ws-transport-configurable.js';
+
+import type { ISessionDirectory, ISessionListing } from '@robota-sdk/agent-interface-session';
+import type { TServerMessage } from '@robota-sdk/agent-transport';
+
+const listing: ISessionListing = {
+  currentSessionId: 'session-1',
+  sessions: [],
+  unreadableSessionIds: [],
+};
+
+function createDirectory(): ISessionDirectory {
+  return {
+    listSessions: vi.fn(() => listing),
+    switchSession: vi.fn(async () => undefined),
+    newSession: vi.fn(async () => undefined),
+    renameSession: vi.fn(async () => undefined),
+    deleteSession: vi.fn(async () => undefined),
+  };
+}
+
+function mockSession(): ReturnType<typeof createTestInteractiveSession> {
+  return Object.assign(createTestInteractiveSession(), {
+    getMessages: vi.fn().mockReturnValue([]),
+    getExecutionWorkspaceSnapshot: vi.fn().mockReturnValue({ entries: [] }),
+    on: vi.fn(),
+    off: vi.fn(),
+  });
+}
+
+const started: WsTransport[] = [];
+afterEach(async () => {
+  while (started.length) await started.pop()!.stop();
+});
+
+describe('WsTransport session directory (#3189)', () => {
+  it('lets every connection list and switch the host sessions', async () => {
+    const directory = createDirectory();
+    const transport = new WsTransport({
+      port: 17720,
+      maxRetries: 30,
+      open: true,
+      openReason: 'session-directory regression test',
+      sessionDirectory: directory,
+    });
+    transport.attach(mockSession());
+    await transport.start();
+    started.push(transport);
+
+    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);
+    });
+
+    ws.send(JSON.stringify({ type: 'list-sessions', requestId: 'r1' }));
+    ws.send(JSON.stringify({ type: 'switch-session', sessionId: 'session-2' }));
+    await vi.waitFor(() => expect(directory.switchSession).toHaveBeenCalledWith('session-2'));
+    await vi.waitFor(() =>
+      expect(received).toContainEqual({ type: 'sessions', requestId: 'r1', listing }),
+    );
+
+    const closed = new Promise<void>((resolve) => ws.once('close', () => resolve()));
+    ws.close();
+    await closed;
+  });
+
+  it('passes the directory through the adapter form as well', async () => {
+    const directory = createDirectory();
+    const sent: TServerMessage[] = [];
+    const transport = createWsTransport({
+      send: (message) => sent.push(message),
+      sessionDirectory: directory,
+    });
+    transport.attach(mockSession());
+    await transport.start();
+
+    transport.onMessage?.(JSON.stringify({ type: 'list-sessions', requestId: 'r1' }));
+    transport.onMessage?.(JSON.stringify({ type: 'new-session' }));
+
+    expect(sent).toEqual([{ type: 'sessions', requestId: 'r1', listing }]);
+    await vi.waitFor(() => expect(directory.newSession).toHaveBeenCalledTimes(1));
+    await transport.stop();
+  });
+});

package/src/__tests__/ws-transport-auth.test.ts

@@ -0,0 +1,253 @@
+import { createTestInteractiveSession } from '@robota-sdk/agent-interface-session/testing';
+
+import { WebSocket } from 'ws';
+import { describe, it, expect, vi, afterEach } from 'vitest';
+
+import { WsTransport } from '../ws-transport-configurable.js';
+
+import type { IInteractiveSession } from '@robota-sdk/agent-interface-session';
+
+/**
+ * GUI-002 TC-03 — required loopback auth token. A configured token MUST be presented (query param or
+ * `Sec-WebSocket-Protocol` subprotocol) or the socket is closed BEFORE any session data.
+ *
+ * SEC-001 — secure by default: when NO token is configured, the transport AUTO-MINTS one (`resolvedToken`),
+ * so an unauthenticated connection is rejected; `{ open: true }` is the discouraged opt-out. Plus
+ * defense-in-depth: the WS upgrade rejects a non-loopback `Host` (DNS rebinding) and a non-allowed browser
+ * `Origin` at the handshake.
+ */
+
+function mockSession(): IInteractiveSession {
+  return Object.assign(createTestInteractiveSession(), {
+    getMessages: vi.fn().mockReturnValue([{ role: 'user', content: 'hi' }]),
+    getExecutionWorkspaceSnapshot: vi.fn().mockReturnValue({ entries: [] }),
+    on: vi.fn(),
+    off: vi.fn(),
+    submit: vi.fn(),
+    abort: vi.fn(),
+    cancelQueue: vi.fn(),
+    executeCommand: vi.fn(),
+    resolvePermission: vi.fn(),
+    resolveAsk: vi.fn(),
+  });
+}
+
+const started: WsTransport[] = [];
+
+interface IStartConfig {
+  token?: string;
+  open?: boolean;
+  /** SEC-008: required alongside `open` — the transport refuses an opt-out nobody explained. */
+  openReason?: string;
+  allowedHosts?: readonly string[];
+  allowedOrigins?: readonly string[];
+}
+
+/** Start a transport and return its port + the resolved token (auto-minted when none was configured). */
+async function startOn(config: IStartConfig = {}): Promise<{ port: number; token?: string }> {
+  // Use a high, unlikely-occupied base port; retry covers rare collisions.
+  const port = 17000 + Math.floor((started.length + 1) * 7);
+  const t = new WsTransport({ port, maxRetries: 30, ...config });
+  t.attach(mockSession());
+  await t.start();
+  started.push(t);
+  return { port, token: t.resolvedToken };
+}
+
+afterEach(async () => {
+  while (started.length) await started.pop()!.stop();
+});
+
+/**
+ * Connect and resolve with the outcome: `'messages'` if a `messages` frame arrives first, or `'closed'`
+ * with the close code if the socket closes before any frame. 1.5s guard so a hang fails loudly.
+ */
+function probe(
+  port: number,
+  opts: { token?: string; subprotocol?: string; headers?: Record<string, string> } = {},
+): Promise<string> {
+  const url = `ws://127.0.0.1:${port}${opts.token ? `?token=${encodeURIComponent(opts.token)}` : ''}`;
+  const wsOpts = opts.headers ? { headers: opts.headers } : {};
+  const ws = opts.subprotocol
+    ? new WebSocket(url, opts.subprotocol, wsOpts)
+    : new WebSocket(url, wsOpts);
+  return new Promise<string>((resolve) => {
+    const done = (v: string): void => {
+      try {
+        ws.close();
+      } catch {
+        /* already closing */
+      }
+      resolve(v);
+    };
+    const timer = setTimeout(() => done('timeout'), 1500);
+    ws.on('message', (data) => {
+      const msg = JSON.parse(String(data)) as { type: string };
+      if (msg.type === 'messages') {
+        clearTimeout(timer);
+        done('messages');
+      }
+    });
+    ws.on('close', (code) => {
+      clearTimeout(timer);
+      done(`closed:${code}`);
+    });
+    ws.on('error', () => {
+      clearTimeout(timer);
+      done('closed:error');
+    });
+  });
+}
+
+describe('WsTransport loopback auth (GUI-002 TC-03)', () => {
+  it('attributes submissions with the trusted server-side surface driver id', async () => {
+    const port = 17650;
+    const submit = vi.fn().mockResolvedValue(undefined);
+    const session = Object.assign(mockSession(), { submit });
+    const transport = new WsTransport({
+      port,
+      maxRetries: 30,
+      open: true,
+      openReason: 'surface-attribution regression test',
+      driverId: 'app',
+      surface: 'desktop-app',
+    });
+    transport.attach(session);
+    await transport.start();
+    started.push(transport);
+    const ws = new WebSocket(`ws://127.0.0.1:${transport.boundPort}`);
+    await new Promise<void>((resolve, reject) => {
+      ws.on('open', resolve);
+      ws.on('error', reject);
+    });
+
+    ws.send(JSON.stringify({ type: 'submit', prompt: 'attribute me' }));
+    await vi.waitFor(() => expect(submit).toHaveBeenCalled());
+
+    expect(submit).toHaveBeenCalledWith('attribute me', undefined, undefined, {
+      driverId: 'app',
+      surface: 'desktop-app',
+    });
+    const closed = new Promise<void>((resolve) => ws.once('close', () => resolve()));
+    ws.close();
+    await closed;
+  });
+
+  it('carries the driver id on the connection-open messages frame, so a client can learn its own id (#3289 §3)', async () => {
+    // The crux of #3289 §3's own-driver-id feature: a client's first `messages` frame is where it
+    // learns which of every subsequent `authored` message is its own. This is the one place that
+    // sets it — decode-shape validation and the client reducer are covered elsewhere, but neither
+    // would catch this specific line being broken or reverted.
+    const port = 17660;
+    const transport = new WsTransport({
+      port,
+      maxRetries: 30,
+      open: true,
+      openReason: 'own-driver-id regression test',
+      driverId: 'browser',
+      surface: 'browser',
+    });
+    transport.attach(mockSession());
+    await transport.start();
+    started.push(transport);
+    const ws = new WebSocket(`ws://127.0.0.1:${transport.boundPort}`);
+    const firstMessagesFrame = await new Promise<{ type: string; driverId?: string }>(
+      (resolve, reject) => {
+        ws.on('error', reject);
+        ws.on('message', (data) => {
+          const msg = JSON.parse(String(data)) as { type: string; driverId?: string };
+          if (msg.type === 'messages') resolve(msg);
+        });
+      },
+    );
+    expect(firstMessagesFrame.driverId).toBe('browser');
+    const closed = new Promise<void>((resolve) => ws.once('close', () => resolve()));
+    ws.close();
+    await closed;
+  });
+
+  it('accepts a connection presenting the correct token via query param', async () => {
+    const { port } = await startOn({ token: 'secret-nonce' });
+    expect(await probe(port, { token: 'secret-nonce' })).toBe('messages');
+  });
+
+  it('accepts the correct token via Sec-WebSocket-Protocol subprotocol', async () => {
+    const { port } = await startOn({ token: 'secret-nonce' });
+    expect(await probe(port, { subprotocol: 'secret-nonce' })).toBe('messages');
+  });
+
+  it('rejects a MISSING token before any session data is emitted', async () => {
+    const { port } = await startOn({ token: 'secret-nonce' });
+    expect(await probe(port)).toBe('closed:1008'); // never 'messages'
+  });
+
+  it('rejects a WRONG token before any session data is emitted', async () => {
+    const { port } = await startOn({ token: 'secret-nonce' });
+    expect(await probe(port, { token: 'not-the-nonce' })).toBe('closed:1008');
+  });
+
+  // ── SEC-001 ────────────────────────────────────────────────────────────────
+  it('TC-01: NO token configured AUTO-MINTS one — unauthenticated rejected, minted token works', async () => {
+    const { port, token } = await startOn({}); // secure by default
+    expect(token).toBeTruthy();
+    expect(await probe(port)).toBe('closed:1008');
+    expect(await probe(port, { token })).toBe('messages');
+  });
+
+  it('TC-05: the discouraged `open` opt-out restores unauthenticated behavior', async () => {
+    const { port, token } = await startOn({
+      open: true,
+      openReason: 'SEC-008: the discouraged opt-out is the SUBJECT of this case',
+    });
+    expect(token).toBeUndefined();
+    expect(await probe(port)).toBe('messages');
+  });
+
+  it('TC-02: rejects a non-loopback Host at the upgrade (DNS-rebinding defense)', async () => {
+    const { port, token } = await startOn({ token: 'secret-nonce' });
+    expect(await probe(port, { token, headers: { host: 'evil.example.com' } })).not.toBe(
+      'messages',
+    );
+  });
+
+  it('TC-02: accepts a loopback Host on a port-agnostic match', async () => {
+    const { port, token } = await startOn({ token: 'secret-nonce' });
+    expect(await probe(port, { token, headers: { host: `localhost:${port}` } })).toBe('messages');
+  });
+
+  it('TC-03: rejects a non-allowed browser Origin at the upgrade', async () => {
+    const { port, token } = await startOn({ token: 'secret-nonce' });
+    expect(await probe(port, { token, headers: { origin: 'https://evil.example.com' } })).not.toBe(
+      'messages',
+    );
+  });
+
+  it('TC-03: accepts a configured app Origin', async () => {
+    const { port, token } = await startOn({
+      token: 'secret-nonce',
+      allowedOrigins: ['https://app.example.com'],
+    });
+    expect(await probe(port, { token, headers: { origin: 'https://app.example.com' } })).toBe(
+      'messages',
+    );
+  });
+});
+
+describe('SEC-008: `open` takes a written reason here too', () => {
+  // The first version filled a reason in for any caller that omitted one, which made WS the ONE
+  // transport where `{ open: true }` alone was accepted — HTTP and WebRTC both refuse it. Review
+  // found that: a reason invented on the caller's behalf reads, to the next person, as a decision
+  // somebody made, and the whole point of requiring it is that nobody can produce one by accident.
+  it('refuses an opt-out with no reason', () => {
+    expect(() => new WsTransport({ port: 17999, open: true })).toThrow(/openReason/);
+  });
+
+  it('accepts one that says why', () => {
+    // Without this the fix would be "refuse every open transport", which is not the decision — an
+    // open transport is legitimate, it just has to be chosen out loud.
+    expect(
+      () =>
+        new WsTransport({ port: 17999, open: true, openReason: 'loopback only — no remote peer' }),
+    ).not.toThrow();
+  });
+});

package/src/__tests__/ws-transport-lifecycle.test.ts

@@ -0,0 +1,135 @@
+import { createServer } from 'node:net';
+
+import { runTransportLifecycleConformance } from '@robota-sdk/agent-interface-transport/testing';
+import { createTestInteractiveSession } from '@robota-sdk/agent-interface-session/testing';
+
+import { WebSocket } from 'ws';
+import { describe, it, expect, expectTypeOf, vi, afterEach } from 'vitest';
+
+import { WsTransport } from '../ws-transport-configurable.js';
+
+import type { IConfigurableTransport } from '@robota-sdk/agent-interface-transport';
+import type { IInteractiveSession } from '@robota-sdk/agent-interface-session';
+import type { IProtocolSession } from '@robota-sdk/agent-transport';
+
+/**
+ * ARCH-004 RUNTIME-13 — `stop()` must resolve even with a client still connected.
+ *
+ * Before the fix, `stop()` did `wss.close(cb)`, whose callback fires only after every client socket is gone,
+ * so a live client made `stop()` hang forever. The fix sends a close frame to each client and terminates any
+ * survivor at a 5s deadline, so the server-close callback always resolves.
+ */
+
+function mockSession(): IInteractiveSession {
+  return Object.assign(createTestInteractiveSession(), {
+    getMessages: vi.fn().mockReturnValue([]),
+    getExecutionWorkspaceSnapshot: vi.fn().mockReturnValue({ entries: [] }),
+    on: vi.fn(),
+    off: vi.fn(),
+    submit: vi.fn(),
+    abort: vi.fn(),
+    cancelQueue: vi.fn(),
+  });
+}
+
+const started: WsTransport[] = [];
+afterEach(async () => {
+  while (started.length) await started.pop()!.stop();
+});
+
+describe('WsTransport lifecycle (ARCH-004 RUNTIME-13)', () => {
+  it('accepts only the protocol session roles required by the carrier', () => {
+    const transport = new WsTransport({
+      open: true,
+      openReason: 'type compatibility test',
+    });
+    expectTypeOf(transport).toMatchTypeOf<IConfigurableTransport<IProtocolSession>>();
+    expectTypeOf(transport.attach).toEqualTypeOf<(session: IProtocolSession) => void>();
+  });
+
+  it('stop() resolves promptly with a client still connected (previously hung forever)', async () => {
+    const t = new WsTransport({
+      port: 17800,
+      maxRetries: 40,
+      open: true,
+      openReason: 'SEC-008: this case is about the stop() lifecycle, not admission',
+    });
+    t.attach(mockSession());
+    await t.start();
+    started.push(t);
+    const port = t.boundPort;
+
+    const ws = new WebSocket(`ws://127.0.0.1:${port}`);
+    await new Promise<void>((resolve, reject) => {
+      ws.on('open', () => resolve());
+      ws.on('error', reject);
+    });
+
+    const startedAt = Date.now();
+    await t.stop(); // must not hang — the whole test would time out if it did
+    const elapsed = Date.now() - startedAt;
+
+    // A well-behaved client closes on the 1001 frame, so stop() resolves well under the 5s terminate deadline.
+    expect(elapsed).toBeLessThan(4500);
+    started.pop(); // already stopped
+    try {
+      ws.terminate();
+    } catch {
+      /* already closed */
+    }
+  });
+
+  it('can retry start after a bind failure without an intervening stop', async () => {
+    const blocker = createServer();
+    await new Promise<void>((resolve, reject) => {
+      blocker.once('error', reject);
+      blocker.listen(0, '127.0.0.1', resolve);
+    });
+    const address = blocker.address();
+    if (!address || typeof address === 'string') throw new Error('Expected a TCP address.');
+
+    const transport = new WsTransport({
+      port: address.port,
+      maxRetries: 0,
+      open: true,
+      openReason: 'bind failure lifecycle regression',
+    });
+    transport.attach(mockSession());
+    let blockerOpen = true;
+    try {
+      await expect(transport.start()).rejects.toMatchObject({ code: 'EADDRINUSE' });
+      await new Promise<void>((resolve, reject) =>
+        blocker.close((error) => (error ? reject(error) : resolve())),
+      );
+      blockerOpen = false;
+
+      await expect(transport.start()).resolves.toBeUndefined();
+      started.push(transport);
+      expect(transport.boundPort).toBe(address.port);
+    } finally {
+      if (blockerOpen) {
+        await new Promise<void>((resolve) => blocker.close(() => resolve()));
+      }
+    }
+  });
+
+  it('invokes the shared lifecycle conformance suite', async () => {
+    await runTransportLifecycleConformance({
+      subjectId: '@robota-sdk/agent-transport-ws#WsTransport',
+      kind: 'service',
+      createAdapter: () =>
+        new WsTransport({
+          port: 0,
+          open: true,
+          openReason: 'ARCH-011 lifecycle conformance',
+        }),
+      createSession: mockSession,
+      assertReady: (transport) => {
+        if (transport.boundPort === undefined) throw new Error('WS endpoint not bound');
+      },
+      assertStopped: (transport) => {
+        if (transport.boundPort !== undefined) throw new Error('WS endpoint still bound');
+      },
+    });
+  });
+});

package/src/__tests__/ws-transport.test.ts

@@ -0,0 +1,117 @@
+import { runTransportLifecycleConformance } from '@robota-sdk/agent-interface-transport/testing';
+import { createTestInteractiveSession } from '@robota-sdk/agent-interface-session/testing';
+
+import { describe, it, expect, expectTypeOf, vi } from 'vitest';
+import { createWsTransport } from '../ws-transport.js';
+import type { ITransportAdapter } from '@robota-sdk/agent-interface-transport';
+import type { IInteractiveSession } from '@robota-sdk/agent-interface-session';
+import type { IProtocolSession } from '@robota-sdk/agent-transport';
+
+function createMockSession(): IInteractiveSession {
+  return Object.assign(createTestInteractiveSession(), {
+    submit: vi.fn(),
+    abort: vi.fn(),
+    cancelQueue: vi.fn(),
+    getMessages: vi.fn().mockReturnValue([]),
+    getContextState: vi
+      .fn()
+      .mockReturnValue({ usedPercentage: 0, usedTokens: 0, maxTokens: 200000 }),
+    isExecuting: vi.fn().mockReturnValue(false),
+    getPendingPrompt: vi.fn().mockReturnValue(null),
+    executeCommand: vi.fn().mockResolvedValue({ message: 'ok', success: true }),
+    listCommands: vi.fn().mockReturnValue([]),
+    on: vi.fn(),
+    off: vi.fn(),
+  });
+}
+
+describe('createWsTransport', () => {
+  it('accepts only the protocol session roles required by the carrier', () => {
+    const transport = createWsTransport({ send: vi.fn() });
+    expectTypeOf(transport).toMatchTypeOf<ITransportAdapter<IProtocolSession>>();
+    expectTypeOf(transport.attach).toEqualTypeOf<(session: IProtocolSession) => void>();
+  });
+
+  it('returns an adapter with name "ws"', () => {
+    const transport = createWsTransport({ send: vi.fn() });
+    expect(transport.name).toBe('ws');
+  });
+
+  it('throws if start() is called without attach()', async () => {
+    const transport = createWsTransport({ send: vi.fn() });
+    await expect(transport.start()).rejects.toMatchObject({
+      name: 'TransportLifecycleError',
+      code: 'not-attached',
+    });
+  });
+
+  it('onMessage is null before start()', () => {
+    const transport = createWsTransport({ send: vi.fn() });
+    expect(transport.onMessage).toBeNull();
+  });
+
+  it('provides onMessage after attach + start', async () => {
+    const transport = createWsTransport({ send: vi.fn() });
+    transport.attach(createMockSession() as never);
+    await transport.start();
+    expect(typeof transport.onMessage).toBe('function');
+  });
+
+  it('clears onMessage after stop()', async () => {
+    const transport = createWsTransport({ send: vi.fn() });
+    transport.attach(createMockSession() as never);
+    await transport.start();
+    await transport.stop();
+    expect(transport.onMessage).toBeNull();
+  });
+
+  it('isolates an outbound failure, cleans subscriptions, and reports to the carrier owner', async () => {
+    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'],
+    });
+    const onDeliveryError = vi.fn();
+    const transport = createWsTransport({
+      send: () => {
+        throw new Error('functional adapter socket closed');
+      },
+      onDeliveryError,
+    });
+    transport.attach(session);
+    await transport.start();
+
+    expect(() =>
+      handlers.get('branch_event')?.({
+        kind: 'checkpoint_created',
+        checkpointId: 'turn-0001',
+        branchId: 'main',
+      }),
+    ).not.toThrow();
+    expect(onDeliveryError).toHaveBeenCalledWith(
+      expect.objectContaining({ message: 'functional adapter socket closed' }),
+      'branch_event',
+    );
+    expect(handlers.size).toBe(0);
+    expect(transport.onMessage).toBeNull();
+  });
+
+  it('invokes the shared lifecycle conformance suite', async () => {
+    await runTransportLifecycleConformance({
+      subjectId: '@robota-sdk/agent-transport-ws#createWsTransport',
+      kind: 'service',
+      createAdapter: () => createWsTransport({ send: vi.fn() }),
+      createSession: createMockSession,
+      assertReady: (transport) => {
+        if (typeof transport.onMessage !== 'function') throw new Error('WS handler not ready');
+      },
+      assertStopped: (transport) => {
+        if (transport.onMessage !== null) throw new Error('WS handler still ready');
+      },
+    });
+  });
+});

package/src/index.ts

@@ -0,0 +1,7 @@
+export { createWsTransport } from './ws-transport.js';
+export type { IWsTransport, IWsTransportOptions } from './ws-transport.js';
+export { WsTransport } from './ws-transport-configurable.js';
+export type { IWsTransportConfig } from './ws-transport-config.js';
+// TRANS-001 — payload-agnostic channel multiplexing (also usable standalone by another carrier).
+export { PayloadChannelRegistry } from './payload-channels.js';
+export type { TChannelSink } from './payload-channels.js';