Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

4.7 KB
Raw Blame
// SPDX-License-Identifier: FSL-1.1-MIT
// Copyright (c) 2026 Cua AI, Inc.

// "Join with a code" (`host.joinWithCode`): sets this computer up with a
// one-time pairing code made on another device, by running the bundled
// `cua host setup --pair <code>`, as the install script does. The page
// confirms first; nothing here runs on a link alone. The Swift host answers
// the same method (`JoinWithCode.swift`).
import { spawn } from "node:child_process";

import { string } from "./args";
import type { BridgeContext } from "./context";
import { Failure, type Handlers } from "./host";
import { hostStatus } from "./machines";

/** Long enough for the driver download and the service start; the relay answers in seconds. */
export const JOIN_TIMEOUT_MS = 180_000;

const ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";

/** The 12-character code in what was typed or pasted (`cua_host::normalize_pairing_code`), or null. */
export function normalizeCode(input: string): string | null {
  let s = input.trim();
  const at = s.indexOf("/add/");
  if (at >= 0) s = s.slice(at + 5).split(/[?#/]/)[0] ?? "";
  if (s.startsWith("cpc_")) s = s.slice(4);
  let out = "";
  for (const raw of s) {
    const c = raw.toUpperCase();
    if (c === "-" || c === " ") continue;
    const m = c === "I" || c === "L" ? "1" : c === "O" ? "0" : c;
    if (m.length !== 1 || !ALPHABET.includes(m)) return null;
    out += m;
  }
  return out.length === 12 ? out : null;
}

/** The relay another than the production one that a link names (`?relay=`), when it is an http(s) URL. */
export function linkRelay(input: string): string | null {
  try {
    const v = new URL(input.trim()).searchParams.get("relay")?.trim();
    return v && /^https?:\/\//i.test(v) ? v : null;
  } catch {
    return null;
  }
}

/** `cua`'s arguments for joining with `code` (the canonical code, so nothing typed reaches the command line as is). */
export function joinArgs(code: string, relay: string | null): string[] {
  // It provides Spaces and keeps its screen private, as a computer added by
  // signing in does; sharing its desktop is a choice on its page.
  return ["host", "setup", "--pair", code, ...(relay ? ["--relay", relay] : []), "--no-desktop", "--provide-spaces"];
}

/** The line to show for a failed run: the last one the command wrote to stderr, else the exit status. */
export function failureText(stderr: string, status: string): string {
  const lines = stderr
    .split(/\r?\n/)
    .map((l) => l.trim())
    .filter(Boolean);
  return lines.length ? lines[lines.length - 1]! : `cua host setup ${status}`;
}

export interface CuaRun {
  ok: boolean;
  stderr: string;
  status: string;
}

/** Runs `cua` with `args` and waits for it (stopped after `timeoutMs`). */
export function runCua(cua: string, args: string[], env: NodeJS.ProcessEnv, timeoutMs = JOIN_TIMEOUT_MS): Promise<CuaRun> {
  return new Promise((resolve) => {
    let stderr = "";
    let settled = false;
    const done = (r: CuaRun) => {
      if (settled) return;
      settled = true;
      clearTimeout(timer);
      resolve(r);
    };
    let child;
    try {
      child = spawn(cua, args, { env, stdio: ["ignore", "ignore", "pipe"], windowsHide: true });
    } catch (e) {
      resolve({ ok: false, stderr: "", status: `could not start: ${e instanceof Error ? e.message : String(e)}` });
      return;
    }
    const timer = setTimeout(() => {
      child.kill("SIGKILL");
      done({ ok: false, stderr, status: "timed out" });
    }, timeoutMs);
    child.stderr?.on("data", (d: Buffer) => {
      stderr = (stderr + d.toString()).slice(-4000);
    });
    child.on("error", (e) => done({ ok: false, stderr: "", status: `could not start: ${e.message}` }));
    child.on("exit", (code, signal) => done({ ok: code === 0, stderr, status: signal ? `stopped by ${signal}` : `exited with ${code}` }));
  });
}

export function joinMethods(ctx: BridgeContext, run: typeof runCua = runCua): Handlers {
  const { model, supervisor, env } = ctx;
  return {
    "host.joinWithCode": async (args) => {
      const input = string(args, "code");
      const code = normalizeCode(input);
      if (!code) throw Failure.badArgs("code: 12 letters and digits, like K7QM-4XPB-2RHD");
      const named = typeof args.relay === "string" && args.relay.trim() ? args.relay.trim() : null;
      if (named && !/^https?:\/\//i.test(named)) throw Failure.badArgs("relay: an http(s) URL");
      if (!supervisor) throw Failure.unsupported("This build has no bundled cua to join with a code. Use the install command on this machine.");
      const result = await run(supervisor.cua, joinArgs(code, named ?? linkRelay(input)), { ...env });
      if (!result.ok) throw Failure.failed(failureText(result.stderr, result.status));
      await model.host.refresh();
      return hostStatus(model);
    },
  };
}