harness-mix 0.1.0

package/src/native-ui/desktop-control/src/controller-attachment-server.ts

@@ -0,0 +1,93 @@
+import { createServer, type Server, type Socket } from "node:net";
+
+const MAX_REQUEST_BYTES = 96;
+
+export interface ControllerAttachmentServer {
+  close(): Promise<void>;
+}
+
+export interface StartControllerAttachmentServerOptions {
+  port: number;
+  nonce: string;
+  attach(): Promise<void>;
+}
+
+function validPort(value: number): boolean {
+  return Number.isInteger(value) && value >= 1 && value <= 65_535;
+}
+
+function validNonce(value: string): boolean {
+  return /^[0-9a-f]{32}$/.test(value);
+}
+
+function closeServer(server: Server): Promise<void> {
+  return new Promise((resolve, reject) => {
+    server.close((error) => {
+      if (error) reject(error);
+      else resolve();
+    });
+  });
+}
+
+function respond(socket: Socket, value: "ready" | "rejected" | "failed"): void {
+  socket.end(`${value}\n`);
+}
+
+export async function startControllerAttachmentServer(
+  options: StartControllerAttachmentServerOptions,
+): Promise<ControllerAttachmentServer> {
+  if (!validPort(options.port)) throw new Error("attachment port must be a valid TCP port");
+  if (!validNonce(options.nonce)) {
+    throw new Error("attachment nonce must be 32 lowercase hexadecimal characters");
+  }
+
+  const sockets = new Set<Socket>();
+  const server = createServer((socket) => {
+    sockets.add(socket);
+    socket.once("close", () => sockets.delete(socket));
+    socket.setEncoding("utf8");
+    socket.setTimeout(5_000, () => socket.destroy());
+    let request = "";
+    let handled = false;
+    socket.on("data", (chunk: string) => {
+      if (handled) return;
+      request += chunk;
+      if (request.length > MAX_REQUEST_BYTES) {
+        handled = true;
+        respond(socket, "rejected");
+        return;
+      }
+      const newline = request.indexOf("\n");
+      if (newline < 0) return;
+      handled = true;
+      const line = request.slice(0, newline).replace(/\r$/, "");
+      if (line === `ATTACH ${options.nonce}`) {
+        void options.attach().then(
+          () => respond(socket, "ready"),
+          () => respond(socket, "failed"),
+        );
+        return;
+      }
+      respond(socket, "rejected");
+    });
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    const onError = (error: Error): void => reject(error);
+    server.once("error", onError);
+    server.listen(options.port, "127.0.0.1", () => {
+      server.off("error", onError);
+      resolve();
+    });
+  });
+
+  let closed = false;
+  return {
+    async close() {
+      if (closed) return;
+      closed = true;
+      for (const socket of sockets) socket.destroy();
+      await closeServer(server);
+    },
+  };
+}

package/src/native-ui/desktop-control/src/index.ts

@@ -0,0 +1,91 @@
+import { WORKSPACE_CONTRACT_VERSION } from "@codexhost/shared-contracts";
+
+export {
+  CdpClient,
+  getCdpBrowserVersion,
+  listCdpTargets,
+  waitForRendererTarget,
+} from "./cdp-client.js";
+export type {
+  CdpBrowserVersion,
+  CdpClientOptions,
+  CdpEventListener,
+  CdpFetch,
+  CdpFetchResponse,
+  CdpSocketFactory,
+  CdpTarget,
+} from "./cdp-client.js";
+export {
+  DESKTOP_CONTRACT_AUDIT_SCHEMA_VERSION,
+  inspectDesktopContracts,
+  validateRendererContractAuditInspection,
+} from "./contract-audit.js";
+export type {
+  DesktopContractAuditObservation,
+  InspectDesktopContractsOptions,
+  RendererContractAuditInspection,
+} from "./contract-audit.js";
+export { inspectRendererDom, validateRendererDomInspection } from "./renderer-dom.js";
+export {
+  createRendererCdpControlSession,
+  installRendererCdpControlSession,
+  selectPrimaryRendererTarget,
+} from "./renderer-cdp-control-session.js";
+export type {
+  InstallRendererCdpControlOptions,
+  ProductionRendererStatus as RendererCdpProductionStatus,
+  RendererCdpControlSession,
+  RendererCdpControlSnapshot,
+} from "./renderer-cdp-control-session.js";
+export {
+  activateElectronDesktop,
+  createRendererControlSession,
+  inspectElectronWebContents,
+  installRendererControlSession,
+  selectRendererWebContents,
+  waitForInspectorTarget,
+  waitForRendererTitlePolicyReady,
+} from "./renderer-control-session.js";
+export type {
+  ElectronRendererSummary,
+  InstallRendererControlOptions,
+  ProductionRendererStatus,
+  RendererControlSession,
+  RendererControlSnapshot,
+} from "./renderer-control-session.js";
+export type {
+  RendererDomInspection,
+  RendererDomNodeSummary,
+  RendererShadowRootSummary,
+} from "./renderer-dom.js";
+export {
+  installMainProcessTitlePolicy,
+  markRendererTitlePolicyReady,
+  readMainProcessTitlePolicyCounters,
+} from "./main-process-title-policy.js";
+export type {
+  MainProcessTitlePolicyCounters,
+  MainProcessTitlePolicyStatus,
+  RendererTitlePolicyReadiness,
+} from "./main-process-title-policy.js";
+export {
+  installRendererDraftPrewarmPolicy,
+  installRendererDraftPrewarmPolicyDirect,
+} from "./renderer-draft-prewarm-policy.js";
+export type { RendererDraftPrewarmPolicyStatus } from "./renderer-draft-prewarm-policy.js";
+
+export {
+  parseDesktopControllerArguments,
+  runDesktopController,
+  serializeDesktopControllerReadiness,
+} from "./production-controller.js";
+export type {
+  DesktopControllerDependencies,
+  DesktopControllerOptions,
+  DesktopControllerReadiness,
+} from "./production-controller.js";
+
+export const packageMetadata = {
+  name: "@codexhost/desktop-control",
+  contractVersion: WORKSPACE_CONTRACT_VERSION,
+} as const;

package/src/native-ui/desktop-control/src/main-process-title-policy.ts

@@ -0,0 +1,334 @@
+import type { CdpClient } from "./cdp-client.js";
+
+interface CdpCommander {
+  command(method: string, params?: Record<string, unknown>): Promise<unknown>;
+}
+
+interface RemoteObject {
+  objectId?: string;
+  value?: unknown;
+}
+
+interface RuntimeProperty {
+  name?: string;
+  value?: RemoteObject;
+}
+
+export interface MainProcessTitlePolicyStatus {
+  state: "ready";
+  reason: "ready";
+  requiresRendererReload: true;
+}
+
+export interface MainProcessTitlePolicyCounters {
+  codexTitleCalls: number;
+  piTitleSkips: number;
+  externalTitleSkips: number;
+  ambiguousTitleSkips: number;
+}
+
+export interface RendererTitlePolicyReadiness {
+  state: "ready";
+  reason: "owned-metadata-service";
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function resultRecord(value: unknown, command: string): Record<string, unknown> {
+  if (!isRecord(value)) throw new Error(`${command} returned an invalid result`);
+  if (isRecord(value.exceptionDetails)) {
+    const exception = value.exceptionDetails.exception;
+    const description = isRecord(exception) ? exception.description : null;
+    const text = value.exceptionDetails.text;
+    throw new Error(
+      typeof description === "string"
+        ? description
+        : typeof text === "string"
+          ? text
+          : `${command} failed`,
+    );
+  }
+  return value;
+}
+
+function remoteObjectId(value: unknown, label: string): string {
+  if (!isRecord(value) || typeof value.objectId !== "string") {
+    throw new Error(`${label} is unavailable`);
+  }
+  return value.objectId;
+}
+
+function properties(value: unknown, command: string): RuntimeProperty[] {
+  const result = resultRecord(value, command).result;
+  if (!Array.isArray(result)) throw new Error(`${command} returned invalid properties`);
+  return result.filter(isRecord) as RuntimeProperty[];
+}
+
+const ELECTRON_MODULE_EXPRESSION = `(() => {
+  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');
+})()`;
+
+const CONNECT_APP_HOST_CHANNEL = "codex_desktop:connect-app-host";
+const POLICY_STATE_SYMBOL = "codexhost.main-process-title-policy.v1";
+const SERVICE_OWNER_SYMBOL = "codexhost.main-process-title-policy.owner.v1";
+const RENDERER_READY_EXPRESSION =
+  "(() => { Object.defineProperty(window, '__codexhostMainProcessTitlePolicyV1', { configurable: true, value: { state: 'ready' } }); return 'ready'; })()";
+
+const INSTALL_POLICY_FUNCTION = `async function (rendererWebContentsId) {
+  const mainModule = process.mainModule;
+  const electron = mainModule != null && typeof mainModule.require === 'function'
+    ? mainModule.require('electron')
+    : process.getBuiltinModule('module').createRequire(process.execPath)('electron');
+  const selected = electron.webContents.fromId(rendererWebContentsId);
+  if (selected == null || selected.isDestroyed() || selected.getType() !== 'window') {
+    throw new Error('Owned Renderer unavailable for title policy');
+  }
+
+  const context = this(selected);
+  if (context == null || typeof context.createAppHost !== 'function') {
+    throw new Error('WindowContext unavailable for title policy');
+  }
+  const stateSymbol = Symbol.for(${JSON.stringify(POLICY_STATE_SYMBOL)});
+  const ownerSymbol = Symbol.for(${JSON.stringify(SERVICE_OWNER_SYMBOL)});
+  globalThis[stateSymbol]?.dispose?.();
+
+  const originalCreateAppHost = context.createAppHost;
+  const sampleHost = originalCreateAppHost.call(context, selected);
+  const sampleService = sampleHost?.services?.threadMetadataGeneration;
+  const servicePrototype = sampleService == null ? null : Object.getPrototypeOf(sampleService);
+  const originalGenerateTitle = servicePrototype?.generateTitle;
+  if (
+    servicePrototype == null ||
+    typeof originalGenerateTitle !== 'function' ||
+    !Function.prototype.toString.call(originalGenerateTitle).includes('Failed to generate thread title')
+  ) {
+    throw new Error('ThreadMetadataGenerationService signature mismatch');
+  }
+  const counters = {
+    codexTitleCalls: 0,
+    piTitleSkips: 0,
+    externalTitleSkips: 0,
+    ambiguousTitleSkips: 0,
+  };
+  const ownedWebContentsIds = new Set();
+  const ownService = (service, contents) => {
+    const existingOwner = service[ownerSymbol];
+    if (existingOwner != null && existingOwner !== contents) {
+      throw new Error('Thread metadata service ownership mismatch');
+    }
+    if (existingOwner == null) {
+      Object.defineProperty(service, ownerSymbol, { value: contents });
+    }
+    ownedWebContentsIds.add(contents.id);
+  };
+  ownService(sampleService, selected);
+  const wrappedCreateAppHost = function (contents) {
+    const host = originalCreateAppHost.call(this, contents);
+    const service = host?.services?.threadMetadataGeneration;
+    if (service != null) ownService(service, contents);
+    return host;
+  };
+  const wrappedGenerateTitle = async function (params) {
+    const owner = this[ownerSymbol];
+    if (owner == null || owner.isDestroyed()) {
+      counters.ambiguousTitleSkips += 1;
+      return null;
+    }
+    let selection = null;
+    try {
+      selection = await owner.executeJavaScript(
+        "window.__codexhostRendererBindingProbeV1?.lockedSelection() ?? null",
+        true,
+      );
+    } catch {}
+    if (selection?.phase !== 'locked') {
+      counters.ambiguousTitleSkips += 1;
+      return null;
+    }
+    if (selection.agent === 'pi') {
+      counters.piTitleSkips += 1;
+      return null;
+    }
+    if (selection.agent !== 'codex') {
+      counters.externalTitleSkips += 1;
+      return null;
+    }
+    counters.codexTitleCalls += 1;
+    return originalGenerateTitle.call(this, params);
+  };
+
+  context.createAppHost = wrappedCreateAppHost;
+  servicePrototype.generateTitle = wrappedGenerateTitle;
+  const state = {
+    counters,
+    ownedWebContentsIds,
+    dispose() {
+      if (context.createAppHost === wrappedCreateAppHost) {
+        context.createAppHost = originalCreateAppHost;
+      }
+      if (servicePrototype.generateTitle === wrappedGenerateTitle) {
+        servicePrototype.generateTitle = originalGenerateTitle;
+      }
+      if (globalThis[stateSymbol] === state) delete globalThis[stateSymbol];
+    },
+  };
+  globalThis[stateSymbol] = state;
+  return {
+    state: 'ready',
+    reason: 'ready',
+    requiresRendererReload: true,
+  };
+}`;
+
+export async function installMainProcessTitlePolicy(
+  inspector: Pick<CdpClient, "command"> | CdpCommander,
+  rendererWebContentsId: number,
+): Promise<MainProcessTitlePolicyStatus> {
+  if (!Number.isInteger(rendererWebContentsId) || rendererWebContentsId <= 0) {
+    throw new Error("Renderer webContents ID must be a positive integer");
+  }
+  const listenerResponse = resultRecord(
+    await inspector.command("Runtime.evaluate", {
+      expression: `(${ELECTRON_MODULE_EXPRESSION}).ipcMain.listeners(${JSON.stringify(
+        CONNECT_APP_HOST_CHANNEL,
+      )})[0]`,
+    }),
+    "Runtime.evaluate",
+  );
+  const listener = listenerResponse.result;
+  const listenerId = remoteObjectId(listener, "connect-app-host listener");
+
+  const listenerProperties = resultRecord(
+    await inspector.command("Runtime.getProperties", { objectId: listenerId }),
+    "Runtime.getProperties",
+  );
+  const internalProperties = listenerProperties.internalProperties;
+  if (!Array.isArray(internalProperties)) {
+    throw new Error("connect-app-host listener scopes are unavailable");
+  }
+  const scopes = internalProperties.find(
+    (property) => isRecord(property) && property.name === "[[Scopes]]",
+  );
+  const scopesId = remoteObjectId(
+    isRecord(scopes) ? scopes.value : null,
+    "connect-app-host listener scopes",
+  );
+
+  const scopeProperties = properties(
+    await inspector.command("Runtime.getProperties", {
+      objectId: scopesId,
+      ownProperties: true,
+    }),
+    "Runtime.getProperties",
+  );
+  const localScope = scopeProperties.find((property) => property.name === "0");
+  const localScopeId = remoteObjectId(localScope?.value, "connect-app-host local scope");
+
+  const localProperties = properties(
+    await inspector.command("Runtime.getProperties", {
+      objectId: localScopeId,
+      ownProperties: true,
+    }),
+    "Runtime.getProperties",
+  );
+  const getContext = localProperties.find(
+    (property) => property.name === "f" && typeof property.value?.objectId === "string",
+  );
+  const getContextId = remoteObjectId(getContext?.value, "getContextForWebContents");
+
+  const installPromise = resultRecord(
+    await inspector.command("Runtime.callFunctionOn", {
+      objectId: getContextId,
+      functionDeclaration: INSTALL_POLICY_FUNCTION,
+      arguments: [{ value: rendererWebContentsId }],
+    }),
+    "Runtime.callFunctionOn",
+  );
+  const promiseObjectId = remoteObjectId(
+    installPromise.result,
+    "Main-process title policy installation promise",
+  );
+  const installResponse = resultRecord(
+    await inspector.command("Runtime.awaitPromise", {
+      promiseObjectId,
+      returnByValue: true,
+    }),
+    "Runtime.awaitPromise",
+  );
+  const remoteResult = installResponse.result;
+  const value = isRecord(remoteResult) ? remoteResult.value : null;
+  if (
+    !isRecord(value) ||
+    value.state !== "ready" ||
+    value.reason !== "ready" ||
+    value.requiresRendererReload !== true ||
+    Object.keys(value).length !== 3
+  ) {
+    throw new Error("Main-process title policy returned an invalid status");
+  }
+  return value as unknown as MainProcessTitlePolicyStatus;
+}
+
+export async function markRendererTitlePolicyReady(
+  inspector: Pick<CdpClient, "evaluate">,
+  rendererWebContentsId: number,
+): Promise<RendererTitlePolicyReadiness> {
+  if (!Number.isInteger(rendererWebContentsId) || rendererWebContentsId <= 0) {
+    throw new Error("Renderer webContents ID must be a positive integer");
+  }
+  const value = await inspector.evaluate<unknown>(`(async () => {
+    const state = globalThis[Symbol.for(${JSON.stringify(POLICY_STATE_SYMBOL)})];
+    if (state == null) throw new Error('Main-process title policy is unavailable');
+    const mainModule = process.mainModule;
+    const electron = mainModule != null && typeof mainModule.require === 'function'
+      ? mainModule.require('electron')
+      : process.getBuiltinModule('module').createRequire(process.execPath)('electron');
+    const selected = electron.webContents.fromId(${rendererWebContentsId});
+    if (selected == null || selected.isDestroyed() || selected.getType() !== 'window') {
+      throw new Error('Owned Renderer unavailable for title policy readiness');
+    }
+    if (!state.ownedWebContentsIds.has(selected.id)) {
+      throw new Error('Renderer metadata service ownership is unavailable');
+    }
+    const marker = selected.executeJavaScript(
+      ${JSON.stringify(RENDERER_READY_EXPRESSION)},
+      true,
+    );
+    const markerTimeout = new Promise((_, reject) => {
+      setTimeout(() => reject(new Error('Renderer readiness marker timed out')), 2_000);
+    });
+    await Promise.race([marker, markerTimeout]);
+    return { state: 'ready', reason: 'owned-metadata-service' };
+  })()`);
+  if (!isRecord(value) || value.state !== "ready" || value.reason !== "owned-metadata-service") {
+    throw new Error("Renderer title policy returned an invalid readiness status");
+  }
+  return value as unknown as RendererTitlePolicyReadiness;
+}
+
+export async function readMainProcessTitlePolicyCounters(
+  inspector: Pick<CdpClient, "evaluate">,
+): Promise<MainProcessTitlePolicyCounters | null> {
+  const value = await inspector.evaluate<unknown>(`(() => {
+    const state = globalThis[Symbol.for(${JSON.stringify(POLICY_STATE_SYMBOL)})];
+    return state == null ? null : { ...state.counters };
+  })()`);
+  if (value === null) return null;
+  if (
+    !isRecord(value) ||
+    !Number.isInteger(value.codexTitleCalls) ||
+    !Number.isInteger(value.piTitleSkips) ||
+    !Number.isInteger(value.externalTitleSkips) ||
+    !Number.isInteger(value.ambiguousTitleSkips)
+  ) {
+    throw new Error("Main-process title policy returned invalid counters");
+  }
+  return value as unknown as MainProcessTitlePolicyCounters;
+}