@beeos-ai/device-agent 0.4.0

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

@@ -0,0 +1,60 @@
+/**
+ * agent-runtime/skills/sqlite-store — SQLite-backed
+ * {@link SkillCacheStore}.
+ *
+ * Phase 3.1 of the [device-agent reflector upgrade plan](../../../../../../.cursor/plans/device-agent-reflector-skills_d5599350.plan.md).
+ *
+ * Schema (kept verbatim with the plan):
+ * ```sql
+ * CREATE TABLE skills (
+ *   id TEXT PRIMARY KEY,
+ *   app_package TEXT NOT NULL,
+ *   task_summary TEXT NOT NULL,
+ *   task_embedding BLOB,
+ *   action_sequence_json TEXT NOT NULL,
+ *   success_count INTEGER NOT NULL DEFAULT 1,
+ *   fail_count INTEGER NOT NULL DEFAULT 0,
+ *   last_used_at INTEGER NOT NULL,
+ *   created_at INTEGER NOT NULL
+ * );
+ * CREATE INDEX idx_skills_app ON skills(app_package);
+ * ```
+ *
+ * Default DB path: `~/.beeos/device-agent/skills.sqlite`. Containerised
+ * deployments mount `/var/lib/beeos/device-agent` and override
+ * `SKILL_CACHE_PATH` accordingly.
+ *
+ * Search is implemented as a full scan over the matching app rows —
+ * the cache is intentionally small (<10k rows / device), so a brute
+ * cosine pass is cheaper than maintaining an ANN index. If profile
+ * data shows that's wrong we can plug in `sqlite-vss` / `pgvector`
+ * later behind the same {@link SkillCacheStore} interface.
+ */
+import type { Database as DB } from "better-sqlite3";
+import type { NewSkillInput, Skill, SkillCacheStore, SkillMatch } from "./types.js";
+export interface SQLiteSkillCacheStoreOptions {
+    /** Override the default DB path. Use ":memory:" for ephemeral tests. */
+    path?: string;
+    /** Pre-built better-sqlite3 Database (used by tests). */
+    db?: DB;
+    /** Skip auto-mkdir on the parent dir (when path is :memory:). */
+    noMkdir?: boolean;
+}
+export declare function defaultSkillCachePath(): string;
+export declare class SQLiteSkillCacheStore implements SkillCacheStore {
+    private readonly db;
+    private readonly stmts;
+    private closed;
+    constructor(opts?: SQLiteSkillCacheStoreOptions);
+    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 applyMigrations;
+}

package/dist/agent-runtime/skills/sqlite-store.js

@@ -0,0 +1,234 @@
+/**
+ * agent-runtime/skills/sqlite-store — SQLite-backed
+ * {@link SkillCacheStore}.
+ *
+ * Phase 3.1 of the [device-agent reflector upgrade plan](../../../../../../.cursor/plans/device-agent-reflector-skills_d5599350.plan.md).
+ *
+ * Schema (kept verbatim with the plan):
+ * ```sql
+ * CREATE TABLE skills (
+ *   id TEXT PRIMARY KEY,
+ *   app_package TEXT NOT NULL,
+ *   task_summary TEXT NOT NULL,
+ *   task_embedding BLOB,
+ *   action_sequence_json TEXT NOT NULL,
+ *   success_count INTEGER NOT NULL DEFAULT 1,
+ *   fail_count INTEGER NOT NULL DEFAULT 0,
+ *   last_used_at INTEGER NOT NULL,
+ *   created_at INTEGER NOT NULL
+ * );
+ * CREATE INDEX idx_skills_app ON skills(app_package);
+ * ```
+ *
+ * Default DB path: `~/.beeos/device-agent/skills.sqlite`. Containerised
+ * deployments mount `/var/lib/beeos/device-agent` and override
+ * `SKILL_CACHE_PATH` accordingly.
+ *
+ * Search is implemented as a full scan over the matching app rows —
+ * the cache is intentionally small (<10k rows / device), so a brute
+ * cosine pass is cheaper than maintaining an ANN index. If profile
+ * data shows that's wrong we can plug in `sqlite-vss` / `pgvector`
+ * later behind the same {@link SkillCacheStore} interface.
+ */
+import { mkdirSync } from "node:fs";
+import path from "node:path";
+import { homedir } from "node:os";
+import { randomUUID } from "node:crypto";
+import Database from "better-sqlite3";
+import { bufferToEmbedding, cosine, embeddingToBuffer, } from "./embedding.js";
+const SCHEMA_VERSION = 1;
+const SCHEMA_SQL = `
+PRAGMA journal_mode=WAL;
+PRAGMA synchronous=NORMAL;
+PRAGMA foreign_keys=ON;
+
+CREATE TABLE IF NOT EXISTS skills (
+  id                  TEXT PRIMARY KEY,
+  app_package         TEXT NOT NULL,
+  task_summary        TEXT NOT NULL,
+  task_embedding      BLOB,
+  action_sequence_json TEXT NOT NULL,
+  success_count       INTEGER NOT NULL DEFAULT 1,
+  fail_count          INTEGER NOT NULL DEFAULT 0,
+  last_used_at        INTEGER NOT NULL,
+  created_at          INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_skills_app ON skills(app_package);
+
+CREATE TABLE IF NOT EXISTS skill_meta (
+  key   TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+`;
+export function defaultSkillCachePath() {
+    const env = process.env.SKILL_CACHE_PATH;
+    if (env && env.length > 0)
+        return env;
+    return path.join(homedir(), ".beeos", "device-agent", "skills.sqlite");
+}
+export class SQLiteSkillCacheStore {
+    db;
+    stmts;
+    closed = false;
+    constructor(opts = {}) {
+        const dbPath = opts.path ?? defaultSkillCachePath();
+        if (opts.db) {
+            this.db = opts.db;
+        }
+        else {
+            if (!opts.noMkdir && dbPath !== ":memory:") {
+                mkdirSync(path.dirname(dbPath), { recursive: true });
+            }
+            this.db = new Database(dbPath);
+        }
+        this.db.exec(SCHEMA_SQL);
+        this.applyMigrations();
+        this.stmts = prepareStatements(this.db);
+    }
+    insert(input) {
+        if (this.closed)
+            throw new Error("SQLiteSkillCacheStore: handle closed");
+        const now = Date.now();
+        const id = randomUUID();
+        this.stmts.insert.run({
+            id,
+            app: input.appPackage,
+            summary: input.taskSummary,
+            embed: input.taskEmbedding ? embeddingToBuffer(input.taskEmbedding) : null,
+            seq: serialiseSequence(input.actionSequence),
+            now,
+        });
+        return {
+            id,
+            appPackage: input.appPackage,
+            taskSummary: input.taskSummary,
+            taskEmbedding: input.taskEmbedding ? new Float32Array(input.taskEmbedding) : undefined,
+            actionSequence: input.actionSequence,
+            successCount: 1,
+            failCount: 0,
+            lastUsedAt: now,
+            createdAt: now,
+        };
+    }
+    get(id) {
+        const row = this.stmts.getById.get({ id });
+        return row ? rowToSkill(row) : undefined;
+    }
+    listByApp(appPackage, limit = 50) {
+        const rows = this.stmts.listByApp.all({ app: appPackage, limit });
+        return rows.map(rowToSkill);
+    }
+    listAll(limit = 200) {
+        const rows = this.stmts.listAll.all({ limit });
+        return rows.map(rowToSkill);
+    }
+    search(appPackage, query, k) {
+        const rows = this.stmts.searchByApp.all({ app: appPackage });
+        const matches = [];
+        for (const row of rows) {
+            if (!row.task_embedding)
+                continue;
+            const v = bufferToEmbedding(row.task_embedding);
+            if (v.length !== query.length)
+                continue;
+            const score = cosine(query, v);
+            matches.push({ skill: rowToSkill(row), score });
+        }
+        matches.sort((a, b) => b.score - a.score);
+        return matches.slice(0, Math.max(0, k));
+    }
+    recordSuccess(id, now = Date.now()) {
+        this.stmts.success.run({ id, now });
+    }
+    recordFailure(id, now = Date.now()) {
+        this.stmts.failure.run({ id, now });
+    }
+    delete(id) {
+        const res = this.stmts.delete.run({ id });
+        return res.changes > 0;
+    }
+    clear() {
+        this.db.exec("DELETE FROM skills;");
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        try {
+            this.db.close();
+        }
+        catch {
+            /* swallow — close is best-effort */
+        }
+    }
+    applyMigrations() {
+        const row = this.db
+            .prepare("SELECT value FROM skill_meta WHERE key = 'schema_version'")
+            .get();
+        if (!row) {
+            this.db
+                .prepare("INSERT INTO skill_meta(key, value) VALUES('schema_version', ?)")
+                .run(String(SCHEMA_VERSION));
+            return;
+        }
+        // Future migrations would diff `row.value` against SCHEMA_VERSION here.
+    }
+}
+function prepareStatements(db) {
+    return {
+        insert: db.prepare(`INSERT INTO skills (
+         id, app_package, task_summary, task_embedding,
+         action_sequence_json, success_count, fail_count, last_used_at, created_at
+       ) VALUES (
+         @id, @app, @summary, @embed,
+         @seq, 1, 0, @now, @now
+       );`),
+        getById: db.prepare(`SELECT * FROM skills WHERE id = @id`),
+        listByApp: db.prepare(`SELECT * FROM skills
+       WHERE app_package = @app
+       ORDER BY last_used_at DESC
+       LIMIT @limit`),
+        listAll: db.prepare(`SELECT * FROM skills
+       ORDER BY last_used_at DESC
+       LIMIT @limit`),
+        searchByApp: db.prepare(`SELECT * FROM skills WHERE app_package = @app`),
+        success: db.prepare(`UPDATE skills SET success_count = success_count + 1,
+                          last_used_at = @now
+       WHERE id = @id`),
+        failure: db.prepare(`UPDATE skills SET fail_count = fail_count + 1,
+                          last_used_at = @now
+       WHERE id = @id`),
+        delete: db.prepare(`DELETE FROM skills WHERE id = @id`),
+    };
+}
+function serialiseSequence(seq) {
+    return JSON.stringify(seq);
+}
+function deserialiseSequence(raw) {
+    if (!raw)
+        return [];
+    try {
+        const v = JSON.parse(raw);
+        if (Array.isArray(v)) {
+            return v;
+        }
+        return [];
+    }
+    catch {
+        return [];
+    }
+}
+function rowToSkill(row) {
+    return {
+        id: row.id,
+        appPackage: row.app_package,
+        taskSummary: row.task_summary,
+        taskEmbedding: row.task_embedding ? bufferToEmbedding(row.task_embedding) : undefined,
+        actionSequence: deserialiseSequence(row.action_sequence_json),
+        successCount: row.success_count,
+        failCount: row.fail_count,
+        lastUsedAt: row.last_used_at,
+        createdAt: row.created_at,
+    };
+}
+//# sourceMappingURL=sqlite-store.js.map

package/dist/agent-runtime/skills/sqlite-store.js.map

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

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

@@ -0,0 +1,99 @@
+/**
+ * agent-runtime/skills/types — Skill memory shared types.
+ *
+ * Phase 3.1 of the [device-agent reflector upgrade plan](../../../../../../.cursor/plans/device-agent-reflector-skills_d5599350.plan.md).
+ *
+ * The skill cache stores normalised action sequences keyed by (app, task
+ * summary). At task-entry time the {@link SkillMatcher} consults the
+ * cache; at task-exit time the {@link SkillEvolver} updates success /
+ * failure counters. Both layers depend only on this minimal type
+ * surface, which is also exercised by the unit tests via the in-memory
+ * implementation.
+ */
+import type { Action } from "@beeos-ai/device-common";
+/**
+ * Normalised action sequence — the minimum the executor needs to
+ * replay a successful task. Coordinates and rationales are kept; ad-hoc
+ * `screenshot` / `wait` steps are stripped by the evolver before
+ * persistence so the replay budget stays small.
+ */
+export type SkillActionSequence = readonly Action[];
+/**
+ * One persisted skill row.
+ *
+ * All numeric fields are stored as integers (epoch millis for
+ * timestamps). `taskEmbedding` is an optional dense vector — the
+ * matcher computes cosine similarity against the live task embedding.
+ * When the embedding model is unavailable we fall back to the
+ * deterministic hash bag-of-words producer in
+ * [embedding.ts](./embedding.ts), which is good enough for "same
+ * grocery-shopping task" recall.
+ */
+export interface Skill {
+    id: string;
+    appPackage: string;
+    taskSummary: string;
+    taskEmbedding?: Float32Array;
+    actionSequence: SkillActionSequence;
+    successCount: number;
+    failCount: number;
+    lastUsedAt: number;
+    createdAt: number;
+}
+/** Result of a similarity search. */
+export interface SkillMatch {
+    skill: Skill;
+    /** cosine similarity in `[0, 1]`. */
+    score: number;
+}
+/** Read-only skill view returned by the CLI. Hides the raw embedding blob. */
+export type SkillSummary = Omit<Skill, "taskEmbedding"> & {
+    successRate: number;
+    hasEmbedding: boolean;
+};
+export interface NewSkillInput {
+    appPackage: string;
+    taskSummary: string;
+    taskEmbedding?: Float32Array;
+    actionSequence: SkillActionSequence;
+}
+/**
+ * Storage abstraction for the skill cache. Implementations:
+ *  - {@link FileSystemSkillCacheStore} — production directory layout at
+ *    `~/.beeos/device-agent/skills/<appPackage>/<id>.json` with
+ *    append-only `<id>.deltas.jsonl` counter logs (POSIX-atomic, lock-free).
+ *  - {@link InMemorySkillCacheStore} — used by tests and any caller
+ *    that wants ephemeral state.
+ *
+ * Methods are synchronous because the filesystem backend uses
+ * `fs.appendFileSync` / atomic tmp+rename — both are synchronous and
+ * we deliberately avoid leaking a Promise indirection through the
+ * loop's hot path. Concurrency across processes is handled by
+ * O_APPEND for ≤PIPE_BUF writes; no in-process locking is required.
+ */
+export interface SkillCacheStore {
+    /** Persist a brand-new skill row and return the id. */
+    insert(input: NewSkillInput): Skill;
+    /** Fetch a single skill by id (or undefined). */
+    get(id: string): Skill | undefined;
+    /** List all skills for one app package, newest first. */
+    listByApp(appPackage: string, limit?: number): Skill[];
+    /** List every skill (debug / CLI). */
+    listAll(limit?: number): Skill[];
+    /**
+     * Top-K cosine search restricted to the given app package. Skills
+     * without an embedding are skipped (caller may still call `listByApp`
+     * to consider them).
+     */
+    search(appPackage: string, query: Float32Array, k: number): SkillMatch[];
+    /** Increment the success counter and bump `last_used_at`. */
+    recordSuccess(id: string, now?: number): void;
+    /** Increment the fail counter and bump `last_used_at`. */
+    recordFailure(id: string, now?: number): void;
+    /** Delete a single skill (CLI `forget`). */
+    delete(id: string): boolean;
+    /** Delete all skills (test reset / CLI `forget --all`). */
+    clear(): void;
+    /** Free underlying handles. Safe to call multiple times. */
+    close(): void;
+}

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

@@ -0,0 +1,14 @@
+/**
+ * agent-runtime/skills/types — Skill memory shared types.
+ *
+ * Phase 3.1 of the [device-agent reflector upgrade plan](../../../../../../.cursor/plans/device-agent-reflector-skills_d5599350.plan.md).
+ *
+ * The skill cache stores normalised action sequences keyed by (app, task
+ * summary). At task-entry time the {@link SkillMatcher} consults the
+ * cache; at task-exit time the {@link SkillEvolver} updates success /
+ * failure counters. Both layers depend only on this minimal type
+ * surface, which is also exercised by the unit tests via the in-memory
+ * implementation.
+ */
+export {};
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/agent-runtime/skills/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/agent.d.ts

@@ -0,0 +1,110 @@
+/**
+ * @deprecated since v0.3.0 — use `AgentRunner` from `agent-runtime/agent-runner.ts`
+ * (or the `AgentRunnerCore` adapter at `adapters/agentcore-runner.ts` for
+ * embedders that need an `IAgentCore`). This shim only exists so that
+ * `InnerLoopVlm`, the legacy `api.ts` HTTP debug server, and external
+ * test embedders keep working without changes — new call sites must NOT
+ * reach for this class.
+ *
+ * Migration sketch:
+ *
+ * ```typescript
+ * // Before (v0.2.x)
+ * const a = new Agent(modelClient, device);
+ * const r = await a.run(task, { onStep, signal });
+ *
+ * // After (v0.3.0+)
+ * const adapter = new OpenAIAdapter({ client: modelClient, lang: "cn" });
+ * const mcp = new InProcMcpClient(device);
+ * const runner = new AgentRunner({ task, env: "mobile", mcp, adapter });
+ * const r = await runner.run();
+ * ```
+ *
+ * Legacy `Agent` — backwards-compatible shim around the new `AgentLoop`.
+ *
+ * Pre-monorepo this class hosted a hand-rolled screenshot → reason → act
+ * loop. The loop has now moved into `agent-runtime/core.AgentLoop`, which is
+ * Plan-Act-Reflect-aware, drives any `IMcpRuntime`, and wires every model
+ * through an `IModelAdapter`. This file keeps the original constructor
+ * signature, public methods, hook payload shapes, and termination strings so
+ * that `InnerLoopVlm`, `api.ts`, the `agent-hooks` test suite, and any
+ * external embedder continue to work without changes.
+ *
+ * Internally a fresh `AgentLoop` is constructed for each `run()` call. The
+ * device handed to the constructor is wrapped in `InProcMcpClient` (no HTTP
+ * hop), and the `ModelClient` is wrapped in `OpenAIAdapter` (the adapter
+ * that already translates legacy `ParsedAction` outputs onto the new unified
+ * `Action` schema, preserving coordinate-system metadata for AgentLoop's
+ * scaling layer).
+ *
+ * The shim is intentionally thin — anything new (waitForUser, reflection
+ * hooks, custom adapters, alternate envs) should go straight to `AgentLoop`
+ * (or `AgentRunner` for the Hybrid Plan-Act path).
+ */
+import type { Device } from "./device/base.js";
+import type { ModelClient } from "./model/base.js";
+export interface AgentConfig {
+    maxSteps?: number;
+    lang?: "cn" | "en";
+    verbose?: boolean;
+}
+/**
+ * Per-step record surfaced via `Agent.run`'s `onStep` hook. Kept stable so
+ * callers (notably `InnerLoopVlm`) can map directly onto the public
+ * `VlmStep` shape without re-deriving fields.
+ */
+export interface AgentStepRecord {
+    /** 1-based step index, matches `Agent.stepCount`. */
+    index: number;
+    /** Model thinking text for this step. */
+    thinking: string;
+    /** Parsed action (tool call) the model decided on. */
+    action: {
+        actionType: string;
+        params: Record<string, unknown>;
+    } | null;
+    /** True iff this step was the terminating step. */
+    finished: boolean;
+    /** Final user-facing message when `finished` is true. */
+    message: string | null;
+}
+/** Optional progress callbacks for `Agent.run`. */
+export interface AgentRunHooks {
+    /** Streaming token delta from the underlying model. */
+    onText?: (delta: string) => void | Promise<void>;
+    /** Fired exactly once per step after the action has been parsed. */
+    onStep?: (step: AgentStepRecord) => void | Promise<void>;
+}
+export interface AgentRunOptions extends AgentRunHooks {
+    signal?: AbortSignal;
+    /**
+     * Per-call override of `AgentConfig.maxSteps`. When omitted the value
+     * passed to the constructor is used.
+     */
+    maxSteps?: number;
+}
+export interface AgentRunResult {
+    /** Final user-facing message, identical to the legacy `string` return. */
+    finalText: string;
+    /** Number of `executeStep` invocations (1-based count). */
+    steps: number;
+    /** True iff the run terminated due to abort. */
+    cancelled: boolean;
+}
+/** @deprecated since v0.3.0 — use `AgentRunner` instead. */
+export declare class Agent {
+    private readonly modelClient;
+    private readonly cfg;
+    private readonly mcp;
+    private readonly adapter;
+    constructor(modelClient: ModelClient, device: Device, config?: AgentConfig);
+    run(task: string, opts?: AgentRunOptions): Promise<AgentRunResult>;
+    /**
+     * Legacy hook — clears any rolling adapter context so the next `run()`
+     * starts fresh. The new `AgentLoop` already isolates state per run, so
+     * this only matters if callers reach into the adapter directly.
+     */
+    reset(): void;
+    /** Internal — kept for backwards compatibility with embedders that peek. */
+    get model(): ModelClient;
+}