@illuma-ai/agents 1.1.25 → 1.3.0

package/src/utils/__tests__/childAgentContext.test.ts

@@ -0,0 +1,217 @@
+/**
+ * Unit tests for child-agent context preparation.
+ *
+ * These strategies are the primary defense against schema confusion and
+ * Bedrock/VertexAI message-shape rejections, so their behavior must be
+ * locked down with fixtures that mirror real provider output shapes.
+ */
+import {
+  AIMessage,
+  HumanMessage,
+  SystemMessage,
+  ToolMessage,
+} from '@langchain/core/messages';
+import type { BaseMessage } from '@langchain/core/messages';
+import {
+  HANDOFF_TAIL_CONTEXT_PREFIX,
+  buildIsolatedChildPrompt,
+  prepareHandoffMessages,
+  prepareIsolatedChildMessages,
+} from '../childAgentContext';
+
+describe('buildIsolatedChildPrompt', () => {
+  it('wraps upstream text in the prior-step / your-task sections', () => {
+    const out = buildIsolatedChildPrompt('RESEARCH FINDINGS');
+    expect(out).toContain('## Prior step output');
+    expect(out).toContain('RESEARCH FINDINGS');
+    expect(out).toContain('## Your task');
+    expect(out).toMatch(/You MUST now/);
+  });
+
+  it('instructs the model to call tools directly without asking for clarification', () => {
+    const out = buildIsolatedChildPrompt('x');
+    expect(out).toMatch(/call it directly/);
+    expect(out).toMatch(/do not ask for clarification/);
+  });
+});
+
+describe('prepareHandoffMessages', () => {
+  it('returns an empty array unchanged', () => {
+    expect(prepareHandoffMessages([])).toEqual([]);
+  });
+
+  it('preserves system and human messages verbatim', () => {
+    const msgs: BaseMessage[] = [
+      new SystemMessage('sys'),
+      new HumanMessage('hello'),
+    ];
+    const out = prepareHandoffMessages(msgs);
+    expect(out).toHaveLength(2);
+    expect(out[0].getType()).toBe('system');
+    expect(out[1].getType()).toBe('human');
+  });
+
+  it('drops orphaned tool_use blocks (handoff tool has no matching result)', () => {
+    const ai = new AIMessage({
+      content: 'transferring',
+      tool_calls: [{ name: 'handoff_to_writer', args: {}, id: 'call_1' }],
+    });
+    const out = prepareHandoffMessages([new HumanMessage('go'), ai]);
+    // The assistant tail becomes a HumanMessage with the context prefix
+    // because the orphaned tool_use was stripped, leaving only text.
+    expect(out).toHaveLength(2);
+    expect(out[1].getType()).toBe('human');
+    expect(out[1].content).toContain('transferring');
+    expect(out[1].content).toContain(HANDOFF_TAIL_CONTEXT_PREFIX);
+  });
+
+  it('compacts paired tool_use/tool_result into a text summary', () => {
+    const ai = new AIMessage({
+      content: '',
+      tool_calls: [{ name: 'search', args: { q: 'x' }, id: 'call_a' }],
+    });
+    const toolResult = new ToolMessage({
+      content: 'hit: 42',
+      tool_call_id: 'call_a',
+    });
+    const out = prepareHandoffMessages([
+      new HumanMessage('find x'),
+      ai,
+      toolResult,
+      new HumanMessage('what did you find?'),
+    ]);
+    // The paired tool_use+result should have become a text summary on the
+    // rewritten AI message; the original ToolMessage should be gone.
+    expect(out.some((m) => m.getType() === 'tool')).toBe(false);
+    const rewrittenAI = out.find((m) => m.getType() === 'ai');
+    expect(rewrittenAI).toBeDefined();
+    expect(String(rewrittenAI?.content)).toContain('[Tool "search"');
+    expect(String(rewrittenAI?.content)).toContain('hit: 42');
+  });
+
+  it('truncates long tool_result content at 500 chars in the summary', () => {
+    const long = 'x'.repeat(1200);
+    const ai = new AIMessage({
+      content: '',
+      tool_calls: [{ name: 'dump', args: {}, id: 'call_big' }],
+    });
+    const tool = new ToolMessage({ content: long, tool_call_id: 'call_big' });
+    const out = prepareHandoffMessages([new HumanMessage('hi'), ai, tool]);
+    // After the paired compaction the tail is an AIMessage with no text, so
+    // it gets dropped (empty) — find the one that carries the summary by
+    // scanning for the "[Tool" marker in any message.
+    const blob = out.map((m) => String(m.content)).join(' ');
+    expect(blob).toContain('[Tool "dump"');
+    // The truncated slice is 500 chars of x, not the full 1200.
+    const match = blob.match(/x+/);
+    expect(match).toBeTruthy();
+    expect((match?.[0].length ?? 0) <= 500).toBe(true);
+  });
+
+  it('ensures the tail message is a HumanMessage by rewriting a trailing AI', () => {
+    const msgs: BaseMessage[] = [
+      new HumanMessage('question'),
+      new AIMessage('plain text answer'),
+    ];
+    const out = prepareHandoffMessages(msgs);
+    expect(out[out.length - 1].getType()).toBe('human');
+    expect(out[out.length - 1].content).toBe(
+      `${HANDOFF_TAIL_CONTEXT_PREFIX}plain text answer`
+    );
+  });
+
+  it('drops a trailing empty AIMessage instead of creating an empty human', () => {
+    const msgs: BaseMessage[] = [
+      new HumanMessage('q'),
+      new AIMessage(''), // empty, nothing to carry forward
+    ];
+    const out = prepareHandoffMessages(msgs);
+    expect(out).toHaveLength(1);
+    expect(out[0].getType()).toBe('human');
+  });
+});
+
+describe('prepareIsolatedChildMessages', () => {
+  it('returns empty input unchanged', () => {
+    expect(prepareIsolatedChildMessages([])).toEqual([]);
+  });
+
+  it('keeps only the first human message and a synthetic directive', () => {
+    const msgs: BaseMessage[] = [
+      new HumanMessage('original request'),
+      new AIMessage('upstream produced this result'),
+    ];
+    const out = prepareIsolatedChildMessages(msgs);
+    expect(out).toHaveLength(2);
+    expect(out[0].getType()).toBe('human');
+    expect(out[0].content).toBe('original request');
+    expect(out[1].getType()).toBe('human');
+    expect(String(out[1].content)).toContain('upstream produced this result');
+    expect(String(out[1].content)).toContain('## Your task');
+  });
+
+  it('discards upstream tool_use/tool_result blocks entirely', () => {
+    const aiWithTool = new AIMessage({
+      content: 'working',
+      tool_calls: [{ name: 'search', args: {}, id: 'c1' }],
+    });
+    const toolResult = new ToolMessage({
+      content: 'search result',
+      tool_call_id: 'c1',
+    });
+    const aiFinal = new AIMessage('final summary text');
+    const out = prepareIsolatedChildMessages([
+      new HumanMessage('user ask'),
+      aiWithTool,
+      toolResult,
+      aiFinal,
+    ]);
+    // Must not contain any ToolMessage or upstream tool_calls.
+    expect(out.some((m) => m.getType() === 'tool')).toBe(false);
+    // The synthetic directive should reference only the final text output.
+    const directive = String(out[1].content);
+    expect(directive).toContain('final summary text');
+    expect(directive).not.toContain('search result');
+  });
+
+  it('picks the most recent non-empty AI text output', () => {
+    const msgs: BaseMessage[] = [
+      new HumanMessage('req'),
+      new AIMessage('older text'),
+      new AIMessage(''),
+      new AIMessage('newer text'),
+    ];
+    const out = prepareIsolatedChildMessages(msgs);
+    expect(String(out[1].content)).toContain('newer text');
+    expect(String(out[1].content)).not.toContain('older text');
+  });
+
+  it('handles AI content in Anthropic array-of-blocks shape', () => {
+    const ai = new AIMessage({
+      content: [
+        { type: 'tool_use', name: 'x', input: {}, id: 'c1' },
+        { type: 'text', text: 'block text result' },
+      ] as unknown as string, // the SDK types are strict, cast for fixture
+    });
+    const out = prepareIsolatedChildMessages([new HumanMessage('q'), ai]);
+    expect(out).toHaveLength(2);
+    expect(String(out[1].content)).toContain('block text result');
+  });
+
+  it('falls back to raw messages if no human and no upstream text exist', () => {
+    const msgs: BaseMessage[] = [new SystemMessage('just system')];
+    const out = prepareIsolatedChildMessages(msgs);
+    expect(out).toBe(msgs);
+  });
+
+  it('returns just the user message when upstream has no text content', () => {
+    const msgs: BaseMessage[] = [
+      new HumanMessage('only user'),
+      new AIMessage(''),
+    ];
+    const out = prepareIsolatedChildMessages(msgs);
+    expect(out).toHaveLength(1);
+    expect(out[0].getType()).toBe('human');
+    expect(out[0].content).toBe('only user');
+  });
+});

package/src/utils/__tests__/finishReasons.test.ts

@@ -0,0 +1,55 @@
+/**
+ * Unit tests for the finish-reason detection helpers.
+ *
+ * Guards the single source of truth that truncation-aware callers
+ * (Graph.ts sticky finish reason, host continuation retry) rely on.
+ */
+import {
+  TRUNCATION_FINISH_REASONS,
+  isTruncationReason,
+} from '../finishReasons';
+
+describe('TRUNCATION_FINISH_REASONS', () => {
+  it('includes every provider-specific truncation value we support', () => {
+    expect(TRUNCATION_FINISH_REASONS.has('max_tokens')).toBe(true);
+    expect(TRUNCATION_FINISH_REASONS.has('length')).toBe(true);
+    expect(TRUNCATION_FINISH_REASONS.has('MAX_TOKENS')).toBe(true);
+  });
+
+  it('is case-sensitive — lowercase vertex value is not accepted', () => {
+    // VertexAI uses the uppercase enum name; lowercase would be a wire bug
+    // we do not want to silently treat as truncation.
+    expect(TRUNCATION_FINISH_REASONS.has('max_Tokens')).toBe(false);
+  });
+});
+
+describe('isTruncationReason', () => {
+  it('returns true for Anthropic/Bedrock max_tokens', () => {
+    expect(isTruncationReason('max_tokens')).toBe(true);
+  });
+
+  it('returns true for OpenAI length', () => {
+    expect(isTruncationReason('length')).toBe(true);
+  });
+
+  it('returns true for VertexAI MAX_TOKENS', () => {
+    expect(isTruncationReason('MAX_TOKENS')).toBe(true);
+  });
+
+  it('returns false for the stop/end_turn happy path', () => {
+    expect(isTruncationReason('stop')).toBe(false);
+    expect(isTruncationReason('end_turn')).toBe(false);
+    expect(isTruncationReason('STOP')).toBe(false);
+  });
+
+  it('returns false for tool_use / tool_calls', () => {
+    expect(isTruncationReason('tool_use')).toBe(false);
+    expect(isTruncationReason('tool_calls')).toBe(false);
+  });
+
+  it('returns false for undefined, null, and empty string', () => {
+    expect(isTruncationReason(undefined)).toBe(false);
+    expect(isTruncationReason(null)).toBe(false);
+    expect(isTruncationReason('')).toBe(false);
+  });
+});

package/src/utils/__tests__/toolCallNormalization.test.ts

@@ -0,0 +1,181 @@
+/**
+ * Unit tests for `toolCallNormalization`.
+ *
+ * Exercises every resolution branch of `normalizeToolCallName` and
+ * `normalizeMessageToolCalls` so future edits can't silently regress the
+ * fault-tolerance guarantees the downstream ToolNode relies on.
+ */
+import {
+  normalizeToolCallName,
+  normalizeMessageToolCalls,
+} from '../toolCallNormalization';
+
+const allowed = new Set([
+  'outlook_operations',
+  'teams_operations',
+  'sharepoint_operations',
+  'person_lookup',
+]);
+
+describe('normalizeToolCallName', () => {
+  describe('exact match fast path', () => {
+    it('returns the name unchanged when it matches exactly', () => {
+      expect(normalizeToolCallName('outlook_operations', allowed)).toBe(
+        'outlook_operations'
+      );
+    });
+  });
+
+  describe('delimiter normalization', () => {
+    it('maps slash delimiters to underscore', () => {
+      expect(normalizeToolCallName('outlook/operations', allowed)).toBe(
+        'outlook_operations'
+      );
+    });
+
+    it('maps dot delimiters to underscore', () => {
+      expect(normalizeToolCallName('outlook.operations', allowed)).toBe(
+        'outlook_operations'
+      );
+    });
+
+    it('maps dash delimiters to underscore', () => {
+      expect(normalizeToolCallName('outlook-operations', allowed)).toBe(
+        'outlook_operations'
+      );
+    });
+
+    it('returns the trimmed input when delimiter-normalized form is not registered', () => {
+      // `outlook_operations_v2` is not in the allowed set, so the resolver
+      // leaves the name untouched rather than guessing which variant the
+      // model meant.
+      expect(normalizeToolCallName('outlook.operations-v2', allowed)).toBe(
+        'outlook.operations-v2'
+      );
+    });
+  });
+
+  describe('case folding', () => {
+    it('resolves camelCase to registered snake_case', () => {
+      expect(normalizeToolCallName('Outlook_Operations', allowed)).toBe(
+        'outlook_operations'
+      );
+    });
+
+    it('resolves SCREAMING_CASE', () => {
+      expect(normalizeToolCallName('OUTLOOK_OPERATIONS', allowed)).toBe(
+        'outlook_operations'
+      );
+    });
+  });
+
+  describe('structured candidates — prefix stripping', () => {
+    it('strips functions. prefix', () => {
+      expect(
+        normalizeToolCallName('functions.outlook_operations', allowed)
+      ).toBe('outlook_operations');
+    });
+
+    it('strips tools. prefix', () => {
+      expect(normalizeToolCallName('tools.teams_operations', allowed)).toBe(
+        'teams_operations'
+      );
+    });
+
+    it('takes suffix segment when dotted path has multiple segments', () => {
+      expect(
+        normalizeToolCallName('namespace.group.person_lookup', allowed)
+      ).toBe('person_lookup');
+    });
+  });
+
+  describe('infer from tool_call id when name is empty', () => {
+    it('recovers name from an id containing the tool name', () => {
+      expect(
+        normalizeToolCallName('', allowed, 'call_outlook_operations_42')
+      ).toBe('outlook_operations');
+    });
+
+    it('strips counter suffix from id', () => {
+      expect(normalizeToolCallName('', allowed, 'outlook_operations_1')).toBe(
+        'outlook_operations'
+      );
+    });
+
+    it('returns empty string when id is also absent', () => {
+      expect(normalizeToolCallName('', allowed, undefined)).toBe('');
+    });
+  });
+
+  describe('fail-safe behavior', () => {
+    it('returns the trimmed input when no match is possible', () => {
+      expect(normalizeToolCallName('totally_unknown_tool', allowed)).toBe(
+        'totally_unknown_tool'
+      );
+    });
+
+    it('returns the trimmed input when allowed set is empty', () => {
+      expect(normalizeToolCallName('outlook_operations', new Set())).toBe(
+        'outlook_operations'
+      );
+    });
+
+    it('fails closed when case-insensitive match is ambiguous', () => {
+      const ambiguous = new Set(['Tool', 'tool']);
+      // Two allowed names fold to the same lowercase — resolver must not
+      // guess. It returns the input unchanged (via structured fallthrough).
+      const out = normalizeToolCallName('TOOL', ambiguous);
+      expect(out).toBe('TOOL');
+    });
+  });
+});
+
+describe('normalizeMessageToolCalls', () => {
+  it('rewrites LangChain-style tool_calls in place', () => {
+    const msg = {
+      tool_calls: [
+        { name: 'functions.outlook_operations', id: 'call_1' },
+        { name: 'Teams_Operations', id: 'call_2' },
+      ],
+    };
+    const changed = normalizeMessageToolCalls(msg, allowed);
+    expect(changed).toBe(true);
+    expect(msg.tool_calls[0].name).toBe('outlook_operations');
+    expect(msg.tool_calls[1].name).toBe('teams_operations');
+  });
+
+  it('rewrites Anthropic-style tool_use content blocks in place', () => {
+    const msg = {
+      content: [
+        { type: 'text', text: 'ok' },
+        { type: 'tool_use', name: 'outlook/operations', id: 'toolu_1' },
+      ],
+    };
+    const changed = normalizeMessageToolCalls(msg, allowed);
+    expect(changed).toBe(true);
+    const toolBlock = msg.content[1] as { name?: string };
+    expect(toolBlock.name).toBe('outlook_operations');
+  });
+
+  it('returns false when nothing needed rewriting', () => {
+    const msg = {
+      tool_calls: [{ name: 'outlook_operations', id: 'call_1' }],
+    };
+    expect(normalizeMessageToolCalls(msg, allowed)).toBe(false);
+  });
+
+  it('is a no-op for non-message objects', () => {
+    expect(normalizeMessageToolCalls(null, allowed)).toBe(false);
+    expect(normalizeMessageToolCalls(undefined, allowed)).toBe(false);
+    expect(normalizeMessageToolCalls('string', allowed)).toBe(false);
+  });
+
+  it('handles empty name by inferring from id', () => {
+    const msg = {
+      tool_calls: [{ name: '', id: 'call_person_lookup_99' }],
+    };
+    const changed = normalizeMessageToolCalls(msg, allowed);
+    expect(changed).toBe(true);
+    expect(msg.tool_calls[0].name).toBe('person_lookup');
+  });
+});