@illuma-ai/agents 1.4.0-alpha.6 → 1.5.1

package/src/specs/prune.orphans.test.ts

@@ -0,0 +1,248 @@
+// Orphan tool message repair + sanitize coverage. Ported from the reference implementation's
+// `prune.test.ts` "Tool Message Handling" + top-level `sanitizeOrphanToolBlocks`
+// describes — kept in a dedicated file to keep the diff against illuma's
+// existing prune.test.ts narrow.
+import {
+  AIMessage,
+  BaseMessage,
+  ToolMessage,
+  HumanMessage,
+  SystemMessage,
+} from '@langchain/core/messages';
+import type * as t from '@/types';
+import {
+  repairOrphanedToolMessages,
+  sanitizeOrphanToolBlocks,
+} from '@/messages/prune';
+
+const createTestTokenCounter = (): t.TokenCounter => {
+  return (message: BaseMessage): number => {
+    if (typeof message.content === 'string') {
+      return Math.max(1, Math.ceil(message.content.length / 4));
+    }
+    if (Array.isArray(message.content)) {
+      let total = 0;
+      for (const block of message.content) {
+        if (typeof block === 'object' && block !== null) {
+          total += Math.ceil(JSON.stringify(block).length / 4);
+        }
+      }
+      return Math.max(1, total);
+    }
+    return 1;
+  };
+};
+
+describe('repairOrphanedToolMessages', () => {
+  it('drops orphan ToolMessages that no longer have a matching AIMessage tool_call', () => {
+    const tokenCounter = createTestTokenCounter();
+    const context = [
+      new SystemMessage('System'),
+      new ToolMessage({ content: 'Orphan result', tool_call_id: 'gone' }),
+      new HumanMessage('User question'),
+      new AIMessage({
+        content: 'thinking',
+        tool_calls: [{ name: 't1', args: {}, id: 'tool1' }],
+      }),
+      new ToolMessage({ content: 'Tool result 1', tool_call_id: 'tool1' }),
+    ];
+
+    const result = repairOrphanedToolMessages({
+      context,
+      allMessages: context,
+      tokenCounter,
+      indexTokenCountMap: {},
+    });
+
+    expect(result.droppedOrphanCount).toBe(1);
+    expect(result.context).toHaveLength(4);
+    expect(
+      result.context.some(
+        (m) =>
+          m.getType() === 'tool' && (m as ToolMessage).tool_call_id === 'gone'
+      )
+    ).toBe(false);
+    expect(result.droppedMessages).toHaveLength(1);
+  });
+
+  it('strips orphan tool_use content blocks from AIMessages whose ToolMessage was dropped', () => {
+    const tokenCounter = createTestTokenCounter();
+    const context = [
+      new HumanMessage('Hi'),
+      new AIMessage({
+        content: [
+          { type: 'text', text: 'Calling tool…' },
+          { type: 'tool_use', id: 'tool_orphan', name: 'foo', input: {} },
+        ],
+        tool_calls: [{ name: 'foo', args: {}, id: 'tool_orphan' }],
+      }),
+      // Note: NO matching ToolMessage for tool_orphan
+    ];
+
+    const result = repairOrphanedToolMessages({
+      context,
+      allMessages: context,
+      tokenCounter,
+      indexTokenCountMap: {},
+    });
+
+    // The AI message should still be in context, but with the tool_use block stripped
+    expect(result.context).toHaveLength(2);
+    const ai = result.context[1] as AIMessage;
+    expect(ai.tool_calls?.length ?? 0).toBe(0);
+    if (Array.isArray(ai.content)) {
+      const toolUseBlocks = ai.content.filter(
+        (b) =>
+          typeof b === 'object' &&
+          ((b as { type?: string }).type === 'tool_use' ||
+            (b as { type?: string }).type === 'tool_call')
+      );
+      expect(toolUseBlocks).toHaveLength(0);
+    }
+  });
+
+  it('drops the entire AIMessage when stripping leaves no content blocks', () => {
+    const tokenCounter = createTestTokenCounter();
+    const context = [
+      new HumanMessage('Question'),
+      new AIMessage({
+        content: [
+          { type: 'tool_use', id: 'orphan_only', name: 'foo', input: {} },
+        ],
+        tool_calls: [{ name: 'foo', args: {}, id: 'orphan_only' }],
+      }),
+    ];
+
+    const result = repairOrphanedToolMessages({
+      context,
+      allMessages: context,
+      tokenCounter,
+      indexTokenCountMap: {},
+    });
+
+    expect(result.context).toHaveLength(1);
+    expect(result.droppedOrphanCount).toBe(1);
+    expect(result.droppedMessages).toHaveLength(1);
+  });
+
+  it('preserves matched tool_call ↔ tool_result pairs intact', () => {
+    const tokenCounter = createTestTokenCounter();
+    const context = [
+      new HumanMessage('Question'),
+      new AIMessage({
+        content: 'thinking',
+        tool_calls: [{ name: 'foo', args: {}, id: 'paired' }],
+      }),
+      new ToolMessage({ content: 'result', tool_call_id: 'paired' }),
+    ];
+
+    const result = repairOrphanedToolMessages({
+      context,
+      allMessages: context,
+      tokenCounter,
+      indexTokenCountMap: {},
+    });
+
+    expect(result.context).toEqual(context);
+    expect(result.droppedOrphanCount).toBe(0);
+  });
+});
+
+describe('sanitizeOrphanToolBlocks', () => {
+  it('strips orphan tool_use blocks from AI messages with no matching ToolMessage', () => {
+    const messages: BaseMessage[] = [
+      new HumanMessage('Hello'),
+      new AIMessage({
+        content: [
+          { type: 'text', text: 'Let me check.' },
+          { type: 'tool_use', id: 'tu_orphan', name: 'search', input: {} },
+        ],
+        tool_calls: [{ name: 'search', args: {}, id: 'tu_orphan' }],
+      }),
+      // No ToolMessage with tool_call_id 'tu_orphan'
+      new HumanMessage('Follow-up'),
+    ];
+
+    const out = sanitizeOrphanToolBlocks(messages);
+    // The result depends on whether the stripped AI is at the end (popped by
+    // the trailing-stripped-AI rule). Here it is NOT trailing, so it stays.
+    expect(out).toHaveLength(3);
+    const ai = out[1] as AIMessage;
+    expect(ai.tool_calls?.length ?? 0).toBe(0);
+    if (Array.isArray(ai.content)) {
+      expect(
+        ai.content.some(
+          (b) =>
+            typeof b === 'object' &&
+            (b as { type?: string }).type === 'tool_use'
+        )
+      ).toBe(false);
+    }
+  });
+
+  it('drops orphan ToolMessages whose matching tool_use is missing', () => {
+    const messages: BaseMessage[] = [
+      new HumanMessage('Hi'),
+      new AIMessage('Plain response'),
+      new ToolMessage({ content: 'orphaned', tool_call_id: 'gone' }),
+    ];
+
+    const out = sanitizeOrphanToolBlocks(messages);
+    expect(out).toHaveLength(2);
+    expect(out.find((m) => m.getType() === 'tool')).toBeUndefined();
+  });
+
+  it('returns the original array unchanged when every pair is matched (fast path)', () => {
+    const messages: BaseMessage[] = [
+      new HumanMessage('Hi'),
+      new AIMessage({
+        content: 'thinking',
+        tool_calls: [{ name: 't1', args: {}, id: 'tool1' }],
+      }),
+      new ToolMessage({ content: 'r1', tool_call_id: 'tool1' }),
+    ];
+    const out = sanitizeOrphanToolBlocks(messages);
+    expect(out).toBe(messages);
+  });
+
+  it('pops trailing AI messages whose tool_use blocks were all stripped', () => {
+    const messages: BaseMessage[] = [
+      new HumanMessage('Hi'),
+      new AIMessage({
+        content: [
+          { type: 'tool_use', id: 'orphan_trail', name: 'x', input: {} },
+        ],
+        tool_calls: [{ name: 'x', args: {}, id: 'orphan_trail' }],
+      }),
+    ];
+
+    const out = sanitizeOrphanToolBlocks(messages);
+    // Trailing stripped-AI is popped per Bedrock/Anthropic rule: the
+    // conversation must not end with an empty assistant exchange.
+    expect(out).toHaveLength(1);
+    expect(out[0].getType()).toBe('human');
+  });
+
+  it('ignores Anthropic server-tool ids (srvtoolu_*)', () => {
+    const messages: BaseMessage[] = [
+      new HumanMessage('Hi'),
+      new AIMessage({
+        content: [
+          {
+            type: 'tool_use',
+            id: 'srvtoolu_anthropic_internal',
+            name: 'web_search',
+            input: {},
+          },
+        ],
+        tool_calls: [
+          { name: 'web_search', args: {}, id: 'srvtoolu_anthropic_internal' },
+        ],
+      }),
+    ];
+
+    const out = sanitizeOrphanToolBlocks(messages);
+    // No orphans detected — the server-tool prefix is exempt.
+    expect(out).toBe(messages);
+  });
+});

package/src/specs/prune.test.ts

@@ -11,7 +11,10 @@ import {
 import type { RunnableConfig } from '@langchain/core/runnables';
 import type { UsageMetadata } from '@langchain/core/messages';
 import type * as t from '@/types';
-import { createPruneMessages } from '@/messages/prune';
+import {
+  createPruneMessages,
+  getMessagesWithinTokenLimit as realGetMessagesWithinTokenLimit,
+} from '@/messages/prune';
 import { getLLMConfig } from '@/utils/llmConfig';
 import { Providers } from '@/common';
 import { Run } from '@/run';
@@ -362,6 +365,64 @@ describe('Prune Messages Tests', () => {
     });
   });
 
+  describe('instructionTokens budget reservation', () => {
+    it('reserves overhead from the budget when no system message is in the messages array', () => {
+      const tokenCounter = createTestTokenCounter();
+      // Budget is 100; `instructionTokens` claims 60 of it for runtime-built
+      // system + tool schemas. Effective message budget is 40 + 3 (assistant
+      // priming) = 37. Two AI messages of 30 tokens each must drop one.
+      const messages = [
+        new HumanMessage('q'),
+        new AIMessage('first response'),
+        new AIMessage('second response'),
+      ];
+      const indexTokenCountMap = { 0: 5, 1: 30, 2: 30 };
+
+      const resultWithReservation = realGetMessagesWithinTokenLimit({
+        messages,
+        maxContextTokens: 100,
+        indexTokenCountMap,
+        tokenCounter,
+        instructionTokens: 60,
+      });
+
+      const resultWithoutReservation = realGetMessagesWithinTokenLimit({
+        messages,
+        maxContextTokens: 100,
+        indexTokenCountMap,
+        tokenCounter,
+      });
+
+      // With reservation, fewer messages fit.
+      expect(resultWithReservation.context.length).toBeLessThan(
+        resultWithoutReservation.context.length
+      );
+    });
+
+    it('ignores instructionTokens when a system message is already in the messages array', () => {
+      const tokenCounter = createTestTokenCounter();
+      // Caller wires the system message in directly — its tokens come from
+      // indexTokenCountMap[0], not from instructionTokens. Setting
+      // instructionTokens here must not cause a double-deduction.
+      const messages = [
+        new SystemMessage('sys'),
+        new HumanMessage('q'),
+        new AIMessage('a'),
+      ];
+      const indexTokenCountMap = { 0: 10, 1: 5, 2: 5 };
+
+      const result = realGetMessagesWithinTokenLimit({
+        messages,
+        maxContextTokens: 50,
+        indexTokenCountMap,
+        tokenCounter,
+        instructionTokens: 9999, // would over-reserve if double-counted
+      });
+
+      expect(result.context.length).toBe(3);
+    });
+  });
+
   describe('checkValidNumber', () => {
     it('should return true for valid positive numbers', () => {
       expect(checkValidNumber(5)).toBe(true);
@@ -537,9 +598,15 @@ describe('Prune Messages Tests', () => {
       const tokenCounter = createTestTokenCounter();
       const messages = [
         new SystemMessage('System instruction'),
-        new AIMessage('AI message 1'),
+        new AIMessage({
+          content: 'AI message 1',
+          tool_calls: [{ name: 't1', args: {}, id: 'tool1' }],
+        }),
         new ToolMessage({ content: 'Tool result 1', tool_call_id: 'tool1' }),
-        new AIMessage('AI message 2'),
+        new AIMessage({
+          content: 'AI message 2',
+          tool_calls: [{ name: 't2', args: {}, id: 'tool2' }],
+        }),
         new ToolMessage({ content: 'Tool result 2', tool_call_id: 'tool2' }),
       ];
 
@@ -574,7 +641,10 @@ describe('Prune Messages Tests', () => {
       const messages = [
         new SystemMessage('System instruction'),
         new HumanMessage('Human message 1'),
-        new AIMessage('AI message 1'),
+        new AIMessage({
+          content: 'AI message 1',
+          tool_calls: [{ name: 't1', args: {}, id: 'tool1' }],
+        }),
         new ToolMessage({ content: 'Tool result 1', tool_call_id: 'tool1' }),
         new HumanMessage('Human message 2'),
         new ToolMessage({ content: 'Tool result 2', tool_call_id: 'tool2' }),
@@ -599,12 +669,12 @@ describe('Prune Messages Tests', () => {
 
       const result = pruneMessages({ messages });
 
-      // The context should include the system message, Human message 2, and Tool result 2
-      // It should NOT start with Tool result 2 alone
-      expect(result.context.length).toBe(3);
+      // Tool result 2 has no parent AIMessage with a matching tool_call (the
+      // test fixture is structurally broken), so orphan repair drops it.
+      // The context now ends cleanly at the Human message.
+      expect(result.context.length).toBe(2);
       expect(result.context[0]).toBe(messages[0]); // System message
       expect(result.context[1]).toBe(messages[4]); // Human message 2
-      expect(result.context[2]).toBe(messages[5]); // Tool result 2
     });
 
     it('should handle the case where a tool message is followed by an AI message', () => {
@@ -676,11 +746,20 @@ describe('Prune Messages Tests', () => {
       const messages = [
         new SystemMessage('System instruction'),
         new HumanMessage('Human message 1'),
-        new AIMessage('AI message 1 with tool use'),
+        new AIMessage({
+          content: 'AI message 1 with tool use',
+          tool_calls: [{ name: 't1', args: {}, id: 'tool1' }],
+        }),
         new ToolMessage({ content: 'Tool result 1', tool_call_id: 'tool1' }),
-        new AIMessage('AI message 2 with tool use'),
+        new AIMessage({
+          content: 'AI message 2 with tool use',
+          tool_calls: [{ name: 't2', args: {}, id: 'tool2' }],
+        }),
         new ToolMessage({ content: 'Tool result 2', tool_call_id: 'tool2' }),
-        new AIMessage('AI message 3 with tool use'),
+        new AIMessage({
+          content: 'AI message 3 with tool use',
+          tool_calls: [{ name: 't3', args: {}, id: 'tool3' }],
+        }),
         new ToolMessage({ content: 'Tool result 3', tool_call_id: 'tool3' }),
       ];
 
@@ -749,10 +828,10 @@ describe('Prune Messages Tests', () => {
       const tokenCounter = createTestTokenCounter();
       const messages = [
         new SystemMessage('System instruction'), // 18 chars
-        new HumanMessage('First message from user'),  // 23 chars
+        new HumanMessage('First message from user'), // 23 chars
         new AIMessage('First response from assistant'), // 29 chars
         new HumanMessage('Second message from user'), // 24 chars
-        new AIMessage('Second response'),  // 15 chars
+        new AIMessage('Second response'), // 15 chars
         new HumanMessage('Third message'), // 13 chars
         new AIMessage('Third response'), // 14 chars
       ];
@@ -798,7 +877,7 @@ describe('Prune Messages Tests', () => {
       for (const msg of result.messagesToRefine) {
         expect(msg).toBeDefined();
         expect(typeof msg.getType()).toBe('string');
-      };
+      }
     });
 
     it('should return messagesToRefine compatible with summarization callbacks', () => {
@@ -837,7 +916,14 @@ describe('Prune Messages Tests', () => {
 
         // Each message should have a valid type
         const msgType = msg.getType();
-        expect(['human', 'ai', 'system', 'tool', 'generic', 'function']).toContain(msgType);
+        expect([
+          'human',
+          'ai',
+          'system',
+          'tool',
+          'generic',
+          'function',
+        ]).toContain(msgType);
 
         // Each message should have accessible content (string or array)
         expect(msg.content).toBeDefined();
@@ -852,7 +938,9 @@ describe('Prune Messages Tests', () => {
         content: msg.content,
       }));
       expect(serialized.length).toBe(result.messagesToRefine.length);
-      expect(serialized.every((s) => s.type && s.content !== undefined)).toBe(true);
+      expect(serialized.every((s) => s.type && s.content !== undefined)).toBe(
+        true
+      );
     });
   });
 

package/src/specs/thinking-handoff.test.ts

@@ -61,7 +61,7 @@ describe('Thinking-Enabled Agent Handoff Tests', () => {
           agentId: 'specialist',
           provider: Providers.ANTHROPIC,
           clientOptions: {
-            modelName: 'claude-3-7-sonnet-20250219',
+            modelName: 'claude-sonnet-4-5-20250929',
             apiKey: 'test-key',
             thinking: {
               type: 'enabled',
@@ -77,7 +77,7 @@ describe('Thinking-Enabled Agent Handoff Tests', () => {
         {
           from: 'supervisor',
           to: 'specialist',
-          edgeType: EdgeType.TRANSFER,
+          edgeType: EdgeType.HANDOFF,
           description: 'Transfer to specialist for detailed analysis',
         },
       ];
@@ -150,7 +150,7 @@ describe('Thinking-Enabled Agent Handoff Tests', () => {
           agentId: 'agent_b',
           provider: Providers.ANTHROPIC,
           clientOptions: {
-            modelName: 'claude-3-7-sonnet-20250219',
+            modelName: 'claude-sonnet-4-5-20250929',
             apiKey: 'test-key',
             thinking: {
               type: 'enabled',
@@ -166,7 +166,7 @@ describe('Thinking-Enabled Agent Handoff Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: EdgeType.TRANSFER,
+          edgeType: EdgeType.HANDOFF,
         },
       ];
 
@@ -195,7 +195,7 @@ describe('Thinking-Enabled Agent Handoff Tests', () => {
           provider: Providers.BEDROCK,
           clientOptions: {
             region: 'us-east-1',
-            model: 'anthropic.claude-3-5-haiku-20241022-v1:0',
+            model: 'us.anthropic.claude-haiku-4-5-20251001-v1:0',
             // No thinking config
           },
           instructions: 'You are a coordinator',
@@ -206,7 +206,7 @@ describe('Thinking-Enabled Agent Handoff Tests', () => {
           provider: Providers.BEDROCK,
           clientOptions: {
             region: 'us-east-1',
-            model: 'us.anthropic.claude-3-7-sonnet-20250219-v1:0',
+            model: 'us.anthropic.claude-sonnet-4-5-20250929-v1:0',
             additionalModelRequestFields: {
               thinking: {
                 type: 'enabled',
@@ -223,7 +223,7 @@ describe('Thinking-Enabled Agent Handoff Tests', () => {
         {
           from: 'coordinator',
           to: 'analyst',
-          edgeType: EdgeType.TRANSFER,
+          edgeType: EdgeType.HANDOFF,
           description: 'Transfer to analyst for deep analysis',
         },
       ];
@@ -280,7 +280,7 @@ describe('Thinking-Enabled Agent Handoff Tests', () => {
           provider: Providers.BEDROCK,
           clientOptions: {
             region: 'us-east-1',
-            model: 'us.anthropic.claude-3-7-sonnet-20250219-v1:0',
+            model: 'us.anthropic.claude-sonnet-4-5-20250929-v1:0',
             additionalModelRequestFields: {
               thinking: {
                 type: 'enabled',
@@ -297,7 +297,7 @@ describe('Thinking-Enabled Agent Handoff Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: EdgeType.TRANSFER,
+          edgeType: EdgeType.HANDOFF,
         },
       ];
 
@@ -343,7 +343,7 @@ describe('Thinking-Enabled Agent Handoff Tests', () => {
           provider: Providers.BEDROCK,
           clientOptions: {
             region: 'us-east-1',
-            model: 'us.anthropic.claude-3-7-sonnet-20250219-v1:0',
+            model: 'us.anthropic.claude-sonnet-4-5-20250929-v1:0',
             additionalModelRequestFields: {
               thinking: {
                 type: 'enabled',
@@ -360,7 +360,7 @@ describe('Thinking-Enabled Agent Handoff Tests', () => {
         {
           from: 'supervisor',
           to: 'bedrock_specialist',
-          edgeType: EdgeType.TRANSFER,
+          edgeType: EdgeType.HANDOFF,
           description: 'Transfer to Bedrock specialist',
         },
       ];
@@ -434,7 +434,7 @@ describe('Thinking-Enabled Agent Handoff Tests', () => {
           agentId: 'reviewer',
           provider: Providers.ANTHROPIC,
           clientOptions: {
-            modelName: 'claude-3-7-sonnet-20250219',
+            modelName: 'claude-sonnet-4-5-20250929',
             apiKey: 'test-key',
             thinking: {
               type: 'enabled',
@@ -450,12 +450,12 @@ describe('Thinking-Enabled Agent Handoff Tests', () => {
         {
           from: 'router',
           to: 'processor',
-          edgeType: EdgeType.TRANSFER,
+          edgeType: EdgeType.HANDOFF,
         },
         {
           from: 'processor',
           to: 'reviewer',
-          edgeType: EdgeType.TRANSFER,
+          edgeType: EdgeType.HANDOFF,
         },
       ];
 
@@ -508,7 +508,7 @@ describe('Thinking-Enabled Agent Handoff Tests', () => {
           agentId: 'agent_a',
           provider: Providers.ANTHROPIC,
           clientOptions: {
-            modelName: 'claude-3-7-sonnet-20250219',
+            modelName: 'claude-sonnet-4-5-20250929',
             apiKey: 'test-key',
             thinking: {
               type: 'enabled',
@@ -522,7 +522,7 @@ describe('Thinking-Enabled Agent Handoff Tests', () => {
           agentId: 'agent_b',
           provider: Providers.ANTHROPIC,
           clientOptions: {
-            modelName: 'claude-3-7-sonnet-20250219',
+            modelName: 'claude-sonnet-4-5-20250929',
             apiKey: 'test-key',
             thinking: {
               type: 'enabled',
@@ -538,7 +538,7 @@ describe('Thinking-Enabled Agent Handoff Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: EdgeType.TRANSFER,
+          edgeType: EdgeType.HANDOFF,
         },
       ];
 
@@ -587,7 +587,7 @@ describe('Thinking-Enabled Agent Handoff Tests', () => {
           agentId: 'agent_b',
           provider: Providers.ANTHROPIC,
           clientOptions: {
-            modelName: 'claude-3-7-sonnet-20250219',
+            modelName: 'claude-sonnet-4-5-20250929',
             apiKey: 'test-key',
             thinking: {
               type: 'enabled',
@@ -603,7 +603,7 @@ describe('Thinking-Enabled Agent Handoff Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: EdgeType.TRANSFER,
+          edgeType: EdgeType.HANDOFF,
         },
       ];