Skip to content

Computer use for the Pi coding agent — Windows apps, browsers and desktops through native UI trees, screenshots and real input.

Prepare compatible computer runtimes automatically

alexshpunt-clanker[bot]e35f9da4cfc7
diff --git a/src/config.ts b/src/config.ts
index c71c1c8..018f469 100644
--- a/src/config.ts
+++ b/src/config.ts
@@ -11,6 +11,8 @@ export interface ComputerConfig {
interop?: string;
runtime?: "windows-held-paths" | "windows-key-holds" | "windows-selected-displays" | "windows-capture-drag" | "windows-shell-desktops" | "windows-single-png" | "windows-semantic-actions" | "windows-fast-bilinear" | "windows-direct-process" | "windows-persistent-wgc" | "windows-native-pointer" | "windows-coordinate-scroll" | "windows-window-restore" | "windows-window-management" | "windows-desktop";
bundled?: BundledRuntime;
+ /** Explicitly trusted experimental driver, with protocol checks instead of packaged-byte checks. */
+ driverOverride?: true;
/** A sandbox guest's driver behind a host loopback relay. Set by the sandbox lifecycle, never read from config files. */
endpoint?: GuestEndpoint;
/** SSH alias when the driver runs on another machine. Set by connect, never read from config files. */
@@ -23,13 +25,17 @@ export interface ComputerConfig {
export interface MachineConfig {
/** OpenSSH alias; authentication and host trust stay in the user's SSH config. */
ssh: string;
- /** Remote WSL path of cua-driver.exe. */
- command: string;
+ /** Trusted remote driver override; omitted for the package-managed runtime. */
+ command?: string;
+ /** Keep a managed-looking path as an explicit test override. */
+ driverOverride?: true;
runtime?: ComputerConfig["runtime"];
/** Remote WSL path of Windows node.exe, needed for open_browser. */
node?: string;
/** Remote WSL path of a copy of this extension with playwright-core, needed for open_browser. */
package?: string;
+ /** Keep a legacy managed-looking browser path as an explicit test override. */
+ browserOverride?: true;
}
/** Host loopback ports that relay to one sandbox guest's driver and window identity peer. */
@@ -52,25 +58,31 @@ export async function loadComputerConfig(cwd: string): Promise<ComputerConfig> {
if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw new Error("Invalid .pi/computer-use.json; see docs/setup.md#override-the-runtime.");
}
if (!raw || typeof raw !== "object" || Array.isArray(raw)
- || Object.keys(raw).some(key => !["command", "args", "interop", "runtime", "machines"].includes(key))
+ || Object.keys(raw).some(key => !["command", "args", "interop", "runtime", "machines", "driverOverride"].includes(key))
+ || (raw.driverOverride !== undefined && raw.driverOverride !== true)
+ || (raw.driverOverride === true && typeof raw.command !== "string")
|| (raw.command !== undefined && (typeof raw.command !== "string" || !raw.command))
|| (raw.args !== undefined && (!Array.isArray(raw.args) || !raw.args.every(arg => typeof arg === "string")))
|| (raw.interop !== undefined && typeof raw.interop !== "string")
|| (raw.runtime !== undefined && (typeof raw.runtime !== "string" || !RUNTIMES.includes(raw.runtime)))
|| (raw.runtime !== undefined && (typeof raw.command !== "string" || raw.args !== undefined)))
throw new Error("Invalid computer-use configuration. Remove the old target field: this extension uses YOLO session window references, not configured PID/HWND.");
- const command = raw.command as string | undefined ?? process.env.CUA_DRIVER_PATH;
+ // Older setup wrote its managed, versioned desktop runtime into config. Treat that generated path as a default,
+ // not a permanent override. A custom path, an environment override, or driverOverride: true stays explicit.
+ const configured = raw.command as string | undefined;
+ const legacyManaged = raw.driverOverride !== true && raw.runtime === "windows-desktop" && !!configured && isLegacyManagedDriver(configured);
+ const command = legacyManaged ? process.env.CUA_DRIVER_PATH : configured ?? process.env.CUA_DRIVER_PATH;
if (!command && raw.args !== undefined) throw new Error("Bundled runtimes use their pinned MCP arguments; set a trusted command to override arguments.");
// A configured socket is used as given; otherwise a live one, since WSL_INTEROP can outlive its WSL session.
const interop = raw.interop as string | undefined ?? await liveInterop();
const bundled = command ? undefined : await findBundledRuntime(interop);
// The shipped runtime is the qualified windows-desktop build, so it gets that profile's capabilities.
// A configured runtime always comes with its own trusted command.
- const runtime = (raw.runtime as ComputerConfig["runtime"]) ?? (bundled ? "windows-desktop" : undefined);
+ const runtime = legacyManaged && !command ? "windows-desktop" : (raw.runtime as ComputerConfig["runtime"]) ?? (bundled ? "windows-desktop" : undefined);
return { command: command || bundled!.command,
...(bundled ? { bundled } : {}),
...(raw.args ? { args: raw.args as string[] } : {}), ...(interop ? { interop } : {}),
- ...(runtime ? { runtime } : {}),
+ ...(runtime ? { runtime } : {}), ...(raw.driverOverride === true ? { driverOverride: true as const } : {}),
...(raw.machines !== undefined ? { machines: parseMachines(raw.machines) } : {}) };
}
@@ -87,6 +99,10 @@ export async function readMachineSettings(cwd: string): Promise<{ interop?: stri
return { ...(interop ? { interop } : {}), machines: machines === undefined ? {} : parseMachines(machines) };
}
+/** Paths emitted by the old setup command are package-managed defaults, not permanent user overrides. */
+function isLegacyManagedDriver(command: string): boolean {
+ return /[\\/]Programs[\\/]PiComputerUse(?:PoC)?[\\/]cua-driver-\d+\.\d+\.\d+-[0-9a-f]{8}[\\/]runtime[\\/]cua-driver\.exe$/i.test(command);
+}
function parseMachines(value: unknown): Record<string, MachineConfig> {
const invalid = () => { throw new Error("Invalid machines in .pi/computer-use.json: use {\"<name>\": {\"ssh\", \"command\", \"runtime\"?, \"node\"?, \"package\"?}}."); };
if (!value || typeof value !== "object" || Array.isArray(value)) return invalid();
@@ -96,11 +112,19 @@ function parseMachines(value: unknown): Record<string, MachineConfig> {
// Short addresses start with the machine name (computer:<name>/w3qk), so it never takes an address kind word.
if (!/^[a-z0-9][a-z0-9_-]{0,63}$/.test(name) || name === "local" || ADDRESS_KINDS.has(name) || !raw || typeof raw !== "object" || Array.isArray(raw)) return invalid();
const machine = raw as Record<string, unknown>;
- if (Object.keys(machine).some(key => !["ssh", "command", "runtime", "node", "package"].includes(key))
- || typeof machine.ssh !== "string" || typeof machine.command !== "string" || !machine.command.startsWith("/")
- || (machine.runtime !== undefined && !RUNTIMES.includes(machine.runtime as string))
+ if (Object.keys(machine).some(key => !["ssh", "command", "runtime", "node", "package", "driverOverride", "browserOverride"].includes(key))
+ || typeof machine.ssh !== "string" || !machine.ssh
+ || (machine.command !== undefined && (typeof machine.command !== "string" || !machine.command.startsWith("/")))
+ || (machine.driverOverride !== undefined && (machine.driverOverride !== true || !machine.command))
+ || (machine.browserOverride !== undefined && (machine.browserOverride !== true || (!machine.node && !machine.package)))
+ || (machine.runtime !== undefined && (!machine.command || !RUNTIMES.includes(machine.runtime as string)))
|| [machine.node, machine.package].some(path => path !== undefined && (typeof path !== "string" || !path.startsWith("/")))) return invalid();
- machines[name] = machine as unknown as MachineConfig;
+ const legacy = machine.driverOverride !== true && machine.runtime === "windows-desktop" && typeof machine.command === "string" && isLegacyManagedDriver(machine.command);
+ const { command, runtime, node, package: worker, ...rest } = machine;
+ const keepNode = typeof node === "string" && (machine.browserOverride === true || !/[\\/]Programs[\\/]PiComputerUse[\\/]node-v[^/\\]+[\\/]node\.exe$/i.test(node));
+ const keepWorker = typeof worker === "string" && (machine.browserOverride === true || !/\/\.local\/share\/pi-computer-use\/package$/.test(worker));
+ machines[name] = { ...rest, ...(!legacy && command ? { command } : {}), ...(!legacy && runtime ? { runtime } : {}),
+ ...(keepNode ? { node } : {}), ...(keepWorker ? { package: worker } : {}) } as unknown as MachineConfig;
}
return machines;
}
diff --git a/src/driver.ts b/src/driver.ts
index cfcc859..46f706c 100644
--- a/src/driver.ts
+++ b/src/driver.ts
@@ -1,4 +1,5 @@
import { readFile, stat } from "node:fs/promises";
+import { readFileSync } from "node:fs";
import { createHash } from "node:crypto";
import { setTimeout as delay } from "node:timers/promises";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
@@ -86,10 +87,10 @@ export const WINDOW_RESTORE_RUNTIME = {
sha256: "c53dbdd3bd9a75469e14783b8e6f44573a9aa3f6c3c4998da9ee4e9a7a02d614",
} as const;
/** Window management plus every earlier native capability; `windows-desktop` selects these bytes. Browser pages use Playwright, not this runtime. */
+const shippedRuntime = JSON.parse(readFileSync(new URL("./runtime-pins.json", import.meta.url), "utf8")) as { source: string; version: string; files: Record<string, string> };
export const WINDOW_MANAGEMENT_RUNTIME = {
- source: "4b547b547edf415908557829fa723f143f781649", version: "0.38.0",
- sha256: "18d3e3378a4111cf41e3fafd85035525dab1870af77b1ac0725f5b410397f623",
-} as const;
+ source: shippedRuntime.source, version: shippedRuntime.version, sha256: shippedRuntime.files["cua-driver.exe"],
+};
const forkRuntimes = {
"windows-desktop": WINDOW_MANAGEMENT_RUNTIME,
"windows-window-management": WINDOW_MANAGEMENT_RUNTIME,
@@ -129,6 +130,7 @@ export class McpDriver implements Driver {
private readonly windowIdentity?: WindowIdentity;
private nativeTools?: Set<string>;
+ private connectedVersion?: string;
private get forkRuntime() { return this.config.runtime ? forkRuntimes[this.config.runtime] : undefined; }
private get bundledWindows() { return this.config.bundled?.target === "win32-x64"; }
@@ -207,7 +209,7 @@ export class McpDriver implements Driver {
if (this.config.bundled) {
if (this.config.command !== this.config.bundled.command) throw new Error("native_runtime_command_mismatch");
await verifyBundledRuntime(this.config.bundled, signal);
- } else if (this.forkRuntime) {
+ } else if (this.forkRuntime && !this.config.driverOverride) {
const hash = this.config.ssh ? (await sshRunner(this.config.ssh).run("sha256sum", [this.config.command], { signal })).split(" ")[0]
: createHash("sha256").update(await readFile(this.config.command)).digest("hex");
if (hash !== this.forkRuntime.sha256) throw new Error("Native fork artifact hash mismatch; no Driver process was started.");
@@ -223,15 +225,16 @@ export class McpDriver implements Driver {
await client.connect(transport, { signal, timeout: 15_000 });
const server = client.getServerVersion();
const version = this.config.bundled?.driverVersion ?? this.forkRuntime?.version ?? this.version;
- if (server?.name !== "cua-driver" || server.version !== version)
- throw new Error(`This backend requires cua-driver ${version}. Requalify before changing the pin.`);
+ if (server?.name !== "cua-driver" || (this.config.driverOverride ? !/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(server.version ?? "") : server.version !== version))
+ throw new Error(this.config.driverOverride ? "The experimental driver did not report a valid cua-driver version." : `This backend requires cua-driver ${version}. Requalify before changing the pin.`);
+ this.connectedVersion = server.version;
if (this.envelopes && (client.getServerCapabilities()?.experimental?.["ai.cua.driver.envelopes"] as { version?: unknown } | undefined)?.version !== 1)
throw new Error("The native fork runtime did not acknowledge its EOF-aware receiver.");
const { tools } = await client.listTools({}, { signal, timeout: 15_000 });
this.nativeVisualsAvailable = ["present_agent_activity", "set_agent_visuals"].every(name => tools.some(tool => tool.name === name && tool.inputSchema.type === "object"));
- if (this.config.bundled) {
+ if (this.config.bundled || this.config.driverOverride) {
this.nativeTools = new Set(tools.map(tool => tool.name));
- if (this.config.bundled)
+ if (this.config.bundled || this.config.runtime === "windows-desktop")
for (const name of ["list_apps", "list_windows", "get_window_state", "get_desktop_state"])
if (!tools.some(tool => tool.name === name && tool.inputSchema.type === "object"))
throw new Error(`native_runtime_schema_missing: ${name}`);
@@ -364,7 +367,7 @@ export class McpDriver implements Driver {
if (this.nativeTools && !this.nativeTools.has(name))
return { content: [], structuredContent: { status: "refused", code: "unsupported_native_capability", platform: this.platform, tool: name, attempted: false, fallback: false }, isError: true };
// Since 0.35 the driver shapes window state for models; the adapter needs the full payload with `elements`.
- if (name === "get_window_state" && compactWindowState(this.config.bundled?.driverVersion ?? this.forkRuntime?.version ?? this.version)) args = { ...args, full_output: true };
+ if (name === "get_window_state" && compactWindowState(this.connectedVersion ?? this.config.bundled?.driverVersion ?? this.forkRuntime?.version ?? this.version)) args = { ...args, full_output: true };
// A timeline runs for its own length and a large app (GIMP, Blender) can take over 15 s to show its first window;
// every other native call answers well within 15 s.
const timeout = name === "input_timeline" ? 15_000 + timelineLength(args) : name === "launch_app" ? 90_000 : 15_000;
@@ -391,6 +394,7 @@ export class McpDriver implements Driver {
this.client = undefined;
this.transport = undefined;
this.nativeTools = undefined;
+ this.connectedVersion = undefined;
try { await client?.close(); }
finally {
try { await transport?.close(); }
diff --git a/src/machine.ts b/src/machine.ts
index 98fad0f..2448921 100644
--- a/src/machine.ts
+++ b/src/machine.ts
@@ -2,7 +2,10 @@ import { createHash } from "node:crypto";
import { readFile } from "node:fs/promises";
import { createRequire } from "node:module";
import { fileURLToPath } from "node:url";
-import { loadComputerConfig, type ComputerConfig } from "./config.ts";
+import { loadComputerConfig, readMachineSettings, type ComputerConfig } from "./config.ts";
+import { prepareRemoteRuntime } from "./remote-runtime.ts";
+import { prepareRemoteBrowser } from "./remote-browser.ts";
+import { RemotePreparationUncertain } from "./remote-provision-error.ts";
import { ComputerRequestError, machineGuide, type MachineFactory, type SandboxFactory } from "./computer-resources.ts";
import type { CuaVisionSettings } from "./cua-image-settings.ts";
import { McpDriver } from "./driver.ts";
@@ -11,12 +14,12 @@ import { localRunner, sshRunner, type CommandRunner } from "./runner.ts";
import { WindowsSandbox, runnerHost, sandboxOptions, waitForGuestDriver } from "./sandbox.ts";
import { IsolatedSession } from "./isolated-session.ts";
import { ComputerSession, type ComputerMode } from "./session.ts";
-import { WebBrowser } from "./web-browser.ts";
+import { WebBrowser, WebError } from "./web-browser.ts";
import type { VisualSettings } from "./native-visuals.ts";
/** The configured machine for a connect command; unknown names refuse before any SSH work. */
export async function machineConfig(cwd: string, name: string): Promise<NonNullable<ComputerConfig["machines"]>[string]> {
- const machine = (await loadComputerConfig(cwd)).machines?.[name];
+ const machine = (await readMachineSettings(cwd)).machines[name];
if (!machine) throw new ComputerRequestError(`No machine named ${name} is configured in .pi/computer-use.json.`);
return machine;
}
@@ -57,13 +60,16 @@ export function sandboxFactory(options: { settings: () => CuaVisionSettings; vis
if (command.action === "open_session" && Object.keys(command).some(key => key !== "action")) throw new Error("open_session takes no options.");
parsed = command.action === "open_session" ? undefined : sandboxOptions(command);
} catch (error) { throw new ComputerRequestError(error instanceof Error ? error.message : String(error)); }
- const config = await loadComputerConfig(cwd);
const machine = machineName ? await machineConfig(cwd, machineName) : undefined;
- const runner = machine ? sshRunner(machine.ssh) : localRunner(config.interop);
- const sandbox = parsed ? await WindowsSandbox.open(runnerHost(runner), machine?.command ?? config.command, parsed, signal)
- : await IsolatedSession.open(runnerHost(runner), machine?.command ?? config.command, signal);
+ const config = machine ? undefined : await loadComputerConfig(cwd);
+ const runner = machine ? sshRunner(machine.ssh) : localRunner(config!.interop);
+ const commandPath = machine ? machine.command ?? await prepareRemoteRuntime(runner, signal) : config!.command;
+ const runtime = machine ? machine.command ? machine.runtime : "windows-desktop" : config!.runtime;
+ const sandbox = parsed ? await WindowsSandbox.open(runnerHost(runner), commandPath, parsed, signal)
+ : await IsolatedSession.open(runnerHost(runner), commandPath, signal);
// The endpoint selects the guest transport; ssh only makes the runtime hash check read the machine's own bytes.
- const driver = new McpDriver({ command: machine?.command ?? config.command, ...(machine?.runtime ?? config.runtime ? { runtime: machine?.runtime ?? config.runtime } : {}),
+ const override = machine ? machine.driverOverride : config!.driverOverride;
+ const driver = new McpDriver({ command: commandPath, ...(runtime ? { runtime } : {}), ...(override ? { driverOverride: true as const } : {}),
endpoint: sandbox.endpoint, ...(machine ? { ssh: machine.ssh } : {}) }, undefined, options.visuals);
try { await waitForGuestDriver(driver, signal); }
catch (error) { await driver.close().catch(() => undefined); await sandbox.close(); throw error; }
@@ -80,21 +86,26 @@ export function sandboxFactory(options: { settings: () => CuaVisionSettings; vis
export function machineFactory(options: { getMode: () => ComputerMode; settings: () => CuaVisionSettings; visuals?: VisualSettings }): MachineFactory {
return async (cwd, name, signal) => {
const machine = await machineConfig(cwd, name);
- const refresh = `setup part machine (user: /computer-setup machine ${machine.ssh} ${name})`;
const runner = sshRunner(machine.ssh);
- const driver = new McpDriver({ command: machine.command, ...(machine.runtime ? { runtime: machine.runtime } : {}), ssh: machine.ssh }, undefined, options.visuals);
+ const command = machine.command ?? await prepareRemoteRuntime(runner, signal);
+ const runtime = machine.command ? machine.runtime : "windows-desktop";
+ const driver = new McpDriver({ command, ...(runtime ? { runtime } : {}), ...(machine.driverOverride ? { driverOverride: true as const } : {}), ssh: machine.ssh }, undefined, options.visuals);
try { await waitForGuestDriver(driver, signal, 30_000); }
catch (error) { await driver.close().catch(() => undefined); throw error; }
- const launchWeb = machine.node && machine.package
- ? async (launch: Parameters<typeof WebBrowser.launch>[0], webSignal?: AbortSignal) => {
- await checkRemoteWorker(runner, machine.package!, refresh, webSignal);
- return WebBrowser.launch({ ...launch, remote: { runner, node: machine.node!, worker: `${machine.package}/src/web-worker.ts` } }, webSignal);
- }
- : undefined;
+ const launchWeb = async (launch: Parameters<typeof WebBrowser.launch>[0], webSignal?: AbortSignal) => {
+ const prepared = await prepareRemoteBrowser(runner, webSignal, { node: machine.node, package: machine.package }).catch(error => {
+ if (error instanceof RemotePreparationUncertain) throw new WebError(error.message, false, true);
+ throw error;
+ });
+ const node = prepared.node;
+ const workerPackage = prepared.package;
+ if (machine.package) await checkRemoteWorker(runner, workerPackage, "the explicit browser worker override", webSignal);
+ return WebBrowser.launch({ ...launch, remote: { runner, node, worker: `${workerPackage}/src/web-worker.ts` } }, webSignal);
+ };
const remote = new ComputerSession(driver, options.getMode, options.settings, undefined, launchWeb, new MachineHost(runner));
return { ref: name, session: remote,
describe: source => [`# Machine ${name}`, `Address: ${source}`, `SSH: ${machine.ssh}`,
- `Browser: ${launchWeb ? "available" : "not configured (node and package)"}`, ...machineGuide(source)].join("\n"),
+ "Browser: prepared automatically on first use", ...machineGuide(source)].join("\n"),
close: () => remote.close() };
};
}
diff --git a/src/remote-browser.ts b/src/remote-browser.ts
new file mode 100644
index 0000000..1bc9643
--- /dev/null
+++ b/src/remote-browser.ts
@@ -0,0 +1,191 @@
+import { spawn, type ChildProcess } from "node:child_process";
+import { createHash } from "node:crypto";
+import { cp, lstat, mkdir, mkdtemp, readFile, readdir, rm } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { WINDOWS_POWERSHELL, runPowerShell, type CommandRunner } from "./runner.ts";
+import { WINDOWS_NODE } from "./setup-pins.ts";
+import { RemotePreparationUncertain } from "./remote-provision-error.ts";
+
+const packageRoot = fileURLToPath(new URL("..", import.meta.url));
+// Node publishes a separate checksum for its standalone executable and its ZIP.
+const NODE_EXE_VERSION = WINDOWS_NODE.version;
+const NODE_EXE_SHA256 = WINDOWS_NODE.executableSha256;
+type Manifest = { path: string; hash: string }[];
+
+/** Every copied file participates in the cache key. Reject symlinks and names sha256sum cannot represent safely. */
+async function manifest(source: string, playwright: string, signal?: AbortSignal): Promise<Manifest> {
+ const files: Manifest = [];
+ const visit = async (directory: string, prefix: string) => {
+ signal?.throwIfAborted();
+ for (const entry of await readdir(directory, { withFileTypes: true })) {
+ const name = prefix ? `${prefix}/${entry.name}` : entry.name;
+ if (!/^[A-Za-z0-9_./@+ -]+$/.test(name)) throw new Error("Unsupported browser worker filename.");
+ const file = path.join(directory, entry.name);
+ const info = await lstat(file);
+ if (info.isDirectory()) await visit(file, name);
+ else if (info.isFile()) files.push({ path: name, hash: createHash("sha256").update(await readFile(file)).digest("hex") });
+ else throw new Error(`Browser worker contains a non-regular file: ${name}`);
+ }
+ };
+ await visit(path.join(source, "src"), "src");
+ await visit(playwright, "node_modules/playwright-core");
+ const packageFile = path.join(source, "package.json"), packageInfo = await lstat(packageFile);
+ if (!packageInfo.isFile()) throw new Error("Browser worker package.json is not a regular file.");
+ files.push({ path: "package.json", hash: createHash("sha256").update(await readFile(packageFile)).digest("hex") });
+ return files.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+}
+
+const exists = async (runner: CommandRunner, directory: string, signal?: AbortSignal) => {
+ const out = await runner.run("bash", ["-c", 'if [ -e "$1" ] || [ -L "$1" ]; then printf present; else printf absent; fi', "worker-check", directory], { signal, timeoutMs: 30_000 });
+ if (out !== "present" && out !== "absent") throw new Error("Could not determine remote browser worker state.");
+ return out === "present";
+};
+
+/** Verify both the file set and every byte; never trust a copied manifest on the remote machine. */
+async function verify(runner: CommandRunner, directory: string, files: Manifest, signal?: AbortSignal) {
+ const list = await runner.run("bash", ["-c", 'set -eu; [ -d "$1" ] && [ ! -L "$1" ]; cd -- "$1"; if [ -n "$(find . ! -type f ! -type d -print -quit)" ]; then exit 1; fi; find . -type f -printf "%P\\n" | LC_ALL=C sort', "worker-verify", directory], { signal, timeoutMs: 120_000 });
+ const names = list.trimEnd() ? list.trimEnd().split("\n") : [];
+ if (names.length !== files.length || names.some((name, index) => name !== files[index].path)) throw new Error("Remote browser worker file set differs from the package.");
+ await runner.run("bash", ["-c", 'set -eu; cd -- "$1"; sha256sum --check --strict --status', "worker-hash", directory],
+ { input: files.map(file => `${file.hash} ${file.path}\n`).join(""), signal, timeoutMs: 120_000 });
+}
+
+/** Stream one staged local archive over SSH; a cancelled or failed stream is never promoted. */
+async function transfer(runner: CommandRunner, from: string, to: string, signal?: AbortSignal): Promise<void> {
+ signal?.throwIfAborted();
+ const pack = spawn("tar", ["-cf", "-", "-C", from, "."], { stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
+ let unpack: ReturnType<CommandRunner["spawn"]>;
+ try { unpack = runner.spawn("tar", ["-xf", "-", "-C", to]); }
+ catch (error) { pack.kill(); throw error; }
+ let diagnostic = "";
+ pack.stderr.on("data", chunk => { diagnostic = (diagnostic + String(chunk)).slice(-1000); });
+ unpack.stderr.on("data", chunk => { diagnostic = (diagnostic + String(chunk)).slice(-1000); });
+ const wait = (child: ChildProcess) => new Promise<void>((resolve, reject) => {
+ child.once("error", reject);
+ child.once("close", code => {
+ if (code === 0) resolve();
+ else { const error = new Error(`Browser worker transfer failed (${code}): ${diagnostic}`); Object.assign(error, { exitCode: code }); reject(error); }
+ });
+ });
+ // Stop producing bytes on cancellation, but keep SSH alive until remote tar has seen EOF and exited.
+ const onAbort = () => { pack.kill(); };
+ let timedOut = false;
+ const timer = setTimeout(() => { timedOut = true; pack.kill(); unpack.kill(); }, 180_000);
+ signal?.addEventListener("abort", onAbort, { once: true });
+ if (signal?.aborted) onAbort();
+ pack.stdout.pipe(unpack.stdin);
+ unpack.stdin.on("error", () => { /* The process exit below reports the transfer failure. */ });
+ try {
+ const [packed, unpacked] = await Promise.allSettled([wait(pack), wait(unpack)]);
+ if (timedOut) throw new RemotePreparationUncertain("Browser worker transfer outcome is unknown; remote extraction may still be running.");
+ if (unpacked.status === "rejected" && (runner.ssh && (unpacked.reason?.exitCode === 255 || unpacked.reason?.exitCode == null) || !signal?.aborted))
+ throw new RemotePreparationUncertain(`Browser worker transfer outcome is unknown; remote extraction may still be running: ${String(unpacked.reason)}`);
+ signal?.throwIfAborted();
+ if (packed.status === "rejected") throw packed.reason;
+ if (unpacked.status === "rejected") throw unpacked.reason;
+ } finally { clearTimeout(timer); signal?.removeEventListener("abort", onAbort); }
+}
+
+/** Copy the current worker into a content-addressed remote package; old workers remain untouched. */
+export async function prepareWorkerPackage(runner: CommandRunner, source: string, playwright: string, home: string, signal?: AbortSignal): Promise<string> {
+ signal?.throwIfAborted();
+ const files = await manifest(source, playwright, signal);
+ const key = createHash("sha256").update(JSON.stringify(files)).digest("hex");
+ const parent = path.posix.join(home, ".local/share/pi-computer-use/workers"), target = path.posix.join(parent, key);
+ const resolvedParent = (await runner.run("realpath", ["-m", "--", parent], { signal, timeoutMs: 15_000 })).trim();
+ if (resolvedParent !== parent) throw new Error("Remote browser worker cache parent is redirected.");
+ if (await exists(runner, target, signal)) { await verify(runner, target, files, signal); return target; }
+ await runner.run("mkdir", ["-p", "--", parent], { signal, timeoutMs: 30_000 });
+ signal?.throwIfAborted();
+ const stage = (await runner.run("mktemp", ["-d", `${parent}/.staging-XXXXXXXX`], { timeoutMs: 30_000 }).catch(error => { throw new RemotePreparationUncertain(`Remote staging outcome is unknown: ${error instanceof Error ? error.message : String(error)}`); })).trim();
+ if (!stage.startsWith(`${parent}/.staging-`) || stage.slice(parent.length + 1).includes("/")) throw new Error("Invalid remote staging directory.");
+ let local: string | undefined;
+ try {
+ local = await mkdtemp(path.join(tmpdir(), "pi-remote-browser-"));
+ await mkdir(path.join(local, "node_modules"));
+ await cp(path.join(source, "src"), path.join(local, "src"), { recursive: true });
+ await cp(playwright, path.join(local, "node_modules", "playwright-core"), { recursive: true });
+ await cp(path.join(source, "package.json"), path.join(local, "package.json"));
+ await transfer(runner, local, stage, signal);
+ await verify(runner, stage, files, signal);
+ signal?.throwIfAborted();
+ // GNU mv -T -n never replaces an existing published directory. A racing winner is verified below.
+ try { await runner.run("mv", ["-T", "-n", "--", stage, target], { timeoutMs: 30_000 }); }
+ catch (error) {
+ if (!await exists(runner, target).catch(() => false)) throw new RemotePreparationUncertain(`Remote browser worker publication outcome is unknown: ${error instanceof Error ? error.message : String(error)}`);
+ }
+ if (signal?.aborted) throw new RemotePreparationUncertain("Cancelled after remote worker publication; the cache may already be present.");
+ await verify(runner, target, files, signal);
+ return target;
+ } finally {
+ const cleanup = await Promise.allSettled([...(local ? [rm(local, { recursive: true, force: true })] : []), runner.run("rm", ["-rf", "--", stage], { timeoutMs: 30_000 })]);
+ if (cleanup.some(result => result.status === "rejected")) throw new RemotePreparationUncertain(`Browser worker staging cleanup is unconfirmed: ${stage}`);
+ }
+}
+
+/** Find a compatible Windows Node or install the verified standalone executable in an owned cache. */
+export async function prepareWindowsNode(runner: CommandRunner, signal?: AbortSignal): Promise<string> {
+ const url = `https://nodejs.org/dist/${NODE_EXE_VERSION}/win-x64/node.exe`;
+ const ps = `
+$ErrorActionPreference = 'Stop'
+[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12
+function Hash([string]$f) { $s = [IO.File]::OpenRead($f); try { -join ([Security.Cryptography.SHA256]::Create().ComputeHash($s) | ForEach-Object { $_.ToString('x2') }) } finally { $s.Dispose() } }
+function ValidNode([string]$f) {
+ if (!(Test-Path -LiteralPath $f -PathType Leaf)) { return $false }
+ try { $v = (& $f --version 2>$null); $a = (& $f -p 'process.arch' 2>$null); if ($v -notmatch '^v(\\d+)\\.(\\d+)\\.') { return $false }; $major = [int]$Matches[1]; $minor = [int]$Matches[2]; return $a -eq 'x64' -and ($major -ge 24 -or ($major -eq 23 -and $minor -ge 6) -or ($major -eq 22 -and $minor -ge 19)) } catch { return $false }
+}
+$installed = (Get-Command node.exe -ErrorAction SilentlyContinue | Select-Object -First 1).Source
+if ($installed -and (ValidNode $installed)) { $installed; return }
+$legacy = Join-Path $env:LOCALAPPDATA 'Programs\\PiComputerUse\\node-${NODE_EXE_VERSION}-win-x64\\node.exe'
+if ((Test-Path -LiteralPath $legacy -PathType Leaf) -and (Hash $legacy) -eq '${NODE_EXE_SHA256}') { $legacy; return }
+$root = Join-Path $env:LOCALAPPDATA 'PiComputerUse\\browser-node'
+$dir = Join-Path $root '${NODE_EXE_SHA256}'
+$exe = Join-Path $dir 'node.exe'
+if (Test-Path -LiteralPath $dir) {
+ if (((Get-Item -Force -LiteralPath $dir).Attributes -band [IO.FileAttributes]::ReparsePoint) -or !(Test-Path -LiteralPath $exe -PathType Leaf) -or (Hash $exe) -ne '${NODE_EXE_SHA256}') { throw 'Cached Windows Node does not match the package.' }
+ $exe; return
+}
+New-Item -ItemType Directory -Force -Path $root | Out-Null
+$stage = Join-Path $root ('.staging-' + [guid]::NewGuid().ToString('N'))
+New-Item -ItemType Directory -Path $stage | Out-Null
+try {
+ $download = Join-Path $stage 'node.exe'
+ (New-Object Net.WebClient).DownloadFile('${url}', $download)
+ if ((Hash $download) -ne '${NODE_EXE_SHA256}') { throw 'Windows Node download failed integrity verification.' }
+ try { [IO.Directory]::Move($stage, $dir) } catch { if (!(Test-Path -LiteralPath $dir)) { throw } }
+ if (((Get-Item -Force -LiteralPath $dir).Attributes -band [IO.FileAttributes]::ReparsePoint) -or !(Test-Path -LiteralPath $exe -PathType Leaf) -or (Hash $exe) -ne '${NODE_EXE_SHA256}') { throw 'Cached Windows Node does not match the package.' }
+ $exe
+} finally { if (Test-Path -LiteralPath $stage) { Remove-Item -LiteralPath $stage -Recurse -Force } }`;
+ signal?.throwIfAborted();
+ let windows: string;
+ try { windows = await runPowerShell(runner, WINDOWS_POWERSHELL, ps, { timeoutMs: 600_000, scriptOnStdin: true }); }
+ catch (error) { throw new RemotePreparationUncertain(`Windows Node preparation outcome is unknown; a remote installer may still be running: ${error instanceof Error ? error.message : String(error)}`); }
+ if (!/^[A-Za-z]:\\/.test(windows)) throw new Error("Windows Node path is invalid.");
+ if (signal?.aborted) throw new Error("Cancelled after Windows Node was prepared; its verified cache remains available.");
+ return (await runner.run("wslpath", ["-u", windows], { signal, timeoutMs: 30_000 })).trim();
+}
+
+/** Prepare only the worker; a user-supplied Node must not trigger another Node installation. */
+export async function prepareRemoteWorker(runner: CommandRunner, signal?: AbortSignal): Promise<string> {
+ const home = (await runner.run("bash", ["-c", 'printf %s "$HOME"'], { signal, timeoutMs: 30_000 })).trim();
+ if (!home.startsWith("/") || home.includes("\n")) throw new Error("Remote home directory is invalid.");
+ const playwright = path.dirname(createRequire(import.meta.url).resolve("playwright-core/package.json"));
+ return prepareWorkerPackage(runner, packageRoot, playwright, home, signal);
+}
+
+/** Provision the missing browser parts; explicit overrides are left untouched. */
+export async function prepareRemoteBrowser(runner: CommandRunner, signal?: AbortSignal,
+ overrides: { node?: string; package?: string } = {}, deps = { node: prepareWindowsNode, worker: prepareRemoteWorker }): Promise<{ node: string; package: string }> {
+ const [node, remotePackage] = await Promise.allSettled([
+ overrides.node ? Promise.resolve(overrides.node) : deps.node(runner, signal),
+ overrides.package ? Promise.resolve(overrides.package) : deps.worker(runner, signal),
+ ]);
+ if (node.status === "rejected" && node.reason instanceof RemotePreparationUncertain) throw node.reason;
+ if (remotePackage.status === "rejected" && remotePackage.reason instanceof RemotePreparationUncertain) throw remotePackage.reason;
+ if (node.status === "rejected") throw node.reason;
+ if (remotePackage.status === "rejected") throw remotePackage.reason;
+ return { node: node.value, package: remotePackage.value };
+}
diff --git a/src/remote-provision-error.ts b/src/remote-provision-error.ts
new file mode 100644
index 0000000..7f179c6
--- /dev/null
+++ b/src/remote-provision-error.ts
@@ -0,0 +1,2 @@
+/** The transport ended after dispatch; a remote preparation step may still be running or may have completed. */
+export class RemotePreparationUncertain extends Error {}
diff --git a/src/remote-runtime.ts b/src/remote-runtime.ts
new file mode 100644
index 0000000..2935162
--- /dev/null
+++ b/src/remote-runtime.ts
@@ -0,0 +1,91 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fetchRuntime, loadBundledRuntime, PACKAGED_RUNTIME, readRuntimePins, type BundledRuntime } from "./native-runtime.ts";
+import { runPowerShell, WINDOWS_POWERSHELL, type CommandRunner } from "./runner.ts";
+import { RemotePreparationUncertain } from "./remote-provision-error.ts";
+
+/** The package's own checked runtime; a Git checkout obtains it through the same path as local use. */
+async function localRuntime(signal?: AbortSignal): Promise<BundledRuntime> {
+ const pins = await readRuntimePins();
+ await fetchRuntime(PACKAGED_RUNTIME, pins, signal);
+ return loadBundledRuntime(PACKAGED_RUNTIME, pins);
+}
+
+/** Ask the remote Windows host for its own user folder; never guess a Windows username. */
+async function remoteLocalAppData(runner: CommandRunner, signal?: AbortSignal): Promise<string> {
+ const windows = await runPowerShell(runner, WINDOWS_POWERSHELL,
+ "[Environment]::GetFolderPath([Environment+SpecialFolder]::LocalApplicationData)", { signal, timeoutMs: 15_000 });
+ if (!/^[A-Za-z]:\\/.test(windows) || /[\r\n]/.test(windows)) throw new Error("remote_runtime_local_appdata_unavailable");
+ const native = (await runner.run("wslpath", ["-u", windows], { signal, timeoutMs: 10_000 })).trim();
+ if (!path.posix.isAbsolute(native) || /[\r\n]/.test(native)) throw new Error("remote_runtime_local_appdata_unavailable");
+ return native;
+}
+
+interface RemoteRuntimeDeps {
+ localRuntime(signal?: AbortSignal): Promise<BundledRuntime>;
+ remoteLocalAppData(runner: CommandRunner, signal?: AbortSignal): Promise<string>;
+}
+const defaultDeps: RemoteRuntimeDeps = { localRuntime, remoteLocalAppData };
+
+/** Copy the checked package runtime to an immutable remote cache and return its remote WSL executable path. */
+export async function prepareRemoteRuntime(runner: CommandRunner, signal?: AbortSignal, deps: RemoteRuntimeDeps = defaultDeps): Promise<string> {
+ signal?.throwIfAborted();
+ const runtime = await deps.localRuntime(signal);
+ if (!/^[a-f0-9]{40}$/.test(runtime.source) || runtime.target !== "win32-x64") throw new Error("remote_runtime_identity_invalid");
+ const names = Object.keys(runtime.files).sort();
+ if (!names.length || !names.includes("cua-driver.exe") || names.some(name => !/^[A-Za-z0-9_.-]+$/.test(name) || !/^[a-f0-9]{64}$/.test(runtime.files[name])))
+ throw new Error("remote_runtime_manifest_invalid");
+ const appData = await deps.remoteLocalAppData(runner, signal);
+ if (!path.posix.isAbsolute(appData) || /[\r\n]/.test(appData)) throw new Error("remote_runtime_local_appdata_unavailable");
+ // The manifest identity changes when any runtime byte changes, even if a build reused its source revision.
+ const identity = createHash("sha256").update(JSON.stringify(names.map(name => [name, runtime.files[name]]))).digest("hex");
+ const parent = path.posix.join(appData, "PiComputerUse", "native-runtimes", runtime.source, identity);
+ const destination = path.posix.join(parent, runtime.target), folder = path.posix.join(destination, "runtime");
+ const command = path.posix.join(folder, "cua-driver.exe");
+ const exists = async () => (await runner.run("bash", ["-c", 'if [ -e "$1" ] || [ -L "$1" ]; then printf present; else printf missing; fi', "bash", destination], { signal, timeoutMs: 15_000 })).trim() === "present";
+ const verify = async (root: string) => {
+ // Do not follow a pre-existing symlink for the cache directory or any executable/companion.
+ const script = 'set -eu; root=$1; shift; test -d "$root" && test ! -L "$root" && test ! -L "$root/runtime" && test "$(realpath -e -- "$root")" = "$root"; for file in "$@"; do test -f "$file" && test ! -L "$file"; done; sha256sum -- "$@"';
+ const paths = names.map(name => path.posix.join(root, "runtime", name));
+ const out = await runner.run("bash", ["-c", script, "bash", root, ...paths], { signal, timeoutMs: 120_000 });
+ const hashes = out.trim().split("\n").map(line => line.slice(0, 64));
+ if (hashes.length !== names.length || hashes.some((hash, index) => hash !== runtime.files[names[index]]))
+ throw new Error("remote_runtime_hash_mismatch: existing remote runtime was not replaced");
+ };
+ if (await exists()) { await verify(destination); return command; }
+ await runner.run("mkdir", ["-p", "--", parent], { signal, timeoutMs: 30_000 });
+ // Refuse redirected parent paths: a cache must stay beneath the intended Windows user folder.
+ const actualParent = (await runner.run("realpath", ["-e", "--", parent], { signal, timeoutMs: 15_000 })).trim();
+ if (actualParent !== parent) throw new Error("remote_runtime_cache_symlink_refused");
+ signal?.throwIfAborted();
+ const staging = (await runner.run("mktemp", ["-d", `${parent}/.staging-XXXXXXXX`], { timeoutMs: 30_000 }).catch(error => { throw new RemotePreparationUncertain(`Remote staging outcome is unknown: ${error instanceof Error ? error.message : String(error)}`); })).trim();
+ if (!staging.startsWith(`${parent}/.staging-`) || staging.slice(parent.length + 10).includes("/")) throw new Error("remote_runtime_staging_invalid");
+ let failure: unknown;
+ try {
+ signal?.throwIfAborted();
+ await runner.run("mkdir", ["--", path.posix.join(staging, "runtime")], { timeoutMs: 30_000 });
+ for (const name of names) {
+ signal?.throwIfAborted();
+ const bytes = await readFile(path.join(runtime.root, "runtime", name));
+ // Keep SSH open until the dispatched writer exits. Killing the local client does not prove the remote writer stopped.
+ try { await runner.run("dd", ["status=none", `of=${path.posix.join(staging, "runtime", name)}`], { input: bytes, timeoutMs: 600_000 }); }
+ catch (error) { throw new RemotePreparationUncertain(`Remote runtime transfer outcome is unknown; a remote writer may still be running: ${error instanceof Error ? error.message : String(error)}`); }
+ signal?.throwIfAborted();
+ }
+ await verify(staging);
+ // GNU mv -n -T never replaces a destination. A concurrent winner is checked below.
+ signal?.throwIfAborted();
+ try { await runner.run("mv", ["-n", "-T", "--", staging, destination], { timeoutMs: 30_000 }); }
+ catch (error) {
+ // A concurrent publisher may have won, or SSH may have lost the rename response. Never replay the rename.
+ if (!await exists().catch(() => false)) throw new RemotePreparationUncertain(`Remote runtime publication outcome is unknown: ${error instanceof Error ? error.message : String(error)}`);
+ }
+ if (signal?.aborted) throw new RemotePreparationUncertain("Cancelled after remote runtime publication; the cache may already be present.");
+ await verify(destination);
+ } catch (error) { failure = error; }
+ try { await runner.run("rm", ["-rf", "--", staging], { timeoutMs: 30_000 }); }
+ catch (error) { throw new RemotePreparationUncertain(`Remote runtime staging cleanup is unconfirmed: ${error instanceof Error ? error.message : String(error)}`, { cause: failure }); }
+ if (failure) throw failure;
+ return command;
+}
diff --git a/src/setup-pins.ts b/src/setup-pins.ts
index 65a946d..0ae00b5 100644
--- a/src/setup-pins.ts
+++ b/src/setup-pins.ts
@@ -5,6 +5,7 @@ export const WINDOWS_NODE = {
version: "v22.22.2",
url: "https://nodejs.org/dist/v22.22.2/node-v22.22.2-win-x64.zip",
sha256: "7c93e9d92bf68c07182b471aa187e35ee6cd08ef0f24ab060dfff605fcc1c57c",
+ executableSha256: "ae1a50511be58e987483fdbc12125407443926d2d394669ade2352776e920dd3",
};
/** Microsoft Execution Containers; only x64/wxc-exec.exe is used, for isolated agent sessions. */
diff --git a/src/setup.ts b/src/setup.ts
index 807fbdb..12f5911 100644
--- a/src/setup.ts
+++ b/src/setup.ts
@@ -1,14 +1,16 @@
-import { execFile, spawn } from "node:child_process";
+import { execFile } from "node:child_process";
import { copyFile, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
import { createRequire } from "node:module";
import { tmpdir } from "node:os";
import path from "node:path";
import { fileURLToPath } from "node:url";
import { loadComputerConfig, readMachineSettings, type MachineConfig } from "./config.ts";
-import { PACKAGED_RUNTIME, fetchRuntime, isWsl, loadBundledRuntime, readRuntimePins } from "./native-runtime.ts";
+import { isWsl } from "./native-runtime.ts";
import { WINDOWS_POWERSHELL, localRunner, runPowerShell, sshRunner, type CommandRunner } from "./runner.ts";
import { MXC, PERCEPTION, WINDOWS_NODE } from "./setup-pins.ts";
-import { findWindowsNode } from "./windows-node.ts";
+import { ensureWindowsNode } from "./windows-node.ts";
+import { prepareRemoteBrowser } from "./remote-browser.ts";
+import { prepareRemoteRuntime } from "./remote-runtime.ts";
/** Optional parts and what each adds; `machine` prepares another machine instead of installing on one. */
export const SETUP_PARTS = [
@@ -157,21 +159,16 @@ async function browser(target: Target, signal?: AbortSignal): Promise<string> {
return node.installed ? `Installed Windows Node ${WINDOWS_NODE.version} on ${target.label}: ${node.exe}` : `Windows Node is already installed on ${target.label}: ${node.exe}`;
}
-function needsBrowserCopy(target: Target): never {
- throw new SetupError(`${target.label} has no browser worker yet; prepare it with setup part machine (ssh ${target.machine!.ssh}) first. Nothing was installed.`);
-}
-
async function firefox(target: Target, signal?: AbortSignal): Promise<string> {
const cli = path.join(path.dirname(createRequire(import.meta.url).resolve("playwright-core/package.json")), "cli.js");
let node: string, script: string;
if (target.machine) {
- if (!target.machine.node || !target.machine.package) needsBrowserCopy(target);
- node = target.machine.node;
- script = await windowsPath(target, `${target.machine.package}/node_modules/playwright-core/cli.js`);
+ const prepared = await prepareRemoteBrowser(target.runner, signal, { node: target.machine.node, package: target.machine.package });
+ node = prepared.node;
+ script = await windowsPath(target, `${prepared.package}/node_modules/playwright-core/cli.js`);
} else if (target.native) { node = process.execPath; script = cli; }
else {
- node = await findWindowsNode(target.interop)
- .catch(error => { throw new SetupError(`${error instanceof Error ? error.message : error} Firefox needs it too; install browser first.`); });
+ node = await ensureWindowsNode(target.interop, signal);
script = await windowsPath(target, cli);
}
const out = await target.runner.run(node, [script, "install", "firefox"], { timeoutMs: 900_000, ...(signal ? { signal } : {}) });
@@ -179,7 +176,7 @@ async function firefox(target: Target, signal?: AbortSignal): Promise<string> {
}
async function perception(target: Target, cwd: string, signal?: AbortSignal): Promise<string> {
- const driver = await windowsPath(target, target.machine ? target.machine.command : (await loadComputerConfig(cwd)).command);
+ const driver = await windowsPath(target, target.machine ? target.machine.command ?? await prepareRemoteRuntime(target.runner, signal) : (await loadComputerConfig(cwd)).command);
const { name, release, catalog, archive, version } = PERCEPTION;
const out = await ps(target, `
$driver = ${psString(driver)}
@@ -277,56 +274,17 @@ New-Item -ItemType Directory -Force -Path (Split-Path -Parent $argv) | Out-Null
return `Installed the Pi Browser Bridge into ${codeCmd} on ${target.label}. ${argvJson} ${next === undefined ? "already allows" : "now allows"} its proposed API. Quit VS Code fully and start it again; Reload Window does not reread argv.json.`;
}
-/** Stream a local folder into a fresh folder on the remote WSL through tar. */
-async function copyTree(runner: CommandRunner, from: string, to: string): Promise<void> {
- await runner.run("rm", ["-rf", to]);
- await runner.run("mkdir", ["-p", to]);
- await new Promise<void>((resolve, reject) => {
- const remote = runner.spawn("tar", ["-x", "-f", "-", "-C", to]);
- const pack = spawn("tar", ["-c", "-f", "-", "-C", from, "."], { stdio: ["ignore", "pipe", "pipe"] });
- let failed = "";
- pack.stderr.on("data", chunk => { failed += chunk; });
- remote.stderr.on("data", chunk => { failed += chunk; });
- pack.stdout.pipe(remote.stdin);
- pack.on("error", reject);
- remote.on("error", reject);
- remote.on("close", code => code === 0 ? resolve() : reject(new Error(`Copying ${path.basename(from)} failed: ${failed.trim().slice(-500)}`)));
- });
-}
-
async function prepareMachine(request: SetupRequest, deps: SetupDeps, progress: Progress, signal?: AbortSignal): Promise<string> {
const alias = request.ssh;
if (!alias || !/^[A-Za-z0-9][A-Za-z0-9._@-]{0,127}$/.test(alias)) throw new SetupError("machine needs the SSH alias of a Windows machine with WSL; nothing was installed.");
const name = request.name ?? alias;
if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(name) || name === "local") throw new SetupError("The machine name must be letters, digits, - or _, and not local.");
- const target: Target = { label: `machine ${name}`, runner: deps.ssh(alias), powershell: WINDOWS_POWERSHELL, native: false, machine: { ssh: alias, command: "" } };
- const { runner } = target;
-
- progress("checking the local runtime");
- const pins = await readRuntimePins();
- await fetchRuntime(PACKAGED_RUNTIME, pins, signal);
- const runtime = await loadBundledRuntime(PACKAGED_RUNTIME, pins);
- progress("copying the driver");
- const appData = await targetPath(target, await ps(target, "$env:LOCALAPPDATA", 30_000, signal));
- const folder = `${appData}/Programs/PiComputerUse/cua-driver-${pins.version}-${pins.source.slice(0, 8)}/runtime`;
- await runner.run("mkdir", ["-p", folder]);
- const names = Object.keys(pins.files);
- for (const file of names) await runner.run("dd", ["status=none", `of=${folder}/${file}`], { input: await readFile(path.join(runtime.root, "runtime", file)), timeoutMs: 600_000 });
- const sums = (await runner.run("sha256sum", names.map(file => `${folder}/${file}`))).trim().split("\n").map(line => line.split(" ")[0]);
- const bad = names.filter((file, index) => sums[index] !== pins.files[file]);
- if (bad.length) throw new SetupError(`The copied driver files do not match their pins (${bad.join(", ")}).`);
-
- progress("installing Windows Node");
- const node = await targetPath(target, (await installNode(target, signal)).exe);
- progress("copying the browser worker");
- const home = (await runner.run("bash", ["-c", 'printf %s "$HOME"'])).trim();
- const remotePackage = `${home}/.local/share/pi-computer-use/package`;
- await copyTree(runner, path.join(PACKAGE, "src"), `${remotePackage}/src`);
- await copyTree(runner, path.dirname(createRequire(import.meta.url).resolve("playwright-core/package.json")), `${remotePackage}/node_modules/playwright-core`);
- await runner.run("dd", ["status=none", `of=${remotePackage}/package.json`], { input: await readFile(path.join(PACKAGE, "package.json")) });
-
- const entry = { ssh: alias, runtime: "windows-desktop", command: `${folder}/cua-driver.exe`, node, package: remotePackage };
- return `Prepared ${alias} for computer use. Add this under "machines" in .pi/computer-use.json:\n${JSON.stringify({ [name]: entry }, null, 2)}`;
+ const runner = deps.ssh(alias);
+ progress("preparing the driver");
+ await prepareRemoteRuntime(runner, signal);
+ progress("preparing the browser worker");
+ await prepareRemoteBrowser(runner, signal);
+ return `Prepared ${alias} for computer use. Add this trusted machine under "machines" in .pi/computer-use.json:\n${JSON.stringify({ [name]: { ssh: alias } }, null, 2)}`;
}
const tail = (out: string) => {
diff --git a/src/web-browser.ts b/src/web-browser.ts
index 57c3030..5831da3 100644
--- a/src/web-browser.ts
+++ b/src/web-browser.ts
@@ -3,7 +3,8 @@ import { fileURLToPath } from "node:url";
import { promisify } from "node:util";
import type { CommandRunner } from "./runner.ts";
import { ATTACH_APPROVAL_MS } from "./browser-command-line.ts";
-import { findWindowsNode } from "./windows-node.ts";
+import { ensureWindowsNode } from "./windows-node.ts";
+import { RemotePreparationUncertain } from "./remote-provision-error.ts";
import { locatorSelector } from "./native-locator.ts";
const run = promisify(execFile);
@@ -436,7 +437,7 @@ export class WebBrowser {
child = runner.spawn(options.remote.node, ["--disable-warning=ExperimentalWarning", worker]);
} else {
if (process.platform === "linux") {
- command = await findWindowsNode(options.interop).catch((error: Error) => { throw new WebError(error.message); });
+ command = await ensureWindowsNode(options.interop, signal).catch((error: Error) => { throw new WebError(error.message, false, error instanceof RemotePreparationUncertain); });
worker = (await run("wslpath", ["-w", worker], { timeout: 5000 })).stdout.trim();
} else if (process.platform !== "win32") throw new WebError("The Playwright browser backend runs only on Windows or WSL.");
signal?.throwIfAborted();
diff --git a/src/windows-node.ts b/src/windows-node.ts
index 7abb0d0..37d8099 100644
--- a/src/windows-node.ts
+++ b/src/windows-node.ts
@@ -5,6 +5,10 @@ import { WINDOWS_NODE } from "./setup-pins.ts";
const INSTALLED_NODE = "/mnt/c/Program Files/nodejs/node.exe";
+export class WindowsNodeMissingError extends Error {
+ constructor() { super("Browsers need Node.js on Windows, and none is installed here. Ask the user to install it with /computer-setup browser (about 30 MB into their own folders), then open the browser again."); }
+}
+
/** Where setup part browser puts the pinned portable Node under a Local Application Data folder (WSL path). */
export function portableNodePath(localAppData: string): string {
return path.join(localAppData, "Programs", "PiComputerUse", `node-${WINDOWS_NODE.version}-win-x64`, "node.exe");
@@ -19,6 +23,11 @@ const exists = (file: string) => access(file).then(() => true, () => false);
export async function findWindowsNode(interop?: string, deps = { localAppData: windowsLocalAppData, exists }): Promise<string> {
const candidates = [portableNodePath(await deps.localAppData(interop)), INSTALLED_NODE];
for (const candidate of candidates) if (await deps.exists(candidate)) return candidate;
- throw new Error("Browsers need Node.js on Windows, and none is installed here. Ask the user to install it "
- + "with /computer-setup browser (about 30 MB into their own folders), then open the browser again.");
+ throw new WindowsNodeMissingError();
}
+
+/** Find a compatible Windows Node or prepare the package-managed executable on first browser use. */
+export async function ensureWindowsNode(interop?: string, signal?: AbortSignal): Promise<string> {
+ const [{ prepareWindowsNode }, { localRunner }] = await Promise.all([import("./remote-browser.ts"), import("./runner.ts")]);
+ return prepareWindowsNode(localRunner(interop), signal);
+}
\ No newline at end of file