@agentionai/agents 0.8.1 → 0.10.0

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/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,4 +154,27 @@ 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.
+ */
+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/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.8.1",
+  "version": "0.10.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": [