@melaya/runner 1.1.68 → 1.1.70

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.1";
+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;