Skip to content

A desktop coding agent with free access to frontier models.

TypeScript
6.5 KB
Raw Blame
import type { BrowserEvaluation } from "./browser-script.ts";
import { probeAppState } from "./app-state.ts";
import { callFunction, DEFAULT_CDP_PROBE_TIMEOUT_MS, connect, debuggerUrlFor, evaluate, pickAppTarget } from "./cdp.ts";
import { firstPageTarget, targetById, waitForCdp } from "./targets.ts";
import type { AppStateProbe } from "./app-state.ts";
import type { CdpClient, CdpFunctionArgument, CdpTarget, EvaluateOptions } from "./cdp.ts";

export type SurfaceKind = "electron" | "chrome";

export interface SurfaceHandle {
  name: string;
  kind: SurfaceKind;
  hostKind: string;
  cdpUrl: string;
  pid?: number;
  profileDir?: string;
  sandboxId?: string;
  meta?: Record<string, string>;
}

export interface Surface {
  handle: SurfaceHandle;
  client: CdpClient;
}

export interface AttachedSurface extends Surface, AsyncDisposable {
  stop(): Promise<void>;
}

const REATTACH_FLOOR_MS = 8_000;
const HTTP_LIVENESS_TIMEOUT_MS = 4_000;

async function connectToAppTarget(handle: SurfaceHandle, timeoutMs = 30_000, preferredTargetId?: string): Promise<CdpClient> {
  const startedAt = Date.now();
  const remaining = () => Math.max(1, timeoutMs - (Date.now() - startedAt));
  const fallbackTarget = () => handle.kind === "electron"
    ? pickAppTarget(handle.cdpUrl, { timeoutMs: remaining() })
    : firstPageTarget(handle.cdpUrl, { timeoutMs: remaining() });
  const target: CdpTarget = preferredTargetId
    ? await targetById(handle.cdpUrl, preferredTargetId, { timeoutMs: remaining() }).catch(fallbackTarget)
    : await fallbackTarget();
  const client = await connect(debuggerUrlFor(handle.cdpUrl, target), {
    connectTimeoutMs: remaining(),
    sendTimeoutMs: remaining(),
  });
  await client.send("Page.enable", {}, { timeoutMs: remaining() }).catch(() => undefined);
  return client;
}

export async function attachSurface(handle: SurfaceHandle, opts: { timeoutMs?: number } = {}): Promise<AttachedSurface> {
  const timeoutMs = opts.timeoutMs ?? 30_000;
  const startedAt = Date.now();
  await waitForCdp(handle.cdpUrl, { timeoutMs });
  const client = await connectToAppTarget(handle, Math.max(1, timeoutMs - (Date.now() - startedAt)));
  const surface: AttachedSurface = {
    handle,
    client,
    stop: async () => surface.client.close(),
    [Symbol.asyncDispose]: async () => surface.client.close(),
  };
  return surface;
}

/**
 * Re-attach to the app's CURRENT page target.
 *
 * The desktop recreates its page target during some transitions (finishing
 * onboarding, for example). Evaluations against the old target then hang rather
 * than fail, which looks exactly like a blocked renderer. The legacy runner had
 * the same escape hatch as `ctx.reconnect()`.
 */
export async function reattachSurface(surface: Surface, opts: { timeoutMs?: number } = {}): Promise<void> {
  const targetId = surface.client.targetId ?? undefined;
  try {
    surface.client.close();
  } catch {
    // The old client is already gone; that is the case we are recovering from.
  }
  const client = await connectToAppTarget(surface.handle, Math.max(1, opts.timeoutMs ?? 30_000), targetId);
  surface.client = client;
}

function isRecoverableTransportError(error: unknown): boolean {
  if (!(error instanceof Error)) return false;
  return /timed out|timeout|CDP socket is not open|CDP transport stalled|CDP websocket (failed|closed)/i.test(error.message);
}

async function isCdpHttpAlive(cdpUrl: string): Promise<boolean> {
  try {
    const response = await fetch(`${cdpUrl.replace(/\/$/, "")}/json/version`, {
      signal: AbortSignal.timeout(HTTP_LIVENESS_TIMEOUT_MS),
    });
    return response.ok;
  } catch {
    return false;
  }
}

async function readOnSurface<T>(
  surface: Surface,
  read: (client: CdpClient, timeoutMs: number) => Promise<T>,
  { timeoutMs, reattachAttempts }: { timeoutMs: number; reattachAttempts: number },
): Promise<T> {
  const startedAt = Date.now();
  const remaining = () => Math.max(0, timeoutMs - (Date.now() - startedAt));
  let lastError: unknown = null;
  for (let attempt = 0; attempt <= reattachAttempts; attempt += 1) {
    try {
      const attemptTimeoutMs = attempt === 0 ? Math.max(1, remaining()) : Math.max(remaining(), REATTACH_FLOOR_MS);
      return await read(surface.client, attemptTimeoutMs);
    } catch (error) {
      lastError = error;
      if (attempt === reattachAttempts || !isRecoverableTransportError(error)) break;
      if (!await isCdpHttpAlive(surface.handle.cdpUrl)) throw error;
      surface.client.abort?.(error instanceof Error ? error : undefined);
      await reattachSurface(surface, { timeoutMs: Math.max(remaining(), REATTACH_FLOOR_MS) }).catch(() => undefined);
    }
  }
  throw lastError instanceof Error ? lastError : new Error("Surface read failed.");
}

/**
 * Evaluate against a surface, healing a replaced page target.
 *
 * The desktop swaps its page target during transitions; evaluations against the
 * old one hang until they time out, which reads like a blocked renderer. Owning
 * that here means callers — behaviours, specs, the readiness gate — never carry
 * re-attach bookkeeping.
 */
export async function evaluateOnSurface<T>(
  surface: Surface,
  expression: BrowserEvaluation<T>,
  opts: EvaluateOptions & { reattachAttempts?: number } = {},
): Promise<Awaited<T>> {
  const { reattachAttempts = 1, timeoutMs = DEFAULT_CDP_PROBE_TIMEOUT_MS, ...evaluateOptions } = opts;
  return readOnSurface(
    surface,
    (client, attemptTimeoutMs) => evaluate(client, expression, { ...evaluateOptions, timeoutMs: attemptTimeoutMs }),
    { timeoutMs: Math.max(1, timeoutMs), reattachAttempts },
  );
}

export async function callFunctionOnSurface<Args extends CdpFunctionArgument[], T>(
  surface: Surface,
  functionDeclaration: (...args: Args) => T,
  args: [...Args],
  opts: EvaluateOptions & { reattachAttempts?: number } = {},
): Promise<Awaited<T>> {
  const { reattachAttempts = 1, timeoutMs = DEFAULT_CDP_PROBE_TIMEOUT_MS, ...callOptions } = opts;
  return readOnSurface(
    surface,
    (client, attemptTimeoutMs) => callFunction(client, functionDeclaration, args, { ...callOptions, timeoutMs: attemptTimeoutMs }),
    { timeoutMs: Math.max(1, timeoutMs), reattachAttempts },
  );
}

export async function probeAppStateOnSurface(
  surface: Surface,
  opts: EvaluateOptions & { reattachAttempts?: number } = {},
): Promise<AppStateProbe> {
  const { reattachAttempts = 1, timeoutMs = DEFAULT_CDP_PROBE_TIMEOUT_MS, ...probeOptions } = opts;
  return readOnSurface(
    surface,
    (client, attemptTimeoutMs) => probeAppState(client, { ...probeOptions, timeoutMs: attemptTimeoutMs }),
    { timeoutMs: Math.max(1, timeoutMs), reattachAttempts },
  );
}