@melaya/runner 1.1.73 → 1.1.75

package/dist/computerRelay.js

@@ -36,6 +36,8 @@ export const COMPUTER_EVENTS = {
 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;
+/** Most pause time (user at the keyboard) one command may add to its deadline (contract COMPUTER_PAUSE.budgetMs, with room). */
+const MAX_PAUSE_BUDGET_MS = 300_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.
@@ -173,14 +175,19 @@ export function attachComputerRelay(socket, opts = {}) {
         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;
+        // Pause and resume (2026-10-23): time the executor may spend paused for the user on top of the deadline
+        // (sent only to executors that report pauseResume; the server waits that much longer too).
+        const budget = Math.floor(Number(p.pauseBudgetMs));
+        const pauseBudgetMs = Number.isFinite(budget) && budget > 0 ? Math.min(MAX_PAUSE_BUDGET_MS, budget) : 0;
         const msg = {
             type: "computer.command", id, action, deadlineMs, allowedAppIds,
             ...(allowedApps ? { allowedApps } : {}),
+            ...(pauseBudgetMs ? { pauseBudgetMs } : {}),
         };
         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);
+        }, deadlineMs + pauseBudgetMs);
         pending.set(id, { ack, kind, startedAt, timer });
         if (hosted) {
             log(`  [computer] ${kind} -> desktop app`);

package/dist/connection.js

@@ -44,6 +44,9 @@ import { newTurnFileState, readTurnFile, turnOutputDir } from "./assistantFiles.
 // registered on this computer, served after the runner verifies each
 // capability itself.
 import { VAULT_HOST_CAPABILITY, VaultHostProcess, VaultRegistry, VaultService, attachVaultSocketHandlers, findVaultHostScript, setVaultRelayPort, vaultToolEnv, trustRunVaultCapability, } from "./vaults.js";
+// Stored plans: the server reads ~/.melaya/plans/<name>.json through this runner
+// for the grouped-step tools' plan: {file} source (runner:plan-read).
+import { attachPlanSocketHandlers } from "./stepPlans.js";
 // Obsidian app bridge: App ops through the user's running Obsidian (CLI /
 // Local REST API); the REST key stays in ~/.melaya-runner/vaults.
 import { ObsidianAppBridge } from "./obsidianApp.js";
@@ -106,7 +109,11 @@ const RESERVED_BROWSER_ENV = ["MEL_BROWSER_URL", "MEL_BROWSER_TOKEN"];
 // to the server as `file` frames with their bytes, under the caps and path
 // confinement of assistantFiles.ts. A server that does not send `fileDelivery`
 // gets exactly the v3 behaviour (files stay on this computer only).
-const ASSISTANT_PROTOCOL_VERSION = 4;
+// v5: Computer Control. A start / prewarm frame may carry `computerReady`; the
+// host then registers the computer_* toolkit (MEL_ASSISTANT_COMPUTER_READY) and
+// hashes "computer" after "browser". A server only sends it to a v5 runner, so
+// an older host never boots config-stale over it.
+const ASSISTANT_PROTOCOL_VERSION = 5;
 // Best-effort read of our own package version (mirrors cli.ts). Advertised in the
 // hello so the server can log / gate on a package floor too.
 let RUNNER_VERSION = "0.0.0";
@@ -305,6 +312,7 @@ export async function connect(opts) {
         app: new ObsidianAppBridge({ dir: vaultRegistry.dir, log: vaultLog }),
     });
     attachVaultSocketHandlers(socket, vaultService, () => pickNativeFolder("Select your Obsidian vault folder"));
+    attachPlanSocketHandlers(socket);
     if (vaultRegistry.list().length) {
         void vaultService.restore().catch((e) => vaultLog(`restore failed: ${e?.message || e}`));
     }
@@ -2024,6 +2032,12 @@ export async function connect(opts) {
             // always hash "browser" while a non-browser server hash omitted it, which
             // pinned every turn to a permanent runner_host_config_stale.
             MEL_ASSISTANT_BROWSER_CAPABLE: payload.browserCapable ? "1" : "",
+            // Computer Control (v5): the computer_* toolkit joins the host when a
+            // computer is on for the chat (Devices tile) or, with no selection, the
+            // user has one online. Part of the config hash ("computer", appended only
+            // when set), so switching the computer on or off reboots the host. The
+            // server pins every computer call to the chat's computers itself.
+            MEL_ASSISTANT_COMPUTER_READY: payload.computerReady ? "1" : "",
             // Connector tool sets the user enabled for this chat (comma-joined service
             // ids). The host seeds a lazy toolkit from these so ANY connector's tools
             // are reachable without exploding context.

package/dist/hostChannel.d.ts

@@ -53,6 +53,7 @@ export type RunnerToHostMessage = {
         tier: "view" | "click" | "full";
         expiresAt?: string;
     }>;
+    pauseBudgetMs?: number;
 } | {
     type: "computer.stop";
     reason: string;

package/dist/stepPlans.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Stored plans on the user's own computer: the `plan: { file: "<name>.json" }`
+ * source of the grouped-step tools (computer batch / path / fast, browser and
+ * phone batch / fast). A local agent writes a big step list (a drawing, a
+ * 3000-step batch) to ~/.melaya/plans/<name>.json and references it; the
+ * server asks this runner for the file (runner:plan-read, answered on the
+ * socket.io ack) instead of the model writing every step into the call.
+ *
+ * Only ONE folder, ONE plain file name: no separators, no traversal, no hidden
+ * files, .json only, no symbolic links (the file itself, or the folder resolving
+ * elsewhere), no hard-linked files, at most 2 MB. The content is returned as
+ * text and parsed by the server; it is never executed or logged here.
+ *
+ * The desktop app runs this same runner (utilityProcess), so it answers too.
+ */
+export declare const PLAN_FILE_MAX_BYTES: number;
+/** A plain file name: same rule as the server (services/plans/stepPlans.ts). */
+export declare const PLAN_FILE_RE: RegExp;
+/** ~/.melaya/plans */
+export declare function plansDir(home?: string): string;
+export type PlanReadResult = {
+    ok: true;
+    text: string;
+    bytes: number;
+} | {
+    ok: false;
+    code: "bad_name" | "not_found" | "not_a_file" | "too_large" | "outside" | "read_failed";
+    message: string;
+};
+/** Read one plan file from `dir` (default ~/.melaya/plans, created when missing). */
+export declare function readPlanFile(name: unknown, dir?: string): Promise<PlanReadResult>;
+/** The subset of a socket.io-client Socket used here (a fake in tests). */
+export interface PlanSocketLike {
+    on(event: string, cb: (...args: any[]) => void): unknown;
+}
+/** runner:plan-read {file} -> ack(PlanReadResult). Old servers never send it. */
+export declare function attachPlanSocketHandlers(socket: PlanSocketLike, dir?: () => string): void;

package/dist/stepPlans.js

@@ -0,0 +1,103 @@
+/**
+ * Stored plans on the user's own computer: the `plan: { file: "<name>.json" }`
+ * source of the grouped-step tools (computer batch / path / fast, browser and
+ * phone batch / fast). A local agent writes a big step list (a drawing, a
+ * 3000-step batch) to ~/.melaya/plans/<name>.json and references it; the
+ * server asks this runner for the file (runner:plan-read, answered on the
+ * socket.io ack) instead of the model writing every step into the call.
+ *
+ * Only ONE folder, ONE plain file name: no separators, no traversal, no hidden
+ * files, .json only, no symbolic links (the file itself, or the folder resolving
+ * elsewhere), no hard-linked files, at most 2 MB. The content is returned as
+ * text and parsed by the server; it is never executed or logged here.
+ *
+ * The desktop app runs this same runner (utilityProcess), so it answers too.
+ */
+import { constants as FS, promises as fsp } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+export const PLAN_FILE_MAX_BYTES = 2 * 1024 * 1024;
+/** A plain file name: same rule as the server (services/plans/stepPlans.ts). */
+export const PLAN_FILE_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}\.json$/;
+/** ~/.melaya/plans */
+export function plansDir(home = homedir()) {
+    return join(home, ".melaya", "plans");
+}
+const fail = (code, message) => ({ ok: false, code, message });
+/** Read one plan file from `dir` (default ~/.melaya/plans, created when missing). */
+export async function readPlanFile(name, dir = plansDir()) {
+    if (typeof name !== "string" || !PLAN_FILE_RE.test(name)) {
+        return fail("bad_name", "a plan file is a plain .json name inside ~/.melaya/plans/ (letters, digits, . _ -).");
+    }
+    try {
+        await fsp.mkdir(dir, { recursive: true, mode: 0o700 });
+    }
+    catch { /* reported below as not_found */ }
+    const full = join(dir, name);
+    let st;
+    try {
+        st = await fsp.lstat(full);
+    }
+    catch (e) {
+        return e?.code === "ENOENT"
+            ? fail("not_found", `~/.melaya/plans/${name} does not exist.`)
+            : fail("read_failed", `~/.melaya/plans/${name} could not be read.`);
+    }
+    if (st.isSymbolicLink())
+        return fail("outside", "symbolic links are not followed in ~/.melaya/plans/.");
+    if (!st.isFile())
+        return fail("not_a_file", `~/.melaya/plans/${name} is not a regular file.`);
+    if (st.nlink > 1)
+        return fail("outside", "hard-linked files are not read from ~/.melaya/plans/.");
+    if (st.size > PLAN_FILE_MAX_BYTES)
+        return fail("too_large", `~/.melaya/plans/${name} is larger than 2 MB.`);
+    // The folder itself may be a link: the file's real location must be the plans folder.
+    try {
+        const [realDir, realFile] = await Promise.all([fsp.realpath(dir), fsp.realpath(full)]);
+        if (dirname(realFile) !== realDir)
+            return fail("outside", "the plan file resolves outside ~/.melaya/plans/.");
+    }
+    catch {
+        return fail("read_failed", `~/.melaya/plans/${name} could not be read.`);
+    }
+    let fh = null;
+    try {
+        // O_NOFOLLOW where the platform has it (not on Windows: lstat above covers it).
+        fh = await fsp.open(full, FS.O_RDONLY | (FS.O_NOFOLLOW ?? 0));
+        const st2 = await fh.stat();
+        if (!st2.isFile() || st2.size > PLAN_FILE_MAX_BYTES)
+            return fail("too_large", `~/.melaya/plans/${name} is larger than 2 MB.`);
+        const buf = Buffer.alloc(Math.min(st2.size, PLAN_FILE_MAX_BYTES) + 1);
+        let read = 0;
+        while (read < buf.length) {
+            const { bytesRead } = await fh.read(buf, read, buf.length - read, read);
+            if (!bytesRead)
+                break;
+            read += bytesRead;
+        }
+        if (read > PLAN_FILE_MAX_BYTES)
+            return fail("too_large", `~/.melaya/plans/${name} is larger than 2 MB.`);
+        return { ok: true, text: buf.subarray(0, read).toString("utf8"), bytes: read };
+    }
+    catch (e) {
+        return e?.code === "ELOOP"
+            ? fail("outside", "symbolic links are not followed in ~/.melaya/plans/.")
+            : fail("read_failed", `~/.melaya/plans/${name} could not be read.`);
+    }
+    finally {
+        await fh?.close().catch(() => undefined);
+    }
+}
+/** runner:plan-read {file} -> ack(PlanReadResult). Old servers never send it. */
+export function attachPlanSocketHandlers(socket, dir) {
+    socket.on("runner:plan-read", async (p, ack) => {
+        if (typeof ack !== "function")
+            return;
+        try {
+            ack(await readPlanFile(p?.file, dir ? dir() : plansDir()));
+        }
+        catch {
+            ack(fail("read_failed", "the plan file could not be read."));
+        }
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@melaya/runner",
-  "version": "1.1.73",
+  "version": "1.1.75",
   "description": "Run Melaya AI pipelines locally with your own LM Studio or Ollama models",
   "license": "Apache-2.0",
   "author": "Melaya Labs LLC",