@melaya/runner 1.1.67 → 1.1.69

package/dist/computerHostCli.js

@@ -0,0 +1,808 @@
+/**
+ * Computer control hosted by the runner CLI: `npx @melaya/runner --computer`.
+ *
+ * On a headless Linux machine or VM (and on any computer without the Melaya
+ * desktop app) the runner itself hosts the computer executor: it starts the
+ * native helper for this platform (desktop/native/computer-linux on Linux; the
+ * Windows / macOS helpers speak the same protocol) and drives it over stdio
+ * exactly as the desktop app's helperProcess.ts does. The protocol is
+ * desktop/native/PROTOCOL.md (v1):
+ *
+ *   helper -> {"event":"ready",...}                     first line
+ *   host   -> {"id","op":"init","denyPatterns","selfPids"}            <- {"id","ok":true}
+ *   host   -> {"id","op":"capabilities"}                              <- {"id","capabilities"}
+ *   host   -> {"id","op":"ping"}                                      <- {"id","pong":true,"busy","current"}
+ *   host   -> {"id","op":"command","action","allowedAppIds","allowedApps","deadlineMs"}  <- {"id","result"}
+ *   host   -> {"op":"cancel","target?"}  /  {"op":"shutdown"}
+ *   helper -> events: target, user_input, log
+ *
+ * Like the desktop app, this host runs `batch` (step by step, per-step
+ * `expect`), `keep_awake` (systemd-inhibit / caffeinate) and `handoff` (no one
+ * is at a headless screen: unsupported) itself, and never sends them to the
+ * helper.
+ *
+ * computerRelay.ts (server socket <-> executor) loads this module lazily and
+ * calls createCliComputerHost({ send, verbose }) when the runner is not inside
+ * the desktop app. It returns null unless the CLI was started with --computer
+ * (enableCliComputerHost) or MELAYA_COMPUTER=1.
+ *
+ * Before anything reaches the helper this file enforces what the desktop app's
+ * bridge does (the runner cannot import desktop/): known kinds, batch limits,
+ * the allowlist, per-app tiers (the server's requiredTierOf,
+ * server/src/services/computer/computerEffects.ts) and a hard-deny list of apps
+ * no agent may touch (Melaya itself, authentication prompts, lock screens). The
+ * helper enforces the allowlist and tiers again per window.
+ *
+ * Helper binary: --computer-helper <path> or MELAYA_COMPUTER_HELPER, else
+ * <package>/native/<platform>-<arch>/, else the per-user cache
+ * ~/.melaya/computer/<version>/<platform>-<arch>/ where a pinned release (url +
+ * sha256 in HELPER_MANIFEST) is downloaded and verified. Types MIRROR
+ * packages/desktop-contract/src/computer.ts (this package cannot import it).
+ */
+import { spawn as rawNodeSpawn } from "child_process";
+import { trackChild } from "./processTree.js";
+// Tracked so runner shutdown stops the helper / inhibitor even if dispose()'s delayed kill never fires.
+const nodeSpawn = ((cmd, args, opts) => trackChild(rawNodeSpawn(cmd, args, opts)));
+import { createHash } from "crypto";
+import { chmodSync, existsSync, mkdirSync, renameSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { delimiter, dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { COMPUTER_HELPER_MANIFEST, COMPUTER_HELPER_VERSION } from "./computerHelperManifest.js";
+export const COMPUTER_ACTION_KINDS = [
+    "screen", "screenshot", "find", "get_text", "current_app", "list_windows", "list_apps", "list_displays",
+    "clipboard_read", "ocr", "wait", "hover", "move", "scroll",
+    "focus_window", "open_app", "open_url", "open_file", "click", "type", "press", "drag", "select", "set_value",
+    "toggle", "window", "clipboard_write", "file_dialog", "batch",
+    "zoom", "cursor_position", "read_table", "expect", "mouse", "hold_key", "select_text", "quit_app",
+    "save_dialog", "handoff", "keep_awake",
+];
+const READ_KINDS = new Set([
+    "screen", "screenshot", "find", "get_text", "current_app", "list_windows", "list_apps",
+    "list_displays", "clipboard_read", "ocr", "wait", "hover", "move", "scroll",
+    "zoom", "cursor_position", "read_table", "expect", "handoff", "keep_awake",
+]);
+const KIND_SET = new Set(COMPUTER_ACTION_KINDS);
+/** Kinds that do not act on an app window: an empty allowlist does not block them. */
+export const APP_INDEPENDENT_KINDS = new Set(["list_apps", "list_displays", "cursor_position", "keep_awake", "handoff"]);
+/** File handles need the desktop app's handle store (it sends `resolved.path`); the CLI has none. */
+const NEEDS_FILE_HANDLES = new Set(["open_file", "file_dialog", "save_dialog"]);
+export const COMPUTER_MAX_BATCH_STEPS = 100;
+const DEFAULT_DEADLINE_MS = 15_000;
+const MAX_DEADLINE_MS = 31 * 60_000;
+const PROTOCOL_VERSION = 1;
+// ── tiers (port of the server's requiredTierOf) ─────────────────────────────
+const TIER_RANK = { view: 0, click: 1, full: 2 };
+const NAVIGATION_KEYS = new Set([
+    "tab", "escape", "esc", "up", "down", "left", "right", "arrowup", "arrowdown", "arrowleft", "arrowright",
+    "home", "end", "pageup", "pagedown", "space",
+]);
+const MODIFIER_KEYS = new Set(["shift", "ctrl", "control", "alt", "option", "cmd", "command", "meta", "win", "super"]);
+function splitChord(keys) {
+    const parts = keys.split("+").map((p) => p.trim()).filter(Boolean);
+    const key = (parts.pop() || "").toLowerCase();
+    const mods = new Set(parts.map((m) => {
+        const l = m.toLowerCase();
+        if (l === "control")
+            return "ctrl";
+        if (l === "command" || l === "meta" || l === "super" || l === "win")
+            return "cmd";
+        if (l === "option")
+            return "alt";
+        return l;
+    }));
+    return { mods, key };
+}
+/** The lowest app tier that allows this action (same rule as the server and the helpers). */
+export function requiredTierOf(action) {
+    const kind = String(action.kind || "");
+    if (READ_KINDS.has(kind))
+        return "view";
+    switch (kind) {
+        case "focus_window":
+            return "view";
+        case "open_app":
+            return Array.isArray(action.args) && action.args.length > 0 ? "full" : "view";
+        case "click":
+        case "select":
+        case "toggle":
+        case "mouse":
+        case "select_text":
+            return "click";
+        case "window":
+            return action.op === "close" ? "full" : "click";
+        case "hold_key":
+            return MODIFIER_KEYS.has(String(action.key || "").toLowerCase()) ? "click" : "full";
+        case "press": {
+            const { mods, key } = splitChord(String(action.keys || ""));
+            const onlyShift = [...mods].every((m) => m === "shift");
+            return NAVIGATION_KEYS.has(key) && onlyShift ? "click" : "full";
+        }
+        case "batch": {
+            let worst = "view";
+            for (const s of (Array.isArray(action.steps) ? action.steps : [])) {
+                const t = requiredTierOf(s && typeof s === "object" ? s : {});
+                if (TIER_RANK[t] > TIER_RANK[worst])
+                    worst = t;
+            }
+            return worst;
+        }
+        default:
+            return "full";
+    }
+}
+// ── hard deny ───────────────────────────────────────────────────────────────
+/**
+ * Apps no agent may read or drive, whatever the allowlist says. Sent to the
+ * helper at init (it adds them to its own built-in list) and checked here for
+ * actions that name an app and for app / window lists coming back. Plain
+ * regexes valid in JS, .NET and Rust.
+ */
+export const HARD_DENY_SOURCES = [
+    "melaya",
+    // authentication prompts and privilege elevation
+    "polkit|pkexec|gksu|kdesu|lxsudo",
+    "pinentry|gcr-prompter|gnome-keyring|ssh-askpass|ksshaskpass|kwalletd",
+    "consent\\.exe|credentialuibroker|logonui|securityagent|coreautha|loginwindow",
+    // lock screens and greeters
+    "screensaver|light-locker|i3lock|swaylock|xsecurelock|slock|kscreenlocker|lockapp",
+    "^gdm|greeter|lightdm|sddm",
+];
+const HARD_DENY = HARD_DENY_SOURCES.map((s) => new RegExp(s, "i"));
+export function isHardDenied(appId) {
+    const s = String(appId || "").trim();
+    return !!s && HARD_DENY.some((re) => re.test(s));
+}
+// ── command policy (pure; tested) ───────────────────────────────────────────
+function errorResult(kind, code, message, elapsedMs = 0) {
+    return { ok: false, kind: kind || "screen", error: { code, message }, elapsedMs };
+}
+function asTier(v) {
+    return v === "view" || v === "click" || v === "full" ? v : null;
+}
+/**
+ * Everything the CLI host checks before a command reaches the helper: shape,
+ * kinds, batch limits, allowlist (minus hard-denied apps), the tier ceiling and
+ * the app an action names. Returns the sanitized allowlist to forward.
+ */
+export function checkCommand(msg) {
+    const action = (msg.action && typeof msg.action === "object" ? msg.action : null);
+    const kind = typeof action?.kind === "string" ? action.kind : "";
+    if (!action || !KIND_SET.has(kind))
+        return { ok: false, result: errorResult(kind || "screen", "invalid_action", `Unknown action kind "${kind}".`) };
+    if (kind === "batch") {
+        const steps = action.steps;
+        if (!Array.isArray(steps) || steps.length === 0)
+            return { ok: false, result: errorResult(kind, "invalid_action", "batch needs at least one step.") };
+        if (steps.length > COMPUTER_MAX_BATCH_STEPS)
+            return { ok: false, result: errorResult(kind, "invalid_action", `batch takes at most ${COMPUTER_MAX_BATCH_STEPS} steps.`) };
+        for (const s of steps) {
+            const sk = s && typeof s === "object" ? String(s.kind || "") : "";
+            if (sk === "batch")
+                return { ok: false, result: errorResult(kind, "invalid_action", "A batch cannot contain another batch.") };
+            if (!KIND_SET.has(sk))
+                return { ok: false, result: errorResult(kind, "invalid_action", `Unknown step kind "${sk}".`) };
+        }
+    }
+    // Allowlist: tiers from allowedApps win; bare ids are "full" (PROTOCOL.md §3). Hard-denied ids are dropped.
+    const tiers = new Map();
+    for (const id of Array.isArray(msg.allowedAppIds) ? msg.allowedAppIds : []) {
+        if (typeof id !== "string" || !id.trim())
+            continue;
+        tiers.set(id.trim().toLowerCase(), { appId: id.trim(), tier: "full" });
+    }
+    for (const a of Array.isArray(msg.allowedApps) ? msg.allowedApps : []) {
+        const appId = typeof a?.appId === "string" ? a.appId.trim() : "";
+        if (!appId)
+            continue;
+        const tier = asTier(a.tier);
+        if (tier)
+            tiers.set(appId.toLowerCase(), { appId, tier });
+        else
+            tiers.delete(appId.toLowerCase()); // an unknown tier never widens access
+    }
+    for (const [k, v] of [...tiers])
+        if (isHardDenied(v.appId))
+            tiers.delete(k);
+    const allowedApps = [...tiers.values()];
+    const allowedAppIds = allowedApps.map((a) => a.appId);
+    if (allowedApps.length === 0 && !APP_INDEPENDENT_KINDS.has(kind)) {
+        return { ok: false, result: errorResult(kind, "not_allowed", "No app is allowed on this computer yet. Ask the user to allow apps on the Computer Control page.") };
+    }
+    const need = requiredTierOf(action);
+    const named = (kind === "open_app" || kind === "quit_app") && typeof action.appId === "string" ? action.appId.trim() : "";
+    if (named) {
+        if (isHardDenied(named))
+            return { ok: false, result: errorResult(kind, "not_allowed", "Agents never open or quit that app.") };
+        const t = tiers.get(named.toLowerCase());
+        if (!t)
+            return { ok: false, result: errorResult(kind, "not_allowed", `${named} is not on the user's allowlist. Allowed apps: ${allowedAppIds.join(", ") || "none"}.`) };
+        const needNamed = kind === "quit_app" ? "full" : need;
+        if (TIER_RANK[t.tier] < TIER_RANK[needNamed]) {
+            return { ok: false, result: errorResult(kind, "tier_denied", `${named} is allowed at the "${t.tier}" tier, and ${kind} needs "${needNamed}".`) };
+        }
+    }
+    if (allowedApps.length > 0) {
+        const max = allowedApps.reduce((m, a) => (TIER_RANK[a.tier] > TIER_RANK[m] ? a.tier : m), "view");
+        if (TIER_RANK[need] > TIER_RANK[max]) {
+            return { ok: false, result: errorResult(kind, "tier_denied", `No allowed app has the "${need}" tier that ${kind} needs. Ask the user to raise an app's tier on the Computer Control page.`) };
+        }
+    }
+    const deadlineMs = Math.min(MAX_DEADLINE_MS, Math.max(1_000, Math.floor(Number(msg.deadlineMs) || DEFAULT_DEADLINE_MS)));
+    return { ok: true, action, allowedApps, allowedAppIds, deadlineMs };
+}
+// ── helper binary ───────────────────────────────────────────────────────────
+/**
+ * Pinned helper releases, one per platform-arch, from computerHelperManifest.ts:
+ * generated by the release job (desktop-release.yml,
+ * .github/scripts/write-computer-helper-manifest.mjs) with the published URL
+ * and its sha256, and committed with the release. A download is only ever
+ * accepted when its sha256 matches. Empty until the first release: use
+ * MELAYA_COMPUTER_HELPER or --computer-helper meanwhile.
+ */
+export const HELPER_VERSION = COMPUTER_HELPER_VERSION;
+export const HELPER_MANIFEST = { ...COMPUTER_HELPER_MANIFEST };
+export function platformKey(platform = process.platform, arch = process.arch) {
+    return `${platform}-${arch}`;
+}
+function binaryNames(platform) {
+    return platform === "win32" ? ["melaya-computer.exe"] : ["melaya-computer", "MelayaComputer"];
+}
+function packageDir() {
+    try {
+        return join(dirname(fileURLToPath(import.meta.url)), "..");
+    }
+    catch {
+        return process.cwd();
+    }
+}
+export function helperCacheDir(env = process.env) {
+    return join(env.MELAYA_HOME || join(homedir(), ".melaya"), "computer", HELPER_VERSION, platformKey());
+}
+/** Finds the helper binary on disk (no download). */
+export function resolveHelperPath(opts = {}) {
+    const env = opts.env ?? process.env;
+    const exists = opts.exists ?? existsSync;
+    const explicit = opts.helperPath || env.MELAYA_COMPUTER_HELPER;
+    if (explicit)
+        return exists(explicit) ? explicit : null;
+    const dirs = [join(packageDir(), "native", platformKey()), helperCacheDir(env)];
+    for (const d of dirs) {
+        for (const n of binaryNames(process.platform)) {
+            const p = join(d, n);
+            if (exists(p))
+                return p;
+        }
+    }
+    return null;
+}
+/** Downloads the pinned helper for this platform into the per-user cache and verifies its sha256. */
+export async function downloadHelper(opts = {}) {
+    const entry = (opts.manifest ?? HELPER_MANIFEST)[platformKey()];
+    if (!entry)
+        return null;
+    const fetchFn = opts.fetchFn ?? fetch;
+    const res = await fetchFn(entry.url);
+    if (!res.ok)
+        throw new Error(`helper download failed: HTTP ${res.status}`);
+    const buf = Buffer.from(await res.arrayBuffer());
+    const sum = createHash("sha256").update(buf).digest("hex");
+    if (sum !== entry.sha256.toLowerCase())
+        throw new Error("helper download failed: sha256 mismatch");
+    const dir = helperCacheDir(opts.env);
+    mkdirSync(dir, { recursive: true });
+    const target = join(dir, binaryNames(process.platform)[0]);
+    const tmp = `${target}.part`;
+    writeFileSync(tmp, buf);
+    if (process.platform !== "win32")
+        chmodSync(tmp, 0o755);
+    renameSync(tmp, target);
+    opts.log?.(`  [computer] helper ${HELPER_VERSION} downloaded and verified`);
+    return target;
+}
+export const HELPER_MISSING_MESSAGE = "The computer helper is not installed on this machine. Build it (desktop/native/computer-linux: ./build.sh) and start the runner with MELAYA_COMPUTER_HELPER=/path/to/melaya-computer, or pass --computer-helper.";
+/** Splits a byte stream into JSON objects, one per line; tolerant of partial chunks, CRLF and noise. */
+export class LineDecoder {
+    buf = "";
+    push(chunk, onObject, onNoise) {
+        this.buf += chunk;
+        let i;
+        while ((i = this.buf.indexOf("\n")) >= 0) {
+            const line = this.buf.slice(0, i).replace(/\r$/, "").trim();
+            this.buf = this.buf.slice(i + 1);
+            if (!line)
+                continue;
+            try {
+                const o = JSON.parse(line);
+                if (o && typeof o === "object" && !Array.isArray(o))
+                    onObject(o);
+                else
+                    onNoise?.(line);
+            }
+            catch {
+                onNoise?.(line);
+            }
+        }
+        // The host accepts lines up to 64 MiB (a 4K screenshot is ~10 MB); drop garbage beyond that.
+        if (this.buf.length > 64 * 1024 * 1024)
+            this.buf = "";
+    }
+}
+export class HelperProcess {
+    path;
+    opts;
+    child = null;
+    waiters = new Map();
+    aborted = new Map();
+    seq = 0;
+    restarts = [];
+    disposed = false;
+    starting = null;
+    readyResolve = null;
+    ready = null;
+    constructor(path, opts = {}) {
+        this.path = path;
+        this.opts = opts;
+    }
+    log(l) { this.opts.log?.(l); }
+    async start() {
+        if (this.child)
+            return;
+        if (this.disposed)
+            throw new Error("helper disposed");
+        this.starting ??= (async () => {
+            const spawnFn = this.opts.spawn ?? nodeSpawn;
+            const child = spawnFn(this.path, [], { stdio: ["pipe", "pipe", "pipe"], env: this.opts.env ?? process.env });
+            this.child = child;
+            const ready = new Promise((r) => { this.readyResolve = r; });
+            const dec = new LineDecoder();
+            child.stdout?.setEncoding("utf8");
+            child.stdout?.on("data", (d) => dec.push(d, (o) => this.onMessage(o), (l) => this.log(`  [computer] helper: ${l.slice(0, 200)}`)));
+            child.stderr?.setEncoding("utf8");
+            child.stderr?.on("data", (d) => { for (const l of String(d).split("\n"))
+                if (l.trim())
+                    this.log(`  [computer] helper: ${l.slice(0, 300)}`); });
+            child.stdin?.on("error", () => { });
+            child.on("exit", (code, signal) => this.onExit(child, code, signal));
+            child.on("error", (e) => { this.log(`  [computer] helper failed to start: ${e.message}`); this.onExit(child, null, null); });
+            // The helper announces itself before reading anything; older builds may not: do not wait forever.
+            await Promise.race([ready, new Promise((r) => setTimeout(r, 3_000).unref?.())]);
+            if (!this.child)
+                throw new Error("helper exited at start");
+            // Deny list + our own pid: the helper never treats Melaya or auth prompts as targets.
+            await this.request({ op: "init", protocolVersion: PROTOCOL_VERSION, denyPatterns: HARD_DENY_SOURCES, selfPids: [process.pid] }, 5_000).catch(() => undefined);
+        })().finally(() => { this.starting = null; });
+        return this.starting;
+    }
+    onMessage(o) {
+        // Events first: a `target` event carries the command id too and must never be taken for its reply.
+        if (typeof o.event === "string") {
+            if (o.event === "ready") {
+                this.ready = o;
+                this.readyResolve?.();
+            }
+            this.opts.onEvent?.(o);
+            return;
+        }
+        const id = typeof o.id === "string" ? o.id : (typeof o.id === "number" ? String(o.id) : "");
+        if (!id)
+            return;
+        const late = this.aborted.get(id);
+        if (late) {
+            clearTimeout(late);
+            this.aborted.delete(id);
+            return;
+        } // a cancelled command freed the lane
+        const w = this.waiters.get(id);
+        if (!w)
+            return;
+        this.waiters.delete(id);
+        clearTimeout(w.timer);
+        w.resolve(o);
+    }
+    onExit(child, code, signal) {
+        if (this.child !== child)
+            return;
+        this.child = null;
+        this.readyResolve?.();
+        for (const [id, w] of this.waiters) {
+            clearTimeout(w.timer);
+            w.reject(new Error(`helper exited (${signal || code})`));
+            this.waiters.delete(id);
+        }
+        for (const t of this.aborted.values())
+            clearTimeout(t);
+        this.aborted.clear();
+        if (!this.disposed) {
+            const now = Date.now();
+            this.restarts = this.restarts.filter((t) => now - t < 60_000);
+            this.restarts.push(now);
+            this.log(`  [computer] helper exited (${signal || code}); it restarts on the next command${this.restarts.length >= 3 ? " (crashing repeatedly)" : ""}`);
+        }
+    }
+    get crashLooping() {
+        return this.restarts.length >= 3;
+    }
+    /** Writes one request and waits for the line with the same id. */
+    async request(msg, timeoutMs) {
+        if (!this.child)
+            await this.start();
+        const child = this.child;
+        if (!child?.stdin)
+            throw new Error("helper not running");
+        const id = typeof msg.id === "string" && msg.id ? msg.id : `h${++this.seq}`;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.waiters.delete(id);
+                reject(new Error("helper timeout"));
+            }, timeoutMs);
+            this.waiters.set(id, { resolve, reject, timer });
+            try {
+                child.stdin.write(JSON.stringify({ ...msg, id }) + "\n");
+            }
+            catch (e) {
+                clearTimeout(timer);
+                this.waiters.delete(id);
+                reject(e);
+            }
+        });
+    }
+    /** Fire-and-forget line. */
+    send(msg) {
+        try {
+            this.child?.stdin?.write(JSON.stringify(msg) + "\n");
+        }
+        catch { /* helper gone */ }
+    }
+    /**
+     * Aborts one command (or every one). A command that has not answered `stopped`
+     * within the grace period gets the helper killed; it restarts on the next command.
+     */
+    cancel(target) {
+        this.send(target ? { op: "cancel", target } : { op: "cancel" });
+        if (!target || !this.child)
+            return;
+        const child = this.child;
+        this.aborted.set(target, setTimeout(() => {
+            this.aborted.delete(target);
+            if (this.child === child) {
+                this.log("  [computer] the helper did not stop in time: restarting it");
+                try {
+                    child.kill("SIGKILL");
+                }
+                catch { /* ignore */ }
+            }
+        }, this.opts.abortGraceMs ?? 3_000));
+    }
+    get running() {
+        return this.child !== null;
+    }
+    dispose() {
+        this.disposed = true;
+        for (const [, w] of this.waiters) {
+            clearTimeout(w.timer);
+            w.reject(new Error("helper disposed"));
+        }
+        this.waiters.clear();
+        for (const t of this.aborted.values())
+            clearTimeout(t);
+        this.aborted.clear();
+        const c = this.child;
+        this.child = null;
+        if (c) {
+            try {
+                c.stdin?.write(JSON.stringify({ op: "shutdown" }) + "\n");
+                c.stdin?.end();
+            }
+            catch { /* ignore */ }
+            setTimeout(() => { try {
+                c.kill();
+            }
+            catch { /* ignore */ } }, 1_000).unref?.();
+        }
+    }
+}
+// ── keep_awake (run by the host, PROTOCOL.md §7) ────────────────────────────
+function onPath(cmd, env) {
+    for (const d of String(env.PATH || "").split(delimiter)) {
+        if (d && existsSync(join(d, cmd)))
+            return true;
+    }
+    return false;
+}
+/** Holds a sleep inhibitor child process: systemd-inhibit (Linux) or caffeinate (macOS). */
+export class KeepAwake {
+    opts;
+    child = null;
+    constructor(opts = {}) {
+        this.opts = opts;
+    }
+    available() {
+        const env = this.opts.env ?? process.env;
+        const platform = this.opts.platform ?? process.platform;
+        if (platform === "linux" && onPath("systemd-inhibit", env))
+            return "systemd-inhibit";
+        if (platform === "darwin" && onPath("caffeinate", env))
+            return "caffeinate";
+        return null;
+    }
+    get active() {
+        return this.child !== null;
+    }
+    acquire() {
+        if (this.child)
+            return "already";
+        const tool = this.available();
+        if (!tool)
+            return null;
+        const spawnFn = this.opts.spawn ?? nodeSpawn;
+        const args = tool === "systemd-inhibit"
+            ? ["--what=idle:sleep", "--who=Melaya", "--why=An agent is using this computer", "--mode=block", "sleep", "infinity"]
+            : ["-dimsu"];
+        const child = spawnFn(tool, args, { stdio: ["pipe", "pipe", "pipe"], env: this.opts.env ?? process.env });
+        child.on("exit", () => { if (this.child === child)
+            this.child = null; });
+        child.on("error", () => { if (this.child === child)
+            this.child = null; });
+        this.child = child;
+        return tool;
+    }
+    release() {
+        const c = this.child;
+        this.child = null;
+        if (c) {
+            try {
+                c.kill();
+            }
+            catch { /* ignore */ }
+        }
+    }
+}
+let cliEnabled = false;
+let cliDefaults = {};
+/** Called by cli.ts for `--computer`: later createCliComputerHost() calls (from the relay) are enabled. */
+export function enableCliComputerHost(opts = {}) {
+    cliEnabled = true;
+    cliDefaults = { ...cliDefaults, ...opts };
+}
+export function isCliComputerEnabled(env = process.env) {
+    return cliEnabled || env.MELAYA_COMPUTER === "1" || env.MELAYA_COMPUTER === "true";
+}
+/** Test seam: forget enableCliComputerHost(). */
+export function _resetCliComputerHost() {
+    cliEnabled = false;
+    cliDefaults = {};
+}
+/** Real user input seen this recently pauses a batch (`user_interrupted`). */
+const USER_INPUT_PAUSE_MS = 1_500;
+export function createCliComputerHost(options = {}) {
+    const opts = { ...cliDefaults, ...options };
+    const env = opts.env ?? process.env;
+    const enabled = opts.enabled ?? isCliComputerEnabled(env);
+    if (!enabled)
+        return null;
+    const log = (l) => { if (opts.verbose || opts.log)
+        (opts.log ?? console.log)(l); };
+    let helper = null;
+    let helperPath = resolveHelperPath({ helperPath: opts.helperPath, env });
+    let resolving = null;
+    let caps;
+    let capsAt = 0;
+    let disposed = false;
+    let lastUserInput = 0;
+    const keepAwake = opts.keepAwake ?? new KeepAwake({ spawn: opts.spawn, env });
+    const ensureHelper = async () => {
+        if (disposed)
+            return null;
+        if (helper)
+            return helper;
+        if (!helperPath && opts.download !== false && !opts.helperPath && !env.MELAYA_COMPUTER_HELPER) {
+            resolving ??= downloadHelper({ env, log }).catch((e) => { log(`  [computer] ${e.message}`); return null; });
+            helperPath = await resolving;
+        }
+        if (!helperPath)
+            return null;
+        helper = new HelperProcess(helperPath, {
+            spawn: opts.spawn,
+            env,
+            log,
+            abortGraceMs: opts.abortGraceMs,
+            onEvent: (e) => {
+                if (e.event === "user_input") {
+                    lastUserInput = Date.now();
+                    log("  [computer] someone is using this computer: runs pause");
+                }
+                else if (e.event === "log") {
+                    log(`  [computer] ${String(e.message || "").slice(0, 300)}`);
+                }
+            },
+        });
+        return helper;
+    };
+    const capabilities = async () => {
+        if (caps !== undefined && Date.now() - capsAt < 60_000)
+            return caps;
+        const h = await ensureHelper();
+        if (!h) {
+            log(`  [computer] ${HELPER_MISSING_MESSAGE}`);
+            caps = null;
+            capsAt = Date.now();
+            return null;
+        }
+        try {
+            const reply = await h.request({ op: "capabilities" }, 10_000);
+            const c = reply.capabilities && typeof reply.capabilities === "object" ? reply.capabilities : null;
+            if (c) {
+                // What this host adds (batch, keep_awake) and cannot do (file handles, the hand-off overlay).
+                const kinds = new Set((Array.isArray(c.kinds) ? c.kinds : []).filter((k) => !NEEDS_FILE_HANDLES.has(k) && k !== "handoff"));
+                kinds.add("batch");
+                if (keepAwake.available())
+                    kinds.add("keep_awake");
+                else
+                    kinds.delete("keep_awake");
+                caps = { ...c, kinds: COMPUTER_ACTION_KINDS.filter((k) => kinds.has(k)), host: "cli" };
+            }
+            else {
+                caps = null;
+            }
+        }
+        catch (e) {
+            log(`  [computer] helper did not answer: ${e.message}`);
+            caps = null;
+        }
+        capsAt = Date.now();
+        return caps;
+    };
+    /** One action through the helper (never batch / keep_awake / handoff). */
+    const runOnHelper = async (id, action, allowedAppIds, allowedApps, deadlineMs) => {
+        const kind = String(action.kind || "screen");
+        const started = Date.now();
+        if (NEEDS_FILE_HANDLES.has(kind)) {
+            return errorResult(kind, "unsupported", "File handles need the Melaya desktop app; this computer runs the runner only. Ask the user for the file, or type a path they gave you into the app's own dialog.");
+        }
+        const h = await ensureHelper();
+        if (!h)
+            return errorResult(kind, "helper_unavailable", HELPER_MISSING_MESSAGE);
+        if (h.crashLooping && !h.running)
+            return errorResult(kind, "helper_unavailable", "The computer helper keeps crashing on this machine. Check the runner log (--verbose).");
+        try {
+            // The helper keeps its own deadline; the extra second covers the line round trip.
+            const reply = await h.request({ id, op: "command", action, allowedAppIds, allowedApps, deadlineMs }, deadlineMs + 1_000);
+            const result = reply.result;
+            if (!result || typeof result !== "object" || typeof result.ok !== "boolean") {
+                return errorResult(kind, "internal", "The computer helper answered without a result.", Date.now() - started);
+            }
+            return filterResult(result);
+        }
+        catch (e) {
+            const m = e.message || String(e);
+            if (m === "helper timeout") {
+                h.cancel(id);
+                return errorResult(kind, "timeout", "The computer did not finish before the deadline. Read the screen before retrying: the action may or may not have happened.", Date.now() - started);
+            }
+            return errorResult(kind, "helper_unavailable", `The computer helper stopped: ${m}`, Date.now() - started);
+        }
+    };
+    /** batch, run here step by step (PROTOCOL.md §7): per-step expect, onError, user-input pause, shared deadline. */
+    const runBatch = async (id, action, allowedAppIds, allowedApps, deadlineMs) => {
+        const started = Date.now();
+        const steps = action.steps || [];
+        const stopDefault = action.stopOnError !== false;
+        const results = [];
+        let failed = 0;
+        const left = () => deadlineMs - (Date.now() - started);
+        for (let i = 0; i < steps.length; i++) {
+            const step = steps[i];
+            const kind = String(step.kind || "");
+            let r;
+            let expectFailed = false;
+            if (i > 0 && Date.now() - lastUserInput < USER_INPUT_PAUSE_MS) {
+                r = errorResult(kind, "user_interrupted", "Someone started using the mouse or keyboard, so the batch paused here. Read the screen before continuing.");
+            }
+            else if (left() < 200) {
+                r = errorResult(kind, "timeout", "The batch ran out of time before this step.");
+            }
+            else if (kind === "keep_awake" || kind === "handoff") {
+                r = await runLocal(kind, step);
+            }
+            else {
+                const { expect: cond, onError: _onError, expectTimeoutMs, ...plain } = step;
+                r = await runOnHelper(`${id}.${i + 1}`, plain, allowedAppIds, allowedApps, Math.max(500, left()));
+                if (r.ok && cond && typeof cond === "object") {
+                    const timeoutMs = Math.min(Math.max(100, Number(expectTimeoutMs) || 2_000), Math.max(100, left() - 100));
+                    const ex = await runOnHelper(`${id}.${i + 1}e`, { kind: "expect", condition: cond, timeoutMs }, allowedAppIds, allowedApps, timeoutMs + 500);
+                    if (!ex.ok) {
+                        expectFailed = true;
+                        const em = ex.error?.message || "the expectation failed";
+                        r = { ok: false, kind, error: { code: ex.error?.code || "timeout", message: `The step ran but its expectation failed: ${em}` }, elapsedMs: r.elapsedMs };
+                    }
+                }
+            }
+            results.push(r);
+            if (!r.ok) {
+                failed++;
+                const code = String(r.error?.code || "internal");
+                const onError = step.onError === "continue" ? false : step.onError === "stop" ? true : stopDefault;
+                // A failed expectation follows onError; a stop, a timeout or a person at the keyboard always ends the batch.
+                const forced = !expectFailed && ["stopped", "timeout", "user_interrupted", "screen_locked", "secure_desktop"].includes(code);
+                if (onError || forced) {
+                    const msg = r.error?.message || "";
+                    return { ok: false, kind: "batch", error: { code, message: `Step ${i + 1} failed: ${msg}` }, steps: results, elapsedMs: Date.now() - started };
+                }
+            }
+        }
+        const text = failed === 0 ? `All ${results.length} steps done.` : `${results.length} steps run, ${failed} failed (onError continue).`;
+        return { ok: true, kind: "batch", text, steps: results, elapsedMs: Date.now() - started };
+    };
+    /** keep_awake and handoff, run by the host. */
+    const runLocal = async (kind, action) => {
+        if (kind === "handoff") {
+            return errorResult(kind, "unsupported", "No one is at this computer's screen to take over (runner-hosted computer). Ask the user in chat instead.");
+        }
+        if (action.on === false) {
+            keepAwake.release();
+            return { ok: true, kind, text: "The computer may sleep again.", elapsedMs: 0 };
+        }
+        const tool = keepAwake.acquire();
+        if (!tool)
+            return errorResult(kind, "unsupported", "No sleep inhibitor is available here (systemd-inhibit on Linux, caffeinate on macOS). Headless VMs usually never sleep; check the VM's power settings.");
+        return { ok: true, kind, text: `Keeping the computer awake (${tool}). Released on stop.`, elapsedMs: 0 };
+    };
+    const run = async (msg) => {
+        const check = checkCommand(msg);
+        if (!check.ok)
+            return check.result;
+        const kind = String(check.action.kind);
+        const id = typeof msg.id === "string" && msg.id ? msg.id : `cli${Date.now()}`;
+        if (kind === "keep_awake" || kind === "handoff")
+            return runLocal(kind, check.action);
+        if (kind === "batch")
+            return runBatch(id, check.action, check.allowedAppIds, check.allowedApps, check.deadlineMs);
+        return runOnHelper(id, check.action, check.allowedAppIds, check.allowedApps, check.deadlineMs);
+    };
+    const api = {
+        async handle(msg) {
+            if (!msg || typeof msg !== "object")
+                return;
+            if (msg.type === "computer.capabilities.request") {
+                const c = await capabilities();
+                const out = { type: "computer.capabilities", capabilities: c };
+                opts.send?.(out);
+                return out;
+            }
+            if (msg.type === "computer.stop") {
+                api.stopAll(msg.reason);
+                return;
+            }
+            if (msg.type === "computer.command") {
+                const id = typeof msg.id === "string" ? msg.id : "";
+                const result = await run(msg);
+                return { type: "computer.result", id, result };
+            }
+        },
+        capabilities,
+        stopAll(reason) {
+            log(`  [computer] stop (${String(reason || "stop").slice(0, 200)})`);
+            helper?.cancel();
+            keepAwake.release();
+        },
+        dispose() {
+            disposed = true;
+            keepAwake.release();
+            helper?.dispose();
+            helper = null;
+        },
+    };
+    return api;
+}
+/** Defense in depth on what goes back to the server: no hard-denied app in app / window lists. */
+function filterResult(r) {
+    const out = { ...r };
+    if (Array.isArray(out.apps))
+        out.apps = out.apps.filter((a) => !isHardDenied(String(a?.appId || "")));
+    if (Array.isArray(out.windows))
+        out.windows = out.windows.filter((w) => !isHardDenied(String(w?.appId || "")));
+    if (Array.isArray(out.steps))
+        out.steps = out.steps.map((s) => (s && typeof s === "object" ? filterResult(s) : s));
+    return out;
+}