@bitkyc08/opencodex 2.52.0-preview.20260911 → 2.52.0

package/src/providers/stale-context-window-migration.ts

@@ -0,0 +1,92 @@
+/**
+ * Repair context windows that a saved config inherited from a wrong registry seed.
+ *
+ * `enrichProviderFromRegistry` is fill-only: it seeds `modelContextWindows` when
+ * the row has none and never rewrites it afterwards. That posture is right — a
+ * hand-tuned window must survive an upgrade — but it means a registry table that
+ * shipped WRONG numbers is frozen into every config that was saved while those
+ * numbers were current. Correcting the registry alone fixes new installs and
+ * leaves existing ones reporting the old figure forever.
+ *
+ * This rewrites one thing: a window whose saved value is still byte-for-byte the
+ * wrong number this file names, on a provider that still carries the registry's
+ * adapter. A value the user changed does not match `from` and is left alone, and
+ * nothing else in the row is touched. Same shape and the same restraint as
+ * `model-rename-migration`, for the case where the id was right and the number
+ * was not.
+ */
+import { PROVIDER_REGISTRY } from "./registry";
+import type { OcxConfig } from "../types";
+
+export interface StaleContextWindow {
+  /** Registry provider id whose saved rows may carry the wrong window. */
+  provider: string;
+  model: string;
+  /** The wrong value this migration is allowed to replace, and nothing else. */
+  from: number;
+  to: number;
+}
+
+export interface StaleContextWindowProjection {
+  config: OcxConfig;
+  changed: boolean;
+  warnings: string[];
+}
+
+/**
+ * Cognition windows corrected against a live `GetCascadeModelConfigs` response.
+ *
+ * The shipped table had been assembled from each model's ORIGINAL vendor window
+ * rather than from what Cognition serves, so the Claude rows claimed 200k against
+ * an actual 1M and Grok claimed 256k against 500k. Cognition documents no window
+ * anywhere, so the per-account catalog is the only first-party source; these are
+ * the degraded-mode figures, and live discovery supersedes them when it runs.
+ */
+export const STALE_CONTEXT_WINDOWS: readonly StaleContextWindow[] = [
+  { provider: "devin", model: "swe-1-7", from: 256_000, to: 262_000 },
+  { provider: "devin", model: "swe-1-7-lightning", from: 256_000, to: 202_752 },
+  { provider: "devin", model: "gpt-5-6-sol", from: 1_050_000, to: 1_000_000 },
+  { provider: "devin", model: "gpt-5-6-luna", from: 1_050_000, to: 1_000_000 },
+  { provider: "devin", model: "gpt-5-6-terra", from: 1_050_000, to: 1_000_000 },
+  { provider: "devin", model: "claude-opus-4-8", from: 200_000, to: 1_000_000 },
+  { provider: "devin", model: "claude-fable-5-1", from: 200_000, to: 1_000_000 },
+  { provider: "devin", model: "claude-sonnet-5", from: 200_000, to: 1_000_000 },
+  { provider: "devin", model: "kimi-k2-7", from: 256_000, to: 262_144 },
+  { provider: "devin", model: "grok-4-5", from: 256_000, to: 500_000 },
+];
+
+function providerStillMatchesRegistry(id: string, adapter: unknown): boolean {
+  const entry = PROVIDER_REGISTRY.find(row => row.id === id);
+  return entry !== undefined && entry.adapter === adapter;
+}
+
+/** Pure projection. The caller decides whether to persist. */
+export function projectStaleContextWindows(
+  config: OcxConfig,
+  entries: readonly StaleContextWindow[] = STALE_CONTEXT_WINDOWS,
+): StaleContextWindowProjection {
+  const warnings: string[] = [];
+  const repaired = new Map<string, string[]>();
+
+  for (const entry of entries) {
+    const prov = config.providers?.[entry.provider];
+    if (!prov) continue;
+    if (!providerStillMatchesRegistry(entry.provider, prov.adapter)) continue;
+    const windows = prov.modelContextWindows;
+    if (!windows || windows[entry.model] !== entry.from) continue;
+    windows[entry.model] = entry.to;
+    const list = repaired.get(entry.provider) ?? [];
+    list.push(`${entry.model} ${entry.from} -> ${entry.to}`);
+    repaired.set(entry.provider, list);
+  }
+
+  for (const [provider, list] of repaired) {
+    warnings.push(
+      `corrected ${list.length} context window(s) on "${provider}" that the saved config `
+      + `inherited from a wrong registry seed: ${list.join(", ")}.`,
+    );
+  }
+
+  return { config, changed: repaired.size > 0, warnings };
+}
+

package/src/providers/zai-responses-migration.ts

@@ -0,0 +1,45 @@
+import { getProviderRegistryEntry, providerMatchesRegistryTransport } from "./registry";
+import type { OcxConfig } from "../types";
+
+export const ZAI_PROVIDER_ID = "zai";
+export const ZAI_RESPONSES_DEFAULT_VERSION = 1;
+
+/**
+ * Persist the Responses destination the router already applies to the `zai` row.
+ *
+ * The Z.AI coding plan moved from Chat Completions at /api/coding/paas/v4 to Responses at
+ * /api/v1 (#4297). A config written before that move still stores the Chat adapter and the old
+ * base URL, and `routedProviderConfig()` rewrites both on every request because the registry
+ * entry owns a fixed destination. The row therefore already talks Responses while the dashboard,
+ * `ocx doctor` and any direct config reader show the retired Chat endpoint, and each boot logs a
+ * "configured baseUrl is ignored" warning about a value the user never chose.
+ *
+ * This migration writes the canonical pair once so the stored row matches the live wire. It is
+ * behavior-preserving by construction: it only rewrites rows the router canonicalizes anyway.
+ * Chat remains reachable per model through `modelAdapters`, and the persisted marker keeps a
+ * later explicit Chat choice from being migrated again.
+ *
+ * A custom-named provider pointing at the retired endpoint is deliberately left alone. The router
+ * does not canonicalize it, so rewriting it would change a wire the operator actually configured;
+ * `destinationAliases` already gives it this row's metadata.
+ */
+export function migrateZaiResponsesDefault(config: OcxConfig): boolean {
+  const provider = config.providers[ZAI_PROVIDER_ID];
+  if (!provider || (provider.zaiResponsesDefaultVersion ?? 0) >= ZAI_RESPONSES_DEFAULT_VERSION) return false;
+  const entry = getProviderRegistryEntry(ZAI_PROVIDER_ID);
+  if (!entry) return false;
+  // Fail closed if a later registry edit makes this destination operator-owned: only a fixed,
+  // non-templated endpoint is canonicalized at request time, so only that one may be persisted.
+  if (entry.allowBaseUrlOverride || /\{[^}]*\}/.test(entry.baseUrl)) return false;
+  if (!providerMatchesRegistryTransport(ZAI_PROVIDER_ID, provider)) return false;
+  config.providers = {
+    ...config.providers,
+    [ZAI_PROVIDER_ID]: {
+      ...provider,
+      adapter: entry.adapter,
+      baseUrl: entry.baseUrl,
+      zaiResponsesDefaultVersion: ZAI_RESPONSES_DEFAULT_VERSION,
+    },
+  };
+  return true;
+}

package/src/quota/reset-observer.ts

@@ -55,6 +55,7 @@ export function observeQuotaSnapshot(input: {
   readonly accountKey: string;
   readonly windows: ReadonlyArray<QuotaWindowObservation>;
   readonly now?: number;
+  readonly retainAbsentShortWindow?: boolean;
 }): QuotaResetEvent[] {
   try {
     if (!sink) return [];
@@ -65,7 +66,7 @@ export function observeQuotaSnapshot(input: {
     // between two observations to tell a rolling window's natural decay from a real reset,
     // and only this layer knows when the snapshot was taken.
     const stamped = input.windows.map(window => ({ ...window, observedAt: now }));
-    const previous = swapLastObservedWindows(input.scope, accountTag, stamped);
+    const previous = swapLastObservedWindows(input.scope, accountTag, stamped, input.retainAbsentShortWindow);
     if (!previous) return [];
 
     const detected = detectQuotaResets({

package/src/quota/reset-seen-store.ts

@@ -306,6 +306,7 @@ export function swapLastObservedWindows(
   scope: string,
   accountTag: string,
   windows: ReadonlyArray<QuotaWindowObservation>,
+  retainAbsentShortWindow = false,
 ): ReadonlyArray<QuotaWindowObservation> | undefined {
   hydrate();
   const key = observedKey(scope, accountTag);
@@ -317,7 +318,14 @@ export function swapLastObservedWindows(
   // Measured: the hottest scope was evicted and its next genuine scheduled reset was
   // silently missed, because a re-baselined row has no previous value to diff against.
   observed.delete(key);
-  observed.set(key, windows.map(window => ({ ...window })));
+  const next = windows.map(window => ({ ...window }));
+  // Codex display eviction is not a new short observation. Retain notification history
+  // with its original clock until a real reading replaces it or account cleanup forgets it.
+  if (retainAbsentShortWindow && !next.some(window => window.window === "5h")) {
+    const short = previous?.find(window => window.window === "5h");
+    if (short) next.push({ ...short });
+  }
+  observed.set(key, next);
   if (observed.size > MAX_OBSERVED_SCOPES) {
     // Least-recently-observed first. Evicting only costs a re-baseline, never a duplicate
     // notification, because the claim ledger is separate — but a re-baseline DOES cost the

package/src/remote-control/crypto.ts

@@ -0,0 +1,442 @@
+import {
+  createCipheriv,
+  createDecipheriv,
+  createHash,
+  createPrivateKey,
+  createPublicKey,
+  diffieHellman,
+  generateKeyPairSync,
+  hkdfSync,
+  randomBytes,
+  sign,
+  verify,
+  type KeyObject,
+} from "node:crypto";
+import {
+  REMOTE_CONTROL_MAX_RELAY_PAYLOAD_BYTES,
+  REMOTE_CONTROL_PROTOCOL_VERSION,
+  isRemoteControlCommandProfile,
+  isRemoteControlUuid,
+  normalizeRemoteControlCapabilities,
+  remoteControlUuidBytes,
+  type RemoteControlCapability,
+  type RemoteControlClientHello,
+  type RemoteControlCommandProfile,
+  type RemoteControlHostHello,
+} from "./protocol";
+
+const HELLO_MAX_BYTES = 16 * 1024;
+const NONCE_BYTES = 32;
+const GCM_TAG_BYTES = 16;
+const COUNTER_BYTES = 8;
+const MAX_COUNTER = 0xffff_ffff_ffff_ffffn;
+const MAX_ENCRYPTED_PLAINTEXT_BYTES = REMOTE_CONTROL_MAX_RELAY_PAYLOAD_BYTES - GCM_TAG_BYTES - COUNTER_BYTES;
+const BASE64URL_PATTERN = /^[A-Za-z0-9_-]+$/;
+
+export interface RemoteControlIdentityKeyPair {
+  publicKey: string;
+  privateKey: string;
+}
+
+export interface CreateRemoteControlClientHandshakeOptions {
+  sessionId: string;
+  deviceId: string;
+  commandProfile: RemoteControlCommandProfile;
+  capabilities: readonly RemoteControlCapability[];
+  accountPrivateKey: string;
+}
+
+export interface AcceptRemoteControlClientHelloOptions {
+  expectedSessionId: string;
+  expectedDeviceId: string;
+  accountPublicKey: string;
+  devicePrivateKey: string;
+  allowedCapabilities: readonly RemoteControlCapability[];
+}
+
+function encode(value: Uint8Array): string {
+  return Buffer.from(value).toString("base64url");
+}
+
+function decode(value: unknown, label: string, maxBytes: number): Buffer {
+  if (typeof value !== "string" || !BASE64URL_PATTERN.test(value) || value.length > Math.ceil(maxBytes * 4 / 3) + 4) {
+    throw new Error(`invalid ${label}`);
+  }
+  const decoded = Buffer.from(value, "base64url");
+  if (decoded.byteLength === 0 || decoded.byteLength > maxBytes || encode(decoded) !== value) throw new Error(`invalid ${label}`);
+  return decoded;
+}
+
+function privateSigningKey(value: string): KeyObject {
+  const key = createPrivateKey({ key: decode(value, "remote control private key", 256), format: "der", type: "pkcs8" });
+  if (key.asymmetricKeyType !== "ed25519") throw new Error("remote control private key must be Ed25519");
+  return key;
+}
+
+function publicSigningKey(value: string): KeyObject {
+  const key = createPublicKey({ key: decode(value, "remote control public key", 256), format: "der", type: "spki" });
+  if (key.asymmetricKeyType !== "ed25519") throw new Error("remote control public key must be Ed25519");
+  return key;
+}
+
+function publicEphemeralKey(value: string): KeyObject {
+  const key = createPublicKey({ key: decode(value, "remote control ephemeral key", 256), format: "der", type: "spki" });
+  if (key.asymmetricKeyType !== "ec" || key.asymmetricKeyDetails?.namedCurve !== "prime256v1") {
+    throw new Error("remote control ephemeral key must use P-256");
+  }
+  return key;
+}
+
+function lengthPrefixed(value: Uint8Array): Buffer {
+  if (value.byteLength > 0xffff) throw new Error("remote control transcript field is too large");
+  const length = Buffer.alloc(2);
+  length.writeUInt16BE(value.byteLength);
+  return Buffer.concat([length, Buffer.from(value)]);
+}
+
+function capabilityTranscript(capabilities: readonly RemoteControlCapability[]): Buffer {
+  const normalized = normalizeRemoteControlCapabilities([...capabilities]);
+  return Buffer.concat([
+    Buffer.from([normalized.length]),
+    ...normalized.map(capability => lengthPrefixed(Buffer.from(capability, "utf8"))),
+  ]);
+}
+
+function clientTranscript(hello: Omit<RemoteControlClientHello, "signature">): Buffer {
+  return Buffer.concat([
+    Buffer.from("opencodex-remote-control-client-v1\0", "utf8"),
+    Buffer.from([hello.version]),
+    Buffer.from(remoteControlUuidBytes(hello.sessionId)),
+    Buffer.from(remoteControlUuidBytes(hello.deviceId)),
+    lengthPrefixed(Buffer.from(hello.commandProfile, "utf8")),
+    capabilityTranscript(hello.capabilities),
+    lengthPrefixed(decode(hello.ephemeralPublicKey, "remote control ephemeral key", 256)),
+    decode(hello.nonce, "remote control client nonce", NONCE_BYTES),
+  ]);
+}
+
+function hostTranscript(
+  client: Buffer,
+  hello: Omit<RemoteControlHostHello, "signature">,
+): Buffer {
+  return Buffer.concat([
+    Buffer.from("opencodex-remote-control-host-v1\0", "utf8"),
+    createHash("sha256").update(client).digest(),
+    capabilityTranscript(hello.capabilities),
+    lengthPrefixed(decode(hello.ephemeralPublicKey, "remote control ephemeral key", 256)),
+    decode(hello.nonce, "remote control host nonce", NONCE_BYTES),
+  ]);
+}
+
+function parseJsonObject(value: Uint8Array, label: string): Record<string, unknown> {
+  if (!(value instanceof Uint8Array) || value.byteLength === 0 || value.byteLength > HELLO_MAX_BYTES) {
+    throw new Error(`invalid ${label}`);
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(value));
+  } catch {
+    throw new Error(`invalid ${label}`);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error(`invalid ${label}`);
+  return parsed as Record<string, unknown>;
+}
+
+function validateCommonHello(raw: Record<string, unknown>, label: string): {
+  sessionId: string;
+  deviceId: string;
+  capabilities: RemoteControlCapability[];
+  ephemeralPublicKey: string;
+  nonce: string;
+  signature: string;
+} {
+  if (raw.version !== REMOTE_CONTROL_PROTOCOL_VERSION) throw new Error(`unsupported ${label} version`);
+  if (!isRemoteControlUuid(raw.sessionId) || !isRemoteControlUuid(raw.deviceId)) throw new Error(`invalid ${label} identity`);
+  const capabilities = normalizeRemoteControlCapabilities(raw.capabilities);
+  if (typeof raw.ephemeralPublicKey !== "string" || typeof raw.nonce !== "string" || typeof raw.signature !== "string") {
+    throw new Error(`invalid ${label} cryptographic fields`);
+  }
+  const ephemeralPublicKey = raw.ephemeralPublicKey;
+  const encodedNonce = raw.nonce;
+  const encodedSignature = raw.signature;
+  decode(ephemeralPublicKey, `${label} ephemeral key`, 256);
+  const nonce = decode(encodedNonce, `${label} nonce`, NONCE_BYTES);
+  if (nonce.byteLength !== NONCE_BYTES) throw new Error(`invalid ${label} nonce`);
+  const signature = decode(encodedSignature, `${label} signature`, 128);
+  if (signature.byteLength !== 64) throw new Error(`invalid ${label} signature`);
+  return {
+    sessionId: raw.sessionId,
+    deviceId: raw.deviceId,
+    capabilities,
+    ephemeralPublicKey,
+    nonce: encodedNonce,
+    signature: encodedSignature,
+  };
+}
+
+export function parseRemoteControlClientHello(value: Uint8Array): RemoteControlClientHello {
+  const raw = parseJsonObject(value, "remote control client hello");
+  const common = validateCommonHello(raw, "remote control client hello");
+  if (!isRemoteControlCommandProfile(raw.commandProfile)) throw new Error("invalid remote control command profile");
+  return {
+    version: REMOTE_CONTROL_PROTOCOL_VERSION,
+    ...common,
+    commandProfile: raw.commandProfile,
+  };
+}
+
+export function parseRemoteControlHostHello(value: Uint8Array): RemoteControlHostHello {
+  const raw = parseJsonObject(value, "remote control host hello");
+  return { version: REMOTE_CONTROL_PROTOCOL_VERSION, ...validateCommonHello(raw, "remote control host hello") };
+}
+
+export function serializeRemoteControlHello(value: RemoteControlClientHello | RemoteControlHostHello): Uint8Array {
+  const encoded = new TextEncoder().encode(JSON.stringify(value));
+  if (encoded.byteLength > HELLO_MAX_BYTES) throw new Error("remote control hello is too large");
+  return encoded;
+}
+
+export function generateRemoteControlIdentityKeyPair(): RemoteControlIdentityKeyPair {
+  const pair = generateKeyPairSync("ed25519");
+  return {
+    publicKey: encode(pair.publicKey.export({ format: "der", type: "spki" })),
+    privateKey: encode(pair.privateKey.export({ format: "der", type: "pkcs8" })),
+  };
+}
+
+function nonce(prefix: Buffer, counter: bigint): Buffer {
+  const result = Buffer.alloc(12);
+  prefix.copy(result, 0);
+  result.writeBigUInt64BE(counter, 4);
+  return result;
+}
+
+function frameAad(sessionId: string, direction: 0 | 1, counter: bigint): Buffer {
+  const counterBytes = Buffer.alloc(COUNTER_BYTES);
+  counterBytes.writeBigUInt64BE(counter);
+  return Buffer.concat([
+    Buffer.from("opencodex-remote-control-frame-v1\0", "utf8"),
+    Buffer.from(remoteControlUuidBytes(sessionId)),
+    Buffer.from([direction]),
+    counterBytes,
+  ]);
+}
+
+export class RemoteControlCipher {
+  private sendCounter = 0n;
+  private receiveCounter = 0n;
+  private destroyed = false;
+
+  constructor(
+    private readonly sessionId: string,
+    private readonly sendDirection: 0 | 1,
+    private readonly sendKey: Buffer,
+    private readonly receiveKey: Buffer,
+    private readonly sendNoncePrefix: Buffer,
+    private readonly receiveNoncePrefix: Buffer,
+  ) {}
+
+  encrypt(value: Uint8Array): Uint8Array {
+    if (this.destroyed) throw new Error("remote control cipher is closed");
+    if (!(value instanceof Uint8Array) || value.byteLength > MAX_ENCRYPTED_PLAINTEXT_BYTES) {
+      throw new Error("remote control encrypted payload is too large");
+    }
+    if (this.sendCounter > MAX_COUNTER) throw new Error("remote control send counter exhausted");
+    const counter = this.sendCounter;
+    const cipher = createCipheriv("aes-256-gcm", this.sendKey, nonce(this.sendNoncePrefix, counter), { authTagLength: GCM_TAG_BYTES });
+    cipher.setAAD(frameAad(this.sessionId, this.sendDirection, counter));
+    const ciphertext = Buffer.concat([cipher.update(value), cipher.final()]);
+    const counterBytes = Buffer.alloc(COUNTER_BYTES);
+    counterBytes.writeBigUInt64BE(counter);
+    this.sendCounter += 1n;
+    return Buffer.concat([counterBytes, ciphertext, cipher.getAuthTag()]);
+  }
+
+  decrypt(value: Uint8Array): Uint8Array {
+    if (this.destroyed) throw new Error("remote control cipher is closed");
+    if (
+      !(value instanceof Uint8Array)
+      || value.byteLength < COUNTER_BYTES + GCM_TAG_BYTES
+      || value.byteLength > REMOTE_CONTROL_MAX_RELAY_PAYLOAD_BYTES
+    ) throw new Error("invalid remote control encrypted frame");
+    const bytes = Buffer.from(value);
+    const counter = bytes.readBigUInt64BE(0);
+    if (counter !== this.receiveCounter) throw new Error("replayed or out-of-order remote control frame");
+    const ciphertextEnd = bytes.byteLength - GCM_TAG_BYTES;
+    const decipher = createDecipheriv(
+      "aes-256-gcm",
+      this.receiveKey,
+      nonce(this.receiveNoncePrefix, counter),
+      { authTagLength: GCM_TAG_BYTES },
+    );
+    decipher.setAAD(frameAad(this.sessionId, this.sendDirection === 0 ? 1 : 0, counter));
+    decipher.setAuthTag(bytes.subarray(ciphertextEnd));
+    const plaintext = Buffer.concat([decipher.update(bytes.subarray(COUNTER_BYTES, ciphertextEnd)), decipher.final()]);
+    this.receiveCounter += 1n;
+    return plaintext;
+  }
+
+  destroy(): void {
+    if (this.destroyed) return;
+    this.destroyed = true;
+    this.sendKey.fill(0);
+    this.receiveKey.fill(0);
+    this.sendNoncePrefix.fill(0);
+    this.receiveNoncePrefix.fill(0);
+  }
+}
+
+function deriveCipher(options: {
+  sessionId: string;
+  shared: Buffer;
+  clientNonce: Buffer;
+  hostNonce: Buffer;
+  role: "client" | "host";
+}): RemoteControlCipher {
+  const salt = createHash("sha256").update(options.clientNonce).update(options.hostNonce).digest();
+  const expand = (info: string, length: number): Buffer => Buffer.from(hkdfSync(
+    "sha256",
+    options.shared,
+    salt,
+    Buffer.from(info, "utf8"),
+    length,
+  ));
+  const clientToHostKey = expand("opencodex remote control client to host key v1", 32);
+  const hostToClientKey = expand("opencodex remote control host to client key v1", 32);
+  const clientToHostNonce = expand("opencodex remote control client to host nonce v1", 4);
+  const hostToClientNonce = expand("opencodex remote control host to client nonce v1", 4);
+  options.shared.fill(0);
+  return options.role === "client"
+    ? new RemoteControlCipher(options.sessionId, 0, clientToHostKey, hostToClientKey, clientToHostNonce, hostToClientNonce)
+    : new RemoteControlCipher(options.sessionId, 1, hostToClientKey, clientToHostKey, hostToClientNonce, clientToHostNonce);
+}
+
+export class RemoteControlClientHandshake {
+  readonly hello: RemoteControlClientHello;
+  private completed = false;
+
+  private constructor(
+    hello: RemoteControlClientHello,
+    private readonly ephemeralPrivateKey: KeyObject,
+    private readonly transcript: Buffer,
+  ) {
+    this.hello = hello;
+  }
+
+  static create(options: CreateRemoteControlClientHandshakeOptions): RemoteControlClientHandshake {
+    if (!isRemoteControlUuid(options.sessionId) || !isRemoteControlUuid(options.deviceId)) {
+      throw new Error("invalid remote control handshake identity");
+    }
+    if (!isRemoteControlCommandProfile(options.commandProfile)) throw new Error("invalid remote control command profile");
+    const capabilities = normalizeRemoteControlCapabilities([...options.capabilities]);
+    const ephemeral = generateKeyPairSync("ec", { namedCurve: "prime256v1" });
+    const unsigned: Omit<RemoteControlClientHello, "signature"> = {
+      version: REMOTE_CONTROL_PROTOCOL_VERSION,
+      sessionId: options.sessionId,
+      deviceId: options.deviceId,
+      commandProfile: options.commandProfile,
+      capabilities,
+      ephemeralPublicKey: encode(ephemeral.publicKey.export({ format: "der", type: "spki" })),
+      nonce: encode(randomBytes(NONCE_BYTES)),
+    };
+    const transcript = clientTranscript(unsigned);
+    const hello: RemoteControlClientHello = {
+      ...unsigned,
+      signature: encode(sign(null, transcript, privateSigningKey(options.accountPrivateKey))),
+    };
+    return new RemoteControlClientHandshake(hello, ephemeral.privateKey, transcript);
+  }
+
+  complete(hostHello: RemoteControlHostHello, devicePublicKey: string): RemoteControlCipher {
+    if (this.completed) throw new Error("remote control client handshake already completed");
+    const validated = parseRemoteControlHostHello(serializeRemoteControlHello(hostHello));
+    if (validated.sessionId !== this.hello.sessionId || validated.deviceId !== this.hello.deviceId) {
+      throw new Error("remote control host hello identity mismatch");
+    }
+    const requested = new Set(this.hello.capabilities);
+    if (validated.capabilities.some(capability => !requested.has(capability))) {
+      throw new Error("remote control host granted an unrequested capability");
+    }
+    const unsigned: Omit<RemoteControlHostHello, "signature"> = {
+      version: validated.version,
+      sessionId: validated.sessionId,
+      deviceId: validated.deviceId,
+      capabilities: validated.capabilities,
+      ephemeralPublicKey: validated.ephemeralPublicKey,
+      nonce: validated.nonce,
+    };
+    if (!verify(
+      null,
+      hostTranscript(this.transcript, unsigned),
+      publicSigningKey(devicePublicKey),
+      decode(validated.signature, "remote control host signature", 128),
+    )) throw new Error("remote control host identity verification failed");
+    const cipher = deriveCipher({
+      sessionId: this.hello.sessionId,
+      shared: Buffer.from(diffieHellman({
+        privateKey: this.ephemeralPrivateKey,
+        publicKey: publicEphemeralKey(validated.ephemeralPublicKey),
+      })),
+      clientNonce: decode(this.hello.nonce, "remote control client nonce", NONCE_BYTES),
+      hostNonce: decode(validated.nonce, "remote control host nonce", NONCE_BYTES),
+      role: "client",
+    });
+    this.completed = true;
+    return cipher;
+  }
+}
+
+export function acceptRemoteControlClientHello(
+  clientHello: RemoteControlClientHello,
+  options: AcceptRemoteControlClientHelloOptions,
+): { hello: RemoteControlHostHello; cipher: RemoteControlCipher } {
+  const validated = parseRemoteControlClientHello(serializeRemoteControlHello(clientHello));
+  if (validated.sessionId !== options.expectedSessionId || validated.deviceId !== options.expectedDeviceId) {
+    throw new Error("remote control client hello identity mismatch");
+  }
+  const allowed = new Set(normalizeRemoteControlCapabilities([...options.allowedCapabilities]));
+  const capabilities = validated.capabilities.filter(capability => allowed.has(capability));
+  const unsignedClient: Omit<RemoteControlClientHello, "signature"> = {
+    version: validated.version,
+    sessionId: validated.sessionId,
+    deviceId: validated.deviceId,
+    commandProfile: validated.commandProfile,
+    capabilities: validated.capabilities,
+    ephemeralPublicKey: validated.ephemeralPublicKey,
+    nonce: validated.nonce,
+  };
+  const transcript = clientTranscript(unsignedClient);
+  if (!verify(
+    null,
+    transcript,
+    publicSigningKey(options.accountPublicKey),
+    decode(validated.signature, "remote control client signature", 128),
+  )) throw new Error("remote control account identity verification failed");
+
+  const ephemeral = generateKeyPairSync("ec", { namedCurve: "prime256v1" });
+  const unsignedHost: Omit<RemoteControlHostHello, "signature"> = {
+    version: REMOTE_CONTROL_PROTOCOL_VERSION,
+    sessionId: validated.sessionId,
+    deviceId: validated.deviceId,
+    capabilities,
+    ephemeralPublicKey: encode(ephemeral.publicKey.export({ format: "der", type: "spki" })),
+    nonce: encode(randomBytes(NONCE_BYTES)),
+  };
+  const hello: RemoteControlHostHello = {
+    ...unsignedHost,
+    signature: encode(sign(null, hostTranscript(transcript, unsignedHost), privateSigningKey(options.devicePrivateKey))),
+  };
+  return {
+    hello,
+    cipher: deriveCipher({
+      sessionId: validated.sessionId,
+      shared: Buffer.from(diffieHellman({
+        privateKey: ephemeral.privateKey,
+        publicKey: publicEphemeralKey(validated.ephemeralPublicKey),
+      })),
+      clientNonce: decode(validated.nonce, "remote control client nonce", NONCE_BYTES),
+      hostNonce: decode(hello.nonce, "remote control host nonce", NONCE_BYTES),
+      role: "host",
+    }),
+  };
+}