@bitkyc08/opencodex 2.51.0 → 2.52.0-preview.20260912

package/src/remote-control/host.ts

@@ -0,0 +1,175 @@
+import {
+  acceptRemoteControlClientHello,
+  parseRemoteControlClientHello,
+  serializeRemoteControlHello,
+  type RemoteControlCipher,
+} from "./crypto";
+import {
+  REMOTE_CONTROL_CAPABILITIES,
+  REMOTE_CONTROL_MAX_RELAY_PAYLOAD_BYTES,
+  REMOTE_CONTROL_MAX_SESSIONS_PER_DEVICE,
+  decodeRemoteControlApplicationFrame,
+  encodeRemoteControlApplicationFrame,
+  type RemoteControlApplicationFrame,
+  type RemoteControlCapability,
+  type RemoteControlCommandProfile,
+} from "./protocol";
+
+export interface RemoteControlTerminal {
+  write(value: Uint8Array): void | Promise<void>;
+  resize(columns: number, rows: number): void | Promise<void>;
+  close(): void | Promise<void>;
+}
+
+export interface RemoteControlTerminalFactory {
+  create(options: {
+    commandProfile: RemoteControlCommandProfile;
+    onOutput(value: Uint8Array): void;
+    onExit(code: number): void;
+  }): RemoteControlTerminal | Promise<RemoteControlTerminal>;
+}
+
+interface HostSession {
+  commandProfile: RemoteControlCommandProfile;
+  capabilities: Set<RemoteControlCapability>;
+  cipher: RemoteControlCipher;
+  onCiphertext(value: Uint8Array): void;
+  terminal?: RemoteControlTerminal;
+  queue: Promise<void>;
+  closed: boolean;
+}
+
+export interface RemoteControlHostOptions {
+  deviceId: string;
+  devicePrivateKey: string;
+  accountPublicKey: string;
+  terminalFactory: RemoteControlTerminalFactory;
+  allowedCapabilities?: readonly RemoteControlCapability[];
+  maxSessions?: number;
+}
+
+/**
+ * Local execution boundary for the Paseo-style topology. The relay never owns
+ * this registry or a terminal. A successfully signed hello reserves only a
+ * session; the first authenticated input/resize frame starts the local process.
+ */
+export class RemoteControlHost {
+  private readonly sessions = new Map<string, HostSession>();
+  private readonly allowedCapabilities: readonly RemoteControlCapability[];
+  private readonly maxSessions: number;
+
+  constructor(private readonly options: RemoteControlHostOptions) {
+    this.allowedCapabilities = options.allowedCapabilities ?? REMOTE_CONTROL_CAPABILITIES;
+    this.maxSessions = options.maxSessions ?? REMOTE_CONTROL_MAX_SESSIONS_PER_DEVICE;
+    if (!Number.isSafeInteger(this.maxSessions) || this.maxSessions < 1) {
+      throw new Error("invalid remote control host session limit");
+    }
+  }
+
+  open(sessionId: string, clientHelloPayload: Uint8Array, onCiphertext: (value: Uint8Array) => void): Uint8Array {
+    if (this.sessions.has(sessionId)) throw new Error("remote control host session already exists");
+    if (this.sessions.size >= this.maxSessions) throw new Error("remote control host session limit reached");
+    const clientHello = parseRemoteControlClientHello(clientHelloPayload);
+    const accepted = acceptRemoteControlClientHello(clientHello, {
+      expectedSessionId: sessionId,
+      expectedDeviceId: this.options.deviceId,
+      accountPublicKey: this.options.accountPublicKey,
+      devicePrivateKey: this.options.devicePrivateKey,
+      allowedCapabilities: this.allowedCapabilities,
+    });
+    this.sessions.set(sessionId, {
+      commandProfile: clientHello.commandProfile,
+      capabilities: new Set(accepted.hello.capabilities),
+      cipher: accepted.cipher,
+      onCiphertext,
+      queue: Promise.resolve(),
+      closed: false,
+    });
+    return serializeRemoteControlHello(accepted.hello);
+  }
+
+  receive(sessionId: string, encryptedPayload: Uint8Array): Promise<void> {
+    const session = this.sessions.get(sessionId);
+    if (!session || session.closed) return Promise.reject(new Error("unknown remote control host session"));
+    const run = session.queue
+      .then(() => this.handleAuthenticatedFrame(sessionId, session, encryptedPayload))
+      .catch(async error => {
+        await this.close(sessionId);
+        throw error;
+      });
+    session.queue = run.catch(() => undefined);
+    return run;
+  }
+
+  async close(sessionId: string): Promise<void> {
+    const session = this.sessions.get(sessionId);
+    if (!session) return;
+    this.sessions.delete(sessionId);
+    session.closed = true;
+    session.cipher.destroy();
+    if (session.terminal) await session.terminal.close();
+  }
+
+  private async handleAuthenticatedFrame(
+    sessionId: string,
+    session: HostSession,
+    encryptedPayload: Uint8Array,
+  ): Promise<void> {
+    let frame: RemoteControlApplicationFrame;
+    try {
+      frame = decodeRemoteControlApplicationFrame(session.cipher.decrypt(encryptedPayload));
+    } catch (error) {
+      await this.close(sessionId);
+      throw error;
+    }
+    if (frame.kind !== "input" && frame.kind !== "resize") {
+      await this.close(sessionId);
+      throw new Error("remote control client sent a host-only terminal frame");
+    }
+    const required: RemoteControlCapability = frame.kind === "input" ? "terminal.input" : "terminal.resize";
+    if (!session.capabilities.has(required)) {
+      await this.close(sessionId);
+      throw new Error(`remote control capability ${required} was not granted`);
+    }
+    if (!session.terminal) {
+      const terminal = await this.startTerminal(sessionId, session);
+      if (session.closed) {
+        await terminal.close();
+        throw new Error("remote control host session closed while starting the terminal");
+      }
+      session.terminal = terminal;
+    }
+    if (frame.kind === "input") await session.terminal.write(frame.data);
+    else await session.terminal.resize(frame.columns, frame.rows);
+  }
+
+  private async startTerminal(sessionId: string, session: HostSession): Promise<RemoteControlTerminal> {
+    return await this.options.terminalFactory.create({
+      commandProfile: session.commandProfile,
+      onOutput: value => {
+        if (session.closed || !session.capabilities.has("terminal.output")) return;
+        const maxChunk = REMOTE_CONTROL_MAX_RELAY_PAYLOAD_BYTES - 25;
+        for (let offset = 0; offset < value.byteLength; offset += maxChunk) {
+          this.emitApplicationFrame(sessionId, session, { kind: "output", data: value.subarray(offset, offset + maxChunk) });
+        }
+      },
+      onExit: code => {
+        if (session.closed) return;
+        this.emitApplicationFrame(sessionId, session, { kind: "exit", code });
+        void this.close(sessionId);
+      },
+    });
+  }
+
+  private emitApplicationFrame(
+    sessionId: string,
+    session: HostSession,
+    frame: RemoteControlApplicationFrame,
+  ): void {
+    try {
+      session.onCiphertext(session.cipher.encrypt(encodeRemoteControlApplicationFrame(frame)));
+    } catch {
+      void this.close(sessionId);
+    }
+  }
+}

package/src/remote-control/index.ts

@@ -0,0 +1,100 @@
+export {
+  REMOTE_CONTROL_PROTOCOL_VERSION,
+  REMOTE_CONTROL_RELAY_HEADER_BYTES,
+  REMOTE_CONTROL_MAX_RELAY_PAYLOAD_BYTES,
+  REMOTE_CONTROL_MAX_SESSIONS_PER_DEVICE,
+  REMOTE_CONTROL_MAX_BUFFERED_BYTES,
+  REMOTE_CONTROL_COMMAND_PROFILES,
+  REMOTE_CONTROL_CAPABILITIES,
+  isRemoteControlUuid,
+  remoteControlUuidBytes,
+  isRemoteControlCommandProfile,
+  normalizeRemoteControlCapabilities,
+  encodeRemoteControlRelayFrame,
+  decodeRemoteControlRelayFrame,
+  encodeRemoteControlApplicationFrame,
+  decodeRemoteControlApplicationFrame,
+} from "./protocol";
+export type {
+  RemoteControlCommandProfile,
+  RemoteControlCapability,
+  RemoteControlClientHello,
+  RemoteControlHostHello,
+  RemoteControlRelayFrameKind,
+  RemoteControlRelayFrame,
+  RemoteControlApplicationFrame,
+} from "./protocol";
+export {
+  parseRemoteControlClientHello,
+  parseRemoteControlHostHello,
+  serializeRemoteControlHello,
+  generateRemoteControlIdentityKeyPair,
+  RemoteControlCipher,
+  RemoteControlClientHandshake,
+  acceptRemoteControlClientHello,
+} from "./crypto";
+export type {
+  RemoteControlIdentityKeyPair,
+  CreateRemoteControlClientHandshakeOptions,
+  AcceptRemoteControlClientHelloOptions,
+} from "./crypto";
+export {
+  RemoteControlHost,
+} from "./host";
+export type {
+  RemoteControlTerminal,
+  RemoteControlTerminalFactory,
+  RemoteControlHostOptions,
+} from "./host";
+export {
+  OpaqueRemoteControlRelay,
+} from "./relay";
+export type {
+  RemoteControlRelayPeer,
+  OpaqueRemoteControlRelayOptions,
+} from "./relay";
+export {
+  REMOTE_WORKSPACE_TOOL_NAMESPACE,
+  REMOTE_WORKSPACE_MAX_TOOL_RESULT_BYTES,
+  REMOTE_WORKSPACE_CAPABILITIES,
+  REMOTE_WORKSPACE_DYNAMIC_TOOLS,
+  parseRemoteWorkspaceCapabilities,
+  remoteWorkspaceToolsForCapabilities,
+  remoteWorkspaceDynamicToolsForCapabilities,
+  remoteWorkspaceCapabilityForTool,
+  isRemoteWorkspaceCapability,
+  isRemoteWorkspaceToolName,
+  parseRemoteWorkspaceToolCall,
+  remoteWorkspaceDeveloperInstructions,
+  remoteWorkspaceCodexDeveloperInstructions,
+} from "./workspace-tools";
+export type {
+  RemoteWorkspaceCapability,
+  RemoteWorkspaceToolName,
+  RemoteWorkspaceDynamicToolFunction,
+  RemoteWorkspaceDynamicToolNamespace,
+  RemoteWorkspaceToolCallParams,
+  RemoteWorkspaceToolResult,
+} from "./workspace-tools";
+export {
+  REMOTE_WORKSPACE_AGENT_PROTOCOL_VERSION,
+  REMOTE_WORKSPACE_AGENT_MAX_CONTROL_BYTES,
+  isRemoteWorkspaceAgentProfile,
+  serializeRemoteWorkspaceHubMessage,
+  serializeRemoteWorkspaceAgentMessage,
+  parseRemoteWorkspaceHubMessage,
+  parseRemoteWorkspaceAgentMessage,
+} from "./workspace-agent-protocol";
+export type {
+  RemoteWorkspaceAgentProfile,
+  RemoteWorkspaceHubMessage,
+  RemoteWorkspaceAgentMessage,
+} from "./workspace-agent-protocol";
+export {
+  REMOTE_WORKSPACE_RPC_MAX_MESSAGE_BYTES,
+  frameRemoteWorkspaceRpcMessage,
+  RemoteWorkspaceRpcReassembler,
+} from "./workspace-rpc-framing";
+export {
+  truncateRemoteWorkspaceUtf8,
+} from "./workspace-utf8";

package/src/remote-control/protocol.ts

@@ -0,0 +1,200 @@
+export const REMOTE_CONTROL_PROTOCOL_VERSION = 1 as const;
+export const REMOTE_CONTROL_RELAY_HEADER_BYTES = 18;
+export const REMOTE_CONTROL_MAX_RELAY_PAYLOAD_BYTES = 64 * 1024;
+export const REMOTE_CONTROL_MAX_SESSIONS_PER_DEVICE = 4;
+export const REMOTE_CONTROL_MAX_BUFFERED_BYTES = 1024 * 1024;
+
+export const REMOTE_CONTROL_COMMAND_PROFILES = ["shell", "codex", "claude", "pi"] as const;
+export type RemoteControlCommandProfile = typeof REMOTE_CONTROL_COMMAND_PROFILES[number];
+
+export const REMOTE_CONTROL_CAPABILITIES = [
+  "terminal.input",
+  "terminal.output",
+  "terminal.resize",
+  "workspace.read",
+  "workspace.write",
+  "workspace.exec",
+] as const;
+export type RemoteControlCapability = typeof REMOTE_CONTROL_CAPABILITIES[number];
+
+export interface RemoteControlClientHello {
+  version: typeof REMOTE_CONTROL_PROTOCOL_VERSION;
+  sessionId: string;
+  deviceId: string;
+  commandProfile: RemoteControlCommandProfile;
+  capabilities: RemoteControlCapability[];
+  ephemeralPublicKey: string;
+  nonce: string;
+  signature: string;
+}
+
+export interface RemoteControlHostHello {
+  version: typeof REMOTE_CONTROL_PROTOCOL_VERSION;
+  sessionId: string;
+  deviceId: string;
+  capabilities: RemoteControlCapability[];
+  ephemeralPublicKey: string;
+  nonce: string;
+  signature: string;
+}
+
+export type RemoteControlRelayFrameKind = "open" | "data" | "close";
+
+export interface RemoteControlRelayFrame {
+  kind: RemoteControlRelayFrameKind;
+  sessionId: string;
+  payload: Uint8Array;
+}
+
+export type RemoteControlApplicationFrame =
+  | { kind: "input"; data: Uint8Array }
+  | { kind: "resize"; columns: number; rows: number }
+  | { kind: "output"; data: Uint8Array }
+  | { kind: "exit"; code: number };
+
+const RELAY_KIND_TO_BYTE: Record<RemoteControlRelayFrameKind, number> = {
+  open: 1,
+  data: 2,
+  close: 3,
+};
+const RELAY_BYTE_TO_KIND = new Map<number, RemoteControlRelayFrameKind>([
+  [1, "open"],
+  [2, "data"],
+  [3, "close"],
+]);
+
+const APPLICATION_KIND_TO_BYTE = {
+  input: 1,
+  resize: 2,
+  output: 3,
+  exit: 4,
+} as const;
+
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export function isRemoteControlUuid(value: unknown): value is string {
+  return typeof value === "string" && UUID_PATTERN.test(value);
+}
+
+export function remoteControlUuidBytes(value: string): Uint8Array {
+  if (!isRemoteControlUuid(value)) throw new Error("invalid remote control UUID");
+  return Uint8Array.from(value.replaceAll("-", "").match(/.{2}/g)!, byte => Number.parseInt(byte, 16));
+}
+
+function remoteControlUuidString(value: Uint8Array): string {
+  if (value.byteLength !== 16) throw new Error("invalid remote control UUID bytes");
+  const hex = Buffer.from(value).toString("hex");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+export function isRemoteControlCommandProfile(value: unknown): value is RemoteControlCommandProfile {
+  return typeof value === "string" && (REMOTE_CONTROL_COMMAND_PROFILES as readonly string[]).includes(value);
+}
+
+export function normalizeRemoteControlCapabilities(value: unknown): RemoteControlCapability[] {
+  if (!Array.isArray(value) || value.length > REMOTE_CONTROL_CAPABILITIES.length) {
+    throw new Error("invalid remote control capabilities");
+  }
+  const allowed = new Set<string>(REMOTE_CONTROL_CAPABILITIES);
+  const result = value.map(capability => {
+    if (typeof capability !== "string" || !allowed.has(capability)) {
+      throw new Error("invalid remote control capability");
+    }
+    return capability as RemoteControlCapability;
+  });
+  if (new Set(result).size !== result.length) throw new Error("duplicate remote control capability");
+  return result.sort();
+}
+
+export function encodeRemoteControlRelayFrame(frame: RemoteControlRelayFrame): Uint8Array {
+  if (!isRemoteControlUuid(frame.sessionId)) throw new Error("invalid relay session ID");
+  if (!(frame.payload instanceof Uint8Array) || frame.payload.byteLength > REMOTE_CONTROL_MAX_RELAY_PAYLOAD_BYTES) {
+    throw new Error("remote control relay payload is too large");
+  }
+  const kind = RELAY_KIND_TO_BYTE[frame.kind];
+  if (!kind) throw new Error("invalid remote control relay frame kind");
+  const result = new Uint8Array(REMOTE_CONTROL_RELAY_HEADER_BYTES + frame.payload.byteLength);
+  result[0] = REMOTE_CONTROL_PROTOCOL_VERSION;
+  result[1] = kind;
+  result.set(remoteControlUuidBytes(frame.sessionId), 2);
+  result.set(frame.payload, REMOTE_CONTROL_RELAY_HEADER_BYTES);
+  return result;
+}
+
+export function decodeRemoteControlRelayFrame(value: Uint8Array): RemoteControlRelayFrame {
+  if (
+    !(value instanceof Uint8Array)
+    || value.byteLength < REMOTE_CONTROL_RELAY_HEADER_BYTES
+    || value.byteLength > REMOTE_CONTROL_RELAY_HEADER_BYTES + REMOTE_CONTROL_MAX_RELAY_PAYLOAD_BYTES
+  ) throw new Error("invalid remote control relay frame length");
+  if (value[0] !== REMOTE_CONTROL_PROTOCOL_VERSION) throw new Error("unsupported remote control relay protocol");
+  const kind = RELAY_BYTE_TO_KIND.get(value[1]!);
+  if (!kind) throw new Error("invalid remote control relay frame kind");
+  return {
+    kind,
+    sessionId: remoteControlUuidString(value.subarray(2, REMOTE_CONTROL_RELAY_HEADER_BYTES)),
+    payload: value.slice(REMOTE_CONTROL_RELAY_HEADER_BYTES),
+  };
+}
+
+function validTerminalDimension(value: number): boolean {
+  return Number.isInteger(value) && value >= 1 && value <= 4096;
+}
+
+export function encodeRemoteControlApplicationFrame(frame: RemoteControlApplicationFrame): Uint8Array {
+  if (frame.kind === "input" || frame.kind === "output") {
+    if (!(frame.data instanceof Uint8Array) || frame.data.byteLength > REMOTE_CONTROL_MAX_RELAY_PAYLOAD_BYTES - 25) {
+      throw new Error("remote control terminal payload is too large");
+    }
+    const result = new Uint8Array(1 + frame.data.byteLength);
+    result[0] = APPLICATION_KIND_TO_BYTE[frame.kind];
+    result.set(frame.data, 1);
+    return result;
+  }
+  if (frame.kind === "resize") {
+    if (!validTerminalDimension(frame.columns) || !validTerminalDimension(frame.rows)) {
+      throw new Error("invalid remote control terminal size");
+    }
+    const result = new Uint8Array(5);
+    result[0] = APPLICATION_KIND_TO_BYTE.resize;
+    const view = new DataView(result.buffer);
+    view.setUint16(1, frame.columns, false);
+    view.setUint16(3, frame.rows, false);
+    return result;
+  }
+  if (!Number.isInteger(frame.code) || frame.code < -0x80000000 || frame.code > 0x7fffffff) {
+    throw new Error("invalid remote control terminal exit code");
+  }
+  const result = new Uint8Array(5);
+  result[0] = APPLICATION_KIND_TO_BYTE.exit;
+  new DataView(result.buffer).setInt32(1, frame.code, false);
+  return result;
+}
+
+export function decodeRemoteControlApplicationFrame(value: Uint8Array): RemoteControlApplicationFrame {
+  if (!(value instanceof Uint8Array) || value.byteLength < 1) throw new Error("empty remote control application frame");
+  if (value[0] === APPLICATION_KIND_TO_BYTE.input || value[0] === APPLICATION_KIND_TO_BYTE.output) {
+    if (value.byteLength > REMOTE_CONTROL_MAX_RELAY_PAYLOAD_BYTES - 24) {
+      throw new Error("remote control terminal payload is too large");
+    }
+    return {
+      kind: value[0] === APPLICATION_KIND_TO_BYTE.input ? "input" : "output",
+      data: value.slice(1),
+    };
+  }
+  if (value[0] === APPLICATION_KIND_TO_BYTE.resize) {
+    if (value.byteLength !== 5) throw new Error("invalid remote control resize frame");
+    const view = new DataView(value.buffer, value.byteOffset, value.byteLength);
+    const columns = view.getUint16(1, false);
+    const rows = view.getUint16(3, false);
+    if (!validTerminalDimension(columns) || !validTerminalDimension(rows)) {
+      throw new Error("invalid remote control terminal size");
+    }
+    return { kind: "resize", columns, rows };
+  }
+  if (value[0] === APPLICATION_KIND_TO_BYTE.exit) {
+    if (value.byteLength !== 5) throw new Error("invalid remote control exit frame");
+    return { kind: "exit", code: new DataView(value.buffer, value.byteOffset, value.byteLength).getInt32(1, false) };
+  }
+  throw new Error("unknown remote control application frame");
+}

package/src/remote-control/relay.ts

@@ -0,0 +1,162 @@
+import {
+  REMOTE_CONTROL_MAX_BUFFERED_BYTES,
+  REMOTE_CONTROL_MAX_SESSIONS_PER_DEVICE,
+  decodeRemoteControlRelayFrame,
+  encodeRemoteControlRelayFrame,
+  isRemoteControlUuid,
+  type RemoteControlRelayFrameKind,
+} from "./protocol";
+
+export interface RemoteControlRelayPeer {
+  bufferedAmount(): number;
+  send(value: Uint8Array): void;
+  close(code: number, reason: string): void;
+}
+
+interface RelaySession {
+  deviceId: string;
+  client: RemoteControlRelayPeer;
+}
+
+export interface OpaqueRemoteControlRelayOptions {
+  maxBufferedBytes?: number;
+  maxSessionsPerDevice?: number;
+}
+
+/**
+ * Routes bounded envelopes without decoding the handshake or application payload.
+ * Account/session authorization belongs at the HTTP/WebSocket upgrade boundary;
+ * this class begins only after that control-plane decision has succeeded.
+ */
+export class OpaqueRemoteControlRelay {
+  private readonly hosts = new Map<string, RemoteControlRelayPeer>();
+  private readonly sessions = new Map<string, RelaySession>();
+  private readonly maxBufferedBytes: number;
+  private readonly maxSessionsPerDevice: number;
+
+  constructor(options: OpaqueRemoteControlRelayOptions = {}) {
+    this.maxBufferedBytes = options.maxBufferedBytes ?? REMOTE_CONTROL_MAX_BUFFERED_BYTES;
+    this.maxSessionsPerDevice = options.maxSessionsPerDevice ?? REMOTE_CONTROL_MAX_SESSIONS_PER_DEVICE;
+    if (!Number.isSafeInteger(this.maxBufferedBytes) || this.maxBufferedBytes < 1) {
+      throw new Error("invalid remote control relay buffer limit");
+    }
+    if (!Number.isSafeInteger(this.maxSessionsPerDevice) || this.maxSessionsPerDevice < 1) {
+      throw new Error("invalid remote control relay session limit");
+    }
+  }
+
+  registerHost(deviceId: string, host: RemoteControlRelayPeer): () => void {
+    if (!isRemoteControlUuid(deviceId)) throw new Error("invalid remote control device ID");
+    const previous = this.hosts.get(deviceId);
+    if (previous && previous !== host) {
+      previous.close(1012, "remote control host reconnected");
+      this.closeDeviceSessions(deviceId, 1012, "remote control host reconnected");
+    }
+    this.hosts.set(deviceId, host);
+    return () => {
+      if (this.hosts.get(deviceId) !== host) return;
+      this.hosts.delete(deviceId);
+      this.closeDeviceSessions(deviceId, 1013, "remote control host disconnected");
+    };
+  }
+
+  attachClient(options: {
+    sessionId: string;
+    deviceId: string;
+    client: RemoteControlRelayPeer;
+    openPayload: Uint8Array;
+  }): () => void {
+    if (this.sessions.has(options.sessionId)) throw new Error("remote control session is already attached");
+    const host = this.hosts.get(options.deviceId);
+    if (!host) throw new Error("remote control host is offline");
+    const active = [...this.sessions.values()].filter(session => session.deviceId === options.deviceId).length;
+    if (active >= this.maxSessionsPerDevice) throw new Error("remote control device session limit reached");
+    const session: RelaySession = { deviceId: options.deviceId, client: options.client };
+    this.sessions.set(options.sessionId, session);
+    try {
+      this.forward(host, "open", options.sessionId, options.openPayload);
+    } catch (error) {
+      this.sessions.delete(options.sessionId);
+      throw error;
+    }
+    return () => this.detachClient(options.sessionId, options.client);
+  }
+
+  receiveFromClient(sessionId: string, client: RemoteControlRelayPeer, payload: Uint8Array): void {
+    const session = this.sessions.get(sessionId);
+    if (!session || session.client !== client) throw new Error("unknown remote control client session");
+    const host = this.hosts.get(session.deviceId);
+    if (!host) {
+      this.sessions.delete(sessionId);
+      client.close(1013, "remote control host is offline");
+      return;
+    }
+    try {
+      this.forward(host, "data", sessionId, payload);
+    } catch (error) {
+      this.sessions.delete(sessionId);
+      client.close(1013, "remote control host is backpressured");
+      throw error;
+    }
+  }
+
+  receiveFromHost(deviceId: string, host: RemoteControlRelayPeer, encoded: Uint8Array): void {
+    if (this.hosts.get(deviceId) !== host) throw new Error("unknown remote control host");
+    const frame = decodeRemoteControlRelayFrame(encoded);
+    if (frame.kind === "open") throw new Error("remote control host cannot open browser sessions");
+    const session = this.sessions.get(frame.sessionId);
+    if (!session) return;
+    if (session.deviceId !== deviceId) {
+      host.close(1008, "remote control session ownership mismatch");
+      return;
+    }
+    if (frame.kind === "close") {
+      this.sessions.delete(frame.sessionId);
+      session.client.close(1000, "remote control host closed the session");
+      return;
+    }
+    if (session.client.bufferedAmount() > this.maxBufferedBytes) {
+      this.sessions.delete(frame.sessionId);
+      session.client.close(1013, "remote control relay backpressure");
+      this.forward(host, "close", frame.sessionId, new Uint8Array());
+      return;
+    }
+    // Intentionally forward the payload byte-for-byte. Only the endpoints parse it.
+    session.client.send(frame.payload);
+  }
+
+  private detachClient(sessionId: string, client: RemoteControlRelayPeer): void {
+    const session = this.sessions.get(sessionId);
+    if (!session || session.client !== client) return;
+    this.sessions.delete(sessionId);
+    const host = this.hosts.get(session.deviceId);
+    if (host) {
+      try {
+        this.forward(host, "close", sessionId, new Uint8Array());
+      } catch {
+        // The client is already detached; the host transport owns its own close path.
+      }
+    }
+  }
+
+  private closeDeviceSessions(deviceId: string, code: number, reason: string): void {
+    for (const [sessionId, session] of this.sessions) {
+      if (session.deviceId !== deviceId) continue;
+      this.sessions.delete(sessionId);
+      session.client.close(code, reason);
+    }
+  }
+
+  private forward(
+    target: RemoteControlRelayPeer,
+    kind: RemoteControlRelayFrameKind,
+    sessionId: string,
+    payload: Uint8Array,
+  ): void {
+    if (target.bufferedAmount() > this.maxBufferedBytes) {
+      target.close(1013, "remote control relay backpressure");
+      throw new Error("remote control relay target is backpressured");
+    }
+    target.send(encodeRemoteControlRelayFrame({ kind, sessionId, payload }));
+  }
+}