A desktop coding agent with free access to frontier models.
TypeScript
import { execFile, spawn } from "node:child_process";
import { constants, existsSync, openSync } from "node:fs";
import { access, mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
import { homedir } from "node:os";
import { delimiter, dirname, join, resolve } from "node:path";
import { allocateFreePort, allocateFreePorts, listTargets, waitForCdp } from "@omnirush/cdp";
import {
desktopBootstrapPath,
globalOpencodeConfigDir,
opencodeDbCandidates,
omnirushEnvStorePath,
omnirushServerConfigPath,
omnirushServerDataDir,
} from "@omnirush/paths";
import { ensureDenStack } from "./den-stack.ts";
import { resolveEvalEngineValue } from "./eval-engine.ts";
import type { ChildProcess } from "node:child_process";
import type { DisposableHost, SurfaceHandle, ElectronSurfaceOptions, ChromeSurfaceOptions, DenServiceOptions, DenServiceHandle, ShareLinks } from "./types.ts";
type OrgMode = "single_org" | "multi_org";
export interface LocalHostOptions {
repoRoot: string;
rootDir?: string;
log(message: string): void;
}
export interface ElectronProfilePaths {
appDataDir: string;
bootstrapPath: string;
cacheHome: string;
configHome: string;
dataDir: string;
dataHome: string;
envStorePath: string;
homeDir: string;
localAppDataDir: string;
opencodeConfigDir: string;
root: string;
stateHome: string;
userDataDir: string;
}
export interface InstalledProductionDesktopState {
bootstrapPath: string;
dataDir: string;
envStorePath: string;
homeDir: string;
opencodeDb: string;
opencodeConfigDir: string;
serverConfigPath: string;
serverStatePath: string;
serverTokenStorePath: string;
workspaceStatePath: string;
}
export interface InstalledProductionDesktopStateOptions {
env?: NodeJS.ProcessEnv;
homeDir?: string;
platform?: NodeJS.Platform;
}
interface ElectronSurfaceEnvOptions {
appName: string;
appIdentifier: string;
port: number;
cdpPort: number;
}
interface SpawnedDetached {
child: ChildProcess;
pid: number;
}
interface SpawnDetachedOptions {
cwd: string;
env: NodeJS.ProcessEnv;
logPath: string;
}
const liveProfileRoots = new Set<string>();
export function registerLiveProfileRoot(profileRoot: string): void {
liveProfileRoots.add(resolve(profileRoot));
}
export function unregisterLiveProfileRoot(profileRoot: string): void {
liveProfileRoots.delete(resolve(profileRoot));
}
interface KillLocalPidOptions {
graceMs?: number;
log?: (message: string) => void;
}
export interface FreePortOptions {
log?: (message: string) => void;
}
const CDP_WAIT_TIMEOUT_MS = 120_000;
const KILL_GRACE_MS = 5_000;
const POLL_INTERVAL_MS = 250;
const DEFAULT_CHROME_START_URL = "about:blank";
const DEFAULT_DARWIN_CHROME = "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome";
const LINUX_CHROME_BINARIES = ["google-chrome", "chromium", "chromium-browser"];
let prepareSharedResourcesPromise: Promise<void> | null = null;
const delay = (ms: number) => new Promise((resolveDelay) => setTimeout(resolveDelay, ms));
function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === "object" && value !== null && !Array.isArray(value);
}
function isNonEmptyString(value: unknown): value is string {
return typeof value === "string" && value.length > 0;
}
function errorCode(error: unknown): string | null {
return isRecord(error) && typeof error.code === "string" ? error.code : null;
}
function messageText(error: unknown): string {
return error instanceof Error ? error.message : String(error);
}
function sanitizeSlug(value: string): string {
return value.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-|-$/g, "") || "surface";
}
function timestamp(): string {
return new Date().toISOString().replace(/[-:.TZ]/g, "").slice(0, 17);
}
function pnpmCommand(): string {
return process.platform === "win32" ? "pnpm.cmd" : "pnpm";
}
function needsShell(command: string): boolean {
return process.platform === "win32" && /\.(cmd|bat)$/i.test(command);
}
function executableOnPath(name: string, env: NodeJS.ProcessEnv, platform: string): string | null {
const rawPath = env.PATH ?? env.Path ?? "";
if (!rawPath) return null;
const pathDelimiter = platform === "win32" ? ";" : delimiter;
for (const entry of rawPath.split(pathDelimiter)) {
if (!entry) continue;
const candidate = join(entry, name);
if (existsSync(candidate)) return candidate;
}
return null;
}
function windowsChromeCandidates(env: NodeJS.ProcessEnv): string[] {
const roots = [env.LOCALAPPDATA, env.PROGRAMFILES, env["PROGRAMFILES(X86)"], env.ProgramFiles]
.filter(isNonEmptyString);
return roots.map((root) => join(root, "Google", "Chrome", "Application", "chrome.exe"));
}
function pidIsAlive(pid: number): boolean {
try {
process.kill(pid, 0);
return true;
} catch (error) {
return errorCode(error) !== "ESRCH";
}
}
function signalPid(pid: number, signal: NodeJS.Signals): boolean {
try {
process.kill(pid, signal);
return true;
} catch (error) {
if (errorCode(error) === "ESRCH") return false;
return false;
}
}
function signalProcessGroup(pid: number, signal: NodeJS.Signals): boolean {
if (process.platform === "win32") return false;
try {
process.kill(-pid, signal);
return true;
} catch (error) {
if (errorCode(error) === "ESRCH") return false;
return false;
}
}
function processGroupIsAlive(pid: number): boolean {
if (process.platform === "win32") return false;
try {
process.kill(-pid, 0);
return true;
} catch (error) {
return errorCode(error) !== "ESRCH";
}
}
async function waitUntilGone(pid: number, timeoutMs: number): Promise<boolean> {
const startedAt = Date.now();
while (Date.now() - startedAt < timeoutMs) {
if (!pidIsAlive(pid) && !processGroupIsAlive(pid)) return true;
await delay(POLL_INTERVAL_MS);
}
return !pidIsAlive(pid) && !processGroupIsAlive(pid);
}
function listeningPids(port: number): Promise<number[]> {
if (process.platform !== "darwin" && process.platform !== "linux") return Promise.resolve([]);
return new Promise((resolve, reject) => {
execFile(
"lsof",
[`-tiTCP:${port}`, "-sTCP:LISTEN"],
{ encoding: "utf8", timeout: 5_000 },
(error, stdout) => {
const code = isRecord(error) ? error.code : null;
if (error && code !== 1 && code !== "1") {
reject(error);
return;
}
const pids = stdout.split(/\s+/)
.map((value) => Number(value))
.filter((value) => Number.isInteger(value) && value > 0);
resolve([...new Set(pids)]);
},
);
});
}
function processGroupId(pid: number): Promise<number | null> {
if (process.platform === "win32") return Promise.resolve(null);
return new Promise((resolve) => {
execFile("ps", ["-o", "pgid=", "-p", String(pid)], { encoding: "utf8", timeout: 5_000 }, (error, stdout) => {
if (error) {
resolve(null);
return;
}
const pgid = Number(stdout.trim());
resolve(Number.isInteger(pgid) && pgid > 1 ? pgid : null);
});
});
}
/** Ensure no process is listening on a local TCP port, killing stale owners. */
export async function freePort(port: number, { log }: FreePortOptions = {}): Promise<void> {
if (!Number.isInteger(port) || port <= 0 || port > 65_535) {
throw new Error(`Port must be an integer from 1 to 65535, got ${port}.`);
}
if (process.platform !== "darwin" && process.platform !== "linux") return;
const deadline = Date.now() + 10_000;
const currentProcessGroup = await processGroupId(process.pid);
let pids = await listeningPids(port);
while (pids.length > 0 && Date.now() < deadline) {
for (const pid of pids) {
if (pid === process.pid) throw new Error(`Refusing to kill the current process listening on port ${port}.`);
const listenerGroup = await processGroupId(pid);
const killPid = listenerGroup !== null && currentProcessGroup !== null && listenerGroup !== currentProcessGroup
? listenerGroup
: pid;
const groupDetail = killPid === pid ? "" : ` in process group ${killPid}`;
log?.(`Port ${port} is still held by listener pid ${pid}${groupDetail}; stopping it.`);
await killLocalPid(killPid, { graceMs: 1_000, log });
}
await delay(100);
pids = await listeningPids(port);
}
if (pids.length > 0) {
throw new Error(`Port ${port} is still held by listener pid${pids.length === 1 ? "" : "s"} ${pids.join(", ")} after cleanup.`);
}
}
async function tailLines(filePath: string, lineCount: number): Promise<string> {
try {
const text = await readFile(filePath, "utf8");
return text.split(/\r?\n/).slice(-lineCount).join("\n");
} catch (error) {
return `Could not read ${filePath}: ${messageText(error)}`;
}
}
async function waitForPageTarget(cdpUrl: string, timeoutMs: number): Promise<void> {
const startedAt = Date.now();
let lastDetail = "no page targets yet";
while (Date.now() - startedAt < timeoutMs) {
try {
await waitForCdp(cdpUrl, {
timeoutMs: Math.min(1_000, Math.max(0, timeoutMs - (Date.now() - startedAt))),
});
const targets = await listTargets(cdpUrl, {
timeoutMs: Math.min(1_000, Math.max(0, timeoutMs - (Date.now() - startedAt))),
});
if (targets.some((target) => target.type === "page" && target.webSocketDebuggerUrl)) return;
lastDetail = `saw ${targets.length} targets, none were pages`;
} catch (error) {
lastDetail = messageText(error);
}
await delay(Math.min(POLL_INTERVAL_MS, Math.max(0, timeoutMs - (Date.now() - startedAt))));
}
throw new Error(`Timed out after ${timeoutMs}ms waiting for a page target at ${cdpUrl} (${lastDetail})`);
}
function spawnDetached(command: string, args: string[], { cwd, env, logPath }: SpawnDetachedOptions): SpawnedDetached {
const logFd = openSync(logPath, "a");
const child = spawn(command, args, {
cwd,
env,
detached: true,
shell: needsShell(command),
stdio: ["ignore", logFd, logFd],
});
child.unref();
if (!child.pid) throw new Error(`Could not spawn ${command}.`);
return { child, pid: child.pid };
}
function chromeArgs(cdpPort: number, profileDir: string, startUrl: string, headless: boolean): string[] {
const args = [
`--remote-debugging-port=${cdpPort}`,
`--user-data-dir=${profileDir}`,
"--window-size=1280,900",
"--no-first-run",
"--no-default-browser-check",
"--disable-popup-blocking",
// Avoid the Daytona preview h2 stall when ~28 dev chunks multiplex; h1.1 loads them, while plain-http local Den never negotiates h2.
"--disable-http2",
startUrl,
];
return headless ? ["--headless=new", ...args] : args;
}
async function waitForCdpOrExit(label: string, cdpUrl: string, spawned: SpawnedDetached, logPath: string, requirePageTarget = false): Promise<void> {
let exitDetail: string | null = null;
const exitPromise = new Promise<void>((_resolve, reject) => {
spawned.child.once("exit", async (code, signal) => {
const detail = signal ? `signal ${signal}` : `exit ${code ?? 0}`;
exitDetail = detail;
const tail = await tailLines(logPath, 40);
reject(new Error(`${label} process ${spawned.pid} stopped before CDP was ready (${detail}). Last 40 lines of ${logPath}:\n${tail}`));
});
});
const livenessPromise = new Promise<void>((_resolve, reject) => {
const timer = setInterval(async () => {
if (exitDetail || pidIsAlive(spawned.pid)) return;
clearInterval(timer);
const tail = await tailLines(logPath, 40);
reject(new Error(`${label} process ${spawned.pid} is not alive before CDP was ready. Last 40 lines of ${logPath}:\n${tail}`));
}, POLL_INTERVAL_MS);
timer.unref();
});
await Promise.race([
(requirePageTarget ? waitForPageTarget(cdpUrl, CDP_WAIT_TIMEOUT_MS) : waitForCdp(cdpUrl, { timeoutMs: CDP_WAIT_TIMEOUT_MS })).catch(async (error) => {
const tail = await tailLines(logPath, 40);
throw new Error(`${messageText(error)}. Last 40 lines of ${logPath}:\n${tail}`);
}),
exitPromise,
livenessPromise,
]);
}
async function runPrepareScript(scriptPath: string, outDir: string, desktopRoot: string): Promise<void> {
try {
await access(scriptPath, constants.R_OK);
} catch {
throw new Error(`Required Electron prepare helper is missing: ${scriptPath}`);
}
await new Promise<void>((resolveRun, reject) => {
execFile(process.execPath, [scriptPath, "--force", "--outdir", outDir], { cwd: desktopRoot, encoding: "utf8", maxBuffer: 16 * 1024 * 1024 }, (error, _stdout, stderr) => {
if (error) {
reject(new Error(`Electron shared resource prepare failed for ${scriptPath}: ${stderr || error.message}`));
return;
}
resolveRun();
});
});
}
async function prepareSharedElectronResources(repoRoot: string, log: (message: string) => void): Promise<void> {
if (process.env.OMNIRUSH_EVAL_ELECTRON_RESOURCES_PREPARED === "1") return;
if (!prepareSharedResourcesPromise) {
prepareSharedResourcesPromise = (async () => {
const desktopRoot = join(repoRoot, "apps", "desktop");
const scriptsRoot = join(desktopRoot, "scripts");
log("Preparing shared Electron sidecars/helpers once for local eval surfaces...");
await runPrepareScript(join(scriptsRoot, "prepare-sidecar.mjs"), join(desktopRoot, "resources", "sidecars"), desktopRoot);
await runPrepareScript(join(scriptsRoot, "prepare-computer-use-helper.mjs"), join(desktopRoot, "resources", "helpers"), desktopRoot);
})();
}
await prepareSharedResourcesPromise;
}
async function ensureElectronProfile(paths: ElectronProfilePaths): Promise<void> {
await Promise.all([
mkdir(paths.root, { recursive: true }),
mkdir(paths.userDataDir, { recursive: true }),
mkdir(paths.appDataDir, { recursive: true }),
mkdir(paths.localAppDataDir, { recursive: true }),
mkdir(paths.opencodeConfigDir, { recursive: true }),
mkdir(paths.dataDir, { recursive: true }),
mkdir(paths.homeDir, { recursive: true }),
mkdir(paths.configHome, { recursive: true }),
mkdir(paths.dataHome, { recursive: true }),
mkdir(paths.cacheHome, { recursive: true }),
mkdir(paths.stateHome, { recursive: true }),
]);
}
async function writeBootstrap(filePath: string, bootstrap: ElectronSurfaceOptions["bootstrap"]): Promise<void> {
if (!bootstrap) return;
await mkdir(dirname(filePath), { recursive: true });
await writeFile(
filePath,
`${JSON.stringify(bootstrap, null, 2)}\n`,
"utf8",
);
}
function cleanUrl(value: string): string {
return value.trim().replace(/\/+$/, "");
}
function isOrgMode(value: unknown): value is OrgMode {
return value === "single_org" || value === "multi_org";
}
async function runtimeOrgMode(webUrl: string): Promise<OrgMode> {
const response = await fetch(`${cleanUrl(webUrl)}/api/runtime-config`, { signal: AbortSignal.timeout(8_000) });
if (!response.ok) throw new Error(`runtime-config returned HTTP ${response.status}`);
const body: unknown = await response.json();
if (isRecord(body) && isOrgMode(body.orgMode)) return body.orgMode;
throw new Error("runtime-config response did not include orgMode");
}
export function electronProfilePaths(root: string): ElectronProfilePaths {
return {
appDataDir: join(root, "appdata"),
bootstrapPath: join(root, "bootstrap.json"),
cacheHome: join(root, "xdg-cache"),
configHome: join(root, "xdg-config"),
dataDir: join(root, "omnirush-data"),
dataHome: join(root, "xdg-data"),
envStorePath: join(root, "omnirush-env.json"),
homeDir: join(root, "home"),
localAppDataDir: join(root, "local-appdata"),
opencodeConfigDir: join(root, "opencode-config"),
root,
stateHome: join(root, "xdg-state"),
userDataDir: join(root, "electron-userdata"),
};
}
/**
* Where the HOST keeps pnpm's self-managed versions. The surface's fresh HOME
* hides this cache, and pnpm (packageManager pin vs the global binary) then
* re-downloads its pinned version from the network on EVERY spawn — observed
* on a Daytona sandbox as a 21MB download per Electron spawn that, when it
* failed once, degenerated into a self-sustaining recursive `pnpm add pnpm`
* cascade that outlived the spec run. Pointing PNPM_HOME at the host's real
* pnpm home keeps version redirection local and instant.
*/
function hostPnpmHome(): string | null {
const configured = process.env.PNPM_HOME?.trim();
if (configured) return configured;
if (process.platform === "darwin") return join(homedir(), "Library", "pnpm");
if (process.platform === "linux") {
const dataHome = process.env.XDG_DATA_HOME?.trim();
return join(dataHome || join(homedir(), ".local", "share"), "pnpm");
}
if (process.platform === "win32") {
const localAppData = process.env.LOCALAPPDATA?.trim();
return localAppData ? join(localAppData, "pnpm") : null;
}
return null;
}
/** Nothing listens on the discard port: every account and gateway call from an eval surface fails at once. */
export const EVAL_DEAD_GATEWAY_URL = "http://127.0.0.1:9/omnirush/v1";
export function electronSurfaceEnv(
paths: ElectronProfilePaths,
options: ElectronSurfaceEnvOptions,
overrides: Record<string, string> = {},
): Record<string, string> {
const pnpmHome = hostPnpmHome();
// Give local eval Electron surfaces isolated app data, config, and identity so
// they cannot affect the user's real desktop app.
return {
// No account: empty tokens and a dead gateway, so a source app on the
// owner's Mac cannot sign in from the legacy keychain entries or reach
// omnirush.ai. A spec that needs an account passes its own.
OMNIRUSH_ACCESS_TOKEN: "",
OMNIRUSH_REFRESH_TOKEN: "",
OMNIRUSH_GATEWAY_URL: EVAL_DEAD_GATEWAY_URL,
...(pnpmHome ? { PNPM_HOME: pnpmHome } : {}),
APPDATA: paths.appDataDir,
HOME: paths.homeDir,
LOCALAPPDATA: paths.localAppDataDir,
OMNIRUSH_DATA_DIR: paths.dataDir,
OMNIRUSH_DESKTOP_BOOTSTRAP_PATH: paths.bootstrapPath,
OMNIRUSH_DESKTOP_DISABLE_WORKSPACE_RECOVERY: "1",
OMNIRUSH_DEV_MODE: "1",
OMNIRUSH_ENV_STORE: paths.envStorePath,
...(resolveEvalEngineValue(process.env.OMNIRUSH_EVAL_ENGINE) === "v2" ? { OMNIRUSH_ENGINE_V2_PREVIEW: "1" } : {}),
OPENCODE_CONFIG_DIR: paths.opencodeConfigDir,
VITE_DISABLE_OMNIRUSH_MODELS: "1",
OMNIRUSH_ELECTRON_APP_IDENTIFIER: options.appIdentifier,
OMNIRUSH_ELECTRON_APP_NAME: options.appName,
OMNIRUSH_ELECTRON_DISABLE_PROTOCOL_REGISTRATION: "1",
OMNIRUSH_ELECTRON_REMOTE_DEBUG_PORT: String(options.cdpPort),
OMNIRUSH_ELECTRON_SKIP_SHARED_PREPARE: "1",
OMNIRUSH_ELECTRON_USE_MOCK_KEYCHAIN: "1",
OMNIRUSH_ELECTRON_USERDATA: paths.userDataDir,
PORT: String(options.port),
XDG_CACHE_HOME: paths.cacheHome,
XDG_CONFIG_HOME: paths.configHome,
XDG_DATA_HOME: paths.dataHome,
XDG_STATE_HOME: paths.stateHome,
...overrides,
};
}
export function liveSharedProductionStateEnv(state: InstalledProductionDesktopState): Record<string, string> {
return {
HOME: state.homeDir,
USERPROFILE: state.homeDir,
XDG_CONFIG_HOME: join(state.homeDir, ".config"),
XDG_DATA_HOME: join(state.homeDir, ".local", "share"),
XDG_CACHE_HOME: join(state.homeDir, ".cache"),
XDG_STATE_HOME: join(state.homeDir, ".local", "state"),
OMNIRUSH_DATA_DIR: state.dataDir,
OMNIRUSH_DESKTOP_BOOTSTRAP_PATH: state.bootstrapPath,
OMNIRUSH_DESKTOP_DISABLE_WORKSPACE_RECOVERY: "0",
OMNIRUSH_DESKTOP_WORKSPACE_STATE_PATH: state.workspaceStatePath,
OMNIRUSH_DEV_SHARED_STATE: "1",
OMNIRUSH_ENV_STORE: state.envStorePath,
OMNIRUSH_SERVER_CONFIG: state.serverConfigPath,
OMNIRUSH_SERVER_STATE_PATH: state.serverStatePath,
OMNIRUSH_SERVER_TOKEN_STORE_PATH: state.serverTokenStorePath,
OPENCODE_DB: state.opencodeDb,
OPENCODE_CONFIG_DIR: state.opencodeConfigDir,
};
}
async function requireInstalledPath(path: string, kind: "directory" | "file", label: string): Promise<void> {
let metadata;
try {
metadata = await stat(path);
} catch {
throw new Error(`${label} is unavailable at ${path}. Start the installed production OmniRush.ai desktop once and confirm its local state exists.`);
}
const matches = kind === "directory" ? metadata.isDirectory() : metadata.isFile();
if (!matches) throw new Error(`${label} at ${path} is not a ${kind}.`);
}
/** Resolve installed production stores without launching, copying, linking, or mutating them. */
export async function resolveInstalledProductionDesktopState(
options: InstalledProductionDesktopStateOptions = {},
): Promise<InstalledProductionDesktopState> {
const platform = options.platform ?? process.platform;
if (platform !== "darwin") {
throw new Error(`Live shared installed-production state is currently supported only on macOS; received ${platform}.`);
}
const env = options.env ?? process.env;
const homeDir = options.homeDir ?? homedir();
const dataDir = omnirushServerDataDir({ env, homeDir, platform });
await requireInstalledPath(dataDir, "directory", "Installed production OmniRush.ai data directory");
const userDataDir = join(homeDir, "Library", "Application Support", "ai.omnirush.desktop");
const workspaceStatePath = join(userDataDir, "omnirush-workspaces.json");
const serverTokenStorePath = join(userDataDir, "omnirush-server-tokens.json");
const serverStatePath = join(userDataDir, "omnirush-server-state.json");
const serverConfigPath = omnirushServerConfigPath({ env, homeDir, platform });
const envStorePath = omnirushEnvStorePath({ env, homeDir, platform });
const bootstrapPath = desktopBootstrapPath({ env, homeDir, platform, userDataDir });
const opencodeConfigDir = globalOpencodeConfigDir({ env, homeDir, platform });
for (const [path, label] of [
[workspaceStatePath, "Installed production workspace state"],
[serverTokenStorePath, "Installed production server token store"],
[serverStatePath, "Installed production server state"],
[serverConfigPath, "Installed production server config"],
[envStorePath, "Installed production environment store"],
[bootstrapPath, "Installed production desktop bootstrap"],
]) {
await requireInstalledPath(path, "file", label);
}
await requireInstalledPath(opencodeConfigDir, "directory", "Installed production OpenCode config directory");
const candidates = opencodeDbCandidates({
env,
homeDir,
platform,
defaultChannel: "latest",
});
let opencodeDb: string | undefined;
for (const candidate of candidates) {
const metadata = await stat(candidate).catch(() => null);
if (metadata?.isFile()) {
opencodeDb = candidate;
break;
}
}
if (!opencodeDb) {
throw new Error(
`Installed production OpenCode database is unavailable. Checked channel-aware candidates: ${candidates.join(", ")}.`,
);
}
return {
bootstrapPath,
dataDir,
envStorePath,
homeDir,
opencodeDb,
opencodeConfigDir,
serverConfigPath,
serverStatePath,
serverTokenStorePath,
workspaceStatePath,
};
}
export function resolveChromeBinary(env: NodeJS.ProcessEnv = process.env, platform: string = process.platform): string {
const configured = env.CHROME_BIN?.trim();
if (configured) return configured;
if (platform === "darwin") return DEFAULT_DARWIN_CHROME;
if (platform === "linux") {
for (const name of LINUX_CHROME_BINARIES) {
const resolved = executableOnPath(name, env, platform);
if (resolved) return resolved;
}
throw new Error(`Could not resolve Chrome binary on linux. Set CHROME_BIN or put one of ${LINUX_CHROME_BINARIES.join(", ")} on PATH.`);
}
if (platform === "win32") {
for (const candidate of windowsChromeCandidates(env)) {
if (existsSync(candidate)) return candidate;
}
throw new Error("Could not resolve Chrome binary on win32. Set CHROME_BIN or install Google Chrome in a standard location.");
}
throw new Error(`Could not resolve Chrome binary on unsupported platform ${platform}. Set CHROME_BIN.`);
}
export async function killLocalPid(pid: number, options: KillLocalPidOptions = {}): Promise<boolean> {
if (!Number.isInteger(pid) || pid <= 0) return false;
const rootWasAlive = pidIsAlive(pid);
if (process.platform === "win32") {
// Node cannot send console Ctrl-C to a detached Windows pnpm tree.
// Stop this host-owned tree, including Electron and its database workers.
if (!rootWasAlive) return false;
await new Promise<void>((resolveKill, reject) => {
execFile("taskkill", ["/PID", String(pid), "/T", "/F"], { encoding: "utf8", timeout: 10_000 }, (error, _stdout, stderr) => {
if (error && pidIsAlive(pid)) { reject(new Error("Could not stop owned Windows process tree " + pid + ": " + (stderr || error.message))); return; }
resolveKill();
});
});
await waitUntilGone(pid, KILL_GRACE_MS);
return true;
}
const graceMs = options.graceMs ?? KILL_GRACE_MS;
const sentGroup = signalProcessGroup(pid, "SIGINT");
const sentDirect = !sentGroup && rootWasAlive ? signalPid(pid, "SIGINT") : false;
if (!sentGroup && !sentDirect) return false;
if (sentGroup) options.log?.(`Sent SIGINT to process group ${pid}`);
if (sentDirect && !sentGroup) options.log?.(`Sent SIGINT to pid ${pid}`);
if (await waitUntilGone(pid, graceMs)) return true;
const killedGroup = signalProcessGroup(pid, "SIGKILL");
const killedDirect = pidIsAlive(pid) ? signalPid(pid, "SIGKILL") : false;
if (killedGroup) options.log?.(`Sent SIGKILL to process group ${pid}`);
else if (killedDirect) options.log?.(`Sent SIGKILL to pid ${pid}`);
await waitUntilGone(pid, 1_000);
return true;
}
export function ownedSurfaceFilePaths(handle: SurfaceHandle): string[] {
return handle.kind === "electron" && handle.profileDir && handle.meta?.profileOwner !== "caller"
? [handle.profileDir]
: [];
}
export async function removeOwnedSurfaceFiles(handle: SurfaceHandle): Promise<void> {
for (const path of ownedSurfaceFilePaths(handle)) {
await rm(path, { recursive: true, force: true });
}
}
/** Stop a detached eval Electron only when its process environment still names its isolated profile. */
export async function stopOwnedElectronSurface(pid: number, profileDir: string): Promise<void> {
if (!Number.isInteger(pid) || pid <= 1 || !profileDir.trim()) {
throw new Error("Detached Electron ownership requires a valid pid and profile directory.");
}
const processDescription = await new Promise<string>((resolveDescription, reject) => {
execFile("ps", ["eww", "-p", String(pid)], { encoding: "utf8", timeout: 5_000 }, (error, stdout) => {
if (error) {
reject(new Error(`Detached Electron process ${pid} is not running.`));
return;
}
resolveDescription(stdout);
});
});
if (!processDescription.includes(`OMNIRUSH_ELECTRON_USERDATA=${join(profileDir, "electron-userdata")}`)) {
throw new Error(`Refusing to stop pid ${pid}: it does not own the expected eval Electron profile.`);
}
await killLocalPid(pid);
await rm(profileDir, { recursive: true, force: true });
}
export async function pruneStaleSurfaceProfiles(
rootDir: string,
options: {
live?: ReadonlySet<string>;
log?: (message: string) => void;
kill?: (path: string) => Promise<void>;
},
): Promise<{ removed: string[]; kept: string[] }> {
const entries = await readdir(rootDir).catch(() => []);
const removed: string[] = [];
const kept: string[] = [];
const live = options.live ?? liveProfileRoots;
const kill = options.kill ?? ((path: string) => new Promise<void>((done) => {
execFile("pkill", ["-f", path], () => done());
}));
for (const entry of entries) {
const path = resolve(rootDir, entry);
if (live.has(path)) {
kept.push(path);
continue;
}
await kill(path);
await rm(path, { recursive: true, force: true });
removed.push(path);
}
options.log?.(`Cleared ${removed.length} stale profile director${removed.length === 1 ? "y" : "ies"} in ${rootDir} (kept ${kept.length} live).`);
return { removed, kept };
}
function explicitPort(url: string): number | null {
try {
const parsed = new URL(url);
if (parsed.hostname !== "127.0.0.1" && parsed.hostname !== "localhost" && parsed.hostname !== "::1") return null;
const port = Number(parsed.port);
return Number.isInteger(port) && port > 0 ? port : null;
} catch {
return null;
}
}
function surfacePorts(handle: SurfaceHandle): number[] {
const ports = new Set<number>();
const fromUrl = explicitPort(handle.cdpUrl);
if (fromUrl !== null) ports.add(fromUrl);
for (const value of [handle.meta?.vitePort, handle.meta?.cdpPort]) {
const port = Number(value);
if (Number.isInteger(port) && port > 0 && port <= 65_535) ports.add(port);
}
return [...ports];
}
export function createLocalHost(options: LocalHostOptions): DisposableHost {
// Surface profiles become the Electron process HOME. node-gyp/electron-rebuild
// generate Makefiles with unquoted include paths under that HOME, so a repo
// checkout on a path containing spaces breaks every native rebuild. The env
// override lets such machines park surfaces on a space-free path (e.g. /tmp).
const surfacesRootOverride = process.env.OMNIRUSH_EVAL_SURFACES_DIR?.trim();
const rootDir = options.rootDir ?? (surfacesRootOverride
? surfacesRootOverride
: join(options.repoRoot, "evals", "results", ".surfaces", String(process.pid)));
const log = options.log;
const spawnedSurfaces = new Set<SurfaceHandle>();
const denPorts = new Set<number>();
async function disposeKnownPorts(handle: SurfaceHandle): Promise<void> {
for (const port of surfacePorts(handle)) await freePort(port, { log });
}
async function disposeDenPorts(): Promise<void> {
for (const port of denPorts) await freePort(port, { log });
denPorts.clear();
}
// Containers (Daytona sandboxes) cannot use Chromium's SUID sandbox: the helper
// binary in a mounted pnpm store is not root-owned, and Electron aborts with
// "The SUID sandbox helper binary was found, but is not configured correctly".
// The desktop honours ELECTRON_EXTRA_LAUNCH_ARGS (apps/desktop/electron/main.mjs),
// so pass the container-safe switches when we detect a sandbox.
function insideContainerSandbox(env: NodeJS.ProcessEnv = process.env): boolean {
if ((env.DAYTONA_SANDBOX_ID ?? "").trim().length > 0) return true;
if ((env.OMNIRUSH_EVAL_CONTAINER_ELECTRON ?? "").trim() === "1") return true;
return existsSync("/daytona-secrets") || existsSync("/daytona-artifacts");
}
function containerLaunchArgs(existing: string | undefined): string | undefined {
if (!insideContainerSandbox()) return existing;
const needed = ["--no-sandbox", "--disable-gpu", "--disable-dev-shm-usage", "--enable-unsafe-swiftshader"];
const present = (existing ?? "").split(/\s+/).filter((entry) => entry.length > 0);
for (const arg of needed) if (!present.includes(arg)) present.push(arg);
return present.join(" ");
}
/**
* Spawning a desktop has environment preconditions that only this component can
* reasonably own. Callers should not have to know that Electron needs a live X
* server, or that a previous run's process may still hold a port.
*/
const sleepMs = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
async function displayAnswers(display: string): Promise<boolean> {
return new Promise((resolve) => {
execFile("xdpyinfo", ["-display", display], (error) => resolve(!error));
});
}
async function ensureDisplay(repoRoot: string, env: NodeJS.ProcessEnv, log: (message: string) => void): Promise<void> {
const display = (env.DISPLAY ?? "").trim();
if (!display) return;
if (await displayAnswers(display)) return;
// A stale /tmp/.X11-unix socket is not proof the server is alive: Electron
// exits with "Missing X server or $DISPLAY", which looks like a hung renderer.
const starter = join(repoRoot, ".devcontainer", "start-daytona-vnc.sh");
if (!existsSync(starter)) {
log(`Display ${display} is not answering and ${starter} is missing; Electron will fail to start.`);
return;
}
log(`Display ${display} is not answering; starting the virtual display...`);
spawnDetached("bash", [starter], { cwd: repoRoot, env, logPath: join(repoRoot, "evals", "results", "virtual-display.log") });
for (let attempt = 0; attempt < 30; attempt += 1) {
await sleepMs(2_000);
if (await displayAnswers(display)) {
log(`Display ${display} is live.`);
return;
}
}
log(`Display ${display} still not answering after 60s; Electron will fail to start.`);
}
/**
* Kill Electron processes from earlier runs of THIS host's surfaces, and delete
* the profile directories they left behind.
*
* Disposal removes a profile on the happy path, but every killed or failed run
* leaks one at ~50MB. Twenty-seven of them filled a 10GB sandbox to 99%, and the
* symptom was not "disk full" — it was the renderer failing to answer
* `Runtime.evaluate` for 240s, which reads exactly like a broken app. Pruning
* here is cheap and keeps that failure from being invented again.
*/
return {
kind: "local",
workspaceRoot: options.repoRoot,
async spawnElectron(name: string, opts: ElectronSurfaceOptions = {}): Promise<SurfaceHandle> {
if (opts.prepareSharedResources !== false) {
await prepareSharedElectronResources(options.repoRoot, log);
}
const spawnEnvForChecks: NodeJS.ProcessEnv = { ...process.env, ...opts.env };
if (insideContainerSandbox() && (spawnEnvForChecks.DISPLAY ?? "").trim().length === 0) spawnEnvForChecks.DISPLAY = ":99";
await ensureDisplay(options.repoRoot, spawnEnvForChecks, log);
if (opts.profileDir !== undefined && !opts.profileDir.trim()) {
throw new Error("Electron profileDir must not be empty.");
}
const callerOwnedProfile = opts.profileDir !== undefined;
if (!callerOwnedProfile) await pruneStaleSurfaceProfiles(rootDir, { live: liveProfileRoots, log });
const profileRoot = opts.profileDir ?? resolve(rootDir, `${sanitizeSlug(name)}-${timestamp()}-${process.pid}`);
if (!callerOwnedProfile) registerLiveProfileRoot(profileRoot);
const paths = electronProfilePaths(profileRoot);
await ensureElectronProfile(paths);
await writeBootstrap(paths.bootstrapPath, opts.bootstrap);
const [port, cdpPort] = await allocateFreePorts(2);
if (port === undefined || cdpPort === undefined) throw new Error("Could not allocate Electron Vite/CDP ports.");
const appName = `OmniRush.ai Eval ${name}`;
const appIdentifier = `ai.omnirush.desktop.eval.${sanitizeSlug(name)}`;
const isolationEnv = electronSurfaceEnv(paths, { appName, appIdentifier, port, cdpPort }, opts.env);
const env: NodeJS.ProcessEnv = { ...process.env, ...isolationEnv };
const launchArgs = containerLaunchArgs(env.ELECTRON_EXTRA_LAUNCH_ARGS);
if (launchArgs !== undefined) env.ELECTRON_EXTRA_LAUNCH_ARGS = launchArgs;
// appendSwitch() in the main process runs too late for the SUID sandbox
// check (it aborts in a child before our JS switches apply), so disable
// the sandbox at process start the way Electron documents.
if (insideContainerSandbox()) env.ELECTRON_DISABLE_SANDBOX = "1";
// Sandbox exec sessions do not export DISPLAY, but Xvfb is running on :99
// (see .devcontainer/start-daytona-electron.sh). Without it Electron
// segfaults instead of opening a window.
if (insideContainerSandbox() && (env.DISPLAY ?? "").trim().length === 0) env.DISPLAY = ":99";
const logPath = join(profileRoot, "electron.log");
const packagedBinary = opts.devCommand === undefined
? process.env.OMNIRUSH_EVAL_ELECTRON_BINARY?.trim()
: undefined;
let spawned: SpawnedDetached;
if (packagedBinary) {
await access(packagedBinary, constants.F_OK).catch(() => {
throw new Error(`OMNIRUSH_EVAL_ELECTRON_BINARY does not exist: ${packagedBinary}`);
});
log(`Starting local Electron surface ${name} from packaged binary ${packagedBinary} (CDP :${cdpPort})...`);
// An installed artifact must not resolve assets from the checkout's cwd.
spawned = spawnDetached(packagedBinary, [], { cwd: profileRoot, env, logPath });
} else {
log(`Starting local Electron surface ${name} (Vite :${port}, CDP :${cdpPort})...`);
// Launch pnpm's JS entry on Windows: a detached .cmd shell can exit
// without starting the app or forwarding its diagnostics.
const pnpmEntry = process.env.npm_execpath;
if (process.platform === "win32") {
// Workspace dev scripts use POSIX environment assignments.
// Keep the emulator scoped to this isolated eval process.
env.pnpm_config_shell_emulator = "true";
env.npm_config_shell_emulator = "true";
if (!pnpmEntry || !/pnpm\.(?:c|m)?js$/i.test(pnpmEntry) || !existsSync(pnpmEntry)) {
throw new Error("Run Windows Electron journeys through pnpm so npm_execpath names its JS entry.");
}
spawned = spawnDetached(process.execPath, [pnpmEntry, opts.devCommand ?? "dev:electron"], { cwd: options.repoRoot, env, logPath });
} else {
spawned = spawnDetached(pnpmCommand(), [opts.devCommand ?? "dev:electron"], { cwd: options.repoRoot, env, logPath });
}
}
const cdpUrl = `http://127.0.0.1:${cdpPort}`;
try {
await waitForCdpOrExit("Electron", cdpUrl, spawned, logPath, true);
} catch (error) {
await killLocalPid(spawned.pid, { log });
await Promise.all([
freePort(port, { log }),
freePort(cdpPort, { log }),
]).catch((cleanupError: unknown) => log(`Electron port cleanup failed: ${messageText(cleanupError)}`));
throw error;
}
const handle: SurfaceHandle = {
name,
kind: "electron",
hostKind: "local",
cdpUrl,
pid: spawned.pid,
profileDir: profileRoot,
meta: { vitePort: String(port), cdpPort: String(cdpPort), log: logPath, profileRoot, profileOwner: callerOwnedProfile ? "caller" : "host" },
};
spawnedSurfaces.add(handle);
return handle;
},
async spawnChrome(name: string, opts: ChromeSurfaceOptions = {}): Promise<SurfaceHandle> {
await pruneStaleSurfaceProfiles(rootDir, { live: liveProfileRoots, log });
const profileRoot = resolve(rootDir, `${sanitizeSlug(name)}-${timestamp()}-${process.pid}`);
registerLiveProfileRoot(profileRoot);
const profileDir = join(profileRoot, "chrome-profile");
await mkdir(profileDir, { recursive: true });
const cdpPort = await allocateFreePort();
const binary = resolveChromeBinary(process.env, process.platform);
const startUrl = opts.startUrl ?? DEFAULT_CHROME_START_URL;
const logPath = join(profileRoot, "chrome.log");
const env: NodeJS.ProcessEnv = { ...process.env };
const cdpUrl = `http://127.0.0.1:${cdpPort}`;
const launch = async (headless: boolean): Promise<SpawnedDetached> => {
const spawned = spawnDetached(binary, chromeArgs(cdpPort, profileDir, startUrl, headless), { cwd: profileRoot, env, logPath });
await writeFile(join(profileDir, "omnirush-eval-chrome.pid"), `${spawned.pid}\n`, "utf8");
try {
await waitForCdpOrExit("Chrome", cdpUrl, spawned, logPath);
} catch (error) {
await killLocalPid(spawned.pid, { log });
await freePort(cdpPort, { log })
.catch((cleanupError: unknown) => log(`Chrome port cleanup failed: ${messageText(cleanupError)}`));
throw error;
}
return spawned;
};
let spawned: SpawnedDetached;
try {
spawned = await launch(opts.headless === true || process.env.OMNIRUSH_EVAL_CHROME_HEADLESS === "1");
} catch (error) {
if (!messageText(error).includes("SIGTRAP")) throw error;
log(`Chrome surface ${name} exited with SIGTRAP under the windowed launch; retrying with --headless=new.`);
spawned = await launch(true);
}
const handle: SurfaceHandle = {
name,
kind: "chrome",
hostKind: "local",
cdpUrl,
pid: spawned.pid,
profileDir,
meta: { cdpPort: String(cdpPort), log: logPath, profileRoot },
};
spawnedSurfaces.add(handle);
return handle;
},
async startDen(opts: DenServiceOptions = {}): Promise<DenServiceHandle> {
if (opts.seed === "none") {
log("seed:none requested; local Den stack currently keeps the Acme demo seed, so continuing with the default seed.");
}
await ensureDenStack({ log, cdpCandidates: [], skipApp: true, orgMode: opts.orgMode });
const apiUrl = process.env.OMNIRUSH_EVAL_DEN_API_URL?.trim();
const webUrl = process.env.OMNIRUSH_EVAL_DEN_WEB_URL?.trim();
if (!apiUrl || !webUrl) throw new Error("Den stack did not export OMNIRUSH_EVAL_DEN_API_URL / OMNIRUSH_EVAL_DEN_WEB_URL.");
const orgMode = await runtimeOrgMode(webUrl);
const apiPort = explicitPort(apiUrl);
const webPort = explicitPort(webUrl);
if (apiPort !== null) denPorts.add(apiPort);
if (webPort !== null) denPorts.add(webPort);
return { webUrl, apiUrl, orgMode, hostKind: "local" };
},
async share(): Promise<ShareLinks> {
const links: ShareLinks = [];
const webUrl = process.env.OMNIRUSH_EVAL_DEN_WEB_URL?.trim();
const apiUrl = process.env.OMNIRUSH_EVAL_DEN_API_URL?.trim();
if (webUrl) links.push({ label: "Den Web", url: webUrl });
if (apiUrl) links.push({ label: "Den API", url: apiUrl });
return links;
},
async disposeSurface(handle: SurfaceHandle): Promise<void> {
if (handle.pid !== undefined) {
await killLocalPid(handle.pid, { log });
}
await disposeKnownPorts(handle);
await removeOwnedSurfaceFiles(handle);
if (handle.meta?.profileOwner !== "caller" && handle.meta?.profileRoot) unregisterLiveProfileRoot(handle.meta.profileRoot);
spawnedSurfaces.delete(handle);
},
async stop(): Promise<void> {
for (const handle of [...spawnedSurfaces]) await this.disposeSurface(handle);
await disposeDenPorts();
},
async [Symbol.asyncDispose](): Promise<void> {
for (const handle of [...spawnedSurfaces]) {
await this.disposeSurface(handle)
.catch((error: unknown) => log(`Local surface ${handle.name} cleanup failed: ${messageText(error)}`));
}
await disposeDenPorts()
.catch((error: unknown) => log(`Local Den port cleanup failed: ${messageText(error)}`));
},
};
}