@illuma-ai/agents 1.1.28 → 1.3.1

package/src/utils/errors.ts

@@ -0,0 +1,115 @@
+/**
+ * Context-overflow error detection helpers.
+ *
+ * Provider error messages vary — Anthropic returns "prompt is too long",
+ * OpenAI returns "context_length_exceeded", Bedrock returns "Input is too
+ * long", Google returns a size-limit phrase. This module centralises the
+ * phrase list so the agent graph's emergency-prune retry can classify
+ * errors consistently instead of duplicating inline substring matches at
+ * each call site.
+ *
+ * The strict check (`isContextOverflowError`) matches only known phrases.
+ * The loose check (`isLikelyContextOverflowError`) also matches a heuristic
+ * regex for providers we haven't explicitly catalogued. Both filter out
+ * false positives (rate-limit, auth, quota, billing) that might otherwise
+ * trigger an unnecessary prune retry.
+ */
+
+const CONTEXT_OVERFLOW_PHRASES = [
+  'request_too_large',
+  'context length exceeded',
+  'maximum context length',
+  'prompt is too long',
+  'exceeds model context window',
+  'exceeds the model',
+  'too large for model',
+  'context_length_exceeded',
+  'max_tokens',
+  'token limit',
+  'input too long',
+  'input is too long',
+  'payload too large',
+  'content_too_large',
+] as const;
+
+const CONTEXT_OVERFLOW_HINT_RE =
+  /413|too large|too long|context.*exceed|exceed.*context|token.*limit|limit.*token|prompt.*size|size.*limit|maximum.*length|length.*maximum/i;
+
+const FALSE_POSITIVE_RE =
+  /rate.?limit|too many requests|quota|billing|auth|permission|forbidden/i;
+
+/**
+ * Extracts a human-readable error message from an unknown error value.
+ * Walks common shapes: strings, Error instances, `{ message }`,
+ * `{ error: string }`, `{ error: { message } }`. Falls back to
+ * JSON.stringify or String() so callers never have to null-check.
+ */
+export function extractErrorMessage(error: unknown): string {
+  if (error == null) {
+    return '';
+  }
+  if (typeof error === 'string') {
+    return error;
+  }
+  if (error instanceof Error) {
+    return error.message;
+  }
+  if (typeof error === 'object') {
+    const record = error as Record<string, unknown>;
+    if (typeof record.message === 'string') {
+      return record.message;
+    }
+    if (typeof record.error === 'string') {
+      return record.error;
+    }
+    if (
+      typeof record.error === 'object' &&
+      record.error != null &&
+      typeof (record.error as Record<string, unknown>).message === 'string'
+    ) {
+      return (record.error as Record<string, unknown>).message as string;
+    }
+  }
+  try {
+    return JSON.stringify(error);
+  } catch {
+    return String(error);
+  }
+}
+
+/**
+ * Strict check: returns true only for known, unambiguous context-overflow
+ * phrases. Use when the recovery action is expensive (full prune + retry)
+ * and false positives are undesirable.
+ */
+export function isContextOverflowError(errorMessage?: string): boolean {
+  if (!errorMessage) {
+    return false;
+  }
+  const lower = errorMessage.toLowerCase();
+  if (FALSE_POSITIVE_RE.test(lower)) {
+    return false;
+  }
+  return CONTEXT_OVERFLOW_PHRASES.some((phrase) => lower.includes(phrase));
+}
+
+/**
+ * Loose check: returns true for known phrases OR heuristic regex matches.
+ * Preferred by the graph's emergency-prune retry because the cost of a
+ * false positive is one extra retry with a smaller context, while the
+ * cost of a false negative is an opaque provider failure surfaced to
+ * the user.
+ */
+export function isLikelyContextOverflowError(errorMessage?: string): boolean {
+  if (!errorMessage) {
+    return false;
+  }
+  if (isContextOverflowError(errorMessage)) {
+    return true;
+  }
+  const lower = errorMessage.toLowerCase();
+  if (FALSE_POSITIVE_RE.test(lower)) {
+    return false;
+  }
+  return CONTEXT_OVERFLOW_HINT_RE.test(lower);
+}

package/src/utils/events.ts

@@ -1,11 +1,42 @@
 /* eslint-disable no-console */
 // src/utils/events.ts
 import { dispatchCustomEvent } from '@langchain/core/callbacks/dispatch';
+import { AsyncLocalStorageProviderSingleton } from '@langchain/core/singletons';
 import type { RunnableConfig } from '@langchain/core/runnables';
 
+/**
+ * Returns the RunnableConfig currently active in LangChain's AsyncLocalStorage,
+ * or undefined if none is installed. This is the per-async-branch config that
+ * LangGraph installs when entering a node — it carries the correct
+ * `metadata.spawnKey` for child subgraph invocations inside `Promise.all`
+ * parallel handoffs.
+ *
+ * Prefer this over any Graph-instance-cached config (e.g. `this.config`)
+ * when dispatching events from code that may run concurrently across multiple
+ * child subgraphs. An instance-level cache is shared state and races between
+ * siblings — the last child to enter wins, so events fire with the wrong
+ * child's metadata and the backend routes them to the wrong spawnKey.
+ */
+export function getCurrentRunnableConfig(): RunnableConfig | undefined {
+  try {
+    return AsyncLocalStorageProviderSingleton.getInstance().getStore() as
+      | RunnableConfig
+      | undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Safely dispatches a custom event and properly awaits it to avoid
  * race conditions where events are dispatched after run cleanup.
+ *
+ * **Parallel-handoff correctness:** callers should prefer passing
+ * `undefined` (or the per-node runtime config). When `config` is omitted,
+ * LangChain's `ensureConfig` reads the current RunnableConfig from
+ * AsyncLocalStorage, which is correctly isolated per async branch under
+ * `Promise.all`. Passing a stale instance-cached config overrides that
+ * implicit config's metadata and cross-contaminates parallel children.
  */
 export async function safeDispatchCustomEvent(
   event: string,
@@ -13,10 +44,11 @@ export async function safeDispatchCustomEvent(
   config?: RunnableConfig
 ): Promise<void> {
   try {
-    if (event === 'on_agent_transition') {
-      console.log(`[safeDispatchCustomEvent] Dispatching: ${event}, payload=${JSON.stringify(payload)}`);
-    }
-    await dispatchCustomEvent(event, payload, config);
+    // If the caller did not pass a config, fall back to the current
+    // AsyncLocalStorage-resident runnable config so nested Promise.all
+    // branches each use their own metadata.
+    const effectiveConfig = config ?? getCurrentRunnableConfig();
+    await dispatchCustomEvent(event, payload, effectiveConfig);
   } catch (e) {
     // Check if this is the known EventStreamCallbackHandler error
     if (
@@ -24,9 +56,7 @@ export async function safeDispatchCustomEvent(
       e.message.includes('handleCustomEvent: Run ID') &&
       e.message.includes('not found in run map')
     ) {
-      // Suppress this specific error - it's expected during parallel execution
-      // when EventStreamCallbackHandler loses track of run IDs
-      // console.debug('Suppressed error dispatching custom event:', e);
+      // Suppress — expected during parallel/async execution
       return;
     }
     // Log other errors

package/src/utils/finishReasons.ts

@@ -0,0 +1,40 @@
+/**
+ * Finish-reason constants and helpers.
+ *
+ * LLM providers emit different keys (`finish_reason`, `stop_reason`,
+ * `stopReason`, `finishReason`) and different values for the same concept.
+ * This module is the single source of truth for detecting *truncation* —
+ * i.e., the model hit its output budget and the response is incomplete.
+ *
+ * Used by:
+ *  - `Graph.ts` — sticky `lastFinishReason` across inner subgraph invokes,
+ *    so host's continuation retry can detect truncation that happens
+ *    inside a scoped-subgraph child node.
+ *  - Any future continuation / auto-retry logic added to agents.
+ *
+ * Kept as a small utils module (instead of inline in Graph.ts) so that
+ * additional callers — e.g., structured output recovery, sub-agent
+ * orchestrators — can reuse the exact same detection logic without drift.
+ */
+
+/**
+ * Canonical set of finish-reason strings that mean "output was truncated".
+ *
+ * Covers:
+ *  - `max_tokens` — Anthropic direct API, Bedrock
+ *  - `length`    — OpenAI/Azure
+ *  - `MAX_TOKENS` — VertexAI/Google (uppercased enum)
+ */
+export const TRUNCATION_FINISH_REASONS: ReadonlySet<string> = new Set([
+  'max_tokens',
+  'length',
+  'MAX_TOKENS',
+]);
+
+/**
+ * @returns true when the given finish/stop reason indicates the response
+ *          was cut short by the output token budget.
+ */
+export function isTruncationReason(reason: string | undefined | null): boolean {
+  return reason != null && TRUNCATION_FINISH_REASONS.has(reason);
+}

package/src/utils/index.ts

@@ -12,3 +12,4 @@ export * from './contextPressure';
 export * from './toolDiscoveryCache';
 export * from './pruneCalibration';
 export * from './fileManifest';
+export * from './errors';

package/src/utils/llm.ts

@@ -24,4 +24,3 @@ export function isGoogleLike(provider?: string | Providers): boolean {
     provider
   );
 }
-

package/src/utils/logging.ts

@@ -2,6 +2,33 @@
 import fs from 'fs';
 import util from 'util';
 
+/**
+ * Multi-agent debug gate. Controls chatty graph/handoff/transfer/sequence
+ * trace logs emitted from `MultiAgentGraph` and `Graph`. Off by default so the
+ * package stays quiet when embedded in host apps. Flip to
+ * `DEBUG_MULTIAGENT=true` in the host env to re-enable for testing.
+ *
+ * Exported as functions so runtime toggling via env reload works; the check
+ * is cheap (string equality) and only runs when a log site fires.
+ */
+function isMultiAgentDebugEnabled(): boolean {
+  return process.env.DEBUG_MULTIAGENT === 'true';
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const mlog = (...args: any[]): void => {
+  if (isMultiAgentDebugEnabled()) {
+    console.debug(...args);
+  }
+};
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const mwarn = (...args: any[]): void => {
+  if (isMultiAgentDebugEnabled()) {
+    console.warn(...args);
+  }
+};
+
 export function setupLogging(logFileName: string): void {
   const logFile = fs.createWriteStream(logFileName, { flags: 'a' });
 
@@ -10,39 +37,49 @@ export function setupLogging(logFileName: string): void {
   const originalStdoutWrite = process.stdout.write;
   const originalStderrWrite = process.stderr.write;
 
-  console.log = function(...args): void {
+  console.log = function (...args): void {
     logFile.write(util.format.apply(null, args) + ' ');
     originalConsoleLog.apply(console, args);
   };
 
-  console.error = function(...args): void {
+  console.error = function (...args): void {
     logFile.write(util.format.apply(null, args) + ' ');
     originalConsoleError.apply(console, args);
   };
 
-  process.stdout.write = function(
+  process.stdout.write = function (
     buffer: Uint8Array | string,
     cb?: ((err?: Error) => void) | string,
-    fd?: ((err?: Error) => void)
+    fd?: (err?: Error) => void
   ): boolean {
     if (typeof buffer === 'string') {
       logFile.write(buffer);
     } else {
       logFile.write(buffer.toString());
     }
-    return originalStdoutWrite.call(process.stdout, buffer, cb as BufferEncoding | undefined, fd);
+    return originalStdoutWrite.call(
+      process.stdout,
+      buffer,
+      cb as BufferEncoding | undefined,
+      fd
+    );
   };
 
-  process.stderr.write = function(
+  process.stderr.write = function (
     buffer: Uint8Array | string,
     cb?: ((err?: Error) => void) | string,
-    fd?: ((err?: Error) => void)
+    fd?: (err?: Error) => void
   ): boolean {
     if (typeof buffer === 'string') {
       logFile.write(buffer);
     } else {
       logFile.write(buffer.toString());
     }
-    return originalStderrWrite.call(process.stderr, buffer, cb as BufferEncoding | undefined, fd);
+    return originalStderrWrite.call(
+      process.stderr,
+      buffer,
+      cb as BufferEncoding | undefined,
+      fd
+    );
   };
 }

package/src/utils/toolCallNormalization.ts

@@ -0,0 +1,271 @@
+/**
+ * Tool-call name normalization for malformed LLM tool_use outputs.
+ *
+ * LLMs — especially smaller / faster models — frequently emit tool_use
+ * blocks with names that don't exactly match the registered tool name:
+ *
+ *   - Wrong delimiter: `outlook/operations` vs `outlook_operations`
+ *   - Function-prefix style: `functions.outlook_operations`
+ *   - Case drift: `Outlook_Operations`
+ *   - Counter suffix: `outlook_operations_1`
+ *   - Missing name, only id: `{name: "", id: "tool_outlook_operations_42"}`
+ *
+ * Before this normalization layer, any of the above caused the LangGraph
+ * ToolNode to throw "Tool X not found" and the whole turn to fail. With
+ * normalization, we resolve to the correct registered name case-insensitively
+ * and transparently fix the tool_call in place.
+ *
+ * Resolution order:
+ *   1. Exact match
+ *   2. Normalized delimiter + exact
+ *   3. Case-insensitive match
+ *   4. Structured candidates (strip prefixes, take suffix segments)
+ *   5. Infer from tool_call id (strip trailing digits, function/tool prefix)
+ *
+ * Any unresolvable tool_call is left as-is — the downstream ToolNode will
+ * fail with its usual error and the auto-recovery path kicks in.
+ */
+
+function lowercaseOrEmpty(value: string): string {
+  return typeof value === 'string' ? value.toLowerCase() : '';
+}
+
+/** Collapse common delimiters (space, dot, slash, dash) to `_` and fold case. */
+function normalizeDelimiters(name: string): string {
+  return name
+    .trim()
+    .replace(/[\s./-]+/g, '_')
+    .replace(/_{2,}/g, '_')
+    .replace(/^_+|_+$/g, '');
+}
+
+function resolveCaseInsensitive(
+  rawName: string,
+  allowed: Set<string>
+): string | null {
+  if (allowed.size === 0) return null;
+  const folded = lowercaseOrEmpty(rawName);
+  let match: string | null = null;
+  for (const name of allowed) {
+    if (lowercaseOrEmpty(name) !== folded) continue;
+    // Ambiguous → fail closed
+    if (match && match !== name) return null;
+    match = name;
+  }
+  return match;
+}
+
+function resolveExact(rawName: string, allowed: Set<string>): string | null {
+  if (allowed.size === 0) return null;
+  if (allowed.has(rawName)) return rawName;
+  const normalized = normalizeDelimiters(rawName);
+  if (allowed.has(normalized)) return normalized;
+  return (
+    resolveCaseInsensitive(rawName, allowed) ??
+    resolveCaseInsensitive(normalized, allowed)
+  );
+}
+
+function buildStructuredCandidates(rawName: string): string[] {
+  const trimmed = rawName.trim();
+  if (!trimmed) return [];
+  const seen = new Set<string>();
+  const out: string[] = [];
+  const add = (value: string): void => {
+    const c = value.trim();
+    if (!c || seen.has(c)) return;
+    seen.add(c);
+    out.push(c);
+  };
+  add(trimmed);
+  add(normalizeDelimiters(trimmed));
+  // Also try dot-normalized, then split
+  const dotForm = trimmed.replace(/\//g, '.');
+  add(dotForm);
+  add(normalizeDelimiters(dotForm));
+  const segments = dotForm
+    .split('.')
+    .map((s) => s.trim())
+    .filter(Boolean);
+  if (segments.length > 1) {
+    for (let i = 1; i < segments.length; i++) {
+      const suffix = segments.slice(i).join('.');
+      add(suffix);
+      add(normalizeDelimiters(suffix));
+    }
+  }
+  return out;
+}
+
+function resolveStructured(
+  rawName: string,
+  allowed: Set<string>
+): string | null {
+  if (allowed.size === 0) return null;
+  const candidates = buildStructuredCandidates(rawName);
+  for (const c of candidates) {
+    if (allowed.has(c)) return c;
+  }
+  for (const c of candidates) {
+    const ci = resolveCaseInsensitive(c, allowed);
+    if (ci) return ci;
+  }
+  return null;
+}
+
+function inferFromToolCallId(
+  rawId: string | undefined,
+  allowed: Set<string>
+): string | null {
+  if (!rawId || allowed.size === 0) return null;
+  const id = rawId.trim();
+  if (!id) return null;
+
+  const tokens = new Set<string>();
+  const addTokens = (value: string): void => {
+    const t = value.trim();
+    if (!t) return;
+    tokens.add(t);
+    tokens.add(t.replace(/[:._/-]\d+$/, ''));
+    tokens.add(t.replace(/\d+$/, ''));
+    const dotForm = t.replace(/\//g, '.');
+    tokens.add(dotForm);
+    tokens.add(dotForm.replace(/[:._-]\d+$/, ''));
+    tokens.add(dotForm.replace(/\d+$/, ''));
+    for (const prefix of [/^functions?[._-]?/i, /^tools?[._-]?/i]) {
+      const stripped = dotForm.replace(prefix, '');
+      if (stripped !== dotForm) {
+        tokens.add(stripped);
+        tokens.add(stripped.replace(/[:._-]\d+$/, ''));
+        tokens.add(stripped.replace(/\d+$/, ''));
+      }
+    }
+  };
+
+  const preColon = id.split(':')[0] ?? id;
+  addTokens(id);
+  addTokens(preColon);
+
+  let singleMatch: string | null = null;
+  for (const token of tokens) {
+    const matched = resolveStructured(token, allowed);
+    if (!matched) continue;
+    // Ambiguous → fail closed
+    if (singleMatch && singleMatch !== matched) return null;
+    singleMatch = matched;
+  }
+  if (singleMatch) return singleMatch;
+
+  // Substring fallback: ids frequently look like `call_<toolname>_<n>` or
+  // `toolu_01...<toolname>...`. Scan for any allowed name embedded in the
+  // delimiter-normalized id (case-insensitive) and fail closed if more than
+  // one distinct allowed name matches.
+  const haystack = lowercaseOrEmpty(normalizeDelimiters(id));
+  let substrMatch: string | null = null;
+  for (const allowedName of allowed) {
+    const needle = lowercaseOrEmpty(allowedName);
+    if (!needle) continue;
+    if (!haystack.includes(needle)) continue;
+    if (substrMatch && substrMatch !== allowedName) return null;
+    substrMatch = allowedName;
+  }
+  return substrMatch;
+}
+
+/**
+ * Produce the best allowed tool name for a raw LLM tool_use name.
+ * Returns the original name unchanged if no resolution is possible —
+ * the downstream executor will then fail with its normal error path.
+ */
+export function normalizeToolCallName(
+  rawName: string,
+  allowedToolNames: Set<string>,
+  rawToolCallId?: string
+): string {
+  const trimmed = rawName.trim() ?? '';
+  if (!trimmed) {
+    return (
+      inferFromToolCallId(rawToolCallId, allowedToolNames) ?? rawName ?? ''
+    );
+  }
+  if (allowedToolNames.size === 0) return trimmed;
+
+  const exact = resolveExact(trimmed, allowedToolNames);
+  if (exact) return exact;
+
+  const structured = resolveStructured(trimmed, allowedToolNames);
+  if (structured) return structured;
+
+  // Last-resort: try the raw id (if supplied). Substring matching lives
+  // inside inferFromToolCallId — only safe to invoke when the caller
+  // passed a real provider id, not when the raw name was used above.
+  const inferred = inferFromToolCallId(rawToolCallId, allowedToolNames);
+  if (inferred) return inferred;
+
+  return trimmed;
+}
+
+/**
+ * In-place normalization of all tool_calls on an AIMessage-like object.
+ *
+ * Applies `normalizeToolCallName` to each tool_call's `name` field using the
+ * provided allowed-tool set (derived from the agent's toolMap keys). Also
+ * rewrites the `name` field inside any content blocks of type `tool_use` so
+ * that downstream providers see the corrected name.
+ *
+ * Returns `true` if any name was rewritten.
+ */
+export function normalizeMessageToolCalls(
+  message: unknown,
+  allowedToolNames: Set<string>
+): boolean {
+  if (!message || typeof message !== 'object') return false;
+  let changed = false;
+
+  // LangChain AIMessage.tool_calls (normalized form)
+  const msg = message as {
+    tool_calls?: Array<{ name?: string; id?: string }>;
+    content?: unknown;
+  };
+  if (Array.isArray(msg.tool_calls)) {
+    for (const tc of msg.tool_calls) {
+      if (!tc || typeof tc !== 'object') continue;
+      const rawName = typeof tc.name === 'string' ? tc.name : '';
+      const rawId = typeof tc.id === 'string' ? tc.id : undefined;
+      const normalized = normalizeToolCallName(
+        rawName,
+        allowedToolNames,
+        rawId
+      );
+      if (normalized && normalized !== rawName) {
+        tc.name = normalized;
+        changed = true;
+      }
+    }
+  }
+
+  // Anthropic-style content blocks with type: 'tool_use'
+  if (Array.isArray(msg.content)) {
+    for (const block of msg.content as Array<{
+      type?: unknown;
+      name?: unknown;
+      id?: unknown;
+    }>) {
+      if (!block || typeof block !== 'object') continue;
+      if (block.type !== 'tool_use') continue;
+      const rawName = typeof block.name === 'string' ? block.name : '';
+      const rawId = typeof block.id === 'string' ? block.id : undefined;
+      const normalized = normalizeToolCallName(
+        rawName,
+        allowedToolNames,
+        rawId
+      );
+      if (normalized && normalized !== rawName) {
+        block.name = normalized;
+        changed = true;
+      }
+    }
+  }
+
+  return changed;
+}