@beeos-ai/device-agent 0.4.0

package/dist/agent-runtime/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @beeos-ai/device-agent — agent-runtime barrel.
+ *
+ * Public API for the new Plan-Act-Reflect loop and adapter registry.
+ */
+export { AgentLoop, type AgentErrorCode, type AgentErrorEvent, type AgentLoopTerminator, type AgentRunHooks, type AgentRunOptions, type AgentRunResult, type AgentStepEvent, type AgentToolEvent, } from "./core.js";
+export { HierarchicalReflector, actionsEqual, type HierarchicalReflectorOptions, type PreActionVeto, } from "./reflection.js";
+export { HIGH_RISK_VERBS, LLMActionReflector, type ActionReflectCtx, type ActionReflectVerdict, type ActionReflectorGating, type IActionReflector, type LLMActionReflectorOptions, } from "./reflectors/action-reflector.js";
+export { buildReflectorPolicyFromEnv, resolveActionReflector, resolveTrajectoryReflector, type ReflectorPolicy, } from "./reflectors/policy.js";
+export { availableAdapters, clearAdapters, makePrediction, MockAdapter, OpenAIAdapter, parsedToAction, registerAdapter, resolveAdapter, resolveAdapterSync, UITarsAdapter, type AdapterDescriptor, type IModelAdapter, type MockAdapterOptions, type ModelUsage, type OpenAIAdapterOptions, type PredictHooks, type PredictOptions, type Prediction, type StepHistory, } from "./adapters/index.js";
+export { extractFirstJson, makePlanResult, normalisePlanPayload, type IPlanner, type Plan, type PlanContext, type PlanOptions, type PlanResult, type PlanStep, } from "./planner/base.js";
+export { LLMPlanner, type LLMPlannerOptions } from "./planner/llm-planner.js";
+export { NoOpPlanner } from "./planner/noop-planner.js";
+export { PlanExecutor, type PlanExecutorOptions, type PlanExecutorResult, } from "./plan-executor.js";
+export { AgentRunner, type AgentPlanMode, type AgentRunnerOptions, type AgentRunnerResult, } from "./agent-runner.js";
+export { bufferToEmbedding, cosine, DEFAULT_EMBEDDING_DIM, defaultSkillCachePath, embeddingToBuffer, evolveSkill, FileSystemSkillCacheStore, HashEmbeddingProvider, InMemorySkillCacheStore, matchSkill, normaliseActionSequence, similarityRatio, type EmbeddingProvider, type FileSystemSkillCacheStoreOptions, type NewSkillInput, type Skill, type SkillActionSequence, type SkillCacheStore, type SkillEvolverOptions, type SkillMatch, type SkillMatcherOptions, type SkillMatchOutcome, type SkillSummary, } from "./skills/index.js";

package/dist/agent-runtime/index.js

@@ -0,0 +1,17 @@
+/**
+ * @beeos-ai/device-agent — agent-runtime barrel.
+ *
+ * Public API for the new Plan-Act-Reflect loop and adapter registry.
+ */
+export { AgentLoop, } from "./core.js";
+export { HierarchicalReflector, actionsEqual, } from "./reflection.js";
+export { HIGH_RISK_VERBS, LLMActionReflector, } from "./reflectors/action-reflector.js";
+export { buildReflectorPolicyFromEnv, resolveActionReflector, resolveTrajectoryReflector, } from "./reflectors/policy.js";
+export { availableAdapters, clearAdapters, makePrediction, MockAdapter, OpenAIAdapter, parsedToAction, registerAdapter, resolveAdapter, resolveAdapterSync, UITarsAdapter, } from "./adapters/index.js";
+export { extractFirstJson, makePlanResult, normalisePlanPayload, } from "./planner/base.js";
+export { LLMPlanner } from "./planner/llm-planner.js";
+export { NoOpPlanner } from "./planner/noop-planner.js";
+export { PlanExecutor, } from "./plan-executor.js";
+export { AgentRunner, } from "./agent-runner.js";
+export { bufferToEmbedding, cosine, DEFAULT_EMBEDDING_DIM, defaultSkillCachePath, embeddingToBuffer, evolveSkill, FileSystemSkillCacheStore, HashEmbeddingProvider, InMemorySkillCacheStore, matchSkill, normaliseActionSequence, similarityRatio, } from "./skills/index.js";
+//# sourceMappingURL=index.js.map

package/dist/agent-runtime/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/agent-runtime/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,SAAS,GASV,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,qBAAqB,EACrB,YAAY,GAGb,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,eAAe,EACf,kBAAkB,GAMnB,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EACL,2BAA2B,EAC3B,sBAAsB,EACtB,0BAA0B,GAE3B,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,WAAW,EACX,aAAa,EACb,cAAc,EACd,eAAe,EACf,cAAc,EACd,kBAAkB,EAClB,aAAa,GAUd,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,oBAAoB,GAOrB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,UAAU,EAA0B,MAAM,0BAA0B,CAAC;AAC9E,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,EACL,YAAY,GAGb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,WAAW,GAIZ,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,iBAAiB,EACjB,MAAM,EACN,qBAAqB,EACrB,qBAAqB,EACrB,iBAAiB,EACjB,WAAW,EACX,yBAAyB,EACzB,qBAAqB,EACrB,uBAAuB,EACvB,UAAU,EACV,uBAAuB,EACvB,eAAe,GAYhB,MAAM,mBAAmB,CAAC"}

package/dist/agent-runtime/plan-executor.d.ts

@@ -0,0 +1,118 @@
+/**
+ * agent-runtime/plan-executor — runs a structured Plan by spinning up
+ * one `AgentLoop` per `PlanStep`.
+ *
+ * This is the bridge between the *strategy* tier (`IPlanner`) and the
+ * *act* tier (`AgentLoop` + `IModelAdapter` + `IMcpRuntime`):
+ *
+ *   - For each `PlanStep`, we spawn a focused `AgentLoop` whose
+ *     `task` is the step description (the inner adapter sees only this
+ *     mini-goal and natural-language target hints) and whose step
+ *     budget is `step.maxSteps ?? perStepBudget`.
+ *   - When a step's loop terminates with `done` we move on; with
+ *     `fail` / `step_budget` / `reflection_veto` / `timeout` we ask
+ *     the planner to `replan()` (up to `maxReplans` times). The
+ *     replanned `Plan` replaces the remainder of the current plan.
+ *   - When all replans are exhausted we make a single ReAct fallback
+ *     attempt — a fresh `AgentLoop` over the original goal — and
+ *     accept its result as terminal.
+ *
+ * Mirrors the spirit (not the line-by-line shape) of the Python
+ * reference at
+ *   /Users/heat/workspace/deviceagent_research/deviceagent/agent_runtime/loop/plan_executor.py
+ *
+ * Differences from the reference:
+ *   - We delegate per-step grounding + acting back to a full
+ *     `AgentLoop`, instead of explicit Grounder + Verifier passes —
+ *     AutoGLM-Phone-9B does both in one VLM call already.
+ *   - We don't keep a `Verifier` tier yet; the inner loop's
+ *     `done` / `fail` short-circuit is the verification signal.
+ *   - We don't pull `accessibility_tree` (the v0.2.3 mcp-server doesn't
+ *     expose it).
+ */
+import type { Action, Observation } from "@beeos-ai/device-common";
+import type { IMcpRuntime } from "../mcp-client/runtime.js";
+import type { IModelAdapter, ModelUsage, StepHistory } from "./adapters/base.js";
+import { type AgentLoopTerminator, type AgentRunHooks } from "./core.js";
+import type { IPlanner } from "./planner/base.js";
+import type { HierarchicalReflector } from "./reflection.js";
+export interface PlanExecutorOptions {
+    planner: IPlanner;
+    adapter: IModelAdapter;
+    mcp: IMcpRuntime;
+    goal: string;
+    env: Observation["env"];
+    /** Total step budget across the entire run. Defaults to 30. */
+    maxSteps?: number;
+    /** Per sub-task default step budget. Defaults to `ceil(maxSteps / steps)`. */
+    perStepBudget?: number;
+    /** Wall-clock deadline. Defaults to 5 minutes. */
+    timeoutMs?: number;
+    /** Maximum number of `planner.replan()` calls allowed. Defaults to 2. */
+    maxReplans?: number;
+    /** Optional outside cancellation. */
+    signal?: AbortSignal;
+    /** Streaming hooks forwarded to the inner `AgentLoop`. */
+    hooks?: AgentRunHooks;
+    /**
+     * When `true` (default), exhausting replans triggers a single ReAct
+     * fallback over the original goal. Set to `false` for tests / when the
+     * caller wants to handle escalation themselves.
+     */
+    reactFallback?: boolean;
+    /**
+     * Optional reflector shared with the parent {@link AgentRunner}. When
+     * provided, every spawned `AgentLoop` reuses the same instance so that
+     * Phase 1.4 (model-based action reflector) and Phase 2.2 (trajectory
+     * reflector) configuration is applied uniformly across sub-tasks and
+     * the ReAct fallback. When omitted, each `AgentLoop` constructs its
+     * own (heuristic-only) reflector — preserving legacy behaviour.
+     */
+    reflector?: HierarchicalReflector;
+}
+export interface PlanExecutorResult {
+    /** Strict success only when the last `AgentLoop` ended with `done`. */
+    ok: boolean;
+    finalText: string;
+    steps: number;
+    /** Aggregated usage across all loops + planner calls. */
+    usage: ModelUsage;
+    history: StepHistory[];
+    /** Number of distinct plans the executor went through (1 + replans). */
+    plansEmitted: number;
+    /** Number of replan calls (≤ `maxReplans`). */
+    replans: number;
+    /** Whether the ReAct fallback was used. */
+    reactFallbackUsed: boolean;
+    /** Final terminator of the *last* AgentLoop. */
+    terminator: AgentLoopTerminator;
+    cancelled: boolean;
+    /**
+     * Phase 2.1 — flat union of every note collected by inner AgentLoops,
+     * preserved in observation order. Surfaced through {@link AgentRunner}
+     * to the caller so they can stitch notes into downstream UX.
+     */
+    notes: string[];
+}
+export declare class PlanExecutor {
+    private readonly opts;
+    private static readonly DEFAULT_MAX_STEPS;
+    private static readonly DEFAULT_TIMEOUT_MS;
+    private static readonly DEFAULT_MAX_REPLANS;
+    constructor(opts: PlanExecutorOptions);
+    run(): Promise<PlanExecutorResult>;
+    private firePlan;
+    private fireError;
+    private finish;
+    /**
+     * Build a fresh `Observation` snapshot to feed the (text-only) planner on
+     * the replan path. Always pulls the screenshot (cheap; needed for
+     * `screenW/screenH`) and unconditionally tries `mcp.uiDump()` — for the
+     * planner the UI hierarchy is genuinely useful (it can't see pixels), and
+     * this is independent of whether the inner adapter consumes ui_dump.
+     * Returns `undefined` only when even the screenshot fails, so the replan
+     * still has a chance to fire with the previous plan + history alone.
+     */
+    private snapshotForPlanner;
+}
+export type { Action };

package/dist/agent-runtime/plan-executor.js

@@ -0,0 +1,501 @@
+/**
+ * agent-runtime/plan-executor — runs a structured Plan by spinning up
+ * one `AgentLoop` per `PlanStep`.
+ *
+ * This is the bridge between the *strategy* tier (`IPlanner`) and the
+ * *act* tier (`AgentLoop` + `IModelAdapter` + `IMcpRuntime`):
+ *
+ *   - For each `PlanStep`, we spawn a focused `AgentLoop` whose
+ *     `task` is the step description (the inner adapter sees only this
+ *     mini-goal and natural-language target hints) and whose step
+ *     budget is `step.maxSteps ?? perStepBudget`.
+ *   - When a step's loop terminates with `done` we move on; with
+ *     `fail` / `step_budget` / `reflection_veto` / `timeout` we ask
+ *     the planner to `replan()` (up to `maxReplans` times). The
+ *     replanned `Plan` replaces the remainder of the current plan.
+ *   - When all replans are exhausted we make a single ReAct fallback
+ *     attempt — a fresh `AgentLoop` over the original goal — and
+ *     accept its result as terminal.
+ *
+ * Mirrors the spirit (not the line-by-line shape) of the Python
+ * reference at
+ *   /Users/heat/workspace/deviceagent_research/deviceagent/agent_runtime/loop/plan_executor.py
+ *
+ * Differences from the reference:
+ *   - We delegate per-step grounding + acting back to a full
+ *     `AgentLoop`, instead of explicit Grounder + Verifier passes —
+ *     AutoGLM-Phone-9B does both in one VLM call already.
+ *   - We don't keep a `Verifier` tier yet; the inner loop's
+ *     `done` / `fail` short-circuit is the verification signal.
+ *   - We don't pull `accessibility_tree` (the v0.2.3 mcp-server doesn't
+ *     expose it).
+ */
+import { AgentLoop, } from "./core.js";
+/* ──────────────────────────────────────────────────────────────────────── */
+/* PlanExecutor                                                             */
+/* ──────────────────────────────────────────────────────────────────────── */
+const SUCCESS_TERMINATORS = new Set(["done"]);
+/** Subtask terminators we treat as recoverable enough to attempt a replan. */
+const REPLAN_TERMINATORS = new Set([
+    "fail",
+    "step_budget",
+    "timeout",
+    "reflection_veto",
+    "error",
+    "call_for_user",
+]);
+export class PlanExecutor {
+    opts;
+    static DEFAULT_MAX_STEPS = 30;
+    static DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
+    static DEFAULT_MAX_REPLANS = 2;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    async run() {
+        const maxSteps = this.opts.maxSteps ?? PlanExecutor.DEFAULT_MAX_STEPS;
+        const timeoutMs = this.opts.timeoutMs ?? PlanExecutor.DEFAULT_TIMEOUT_MS;
+        const maxReplans = this.opts.maxReplans ?? PlanExecutor.DEFAULT_MAX_REPLANS;
+        const deadline = Date.now() + timeoutMs;
+        const reactFallback = this.opts.reactFallback ?? true;
+        const usage = { inputTokens: 0, outputTokens: 0 };
+        const history = [];
+        const notes = [];
+        let stepsConsumed = 0;
+        let plansEmitted = 0;
+        let replans = 0;
+        let reactFallbackUsed = false;
+        let lastTerminator = "error";
+        let lastFinalText = "";
+        /**
+         * Phase 2.2 / 2.3 — most recent non-`on_track` verdict from any inner
+         * AgentLoop. Threaded into the next `PlanContext.trajectoryVerdict`
+         * so the planner can pivot the plan rather than re-deriving the
+         * failure mode.
+         */
+        let lastTrajectoryVerdict;
+        // ── Initial plan ────────────────────────────────────────────────────
+        // The planner round-trip can fail intermittently (upstream LLM 5xx /
+        // network reset). Don't let that bubble up as a fatal task error —
+        // when `reactFallback` is enabled we degrade gracefully into a pure
+        // ReAct loop so the user-visible task can still make progress.
+        let firstPlanRes;
+        try {
+            firstPlanRes = await this.opts.planner.makePlan({ goal: this.opts.goal, history: [] }, { signal: this.opts.signal });
+        }
+        catch (e) {
+            await this.fireError(`makePlan failed: ${errMsg(e)}`);
+            if (reactFallback) {
+                const planFbRemaining = deadline - Date.now();
+                if (planFbRemaining <= 0) {
+                    return this.finish({
+                        ok: false,
+                        finalText: `plan executor exceeded ${timeoutMs}ms budget`,
+                        stepsConsumed,
+                        usage,
+                        history,
+                        notes,
+                        plansEmitted,
+                        replans,
+                        reactFallbackUsed,
+                        terminator: "timeout",
+                        cancelled: false,
+                    });
+                }
+                reactFallbackUsed = true;
+                const fb = await new AgentLoop({
+                    task: this.opts.goal,
+                    env: this.opts.env,
+                    mcp: this.opts.mcp,
+                    adapter: this.opts.adapter,
+                    maxSteps: Math.max(1, maxSteps - stepsConsumed),
+                    timeoutMs: planFbRemaining,
+                    signal: this.opts.signal,
+                    hooks: this.opts.hooks,
+                    reflector: this.opts.reflector,
+                }).run();
+                stepsConsumed += fb.steps;
+                accumulateUsage(usage, fb.usage);
+                history.push(...fb.history);
+                notes.push(...fb.notes);
+                return this.finish({
+                    ok: SUCCESS_TERMINATORS.has(fb.terminator),
+                    finalText: fb.finalText,
+                    stepsConsumed,
+                    usage,
+                    history,
+                    notes,
+                    plansEmitted,
+                    replans,
+                    reactFallbackUsed,
+                    terminator: fb.terminator,
+                    cancelled: fb.terminator === "cancelled",
+                });
+            }
+            throw e;
+        }
+        let plan = firstPlanRes.plan;
+        accumulateUsage(usage, firstPlanRes.usage);
+        plansEmitted += 1;
+        await this.firePlan(plan, /*isReplan*/ false, replans);
+        // ── Main loop: walk the plan ───────────────────────────────────────
+        let cur = 0;
+        while (cur < plan.steps.length) {
+            if (this.opts.signal?.aborted) {
+                return this.finish({
+                    ok: false,
+                    finalText: "Task cancelled",
+                    stepsConsumed,
+                    usage,
+                    history,
+                    notes,
+                    plansEmitted,
+                    replans,
+                    reactFallbackUsed,
+                    terminator: "cancelled",
+                    cancelled: true,
+                });
+            }
+            if (Date.now() > deadline) {
+                return this.finish({
+                    ok: false,
+                    finalText: `plan executor exceeded ${timeoutMs}ms budget`,
+                    stepsConsumed,
+                    usage,
+                    history,
+                    notes,
+                    plansEmitted,
+                    replans,
+                    reactFallbackUsed,
+                    terminator: "timeout",
+                    cancelled: false,
+                });
+            }
+            const stepsLeft = maxSteps - stepsConsumed;
+            if (stepsLeft <= 0) {
+                return this.finish({
+                    ok: false,
+                    finalText: `hit step budget ${maxSteps}`,
+                    stepsConsumed,
+                    usage,
+                    history,
+                    notes,
+                    plansEmitted,
+                    replans,
+                    reactFallbackUsed,
+                    terminator: "step_budget",
+                    cancelled: false,
+                });
+            }
+            const step = plan.steps[cur];
+            const subBudget = clamp(step.maxSteps ?? this.opts.perStepBudget ?? defaultPerStepBudget(plan.steps.length, maxSteps), 1, stepsLeft);
+            const innerTask = formatStepAsTask(this.opts.goal, plan, cur);
+            // CRITICAL: do NOT clamp the inner timeout to a floor (1000ms) —
+            // when the wall-clock budget is already exhausted that floor
+            // makes the child AgentLoop pretend it still has 1s, which
+            // immediately re-fires `agent exceeded 1000ms budget`. The user
+            // sees absurd "94220ms → 1000ms" budget messages back-to-back
+            // because every replan stage spawns one of these doomed children.
+            // Honour the real remaining budget; if it's already gone, end
+            // the executor with `timeout` directly.
+            const innerRemaining = deadline - Date.now();
+            if (innerRemaining <= 0) {
+                return this.finish({
+                    ok: false,
+                    finalText: `plan executor exceeded ${timeoutMs}ms budget`,
+                    stepsConsumed,
+                    usage,
+                    history,
+                    notes,
+                    plansEmitted,
+                    replans,
+                    reactFallbackUsed,
+                    terminator: "timeout",
+                    cancelled: false,
+                });
+            }
+            const result = await new AgentLoop({
+                task: innerTask,
+                env: this.opts.env,
+                mcp: this.opts.mcp,
+                adapter: this.opts.adapter,
+                maxSteps: subBudget,
+                timeoutMs: innerRemaining,
+                signal: this.opts.signal,
+                hooks: this.opts.hooks,
+                reflector: this.opts.reflector,
+            }).run();
+            stepsConsumed += result.steps;
+            accumulateUsage(usage, result.usage);
+            history.push(...result.history);
+            notes.push(...result.notes);
+            if (result.trajectoryVerdict)
+                lastTrajectoryVerdict = result.trajectoryVerdict;
+            lastTerminator = result.terminator;
+            lastFinalText = result.finalText;
+            if (SUCCESS_TERMINATORS.has(result.terminator)) {
+                cur += 1;
+                continue;
+            }
+            // Sub-task did not finish cleanly — try a replan if we still can.
+            if (result.terminator === "cancelled") {
+                return this.finish({
+                    ok: false,
+                    finalText: result.finalText,
+                    stepsConsumed,
+                    usage,
+                    history,
+                    notes,
+                    plansEmitted,
+                    replans,
+                    reactFallbackUsed,
+                    terminator: "cancelled",
+                    cancelled: true,
+                });
+            }
+            if (replans < maxReplans && REPLAN_TERMINATORS.has(result.terminator)) {
+                replans += 1;
+                // Take a fresh observation snapshot so the (text-only) planner can
+                // see what the screen looks like *now* — the inner AgentLoop's last
+                // observation is gone by this point, and the screen state may have
+                // shifted between the loop ending and the replan firing. Both the
+                // screenshot and ui_dump are best-effort: a failure here must not
+                // block the replan attempt itself.
+                const ctx = {
+                    goal: this.opts.goal,
+                    observation: await this.snapshotForPlanner(),
+                    history,
+                    previousPlan: plan,
+                    failureReason: `step ${step.idx} (${step.description}) ended with ${result.terminator}: ${result.finalText}`,
+                    lastStepIdx: step.idx,
+                    // Phase 2.1 / 2.3 — surface accumulated notes to the planner.
+                    notes: notes.length > 0 ? [...notes] : undefined,
+                    // Phase 2.2 / 2.3 — surface the most recent trajectory verdict so
+                    // the planner can react to "off_track" / "stuck" explicitly.
+                    trajectoryVerdict: lastTrajectoryVerdict,
+                };
+                try {
+                    const repl = await this.opts.planner.replan(ctx, { signal: this.opts.signal });
+                    accumulateUsage(usage, repl.usage);
+                    plan = repl.plan;
+                    plansEmitted += 1;
+                    cur = 0;
+                    await this.firePlan(plan, /*isReplan*/ true, replans);
+                    continue;
+                }
+                catch (e) {
+                    // planner blew up — fall through to ReAct fallback
+                    await this.fireError(`replan failed: ${errMsg(e)}`);
+                }
+            }
+            // Replans exhausted (or planner threw). Optional ReAct fallback.
+            if (reactFallback && !reactFallbackUsed) {
+                const fbRemaining = deadline - Date.now();
+                if (fbRemaining <= 0) {
+                    return this.finish({
+                        ok: false,
+                        finalText: `plan executor exceeded ${timeoutMs}ms budget`,
+                        stepsConsumed,
+                        usage,
+                        history,
+                        notes,
+                        plansEmitted,
+                        replans,
+                        reactFallbackUsed,
+                        terminator: "timeout",
+                        cancelled: false,
+                    });
+                }
+                reactFallbackUsed = true;
+                const fallback = await new AgentLoop({
+                    task: this.opts.goal,
+                    env: this.opts.env,
+                    mcp: this.opts.mcp,
+                    adapter: this.opts.adapter,
+                    maxSteps: Math.max(1, maxSteps - stepsConsumed),
+                    timeoutMs: fbRemaining,
+                    signal: this.opts.signal,
+                    hooks: this.opts.hooks,
+                    reflector: this.opts.reflector,
+                }).run();
+                stepsConsumed += fallback.steps;
+                accumulateUsage(usage, fallback.usage);
+                history.push(...fallback.history);
+                notes.push(...fallback.notes);
+                lastTerminator = fallback.terminator;
+                lastFinalText = fallback.finalText;
+                return this.finish({
+                    ok: SUCCESS_TERMINATORS.has(fallback.terminator),
+                    finalText: fallback.finalText,
+                    stepsConsumed,
+                    usage,
+                    history,
+                    notes,
+                    plansEmitted,
+                    replans,
+                    reactFallbackUsed,
+                    terminator: fallback.terminator,
+                    cancelled: fallback.terminator === "cancelled",
+                });
+            }
+            // No fallback (or already used) — bail out with the failure.
+            return this.finish({
+                ok: false,
+                finalText: result.finalText,
+                stepsConsumed,
+                usage,
+                history,
+                notes,
+                plansEmitted,
+                replans,
+                reactFallbackUsed,
+                terminator: result.terminator,
+                cancelled: false,
+            });
+        }
+        return this.finish({
+            ok: lastTerminator === "done" || (cur > 0 && plan.steps.length > 0),
+            finalText: lastFinalText || "task complete",
+            stepsConsumed,
+            usage,
+            history,
+            notes,
+            plansEmitted,
+            replans,
+            reactFallbackUsed,
+            terminator: lastTerminator || "done",
+            cancelled: false,
+        });
+    }
+    async firePlan(plan, isReplan, replanCount) {
+        if (!this.opts.hooks?.onReasoning)
+            return;
+        try {
+            await this.opts.hooks.onReasoning(`[planner] ${isReplan ? `replan #${replanCount}` : "plan"}: ${describePlan(plan)}`);
+        }
+        catch {
+            // never let hooks bubble up
+        }
+    }
+    async fireError(message) {
+        if (!this.opts.hooks?.onError)
+            return;
+        try {
+            await this.opts.hooks.onError({ code: "MODEL_PREDICT_FAILED", message, fatal: false });
+        }
+        catch {
+            // ditto
+        }
+    }
+    finish(args) {
+        return {
+            ok: args.ok,
+            finalText: args.finalText,
+            steps: args.stepsConsumed,
+            usage: args.usage,
+            history: args.history,
+            notes: args.notes,
+            plansEmitted: args.plansEmitted,
+            replans: args.replans,
+            reactFallbackUsed: args.reactFallbackUsed,
+            terminator: args.terminator,
+            cancelled: args.cancelled,
+        };
+    }
+    /**
+     * Build a fresh `Observation` snapshot to feed the (text-only) planner on
+     * the replan path. Always pulls the screenshot (cheap; needed for
+     * `screenW/screenH`) and unconditionally tries `mcp.uiDump()` — for the
+     * planner the UI hierarchy is genuinely useful (it can't see pixels), and
+     * this is independent of whether the inner adapter consumes ui_dump.
+     * Returns `undefined` only when even the screenshot fails, so the replan
+     * still has a chance to fire with the previous plan + history alone.
+     */
+    async snapshotForPlanner() {
+        let ss;
+        try {
+            ss = await this.opts.mcp.screenshot();
+        }
+        catch {
+            return undefined;
+        }
+        let uiDump;
+        try {
+            const dump = await this.opts.mcp.uiDump();
+            if (dump.supported && dump.content)
+                uiDump = dump.content;
+        }
+        catch {
+            // best-effort — desktop / iOS backends can't always produce one
+        }
+        return {
+            task: this.opts.goal,
+            env: this.opts.env,
+            screenW: ss.deviceWidth ?? ss.width ?? 0,
+            screenH: ss.deviceHeight ?? ss.height ?? 0,
+            screenshotB64: ss.b64,
+            uiDump,
+        };
+    }
+}
+/* ──────────────────────────────────────────────────────────────────────── */
+/* helpers                                                                  */
+/* ──────────────────────────────────────────────────────────────────────── */
+function defaultPerStepBudget(planSteps, maxSteps) {
+    if (planSteps <= 0)
+        return Math.max(1, maxSteps);
+    return Math.max(1, Math.ceil(maxSteps / Math.max(1, planSteps)));
+}
+function clamp(n, lo, hi) {
+    return Math.max(lo, Math.min(hi, n));
+}
+function accumulateUsage(into, src) {
+    into.inputTokens += src.inputTokens;
+    into.outputTokens += src.outputTokens;
+    if (src.cachedInputTokens)
+        into.cachedInputTokens = (into.cachedInputTokens ?? 0) + src.cachedInputTokens;
+    if (src.costUsd)
+        into.costUsd = (into.costUsd ?? 0) + src.costUsd;
+}
+function describePlan(plan) {
+    if (plan.steps.length === 0)
+        return "(empty plan)";
+    const lines = plan.steps
+        .slice(0, 8)
+        .map((s) => `  ${s.idx}. ${s.description}${s.targetDesc ? ` → ${s.targetDesc}` : ""}`)
+        .join("\n");
+    return `\n${lines}`;
+}
+function errMsg(e) {
+    if (e instanceof Error)
+        return e.message;
+    return String(e);
+}
+/**
+ * Format a `PlanStep` as the inner `AgentLoop`'s `task` string. We splice
+ * in a few light directives so the inner adapter knows what high-level
+ * goal it serves and what the upcoming sub-tasks look like, but the
+ * primary instruction is still the current step's description.
+ */
+function formatStepAsTask(rootGoal, plan, idx) {
+    const step = plan.steps[idx];
+    const upcoming = plan.steps
+        .slice(idx + 1, idx + 4)
+        .map((s) => `${s.idx}. ${s.description}`)
+        .join("; ");
+    const targetHint = step.targetDesc ? `\n# Target: ${step.targetDesc}` : "";
+    const expectedOutcome = step.expectedOutcome ? `\n# Expected: ${step.expectedOutcome}` : "";
+    const upcomingLine = upcoming ? `\n# Upcoming: ${upcoming}` : "";
+    return [
+        `# Goal: ${rootGoal}`,
+        `# Sub-task ${idx + 1}/${plan.steps.length}: ${step.description}`,
+        targetHint,
+        expectedOutcome,
+        upcomingLine,
+        "",
+        "Focus only on this sub-task. Call finish() when this sub-task is complete.",
+    ]
+        .filter((line) => line !== "")
+        .join("\n");
+}
+//# sourceMappingURL=plan-executor.js.map