@illuma-ai/agents 1.1.25 → 1.3.0

package/dist/esm/utils/events.mjs

@@ -1,23 +1,54 @@
 import { dispatchCustomEvent } from '@langchain/core/callbacks/dispatch';
+import { AsyncLocalStorageProviderSingleton } from '@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 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 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 (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
@@ -25,5 +56,5 @@ async function safeDispatchCustomEvent(event, payload, config) {
     }
 }
 
-export { safeDispatchCustomEvent };
+export { getCurrentRunnableConfig, safeDispatchCustomEvent };
 //# sourceMappingURL=events.mjs.map

package/dist/esm/utils/events.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"events.mjs","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":[],"mappings":";;AAAA;AACA;AAIA;;;AAGG;AACI,eAAe,uBAAuB,CAC3C,KAAa,EACb,OAAgB,EAChB,MAAuB,EAAA;AAEvB,IAAA,IAAI;QACF,MAAM,mBAAmB,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.mjs","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":[],"mappings":";;;AAAA;AACA;AAKA;;;;;;;;;;;;AAYG;SACa,wBAAwB,GAAA;AACtC,IAAA,IAAI;AACF,QAAA,OAAO,kCAAkC,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,MAAM,mBAAmB,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/esm/utils/finishReasons.mjs

@@ -0,0 +1,41 @@
+/**
+ * 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);
+}
+
+export { TRUNCATION_FINISH_REASONS, isTruncationReason };
+//# sourceMappingURL=finishReasons.mjs.map

package/dist/esm/utils/finishReasons.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"finishReasons.mjs","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/esm/utils/llm.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"llm.mjs","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":[],"mappings":";;;AAAA;AAGM,SAAU,YAAY,CAAC,QAA6B,EAAA;AACxD,IAAA,IAAI,QAAQ,IAAI,IAAI,EAAE;AACpB,QAAA,OAAO,KAAK;IACd;IACA,OACE;AACE,QAAA,SAAS,CAAC,MAAM;AAChB,QAAA,SAAS,CAAC,KAAK;AACf,QAAA,SAAS,CAAC,UAAU;AACpB,QAAA,SAAS,CAAC,GAAG;AACb,QAAA,SAAS,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,CAAC,SAAS,CAAC,MAAM,EAAE,SAAS,CAAC,QAAQ,CAAc,CAAC,QAAQ,CAClE,QAAQ,CACT;AACH;;;;"}
+{"version":3,"file":"llm.mjs","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":[],"mappings":";;;AAAA;AAGM,SAAU,YAAY,CAAC,QAA6B,EAAA;AACxD,IAAA,IAAI,QAAQ,IAAI,IAAI,EAAE;AACpB,QAAA,OAAO,KAAK;IACd;IACA,OACE;AACE,QAAA,SAAS,CAAC,MAAM;AAChB,QAAA,SAAS,CAAC,KAAK;AACf,QAAA,SAAS,CAAC,UAAU;AACpB,QAAA,SAAS,CAAC,GAAG;AACb,QAAA,SAAS,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,CAAC,SAAS,CAAC,MAAM,EAAE,SAAS,CAAC,QAAQ,CAAc,CAAC,QAAQ,CAClE,QAAQ,CACT;AACH;;;;"}

package/dist/esm/utils/logging.mjs

@@ -0,0 +1,31 @@
+import 'fs';
+import '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);
+    }
+};
+
+export { mlog, mwarn };
+//# sourceMappingURL=logging.mjs.map

package/dist/esm/utils/logging.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"logging.mjs","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/esm/utils/toolCallNormalization.mjs

@@ -0,0 +1,247 @@
+/**
+ * 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;
+}
+
+export { normalizeMessageToolCalls, normalizeToolCallName };
+//# sourceMappingURL=toolCallNormalization.mjs.map

package/dist/esm/utils/toolCallNormalization.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolCallNormalization.mjs","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/types/common/index.d.ts

@@ -1,3 +1,4 @@
 export * from './enum';
 export * from './constants';
+export * from './spawnPath';
 export * from '../tools/approval/constants';

package/dist/types/common/spawnPath.d.ts

@@ -0,0 +1,59 @@
+/**
+ * spawnPath — hierarchical invocation identity for nested multi-agent orchestration.
+ *
+ * A spawnPath is a slash-separated chain of spawnKeys from the root of the current
+ * agent invocation to the current spawn. The root agent has an empty spawnPath;
+ * each handoff/transfer/sequence that spawns a new subgraph appends a new spawnKey.
+ *
+ * Examples:
+ *   ""                               → primary agent (no spawn)
+ *   "call_abc"                       → first-level handoff child
+ *   "call_abc/call_def"              → grandchild (depth 2)
+ *   "call_abc/call_def/call_ghi"     → depth 3
+ *
+ * These utilities are the single source of truth for path manipulation across:
+ *   - @illuma-ai/agents (MultiAgentGraph, HandoffRegistry, callbacks)
+ *   - host api (initialize.js, callbacks.js, ExecutionTrace writes)
+ *   - host client (subagent store, sidebar rendering)
+ *
+ * See docs/multi-agent-nesting-architecture.md for the full design.
+ */
+/** Separator between spawnKeys in a spawnPath. Chosen so that the path looks
+ * like a filesystem/URL path, which makes it easy to read in logs and traces. */
+export declare const SPAWN_PATH_SEP = "/";
+/** Hard cap on nested multi-agent invocations. Prevents runaway recursion.
+ * Can be overridden at the host api layer via MULTI_AGENT_MAX_NESTING_DEPTH. */
+export declare const MAX_NESTING_DEPTH = 5;
+/**
+ * Append a spawnKey to a parent spawnPath.
+ *
+ * @param parent - Parent spawnPath (may be undefined/null/empty for root)
+ * @param key    - spawnKey to append
+ * @returns New spawnPath string
+ */
+export declare function buildSpawnPath(parent: string | undefined | null, key: string): string;
+/**
+ * Compute the depth of a spawnPath.
+ * Root (empty) → 0; single-segment → 1; etc.
+ */
+export declare function spawnPathDepth(path: string | undefined | null): number;
+/**
+ * Return the parent spawnPath, or null if the input is already root.
+ *
+ * - parentSpawnPath("a/b/c") === "a/b"
+ * - parentSpawnPath("a") === ""
+ * - parentSpawnPath("") === null
+ */
+export declare function parentSpawnPath(path: string | undefined | null): string | null;
+/** Split a spawnPath into its constituent spawnKey segments. */
+export declare function spawnPathParts(path: string | undefined | null): string[];
+/**
+ * Return the last spawnKey in a spawnPath (the "current" spawn).
+ * Returns null for root.
+ */
+export declare function leafSpawnKey(path: string | undefined | null): string | null;
+/**
+ * True if `ancestor` is a strict ancestor of `descendant`. Root ("") is
+ * ancestor of everything except itself.
+ */
+export declare function isAncestorSpawnPath(ancestor: string | undefined | null, descendant: string | undefined | null): boolean;

package/dist/types/graphs/HandoffRegistry.d.ts

@@ -0,0 +1,97 @@
+import type { BaseMessage } from '@langchain/core/messages';
+import type * as t from '@/types';
+/**
+ * Tracks the lifecycle of a spawned handoff child agent.
+ */
+export type HandoffRecord = {
+    /** Agent identity (destination agentId) — stable across multiple spawns of the same agent */
+    id: string;
+    /** Unique internal key for this specific spawn (agentId + monotonic counter) */
+    spawnKey: string;
+    /** Display name of the child agent */
+    name: string;
+    /** Task description / instructions passed to child */
+    task: string;
+    /** When the handoff was spawned */
+    spawnedAt: number;
+    /** Current status */
+    status: 'pending' | 'running' | 'completed' | 'failed';
+    /** The background promise executing the child subgraph */
+    promise: Promise<t.BaseGraphState>;
+    /** Resolved result text (populated on completion) */
+    resultText?: string;
+    /** Error message (populated on failure) */
+    error?: string;
+    /** Duration in ms (populated on completion/failure) */
+    durationMs?: number;
+    /** Number of messages in child's output */
+    resultMessageCount?: number;
+};
+/**
+ * Registry for async handoff execution.
+ *
+ * Enables the autonomous orchestration pattern:
+ * 1. Orchestrator spawns children (non-blocking)
+ * 2. Orchestrator stays alive to reason, spawn more, or check status
+ * 3. Orchestrator collects results when ready
+ *
+ * Scoped per MultiAgentGraph instance — each orchestrator graph gets its own registry.
+ */
+export declare class HandoffRegistry {
+    private records;
+    /** Monotonically increasing counter for unique spawn IDs */
+    private spawnCounter;
+    /**
+     * Register a spawned handoff child.
+     * The promise runs in the background — not awaited here.
+     * Uses a unique key per spawn so the same agent can be spawned multiple times
+     * across rounds without overwriting prior records.
+     */
+    spawn(params: {
+        id: string;
+        name: string;
+        task: string;
+        promise: Promise<t.BaseGraphState>;
+        extractResult: (messages: BaseMessage[], agentId: string) => string;
+        truncateResult: (text: string, maxChars: number) => string;
+        maxResultChars: number;
+        /** Callback when child completes (for SSE events) */
+        onComplete?: (record: HandoffRecord) => void;
+    }): void;
+    /** List all pending (running) handoffs */
+    listPending(): HandoffRecord[];
+    /** List all completed handoffs (not yet collected) */
+    listCompleted(): HandoffRecord[];
+    /** List all handoffs regardless of status */
+    listAll(): HandoffRecord[];
+    /**
+     * Get a handoff record by either its unique spawnKey or by agentId.
+     * - Exact spawnKey match wins (O(1)).
+     * - Falls back to the most recently spawned record for that agentId — matching
+     *   lookups by callers that only know the agent identity, not the spawn round.
+     */
+    get(idOrSpawnKey: string): HandoffRecord | undefined;
+    /** Check if any handoffs are still running */
+    hasPending(): boolean;
+    /**
+     * Wait for ALL pending handoffs to complete and return all records.
+     * Records are NOT auto-cleared — caller removes collected records via remove().
+     */
+    waitForAll(): Promise<HandoffRecord[]>;
+    /**
+     * Wait for ANY pending handoff to complete.
+     * Returns the newly completed record(s).
+     */
+    waitForAny(): Promise<HandoffRecord[]>;
+    /**
+     * Remove record(s) by spawnKey or agentId.
+     * - Exact spawnKey match removes only that record.
+     * - agentId match removes ALL records for that agent (covers callers that
+     *   want to forget everything tied to a given agent).
+     */
+    remove(idOrSpawnKey: string): void;
+    /** Clear all records (for cleanup between graph invocations) */
+    clear(): void;
+    /** Number of total tracked handoffs */
+    get size(): number;
+}