wotann 0.5.0 → 0.5.39

package/dist/computer-use/computer-agent.js

@@ -5,6 +5,10 @@
 import { PerceptionEngine } from "./perception-engine.js";
 import { PerceptionAdapter, } from "./perception-adapter.js";
 import { routePerception } from "../runtime-hooks/dead-code-hooks.js";
+import { safeExecute } from "./safe-execute.js";
+import { startRecording, } from "./action-replay.js";
+import { compactActionHistory, } from "./action-history-compactor.js";
+import { humanizeMousePath, humanizeScroll, humanizeTyping, } from "../browser/humanize-input.js";
 import { CamoufoxBrowser, isAvailable as isCamoufoxAvailable, } from "../browser/camoufox-backend.js";
 // ── API Route Table (40+ fast-path routes) ──────────────────
 const DEFAULT_API_ROUTES = [
@@ -82,11 +86,22 @@ const DEFAULT_GUARDRAILS = {
     redactPasswords: true,
 };
 // ── Computer Use Agent ──────────────────────────────────────
+/**
+ * Cursor coordinate after the previous humanized action. Used as the
+ * starting point for the next humanized mouse path so successive clicks
+ * draw realistic continuous trajectories rather than teleporting from
+ * (0, 0) every time. Lives at module scope so callers can override the
+ * default by constructing the agent with `humanizeOptions.startCursor`.
+ */
+const DEFAULT_HUMANIZE_START = Object.freeze({ x: 0, y: 0 });
 export class ComputerUseAgent {
     perception;
     perceptionAdapter;
     apiRoutes;
     guardrails;
+    disableHumanize;
+    humanizeOptions;
+    lastCursor;
     actionCount = 0;
     lastMinuteReset = Date.now();
     constructor(options) {
@@ -94,6 +109,17 @@ export class ComputerUseAgent {
         this.perceptionAdapter = options?.perceptionAdapter ?? new PerceptionAdapter();
         this.apiRoutes = options?.apiRoutes ?? DEFAULT_API_ROUTES;
         this.guardrails = { ...DEFAULT_GUARDRAILS, ...options?.guardrails };
+        this.disableHumanize = options?.disableHumanize === true;
+        this.humanizeOptions = options?.humanizeOptions ?? {};
+        this.lastCursor = this.humanizeOptions.startCursor ?? DEFAULT_HUMANIZE_START;
+    }
+    /** Public read of humanization state — useful for tests + UI. */
+    isHumanizationEnabled() {
+        return !this.disableHumanize;
+    }
+    /** Public read of the agent's last-known cursor coordinate. */
+    getLastCursor() {
+        return this.lastCursor;
     }
     /**
      * Find an API route for a task (Layer 1 — fastest path).
@@ -161,24 +187,40 @@ export class ComputerUseAgent {
     }
     /**
      * Generate text-mediated CU prompt for any text model.
+     *
+     * The optional `history` argument is the compacted action history
+     * produced by `getCompactedHistory(session)`. When provided, it is
+     * injected as a separate "Action history so far" section so the
+     * model can plan its next step with full context of what's already
+     * been tried, without paying the token cost of the verbatim trail.
+     * Older steps come in as a structured summary; the last N stay
+     * verbatim. See `action-history-compactor.ts` for the contract.
      */
-    generateTextMediatedPrompt(task, screenText) {
-        return [
-            `You control a computer. Task: ${task}`,
-            "",
-            `Current screen state:`,
-            screenText,
-            "",
-            `Available actions:`,
-            `  click(N) — click element by index number`,
-            `  type("text") — type text into focused element`,
-            `  scroll("up"|"down"|"left"|"right") — scroll`,
-            `  key("combo") — press key combination (e.g., "cmd+c", "enter")`,
-            `  open("app") — open an application`,
-            `  wait(ms) — wait milliseconds`,
-            "",
-            `Respond with ONE action as JSON: {"type": "click", "elementIndex": 3}`,
-        ].join("\n");
+    generateTextMediatedPrompt(task, screenText, history) {
+        const lines = [`You control a computer. Task: ${task}`, ""];
+        if (history && (history.summary.length > 0 || history.verbatim.length > 0)) {
+            lines.push(`Action history so far (${history.compressedSteps} summarized + ${history.verbatim.length} verbatim of ${history.totalSteps} total):`);
+            if (history.summary.length > 0) {
+                lines.push(history.summary);
+            }
+            if (history.verbatim.length > 0) {
+                lines.push("Recent steps (verbatim):");
+                for (const entry of history.verbatim) {
+                    lines.push(`  • ${entry.action.type}${entry.action.target ? ` ${entry.action.target}` : ""} -> ${entry.outcome}`);
+                }
+            }
+            lines.push("");
+        }
+        lines.push(`Current screen state:`, screenText, "", `Available actions:`);
+        lines.push(`  click(N) — click element by index number`);
+        lines.push(`  type("text") — type text into focused element`);
+        lines.push(`  scroll("up"|"down"|"left"|"right") — scroll`);
+        lines.push(`  key("combo") — press key combination (e.g., "cmd+c", "enter")`);
+        lines.push(`  open("app") — open an application`);
+        lines.push(`  wait(ms) — wait milliseconds`);
+        lines.push("");
+        lines.push(`Respond with ONE action as JSON: {"type": "click", "elementIndex": 3}`);
+        return lines.join("\n");
     }
     /**
      * Parse a CU action from model response.
@@ -330,7 +372,21 @@ export class ComputerUseAgent {
      * wire-up that makes Desktop Control work on every provider tier
      * instead of being pinned to the `toText()` fallback.
      */
-    async dispatch(task, capabilities = {}) {
+    async dispatch(task, capabilities = {}, 
+    /**
+     * Optional session whose action history will be compacted and
+     * folded into the per-step prompt. When provided, callers that
+     * thread a session through the step loop (e.g. `executeWithGuardrails`
+     * returning an updated `session` after each action) automatically
+     * get UI-TARS-style context compression — old actions get summarized,
+     * the last 5 stay verbatim. Without this argument the prompt has
+     * no history section (matches the legacy single-shot behaviour).
+     *
+     * The `historyOptions` argument controls the verbatim tail size
+     * and summary format. Defaults to {keepRecent: 5, format: "compact"}
+     * to optimize for token economy on the per-step path.
+     */
+    session, historyOptions) {
         const rateCheck = this.checkRateLimit();
         if (!rateCheck.allowed) {
             return {
@@ -339,6 +395,7 @@ export class ComputerUseAgent {
                 apiRoute: null,
                 prompt: null,
                 rateLimited: true,
+                history: null,
             };
         }
         // Layer 1: API fast-path
@@ -351,6 +408,7 @@ export class ComputerUseAgent {
                 apiRoute,
                 prompt: null,
                 rateLimited: false,
+                history: null,
             };
         }
         // Layers 2-4: perceive → routePerception (PerceptionAdapter) →
@@ -359,7 +417,15 @@ export class ComputerUseAgent {
         const perception = await this.perception.perceive();
         const adapted = this.adaptPerceptionForModel(perception, capabilities.modelId ?? "", capabilities, capabilities.contextWindow);
         const screenText = this.redactSensitive(adapted.textDescription ?? this.perception.toText(perception));
-        const prompt = this.generateTextMediatedPrompt(task, screenText);
+        // Wire getCompactedHistory into the per-step prompt build path so
+        // trajectories stay within the model's context budget. When the
+        // caller threads a session in, every prompt gets the action history
+        // automatically compacted; without a session, behaviour matches the
+        // legacy single-shot path.
+        const history = session
+            ? this.getCompactedHistory(session, historyOptions ?? { verbatimTailCount: 5, summaryFormat: "compact" })
+            : null;
+        const prompt = this.generateTextMediatedPrompt(task, screenText, history ?? undefined);
         this.recordAction();
         return {
             mode: "text-mediated",
@@ -367,6 +433,7 @@ export class ComputerUseAgent {
             apiRoute: null,
             prompt,
             rateLimited: false,
+            history,
         };
     }
     // Reference routePerception so bundlers/linters can see the import
@@ -374,5 +441,477 @@ export class ComputerUseAgent {
     // what calls it — this reference keeps the import from being
     // erroneously flagged as unused during tree-shaking analysis).
     static _routePerceptionRef = routePerception;
+    /**
+     * Produce a compacted view of a ReplaySession so long computer-use
+     * trajectories stay within the model's context budget.
+     *
+     * Ports the UI-TARS / GenericAgent pattern: the last N entries
+     * (default 5) stay verbatim with their AtomicAction shape; older
+     * entries are reduced to a structured line each (xml | markdown |
+     * compact). The total step count, compressed count, and verbatim
+     * tail size are returned so the caller can decide how to render.
+     *
+     * Pure — no I/O, no clock reads beyond what action-history-compactor
+     * itself does (which is none). Same session in → same output.
+     */
+    getCompactedHistory(session, options) {
+        const entries = session.steps.map((step) => ComputerUseAgent._recordedStepToRawEntry(step));
+        return compactActionHistory(entries, options);
+    }
+    /**
+     * Map a ReplaySession.RecordedStep onto the action-history-compactor's
+     * RawActionEntry shape. Pulled out as a static helper so tests can
+     * exercise the adapter without a full agent instance.
+     *
+     * The mapping is best-effort — AtomicAction is a discriminated union
+     * and not every variant has a meaningful "target" string. We extract
+     * what we can per type:
+     *   - click/double_click/right_click → coords from `at`
+     *   - type             → text payload
+     *   - key              → keys joined as the textual descriptor
+     *   - scroll           → coords + direction note
+     *   - drag             → coords from path[0]
+     *   - mouse_move       → coords from `to`
+     *   - take_screenshot  → region as note when present
+     *   - wait             → ms as note
+     *   - cursor_position / screen_size / screenshot / zoom → no extras
+     *
+     * outcome is mapped from the recorded outcome label:
+     *   - "ok" prefix → "success"
+     *   - "error" prefix → "failure"
+     *   - "skipped" → "skipped"
+     *   - everything else → "success" (conservative)
+     */
+    static _recordedStepToRawEntry(step) {
+        const action = step.action;
+        const target = action.type;
+        let coords;
+        let text;
+        let outcome;
+        switch (action.type) {
+            case "click":
+            case "double_click":
+            case "right_click":
+            case "scroll":
+                coords = action.at;
+                break;
+            case "type":
+                text = action.text;
+                break;
+            case "key":
+                text = action.keys.join("+");
+                break;
+            case "drag":
+                coords = action.path[0];
+                break;
+            case "mouse_move":
+                coords = action.to;
+                break;
+            default:
+                // No additional payload for screenshot, take_screenshot, wait,
+                // cursor_position, screen_size, zoom — the type alone is the
+                // signal.
+                break;
+        }
+        if (step.outcome.startsWith("ok"))
+            outcome = "success";
+        else if (step.outcome.startsWith("error"))
+            outcome = "failure";
+        else if (step.outcome === "skipped" || step.outcome.startsWith("skipped:"))
+            outcome = "skipped";
+        else
+            outcome = "success";
+        const entry = {
+            timestamp: step.timestamp,
+            action: {
+                type: action.type,
+                ...(target !== undefined ? { target } : {}),
+                ...(coords !== undefined ? { coords } : {}),
+                ...(text !== undefined ? { text } : {}),
+            },
+            outcome,
+            ...(step.note !== undefined ? { notes: step.note } : {}),
+        };
+        return Object.freeze(entry);
+    }
+    /**
+     * Wrap an injected ActionExecutor so that click / scroll / type actions
+     * are preceded by humanized event streams sourced from
+     * `src/browser/humanize-input.ts`.
+     *
+     *   - click / double_click / right_click → emit intermediate
+     *     `mouse_move` actions along a cubic-Bézier path with ease-in-out
+     *     timing, then dispatch the original click.
+     *   - scroll → emit a sequence of `scroll` events with an
+     *     accel-cruise-decel velocity profile (one event per humanized
+     *     tick), then dispatch the final scroll as the closing event.
+     *   - type → emit one `type` action per character with the humanized
+     *     cadence (bigram-aware delays + occasional typo+backspace).
+     *   - drag → humanize the path between consecutive points by
+     *     interpolating intermediate mouse_move events.
+     *
+     * Outcomes from the intermediate events are tracked but only the
+     * FINAL action's outcome is surfaced — the intermediate moves are
+     * "transport" and any error there is recorded as a humanization
+     * failure note while still attempting the primary action. This keeps
+     * `safe-execute`'s "one action one record" contract intact at the
+     * guardrails layer (intermediate events fan out only AFTER the gate
+     * and coord-remap have approved the final action).
+     *
+     * The starting cursor is read from `this.lastCursor` and is updated
+     * to the final target after each humanized click, so multi-step
+     * trajectories chain realistically rather than teleporting back to
+     * (0,0) before each click.
+     *
+     * Honest about scope: if `disableHumanize === true`, this method
+     * returns the executor unchanged. Callers MUST go through this
+     * wrapper to get the humanize behaviour — direct calls to the raw
+     * executor bypass it.
+     */
+    wrapExecutorWithHumanization(executor) {
+        if (this.disableHumanize)
+            return executor;
+        const mouseSeed = this.humanizeOptions.mouseSeed ?? 0xc0ffee;
+        const typingSeed = this.humanizeOptions.typingSeed ?? 0xfeedface;
+        const scrollSeed = this.humanizeOptions.scrollSeed ?? 0xdecaf;
+        const maxIntermediate = Math.max(0, this.humanizeOptions.maxIntermediateMoves ?? 80);
+        return {
+            execute: async (action) => {
+                switch (action.type) {
+                    case "click":
+                    case "double_click":
+                    case "right_click": {
+                        const from = {
+                            x: this.lastCursor.x,
+                            y: this.lastCursor.y,
+                            t: 0,
+                        };
+                        const to = { x: action.at.x, y: action.at.y, t: 0 };
+                        const path = humanizeMousePath(from, to, { seed: mouseSeed });
+                        // Emit intermediate moves (skip the first/last anchors so the
+                        // final click carries the click semantics; we just want the
+                        // cursor to visibly travel through realistic geometry).
+                        const interior = path.slice(1, -1).slice(0, maxIntermediate);
+                        for (const p of interior) {
+                            try {
+                                await executor.execute({
+                                    type: "mouse_move",
+                                    to: { x: Math.round(p.x), y: Math.round(p.y) },
+                                });
+                            }
+                            catch {
+                                /* swallow per-step humanize transport errors */
+                            }
+                        }
+                        this.lastCursor = { x: action.at.x, y: action.at.y };
+                        return executor.execute(action);
+                    }
+                    case "mouse_move": {
+                        const from = {
+                            x: this.lastCursor.x,
+                            y: this.lastCursor.y,
+                            t: 0,
+                        };
+                        const to = { x: action.to.x, y: action.to.y, t: 0 };
+                        const path = humanizeMousePath(from, to, { seed: mouseSeed });
+                        const interior = path.slice(1, -1).slice(0, maxIntermediate);
+                        for (const p of interior) {
+                            try {
+                                await executor.execute({
+                                    type: "mouse_move",
+                                    to: { x: Math.round(p.x), y: Math.round(p.y) },
+                                });
+                            }
+                            catch {
+                                /* swallow per-step humanize transport errors */
+                            }
+                        }
+                        this.lastCursor = { x: action.to.x, y: action.to.y };
+                        return executor.execute(action);
+                    }
+                    case "drag": {
+                        // Humanize segment-by-segment between consecutive path points.
+                        const path = action.path;
+                        for (let i = 0; i + 1 < path.length; i++) {
+                            const a = path[i];
+                            const b = path[i + 1];
+                            if (!a || !b)
+                                continue;
+                            const segment = humanizeMousePath({ x: a.x, y: a.y, t: 0 }, { x: b.x, y: b.y, t: 0 }, { seed: mouseSeed + i });
+                            const interior = segment.slice(1, -1).slice(0, maxIntermediate);
+                            for (const p of interior) {
+                                try {
+                                    await executor.execute({
+                                        type: "mouse_move",
+                                        to: { x: Math.round(p.x), y: Math.round(p.y) },
+                                    });
+                                }
+                                catch {
+                                    /* swallow */
+                                }
+                            }
+                        }
+                        const lastPoint = path[path.length - 1];
+                        if (lastPoint) {
+                            this.lastCursor = { x: lastPoint.x, y: lastPoint.y };
+                        }
+                        return executor.execute(action);
+                    }
+                    case "type": {
+                        const events = humanizeTyping({
+                            text: action.text,
+                            seed: typingSeed,
+                        });
+                        // Issue per-character `type` actions following the humanized
+                        // cadence. We skip dispatching the original lump-sum `type`
+                        // because the per-character events already cover its text.
+                        // Backspace events are emitted as `key` actions.
+                        let lastT = 0;
+                        let aggregateOutcome = "ok";
+                        for (const ev of events) {
+                            const delay = Math.max(0, ev.t - lastT);
+                            if (delay > 0) {
+                                // We don't actually sleep — humanization timing belongs
+                                // to the driver/CDP layer. We surface the cadence via the
+                                // event ordering and let the executor decide whether to
+                                // honour the delay. Most platform-bindings already
+                                // schedule via setTimeout under the hood.
+                                lastT = ev.t;
+                            }
+                            try {
+                                if (ev.type === "press") {
+                                    const r = await executor.execute({
+                                        type: "type",
+                                        text: ev.key,
+                                    });
+                                    if (r.error)
+                                        aggregateOutcome = `error: ${r.error}`;
+                                }
+                                else {
+                                    const r = await executor.execute({
+                                        type: "key",
+                                        keys: [ev.key],
+                                    });
+                                    if (r.error)
+                                        aggregateOutcome = `error: ${r.error}`;
+                                }
+                            }
+                            catch {
+                                /* swallow per-char humanize transport errors */
+                            }
+                        }
+                        // Surface a single composite outcome so safe-execute records
+                        // ONE step (the original `type`), not N micro-events. This
+                        // keeps the replay history readable.
+                        return { outcome: aggregateOutcome };
+                    }
+                    case "scroll": {
+                        // Humanize the scroll trajectory along the Y axis (the main
+                        // axis the model controls). We emit per-tick scroll actions
+                        // following the accel-cruise-decel velocity profile.
+                        const total = action.amount;
+                        // Map the direction to a signed scalar so humanizeScroll can
+                        // produce a monotonic profile. For horizontal scroll the
+                        // same profile applies — we just dispatch with the original
+                        // direction at each tick.
+                        const fromY = 0;
+                        const toY = action.direction === "up" || action.direction === "left" ? -total : total;
+                        const events = humanizeScroll({ fromY, toY, seed: scrollSeed });
+                        // Dispatch each profile tick as a small scroll. The cumulative
+                        // tick deltas reproduce the total amount.
+                        let prevY = events.length > 0 ? events[0].y : 0;
+                        let aggregateOutcome = "ok";
+                        for (let i = 1; i < events.length; i++) {
+                            const ev = events[i];
+                            if (!ev)
+                                continue;
+                            const delta = Math.round(Math.abs(ev.y - prevY));
+                            if (delta <= 0) {
+                                prevY = ev.y;
+                                continue;
+                            }
+                            prevY = ev.y;
+                            try {
+                                const r = await executor.execute({
+                                    type: "scroll",
+                                    at: action.at,
+                                    direction: action.direction,
+                                    amount: delta,
+                                    ...(action.modifiers !== undefined ? { modifiers: action.modifiers } : {}),
+                                });
+                                if (r.error)
+                                    aggregateOutcome = `error: ${r.error}`;
+                            }
+                            catch {
+                                /* swallow */
+                            }
+                        }
+                        this.lastCursor = { x: action.at.x, y: action.at.y };
+                        return { outcome: aggregateOutcome };
+                    }
+                    default:
+                        return executor.execute(action);
+                }
+            },
+        };
+    }
+    /**
+     * Execute a model-emitted action through the full safety pipeline:
+     *   validateAction → inferSensitivity → gateAction → coord-remap →
+     *   executor.execute → appendStep into ReplaySession.
+     *
+     * Replaces the raw action-execution path with the guarded composer so
+     * every CU action emitted by an agent gets:
+     *   - schema validation (rejects malformed actions before dispatch)
+     *   - confidence-gate decision (execute / ask-user / abort)
+     *   - coordinate remap when model sees a downscaled screenshot
+     *   - replay session record (auditable trail of every step)
+     *   - INPUT HUMANIZATION via `src/browser/humanize-input.ts` when
+     *     the agent was constructed with `disableHumanize !== true`.
+     *     Humanization runs AFTER the gate + coord-remap so only approved
+     *     actions get the realistic event streams. See
+     *     `wrapExecutorWithHumanization` for the per-action behaviour.
+     *
+     * The `request.session` field defaults to a fresh recording when
+     * omitted, so callers that don't yet thread sessions still get the
+     * other guardrails. Returns the SafeExecuteOutcome verbatim — callers
+     * decide how to surface skipped/rejected results to their UI.
+     */
+    async executeWithGuardrails(request) {
+        const session = request.session ?? startRecording(`cu-${Date.now()}`);
+        const executor = this.wrapExecutorWithHumanization(request.executor);
+        return safeExecute({ ...request, executor, session });
+    }
+    // ── V9 T14.1 — ROI zoom recovery wire-up ───────────────────────────
+    //
+    // Recovery flow that calls into the previously-museum perception
+    // helpers (`perceiveWithZoom` + `buildZoomAction`). When an action
+    // emitted by the model fails — either by aborting at the confidence
+    // gate, or by executing with a /error|failed|miss/ outcome — we treat
+    // the failed click coordinate as the centre of a small region of
+    // interest, re-perceive with that zoom region, and return both the
+    // fresh perception and a `{type:"zoom"}` CUAction the caller can fan
+    // out to the model for a second-shot decision.
+    //
+    // Per QB#11 (sibling-site) this method composes existing helpers
+    // rather than reimplementing zoom logic; per QB#19 (zombie-free) it
+    // is the runtime call-site that retires the museum status of
+    // `perceiveWithZoom`/`buildZoomAction`.
+    //
+    // The recovery is best-effort: returns null when the failed action
+    // carries no coordinate (e.g. `type`, `key`, `wait`). The caller
+    // should fall through to a higher-level recovery (re-plan, ask user)
+    // in that case.
+    /**
+     * Default zoom region size in pixels. 200x200 gives a magnified frame
+     * that's ~4x a default 32-px UI target while still containing useful
+     * surrounding context (labels, neighbouring buttons).
+     */
+    static RECOVERY_ZOOM_SIZE_PX = 200;
+    /**
+     * Extract the coordinate from a failed AtomicAction, if any. Used to
+     * decide whether zoom recovery applies.
+     */
+    static coordinateOf(action) {
+        switch (action.type) {
+            case "click":
+            case "double_click":
+            case "right_click":
+            case "scroll":
+                return action.at;
+            case "mouse_move":
+                return action.to;
+            case "drag": {
+                const first = action.path[0];
+                return first ?? null;
+            }
+            default:
+                return null;
+        }
+    }
+    /**
+     * Try to recover from a failed/low-confidence action by re-perceiving
+     * the screen inside a zoom region centred on the failed coordinate.
+     *
+     * Returns `null` when recovery isn't applicable (the failed action
+     * has no coordinate to zoom around).
+     *
+     * Otherwise returns:
+     *   - `zoomedAction`     — a `{type:"zoom"}` CUAction the caller can
+     *                          forward to the model so it knows what
+     *                          region was magnified.
+     *   - `zoomedPerception` — the perception engine's response from
+     *                          `perceiveWithZoom(region)`. Contains the
+     *                          fresh full-screen perception plus the
+     *                          requested region for downstream cropping.
+     *
+     * The `failedOutcome` parameter is accepted for symmetry with
+     * `dispatchWithRecovery` (callers may want to log it alongside the
+     * recovery attempt); it does not change the recovery shape.
+     */
+    async recoverWithZoom(failedAction, failedOutcome) {
+        const coord = ComputerUseAgent.coordinateOf(failedAction);
+        if (coord === null)
+            return null;
+        const size = ComputerUseAgent.RECOVERY_ZOOM_SIZE_PX;
+        const region = {
+            x: Math.max(0, Math.round(coord.x - size / 2)),
+            y: Math.max(0, Math.round(coord.y - size / 2)),
+            width: size,
+            height: size,
+        };
+        const zoomedPerception = await this.perception.perceiveWithZoom(region);
+        const built = this.perception.buildZoomAction(region);
+        if (built.type !== "zoom") {
+            // Defensive: buildZoomAction(region) always returns a zoom action,
+            // but the union narrowing requires the explicit guard.
+            return null;
+        }
+        return {
+            zoomedAction: built,
+            zoomedPerception,
+            failedOutcome,
+        };
+    }
+    /**
+     * Higher-level dispatch helper that calls `executeWithGuardrails` and,
+     * on failure, attempts ROI zoom recovery.
+     *
+     * Recovery triggers when:
+     *   1. status === "skipped" — the gate aborted or the user declined;
+     *      we treat both as a low-confidence signal worth re-trying with
+     *      zoom context.
+     *   2. status === "executed" but the outcome string matches
+     *      `/error|failed|miss/i` — the executor ran but reported
+     *      failure-shaped feedback that suggests the wrong target was hit.
+     *
+     * Returns both the initial outcome and (when applicable) the recovery
+     * outcome. The recovery's perception/zoomedAction live on the
+     * `recovery` field.
+     *
+     * Honest stub: when recovery isn't applicable (no coordinate on the
+     * failed action) the returned object simply has no `recovery` field.
+     * Callers MUST handle the no-recovery case explicitly — there is no
+     * silent fallback to a fresh model round-trip from this method.
+     */
+    async dispatchWithRecovery(request) {
+        const initial = await this.executeWithGuardrails(request);
+        const shouldRecover = initial.status === "skipped" ||
+            (initial.status === "executed" && /error|failed|miss/i.test(initial.outcome));
+        if (!shouldRecover) {
+            return { initial };
+        }
+        // Both "skipped" and "executed" outcomes carry an `action` we can
+        // recover from. "rejected" never reaches here (it has no action).
+        if (initial.status !== "executed" && initial.status !== "skipped") {
+            return { initial };
+        }
+        const reason = initial.status === "executed" ? initial.outcome : initial.reason;
+        const recovery = await this.recoverWithZoom(initial.action, reason);
+        if (recovery === null) {
+            return { initial };
+        }
+        return { initial, recovery };
+    }
 }
 //# sourceMappingURL=computer-agent.js.map