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

package/packages/agent/src/runtime/subagent-output.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Subagent output helpers for delivering final task output to the originating
+ * chat channel.
+ *
+ * The swarm synthesis path uses `completionSummary` (a short LLM-generated
+ * description of what the agent did). For user-facing replies we want the
+ * subagent's actual answer — the last `stop_reason: end_turn` assistant
+ * message from the Claude Code session jsonl. This module reads that and
+ * provides Discord-safe chunking.
+ *
+ * Path encoding mirrors Claude Code: `/home/eliza/.eliza/workspaces/abc`
+ * becomes `-home-eliza--eliza-workspaces-abc` (every `/` and `.` maps to
+ * `-`; the sequence `/.` produces `--`).
+ *
+ * @module runtime/subagent-output
+ */
+/**
+ * Read the latest `stop_reason: end_turn` assistant text from the Claude Code
+ * session jsonl under a subagent's workdir. Returns null when no such line
+ * exists yet (still running, crashed before responding, or wrong workdir).
+ */
+export declare function readLastAssistantTextFromJsonl(workdir: string): Promise<string | null>;
+/**
+ * Locate the newest `.jsonl` file under Claude Code's project directory for
+ * the given workdir.
+ */
+export declare function findLatestJsonl(workdir: string): Promise<string | null>;
+/**
+ * Scan jsonl text tail-first for the latest assistant message with
+ * `stop_reason: end_turn` and return its text. Walks past any trailing
+ * `tool_use` turns (the coordinator's "respond" follow-up can trigger
+ * another tool round after the real answer, leaving a tool_use line
+ * as the tail). Skips synthetic retry shims and Anthropic api_error
+ * frames (529/overload) so transient retries never surface as the
+ * agent's answer.
+ */
+export declare function findLatestEndTurnText(content: string): string | null;
+/**
+ * Scan jsonl tail-first for the most recent subagent activity worth showing
+ * the user in a heartbeat — the name of the most recent `tool_use` call,
+ * falling back to the leading text of the latest assistant block. Returns
+ * null if the jsonl has no assistant/tool activity yet.
+ */
+export declare function readCurrentActivityFromJsonl(workdir: string): Promise<string | null>;
+/**
+ * Split text into Discord-safe chunks (≤ max chars each), preferring
+ * paragraph → line → word boundaries past the halfway mark. Callers should
+ * pass 1900 to leave headroom under Discord's 2000-char per-message limit.
+ */
+export declare function chunkForDiscord(text: string, max: number): string[];
+//# sourceMappingURL=subagent-output.d.ts.map

package/packages/agent/src/runtime/subagent-output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-output.d.ts","sourceRoot":"","sources":["../../../../../src/runtime/subagent-output.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AA4BH;;;;GAIG;AACH,wBAAsB,8BAA8B,CAClD,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAGxB;AAED;;;GAGG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAmB7E;AAYD;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAqBpE;AAED;;;;;GAKG;AACH,wBAAsB,4BAA4B,CAChD,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAwBxB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAenE"}

package/packages/agent/src/runtime/subagent-output.js

@@ -0,0 +1,173 @@
+/**
+ * Subagent output helpers for delivering final task output to the originating
+ * chat channel.
+ *
+ * The swarm synthesis path uses `completionSummary` (a short LLM-generated
+ * description of what the agent did). For user-facing replies we want the
+ * subagent's actual answer — the last `stop_reason: end_turn` assistant
+ * message from the Claude Code session jsonl. This module reads that and
+ * provides Discord-safe chunking.
+ *
+ * Path encoding mirrors Claude Code: `/home/eliza/.eliza/workspaces/abc`
+ * becomes `-home-eliza--eliza-workspaces-abc` (every `/` and `.` maps to
+ * `-`; the sequence `/.` produces `--`).
+ *
+ * @module runtime/subagent-output
+ */
+import { promises as fs } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+function parseJsonlLine(line) {
+    try {
+        return JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Read the latest `stop_reason: end_turn` assistant text from the Claude Code
+ * session jsonl under a subagent's workdir. Returns null when no such line
+ * exists yet (still running, crashed before responding, or wrong workdir).
+ */
+export async function readLastAssistantTextFromJsonl(workdir) {
+    const content = await readJsonl(workdir);
+    return content === null ? null : findLatestEndTurnText(content);
+}
+/**
+ * Locate the newest `.jsonl` file under Claude Code's project directory for
+ * the given workdir.
+ */
+export async function findLatestJsonl(workdir) {
+    const projectKey = workdir.replace(/[/.]/g, "-");
+    const projectDir = join(homedir(), ".claude", "projects", projectKey);
+    let entries;
+    try {
+        entries = await fs.readdir(projectDir);
+    }
+    catch {
+        return null;
+    }
+    const jsonls = entries.filter((f) => f.endsWith(".jsonl"));
+    if (jsonls.length === 0)
+        return null;
+    const withMtime = await Promise.all(jsonls.map(async (f) => {
+        const s = await fs.stat(join(projectDir, f));
+        return { f, mtime: s.mtimeMs };
+    }));
+    withMtime.sort((a, b) => b.mtime - a.mtime);
+    return join(projectDir, withMtime[0].f);
+}
+async function readJsonl(workdir) {
+    const jsonlPath = await findLatestJsonl(workdir);
+    if (!jsonlPath)
+        return null;
+    try {
+        return await fs.readFile(jsonlPath, "utf-8");
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Scan jsonl text tail-first for the latest assistant message with
+ * `stop_reason: end_turn` and return its text. Walks past any trailing
+ * `tool_use` turns (the coordinator's "respond" follow-up can trigger
+ * another tool round after the real answer, leaving a tool_use line
+ * as the tail). Skips synthetic retry shims and Anthropic api_error
+ * frames (529/overload) so transient retries never surface as the
+ * agent's answer.
+ */
+export function findLatestEndTurnText(content) {
+    const lines = content.split("\n");
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i].trim();
+        if (!line)
+            continue;
+        const parsed = parseJsonlLine(line);
+        if (!parsed)
+            continue;
+        if (parsed.subtype === "api_error" || parsed.isApiErrorMessage)
+            continue;
+        const msg = parsed.message;
+        if (!msg || msg.role !== "assistant")
+            continue;
+        if (msg.model === "<synthetic>")
+            continue;
+        if (msg.stop_reason !== "end_turn")
+            continue;
+        const textParts = [];
+        for (const c of msg.content ?? []) {
+            if (c.type === "text" && typeof c.text === "string" && c.text.trim()) {
+                textParts.push(c.text.trim());
+            }
+        }
+        if (textParts.length > 0)
+            return textParts.join("\n\n");
+    }
+    return null;
+}
+/**
+ * Scan jsonl tail-first for the most recent subagent activity worth showing
+ * the user in a heartbeat — the name of the most recent `tool_use` call,
+ * falling back to the leading text of the latest assistant block. Returns
+ * null if the jsonl has no assistant/tool activity yet.
+ */
+export async function readCurrentActivityFromJsonl(workdir) {
+    const content = await readJsonl(workdir);
+    if (content === null)
+        return null;
+    const lines = content.split("\n");
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i].trim();
+        if (!line)
+            continue;
+        const parsed = parseJsonlLine(line);
+        if (!parsed)
+            continue;
+        if (parsed.subtype === "api_error" || parsed.isApiErrorMessage)
+            continue;
+        const msg = parsed.message;
+        if (!msg || msg.role !== "assistant")
+            continue;
+        if (msg.model === "<synthetic>")
+            continue;
+        for (const c of msg.content ?? []) {
+            if (c.type === "tool_use" && typeof c.name === "string")
+                return c.name;
+        }
+        for (const c of msg.content ?? []) {
+            if (c.type === "text" && typeof c.text === "string" && c.text.trim()) {
+                const first = c.text.trim().split("\n")[0] ?? "";
+                return first.length > 80 ? `${first.slice(0, 77)}…` : first;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Split text into Discord-safe chunks (≤ max chars each), preferring
+ * paragraph → line → word boundaries past the halfway mark. Callers should
+ * pass 1900 to leave headroom under Discord's 2000-char per-message limit.
+ */
+export function chunkForDiscord(text, max) {
+    if (text.length <= max)
+        return [text];
+    const out = [];
+    let remaining = text;
+    while (remaining.length > max) {
+        const half = Math.floor(max / 2);
+        let cut = remaining.lastIndexOf("\n\n", max);
+        if (cut < half)
+            cut = remaining.lastIndexOf("\n", max);
+        if (cut < half)
+            cut = remaining.lastIndexOf(" ", max);
+        if (cut < half)
+            cut = max;
+        out.push(remaining.slice(0, cut).trimEnd());
+        remaining = remaining.slice(cut).trimStart();
+    }
+    if (remaining)
+        out.push(remaining);
+    return out;
+}

package/packages/agent/src/runtime/task-heartbeat.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Task heartbeat — one "still working" chat ping per originating room per
+ * {@link HEARTBEAT_MIN_INTERVAL_MS}, for any PTY session that's been
+ * running past {@link HEARTBEAT_AFTER_MS}.
+ *
+ * Rate-limited by roomId (not by sessionId) because a swarm can spawn
+ * multiple sessions for a single user prompt and the user sees that as
+ * one task; firing one heartbeat per session would read as spam.
+ *
+ * Silent for autonomous sessions (no originating roomId) so background
+ * coordinator work doesn't spam chat.
+ *
+ * @module runtime/task-heartbeat
+ */
+import type { IAgentRuntime } from "@elizaos/core";
+/**
+ * Install the heartbeat on a PTY service. Returns a disposer that
+ * unsubscribes the listener. No-op when the service does not expose the
+ * event API (tests, mocks).
+ */
+export declare function installTaskHeartbeat(runtime: IAgentRuntime, ptyService: unknown): () => void;
+//# sourceMappingURL=task-heartbeat.d.ts.map

package/packages/agent/src/runtime/task-heartbeat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-heartbeat.d.ts","sourceRoot":"","sources":["../../../../../src/runtime/task-heartbeat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAQ,MAAM,eAAe,CAAC;AA8BzD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,aAAa,EACtB,UAAU,EAAE,OAAO,GAClB,MAAM,IAAI,CAoEZ"}

package/packages/agent/src/runtime/task-heartbeat.js

@@ -0,0 +1,84 @@
+/**
+ * Task heartbeat — one "still working" chat ping per originating room per
+ * {@link HEARTBEAT_MIN_INTERVAL_MS}, for any PTY session that's been
+ * running past {@link HEARTBEAT_AFTER_MS}.
+ *
+ * Rate-limited by roomId (not by sessionId) because a swarm can spawn
+ * multiple sessions for a single user prompt and the user sees that as
+ * one task; firing one heartbeat per session would read as spam.
+ *
+ * Silent for autonomous sessions (no originating roomId) so background
+ * coordinator work doesn't spam chat.
+ *
+ * @module runtime/task-heartbeat
+ */
+import { logger } from "@elizaos/core";
+import { readCurrentActivityFromJsonl } from "./subagent-output.js";
+/** Time before the first heartbeat fires for a freshly-spawned session. */
+const HEARTBEAT_AFTER_MS = 45_000;
+/** Minimum gap between heartbeat messages posted to the same room. */
+const HEARTBEAT_MIN_INTERVAL_MS = 120_000;
+/**
+ * Install the heartbeat on a PTY service. Returns a disposer that
+ * unsubscribes the listener. No-op when the service does not expose the
+ * event API (tests, mocks).
+ */
+export function installTaskHeartbeat(runtime, ptyService) {
+    const svc = ptyService;
+    if (!svc || typeof svc.onSessionEvent !== "function") {
+        return () => { };
+    }
+    const sessions = new Map();
+    // Global rate limit: one heartbeat per room per HEARTBEAT_MIN_INTERVAL_MS.
+    // A single user prompt can spawn multiple sessions; treating each as its
+    // own heartbeat target reads as spam.
+    const lastPostedAtByRoom = new Map();
+    const fire = async (sessionId) => {
+        const state = sessions.get(sessionId);
+        if (!state)
+            return;
+        sessions.delete(sessionId);
+        const meta = svc.sessionMetadata?.get(sessionId);
+        const roomId = typeof meta?.roomId === "string" ? meta.roomId : null;
+        if (!roomId)
+            return;
+        const now = Date.now();
+        const lastPosted = lastPostedAtByRoom.get(roomId) ?? 0;
+        if (now - lastPosted < HEARTBEAT_MIN_INTERVAL_MS)
+            return;
+        lastPostedAtByRoom.set(roomId, now);
+        const room = await runtime
+            .getRoom(roomId)
+            .catch(() => null);
+        if (!room?.channelId || !room.source)
+            return;
+        const workdir = svc.getSession?.(sessionId)?.workdir;
+        const activity = workdir
+            ? await readCurrentActivityFromJsonl(workdir).catch(() => null)
+            : null;
+        const seconds = Math.round((now - state.startedAt) / 1000);
+        const text = activity
+            ? `still working — ${seconds}s in (${activity})`
+            : `still working — ${seconds}s in`;
+        await runtime.sendMessageToTarget({ source: room.source, roomId, channelId: room.channelId }, { text, source: "task-heartbeat" });
+    };
+    return svc.onSessionEvent((sessionId, event) => {
+        if (event === "stopped" || event === "task_complete" || event === "error") {
+            const state = sessions.get(sessionId);
+            if (state)
+                clearTimeout(state.timer);
+            sessions.delete(sessionId);
+            return;
+        }
+        if (sessions.has(sessionId))
+            return;
+        sessions.set(sessionId, {
+            startedAt: Date.now(),
+            timer: setTimeout(() => {
+                void fire(sessionId).catch((err) => {
+                    logger.debug(`[task-heartbeat] fire failed for ${sessionId}: ${err instanceof Error ? err.message : String(err)}`);
+                });
+            }, HEARTBEAT_AFTER_MS),
+        });
+    });
+}

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

@@ -0,0 +1,62 @@
+/**
+ * Tool-call cache.
+ *
+ * Two-tier: in-memory LRU + on-disk persistent. Entries are keyed by
+ * `sha256(toolName + ':' + canonicalJson(args))` and tagged with the tool
+ * implementation version. A version bump on the descriptor invalidates all
+ * prior entries for that tool without an explicit purge. Side-effect tools
+ * opt out via `cacheable: false` and short-circuit straight to the
+ * underlying executor.
+ *
+ * The disk tier runs every output through a privacy redactor before
+ * serialisation. Tool inputs/outputs may contain user PII (search queries,
+ * fetched HTML, file contents) and the cross-session disk reuse is what
+ * forces this — a process-only cache could rely on the surrounding
+ * trajectory filter, but a shared on-disk store cannot.
+ */
+import type { CacheableToolDescriptor, PrivacyRedactor, ToolArgs, ToolCacheEntry, ToolOutput } from "./types.ts";
+export interface ToolCallCacheOptions {
+    /** Root directory for the on-disk tier. Defaults to ~/.milady/tool-cache. */
+    diskRoot?: string;
+    /** Maximum entries in the in-memory tier. Default 1000. */
+    memoryCapacity?: number;
+    /** Privacy redactor applied to outputs before disk write. Required. */
+    redact: PrivacyRedactor;
+    /** Clock injection for tests. */
+    now?: () => number;
+}
+export declare class ToolCallCache {
+    private readonly memory;
+    private readonly disk;
+    private readonly now;
+    constructor(options: ToolCallCacheOptions);
+    /**
+     * Look up a cache entry for (toolName, args). Returns undefined on miss,
+     * on TTL expiry, or on tool-version mismatch. A disk hit promotes the
+     * entry into the in-memory tier.
+     */
+    get(descriptor: CacheableToolDescriptor, args: ToolArgs): ToolCacheEntry | undefined;
+    /**
+     * Record a fresh tool result. No-op when the descriptor is not cacheable.
+     * Both tiers are written synchronously; the disk tier runs through the
+     * privacy redactor inside DiskStore.write.
+     */
+    set(descriptor: CacheableToolDescriptor, args: ToolArgs, output: ToolOutput): void;
+    /**
+     * Drop entries from the cache. With no arguments this purges everything.
+     * With a tool name it purges every in-memory entry whose toolName matches,
+     * and removes the disk-tier file for each matching key. Disk entries
+     * written from a previous process that never made it into this LRU are
+     * not enumerable (we deliberately do not maintain a disk index) — for a
+     * full per-tool disk purge, bump the tool's `version` in its descriptor,
+     * which forces every prior entry to miss on lookup.
+     */
+    invalidate(toolName?: string, argHash?: string): void;
+    /**
+     * Run a tool through the cache. On hit, returns the cached output without
+     * invoking `execute`. On miss, runs `execute`, persists the result, and
+     * returns it. Side-effect tools (`cacheable: false`) always run.
+     */
+    run(descriptor: CacheableToolDescriptor, args: ToolArgs, execute: () => Promise<ToolOutput>): Promise<ToolOutput>;
+}
+//# sourceMappingURL=cache.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../../../../../src/runtime/tool-call-cache/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAOH,OAAO,KAAK,EACV,uBAAuB,EACvB,eAAe,EACf,QAAQ,EACR,cAAc,EACd,UAAU,EACX,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,oBAAoB;IACnC,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,uEAAuE;IACvE,MAAM,EAAE,eAAe,CAAC;IACxB,iCAAiC;IACjC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8B;IACrD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAY;IACjC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;gBAEvB,OAAO,EAAE,oBAAoB;IAazC;;;;OAIG;IACH,GAAG,CACD,UAAU,EAAE,uBAAuB,EACnC,IAAI,EAAE,QAAQ,GACb,cAAc,GAAG,SAAS;IAsB7B;;;;OAIG;IACH,GAAG,CACD,UAAU,EAAE,uBAAuB,EACnC,IAAI,EAAE,QAAQ,EACd,MAAM,EAAE,UAAU,GACjB,IAAI;IAgBP;;;;;;;;OAQG;IACH,UAAU,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;IAqBrD;;;;OAIG;IACG,GAAG,CACP,UAAU,EAAE,uBAAuB,EACnC,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,MAAM,OAAO,CAAC,UAAU,CAAC,GACjC,OAAO,CAAC,UAAU,CAAC;CAOvB"}

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

@@ -0,0 +1,123 @@
+/**
+ * Tool-call cache.
+ *
+ * Two-tier: in-memory LRU + on-disk persistent. Entries are keyed by
+ * `sha256(toolName + ':' + canonicalJson(args))` and tagged with the tool
+ * implementation version. A version bump on the descriptor invalidates all
+ * prior entries for that tool without an explicit purge. Side-effect tools
+ * opt out via `cacheable: false` and short-circuit straight to the
+ * underlying executor.
+ *
+ * The disk tier runs every output through a privacy redactor before
+ * serialisation. Tool inputs/outputs may contain user PII (search queries,
+ * fetched HTML, file contents) and the cross-session disk reuse is what
+ * forces this — a process-only cache could rely on the surrounding
+ * trajectory filter, but a shared on-disk store cannot.
+ */
+import path from "node:path";
+import { DiskStore } from "./disk-store.js";
+import { buildCacheKey } from "./key.js";
+import { Lru } from "./lru.js";
+export class ToolCallCache {
+    memory;
+    disk;
+    now;
+    constructor(options) {
+        const root = options.diskRoot ??
+            path.join(process.env.HOME ?? process.env.USERPROFILE ?? "/tmp", ".milady", "tool-cache");
+        this.memory = new Lru(options.memoryCapacity ?? 1000);
+        this.disk = new DiskStore(root, options.redact);
+        this.now = options.now ?? Date.now;
+    }
+    /**
+     * Look up a cache entry for (toolName, args). Returns undefined on miss,
+     * on TTL expiry, or on tool-version mismatch. A disk hit promotes the
+     * entry into the in-memory tier.
+     */
+    get(descriptor, args) {
+        if (!descriptor.cacheable)
+            return undefined;
+        const key = buildCacheKey(descriptor.name, args);
+        const fromMemory = this.memory.get(key);
+        const candidate = fromMemory ?? this.disk.read(key);
+        if (!candidate)
+            return undefined;
+        if (candidate.toolVersion !== descriptor.version) {
+            this.memory.delete(key);
+            this.disk.delete(key);
+            return undefined;
+        }
+        if (candidate.expiresAt <= this.now()) {
+            this.memory.delete(key);
+            this.disk.delete(key);
+            return undefined;
+        }
+        if (!fromMemory)
+            this.memory.set(key, candidate);
+        return candidate;
+    }
+    /**
+     * Record a fresh tool result. No-op when the descriptor is not cacheable.
+     * Both tiers are written synchronously; the disk tier runs through the
+     * privacy redactor inside DiskStore.write.
+     */
+    set(descriptor, args, output) {
+        if (!descriptor.cacheable)
+            return;
+        const key = buildCacheKey(descriptor.name, args);
+        const cachedAt = this.now();
+        const entry = {
+            key,
+            toolName: descriptor.name,
+            toolVersion: descriptor.version,
+            cachedAt,
+            expiresAt: cachedAt + descriptor.ttlMs,
+            output,
+        };
+        this.memory.set(key, entry);
+        this.disk.write(entry);
+    }
+    /**
+     * Drop entries from the cache. With no arguments this purges everything.
+     * With a tool name it purges every in-memory entry whose toolName matches,
+     * and removes the disk-tier file for each matching key. Disk entries
+     * written from a previous process that never made it into this LRU are
+     * not enumerable (we deliberately do not maintain a disk index) — for a
+     * full per-tool disk purge, bump the tool's `version` in its descriptor,
+     * which forces every prior entry to miss on lookup.
+     */
+    invalidate(toolName, argHash) {
+        if (!toolName) {
+            this.memory.clear();
+            this.disk.clear();
+            return;
+        }
+        if (argHash) {
+            this.memory.delete(argHash);
+            this.disk.delete(argHash);
+            return;
+        }
+        const toDelete = [];
+        for (const [key, entry] of this.memory.entries()) {
+            if (entry.toolName === toolName)
+                toDelete.push(key);
+        }
+        for (const key of toDelete) {
+            this.memory.delete(key);
+            this.disk.delete(key);
+        }
+    }
+    /**
+     * Run a tool through the cache. On hit, returns the cached output without
+     * invoking `execute`. On miss, runs `execute`, persists the result, and
+     * returns it. Side-effect tools (`cacheable: false`) always run.
+     */
+    async run(descriptor, args, execute) {
+        const hit = this.get(descriptor, args);
+        if (hit)
+            return hit.output;
+        const output = await execute();
+        this.set(descriptor, args, output);
+        return output;
+    }
+}

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

@@ -0,0 +1,23 @@
+/**
+ * On-disk tier for the tool-call cache.
+ *
+ * Layout: <root>/<sha-prefix>/<full-sha>.json
+ * The two-char prefix keeps any single directory under a few thousand files
+ * even with a million entries.
+ *
+ * Reads/writes synchronously to keep the wrapping flow simple. Tool calls
+ * already cross network or shell boundaries, so a small fs touch is in the
+ * noise. Writes go through the privacy redactor before serialisation.
+ */
+import type { PrivacyRedactor, ToolCacheEntry } from "./types.ts";
+export declare class DiskStore {
+    private readonly root;
+    private readonly redact;
+    constructor(root: string, redact: PrivacyRedactor);
+    private pathFor;
+    read(key: string): ToolCacheEntry | undefined;
+    write(entry: ToolCacheEntry): void;
+    delete(key: string): void;
+    clear(): void;
+}
+//# sourceMappingURL=disk-store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"disk-store.d.ts","sourceRoot":"","sources":["../../../../../../src/runtime/tool-call-cache/disk-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAWH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAElE,qBAAa,SAAS;IAElB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBADN,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,eAAe;IAG1C,OAAO,CAAC,OAAO;IAIf,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAS7C,KAAK,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI;IAYlC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAKzB,KAAK,IAAI,IAAI;CAKd"}

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

@@ -0,0 +1,55 @@
+/**
+ * On-disk tier for the tool-call cache.
+ *
+ * Layout: <root>/<sha-prefix>/<full-sha>.json
+ * The two-char prefix keeps any single directory under a few thousand files
+ * even with a million entries.
+ *
+ * Reads/writes synchronously to keep the wrapping flow simple. Tool calls
+ * already cross network or shell boundaries, so a small fs touch is in the
+ * noise. Writes go through the privacy redactor before serialisation.
+ */
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
+import path from "node:path";
+export class DiskStore {
+    root;
+    redact;
+    constructor(root, redact) {
+        this.root = root;
+        this.redact = redact;
+    }
+    pathFor(key) {
+        return path.join(this.root, key.slice(0, 2), `${key}.json`);
+    }
+    read(key) {
+        const file = this.pathFor(key);
+        if (!existsSync(file))
+            return undefined;
+        const raw = readFileSync(file, "utf8");
+        const parsed = JSON.parse(raw);
+        if (parsed.key !== key)
+            return undefined;
+        return parsed;
+    }
+    write(entry) {
+        const file = this.pathFor(entry.key);
+        const dir = path.dirname(file);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        const sanitized = {
+            ...entry,
+            output: this.redact(entry.output),
+        };
+        writeFileSync(file, JSON.stringify(sanitized), "utf8");
+    }
+    delete(key) {
+        const file = this.pathFor(key);
+        if (existsSync(file))
+            rmSync(file, { force: true });
+    }
+    clear() {
+        if (existsSync(this.root)) {
+            rmSync(this.root, { recursive: true, force: true });
+        }
+    }
+}

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

@@ -0,0 +1,7 @@
+export { ToolCallCache } from "./cache.ts";
+export type { ToolCallCacheOptions } from "./cache.ts";
+export { buildCacheKey, canonicalizeJson } from "./key.ts";
+export { defaultPrivacyRedactor } from "./redact.ts";
+export { CACHEABLE_TOOL_REGISTRY, resolveToolDescriptor, isCacheable, } from "./registry.ts";
+export type { CacheableToolDescriptor, PrivacyRedactor, ToolArgs, ToolCacheEntry, ToolOutput, } from "./types.ts";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../src/runtime/tool-call-cache/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,YAAY,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAC3D,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EACL,uBAAuB,EACvB,qBAAqB,EACrB,WAAW,GACZ,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,uBAAuB,EACvB,eAAe,EACf,QAAQ,EACR,cAAc,EACd,UAAU,GACX,MAAM,YAAY,CAAC"}

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

@@ -0,0 +1,4 @@
+export { ToolCallCache } from "./cache.js";
+export { buildCacheKey, canonicalizeJson } from "./key.js";
+export { defaultPrivacyRedactor } from "./redact.js";
+export { CACHEABLE_TOOL_REGISTRY, resolveToolDescriptor, isCacheable, } from "./registry.js";

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

@@ -0,0 +1,11 @@
+/**
+ * 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 type { ToolArgs } from "./types.ts";
+export declare function canonicalizeJson(value: unknown): string;
+export declare function buildCacheKey(toolName: string, args: ToolArgs): string;
+//# sourceMappingURL=key.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"key.d.ts","sourceRoot":"","sources":["../../../../../../src/runtime/tool-call-cache/key.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAcvD;AAED,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,MAAM,CAOtE"}