@illuma-ai/agents 1.1.25 → 1.3.0

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

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,7 +44,11 @@ export async function safeDispatchCustomEvent(
   config?: RunnableConfig
 ): Promise<void> {
   try {
-    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 (
@@ -21,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/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
+    );
   };
 }