@illuma-ai/agents 1.4.0-alpha.6 → 1.5.1

package/src/utils/truncation.ts

@@ -0,0 +1,154 @@
+/**
+ * Ingestion-time and pre-flight truncation utilities for tool results.
+ *
+ * Prevents oversized tool outputs from entering the message array and
+ * consuming the entire context window.
+ */
+
+/**
+ * Absolute hard cap on tool result length (characters).
+ * Even if the model has a 1M-token context, a single tool result
+ * larger than this is almost certainly a bug (e.g., dumping a binary file).
+ */
+export const HARD_MAX_TOOL_RESULT_CHARS = 400_000;
+
+/**
+ * Absolute hard cap on the aggregate size (characters) of all registered
+ * tool outputs kept for `{{tool<i>turn<n>}}` substitution. Set at 5 MB
+ * because the registry stores *raw, untruncated* tool output — full
+ * fidelity for piping into downstream bash/jq — so the budget needs
+ * enough headroom to keep a handful of large responses without
+ * ballooning unbounded.
+ */
+export const HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE = 5_000_000;
+
+/**
+ * Computes the dynamic max tool result size based on the model's context window.
+ * Uses 30% of the context window (in estimated characters, ~4 chars/token)
+ * capped at HARD_MAX_TOOL_RESULT_CHARS.
+ *
+ * @param contextWindowTokens - The model's max context tokens (optional).
+ * @returns Maximum allowed characters for a single tool result.
+ */
+export function calculateMaxToolResultChars(
+  contextWindowTokens?: number
+): number {
+  if (contextWindowTokens == null || contextWindowTokens <= 0) {
+    return HARD_MAX_TOOL_RESULT_CHARS;
+  }
+  return Math.min(
+    Math.floor(contextWindowTokens * 0.3) * 4,
+    HARD_MAX_TOOL_RESULT_CHARS
+  );
+}
+
+/**
+ * Computes the default aggregate size (characters) for the tool output
+ * reference registry based on the per-output budget. Mirrors
+ * `calculateMaxToolResultChars`'s shape: a multiple of the per-output
+ * cap, clamped to `HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE`.
+ *
+ * @param maxOutputSize - Per-output maximum characters (e.g., the
+ *   ToolNode's `maxToolResultChars`). When omitted or non-positive,
+ *   falls back to the absolute total cap.
+ * @returns Maximum total characters retained across the registry.
+ */
+export function calculateMaxTotalToolOutputSize(
+  maxOutputSize?: number
+): number {
+  if (maxOutputSize == null || maxOutputSize <= 0) {
+    return HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE;
+  }
+  return Math.min(maxOutputSize * 2, HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE);
+}
+
+/**
+ * Truncates a tool-call input (the arguments/payload of a tool_use block)
+ * using head+tail strategy. Returns an object with `_truncated` (the
+ * truncated string) and `_originalChars` (for diagnostics).
+ *
+ * Accepts any type — objects are JSON-serialized before truncation.
+ *
+ * @param input - The tool input (string, object, etc.).
+ * @param maxChars - Maximum allowed characters.
+ */
+export function truncateToolInput(
+  input: unknown,
+  maxChars: number
+): { _truncated: string; _originalChars: number } {
+  const serialized = typeof input === 'string' ? input : JSON.stringify(input);
+  if (serialized.length <= maxChars) {
+    return { _truncated: serialized, _originalChars: serialized.length };
+  }
+  const indicator = `\n… [truncated: ${serialized.length} chars exceeded ${maxChars} limit] …\n`;
+  const available = maxChars - indicator.length;
+
+  if (available < 100) {
+    return {
+      _truncated: serialized.slice(0, maxChars) + indicator.trimEnd(),
+      _originalChars: serialized.length,
+    };
+  }
+
+  const headSize = Math.ceil(available * 0.7);
+  const tailSize = available - headSize;
+
+  return {
+    _truncated:
+      serialized.slice(0, headSize) +
+      indicator +
+      serialized.slice(serialized.length - tailSize),
+    _originalChars: serialized.length,
+  };
+}
+
+/**
+ * Truncates tool result content that exceeds `maxChars` using a head+tail
+ * strategy. Keeps the beginning (structure/headers) and end (return value /
+ * conclusion) of the content so the model retains both the opening context
+ * and the final outcome.
+ *
+ * Head gets ~70% of the budget, tail gets ~30%. Falls back to head-only
+ * when the budget is too small for a meaningful tail.
+ *
+ * @param content - The tool result string content.
+ * @param maxChars - Maximum allowed characters.
+ * @returns The (possibly truncated) content string.
+ */
+export function truncateToolResultContent(
+  content: string,
+  maxChars: number
+): string {
+  if (content.length <= maxChars) {
+    return content;
+  }
+
+  const indicator = `\n\n… [truncated: ${content.length} chars exceeded ${maxChars} limit] …\n\n`;
+  const available = maxChars - indicator.length;
+  if (available <= 0) {
+    return content.slice(0, maxChars);
+  }
+
+  // When budget is too small for a meaningful tail, fall back to head-only
+  if (available < 200) {
+    return content.slice(0, available) + indicator.trimEnd();
+  }
+
+  const headSize = Math.ceil(available * 0.7);
+  const tailSize = available - headSize;
+
+  // Try to break at newline boundaries for cleaner output
+  let headEnd = headSize;
+  const headNewline = content.lastIndexOf('\n', headSize);
+  if (headNewline > headSize - 200 && headNewline > 0) {
+    headEnd = headNewline;
+  }
+
+  let tailStart = content.length - tailSize;
+  const tailNewline = content.indexOf('\n', tailStart);
+  if (tailNewline > 0 && tailNewline < tailStart + 200) {
+    tailStart = tailNewline + 1;
+  }
+
+  return content.slice(0, headEnd) + indicator + content.slice(tailStart);
+}

package/dist/cjs/common/spawnPath.cjs

@@ -1,104 +0,0 @@
-'use strict';
-
-/**
- * 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. */
-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. */
-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
- */
-function buildSpawnPath(parent, key) {
-    if (!key) {
-        throw new Error('[spawnPath] buildSpawnPath called with empty key');
-    }
-    if (parent == null || parent === '')
-        return key;
-    return `${parent}${SPAWN_PATH_SEP}${key}`;
-}
-/**
- * Compute the depth of a spawnPath.
- * Root (empty) → 0; single-segment → 1; etc.
- */
-function spawnPathDepth(path) {
-    if (path == null || path === '')
-        return 0;
-    return path.split(SPAWN_PATH_SEP).filter(Boolean).length;
-}
-/**
- * Return the parent spawnPath, or null if the input is already root.
- *
- * - parentSpawnPath("a/b/c") === "a/b"
- * - parentSpawnPath("a") === ""
- * - parentSpawnPath("") === null
- */
-function parentSpawnPath(path) {
-    if (path == null || path === '')
-        return null;
-    const parts = path.split(SPAWN_PATH_SEP).filter(Boolean);
-    if (parts.length <= 1)
-        return '';
-    return parts.slice(0, -1).join(SPAWN_PATH_SEP);
-}
-/** Split a spawnPath into its constituent spawnKey segments. */
-function spawnPathParts(path) {
-    if (path == null || path === '')
-        return [];
-    return path.split(SPAWN_PATH_SEP).filter(Boolean);
-}
-/**
- * Return the last spawnKey in a spawnPath (the "current" spawn).
- * Returns null for root.
- */
-function leafSpawnKey(path) {
-    const parts = spawnPathParts(path);
-    return parts.length === 0 ? null : parts[parts.length - 1];
-}
-/**
- * True if `ancestor` is a strict ancestor of `descendant`. Root ("") is
- * ancestor of everything except itself.
- */
-function isAncestorSpawnPath(ancestor, descendant) {
-    const a = ancestor ?? '';
-    const d = descendant ?? '';
-    if (a === d)
-        return false;
-    if (a === '')
-        return d !== '';
-    return d.startsWith(a + SPAWN_PATH_SEP);
-}
-
-exports.MAX_NESTING_DEPTH = MAX_NESTING_DEPTH;
-exports.SPAWN_PATH_SEP = SPAWN_PATH_SEP;
-exports.buildSpawnPath = buildSpawnPath;
-exports.isAncestorSpawnPath = isAncestorSpawnPath;
-exports.leafSpawnKey = leafSpawnKey;
-exports.parentSpawnPath = parentSpawnPath;
-exports.spawnPathDepth = spawnPathDepth;
-exports.spawnPathParts = spawnPathParts;
-//# sourceMappingURL=spawnPath.cjs.map

package/dist/cjs/common/spawnPath.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"spawnPath.cjs","sources":["../../../src/common/spawnPath.ts"],"sourcesContent":["/**\n * spawnPath — hierarchical invocation identity for nested multi-agent orchestration.\n *\n * A spawnPath is a slash-separated chain of spawnKeys from the root of the current\n * agent invocation to the current spawn. The root agent has an empty spawnPath;\n * each handoff/transfer/sequence that spawns a new subgraph appends a new spawnKey.\n *\n * Examples:\n *   \"\"                               → primary agent (no spawn)\n *   \"call_abc\"                       → first-level handoff child\n *   \"call_abc/call_def\"              → grandchild (depth 2)\n *   \"call_abc/call_def/call_ghi\"     → depth 3\n *\n * These utilities are the single source of truth for path manipulation across:\n *   - @illuma-ai/agents (MultiAgentGraph, HandoffRegistry, callbacks)\n *   - host api (initialize.js, callbacks.js, ExecutionTrace writes)\n *   - host client (subagent store, sidebar rendering)\n *\n * See docs/multi-agent-nesting-architecture.md for the full design.\n */\n\n/** Separator between spawnKeys in a spawnPath. Chosen so that the path looks\n * like a filesystem/URL path, which makes it easy to read in logs and traces. */\nexport const SPAWN_PATH_SEP = '/';\n\n/** Hard cap on nested multi-agent invocations. Prevents runaway recursion.\n * Can be overridden at the host api layer via MULTI_AGENT_MAX_NESTING_DEPTH. */\nexport const MAX_NESTING_DEPTH = 5;\n\n/**\n * Append a spawnKey to a parent spawnPath.\n *\n * @param parent - Parent spawnPath (may be undefined/null/empty for root)\n * @param key    - spawnKey to append\n * @returns New spawnPath string\n */\nexport function buildSpawnPath(\n  parent: string | undefined | null,\n  key: string\n): string {\n  if (!key) {\n    throw new Error('[spawnPath] buildSpawnPath called with empty key');\n  }\n  if (parent == null || parent === '') return key;\n  return `${parent}${SPAWN_PATH_SEP}${key}`;\n}\n\n/**\n * Compute the depth of a spawnPath.\n * Root (empty) → 0; single-segment → 1; etc.\n */\nexport function spawnPathDepth(path: string | undefined | null): number {\n  if (path == null || path === '') return 0;\n  return path.split(SPAWN_PATH_SEP).filter(Boolean).length;\n}\n\n/**\n * Return the parent spawnPath, or null if the input is already root.\n *\n * - parentSpawnPath(\"a/b/c\") === \"a/b\"\n * - parentSpawnPath(\"a\") === \"\"\n * - parentSpawnPath(\"\") === null\n */\nexport function parentSpawnPath(\n  path: string | undefined | null\n): string | null {\n  if (path == null || path === '') return null;\n  const parts = path.split(SPAWN_PATH_SEP).filter(Boolean);\n  if (parts.length <= 1) return '';\n  return parts.slice(0, -1).join(SPAWN_PATH_SEP);\n}\n\n/** Split a spawnPath into its constituent spawnKey segments. */\nexport function spawnPathParts(path: string | undefined | null): string[] {\n  if (path == null || path === '') return [];\n  return path.split(SPAWN_PATH_SEP).filter(Boolean);\n}\n\n/**\n * Return the last spawnKey in a spawnPath (the \"current\" spawn).\n * Returns null for root.\n */\nexport function leafSpawnKey(path: string | undefined | null): string | null {\n  const parts = spawnPathParts(path);\n  return parts.length === 0 ? null : parts[parts.length - 1];\n}\n\n/**\n * True if `ancestor` is a strict ancestor of `descendant`. Root (\"\") is\n * ancestor of everything except itself.\n */\nexport function isAncestorSpawnPath(\n  ancestor: string | undefined | null,\n  descendant: string | undefined | null\n): boolean {\n  const a = ancestor ?? '';\n  const d = descendant ?? '';\n  if (a === d) return false;\n  if (a === '') return d !== '';\n  return d.startsWith(a + SPAWN_PATH_SEP);\n}\n"],"names":[],"mappings":";;AAAA;;;;;;;;;;;;;;;;;;;AAmBG;AAEH;AACiF;AAC1E,MAAM,cAAc,GAAG;AAE9B;AACgF;AACzE,MAAM,iBAAiB,GAAG;AAEjC;;;;;;AAMG;AACG,SAAU,cAAc,CAC5B,MAAiC,EACjC,GAAW,EAAA;IAEX,IAAI,CAAC,GAAG,EAAE;AACR,QAAA,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC;IACrE;AACA,IAAA,IAAI,MAAM,IAAI,IAAI,IAAI,MAAM,KAAK,EAAE;AAAE,QAAA,OAAO,GAAG;AAC/C,IAAA,OAAO,GAAG,MAAM,CAAA,EAAG,cAAc,CAAA,EAAG,GAAG,EAAE;AAC3C;AAEA;;;AAGG;AACG,SAAU,cAAc,CAAC,IAA+B,EAAA;AAC5D,IAAA,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,KAAK,EAAE;AAAE,QAAA,OAAO,CAAC;AACzC,IAAA,OAAO,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM;AAC1D;AAEA;;;;;;AAMG;AACG,SAAU,eAAe,CAC7B,IAA+B,EAAA;AAE/B,IAAA,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,KAAK,EAAE;AAAE,QAAA,OAAO,IAAI;AAC5C,IAAA,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC;AACxD,IAAA,IAAI,KAAK,CAAC,MAAM,IAAI,CAAC;AAAE,QAAA,OAAO,EAAE;AAChC,IAAA,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC;AAChD;AAEA;AACM,SAAU,cAAc,CAAC,IAA+B,EAAA;AAC5D,IAAA,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,KAAK,EAAE;AAAE,QAAA,OAAO,EAAE;IAC1C,OAAO,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC;AACnD;AAEA;;;AAGG;AACG,SAAU,YAAY,CAAC,IAA+B,EAAA;AAC1D,IAAA,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC;IAClC,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC,GAAG,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;AAC5D;AAEA;;;AAGG;AACG,SAAU,mBAAmB,CACjC,QAAmC,EACnC,UAAqC,EAAA;AAErC,IAAA,MAAM,CAAC,GAAG,QAAQ,IAAI,EAAE;AACxB,IAAA,MAAM,CAAC,GAAG,UAAU,IAAI,EAAE;IAC1B,IAAI,CAAC,KAAK,CAAC;AAAE,QAAA,OAAO,KAAK;IACzB,IAAI,CAAC,KAAK,EAAE;QAAE,OAAO,CAAC,KAAK,EAAE;IAC7B,OAAO,CAAC,CAAC,UAAU,CAAC,CAAC,GAAG,cAAc,CAAC;AACzC;;;;;;;;;;;"}