@elizaos/agent 2.0.0-alpha.98 → 2.0.0-beta.2

package/packages/agent/src/runtime/tool-call-cache/key.js

@@ -0,0 +1,31 @@
+/**
+ * Stable cache-key derivation.
+ *
+ * Args are JSON-stringified with sorted object keys so semantically-equal
+ * argument shapes (e.g. `{a:1,b:2}` and `{b:2,a:1}`) collide on the same
+ * key. The final key is `sha256(toolName + ':' + canonicalJson)`.
+ */
+import { createHash } from "node:crypto";
+export function canonicalizeJson(value) {
+    if (value === null || typeof value !== "object") {
+        return JSON.stringify(value) ?? "null";
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((v) => canonicalizeJson(v)).join(",")}]`;
+    }
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    const parts = [];
+    for (const key of keys) {
+        parts.push(`${JSON.stringify(key)}:${canonicalizeJson(obj[key])}`);
+    }
+    return `{${parts.join(",")}}`;
+}
+export function buildCacheKey(toolName, args) {
+    const canonical = canonicalizeJson(args);
+    const hash = createHash("sha256");
+    hash.update(toolName);
+    hash.update(":");
+    hash.update(canonical);
+    return hash.digest("hex");
+}

package/packages/agent/src/runtime/tool-call-cache/lru.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Tiny insertion-ordered LRU. Map iteration order is insertion order, so
+ * we delete + re-set on access to bump entries to the most-recent slot,
+ * and shift the oldest entry off the front when capacity is exceeded.
+ */
+export declare class Lru<K, V> {
+    private readonly capacity;
+    private readonly map;
+    constructor(capacity: number);
+    get(key: K): V | undefined;
+    set(key: K, value: V): void;
+    delete(key: K): boolean;
+    clear(): void;
+    size(): number;
+    entries(): IterableIterator<[K, V]>;
+}
+//# sourceMappingURL=lru.d.ts.map

package/packages/agent/src/runtime/tool-call-cache/lru.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lru.d.ts","sourceRoot":"","sources":["../../../../../../src/runtime/tool-call-cache/lru.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,qBAAa,GAAG,CAAC,CAAC,EAAE,CAAC;IAGP,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAFrC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAmB;gBAEV,QAAQ,EAAE,MAAM;IAM7C,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS;IAQ1B,GAAG,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAU3B,MAAM,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO;IAIvB,KAAK,IAAI,IAAI;IAIb,IAAI,IAAI,MAAM;IAId,OAAO,IAAI,gBAAgB,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;CAGpC"}

package/packages/agent/src/runtime/tool-call-cache/lru.js

@@ -0,0 +1,46 @@
+/**
+ * Tiny insertion-ordered LRU. Map iteration order is insertion order, so
+ * we delete + re-set on access to bump entries to the most-recent slot,
+ * and shift the oldest entry off the front when capacity is exceeded.
+ */
+export class Lru {
+    capacity;
+    map = new Map();
+    constructor(capacity) {
+        this.capacity = capacity;
+        if (!Number.isInteger(capacity) || capacity <= 0) {
+            throw new Error("Lru capacity must be a positive integer");
+        }
+    }
+    get(key) {
+        const value = this.map.get(key);
+        if (value === undefined)
+            return undefined;
+        this.map.delete(key);
+        this.map.set(key, value);
+        return value;
+    }
+    set(key, value) {
+        if (this.map.has(key)) {
+            this.map.delete(key);
+        }
+        else if (this.map.size >= this.capacity) {
+            const oldest = this.map.keys().next();
+            if (!oldest.done)
+                this.map.delete(oldest.value);
+        }
+        this.map.set(key, value);
+    }
+    delete(key) {
+        return this.map.delete(key);
+    }
+    clear() {
+        this.map.clear();
+    }
+    size() {
+        return this.map.size;
+    }
+    entries() {
+        return this.map.entries();
+    }
+}

package/packages/agent/src/runtime/tool-call-cache/redact.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Default privacy redactor for the tool-call cache.
+ *
+ * The full trajectory privacy filter operates on a richer trajectory shape
+ * (steps, llmCalls, metadata) and exists in `plugins/app-training`. Pulling
+ * that dependency into app-core would invert the layer order, so we keep a
+ * focused redactor here that mirrors the credential + geo passes from that
+ * filter and is applied to every disk write.
+ *
+ * The redactor walks the value tree and replaces:
+ *   - common API key shapes (`sk-…`, `Bearer …`, `ghp_…`, `AKIA…`)
+ *   - environment-variable values whose key name looks like a secret
+ *   - geographic coordinates (matching the Location-plugin patterns)
+ */
+import type { PrivacyRedactor } from "./types.ts";
+export declare const defaultPrivacyRedactor: PrivacyRedactor;
+//# sourceMappingURL=redact.d.ts.map

package/packages/agent/src/runtime/tool-call-cache/redact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.d.ts","sourceRoot":"","sources":["../../../../../../src/runtime/tool-call-cache/redact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAgElD,eAAO,MAAM,sBAAsB,EAAE,eAGpC,CAAC"}

package/packages/agent/src/runtime/tool-call-cache/redact.js

@@ -0,0 +1,77 @@
+/**
+ * Default privacy redactor for the tool-call cache.
+ *
+ * The full trajectory privacy filter operates on a richer trajectory shape
+ * (steps, llmCalls, metadata) and exists in `plugins/app-training`. Pulling
+ * that dependency into app-core would invert the layer order, so we keep a
+ * focused redactor here that mirrors the credential + geo passes from that
+ * filter and is applied to every disk write.
+ *
+ * The redactor walks the value tree and replaces:
+ *   - common API key shapes (`sk-…`, `Bearer …`, `ghp_…`, `AKIA…`)
+ *   - environment-variable values whose key name looks like a secret
+ *   - geographic coordinates (matching the Location-plugin patterns)
+ */
+const CREDENTIAL_PATTERNS = [
+    { label: "openai-key", pattern: /\bsk-[A-Za-z0-9_-]{16,}\b/g },
+    { label: "anthropic-key", pattern: /\bsk-ant-[A-Za-z0-9_-]{16,}\b/g },
+    { label: "bearer", pattern: /\bBearer\s+[A-Za-z0-9._-]{16,}\b/g },
+    { label: "github-token", pattern: /\bghp_[A-Za-z0-9]{20,}\b/g },
+    { label: "aws-access-key", pattern: /\bAKIA[0-9A-Z]{16}\b/g },
+];
+const GEO_PATTERNS = [
+    /"coords"\s*:\s*\{\s*"latitude"\s*:\s*-?\d+(?:\.\d+)?\s*,\s*"longitude"\s*:\s*-?\d+(?:\.\d+)?(?:\s*,\s*"[A-Za-z_][A-Za-z0-9_]*"\s*:\s*[^,}]+)*\s*\}/g,
+    /"latitude"\s*:\s*-?\d+(?:\.\d+)?\s*,\s*"longitude"\s*:\s*-?\d+(?:\.\d+)?/g,
+    /\b(?:current\s+location|location|coords|coordinates)\s*[:=]\s*-?\d+(?:\.\d+)?\s*,\s*-?\d+(?:\.\d+)?/gi,
+    /\b(?:lat|latitude)\s*[:=]\s*-?\d+(?:\.\d+)?\s*[,;]\s*(?:lng|lon|long|longitude)\s*[:=]\s*-?\d+(?:\.\d+)?/gi,
+    /\b-?\d{1,3}\.\d{2,}\s*,\s*-?\d{1,3}\.\d{2,}\b/g,
+];
+const SECRET_NAME = /KEY|TOKEN|SECRET|PASSWORD|API|CREDENTIAL/i;
+function snapshotEnvCredentials() {
+    const out = [];
+    for (const [key, value] of Object.entries(process.env)) {
+        if (!SECRET_NAME.test(key))
+            continue;
+        if (typeof value !== "string" || value.length < 8)
+            continue;
+        out.push(value);
+    }
+    return out;
+}
+function redactString(input, envValues) {
+    let out = input;
+    for (const pattern of GEO_PATTERNS) {
+        out = out.replace(pattern, "[REDACTED_GEO]");
+    }
+    for (const { label, pattern } of CREDENTIAL_PATTERNS) {
+        out = out.replace(pattern, `<REDACTED:${label}>`);
+    }
+    for (const credValue of envValues) {
+        if (!credValue)
+            continue;
+        const escaped = credValue.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        out = out.replace(new RegExp(escaped, "g"), "<REDACTED:env-secret>");
+    }
+    return out;
+}
+function walk(value, envValues) {
+    if (typeof value === "string") {
+        return redactString(value, envValues);
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => walk(item, envValues));
+    }
+    if (value && typeof value === "object") {
+        const obj = value;
+        const out = {};
+        for (const key of Object.keys(obj)) {
+            out[key] = walk(obj[key], envValues);
+        }
+        return out;
+    }
+    return value;
+}
+export const defaultPrivacyRedactor = (value) => {
+    const envValues = snapshotEnvCredentials();
+    return walk(value, envValues);
+};

package/packages/agent/src/runtime/tool-call-cache/registry.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Cacheable-tool whitelist.
+ *
+ * The cache is opt-in. A tool only participates if it is registered here
+ * with `cacheable: true`. The default for any tool not in the registry is
+ * `cacheable: false` so side-effect tools (send_email, post_message,
+ * write_file, run_code, …) are guaranteed never to short-circuit through
+ * the cache, even if a future caller forgets to register them.
+ *
+ * TTLs default to 24h. Tools with shorter freshness needs (file reads
+ * against a working tree) get short TTLs; tools whose results are stable
+ * across days (search results, immutable web archives) get longer ones.
+ */
+import type { CacheableToolDescriptor } from "./types.ts";
+export declare const CACHEABLE_TOOL_REGISTRY: Record<string, CacheableToolDescriptor>;
+export declare function resolveToolDescriptor(name: string, overrides?: Partial<Pick<CacheableToolDescriptor, "ttlMs" | "version">>): CacheableToolDescriptor;
+export declare function isCacheable(name: string): boolean;
+//# sourceMappingURL=registry.d.ts.map

package/packages/agent/src/runtime/tool-call-cache/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../../../../src/runtime/tool-call-cache/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAK1D,eAAO,MAAM,uBAAuB,EAAE,MAAM,CAAC,MAAM,EAAE,uBAAuB,CAgCzE,CAAC;AAEJ,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,SAAS,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,uBAAuB,EAAE,OAAO,GAAG,SAAS,CAAC,CAAC,GACtE,uBAAuB,CAezB;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEjD"}

package/packages/agent/src/runtime/tool-call-cache/registry.js

@@ -0,0 +1,66 @@
+/**
+ * Cacheable-tool whitelist.
+ *
+ * The cache is opt-in. A tool only participates if it is registered here
+ * with `cacheable: true`. The default for any tool not in the registry is
+ * `cacheable: false` so side-effect tools (send_email, post_message,
+ * write_file, run_code, …) are guaranteed never to short-circuit through
+ * the cache, even if a future caller forgets to register them.
+ *
+ * TTLs default to 24h. Tools with shorter freshness needs (file reads
+ * against a working tree) get short TTLs; tools whose results are stable
+ * across days (search results, immutable web archives) get longer ones.
+ */
+const HOUR_MS = 60 * 60 * 1000;
+const DAY_MS = 24 * HOUR_MS;
+export const CACHEABLE_TOOL_REGISTRY = {
+    web_search: {
+        name: "web_search",
+        version: "1",
+        ttlMs: 6 * HOUR_MS,
+        cacheable: true,
+    },
+    web_fetch: {
+        name: "web_fetch",
+        version: "1",
+        ttlMs: DAY_MS,
+        cacheable: true,
+    },
+    file_read: {
+        name: "file_read",
+        version: "1",
+        ttlMs: 5 * 60 * 1000,
+        cacheable: true,
+    },
+    rag_search: {
+        name: "rag_search",
+        version: "1",
+        ttlMs: HOUR_MS,
+        cacheable: true,
+    },
+    knowledge_lookup: {
+        name: "knowledge_lookup",
+        version: "1",
+        ttlMs: HOUR_MS,
+        cacheable: true,
+    },
+};
+export function resolveToolDescriptor(name, overrides) {
+    const base = CACHEABLE_TOOL_REGISTRY[name];
+    if (!base) {
+        return {
+            name,
+            version: "1",
+            ttlMs: 0,
+            cacheable: false,
+        };
+    }
+    return {
+        ...base,
+        ttlMs: overrides?.ttlMs ?? base.ttlMs,
+        version: overrides?.version ?? base.version,
+    };
+}
+export function isCacheable(name) {
+    return CACHEABLE_TOOL_REGISTRY[name]?.cacheable === true;
+}

package/packages/agent/src/runtime/tool-call-cache/types.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Tool-call cache — public types.
+ *
+ * The cache wraps tool execution. Given a (toolName, args) pair, it computes a
+ * stable hash, looks up an entry in either the in-memory LRU or the on-disk
+ * tier, and returns the cached output if it has not expired and matches the
+ * tool's recorded version. Side-effect tools opt out via the `cacheable`
+ * flag on their definition.
+ */
+export type ToolArgs = Record<string, unknown>;
+/**
+ * Tool output type. Tools may return arbitrary JSON-serialisable data.
+ * We constrain to JSON-friendly shapes so the disk tier can persist them.
+ */
+export type ToolOutput = string | number | boolean | null | ToolOutput[] | {
+    [key: string]: ToolOutput;
+};
+export interface ToolCacheEntry {
+    /** sha256 of the canonicalized (toolName, args) pair. */
+    key: string;
+    /** Tool name used to compute the key (for diagnostics + invalidation). */
+    toolName: string;
+    /** Tool implementation version used when the entry was written. */
+    toolVersion: string;
+    /** UTC ms when the entry was written. */
+    cachedAt: number;
+    /** UTC ms when the entry should be considered expired. */
+    expiresAt: number;
+    /** Cached tool output. */
+    output: ToolOutput;
+}
+export interface CacheableToolDescriptor {
+    name: string;
+    /** Implementation version. Bumping invalidates all prior cache entries. */
+    version: string;
+    /** Per-tool TTL in ms. */
+    ttlMs: number;
+    /**
+     * Whether this tool may be cached. Side-effect tools (send_email,
+     * post_message, write_file, run_code) MUST set this to `false`.
+     */
+    cacheable: boolean;
+}
+/**
+ * Strip personally-identifiable information from a value before persisting
+ * it to disk. Implementations must be pure and synchronous so the cache
+ * write path stays predictable.
+ */
+export type PrivacyRedactor = (value: unknown) => unknown;
+//# sourceMappingURL=types.d.ts.map

package/packages/agent/src/runtime/tool-call-cache/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../../src/runtime/tool-call-cache/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE/C;;;GAGG;AACH,MAAM,MAAM,UAAU,GAClB,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,UAAU,EAAE,GACZ;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAAA;CAAE,CAAC;AAElC,MAAM,WAAW,cAAc;IAC7B,yDAAyD;IACzD,GAAG,EAAE,MAAM,CAAC;IACZ,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,WAAW,EAAE,MAAM,CAAC;IACpB,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAC;IAClB,0BAA0B;IAC1B,MAAM,EAAE,UAAU,CAAC;CACpB;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,OAAO,EAAE,MAAM,CAAC;IAChB,0BAA0B;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC"}

package/packages/agent/src/runtime/tool-call-cache/types.js

@@ -0,0 +1,10 @@
+/**
+ * Tool-call cache — public types.
+ *
+ * The cache wraps tool execution. Given a (toolName, args) pair, it computes a
+ * stable hash, looks up an entry in either the in-memory LRU or the on-disk
+ * tier, and returns the cached output if it has not expired and matches the
+ * tool's recorded version. Side-effect tools opt out via the `cacheable`
+ * flag on their definition.
+ */
+export {};

package/packages/agent/src/runtime/tool-call-cache-wrapper.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Tool-call cache wiring for the agent runtime.
+ *
+ * Wraps the `handler` of every registered Action that the cache registry
+ * marks as `cacheable: true` so the result of a (toolName, args) pair is
+ * served from the two-tier `ToolCallCache` instead of re-running the
+ * underlying tool. Side-effect tools and any tool not listed in
+ * `CACHEABLE_TOOL_REGISTRY` pass through unchanged.
+ *
+ * Hooked into the runtime via `wrapActionsWithCache(actions, cache)` which
+ * the eliza loader calls after collecting plugin actions and before handing
+ * them to `AgentRuntime`. Per-tool TTL overrides come from the `tools.cache`
+ * config block (see `zod-schema.agent-runtime.ts`).
+ */
+import type { Action } from "@elizaos/core";
+import { CACHEABLE_TOOL_REGISTRY, ToolCallCache } from "./tool-call-cache/index.ts";
+interface PerToolOverride {
+    ttlMinutes?: number;
+    version?: string;
+}
+export interface ToolCacheConfig {
+    enabled?: boolean;
+    memoryCapacity?: number;
+    diskRoot?: string;
+    perTool?: Record<string, PerToolOverride>;
+}
+/**
+ * Build a ToolCallCache from agent runtime config. Returns null when the
+ * cache is disabled so callers can skip the wrap-step entirely.
+ */
+export declare function createToolCallCacheFromConfig(cfg: ToolCacheConfig | undefined): ToolCallCache | null;
+/**
+ * Wrap an Action's handler so cacheable tools route through the cache.
+ * Non-cacheable actions are returned unchanged.
+ */
+export declare function wrapActionWithCache(action: Action, cache: ToolCallCache, cfg: ToolCacheConfig | undefined): Action;
+export declare function wrapActionsWithCache(actions: Action[], cache: ToolCallCache, cfg: ToolCacheConfig | undefined): Action[];
+export { CACHEABLE_TOOL_REGISTRY };
+//# sourceMappingURL=tool-call-cache-wrapper.d.ts.map

package/packages/agent/src/runtime/tool-call-cache-wrapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-call-cache-wrapper.d.ts","sourceRoot":"","sources":["../../../../../src/runtime/tool-call-cache-wrapper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EACV,MAAM,EAIP,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,uBAAuB,EAKvB,aAAa,EAEd,MAAM,4BAA4B,CAAC;AAEpC,UAAU,eAAe;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;CAC3C;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,CAC3C,GAAG,EAAE,eAAe,GAAG,SAAS,GAC/B,aAAa,GAAG,IAAI,CAOtB;AAyBD;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,aAAa,EACpB,GAAG,EAAE,eAAe,GAAG,SAAS,GAC/B,MAAM,CAkBR;AAED,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EAAE,EACjB,KAAK,EAAE,aAAa,EACpB,GAAG,EAAE,eAAe,GAAG,SAAS,GAC/B,MAAM,EAAE,CAEV;AAED,OAAO,EAAE,uBAAuB,EAAE,CAAC"}

package/packages/agent/src/runtime/tool-call-cache-wrapper.js

@@ -0,0 +1,72 @@
+/**
+ * Tool-call cache wiring for the agent runtime.
+ *
+ * Wraps the `handler` of every registered Action that the cache registry
+ * marks as `cacheable: true` so the result of a (toolName, args) pair is
+ * served from the two-tier `ToolCallCache` instead of re-running the
+ * underlying tool. Side-effect tools and any tool not listed in
+ * `CACHEABLE_TOOL_REGISTRY` pass through unchanged.
+ *
+ * Hooked into the runtime via `wrapActionsWithCache(actions, cache)` which
+ * the eliza loader calls after collecting plugin actions and before handing
+ * them to `AgentRuntime`. Per-tool TTL overrides come from the `tools.cache`
+ * config block (see `zod-schema.agent-runtime.ts`).
+ */
+import { CACHEABLE_TOOL_REGISTRY, defaultPrivacyRedactor, isCacheable, resolveToolDescriptor, ToolCallCache, } from "./tool-call-cache/index.js";
+/**
+ * Build a ToolCallCache from agent runtime config. Returns null when the
+ * cache is disabled so callers can skip the wrap-step entirely.
+ */
+export function createToolCallCacheFromConfig(cfg) {
+    if (cfg && cfg.enabled === false)
+        return null;
+    return new ToolCallCache({
+        diskRoot: cfg?.diskRoot,
+        memoryCapacity: cfg?.memoryCapacity,
+        redact: defaultPrivacyRedactor,
+    });
+}
+function resolveDescriptor(name, cfg) {
+    const override = cfg?.perTool?.[name];
+    return resolveToolDescriptor(name, {
+        ttlMs: override?.ttlMinutes !== undefined
+            ? override.ttlMinutes * 60_000
+            : undefined,
+        version: override?.version,
+    });
+}
+function extractArgs(options) {
+    if (!options || typeof options !== "object")
+        return {};
+    const opts = options;
+    if (opts.parameters && typeof opts.parameters === "object") {
+        return opts.parameters;
+    }
+    return {};
+}
+/**
+ * Wrap an Action's handler so cacheable tools route through the cache.
+ * Non-cacheable actions are returned unchanged.
+ */
+export function wrapActionWithCache(action, cache, cfg) {
+    if (!isCacheable(action.name))
+        return action;
+    const descriptor = resolveDescriptor(action.name, cfg);
+    const original = action.handler;
+    const wrapped = async (runtime, message, state, options, ...rest) => {
+        const args = extractArgs(options);
+        const hit = cache.get(descriptor, args);
+        if (hit)
+            return hit.output;
+        const result = await original(runtime, message, state, options, ...rest);
+        if (result !== undefined) {
+            cache.set(descriptor, args, result);
+        }
+        return result;
+    };
+    return { ...action, handler: wrapped };
+}
+export function wrapActionsWithCache(actions, cache, cfg) {
+    return actions.map((a) => wrapActionWithCache(a, cache, cfg));
+}
+export { CACHEABLE_TOOL_REGISTRY };

package/packages/agent/src/runtime/trajectory-export.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Trajectory export — export and archive operations.
+ *
+ * Re-exports archive helpers and hosts the shared canonical list/detail/export
+ * shaping used by the agent runtime trajectory logger implementations.
+ */
+import type { Trajectory, TrajectoryExportOptions, TrajectoryExportResult, TrajectoryListItem } from "../types/trajectory.ts";
+import { type PersistedTrajectory } from "./trajectory-internals.ts";
+export type RuntimeTrajectoryExportOptions = TrajectoryExportOptions;
+export declare function trajectoryRowToListItem(row: unknown, agentId: string): TrajectoryListItem | null;
+export declare function persistedTrajectoryToDetailRecord(persisted: PersistedTrajectory, agentId: string): Trajectory;
+export declare function exportPersistedTrajectories(params: {
+    agentId: string;
+    persistedTrajectories: PersistedTrajectory[];
+    options: RuntimeTrajectoryExportOptions;
+}): TrajectoryExportResult;
+export { ensureArchiveDirectory, resolvePreferredTrajectoryArchiveRoot, resolveTrajectoryArchiveDirectory, stringifyArchiveRow, TRAJECTORY_ARCHIVE_DIRNAME, toArchiveSafeTimestamp, writeCompressedJsonlRows, } from "./trajectory-internals.ts";
+//# sourceMappingURL=trajectory-export.d.ts.map

package/packages/agent/src/runtime/trajectory-export.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trajectory-export.d.ts","sourceRoot":"","sources":["../../../../../src/runtime/trajectory-export.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EACV,UAAU,EACV,uBAAuB,EACvB,sBAAsB,EACtB,kBAAkB,EAInB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAOL,KAAK,mBAAmB,EAKzB,MAAM,2BAA2B,CAAC;AAEnC,MAAM,MAAM,8BAA8B,GAAG,uBAAuB,CAAC;AA+ErE,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,MAAM,GACd,kBAAkB,GAAG,IAAI,CAmC3B;AAED,wBAAgB,iCAAiC,CAC/C,SAAS,EAAE,mBAAmB,EAC9B,OAAO,EAAE,MAAM,GACd,UAAU,CAsBZ;AAED,wBAAgB,2BAA2B,CAAC,MAAM,EAAE;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,qBAAqB,EAAE,mBAAmB,EAAE,CAAC;IAC7C,OAAO,EAAE,8BAA8B,CAAC;CACzC,GAAG,sBAAsB,CAMzB;AAED,OAAO,EACL,sBAAsB,EACtB,qCAAqC,EACrC,iCAAiC,EACjC,mBAAmB,EACnB,0BAA0B,EAC1B,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,2BAA2B,CAAC"}

package/packages/agent/src/runtime/trajectory-export.js

@@ -0,0 +1,109 @@
+/**
+ * Trajectory export — export and archive operations.
+ *
+ * Re-exports archive helpers and hosts the shared canonical list/detail/export
+ * shaping used by the agent runtime trajectory logger implementations.
+ */
+import { serializeTrajectoryExport } from "@elizaos/core";
+import { enrichTrajectoryLlmCall, normalizeStatus, normalizeTrajectoryMetadata, parseMetadata, toNumber, toOptionalNumber, toText, } from "./trajectory-internals.js";
+function toCreatedAt(timestamp) {
+    return new Date(timestamp ?? Date.now()).toISOString();
+}
+function toPublicTrajectoryLlmCall(call, trajectoryId, stepId) {
+    return enrichTrajectoryLlmCall({
+        ...call,
+        callId: toText(call.callId, `${stepId}-call`),
+        stepId,
+        trajectoryId,
+        timestamp: toNumber(call.timestamp, Date.now()),
+        model: toText(call.model, "unknown"),
+        systemPrompt: toText(call.systemPrompt, ""),
+        userPrompt: toText(call.userPrompt, ""),
+        response: toText(call.response, ""),
+        temperature: toNumber(call.temperature, 0),
+        maxTokens: toNumber(call.maxTokens, 0),
+        purpose: toText(call.purpose, "action"),
+        actionType: toText(call.actionType, "runtime.useModel"),
+        latencyMs: toNumber(call.latencyMs, 0),
+        ...(call.createdAt
+            ? { createdAt: toText(call.createdAt, toCreatedAt(call.timestamp)) }
+            : { createdAt: toCreatedAt(call.timestamp) }),
+    });
+}
+function toPublicTrajectoryProviderAccess(access, trajectoryId, stepId) {
+    return {
+        ...access,
+        providerId: toText(access.providerId, `${stepId}-provider`),
+        stepId,
+        trajectoryId,
+        providerName: toText(access.providerName, "unknown"),
+        purpose: toText(access.purpose, "provider"),
+        data: access.data && typeof access.data === "object" ? access.data : {},
+        timestamp: toNumber(access.timestamp, Date.now()),
+        ...(access.createdAt
+            ? { createdAt: toText(access.createdAt, toCreatedAt(access.timestamp)) }
+            : { createdAt: toCreatedAt(access.timestamp) }),
+    };
+}
+function toPublicTrajectoryStep(step, trajectoryId) {
+    return {
+        ...step,
+        stepId: toText(step.stepId, trajectoryId),
+        timestamp: toNumber(step.timestamp, Date.now()),
+        llmCalls: (step.llmCalls ?? []).map((call) => toPublicTrajectoryLlmCall(call, trajectoryId, toText(step.stepId, trajectoryId))),
+        providerAccesses: (step.providerAccesses ?? []).map((access) => toPublicTrajectoryProviderAccess(access, trajectoryId, toText(step.stepId, trajectoryId))),
+    };
+}
+export function trajectoryRowToListItem(row, agentId) {
+    if (!row || typeof row !== "object" || Array.isArray(row))
+        return null;
+    const record = row;
+    const normalizedMetadata = normalizeTrajectoryMetadata(parseMetadata(record.metadata), {
+        scenarioId: record.scenario_id,
+        batchId: record.batch_id,
+    });
+    return {
+        id: toText(record.id ?? record.trajectory_id, ""),
+        agentId: toText(record.agent_id, agentId),
+        source: toText(record.source, "runtime"),
+        status: normalizeStatus(record.status, "completed"),
+        startTime: toNumber(record.start_time, Date.now()),
+        endTime: toOptionalNumber(record.end_time) ?? null,
+        durationMs: toOptionalNumber(record.duration_ms) ?? null,
+        stepCount: toNumber(record.step_count, 0),
+        llmCallCount: toNumber(record.llm_call_count, 0),
+        providerAccessCount: toNumber(record.provider_access_count, 0),
+        totalPromptTokens: toNumber(record.total_prompt_tokens, 0),
+        totalCompletionTokens: toNumber(record.total_completion_tokens, 0),
+        scenarioId: normalizedMetadata.scenarioId,
+        batchId: normalizedMetadata.batchId,
+        createdAt: toText(record.created_at, new Date(toNumber(record.start_time, Date.now())).toISOString()),
+        metadata: normalizedMetadata.metadata,
+    };
+}
+export function persistedTrajectoryToDetailRecord(persisted, agentId) {
+    const endTime = typeof persisted.endTime === "number" ? persisted.endTime : undefined;
+    return {
+        trajectoryId: persisted.id,
+        agentId,
+        source: persisted.source,
+        status: persisted.status,
+        startTime: persisted.startTime,
+        ...(endTime !== undefined ? { endTime } : {}),
+        ...(endTime !== undefined
+            ? { durationMs: Math.max(0, endTime - persisted.startTime) }
+            : {}),
+        ...(persisted.scenarioId ? { scenarioId: persisted.scenarioId } : {}),
+        ...(persisted.batchId ? { batchId: persisted.batchId } : {}),
+        steps: (persisted.steps ?? []).map((step) => toPublicTrajectoryStep(step, persisted.id)),
+        metrics: { finalStatus: persisted.status },
+        metadata: persisted.metadata,
+        stepsJson: JSON.stringify(persisted.steps ?? []),
+    };
+}
+export function exportPersistedTrajectories(params) {
+    const { agentId, persistedTrajectories, options } = params;
+    const trajectories = persistedTrajectories.map((trajectory) => persistedTrajectoryToDetailRecord(trajectory, agentId));
+    return serializeTrajectoryExport(trajectories, options);
+}
+export { ensureArchiveDirectory, resolvePreferredTrajectoryArchiveRoot, resolveTrajectoryArchiveDirectory, stringifyArchiveRow, TRAJECTORY_ARCHIVE_DIRNAME, toArchiveSafeTimestamp, writeCompressedJsonlRows, } from "./trajectory-internals.js";