@beeos-ai/device-agent 0.15.0 → 0.16.0

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

@@ -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
@@ -32,10 +32,9 @@ import { type Action, type Observation } from "@beeos-ai/device-common";
 import type { IMcpRuntime } from "../mcp-client/runtime.js";
 import type { IModelAdapter, ModelUsage, Prediction, StepHistory } from "./adapters/base.js";
 import { type StepFeedback } from "./feedback.js";
-import { HierarchicalReflector } from "./reflection.js";
+import { ExecutionChecks } from "./execution-checks.js";
 import { ProTaskMemory } from "./pro-memory.js";
 import { type OcrProvider } from "./ocr.js";
-import type { TrajectoryVerdict } from "./reflectors/trajectory-reflector.js";
 import { type ObservationMode } from "./observation-mode.js";
 export type AgentLoopTerminator = "done" | "fail" | "call_for_user" | "step_budget" | "timeout" | "reflection_veto" | "cancelled" | "error";
 export interface AgentRunHooks {
@@ -61,6 +60,8 @@ export interface AgentObservationEvent {
 export interface AgentStepEvent {
     /** 1-based step index. */
     index: number;
+    /** Observation index before a sequence charges its additional taps. */
+    observationIndex?: number;
     rationale: string;
     action: Action;
     prediction: Prediction;
@@ -87,6 +88,11 @@ export interface AgentErrorEvent {
 export type AgentErrorCode = "MODEL_PREDICT_FAILED" | "MCP_ACT_FAILED" | "MCP_ACT_ACTIONABLE" | "MCP_OBSERVE_FAILED" | "STEP_BUDGET" | "TIMEOUT" | "REFLECTION_VETO" | "MODEL_FAIL" | "CALL_FOR_USER_TIMEOUT" | "ABORTED";
 export interface AgentRunOptions {
     task: string;
+    /** Preserve task identity independently of scoped prompts and recovery text. */
+    taskContext?: {
+        rootGoal: string;
+        currentMilestone: string;
+    };
     env: Observation["env"];
     mcp: IMcpRuntime;
     adapter: IModelAdapter;
@@ -106,11 +112,13 @@ export interface AgentRunOptions {
     signal?: AbortSignal;
     /** Run hooks for streaming events. */
     hooks?: AgentRunHooks;
-    /** Optional pre-built reflector (test injection). */
-    reflector?: HierarchicalReflector;
+    /** Optional pre-built deterministic checks (test injection). */
+    executionChecks?: ExecutionChecks;
     /** Pro only: completed prior loops within this same task, never another task. */
     priorHistory?: StepHistory[];
     proOperator?: boolean;
+    /** Whole-task plan guidance, separate from the immutable user goal. */
+    operatorGuidance?: string;
     /** Optional injected OCR backend. Production uses BEEOS_OCR_API_KEY. */
     ocrProvider?: OcrProvider;
     proMemory?: ProTaskMemory;
@@ -132,20 +140,9 @@ export interface AgentRunResult {
      * (verification codes, computed prices, etc.).
      */
     notes: string[];
-    /**
-     * Phase 2.2 — final verdict from the {@link ITrajectoryReflector}, if any.
-     * Set when the periodic trajectory check flipped to `off_track` or
-     * `stuck`. The PlanExecutor surfaces this into `PlanContext.trajectoryVerdict`
-     * on replan so the planner can pivot the plan rather than re-deriving the
-     * failure mode.
-     */
-    trajectoryVerdict?: {
-        verdict: Exclude<TrajectoryVerdict, "on_track">;
-        reason: string;
-    };
     /**
      * Append-only log of every {@link StepFeedback} pushed during the run
-     * (pre-sanity vetoes, MCP act failures, trajectory reflector verdicts).
+     * (pre-sanity vetoes, MCP act failures).
      * The PlanExecutor surfaces the tail of this list as
      * `PlanContext.failureChain` on replan so the planner sees the precise
      * chain of failures rather than a free-form failure-reason string.
@@ -154,18 +151,19 @@ export interface AgentRunResult {
 }
 export declare class AgentLoop {
     private readonly opts;
+    private readonly batch;
     private static readonly DEFAULT_MAX_STEPS;
     private static readonly DEFAULT_TIMEOUT_MS;
     private readonly history;
     private evidence?;
+    private observationIndex?;
     private readonly proMemory?;
-    private readonly reflector;
+    private readonly executionChecks;
     private readonly notes;
-    private 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).
      */
@@ -187,10 +185,14 @@ export declare class AgentLoop {
      * four identical actions.
      */
     private vetoCodeCount;
+    private signal?;
+    private deadline;
+    private readonly timeoutReason;
     constructor(opts: AgentRunOptions);
     /** Push feedback into both the pending queue and the immutable log. */
     private pushFeedback;
     run(): Promise<AgentRunResult>;
+    private runLoop;
     private observe;
     /**
      * Translate a model-frame action into an MCP-frame action by scaling
@@ -198,30 +200,6 @@ export declare class AgentLoop {
      * `_coordSystem` payload hint that `parsedToAction` plants.
      */
     private scaleAction;
-    /**
-     * 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.
-     */
-    private maybeRunActionReflector;
-    /**
-     * 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.
-     */
-    private maybeRunTrajectoryReflector;
     private recordHistory;
     /**
      * Backfill `screenStateHashAfter` on the just-pushed terminal history
@@ -246,8 +224,8 @@ export declare class AgentLoop {
  * 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 declare function computeScreenStateHash(uiDump: string | undefined): string | undefined;