@illuma-ai/agents 1.1.28 → 1.3.1

package/dist/esm/utils/errors.mjs

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.mjs","sources":["../../../src/utils/errors.ts"],"sourcesContent":["/**\n * Context-overflow error detection helpers.\n *\n * Provider error messages vary — Anthropic returns \"prompt is too long\",\n * OpenAI returns \"context_length_exceeded\", Bedrock returns \"Input is too\n * long\", Google returns a size-limit phrase. This module centralises the\n * phrase list so the agent graph's emergency-prune retry can classify\n * errors consistently instead of duplicating inline substring matches at\n * each call site.\n *\n * The strict check (`isContextOverflowError`) matches only known phrases.\n * The loose check (`isLikelyContextOverflowError`) also matches a heuristic\n * regex for providers we haven't explicitly catalogued. Both filter out\n * false positives (rate-limit, auth, quota, billing) that might otherwise\n * trigger an unnecessary prune retry.\n */\n\nconst CONTEXT_OVERFLOW_PHRASES = [\n  'request_too_large',\n  'context length exceeded',\n  'maximum context length',\n  'prompt is too long',\n  'exceeds model context window',\n  'exceeds the model',\n  'too large for model',\n  'context_length_exceeded',\n  'max_tokens',\n  'token limit',\n  'input too long',\n  'input is too long',\n  'payload too large',\n  'content_too_large',\n] as const;\n\nconst CONTEXT_OVERFLOW_HINT_RE =\n  /413|too large|too long|context.*exceed|exceed.*context|token.*limit|limit.*token|prompt.*size|size.*limit|maximum.*length|length.*maximum/i;\n\nconst FALSE_POSITIVE_RE =\n  /rate.?limit|too many requests|quota|billing|auth|permission|forbidden/i;\n\n/**\n * Extracts a human-readable error message from an unknown error value.\n * Walks common shapes: strings, Error instances, `{ message }`,\n * `{ error: string }`, `{ error: { message } }`. Falls back to\n * JSON.stringify or String() so callers never have to null-check.\n */\nexport function extractErrorMessage(error: unknown): string {\n  if (error == null) {\n    return '';\n  }\n  if (typeof error === 'string') {\n    return error;\n  }\n  if (error instanceof Error) {\n    return error.message;\n  }\n  if (typeof error === 'object') {\n    const record = error as Record<string, unknown>;\n    if (typeof record.message === 'string') {\n      return record.message;\n    }\n    if (typeof record.error === 'string') {\n      return record.error;\n    }\n    if (\n      typeof record.error === 'object' &&\n      record.error != null &&\n      typeof (record.error as Record<string, unknown>).message === 'string'\n    ) {\n      return (record.error as Record<string, unknown>).message as string;\n    }\n  }\n  try {\n    return JSON.stringify(error);\n  } catch {\n    return String(error);\n  }\n}\n\n/**\n * Strict check: returns true only for known, unambiguous context-overflow\n * phrases. Use when the recovery action is expensive (full prune + retry)\n * and false positives are undesirable.\n */\nexport function isContextOverflowError(errorMessage?: string): boolean {\n  if (!errorMessage) {\n    return false;\n  }\n  const lower = errorMessage.toLowerCase();\n  if (FALSE_POSITIVE_RE.test(lower)) {\n    return false;\n  }\n  return CONTEXT_OVERFLOW_PHRASES.some((phrase) => lower.includes(phrase));\n}\n\n/**\n * Loose check: returns true for known phrases OR heuristic regex matches.\n * Preferred by the graph's emergency-prune retry because the cost of a\n * false positive is one extra retry with a smaller context, while the\n * cost of a false negative is an opaque provider failure surfaced to\n * the user.\n */\nexport function isLikelyContextOverflowError(errorMessage?: string): boolean {\n  if (!errorMessage) {\n    return false;\n  }\n  if (isContextOverflowError(errorMessage)) {\n    return true;\n  }\n  const lower = errorMessage.toLowerCase();\n  if (FALSE_POSITIVE_RE.test(lower)) {\n    return false;\n  }\n  return CONTEXT_OVERFLOW_HINT_RE.test(lower);\n}\n"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;AAeG;AAEH,MAAM,wBAAwB,GAAG;IAC/B,mBAAmB;IACnB,yBAAyB;IACzB,wBAAwB;IACxB,oBAAoB;IACpB,8BAA8B;IAC9B,mBAAmB;IACnB,qBAAqB;IACrB,yBAAyB;IACzB,YAAY;IACZ,aAAa;IACb,gBAAgB;IAChB,mBAAmB;IACnB,mBAAmB;IACnB,mBAAmB;CACX;AAEV,MAAM,wBAAwB,GAC5B,4IAA4I;AAE9I,MAAM,iBAAiB,GACrB,wEAAwE;AAE1E;;;;;AAKG;AACG,SAAU,mBAAmB,CAAC,KAAc,EAAA;AAChD,IAAA,IAAI,KAAK,IAAI,IAAI,EAAE;AACjB,QAAA,OAAO,EAAE;IACX;AACA,IAAA,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE;AAC7B,QAAA,OAAO,KAAK;IACd;AACA,IAAA,IAAI,KAAK,YAAY,KAAK,EAAE;QAC1B,OAAO,KAAK,CAAC,OAAO;IACtB;AACA,IAAA,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE;QAC7B,MAAM,MAAM,GAAG,KAAgC;AAC/C,QAAA,IAAI,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ,EAAE;YACtC,OAAO,MAAM,CAAC,OAAO;QACvB;AACA,QAAA,IAAI,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ,EAAE;YACpC,OAAO,MAAM,CAAC,KAAK;QACrB;AACA,QAAA,IACE,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ;YAChC,MAAM,CAAC,KAAK,IAAI,IAAI;YACpB,OAAQ,MAAM,CAAC,KAAiC,CAAC,OAAO,KAAK,QAAQ,EACrE;AACA,YAAA,OAAQ,MAAM,CAAC,KAAiC,CAAC,OAAiB;QACpE;IACF;AACA,IAAA,IAAI;AACF,QAAA,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC;IAC9B;AAAE,IAAA,MAAM;AACN,QAAA,OAAO,MAAM,CAAC,KAAK,CAAC;IACtB;AACF;AAEA;;;;AAIG;AACG,SAAU,sBAAsB,CAAC,YAAqB,EAAA;IAC1D,IAAI,CAAC,YAAY,EAAE;AACjB,QAAA,OAAO,KAAK;IACd;AACA,IAAA,MAAM,KAAK,GAAG,YAAY,CAAC,WAAW,EAAE;AACxC,IAAA,IAAI,iBAAiB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE;AACjC,QAAA,OAAO,KAAK;IACd;AACA,IAAA,OAAO,wBAAwB,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AAC1E;AAEA;;;;;;AAMG;AACG,SAAU,4BAA4B,CAAC,YAAqB,EAAA;IAChE,IAAI,CAAC,YAAY,EAAE;AACjB,QAAA,OAAO,KAAK;IACd;AACA,IAAA,IAAI,sBAAsB,CAAC,YAAY,CAAC,EAAE;AACxC,QAAA,OAAO,IAAI;IACb;AACA,IAAA,MAAM,KAAK,GAAG,YAAY,CAAC,WAAW,EAAE;AACxC,IAAA,IAAI,iBAAiB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE;AACjC,QAAA,OAAO,KAAK;IACd;AACA,IAAA,OAAO,wBAAwB,CAAC,IAAI,CAAC,KAAK,CAAC;AAC7C;;;;"}

package/dist/esm/utils/events.mjs

@@ -1,26 +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 {
-        if (event === 'on_agent_transition') {
-            console.log(`[safeDispatchCustomEvent] Dispatching: ${event}, payload=${JSON.stringify(payload)}`);
-        }
-        await dispatchCustomEvent(event, payload, config);
+        // If the caller did not pass a config, fall back to the current
+        // AsyncLocalStorage-resident runnable config so nested Promise.all
+        // branches each use their own metadata.
+        const effectiveConfig = config ?? getCurrentRunnableConfig();
+        await dispatchCustomEvent(event, payload, effectiveConfig);
     }
     catch (e) {
         // Check if this is the known EventStreamCallbackHandler error
         if (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
@@ -28,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    if (event === 'on_agent_transition') {\n      console.log(`[safeDispatchCustomEvent] Dispatching: ${event}, payload=${JSON.stringify(payload)}`);\n    }\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;AACF,QAAA,IAAI,KAAK,KAAK,qBAAqB,EAAE;AACnC,YAAA,OAAO,CAAC,GAAG,CAAC,CAAA,uCAAA,EAA0C,KAAK,CAAA,UAAA,EAAa,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAA,CAAE,CAAC;QACpG;QACA,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;