@agentionai/agents 0.8.1 → 0.10.0

package/README.md

@@ -73,6 +73,7 @@ import { ClaudeAgent, OpenAiAgent } from '@agentionai/agents';
 
 - **Multi-Provider, No Lock-in** - Claude, OpenAI, Gemini, Mistral—same interface. Switch models with one line.
 - **Composable, Not Magical** - Agents are objects. Pipelines are arrays. No hidden state, no surprises.
+- **Multimodal / Vision** - Send images alongside text with a unified `MessageContent[]` API across all providers.
 - **Full Observability** - Per-call token counts, execution timing, pipeline structure visualization.
 - **TypeScript-Native** - Strict typing, interfaces, and generics from the ground up.
 - **RAG Ready** - LanceDB vector store, token-aware chunking, ingestion pipeline out of the box.
@@ -175,6 +176,43 @@ const researcher = new ClaudeAgent({
 const result = await researcher.execute('Latest developments in quantum computing');
 ```
 
+### Multimodal / Vision
+
+Send images alongside text using `imageUrl()` or `imageBase64()`. The same `MessageContent[]` interface works across all providers:
+
+```typescript
+import { ClaudeAgent } from '@agentionai/agents/claude';
+import { imageUrl, imageBase64 } from '@agentionai/agents/core';
+import * as fs from 'fs';
+
+const agent = new ClaudeAgent({
+  apiKey: process.env.ANTHROPIC_API_KEY,
+  model: 'claude-opus-4-6',
+  name: 'VisionAgent',
+  description: 'You analyze images.',
+});
+
+// Remote image by URL
+const response = await agent.execute([
+  imageUrl('https://example.com/chart.png'),
+  { type: 'text', text: 'Summarize this chart in one sentence.' },
+]);
+
+// Local image as base64
+const data = fs.readFileSync('./photo.jpg').toString('base64');
+const response2 = await agent.execute([
+  imageBase64(data, 'image/jpeg'),
+  { type: 'text', text: 'What plant is this?' },
+]);
+```
+
+| Provider | URL | Base64 |
+|----------|:---:|:------:|
+| Claude | ✅ | ✅ |
+| OpenAI | ✅ | ✅ |
+| Gemini | ✅ | ✅ |
+| Mistral | ✅ | ❌ |
+
 ## Core Concepts
 
 ### Agents
@@ -187,6 +225,11 @@ JSON Schema + handler pattern. Unique capability: wrap any agent as a tool for d
 
 [Learn more →](https://docs.agention.ai/guide/tools)
 
+### Multimodal / Vision
+Unified `MessageContent[]` interface for images across all providers. URL and base64 images, mix text and images freely in a single call.
+
+[Learn more →](https://docs.agention.ai/guide/multimodal)
+
 ### History
 Provider-agnostic, persistent (Redis, file, custom), shareable across agents of different providers.
 
@@ -213,6 +256,7 @@ Per-call and per-node token counts, duration metrics, full execution visibility.
 - **[Quick Start](https://docs.agention.ai/guide/quickstart)** - Build a weather assistant in 5 minutes
 - **[Agents](https://docs.agention.ai/guide/agents)** - Agent configuration and providers
 - **[Tools](https://docs.agention.ai/guide/tools)** - Adding capabilities and agent delegation
+- **[Multimodal / Vision](https://docs.agention.ai/guide/multimodal)** - Sending images across all providers
 - **[Graph Pipelines](https://docs.agention.ai/guide/graph-pipelines)** - Multi-agent workflows
 - **[Vector Stores](https://docs.agention.ai/guide/vector-stores)** - RAG and semantic search
 - **[Examples](https://docs.agention.ai/guide/examples)** - Real-world implementations

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

@@ -1,8 +1,8 @@
 import EventEmitter from "events";
 import { Tool } from "../tools/Tool";
-import { History, HistoryEntry, MessageRole, MessageContent } from "../history/History";
+import { History, HistoryEntry, MessageRole, MessageContent, ImageMimeType } from "../history/History";
 import { AgentVendor, CommonAgentConfig, VendorSpecificConfig } from "./AgentConfig";
-export type { HistoryEntry, MessageRole, MessageContent };
+export type { HistoryEntry, MessageRole, MessageContent, ImageMimeType };
 export type { AgentVendor };
 /**
  * Agent config as used across all agents
@@ -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.d.ts

@@ -1,7 +1,7 @@
 import { Message, Usage } from "@anthropic-ai/sdk/resources";
 import { type ToolDefinition } from "../../tools/Tool";
 import { BaseAgent, BaseAgentConfig, TokenUsage } from "../BaseAgent";
-import { History } from "../../history/History";
+import { History, MessageContent } from "../../history/History";
 import { ClaudeModel } from "../model-types";
 type AgentConfig = BaseAgentConfig & {
     apiKey: string;
@@ -37,7 +37,7 @@ export declare class ClaudeAgent extends BaseAgent {
     constructor(config: Omit<AgentConfig, "vendor">, history?: History);
     protected getToolDefinitions(): ToolDefinition[];
     protected process(_input: string): Promise<string>;
-    execute(input: string): Promise<string>;
+    execute(input: string | MessageContent[]): Promise<string>;
     protected handleResponse(response: Message): Promise<string>;
     private handleToolUse;
     protected parseUsage(input: Usage): TokenUsage;

package/dist/agents/anthropic/ClaudeAgent.js

@@ -64,18 +64,25 @@ class ClaudeAgent extends BaseAgent_1.BaseAgent {
         // Reset token usage for this execution
         this.lastTokenUsage = undefined;
         this.currentToolCallCount = 0;
+        // Normalise input to a display string for viz reporting
+        const inputPreview = typeof input === "string" ? input : JSON.stringify(input);
         // Start visualization reporting
         if (VizConfig_1.vizConfig.isEnabled()) {
-            this.vizEventId = VizReporter_1.vizReporter.agentStart(this.id, this.name, this.config.model, "anthropic", input);
+            this.vizEventId = VizReporter_1.vizReporter.agentStart(this.id, this.name, this.config.model, "anthropic", inputPreview);
         }
         if (this.history.transient) {
             this.history.clear();
             // Re-add system message after clear
             this.addSystemMessage(this.getSystemMessage());
         }
-        this.addTextToHistory("user", input);
+        if (typeof input === "string") {
+            this.addTextToHistory("user", input);
+        }
+        else {
+            this.addMessageToHistory("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,9 +184,10 @@ 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,
+                        system: this.history.getSystemMessage(),
                         max_tokens: this.config.maxTokens,
                         messages,
                         tools: this.getToolDefinitions(),
@@ -224,6 +232,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 +246,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 +269,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.d.ts

@@ -1,6 +1,6 @@
 import { FunctionDeclarationsTool, GenerateContentResult, Schema } from "@google/generative-ai";
 import { BaseAgent, BaseAgentConfig, TokenUsage } from "../BaseAgent";
-import { History } from "../../history/History";
+import { History, MessageContent } from "../../history/History";
 import { GeminiModel } from "../model-types";
 type AgentConfig = BaseAgentConfig & {
     apiKey: string;
@@ -50,7 +50,7 @@ export declare class GeminiAgent extends BaseAgent {
      */
     private mapJsonSchemaTypeToGemini;
     protected process(_input: string): Promise<string>;
-    execute(input: string): Promise<string>;
+    execute(input: string | MessageContent[]): Promise<string>;
     protected handleResponse(response: GenerateContentResult): Promise<string>;
     private handleFunctionCalls;
     protected parseUsage(input: {

package/dist/agents/google/GeminiAgent.js

@@ -165,18 +165,24 @@ class GeminiAgent extends BaseAgent_1.BaseAgent {
         // Reset token usage for this execution
         this.lastTokenUsage = undefined;
         this.currentToolCallCount = 0;
+        const inputPreview = typeof input === "string" ? input : JSON.stringify(input);
         // Start visualization reporting
         if (VizConfig_1.vizConfig.isEnabled()) {
-            this.vizEventId = VizReporter_1.vizReporter.agentStart(this.id, this.name, this.config.model, "gemini", input);
+            this.vizEventId = VizReporter_1.vizReporter.agentStart(this.id, this.name, this.config.model, "gemini", inputPreview);
         }
         if (this.history.transient) {
             this.history.clear();
             // Re-add system message after clear
             this.addSystemMessage(this.getSystemMessage());
         }
-        this.addTextToHistory("user", input);
+        if (typeof input === "string") {
+            this.addTextToHistory("user", input);
+        }
+        else {
+            this.addMessageToHistory("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 +296,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.d.ts

@@ -1,5 +1,5 @@
 import { BaseAgent, BaseAgentConfig, TokenUsage } from "../BaseAgent";
-import { History } from "../../history/History";
+import { History, MessageContent } from "../../history/History";
 import { ChatCompletionResponse, Tool, UsageInfo } from "@mistralai/mistralai/models/components";
 import { MistralModel } from "../model-types";
 type AgentConfig = BaseAgentConfig & {
@@ -38,7 +38,7 @@ export declare class MistralAgent extends BaseAgent {
     constructor(config: Omit<AgentConfig, "vendor">, history?: History);
     protected getToolDefinitions(): Tool[];
     protected process(_input: string): Promise<string>;
-    execute(input: string): Promise<string>;
+    execute(input: string | MessageContent[]): Promise<string>;
     protected handleResponse(response: ChatCompletionResponse): Promise<string>;
     private handleToolCalls;
     protected parseUsage(input: UsageInfo): TokenUsage;

package/dist/agents/mistral/MistralAgent.js

@@ -75,18 +75,24 @@ class MistralAgent extends BaseAgent_1.BaseAgent {
         // Reset token usage for this execution
         this.lastTokenUsage = undefined;
         this.currentToolCallCount = 0;
+        const inputPreview = typeof input === "string" ? input : JSON.stringify(input);
         // Start visualization reporting
         if (VizConfig_1.vizConfig.isEnabled()) {
-            this.vizEventId = VizReporter_1.vizReporter.agentStart(this.id, this.name, this.config.model, "mistral", input);
+            this.vizEventId = VizReporter_1.vizReporter.agentStart(this.id, this.name, this.config.model, "mistral", inputPreview);
         }
         if (this.history.transient) {
             this.history.clear();
             // Re-add system message after clear
             this.addSystemMessage(this.getSystemMessage());
         }
-        this.addTextToHistory("user", input);
+        if (typeof input === "string") {
+            this.addTextToHistory("user", input);
+        }
+        else {
+            this.addMessageToHistory("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 +208,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.d.ts

@@ -1,5 +1,5 @@
 import { BaseAgent, BaseAgentConfig, TokenUsage } from "../BaseAgent";
-import { History } from "../../history/History";
+import { History, MessageContent } from "../../history/History";
 import { Tool, Response, ResponseUsage } from "openai/resources/responses/responses";
 import { OpenAIModel } from "../model-types";
 type AgentConfig = BaseAgentConfig & {
@@ -39,7 +39,7 @@ export declare class OpenAiAgent extends BaseAgent {
     constructor(config: Omit<AgentConfig, "vendor">, history?: History);
     protected getToolDefinitions(): Tool[];
     protected process(_input: string): Promise<string>;
-    execute(input: string): Promise<string>;
+    execute(input: string | MessageContent[]): Promise<string>;
     protected handleResponse(response: Response): Promise<string>;
     private handleToolUse;
     protected parseUsage(input: ResponseUsage): TokenUsage;

package/dist/agents/openai/OpenAiAgent.js

@@ -86,18 +86,24 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
         // Reset token usage for this execution
         this.lastTokenUsage = undefined;
         this.currentToolCallCount = 0;
+        const inputPreview = typeof input === "string" ? input : JSON.stringify(input);
         // Start visualization reporting
         if (VizConfig_1.vizConfig.isEnabled()) {
-            this.vizEventId = VizReporter_1.vizReporter.agentStart(this.id, this.name, this.config.model, "openai", input);
+            this.vizEventId = VizReporter_1.vizReporter.agentStart(this.id, this.name, this.config.model, "openai", inputPreview);
         }
         if (this.history.transient) {
             this.history.clear();
             // Re-add system message after clear
             this.addSystemMessage(this.getSystemMessage());
         }
-        this.addTextToHistory("user", input);
+        if (typeof input === "string") {
+            this.addTextToHistory("user", input);
+        }
+        else {
+            this.addMessageToHistory("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 +222,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";
-export { text, toolUse, toolResult, textMessage, isTextContent, isToolUseContent, isToolResultContent, } from "./types";
+import type { ReduceOptions } from "./types";
+/** @internal — exposed for test teardown only */
+export declare function resetTokenxCache(): void;
+export type { HistoryEntry, MessageRole, MessageContent, ReduceOptions, ImageMimeType, ImageUrlContent, ImageBase64Content, } from "./types";
+export { text, toolUse, toolResult, textMessage, imageUrl, imageBase64, isTextContent, isToolUseContent, isToolResultContent, isImageUrlContent, isImageBase64Content, isImageContent, } 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