harness-mix 0.1.0

package/src/native-ui/desktop-control/src/cdp-client.ts

@@ -0,0 +1,347 @@
+export interface CdpTarget {
+  id: string;
+  type: string;
+  title: string;
+  url: string;
+  webSocketDebuggerUrl: string;
+}
+
+export interface CdpBrowserVersion {
+  browser: string;
+  protocolVersion: string;
+  webSocketDebuggerUrl: string;
+}
+
+export interface CdpFetchResponse {
+  ok: boolean;
+  status: number;
+  json(): Promise<unknown>;
+}
+
+export type CdpFetch = (url: string) => Promise<CdpFetchResponse>;
+
+interface CdpSocketEvent {
+  data?: unknown;
+}
+
+interface CdpSocket {
+  addEventListener(
+    type: "open" | "message" | "error" | "close",
+    listener: (event: CdpSocketEvent) => void,
+  ): void;
+  removeEventListener(
+    type: "open" | "message" | "error" | "close",
+    listener: (event: CdpSocketEvent) => void,
+  ): void;
+  send(data: string): void;
+  close(): void;
+}
+
+export type CdpSocketFactory = (url: string) => CdpSocket;
+
+export interface CdpClientOptions {
+  commandTimeoutMs?: number;
+  connectTimeoutMs?: number;
+  socketFactory?: CdpSocketFactory;
+}
+
+export type CdpEventListener = (params: unknown, sessionId: string | undefined) => void;
+
+interface PendingCommand {
+  resolve(value: unknown): void;
+  reject(error: Error): void;
+  timeout: NodeJS.Timeout;
+}
+
+interface CdpResponse {
+  id: number;
+  result?: unknown;
+  error?: {
+    code?: number;
+    message?: string;
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function nonEmptyString(value: unknown, field: string): string {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`CDP target '${field}' must be non-empty text`);
+  }
+  return value;
+}
+
+function loopbackUrl(value: string, protocols: readonly string[]): URL {
+  const url = new URL(value);
+  if (!protocols.includes(url.protocol)) {
+    throw new Error(`CDP endpoint must use ${protocols.join(" or ")}`);
+  }
+  if (!["127.0.0.1", "localhost", "[::1]"].includes(url.hostname)) {
+    throw new Error("CDP endpoint must use a loopback host");
+  }
+  return url;
+}
+
+function parseTarget(value: unknown): CdpTarget {
+  if (!isRecord(value)) throw new Error("CDP target must be an object");
+  const target = {
+    id: nonEmptyString(value.id, "id"),
+    type: nonEmptyString(value.type, "type"),
+    title: typeof value.title === "string" ? value.title : "",
+    url: nonEmptyString(value.url, "url"),
+    webSocketDebuggerUrl: nonEmptyString(value.webSocketDebuggerUrl, "webSocketDebuggerUrl"),
+  };
+  loopbackUrl(target.webSocketDebuggerUrl, ["ws:", "wss:"]);
+  return target;
+}
+
+function defaultFetch(url: string): Promise<CdpFetchResponse> {
+  return fetch(url);
+}
+
+function defaultSocketFactory(url: string): CdpSocket {
+  return new WebSocket(url) as unknown as CdpSocket;
+}
+
+function messageText(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (value instanceof ArrayBuffer) return new TextDecoder().decode(value);
+  if (ArrayBuffer.isView(value)) {
+    return new TextDecoder().decode(
+      new Uint8Array(value.buffer, value.byteOffset, value.byteLength),
+    );
+  }
+  throw new Error("CDP WebSocket returned a non-text message");
+}
+
+function parseResponse(value: unknown): CdpResponse | null {
+  if (!isRecord(value) || typeof value.id !== "number") return null;
+  const response: CdpResponse = { id: value.id };
+  if ("result" in value) response.result = value.result;
+  if (isRecord(value.error)) {
+    response.error = {
+      ...(typeof value.error.code === "number" ? { code: value.error.code } : {}),
+      ...(typeof value.error.message === "string" ? { message: value.error.message } : {}),
+    };
+  }
+  return response;
+}
+
+export async function getCdpBrowserVersion(
+  endpoint: string,
+  fetchImpl: CdpFetch = defaultFetch,
+): Promise<CdpBrowserVersion> {
+  const baseUrl = loopbackUrl(endpoint, ["http:", "https:"]);
+  const response = await fetchImpl(new URL("/json/version", baseUrl).toString());
+  if (!response.ok) throw new Error(`CDP version discovery failed with HTTP ${response.status}`);
+  const value = await response.json();
+  if (!isRecord(value)) throw new Error("CDP version discovery did not return an object");
+  const version = {
+    browser: nonEmptyString(value.Browser, "Browser"),
+    protocolVersion: nonEmptyString(value["Protocol-Version"], "Protocol-Version"),
+    webSocketDebuggerUrl: nonEmptyString(value.webSocketDebuggerUrl, "webSocketDebuggerUrl"),
+  };
+  loopbackUrl(version.webSocketDebuggerUrl, ["ws:", "wss:"]);
+  return version;
+}
+
+export async function listCdpTargets(
+  endpoint: string,
+  fetchImpl: CdpFetch = defaultFetch,
+): Promise<CdpTarget[]> {
+  const baseUrl = loopbackUrl(endpoint, ["http:", "https:"]);
+  const targetsUrl = new URL("/json/list", baseUrl).toString();
+  const response = await fetchImpl(targetsUrl);
+  if (!response.ok) throw new Error(`CDP target discovery failed with HTTP ${response.status}`);
+  const value = await response.json();
+  if (!Array.isArray(value)) throw new Error("CDP target discovery did not return an array");
+  return value.map(parseTarget);
+}
+
+export async function waitForRendererTarget(
+  endpoint: string,
+  options: {
+    fetchImpl?: CdpFetch;
+    pollIntervalMs?: number;
+    timeoutMs?: number;
+  } = {},
+): Promise<CdpTarget> {
+  const fetchImpl = options.fetchImpl ?? defaultFetch;
+  const pollIntervalMs = options.pollIntervalMs ?? 250;
+  const timeoutMs = options.timeoutMs ?? 30_000;
+  const deadline = Date.now() + timeoutMs;
+  let lastError: unknown;
+  while (Date.now() < deadline) {
+    try {
+      const targets = await listCdpTargets(endpoint, fetchImpl);
+      const renderer = targets.find(
+        (target) => target.type === "page" && target.url.startsWith("app://"),
+      );
+      if (renderer) return renderer;
+      lastError = new Error("CDP has no app:// page target");
+    } catch (error) {
+      lastError = error;
+    }
+    await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+  }
+  const detail = lastError instanceof Error ? `: ${lastError.message}` : "";
+  throw new Error(`Codex Renderer CDP target did not become ready${detail}`);
+}
+
+export class CdpClient {
+  readonly #commandTimeoutMs: number;
+  readonly #socket: CdpSocket;
+  #closed = false;
+  #nextId = 1;
+  #pending = new Map<number, PendingCommand>();
+  #listeners = new Map<string, Set<CdpEventListener>>();
+
+  private constructor(socket: CdpSocket, commandTimeoutMs: number) {
+    this.#socket = socket;
+    this.#commandTimeoutMs = commandTimeoutMs;
+    socket.addEventListener("message", (event) => this.#onMessage(event));
+    socket.addEventListener("error", () => this.#fail(new Error("CDP WebSocket failed")));
+    socket.addEventListener("close", () => this.#fail(new Error("CDP WebSocket closed")));
+  }
+
+  static async connect(url: string, options: CdpClientOptions = {}): Promise<CdpClient> {
+    loopbackUrl(url, ["ws:", "wss:"]);
+    const socketFactory = options.socketFactory ?? defaultSocketFactory;
+    const socket = socketFactory(url);
+    const connectTimeoutMs = options.connectTimeoutMs ?? 10_000;
+    await new Promise<void>((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        cleanup();
+        socket.close();
+        reject(new Error("CDP WebSocket connection timed out"));
+      }, connectTimeoutMs);
+      const onOpen = (): void => {
+        cleanup();
+        resolve();
+      };
+      const onError = (): void => {
+        cleanup();
+        reject(new Error("CDP WebSocket connection failed"));
+      };
+      const cleanup = (): void => {
+        clearTimeout(timeout);
+        socket.removeEventListener("open", onOpen);
+        socket.removeEventListener("error", onError);
+      };
+      socket.addEventListener("open", onOpen);
+      socket.addEventListener("error", onError);
+    });
+    return new CdpClient(socket, options.commandTimeoutMs ?? 10_000);
+  }
+
+  command(method: string, params: Record<string, unknown> = {}): Promise<unknown> {
+    return this.#send(method, params);
+  }
+
+  sessionCommand(
+    sessionId: string,
+    method: string,
+    params: Record<string, unknown> = {},
+  ): Promise<unknown> {
+    if (sessionId.length === 0) return Promise.reject(new Error("CDP session ID is required"));
+    return this.#send(method, params, sessionId);
+  }
+
+  on(method: string, listener: CdpEventListener): () => void {
+    const listeners = this.#listeners.get(method) ?? new Set();
+    listeners.add(listener);
+    this.#listeners.set(method, listeners);
+    return () => {
+      listeners.delete(listener);
+      if (listeners.size === 0) this.#listeners.delete(method);
+    };
+  }
+
+  #send(method: string, params: Record<string, unknown>, sessionId?: string): Promise<unknown> {
+    if (this.#closed) return Promise.reject(new Error("CDP client is closed"));
+    const id = this.#nextId++;
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.#pending.delete(id);
+        reject(new Error(`CDP command '${method}' timed out`));
+      }, this.#commandTimeoutMs);
+      this.#pending.set(id, { resolve, reject, timeout });
+      try {
+        this.#socket.send(
+          JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) }),
+        );
+      } catch (error) {
+        clearTimeout(timeout);
+        this.#pending.delete(id);
+        reject(error instanceof Error ? error : new Error(String(error)));
+      }
+    });
+  }
+
+  async evaluate<T>(expression: string): Promise<T> {
+    const response = await this.command("Runtime.evaluate", {
+      expression,
+      awaitPromise: true,
+      returnByValue: true,
+    });
+    if (!isRecord(response)) throw new Error("Runtime.evaluate returned an invalid result");
+    if (isRecord(response.exceptionDetails)) {
+      const text =
+        typeof response.exceptionDetails.text === "string"
+          ? response.exceptionDetails.text
+          : "Renderer evaluation failed";
+      throw new Error(text);
+    }
+    if (!isRecord(response.result) || !("value" in response.result)) {
+      throw new Error("Runtime.evaluate did not return a value");
+    }
+    return response.result.value as T;
+  }
+
+  close(): void {
+    if (this.#closed) return;
+    this.#closed = true;
+    this.#fail(new Error("CDP client closed"));
+    this.#listeners.clear();
+    this.#socket.close();
+  }
+
+  #onMessage(event: CdpSocketEvent): void {
+    try {
+      const value: unknown = JSON.parse(messageText(event.data));
+      const response = parseResponse(value);
+      if (!response) {
+        if (!isRecord(value) || typeof value.method !== "string") return;
+        const sessionId = typeof value.sessionId === "string" ? value.sessionId : undefined;
+        for (const listener of this.#listeners.get(value.method) ?? []) {
+          listener(value.params, sessionId);
+        }
+        return;
+      }
+      const pending = this.#pending.get(response.id);
+      if (!pending) return;
+      clearTimeout(pending.timeout);
+      this.#pending.delete(response.id);
+      if (response.error) {
+        const code = response.error.code === undefined ? "unknown" : String(response.error.code);
+        pending.reject(
+          new Error(response.error.message ?? `CDP command failed with error ${code}`),
+        );
+      } else {
+        pending.resolve(response.result);
+      }
+    } catch (error) {
+      this.#fail(error instanceof Error ? error : new Error(String(error)));
+    }
+  }
+
+  #fail(error: Error): void {
+    for (const pending of this.#pending.values()) {
+      clearTimeout(pending.timeout);
+      pending.reject(error);
+    }
+    this.#pending.clear();
+  }
+}

package/src/native-ui/desktop-control/src/contract-audit.ts

@@ -0,0 +1,291 @@
+import { CdpClient, getCdpBrowserVersion, type CdpBrowserVersion } from "./cdp-client.js";
+import {
+  inspectElectronWebContents,
+  selectRendererWebContents,
+  waitForInspectorTarget,
+  type ElectronRendererSummary,
+} from "./renderer-control-session.js";
+
+export const DESKTOP_CONTRACT_AUDIT_SCHEMA_VERSION = 1 as const;
+
+export type ContractAuditCardinalityState = "unique" | "missing" | "ambiguous" | "inactive";
+
+export interface RendererContractAuditInspection {
+  schemaVersion: 1;
+  composer: {
+    composerCount: number;
+    visibleComposerCount: number;
+    activeComposerCount: number;
+    modelCandidateCount: number;
+    verifiedModelCandidateCount: number;
+    permissionCandidateCount: number;
+    verifiedPermissionCandidateCount: number;
+    contextUsageCandidateCount: number;
+    verifiedContextUsageCandidateCount: number;
+    sendButtonCount: number;
+    trailingActionOwnerCount: number;
+  };
+  model: {
+    draftCount: number;
+    conversationCount: number;
+    missingCount: number;
+    ambiguousCount: number;
+  };
+  settings: {
+    headerCount: number;
+    visibleHeaderCount: number;
+    insertionPointCount: number;
+  };
+  sidebar: {
+    rowCount: number;
+    titleOwnerCount: number;
+    resolvedThreadCount: number;
+    ambiguousThreadCount: number;
+  };
+  transcript: {
+    turnCount: number;
+    itemNodeCount: number;
+    identifiedItemCount: number;
+    textBodyCount: number;
+    textBodyOwnerCount: number;
+  };
+  fork: {
+    annotatedResponseCount: number;
+    candidateButtonCount: number;
+    verifiedButtonCount: number;
+  };
+  production: {
+    bindingPresent: boolean;
+    adapterState: "installing" | "ready" | "unsupported" | "absent";
+    adapterReason: string;
+    titlePolicyState: "ready" | "absent" | "unknown";
+    draftPrewarmPolicyState: "ready" | "absent" | "unknown";
+  };
+}
+
+export interface DesktopContractAuditObservation {
+  schemaVersion: typeof DESKTOP_CONTRACT_AUDIT_SCHEMA_VERSION;
+  browser: {
+    browser: string;
+    protocolVersion: string;
+  };
+  renderer: ElectronRendererSummary;
+  contracts: RendererContractAuditInspection;
+}
+
+export interface InspectDesktopContractsOptions {
+  endpoint: string;
+  inspectorEndpoint: string;
+  rendererAuditSource: string;
+  timeoutMs?: number;
+}
+
+interface RecordValue {
+  [key: string]: unknown;
+}
+
+function isRecord(value: unknown): value is RecordValue {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function strictKeys(value: RecordValue, expected: readonly string[], label: string): void {
+  const keys = Object.keys(value).toSorted();
+  const sortedExpected = [...expected].toSorted();
+  if (
+    keys.length !== sortedExpected.length ||
+    keys.some((key, index) => key !== sortedExpected[index])
+  ) {
+    throw new Error(`${label} contains unknown or missing fields`);
+  }
+}
+
+function integer(value: unknown, label: string): number {
+  if (!Number.isInteger(value) || (value as number) < 0) {
+    throw new Error(`${label} must be a non-negative integer`);
+  }
+  return value as number;
+}
+
+function integerRecord<T extends readonly string[]>(
+  value: unknown,
+  keys: T,
+  label: string,
+): { [K in T[number]]: number } {
+  if (!isRecord(value)) throw new Error(`${label} must be an object`);
+  strictKeys(value, keys, label);
+  return Object.fromEntries(keys.map((key) => [key, integer(value[key], `${label}.${key}`)])) as {
+    [K in T[number]]: number;
+  };
+}
+
+export function validateRendererContractAuditInspection(
+  value: unknown,
+): RendererContractAuditInspection {
+  if (!isRecord(value)) throw new Error("Renderer contract audit must be an object");
+  strictKeys(
+    value,
+    [
+      "schemaVersion",
+      "composer",
+      "model",
+      "settings",
+      "sidebar",
+      "transcript",
+      "fork",
+      "production",
+    ],
+    "Renderer contract audit",
+  );
+  if (value.schemaVersion !== 1) throw new Error("Renderer contract audit schema is unsupported");
+  const production = value.production;
+  if (!isRecord(production)) throw new Error("Renderer contract audit production state is invalid");
+  strictKeys(
+    production,
+    [
+      "bindingPresent",
+      "adapterState",
+      "adapterReason",
+      "titlePolicyState",
+      "draftPrewarmPolicyState",
+    ],
+    "Renderer contract audit production state",
+  );
+  if (
+    typeof production.bindingPresent !== "boolean" ||
+    !["installing", "ready", "unsupported", "absent"].includes(String(production.adapterState)) ||
+    typeof production.adapterReason !== "string" ||
+    production.adapterReason.length > 64 ||
+    !["ready", "absent", "unknown"].includes(String(production.titlePolicyState)) ||
+    !["ready", "absent", "unknown"].includes(String(production.draftPrewarmPolicyState))
+  ) {
+    throw new Error("Renderer contract audit production state is invalid");
+  }
+  return {
+    schemaVersion: 1,
+    composer: integerRecord(
+      value.composer,
+      [
+        "composerCount",
+        "visibleComposerCount",
+        "activeComposerCount",
+        "modelCandidateCount",
+        "verifiedModelCandidateCount",
+        "permissionCandidateCount",
+        "verifiedPermissionCandidateCount",
+        "contextUsageCandidateCount",
+        "verifiedContextUsageCandidateCount",
+        "sendButtonCount",
+        "trailingActionOwnerCount",
+      ] as const,
+      "Renderer composer contract",
+    ),
+    model: integerRecord(
+      value.model,
+      ["draftCount", "conversationCount", "missingCount", "ambiguousCount"] as const,
+      "Renderer model contract",
+    ),
+    settings: integerRecord(
+      value.settings,
+      ["headerCount", "visibleHeaderCount", "insertionPointCount"] as const,
+      "Renderer settings contract",
+    ),
+    sidebar: integerRecord(
+      value.sidebar,
+      ["rowCount", "titleOwnerCount", "resolvedThreadCount", "ambiguousThreadCount"] as const,
+      "Renderer sidebar contract",
+    ),
+    transcript: integerRecord(
+      value.transcript,
+      [
+        "turnCount",
+        "itemNodeCount",
+        "identifiedItemCount",
+        "textBodyCount",
+        "textBodyOwnerCount",
+      ] as const,
+      "Renderer transcript contract",
+    ),
+    fork: integerRecord(
+      value.fork,
+      ["annotatedResponseCount", "candidateButtonCount", "verifiedButtonCount"] as const,
+      "Renderer fork contract",
+    ),
+    production: {
+      bindingPresent: production.bindingPresent,
+      adapterState:
+        production.adapterState as RendererContractAuditInspection["production"]["adapterState"],
+      adapterReason: production.adapterReason,
+      titlePolicyState:
+        production.titlePolicyState as RendererContractAuditInspection["production"]["titlePolicyState"],
+      draftPrewarmPolicyState:
+        production.draftPrewarmPolicyState as RendererContractAuditInspection["production"]["draftPrewarmPolicyState"],
+    },
+  };
+}
+
+const electronModuleExpression = `(() => {
+  const mainModule = process.mainModule;
+  if (mainModule != null && typeof mainModule.require === 'function') {
+    return mainModule.require('electron');
+  }
+  const { createRequire } = process.getBuiltinModule('module');
+  return createRequire(process.execPath)('electron');
+})()`;
+
+async function executeReadOnlyAudit(
+  inspector: Pick<CdpClient, "evaluate">,
+  rendererWebContentsId: number,
+  source: string,
+): Promise<unknown> {
+  return inspector.evaluate<unknown>(`(async () => {
+    const { webContents } = ${electronModuleExpression};
+    const contents = webContents.fromId(${rendererWebContentsId});
+    if (contents == null || contents.isDestroyed()) throw new Error('Renderer webContents is unavailable');
+    return contents.executeJavaScript(${JSON.stringify(`(() => {
+      const previous = window.__codexhostContractAuditV1;
+      ${source}
+      try {
+        const audit = window.__codexhostContractAuditV1;
+        if (audit == null || typeof audit.inspect !== 'function') {
+          throw new Error('Renderer contract audit entry is unavailable');
+        }
+        return audit.inspect();
+      } finally {
+        if (previous === undefined) delete window.__codexhostContractAuditV1;
+        else window.__codexhostContractAuditV1 = previous;
+      }
+    })()`)}, true);
+  })()`);
+}
+
+function browserIdentity(version: CdpBrowserVersion): DesktopContractAuditObservation["browser"] {
+  return { browser: version.browser, protocolVersion: version.protocolVersion };
+}
+
+export async function inspectDesktopContracts(
+  options: InspectDesktopContractsOptions,
+): Promise<DesktopContractAuditObservation> {
+  const timeoutMs = options.timeoutMs ?? 30_000;
+  const [browser, inspectorTarget] = await Promise.all([
+    getCdpBrowserVersion(options.endpoint),
+    waitForInspectorTarget(options.inspectorEndpoint, { timeoutMs }),
+  ]);
+  const inspector = await CdpClient.connect(inspectorTarget.webSocketDebuggerUrl);
+  try {
+    await inspector.command("Runtime.enable");
+    const inventory = await inspectElectronWebContents(inspector);
+    const renderer = selectRendererWebContents(inventory);
+    if (!renderer) throw new Error("Contract audit did not find a primary Renderer");
+    const contracts = validateRendererContractAuditInspection(
+      await executeReadOnlyAudit(inspector, renderer.id, options.rendererAuditSource),
+    );
+    return {
+      schemaVersion: DESKTOP_CONTRACT_AUDIT_SCHEMA_VERSION,
+      browser: browserIdentity(browser),
+      renderer,
+      contracts,
+    };
+  } finally {
+    inspector.close();
+  }
+}