@beeos-ai/device-agent 0.4.3 → 0.5.0

package/dist/resources/cache.js

@@ -0,0 +1,107 @@
+/**
+ * Resource Resolution Cache — keyed by SHA-256(url), value is a
+ * `ResolvedAsset`. Cache hits MUST validate the device-side file is
+ * still there before reuse.
+ *
+ * Why an in-memory cache and not skill memory?
+ *   - Skill memory is per-app GUI sequences (see ADR 001). Resolutions
+ *     are app-agnostic and have a much shorter natural lifetime
+ *     (TTL=7d) — different concern, different data shape.
+ *   - The cache lives for the AgentHost lifetime; we deliberately do
+ *     NOT persist it to disk for Phase 1. A future plan may add an FS
+ *     mirror under `~/.beeos/device-agent/resources-cache/` once the
+ *     access pattern stabilises.
+ *
+ * Cache validation:
+ *   When a hit is returned, the consumer is REQUIRED to call
+ *   `validateAlive(asset, mcp)` to confirm the device-side file still
+ *   exists (operators occasionally clear `/sdcard/Pictures/` between
+ *   tasks). On a missing file, the cache entry is invalidated and the
+ *   resolution is re-run.
+ */
+import { createHash } from "node:crypto";
+const DEFAULT_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+const DEFAULT_MAX_BYTES = 500 * 1024 * 1024;
+export class ResourceResolutionCache {
+    ttlMs;
+    maxBytes;
+    entries = new Map();
+    constructor(opts = {}) {
+        this.ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
+        this.maxBytes = opts.maxBytes ?? DEFAULT_MAX_BYTES;
+    }
+    /** Stable cache key — SHA-256 of the URL. */
+    static keyForUrl(url) {
+        return createHash("sha256").update(url).digest("hex");
+    }
+    get(key, now = Date.now()) {
+        const e = this.entries.get(key);
+        if (!e)
+            return undefined;
+        if (now - e.storedAt > this.ttlMs) {
+            this.entries.delete(key);
+            return undefined;
+        }
+        e.lastUsed = now;
+        return e.asset;
+    }
+    set(key, asset, now = Date.now()) {
+        this.entries.set(key, { asset, storedAt: now, lastUsed: now });
+        this.evictIfNeeded();
+    }
+    invalidate(key) {
+        this.entries.delete(key);
+    }
+    size() {
+        return this.entries.size;
+    }
+    totalBytes() {
+        let sum = 0;
+        for (const e of this.entries.values())
+            sum += e.asset.sizeBytes;
+        return sum;
+    }
+    /** Test helper — visible-for-spec, not for production callers. */
+    __debug() {
+        return { size: this.size(), totalBytes: this.totalBytes() };
+    }
+    /**
+     * Verify the device-side file referenced by a cached entry is still
+     * present. Returns `true` iff `ls <remotePath>` succeeds with non-
+     * empty output (or an explicit success exit code).
+     *
+     * MUST be called by every consumer that hits the cache before
+     * returning the asset to upstream code.
+     */
+    static async validateAlive(asset, mcp) {
+        if (typeof mcp.executeCommand !== "function") {
+            // No `executeCommand` ⇒ we cannot verify ⇒ pessimistic: treat
+            // as missing so we re-resolve. This keeps stale cache entries
+            // from sneaking into the in-proc legacy bridge.
+            return false;
+        }
+        try {
+            const r = await mcp.executeCommand(`ls -1 ${shellQuote(asset.remotePath)} 2>/dev/null`);
+            const exit = r.exitCode ?? 0;
+            const stdout = (r.stdout ?? "").trim();
+            return exit === 0 && stdout.length > 0;
+        }
+        catch {
+            return false;
+        }
+    }
+    evictIfNeeded() {
+        if (this.totalBytes() <= this.maxBytes)
+            return;
+        // LRU by lastUsed.
+        const sorted = [...this.entries.entries()].sort((a, b) => a[1].lastUsed - b[1].lastUsed);
+        while (this.totalBytes() > this.maxBytes && sorted.length > 0) {
+            const [key] = sorted.shift();
+            this.entries.delete(key);
+        }
+    }
+}
+function shellQuote(s) {
+    return `'${s.replace(/'/g, "'\\''")}'`;
+}
+//# sourceMappingURL=cache.js.map

package/dist/resources/cache.js.map

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

package/dist/resources/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * resources/ — Resource Resolution Layer barrel.
+ *
+ * See `types.ts` for the protocol overview.
+ */
+export type { ResourceRef, ResolvedAsset, ResolverContext, ResolveProgressEvent, ResolverLogger, ResourceResolver, ResourceParser, TaskContextAugmenter, ResolveOutcomeLabel, } from "./types.js";
+export { UrlParser, BeeosFileParser, defaultParsers } from "./parsers.js";
+export { ResourceContextAugmenter } from "./augmenter.js";
+export { ResourceResolverRegistry, type ResolveAllResult, type ResolverRegistryOptions, } from "./registry.js";
+export { UrlResolver, ResolverError, isPrivateOrLoopback, type UrlResolverOptions, } from "./resolvers/url-resolver.js";
+export { BeeosFileResolver, type BeeosFileResolverOptions, } from "./resolvers/beeos-file-resolver.js";
+export { ResourceResolutionCache, type ResourceCacheOptions, } from "./cache.js";
+export { ALLOWED_MIMES, ALLOWED_MIME_PREFIXES, MIME_TO_EXT, mapMimeToExt, } from "./resolvers/mime-table.js";
+export { AGENT_HOST_ERROR_LABELS, type ResolverErrorCode, } from "./resolvers/errors.js";
+export type { DiskPressureGuard, DiskPressureCheckArgs, } from "./types.js";
+export type { LifecycleMode, ResourceLifecycleConfig, ResourceLifecycleManager, ResourceLifecycleSweeper, LifecycleWiring, } from "./lifecycle/index.js";
+export { FsResourceLifecycleManager, FsResourceLifecycleSweeper, FsDiskPressureGuard, parseDfFreeMb, type DiskPressureGuardOptions, } from "./lifecycle/index.js";

package/dist/resources/index.js

@@ -0,0 +1,15 @@
+/**
+ * resources/ — Resource Resolution Layer barrel.
+ *
+ * See `types.ts` for the protocol overview.
+ */
+export { UrlParser, BeeosFileParser, defaultParsers } from "./parsers.js";
+export { ResourceContextAugmenter } from "./augmenter.js";
+export { ResourceResolverRegistry, } from "./registry.js";
+export { UrlResolver, ResolverError, isPrivateOrLoopback, } from "./resolvers/url-resolver.js";
+export { BeeosFileResolver, } from "./resolvers/beeos-file-resolver.js";
+export { ResourceResolutionCache, } from "./cache.js";
+export { ALLOWED_MIMES, ALLOWED_MIME_PREFIXES, MIME_TO_EXT, mapMimeToExt, } from "./resolvers/mime-table.js";
+export { AGENT_HOST_ERROR_LABELS, } from "./resolvers/errors.js";
+export { FsResourceLifecycleManager, FsResourceLifecycleSweeper, FsDiskPressureGuard, parseDfFreeMb, } from "./lifecycle/index.js";
+//# sourceMappingURL=index.js.map

package/dist/resources/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/resources/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAcH,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC1E,OAAO,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,EACL,wBAAwB,GAGzB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,WAAW,EACX,aAAa,EACb,mBAAmB,GAEpB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,iBAAiB,GAElB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EACL,uBAAuB,GAExB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,aAAa,EACb,qBAAqB,EACrB,WAAW,EACX,YAAY,GACb,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,uBAAuB,GAExB,MAAM,uBAAuB,CAAC;AAY/B,OAAO,EACL,0BAA0B,EAC1B,0BAA0B,EAC1B,mBAAmB,EACnB,aAAa,GAEd,MAAM,sBAAsB,CAAC"}

package/dist/resources/lifecycle/disk-pressure.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Resource Lifecycle — L3 (disk-pressure adaptive sweep).
+ *
+ * Runs immediately before each `mcp.fileWrite` in the resolver. We
+ * read free space on the sandbox volume via `df`; when free MB drops
+ * below `diskMinFreeMb` we trigger a force-sweep (the same path the
+ * L2 timer uses) so the daemon doesn't fill the device's external
+ * storage on a long burst of downloads. If after sweeping free space
+ * is *still* below `diskCriticalFreeMb`, we abort the resolve with
+ * a structured `disk_pressure` error — that's the resolver's signal
+ * to fail fast rather than write a partial file the picker will
+ * never see.
+ *
+ * The two thresholds form a hysteresis band:
+ *   - `diskMinFreeMb`     — soft, triggers eviction.
+ *   - `diskCriticalFreeMb` — hard, triggers rejection.
+ * Operators are responsible for keeping `critical < min`; if the two
+ * cross over, L3 still fail-softs (an over-strict critical just means
+ * a few extra rejections under pressure, never silent corruption).
+ *
+ * Why we parse `df` output ourselves:
+ *   Android's BusyBox `df` does not have a `--output=avail` switch
+ *   the way GNU coreutils does. The `-k` flag gives a stable
+ *   `Filesystem 1K-blocks Used Available …` header on every BusyBox
+ *   build I've seen since Android 7. We strip the header and read
+ *   the column at index 3 (zero-indexed) of the **last** non-empty
+ *   line. Unknown shapes return `null` and `assertCapacity` fails
+ *   soft (warn + allow write) rather than rejecting downloads on a
+ *   parse hiccup.
+ */
+import type { IMcpRuntime } from "../../mcp-client/runtime.js";
+import type { DiskPressureGuard, DiskPressureCheckArgs, ResolverLogger } from "../types.js";
+import type { ResourceLifecycleSweeper } from "./types.js";
+export interface DiskPressureGuardOptions {
+    /** Soft threshold — below this we force a sweep. */
+    readonly minFreeMb: number;
+    /** Hard threshold — below this AFTER a sweep we reject. */
+    readonly criticalFreeMb: number;
+    /** Sweeper used for the force-sweep step. */
+    readonly sweeper: ResourceLifecycleSweeper;
+    /**
+     * Optional: skip the live `df` shell call when known to be safe.
+     * Useful for fleet operators that have provisioned a dedicated
+     * /sdcard volume and want to disable the L3 layer.
+     */
+    readonly enabled?: boolean;
+}
+export declare class FsDiskPressureGuard implements DiskPressureGuard {
+    private readonly opts;
+    constructor(opts: DiskPressureGuardOptions);
+    assertCapacity(args: DiskPressureCheckArgs): Promise<void>;
+    /**
+     * Returns free MB on the volume containing `sandboxDir`, or `null`
+     * if `df` output couldn't be parsed. Visible-for-test.
+     */
+    dfFreeMb(mcp: IMcpRuntime, sandboxDir: string, log: ResolverLogger): Promise<number | null>;
+}
+/**
+ * Parse a `df -k` output and return free MB on the relevant volume,
+ * or `null` if the output doesn't match any known shape.
+ *
+ * Android BusyBox `df -k /sdcard` emits something like:
+ *
+ *   Filesystem        1K-blocks      Used Available Use% Mounted on
+ *   /dev/block/dm-25   116228032  74283456  41789120  64% /storage/emulated
+ *
+ * The "Available" column is the 4th whitespace-separated field. We
+ * walk lines from the bottom up and return the first row with four
+ * numeric-looking fields after the device name. Anything else
+ * returns `null` and the L3 guard fails soft.
+ *
+ * Visible-for-test (exported as a pure function so unit tests don't
+ * need an MCP stub).
+ */
+export declare function parseDfFreeMb(out: string): number | null;

package/dist/resources/lifecycle/disk-pressure.js

@@ -0,0 +1,148 @@
+/**
+ * Resource Lifecycle — L3 (disk-pressure adaptive sweep).
+ *
+ * Runs immediately before each `mcp.fileWrite` in the resolver. We
+ * read free space on the sandbox volume via `df`; when free MB drops
+ * below `diskMinFreeMb` we trigger a force-sweep (the same path the
+ * L2 timer uses) so the daemon doesn't fill the device's external
+ * storage on a long burst of downloads. If after sweeping free space
+ * is *still* below `diskCriticalFreeMb`, we abort the resolve with
+ * a structured `disk_pressure` error — that's the resolver's signal
+ * to fail fast rather than write a partial file the picker will
+ * never see.
+ *
+ * The two thresholds form a hysteresis band:
+ *   - `diskMinFreeMb`     — soft, triggers eviction.
+ *   - `diskCriticalFreeMb` — hard, triggers rejection.
+ * Operators are responsible for keeping `critical < min`; if the two
+ * cross over, L3 still fail-softs (an over-strict critical just means
+ * a few extra rejections under pressure, never silent corruption).
+ *
+ * Why we parse `df` output ourselves:
+ *   Android's BusyBox `df` does not have a `--output=avail` switch
+ *   the way GNU coreutils does. The `-k` flag gives a stable
+ *   `Filesystem 1K-blocks Used Available …` header on every BusyBox
+ *   build I've seen since Android 7. We strip the header and read
+ *   the column at index 3 (zero-indexed) of the **last** non-empty
+ *   line. Unknown shapes return `null` and `assertCapacity` fails
+ *   soft (warn + allow write) rather than rejecting downloads on a
+ *   parse hiccup.
+ */
+import { ResolverError } from "../resolvers/url-resolver.js";
+export class FsDiskPressureGuard {
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    async assertCapacity(args) {
+        if (this.opts.enabled === false)
+            return;
+        if (typeof args.mcp.executeCommand !== "function")
+            return;
+        const initialFreeMb = await this.dfFreeMb(args.mcp, args.sandboxDir, args.log);
+        if (initialFreeMb === null) {
+            // df failed → log + skip (we'd rather over-write than reject
+            // every download because of a parse hiccup).
+            args.log.warn({ sandboxDir: args.sandboxDir }, "disk-pressure: df parse failed; allowing write");
+            return;
+        }
+        const incomingMb = Math.ceil(args.incomingBytes / (1024 * 1024));
+        const projectedFreeMb = initialFreeMb - incomingMb;
+        if (projectedFreeMb >= this.opts.minFreeMb) {
+            // Plenty of headroom.
+            return;
+        }
+        args.log.info({
+            initialFreeMb,
+            incomingMb,
+            projectedFreeMb,
+            minFreeMb: this.opts.minFreeMb,
+        }, "disk-pressure: low headroom, triggering force-sweep");
+        let deleted = 0;
+        try {
+            deleted = await this.opts.sweeper.sweepNow();
+        }
+        catch (e) {
+            args.log.warn({ err: errString(e) }, "disk-pressure: force-sweep threw (continuing)");
+        }
+        const postFreeMb = await this.dfFreeMb(args.mcp, args.sandboxDir, args.log);
+        if (postFreeMb === null) {
+            args.log.warn({ deleted }, "disk-pressure: post-sweep df parse failed; allowing write");
+            return;
+        }
+        const postProjectedMb = postFreeMb - incomingMb;
+        if (postProjectedMb >= this.opts.criticalFreeMb) {
+            args.log.info({ initialFreeMb, postFreeMb, deleted, postProjectedMb }, "disk-pressure: sweep recovered enough space");
+            return;
+        }
+        throw new ResolverError("disk_pressure", `device sandbox is critically low (${postFreeMb}MB free, threshold ${this.opts.criticalFreeMb}MB)`, {
+            initialFreeMb,
+            postFreeMb,
+            incomingMb,
+            sweptFiles: deleted,
+            sandboxDir: args.sandboxDir,
+        });
+    }
+    /**
+     * Returns free MB on the volume containing `sandboxDir`, or `null`
+     * if `df` output couldn't be parsed. Visible-for-test.
+     */
+    async dfFreeMb(mcp, sandboxDir, log) {
+        if (typeof mcp.executeCommand !== "function")
+            return null;
+        let stdout = "";
+        try {
+            const r = await mcp.executeCommand(`df -k ${shellQuote(sandboxDir)} 2>/dev/null`);
+            stdout = (r.stdout ?? "").trim();
+        }
+        catch (e) {
+            log.warn({ err: errString(e), sandboxDir }, "disk-pressure: df threw");
+            return null;
+        }
+        return parseDfFreeMb(stdout);
+    }
+}
+/**
+ * Parse a `df -k` output and return free MB on the relevant volume,
+ * or `null` if the output doesn't match any known shape.
+ *
+ * Android BusyBox `df -k /sdcard` emits something like:
+ *
+ *   Filesystem        1K-blocks      Used Available Use% Mounted on
+ *   /dev/block/dm-25   116228032  74283456  41789120  64% /storage/emulated
+ *
+ * The "Available" column is the 4th whitespace-separated field. We
+ * walk lines from the bottom up and return the first row with four
+ * numeric-looking fields after the device name. Anything else
+ * returns `null` and the L3 guard fails soft.
+ *
+ * Visible-for-test (exported as a pure function so unit tests don't
+ * need an MCP stub).
+ */
+export function parseDfFreeMb(out) {
+    if (!out)
+        return null;
+    const lines = out.split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+    if (lines.length < 2)
+        return null;
+    // Header sanity — we expect "Filesystem" to be a token on the first line.
+    if (!/Filesystem/i.test(lines[0]))
+        return null;
+    for (let i = lines.length - 1; i >= 1; i--) {
+        const cols = lines[i].split(/\s+/);
+        if (cols.length >= 4 && /^\d+$/.test(cols[3])) {
+            const availKb = parseInt(cols[3], 10);
+            return Math.floor(availKb / 1024);
+        }
+    }
+    return null;
+}
+function shellQuote(s) {
+    return `'${s.replace(/'/g, "'\\''")}'`;
+}
+function errString(e) {
+    if (e instanceof Error)
+        return e.message;
+    return String(e);
+}
+//# sourceMappingURL=disk-pressure.js.map

package/dist/resources/lifecycle/disk-pressure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"disk-pressure.js","sourceRoot":"","sources":["../../../src/resources/lifecycle/disk-pressure.ts"],"names":[],"mappings":"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"}

package/dist/resources/lifecycle/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * resources/lifecycle/ — barrel for the three-layer GC.
+ */
+export type { LifecycleMode, ResourceLifecycleConfig, ResourceLifecycleManager, ResourceLifecycleSweeper, LifecycleWiring, } from "./types.js";
+export { FsResourceLifecycleManager } from "./manager.js";
+export { FsResourceLifecycleSweeper } from "./sweeper.js";
+export { FsDiskPressureGuard, parseDfFreeMb, type DiskPressureGuardOptions, } from "./disk-pressure.js";

package/dist/resources/lifecycle/index.js

@@ -0,0 +1,7 @@
+/**
+ * resources/lifecycle/ — barrel for the three-layer GC.
+ */
+export { FsResourceLifecycleManager } from "./manager.js";
+export { FsResourceLifecycleSweeper } from "./sweeper.js";
+export { FsDiskPressureGuard, parseDfFreeMb, } from "./disk-pressure.js";
+//# sourceMappingURL=index.js.map

package/dist/resources/lifecycle/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/resources/lifecycle/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AASH,OAAO,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,EACL,mBAAmB,EACnB,aAAa,GAEd,MAAM,oBAAoB,CAAC"}

package/dist/resources/lifecycle/manager.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Resource Lifecycle — L1 (per-task ephemeral) implementation.
+ *
+ * Tracks every fresh asset a task pushed to the device and, when the
+ * task ends, schedules a delayed `rm` + cache invalidate + MediaScanner
+ * rebroadcast. The delay protects against asynchronous picker uploads
+ * that read the original file *after* the task completes (WeChat
+ * Moments, for example, queues a background upload and reads the file
+ * a second time when the user has slow connectivity).
+ *
+ * Cache hits are intentionally NOT tracked here. They were created by
+ * a prior task that owns their lifecycle; deleting them eagerly would
+ * starve a `cache hit + revalidate` workflow that the resolution layer
+ * already supports out of the box. They get reclaimed by L2 once
+ * `sweepAgeHours` elapses.
+ *
+ * The implementation is platform-aware: when `device.getInfo().os` is
+ * not `"android"`, every method short-circuits to a no-op so the desk-
+ * top adapter can boot without spurious telemetry.
+ */
+import type { ResolvedAsset } from "../types.js";
+import type { LifecycleWiring, ResourceLifecycleManager } from "./types.js";
+export declare class FsResourceLifecycleManager implements ResourceLifecycleManager {
+    private readonly tasks;
+    private readonly wiring;
+    /**
+     * Cached platform string from `device.getInfo()`. We resolve lazily
+     * so unit tests don't have to await `getInfo()` at construction
+     * time. `null` = not yet probed; `""` = probed and unknown.
+     */
+    private platform;
+    constructor(wiring: LifecycleWiring);
+    trackFresh(taskId: string, asset: ResolvedAsset): void;
+    onTaskEnd(taskId: string): Promise<void>;
+    flushPending(): Promise<void>;
+    private detectPlatform;
+    private deletePaths;
+}

package/dist/resources/lifecycle/manager.js

@@ -0,0 +1,205 @@
+/**
+ * Resource Lifecycle — L1 (per-task ephemeral) implementation.
+ *
+ * Tracks every fresh asset a task pushed to the device and, when the
+ * task ends, schedules a delayed `rm` + cache invalidate + MediaScanner
+ * rebroadcast. The delay protects against asynchronous picker uploads
+ * that read the original file *after* the task completes (WeChat
+ * Moments, for example, queues a background upload and reads the file
+ * a second time when the user has slow connectivity).
+ *
+ * Cache hits are intentionally NOT tracked here. They were created by
+ * a prior task that owns their lifecycle; deleting them eagerly would
+ * starve a `cache hit + revalidate` workflow that the resolution layer
+ * already supports out of the box. They get reclaimed by L2 once
+ * `sweepAgeHours` elapses.
+ *
+ * The implementation is platform-aware: when `device.getInfo().os` is
+ * not `"android"`, every method short-circuits to a no-op so the desk-
+ * top adapter can boot without spurious telemetry.
+ */
+import { ResourceResolutionCache } from "../cache.js";
+export class FsResourceLifecycleManager {
+    tasks = new Map();
+    wiring;
+    /**
+     * Cached platform string from `device.getInfo()`. We resolve lazily
+     * so unit tests don't have to await `getInfo()` at construction
+     * time. `null` = not yet probed; `""` = probed and unknown.
+     */
+    platform = null;
+    constructor(wiring) {
+        this.wiring = wiring;
+    }
+    trackFresh(taskId, asset) {
+        if (this.wiring.config.mode === "off")
+            return;
+        let entry = this.tasks.get(taskId);
+        if (!entry) {
+            entry = { paths: new Set(), cacheKeys: new Set(), ended: false };
+            this.tasks.set(taskId, entry);
+        }
+        // AgentHost.runOne always calls trackFresh BEFORE onTaskEnd
+        // (resolution happens inside `resolveAndAugment`, the cleanup is
+        // wired in `runOne`'s `finally`). We rely on that invariant — any
+        // late arrival is a programmer error and fails loud naturally.
+        entry.paths.add(asset.remotePath);
+        if (asset.sourceUrl) {
+            entry.cacheKeys.add(ResourceResolutionCache.keyForUrl(asset.sourceUrl));
+        }
+    }
+    async onTaskEnd(taskId) {
+        const entry = this.tasks.get(taskId);
+        if (!entry)
+            return;
+        if (entry.ended) {
+            // Idempotency: a second onTaskEnd just observes the same
+            // memoised `fire()` promise. `fire` is unset for the
+            // persistent / no-op branches; in those cases there's nothing
+            // to wait for.
+            if (entry.fire)
+                await entry.fire();
+            return;
+        }
+        entry.ended = true;
+        const mode = this.wiring.config.mode;
+        if (mode !== "ephemeral") {
+            // persistent: keep the file, just drop our tracking; L2 will
+            // reap on age. (mode === "off" was already handled in
+            // trackFresh — entry.paths is empty.)
+            this.tasks.delete(taskId);
+            return;
+        }
+        if (entry.paths.size === 0) {
+            this.tasks.delete(taskId);
+            return;
+        }
+        const paths = Array.from(entry.paths);
+        const cacheKeys = Array.from(entry.cacheKeys);
+        const delaySec = Math.max(0, this.wiring.config.perTaskDeleteDelaySec);
+        // Single fire-once trigger shared by the timer, the idempotent
+        // second `onTaskEnd`, and the shutdown `flushPending` hijack.
+        // The first call kicks off `deletePaths(...)`; every subsequent
+        // call awaits the same Promise.
+        let firePromise = null;
+        const fire = () => {
+            if (!firePromise) {
+                firePromise = this.deletePaths(paths, cacheKeys).finally(() => {
+                    this.tasks.delete(taskId);
+                });
+            }
+            return firePromise;
+        };
+        entry.fire = fire;
+        if (delaySec === 0) {
+            // Inline delete (tests + emergency shutdown).
+            await fire();
+            return;
+        }
+        // Schedule the delete; let the caller (`agent-host.runOne`)
+        // return as soon as cleanup is *scheduled*. The SIGTERM handler
+        // will call `flushPending` to fire the timer early if we shut
+        // down before the delay elapses.
+        entry.timer = setTimeout(() => {
+            void fire();
+        }, delaySec * 1000);
+        if (typeof entry.timer.unref === "function") {
+            entry.timer.unref();
+        }
+    }
+    async flushPending() {
+        const pending = [];
+        for (const [, entry] of this.tasks) {
+            if (entry.timer) {
+                clearTimeout(entry.timer);
+                entry.timer = undefined;
+            }
+            if (entry.fire)
+                pending.push(entry.fire());
+        }
+        this.tasks.clear();
+        await Promise.allSettled(pending);
+    }
+    // ── Internals ───────────────────────────────────────────────────────────
+    async detectPlatform() {
+        if (this.platform !== null)
+            return this.platform;
+        try {
+            const info = await this.wiring.device.getInfo();
+            this.platform = (info.os ?? info.type ?? "").toString().toLowerCase();
+        }
+        catch {
+            this.platform = "";
+        }
+        return this.platform;
+    }
+    async deletePaths(paths, cacheKeys) {
+        if (paths.length === 0)
+            return;
+        const platform = await this.detectPlatform();
+        if (platform !== "android") {
+            // Non-Android (desktop, lab) — nothing to do on disk; still
+            // invalidate cache so an eventual `validateAlive` re-check
+            // doesn't return a stale entry.
+            for (const k of cacheKeys)
+                this.wiring.cache?.invalidate(k);
+            return;
+        }
+        let mcp;
+        try {
+            mcp = this.wiring.mcpProvider();
+        }
+        catch (e) {
+            this.wiring.log.warn({ paths, err: errString(e) }, "lifecycle: mcpProvider() threw; skipping rm (cache still invalidated)");
+            for (const k of cacheKeys)
+                this.wiring.cache?.invalidate(k);
+            return;
+        }
+        if (typeof mcp.executeCommand !== "function") {
+            // No way to talk to the device shell. Best-effort: keep cache
+            // honest so the next resolve sees a clean slate.
+            for (const k of cacheKeys)
+                this.wiring.cache?.invalidate(k);
+            return;
+        }
+        // 1. rm -f every tracked file. We batch so a single `executeCommand`
+        //    round-trip handles everything; on a multi-asset task that's
+        //    one shell hop instead of N. The `||:` swallows partial
+        //    failures (e.g. file already gone via L2) without poisoning
+        //    the rest of the batch.
+        const rmCmd = paths.map((p) => `rm -f ${shellQuote(p)}`).join(" ; ") + " ; :";
+        try {
+            await mcp.executeCommand(rmCmd);
+        }
+        catch (e) {
+            this.wiring.log.warn({ paths, err: errString(e) }, "lifecycle: rm batch failed (non-fatal)");
+        }
+        // 2. Trigger MediaScanner so the gallery thumbnail disappears
+        //    promptly. Per-file broadcast — the API only accepts a single
+        //    `-d` URI per `am broadcast` invocation.
+        for (const p of paths) {
+            try {
+                await mcp.executeCommand(`am broadcast -a android.intent.action.MEDIA_SCANNER_SCAN_FILE -d file://${p}`);
+            }
+            catch (e) {
+                this.wiring.log.debug({ path: p, err: errString(e) }, "lifecycle: media-scan after rm failed (non-fatal)");
+            }
+        }
+        // 3. Drop cache entries so the next `submitTask` for the same
+        //    URL re-resolves. `validateAlive` would catch this anyway via
+        //    a follow-up `ls`, but invalidating now saves one shell
+        //    round-trip on the happy path.
+        for (const k of cacheKeys)
+            this.wiring.cache?.invalidate(k);
+        this.wiring.log.info({ count: paths.length, paths }, "lifecycle: per-task cleanup complete");
+    }
+}
+function shellQuote(s) {
+    return `'${s.replace(/'/g, "'\\''")}'`;
+}
+function errString(e) {
+    if (e instanceof Error)
+        return e.message;
+    return String(e);
+}
+//# sourceMappingURL=manager.js.map