@agentionai/agents 0.8.1-beta → 0.9.0

package/dist/agents/AgentConfig.d.ts

@@ -18,6 +18,12 @@ export interface CommonAgentConfig {
     debug?: boolean;
     /** Maximum number of messages to retain in conversation history */
     maxHistoryLength?: number;
+    /**
+     * Maximum estimated tokens to retain in conversation history.
+     * When exceeded, oldest non-system entries are dropped.
+     * Takes precedence over maxHistoryLength for context-window-aware trimming.
+     */
+    maxHistoryTokens?: number;
     /** Model identifier (e.g., "claude-3-5-sonnet-20241022", "gpt-4") */
     model?: string;
     /** Array of tools the agent can use during execution */

package/dist/agents/BaseAgent.d.ts

@@ -22,13 +22,13 @@ export type TokenUsage = {
  * Handles the BaseConfig
  */
 export declare abstract class BaseAgent<TInput = unknown, TOutput = unknown> extends EventEmitter {
-    protected history: History;
     protected id: string;
     protected debug: boolean;
     protected name: string;
     protected description: string;
     protected tools: Map<string, Tool<unknown>>;
     protected maxHistoryLength: number;
+    protected history: History;
     /** The vendor/provider for this agent (anthropic, openai, mistral, gemini) */
     protected vendor: AgentVendor;
     /** The model identifier for this agent */

package/dist/agents/BaseAgent.js

@@ -21,9 +21,8 @@ class BaseAgent extends events_1.default {
      *                 prompts, then supply a History object.
      *
      */
-    constructor(config, history = new History_1.History([], { transient: true })) {
+    constructor(config, history) {
         super();
-        this.history = history;
         this.debug = true;
         this.id = config.id;
         this.debug = config.debug || false;
@@ -31,6 +30,12 @@ class BaseAgent extends events_1.default {
         this.description = config.description;
         this.vendor = config.vendor;
         this.model = config.model || "unknown";
+        this.maxHistoryLength = config.maxHistoryLength || 100;
+        this.history = history ?? new History_1.History([], {
+            transient: true,
+            maxLength: config.maxHistoryLength,
+            maxTokens: config.maxHistoryTokens,
+        });
         if (config.agents) {
             const agentTools = config.agents.map((agent) => {
                 return Tool_1.Tool.fromAgent(agent, `You can use this agent ${agent.getName()} to execute tasks`);
@@ -40,7 +45,6 @@ class BaseAgent extends events_1.default {
                 : agentTools;
         }
         this.tools = new Map((config.tools || []).map((tool) => [tool.name, tool]));
-        this.maxHistoryLength = config.maxHistoryLength || 100;
     }
     getToolDefinitions() {
         return Array.from(this.tools.values()).map((tool) => tool.getPrompt());
@@ -108,7 +112,7 @@ class BaseAgent extends events_1.default {
         return this.model;
     }
     getHistoryEntries() {
-        return this.history.entries;
+        return this.history.getEntries();
     }
     getTools() {
         return [...this.tools.values()];

package/dist/agents/anthropic/ClaudeAgent.js

@@ -75,7 +75,7 @@ class ClaudeAgent extends BaseAgent_1.BaseAgent {
         }
         this.addTextToHistory("user", input);
         try {
-            const messages = transformers_1.anthropicTransformer.toProvider(this.history.entries);
+            const messages = transformers_1.anthropicTransformer.toProvider(this.history.getEntries());
             const systemMessage = this.history.getSystemMessage();
             const response = await this.client.messages.create({
                 model: this.config.model,
@@ -177,7 +177,7 @@ class ClaudeAgent extends BaseAgent_1.BaseAgent {
                 this.addMessageToHistory("user", toolResults);
                 // Continue conversation with tool results
                 try {
-                    const messages = transformers_1.anthropicTransformer.toProvider(this.history.entries);
+                    const messages = transformers_1.anthropicTransformer.toProvider(this.history.getEntries());
                     const newResponse = await this.client.messages.create({
                         model: this.config.model,
                         max_tokens: this.config.maxTokens,
@@ -224,6 +224,12 @@ class ClaudeAgent extends BaseAgent_1.BaseAgent {
         }
         // Track tool call count for viz reporting
         this.currentToolCallCount += toolUseBlocks.length;
+        const agentSource = {
+            agentId: this.getId(),
+            agentName: this.getName(),
+            model: this.config.model,
+            vendor: "anthropic",
+        };
         const results = await Promise.all(toolUseBlocks.map(async (block) => {
             const tool = this.tools.get(block.name);
             if (!tool) {
@@ -232,10 +238,20 @@ class ClaudeAgent extends BaseAgent_1.BaseAgent {
                 if (this.debug) {
                     console.error(error);
                 }
+                if (VizConfig_1.vizConfig.isEnabled()) {
+                    const vizEventId = VizReporter_1.vizReporter.toolStart(block.name, block.id, block.input, agentSource);
+                    VizReporter_1.vizReporter.toolError(vizEventId, block.name, block.id, errorMessage);
+                }
                 return (0, History_1.toolResult)(block.id, errorMessage, true);
             }
+            const vizEventId = VizConfig_1.vizConfig.isEnabled()
+                ? VizReporter_1.vizReporter.toolStart(block.name, block.id, block.input, agentSource)
+                : undefined;
             try {
                 const result = await tool.execute(this.getId(), this.getName(), block.input, block.id, this.config.model, "anthropic");
+                if (vizEventId) {
+                    VizReporter_1.vizReporter.toolComplete(vizEventId, block.name, block.id, true, result);
+                }
                 return (0, History_1.toolResult)(block.id, JSON.stringify(result));
             }
             catch (error) {
@@ -245,6 +261,9 @@ class ClaudeAgent extends BaseAgent_1.BaseAgent {
                 }
                 const toolError = new AgentError_1.ToolExecutionError(errorMessage, block.name, block.input);
                 this.emit(AgentEvent_1.AgentEvent.TOOL_ERROR, toolError);
+                if (vizEventId) {
+                    VizReporter_1.vizReporter.toolError(vizEventId, block.name, block.id, errorMessage);
+                }
                 return (0, History_1.toolResult)(block.id, errorMessage, true);
             }
         }));

package/dist/agents/google/GeminiAgent.js

@@ -176,7 +176,7 @@ class GeminiAgent extends BaseAgent_1.BaseAgent {
         }
         this.addTextToHistory("user", input);
         try {
-            const contents = transformers_1.geminiTransformer.toProvider(this.history.entries);
+            const contents = transformers_1.geminiTransformer.toProvider(this.history.getEntries());
             const systemMessage = this.history.getSystemMessage();
             const tools = this.getToolDefinitionsForGemini();
             const response = await this.generativeModel.generateContent({
@@ -290,7 +290,7 @@ class GeminiAgent extends BaseAgent_1.BaseAgent {
             }
             // Continue conversation
             try {
-                const newContents = transformers_1.geminiTransformer.toProvider(this.history.entries);
+                const newContents = transformers_1.geminiTransformer.toProvider(this.history.getEntries());
                 const systemMessage = this.history.getSystemMessage();
                 const tools = this.getToolDefinitionsForGemini();
                 const newResponse = await this.generativeModel.generateContent({

package/dist/agents/mistral/MistralAgent.js

@@ -86,7 +86,7 @@ class MistralAgent extends BaseAgent_1.BaseAgent {
         }
         this.addTextToHistory("user", input);
         try {
-            const messages = transformers_1.mistralTransformer.toProvider(this.history.entries);
+            const messages = transformers_1.mistralTransformer.toProvider(this.history.getEntries());
             const response = await this.client.chat.complete({
                 model: this.config.model,
                 messages: messages,
@@ -202,7 +202,7 @@ class MistralAgent extends BaseAgent_1.BaseAgent {
                 await (0, promises_1.setTimeout)(this.config.rateLimitDelay || 1500);
                 // Continue conversation
                 try {
-                    const messages = transformers_1.mistralTransformer.toProvider(this.history.entries);
+                    const messages = transformers_1.mistralTransformer.toProvider(this.history.getEntries());
                     const newResponse = await this.client.chat.complete({
                         model: this.config.model,
                         messages: messages,

package/dist/agents/openai/OpenAiAgent.js

@@ -97,7 +97,7 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
         }
         this.addTextToHistory("user", input);
         try {
-            const inputMessages = transformers_1.openAiTransformer.toProvider(this.history.entries);
+            const inputMessages = transformers_1.openAiTransformer.toProvider(this.history.getEntries());
             const response = await this.client.responses.create({
                 model: this.config.model,
                 max_output_tokens: this.config.maxTokens,
@@ -216,7 +216,7 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
                 }
                 // Continue conversation
                 try {
-                    const inputMessages = transformers_1.openAiTransformer.toProvider(this.history.entries);
+                    const inputMessages = transformers_1.openAiTransformer.toProvider(this.history.getEntries());
                     const newResponse = await this.client.responses.create({
                         model: this.config.model,
                         max_output_tokens: this.config.maxTokens,

package/dist/history/History.d.ts

@@ -1,22 +1,80 @@
 import EventEmitter from "events";
 import { HistoryEntry, MessageRole, MessageContent } from "./types";
-export type { HistoryEntry, MessageRole, MessageContent } from "./types";
+import type { ReduceOptions } from "./types";
+/** @internal — exposed for test teardown only */
+export declare function resetTokenxCache(): void;
+export type { HistoryEntry, MessageRole, MessageContent, ReduceOptions } from "./types";
 export { text, toolUse, toolResult, textMessage, isTextContent, isToolUseContent, isToolResultContent, } from "./types";
 /**
- * Internal entry with metadata
+ * Metadata stored alongside each history entry.
+ * Extended with summary tracking fields for the compression plugin.
  */
-type EntryWithMetadata = HistoryEntry & {
-    __metadata: {
-        date: string;
-        contentLength: number;
+export type EntryMetadata = {
+    date: string;
+    contentLength: number;
+    estimatedTokens: number;
+    /**
+     * True when this entry was produced by a compression plugin as a rolling
+     * summary of earlier turns. Used so subsequent compressions can include
+     * the existing summary as prior context rather than treating it as a
+     * regular conversation turn.
+     */
+    isSummary?: boolean;
+    /**
+     * ISO date range covered by a summary entry.
+     * Only present when isSummary is true.
+     */
+    coversRange?: {
+        from: string;
+        to: string;
     };
 };
+/**
+ * A history entry with its internal metadata attached.
+ * Passed to plugin reduce() and transform() hooks.
+ */
+export type ReducibleEntry = HistoryEntry & {
+    __metadata: EntryMetadata;
+};
+/**
+ * A history plugin. Register with `history.use(plugin)`.
+ *
+ * Hooks:
+ * - `onRegistered` — called once immediately when the plugin is registered
+ * - `afterAdd` — called fire-and-forget after every addEntry(); errors are
+ *   routed to the `onPluginError` option / `"pluginError"` event, never thrown
+ * - `reduce` — called by history.reduce(); receives and returns the full
+ *   entry array; plugins are piped in registration order
+ * - `transform` — pure read-time rewrite; called by history.getEntries();
+ *   sync, cheap, must not mutate stored entries; applied in registration order
+ */
+export type HistoryPlugin = {
+    onRegistered?: (history: History) => void;
+    afterAdd?: (history: History) => void | Promise<void>;
+    reduce?: (entries: ReducibleEntry[], options: ReduceOptions) => Promise<ReducibleEntry[]>;
+    transform?: (entries: ReducibleEntry[]) => ReducibleEntry[];
+};
+/**
+ * Internal entry with metadata
+ */
+type EntryWithMetadata = ReducibleEntry;
 /**
  * History configuration options
  */
 type HistoryOptions = {
     maxLength?: number;
+    /**
+     * Maximum estimated tokens to retain in history. When exceeded, oldest
+     * non-system entries are dropped via the addEntry() safety net.
+     * The system message is always preserved.
+     */
+    maxTokens?: number;
     transient?: boolean;
+    /**
+     * Called when a plugin's afterAdd hook throws. If not provided, the error
+     * is re-emitted as a "pluginError" event on the History instance.
+     */
+    onPluginError?: (error: Error, plugin: HistoryPlugin, hook: "afterAdd") => void;
 };
 /**
  * Manages conversation history in a provider-agnostic format.
@@ -27,6 +85,10 @@ type HistoryOptions = {
  * 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();
@@ -34,6 +96,19 @@ type HistoryOptions = {
  * 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();
@@ -46,7 +121,22 @@ export declare class History extends EventEmitter {
     protected _entries: EntryWithMetadata[];
     private options;
     transient: boolean;
+    private _plugins;
+    private _reducing;
     constructor(entries?: HistoryEntry[], options?: HistoryOptions);
+    /**
+     * 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: HistoryPlugin): this;
     /**
      * Add a complete history entry
      */
@@ -64,9 +154,27 @@ export declare class History extends EventEmitter {
      */
     addSystem(content: string): void;
     /**
-     * Get all entries (without internal metadata)
+     * 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(): HistoryEntry[];
+    /**
+     * Get all entries without transform plugins applied (raw storage).
+     * Use for serialization, cloning, and debugging.
      */
     get entries(): HistoryEntry[];
+    /**
+     * 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: string): string | undefined;
     /**
      * Get the number of entries
      */
@@ -75,6 +183,11 @@ export declare class History extends EventEmitter {
      * Get total content size in characters
      */
     get size(): number;
+    /**
+     * Get total estimated token count across all entries.
+     * Uses a rough approximation of 1 token ≈ 4 characters.
+     */
+    get totalEstimatedTokens(): number;
     /**
      * Get the last entry
      */
@@ -84,9 +197,25 @@ export declare class History extends EventEmitter {
      */
     getSystemMessage(): string | undefined;
     /**
-     * Get entries without system messages
+     * Get entries without system messages, with transform plugins applied.
      */
     getMessagesWithoutSystem(): HistoryEntry[];
+    /**
+     * 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 });
+     * ```
+     */
+    reduce(options?: ReduceOptions): Promise<void>;
     /**
      * Clear all history entries
      */
@@ -103,5 +232,11 @@ export declare class History extends EventEmitter {
      * Create a copy of this history
      */
     clone(options?: HistoryOptions): History;
+    /**
+     * Drop oldest non-system entries until totalEstimatedTokens fits within budget.
+     * Called synchronously from addEntry() as a safety net.
+     * The system message is always preserved.
+     */
+    private trimToTokenBudget;
 }
 //# sourceMappingURL=History.d.ts.map

package/dist/history/History.js

@@ -1,11 +1,58 @@
 "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.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);
+}
 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; } });
@@ -23,6 +70,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 +81,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 +107,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 +116,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: _estimateTokenCount(serialized),
         };
         this._entries.push({
             ...entry,
@@ -65,7 +157,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 +200,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 +229,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 +261,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 +292,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 +364,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

package/dist/history/plugins/toolResultMaskingPlugin.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toolResultMaskingPlugin = toolResultMaskingPlugin;
+const Tool_1 = require("../../tools/Tool");
+const types_1 = require("../types");
+/**
+ * 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);
+ * ```
+ */
+function toolResultMaskingPlugin(options) {
+    const { keepRecentResults = 2, exclude, include, minTokensToMask, } = options ?? {};
+    if (exclude && include) {
+        throw new Error("toolResultMaskingPlugin: `exclude` and `include` are mutually exclusive");
+    }
+    if (keepRecentResults === 0) {
+        console.warn("[toolResultMaskingPlugin] keepRecentResults: 0 masks all tool results. " +
+            "Ensure maskingPlugin.retrieveTool is added to the agent's tool list.");
+    }
+    // History reference captured at registration time via onRegistered
+    let _history;
+    const retrieveTool = new Tool_1.Tool({
+        name: "retrieve_tool_result",
+        description: "Retrieve the full result of a previous tool call that has been masked " +
+            "in the conversation history. Use this when you need to re-examine an " +
+            "earlier tool result.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                tool_call_id: {
+                    type: "string",
+                    description: "The tool_use_id of the masked tool result to retrieve",
+                },
+            },
+            required: ["tool_call_id"],
+        },
+        execute: async (input) => {
+            if (!_history) {
+                throw new Error("retrieve_tool_result: plugin has not been registered with a history " +
+                    "instance. Call history.use(maskingPlugin) before executing the agent.");
+            }
+            const result = _history.getToolResult(input.tool_call_id);
+            if (result === undefined) {
+                return `No tool result found for id: ${input.tool_call_id}`;
+            }
+            return result;
+        },
+    });
+    const plugin = {
+        get retrieveTool() {
+            return retrieveTool;
+        },
+        onRegistered(history) {
+            _history = history;
+        },
+        transform(entries) {
+            // First pass: build a map of tool_use_id → tool_name from tool_use blocks
+            const toolNameById = new Map();
+            for (const entry of entries) {
+                for (const block of entry.content) {
+                    if ((0, types_1.isToolUseContent)(block)) {
+                        toolNameById.set(block.id, block.name);
+                    }
+                }
+            }
+            const maskable = [];
+            for (let ei = 0; ei < entries.length; ei++) {
+                const entry = entries[ei];
+                for (let bi = 0; bi < entry.content.length; bi++) {
+                    const block = entry.content[bi];
+                    if (!(0, types_1.isToolResultContent)(block))
+                        continue;
+                    const toolName = toolNameById.get(block.tool_use_id) ?? "";
+                    // include mode: only mask listed tools
+                    if (include && !include.includes(toolName))
+                        continue;
+                    // exclude mode: skip listed tools
+                    if (exclude && exclude.includes(toolName))
+                        continue;
+                    // minTokensToMask: skip small results
+                    if (minTokensToMask !== undefined) {
+                        const estimatedTokens = Math.ceil(block.content.length / 4);
+                        if (estimatedTokens < minTokensToMask)
+                            continue;
+                    }
+                    maskable.push({ entryIdx: ei, blockIdx: bi, id: block.tool_use_id });
+                }
+            }
+            // Determine which maskable results to mask (all but the last N)
+            const toMask = new Set();
+            const keepFrom = Math.max(0, maskable.length - keepRecentResults);
+            for (let i = 0; i < keepFrom; i++) {
+                toMask.add(maskable[i].id);
+            }
+            if (toMask.size === 0)
+                return entries;
+            // Third pass: build new entry array with masked content (never mutate originals)
+            return entries.map((entry) => {
+                const needsChange = entry.content.some((block) => (0, types_1.isToolResultContent)(block) && toMask.has(block.tool_use_id));
+                if (!needsChange)
+                    return entry;
+                const newContent = entry.content.map((block) => {
+                    if ((0, types_1.isToolResultContent)(block) && toMask.has(block.tool_use_id)) {
+                        return {
+                            ...block,
+                            content: `[MASKED - ref: ${block.tool_use_id}]`,
+                        };
+                    }
+                    return block;
+                });
+                return { ...entry, content: newContent };
+            });
+        },
+    };
+    return plugin;
+}
+//# sourceMappingURL=toolResultMaskingPlugin.js.map

package/dist/history/types.d.ts

@@ -127,4 +127,16 @@ export declare function toolResult(tool_use_id: string, content: string, is_erro
  * Create a simple text message entry
  */
 export declare function textMessage(role: MessageRole, value: string): HistoryEntry;
+/**
+ * Options controlling how history.reduce() compacts stored entries.
+ * All fields are optional — supply whichever constraints apply.
+ */
+export type ReduceOptions = {
+    /** Compress/drop entries until total estimated tokens fall below this value. */
+    maxTokens?: number;
+    /** Compress/drop entries until the entry count falls below this value. */
+    maxEntries?: number;
+    /** Compress/drop entries whose timestamp predates this date. */
+    olderThan?: Date;
+};
 //# sourceMappingURL=types.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agentionai/agents",
   "author": "Laurent Zuijdwijk",
-  "version": "0.8.1-beta",
+  "version": "0.9.0",
   "description": "Agent Library",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -53,6 +53,14 @@
     "./ingestion": {
       "types": "./dist/ingestion/index.d.ts",
       "default": "./dist/ingestion/index.js"
+    },
+    "./history": {
+      "types": "./dist/history/index.d.ts",
+      "default": "./dist/history/index.js"
+    },
+    "./history/plugins": {
+      "types": "./dist/history/plugins/index.d.ts",
+      "default": "./dist/history/plugins/index.js"
     }
   },
   "files": [