@elizaos/agent 2.0.0-beta.2 → 2.0.3-beta.3

package/api/index.d.ts

@@ -0,0 +1,44 @@
+export { type AppManagerLike, type AppsRouteContext, type FavoriteAppsStore, handleAppsRoutes, } from "@elizaos/plugin-app-manager";
+export type { WalletAddressesSnapshot, WalletRouteContext, WalletRouteDependencies, WalletRpcReadinessSnapshot, } from "@elizaos/plugin-wallet";
+export declare const handleWalletRoutes: typeof import("@elizaos/plugin-wallet").handleWalletRoutes;
+export * from "./accounts-routes.js";
+export * from "./agent-admin-routes.js";
+export * from "./agent-lifecycle-routes.js";
+export * from "./agent-model.js";
+export * from "./agent-transfer-routes.js";
+export * from "./approval-routes.js";
+export * from "./auth-routes.js";
+export * from "./bug-report-routes.js";
+export * from "./character-routes.js";
+export * from "./compat-utils.js";
+export * from "./connector-health.js";
+export * from "./credit-detection.js";
+export * from "./database.js";
+export * from "./diagnostics-routes.js";
+export { type DispatchRouteArgs, dispatchRoute, } from "./dispatch-route.js";
+export * from "./documents-service-loader.js";
+export * from "./early-logs.js";
+export * from "./memory-bounds.js";
+export * from "./memory-routes.js";
+export * from "./models-routes.js";
+export * from "./parse-action-block.js";
+export * from "./permission-request-prompt.js";
+export * from "./permissions-routes.js";
+export * from "./plugin-validation.js";
+export * from "./provider-switch-config.js";
+export * from "./rate-limiter.js";
+export * from "./registry-routes.js";
+export * from "./registry-service.js";
+export { matchPluginRoutePath, tryHandleRuntimePluginRoute, } from "./runtime-plugin-routes.js";
+export * from "./subscription-routes.js";
+export * from "./terminal-run-limits.js";
+export * from "./training-backend-check.js";
+export * from "./training-service-like.js";
+export * from "./tx-service.js";
+export * from "./wallet.js";
+export * from "./wallet-evm-balance.js";
+export * from "./wallet-rpc.js";
+export * from "./wallet-trading-profile.js";
+export * from "./workbench-vfs-routes.js";
+export * from "./zip-utils.js";
+//# sourceMappingURL=index.d.ts.map

package/api/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,gBAAgB,GACjB,MAAM,6BAA6B,CAAC;AAMrC,YAAY,EACV,uBAAuB,EACvB,kBAAkB,EAClB,uBAAuB,EACvB,0BAA0B,GAC3B,MAAM,wBAAwB,CAAC;AAChC,eAAO,MAAM,kBAAkB,EAAE,cAAc,wBAAwB,EAAE,kBAItE,CAAC;AACJ,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC;AACxC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,kBAAkB,CAAC;AACjC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,yBAAyB,CAAC;AACxC,OAAO,EACL,KAAK,iBAAiB,EACtB,aAAa,GACd,MAAM,qBAAqB,CAAC;AAC7B,cAAc,+BAA+B,CAAC;AAC9C,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AACxC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC;AACvC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AAKtC,OAAO,EACL,oBAAoB,EACpB,2BAA2B,GAC5B,MAAM,4BAA4B,CAAC;AACpC,cAAc,0BAA0B,CAAC;AACzC,cAAc,0BAA0B,CAAC;AACzC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,yBAAyB,CAAC;AACxC,cAAc,iBAAiB,CAAC;AAChC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,gBAAgB,CAAC"}

package/api/index.js

@@ -0,0 +1,53 @@
+// apps routes extracted to @elizaos/plugin-app-manager.
+// Re-export the public surface so downstream callers that imported from
+// `@elizaos/agent` keep working during the transition. New callers
+// should import from `@elizaos/plugin-app-manager` directly.
+export { handleAppsRoutes, } from "@elizaos/plugin-app-manager";
+export const handleWalletRoutes = async (context) => {
+    const walletApi = await import(/* @vite-ignore */ "@elizaos/plugin-wallet");
+    return walletApi.handleWalletRoutes(context);
+};
+export * from "./accounts-routes.js";
+export * from "./agent-admin-routes.js";
+export * from "./agent-lifecycle-routes.js";
+export * from "./agent-model.js";
+export * from "./agent-transfer-routes.js";
+export * from "./approval-routes.js";
+export * from "./auth-routes.js";
+export * from "./bug-report-routes.js";
+export * from "./character-routes.js";
+export * from "./compat-utils.js";
+export * from "./connector-health.js";
+export * from "./credit-detection.js";
+export * from "./database.js";
+export * from "./diagnostics-routes.js";
+export { dispatchRoute, } from "./dispatch-route.js";
+export * from "./documents-service-loader.js";
+export * from "./early-logs.js";
+export * from "./memory-bounds.js";
+export * from "./memory-routes.js";
+export * from "./models-routes.js";
+export * from "./parse-action-block.js";
+export * from "./permission-request-prompt.js";
+export * from "./permissions-routes.js";
+export * from "./plugin-validation.js";
+export * from "./provider-switch-config.js";
+export * from "./rate-limiter.js";
+export * from "./registry-routes.js";
+export * from "./registry-service.js";
+// `runtime-plugin-routes.ts` exports `matchPluginRoutePath` (used by plugin
+// authors and their tests, e.g. plugins/app-vincent/src/vincent-plugin-dispatch.test.ts)
+// and the request-handling helper `tryHandleRuntimePluginRoute` (used by
+// agent runtime wiring). Both are part of the public agent surface.
+export { matchPluginRoutePath, tryHandleRuntimePluginRoute, } from "./runtime-plugin-routes.js";
+export * from "./subscription-routes.js";
+export * from "./terminal-run-limits.js";
+export * from "./training-backend-check.js";
+export * from "./training-service-like.js";
+export * from "./tx-service.js";
+export * from "./wallet.js";
+export * from "./wallet-evm-balance.js";
+export * from "./wallet-rpc.js";
+export * from "./wallet-trading-profile.js";
+export * from "./workbench-vfs-routes.js";
+export * from "./zip-utils.js";

package/api/interactions-routes.d.ts

@@ -0,0 +1,33 @@
+/**
+ * POST /api/interactions/shortcut — report a user-fired UI/keyboard shortcut so
+ * the agent observes it as a first-class interaction (#8792).
+ *
+ * The view-switch half of this contract lives in `views-routes.ts`
+ * (`POST /api/views/:id/navigate` → `VIEW_SWITCHED`). This is the keyboard /
+ * command-palette half: the client reports a stable `shortcutId` and the route
+ * emits `EventType.SHORTCUT_FIRED`, which the proactive-interaction decider
+ * consumes (governed by debounce / cooldown / daily-cap / model-judge-silent).
+ *
+ * Emission is fire-and-forget: a dropped event must never break the shortcut the
+ * user actually pressed. This route is auth+proxy thin — it records nothing and
+ * computes nothing beyond input validation.
+ */
+import type http from "node:http";
+import { type AgentRuntime } from "@elizaos/core";
+export interface InteractionsRouteContext {
+    req: http.IncomingMessage;
+    res: http.ServerResponse;
+    method: string;
+    pathname: string;
+    json: (res: http.ServerResponse, data: unknown, status?: number) => void;
+    error: (res: http.ServerResponse, message: string, status?: number) => void;
+    runtime: AgentRuntime | null | undefined;
+}
+export interface ShortcutInteractionRequest {
+    shortcutId: string;
+    context?: string;
+}
+/** Parse + validate the shortcut report body; null on anything malformed. */
+export declare function parseShortcutBody(raw: string): ShortcutInteractionRequest | null;
+export declare function handleInteractionsRoutes(ctx: InteractionsRouteContext): Promise<boolean>;
+//# sourceMappingURL=interactions-routes.d.ts.map

package/api/interactions-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interactions-routes.d.ts","sourceRoot":"","sources":["../../src/api/interactions-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EACL,KAAK,YAAY,EAGlB,MAAM,eAAe,CAAC;AAQvB,MAAM,WAAW,wBAAwB;IACvC,GAAG,EAAE,IAAI,CAAC,eAAe,CAAC;IAC1B,GAAG,EAAE,IAAI,CAAC,cAAc,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,CAAC,GAAG,EAAE,IAAI,CAAC,cAAc,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACzE,KAAK,EAAE,CAAC,GAAG,EAAE,IAAI,CAAC,cAAc,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5E,OAAO,EAAE,YAAY,GAAG,IAAI,GAAG,SAAS,CAAC;CAC1C;AAED,MAAM,WAAW,0BAA0B;IACzC,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,6EAA6E;AAC7E,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,GACV,0BAA0B,GAAG,IAAI,CAoBnC;AAED,wBAAsB,wBAAwB,CAC5C,GAAG,EAAE,wBAAwB,GAC5B,OAAO,CAAC,OAAO,CAAC,CAuClB"}

package/api/interactions-routes.js

@@ -0,0 +1,63 @@
+import { EventType, readRequestBodyBuffer, } from "@elizaos/core";
+const MAX_BODY_BYTES = 4 * 1024;
+/** Stable shortcut id: kebab-case, bounded length (e.g. "open-command-palette"). */
+const SHORTCUT_ID_PATTERN = /^[a-z][a-z0-9-]{1,48}$/;
+const MAX_CONTEXT_CHARS = 120;
+/** Parse + validate the shortcut report body; null on anything malformed. */
+export function parseShortcutBody(raw) {
+    if (!raw.trim())
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return null;
+    }
+    const body = parsed;
+    const shortcutId = typeof body.shortcutId === "string" ? body.shortcutId.trim() : "";
+    if (!SHORTCUT_ID_PATTERN.test(shortcutId))
+        return null;
+    const context = typeof body.context === "string" && body.context.trim()
+        ? body.context.trim().slice(0, MAX_CONTEXT_CHARS)
+        : undefined;
+    return { shortcutId, ...(context ? { context } : {}) };
+}
+export async function handleInteractionsRoutes(ctx) {
+    const { req, res, method, pathname, json, error, runtime } = ctx;
+    if (pathname !== "/api/interactions/shortcut")
+        return false;
+    if (method !== "POST") {
+        error(res, "Method not allowed", 405);
+        return true;
+    }
+    const buffer = await readRequestBodyBuffer(req, {
+        maxBytes: MAX_BODY_BYTES,
+        returnNullOnTooLarge: true,
+    });
+    const request = parseShortcutBody(buffer?.toString("utf8") ?? "");
+    if (!request) {
+        error(res, "Invalid shortcut interaction body", 400);
+        return true;
+    }
+    // Emit the first-class SHORTCUT_FIRED interaction event (#8792). Fire-and-forget
+    // so the proactive decider can react without ever blocking the response.
+    if (runtime) {
+        void runtime
+            .emitEvent(EventType.SHORTCUT_FIRED, {
+            runtime,
+            source: "shortcut-interaction",
+            shortcutId: request.shortcutId,
+            ...(request.context ? { context: request.context } : {}),
+            initiatedBy: "user",
+        })
+            .catch((err) => {
+            runtime.logger?.debug?.({ src: "InteractionsRoutes", err }, "[InteractionsRoutes] SHORTCUT_FIRED emit failed");
+        });
+    }
+    json(res, { ok: true, shortcutId: request.shortcutId });
+    return true;
+}

package/api/media-runtime.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Runtime wiring for the local media store: a public route so on-device iOS
+ * (in-process dispatch, no HTTP server) can serve media, an outgoing hook that
+ * persists inline `data:` URLs to the store before they hit the DB/context, and
+ * a periodic GC task that sweeps orphaned files.
+ *
+ * The pure store lives in `./media-store.ts`; this module only connects it to
+ * the runtime (routes / pipeline hooks / tasks).
+ */
+import type { IAgentRuntime, Memory, Route } from "@elizaos/core";
+/**
+ * Public GET route for stored media. On HTTP platforms (browser, desktop,
+ * Android) the pre-auth `serveMediaFile` handler answers first and this route
+ * is never reached; it exists for iOS, where requests are dispatched in-process
+ * over `runtime.routes` with no HTTP server. The native bridge base64-encodes
+ * the returned `Buffer` body losslessly.
+ */
+export declare const mediaFileRoute: Route;
+/**
+ * Persist agent-generated / inline `data:` URL attachments to the content-
+ * addressed store before the response is delivered + persisted, so a compact
+ * served `/api/media/<hash>` URL lands in the message record instead of a
+ * multi-KB base64 blob (which would bloat history + the agent's own context),
+ * and pre-compute a thumbnail for stored images so the chat tile loads small.
+ * Runs on `outgoing_before_deliver`, a mutator phase, so the rewrite propagates
+ * to both the wire response and the saved memory.
+ */
+export declare function registerMediaPipelineHook(runtime: IAgentRuntime): void;
+export declare function collectReferencedMedia(memories: Memory[]): Set<string>;
+/**
+ * Register the orphan-media GC: a daily task that diffs every live message
+ * attachment URL against the store and deletes files no message references
+ * (respecting the store's grace window). Runs wherever the agent runs —
+ * desktop/server (Node), Android, and iOS on-device.
+ */
+export declare function registerMediaGcTask(runtime: IAgentRuntime): void;
+//# sourceMappingURL=media-runtime.d.ts.map

package/api/media-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"media-runtime.d.ts","sourceRoot":"","sources":["../../src/api/media-runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAkDlE;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,EAAE,KAmB5B,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,CAyCtE;AAMD,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC,CAyBtE;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,CA2ChE"}

package/api/media-runtime.js

@@ -0,0 +1,193 @@
+/**
+ * Runtime wiring for the local media store: a public route so on-device iOS
+ * (in-process dispatch, no HTTP server) can serve media, an outgoing hook that
+ * persists inline `data:` URLs to the store before they hit the DB/context, and
+ * a periodic GC task that sweeps orphaned files.
+ *
+ * The pure store lives in `./media-store.ts`; this module only connects it to
+ * the runtime (routes / pipeline hooks / tasks).
+ */
+import { fetchRemoteMedia, logger } from "@elizaos/core";
+import { ensureThumbnailForStoredFile, gcUnreferencedMedia, handleMediaRouteRequest, isStoredMediaUrl, mediaFileNameFromUrl, persistAttachmentUrlIfInline, persistMediaBytes, } from "./media-store.js";
+/** Cap on bytes pulled while rehosting a remote attachment into the store. */
+const REHOST_MAX_BYTES = 50 * 1024 * 1024;
+/** Media content types worth rehosting (skip `link` and unknown). */
+const REHOSTABLE_CONTENT_TYPES = new Set([
+    "image",
+    "video",
+    "audio",
+    "document",
+]);
+/**
+ * Rehost a remote (http/https) media URL into the content-addressed store via
+ * the SSRF-guarded fetcher (blocks private/loopback) with a hard size cap, so an
+ * agent-generated/provider URL that may expire becomes a durable, same-origin
+ * `/api/media/<hash>` URL. Returns the served URL, or null on any failure
+ * (blocked host, too large, unreachable) so the caller can keep the original.
+ */
+async function rehostRemoteMediaUrl(url) {
+    try {
+        const { buffer, contentType } = await fetchRemoteMedia({
+            url,
+            maxBytes: REHOST_MAX_BYTES,
+        });
+        return persistMediaBytes(buffer, contentType ?? "application/octet-stream")
+            .url;
+    }
+    catch (err) {
+        logger.warn(`[media-persist] failed to rehost ${url}: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+}
+const MEDIA_URL_PREFIX = "/api/media/";
+/**
+ * Public GET route for stored media. On HTTP platforms (browser, desktop,
+ * Android) the pre-auth `serveMediaFile` handler answers first and this route
+ * is never reached; it exists for iOS, where requests are dispatched in-process
+ * over `runtime.routes` with no HTTP server. The native bridge base64-encodes
+ * the returned `Buffer` body losslessly.
+ */
+export const mediaFileRoute = {
+    type: "GET",
+    path: "/api/media/:filename",
+    // Serve at the literal path, not under the plugin-name prefix.
+    rawPath: true,
+    public: true,
+    name: "media-file",
+    routeHandler: async (ctx) => {
+        const filename = ctx.params?.filename ?? "";
+        const result = handleMediaRouteRequest(`${MEDIA_URL_PREFIX}${filename}`, ctx.method ?? "GET");
+        return {
+            status: result.status,
+            headers: result.headers,
+            ...(result.body !== undefined ? { body: result.body } : {}),
+        };
+    },
+};
+/**
+ * Persist agent-generated / inline `data:` URL attachments to the content-
+ * addressed store before the response is delivered + persisted, so a compact
+ * served `/api/media/<hash>` URL lands in the message record instead of a
+ * multi-KB base64 blob (which would bloat history + the agent's own context),
+ * and pre-compute a thumbnail for stored images so the chat tile loads small.
+ * Runs on `outgoing_before_deliver`, a mutator phase, so the rewrite propagates
+ * to both the wire response and the saved memory.
+ */
+export function registerMediaPipelineHook(runtime) {
+    runtime.registerPipelineHook({
+        id: "media-persist-inline-attachments",
+        phase: "outgoing_before_deliver",
+        handler: async (_rt, ctx) => {
+            if (ctx.phase !== "outgoing_before_deliver")
+                return;
+            const attachments = ctx.content?.attachments;
+            if (!Array.isArray(attachments) || attachments.length === 0)
+                return;
+            for (const attachment of attachments) {
+                if (!attachment || typeof attachment.url !== "string")
+                    continue;
+                if (attachment.url.startsWith("data:")) {
+                    attachment.url = persistAttachmentUrlIfInline(attachment.url);
+                }
+                else if (/^https?:\/\//i.test(attachment.url) &&
+                    !isStoredMediaUrl(attachment.url) &&
+                    typeof attachment.contentType === "string" &&
+                    REHOSTABLE_CONTENT_TYPES.has(attachment.contentType)) {
+                    // Rehost remote agent-generated/outgoing media into the durable store
+                    // so a provider URL that may expire doesn't leave a broken tile in
+                    // history. SSRF-guarded + size-capped; on failure keep the original
+                    // URL and mark it ephemeral so the UI can offer a retry.
+                    const rehosted = await rehostRemoteMediaUrl(attachment.url);
+                    if (rehosted) {
+                        attachment.url = rehosted;
+                    }
+                    else {
+                        attachment.ephemeral = true;
+                    }
+                }
+                // Pre-compute a thumbnail for stored images lacking one (generated
+                // media). `ensureThumbnailForStoredFile` self-gates on image mime/size.
+                if (!attachment.thumbnailUrl && isStoredMediaUrl(attachment.url)) {
+                    const fileName = mediaFileNameFromUrl(attachment.url);
+                    if (fileName) {
+                        const thumbUrl = await ensureThumbnailForStoredFile(fileName);
+                        if (thumbUrl)
+                            attachment.thumbnailUrl = thumbUrl;
+                    }
+                }
+            }
+        },
+    });
+}
+const MEDIA_GC_TASK_NAME = "MEDIA_GC";
+const MEDIA_GC_TAGS = ["queue", "repeat", "media-gc"];
+const MEDIA_GC_INTERVAL_MS = 24 * 60 * 60 * 1000; // daily
+export function collectReferencedMedia(memories) {
+    const referenced = new Set();
+    for (const memory of memories) {
+        const attachments = memory.content?.attachments;
+        if (Array.isArray(attachments)) {
+            for (const attachment of attachments) {
+                const url = typeof attachment?.url === "string" ? attachment.url : "";
+                const name = mediaFileNameFromUrl(url);
+                if (name)
+                    referenced.add(name);
+            }
+        }
+        // Document-linked original-bytes files: a knowledge document references its
+        // stored original via `metadata.mediaUrl` (no content.attachments entry).
+        // Collect it so the file survives GC while the document still references it.
+        const mediaUrl = memory.metadata
+            ?.mediaUrl;
+        if (typeof mediaUrl === "string") {
+            const name = mediaFileNameFromUrl(mediaUrl);
+            if (name)
+                referenced.add(name);
+        }
+    }
+    return referenced;
+}
+/**
+ * Register the orphan-media GC: a daily task that diffs every live message
+ * attachment URL against the store and deletes files no message references
+ * (respecting the store's grace window). Runs wherever the agent runs —
+ * desktop/server (Node), Android, and iOS on-device.
+ */
+export function registerMediaGcTask(runtime) {
+    runtime.registerTaskWorker({
+        name: MEDIA_GC_TASK_NAME,
+        execute: async (rt) => {
+            try {
+                const memories = await rt.getAllMemories();
+                gcUnreferencedMedia(collectReferencedMedia(memories));
+            }
+            catch (err) {
+                rt.logger.warn(`[media-gc] sweep failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            return undefined;
+        },
+    });
+    void (async () => {
+        try {
+            const existing = await runtime.getTasks({
+                agentIds: [runtime.agentId],
+                tags: MEDIA_GC_TAGS,
+            });
+            if (existing.some((task) => task.name === MEDIA_GC_TASK_NAME))
+                return;
+            await runtime.createTask({
+                name: MEDIA_GC_TASK_NAME,
+                description: "Garbage-collect unreferenced local media files",
+                tags: [...MEDIA_GC_TAGS],
+                agentId: runtime.agentId,
+                metadata: {
+                    updateInterval: MEDIA_GC_INTERVAL_MS,
+                    updatedAt: Date.now(),
+                },
+            });
+        }
+        catch (err) {
+            runtime.logger.warn(`[media-gc] failed to schedule GC task: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    })();
+}

package/api/media-store.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Local content-addressed media store for chat attachments.
+ *
+ * Bytes uploaded by the user or generated by the agent are written under
+ * `${STATE_DIR}/media/<sha256>.<ext>` and referenced by a served
+ * `/api/media/<sha256>.<ext>` URL. Content addressing gives free
+ * de-duplication: the same image attached twice is stored once and reuses its
+ * description cache (keyed on the same hash), and only a compact served URL —
+ * never raw base64 — lands in the message record or the agent's context.
+ *
+ * The sha256 filename is an unguessable capability, so media is served before
+ * the auth gate (like static assets); `<img>`/`<audio>` requests carry no auth
+ * header. `serveMediaFile` only ever serves names matching the strict
+ * content-addressed pattern from the dedicated media directory.
+ */
+import type http from "node:http";
+/**
+ * MIME types that are safe to render inline in a browser context. Everything
+ * else — notably `image/svg+xml`, `text/html`, and unknown/active types — is
+ * served with `Content-Disposition: attachment` so it can never execute script
+ * on the dashboard origin (stored-XSS defence). SVG is deliberately excluded:
+ * it is an XML document that can carry `<script>` and event handlers.
+ */
+export declare function isInlineSafeMime(mime: string): boolean;
+/**
+ * Sniff the leading bytes for active XML/HTML markup. Returns the TRUE dangerous
+ * mime when the content is SVG or HTML, else null. Used to reconcile a declared
+ * "safe image" mime against bytes that are really markup, so the store records
+ * (and later serves) the truthful, attachment-served type — defence in depth on
+ * top of the strict extension map and the nosniff header.
+ */
+export declare function sniffMarkupMime(buffer: Buffer): string | null;
+export interface MediaFileStat {
+    name: string;
+    size: number;
+    mtimeMs: number;
+}
+/**
+ * Pure eviction policy: given the current files and a byte cap, return the
+ * names to delete (oldest-by-mtime first) so the store drops to 90% of the
+ * cap. Returns [] when already within budget. Exported for unit tests.
+ */
+export declare function selectMediaToEvict(files: MediaFileStat[], cap: number): string[];
+export interface PersistedMedia {
+    /** Served URL (`/api/media/<sha256>.<ext>`) for the stored bytes. */
+    url: string;
+    /** sha256 of the bytes — also the description-cache key. */
+    hash: string;
+    fileName: string;
+}
+/** Write bytes to the content-addressed store (idempotent) and return the served URL. */
+export declare function persistMediaBytes(buffer: Buffer, mimeType: string): PersistedMedia;
+/** Persist a `data:` URL's bytes to the store; returns null for non-data URLs. */
+export declare function persistDataUrl(dataUrl: string): PersistedMedia | null;
+/** True when a URL already points at this store (no need to re-persist). */
+export declare function isStoredMediaUrl(url: string): boolean;
+/** Extract the stored filename (`<sha256>.<ext>`) from a served media URL, else null. */
+export declare function mediaFileNameFromUrl(url: string): string | null;
+/**
+ * Delete stored media files not referenced by any live attachment. `referenced`
+ * is the set of `<sha256>.<ext>` filenames still in use (built from message
+ * attachment URLs via {@link mediaFileNameFromUrl}). Files younger than the
+ * grace window are kept. Best-effort; returns counts.
+ */
+export declare function gcUnreferencedMedia(referenced: Set<string>): {
+    removed: number;
+    scanned: number;
+};
+export interface MediaFileInfo {
+    fileName: string;
+    url: string;
+    hash: string;
+    mimeType: string;
+    size: number;
+    createdAt: number;
+}
+/**
+ * List every stored media file with derived metadata (size, mime, mtime) for
+ * the Files surface. Read-only directory scan; never throws (returns [] on
+ * failure). Metadata is derived (no separate index), matching the
+ * content-addressed model — original filenames aren't retained here.
+ */
+export declare function listMediaFiles(): MediaFileInfo[];
+/**
+ * Delete a stored media file by its strict content-addressed name. Returns true
+ * when removed. Validates the name + dir to defend against traversal.
+ */
+export declare function deleteMediaFile(fileName: string): boolean;
+/**
+ * Serve a media file for the IN-PROCESS route path (iOS, where no HTTP server
+ * runs and requests are dispatched over `runtime.routes`). Returns a
+ * RouteHandlerResult-shaped object with a `Buffer` body; the native bridge
+ * base64-encodes it losslessly. No Range support — the in-process path buffers
+ * the whole file, which is fine for local on-device media.
+ */
+export declare function handleMediaRouteRequest(pathname: string, method: string): {
+    status: number;
+    headers: Record<string, string>;
+    body?: Buffer;
+};
+/**
+ * Serve a stored media file for `GET/HEAD /api/media/<name>`. Returns true when
+ * the request was handled (including 404/400). Supports HTTP Range so `<video>`
+ * / `<audio>` seeking works. Bytes are immutable (content-addressed) so they
+ * carry a long immutable Cache-Control.
+ */
+export declare function serveMediaFile(req: http.IncomingMessage, res: http.ServerResponse, pathname: string): boolean;
+/**
+ * Generate a downscaled thumbnail from raw image bytes and persist it as its
+ * own store entry. Returns the thumbnail's served URL, or null when the image
+ * isn't thumbnailable / already small / the resizer is unavailable. Best-effort.
+ */
+export declare function persistImageThumbnail(source: Buffer, srcMimeType: string): Promise<string | null>;
+/**
+ * Pre-compute a thumbnail for an already-stored image file (e.g. an
+ * agent-generated image just persisted from a data: URL). Reads the stored
+ * bytes, downscales, and persists the thumbnail. Returns its served URL or null.
+ */
+export declare function ensureThumbnailForStoredFile(fileName: string): Promise<string | null>;
+/** Best-effort: convert a `data:` URL on an attachment to a stored served URL. */
+export declare function persistAttachmentUrlIfInline(url: string): string;
+//# sourceMappingURL=media-store.d.ts.map

package/api/media-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"media-store.d.ts","sourceRoot":"","sources":["../../src/api/media-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAsElC;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAStD;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAiC7D;AAsDD,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,aAAa,EAAE,EACtB,GAAG,EAAE,MAAM,GACV,MAAM,EAAE,CAYV;AAiDD,MAAM,WAAW,cAAc;IAC7B,qEAAqE;IACrE,GAAG,EAAE,MAAM,CAAC;IACZ,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,yFAAyF;AACzF,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACf,cAAc,CAuBhB;AAID,kFAAkF;AAClF,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAgBrE;AAED,4EAA4E;AAC5E,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAErD;AAED,yFAAyF;AACzF,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAI/D;AAMD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG;IAC5D,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB,CAgCA;AAOD,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,IAAI,aAAa,EAAE,CA6BhD;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAWzD;AAwDD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GACb;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CA2BpE;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,IAAI,CAAC,eAAe,EACzB,GAAG,EAAE,IAAI,CAAC,cAAc,EACxB,QAAQ,EAAE,MAAM,GACf,OAAO,CAkET;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAQxB;AAED;;;;GAIG;AACH,wBAAsB,4BAA4B,CAChD,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAWxB;AAED,kFAAkF;AAClF,wBAAgB,4BAA4B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAahE"}