@melaya/runner 1.1.73 → 1.1.74

package/dist/assistantHost.py

@@ -149,7 +149,9 @@ def _config_hash() -> str:
     ONLY when the capability env is set, so a browser-less host hashes exactly
     like a pre-browser server build (parity preserved). The TARGET GRANT itself
     is NEVER hashed and never in the env at boot: it arrives per turn on the
-    turn frame and is purged at turn end (see _apply_browser_turn_grant)."""
+    turn frame and is purged at turn end (see _apply_browser_turn_grant).
+    Computer Control (protocol 5) follows the same rule: "computer" right after
+    "browser", only when MEL_ASSISTANT_COMPUTER_READY is set."""
     import hashlib
     raw_conn = os.environ.get("MEL_ASSISTANT_CONNECTORS", "") or ""
     connectors = ",".join(sorted(c.lower() for c in raw_conn.split(",") if c.strip()))
@@ -162,6 +164,11 @@ def _config_hash() -> str:
     ]
     if _browser_capable():
         fields.append("browser")
+    # Computer Control PRESENCE (protocol 5), same rule as browser: appended
+    # only when on, right after "browser", byte-for-byte like
+    # runnerAssistantRelay.ts assistantConfigHash (COMPUTER_HASH_MARKER).
+    if _computer_ready():
+        fields.append("computer")
     # Surgical tool pinning: PRESENCE of pinned tool names is part of the host
     # boot config, exactly like browser capability above — a warm host that
     # never registered a pinned tool active must reboot when a turn first
@@ -198,6 +205,14 @@ def _browser_capable() -> bool:
     return (os.environ.get("MEL_ASSISTANT_BROWSER_CAPABLE", "") or "") in ("1", "true", "True")
 
 
+def _computer_ready() -> bool:
+    """Computer Control on this host (assistant protocol 5): the server sets
+    MEL_ASSISTANT_COMPUTER_READY when a computer is on for the chat (Devices
+    tile) or, without a selection, the user has one online. The server pins
+    every computer call to the chat's computers (/api/v1/computer/command)."""
+    return (os.environ.get("MEL_ASSISTANT_COMPUTER_READY", "") or "") in ("1", "true", "True")
+
+
 def _render_summary_text(summary) -> str:
     """Render a server AssistantSummary ({facts, provenance}) to a data-only text
     block for the compressed-summary slot. Never policy — reference only."""
@@ -918,10 +933,18 @@ def _build_agent():
     # are trusted-UI-only and never part of this category (plan 0.1).
     browser_enabled = _browser_capable()
 
+    # Computer Control (protocol 5): the computer_* toolkit (registry category
+    # "computer", shared/tools/computer.py) when the server says a computer is on
+    # for this chat. Each call posts to /api/v1/computer/command, where the
+    # server pins it to the chat's computers and applies the allowlist, app
+    # tiers, approvals and the kill switch.
+    computer_enabled = _computer_ready()
+
     # Read-only platform tools (melaya_agent); phone control (Device Control) on
     # mobile only. These POST to /api/v1/private/assistant-tool + /phone/command
     # with MELAYA_API_KEY; tenant scope is enforced server-side.
-    categories = ["melaya_agent"] + (["phone"] if phone_enabled else []) + (["browser"] if browser_enabled else [])
+    categories = (["melaya_agent"] + (["phone"] if phone_enabled else []) + (["browser"] if browser_enabled else [])
+                  + (["computer"] if computer_enabled else []))
     # Connector tool sets the user enabled for THIS chat (any service — odoo,
     # stripe, shopify, …). When present, use a LAZY toolkit: base tools stay
     # active+pinned, and the connectors' tools are deferred + discoverable via
@@ -977,6 +1000,12 @@ def _build_agent():
         # management + every browser action is directly callable, no search/activate.
         if browser_enabled:
             _budget = max(_budget, 64)
+        # Same for the computer: ~38 computer_* tools must all stay pinned (no
+        # search_tools/activate_tool per click, and an activated write would go
+        # through the connector card on top of the server's own approval).
+        # 64 holds melaya_agent + computer; each other device set adds ~40.
+        if computer_enabled:
+            _budget = max(_budget, 24 + 40 * (1 + int(phone_enabled) + int(browser_enabled)))
         # Surgical tool pinning: widen the budget so every pinned tool fits
         # alongside the base active set (melaya_agent + phone/browser if
         # enabled) — mirrors the phone_enabled/browser_enabled widening above,
@@ -1124,6 +1153,45 @@ def _build_agent():
         "or route around it; tell the user if the task needs another site.\n"
         if browser_enabled else ""
     )
+    # Computer Control discipline: a hand-mirror of the cloud Assistant's
+    # computer guidance (assistantComputerTools.ts COMPUTER_PROMPT_HINT,
+    # computerVerbs.ts COMPUTER_ROUTING / COMPUTER_LOOP / COMPUTER_LIMITS,
+    # fastSchema.ts COMPUTER_FAST_GUIDANCE). Keep them in step.
+    computer_rule = (
+        "- COMPUTER CONTROL: you can operate the user's own computer (Windows, macOS or "
+        "Linux, through the Melaya desktop app) with the computer_* tools. When the user "
+        "asks whether you can access or use their computer, the answer is YES. Use the "
+        "computer for desktop apps; prefer a connected service, the browser or the phone "
+        "when they can do the job. Call computer_status first, and whenever a computer "
+        "tool says the app is unreachable.\n"
+        "- SEE THE SCREEN FIRST, then read, act, verify: read the window with "
+        "computer_screen (computer_screenshot, computer_zoom or computer_ocr for a canvas, "
+        "game, remote desktop or video that has no element tree), act on ONE element by "
+        "its @eN ref or exact label, then check the result's observed change. A no_effect "
+        "result means nothing changed: do not repeat the action, read again and pick "
+        "another target. NEVER ask the user to describe, paste or screenshot their own "
+        "screen: you have eyes, use them.\n"
+        "- GO FAST: once you have read the window and can name the next steps, send them in "
+        "ONE computer_fast call (click / type / select / press keys and chords / scroll / "
+        "wait / expect / read by the names you read, collect for lists, for_each for rows) "
+        "instead of one call per click; it re-finds every target, stops at the first "
+        "surprise and hands the window back. computer_batch runs a known list of actions "
+        "in one call; computer_path draws or traces strokes (canvas ink, signatures, "
+        "sliders). Use the single computer_* tools to explore an unread window, for "
+        "logins, secure fields and file dialogs.\n"
+        "- APPROVALS AND LIMITS: writes follow this chat's autonomy mode, decided by the "
+        "SYSTEM. If a result says an approval is waiting, a card is already in front of "
+        "the user: re-issue the SAME call once, never ask in chat instead. Only apps the "
+        "user allowed in Computer Control can be driven, each at its level (not_allowed / "
+        "tier_denied: ask the user to allow it, never open another app or work around it). "
+        "Never type into password, PIN, OTP or card fields (secure_field), and let the user "
+        "answer admin / UAC prompts themselves (elevated_window, secure_desktop).\n"
+        "- STOP: the user can stop you at any moment with the Stop button or the stop "
+        "shortcut (Ctrl+Alt+End). After a stopped result make no more computer calls and "
+        "report honestly what was done. Call computer_stop yourself the moment the user "
+        "says stop or something goes wrong on screen.\n"
+        if computer_enabled else ""
+    )
     # Surgical tool pinning: those exact tool names are already ACTIVE (not
     # deferred), so the rule says to call them directly. Per-turn connectors
     # (protocol 3): connector_services is empty here and the rule is rendered per
@@ -1197,12 +1265,15 @@ def _build_agent():
         "mode the user approves each one). That is your CURRENT TOOLBOX, not a "
         "description of Melaya"
         + (" — plus phone-control tools to drive the user's paired phone." if phone_enabled else ".")
+        + (" Computer-control tools (computer_*) drive the user's own computer through the "
+           "Melaya desktop app." if computer_enabled else "")
         + "\nRules:\n"
         "- Use tools to answer questions about the user's pipelines, spend, usage, "
         "templates or evals — never invent numbers. For cost, melaya_cost_summary "
         "supports dimension='pipeline' to find which pipeline cost the most.\n"
         + phone_rule
         + browser_rule
+        + computer_rule
         + connector_rule
         + core_rule
         + "- Be concise and concrete; format small tables or bullet lists when comparing items.\n"
@@ -1279,7 +1350,8 @@ def _build_agent():
         # wall-clock budget is enforced separately in _run_turn.
         max_iters=(int(os.environ.get("MEL_ASSISTANT_MAX_ITERS_PHONE", "300") or "300") if phone_enabled
                    else (int(os.environ.get("MEL_ASSISTANT_MAX_ITERS_BROWSER", "300") or "300") if browser_enabled
-                         else (40 if (connector_services or _turn_connectors_mode()) else 8))),
+                         else (int(os.environ.get("MEL_ASSISTANT_MAX_ITERS_COMPUTER", "300") or "300") if computer_enabled
+                               else (40 if (connector_services or _turn_connectors_mode()) else 8)))),
         # EVERY assistant turn is long-horizon, not only device-driving ones.
         #
         # The codex cap is a latency default written for pipeline phases. An

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/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.74",
   "description": "Run Melaya AI pipelines locally with your own LM Studio or Ollama models",
   "license": "Apache-2.0",
   "author": "Melaya Labs LLC",