@illuma-ai/agents 1.1.25 → 1.3.0

package/dist/cjs/utils/childAgentContext.cjs.map

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

package/dist/cjs/utils/events.cjs

@@ -1,25 +1,56 @@
 'use strict';
 
 var dispatch = require('@langchain/core/callbacks/dispatch');
+var singletons = require('@langchain/core/singletons');
 
 /* eslint-disable no-console */
 // src/utils/events.ts
+/**
+ * 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.
+ */
+function getCurrentRunnableConfig() {
+    try {
+        return singletons.AsyncLocalStorageProviderSingleton.getInstance().getStore();
+    }
+    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.
  */
 async function safeDispatchCustomEvent(event, payload, config) {
     try {
-        await dispatch.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 dispatch.dispatchCustomEvent(event, payload, effectiveConfig);
     }
     catch (e) {
         // Check if this is the known EventStreamCallbackHandler error
         if (e instanceof Error &&
             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
@@ -27,5 +58,6 @@ async function safeDispatchCustomEvent(event, payload, config) {
     }
 }
 
+exports.getCurrentRunnableConfig = getCurrentRunnableConfig;
 exports.safeDispatchCustomEvent = safeDispatchCustomEvent;
 //# sourceMappingURL=events.cjs.map

package/dist/cjs/utils/events.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"events.cjs","sources":["../../../src/utils/events.ts"],"sourcesContent":["/* eslint-disable no-console */\n// src/utils/events.ts\nimport { dispatchCustomEvent } from '@langchain/core/callbacks/dispatch';\nimport type { RunnableConfig } from '@langchain/core/runnables';\n\n/**\n * Safely dispatches a custom event and properly awaits it to avoid\n * race conditions where events are dispatched after run cleanup.\n */\nexport async function safeDispatchCustomEvent(\n  event: string,\n  payload: unknown,\n  config?: RunnableConfig\n): Promise<void> {\n  try {\n    await dispatchCustomEvent(event, payload, config);\n  } catch (e) {\n    // Check if this is the known EventStreamCallbackHandler error\n    if (\n      e instanceof Error &&\n      e.message.includes('handleCustomEvent: Run ID') &&\n      e.message.includes('not found in run map')\n    ) {\n      // Suppress this specific error - it's expected during parallel execution\n      // when EventStreamCallbackHandler loses track of run IDs\n      // console.debug('Suppressed error dispatching custom event:', e);\n      return;\n    }\n    // Log other errors\n    console.error('Error dispatching custom event:', e);\n  }\n}\n"],"names":["dispatchCustomEvent"],"mappings":";;;;AAAA;AACA;AAIA;;;AAGG;AACI,eAAe,uBAAuB,CAC3C,KAAa,EACb,OAAgB,EAChB,MAAuB,EAAA;AAEvB,IAAA,IAAI;QACF,MAAMA,4BAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC;IACnD;IAAE,OAAO,CAAC,EAAE;;QAEV,IACE,CAAC,YAAY,KAAK;AAClB,YAAA,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,2BAA2B,CAAC;YAC/C,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAC,EAC1C;;;;YAIA;QACF;;AAEA,QAAA,OAAO,CAAC,KAAK,CAAC,iCAAiC,EAAE,CAAC,CAAC;IACrD;AACF;;;;"}
+{"version":3,"file":"events.cjs","sources":["../../../src/utils/events.ts"],"sourcesContent":["/* eslint-disable no-console */\n// src/utils/events.ts\nimport { dispatchCustomEvent } from '@langchain/core/callbacks/dispatch';\nimport { AsyncLocalStorageProviderSingleton } from '@langchain/core/singletons';\nimport type { RunnableConfig } from '@langchain/core/runnables';\n\n/**\n * Returns the RunnableConfig currently active in LangChain's AsyncLocalStorage,\n * or undefined if none is installed. This is the per-async-branch config that\n * LangGraph installs when entering a node — it carries the correct\n * `metadata.spawnKey` for child subgraph invocations inside `Promise.all`\n * parallel handoffs.\n *\n * Prefer this over any Graph-instance-cached config (e.g. `this.config`)\n * when dispatching events from code that may run concurrently across multiple\n * child subgraphs. An instance-level cache is shared state and races between\n * siblings — the last child to enter wins, so events fire with the wrong\n * child's metadata and the backend routes them to the wrong spawnKey.\n */\nexport function getCurrentRunnableConfig(): RunnableConfig | undefined {\n  try {\n    return AsyncLocalStorageProviderSingleton.getInstance().getStore() as\n      | RunnableConfig\n      | undefined;\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * Safely dispatches a custom event and properly awaits it to avoid\n * race conditions where events are dispatched after run cleanup.\n *\n * **Parallel-handoff correctness:** callers should prefer passing\n * `undefined` (or the per-node runtime config). When `config` is omitted,\n * LangChain's `ensureConfig` reads the current RunnableConfig from\n * AsyncLocalStorage, which is correctly isolated per async branch under\n * `Promise.all`. Passing a stale instance-cached config overrides that\n * implicit config's metadata and cross-contaminates parallel children.\n */\nexport async function safeDispatchCustomEvent(\n  event: string,\n  payload: unknown,\n  config?: RunnableConfig\n): Promise<void> {\n  try {\n    // If the caller did not pass a config, fall back to the current\n    // AsyncLocalStorage-resident runnable config so nested Promise.all\n    // branches each use their own metadata.\n    const effectiveConfig = config ?? getCurrentRunnableConfig();\n    await dispatchCustomEvent(event, payload, effectiveConfig);\n  } catch (e) {\n    // Check if this is the known EventStreamCallbackHandler error\n    if (\n      e instanceof Error &&\n      e.message.includes('handleCustomEvent: Run ID') &&\n      e.message.includes('not found in run map')\n    ) {\n      // Suppress — expected during parallel/async execution\n      return;\n    }\n    // Log other errors\n    console.error('Error dispatching custom event:', e);\n  }\n}\n"],"names":["AsyncLocalStorageProviderSingleton","dispatchCustomEvent"],"mappings":";;;;;AAAA;AACA;AAKA;;;;;;;;;;;;AAYG;SACa,wBAAwB,GAAA;AACtC,IAAA,IAAI;AACF,QAAA,OAAOA,6CAAkC,CAAC,WAAW,EAAE,CAAC,QAAQ,EAEnD;IACf;AAAE,IAAA,MAAM;AACN,QAAA,OAAO,SAAS;IAClB;AACF;AAEA;;;;;;;;;;AAUG;AACI,eAAe,uBAAuB,CAC3C,KAAa,EACb,OAAgB,EAChB,MAAuB,EAAA;AAEvB,IAAA,IAAI;;;;AAIF,QAAA,MAAM,eAAe,GAAG,MAAM,IAAI,wBAAwB,EAAE;QAC5D,MAAMC,4BAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,eAAe,CAAC;IAC5D;IAAE,OAAO,CAAC,EAAE;;QAEV,IACE,CAAC,YAAY,KAAK;AAClB,YAAA,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,2BAA2B,CAAC;YAC/C,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAC,EAC1C;;YAEA;QACF;;AAEA,QAAA,OAAO,CAAC,KAAK,CAAC,iCAAiC,EAAE,CAAC,CAAC;IACrD;AACF;;;;;"}

package/dist/cjs/utils/finishReasons.cjs

@@ -0,0 +1,44 @@
+'use strict';
+
+/**
+ * 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)
+ */
+const TRUNCATION_FINISH_REASONS = 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.
+ */
+function isTruncationReason(reason) {
+    return reason != null && TRUNCATION_FINISH_REASONS.has(reason);
+}
+
+exports.TRUNCATION_FINISH_REASONS = TRUNCATION_FINISH_REASONS;
+exports.isTruncationReason = isTruncationReason;
+//# sourceMappingURL=finishReasons.cjs.map

package/dist/cjs/utils/finishReasons.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"finishReasons.cjs","sources":["../../../src/utils/finishReasons.ts"],"sourcesContent":["/**\n * Finish-reason constants and helpers.\n *\n * LLM providers emit different keys (`finish_reason`, `stop_reason`,\n * `stopReason`, `finishReason`) and different values for the same concept.\n * This module is the single source of truth for detecting *truncation* —\n * i.e., the model hit its output budget and the response is incomplete.\n *\n * Used by:\n *  - `Graph.ts` — sticky `lastFinishReason` across inner subgraph invokes,\n *    so host's continuation retry can detect truncation that happens\n *    inside a scoped-subgraph child node.\n *  - Any future continuation / auto-retry logic added to agents.\n *\n * Kept as a small utils module (instead of inline in Graph.ts) so that\n * additional callers — e.g., structured output recovery, sub-agent\n * orchestrators — can reuse the exact same detection logic without drift.\n */\n\n/**\n * Canonical set of finish-reason strings that mean \"output was truncated\".\n *\n * Covers:\n *  - `max_tokens` — Anthropic direct API, Bedrock\n *  - `length`    — OpenAI/Azure\n *  - `MAX_TOKENS` — VertexAI/Google (uppercased enum)\n */\nexport const TRUNCATION_FINISH_REASONS: ReadonlySet<string> = new Set([\n  'max_tokens',\n  'length',\n  'MAX_TOKENS',\n]);\n\n/**\n * @returns true when the given finish/stop reason indicates the response\n *          was cut short by the output token budget.\n */\nexport function isTruncationReason(reason: string | undefined | null): boolean {\n  return reason != null && TRUNCATION_FINISH_REASONS.has(reason);\n}\n"],"names":[],"mappings":";;AAAA;;;;;;;;;;;;;;;;;AAiBG;AAEH;;;;;;;AAOG;AACI,MAAM,yBAAyB,GAAwB,IAAI,GAAG,CAAC;IACpE,YAAY;IACZ,QAAQ;IACR,YAAY;AACb,CAAA;AAED;;;AAGG;AACG,SAAU,kBAAkB,CAAC,MAAiC,EAAA;IAClE,OAAO,MAAM,IAAI,IAAI,IAAI,yBAAyB,CAAC,GAAG,CAAC,MAAM,CAAC;AAChE;;;;;"}

package/dist/cjs/utils/llm.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"llm.cjs","sources":["../../../src/utils/llm.ts"],"sourcesContent":["// src/utils/llm.ts\nimport { Providers } from '@/common';\n\nexport function isOpenAILike(provider?: string | Providers): boolean {\n  if (provider == null) {\n    return false;\n  }\n  return (\n    [\n      Providers.OPENAI,\n      Providers.AZURE,\n      Providers.OPENROUTER,\n      Providers.XAI,\n      Providers.DEEPSEEK,\n    ] as string[]\n  ).includes(provider);\n}\n\nexport function isGoogleLike(provider?: string | Providers): boolean {\n  if (provider == null) {\n    return false;\n  }\n  return ([Providers.GOOGLE, Providers.VERTEXAI] as string[]).includes(\n    provider\n  );\n}\n\n"],"names":["Providers"],"mappings":";;;;;AAAA;AAGM,SAAU,YAAY,CAAC,QAA6B,EAAA;AACxD,IAAA,IAAI,QAAQ,IAAI,IAAI,EAAE;AACpB,QAAA,OAAO,KAAK;IACd;IACA,OACE;AACE,QAAAA,eAAS,CAAC,MAAM;AAChB,QAAAA,eAAS,CAAC,KAAK;AACf,QAAAA,eAAS,CAAC,UAAU;AACpB,QAAAA,eAAS,CAAC,GAAG;AACb,QAAAA,eAAS,CAAC,QAAQ;AAErB,KAAA,CAAC,QAAQ,CAAC,QAAQ,CAAC;AACtB;AAEM,SAAU,YAAY,CAAC,QAA6B,EAAA;AACxD,IAAA,IAAI,QAAQ,IAAI,IAAI,EAAE;AACpB,QAAA,OAAO,KAAK;IACd;AACA,IAAA,OAAQ,CAACA,eAAS,CAAC,MAAM,EAAEA,eAAS,CAAC,QAAQ,CAAc,CAAC,QAAQ,CAClE,QAAQ,CACT;AACH;;;;;"}
+{"version":3,"file":"llm.cjs","sources":["../../../src/utils/llm.ts"],"sourcesContent":["// src/utils/llm.ts\nimport { Providers } from '@/common';\n\nexport function isOpenAILike(provider?: string | Providers): boolean {\n  if (provider == null) {\n    return false;\n  }\n  return (\n    [\n      Providers.OPENAI,\n      Providers.AZURE,\n      Providers.OPENROUTER,\n      Providers.XAI,\n      Providers.DEEPSEEK,\n    ] as string[]\n  ).includes(provider);\n}\n\nexport function isGoogleLike(provider?: string | Providers): boolean {\n  if (provider == null) {\n    return false;\n  }\n  return ([Providers.GOOGLE, Providers.VERTEXAI] as string[]).includes(\n    provider\n  );\n}\n"],"names":["Providers"],"mappings":";;;;;AAAA;AAGM,SAAU,YAAY,CAAC,QAA6B,EAAA;AACxD,IAAA,IAAI,QAAQ,IAAI,IAAI,EAAE;AACpB,QAAA,OAAO,KAAK;IACd;IACA,OACE;AACE,QAAAA,eAAS,CAAC,MAAM;AAChB,QAAAA,eAAS,CAAC,KAAK;AACf,QAAAA,eAAS,CAAC,UAAU;AACpB,QAAAA,eAAS,CAAC,GAAG;AACb,QAAAA,eAAS,CAAC,QAAQ;AAErB,KAAA,CAAC,QAAQ,CAAC,QAAQ,CAAC;AACtB;AAEM,SAAU,YAAY,CAAC,QAA6B,EAAA;AACxD,IAAA,IAAI,QAAQ,IAAI,IAAI,EAAE;AACpB,QAAA,OAAO,KAAK;IACd;AACA,IAAA,OAAQ,CAACA,eAAS,CAAC,MAAM,EAAEA,eAAS,CAAC,QAAQ,CAAc,CAAC,QAAQ,CAClE,QAAQ,CACT;AACH;;;;;"}

package/dist/cjs/utils/logging.cjs

@@ -0,0 +1,34 @@
+'use strict';
+
+require('fs');
+require('util');
+
+// src/utils/logging.ts
+/**
+ * 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() {
+    return process.env.DEBUG_MULTIAGENT === 'true';
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const mlog = (...args) => {
+    if (isMultiAgentDebugEnabled()) {
+        console.debug(...args);
+    }
+};
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const mwarn = (...args) => {
+    if (isMultiAgentDebugEnabled()) {
+        console.warn(...args);
+    }
+};
+
+exports.mlog = mlog;
+exports.mwarn = mwarn;
+//# sourceMappingURL=logging.cjs.map

package/dist/cjs/utils/logging.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"logging.cjs","sources":["../../../src/utils/logging.ts"],"sourcesContent":["// src/utils/logging.ts\nimport fs from 'fs';\nimport util from 'util';\n\n/**\n * Multi-agent debug gate. Controls chatty graph/handoff/transfer/sequence\n * trace logs emitted from `MultiAgentGraph` and `Graph`. Off by default so the\n * package stays quiet when embedded in host apps. Flip to\n * `DEBUG_MULTIAGENT=true` in the host env to re-enable for testing.\n *\n * Exported as functions so runtime toggling via env reload works; the check\n * is cheap (string equality) and only runs when a log site fires.\n */\nfunction isMultiAgentDebugEnabled(): boolean {\n  return process.env.DEBUG_MULTIAGENT === 'true';\n}\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport const mlog = (...args: any[]): void => {\n  if (isMultiAgentDebugEnabled()) {\n    console.debug(...args);\n  }\n};\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport const mwarn = (...args: any[]): void => {\n  if (isMultiAgentDebugEnabled()) {\n    console.warn(...args);\n  }\n};\n\nexport function setupLogging(logFileName: string): void {\n  const logFile = fs.createWriteStream(logFileName, { flags: 'a' });\n\n  const originalConsoleLog = console.log;\n  const originalConsoleError = console.error;\n  const originalStdoutWrite = process.stdout.write;\n  const originalStderrWrite = process.stderr.write;\n\n  console.log = function (...args): void {\n    logFile.write(util.format.apply(null, args) + ' ');\n    originalConsoleLog.apply(console, args);\n  };\n\n  console.error = function (...args): void {\n    logFile.write(util.format.apply(null, args) + ' ');\n    originalConsoleError.apply(console, args);\n  };\n\n  process.stdout.write = function (\n    buffer: Uint8Array | string,\n    cb?: ((err?: Error) => void) | string,\n    fd?: (err?: Error) => void\n  ): boolean {\n    if (typeof buffer === 'string') {\n      logFile.write(buffer);\n    } else {\n      logFile.write(buffer.toString());\n    }\n    return originalStdoutWrite.call(\n      process.stdout,\n      buffer,\n      cb as BufferEncoding | undefined,\n      fd\n    );\n  };\n\n  process.stderr.write = function (\n    buffer: Uint8Array | string,\n    cb?: ((err?: Error) => void) | string,\n    fd?: (err?: Error) => void\n  ): boolean {\n    if (typeof buffer === 'string') {\n      logFile.write(buffer);\n    } else {\n      logFile.write(buffer.toString());\n    }\n    return originalStderrWrite.call(\n      process.stderr,\n      buffer,\n      cb as BufferEncoding | undefined,\n      fd\n    );\n  };\n}\n"],"names":[],"mappings":";;;;;AAAA;AAIA;;;;;;;;AAQG;AACH,SAAS,wBAAwB,GAAA;AAC/B,IAAA,OAAO,OAAO,CAAC,GAAG,CAAC,gBAAgB,KAAK,MAAM;AAChD;AAEA;MACa,IAAI,GAAG,CAAC,GAAG,IAAW,KAAU;IAC3C,IAAI,wBAAwB,EAAE,EAAE;AAC9B,QAAA,OAAO,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC;IACxB;AACF;AAEA;MACa,KAAK,GAAG,CAAC,GAAG,IAAW,KAAU;IAC5C,IAAI,wBAAwB,EAAE,EAAE;AAC9B,QAAA,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACvB;AACF;;;;;"}

package/dist/cjs/utils/toolCallNormalization.cjs

@@ -0,0 +1,250 @@
+'use strict';
+
+/**
+ * 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) {
+    return typeof value === 'string' ? value.toLowerCase() : '';
+}
+/** Collapse common delimiters (space, dot, slash, dash) to `_` and fold case. */
+function normalizeDelimiters(name) {
+    return name
+        .trim()
+        .replace(/[\s./-]+/g, '_')
+        .replace(/_{2,}/g, '_')
+        .replace(/^_+|_+$/g, '');
+}
+function resolveCaseInsensitive(rawName, allowed) {
+    if (allowed.size === 0)
+        return null;
+    const folded = lowercaseOrEmpty(rawName);
+    let match = 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, allowed) {
+    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) {
+    const trimmed = rawName.trim();
+    if (!trimmed)
+        return [];
+    const seen = new Set();
+    const out = [];
+    const add = (value) => {
+        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, allowed) {
+    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, allowed) {
+    if (!rawId || allowed.size === 0)
+        return null;
+    const id = rawId.trim();
+    if (!id)
+        return null;
+    const tokens = new Set();
+    const addTokens = (value) => {
+        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 = 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 = 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.
+ */
+function normalizeToolCallName(rawName, allowedToolNames, rawToolCallId) {
+    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.
+ */
+function normalizeMessageToolCalls(message, allowedToolNames) {
+    if (!message || typeof message !== 'object')
+        return false;
+    let changed = false;
+    // LangChain AIMessage.tool_calls (normalized form)
+    const msg = message;
+    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) {
+            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;
+}
+
+exports.normalizeMessageToolCalls = normalizeMessageToolCalls;
+exports.normalizeToolCallName = normalizeToolCallName;
+//# sourceMappingURL=toolCallNormalization.cjs.map

package/dist/cjs/utils/toolCallNormalization.cjs.map

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

package/dist/esm/agents/AgentContext.mjs

@@ -452,12 +452,29 @@ class AgentContext {
         const { sourceAgentName, parallelSiblings } = this.handoffContext;
         const isParallel = parallelSiblings.length > 0;
         const lines = [];
-        lines.push('## Multi-Agent Workflow');
-        lines.push(`You are "${displayName}", transferred from "${sourceAgentName}".`);
+        lines.push('## Subagent Context');
+        lines.push('');
+        lines.push(`You are "${displayName}", a subagent spawned by "${sourceAgentName}" for a specific task.`);
         if (isParallel) {
             lines.push(`Running in parallel with: ${parallelSiblings.join(', ')}.`);
         }
-        lines.push('Execute only tasks relevant to your role. Routing is already handled if requested, unless you can route further.');
+        lines.push('');
+        lines.push('### Your Role');
+        lines.push('- Complete your assigned task. That is your entire purpose.');
+        lines.push(`- You are NOT "${sourceAgentName}". Do not try to be.`);
+        lines.push('');
+        lines.push('### Rules');
+        lines.push('1. **Stay focused** — Do your assigned task, nothing else.');
+        lines.push('2. **Complete the task** — Your final message will be automatically reported back.');
+        lines.push('3. **Be autonomous** — Execute directly without asking for user confirmation. Use your tools and best judgment.');
+        lines.push('4. **No placeholders** — Never generate fake or placeholder data. If you cannot retrieve real data, say so.');
+        lines.push('5. **No side effects** — Do not send messages, emails, or notifications unless explicitly tasked to do so.');
+        lines.push('');
+        lines.push('### Output');
+        lines.push('When complete, your final response should include:');
+        lines.push('- What you accomplished or found');
+        lines.push('- Any relevant details the orchestrator should know');
+        lines.push('- Keep it concise but informative');
         return lines.join('\n');
     }
     /**