@beeos-ai/device-agent 0.4.2 → 0.5.0

package/dist/agent-runtime/shortcuts/fs-store.js

@@ -0,0 +1,122 @@
+/**
+ * Filesystem-backed `ShortcutMemoryStore` — minimal Phase 3
+ * implementation per ADR 001.
+ *
+ * Layout (under `<root>/`, defaults to
+ * `~/.beeos/device-agent/shortcuts/`):
+ *
+ *   <root>/index.json         — single JSON file mapping
+ *                                "<taskPattern>::<shortcutId>" →
+ *                                ShortcutMemoryRecord.
+ *
+ * We deliberately use a single index file (not one-file-per-record)
+ * because Phase 3 is write-only telemetry and the catalogue is
+ * 4 shortcuts. The file is rewritten atomically (tmp + rename) on
+ * every increment to keep the on-disk view consistent for the
+ * future matcher.
+ *
+ * Concurrency:
+ *   The bootstrap process creates one `FsShortcutMemoryStore` per
+ *   device-agent process. Cross-process locking is out of scope for
+ *   Phase 3 — nothing reads-modifies the index outside the agent.
+ */
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { homedir } from "node:os";
+const INDEX_FILE = "index.json";
+function defaultRoot() {
+    return path.join(homedir(), ".beeos", "device-agent", "shortcuts");
+}
+function recordKey(taskPattern, shortcutId) {
+    return `${taskPattern}::${shortcutId}`;
+}
+export class FsShortcutMemoryStore {
+    root;
+    cache = null;
+    /** Serialise concurrent writes within the same process. */
+    writeChain = Promise.resolve();
+    constructor(opts = {}) {
+        this.root = opts.root ?? defaultRoot();
+    }
+    async recordSuccess(taskPattern, shortcutId) {
+        return this.mutate(taskPattern, shortcutId, (rec, now) => {
+            rec.successCount += 1;
+            rec.totalCount += 1;
+            rec.lastUpdatedAt = now;
+        });
+    }
+    async recordFailure(taskPattern, shortcutId, code) {
+        return this.mutate(taskPattern, shortcutId, (rec, now) => {
+            rec.failCountByCode[code] = (rec.failCountByCode[code] ?? 0) + 1;
+            rec.totalCount += 1;
+            rec.lastUpdatedAt = now;
+        });
+    }
+    async get(taskPattern, shortcutId) {
+        const idx = await this.loadIndex();
+        return idx[recordKey(taskPattern, shortcutId)];
+    }
+    async list() {
+        const idx = await this.loadIndex();
+        return Object.values(idx);
+    }
+    /* ---------------------------------------------------------------- */
+    /* internals                                                         */
+    /* ---------------------------------------------------------------- */
+    async loadIndex() {
+        if (this.cache)
+            return this.cache;
+        try {
+            const raw = await fs.readFile(path.join(this.root, INDEX_FILE), "utf8");
+            this.cache = JSON.parse(raw);
+        }
+        catch (e) {
+            const err = e;
+            if (err.code !== "ENOENT") {
+                // Corruption / parse error — start fresh rather than crash. The
+                // store is telemetry, the agent must keep running.
+                this.cache = {};
+                return this.cache;
+            }
+            this.cache = {};
+        }
+        return this.cache;
+    }
+    async writeIndex() {
+        if (!this.cache)
+            return;
+        await fs.mkdir(this.root, { recursive: true });
+        const finalPath = path.join(this.root, INDEX_FILE);
+        const tmpPath = `${finalPath}.tmp-${process.pid}-${Date.now()}`;
+        await fs.writeFile(tmpPath, JSON.stringify(this.cache, null, 2), "utf8");
+        await fs.rename(tmpPath, finalPath);
+    }
+    mutate(taskPattern, shortcutId, update) {
+        const next = this.writeChain.then(async () => {
+            const now = Date.now();
+            const idx = await this.loadIndex();
+            const key = recordKey(taskPattern, shortcutId);
+            let rec = idx[key];
+            if (!rec) {
+                rec = {
+                    taskPattern,
+                    shortcutId,
+                    successCount: 0,
+                    failCountByCode: {},
+                    totalCount: 0,
+                    createdAt: now,
+                    lastUpdatedAt: now,
+                };
+                idx[key] = rec;
+            }
+            update(rec, now);
+            await this.writeIndex();
+        });
+        // Swallow errors on the chain so a single failed write doesn't
+        // poison every subsequent one. Each `next` promise still rejects
+        // for the caller that triggered it.
+        this.writeChain = next.catch(() => undefined);
+        return next;
+    }
+}
+//# sourceMappingURL=fs-store.js.map

package/dist/agent-runtime/shortcuts/fs-store.js.map

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

package/dist/agent-runtime/shortcuts/in-memory-store.d.ts

@@ -0,0 +1,20 @@
+/**
+ * In-memory `ShortcutMemoryStore` — used by tests and as the default
+ * before the bootstrap layer optionally swaps in a `FsShortcutMemoryStore`.
+ *
+ * Storage layout:
+ *   `Map<key, ShortcutMemoryRecord>` where `key = "<taskPattern>::<shortcutId>"`.
+ *
+ * The store is intentionally tiny — Phase 3 is "telemetry-only" per
+ * the plan. Compaction, eviction, and concurrency safety are out of
+ * scope; tests confirm the pure-counter semantics.
+ */
+import type { ShortcutMemoryRecord, ShortcutMemoryStore } from "./types.js";
+import type { ShortcutErrorCode } from "../../shortcuts/types.js";
+export declare class InMemoryShortcutMemoryStore implements ShortcutMemoryStore {
+    private readonly entries;
+    recordSuccess(taskPattern: string, shortcutId: string): Promise<void>;
+    recordFailure(taskPattern: string, shortcutId: string, code: ShortcutErrorCode): Promise<void>;
+    get(taskPattern: string, shortcutId: string): Promise<ShortcutMemoryRecord | undefined>;
+    list(): Promise<ShortcutMemoryRecord[]>;
+}

package/dist/agent-runtime/shortcuts/in-memory-store.js

@@ -0,0 +1,64 @@
+/**
+ * In-memory `ShortcutMemoryStore` — used by tests and as the default
+ * before the bootstrap layer optionally swaps in a `FsShortcutMemoryStore`.
+ *
+ * Storage layout:
+ *   `Map<key, ShortcutMemoryRecord>` where `key = "<taskPattern>::<shortcutId>"`.
+ *
+ * The store is intentionally tiny — Phase 3 is "telemetry-only" per
+ * the plan. Compaction, eviction, and concurrency safety are out of
+ * scope; tests confirm the pure-counter semantics.
+ */
+function recordKey(taskPattern, shortcutId) {
+    return `${taskPattern}::${shortcutId}`;
+}
+export class InMemoryShortcutMemoryStore {
+    entries = new Map();
+    async recordSuccess(taskPattern, shortcutId) {
+        const now = Date.now();
+        const key = recordKey(taskPattern, shortcutId);
+        const existing = this.entries.get(key);
+        if (existing) {
+            existing.successCount += 1;
+            existing.totalCount += 1;
+            existing.lastUpdatedAt = now;
+            return;
+        }
+        this.entries.set(key, {
+            taskPattern,
+            shortcutId,
+            successCount: 1,
+            failCountByCode: {},
+            totalCount: 1,
+            createdAt: now,
+            lastUpdatedAt: now,
+        });
+    }
+    async recordFailure(taskPattern, shortcutId, code) {
+        const now = Date.now();
+        const key = recordKey(taskPattern, shortcutId);
+        const existing = this.entries.get(key);
+        if (existing) {
+            existing.failCountByCode[code] = (existing.failCountByCode[code] ?? 0) + 1;
+            existing.totalCount += 1;
+            existing.lastUpdatedAt = now;
+            return;
+        }
+        this.entries.set(key, {
+            taskPattern,
+            shortcutId,
+            successCount: 0,
+            failCountByCode: { [code]: 1 },
+            totalCount: 1,
+            createdAt: now,
+            lastUpdatedAt: now,
+        });
+    }
+    async get(taskPattern, shortcutId) {
+        return this.entries.get(recordKey(taskPattern, shortcutId));
+    }
+    async list() {
+        return Array.from(this.entries.values());
+    }
+}
+//# sourceMappingURL=in-memory-store.js.map

package/dist/agent-runtime/shortcuts/in-memory-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-memory-store.js","sourceRoot":"","sources":["../../../src/agent-runtime/shortcuts/in-memory-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAQH,SAAS,SAAS,CAAC,WAAmB,EAAE,UAAkB;IACxD,OAAO,GAAG,WAAW,KAAK,UAAU,EAAE,CAAC;AACzC,CAAC;AAED,MAAM,OAAO,2BAA2B;IACrB,OAAO,GAAG,IAAI,GAAG,EAAgC,CAAC;IAEnE,KAAK,CAAC,aAAa,CAAC,WAAmB,EAAE,UAAkB;QACzD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,GAAG,GAAG,SAAS,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC;QAC/C,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACvC,IAAI,QAAQ,EAAE,CAAC;YACb,QAAQ,CAAC,YAAY,IAAI,CAAC,CAAC;YAC3B,QAAQ,CAAC,UAAU,IAAI,CAAC,CAAC;YACzB,QAAQ,CAAC,aAAa,GAAG,GAAG,CAAC;YAC7B,OAAO;QACT,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE;YACpB,WAAW;YACX,UAAU;YACV,YAAY,EAAE,CAAC;YACf,eAAe,EAAE,EAAE;YACnB,UAAU,EAAE,CAAC;YACb,SAAS,EAAE,GAAG;YACd,aAAa,EAAE,GAAG;SACnB,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,aAAa,CACjB,WAAmB,EACnB,UAAkB,EAClB,IAAuB;QAEvB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,GAAG,GAAG,SAAS,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC;QAC/C,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACvC,IAAI,QAAQ,EAAE,CAAC;YACb,QAAQ,CAAC,eAAe,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;YAC3E,QAAQ,CAAC,UAAU,IAAI,CAAC,CAAC;YACzB,QAAQ,CAAC,aAAa,GAAG,GAAG,CAAC;YAC7B,OAAO;QACT,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE;YACpB,WAAW;YACX,UAAU;YACV,YAAY,EAAE,CAAC;YACf,eAAe,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE;YAC9B,UAAU,EAAE,CAAC;YACb,SAAS,EAAE,GAAG;YACd,aAAa,EAAE,GAAG;SACnB,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,GAAG,CACP,WAAmB,EACnB,UAAkB;QAElB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC,CAAC;IAC9D,CAAC;IAED,KAAK,CAAC,IAAI;QACR,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC3C,CAAC;CACF"}

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

@@ -0,0 +1,10 @@
+/**
+ * Phase 3 — Shortcut Memory Store barrel.
+ *
+ * Per ADR 001, this module is intentionally separate from
+ * `src/agent-runtime/skills/`. Use the in-memory store in tests; the
+ * filesystem store ships as the bootstrap default.
+ */
+export type { ShortcutMemoryRecord, ShortcutMemoryStore, ShortcutOutcome, } from "./types.js";
+export { InMemoryShortcutMemoryStore } from "./in-memory-store.js";
+export { FsShortcutMemoryStore, type FsShortcutMemoryStoreOptions, } from "./fs-store.js";

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

@@ -0,0 +1,10 @@
+/**
+ * Phase 3 — Shortcut Memory Store barrel.
+ *
+ * Per ADR 001, this module is intentionally separate from
+ * `src/agent-runtime/skills/`. Use the in-memory store in tests; the
+ * filesystem store ships as the bootstrap default.
+ */
+export { InMemoryShortcutMemoryStore } from "./in-memory-store.js";
+export { FsShortcutMemoryStore, } from "./fs-store.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/agent-runtime/shortcuts/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAQH,OAAO,EAAE,2BAA2B,EAAE,MAAM,sBAAsB,CAAC;AACnE,OAAO,EACL,qBAAqB,GAEtB,MAAM,eAAe,CAAC"}

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

@@ -0,0 +1,69 @@
+/**
+ * Phase 3 — Shortcut Memory Store types.
+ *
+ * Per ADR 001 (Shortcut Memory Store: Bypass `SkillCacheStore`), the
+ * shortcut memory store is **separate** from the existing skill cache.
+ * It only records counter primitives (`recordSuccess`,
+ * `recordFailure`) keyed by `(taskPattern, shortcutId)` — no
+ * `appPackage`, no GUI action sequence, no embedding search.
+ *
+ * Recall ("which shortcut should I prefer for this task?") is
+ * deliberately deferred to a future ADR. The 4-shortcut catalogue is
+ * small enough that the orchestrator's static system prompt
+ * (`orchestrator-system-prompt.ts`) covers selection without a
+ * runtime matcher.
+ */
+import type { ShortcutErrorCode } from "../../shortcuts/types.js";
+/** Discriminated outcome — mirrors `ShortcutResult` but counter-shaped. */
+export type ShortcutOutcome = {
+    ok: true;
+} | {
+    ok: false;
+    code: ShortcutErrorCode;
+};
+/**
+ * One per (taskPattern, shortcutId) pair. The `taskPattern` is a
+ * caller-supplied digest of the task — typically the prompt's first
+ * 80 chars normalised; the store doesn't impose a schema beyond
+ * "string". Phase 3+ may add normalisation helpers when the matcher
+ * lands.
+ */
+export interface ShortcutMemoryRecord {
+    taskPattern: string;
+    shortcutId: string;
+    successCount: number;
+    failCountByCode: Record<string, number>;
+    /** Sum of all counter increments — convenience for sorting. */
+    totalCount: number;
+    /** Wallclock ms of the last increment. */
+    lastUpdatedAt: number;
+    /** Wallclock ms of the first increment. */
+    createdAt: number;
+}
+/**
+ * Write-only audit log surface. Phase 3 keeps `ShortcutMemoryStore`
+ * intentionally narrow so callers can swap in-memory ↔ filesystem
+ * implementations without touching production code. A future
+ * `MatcherEvolver` may consume these records read-only via
+ * `top(taskPattern)` once the catalogue grows.
+ */
+export interface ShortcutMemoryStore {
+    /** Increment the success counter for `(taskPattern, shortcutId)`. */
+    recordSuccess(taskPattern: string, shortcutId: string): Promise<void>;
+    /**
+     * Increment the failure counter, bucketed by error code. The error
+     * vocabulary is the closed-set `ShortcutErrorCode` so consumers can
+     * query "how often does `set_clipboard` hit `permission_denied`?".
+     */
+    recordFailure(taskPattern: string, shortcutId: string, code: ShortcutErrorCode): Promise<void>;
+    /**
+     * Read the record for `(taskPattern, shortcutId)`. Returns
+     * `undefined` when the pair has never been written.
+     */
+    get(taskPattern: string, shortcutId: string): Promise<ShortcutMemoryRecord | undefined>;
+    /**
+     * Enumerate every record. Used by the future matcher; Phase 3 callers
+     * mostly use it for diagnostics / tests.
+     */
+    list(): Promise<ShortcutMemoryRecord[]>;
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Phase 3 — Shortcut Memory Store types.
+ *
+ * Per ADR 001 (Shortcut Memory Store: Bypass `SkillCacheStore`), the
+ * shortcut memory store is **separate** from the existing skill cache.
+ * It only records counter primitives (`recordSuccess`,
+ * `recordFailure`) keyed by `(taskPattern, shortcutId)` — no
+ * `appPackage`, no GUI action sequence, no embedding search.
+ *
+ * Recall ("which shortcut should I prefer for this task?") is
+ * deliberately deferred to a future ADR. The 4-shortcut catalogue is
+ * small enough that the orchestrator's static system prompt
+ * (`orchestrator-system-prompt.ts`) covers selection without a
+ * runtime matcher.
+ */
+export {};
+//# sourceMappingURL=types.js.map

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

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

package/dist/app/agent-host.d.ts

@@ -22,6 +22,21 @@ import type { IAgentCore } from "../ports/agent-core.js";
 import type { AgentEventListener, AgentHost, SubmitTaskOptions, SubmittedTask } from "../ports/agent-host.js";
 import type { IDeviceIdentity } from "../ports/identity.js";
 import type { DeviceManager } from "./device-manager.js";
+import type { IMcpRuntime } from "../mcp-client/runtime.js";
+import { ResourceResolutionCache, ResourceResolverRegistry, type DiskPressureGuard, type ResourceLifecycleManager, type TaskContextAugmenter } from "../resources/index.js";
+export interface AgentHostResourceConfig {
+    /** Master switch — when false, the entire layer is short-circuited. */
+    enabled: boolean;
+    /** Per-resource hard cap on body bytes. */
+    maxBytes: number;
+    /** Per-resource fetch timeout. */
+    timeoutMs: number;
+    /** URL schemes the URL resolver will accept. */
+    allowedSchemes: readonly string[];
+    /** Refuse to fetch URLs that DNS-resolve to private/loopback IPs. */
+    denyPrivateIp: boolean;
+}
+export declare const DEFAULT_RESOURCE_CONFIG: AgentHostResourceConfig;
 export interface AgentHostOptions {
     agent: IAgentCore;
     devices: DeviceManager;
@@ -31,6 +46,50 @@ export interface AgentHostOptions {
     defaultMaxSteps?: number;
     /** Override notice throttle (ms). Tests pin this to 0 to disable. */
     noticeWarnThrottleMs?: number;
+    /**
+     * Optional resolver registry. When omitted, the layer is
+     * short-circuited and `prompt` flows through to `IAgentCore.run`
+     * unchanged (legacy passthrough).
+     */
+    resourceResolver?: ResourceResolverRegistry;
+    /**
+     * Process-wide resolution cache (SHA-256(url) → ResolvedAsset).
+     * Optional — when omitted, every resolve goes to the network.
+     */
+    resourceCache?: ResourceResolutionCache;
+    /**
+     * Augmenter that injects "Resources prepared: …" preamble into the
+     * task before it reaches the agent core. Defaults to the standard
+     * `ResourceContextAugmenter` when omitted.
+     */
+    resourceAugmenter?: TaskContextAugmenter;
+    /**
+     * MCP runtime resolver (callback so an ACP `device/select` reflects
+     * immediately). Required for resource resolution to work — without
+     * it, the layer logs a `cache_validation_miss`-equivalent and falls
+     * back to the original prompt.
+     */
+    mcpProvider?: () => IMcpRuntime;
+    /**
+     * Feature-flag config — see `DEFAULT_RESOURCE_CONFIG`. The host
+     * owns evaluation of `enabled` so callers can hot-swap behaviour
+     * without rebuilding the registry.
+     */
+    resourceConfig?: AgentHostResourceConfig;
+    /**
+     * Phase 1.5 lifecycle manager (L1 per-task ephemeral cleanup).
+     * Optional — when omitted the host runs without per-task GC,
+     * matching pre-1.5 behaviour. Bootstrap wires
+     * `FsResourceLifecycleManager` for production runs.
+     */
+    lifecycle?: ResourceLifecycleManager;
+    /**
+     * Phase 1.5 disk-pressure guard (L3). Threaded through to the
+     * `ResolverContext` so the URL resolver can consult it just before
+     * `fileWrite`. Optional — when omitted the resolver behaves
+     * exactly as it did pre-1.5.
+     */
+    diskPressure?: DiskPressureGuard;
 }
 export declare class AgentHostImpl implements AgentHost {
     readonly agent: IAgentCore;
@@ -41,12 +100,36 @@ export declare class AgentHostImpl implements AgentHost {
     private readonly noticeWarnThrottleMs;
     private readonly listeners;
     private readonly tasks;
+    private readonly resourceResolver?;
+    private readonly resourceCache?;
+    private readonly resourceAugmenter;
+    private readonly resourceConfig;
+    private readonly mcpProvider?;
+    private readonly lifecycle?;
+    private readonly diskPressure?;
     constructor(opts: AgentHostOptions);
     on(listener: AgentEventListener): () => void;
     submitTask(prompt: string, opts?: SubmitTaskOptions): SubmittedTask;
     cancel(taskId: string): boolean;
     cancelAll(): Promise<void>;
     private runOne;
+    /**
+     * Resolve every resource referenced by the task prompt and return
+     * the augmented prompt (or the original prompt if resolution is
+     * disabled / unavailable / yielded zero assets). Each resolution
+     * surface as a `task:tool` event with `name = "resolve_resource"`
+     * and `start | update | end` lifecycle so the UI can render a
+     * download progress card. Failures degrade silently to the original
+     * prompt — the agent must remain functional even when the network
+     * is flaky or the URL points at a 404.
+     */
+    private resolveAndAugment;
+    /**
+     * Resolve a single ref by dispatching to the first matching resolver
+     * registered on `this.resourceResolver`. Mirrors the registry's
+     * private `pick` logic without re-parsing the task.
+     */
+    private resolveOne;
     /**
      * Translate a structured runtime error into a `task:notice` for the
      * UI, throttling non-fatal warnings so a 5xx retry storm doesn't