@melaya/runner 1.1.68 → 1.1.69

package/dist/computerRelay.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Computer control relay: the server's runner socket <-> the computer executor.
+ *
+ * Path of one command (packages/desktop-contract/src/computer.ts):
+ *   server dispatchComputerCommand
+ *     -> socket "computer:command" { id, action, deadlineMs, allowedAppIds, allowedApps } + ack
+ *     -> this relay -> host channel { type: "computer.command", ... }   (desktop app main process)
+ *     <- { type: "computer.result", id, result } -> ack(result)
+ *
+ * Who executes:
+ *   - inside the Melaya desktop app (isHosted()): the app's executor, over the
+ *     utilityProcess parent port (hostChannel.ts);
+ *   - plain `npx @melaya/runner --computer` on a headless machine / VM: the CLI
+ *     computer host (computerHostCli.ts, createCliComputerHost), when enabled;
+ *   - otherwise: every command is answered `unsupported`.
+ *
+ * The relay enforces the deadline on its side too: a command that has no
+ * result by `deadlineMs` is acked as a timeout, and a late result is dropped.
+ * `computer:stop` is forwarded at once. Capabilities are reported on every
+ * (re)connect and whenever the executor reports a change.
+ *
+ * Message types MIRROR the contract (this package cannot import it).
+ */
+import { type HostToRunnerMessage, type RunnerToHostMessage } from "./hostChannel.js";
+export declare const COMPUTER_EVENTS: {
+    readonly command: "computer:command";
+    readonly stop: "computer:stop";
+    readonly capabilities: "computer:capabilities";
+    /** server -> runner: show a native approval dialog { approvalId, summary, effect, appName?, expiresAt } */
+    readonly approval: "computer:approval";
+    /** server -> runner: close it (decided elsewhere or expired) { approvalId } */
+    readonly approvalClosed: "computer:approval-closed";
+    /** runner -> server: the user's answer in the dialog { approvalId, decision } */
+    readonly approvalAnswer: "computer:approval-answer";
+};
+export declare const UNSUPPORTED_MESSAGE = "Computer control needs the Melaya desktop app on this computer.";
+/** The parts of a socket.io-client Socket the relay uses (tests pass a fake). */
+export interface RelaySocket {
+    connected?: boolean;
+    on(event: string, listener: (...args: any[]) => void): unknown;
+    emit(event: string, ...args: any[]): unknown;
+}
+/** The computer executor the runner CLI hosts on a headless machine
+ *  (packages/runner/src/computerHostCli.ts). Results may come back from
+ *  `handle` or through the `send` callback given at creation. */
+export interface CliComputerHost {
+    handle(msg: RunnerToHostMessage): unknown;
+    capabilities(): unknown;
+    stopAll(reason: string): void;
+    dispose(): void;
+}
+export interface ComputerRelayDeps {
+    isHosted(): boolean;
+    sendToHost(msg: RunnerToHostMessage): void;
+    onHostMessage(cb: (msg: HostToRunnerMessage) => void): () => void;
+    /** Create the CLI host (null when computer control is not enabled for the CLI). */
+    createCliHost(opts: {
+        send: (msg: HostToRunnerMessage) => void;
+        verbose?: boolean;
+    }): Promise<CliComputerHost | null>;
+    log(line: string): void;
+}
+/**
+ * Attach the relay to the runner's server socket. Call once, right after the
+ * socket is created (before it connects). Returns a disposer.
+ */
+export declare function attachComputerRelay(socket: RelaySocket, opts?: {
+    verbose?: boolean;
+    deps?: Partial<ComputerRelayDeps>;
+}): {
+    dispose(): void;
+    pendingCount(): number;
+};

package/dist/computerRelay.js

@@ -0,0 +1,280 @@
+/**
+ * Computer control relay: the server's runner socket <-> the computer executor.
+ *
+ * Path of one command (packages/desktop-contract/src/computer.ts):
+ *   server dispatchComputerCommand
+ *     -> socket "computer:command" { id, action, deadlineMs, allowedAppIds, allowedApps } + ack
+ *     -> this relay -> host channel { type: "computer.command", ... }   (desktop app main process)
+ *     <- { type: "computer.result", id, result } -> ack(result)
+ *
+ * Who executes:
+ *   - inside the Melaya desktop app (isHosted()): the app's executor, over the
+ *     utilityProcess parent port (hostChannel.ts);
+ *   - plain `npx @melaya/runner --computer` on a headless machine / VM: the CLI
+ *     computer host (computerHostCli.ts, createCliComputerHost), when enabled;
+ *   - otherwise: every command is answered `unsupported`.
+ *
+ * The relay enforces the deadline on its side too: a command that has no
+ * result by `deadlineMs` is acked as a timeout, and a late result is dropped.
+ * `computer:stop` is forwarded at once. Capabilities are reported on every
+ * (re)connect and whenever the executor reports a change.
+ *
+ * Message types MIRROR the contract (this package cannot import it).
+ */
+import { isHosted, onHostMessage, sendToHost } from "./hostChannel.js";
+export const COMPUTER_EVENTS = {
+    command: "computer:command",
+    stop: "computer:stop",
+    capabilities: "computer:capabilities",
+    /** server -> runner: show a native approval dialog { approvalId, summary, effect, appName?, expiresAt } */
+    approval: "computer:approval",
+    /** server -> runner: close it (decided elsewhere or expired) { approvalId } */
+    approvalClosed: "computer:approval-closed",
+    /** runner -> server: the user's answer in the dialog { approvalId, decision } */
+    approvalAnswer: "computer:approval-answer",
+};
+export const UNSUPPORTED_MESSAGE = "Computer control needs the Melaya desktop app on this computer.";
+const MIN_DEADLINE_MS = 1_000;
+const MAX_DEADLINE_MS = 31 * 60_000;
+const MAX_PENDING = 64;
+// The CLI host module is optional (it may be absent from a build): load it by
+// a variable specifier so this file compiles and runs without it.
+const CLI_HOST_MODULE = "./computerHostCli.js";
+const liveDeps = {
+    isHosted,
+    sendToHost,
+    onHostMessage,
+    createCliHost: async (opts) => {
+        try {
+            const m = (await import(CLI_HOST_MODULE));
+            return typeof m.createCliComputerHost === "function" ? m.createCliComputerHost(opts) ?? null : null;
+        }
+        catch {
+            return null;
+        }
+    },
+    log: () => { },
+};
+function errorResult(kind, code, message, elapsedMs = 0) {
+    return { ok: false, kind: kind || "screen", error: { code, message }, elapsedMs };
+}
+function isResultLike(v) {
+    return !!v && typeof v === "object" && ("ok" in v) && ("kind" in v);
+}
+/**
+ * Attach the relay to the runner's server socket. Call once, right after the
+ * socket is created (before it connects). Returns a disposer.
+ */
+export function attachComputerRelay(socket, opts = {}) {
+    const deps = { ...liveDeps, ...(opts.deps ?? {}) };
+    const log = (line) => { if (opts.verbose)
+        deps.log(line); };
+    const pending = new Map();
+    let lastCapabilities = undefined;
+    let cliHost = null;
+    let cliHostLoading = null;
+    const hosted = deps.isHosted();
+    const settle = (id, result) => {
+        const p = pending.get(id);
+        if (!p)
+            return; // late or unknown: the server already got a timeout
+        pending.delete(id);
+        clearTimeout(p.timer);
+        try {
+            p.ack(result);
+        }
+        catch { /* socket gone */ }
+    };
+    const emitCapabilities = (caps) => {
+        lastCapabilities = caps;
+        if (socket.connected !== false) {
+            try {
+                socket.emit(COMPUTER_EVENTS.capabilities, caps ?? null);
+            }
+            catch { /* reconnect re-sends */ }
+        }
+    };
+    // Executor -> runner (the desktop app, or the CLI host through `send`).
+    const onExecutorMessage = (msg) => {
+        if (!msg || typeof msg !== "object")
+            return;
+        // The native approval dialog's answer (contract computer.approval.answer),
+        // re-checked field by field: it crossed a process boundary. Only the
+        // desktop app has a dialog: the CLI host never sends one.
+        const loose = msg;
+        if (loose.type === "computer.approval.answer") {
+            const approvalId = typeof loose.approvalId === "string" ? loose.approvalId.slice(0, 100) : "";
+            const decision = loose.decision === "approve" || loose.decision === "decline" ? loose.decision : null;
+            if (hosted && approvalId && decision && socket.connected !== false) {
+                try {
+                    socket.emit(COMPUTER_EVENTS.approvalAnswer, { approvalId, decision });
+                }
+                catch { /* the web card still decides */ }
+            }
+            return;
+        }
+        if (msg.type === "computer.result") {
+            const id = typeof msg.id === "string" ? msg.id : "";
+            if (id)
+                settle(id, msg.result);
+        }
+        else if (msg.type === "computer.capabilities") {
+            emitCapabilities(msg.capabilities ?? null);
+        }
+    };
+    const unsubscribeHost = hosted ? deps.onHostMessage(onExecutorMessage) : () => { };
+    const loadCliHost = () => {
+        if (hosted)
+            return Promise.resolve(null);
+        if (cliHost)
+            return Promise.resolve(cliHost);
+        cliHostLoading ??= deps.createCliHost({ send: onExecutorMessage, verbose: opts.verbose })
+            .then((h) => { cliHost = h; return h; })
+            .catch(() => null);
+        return cliHostLoading;
+    };
+    const refreshCapabilities = async () => {
+        if (hosted) {
+            if (lastCapabilities !== undefined)
+                emitCapabilities(lastCapabilities);
+            deps.sendToHost({ type: "computer.capabilities.request" });
+            return;
+        }
+        const h = await loadCliHost();
+        if (!h)
+            return; // a plain CLI runner reports nothing: the server sees no computer control
+        try {
+            emitCapabilities(await h.capabilities());
+        }
+        catch {
+            emitCapabilities(null);
+        }
+    };
+    socket.on("connect", () => { void refreshCapabilities(); });
+    socket.on(COMPUTER_EVENTS.command, (payload, ack) => {
+        if (typeof ack !== "function")
+            return; // fire-and-forget commands are not part of the contract
+        const p = (payload && typeof payload === "object" ? payload : {});
+        const action = (p.action && typeof p.action === "object" ? p.action : null);
+        const kind = typeof action?.kind === "string" ? action.kind : "screen";
+        const id = typeof p.id === "string" && p.id ? p.id.slice(0, 100) : "";
+        if (!id || !action) {
+            ack(errorResult(kind, "invalid_action", "The command was malformed (no id or action)."));
+            return;
+        }
+        if (pending.has(id)) {
+            ack(errorResult(kind, "invalid_action", "A command with this id is already running."));
+            return;
+        }
+        if (pending.size >= MAX_PENDING) {
+            ack(errorResult(kind, "busy", "Too many computer commands are in flight on this computer."));
+            return;
+        }
+        const deadlineMs = Math.min(MAX_DEADLINE_MS, Math.max(MIN_DEADLINE_MS, Math.floor(Number(p.deadlineMs) || 15_000)));
+        const allowedAppIds = Array.isArray(p.allowedAppIds) ? p.allowedAppIds.filter((x) => typeof x === "string") : [];
+        const allowedApps = Array.isArray(p.allowedApps) ? p.allowedApps : undefined;
+        const msg = {
+            type: "computer.command", id, action, deadlineMs, allowedAppIds,
+            ...(allowedApps ? { allowedApps } : {}),
+        };
+        const startedAt = Date.now();
+        const timer = setTimeout(() => {
+            settle(id, 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() - startedAt));
+        }, deadlineMs);
+        pending.set(id, { ack, kind, startedAt, timer });
+        if (hosted) {
+            log(`  [computer] ${kind} -> desktop app`);
+            deps.sendToHost(msg);
+            return;
+        }
+        void loadCliHost().then(async (h) => {
+            if (!h) {
+                settle(id, errorResult(kind, "unsupported", UNSUPPORTED_MESSAGE));
+                return;
+            }
+            try {
+                const out = await h.handle(msg);
+                if (out && typeof out === "object" && out.type === "computer.result") {
+                    settle(id, out.result);
+                }
+                else if (isResultLike(out)) {
+                    settle(id, out);
+                } // else: the host answers through `send` (onExecutorMessage)
+            }
+            catch (e) {
+                settle(id, errorResult(kind, "helper_unavailable", `The computer helper failed: ${e?.message || e}`, Date.now() - startedAt));
+            }
+        });
+    });
+    // Approval dialogs: forwarded to the desktop app only (a CLI host has no UI;
+    // the web card and the phone push still carry the approval).
+    socket.on(COMPUTER_EVENTS.approval, (payload) => {
+        if (!hosted)
+            return;
+        const p = (payload && typeof payload === "object" ? payload : {});
+        const approvalId = typeof p.approvalId === "string" ? p.approvalId.slice(0, 100) : "";
+        if (!approvalId)
+            return;
+        deps.sendToHost({
+            type: "computer.approval.request",
+            approvalId,
+            summary: typeof p.summary === "string" ? p.summary.slice(0, 300) : "An action needs your approval.",
+            effect: typeof p.effect === "string" ? p.effect.slice(0, 40) : "message",
+            ...(typeof p.appName === "string" && p.appName ? { appName: p.appName.slice(0, 120) } : {}),
+            expiresAt: typeof p.expiresAt === "string" ? p.expiresAt : new Date(Date.now() + 15 * 60_000).toISOString(),
+        });
+    });
+    socket.on(COMPUTER_EVENTS.approvalClosed, (payload) => {
+        if (!hosted)
+            return;
+        const approvalId = typeof payload?.approvalId === "string"
+            ? String(payload.approvalId).slice(0, 100) : "";
+        if (approvalId)
+            deps.sendToHost({ type: "computer.approval.closed", approvalId });
+    });
+    socket.on(COMPUTER_EVENTS.stop, (payload) => {
+        const reason = typeof payload?.reason === "string"
+            ? String(payload.reason).slice(0, 200)
+            : "stop";
+        log(`  [computer] stop (${reason})`);
+        if (hosted)
+            deps.sendToHost({ type: "computer.stop", reason });
+        else if (cliHost) {
+            try {
+                cliHost.stopAll(reason);
+            }
+            catch { /* best effort */ }
+        }
+    });
+    // A dropped socket leaves no one to supervise an action in flight: stop it.
+    socket.on("disconnect", () => {
+        if (!pending.size)
+            return;
+        for (const id of [...pending.keys()])
+            settle(id, errorResult(pending.get(id).kind, "stopped", "The connection to Melaya dropped."));
+        if (hosted)
+            deps.sendToHost({ type: "computer.stop", reason: "server_disconnected" });
+        else if (cliHost) {
+            try {
+                cliHost.stopAll("server_disconnected");
+            }
+            catch { /* best effort */ }
+        }
+    });
+    return {
+        dispose() {
+            unsubscribeHost();
+            for (const p of pending.values())
+                clearTimeout(p.timer);
+            pending.clear();
+            if (cliHost) {
+                try {
+                    cliHost.dispose();
+                }
+                catch { /* ignore */ }
+                cliHost = null;
+            }
+        },
+        pendingCount: () => pending.size,
+    };
+}

package/dist/connection.d.ts

@@ -14,10 +14,20 @@ import { type DetectedModel } from "./detect.js";
 interface ConnectOpts {
     token: string;
     serverUrl: string;
-    pythonPath: string;
+    /** The interpreter, or a promise of it: the socket connects before Python is
+     *  resolved (cli.ts). null = no usable Python (the CLI then exits). */
+    pythonPath: string | Promise<string | null>;
+    /** Initial list (last good from disk, or empty); fresh discovery arrives via publishModels. */
     models: DetectedModel[];
     verbose: boolean;
 }
-export declare function connect(opts: ConnectOpts): Promise<void>;
+/** What cli.ts uses after connect(): publish fresh discovery, print around the spinner. */
+export interface RunnerConnection {
+    /** Replace the model list and push it through `runner:models` when it changed. */
+    publishModels(models: DetectedModel[]): void;
+    /** console.log that keeps the connect spinner intact. */
+    print(line: string): void;
+}
+export declare function connect(opts: ConnectOpts): Promise<RunnerConnection>;
 export declare function verifySignature(content: string, signature: string, runnerToken: string): boolean;
 export {};