@illuma-ai/agents 1.1.28 → 1.3.1

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

@@ -0,0 +1,136 @@
+/**
+ * Unit tests for context-overflow error classification.
+ *
+ * The graph's emergency-prune retry relies on these helpers to decide
+ * whether a provider failure warrants a truncated retry. False positives
+ * cost one extra retry; false negatives surface an opaque failure to the
+ * user. Both are cheaper than the previous inline substring matching,
+ * which missed phrases like "request_too_large" (Anthropic 429-adjacent)
+ * and could falsely trigger on rate-limit errors mentioning "too many".
+ */
+import {
+  extractErrorMessage,
+  isContextOverflowError,
+  isLikelyContextOverflowError,
+} from '../errors';
+
+describe('extractErrorMessage', () => {
+  it('returns empty string for null/undefined', () => {
+    expect(extractErrorMessage(null)).toBe('');
+    expect(extractErrorMessage(undefined)).toBe('');
+  });
+
+  it('returns the string directly', () => {
+    expect(extractErrorMessage('something broke')).toBe('something broke');
+  });
+
+  it('reads Error.message', () => {
+    expect(extractErrorMessage(new Error('boom'))).toBe('boom');
+  });
+
+  it('reads plain-object message/error fields', () => {
+    expect(extractErrorMessage({ message: 'm' })).toBe('m');
+    expect(extractErrorMessage({ error: 'e' })).toBe('e');
+    expect(extractErrorMessage({ error: { message: 'nested' } })).toBe(
+      'nested'
+    );
+  });
+
+  it('falls back to JSON stringify for unknown shapes', () => {
+    expect(extractErrorMessage({ status: 500 })).toBe('{"status":500}');
+  });
+});
+
+describe('isContextOverflowError (strict)', () => {
+  it('returns false for empty input', () => {
+    expect(isContextOverflowError()).toBe(false);
+    expect(isContextOverflowError('')).toBe(false);
+  });
+
+  it('matches Anthropic prompt-too-long', () => {
+    expect(
+      isContextOverflowError('prompt is too long: 250000 tokens > 200000')
+    ).toBe(true);
+  });
+
+  it('matches OpenAI context_length_exceeded', () => {
+    expect(
+      isContextOverflowError(
+        "This model's maximum context length is 128000 tokens. context_length_exceeded"
+      )
+    ).toBe(true);
+  });
+
+  it('matches Bedrock input-too-long', () => {
+    expect(
+      isContextOverflowError(
+        'ValidationException: Input is too long for requested model.'
+      )
+    ).toBe(true);
+  });
+
+  it('matches request_too_large', () => {
+    expect(
+      isContextOverflowError('Error code 413: request_too_large')
+    ).toBe(true);
+  });
+
+  it('is case-insensitive', () => {
+    expect(isContextOverflowError('PROMPT IS TOO LONG')).toBe(true);
+  });
+
+  it('rejects rate-limit errors even if they mention "too many"', () => {
+    expect(
+      isContextOverflowError('429 rate_limit_exceeded: too many requests')
+    ).toBe(false);
+  });
+
+  it('rejects auth / billing errors', () => {
+    expect(isContextOverflowError('insufficient quota on billing plan')).toBe(
+      false
+    );
+    expect(isContextOverflowError('forbidden: missing permission')).toBe(false);
+  });
+
+  it('does not match loose phrases like bare "too long"', () => {
+    // Strict check should NOT fire on just "too long" — that's for the
+    // loose variant. Keeps the retry budget tight.
+    expect(isContextOverflowError('the response was too long')).toBe(false);
+  });
+});
+
+describe('isLikelyContextOverflowError (loose)', () => {
+  it('matches everything the strict check matches', () => {
+    expect(isLikelyContextOverflowError('prompt is too long')).toBe(true);
+    expect(isLikelyContextOverflowError('context_length_exceeded')).toBe(true);
+  });
+
+  it('matches heuristic regex: bare "too long"', () => {
+    expect(isLikelyContextOverflowError('response was too long')).toBe(true);
+  });
+
+  it('matches heuristic regex: 413 status code', () => {
+    expect(isLikelyContextOverflowError('HTTP 413 payload')).toBe(true);
+  });
+
+  it('matches "context ... exceed" in either order', () => {
+    expect(isLikelyContextOverflowError('your context exceeds limits')).toBe(
+      true
+    );
+    expect(isLikelyContextOverflowError('exceeds context window')).toBe(true);
+  });
+
+  it('still rejects rate-limit / auth even on loose match', () => {
+    expect(
+      isLikelyContextOverflowError('rate limit: too many requests queued')
+    ).toBe(false);
+    expect(
+      isLikelyContextOverflowError('authorization exceeds allowed quota')
+    ).toBe(false);
+  });
+
+  it('returns false for unrelated errors', () => {
+    expect(isLikelyContextOverflowError('ECONNREFUSED')).toBe(false);
+    expect(isLikelyContextOverflowError('unexpected token in JSON')).toBe(false);
+  });
+});

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');
+  });
+});

package/src/utils/childAgentContext.ts

@@ -0,0 +1,259 @@
+/**
+ * Child-agent context preparation utilities.
+ *
+ * When a parent agent invokes a child agent — via handoff, sequence edge,
+ * or scoped subgraph — the child cannot just receive `state.messages`
+ * verbatim. The parent's conversation contains tool_use/tool_result blocks
+ * that are (a) often incompatible with the child's tool registry, and
+ * (b) actively harmful to the child's ability to reason cleanly about its
+ * own task (noise → schema confusion → malformed tool_use).
+ *
+ * This module provides the two canonical strategies, extracted from
+ * `MultiAgentGraph` so they can be unit-tested in isolation and reused by
+ * future sub-agent orchestrators:
+ *
+ *   1. `prepareHandoffMessages` — "cleaned parent history"
+ *      Used when the child still needs the orchestrator's context (it's
+ *      the handoff target). Drops orphaned tool_use, compacts paired
+ *      tool_use/tool_result into text summaries, and guarantees the tail
+ *      is a HumanMessage so Bedrock/VertexAI won't reject the conversation
+ *      with "assistant message prefill" errors.
+ *
+ *   2. `prepareIsolatedChildMessages` — "fresh session"
+ *      Used for downstream sequence-node children inside a scoped subgraph.
+ *      The child sees only the original user request plus a synthetic
+ *      HumanMessage summarizing the upstream agent's final text output and
+ *      directing the child to act. Raw upstream tool_use/tool_result blocks
+ *      are discarded.
+ *
+ * Both helpers are pure functions over message arrays — no I/O, no
+ * LangGraph coupling — so they can be exercised by unit tests with
+ * synthetic message fixtures.
+ */
+
+import { AIMessage, HumanMessage, ToolMessage } from '@langchain/core/messages';
+import type { AIMessageChunk, BaseMessage } from '@langchain/core/messages';
+
+/* -------------------------------------------------------------------------- */
+/*  Prompt template constants (kept outside the functions for reuse/tuning)   */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Prefix injected in front of a trailing AIMessage when we flip it to a
+ * HumanMessage to satisfy provider "last message must be user" rules.
+ */
+export const HANDOFF_TAIL_CONTEXT_PREFIX = '[Context from orchestrator]: ';
+
+/**
+ * Directive task-framing wrapper for downstream scoped-subgraph children.
+ *
+ * Design notes — each line is load-bearing:
+ *  - "Prior step output" names the upstream role without leaking the
+ *    agent's internal id.
+ *  - "You MUST now perform..." replaces ambiguity with obligation.
+ *  - "system instructions" references the agent's stored system prompt
+ *    as the source of task definition — so operators can tune behavior
+ *    via data, not code.
+ *  - The tool-first clause prevents small/fast models from stalling on a
+ *    text-only acknowledgement when a tool action is expected.
+ */
+export function buildIsolatedChildPrompt(upstreamText: string): string {
+  return (
+    '## Prior step output\n\n' +
+    upstreamText +
+    '\n\n---\n\n' +
+    '## Your task\n\n' +
+    'The previous step in this workflow has completed. You MUST now ' +
+    'perform your own task as defined in your system instructions, ' +
+    "using the prior step's output as input where relevant.\n\n" +
+    'If your task requires calling a tool, call it directly — do not ' +
+    'ask for clarification and do not produce a text-only response when ' +
+    'a tool action is expected.'
+  );
+}
+
+/* -------------------------------------------------------------------------- */
+/*  Internal helpers                                                          */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Extract concatenated text content from an AI message's content field.
+ * Handles both the string shape (OpenAI/plain) and the array-of-blocks
+ * shape (Anthropic/Bedrock).
+ */
+function extractAIText(msg: AIMessage | AIMessageChunk): string {
+  const content = msg.content;
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content)) return '';
+  return (content as Array<{ type?: string; text?: string }>)
+    .filter((b) => b.type === 'text' && typeof b.text === 'string')
+    .map((b) => b.text ?? '')
+    .join('\n');
+}
+
+/* -------------------------------------------------------------------------- */
+/*  Strategy 1: cleaned parent history (handoff target / root subgraph)       */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Prepare messages for a handoff child agent.
+ *
+ * Handles two problems that break Bedrock/Anthropic conversations:
+ *
+ * 1. **Orphaned tool_use**: The parent's AI message contains a `tool_use`
+ *    block for the handoff tool itself, with no matching `tool_result`.
+ *    Providers (Bedrock/Anthropic) reject this.
+ *
+ * 2. **Paired tool_use/tool_result in history**: The child may not have
+ *    the same tools as the parent. Bedrock requires `toolConfig` when any
+ *    tool_use/tool_result blocks exist in the history. Compacting these
+ *    into text summaries avoids the requirement and reduces context bloat.
+ *
+ * Also ensures the tail is a HumanMessage — some providers reject a
+ * conversation that ends with an assistant message.
+ *
+ * @param messages - Current state messages from the parent
+ * @returns A sanitized copy, safe to pass to any provider as the child's
+ *          input regardless of which tools the child has registered.
+ */
+export function prepareHandoffMessages(messages: BaseMessage[]): BaseMessage[] {
+  if (messages.length === 0) return messages;
+
+  /** Collect tool_result IDs so we know which tool_use blocks are paired */
+  const pairedToolCallIds = new Set<string>();
+  for (const msg of messages) {
+    if (msg.getType() === 'tool') {
+      const tm = msg as ToolMessage;
+      if (tm.tool_call_id) pairedToolCallIds.add(tm.tool_call_id);
+    }
+  }
+
+  /**
+   * Pass 1: Drop all ToolMessages (paired ones are compacted in pass 2),
+   * rewrite AI messages with tool_calls into plain-text summaries, leave
+   * other messages untouched.
+   */
+  const cleaned: BaseMessage[] = [];
+  for (const msg of messages) {
+    if (msg.getType() === 'tool') continue;
+
+    if (msg.getType() !== 'ai') {
+      cleaned.push(msg);
+      continue;
+    }
+
+    const aiMsg = msg as AIMessage | AIMessageChunk;
+    const toolCalls = aiMsg.tool_calls ?? [];
+    if (toolCalls.length === 0) {
+      cleaned.push(msg);
+      continue;
+    }
+
+    const textContent = extractAIText(aiMsg);
+
+    const toolSummaries: string[] = [];
+    for (const tc of toolCalls) {
+      if (tc.id != null && pairedToolCallIds.has(tc.id)) {
+        const toolResult = messages.find(
+          (m) =>
+            m.getType() === 'tool' && (m as ToolMessage).tool_call_id === tc.id
+        ) as ToolMessage | undefined;
+        const resultContent = toolResult
+          ? typeof toolResult.content === 'string'
+            ? toolResult.content.slice(0, 500)
+            : '[complex result]'
+          : '[no result]';
+        toolSummaries.push(`[Tool "${tc.name}": ${resultContent}]`);
+      }
+      // Orphaned tool_use blocks (no matching result) are silently dropped.
+    }
+
+    const parts = [textContent, ...toolSummaries].filter(Boolean);
+    if (parts.length > 0) {
+      cleaned.push(
+        new AIMessage({ content: parts.join('\n\n'), id: aiMsg.id })
+      );
+    }
+  }
+
+  /**
+   * Ensure messages end with a HumanMessage. After stripping tool artifacts
+   * the tail may be an AIMessage, which Bedrock/VertexAI reject. Convert it
+   * to a HumanMessage preserving whatever text content was present, or drop
+   * it entirely if empty.
+   */
+  if (cleaned.length > 0 && cleaned[cleaned.length - 1].getType() === 'ai') {
+    const lastAI = cleaned[cleaned.length - 1];
+    const content = typeof lastAI.content === 'string' ? lastAI.content : '';
+    if (content.trim()) {
+      cleaned[cleaned.length - 1] = new HumanMessage(
+        `${HANDOFF_TAIL_CONTEXT_PREFIX}${content}`
+      );
+    } else {
+      cleaned.pop();
+    }
+  }
+
+  return cleaned;
+}
+
+/* -------------------------------------------------------------------------- */
+/*  Strategy 2: isolated fresh session (downstream scoped-subgraph child)     */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Build an ISOLATED message context for a downstream scoped-subgraph node.
+ *
+ * Unlike `prepareHandoffMessages` (which cleans up tool_use artifacts but
+ * preserves most of the parent history), this helper produces a fresh
+ * minimal context containing only:
+ *
+ *   1. The original user request (first HumanMessage in the history)
+ *   2. A synthetic HumanMessage summarizing the upstream agent's final
+ *      text output and directing the downstream agent to act on it
+ *
+ * Tool_use / tool_result blocks from the upstream agent are discarded —
+ * the downstream agent shouldn't reason about how the upstream agent did
+ * its work, only about the result.
+ *
+ * This "fresh subagent session" pattern is the primary defense against
+ * schema confusion / malformed tool_use JSON that occurs when downstream
+ * models see a noisy upstream conversation.
+ *
+ * Defensive fallback: if the messages array contains neither a user
+ * message nor a non-empty upstream AI message, return the input unchanged
+ * so the caller still has something to invoke on. This only matters for
+ * malformed state fixtures in tests.
+ */
+export function prepareIsolatedChildMessages(
+  messages: BaseMessage[]
+): BaseMessage[] {
+  if (messages.length === 0) return messages;
+
+  /** First HumanMessage is the original user request */
+  const originalUser = messages.find((m) => m.getType() === 'human');
+
+  /** Most recent AIMessage with non-empty text content */
+  let upstreamText = '';
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i];
+    if (msg.getType() !== 'ai') continue;
+    const text = extractAIText(msg as AIMessage | AIMessageChunk);
+    if (text.trim()) {
+      upstreamText = text;
+      break;
+    }
+  }
+
+  const result: BaseMessage[] = [];
+  if (originalUser) result.push(originalUser);
+
+  if (upstreamText.trim()) {
+    result.push(new HumanMessage(buildIsolatedChildPrompt(upstreamText)));
+  } else if (result.length === 0) {
+    /** Defensive: nothing to isolate — fall back to raw messages */
+    return messages;
+  }
+
+  return result;
+}