@agentionai/agents 0.8.1 → 0.10.0

package/dist/history/History.js

@@ -1,19 +1,84 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.History = exports.isToolResultContent = exports.isToolUseContent = exports.isTextContent = exports.textMessage = exports.toolResult = exports.toolUse = exports.text = void 0;
+exports.History = exports.isImageContent = exports.isImageBase64Content = exports.isImageUrlContent = exports.isToolResultContent = exports.isToolUseContent = exports.isTextContent = exports.imageBase64 = exports.imageUrl = exports.textMessage = exports.toolResult = exports.toolUse = exports.text = void 0;
+exports.resetTokenxCache = resetTokenxCache;
 const events_1 = __importDefault(require("events"));
 const types_1 = require("./types");
+// Cached tokenx estimator — starts as a character-based fallback and is
+// replaced with the real tokenx implementation once the module loads.
+let _estimateTokenCount = (t) => Math.ceil(t.length / 4);
+void Promise.resolve().then(() => __importStar(require("tokenx"))).then((mod) => {
+    _estimateTokenCount = mod.estimateTokenCount;
+})
+    .catch(() => {
+    /* keep fallback */
+});
+/** @internal — exposed for test teardown only */
+function resetTokenxCache() {
+    _estimateTokenCount = (t) => Math.ceil(t.length / 4);
+}
+/**
+ * Estimate token count for a content block array.
+ * Image blocks use a flat 1000-token estimate (resolution-independent conservative value).
+ * Text and tool blocks fall through to the tokenx estimator.
+ */
+function estimateContentTokens(content) {
+    return content.reduce((sum, block) => {
+        if ((0, types_1.isImageContent)(block)) {
+            return sum + 1000;
+        }
+        return sum + _estimateTokenCount(JSON.stringify(block));
+    }, 0);
+}
 var types_2 = require("./types");
 Object.defineProperty(exports, "text", { enumerable: true, get: function () { return types_2.text; } });
 Object.defineProperty(exports, "toolUse", { enumerable: true, get: function () { return types_2.toolUse; } });
 Object.defineProperty(exports, "toolResult", { enumerable: true, get: function () { return types_2.toolResult; } });
 Object.defineProperty(exports, "textMessage", { enumerable: true, get: function () { return types_2.textMessage; } });
+Object.defineProperty(exports, "imageUrl", { enumerable: true, get: function () { return types_2.imageUrl; } });
+Object.defineProperty(exports, "imageBase64", { enumerable: true, get: function () { return types_2.imageBase64; } });
 Object.defineProperty(exports, "isTextContent", { enumerable: true, get: function () { return types_2.isTextContent; } });
 Object.defineProperty(exports, "isToolUseContent", { enumerable: true, get: function () { return types_2.isToolUseContent; } });
 Object.defineProperty(exports, "isToolResultContent", { enumerable: true, get: function () { return types_2.isToolResultContent; } });
+Object.defineProperty(exports, "isImageUrlContent", { enumerable: true, get: function () { return types_2.isImageUrlContent; } });
+Object.defineProperty(exports, "isImageBase64Content", { enumerable: true, get: function () { return types_2.isImageBase64Content; } });
+Object.defineProperty(exports, "isImageContent", { enumerable: true, get: function () { return types_2.isImageContent; } });
 /**
  * Manages conversation history in a provider-agnostic format.
  *
@@ -23,6 +88,10 @@ Object.defineProperty(exports, "isToolResultContent", { enumerable: true, get: f
  * History can be shared between agents of different providers, enabling
  * cross-provider conversations and handoffs.
  *
+ * Plugins can be registered with `history.use(plugin)` to add read-time
+ * transforms (e.g., tool result masking) or async reduce strategies
+ * (e.g., rolling LLM summarization).
+ *
  * @example Basic usage
  * ```typescript
  * const history = new History();
@@ -30,6 +99,19 @@ Object.defineProperty(exports, "isToolResultContent", { enumerable: true, get: f
  * history.addText("assistant", "Hi there!");
  * ```
  *
+ * @example With tool result masking plugin
+ * ```typescript
+ * import { toolResultMaskingPlugin } from "agention-lib/history/plugins";
+ *
+ * const maskingPlugin = toolResultMaskingPlugin({ keepRecentResults: 2 });
+ * const history = new History().use(maskingPlugin);
+ *
+ * const agent = new ClaudeAgent(
+ *   { tools: [maskingPlugin.retrieveTool, ...otherTools] },
+ *   history
+ * );
+ * ```
+ *
  * @example Sharing between agents
  * ```typescript
  * const history = new History();
@@ -43,6 +125,8 @@ class History extends events_1.default {
         super();
         this._entries = [];
         this.transient = false;
+        this._plugins = [];
+        this._reducing = false;
         this.options = options;
         this.transient = Boolean(options?.transient);
         // Convert initial entries to internal format with metadata
@@ -50,13 +134,39 @@ class History extends events_1.default {
             this.addEntry(entry);
         }
     }
+    // ===========================================================================
+    // Plugin registration
+    // ===========================================================================
+    /**
+     * Register a plugin with this history instance.
+     * Calls plugin.onRegistered(this) immediately after registration.
+     * Returns `this` for chaining.
+     *
+     * @example
+     * ```typescript
+     * history
+     *   .use(compressionPlugin(summaryAgent))
+     *   .use(toolResultMaskingPlugin({ keepRecentResults: 2 }));
+     * ```
+     */
+    use(plugin) {
+        this._plugins.push(plugin);
+        plugin.onRegistered?.(this);
+        return this;
+    }
+    // ===========================================================================
+    // Core write operations
+    // ===========================================================================
     /**
      * Add a complete history entry
      */
     addEntry(entry) {
+        const serialized = JSON.stringify(entry.content);
+        const contentLength = serialized.length;
         const __metadata = {
             date: new Date().toISOString(),
-            contentLength: JSON.stringify(entry.content).length,
+            contentLength,
+            estimatedTokens: estimateContentTokens(entry.content),
         };
         this._entries.push({
             ...entry,
@@ -65,7 +175,27 @@ class History extends events_1.default {
         if (this.options.maxLength && this._entries.length > this.options.maxLength) {
             this._entries = this._entries.slice(this._entries.length - this.options.maxLength);
         }
+        if (this.options.maxTokens) {
+            this.trimToTokenBudget();
+        }
         this.emit("entry", entry);
+        // Fire plugin afterAdd hooks. Skipped during reduce() to avoid recursion
+        // when compression plugins add summary entries to the history.
+        if (!this._reducing) {
+            for (const plugin of this._plugins) {
+                if (!plugin.afterAdd)
+                    continue;
+                void Promise.resolve(plugin.afterAdd(this)).catch((err) => {
+                    const error = err instanceof Error ? err : new Error(String(err));
+                    if (this.options.onPluginError) {
+                        this.options.onPluginError(error, plugin, "afterAdd");
+                    }
+                    else {
+                        this.emit("pluginError", error, plugin, "afterAdd");
+                    }
+                });
+            }
+        }
     }
     /**
      * Add a simple text message
@@ -88,8 +218,28 @@ class History extends events_1.default {
     addSystem(content) {
         this.addText("system", content);
     }
+    // ===========================================================================
+    // Read operations
+    // ===========================================================================
+    /**
+     * Get entries as agents should see them — with all registered transform
+     * plugins applied in registration order.
+     *
+     * Use this when building API requests. The raw `entries` getter is
+     * reserved for serialization, cloning, and other internal purposes.
+     */
+    getEntries() {
+        let entries = this._entries;
+        for (const plugin of this._plugins) {
+            if (plugin.transform) {
+                entries = plugin.transform(entries);
+            }
+        }
+        return entries.map(({ __metadata, ...rest }) => rest);
+    }
     /**
-     * Get all entries (without internal metadata)
+     * Get all entries without transform plugins applied (raw storage).
+     * Use for serialization, cloning, and debugging.
      */
     get entries() {
         return this._entries.map((entry) => {
@@ -97,6 +247,24 @@ class History extends events_1.default {
             return rest;
         });
     }
+    /**
+     * Get the full content of a tool result by its tool_use_id.
+     * Always reads from raw stored entries — never affected by transform plugins.
+     *
+     * For RedisHistory: call await load() before using this method.
+     *
+     * @returns The full result string, or undefined if not found.
+     */
+    getToolResult(tool_use_id) {
+        for (const entry of this._entries) {
+            for (const block of entry.content) {
+                if ((0, types_1.isToolResultContent)(block) && block.tool_use_id === tool_use_id) {
+                    return block.content;
+                }
+            }
+        }
+        return undefined;
+    }
     /**
      * Get the number of entries
      */
@@ -111,6 +279,15 @@ class History extends events_1.default {
             return total + __metadata.contentLength;
         }, 0);
     }
+    /**
+     * Get total estimated token count across all entries.
+     * Uses a rough approximation of 1 token ≈ 4 characters.
+     */
+    get totalEstimatedTokens() {
+        return this._entries.reduce((total, { __metadata }) => {
+            return total + __metadata.estimatedTokens;
+        }, 0);
+    }
     /**
      * Get the last entry
      */
@@ -133,11 +310,52 @@ class History extends events_1.default {
             .join("\n");
     }
     /**
-     * Get entries without system messages
+     * Get entries without system messages, with transform plugins applied.
      */
     getMessagesWithoutSystem() {
-        return this.entries.filter((e) => e.role !== "system");
+        return this.getEntries().filter((e) => e.role !== "system");
+    }
+    // ===========================================================================
+    // Async reduction
+    // ===========================================================================
+    /**
+     * Asynchronously compact history using registered reduce plugins.
+     *
+     * Plugins are called in registration order, each receiving and returning
+     * the full entry array. If no plugin has a `reduce` hook, this is a no-op —
+     * the addEntry() safety net (FIFO drop via maxTokens) runs independently.
+     *
+     * Re-entrant calls during an in-progress reduce() return immediately.
+     *
+     * @example Rolling summarization
+     * ```typescript
+     * history.use(compressionPlugin(summaryAgent));
+     * await history.reduce({ maxTokens: 4000 });
+     * ```
+     */
+    async reduce(options = {}) {
+        if (this._reducing)
+            return;
+        const hasReducePlugin = this._plugins.some((p) => Boolean(p.reduce));
+        if (!hasReducePlugin)
+            return;
+        this._reducing = true;
+        try {
+            let entries = [...this._entries];
+            for (const plugin of this._plugins) {
+                if (plugin.reduce) {
+                    entries = await plugin.reduce(entries, options);
+                }
+            }
+            this._entries = entries;
+        }
+        finally {
+            this._reducing = false;
+        }
     }
+    // ===========================================================================
+    // Utility
+    // ===========================================================================
     /**
      * Clear all history entries
      */
@@ -164,6 +382,25 @@ class History extends events_1.default {
     clone(options) {
         return new History(this.entries, options ?? this.options);
     }
+    // ===========================================================================
+    // Private helpers
+    // ===========================================================================
+    /**
+     * Drop oldest non-system entries until totalEstimatedTokens fits within budget.
+     * Called synchronously from addEntry() as a safety net.
+     * The system message is always preserved.
+     */
+    trimToTokenBudget(maxTokens) {
+        const budget = maxTokens ?? this.options.maxTokens;
+        if (!budget)
+            return;
+        while (this.totalEstimatedTokens > budget && this._entries.length > 1) {
+            const firstNonSystem = this._entries.findIndex((e) => e.role !== "system");
+            if (firstNonSystem === -1)
+                break;
+            this._entries.splice(firstNonSystem, 1);
+        }
+    }
 }
 exports.History = History;
 //# sourceMappingURL=History.js.map

package/dist/history/index.d.ts

@@ -0,0 +1,5 @@
+export { History, resetTokenxCache, type EntryMetadata, type ReducibleEntry, type HistoryPlugin, } from "./History";
+export { RedisHistory } from "./RedisHistory";
+export type { HistoryEntry, MessageRole, MessageContent, TextContent, ToolUseContent, ToolResultContent, ProviderMeta, ReduceOptions, } from "./types";
+export { text, toolUse, toolResult, textMessage, isTextContent, isToolUseContent, isToolResultContent, } from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/history/index.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isToolResultContent = exports.isToolUseContent = exports.isTextContent = exports.textMessage = exports.toolResult = exports.toolUse = exports.text = exports.RedisHistory = exports.resetTokenxCache = exports.History = void 0;
+var History_1 = require("./History");
+Object.defineProperty(exports, "History", { enumerable: true, get: function () { return History_1.History; } });
+Object.defineProperty(exports, "resetTokenxCache", { enumerable: true, get: function () { return History_1.resetTokenxCache; } });
+var RedisHistory_1 = require("./RedisHistory");
+Object.defineProperty(exports, "RedisHistory", { enumerable: true, get: function () { return RedisHistory_1.RedisHistory; } });
+var types_1 = require("./types");
+Object.defineProperty(exports, "text", { enumerable: true, get: function () { return types_1.text; } });
+Object.defineProperty(exports, "toolUse", { enumerable: true, get: function () { return types_1.toolUse; } });
+Object.defineProperty(exports, "toolResult", { enumerable: true, get: function () { return types_1.toolResult; } });
+Object.defineProperty(exports, "textMessage", { enumerable: true, get: function () { return types_1.textMessage; } });
+Object.defineProperty(exports, "isTextContent", { enumerable: true, get: function () { return types_1.isTextContent; } });
+Object.defineProperty(exports, "isToolUseContent", { enumerable: true, get: function () { return types_1.isToolUseContent; } });
+Object.defineProperty(exports, "isToolResultContent", { enumerable: true, get: function () { return types_1.isToolResultContent; } });
+//# sourceMappingURL=index.js.map

package/dist/history/plugins/compressionPlugin.d.ts

@@ -0,0 +1,54 @@
+import type { ReduceOptions } from "../types";
+import type { HistoryPlugin } from "../History";
+import type { BaseAgent } from "../../agents/BaseAgent";
+/** Options for {@link compressionPlugin}. */
+export type CompressionPluginOptions = {
+    /**
+     * When set, the plugin automatically calls `history.reduce()` from its
+     * `afterAdd` hook whenever the history exceeds the given threshold.
+     * The same `ReduceOptions` object is forwarded to `reduce()`.
+     *
+     * @example
+     * ```typescript
+     * history.use(compressionPlugin(summaryAgent, { autoReduceWhen: { maxTokens: 6000 } }));
+     * ```
+     */
+    autoReduceWhen?: ReduceOptions;
+};
+/**
+ * Creates a rolling-summary compression plugin.
+ *
+ * When `history.reduce(options)` is called, this plugin compresses old entries
+ * into a single summary entry using the provided agent. On subsequent reduces,
+ * the existing summary is included as prior context so the agent can extend it
+ * (rolling strategy) — at most one summary entry exists at any time.
+ *
+ * The summary entry uses `role: "user"` because no LLM provider has a
+ * dedicated summary role. Content is always wrapped as
+ * `[Earlier conversation summary: ...]` so it can be detected by pattern
+ * as well as the `isSummary` metadata flag.
+ *
+ * Pass `autoReduceWhen` to trigger compression automatically after every
+ * `addEntry()` call when the given threshold is exceeded — no manual
+ * `history.reduce()` call required.
+ *
+ * @example
+ * ```typescript
+ * const summaryAgent = new ClaudeAgent({
+ *   id: "summarizer",
+ *   name: "Summarizer",
+ *   description: "Summarizes conversation history",
+ *   apiKey: process.env.ANTHROPIC_API_KEY!,
+ *   model: "claude-haiku-4-5-20251001",
+ * });
+ *
+ * // Manual trigger
+ * history.use(compressionPlugin(summaryAgent));
+ * await history.reduce({ maxTokens: 4000 });
+ *
+ * // Automatic trigger
+ * history.use(compressionPlugin(summaryAgent, { autoReduceWhen: { maxTokens: 6000 } }));
+ * ```
+ */
+export declare function compressionPlugin(agent: BaseAgent, options?: CompressionPluginOptions): HistoryPlugin;
+//# sourceMappingURL=compressionPlugin.d.ts.map

package/dist/history/plugins/compressionPlugin.js

@@ -0,0 +1,143 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compressionPlugin = compressionPlugin;
+const types_1 = require("../types");
+/**
+ * Creates a rolling-summary compression plugin.
+ *
+ * When `history.reduce(options)` is called, this plugin compresses old entries
+ * into a single summary entry using the provided agent. On subsequent reduces,
+ * the existing summary is included as prior context so the agent can extend it
+ * (rolling strategy) — at most one summary entry exists at any time.
+ *
+ * The summary entry uses `role: "user"` because no LLM provider has a
+ * dedicated summary role. Content is always wrapped as
+ * `[Earlier conversation summary: ...]` so it can be detected by pattern
+ * as well as the `isSummary` metadata flag.
+ *
+ * Pass `autoReduceWhen` to trigger compression automatically after every
+ * `addEntry()` call when the given threshold is exceeded — no manual
+ * `history.reduce()` call required.
+ *
+ * @example
+ * ```typescript
+ * const summaryAgent = new ClaudeAgent({
+ *   id: "summarizer",
+ *   name: "Summarizer",
+ *   description: "Summarizes conversation history",
+ *   apiKey: process.env.ANTHROPIC_API_KEY!,
+ *   model: "claude-haiku-4-5-20251001",
+ * });
+ *
+ * // Manual trigger
+ * history.use(compressionPlugin(summaryAgent));
+ * await history.reduce({ maxTokens: 4000 });
+ *
+ * // Automatic trigger
+ * history.use(compressionPlugin(summaryAgent, { autoReduceWhen: { maxTokens: 6000 } }));
+ * ```
+ */
+function compressionPlugin(agent, options = {}) {
+    const { autoReduceWhen } = options;
+    function shouldAutoReduce(history) {
+        if (!autoReduceWhen)
+            return false;
+        if (autoReduceWhen.maxTokens !== undefined) {
+            return history.totalEstimatedTokens > autoReduceWhen.maxTokens;
+        }
+        if (autoReduceWhen.maxEntries !== undefined) {
+            return history.length > autoReduceWhen.maxEntries;
+        }
+        // olderThan: always trigger so reduce() can evaluate
+        if (autoReduceWhen.olderThan !== undefined)
+            return true;
+        return false;
+    }
+    return {
+        afterAdd(history) {
+            if (!autoReduceWhen)
+                return;
+            if (!shouldAutoReduce(history))
+                return;
+            // Fire-and-forget — History._reducing guard prevents re-entrancy
+            void history.reduce(autoReduceWhen);
+        },
+        async reduce(entries, options) {
+            const { maxTokens, maxEntries, olderThan } = options;
+            // Separate system entries — always preserved verbatim
+            const systemEntries = entries.filter((e) => e.role === "system");
+            const nonSystemEntries = entries.filter((e) => e.role !== "system");
+            if (nonSystemEntries.length === 0)
+                return entries;
+            // Determine which non-system entries to compress
+            let toCompress = [];
+            if (olderThan) {
+                const cutoff = olderThan.toISOString();
+                toCompress = nonSystemEntries.filter((e) => e.__metadata.date < cutoff);
+            }
+            else if (maxEntries !== undefined) {
+                const totalNonSystem = nonSystemEntries.length;
+                if (totalNonSystem <= maxEntries)
+                    return entries;
+                toCompress = nonSystemEntries.slice(0, totalNonSystem - maxEntries);
+            }
+            else if (maxTokens !== undefined) {
+                // Accumulate from oldest until we'd fit within budget
+                let totalTokens = entries.reduce((sum, e) => sum + e.__metadata.estimatedTokens, 0);
+                let i = 0;
+                while (totalTokens > maxTokens && i < nonSystemEntries.length) {
+                    toCompress.push(nonSystemEntries[i]);
+                    totalTokens -= nonSystemEntries[i].__metadata.estimatedTokens;
+                    i++;
+                }
+            }
+            if (toCompress.length === 0)
+                return entries;
+            // Build prompt — include existing rolling summary as prior context
+            const existingSummary = toCompress.find((e) => e.__metadata.isSummary);
+            const rawToCompress = toCompress.filter((e) => !e.__metadata.isSummary);
+            let prompt = "Produce a concise summary of the following conversation. " +
+                "Preserve key facts, decisions, and outcomes. " +
+                "Omit filler and repetition.\n\n";
+            if (existingSummary) {
+                const summaryText = existingSummary.content
+                    .filter(types_1.isTextContent)
+                    .map((c) => c.text)
+                    .join("\n");
+                prompt += `Prior context:\n${summaryText}\n\nAdditional turns to incorporate:\n`;
+            }
+            for (const entry of rawToCompress) {
+                const lines = entry.content
+                    .filter(types_1.isTextContent)
+                    .map((c) => c.text)
+                    .join(" ");
+                prompt += `[${entry.role}]: ${lines}\n`;
+            }
+            const summaryText = await agent.execute(prompt);
+            // Determine date range covered by this summary
+            const allCompressed = existingSummary
+                ? [existingSummary, ...rawToCompress]
+                : rawToCompress;
+            const earliestDate = existingSummary?.__metadata.coversRange?.from ??
+                allCompressed[0].__metadata.date;
+            const latestDate = allCompressed[allCompressed.length - 1].__metadata.date;
+            const content = `[Earlier conversation summary: ${summaryText}]`;
+            const __metadata = {
+                date: new Date().toISOString(),
+                contentLength: content.length,
+                estimatedTokens: Math.ceil(content.length / 4),
+                isSummary: true,
+                coversRange: { from: earliestDate, to: latestDate },
+            };
+            const summaryEntry = {
+                role: "user",
+                content: [(0, types_1.text)(content)],
+                __metadata,
+            };
+            const toCompressSet = new Set(toCompress);
+            const recent = nonSystemEntries.filter((e) => !toCompressSet.has(e));
+            return [...systemEntries, summaryEntry, ...recent];
+        },
+    };
+}
+//# sourceMappingURL=compressionPlugin.js.map

package/dist/history/plugins/index.d.ts

@@ -0,0 +1,3 @@
+export { compressionPlugin, type CompressionPluginOptions } from "./compressionPlugin";
+export { toolResultMaskingPlugin, type ToolResultMaskingPlugin, type ToolResultMaskingOptions, } from "./toolResultMaskingPlugin";
+//# sourceMappingURL=index.d.ts.map

package/dist/history/plugins/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toolResultMaskingPlugin = exports.compressionPlugin = void 0;
+var compressionPlugin_1 = require("./compressionPlugin");
+Object.defineProperty(exports, "compressionPlugin", { enumerable: true, get: function () { return compressionPlugin_1.compressionPlugin; } });
+var toolResultMaskingPlugin_1 = require("./toolResultMaskingPlugin");
+Object.defineProperty(exports, "toolResultMaskingPlugin", { enumerable: true, get: function () { return toolResultMaskingPlugin_1.toolResultMaskingPlugin; } });
+//# sourceMappingURL=index.js.map

package/dist/history/plugins/toolResultMaskingPlugin.d.ts

@@ -0,0 +1,66 @@
+import { Tool } from "../../tools/Tool";
+import type { HistoryPlugin } from "../History";
+export type ToolResultMaskingOptions = {
+    /**
+     * Number of most-recent tool results to keep verbatim.
+     * Older results are replaced with a reference marker.
+     * @default 2
+     */
+    keepRecentResults?: number;
+    /**
+     * Tool names that are never masked, regardless of age or size.
+     * Mutually exclusive with `include`.
+     */
+    exclude?: string[];
+    /**
+     * When set, only results from these tools are masked.
+     * Mutually exclusive with `exclude`.
+     */
+    include?: string[];
+    /**
+     * Skip masking for results whose estimated token count is below this
+     * threshold. Small results don't consume a `keepRecentResults` slot.
+     */
+    minTokensToMask?: number;
+};
+/**
+ * A HistoryPlugin with an attached `retrieveTool`.
+ * Register the plugin with `history.use(maskingPlugin)`, then add
+ * `maskingPlugin.retrieveTool` to the agent's tool list so the model can
+ * fetch masked results on demand.
+ */
+export type ToolResultMaskingPlugin = HistoryPlugin & {
+    /** Tool the agent can call to retrieve a masked result by its tool_use_id. */
+    readonly retrieveTool: Tool<string>;
+};
+/**
+ * Creates a read-time tool result masking plugin.
+ *
+ * Old tool results are replaced with a reference marker `[MASKED - ref: <id>]`
+ * at read time via `history.getEntries()`. Stored entries are never mutated —
+ * the full content is always available via `history.getToolResult(id)` or the
+ * attached `retrieveTool`.
+ *
+ * Only results that pass the include/exclude/minTokensToMask filters are
+ * candidates for masking. Filtered-out results stay verbatim and do not
+ * consume a `keepRecentResults` slot.
+ *
+ * @throws If both `exclude` and `include` are provided.
+ *
+ * @example
+ * ```typescript
+ * const maskingPlugin = toolResultMaskingPlugin({
+ *   keepRecentResults: 2,
+ *   exclude: ["calculator", "get_date"],
+ *   minTokensToMask: 50,
+ * });
+ *
+ * history.use(maskingPlugin);
+ *
+ * const agent = new ClaudeAgent({
+ *   tools: [maskingPlugin.retrieveTool, ...otherTools],
+ * }, history);
+ * ```
+ */
+export declare function toolResultMaskingPlugin(options?: ToolResultMaskingOptions): ToolResultMaskingPlugin;
+//# sourceMappingURL=toolResultMaskingPlugin.d.ts.map