@beeos-ai/device-agent 0.4.0

package/dist/agent-runtime/reflectors/action-reflector.js

@@ -0,0 +1,233 @@
+/**
+ * agent-runtime/reflectors/action-reflector — model-based action reflection.
+ *
+ * Phase 1.4 of the device-agent reflector upgrade plan
+ * ([../../../../../../.cursor/plans/device-agent-reflector-skills_d5599350.plan.md]).
+ *
+ * Goal: catch *the same step* the grounder just emitted when it's likely
+ * wrong (low confidence, or the MCP `act` failed) and feed back a textual
+ * verdict the next predict call can read. Concretely:
+ *   - heuristic veto (`HierarchicalReflector.maybeVeto`) runs first and
+ *     terminates the loop with a hard stop on stalls;
+ *   - if the heuristics are quiet, we ask the action reflector whether to
+ *     take a closer look. The default {@link LLMActionReflector} fires on
+ *     `actionResult === "act_failed"` OR on low-confidence predictions
+ *     OR (as a defensive fallback) on a small whitelist of high-risk verbs
+ *     so we still help even when the adapter doesn't expose logprobs.
+ *   - the reflector verdict is **advisory**: a `passed: false` result is
+ *     spliced into the next StepHistory rationale ("act_failed: …") so the
+ *     grounder retries with that context. We do NOT terminate the loop —
+ *     stalls are still the heuristic layer's job.
+ *
+ * The cost model is documented in
+ * `agents/device-agent/docs/reflectors.md` (Phase 2.4). Per-task budget
+ * with default config is ≤ 4 cheap text glm-4-flash calls / task, ~600-1200
+ * input tokens / 50 output tokens each.
+ */
+import OpenAI from "openai";
+import { getLogger } from "../../logger/index.js";
+/** Verbs that warrant a reflection on Branch C of the logprobs spike. */
+export const HIGH_RISK_VERBS = new Set([
+    "type",
+    "swipe",
+    "launch_app",
+]);
+const DEFAULT_MODEL = "glm-4-flash";
+const HISTORY_TAIL = 4;
+const RATIONALE_MAX = 200;
+export class LLMActionReflector {
+    name = "llm-action-reflector";
+    client;
+    modelName;
+    confidenceThreshold;
+    gating;
+    maxTokens;
+    temperature;
+    constructor(opts = {}) {
+        this.modelName = opts.modelName ?? process.env.ACTION_REFLECTOR_MODEL ?? DEFAULT_MODEL;
+        this.confidenceThreshold = clamp01(opts.confidenceThreshold ??
+            readFloat(process.env.ACTION_REFLECTOR_CONFIDENCE_THRESHOLD, 0.6));
+        this.gating =
+            opts.gating ??
+                (parseGating(process.env.ACTION_REFLECTOR_GATING) ?? "whitelist");
+        this.maxTokens = opts.maxTokens ?? 80;
+        this.temperature = opts.temperature ?? 0;
+        const baseUrl = opts.baseUrl ??
+            process.env.ACTION_REFLECTOR_BASE_URL ??
+            process.env.PLANNER_BASE_URL ??
+            process.env.GUI_AGENT_BASE_URL ??
+            "https://api.openai.com/v1";
+        const apiKey = opts.apiKey ??
+            process.env.ACTION_REFLECTOR_API_KEY ??
+            process.env.PLANNER_API_KEY ??
+            process.env.GUI_AGENT_API_KEY ??
+            "EMPTY";
+        this.client =
+            opts.client ?? new OpenAI({ baseURL: baseUrl, apiKey, timeout: 30_000, maxRetries: 1 });
+    }
+    shouldReflect(_history, lastPrediction, actionResult) {
+        if (actionResult === "act_failed")
+            return true;
+        // confidence-gated branches use the prediction's confidence (which the
+        // adapter populates from logprobs when supported).
+        if (this.gating === "logprob" || this.gating === "logprob-degraded") {
+            if (typeof lastPrediction.confidence === "number" &&
+                lastPrediction.confidence < this.confidenceThreshold) {
+                return true;
+            }
+        }
+        // whitelist branch — always a fallback so even without logprobs we
+        // catch the highest-risk verbs.
+        if (HIGH_RISK_VERBS.has(lastPrediction.action.type))
+            return true;
+        return false;
+    }
+    async reflect(ctx, signal) {
+        const startedAt = Date.now();
+        const messages = [
+            { role: "system", content: SYSTEM_PROMPT },
+            { role: "user", content: renderUserPrompt(ctx) },
+        ];
+        try {
+            const resp = await this.client.chat.completions.create({
+                model: this.modelName,
+                messages,
+                temperature: this.temperature,
+                max_tokens: this.maxTokens,
+                response_format: { type: "json_object" },
+            }, { signal });
+            const raw = resp.choices?.[0]?.message?.content ?? "";
+            const usage = {
+                inputTokens: resp.usage?.prompt_tokens ?? 0,
+                outputTokens: resp.usage?.completion_tokens ?? 0,
+                durationMs: Date.now() - startedAt,
+                costUsd: estimateCostUsd(this.modelName, resp.usage?.prompt_tokens ?? 0, resp.usage?.completion_tokens ?? 0),
+            };
+            const parsed = parseVerdict(raw);
+            return { ...parsed, usage };
+        }
+        catch (e) {
+            // Reflector failures must NOT abort the run — log and pass.
+            getLogger().warn({ component: "action-reflector", err: errMsg(e) }, "action-reflector.failed");
+            return {
+                passed: true,
+                reason: `reflector unavailable: ${errMsg(e)}`,
+                usage: { inputTokens: 0, outputTokens: 0, durationMs: Date.now() - startedAt, costUsd: 0 },
+            };
+        }
+    }
+}
+/* -------------------------------------------------------------------------- */
+/* Prompts                                                                    */
+/* -------------------------------------------------------------------------- */
+const SYSTEM_PROMPT = `You are an action sanity checker for a mobile agent.
+The grounder (a vision model) just emitted ONE next action. Your job is to
+decide whether that action is *plausible* given the recent step history and
+the most recent screen summary. You DO NOT see screenshots — only text.
+
+Output STRICT JSON: {"passed": <bool>, "reason": "<<=80 chars>"}.
+
+Mark passed=false ONLY when the action is clearly wrong (wrong app, wrong
+verb, contradicts the history, or the previous attempt of the same action
+just failed and re-trying without a change won't help). Be conservative —
+when uncertain, set passed=true and put the doubt in "reason".`;
+function renderUserPrompt(ctx) {
+    const tail = ctx.history.slice(-HISTORY_TAIL).map((h) => ({
+        step: h.stepIdx,
+        action: h.action ? actionToOneLiner(h.action) : null,
+        rationale: truncate(h.rationale, RATIONALE_MAX),
+        actionResult: h.actionResult ?? null,
+        actError: h.actErrorMessage ?? null,
+        obsSummary: truncate(h.observationSummary, RATIONALE_MAX),
+    }));
+    return JSON.stringify({
+        goal: truncate(ctx.goal, RATIONALE_MAX * 2),
+        recentHistory: tail,
+        proposedAction: actionToOneLiner(ctx.prediction.action),
+        proposedRationale: truncate(ctx.prediction.rationale ?? "", RATIONALE_MAX),
+        proposedConfidence: ctx.prediction.confidence ?? null,
+        latestScreenSummary: truncate(ctx.observationSummary, RATIONALE_MAX),
+    }, null, 2);
+}
+function actionToOneLiner(a) {
+    const target = a.target ? ` ${JSON.stringify(a.target)}` : "";
+    const payload = a.payload && Object.keys(a.payload).length > 0 ? ` ${JSON.stringify(a.payload)}` : "";
+    return `${a.type}${target}${payload}`;
+}
+function truncate(s, max) {
+    if (!s)
+        return "";
+    return s.length > max ? `${s.slice(0, max - 1)}…` : s;
+}
+/* -------------------------------------------------------------------------- */
+/* Verdict parsing                                                            */
+/* -------------------------------------------------------------------------- */
+function parseVerdict(raw) {
+    if (!raw)
+        return { passed: true, reason: "empty reflector response" };
+    try {
+        const obj = JSON.parse(raw);
+        if (obj && typeof obj === "object") {
+            const passed = "passed" in obj ? Boolean(obj.passed) : true;
+            const reason = typeof obj.reason === "string"
+                ? obj.reason.trim()
+                : passed
+                    ? "ok"
+                    : "reflector flagged action";
+            return { passed, reason };
+        }
+    }
+    catch {
+        /* fall through */
+    }
+    return { passed: true, reason: `unparseable reflector response: ${truncate(raw, 80)}` };
+}
+const PRICING_PER_KTOK_USD = {
+    // Z.ai pricing as of 2025-Q1 — keep this list short / overridable via env.
+    "glm-4-flash": { input: 0.0001, output: 0.0001 },
+    "glm-4-air": { input: 0.0014, output: 0.0014 },
+    "glm-4-plus": { input: 0.007, output: 0.007 },
+};
+function estimateCostUsd(model, inputTokens, outputTokens) {
+    const p = PRICING_PER_KTOK_USD[model.toLowerCase()];
+    if (!p)
+        return 0;
+    return (inputTokens / 1000) * p.input + (outputTokens / 1000) * p.output;
+}
+/* -------------------------------------------------------------------------- */
+/* Misc helpers                                                               */
+/* -------------------------------------------------------------------------- */
+function clamp01(n) {
+    if (!Number.isFinite(n))
+        return 0.5;
+    return Math.max(0, Math.min(1, n));
+}
+function readFloat(raw, fallback) {
+    if (!raw)
+        return fallback;
+    const n = Number(raw);
+    return Number.isFinite(n) ? n : fallback;
+}
+function parseGating(raw) {
+    if (!raw)
+        return undefined;
+    switch (raw.trim().toLowerCase()) {
+        case "logprob":
+            return "logprob";
+        case "logprob-degraded":
+        case "logprob_degraded":
+            return "logprob-degraded";
+        case "whitelist":
+        case "fallback":
+        case "default":
+            return "whitelist";
+        default:
+            return undefined;
+    }
+}
+function errMsg(e) {
+    if (e instanceof Error)
+        return e.message;
+    return String(e);
+}
+//# sourceMappingURL=action-reflector.js.map

package/dist/agent-runtime/reflectors/action-reflector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-reflector.js","sourceRoot":"","sources":["../../../src/agent-runtime/reflectors/action-reflector.ts"],"names":[],"mappings":"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"}

package/dist/agent-runtime/reflectors/policy.d.ts

@@ -0,0 +1,53 @@
+/**
+ * agent-runtime/reflectors/policy — env-driven factory for the Phase 1+2
+ * reflector stack.
+ *
+ * The runtime resolves a single {@link ReflectorPolicy} object from
+ * environment variables and threads it through `AgentRunner` →
+ * `PlanExecutor` → `AgentLoop` → `HierarchicalReflector`. Every reflector
+ * is **off by default**; switching one on never widens the surface area
+ * of the existing heuristics — those continue to fire.
+ *
+ * Env vars (see also `agents/device-agent/docs/reflectors.md`):
+ *   ACTION_REFLECTOR        = "off" | "llm"          (default "off")
+ *   ACTION_REFLECTOR_MODEL  = chat model name        (default "glm-4-flash")
+ *   ACTION_REFLECTOR_GATING = "logprob" | "logprob-degraded" | "whitelist"
+ *                                                     (default "whitelist")
+ *   ACTION_REFLECTOR_CONFIDENCE_THRESHOLD = 0..1     (default 0.6)
+ *   TRAJECTORY_REFLECTOR    = "off" | "every:N"      (default "off")
+ *   NOTE_TAKER              = "off" | "on"           (default "off")
+ *
+ * Phase 2.4 also exposes a `ReflectorPolicy` type that callers can build
+ * programmatically (CLI flags, integration tests).
+ */
+import type { IActionReflector, LLMActionReflectorOptions } from "./action-reflector.js";
+import type { ITrajectoryReflector, LLMTrajectoryReflectorOptions } from "./trajectory-reflector.js";
+export type ActionReflectorMode = "off" | "llm";
+export type TrajectoryReflectorMode = "off" | {
+    kind: "every";
+    everyNSteps: number;
+};
+export type NoteTakerMode = "off" | "on";
+export interface ReflectorPolicy {
+    actionReflector: ActionReflectorMode;
+    /** Optional pre-built reflector (test injection). */
+    actionReflectorInstance?: IActionReflector;
+    actionReflectorOptions?: LLMActionReflectorOptions;
+    trajectoryReflector: TrajectoryReflectorMode;
+    /** Optional pre-built trajectory reflector (test injection). */
+    trajectoryReflectorInstance?: ITrajectoryReflector;
+    trajectoryReflectorOptions?: LLMTrajectoryReflectorOptions;
+    noteTaker: NoteTakerMode;
+}
+/** Build a `ReflectorPolicy` from process.env. */
+export declare function buildReflectorPolicyFromEnv(env?: NodeJS.ProcessEnv): ReflectorPolicy;
+/**
+ * Resolve the configured action reflector instance, or `undefined` when
+ * disabled. Re-exported so tests can opt out of env-based config.
+ */
+export declare function resolveActionReflector(policy: ReflectorPolicy): IActionReflector | undefined;
+/**
+ * Resolve the configured trajectory reflector, or `undefined` when off.
+ * Mirrors {@link resolveActionReflector}.
+ */
+export declare function resolveTrajectoryReflector(policy: ReflectorPolicy): ITrajectoryReflector | undefined;

package/dist/agent-runtime/reflectors/policy.js

@@ -0,0 +1,106 @@
+/**
+ * agent-runtime/reflectors/policy — env-driven factory for the Phase 1+2
+ * reflector stack.
+ *
+ * The runtime resolves a single {@link ReflectorPolicy} object from
+ * environment variables and threads it through `AgentRunner` →
+ * `PlanExecutor` → `AgentLoop` → `HierarchicalReflector`. Every reflector
+ * is **off by default**; switching one on never widens the surface area
+ * of the existing heuristics — those continue to fire.
+ *
+ * Env vars (see also `agents/device-agent/docs/reflectors.md`):
+ *   ACTION_REFLECTOR        = "off" | "llm"          (default "off")
+ *   ACTION_REFLECTOR_MODEL  = chat model name        (default "glm-4-flash")
+ *   ACTION_REFLECTOR_GATING = "logprob" | "logprob-degraded" | "whitelist"
+ *                                                     (default "whitelist")
+ *   ACTION_REFLECTOR_CONFIDENCE_THRESHOLD = 0..1     (default 0.6)
+ *   TRAJECTORY_REFLECTOR    = "off" | "every:N"      (default "off")
+ *   NOTE_TAKER              = "off" | "on"           (default "off")
+ *
+ * Phase 2.4 also exposes a `ReflectorPolicy` type that callers can build
+ * programmatically (CLI flags, integration tests).
+ */
+import { LLMActionReflector } from "./action-reflector.js";
+import { LLMTrajectoryReflector } from "./trajectory-reflector.js";
+const DEFAULT_TRAJECTORY_EVERY_N = 5;
+/** Build a `ReflectorPolicy` from process.env. */
+export function buildReflectorPolicyFromEnv(env = process.env) {
+    return {
+        actionReflector: parseActionReflectorMode(env.ACTION_REFLECTOR),
+        trajectoryReflector: parseTrajectoryMode(env.TRAJECTORY_REFLECTOR),
+        noteTaker: parseNoteTakerMode(env.NOTE_TAKER),
+    };
+}
+/**
+ * Resolve the configured action reflector instance, or `undefined` when
+ * disabled. Re-exported so tests can opt out of env-based config.
+ */
+export function resolveActionReflector(policy) {
+    if (policy.actionReflectorInstance)
+        return policy.actionReflectorInstance;
+    switch (policy.actionReflector) {
+        case "llm":
+            return new LLMActionReflector(policy.actionReflectorOptions);
+        case "off":
+        default:
+            return undefined;
+    }
+}
+/**
+ * Resolve the configured trajectory reflector, or `undefined` when off.
+ * Mirrors {@link resolveActionReflector}.
+ */
+export function resolveTrajectoryReflector(policy) {
+    if (policy.trajectoryReflectorInstance)
+        return policy.trajectoryReflectorInstance;
+    if (policy.trajectoryReflector === "off")
+        return undefined;
+    const everyNSteps = policy.trajectoryReflector.everyNSteps;
+    const opts = {
+        ...(policy.trajectoryReflectorOptions ?? {}),
+        everyNSteps,
+    };
+    return new LLMTrajectoryReflector(opts);
+}
+/* -------------------------------------------------------------------------- */
+/* env parsers                                                                */
+/* -------------------------------------------------------------------------- */
+function parseActionReflectorMode(raw) {
+    switch ((raw ?? "").trim().toLowerCase()) {
+        case "llm":
+        case "on":
+            return "llm";
+        case "off":
+        case "":
+        default:
+            return "off";
+    }
+}
+function parseTrajectoryMode(raw) {
+    const v = (raw ?? "").trim().toLowerCase();
+    if (!v || v === "off")
+        return "off";
+    if (v === "on")
+        return { kind: "every", everyNSteps: DEFAULT_TRAJECTORY_EVERY_N };
+    // every:N
+    const m = v.match(/^every:(\d+)$/);
+    if (m) {
+        const n = Number(m[1]);
+        if (Number.isFinite(n) && n > 0)
+            return { kind: "every", everyNSteps: Math.floor(n) };
+    }
+    return "off";
+}
+function parseNoteTakerMode(raw) {
+    switch ((raw ?? "").trim().toLowerCase()) {
+        case "on":
+        case "true":
+        case "1":
+            return "on";
+        case "off":
+        case "":
+        default:
+            return "off";
+    }
+}
+//# sourceMappingURL=policy.js.map

package/dist/agent-runtime/reflectors/policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.js","sourceRoot":"","sources":["../../../src/agent-runtime/reflectors/policy.ts"],"names":[],"mappings":"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"}

package/dist/agent-runtime/reflectors/trajectory-reflector.d.ts

@@ -0,0 +1,94 @@
+/**
+ * agent-runtime/reflectors/trajectory-reflector — periodic global progress
+ * assessment.
+ *
+ * Phase 2.2 of the device-agent reflector upgrade plan
+ * ([../../../../../../.cursor/plans/device-agent-reflector-skills_d5599350.plan.md]).
+ *
+ * Where the {@link IActionReflector} (Phase 1.4) is *step-local* — does THIS
+ * one prediction look right? — the trajectory reflector is *task-global*:
+ * every N steps it inspects the rolling history + accumulated notes + the
+ * current goal and decides whether the agent is making progress, drifting
+ * onto a wrong sub-task, or stuck altogether.
+ *
+ * The default {@link LLMTrajectoryReflector} talks to a cheap text-only
+ * chat model (`glm-4-flash` by default, the same family the planner uses)
+ * and emits a strict `{ verdict, reason, suggestion? }` JSON payload.
+ *
+ * Cost model:
+ *   - One ~600-1000 input token / ≤80 output token request per N steps.
+ *     With N=5 and a 30-step task budget that's ≤ 6 calls / task, ~ ¥0.001
+ *     in incremental cost.
+ *   - Reflector failures are non-fatal: a transient 5xx logs a warning and
+ *     returns `verdict: "on_track"` so the executor keeps going.
+ */
+import OpenAI from "openai";
+import type { ModelUsage, StepHistory } from "../adapters/base.js";
+export type TrajectoryVerdict = "on_track" | "off_track" | "stuck";
+export interface TrajectoryReflectCtx {
+    /** Goal of the surrounding task (agent root goal). */
+    goal: string;
+    /** Inner-loop step counter — first call is at `step === everyNSteps`. */
+    step: number;
+    /** Maximum steps the loop is allowed to take (informational). */
+    maxSteps: number;
+    /**
+     * Rolling step history (most recent last). The reflector trims to the
+     * tail itself; pass the full history.
+     */
+    history: StepHistory[];
+    /** Notes the agent has captured so far via `take_note`. */
+    notes: string[];
+    /** Last observation summary (no base64 — text only). */
+    observationSummary: string;
+}
+export interface TrajectoryReflectVerdict {
+    /** What the reflector thinks of the trajectory so far. */
+    verdict: TrajectoryVerdict;
+    /** ≤ 200-char rationale, surfaced to the planner on `replan()`. */
+    reason: string;
+    /**
+     * Optional concrete next-step suggestion. Surfaced to the planner so it
+     * can pivot the plan rather than re-deriving the failure mode.
+     */
+    suggestion?: string;
+    /** Cost / latency accounting for the reflector call. */
+    usage: ModelUsage;
+}
+export interface ITrajectoryReflector {
+    /**
+     * Should the loop invoke {@link reflect} now? Default implementations
+     * gate on `step % everyNSteps === 0`.
+     */
+    shouldReflect(step: number, history: StepHistory[]): boolean;
+    /** Run the actual reflection. */
+    reflect(ctx: TrajectoryReflectCtx, signal?: AbortSignal): Promise<TrajectoryReflectVerdict>;
+    /** Optional cleanup. */
+    close?(): Promise<void>;
+}
+export interface LLMTrajectoryReflectorOptions {
+    /** Override `process.env.PLANNER_BASE_URL` (planner endpoint reused). */
+    baseUrl?: string;
+    apiKey?: string;
+    /** Defaults to `glm-4-flash`. */
+    modelName?: string;
+    /** Fire every N inner-loop steps. Defaults to 5. */
+    everyNSteps?: number;
+    /** Sampling temperature. Defaults to 0. */
+    temperature?: number;
+    /** Max output tokens. Defaults to 160 (room for `suggestion`). */
+    maxTokens?: number;
+    /** Reused OpenAI client for tests. */
+    client?: OpenAI;
+}
+export declare class LLMTrajectoryReflector implements ITrajectoryReflector {
+    readonly name = "llm-trajectory-reflector";
+    private readonly client;
+    private readonly modelName;
+    private readonly everyNSteps;
+    private readonly maxTokens;
+    private readonly temperature;
+    constructor(opts?: LLMTrajectoryReflectorOptions);
+    shouldReflect(step: number, history: StepHistory[]): boolean;
+    reflect(ctx: TrajectoryReflectCtx, signal?: AbortSignal): Promise<TrajectoryReflectVerdict>;
+}