@melaya/runner 1.1.73 → 1.1.75

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/computerHostCli.d.ts

@@ -19,7 +19,10 @@
  * 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.
+ * helper. Real user input (a VNC / console user) PAUSES a run instead of
+ * stopping it (2026-10-23, computerPause.ts, the same engine as the desktop
+ * app): held input is let go, a pointer stream is cancelled, the run waits
+ * until the user is idle, checks the window and continues where it was.
  *
  * computerRelay.ts (server socket <-> executor) loads this module lazily and
  * calls createCliComputerHost({ send, verbose }) when the runner is not inside
@@ -52,6 +55,7 @@ export type ComputerRunnerToHost = {
     deadlineMs: number;
     allowedAppIds: string[];
     allowedApps?: AllowedApp[];
+    pauseBudgetMs?: number;
 } | {
     type: "computer.stop";
     reason: string;
@@ -187,6 +191,11 @@ export declare class HelperProcess {
      */
     /** Releases every key / button the helper holds (helper 1.2.0+; older helpers ignore the op). */
     release(): void;
+    /**
+     * Cancels one command for a pause (pause and resume): unlike cancel(), its `stopped` reply (with the path's
+     * `progress`) still answers the request, so the host knows how far it got and continues from there.
+     */
+    pauseCancel(target: string): void;
     cancel(target?: string): void;
     get running(): boolean;
     dispose(): void;

package/dist/computerHostCli.js

@@ -19,7 +19,10 @@
  * 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.
+ * helper. Real user input (a VNC / console user) PAUSES a run instead of
+ * stopping it (2026-10-23, computerPause.ts, the same engine as the desktop
+ * app): held input is let go, a pointer stream is cancelled, the run waits
+ * until the user is idle, checks the window and continues where it was.
  *
  * computerRelay.ts (server socket <-> executor) loads this module lazily and
  * calls createCliComputerHost({ send, verbose }) when the runner is not inside
@@ -49,6 +52,7 @@ import { homedir } from "os";
 import { delimiter, dirname, join } from "path";
 import { fileURLToPath } from "url";
 import { COMPUTER_HELPER_MANIFEST, COMPUTER_HELPER_VERSION } from "./computerHelperManifest.js";
+import { PAUSE_DEFAULTS, PauseRun, pauseNeedsIdle, pausePositionOf, pauseReportText, pauseRunStep, pauseStopText, } from "./computerPause.js";
 export const COMPUTER_ACTION_KINDS = [
     "screen", "screenshot", "find", "get_text", "current_app", "list_windows", "list_apps", "list_displays",
     "clipboard_read", "ocr", "wait", "hover", "move", "scroll",
@@ -472,6 +476,13 @@ export class HelperProcess {
     release() {
         this.send({ op: "release" });
     }
+    /**
+     * Cancels one command for a pause (pause and resume): unlike cancel(), its `stopped` reply (with the path's
+     * `progress`) still answers the request, so the host knows how far it got and continues from there.
+     */
+    pauseCancel(target) {
+        this.send({ op: "cancel", target });
+    }
     cancel(target) {
         this.send(target ? { op: "cancel", target } : { op: "cancel" });
         if (!target || !this.child)
@@ -587,8 +598,30 @@ export function _resetCliComputerHost() {
     cliEnabled = false;
     cliDefaults = {};
 }
-/** Real user input seen this recently pauses a batch (`user_interrupted`). */
-const USER_INPUT_PAUSE_MS = 1_500;
+/** Most pause time (someone at the keyboard) one command may add to its deadline (contract COMPUTER_PAUSE.budgetMs, with room). */
+const MAX_PAUSE_BUDGET_MS = 300_000;
+/** A run that paused and could not go on: user_interrupted with where it stopped (a Stop keeps "stopped"). */
+function pauseStopResult(kind, stop, message, elapsedMs, steps, resumeFrom, pauses) {
+    return {
+        ...errorResult(kind, stop.reason === "stopped" ? "stopped" : "user_interrupted", message, elapsedMs),
+        ...(steps ? { steps } : {}),
+        ...(resumeFrom && stop.reason !== "stopped" ? { resumeFrom } : {}),
+        ...(pauses ? { pauses } : {}),
+    };
+}
+/** A resume position the agent copies back (stroke / point / frac, rounded). */
+function cleanPosition(p) {
+    return { stroke: Math.max(0, Math.floor(p.stroke ?? 0)), point: Math.max(0, Math.floor(p.point ?? 0)), frac: Math.round(Math.min(1, Math.max(0, p.frac ?? 0)) * 1000) / 1000 };
+}
+/** A finished command that paused for the user: status completed_with_pauses and the compact report. */
+function withPauses(r, pauses) {
+    if (!pauses)
+        return r;
+    if (!r.ok)
+        return { ...r, pauses };
+    const text = typeof r.text === "string" ? r.text : "";
+    return { ...r, text: `${text}${text ? "\n" : ""}${pauseReportText(pauses)}`, status: "completed_with_pauses", pauses };
+}
 export function createCliComputerHost(options = {}) {
     const opts = { ...cliDefaults, ...options };
     const env = opts.env ?? process.env;
@@ -604,6 +637,10 @@ export function createCliComputerHost(options = {}) {
     let capsAt = 0;
     let disposed = false;
     let lastUserInput = 0;
+    /** Bumped by stopAll: a run started before it has ended (pause and resume stop waiting). */
+    let stopGen = 0;
+    /** The run in flight that pauses for the user (pause and resume, computerPause.ts). */
+    let active = null;
     const keepAwake = opts.keepAwake ?? new KeepAwake({ spawn: opts.spawn, env });
     const ensureHelper = async () => {
         if (disposed)
@@ -624,7 +661,12 @@ export function createCliComputerHost(options = {}) {
             onEvent: (e) => {
                 if (e.event === "user_input") {
                     lastUserInput = Date.now();
-                    log("  [computer] someone is using this computer: runs pause");
+                    // Pause and resume: let go of what the run holds and cancel a pointer stream now; it goes on once they stop.
+                    if (active) {
+                        if (!active.run.interrupted)
+                            log("  [computer] someone is using this computer: the run pauses until they stop");
+                        active.run.onUserInput(active.host);
+                    }
                 }
                 else if (e.event === "log") {
                     log(`  [computer] ${String(e.message || "").slice(0, 300)}`);
@@ -654,7 +696,8 @@ export function createCliComputerHost(options = {}) {
                     kinds.add("keep_awake");
                 else
                     kinds.delete("keep_awake");
-                caps = { ...c, kinds: COMPUTER_ACTION_KINDS.filter((k) => kinds.has(k)), host: "cli" };
+                // pauseResume: this host pauses for the user and resumes (computerPause.ts), takes pauseBudgetMs and resumeFrom.
+                caps = { ...c, kinds: COMPUTER_ACTION_KINDS.filter((k) => kinds.has(k)), host: "cli", pauseResume: true };
             }
             else {
                 caps = null;
@@ -697,61 +740,154 @@ export function createCliComputerHost(options = {}) {
             return errorResult(kind, "helper_unavailable", `The computer helper stopped: ${m}`, Date.now() - started);
         }
     };
-    /** batch, run here step by step (PROTOCOL.md §7): per-step expect, onError, user-input pause, shared deadline. */
-    const runBatch = async (id, action, allowedAppIds, allowedApps, deadlineMs) => {
+    /** What the pause engine needs from this host for one command (every command still goes through runOnHelper). */
+    const pauseHost = (allowedAppIds, allowedApps, clock) => {
+        const gen = stopGen;
+        return {
+            now: () => Date.now(),
+            sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+            exec: (a, hid) => runOnHelper(hid, a, allowedAppIds, allowedApps, Math.max(500, clock.at - Date.now())),
+            cancel: (hid) => { try {
+                helper?.pauseCancel(hid);
+            }
+            catch { /* helper gone */ } },
+            release: () => { try {
+                helper?.release();
+            }
+            catch { /* best effort */ } },
+            ended: () => disposed || gen !== stopGen,
+            timeLeft: () => clock.at - Date.now(),
+            extend: (ms) => {
+                const d = ms > 0 ? Math.min(ms, clock.budgetLeft) : -Math.min(-ms, clock.used);
+                clock.budgetLeft -= d;
+                clock.used += d;
+                clock.at += d;
+                return d;
+            },
+            lastInputAt: () => lastUserInput,
+            markInput: () => { lastUserInput = Date.now(); },
+            overlay: (on) => log(on ? "  [computer] paused: someone is using this computer; it resumes when they stop" : "  [computer] resumed"),
+            quietMs: PAUSE_DEFAULTS.quietMs,
+            maxPauseMs: PAUSE_DEFAULTS.maxPauseMs,
+        };
+    };
+    /** batch, run here step by step (PROTOCOL.md §7): per-step expect, onError, pause and resume, shared deadline. */
+    const runBatch = async (id, action, allowedAppIds, allowedApps, deadlineMs, pauseBudgetMs = 0) => {
         const started = Date.now();
         const steps = action.steps || [];
         const stopDefault = action.stopOnError !== false;
+        // resumeFrom (2026-10-23): continue a batch that stopped midway; a path at that step goes on at its stroke.
+        const resume = pausePositionOf(action.resumeFrom);
+        const start = resume?.step ?? 0;
+        if (start >= steps.length)
+            return errorResult("batch", "invalid_action", `resumeFrom.step ${start} is past the last step (the batch has ${steps.length}; steps count from 0).`);
+        const clock = { at: started + deadlineMs, budgetLeft: pauseBudgetMs, used: 0 };
+        const run = new PauseRun();
+        const host = pauseHost(allowedAppIds, allowedApps, clock);
+        active = { run, host };
         const results = [];
         let failed = 0;
-        const left = () => deadlineMs - (Date.now() - started);
-        for (let i = 0; i < steps.length; i++) {
-            const step = steps[i];
-            const kind = String(step.kind || "");
-            let r;
-            let expectFailed = false;
-            if (i > 0 && Date.now() - lastUserInput < USER_INPUT_PAUSE_MS) {
-                r = errorResult(kind, "user_interrupted", "Someone started using the mouse or keyboard, so the batch paused here. Read the screen before continuing.");
-            }
-            else if (left() < 200) {
-                r = errorResult(kind, "timeout", "The batch ran out of time before this step.");
-            }
-            else if (kind === "keep_awake" || kind === "handoff") {
-                r = await runLocal(kind, step);
-            }
-            else {
-                const { expect: cond, onError: _onError, expectTimeoutMs, ...plain } = step;
-                r = await runOnHelper(`${id}.${i + 1}`, plain, allowedAppIds, allowedApps, Math.max(500, left()));
-                if (r.ok && cond && typeof cond === "object") {
-                    const timeoutMs = Math.min(Math.max(100, Number(expectTimeoutMs) || 2_000), Math.max(100, left() - 100));
-                    const ex = await runOnHelper(`${id}.${i + 1}e`, { kind: "expect", condition: cond, timeoutMs }, allowedAppIds, allowedApps, timeoutMs + 500);
-                    if (!ex.ok) {
-                        expectFailed = true;
-                        const em = ex.error?.message || "the expectation failed";
-                        r = { ok: false, kind, error: { code: ex.error?.code || "timeout", message: `The step ran but its expectation failed: ${em}` }, elapsedMs: r.elapsedMs };
+        const left = () => clock.at - Date.now();
+        try {
+            for (let i = start; i < steps.length; i++) {
+                const step = steps[i];
+                const kind = String(step.kind || "");
+                let r;
+                let expectFailed = false;
+                if (left() < 200) {
+                    r = errorResult(kind, "timeout", "The batch ran out of time before this step.");
+                }
+                else if (kind === "keep_awake" || kind === "handoff") {
+                    r = await runLocal(kind, step);
+                }
+                else {
+                    const { expect: cond, onError: _onError, expectTimeoutMs, ...plain } = step;
+                    const pathStart = i === start && plain.kind === "path" && resume ? resume : null;
+                    const out = await pauseRunStep(host, run, plain, `${id}.${i + 1}`, pathStart);
+                    if ("stop" in out) {
+                        // Someone took over and the run cannot go on safely: say where, and how to continue (resumeFrom).
+                        try {
+                            helper?.release();
+                        }
+                        catch { /* best effort */ }
+                        const at = kind === "path" ? cleanPosition(out.stop.at ?? (pathStart ?? {})) : {};
+                        const resumeFrom = { step: i, ...(kind === "path" ? at : {}) };
+                        const where = `at step ${i + 1} of ${steps.length} (${kind}${kind === "path" ? `, stroke ${(at.stroke ?? 0) + 1}` : ""})`;
+                        return pauseStopResult("batch", out.stop, pauseStopText(out.stop, where, resumeFrom), Date.now() - started, results, resumeFrom, run.report());
+                    }
+                    r = out.result;
+                    if (r.ok && cond && typeof cond === "object") {
+                        const timeoutMs = Math.min(Math.max(100, Number(expectTimeoutMs) || 2_000), Math.max(100, left() - 100));
+                        const ex = await runOnHelper(`${id}.${i + 1}e`, { kind: "expect", condition: cond, timeoutMs }, allowedAppIds, allowedApps, timeoutMs + 500);
+                        if (!ex.ok) {
+                            expectFailed = true;
+                            const em = ex.error?.message || "the expectation failed";
+                            r = { ok: false, kind, error: { code: ex.error?.code || "timeout", message: `The step ran but its expectation failed: ${em}` }, elapsedMs: r.elapsedMs };
+                        }
                     }
                 }
-            }
-            results.push(r);
-            if (!r.ok) {
-                failed++;
-                const code = String(r.error?.code || "internal");
-                const onError = step.onError === "continue" ? false : step.onError === "stop" ? true : stopDefault;
-                // A failed expectation follows onError; a stop, a timeout or a person at the keyboard always ends the batch.
-                const forced = !expectFailed && ["stopped", "timeout", "user_interrupted", "screen_locked", "secure_desktop"].includes(code);
-                if (onError || forced) {
-                    const msg = r.error?.message || "";
-                    // A batch that did not finish leaves nothing pressed (hold_key / mouse down without their up).
-                    try {
-                        helper?.release();
+                results.push(r);
+                if (!r.ok) {
+                    failed++;
+                    const code = String(r.error?.code || "internal");
+                    const onError = step.onError === "continue" ? false : step.onError === "stop" ? true : stopDefault;
+                    // A failed expectation follows onError; a stop, a timeout or a person at the keyboard always ends the batch.
+                    const forced = !expectFailed && ["stopped", "timeout", "user_interrupted", "screen_locked", "secure_desktop"].includes(code);
+                    if (onError || forced) {
+                        const msg = r.error?.message || "";
+                        // A batch that did not finish leaves nothing pressed (hold_key / mouse down without their up).
+                        try {
+                            helper?.release();
+                        }
+                        catch { /* best effort */ }
+                        const pauses = run.report();
+                        return { ok: false, kind: "batch", error: { code, message: `Step ${i + 1} failed: ${msg}` }, steps: results, elapsedMs: Date.now() - started, ...(pauses ? { pauses } : {}) };
                     }
-                    catch { /* best effort */ }
-                    return { ok: false, kind: "batch", error: { code, message: `Step ${i + 1} failed: ${msg}` }, steps: results, elapsedMs: Date.now() - started };
                 }
             }
         }
+        finally {
+            if (active?.run === run)
+                active = null;
+        }
+        const pauses = run.report();
         const text = failed === 0 ? `All ${results.length} steps done.` : `${results.length} steps run, ${failed} failed (onError continue).`;
-        return { ok: true, kind: "batch", text, steps: results, elapsedMs: Date.now() - started };
+        return {
+            ok: true, kind: "batch", text: pauses ? `${text}\n${pauseReportText(pauses)}` : text, steps: results, elapsedMs: Date.now() - started,
+            ...(pauses ? { status: "completed_with_pauses", pauses } : {}),
+        };
+    };
+    /** One action that sends input: it waits while someone uses the computer and resumes a path where it was. */
+    const runPausable = async (id, action, allowedAppIds, allowedApps, deadlineMs, pauseBudgetMs) => {
+        const started = Date.now();
+        const kind = String(action.kind || "screen");
+        const clock = { at: started + deadlineMs, budgetLeft: pauseBudgetMs, used: 0 };
+        const run = new PauseRun();
+        const host = pauseHost(allowedAppIds, allowedApps, clock);
+        active = { run, host };
+        try {
+            const resume = kind === "path" ? pausePositionOf(action.resumeFrom) : null;
+            const out = await pauseRunStep(host, run, action, id, resume);
+            if ("stop" in out) {
+                try {
+                    helper?.release();
+                }
+                catch { /* best effort */ }
+                if (kind === "path") {
+                    const at = cleanPosition(out.stop.at ?? resume ?? {});
+                    return pauseStopResult(kind, out.stop, pauseStopText(out.stop, `at stroke ${(at.stroke ?? 0) + 1}`, at), Date.now() - started, undefined, at, run.report());
+                }
+                return pauseStopResult(kind, out.stop, `${out.stop.message} Melaya stopped before ${kind} ran (nothing of it was done). Read the screen first, then send it again, or ask the user.`, Date.now() - started, undefined, undefined, run.report());
+            }
+            // elapsedMs of a command that paused covers the pauses too (callers subtract pausedMs, like an approval wait).
+            const r = out.result;
+            const pauses = run.report();
+            return withPauses(pauses ? { ...r, elapsedMs: Math.max(Number(r.elapsedMs) || 0, Date.now() - started) } : r, pauses);
+        }
+        finally {
+            if (active?.run === run)
+                active = null;
+        }
     };
     /** keep_awake and handoff, run by the host. */
     const runLocal = async (kind, action) => {
@@ -773,10 +909,14 @@ export function createCliComputerHost(options = {}) {
             return check.result;
         const kind = String(check.action.kind);
         const id = typeof msg.id === "string" && msg.id ? msg.id : `cli${Date.now()}`;
+        const budget = Math.floor(Number(msg.pauseBudgetMs));
+        const pauseBudgetMs = Number.isFinite(budget) && budget > 0 ? Math.min(MAX_PAUSE_BUDGET_MS, budget) : 0;
         if (kind === "keep_awake" || kind === "handoff")
             return runLocal(kind, check.action);
         if (kind === "batch")
-            return runBatch(id, check.action, check.allowedAppIds, check.allowedApps, check.deadlineMs);
+            return runBatch(id, check.action, check.allowedAppIds, check.allowedApps, check.deadlineMs, pauseBudgetMs);
+        if (pauseNeedsIdle(kind))
+            return runPausable(id, check.action, check.allowedAppIds, check.allowedApps, check.deadlineMs, pauseBudgetMs);
         return runOnHelper(id, check.action, check.allowedAppIds, check.allowedApps, check.deadlineMs);
     };
     const api = {
@@ -802,6 +942,8 @@ export function createCliComputerHost(options = {}) {
         capabilities,
         stopAll(reason) {
             log(`  [computer] stop (${String(reason || "stop").slice(0, 200)})`);
+            // A paused run stops waiting at once (Stop always wins over pause and resume).
+            stopGen++;
             helper?.cancel();
             keepAwake.release();
         },