@beeos-ai/device-agent 0.4.0

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

@@ -0,0 +1,223 @@
+/**
+ * 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 { getLogger } from "../../logger/index.js";
+const DEFAULT_MODEL = "glm-4-flash";
+const DEFAULT_EVERY_N = 5;
+const HISTORY_TAIL = 10;
+const STR_MAX = 240;
+export class LLMTrajectoryReflector {
+    name = "llm-trajectory-reflector";
+    client;
+    modelName;
+    everyNSteps;
+    maxTokens;
+    temperature;
+    constructor(opts = {}) {
+        this.modelName =
+            opts.modelName ?? process.env.TRAJECTORY_REFLECTOR_MODEL ?? DEFAULT_MODEL;
+        const fromEnv = readInt(process.env.TRAJECTORY_REFLECTOR_EVERY_N, NaN);
+        this.everyNSteps = Math.max(1, opts.everyNSteps ?? (Number.isFinite(fromEnv) ? fromEnv : DEFAULT_EVERY_N));
+        this.maxTokens = opts.maxTokens ?? 160;
+        this.temperature = opts.temperature ?? 0;
+        const baseUrl = opts.baseUrl ??
+            process.env.TRAJECTORY_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.TRAJECTORY_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(step, history) {
+        if (step <= 0)
+            return false;
+        if (step % this.everyNSteps !== 0)
+            return false;
+        // No need to fire when there is essentially no signal yet.
+        if (history.length === 0)
+            return false;
+        return true;
+    }
+    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: "trajectory-reflector", err: errMsg(e) }, "trajectory-reflector.failed");
+            return {
+                verdict: "on_track",
+                reason: `trajectory reflector unavailable: ${errMsg(e)}`,
+                usage: {
+                    inputTokens: 0,
+                    outputTokens: 0,
+                    durationMs: Date.now() - startedAt,
+                    costUsd: 0,
+                },
+            };
+        }
+    }
+}
+/* -------------------------------------------------------------------------- */
+/* Prompts                                                                    */
+/* -------------------------------------------------------------------------- */
+const SYSTEM_PROMPT = `You are the trajectory reviewer of a mobile-agent run.
+Every few steps you inspect the goal, the rolling step history, any notes the
+agent took mid-run, and the latest screen summary, and you classify the
+trajectory:
+
+- "on_track"  — clear progress toward the goal, keep going.
+- "off_track" — drifting onto a wrong sub-goal / wrong app / wrong screen.
+                Recoverable; the executor should re-plan.
+- "stuck"     — repeated failures or no observable progress for several steps.
+                The executor MUST replan or escalate.
+
+Output STRICT JSON:
+  {"verdict": "on_track" | "off_track" | "stuck",
+   "reason": "<<=200 chars>",
+   "suggestion": "<concrete next step, optional>"}
+
+Be conservative — only flag off_track / stuck when the evidence is clear.
+Empty notes / sparse history is normal early on; that alone is not stuck.`;
+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, STR_MAX),
+        actionResult: h.actionResult ?? null,
+        actError: h.actErrorMessage ?? null,
+        obsSummary: truncate(h.observationSummary, STR_MAX),
+    }));
+    return JSON.stringify({
+        goal: truncate(ctx.goal, STR_MAX * 2),
+        stepCounter: ctx.step,
+        maxSteps: ctx.maxSteps,
+        recentHistory: tail,
+        notes: ctx.notes.slice(-8).map((n) => truncate(n, STR_MAX)),
+        latestScreenSummary: truncate(ctx.observationSummary, STR_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 { verdict: "on_track", reason: "empty trajectory response" };
+    try {
+        const obj = JSON.parse(raw);
+        if (obj && typeof obj === "object") {
+            const verdict = normaliseVerdict(obj.verdict);
+            const reason = typeof obj.reason === "string"
+                ? obj.reason.trim()
+                : "";
+            const suggestion = typeof obj.suggestion === "string"
+                ? obj.suggestion.trim()
+                : undefined;
+            return {
+                verdict,
+                reason: reason || (verdict === "on_track" ? "ok" : "trajectory flagged"),
+                suggestion: suggestion && suggestion.length > 0 ? suggestion : undefined,
+            };
+        }
+    }
+    catch {
+        /* fall through */
+    }
+    return {
+        verdict: "on_track",
+        reason: `unparseable trajectory response: ${truncate(raw, 80)}`,
+    };
+}
+function normaliseVerdict(v) {
+    if (typeof v !== "string")
+        return "on_track";
+    const norm = v.trim().toLowerCase();
+    if (norm === "off_track" || norm === "off-track" || norm === "drift")
+        return "off_track";
+    if (norm === "stuck" || norm === "stalled")
+        return "stuck";
+    return "on_track";
+}
+const PRICING_PER_KTOK_USD = {
+    "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 readInt(raw, fallback) {
+    if (!raw)
+        return fallback;
+    const n = Number(raw);
+    return Number.isFinite(n) ? Math.floor(n) : fallback;
+}
+function errMsg(e) {
+    if (e instanceof Error)
+        return e.message;
+    return String(e);
+}
+//# sourceMappingURL=trajectory-reflector.js.map

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

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

package/dist/agent-runtime/skills/embedding.d.ts

@@ -0,0 +1,53 @@
+/**
+ * agent-runtime/skills/embedding — task-summary → dense vector helpers.
+ *
+ * Phase 3.1 of the [device-agent reflector upgrade plan](../../../../../../.cursor/plans/device-agent-reflector-skills_d5599350.plan.md).
+ *
+ * The plan calls for "glm-4-flash embedding endpoint OR hash
+ * bag-of-words". We default to the deterministic hash producer because:
+ *
+ *  - it has zero external deps and zero token cost,
+ *  - it gives reasonable recall on the "same task wording" case (which
+ *    is exactly what the cache hits on),
+ *  - it lets unit tests run hermetically without an OpenAI client,
+ *  - it can always be swapped out with an `EmbeddingProvider` plug-in
+ *    later (the matcher only needs `Float32Array` of a fixed size).
+ *
+ * The vector dimension matches the SQL schema — Phase 3.1 picks 256.
+ */
+export declare const DEFAULT_EMBEDDING_DIM = 256;
+/**
+ * Provider that turns a string into a fixed-length dense vector.
+ * Implementations may be sync (hash) or async (LLM endpoint). The
+ * matcher only invokes embed once per task, so an async hop is fine.
+ */
+export interface EmbeddingProvider {
+    readonly dim: number;
+    embed(text: string): Promise<Float32Array> | Float32Array;
+}
+/**
+ * Hash bag-of-words — fnv1a-32 per token, mod-projected onto a fixed
+ * dimension, L2-normalised. Same input yields the same vector across
+ * processes, which makes the cache deterministic.
+ */
+export declare class HashEmbeddingProvider implements EmbeddingProvider {
+    readonly dim: number;
+    constructor(dim?: number);
+    embed(text: string): Float32Array;
+}
+/**
+ * Cosine similarity in `[-1, 1]`. Returns 0 when either vector is the
+ * zero vector. Inputs are expected to share the same dimension; mixed
+ * dims throw.
+ */
+export declare function cosine(a: Float32Array, b: Float32Array): number;
+/**
+ * Encode a Float32Array to a Buffer (raw little-endian Float32 layout).
+ * Re-exported because the filesystem store base64-encodes this Buffer
+ * into the per-skill JSON file; bench / migration tooling can use it
+ * directly. The dimension is recovered from `buffer.byteLength / 4` on
+ * read.
+ */
+export declare function embeddingToBuffer(v: Float32Array): Buffer;
+/** Decode a Buffer back into a Float32Array (zero-copy when aligned). */
+export declare function bufferToEmbedding(buf: Buffer): Float32Array;

package/dist/agent-runtime/skills/embedding.js

@@ -0,0 +1,134 @@
+/**
+ * agent-runtime/skills/embedding — task-summary → dense vector helpers.
+ *
+ * Phase 3.1 of the [device-agent reflector upgrade plan](../../../../../../.cursor/plans/device-agent-reflector-skills_d5599350.plan.md).
+ *
+ * The plan calls for "glm-4-flash embedding endpoint OR hash
+ * bag-of-words". We default to the deterministic hash producer because:
+ *
+ *  - it has zero external deps and zero token cost,
+ *  - it gives reasonable recall on the "same task wording" case (which
+ *    is exactly what the cache hits on),
+ *  - it lets unit tests run hermetically without an OpenAI client,
+ *  - it can always be swapped out with an `EmbeddingProvider` plug-in
+ *    later (the matcher only needs `Float32Array` of a fixed size).
+ *
+ * The vector dimension matches the SQL schema — Phase 3.1 picks 256.
+ */
+export const DEFAULT_EMBEDDING_DIM = 256;
+/**
+ * Hash bag-of-words — fnv1a-32 per token, mod-projected onto a fixed
+ * dimension, L2-normalised. Same input yields the same vector across
+ * processes, which makes the cache deterministic.
+ */
+export class HashEmbeddingProvider {
+    dim;
+    constructor(dim = DEFAULT_EMBEDDING_DIM) {
+        this.dim = dim;
+    }
+    embed(text) {
+        const v = new Float32Array(this.dim);
+        if (!text)
+            return v;
+        const tokens = tokenize(text);
+        for (const tok of tokens) {
+            const h = fnv1a32(tok);
+            const idx = h % this.dim;
+            // Sign bit picks +1 / -1 so unrelated tokens don't all just add.
+            const sign = (h >>> 31) === 0 ? 1 : -1;
+            v[idx] += sign;
+        }
+        return l2Normalise(v);
+    }
+}
+/**
+ * Cosine similarity in `[-1, 1]`. Returns 0 when either vector is the
+ * zero vector. Inputs are expected to share the same dimension; mixed
+ * dims throw.
+ */
+export function cosine(a, b) {
+    if (a.length !== b.length) {
+        throw new Error(`cosine: length mismatch ${a.length} vs ${b.length}`);
+    }
+    let dot = 0;
+    let aa = 0;
+    let bb = 0;
+    for (let i = 0; i < a.length; i++) {
+        const ax = a[i];
+        const bx = b[i];
+        dot += ax * bx;
+        aa += ax * ax;
+        bb += bx * bx;
+    }
+    if (aa === 0 || bb === 0)
+        return 0;
+    return dot / Math.sqrt(aa * bb);
+}
+/**
+ * Encode a Float32Array to a Buffer (raw little-endian Float32 layout).
+ * Re-exported because the filesystem store base64-encodes this Buffer
+ * into the per-skill JSON file; bench / migration tooling can use it
+ * directly. The dimension is recovered from `buffer.byteLength / 4` on
+ * read.
+ */
+export function embeddingToBuffer(v) {
+    return Buffer.from(v.buffer, v.byteOffset, v.byteLength);
+}
+/** Decode a Buffer back into a Float32Array (zero-copy when aligned). */
+export function bufferToEmbedding(buf) {
+    // Buffer's underlying ArrayBuffer can be a slice — copy out so callers
+    // can hold the typed array beyond the buffer's lifetime.
+    const view = new Float32Array(buf.byteLength / 4);
+    for (let i = 0; i < view.length; i++) {
+        view[i] = buf.readFloatLE(i * 4);
+    }
+    return view;
+}
+/* -------------------------------------------------------------------------- */
+/* internals                                                                  */
+/* -------------------------------------------------------------------------- */
+function tokenize(text) {
+    // Whitespace tokens for ASCII / Latin scripts + per-character tokens for
+    // CJK (where there's no whitespace between glyphs). This is deliberately
+    // dumb — we only need enough recall to match "buy chicken" against
+    // "purchase chicken" or "买鸡" against "买只鸡".
+    const tokens = [];
+    for (const word of text.toLowerCase().split(/[^\p{L}\p{N}]+/u)) {
+        if (!word)
+            continue;
+        if (/[\u3400-\u9fff]/.test(word)) {
+            // CJK — emit each character + the bigrams to capture local order.
+            const chars = [...word];
+            for (const ch of chars)
+                tokens.push(ch);
+            for (let i = 0; i + 1 < chars.length; i++) {
+                tokens.push(chars[i] + chars[i + 1]);
+            }
+        }
+        else {
+            tokens.push(word);
+        }
+    }
+    return tokens;
+}
+function fnv1a32(s) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i);
+        // 32-bit FNV prime multiplication.
+        h = (h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24))) >>> 0;
+    }
+    return h >>> 0;
+}
+function l2Normalise(v) {
+    let sum = 0;
+    for (let i = 0; i < v.length; i++)
+        sum += v[i] * v[i];
+    if (sum === 0)
+        return v;
+    const inv = 1 / Math.sqrt(sum);
+    for (let i = 0; i < v.length; i++)
+        v[i] *= inv;
+    return v;
+}
+//# sourceMappingURL=embedding.js.map

package/dist/agent-runtime/skills/embedding.js.map

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

package/dist/agent-runtime/skills/fs-store.d.ts

@@ -0,0 +1,88 @@
+/**
+ * agent-runtime/skills/fs-store — FileSystem-backed
+ * {@link SkillCacheStore}.
+ *
+ * Layout:
+ * ```
+ * <root>/
+ * ├── _meta/
+ * │   └── version                         # plain text "1"
+ * ├── com.tencent.mm/
+ * │   ├── 8dc7bafa-...-e58122.json        # main record (atomic tmp+rename)
+ * │   └── 8dc7bafa-...-e58122.deltas.jsonl # append-only counter log
+ * └── com.xunmeng.pinduoduo/
+ *     └── ...
+ * ```
+ *
+ * The default root is `~/.beeos/device-agent/skills/`. Cloud
+ * deployments mount a `ReadWriteMany` PVC at `$HOME/.beeos` so multiple
+ * pods see one shared cache; on a developer laptop / EdgeAgent host the
+ * directory is just a local folder, naturally shared by every
+ * `device-agent` process running on that machine.
+ *
+ * Counter atomicity relies on POSIX O_APPEND semantics: each
+ * `recordSuccess` / `recordFailure` writes a single ≤30-byte line via
+ * `fs.appendFileSync`, which the kernel guarantees to be atomic across
+ * processes (line ≤ PIPE_BUF). When `deltas.jsonl` exceeds
+ * `compactThresholdBytes` (default 4 KB) the next writer folds the
+ * accumulated deltas into the main JSON via tmp+rename and truncates
+ * the deltas file. Read paths always fold the live deltas plus any
+ * orphaned `*.compacting` files left by a crashed writer.
+ *
+ * The schema is intentionally diff-friendly (one self-contained JSON
+ * per skill, base64-encoded embedding) so users can inspect / git-track
+ * / rsync the cache directly.
+ */
+import type { NewSkillInput, Skill, SkillCacheStore, SkillMatch } from "./types.js";
+export interface FileSystemSkillCacheStoreOptions {
+    /**
+     * Root directory under which the per-app subfolders live. Defaults
+     * to `~/.beeos/device-agent/skills/`.
+     */
+    root?: string;
+    /**
+     * Skip the auto-mkdir step on construction. Tests typically pass a
+     * pre-existing tmp dir.
+     */
+    noMkdir?: boolean;
+    /**
+     * Override the compaction trigger size. Tests use a small value
+     * (e.g. 256 bytes) to exercise compaction; production keeps the
+     * default to stay below PIPE_BUF.
+     */
+    compactThresholdBytes?: number;
+}
+/**
+ * Default cache root: `~/.beeos/device-agent/skills/` unless
+ * `SKILL_CACHE_PATH` overrides it. Returns a directory path (the
+ * legacy SQLite store returned a `.sqlite` *file*; the new layout is
+ * directory-based).
+ */
+export declare function defaultSkillCachePath(): string;
+export declare class FileSystemSkillCacheStore implements SkillCacheStore {
+    private readonly root;
+    private readonly compactThreshold;
+    constructor(opts?: FileSystemSkillCacheStoreOptions);
+    insert(input: NewSkillInput): Skill;
+    get(id: string): Skill | undefined;
+    listByApp(appPackage: string, limit?: number): Skill[];
+    listAll(limit?: number): Skill[];
+    search(appPackage: string, query: Float32Array, k: number): SkillMatch[];
+    recordSuccess(id: string, now?: number): void;
+    recordFailure(id: string, now?: number): void;
+    delete(id: string): boolean;
+    clear(): void;
+    close(): void;
+    private writeVersionIfMissing;
+    private appDir;
+    private skillJsonPath;
+    private skillDeltasPath;
+    private appDirs;
+    private skillIdsIn;
+    private locate;
+    private readSkill;
+    private foldDeltaFiles;
+    private findCompacting;
+    private appendDelta;
+    private maybeCompact;
+}