@illuma-ai/agents 1.5.0 → 2.1.1

package/src/index.ts

@@ -78,12 +78,6 @@ export * from './utils';
 /* Types */
 export type * from './types';
 
-/* LangChain compatibility facade — re-exports common langchain primitives
- * so consumers can import from '@illuma-ai/agents/langchain' instead of
- * pinning '@langchain/*' versions directly. Helps keep consumer dep
- * versions in sync with the library's tested set. */
-export * from './langchain';
-
 /* LLM */
 export { CustomOpenAIClient } from './llm/openai';
 export { ChatOpenRouter } from './llm/openrouter';

package/src/llm/anthropic/utils/message_inputs.ts

@@ -592,16 +592,7 @@ function _formatContent(message: BaseMessage) {
         throw new Error('Unsupported message content format');
       }
     });
-    return contentBlocks.filter(
-      (block) =>
-        block !== null &&
-        !(
-          block.type === 'text' &&
-          'text' in block &&
-          typeof block.text === 'string' &&
-          block.text.trim() === ''
-        )
-    );
+    return contentBlocks.filter((block) => block !== null);
   }
 }
 

package/src/llm/bedrock/__tests__/bedrock-caching.test.ts

@@ -194,134 +194,6 @@ describe('Bedrock Prompt Caching', () => {
         expect(model.promptCache).toBe(false);
       });
     });
-
-    describe('Tool cache strategies', () => {
-      const fakeTools = [
-        {
-          toolSpec: {
-            name: 'web_search',
-            description: 'core search',
-            inputSchema: { json: { type: 'object', properties: {} } },
-          },
-        },
-        {
-          toolSpec: {
-            name: 'execute_code',
-            description: 'core code',
-            inputSchema: { json: { type: 'object', properties: {} } },
-          },
-        },
-        {
-          toolSpec: {
-            name: 'search_emails_mcp_Outlook',
-            description: 'mcp tool',
-            inputSchema: { json: { type: 'object', properties: {} } },
-          },
-        },
-        {
-          toolSpec: {
-            name: 'list_documents_mcp_SharePoint',
-            description: 'mcp tool',
-            inputSchema: { json: { type: 'object', properties: {} } },
-          },
-        },
-      ];
-
-      it("default 'single' strategy: one cachePoint at end of tools array", () => {
-        const model = new CustomChatBedrockConverse({
-          model: 'anthropic.claude-3-haiku-20240307-v1:0',
-          region: 'us-east-1',
-          promptCache: true,
-          // toolCacheStrategy omitted — default is 'single'
-        });
-        const params = model.invocationParams({
-          tools: fakeTools,
-        } satisfies InvocationParamsOptions);
-        // 4 tools + 1 cachePoint
-        expect(params.toolConfig?.tools).toHaveLength(5);
-        expect(params.toolConfig?.tools?.[4]).toEqual({
-          cachePoint: { type: 'default' },
-        });
-      });
-
-      it("'split' strategy with toolGroupSelector groups tools by selector key, cachePoint after each group", () => {
-        const model = new CustomChatBedrockConverse({
-          model: 'anthropic.claude-3-haiku-20240307-v1:0',
-          region: 'us-east-1',
-          promptCache: true,
-          toolCacheStrategy: 'split',
-          toolGroupSelector: (toolName) =>
-            toolName.includes('_mcp_') ? 'mcp' : 'core',
-        });
-        const params = model.invocationParams({
-          tools: fakeTools,
-        } satisfies InvocationParamsOptions);
-        // [core, core, cp, mcp, mcp, cp] = 6 entries
-        expect(params.toolConfig?.tools).toHaveLength(6);
-        expect(params.toolConfig?.tools?.[0]).toEqual(fakeTools[0]); // core
-        expect(params.toolConfig?.tools?.[1]).toEqual(fakeTools[1]); // core
-        expect(params.toolConfig?.tools?.[2]).toEqual({
-          cachePoint: { type: 'default' },
-        });
-        expect(params.toolConfig?.tools?.[3]).toEqual(fakeTools[2]); // mcp
-        expect(params.toolConfig?.tools?.[4]).toEqual(fakeTools[3]); // mcp
-        expect(params.toolConfig?.tools?.[5]).toEqual({
-          cachePoint: { type: 'default' },
-        });
-      });
-
-      it("'none' strategy: no cachePoint added at all", () => {
-        const model = new CustomChatBedrockConverse({
-          model: 'anthropic.claude-3-haiku-20240307-v1:0',
-          region: 'us-east-1',
-          promptCache: true,
-          toolCacheStrategy: 'none',
-        });
-        const params = model.invocationParams({
-          tools: fakeTools,
-        } satisfies InvocationParamsOptions);
-        expect(params.toolConfig?.tools).toHaveLength(4);
-        for (const tool of params.toolConfig?.tools ?? []) {
-          expect('cachePoint' in tool).toBe(false);
-        }
-      });
-
-      it("'split' with single-group selector behaves like 'single'", () => {
-        const model = new CustomChatBedrockConverse({
-          model: 'anthropic.claude-3-haiku-20240307-v1:0',
-          region: 'us-east-1',
-          promptCache: true,
-          toolCacheStrategy: 'split',
-          toolGroupSelector: () => 'all', // every tool same group
-        });
-        const params = model.invocationParams({
-          tools: fakeTools,
-        } satisfies InvocationParamsOptions);
-        // 4 tools + 1 cachePoint
-        expect(params.toolConfig?.tools).toHaveLength(5);
-        expect(params.toolConfig?.tools?.[4]).toEqual({
-          cachePoint: { type: 'default' },
-        });
-      });
-
-      it("'split' with empty groups skipped (only emits cachePoint after non-empty groups)", () => {
-        const model = new CustomChatBedrockConverse({
-          model: 'anthropic.claude-3-haiku-20240307-v1:0',
-          region: 'us-east-1',
-          promptCache: true,
-          toolCacheStrategy: 'split',
-          toolGroupSelector: (name) =>
-            name.includes('_mcp_') ? 'mcp' : 'core',
-        });
-        // Only core tools — no MCP
-        const coreOnly = fakeTools.slice(0, 2);
-        const params = model.invocationParams({
-          tools: coreOnly,
-        } satisfies InvocationParamsOptions);
-        // 2 core + 1 cachePoint = 3
-        expect(params.toolConfig?.tools).toHaveLength(3);
-      });
-    });
   });
 
   describe('AgentContext - System Message Caching', () => {
@@ -361,13 +233,7 @@ describe('Bedrock Prompt Caching', () => {
     };
 
     describe('Bedrock system message with promptCache: true', () => {
-      /* Updated contract (2026-05-01, upstream PR #128 alignment): Bedrock
-       * system message gets a `cachePoint` block inline so the system
-       * prefix is cached at the AWS account level (cross-user). Previously
-       * cachePoint was only added at the tool level, leaving the system
-       * prefix uncached. Tools array still gets its own cachePoints from
-       * IllumaBedrockConverse.invocationParams independently. */
-      it('emits content array with cachePoint after stable text (Claude model)', async () => {
+      it('should produce plain string system message (cachePoint is handled at tool level)', async () => {
         const ctx = createBedrockContext({
           instructions: 'You are a helpful assistant.',
           promptCache: true,
@@ -376,20 +242,17 @@ describe('Bedrock Prompt Caching', () => {
         const systemRunnable = ctx.systemRunnable;
         expect(systemRunnable).toBeDefined();
 
+        // Invoke the runnable to get the messages
         const result = await systemRunnable!.invoke([]);
         const systemMessage = result[0];
 
-        const content = systemMessage.content as Array<Record<string, unknown>>;
-        expect(Array.isArray(content)).toBe(true);
-        expect(content).toHaveLength(2);
-        expect(content[0]).toEqual({
-          type: 'text',
-          text: 'You are a helpful assistant.',
-        });
-        expect(content[1]).toEqual({ cachePoint: { type: 'default', ttl: '5m' } });
+        // Bedrock system messages are plain strings — cachePoint is added
+        // at the tool level by IllumaBedrockConverse.invocationParams()
+        expect(typeof systemMessage.content).toBe('string');
+        expect(systemMessage.content).toBe('You are a helpful assistant.');
       });
 
-      it('keeps additional_instructions AFTER cachePoint (dynamic tail not cached)', async () => {
+      it('should include combined instructions and additional_instructions as plain string', async () => {
         const ctx = createBedrockContext({
           instructions: 'Base instructions.',
           additionalInstructions: 'Additional context.',
@@ -398,20 +261,11 @@ describe('Bedrock Prompt Caching', () => {
 
         const result = await ctx.systemRunnable!.invoke([]);
         const systemMessage = result[0];
-        const content = systemMessage.content as Array<Record<string, unknown>>;
 
-        /* Order is critical: stable text → cachePoint → dynamic text.
-         * Anything after the cachePoint is excluded from the cache, so
-         * the per-user/per-request `additional_instructions` does not
-         * invalidate the cached prefix. */
-        expect(content).toHaveLength(3);
-        expect((content[0] as { text: string }).text).toBe(
-          'Base instructions.'
-        );
-        expect(content[1]).toEqual({ cachePoint: { type: 'default', ttl: '5m' } });
-        expect((content[2] as { text: string }).text).toBe(
-          'Additional context.'
-        );
+        // Bedrock system messages are plain strings even with promptCache
+        expect(typeof systemMessage.content).toBe('string');
+        expect(systemMessage.content).toContain('Base instructions.');
+        expect(systemMessage.content).toContain('Additional context.');
       });
     });
 
@@ -458,7 +312,7 @@ describe('Bedrock Prompt Caching', () => {
         expect(content[0]).toEqual({
           type: 'text',
           text: 'You are a helpful assistant.',
-          cache_control: { type: 'ephemeral', ttl: '5m' },
+          cache_control: { type: 'ephemeral' },
         });
       });
 
@@ -476,21 +330,19 @@ describe('Bedrock Prompt Caching', () => {
     });
 
     describe('Provider-specific caching behavior', () => {
-      it('emits cachePoint block inline for Bedrock Claude (account-scoped system caching)', async () => {
+      it('should produce plain string for Bedrock (cachePoint handled at tool level)', async () => {
         const bedrockCtx = createBedrockContext({
           instructions: 'Test',
           promptCache: true,
         });
 
         const result = await bedrockCtx.systemRunnable!.invoke([]);
-        const content = result[0].content as Array<Record<string, unknown>>;
 
-        // Bedrock system messages now carry an inline cachePoint so the
-        // system prefix gets cached at the AWS account level (matching
-        // upstream PR #128). Tool-level cachePoint from
-        // IllumaBedrockConverse.invocationParams() runs independently.
-        expect(Array.isArray(content)).toBe(true);
-        expect(content.some((c) => 'cachePoint' in c)).toBe(true);
+        // Bedrock system messages are plain strings — cachePoint is added
+        // at the tool level by IllumaBedrockConverse.invocationParams(),
+        // not inline in the system message content
+        expect(typeof result[0].content).toBe('string');
+        expect(result[0].content).toBe('Test');
       });
 
       it('should use cache_control format for Anthropic, not cachePoint', async () => {

package/src/llm/bedrock/index.ts

@@ -38,7 +38,6 @@ import type { BaseMessage } from '@langchain/core/messages';
 import { ChatGenerationChunk, ChatResult } from '@langchain/core/outputs';
 import type { CallbackManagerForLLMRun } from '@langchain/core/callbacks/manager';
 import type { ChatBedrockConverseInput } from '@langchain/aws';
-import { isBedrockCacheSupported } from './cacheSupport';
 import {
   convertToConverseMessages,
   handleConverseStreamContentBlockStart,
@@ -53,72 +52,19 @@ import {
  */
 export type ServiceTierType = 'priority' | 'default' | 'flex' | 'reserved';
 
-/**
- * Tool cachePoint allocation strategy.
- *
- *   - 'single':  one cachePoint at the END of the tools array (whole array
- *                cached as one unit). Lightest budget use (1 cachePoint).
- *   - 'split':   split tools into groups via `toolGroupSelector`. Each
- *                non-empty group gets its own cachePoint. Use when groups
- *                have different volatility (e.g. stable core tools vs
- *                volatile MCP tools). Costs more cachePoint budget.
- *   - 'none':    no cachePoint on tools array. Use when tool definitions
- *                change every request anyway.
- */
-export type ToolCacheStrategy = 'single' | 'split' | 'none';
-
-/**
- * Group selector for `toolCacheStrategy: 'split'`. Receives the tool name
- * and returns a stable group key — tools with the same key are grouped
- * together. Group order in the output array follows first-encounter order.
- */
-export type ToolGroupSelector = (toolName: string) => string;
-
-/**
- * Default group selector — puts all tools in a single group named 'core'.
- * Equivalent to 'single' strategy but explicit. Consumers override this
- * to enable per-source grouping (e.g. ranger uses `_mcp_` substring to
- * separate core from MCP tools).
- */
-export const DEFAULT_TOOL_GROUP_SELECTOR: ToolGroupSelector = () => 'core';
-
 /**
  * Extended input interface with additional features:
  * - promptCache: Enable Bedrock prompt caching for tool definitions
  * - applicationInferenceProfile: Use an inference profile ARN instead of model ID
  * - serviceTier: Specify service tier (Priority, Standard, Flex, Reserved)
- * - toolCacheStrategy: How to allocate cachePoints across tools array
- * - toolGroupSelector: Group key resolver for the 'split' strategy
  */
 export interface IllumaBedrockConverseInput extends ChatBedrockConverseInput {
   /**
    * Enable Bedrock prompt caching for tool definitions.
-   * When true, adds cachePoint marker(s) to tools array per
-   * `toolCacheStrategy`. Defaults to 'single'.
+   * When true, adds cachePoint markers to tools array.
    */
   promptCache?: boolean;
 
-  /**
-   * Tool cachePoint allocation. Defaults to 'single' — one cachePoint at
-   * the end of the tools array. Set to 'split' (with `toolGroupSelector`)
-   * when different tool groups have different volatility.
-   */
-  toolCacheStrategy?: ToolCacheStrategy;
-
-  /**
-   * Group selector for 'split' strategy. Receives a tool name, returns
-   * a stable group key. Defaults to a one-group selector (equivalent
-   * to 'single').
-   */
-  toolGroupSelector?: ToolGroupSelector;
-
-  /**
-   * Additional model ID patterns to consider Bedrock-cache-supported.
-   * Defaults are in `src/llm/bedrock/cacheSupport.ts`. Use this when
-   * AWS adds a new model family before the next library release.
-   */
-  bedrockCacheModelPatterns?: readonly RegExp[];
-
   /**
    * Application Inference Profile ARN to use for the model.
    * For example, "arn:aws:bedrock:eu-west-1:123456789102:application-inference-profile/fm16bt65tzgx"
@@ -162,24 +108,11 @@ export class IllumaBedrockConverse extends ChatBedrockConverse {
   /** Service tier for model invocation */
   serviceTier?: ServiceTierType;
 
-  /** Tool cachePoint allocation strategy. */
-  toolCacheStrategy: ToolCacheStrategy;
-
-  /** Group selector for 'split' strategy. */
-  toolGroupSelector: ToolGroupSelector;
-
-  /** Optional consumer extensions to the cache-supported model allowlist. */
-  bedrockCacheModelPatterns?: readonly RegExp[];
-
   constructor(fields?: IllumaBedrockConverseInput) {
     super(fields);
     this.promptCache = fields?.promptCache ?? false;
     this.applicationInferenceProfile = fields?.applicationInferenceProfile;
     this.serviceTier = fields?.serviceTier;
-    this.toolCacheStrategy = fields?.toolCacheStrategy ?? 'single';
-    this.toolGroupSelector =
-      fields?.toolGroupSelector ?? DEFAULT_TOOL_GROUP_SELECTOR;
-    this.bedrockCacheModelPatterns = fields?.bedrockCacheModelPatterns;
 
     // Fix: Force supportsToolChoiceValues for Claude models
     // The parent constructor checks `model.includes('claude-3')` but this fails when:
@@ -250,64 +183,56 @@ export class IllumaBedrockConverse extends ChatBedrockConverse {
       }
     }
 
-    /* Allowlist-based gate (see cacheSupport.ts). Replaces the old
-     * substring heuristic — same default behavior for Claude/Anthropic/
-     * Nova models, plus extension via `bedrockCacheModelPatterns`. */
-    const cacheSupported = isBedrockCacheSupported(
-      this.model,
-      this.bedrockCacheModelPatterns,
-    );
+    // Only Claude models support cachePoint - check model name
+    const modelId = this.model.toLowerCase();
+    const isClaudeModel =
+      modelId.includes('claude') || modelId.includes('anthropic');
 
     if (
       this.promptCache &&
-      cacheSupported &&
-      this.toolCacheStrategy !== 'none' &&
+      isClaudeModel &&
       params.toolConfig?.tools &&
       Array.isArray(params.toolConfig.tools) &&
       params.toolConfig.tools.length > 0
     ) {
-      const tools = params.toolConfig.tools;
-
-      if (this.toolCacheStrategy === 'single') {
-        /* SINGLE: one cachePoint at the end of the tools array. Lightest
-         * budget use; appropriate when the entire tools array is treated
-         * as one unit and changes together. */
-        const toolsWithCache = [
-          ...tools,
-          { cachePoint: { type: 'default' } } as (typeof tools)[number],
-        ];
-        params.toolConfig.tools = toolsWithCache;
-      } else if (this.toolCacheStrategy === 'split') {
-        /* SPLIT: group tools by `toolGroupSelector` and emit a cachePoint
-         * after each non-empty group. Group order follows first-encounter
-         * order in the input. Use when groups have different volatility
-         * (e.g. stable core tools + volatile MCP tools). */
-        const groupOrder: string[] = [];
-        const groupMap = new Map<string, typeof tools>();
-        for (const tool of tools) {
-          const toolName =
-            (tool as { toolSpec?: { name?: string } }).toolSpec?.name ?? '';
-          const groupKey = this.toolGroupSelector(toolName);
-          let group = groupMap.get(groupKey);
-          if (!group) {
-            group = [];
-            groupMap.set(groupKey, group);
-            groupOrder.push(groupKey);
-          }
-          group.push(tool);
+      // Separate core tools from MCP tools
+      // MCP tools have '_mcp_' in their name (e.g., 'search_emails_mcp_Google-Workspace')
+      const coreTools: typeof params.toolConfig.tools = [];
+      const mcpTools: typeof params.toolConfig.tools = [];
+
+      for (const tool of params.toolConfig.tools) {
+        // Check if tool has a name property with '_mcp_' pattern
+        const toolName =
+          (tool as { toolSpec?: { name?: string } }).toolSpec?.name ?? '';
+        if (toolName.includes('_mcp_')) {
+          mcpTools.push(tool);
+        } else {
+          coreTools.push(tool);
         }
+      }
 
-        const toolsWithCache: typeof tools = [];
-        for (const groupKey of groupOrder) {
-          const group = groupMap.get(groupKey);
-          if (!group || group.length === 0) continue;
-          toolsWithCache.push(...group);
-          toolsWithCache.push(
-            { cachePoint: { type: 'default' } } as (typeof tools)[number],
-          );
-        }
-        params.toolConfig.tools = toolsWithCache;
+      // Build tools array with strategic cachePoints:
+      // [CoreTool1, CoreTool2, cachePoint] + [MCPTool1, MCPTool2, cachePoint]
+      const toolsWithCache: typeof params.toolConfig.tools = [];
+
+      // Add core tools with cachePoint (if any)
+      if (coreTools.length > 0) {
+        toolsWithCache.push(...coreTools);
+        toolsWithCache.push({ cachePoint: { type: 'default' } });
+      }
+
+      // Add MCP tools with their own cachePoint (if any)
+      if (mcpTools.length > 0) {
+        toolsWithCache.push(...mcpTools);
+        toolsWithCache.push({ cachePoint: { type: 'default' } });
+      }
+
+      // If no tools at all (shouldn't happen but safety check)
+      if (toolsWithCache.length === 0) {
+        toolsWithCache.push({ cachePoint: { type: 'default' } });
       }
+
+      params.toolConfig.tools = toolsWithCache;
     }
 
     // Add serviceTier support

package/src/llm/openai/utils/index.ts

@@ -302,10 +302,6 @@ export function _convertMessagesToOpenAIParams(
   model?: string,
   options?: ConvertMessagesOptions
 ): OpenAICompletionParam[] {
-  /* DeepSeek reasoning roundtrip (upstream PR #136): reasoning_content on
-   * an AI message must be re-sent only when the message participates in a
-   * tool-call exchange. Track context across the message flat-map. */
-  let hasReasoningToolCallContext = false;
   // TODO: Function messages do not support array content, fix cast
   return messages.flatMap((message) => {
     let role = messageToOpenAIRole(message);
@@ -336,8 +332,6 @@ export function _convertMessagesToOpenAIParams(
       role,
       content,
     };
-    let messageHasToolCalls = false;
-    let messageIsToolResult = false;
     if (message.name != null) {
       completionParam.name = message.name;
     }
@@ -346,11 +340,17 @@ export function _convertMessagesToOpenAIParams(
       completionParam.content = '';
     }
     if (isAIMessage(message) && !!message.tool_calls?.length) {
-      messageHasToolCalls = true;
       completionParam.tool_calls = message.tool_calls.map(
         convertLangChainToolCallToOpenAI
       );
       completionParam.content = hasAnthropicThinkingBlock ? content : '';
+      if (
+        options?.includeReasoningContent === true &&
+        message.additional_kwargs.reasoning_content != null
+      ) {
+        completionParam.reasoning_content =
+          message.additional_kwargs.reasoning_content;
+      }
       if (
         options?.includeReasoningDetails === true &&
         message.additional_kwargs.reasoning_details != null
@@ -398,10 +398,14 @@ export function _convertMessagesToOpenAIParams(
       }
     } else {
       if (message.additional_kwargs.tool_calls != null) {
-        messageHasToolCalls =
-          !Array.isArray(message.additional_kwargs.tool_calls) ||
-          message.additional_kwargs.tool_calls.length > 0;
         completionParam.tool_calls = message.additional_kwargs.tool_calls;
+        if (
+          options?.includeReasoningContent === true &&
+          message.additional_kwargs.reasoning_content != null
+        ) {
+          completionParam.reasoning_content =
+            message.additional_kwargs.reasoning_content;
+        }
         if (
           options?.includeReasoningDetails === true &&
           message.additional_kwargs.reasoning_details != null
@@ -449,31 +453,10 @@ export function _convertMessagesToOpenAIParams(
         }
       }
       if ((message as ToolMessage).tool_call_id != null) {
-        messageIsToolResult = true;
         completionParam.tool_call_id = (message as ToolMessage).tool_call_id;
       }
     }
 
-    /* DeepSeek reasoning roundtrip (upstream PR #136): emit
-     * reasoning_content only when the message is part of a tool-call
-     * exchange — either the message itself has tool_calls, or a previous
-     * AI/tool message established the context. Skipping the gate causes
-     * DeepSeek to drop reasoning content during multi-turn replays. */
-    if (
-      options?.includeReasoningContent === true &&
-      isAIMessage(message) &&
-      (hasReasoningToolCallContext || messageHasToolCalls) &&
-      typeof message.additional_kwargs.reasoning_content === 'string' &&
-      message.additional_kwargs.reasoning_content !== ''
-    ) {
-      completionParam.reasoning_content =
-        message.additional_kwargs.reasoning_content;
-    }
-
-    if (messageHasToolCalls || messageIsToolResult) {
-      hasReasoningToolCallContext = true;
-    }
-
     if (
       message.additional_kwargs.audio &&
       typeof message.additional_kwargs.audio === 'object' &&