@agentionai/agents 0.9.0 → 0.10.1

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/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

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,16 +64,26 @@ 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);
+        }
+        // Mark session boundary so transform plugins (e.g. toolResultMaskingPlugin)
+        // don't mask tool results produced within this execute() loop.
+        this.history.setSessionAnchor();
         try {
             const messages = transformers_1.anthropicTransformer.toProvider(this.history.getEntries());
             const systemMessage = this.history.getSystemMessage();
@@ -180,6 +190,7 @@ class ClaudeAgent extends BaseAgent_1.BaseAgent {
                     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(),

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,16 +165,25 @@ 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);
+        }
+        // Mark session boundary so transform plugins (e.g. toolResultMaskingPlugin)
+        // don't mask tool results produced within this execute() loop.
+        this.history.setSessionAnchor();
         try {
             const contents = transformers_1.geminiTransformer.toProvider(this.history.getEntries());
             const systemMessage = this.history.getSystemMessage();

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,16 +75,25 @@ 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);
+        }
+        // Mark session boundary so transform plugins (e.g. toolResultMaskingPlugin)
+        // don't mask tool results produced within this execute() loop.
+        this.history.setSessionAnchor();
         try {
             const messages = transformers_1.mistralTransformer.toProvider(this.history.getEntries());
             const response = await this.client.chat.complete({

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,16 +86,25 @@ 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);
+        }
+        // Mark session boundary so transform plugins (e.g. toolResultMaskingPlugin)
+        // don't mask tool results produced within this execute() loop.
+        this.history.setSessionAnchor();
         try {
             const inputMessages = transformers_1.openAiTransformer.toProvider(this.history.getEntries());
             const response = await this.client.responses.create({

package/dist/history/History.d.ts

@@ -3,8 +3,8 @@ import { 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";
+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";
 /**
  * Metadata stored alongside each history entry.
  * Extended with summary tracking fields for the compression plugin.
@@ -61,7 +61,7 @@ type EntryWithMetadata = ReducibleEntry;
 /**
  * History configuration options
  */
-type HistoryOptions = {
+export type HistoryOptions = {
     maxLength?: number;
     /**
      * Maximum estimated tokens to retain in history. When exceeded, oldest
@@ -123,6 +123,7 @@ export declare class History extends EventEmitter {
     transient: boolean;
     private _plugins;
     private _reducing;
+    private _sessionAnchor;
     constructor(entries?: HistoryEntry[], options?: HistoryOptions);
     /**
      * Register a plugin with this history instance.
@@ -137,6 +138,20 @@ export declare class History extends EventEmitter {
      * ```
      */
     use(plugin: HistoryPlugin): this;
+    /**
+     * Mark the current entry count as the session boundary.
+     * Call this at the start of each agent `execute()` after adding the user
+     * message. Transform plugins (e.g. toolResultMaskingPlugin) will not mask
+     * any entries added at or after this position, preventing tool results from
+     * the current execution loop from being masked mid-session.
+     */
+    setSessionAnchor(): void;
+    /**
+     * The entry index set by the last call to `setSessionAnchor()`, or `null`
+     * if no anchor has been set. Entries at this index or beyond belong to the
+     * current session and should not be masked by transform plugins.
+     */
+    get sessionAnchor(): number | null;
     /**
      * Add a complete history entry
      */
@@ -232,11 +247,24 @@ export declare class History extends EventEmitter {
      * Create a copy of this history
      */
     clone(options?: HistoryOptions): History;
+    /**
+     * Apply maxLength and maxTokens trimming to the current entry list.
+     * Safe to call after bulk-loading entries (e.g. RedisHistory.load()).
+     * Subclasses may call this after directly manipulating _entries.
+     */
+    protected applyTrimming(): void;
     /**
      * 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;
+    /**
+     * After any trim, remove tool_result blocks whose paired tool_use was dropped.
+     * Entries that become empty after filtering are also removed.
+     * This prevents 400 errors from providers that require tool_result blocks to
+     * have a corresponding tool_use in the conversation history.
+     */
+    private sanitizeToolPairs;
 }
 //# sourceMappingURL=History.d.ts.map

package/dist/history/History.js

@@ -36,7 +36,7 @@ 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");
@@ -53,14 +53,32 @@ void Promise.resolve().then(() => __importStar(require("tokenx"))).then((mod) =>
 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.
  *
@@ -109,6 +127,7 @@ class History extends events_1.default {
         this.transient = false;
         this._plugins = [];
         this._reducing = false;
+        this._sessionAnchor = null;
         this.options = options;
         this.transient = Boolean(options?.transient);
         // Convert initial entries to internal format with metadata
@@ -136,6 +155,24 @@ class History extends events_1.default {
         plugin.onRegistered?.(this);
         return this;
     }
+    /**
+     * Mark the current entry count as the session boundary.
+     * Call this at the start of each agent `execute()` after adding the user
+     * message. Transform plugins (e.g. toolResultMaskingPlugin) will not mask
+     * any entries added at or after this position, preventing tool results from
+     * the current execution loop from being masked mid-session.
+     */
+    setSessionAnchor() {
+        this._sessionAnchor = this._entries.length;
+    }
+    /**
+     * The entry index set by the last call to `setSessionAnchor()`, or `null`
+     * if no anchor has been set. Entries at this index or beyond belong to the
+     * current session and should not be masked by transform plugins.
+     */
+    get sessionAnchor() {
+        return this._sessionAnchor;
+    }
     // ===========================================================================
     // Core write operations
     // ===========================================================================
@@ -148,18 +185,13 @@ class History extends events_1.default {
         const __metadata = {
             date: new Date().toISOString(),
             contentLength,
-            estimatedTokens: _estimateTokenCount(serialized),
+            estimatedTokens: estimateContentTokens(entry.content),
         };
         this._entries.push({
             ...entry,
             __metadata,
         });
-        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.applyTrimming();
         this.emit("entry", entry);
         // Fire plugin afterAdd hooks. Skipped during reduce() to avoid recursion
         // when compression plugins add summary entries to the history.
@@ -367,6 +399,20 @@ class History extends events_1.default {
     // ===========================================================================
     // Private helpers
     // ===========================================================================
+    /**
+     * Apply maxLength and maxTokens trimming to the current entry list.
+     * Safe to call after bulk-loading entries (e.g. RedisHistory.load()).
+     * Subclasses may call this after directly manipulating _entries.
+     */
+    applyTrimming() {
+        if (this.options.maxLength && this._entries.length > this.options.maxLength) {
+            this._entries = this._entries.slice(this._entries.length - this.options.maxLength);
+            this.sanitizeToolPairs();
+        }
+        if (this.options.maxTokens) {
+            this.trimToTokenBudget();
+        }
+    }
     /**
      * Drop oldest non-system entries until totalEstimatedTokens fits within budget.
      * Called synchronously from addEntry() as a safety net.
@@ -382,6 +428,32 @@ class History extends events_1.default {
                 break;
             this._entries.splice(firstNonSystem, 1);
         }
+        this.sanitizeToolPairs();
+    }
+    /**
+     * After any trim, remove tool_result blocks whose paired tool_use was dropped.
+     * Entries that become empty after filtering are also removed.
+     * This prevents 400 errors from providers that require tool_result blocks to
+     * have a corresponding tool_use in the conversation history.
+     */
+    sanitizeToolPairs() {
+        // Collect all tool_use IDs still present in the history
+        const toolUseIds = new Set();
+        for (const entry of this._entries) {
+            for (const block of entry.content) {
+                if ((0, types_1.isToolUseContent)(block)) {
+                    toolUseIds.add(block.id);
+                }
+            }
+        }
+        // Filter out orphaned tool_result blocks; drop entries that become empty
+        this._entries = this._entries.filter((entry) => {
+            const filtered = entry.content.filter((block) => !(0, types_1.isToolResultContent)(block) || toolUseIds.has(block.tool_use_id));
+            if (filtered.length === 0)
+                return false;
+            entry.content = filtered;
+            return true;
+        });
     }
 }
 exports.History = History;

package/dist/history/RedisHistory.d.ts

@@ -1,13 +1,15 @@
-import { History } from "./History";
+import { History, HistoryOptions } from "./History";
 interface RedisInstance {
     get(key: string): Promise<string | null>;
     set(key: string, content: string): Promise<"OK">;
 }
 export declare class RedisHistory extends History {
     private redisInstance;
-    constructor(redisInstance: RedisInstance);
+    constructor(redisInstance: RedisInstance, options?: HistoryOptions);
     /**
-     * Loads history entries from Redis using the specified key
+     * Loads history entries from Redis using the specified key.
+     * Entries are re-added via addEntry() so metadata is computed correctly.
+     * Trimming (maxLength / maxTokens) is applied after load.
      *
      * @param {string} key - The Redis key to retrieve history entries from
      * @returns {Promise<void>} A promise that resolves when history is loaded

package/dist/history/RedisHistory.js

@@ -3,12 +3,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.RedisHistory = void 0;
 const History_1 = require("./History");
 class RedisHistory extends History_1.History {
-    constructor(redisInstance) {
-        super([], { transient: false });
+    constructor(redisInstance, options = {}) {
+        super([], options);
         this.redisInstance = redisInstance;
     }
     /**
-     * Loads history entries from Redis using the specified key
+     * Loads history entries from Redis using the specified key.
+     * Entries are re-added via addEntry() so metadata is computed correctly.
+     * Trimming (maxLength / maxTokens) is applied after load.
      *
      * @param {string} key - The Redis key to retrieve history entries from
      * @returns {Promise<void>} A promise that resolves when history is loaded
@@ -16,15 +18,26 @@ class RedisHistory extends History_1.History {
      */
     async load(key) {
         try {
-            // Retrieve the serialized history from Redis
             const serializedHistory = await this.redisInstance.get(key);
-            // If no history exists for the key, return early
-            if (!serializedHistory) {
+            if (!serializedHistory)
                 return;
-            }
-            // Parse the serialized history and create a new History instance
             const entries = JSON.parse(serializedHistory);
-            this._entries = entries;
+            this._entries = [];
+            // Re-add via addEntry to compute metadata; suppress plugins during bulk load
+            // by temporarily bypassing plugin afterAdd hooks (handled by _reducing flag
+            // which is private — so we push entries directly and call applyTrimming once).
+            for (const entry of entries) {
+                const serialized = JSON.stringify(entry.content);
+                this._entries.push({
+                    ...entry,
+                    __metadata: {
+                        date: new Date().toISOString(),
+                        contentLength: serialized.length,
+                        estimatedTokens: Math.ceil(serialized.length / 4),
+                    },
+                });
+            }
+            this.applyTrimming();
         }
         catch (error) {
             console.error(`Error loading history from Redis key "${key}":`, error);
@@ -40,9 +53,7 @@ class RedisHistory extends History_1.History {
      */
     async save(key) {
         try {
-            // Serialize the current history entries
             const serializedHistory = this.toJSON();
-            // Save the serialized history to Redis
             await this.redisInstance.set(key, serializedHistory);
         }
         catch (error) {

package/dist/history/plugins/toolResultMaskingPlugin.js

@@ -88,7 +88,13 @@ function toolResultMaskingPlugin(options) {
                 }
             }
             const maskable = [];
+            const sessionAnchor = _history?.sessionAnchor ?? null;
             for (let ei = 0; ei < entries.length; ei++) {
+                // Never mask entries from the current execute() session — doing so
+                // would cause the model to call retrieve_tool_result mid-loop, whose
+                // result would itself be masked, creating an infinite retrieval loop.
+                if (sessionAnchor !== null && ei >= sessionAnchor)
+                    continue;
                 const entry = entries[ei];
                 for (let bi = 0; bi < entry.content.length; bi++) {
                     const block = entry.content[bi];

package/dist/history/transformers.js

@@ -40,6 +40,22 @@ exports.anthropicTransformer = {
                         is_error: block.is_error,
                     };
                 }
+                if ((0, types_1.isImageUrlContent)(block)) {
+                    return {
+                        type: "image",
+                        source: { type: "url", url: block.url },
+                    };
+                }
+                if ((0, types_1.isImageBase64Content)(block)) {
+                    return {
+                        type: "image",
+                        source: {
+                            type: "base64",
+                            media_type: block.mimeType,
+                            data: block.data,
+                        },
+                    };
+                }
                 throw new Error(`Unknown content type: ${block.type}`);
             });
             return { role, content };
@@ -122,11 +138,14 @@ exports.openAiTransformer = {
                 });
                 continue;
             }
-            // Separate tool_use from other content for OpenAI format
+            // Separate content blocks by type for OpenAI format
             const textBlocks = entry.content.filter(types_1.isTextContent);
             const toolUseBlocks = entry.content.filter(types_1.isToolUseContent);
             const toolResultBlocks = entry.content.filter(types_1.isToolResultContent);
-            // Add text message if present
+            const imageUrlBlocks = entry.content.filter(types_1.isImageUrlContent);
+            const imageBase64Blocks = entry.content.filter(types_1.isImageBase64Content);
+            const hasImages = imageUrlBlocks.length > 0 || imageBase64Blocks.length > 0;
+            // Add text/image message if present
             if (textBlocks.length > 0 && entry.role !== "user") {
                 items.push({
                     type: "message",
@@ -135,13 +154,42 @@ exports.openAiTransformer = {
                 });
             }
             else if (entry.role === "user" &&
-                textBlocks.length > 0 &&
+                (textBlocks.length > 0 || hasImages) &&
                 toolResultBlocks.length === 0) {
-                items.push({
-                    type: "message",
-                    role: "user",
-                    content: textBlocks.map((c) => c.text).join("\n"),
-                });
+                if (hasImages) {
+                    // Mixed content: build an array of content parts
+                    const parts = [];
+                    for (const block of entry.content) {
+                        if ((0, types_1.isTextContent)(block)) {
+                            parts.push({ type: "input_text", text: block.text });
+                        }
+                        else if ((0, types_1.isImageUrlContent)(block)) {
+                            parts.push({
+                                type: "input_image",
+                                image_url: block.url,
+                                ...(block.detail ? { detail: block.detail } : {}),
+                            });
+                        }
+                        else if ((0, types_1.isImageBase64Content)(block)) {
+                            parts.push({
+                                type: "input_image",
+                                image_url: `data:${block.mimeType};base64,${block.data}`,
+                            });
+                        }
+                    }
+                    items.push({
+                        type: "message",
+                        role: "user",
+                        content: parts,
+                    });
+                }
+                else {
+                    items.push({
+                        type: "message",
+                        role: "user",
+                        content: textBlocks.map((c) => c.text).join("\n"),
+                    });
+                }
             }
             // Add tool calls as separate function_call items (OpenAI format)
             // Convert IDs to OpenAI format if they came from another provider
@@ -243,7 +291,7 @@ exports.mistralTransformer = {
                 messages.push(msg);
                 continue;
             }
-            // User role - could be text or tool results
+            // User role - could be text, images, or tool results
             if (toolResultBlocks.length > 0) {
                 // Mistral uses separate "tool" role messages for each result
                 // We need to find the corresponding tool name from the assistant's tool_calls
@@ -258,11 +306,31 @@ exports.mistralTransformer = {
                     });
                 }
             }
-            else if (textBlocks.length > 0) {
-                messages.push({
-                    role: "user",
-                    content: textBlocks.map((c) => c.text).join("\n"),
-                });
+            else {
+                const imageUrlBlocks = entry.content.filter(types_1.isImageUrlContent);
+                const imageBase64Blocks = entry.content.filter(types_1.isImageBase64Content);
+                if (imageBase64Blocks.length > 0) {
+                    throw new Error("Mistral does not support base64 image inputs. Convert images to URLs before using with MistralAgent.");
+                }
+                if (imageUrlBlocks.length > 0) {
+                    // Mistral vision: array content with text + image_url parts
+                    const parts = [];
+                    for (const block of entry.content) {
+                        if ((0, types_1.isTextContent)(block)) {
+                            parts.push({ type: "text", text: block.text });
+                        }
+                        else if ((0, types_1.isImageUrlContent)(block)) {
+                            parts.push({ type: "image_url", image_url: block.url });
+                        }
+                    }
+                    messages.push({ role: "user", content: parts });
+                }
+                else if (textBlocks.length > 0) {
+                    messages.push({
+                        role: "user",
+                        content: textBlocks.map((c) => c.text).join("\n"),
+                    });
+                }
             }
         }
         return messages;
@@ -336,6 +404,25 @@ exports.geminiTransformer = {
             for (const block of textBlocks) {
                 parts.push({ text: block.text });
             }
+            // Add image parts
+            for (const block of entry.content) {
+                if ((0, types_1.isImageUrlContent)(block)) {
+                    parts.push({
+                        fileData: {
+                            mimeType: block.mimeType ?? "image/jpeg",
+                            fileUri: block.url,
+                        },
+                    });
+                }
+                else if ((0, types_1.isImageBase64Content)(block)) {
+                    parts.push({
+                        inlineData: {
+                            mimeType: block.mimeType,
+                            data: block.data,
+                        },
+                    });
+                }
+            }
             // Add function call parts (for assistant/model messages)
             for (const block of toolUseBlocks) {
                 parts.push({

package/dist/history/types.d.ts

@@ -29,10 +29,34 @@ export type ToolResultContent = {
     content: string;
     is_error?: boolean;
 };
+/**
+ * Supported image MIME types across all providers
+ */
+export type ImageMimeType = "image/jpeg" | "image/png" | "image/gif" | "image/webp";
+/**
+ * Image referenced by URL
+ */
+export type ImageUrlContent = {
+    type: "image_url";
+    url: string;
+    /** Required hint for Gemini (fileData); optional for other providers */
+    mimeType?: ImageMimeType;
+    /** OpenAI detail level hint — ignored by other providers */
+    detail?: "low" | "high" | "auto";
+};
+/**
+ * Image provided as raw base64-encoded data (no data: URI prefix)
+ */
+export type ImageBase64Content = {
+    type: "image_base64";
+    /** Raw base64 string — do not include the `data:<mime>;base64,` prefix */
+    data: string;
+    mimeType: ImageMimeType;
+};
 /**
  * Union of all content types
  */
-export type MessageContent = TextContent | ToolUseContent | ToolResultContent;
+export type MessageContent = TextContent | ToolUseContent | ToolResultContent | ImageUrlContent | ImageBase64Content;
 /**
  * Anthropic-specific metadata
  */
@@ -111,6 +135,9 @@ export type HistoryEntry = {
 export declare function isTextContent(content: MessageContent): content is TextContent;
 export declare function isToolUseContent(content: MessageContent): content is ToolUseContent;
 export declare function isToolResultContent(content: MessageContent): content is ToolResultContent;
+export declare function isImageUrlContent(content: MessageContent): content is ImageUrlContent;
+export declare function isImageBase64Content(content: MessageContent): content is ImageBase64Content;
+export declare function isImageContent(content: MessageContent): content is ImageUrlContent | ImageBase64Content;
 /**
  * Create a text content block
  */
@@ -127,6 +154,17 @@ 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;
+/**
+ * Create an image URL content block
+ */
+export declare function imageUrl(url: string, options?: {
+    mimeType?: ImageMimeType;
+    detail?: "low" | "high" | "auto";
+}): ImageUrlContent;
+/**
+ * Create a base64 image content block
+ */
+export declare function imageBase64(data: string, mimeType: ImageMimeType): ImageBase64Content;
 /**
  * Options controlling how history.reduce() compacts stored entries.
  * All fields are optional — supply whichever constraints apply.

package/dist/history/types.js

@@ -9,10 +9,15 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.isTextContent = isTextContent;
 exports.isToolUseContent = isToolUseContent;
 exports.isToolResultContent = isToolResultContent;
+exports.isImageUrlContent = isImageUrlContent;
+exports.isImageBase64Content = isImageBase64Content;
+exports.isImageContent = isImageContent;
 exports.text = text;
 exports.toolUse = toolUse;
 exports.toolResult = toolResult;
 exports.textMessage = textMessage;
+exports.imageUrl = imageUrl;
+exports.imageBase64 = imageBase64;
 // =============================================================================
 // Helper Type Guards
 // =============================================================================
@@ -25,6 +30,15 @@ function isToolUseContent(content) {
 function isToolResultContent(content) {
     return content.type === "tool_result";
 }
+function isImageUrlContent(content) {
+    return content.type === "image_url";
+}
+function isImageBase64Content(content) {
+    return content.type === "image_base64";
+}
+function isImageContent(content) {
+    return content.type === "image_url" || content.type === "image_base64";
+}
 // =============================================================================
 // Utility Functions
 // =============================================================================
@@ -52,4 +66,16 @@ function toolResult(tool_use_id, content, is_error) {
 function textMessage(role, value) {
     return { role, content: [text(value)] };
 }
+/**
+ * Create an image URL content block
+ */
+function imageUrl(url, options) {
+    return { type: "image_url", url, ...options };
+}
+/**
+ * Create a base64 image content block
+ */
+function imageBase64(data, mimeType) {
+    return { type: "image_base64", data, mimeType };
+}
 //# sourceMappingURL=types.js.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agentionai/agents",
   "author": "Laurent Zuijdwijk",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "description": "Agent Library",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",