@melaya/runner 1.1.67 → 1.1.69

package/dist/cli.js

@@ -17,7 +17,10 @@ import { Command } from "commander";
 import chalk from "chalk";
 import { reportInstallFailure } from "./installReport.js";
 import { connect } from "./connection.js";
-import { detectModels } from "./detect.js";
+import { scanProviders } from "./detect.js";
+import { isHosted, hostStatus, onHostMessage, sendToHost, waitForHostToken, exitHostedSoon } from "./hostChannel.js";
+import { markStage, onStage, startupComplete, startupTimings, formatStartupTimings } from "./startupTimings.js";
+import { readStartupCache, writeStartupCache } from "./startupCache.js";
 // Logo colors: cyan → blue → indigo gradient (matching melaya.org)
 const c1 = chalk.hex("#22D3EE").bold;
 const c2 = chalk.hex("#10B0F0").bold;
@@ -43,15 +46,55 @@ const BANNER = `
   ${br("▸")} ${dm("Local AI Pipeline Runner")}                      ${chalk.hex("#333")(`v${version}`)}
   ${br("─────────────────────────────────────────────────────")}
 `;
+// Inside the desktop app: give the last host message time to leave before exit.
+const flushHost = () => (isHosted() ? new Promise((r) => setTimeout(r, 300)) : Promise.resolve());
+// Desktop app "stop" (pause, disconnect, quit): run the graceful shutdown the
+// CLI already has for Ctrl+C. Newest SIGTERM handler first, so connection.ts
+// stops runs and assistant hosts before singleInstance.ts exits; the lock is
+// released on "exit" either way. Hard exit if nothing is listening yet.
+function stopHosted() {
+    const handlers = process.listeners("SIGTERM").slice().reverse();
+    exitHostedSoon(0, 5000);
+    for (const h of handlers) {
+        try {
+            h("SIGTERM");
+        }
+        catch { /* keep going */ }
+    }
+    if (handlers.length === 0)
+        process.exit(0);
+}
 async function main() {
+    const hosted = isHosted();
     const program = new Command()
         .name("melaya-runner")
-        .description("Run Melaya AI pipelines locally with your own models")
-        .requiredOption("--token <token>", "Runner token from the Melaya platform")
+        .description("Run Melaya AI pipelines locally with your own models");
+    // In the desktop app the token arrives over the host channel, never argv.
+    if (hosted)
+        program.option("--token <token>", "Runner token from the Melaya platform");
+    else
+        program.requiredOption("--token <token>", "Runner token from the Melaya platform");
+    program
         .option("--server <url>", "Server URL", "wss://api.melaya.org")
         .option("--verbose", "Show detailed logs", false)
+        .option("--computer", "Let Melaya agents operate allowed apps on this machine (headless Linux / VM)", false)
+        .option("--computer-helper <path>", "Path to the melaya-computer helper binary (default: MELAYA_COMPUTER_HELPER)")
+        .option("--diagnostics", "Print startup stage timings (config, socket, online, Python, model discovery)", false)
         .parse(process.argv);
     const opts = program.opts();
+    // --computer: this runner hosts the computer executor itself (computerHostCli.ts); the desktop app hosts its own.
+    if (opts.computer && !hosted) {
+        const { enableCliComputerHost } = await import("./computerHostCli.js");
+        enableCliComputerHost({ helperPath: opts.computerHelper, verbose: opts.verbose });
+    }
+    if (hosted) {
+        hostStatus("starting");
+        sendToHost({ type: "version", runnerVersion: version });
+        onHostMessage((msg) => { if (msg.type === "stop")
+            stopHosted(); });
+        opts.token = await waitForHostToken();
+    }
+    markStage("config");
     console.log(BANNER);
     // Single-instance guard: refuse to start if another runner is already running
     // on this machine. Two runners for one user fight over a single server-side
@@ -61,63 +104,128 @@ async function main() {
     const { acquireSingleInstanceLock } = await import("./singleInstance.js");
     const lock = acquireSingleInstanceLock();
     if (!lock.ok) {
+        hostStatus("blocked", `Another Melaya runner is already running on this computer (process ${lock.ownerPid}). Close it, then resume the runner.`);
         console.log(chalk.red(`  ✗ A Melaya runner is already running on this machine (pid ${lock.ownerPid}).`));
         console.log(chalk.gray("    Only one runner can run per machine. Stop the other one first"));
         console.log(chalk.gray(`    (e.g. \`kill ${lock.ownerPid}\`, or close its terminal), then start again.`));
         await reportInstallFailure("single_instance_locked", { token: opts.token, server: opts.server });
+        await flushHost();
         process.exit(1);
     }
-    // Detect Python. Fast path: a supported host interpreter (3.10–3.12). If the
-    // host only has an unsupported/newer Python (Homebrew now ships 3.13/3.14 as
-    // `python3`) — or none at all — we PROVISION a managed CPython 3.12 via uv, so
-    // the runner needs zero Python setup on the box. `venv` can't do this (it only
-    // wraps an existing interpreter); uv downloads a standalone one.
-    let python;
-    const py = await findPython();
-    if (py.ok) {
-        python = py.cmd;
-        console.log(chalk.green(`  ✓ Python: ${python} (3.${py.minor})`));
-    }
-    else {
-        console.log(chalk.yellow(`  ⚠ No supported host Python (need 3.${PY_MIN_MINOR}–3.${PY_MAX_MINOR}` +
-            `${py.foundVersion ? `; host has ${py.foundVersion}` : ""}) — provisioning one automatically`));
-        const { provisionPython } = await import("./uvBootstrap.js");
-        const provisioned = await provisionPython(`3.${PY_MAX_MINOR}`, (m) => console.log(chalk.gray(`    ${m}`)));
-        if (!provisioned) {
-            console.log(chalk.red(`  ✗ Could not auto-provision Python 3.${PY_MAX_MINOR}`));
-            console.log(chalk.gray("    Install a supported Python manually, then restart the runner:"));
-            console.log(chalk.gray("      macOS:   brew install python@3.12"));
-            console.log(chalk.gray("      Linux:   sudo apt install python3.12 python3.12-venv    (or: pyenv install 3.12)"));
-            console.log(chalk.gray("      Windows: winget install Python.Python.3.12"));
-            await reportInstallFailure("python_missing", {
-                token: opts.token, server: opts.server,
-                detail: py.foundVersion ? `host=${py.foundVersion}` : "none",
-            });
-            process.exit(1);
+    // Readiness (audit P1.2): connect FIRST with the last good model list from
+    // disk (or none), then resolve Python and scan model providers in parallel
+    // and publish the fresh list through `runner:models`. Before, Python probing,
+    // provisioning and a serial provider scan (up to ~24 s of timeouts) all ran
+    // before the socket even opened. Requests that need Python wait for it.
+    const cache = readStartupCache();
+    const pythonReady = resolvePython(cache.python);
+    const discovery = scanProviders();
+    const handle = await connect({
+        token: opts.token,
+        serverUrl: opts.server,
+        pythonPath: pythonReady,
+        models: cache.models ?? [],
+        verbose: opts.verbose,
+    });
+    say = (l) => handle.print(l);
+    // Fresh discovery: print it, publish it, remember it for the next start.
+    void discovery.then((scan) => {
+        reportModels(scan.models, (l) => handle.print(l));
+        if (opts.verbose || opts.diagnostics) {
+            const slow = scan.timedOut.length ? `; timed out: ${scan.timedOut.join(", ")}` : "";
+            handle.print(chalk.gray(`    model discovery ${scan.ms}ms (${Object.entries(scan.probeMs).map(([k, v]) => `${k} ${v}ms`).join(", ")}${slow})`));
+        }
+        handle.publishModels(scan.models);
+        writeStartupCache({ models: scan.models, modelsAt: Date.now() });
+        markStage("discovery_done");
+    }).catch(() => { markStage("discovery_done"); });
+    void pythonReady.then(async (python) => {
+        if (python) {
+            markStage("python_ready");
+            return;
+        }
+        // Same terminal failure as before the reorder: no usable Python, no runner.
+        console.log(chalk.red(`  ✗ Could not auto-provision Python 3.${PY_MAX_MINOR}`));
+        console.log(chalk.gray("    Install a supported Python manually, then restart the runner:"));
+        console.log(chalk.gray("      macOS:   brew install python@3.12"));
+        console.log(chalk.gray("      Linux:   sudo apt install python3.12 python3.12-venv    (or: pyenv install 3.12)"));
+        console.log(chalk.gray("      Windows: winget install Python.Python.3.12"));
+        await reportInstallFailure("python_missing", {
+            token: opts.token, server: opts.server,
+            detail: lastPythonFound ? `host=${lastPythonFound}` : "none",
+        });
+        hostStatus("error", `Could not set up Python 3.${PY_MAX_MINOR} for local AI runs. Check your internet connection, then resume the runner.`);
+        await flushHost();
+        process.exit(1);
+    });
+    // --diagnostics (and --verbose): the stage timeline once every stage is in, or after 2 min.
+    if (opts.diagnostics || opts.verbose) {
+        let printed = false;
+        const print = () => {
+            if (printed)
+                return;
+            printed = true;
+            const lines = formatStartupTimings().split("\n").map((l) => `    ${l}`).join("\n");
+            handle.print(chalk.gray(`\n  Startup timings (from process start):\n${lines}`));
+            if (opts.diagnostics)
+                handle.print(`startup-timings ${JSON.stringify(startupTimings().sinceStartMs)}`);
+        };
+        if (startupComplete())
+            print();
+        else {
+            const off = onStage(() => { if (startupComplete()) {
+                off();
+                print();
+            } });
+            setTimeout(() => { off(); print(); }, 120_000).unref?.();
         }
-        python = provisioned;
-        console.log(chalk.green(`  ✓ Python: ${python} (auto-provisioned 3.${PY_MAX_MINOR})`));
     }
-    // Detect local models
-    const models = await detectModels();
+}
+function reportModels(models, print) {
     if (models.length === 0) {
-        console.log(chalk.yellow("  ⚠ No local models detected (LM Studio / Ollama not running; Claude Code / Codex / GitHub Copilot not logged in)"));
-        console.log(chalk.gray("    Start LM Studio or Ollama, log in to Claude Code / Codex, or run `melaya-runner copilot login`, then restart the runner"));
+        print(chalk.yellow("  ⚠ No local models detected (LM Studio / Ollama not running; Claude Code / Codex / GitHub Copilot not logged in)"));
+        print(chalk.gray("    Start LM Studio or Ollama, log in to Claude Code / Codex, or run `melaya-runner copilot login`; the runner picks them up automatically"));
+        return;
     }
-    else {
-        for (const m of models) {
-            console.log(chalk.green(`  ✓ ${m.provider}: ${m.name}`));
+    for (const m of models)
+        print(chalk.green(`  ✓ ${m.provider}: ${m.name}`));
+}
+// The unsupported interpreter found during the last scan (for the failure report).
+let lastPythonFound;
+// Lines printed while the connect spinner may be spinning go through the
+// connection's printer once it exists (keeps the spinner line intact).
+let say = (l) => console.log(l);
+// Detect Python. Fast path: the interpreter that worked last time (one probe).
+// Then every candidate is probed IN PARALLEL (async, so the socket keeps
+// running) and the best one by preference order wins. If the host only has an
+// unsupported/newer Python (Homebrew now ships 3.13/3.14 as `python3`), or
+// none at all, we PROVISION a managed CPython 3.12 via uv, so the runner needs
+// zero Python setup on the box. `venv` can't do this (it only wraps an
+// existing interpreter); uv downloads a standalone one.
+async function resolvePython(cached) {
+    if (cached?.cmd) {
+        const v = await probePyVersion(cached.cmd);
+        if (v && v.major === 3 && v.minor >= PY_MIN_MINOR && v.minor <= PY_MAX_MINOR) {
+            say(chalk.green(`  ✓ Python: ${cached.cmd} (3.${v.minor}${cached.provisioned ? ", auto-provisioned" : ""})`));
+            return cached.cmd;
         }
     }
-    console.log();
-    // Connect to the server
-    await connect({
-        token: opts.token,
-        serverUrl: opts.server,
-        pythonPath: python,
-        models,
-        verbose: opts.verbose,
-    });
+    const py = await findPython();
+    if (py.ok) {
+        say(chalk.green(`  ✓ Python: ${py.cmd} (3.${py.minor})`));
+        writeStartupCache({ python: { cmd: py.cmd, minor: py.minor } });
+        return py.cmd;
+    }
+    lastPythonFound = py.foundVersion;
+    say(chalk.yellow(`  ⚠ No supported host Python (need 3.${PY_MIN_MINOR}–3.${PY_MAX_MINOR}` +
+        `${py.foundVersion ? `; host has ${py.foundVersion}` : ""}) — provisioning one automatically`));
+    const { provisionPython } = await import("./uvBootstrap.js");
+    const provisioned = await provisionPython(`3.${PY_MAX_MINOR}`, (m) => say(chalk.gray(`    ${m}`)));
+    if (!provisioned)
+        return null;
+    say(chalk.green(`  ✓ Python: ${provisioned} (auto-provisioned 3.${PY_MAX_MINOR})`));
+    writeStartupCache({ python: { cmd: provisioned, minor: PY_MAX_MINOR, provisioned: true } });
+    return provisioned;
 }
 // Supported CPython range for the runner's venv. agentscope and its native
 // deps (tiktoken, numpy, pydantic-core, curl_cffi via scrapling, sentence-
@@ -132,17 +240,21 @@ async function main() {
 const PY_MIN_MINOR = 10;
 const PY_MAX_MINOR = 12;
 async function probePyVersion(cmd) {
-    const { execSync } = await import("child_process");
-    try {
-        const out = execSync(`"${cmd}" --version`, { encoding: "utf-8", timeout: 5000, stdio: ["pipe", "pipe", "pipe"] }).trim();
-        const m = out.match(/Python (\d+)\.(\d+)/);
-        if (!m)
-            return null;
-        return { major: Number(m[1]), minor: Number(m[2]) };
-    }
-    catch {
-        return null;
-    }
+    const { execFile } = await import("child_process");
+    // Async (never blocks the socket) and no shell: the command is a fixed name or a cached path.
+    return new Promise((resolve) => {
+        try {
+            execFile(cmd, ["--version"], { encoding: "utf-8", timeout: 5000, windowsHide: true }, (err, stdout, stderr) => {
+                if (err)
+                    return resolve(null);
+                const m = `${stdout || ""}${stderr || ""}`.trim().match(/Python (\d+)\.(\d+)/);
+                resolve(m ? { major: Number(m[1]), minor: Number(m[2]) } : null);
+            });
+        }
+        catch {
+            resolve(null);
+        }
+    });
 }
 async function findPython() {
     const candidates = [];
@@ -165,17 +277,16 @@ async function findPython() {
     }
     // 3. Generic names last — accepted only if they resolve into the supported range.
     candidates.push("python3", "python");
+    // Probe all candidates at once; the preference order above still decides.
+    const unique = [...new Set(candidates)];
+    const versions = await Promise.all(unique.map((cmd) => probePyVersion(cmd)));
     let fallback; // a real 3.x that exists but is out of range
-    const seen = new Set();
-    for (const cmd of candidates) {
-        if (seen.has(cmd))
-            continue;
-        seen.add(cmd);
-        const v = await probePyVersion(cmd);
+    for (let i = 0; i < unique.length; i++) {
+        const v = versions[i];
         if (!v || v.major !== 3)
             continue;
         if (v.minor >= PY_MIN_MINOR && v.minor <= PY_MAX_MINOR)
-            return { ok: true, cmd, minor: v.minor };
+            return { ok: true, cmd: unique[i], minor: v.minor };
         if (!fallback)
             fallback = `Python ${v.major}.${v.minor}`;
     }
@@ -200,6 +311,8 @@ async function bootstrap() {
 }
 bootstrap().catch(async (e) => {
     console.error(chalk.red(`\n  Fatal: ${e.message}\n`));
+    // The full error goes to the app's log (stderr above); the status line stays generic.
+    hostStatus("error", "The runner stopped unexpectedly. Copy diagnostics for details.");
     // Token is parsed inside main(); recover it from argv so a crash BEFORE the
     // socket still reports. Only the STAGE is sent — never the error text, which
     // routinely carries file paths and usernames.
@@ -209,5 +322,6 @@ bootstrap().catch(async (e) => {
         token: tokArg ? tokArg.replace(/^--token[= ]?/, "") : undefined,
         server: srvArg ? srvArg.replace(/^--server[= ]?/, "") : undefined,
     });
+    await flushHost();
     process.exit(1);
 });

package/dist/computerHelperManifest.d.ts

@@ -0,0 +1,5 @@
+export declare const COMPUTER_HELPER_VERSION = "1.0.0";
+export declare const COMPUTER_HELPER_MANIFEST: Record<string, {
+    url: string;
+    sha256: string;
+} | undefined>;

package/dist/computerHelperManifest.js

@@ -0,0 +1,9 @@
+// GENERATED by .github/scripts/write-computer-helper-manifest.mjs in desktop-release.yml.
+// Do not edit by hand: commit the file the release job uploads (artifact
+// "computer-helper-manifest") once the helpers are published at these URLs.
+//
+// Pinned computer helper releases for the runner CLI host (computerHostCli.ts),
+// keyed by `${process.platform}-${process.arch}`. A download is only accepted
+// when its sha256 matches.
+export const COMPUTER_HELPER_VERSION = "1.0.0";
+export const COMPUTER_HELPER_MANIFEST = {};

package/dist/computerHostCli.d.ts

@@ -0,0 +1,233 @@
+/**
+ * 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 { type ChildProcess } from "child_process";
+export type ComputerAppTier = "view" | "click" | "full";
+export interface AllowedApp {
+    appId: string;
+    tier: ComputerAppTier;
+}
+export type ComputerRunnerToHost = {
+    type: "computer.command";
+    id: string;
+    action: unknown;
+    deadlineMs: number;
+    allowedAppIds: string[];
+    allowedApps?: AllowedApp[];
+} | {
+    type: "computer.stop";
+    reason: string;
+} | {
+    type: "computer.capabilities.request";
+};
+export type ComputerHostToRunner = {
+    type: "computer.result";
+    id: string;
+    result: ComputerResultLike;
+} | {
+    type: "computer.capabilities";
+    capabilities: ComputerCapabilitiesLike | null;
+};
+export type ComputerResultLike = Record<string, unknown> & {
+    ok: boolean;
+    kind: string;
+    elapsedMs: number;
+};
+export type ComputerCapabilitiesLike = Record<string, unknown> & {
+    platform: string;
+    backend: string;
+    kinds: string[];
+    host?: "desktop" | "cli";
+};
+export declare const COMPUTER_ACTION_KINDS: readonly ["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"];
+/** Kinds that do not act on an app window: an empty allowlist does not block them. */
+export declare const APP_INDEPENDENT_KINDS: Set<string>;
+export declare const COMPUTER_MAX_BATCH_STEPS = 100;
+/** The lowest app tier that allows this action (same rule as the server and the helpers). */
+export declare function requiredTierOf(action: Record<string, unknown>): ComputerAppTier;
+/**
+ * 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 declare const HARD_DENY_SOURCES: string[];
+export declare function isHardDenied(appId: string): boolean;
+export type PolicyCheck = {
+    ok: true;
+    action: Record<string, unknown>;
+    allowedApps: AllowedApp[];
+    allowedAppIds: string[];
+    deadlineMs: number;
+} | {
+    ok: false;
+    result: ComputerResultLike;
+};
+/**
+ * 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 declare function checkCommand(msg: {
+    action?: unknown;
+    allowedAppIds?: unknown;
+    allowedApps?: unknown;
+    deadlineMs?: unknown;
+}): PolicyCheck;
+/**
+ * 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 declare const HELPER_VERSION = "1.0.0";
+export declare const HELPER_MANIFEST: Record<string, {
+    url: string;
+    sha256: string;
+} | undefined>;
+export declare function platformKey(platform?: string, arch?: string): string;
+export declare function helperCacheDir(env?: NodeJS.ProcessEnv): string;
+/** Finds the helper binary on disk (no download). */
+export declare function resolveHelperPath(opts?: {
+    helperPath?: string;
+    env?: NodeJS.ProcessEnv;
+    exists?: (p: string) => boolean;
+}): string | null;
+/** Downloads the pinned helper for this platform into the per-user cache and verifies its sha256. */
+export declare function downloadHelper(opts?: {
+    env?: NodeJS.ProcessEnv;
+    fetchFn?: typeof fetch;
+    log?: (l: string) => void;
+    manifest?: typeof HELPER_MANIFEST;
+}): Promise<string | null>;
+export declare 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.";
+export type SpawnFn = (command: string, args: string[], options: {
+    stdio: ["pipe", "pipe", "pipe"];
+    env?: NodeJS.ProcessEnv;
+}) => ChildProcess;
+/** Splits a byte stream into JSON objects, one per line; tolerant of partial chunks, CRLF and noise. */
+export declare class LineDecoder {
+    private buf;
+    push(chunk: string, onObject: (o: Record<string, unknown>) => void, onNoise?: (line: string) => void): void;
+}
+export interface HelperOptions {
+    spawn?: SpawnFn;
+    env?: NodeJS.ProcessEnv;
+    log?: (l: string) => void;
+    onEvent?: (e: Record<string, unknown>) => void;
+    /** How long a cancelled command may take to answer before the helper is killed (PROTOCOL.md §5). */
+    abortGraceMs?: number;
+}
+export declare class HelperProcess {
+    private readonly path;
+    private readonly opts;
+    private child;
+    private waiters;
+    private aborted;
+    private seq;
+    private restarts;
+    private disposed;
+    private starting;
+    private readyResolve;
+    ready: Record<string, unknown> | null;
+    constructor(path: string, opts?: HelperOptions);
+    private log;
+    start(): Promise<void>;
+    private onMessage;
+    private onExit;
+    get crashLooping(): boolean;
+    /** Writes one request and waits for the line with the same id. */
+    request(msg: Record<string, unknown>, timeoutMs: number): Promise<Record<string, unknown>>;
+    /** Fire-and-forget line. */
+    send(msg: Record<string, unknown>): void;
+    /**
+     * 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?: string): void;
+    get running(): boolean;
+    dispose(): void;
+}
+/** Holds a sleep inhibitor child process: systemd-inhibit (Linux) or caffeinate (macOS). */
+export declare class KeepAwake {
+    private readonly opts;
+    private child;
+    constructor(opts?: {
+        spawn?: SpawnFn;
+        env?: NodeJS.ProcessEnv;
+        platform?: string;
+    });
+    available(): string | null;
+    get active(): boolean;
+    acquire(): string | null;
+    release(): void;
+}
+export interface CliComputerHostOptions {
+    /** Results / capabilities pushed outside a handle() call (the relay's executor callback). */
+    send?: (msg: ComputerHostToRunner) => void;
+    verbose?: boolean;
+    /** Path to the helper binary (else MELAYA_COMPUTER_HELPER, the package's native/ folder, the per-user cache). */
+    helperPath?: string;
+    /** Force on / off (else enableCliComputerHost() or MELAYA_COMPUTER=1). */
+    enabled?: boolean;
+    /** Download the pinned helper when none is installed (default: true). */
+    download?: boolean;
+    env?: NodeJS.ProcessEnv;
+    spawn?: SpawnFn;
+    log?: (line: string) => void;
+    /** Test seam for keep_awake. */
+    keepAwake?: KeepAwake;
+    abortGraceMs?: number;
+}
+export interface CliComputerHostApi {
+    handle(msg: ComputerRunnerToHost): Promise<ComputerHostToRunner | void>;
+    capabilities(): Promise<ComputerCapabilitiesLike | null>;
+    stopAll(reason: string): void;
+    dispose(): void;
+}
+/** Called by cli.ts for `--computer`: later createCliComputerHost() calls (from the relay) are enabled. */
+export declare function enableCliComputerHost(opts?: Partial<CliComputerHostOptions>): void;
+export declare function isCliComputerEnabled(env?: NodeJS.ProcessEnv): boolean;
+/** Test seam: forget enableCliComputerHost(). */
+export declare function _resetCliComputerHost(): void;
+export declare function createCliComputerHost(options?: CliComputerHostOptions): CliComputerHostApi | null;