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

package/src/ws-connection-guards.ts

@@ -0,0 +1,104 @@
+/**
+ * Connection-admission guards for the WS transport (SEC-001 / GUI-002).
+ *
+ * Pure, socket-free predicates over the HTTP upgrade request — token minting/comparison plus the
+ * `Host` and `Origin` allow-lists. Split out of `ws-transport-configurable.ts` so the transport file
+ * carries lifecycle and frame routing only; the admission policy is independently readable and the
+ * transport module stays within the file-size ratchet.
+ */
+
+import { timingSafeEqual } from 'node:crypto';
+
+import { resolveAdmission } from '@robota-sdk/agent-transport/node';
+
+import type { ITransportAdmission } from '@robota-sdk/agent-interface-transport';
+import type { IncomingMessage } from 'node:http';
+
+/**
+ * Host names that are always loopback (port stripped by the caller). IPv4 bind only, so `[::1]`
+ * inbound is moot, but accepting it is harmless.
+ */
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '[::1]']);
+
+/** Strip the `:port` suffix from a Host/authority (port-agnostic — `bindWithRetry` can walk the port). */
+function hostname(hostHeader: string | undefined): string | null {
+  if (!hostHeader) return null;
+  if (hostHeader.startsWith('[')) return hostHeader.slice(0, hostHeader.indexOf(']') + 1) || null;
+  const colon = hostHeader.lastIndexOf(':');
+  return colon === -1 ? hostHeader : hostHeader.slice(0, colon);
+}
+
+/**
+ * The upgrade `Host` must be a loopback name (port-agnostic) or an explicitly allowed host — closes
+ * DNS rebinding. A missing `Host` is rejected (a well-formed HTTP/1.1 client always sends one).
+ */
+export function hostAllowed(req: IncomingMessage, allowedHosts: ReadonlySet<string>): boolean {
+  const host = hostname(req.headers.host);
+  if (host === null) return false;
+  return LOOPBACK_HOSTS.has(host) || allowedHosts.has(host);
+}
+
+/**
+ * A browser sends an unforgeable `Origin`; require it to be loopback or explicitly allowed. A
+ * non-browser client omits `Origin` (allowed here — the token is its gate). Closes the browser
+ * drive-by hole.
+ */
+export function originAllowed(req: IncomingMessage, allowedOrigins: ReadonlySet<string>): boolean {
+  const origin = req.headers.origin;
+  if (origin === undefined) return true; // non-browser client; token still required
+  if (allowedOrigins.has(origin)) return true;
+  try {
+    return LOOPBACK_HOSTS.has(new URL(origin).hostname);
+  } catch {
+    return false; // malformed Origin → reject
+  }
+}
+
+/**
+ * Constant-time token comparison. Returns false on any length mismatch (never throws), so an
+ * absent/short/long presented token is a plain reject, not an error.
+ */
+export function tokenMatches(expected: string, presented: string | null | undefined): boolean {
+  if (!presented) return false;
+  const a = Buffer.from(expected);
+  const b = Buffer.from(presented);
+  if (a.length !== b.length) return false;
+  return timingSafeEqual(a, b);
+}
+
+/** Read the presented token from the upgrade request: `?token=` query param, else the WS subprotocol. */
+export function presentedToken(req: IncomingMessage): string | null {
+  try {
+    const url = new URL(req.url ?? '', 'ws://127.0.0.1');
+    const q = url.searchParams.get('token');
+    if (q) return q;
+  } catch {
+    // malformed URL → fall through to the subprotocol header
+  }
+  const proto = req.headers['sec-websocket-protocol'];
+  return typeof proto === 'string' ? proto.split(',')[0]?.trim() || null : null;
+}
+
+/**
+ * This transport's admission decision, asked of the shared seam.
+ *
+ * Lives here rather than in the transport file because this module already owns the admission
+ * policy — token comparison and the Host/Origin allow-lists — and the transport file carries
+ * lifecycle and frame routing. The split is also what keeps that file inside its size ratchet.
+ */
+export function resolveWsAdmission(config: {
+  token?: string;
+  open?: boolean;
+  openReason?: string;
+}): ITransportAdmission {
+  // No fabricated reason. The first version filled one in for any caller that omitted it, 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. The whole point of requiring it is that nobody can produce one by
+  // accident, so the seam is asked the question exactly as it was given.
+  return resolveAdmission({
+    ...(config.token !== undefined ? { token: config.token } : {}),
+    ...(config.open === true ? { open: true } : {}),
+    ...(config.openReason !== undefined ? { openReason: config.openReason } : {}),
+  });
+}

package/src/ws-message-data.ts

@@ -0,0 +1,8 @@
+import type { RawData } from 'ws';
+
+/** Normalize the `ws` inbound payload variants to one binary view. */
+export function toBytes(data: RawData): Uint8Array {
+  if (Array.isArray(data)) return new Uint8Array(Buffer.concat(data));
+  if (data instanceof ArrayBuffer) return new Uint8Array(data);
+  return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+}

package/src/ws-session-delivery.ts

@@ -0,0 +1,109 @@
+import {
+  createOutboundDelivery,
+  createPendingStallClock,
+  DEFAULT_MAX_PENDING_BYTES,
+  isOverPendingBudget,
+} from '@robota-sdk/agent-transport';
+import { WebSocket } from 'ws';
+
+import type {
+  IPendingStallClock,
+  TOutboundDeliver,
+  TServerMessage,
+} from '@robota-sdk/agent-transport';
+
+/**
+ * Connection-scoped session delivery lifecycle shared by sync and async WebSocket failures.
+ *
+ * ARCH-030: {@link deliver} is the ONLY way out of this class. The raw sink — the `readyState` check
+ * plus `socket.send` — is private, so no caller can put a frame on this socket outside the connection's
+ * one outbound boundary. That is not stylistic: the previous shape exposed a public `send` that threw
+ * on a closed socket, and every reply the protocol handler produced went through it unguarded.
+ */
+export class WsSessionDelivery {
+  private cleanupProtocol = (): void => undefined;
+  private detachSink = (): void => undefined;
+  private closed = false;
+  /**
+   * Issue #2306: ONE drain clock for the socket. `bufferedAmount` does not distinguish text from
+   * binary, so both halves observe the same clock — a slow reader of payload frames is caught when a
+   * JSON reply is attempted, and the reverse.
+   */
+  private readonly stallClock: IPendingStallClock = createPendingStallClock();
+
+  /**
+   * The connection's outbound boundary. Built here, from this class's own sink and its own `close`
+   * policy, and passed DOWN into `createSessionMessageHandler` — the carrier owns both halves, so it builds the
+   * boundary rather than handing the protocol layer a raw sink to wrap.
+   */
+  readonly deliver: TOutboundDeliver;
+
+  constructor(private readonly socket: WebSocket) {
+    this.deliver = createOutboundDelivery(
+      (message) => this.rawSend(message),
+      () => this.close(),
+      // ARCH-030 / issue #1734: the socket's own count of what it has accepted and not yet written.
+      // Read at call time — it changes underneath.
+      () => this.socket.bufferedAmount,
+      DEFAULT_MAX_PENDING_BYTES,
+      this.stallClock,
+    );
+  }
+
+  /**
+   * Put a TRANS-001 payload frame on this socket, under the SAME budget and the same close policy as
+   * the text protocol (ARCH-030 / issue #1734).
+   *
+   * A WebSocket carries two kinds of outbound frame over one socket, and until this existed the
+   * binary half went straight to `socket.send` — outside the boundary, with no budget, and with a
+   * failure that could only surface as a throw inside a listener. `bufferedAmount` does not
+   * distinguish the two, so a non-reading peer accumulating payload frames was invisible to a budget
+   * that only guarded the other half.
+   *
+   * It is not `deliver`: that boundary is typed for `TServerMessage` and its brand is what makes a
+   * raw send unusable where a protocol frame is required. Widening it to accept bytes would remove
+   * the property the brand exists for.
+   */
+  readonly deliverBinary = (frame: Uint8Array): void => {
+    if (this.closed) return;
+    if (this.socket.readyState !== WebSocket.OPEN) return;
+    if (
+      isOverPendingBudget(this.socket.bufferedAmount) ||
+      this.stallClock.observe(this.socket.bufferedAmount) !== undefined
+    ) {
+      this.close();
+      return;
+    }
+    this.socket.send(frame, { binary: true }, (error) => {
+      if (error) this.close();
+    });
+  };
+
+  private rawSend(message: TServerMessage): void {
+    if (this.socket.readyState !== WebSocket.OPEN) throw new Error('WebSocket is not open');
+    this.socket.send(JSON.stringify(message), (error) => {
+      if (error) this.close();
+    });
+  }
+
+  bindProtocolCleanup(cleanup: () => void): void {
+    this.cleanupProtocol = cleanup;
+  }
+
+  bindSinkDetach(detach: () => void): void {
+    this.detachSink = detach;
+  }
+
+  readonly close = (): void => {
+    if (this.closed) return;
+    this.closed = true;
+    this.detachSink();
+    this.cleanupProtocol();
+    if (
+      this.socket.readyState === WebSocket.OPEN ||
+      this.socket.readyState === WebSocket.CONNECTING
+    ) {
+      this.socket.close(1011, 'session event delivery failed');
+    }
+  };
+}

package/src/ws-transport-config.ts

@@ -0,0 +1,114 @@
+/**
+ * The construction contract for `WsTransport` — what a caller decides before the server exists.
+ *
+ * Split from `ws-transport-configurable.ts` under the file-size ceiling, and the seam is the
+ * honest one: everything here is a decision the CALLER makes (port, retries, admission — SEC-008's
+ * `token`/`open`/`openReason` contract lives in these doc comments), while the class next door is
+ * what the transport DOES with those decisions.
+ */
+
+import type { TUsageSurface } from '@robota-sdk/agent-interface-analytics';
+import type { TDriverId } from '@robota-sdk/agent-interface-session';
+import type { ITransportLifecycleError } from '@robota-sdk/agent-interface-transport';
+import type { ISessionMessageHandlerOptions } from '@robota-sdk/agent-transport';
+
+export const DEFAULT_PORT = 7070;
+export const DEFAULT_MAX_RETRIES = 20;
+
+export interface IWsTransportConfig {
+  /** Trusted server-assigned identity for turns submitted over this product surface. */
+  driverId?: TDriverId;
+  /** Trusted product surface, independent from the connection's driver identity. */
+  surface?: TUsageSurface;
+  /** Host-owned cross-session usage read model, forwarded unchanged to the protocol handler. */
+  personalUsageReporter?: ISessionMessageHandlerOptions['personalUsageReporter'];
+  /** Host-owned current-session trace/cost producer, forwarded unchanged to the protocol handler. */
+  usageReporter?: ISessionMessageHandlerOptions['usageReporter'];
+  /** Host-owned stored-session trace/cost producer for personal-usage drill-down. */
+  storedSessionUsageReporter?: ISessionMessageHandlerOptions['storedSessionUsageReporter'];
+  port?: number;
+  maxRetries?: number;
+  /**
+   * OPTIONAL explicit loopback auth token. When set, every connection MUST present a matching token
+   * (query param `?token=` or the `Sec-WebSocket-Protocol` subprotocol) or the socket is closed BEFORE any
+   * session data is emitted (GUI-002; the GUI sidecar sets `ROBOTA_WS_TOKEN`). SEC-001: when this is unset
+   * AND `open` is not `true`, the transport AUTO-MINTS a random per-launch token (secure by default) —
+   * `resolvedToken` exposes it so the surface can deliver it to the co-located client (a `0600` connection
+   * file / the served monitor's injected `ws-url`). An explicit token here wins over the auto-mint — but NOT
+   * over `open`: SEC-008 makes a token together with `open: true` a contradiction that throws, rather
+   * than a precedence one side quietly wins.
+   */
+  token?: string;
+  /**
+   * SEC-001 discouraged opt-out: when `true`, run WITHOUT auth (no token, no auto-mint) — the pre-SEC-001
+   * open loopback behavior. NOT RECOMMENDED (any local process or browser page can then drive+authorize the
+   * session); mirrors Jupyter's `c.ServerApp.token = ''`.
+   *
+   * SEC-008: `open: true` together with a non-empty `token` is REJECTED, not resolved by precedence. The
+   * two ask for opposite things, and picking a winner silently is how a caller ends up with the admission
+   * it did not choose. `resolveAdmission` decides that for every transport, so they cannot differ.
+   */
+  open?: boolean;
+  /** SEC-008: why running with no credential is correct here. Required when `open` is true. */
+  openReason?: string;
+  /**
+   * SEC-001 defense-in-depth: extra host names (beyond `localhost`/`127.0.0.1`/`::1`) accepted in the
+   * upgrade `Host` header. The `Host` allow-list closes DNS-rebinding independently of the token.
+   */
+  allowedHosts?: readonly string[];
+  /**
+   * SEC-001 defense-in-depth: extra browser `Origin`s (beyond loopback) accepted on the upgrade — e.g. the
+   * `apps/agent-web` app origin. A browser sends an unforgeable `Origin`; a non-browser client omits it (and
+   * is gated by the token instead). Closes the "any web page in any browser" hole before history is emitted.
+   */
+  allowedOrigins?: readonly string[];
+}
+
+type TUsageReporters = Pick<
+  ISessionMessageHandlerOptions,
+  'personalUsageReporter' | 'usageReporter' | 'storedSessionUsageReporter'
+>;
+
+/** Remove absent reporters so exact-optional handler options remain truthful. */
+function configuredUsageReporters(config: IWsTransportConfig): TUsageReporters {
+  return {
+    ...(config.personalUsageReporter
+      ? { personalUsageReporter: config.personalUsageReporter }
+      : {}),
+    ...(config.usageReporter ? { usageReporter: config.usageReporter } : {}),
+    ...(config.storedSessionUsageReporter
+      ? { storedSessionUsageReporter: config.storedSessionUsageReporter }
+      : {}),
+  };
+}
+
+type TConfiguredHandlerOptions = Pick<
+  ISessionMessageHandlerOptions,
+  'driverId' | 'surface' | 'personalUsageReporter' | 'usageReporter' | 'storedSessionUsageReporter'
+>;
+
+/** Project immutable transport attribution/reporters into each protocol handler. */
+export function configuredWsHandlerOptions(config: IWsTransportConfig): TConfiguredHandlerOptions {
+  return {
+    ...(config.driverId ? { driverId: config.driverId } : {}),
+    ...(config.surface ? { surface: config.surface } : {}),
+    ...configuredUsageReporters(config),
+  };
+}
+
+export function validTransportOptions(options: Readonly<Record<string, unknown>>): boolean {
+  const { port, maxRetries } = options;
+  if (port !== undefined && (typeof port !== 'number' || port < 1 || port > 65535)) return false;
+  return maxRetries === undefined || (typeof maxRetries === 'number' && maxRetries >= 0);
+}
+
+export function transportLifecycleError(
+  transportName: string,
+  code: ITransportLifecycleError['code'],
+): ITransportLifecycleError {
+  return Object.assign(new Error(`${transportName} ${code}.`), {
+    name: 'TransportLifecycleError' as const,
+    code,
+    transportName,
+  });
+}

package/src/ws-transport-configurable.ts

@@ -3,29 +3,59 @@
  * Owns the WebSocket server lifecycle (ws package), started/stopped via the transport registry.
  */
 
-import { createServer, type Server } from 'node:http';
+import { createServer, type IncomingMessage, type Server } from 'node:http';
 
-import { WebSocketServer, WebSocket } from 'ws';
+import { createSessionMessageHandler } from '@robota-sdk/agent-transport';
+import { WebSocketServer } from 'ws';
 
-import { createWsHandler } from './ws-handler.js';
+import { PayloadChannelRegistry } from './payload-channels.js';
+import {
+  hostAllowed,
+  originAllowed,
+  presentedToken,
+  resolveWsAdmission,
+  tokenMatches,
+} from './ws-connection-guards.js';
+import { toBytes } from './ws-message-data.js';
+import { WsSessionDelivery } from './ws-session-delivery.js';
+import {
+  DEFAULT_MAX_RETRIES,
+  DEFAULT_PORT,
+  configuredWsHandlerOptions,
+  transportLifecycleError,
+  validTransportOptions,
+} from './ws-transport-config.js';
 
-import type { TServerMessage } from './ws-protocol.js';
+import type { IWsTransportConfig } from './ws-transport-config.js';
 import type { TUniversalValue } from '@robota-sdk/agent-core';
 import type {
+  IChannelDescriptor,
   IConfigurableTransport,
-  IInteractiveSession,
+  IPayloadChannel,
+  IPayloadChannelHost,
+  TChannelEventMap,
 } from '@robota-sdk/agent-interface-transport';
+import type { IProtocolSession } from '@robota-sdk/agent-transport';
+import type { RawData, WebSocket } from 'ws';
 
-const DEFAULT_PORT = 7070;
-const DEFAULT_MAX_RETRIES = 20;
-
-export interface IWsTransportConfig {
-  port?: number;
-  maxRetries?: number;
-}
+/**
+ * RUNTIME-13: forced-terminate deadline for `stop()`. `WebSocketServer.close()` fires its callback only after
+ * every client socket is gone, so a still-connected client would hang `stop()` forever. We send a close frame
+ * (1001 "going away") to each client, then `terminate()` any socket still open at this deadline — the RFC 6455
+ * + `ws` + drain-then-force convention (a WS close handshake completes in well under a second; 5s is generous).
+ */
+const WS_STOP_TERMINATE_DEADLINE_MS = 5000;
 
-export class WsTransport implements IConfigurableTransport<IInteractiveSession> {
+/**
+ * TRANS-001: the WS transport is a payload-agnostic CARRIER that routes by WebSocket frame opcode —
+ * TEXT frames go to the text-agent protocol profile (`createSessionMessageHandler`), BINARY frames go to the
+ * consumer-declared channels. The two profiles share one connection and never constrain each other.
+ */
+export class WsTransport
+  implements IConfigurableTransport<IProtocolSession>, IPayloadChannelHost
+{
   readonly name = 'ws';
+  readonly lifecycle = Object.freeze({ kind: 'service' as const });
   readonly defaultEnabled = true;
   readonly optionsSchema = {
     port: { type: 'number', description: 'WebSocket server port', default: DEFAULT_PORT },
@@ -36,44 +66,132 @@ export class WsTransport implements IConfigurableTransport<IInteractiveSession>
     },
   };
 
-  private session: IInteractiveSession | null = null;
+  private session: IProtocolSession | null = null;
   private stopFn: (() => Promise<void>) | null = null;
-  private readonly port: number;
-  private readonly maxRetries: number;
+  private state: 'detached' | 'attached' | 'starting' | 'ready' | 'stopping' = 'detached';
+  private startOperation: Promise<{ stop: () => Promise<void>; port: number }> | undefined;
+  private startCancelled = false;
+  private port: number;
+  private maxRetries: number;
+  private readonly token?: string;
+  private readonly allowedHosts: ReadonlySet<string>;
+  private readonly allowedOrigins: ReadonlySet<string>;
+  private readonly handlerOptions: ReturnType<typeof configuredWsHandlerOptions>;
+  private readonly channels = new PayloadChannelRegistry();
+  private resolvedPort?: number;
 
   constructor(config: IWsTransportConfig = {}) {
     this.port = config.port ?? DEFAULT_PORT;
     this.maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES;
+    // SEC-001/SEC-008: secure by default, decided by the shared seam rather than a copy here — see
+    // SPEC § Transport Admission. A failed mint throws out of the constructor (fail-closed).
+    const admission = resolveWsAdmission(config);
+    if (admission.token !== null) this.token = admission.token;
+    this.allowedHosts = new Set(config.allowedHosts ?? []);
+    this.allowedOrigins = new Set(config.allowedOrigins ?? []);
+    this.handlerOptions = configuredWsHandlerOptions(config);
   }
 
-  attach(session: IInteractiveSession): void {
+  attach(session: IProtocolSession): void {
     this.session = session;
+    this.state = 'attached';
+  }
+
+  /**
+   * TRANS-001: declare an app-level channel carried on this transport's connections. The channel's
+   * events and opaque binary frames ride alongside the text-agent protocol on the SAME socket — the
+   * transport never inspects the payloads. Register before or after `start()`; a channel opened
+   * later is served by every already-connected client.
+   */
+  registerChannel<TEvents extends TChannelEventMap>(
+    descriptor: IChannelDescriptor<TEvents>,
+  ): IPayloadChannel<TEvents> {
+    return this.channels.registerChannel(descriptor);
+  }
+
+  /** Actually-bound port after start; undefined before start. */
+  get boundPort(): number | undefined {
+    return this.resolvedPort;
+  }
+
+  /**
+   * SEC-001: the resolved auth token (explicit or auto-minted), or `undefined` in the discouraged `open`
+   * mode. The surface reads this to deliver the token to the co-located client (a `0600` connection file /
+   * the served monitor's injected `ws-url`). Never logged by the transport itself.
+   */
+  get resolvedToken(): string | undefined {
+    return this.token;
   }
 
   async start(): Promise<void> {
-    if (!this.session) throw new Error('WsTransport: attach() must be called before start()');
-    const handle = await this.bindWithRetry(this.session, this.port, this.maxRetries);
+    if (!this.session) throw transportLifecycleError(this.name, 'not-attached');
+    if (this.state === 'starting' || this.state === 'ready' || this.state === 'stopping') {
+      throw transportLifecycleError(this.name, 'already-started');
+    }
+    this.state = 'starting';
+    this.startCancelled = false;
+    const operation = this.bindWithRetry(this.session, this.port, this.maxRetries);
+    this.startOperation = operation;
+    let handle: Awaited<typeof operation>;
+    try {
+      handle = await operation;
+    } catch (error) {
+      if (this.state === 'starting' && this.startOperation === operation) {
+        this.startOperation = undefined;
+        this.state = this.session ? 'attached' : 'detached';
+      }
+      throw error;
+    }
+    if (this.startCancelled || this.startOperation !== operation) {
+      await handle.stop();
+      this.state = this.session ? 'attached' : 'detached';
+      throw new Error('WsTransport startup was stopped.');
+    }
     this.stopFn = handle.stop;
+    this.resolvedPort = handle.port;
+    this.startOperation = undefined;
+    this.state = 'ready';
   }
 
   async stop(): Promise<void> {
+    if (this.state === 'starting') {
+      this.state = 'stopping';
+      this.startCancelled = true;
+      try {
+        await this.startOperation;
+      } catch {
+        // The start caller owns bind failure; stop still clears lifecycle state.
+      }
+    }
     await this.stopFn?.();
     this.stopFn = null;
+    this.startOperation = undefined;
+    this.resolvedPort = undefined;
+    this.session = null;
+    this.state = 'detached';
+  }
+
+  /** TRANS-002 (issue #2480): persisted `port`/`maxRetries` reach the server through here, before start. */
+  configure(options: Record<string, TUniversalValue>): void {
+    if (this.state !== 'detached' && this.state !== 'attached') {
+      throw transportLifecycleError(this.name, 'already-started');
+    }
+    if (!this.validateOptions(options)) {
+      throw new TypeError('WsTransport options are invalid (port 1-65535, maxRetries >= 0).');
+    }
+    if (typeof options['port'] === 'number') this.port = options['port'];
+    if (typeof options['maxRetries'] === 'number') this.maxRetries = options['maxRetries'];
   }
 
   validateOptions(options: Record<string, TUniversalValue>): boolean {
-    const { port, maxRetries } = options;
-    if (port !== undefined && (typeof port !== 'number' || port < 1 || port > 65535)) return false;
-    if (maxRetries !== undefined && (typeof maxRetries !== 'number' || maxRetries < 0))
-      return false;
-    return true;
+    return validTransportOptions(options);
   }
 
   private bindWithRetry(
-    session: IInteractiveSession,
+    session: IProtocolSession,
     port: number,
     retriesLeft: number,
-  ): Promise<{ stop: () => Promise<void> }> {
+  ): Promise<{ stop: () => Promise<void>; port: number }> {
     return this.tryBind(session, port).catch((err: NodeJS.ErrnoException) => {
       if (err.code === 'EADDRINUSE' && retriesLeft > 0)
         return this.bindWithRetry(session, port + 1, retriesLeft - 1);
@@ -82,9 +200,9 @@ export class WsTransport implements IConfigurableTransport<IInteractiveSession>
   }
 
   private tryBind(
-    session: IInteractiveSession,
+    session: IProtocolSession,
     port: number,
-  ): Promise<{ stop: () => Promise<void> }> {
+  ): Promise<{ stop: () => Promise<void>; port: number }> {
     return new Promise((resolve, reject) => {
       const httpServer: Server = createServer((_, res) => {
         res.writeHead(400).end('WebSocket endpoint');
@@ -95,31 +213,90 @@ export class WsTransport implements IConfigurableTransport<IInteractiveSession>
         reject(err);
       });
 
+      const expectedToken = this.token;
+      const allowedHosts = this.allowedHosts;
+      const allowedOrigins = this.allowedOrigins;
+      const channels = this.channels;
       httpServer.listen(port, '127.0.0.1', () => {
-        const wss = new WebSocketServer({ server: httpServer });
+        const wss = new WebSocketServer({
+          server: httpServer,
+          // Reject disallowed Host/Origin before the protocol upgrade or any session data.
+          verifyClient: (
+            info: { origin: string; secure: boolean; req: IncomingMessage },
+            cb: (res: boolean, code?: number, message?: string) => void,
+          ) => {
+            if (!hostAllowed(info.req, allowedHosts)) {
+              cb(false, 403, 'Forbidden host');
+              return;
+            }
+            if (!originAllowed(info.req, allowedOrigins)) {
+              cb(false, 403, 'Forbidden origin');
+              return;
+            }
+            cb(true);
+          },
+        });
+
+        wss.on('connection', (ws: WebSocket, req: IncomingMessage) => {
+          // Reject unauthenticated peers before sending history or accepting prompt responses.
+          if (expectedToken !== undefined && !tokenMatches(expectedToken, presentedToken(req))) {
+            ws.close(1008, 'unauthorized');
+            return;
+          }
 
-        wss.on('connection', (ws: WebSocket) => {
-          const send = (message: TServerMessage): void => {
-            if (ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify(message));
-          };
+          const delivery = new WsSessionDelivery(ws);
+          const handler = createSessionMessageHandler({
+            session,
+            deliver: delivery.deliver,
+            ...this.handlerOptions,
+          });
+          delivery.bindProtocolCleanup(handler.cleanup);
 
-          const { onMessage, cleanup } = createWsHandler({ session, send });
+          delivery.bindSinkDetach(
+            // ARCH-030: through the connection's own delivery, so payload frames share the text
+            // protocol's backpressure budget and its close policy. The bare `readyState` check plus
+            // `ws.send` that stood here was the last outbound path on this socket outside the
+            // boundary.
+            channels.addSink((frame: Uint8Array) => delivery.deliverBinary(frame)),
+          );
 
-          ws.on('message', (data) => onMessage(String(data)));
-          ws.on('close', cleanup);
-          ws.on('error', cleanup);
+          // Route by frame opcode: TEXT → the text-agent protocol profile, BINARY → the
+          // payload-agnostic channels. An unroutable channel frame is answered with an explicit
+          // `protocol_error` rather than silently dropped.
+          ws.on('message', (data: RawData, isBinary: boolean) => {
+            if (!isBinary) {
+              handler.onMessage(String(data));
+              return;
+            }
+            const result = channels.receive(toBytes(data));
+            if (!result.ok) delivery.deliver({ type: 'protocol_error', message: result.error });
+          });
+          ws.on('close', delivery.close);
+          ws.on('error', delivery.close);
 
-          send({ type: 'messages', messages: session.getMessages() });
-          send({
+          delivery.deliver({ type: 'messages', messages: session.getMessages() });
+          delivery.deliver({
             type: 'execution_workspace_event',
             snapshot: session.getExecutionWorkspaceSnapshot(),
           });
         });
 
         resolve({
+          port,
           stop: () =>
             new Promise<void>((res) => {
-              wss.close(() => httpServer.close(() => res()));
+              // RUNTIME-13: graceful-then-forced shutdown. Send a close frame to each client so well-behaved
+              // peers close cleanly; terminate any socket still open at the deadline so `wss.close()`'s
+              // all-clients-gone callback can never hang. `verifyClient`/token gates are connection-time and
+              // untouched here (SEC-001 preserved).
+              for (const client of wss.clients) client.close(1001, 'server shutting down');
+              const deadline = setTimeout(() => {
+                for (const client of wss.clients) client.terminate();
+              }, WS_STOP_TERMINATE_DEADLINE_MS);
+              wss.close(() => {
+                clearTimeout(deadline);
+                httpServer.close(() => res());
+              });
             }),
         });
       });