@beeos-ai/device-agent 0.15.0 → 0.16.1

package/dist/agent-runtime/core.js

@@ -1,5 +1,5 @@
 /**
- * agent-runtime/core — Plan-Act-Reflect loop.
+ * Android observation, prediction, execution and deterministic checks.
  *
  * Mirrors the Python reference at
  *   /Users/heat/workspace/deviceagent_research/deviceagent/agent_runtime/loop/core.py
@@ -34,10 +34,14 @@ import { proCalls } from "./adapters/pro.js";
 import { buildProFrame } from "./pro-perception.js";
 import { isTerminal } from "@beeos-ai/device-common";
 import { formatFeedbackForPrompt } from "./feedback.js";
-import { HierarchicalReflector } from "./reflection.js";
+import { ToolBatch } from "./tool-batch.js";
+import { ExecutionChecks } from "./execution-checks.js";
 import { renderProOperatorContext } from "./pro-operator.js";
 import { checkProPerception } from "./pro-target-check.js";
+import { compactUiXmlEvidence } from "../device/ui-xml.js";
+import { visualStateHash } from "./visual-state.js";
 import { waitForAction } from "../core/wait.js";
+import { abortableRead } from "../core/abortable-read.js";
 import { ProTaskMemory } from "./pro-memory.js";
 import { configuredOcrProvider } from "./ocr.js";
 import { resolveObservationMode, } from "./observation-mode.js";
@@ -46,18 +50,19 @@ import { resolveObservationMode, } from "./observation-mode.js";
 /* ──────────────────────────────────────────────────────────────────────── */
 export class AgentLoop {
     opts;
+    batch = new ToolBatch();
     static DEFAULT_MAX_STEPS = 30;
     static DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
     history = [];
     evidence;
+    observationIndex;
     proMemory;
-    reflector;
+    executionChecks;
     notes = [];
-    trajectoryVerdict;
     /**
      * One-way bus for diagnostics that need to surface in the next
      * `Observation.task` prefix. Drained right before each predict; entries
-     * are pushed by veto / act_failed / trajectory-reflector paths. See
+     * are pushed by veto and act_failed paths. See
      * `feedback.ts` for the rationale (closes the reflection feedback loop
      * without adapter protocol changes).
      */
@@ -79,9 +84,12 @@ export class AgentLoop {
      * four identical actions.
      */
     vetoCodeCount = {};
+    signal;
+    deadline = Infinity;
+    timeoutReason = new Error("Task deadline reached");
     constructor(opts) {
         this.opts = opts;
-        this.reflector = opts.reflector ?? new HierarchicalReflector(opts.adapter);
+        this.executionChecks = opts.executionChecks ?? new ExecutionChecks();
         this.proMemory = opts.proOperator || opts.adapter.nativeTools ? (opts.proMemory ?? new ProTaskMemory()) : undefined;
     }
     /** Push feedback into both the pending queue and the immutable log. */
@@ -90,15 +98,28 @@ export class AgentLoop {
         this.feedbackLog.push(item);
     }
     async run() {
+        const budget = new AbortController();
+        this.deadline = Date.now() + (this.opts.timeoutMs ?? AgentLoop.DEFAULT_TIMEOUT_MS);
+        this.signal = AbortSignal.any([budget.signal, ...(this.opts.signal ? [this.opts.signal] : [])]);
+        const timer = setTimeout(() => budget.abort(this.timeoutReason), Math.max(0, this.deadline - Date.now()));
+        timer.unref?.();
+        try {
+            return await this.runLoop();
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    async runLoop() {
         const maxSteps = this.opts.maxSteps ?? AgentLoop.DEFAULT_MAX_STEPS;
         const timeoutMs = this.opts.timeoutMs ?? AgentLoop.DEFAULT_TIMEOUT_MS;
-        const deadline = Date.now() + timeoutMs;
+        const deadline = this.deadline;
         const usage = { inputTokens: 0, outputTokens: 0 };
         let step = 0;
         let lastError;
         let finalText = "";
         while (step < maxSteps) {
-            if (this.opts.signal?.aborted) {
+            if (this.signal?.aborted) {
                 return this.finish("cancelled", step, "Task cancelled", usage, lastError);
             }
             if (Date.now() > deadline) {
@@ -115,18 +136,18 @@ export class AgentLoop {
             let obs;
             try {
                 try {
-                    obs = await this.observe(deadline);
+                    obs = await abortableRead(() => this.observe(deadline), this.signal);
                 }
                 catch (error) {
                     if (!this.opts.adapter.retryObservation || !/timed out|timeout|ECONNRESET/i.test(errMsg(error)) || Date.now() >= deadline)
                         throw error;
                     const retrySignal = AbortSignal.timeout(Math.max(1, deadline - Date.now()));
-                    await delay(250, undefined, { signal: this.opts.signal ? AbortSignal.any([this.opts.signal, retrySignal]) : retrySignal });
-                    obs = await this.observe(deadline);
+                    await delay(250, undefined, { signal: this.signal ? AbortSignal.any([this.signal, retrySignal]) : retrySignal });
+                    obs = await abortableRead(() => this.observe(deadline), this.signal);
                 }
             }
             catch (e) {
-                if (this.opts.signal?.aborted) {
+                if (this.signal?.aborted) {
                     return this.finish("cancelled", step, "Task cancelled", usage, lastError);
                 }
                 const err = {
@@ -142,11 +163,15 @@ export class AgentLoop {
                 return this.finish("timeout", step, `agent exceeded ${timeoutMs}ms budget`, usage, lastError);
             }
             // Compute a normalised screen-state fingerprint. Used downstream by
-            // reflectors to detect "no progress" stalls more reliably than
+            // execution checks to detect "no progress" stalls more reliably than
             // coordinate-similarity heuristics. Only meaningful when uiDump is
             // present; pure-vision flows fall back to the legacy 8px rule.
-            obs.screenStateHash = computeScreenStateHash(obs.uiDump);
+            obs.screenStateHash = computeScreenStateHash(obs.uiDump) ??
+                (this.opts.adapter.nativeTools ? await visualStateHash(obs.screenshotB64) : undefined);
+            if (this.signal?.aborted)
+                return this.finish("cancelled", step, "Task cancelled", usage, lastError);
             this.proMemory?.observe(obs);
+            this.observationIndex = step;
             await this.fire("onObservation", { index: step, observation: obs });
             // Stamp the previous step's `screenStateHashAfter` with the current
             // observation's fingerprint — the MCP act + roundtrip + subsequent
@@ -163,12 +188,12 @@ export class AgentLoop {
             // uiDump's top text/content-desc nodes (when the effective observation
             // mode includes XML); otherwise we fall back to the
             // grounder's rationale once predict() returns. This is what
-            // downstream reflectors read so they don't need the screenshot.
+            // downstream execution checks read so they don't need the screenshot.
             let observationSummary = summarizeUiDump(obs.uiDump);
-            this.evidence = this.opts.proOperator ? { uiDump: obs.uiDump?.slice(0, 12000),
+            this.evidence = this.opts.proOperator || this.opts.adapter.nativeTools ? { uiDump: obs.uiDump ? compactUiXmlEvidence(obs.uiDump) : undefined,
                 screenshotB64: obs.uiDump ? undefined : obs.screenshotB64 } : undefined;
             // ── 2. Predict ────────────────────────────────────────────────
-            // Splice any pending reflector feedback into the prompt so the
+            // Splice any pending execution-check feedback into the prompt so the
             // grounder sees that its previous action was blocked / failed
             // before it picks the next one. This closes the reflection
             // feedback loop without touching adapter protocols. The drained
@@ -184,36 +209,44 @@ export class AgentLoop {
             let prediction;
             let streamedPredictionText = false;
             try {
-                const mcpTools = this.opts.adapter.nativeTools ? await this.opts.mcp.listTools?.() : undefined;
+                const mcpTools = this.opts.adapter.nativeTools
+                    ? await abortableRead(async () => this.opts.mcp.listTools?.(), this.signal) : undefined;
                 if (this.opts.adapter.nativeTools && !mcpTools)
                     throw new Error("Native model tools require an MCP tools/list-capable runtime");
+                const queued = this.batch.next(obs, this.history);
                 const modelHistory = this.opts.proOperator
                     ? [...(this.opts.priorHistory ?? []), ...this.history]
                     : this.history;
-                prediction = await this.opts.adapter.predictAction(obsForPredict, modelHistory, {
+                prediction = queued ?? await abortableRead(() => this.opts.adapter.predictAction(obsForPredict, modelHistory, {
                     mcpTools,
-                    signal: this.opts.signal,
+                    signal: this.signal,
                     contextInstruction: this.opts.proOperator
                         ? renderProOperatorContext(obsForPredict.task, modelHistory) +
+                            `\n${this.opts.operatorGuidance ?? ""}` +
                             `\n${this.proMemory?.render(obsForPredict.task) ?? ""}` +
                             (obs.extra?.ocrStatus === "unavailable" ? "\nOCR failed; absence of OCR text is not evidence that the screen has no text." : "")
                         : this.opts.adapter.nativeTools ? this.proMemory?.render(obsForPredict.task) : undefined,
                     hooks: {
                         onText: this.opts.hooks?.onText
                             ? async (delta) => {
-                                if (!delta)
+                                if (!delta || this.signal?.aborted)
                                     return;
                                 streamedPredictionText = true;
                                 await this.fire("onText", delta);
                             }
                             : undefined,
-                        onReasoning: this.opts.hooks?.onReasoning,
+                        onReasoning: this.opts.hooks?.onReasoning
+                            ? async (delta) => { if (!this.signal?.aborted)
+                                await this.opts.hooks?.onReasoning?.(delta); }
+                            : undefined,
                     },
-                });
+                }), this.signal);
+                if (!queued)
+                    this.batch.enqueue(prediction, obs);
                 this.pendingFeedback = [];
             }
             catch (e) {
-                if (this.opts.signal?.aborted) {
+                if (this.signal?.aborted) {
                     return this.finish("cancelled", step, "Task cancelled", usage, lastError);
                 }
                 const fatal = isPermanentModelError(e);
@@ -244,6 +277,11 @@ export class AgentLoop {
                 }
                 continue;
             }
+            if (this.signal?.aborted) {
+                prediction.toolResult = { ok: false, executed: false, error: "Cancelled before dispatch" };
+                this.recordHistory(step, prediction, observationSummary, "skipped", "Cancelled", obs.screenStateHash, false);
+                return this.finish("cancelled", step, "Task cancelled", usage, lastError);
+            }
             usage.inputTokens += prediction.usage.inputTokens;
             usage.outputTokens += prediction.usage.outputTokens;
             if (prediction.usage.cachedInputTokens) {
@@ -262,11 +300,18 @@ export class AgentLoop {
             if (prediction.rationale && !streamedPredictionText) {
                 await this.fire("onText", prediction.rationale);
             }
+            if (this.signal?.aborted) {
+                prediction.toolResult = { ok: false, executed: false, error: "Cancelled before dispatch" };
+                this.recordHistory(step, prediction, observationSummary, "skipped", "Cancelled", obs.screenStateHash, false);
+                return this.finish("cancelled", step, "Task cancelled", usage, lastError);
+            }
             // ── 3. Act ─────────────────────────────────────────────────────
             const action = prediction.action;
+            if (action.payload._proRejected)
+                prediction.toolResult = { ok: false, executed: false, error: action.payload._proRejected };
             // Phase 2.1 — `take_note` is a *local* book-keeping verb. It does
             // NOT hit MCP, does NOT consume act / pre-sanity budget on the
-            // grounder side, and is recorded in history so reflectors / replan
+            // grounder side, and is recorded in history so execution checks / replan
             // can see it. Step counter still ticks (we already incremented
             // above) so a runaway grounder that only emits notes still hits
             // the heuristic veto.
@@ -275,7 +320,7 @@ export class AgentLoop {
                     const call = proCalls(action)[0];
                     await this.fire("onTool", { name: call.name, args: {}, status: "start" });
                     try {
-                        this.opts.signal?.throwIfAborted();
+                        this.signal?.throwIfAborted();
                         const local = action.payload?._proLocal;
                         if (local === "search_memory")
                             prediction.toolResult = this.proMemory?.search(String(action.payload?.query ?? "")) ?? [];
@@ -290,14 +335,12 @@ export class AgentLoop {
                         else if (local && local !== "take_note") {
                             if (!this.opts.mcp.callTool)
                                 throw new Error("MCP callTool unavailable");
-                            const r = await this.opts.mcp.callTool(call.name, JSON.parse(call.arguments));
+                            const r = await abortableRead(() => this.opts.mcp.callTool(call.name, JSON.parse(call.arguments), { signal: this.signal }), this.signal);
                             prediction.toolResult = { ok: r.ok, data: r.structured ?? r.raw };
                         }
-                        this.opts.signal?.throwIfAborted();
+                        this.signal?.throwIfAborted();
                     }
                     catch (e) {
-                        if (this.opts.signal?.aborted)
-                            return this.finish("cancelled", step, "Task cancelled", usage, lastError);
                         prediction.toolResult = { ok: false, error: errMsg(e) };
                     }
                     const failed = prediction.toolResult?.ok === false;
@@ -307,8 +350,10 @@ export class AgentLoop {
                         if (note)
                             this.notes.push(note);
                     }
-                    this.recordHistory(step, prediction, observationSummary, failed ? "act_failed" : "ok", failed ? JSON.stringify(prediction.toolResult) : undefined, obs.screenStateHash);
+                    this.recordHistory(step, prediction, observationSummary, failed ? "act_failed" : "ok", failed ? JSON.stringify(prediction.toolResult) : undefined, obs.screenStateHash, false);
                     await this.fireStep(step, prediction, false);
+                    if (this.signal?.aborted)
+                        return this.finish("cancelled", step, "Task cancelled", usage, lastError);
                     continue;
                 }
                 const note = stringFromPayload(action.payload, "note") ?? prediction.rationale ?? "";
@@ -321,7 +366,7 @@ export class AgentLoop {
                 this.vetoCodeCount = {};
                 // Heuristic veto still applies (4 identical take_note in a row =
                 // stalled grounder), so fall through to the bottom check.
-                const veto = this.reflector.maybeVeto(this.history, step, maxSteps);
+                const veto = this.executionChecks.maybeVeto(this.history, step, maxSteps);
                 if (veto) {
                     const err = {
                         code: "REFLECTION_VETO",
@@ -331,25 +376,13 @@ export class AgentLoop {
                     await this.fire("onError", err);
                     return this.finish("reflection_veto", step, veto, usage, err);
                 }
-                // Trajectory check still applies — a runaway grounder that only
-                // emits notes is exactly the "stuck" case we want to bail on.
-                const trajVeto = await this.maybeRunTrajectoryReflector(step, maxSteps, usage);
-                if (trajVeto) {
-                    const err = {
-                        code: "REFLECTION_VETO",
-                        message: trajVeto,
-                        fatal: true,
-                    };
-                    await this.fire("onError", err);
-                    return this.finish("reflection_veto", step, trajVeto, usage, err);
-                }
                 continue;
             }
             // Pre-action sanity (Phase 1.3) — block obviously-broken candidates
             // before dispatch. Terminal verbs are short-circuited below so they
             // are never blocked.
             if (!isTerminal(action)) {
-                const veto = this.reflector.maybeBlockAction(this.history, action);
+                const veto = this.executionChecks.maybeBlockAction(this.history, action);
                 if (veto) {
                     const note = `pre-sanity blocked: ${veto.code} — ${veto.reason}`;
                     this.recordHistory(step, prediction, note, "skipped", veto.reason, obs.screenStateHash);
@@ -428,86 +461,91 @@ export class AgentLoop {
                     return this.finish("call_for_user", step, finalText, usage, lastError);
                 }
                 // Phase-1: surfacing the event is enough — wait-for-user is
-                // implemented by the orchestrator layer (OrchestratorAgent).
+                // not available in the Android runtime.
                 return this.finish("call_for_user", step, finalText, usage, lastError);
             }
             const toolArgs = actionToToolArgs(action);
+            const toolName = proCalls(action)[0]?.name ?? action.type;
             await this.fire("onTool", {
-                name: action.type,
+                name: toolName,
                 args: toolArgs,
                 status: "start",
             });
             const t0 = Date.now();
             let actResult;
+            let actionDispatched = false;
             try {
                 let dispatchAction = this.scaleAction(action, obs);
                 this.proMemory?.assertCanScroll(dispatchAction);
-                if (this.opts.proOperator || this.opts.adapter.nativeTools) {
-                    dispatchAction = await checkProPerception(dispatchAction, obs, this.opts.mcp, this.opts.signal);
+                if ((this.opts.proOperator || this.opts.adapter.nativeTools) && !this.opts.adapter.checkAction) {
+                    dispatchAction = await abortableRead(() => checkProPerception(dispatchAction, obs, this.opts.mcp, this.signal), this.signal);
                 }
                 if (this.opts.adapter.checkAction && !["wait", "home", "back", "launch_app"].includes(action.type)) {
                     const signal = AbortSignal.any([AbortSignal.timeout(Math.max(1, deadline - Date.now())),
-                        ...(this.opts.signal ? [this.opts.signal] : [])]);
-                    const fresh = await this.observe(deadline);
-                    const verdict = await this.opts.adapter.checkAction(dispatchAction, fresh, prediction.rationale, signal);
+                        ...(this.signal ? [this.signal] : [])]);
+                    const fresh = await abortableRead(() => this.observe(deadline), signal);
+                    // Grounding and semantic review share one fresh snapshot. Still
+                    // recheck drift after the model review, immediately before dispatch.
+                    dispatchAction = await abortableRead(() => checkProPerception(dispatchAction, obs, this.opts.mcp, signal, fresh), signal);
+                    const intent = stringFromPayload(dispatchAction.payload, "_proIntent") ?? prediction.rationale;
+                    const verdict = await abortableRead(() => this.opts.adapter.checkAction(dispatchAction, fresh, intent, signal), signal);
                     usage.inputTokens += verdict.usage.inputTokens;
                     usage.outputTokens += verdict.usage.outputTokens;
                     signal.throwIfAborted();
                     if (verdict.decision === "handoff") {
                         const message = `Action not executed. Human confirmation/manual action required: ${verdict.reason}`;
                         this.recordHistory(step, prediction, observationSummary, "skipped", message, obs.screenStateHash);
-                        await this.fire("onTool", { name: action.type, args: toolArgs, status: "end", isError: true,
+                        await this.fire("onTool", { name: toolName, args: toolArgs, status: "end", isError: true,
                             result: { confirmationRequired: true, executed: false, message } });
                         return this.finish("call_for_user", step, message, usage, lastError);
                     }
                     if (verdict.decision !== "allow")
                         throw new Error(`Action target rejected: ${verdict.reason}`);
                     // Semantic review takes time: reject drift again immediately before dispatch.
-                    await checkProPerception(dispatchAction, fresh, this.opts.mcp, signal);
+                    await abortableRead(() => checkProPerception(dispatchAction, fresh, this.opts.mcp, signal), signal);
                 }
-                this.opts.signal?.throwIfAborted();
-                if (Date.now() >= deadline)
+                this.signal?.throwIfAborted();
+                if (Date.now() >= deadline) {
+                    prediction.toolResult = { ok: false, executed: false, error: "Task deadline reached before dispatch" };
+                    this.recordHistory(step, prediction, observationSummary, "skipped", "Deadline reached", obs.screenStateHash, false);
+                    await this.fire("onTool", { name: toolName, args: toolArgs, status: "end", isError: true, result: prediction.toolResult });
                     return this.finish("timeout", step, "Task deadline reached before dispatch", usage, { code: "TIMEOUT", message: "Task deadline reached before dispatch", fatal: true });
+                }
                 const call = proCalls(dispatchAction)[0];
                 let r;
                 if (call && action.payload?._proSequence) {
                     if (!this.opts.mcp.callTool)
                         throw new Error("MCP callTool unavailable");
                     const points = action.payload._proSequence;
-                    const completed = [];
-                    prediction.toolResult = { ok: false, completed };
-                    for (const point of points) {
-                        this.opts.signal?.throwIfAborted();
-                        if (Date.now() >= deadline)
-                            throw new Error("Task deadline reached during click sequence");
-                        const result = await this.opts.mcp.callTool("tap", point);
-                        if (!result.ok)
-                            throw new Error(`Sequence stopped after ${completed.length} taps: ${JSON.stringify(result.structured ?? result.raw)}`);
-                        completed.push(point);
-                        if (completed.length < points.length)
-                            await delay(50, undefined, { signal: this.opts.signal });
-                    }
-                    prediction.toolResult = { ok: true, completed, message: "Taps dispatched; verify the resulting screen" };
-                    r = { ok: true, action: action.type };
+                    if (step + points.length - 1 > maxSteps)
+                        throw new Error("Insufficient action budget for click_sequence");
+                    step += points.length - 1;
+                    actionDispatched = true;
+                    const result = await this.opts.mcp.callTool("click_sequence", { points }, { signal: this.signal });
+                    prediction.toolResult = { ok: result.ok, data: result.structured ?? result.raw };
+                    r = { ok: result.ok, action: action.type, error: result.ok ? undefined : { message: JSON.stringify(prediction.toolResult) } };
                 }
                 else if (action.type === "wait") {
-                    await waitForAction(action.payload, this.opts.signal, deadline);
+                    await waitForAction(action.payload, this.signal, deadline);
                     r = { ok: true, action: action.type };
                 }
                 else if (call && action.payload?._proMcp) {
                     if (!this.opts.mcp.callTool)
                         throw new Error("MCP callTool unavailable");
-                    const result = await this.opts.mcp.callTool(String(action.payload._proMcp), action.payload._proDispatchArgs ?? JSON.parse(call.arguments));
+                    actionDispatched = true;
+                    const result = await this.opts.mcp.callTool(String(action.payload._proMcp), action.payload._proDispatchArgs ?? JSON.parse(call.arguments), { signal: this.signal });
                     prediction.toolResult = { ok: result.ok, data: result.structured ?? result.raw };
                     r = { ok: result.ok, action: action.type, error: result.ok ? undefined : { message: JSON.stringify(prediction.toolResult) } };
                 }
-                else
-                    r = await this.opts.mcp.act(dispatchAction);
+                else {
+                    actionDispatched = true;
+                    r = await this.opts.mcp.act(dispatchAction, { signal: this.signal });
+                }
                 // The MCP `act()` envelope can fail two ways:
                 //   1. throw — network / unreachable / SDK transport error (caught below)
                 //   2. resolve with `ok: false` — server returned `isError: true`
                 //      OR (post r3 ActionableError model) `structuredContent.actionable: true`.
-                // Both paths must follow the act_failed branch so the reflector /
+                // Both paths must follow the act_failed branch so the executionChecks /
                 // feedback layer sees the same shape; the only difference is that
                 // actionable errors carry `error.subtype` and we surface that to the
                 // grounder so the LLM can self-correct ("you passed an invalid path"
@@ -532,7 +570,7 @@ export class AgentLoop {
                         fatal: false,
                     };
                     await this.fire("onTool", {
-                        name: action.type,
+                        name: toolName,
                         args: toolArgs,
                         status: "end",
                         result: errInfo,
@@ -548,17 +586,21 @@ export class AgentLoop {
                         code: isActionable ? `actionable:${subtype ?? "unknown"}` : (subtype ?? "act_failed"),
                         reason: errInfo.message,
                     });
-                    await this.maybeRunActionReflector(prediction, "act_failed", usage);
                     continue;
                 }
                 actResult = r.result ?? r;
             }
             catch (e) {
-                if (this.opts.signal?.aborted)
+                if (this.signal?.aborted) {
+                    prediction.toolResult ??= { ok: false, executed: actionDispatched ? "unknown" : false,
+                        error: "Cancelled during dispatch; do not assume success or replay without observation." };
+                    this.recordHistory(step, prediction, observationSummary, "act_failed", "Cancelled", obs.screenStateHash, actionDispatched);
+                    await this.fire("onTool", { name: toolName, args: toolArgs, status: "end", isError: true, result: prediction.toolResult });
                     return this.finish("cancelled", step, "Task cancelled", usage, lastError);
+                }
                 if (action.payload?._proSequence)
                     prediction.toolResult = {
-                        ...prediction.toolResult, ok: false, error: errMsg(e),
+                        ...prediction.toolResult, ok: false, executed: actionDispatched ? "unknown" : false, error: errMsg(e),
                     };
                 const err = {
                     code: "MCP_ACT_FAILED",
@@ -567,7 +609,7 @@ export class AgentLoop {
                     cause: e,
                 };
                 await this.fire("onTool", {
-                    name: action.type,
+                    name: toolName,
                     args: toolArgs,
                     status: "end",
                     result: err.message,
@@ -577,7 +619,7 @@ export class AgentLoop {
                 lastError = err;
                 await this.fire("onError", err);
                 // Record the failed step, then keep going so the model can recover.
-                this.recordHistory(step, prediction, observationSummary, "act_failed", err.message, obs.screenStateHash);
+                this.recordHistory(step, prediction, observationSummary, "act_failed", err.message, obs.screenStateHash, actionDispatched);
                 await this.fireStep(step, prediction, false);
                 // Surface the failure to the next predict so the grounder doesn't
                 // assume the action took effect.
@@ -586,14 +628,11 @@ export class AgentLoop {
                     code: "act_failed",
                     reason: err.message,
                 });
-                // Action reflector is most useful exactly here — fire it before
-                // the next predict so the grounder sees the verdict in history.
-                await this.maybeRunActionReflector(prediction, "act_failed", usage);
                 continue;
             }
             const durationMs = Date.now() - t0;
             await this.fire("onTool", {
-                name: action.type,
+                name: toolName,
                 args: toolArgs,
                 status: "end",
                 result: actResult,
@@ -605,10 +644,8 @@ export class AgentLoop {
             // so a future legitimate retry sequence isn't penalised by stale
             // counts from an earlier loop arc.
             this.vetoCodeCount = {};
-            // ── 4. Reflect (model-based action reflector — Phase 1.4) ──────
-            await this.maybeRunActionReflector(prediction, "ok", usage);
             // ── 5. Heuristic veto ─────────────────────────────────────────
-            const veto = this.reflector.maybeVeto(this.history, step, maxSteps);
+            const veto = this.executionChecks.maybeVeto(this.history, step, maxSteps);
             if (veto) {
                 const err = {
                     code: "REFLECTION_VETO",
@@ -618,18 +655,9 @@ export class AgentLoop {
                 await this.fire("onError", err);
                 return this.finish("reflection_veto", step, veto, usage, err);
             }
-            // ── 6. Trajectory reflector (Phase 2.2) ───────────────────────
-            const trajVeto = await this.maybeRunTrajectoryReflector(step, maxSteps, usage);
-            if (trajVeto) {
-                const err = {
-                    code: "REFLECTION_VETO",
-                    message: trajVeto,
-                    fatal: true,
-                };
-                await this.fire("onError", err);
-                return this.finish("reflection_veto", step, trajVeto, usage, err);
-            }
         }
+        if (this.signal?.aborted)
+            return this.finish("cancelled", step, "Task cancelled", usage, lastError);
         const err = {
             code: "STEP_BUDGET",
             message: `hit step budget ${maxSteps}`,
@@ -649,7 +677,6 @@ export class AgentLoop {
             : resolveObservationMode(requested, this.opts.adapter);
         const needsVision = mode === "vision" || mode === "hybrid";
         const needsXml = mode === "xml" || mode === "hybrid";
-        const ss = needsVision ? await this.opts.mcp.screenshot() : undefined;
         let uiDump;
         if (needsXml) {
             try {
@@ -666,6 +693,12 @@ export class AgentLoop {
         if (mode === "xml" && !uiDump) {
             throw new Error("XML observation requested but the device backend returned no UI hierarchy");
         }
+        // UI acquisition can wait through a transition. Capture pixels afterwards,
+        // not before that wait, so a successful dump cannot leave a stale image.
+        this.signal?.throwIfAborted();
+        if (Date.now() >= deadline)
+            throw new Error("Observation deadline reached during UI acquisition");
+        const ss = needsVision ? await this.opts.mcp.screenshot() : undefined;
         let screenW = ss?.deviceWidth ?? ss?.width ?? 0;
         let screenH = ss?.deviceHeight ?? ss?.height ?? 0;
         if (!ss) {
@@ -674,10 +707,8 @@ export class AgentLoop {
             screenH = size.h;
         }
         // Use the *click coordinate system* (deviceWidth/Height) for scaling —
-        // not the raw image dimensions. They typically match on Android (`wm
-        // size` ≡ rendered bytes) but diverge on macOS Retina (downscaled to
-        // logical points) and iOS (logical vs. physical pixels). Falling back
-        // to width/height keeps older mcp-server builds working — see
+        // not resized image dimensions. Falling back to width/height keeps older
+        // Android mcp-server builds working — see
         // `ScreenshotResult` docstring in `@beeos-ai/device-common`.
         let ocrText;
         let ocrStatus;
@@ -686,8 +717,8 @@ export class AgentLoop {
         if (ocr && ss?.b64) {
             try {
                 const ocrDeadline = AbortSignal.timeout(Math.min(10_000, Math.max(1, deadline - Date.now())));
-                const recognized = await ocr.recognize(ss.b64, this.opts.signal
-                    ? AbortSignal.any([this.opts.signal, ocrDeadline]) : ocrDeadline);
+                const recognized = await ocr.recognize(ss.b64, this.signal
+                    ? AbortSignal.any([this.signal, ocrDeadline]) : ocrDeadline);
                 const sx = screenW / (ss.width || screenW);
                 const sy = screenH / (ss.height || screenH);
                 ocrText = recognized.map((item) => ({ ...item,
@@ -696,7 +727,7 @@ export class AgentLoop {
                 ocrStatus = "ok";
             }
             catch {
-                this.opts.signal?.throwIfAborted();
+                this.signal?.throwIfAborted();
                 ocrStatus = "unavailable";
             }
         }
@@ -707,8 +738,9 @@ export class AgentLoop {
             screenH,
             screenshotB64: ss?.b64 ?? "",
             uiDump,
-            extra: ss?.currentApp || ocrStatus
+            extra: ss?.currentApp || ocrStatus || this.opts.taskContext
                 ? { ...(ss?.currentApp ? { currentApp: ss.currentApp } : {}),
+                    ...(this.opts.taskContext ? { taskContext: this.opts.taskContext } : {}),
                     ...(ocrStatus ? { ocrStatus, ocrText } : {}), }
                 : undefined,
         };
@@ -741,122 +773,7 @@ export class AgentLoop {
         }
         return scaled;
     }
-    /**
-     * Phase 1.4 — invoke the optional model-based action reflector. Verdicts
-     * are advisory: a `passed: false` result is appended to the just-pushed
-     * StepHistory entry's `rationale` (so the next `predict` sees it), and
-     * the entry's `actionResult` is upgraded from `ok` → `act_failed` so
-     * downstream code (skill evolver, trajectory reflector) treats it as a
-     * miss.
-     *
-     * The reflector itself is responsible for {@link IActionReflector.shouldReflect}
-     * gating; this helper just composes the wiring. Cost is rolled into the
-     * surrounding {@link AgentLoop.run} `usage` aggregator.
-     */
-    async maybeRunActionReflector(prediction, actionResult, usage) {
-        const reflector = this.reflector.actionReflector;
-        if (!reflector)
-            return;
-        if (!reflector.shouldReflect(this.history, prediction, actionResult))
-            return;
-        const last = this.history[this.history.length - 1];
-        if (!last)
-            return;
-        try {
-            const verdict = await reflector.reflect({
-                goal: this.opts.task,
-                history: this.history,
-                prediction,
-                observationSummary: last.observationSummary ?? "",
-            }, this.opts.signal);
-            // Roll usage in — even passing reflections cost tokens.
-            usage.inputTokens += verdict.usage.inputTokens;
-            usage.outputTokens += verdict.usage.outputTokens;
-            if (verdict.usage.costUsd) {
-                usage.costUsd = (usage.costUsd ?? 0) + verdict.usage.costUsd;
-            }
-            if (!verdict.passed) {
-                // Splice the verdict into the just-recorded step so the grounder's
-                // next predict reads it. Upgrade outcome to act_failed so reflectors
-                // / evolver downstream treat the step as a miss even if MCP succeeded.
-                last.rationale =
-                    (last.rationale ? last.rationale + "\n" : "") +
-                        `[action_reflector] ${verdict.reason}`;
-                last.actionResult = "act_failed";
-                last.actErrorMessage =
-                    last.actErrorMessage ?? `action reflector flagged: ${verdict.reason}`;
-            }
-        }
-        catch {
-            // Reflector failures must NOT abort the loop. The reflector
-            // implementation is expected to swallow its own errors and return a
-            // `passed: true` verdict — but if it doesn't, the catch-all here is
-            // the final safety net.
-        }
-    }
-    /**
-     * Phase 2.2 — periodic global progress assessment. The reflector decides
-     * its own gating (default: every 5 steps); we just compose the wiring.
-     *
-     * Returns a non-empty veto string only on `stuck`. `off_track` injects an
-     * advisory line into the most recent history entry's rationale so the
-     * grounder sees it next predict, but the loop keeps running. The verdict
-     * itself is stashed on `this.trajectoryVerdict` so the PlanExecutor can
-     * thread it into `PlanContext.trajectoryVerdict` on replan.
-     */
-    async maybeRunTrajectoryReflector(step, maxSteps, usage) {
-        const reflector = this.reflector.trajectoryReflector;
-        if (!reflector)
-            return undefined;
-        if (!reflector.shouldReflect(step, this.history))
-            return undefined;
-        const last = this.history[this.history.length - 1];
-        const observationSummary = last?.observationSummary ?? "";
-        try {
-            const verdict = await reflector.reflect({
-                goal: this.opts.task,
-                step,
-                maxSteps,
-                history: this.history,
-                notes: this.notes,
-                observationSummary,
-            }, this.opts.signal);
-            usage.inputTokens += verdict.usage.inputTokens;
-            usage.outputTokens += verdict.usage.outputTokens;
-            if (verdict.usage.costUsd) {
-                usage.costUsd = (usage.costUsd ?? 0) + verdict.usage.costUsd;
-            }
-            if (verdict.verdict === "on_track")
-                return undefined;
-            // off_track / stuck — annotate history so grounder sees it.
-            const tag = `[trajectory_reflector:${verdict.verdict}] ${verdict.reason}${verdict.suggestion ? ` (suggestion: ${verdict.suggestion})` : ""}`;
-            if (last) {
-                last.rationale = (last.rationale ? last.rationale + "\n" : "") + tag;
-            }
-            this.trajectoryVerdict = { verdict: verdict.verdict, reason: verdict.reason };
-            // Push into the feedback queue so the next predict (or the planner
-            // on replan) sees the trajectory verdict explicitly. For `off_track`
-            // this is the primary signal because the loop keeps going.
-            this.pushFeedback({
-                source: "trajectory_reflector",
-                code: verdict.verdict,
-                reason: verdict.suggestion
-                    ? `${verdict.reason} (suggestion: ${verdict.suggestion})`
-                    : verdict.reason,
-            });
-            if (verdict.verdict === "stuck") {
-                return `trajectory stuck: ${verdict.reason}`;
-            }
-            // off_track is non-fatal — keep going, planner will see the verdict
-            // on the *next* replan if the loop later bails for another reason.
-            return undefined;
-        }
-        catch {
-            // Trajectory reflector failures must not abort the loop.
-            return undefined;
-        }
-    }
-    recordHistory(step, p, summary, actionResult, actErrorMessage, screenStateHashBefore) {
+    recordHistory(step, p, summary, actionResult, actErrorMessage, screenStateHashBefore, actionDispatched) {
         this.proMemory?.record(p.action, actionResult ?? "unknown", actErrorMessage ?? summary);
         this.history.push({
             stepIdx: step,
@@ -864,12 +781,19 @@ export class AgentLoop {
             rationale: p.rationale,
             observationSummary: summary,
             actionResult,
+            actionDispatched,
             confidence: p.confidence,
             actErrorMessage,
             screenStateHashBefore,
             toolResult: p.toolResult,
             evidence: this.evidence,
         });
+        if (this.opts.adapter.nativeTools && !this.opts.proOperator) {
+            const images = this.history.filter((entry) => entry.evidence?.screenshotB64);
+            for (const entry of images.slice(0, -3)) {
+                entry.evidence = { ...entry.evidence, screenshotB64: undefined };
+            }
+        }
     }
     /**
      * Backfill `screenStateHashAfter` on the just-pushed terminal history
@@ -895,6 +819,7 @@ export class AgentLoop {
         try {
             await this.opts.hooks.onStep({
                 index: step,
+                observationIndex: this.observationIndex ?? step,
                 rationale: prediction.rationale,
                 action: prediction.action,
                 prediction,
@@ -917,6 +842,15 @@ export class AgentLoop {
         }
     }
     finish(terminator, steps, finalText, usage, lastError) {
+        // Cancellation wins over a late terminal prediction or the final step budget.
+        if (this.signal?.aborted || Date.now() >= this.deadline) {
+            const timedOut = this.signal?.aborted ? this.signal.reason === this.timeoutReason : true;
+            terminator = timedOut ? "timeout" : "cancelled";
+            finalText = timedOut ? "Task deadline reached" : "Task cancelled";
+            if (timedOut)
+                lastError = { code: "TIMEOUT", message: finalText, fatal: true };
+        }
+        this.batch.stop(this.history, `Task ended with ${terminator}; call not executed.`);
         return {
             terminator,
             steps,
@@ -926,7 +860,6 @@ export class AgentLoop {
             usage,
             lastError,
             notes: [...this.notes],
-            trajectoryVerdict: this.trajectoryVerdict,
             feedbackLog: [...this.feedbackLog],
         };
     }
@@ -1083,9 +1016,9 @@ const NOISY_UI_DUMP_ATTR_RE = new RegExp(`\\b(?:${NOISY_UI_DUMP_ATTRS.join("|")}
  * that look identical to a human should produce the same hash.
  *
  * Returns `undefined` when no `uiDump` is available — pure-vision
- * adapters (Open-AutoGLM, UI-TARS, Qwen-VL) skip the dump round-trip
+ * adapters (AutoGLM) skip the dump round-trip
  * and fall back to the legacy 8px coordinate-similarity heuristic in
- * `HierarchicalReflector.maybeBlockAction`.
+ * `ExecutionChecks.maybeBlockAction`.
  */
 export function computeScreenStateHash(uiDump) {
     if (!uiDump)