@illuma-ai/agents 1.0.96 → 1.1.0

package/dist/esm/main.mjs

@@ -10,6 +10,7 @@ export { addBedrockCacheControl, addCacheControl, stripAnthropicCacheControl, st
 export { formatContentStrings } from './messages/content.mjs';
 export { extractToolDiscoveries, hasToolSearchInCurrentTurn } from './messages/tools.mjs';
 export { FULL_SUMMARY_TEMPLATE, SIMPLE_SUMMARY_TEMPLATE, buildFullSummaryPrompt, buildSimpleSummaryPrompt, createEmergencySummary, formatMessagesForSummary, summarize, validateSummarySize } from './messages/summarize.mjs';
+export { deduplicateSystemMessages } from './messages/dedup.mjs';
 export { Graph, StandardGraph } from './graphs/Graph.mjs';
 export { MultiAgentGraph } from './graphs/MultiAgentGraph.mjs';
 export { Calculator, CalculatorSchema, CalculatorToolDefinition, CalculatorToolDescription, CalculatorToolName } from './tools/Calculator.mjs';
@@ -25,7 +26,7 @@ export { createSearchTool } from './tools/search/tool.mjs';
 export { DATE_RANGE, DEFAULT_COUNTRY_DESCRIPTION, DEFAULT_QUERY_DESCRIPTION, WebSearchToolDefinition, WebSearchToolDescription, WebSearchToolName, WebSearchToolSchema, countrySchema, dateSchema, imagesSchema, newsSchema, querySchema, videosSchema } from './tools/search/schema.mjs';
 export { createValidationErrorMessage, isValidJsonSchema, normalizeJsonSchema, prepareSchemaForProvider, validateStructuredOutput, zodToJsonSchema } from './schemas/validate.mjs';
 export { Callback, CommonEvents, Constants, ContentTypes, EdgeType, EnvVar, FinishReasons, GraphEvents, GraphNodeActions, GraphNodeKeys, MessageTypes, Providers, StepTypes, TitleMethod, ToolCallTypes } from './common/enum.mjs';
-export { MIN_THINKING_BUDGET, TOOL_TURN_THINKING_BUDGET } from './common/constants.mjs';
+export { CONTEXT_SAFETY_BUFFER, DEDUP_MAX_CONTENT_LENGTH, MIN_THINKING_BUDGET, MULTI_DOCUMENT_THRESHOLD, PRUNING_EMA_ALPHA, PRUNING_INITIAL_CALIBRATION, SUMMARIZATION_CONTEXT_THRESHOLD, SUMMARIZATION_RESERVE_RATIO, TOOL_DISCOVERY_CACHE_MAX_SIZE, TOOL_TURN_THINKING_BUDGET } from './common/constants.mjs';
 export { joinKeys, resetIfNotEmpty } from './utils/graph.mjs';
 export { isGoogleLike, isOpenAILike } from './utils/llm.mjs';
 export { isPresent, unescapeObject } from './utils/misc.mjs';
@@ -36,6 +37,9 @@ export { ensureToonLoaded, extractFirstJson, isToonAvailable, isToonFormat, json
 export { buildContextAnalytics } from './utils/contextAnalytics.mjs';
 export { isZodSchema, toJsonSchema } from './utils/schema.mjs';
 export { extractFinishReason, isMaxTokensFinish } from './utils/toolCallContinuation.mjs';
+export { buildMultiDocHintContent, buildPostPruneNote, detectDocuments, hasTaskTool, shouldInjectMultiDocHint } from './utils/contextPressure.mjs';
+export { ToolDiscoveryCache } from './utils/toolDiscoveryCache.mjs';
+export { applyCalibration, createPruneCalibration, updatePruneCalibration } from './utils/pruneCalibration.mjs';
 export { CustomOpenAIClient } from './llm/openai/index.mjs';
 export { ChatOpenRouter } from './llm/openrouter/index.mjs';
 export { getChatModelClass, llmProviders } from './llm/providers.mjs';

package/dist/esm/main.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"main.mjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"main.mjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/esm/messages/dedup.mjs

@@ -0,0 +1,93 @@
+import { MessageTypes } from '../common/enum.mjs';
+import { DEDUP_MAX_CONTENT_LENGTH } from '../common/constants.mjs';
+
+/**
+ * Deduplicates consecutive identical system messages in the context window.
+ *
+ * Problem: In long tool-use chains, the same system messages (e.g., post-prune notes,
+ * conversation summaries) can accumulate when the context is rebuilt on each iteration.
+ * These duplicates waste tokens without adding information.
+ *
+ * Strategy: Only deduplicate system messages that appear consecutively or are exact
+ * duplicates of an earlier system message. The FIRST occurrence is always kept.
+ * Non-system messages (human, ai, tool) are never touched.
+ *
+ * Important constraints:
+ * - The first system message (index 0) is ALWAYS preserved (it's the main system prompt)
+ * - Only system messages are candidates for deduplication
+ * - Messages with content longer than DEDUP_MAX_CONTENT_LENGTH are skipped (too expensive to compare)
+ * - Content comparison is by string equality (fast and deterministic)
+ *
+ * @param messages - The message array to deduplicate (not mutated)
+ * @returns A new array with duplicate system messages removed, and the count of removed messages
+ */
+function deduplicateSystemMessages(messages) {
+    if (messages.length <= 1) {
+        return { messages, removedCount: 0 };
+    }
+    const seenSystemContents = new Set();
+    const result = [];
+    let removedCount = 0;
+    for (let i = 0; i < messages.length; i++) {
+        const msg = messages[i];
+        const type = msg.getType();
+        // Non-system messages are always kept
+        if (type !== MessageTypes.SYSTEM) {
+            result.push(msg);
+            continue;
+        }
+        // First system message (main prompt) is always kept
+        if (i === 0) {
+            result.push(msg);
+            // Track its content for dedup of later duplicates
+            const content = getContentString(msg);
+            if (content != null) {
+                seenSystemContents.add(content);
+            }
+            continue;
+        }
+        // Get string content for comparison
+        const content = getContentString(msg);
+        // Skip dedup for very long or non-string content
+        if (content == null) {
+            result.push(msg);
+            continue;
+        }
+        // Check if this exact system message was already seen
+        if (seenSystemContents.has(content)) {
+            removedCount++;
+            continue; // Skip this duplicate
+        }
+        // New unique system message — keep it and track
+        seenSystemContents.add(content);
+        result.push(msg);
+    }
+    return { messages: result, removedCount };
+}
+/**
+ * Extracts a comparable string from a message's content.
+ * Returns null if the content is too large or non-string (skip dedup for those).
+ */
+function getContentString(msg) {
+    if (typeof msg.content === 'string') {
+        if (msg.content.length > DEDUP_MAX_CONTENT_LENGTH) {
+            return null;
+        }
+        return msg.content;
+    }
+    // Array content (e.g., Anthropic cache_control blocks) — serialize for comparison
+    // but only if reasonably sized
+    try {
+        const serialized = JSON.stringify(msg.content);
+        if (serialized.length > DEDUP_MAX_CONTENT_LENGTH) {
+            return null;
+        }
+        return serialized;
+    }
+    catch {
+        return null;
+    }
+}
+
+export { deduplicateSystemMessages };
+//# sourceMappingURL=dedup.mjs.map

package/dist/esm/messages/dedup.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"dedup.mjs","sources":["../../../src/messages/dedup.ts"],"sourcesContent":["// src/messages/dedup.ts\nimport type { BaseMessage } from '@langchain/core/messages';\nimport { MessageTypes } from '@/common';\nimport { DEDUP_MAX_CONTENT_LENGTH } from '@/common/constants';\n\n/**\n * Deduplicates consecutive identical system messages in the context window.\n *\n * Problem: In long tool-use chains, the same system messages (e.g., post-prune notes,\n * conversation summaries) can accumulate when the context is rebuilt on each iteration.\n * These duplicates waste tokens without adding information.\n *\n * Strategy: Only deduplicate system messages that appear consecutively or are exact\n * duplicates of an earlier system message. The FIRST occurrence is always kept.\n * Non-system messages (human, ai, tool) are never touched.\n *\n * Important constraints:\n * - The first system message (index 0) is ALWAYS preserved (it's the main system prompt)\n * - Only system messages are candidates for deduplication\n * - Messages with content longer than DEDUP_MAX_CONTENT_LENGTH are skipped (too expensive to compare)\n * - Content comparison is by string equality (fast and deterministic)\n *\n * @param messages - The message array to deduplicate (not mutated)\n * @returns A new array with duplicate system messages removed, and the count of removed messages\n */\nexport function deduplicateSystemMessages(messages: BaseMessage[]): {\n  messages: BaseMessage[];\n  removedCount: number;\n} {\n  if (messages.length <= 1) {\n    return { messages, removedCount: 0 };\n  }\n\n  const seenSystemContents = new Set<string>();\n  const result: BaseMessage[] = [];\n  let removedCount = 0;\n\n  for (let i = 0; i < messages.length; i++) {\n    const msg = messages[i];\n    const type = msg.getType();\n\n    // Non-system messages are always kept\n    if (type !== MessageTypes.SYSTEM) {\n      result.push(msg);\n      continue;\n    }\n\n    // First system message (main prompt) is always kept\n    if (i === 0) {\n      result.push(msg);\n      // Track its content for dedup of later duplicates\n      const content = getContentString(msg);\n      if (content != null) {\n        seenSystemContents.add(content);\n      }\n      continue;\n    }\n\n    // Get string content for comparison\n    const content = getContentString(msg);\n\n    // Skip dedup for very long or non-string content\n    if (content == null) {\n      result.push(msg);\n      continue;\n    }\n\n    // Check if this exact system message was already seen\n    if (seenSystemContents.has(content)) {\n      removedCount++;\n      continue; // Skip this duplicate\n    }\n\n    // New unique system message — keep it and track\n    seenSystemContents.add(content);\n    result.push(msg);\n  }\n\n  return { messages: result, removedCount };\n}\n\n/**\n * Extracts a comparable string from a message's content.\n * Returns null if the content is too large or non-string (skip dedup for those).\n */\nfunction getContentString(msg: BaseMessage): string | null {\n  if (typeof msg.content === 'string') {\n    if (msg.content.length > DEDUP_MAX_CONTENT_LENGTH) {\n      return null;\n    }\n    return msg.content;\n  }\n  // Array content (e.g., Anthropic cache_control blocks) — serialize for comparison\n  // but only if reasonably sized\n  try {\n    const serialized = JSON.stringify(msg.content);\n    if (serialized.length > DEDUP_MAX_CONTENT_LENGTH) {\n      return null;\n    }\n    return serialized;\n  } catch {\n    return null;\n  }\n}\n"],"names":[],"mappings":";;;AAKA;;;;;;;;;;;;;;;;;;;AAmBG;AACG,SAAU,yBAAyB,CAAC,QAAuB,EAAA;AAI/D,IAAA,IAAI,QAAQ,CAAC,MAAM,IAAI,CAAC,EAAE;AACxB,QAAA,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,CAAC,EAAE;IACtC;AAEA,IAAA,MAAM,kBAAkB,GAAG,IAAI,GAAG,EAAU;IAC5C,MAAM,MAAM,GAAkB,EAAE;IAChC,IAAI,YAAY,GAAG,CAAC;AAEpB,IAAA,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE;AACxC,QAAA,MAAM,GAAG,GAAG,QAAQ,CAAC,CAAC,CAAC;AACvB,QAAA,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO,EAAE;;AAG1B,QAAA,IAAI,IAAI,KAAK,YAAY,CAAC,MAAM,EAAE;AAChC,YAAA,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC;YAChB;QACF;;AAGA,QAAA,IAAI,CAAC,KAAK,CAAC,EAAE;AACX,YAAA,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC;;AAEhB,YAAA,MAAM,OAAO,GAAG,gBAAgB,CAAC,GAAG,CAAC;AACrC,YAAA,IAAI,OAAO,IAAI,IAAI,EAAE;AACnB,gBAAA,kBAAkB,CAAC,GAAG,CAAC,OAAO,CAAC;YACjC;YACA;QACF;;AAGA,QAAA,MAAM,OAAO,GAAG,gBAAgB,CAAC,GAAG,CAAC;;AAGrC,QAAA,IAAI,OAAO,IAAI,IAAI,EAAE;AACnB,YAAA,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC;YAChB;QACF;;AAGA,QAAA,IAAI,kBAAkB,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE;AACnC,YAAA,YAAY,EAAE;AACd,YAAA,SAAS;QACX;;AAGA,QAAA,kBAAkB,CAAC,GAAG,CAAC,OAAO,CAAC;AAC/B,QAAA,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC;IAClB;AAEA,IAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE;AAC3C;AAEA;;;AAGG;AACH,SAAS,gBAAgB,CAAC,GAAgB,EAAA;AACxC,IAAA,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,EAAE;QACnC,IAAI,GAAG,CAAC,OAAO,CAAC,MAAM,GAAG,wBAAwB,EAAE;AACjD,YAAA,OAAO,IAAI;QACb;QACA,OAAO,GAAG,CAAC,OAAO;IACpB;;;AAGA,IAAA,IAAI;QACF,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC;AAC9C,QAAA,IAAI,UAAU,CAAC,MAAM,GAAG,wBAAwB,EAAE;AAChD,YAAA,OAAO,IAAI;QACb;AACA,QAAA,OAAO,UAAU;IACnB;AAAE,IAAA,MAAM;AACN,QAAA,OAAO,IAAI;IACb;AACF;;;;"}

package/dist/esm/tools/CodeExecutor.mjs

@@ -75,10 +75,27 @@ const CodeExecutionToolDescription = `
 Runs code and returns stdout/stderr output from a stateless execution environment, similar to running scripts in a command-line interface. Each execution is isolated and independent.
 
 Usage:
-- No network access available.
+- No network access available. Do NOT use pip install, npm install, or any package manager.
 - Generated files are automatically delivered; **DO NOT** provide download links.
 - NEVER use this tool to execute malicious code.
 - When a code_id is returned in output, you can edit that code using code_id + old_str + new_str instead of rewriting the entire code block.
+
+Pre-installed Python packages (use directly, no installation needed):
+- Data Science: numpy, pandas
+- Visualization: matplotlib, seaborn, plotly
+- Documents: python-docx, python-pptx, reportlab, fpdf2, PyMuPDF, pdfplumber
+- Spreadsheets: openpyxl, xlsxwriter
+- Image: pillow
+- Data: orjson, lxml, beautifulsoup4, faker
+
+Pre-installed JavaScript packages:
+- pptxgenjs, react, react-dom, react-icons, sharp
+
+Pre-installed Go packages:
+- excelize (Excel), gofpdf (PDF)
+
+Pre-installed R packages:
+- ggplot2, dplyr, tidyr, readxl, writexl, jsonlite, Cairo
 `.trim();
 const CodeExecutionToolName = Constants.EXECUTE_CODE;
 const CodeExecutionToolDefinition = {
@@ -109,11 +126,13 @@ Runs code in a stateless execution environment. Each execution is isolated.
 ✅ ONLY USE FOR:
 - File generation: PowerPoint (.pptx), Word (.docx), PDF (.pdf), Excel (.xlsx)
 - Processing uploaded files (CSV, Excel analysis)
-- Heavy computation requiring Python
+- Heavy computation requiring Python (numpy, pandas for data analytics)
 
 Rules:
-- No network access available
+- No network access — do NOT use pip install, npm install, or any package manager
+- All packages are pre-installed: numpy, pandas, matplotlib, seaborn, plotly, python-docx, python-pptx, reportlab, openpyxl, xlsxwriter, pillow, faker, orjson, lxml, beautifulsoup4
 - Generated files auto-delivered (no download links needed)
+- **Error recovery**: When execution fails, use \`code_id\` + \`old_str\` + \`new_str\` to fix only the broken part — do NOT rewrite the entire code block. This is faster and saves tokens.
 `.trim();
     return tool(async (rawInput, config) => {
         // Resolve URL at call time (not module load time) to pick up env var changes

package/dist/esm/tools/CodeExecutor.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"CodeExecutor.mjs","sources":["../../../src/tools/CodeExecutor.ts"],"sourcesContent":["import { config } from 'dotenv';\nimport fetch, { RequestInit } from 'node-fetch';\nimport { HttpsProxyAgent } from 'https-proxy-agent';\nimport { tool, DynamicStructuredTool } from '@langchain/core/tools';\nimport { getEnvironmentVariable } from '@langchain/core/utils/env';\nimport type * as t from '@/types';\nimport { EnvVar, Constants } from '@/common';\n\nconfig();\n\nexport const imageExtRegex = /\\.(jpg|jpeg|png|gif|webp)$/i;\nexport const getCodeBaseURL = (): string =>\n  getEnvironmentVariable(EnvVar.CODE_BASEURL) ??\n  Constants.OFFICIAL_CODE_BASEURL;\n\nconst imageMessage = 'Image is already displayed to the user';\nconst otherMessage = 'File is already downloaded by the user';\nconst accessMessage =\n  'Note: Files from previous executions are automatically available and can be modified.';\nconst emptyOutputMessage =\n  \"stdout: Empty. Ensure you're writing output explicitly.\\n\";\n\nconst SUPPORTED_LANGUAGES = [\n  'py',\n  'js',\n  'ts',\n  'c',\n  'cpp',\n  'java',\n  'php',\n  'rs',\n  'go',\n  'd',\n  'f90',\n  'r',\n  'bash',\n] as const;\n\nexport const CodeExecutionToolSchema = {\n  type: 'object',\n  properties: {\n    lang: {\n      type: 'string',\n      enum: SUPPORTED_LANGUAGES,\n      description:\n        'The programming language or runtime to execute the code in.',\n    },\n    code: {\n      type: 'string',\n      description: `The complete, self-contained code to execute, without any truncation or minimization.\n- The environment is stateless; variables and imports don't persist between executions.\n- Generated files from previous executions are automatically available in \"/mnt/data/\".\n- Files from previous executions are automatically available and can be modified in place.\n- Input code **IS ALREADY** displayed to the user, so **DO NOT** repeat it in your response unless asked.\n- Output code **IS NOT** displayed to the user, so **DO** write all desired output explicitly.\n- IMPORTANT: You MUST explicitly print/output ALL results you want the user to see.\n- py: This is not a Jupyter notebook environment. Use \\`print()\\` for all outputs.\n- py: Matplotlib: Use \\`plt.savefig()\\` to save plots as files.\n- js: use the \\`console\\` or \\`process\\` methods for all outputs.\n- r: IMPORTANT: No X11 display available. ALL graphics MUST use Cairo library (library(Cairo)).\n- Other languages: use appropriate output functions.`,\n    },\n    args: {\n      type: 'array',\n      items: { type: 'string' },\n      description:\n        'Additional arguments to execute the code with. This should only be used if the input code requires additional arguments to run.',\n    },\n    code_id: {\n      type: 'string',\n      description:\n        'ID of previously stored code (returned by a prior execute_code call). Use with old_str/new_str to edit stored code instead of rewriting it.',\n    },\n    old_str: {\n      type: 'string',\n      description:\n        'Exact string to find in stored code (requires code_id). Copy verbatim from the code you wrote.',\n    },\n    new_str: {\n      type: 'string',\n      description:\n        'Replacement string (requires code_id and old_str). The matched old_str will be replaced with this value.',\n    },\n  },\n  required: ['lang'],\n} as const;\n\n// NOTE: Resolved at call time inside the tool function, not at module load time.\n// Module-level caching caused stale URLs when env vars changed between restarts.\n\ntype SupportedLanguage = (typeof SUPPORTED_LANGUAGES)[number];\n\nexport const CodeExecutionToolDescription = `\nRuns code and returns stdout/stderr output from a stateless execution environment, similar to running scripts in a command-line interface. Each execution is isolated and independent.\n\nUsage:\n- No network access available.\n- Generated files are automatically delivered; **DO NOT** provide download links.\n- NEVER use this tool to execute malicious code.\n- When a code_id is returned in output, you can edit that code using code_id + old_str + new_str instead of rewriting the entire code block.\n`.trim();\n\nexport const CodeExecutionToolName = Constants.EXECUTE_CODE;\n\nexport const CodeExecutionToolDefinition = {\n  name: CodeExecutionToolName,\n  description: CodeExecutionToolDescription,\n  schema: CodeExecutionToolSchema,\n} as const;\n\nfunction createCodeExecutionTool(\n  params: t.CodeExecutionToolParams = {}\n): DynamicStructuredTool {\n  const apiKey =\n    params[EnvVar.CODE_API_KEY] ??\n    params.apiKey ??\n    getEnvironmentVariable(EnvVar.CODE_API_KEY) ??\n    '';\n  if (!apiKey) {\n    throw new Error('No API key provided for code execution tool.');\n  }\n\n  const description = `\n⛔ STOP! Before using this tool, ask: \"Does user need a DOWNLOADABLE FILE?\"\n- If NO (dashboard, chart, visualization, UI) → DO NOT USE THIS TOOL. Use content_tool write instead.\n- If YES (.pptx, .docx, .pdf, .xlsx) → Use this tool.\n\nRuns code in a stateless execution environment. Each execution is isolated.\n\n🚫 NEVER USE FOR:\n- Dashboards, charts, visualizations → Use content_tool write with React/Chart.js\n- \"Mock data\" or \"sample data\" for display → Hardcode data in content_tool write\n- UI components, HTML pages, React apps → Use content_tool write\n\n✅ ONLY USE FOR:\n- File generation: PowerPoint (.pptx), Word (.docx), PDF (.pdf), Excel (.xlsx)\n- Processing uploaded files (CSV, Excel analysis)\n- Heavy computation requiring Python\n\nRules:\n- No network access available\n- Generated files auto-delivered (no download links needed)\n`.trim();\n\n  return tool(\n    async (rawInput, config) => {\n      // Resolve URL at call time (not module load time) to pick up env var changes\n      const baseEndpoint = getCodeBaseURL();\n      const EXEC_ENDPOINT = `${baseEndpoint}/exec`;\n\n      const { lang, code, ...rest } = rawInput as {\n        lang: SupportedLanguage;\n        code: string;\n        code_id?: string;\n        old_str?: string;\n        new_str?: string;\n        args?: string[];\n      };\n      /**\n       * Extract session context from config.toolCall (injected by ToolNode).\n       * - session_id: For API to associate with previous session\n       * - _injected_files: File refs to pass directly (avoids /files endpoint race condition)\n       */\n      const { session_id, _injected_files } = (config.toolCall ?? {}) as {\n        session_id?: string;\n        _injected_files?: t.CodeEnvFile[];\n      };\n\n      const postData: Record<string, unknown> = {\n        lang,\n        code,\n        ...rest,\n        ...params,\n      };\n\n      /**\n       * Pass session_id to /exec so code-executor reuses the existing session workspace.\n       * This allows retries and follow-up executions to access previously generated files.\n       */\n      if (session_id != null && session_id.length > 0) {\n        postData.session_id = session_id;\n      }\n\n      /**\n       * File injection priority:\n       * 1. Use _injected_files from ToolNode (avoids /files endpoint race condition)\n       * 2. Fall back to fetching from /files endpoint if session_id provided but no injected files\n       */\n      if (_injected_files && _injected_files.length > 0) {\n        postData.files = _injected_files;\n      } else if (session_id != null && session_id.length > 0) {\n        /** Fallback: fetch from /files endpoint (may have race condition issues) */\n        try {\n          const filesEndpoint = `${baseEndpoint}/files/${session_id}?detail=full`;\n          const userIdForFiles = params.user_id ?? '';\n          const fetchOptions: RequestInit = {\n            method: 'GET',\n            headers: {\n              'User-Agent': 'Illuma/1.0',\n              'X-API-Key': apiKey,\n              ...(userIdForFiles ? { 'User-Id': userIdForFiles } : {}),\n            },\n          };\n\n          if (process.env.PROXY != null && process.env.PROXY !== '') {\n            fetchOptions.agent = new HttpsProxyAgent(process.env.PROXY);\n          }\n\n          const response = await fetch(filesEndpoint, fetchOptions);\n          if (!response.ok) {\n            throw new Error(\n              `Failed to fetch files for session: ${response.status}`\n            );\n          }\n\n          const files = await response.json();\n          if (Array.isArray(files) && files.length > 0) {\n            const fileReferences: t.CodeEnvFile[] = files.map((file) => {\n              const nameParts = file.name.split('/');\n              const id = nameParts.length > 1 ? nameParts[1].split('.')[0] : '';\n\n              return {\n                session_id,\n                id,\n                name: file.metadata['original-filename'],\n              };\n            });\n\n            postData.files = fileReferences;\n          }\n        } catch {\n          // eslint-disable-next-line no-console\n          console.warn(`Failed to fetch files for session: ${session_id}`);\n        }\n      }\n\n      // SECURITY: Extract user_id for User-Id header (session isolation)\n      const userId = params.user_id ?? '';\n\n      try {\n        const fetchOptions: RequestInit = {\n          method: 'POST',\n          headers: {\n            'Content-Type': 'application/json',\n            'User-Agent': 'Illuma/1.0',\n            'X-API-Key': apiKey,\n            ...(userId ? { 'User-Id': userId } : {}),\n          },\n          body: JSON.stringify(postData),\n        };\n\n        if (process.env.PROXY != null && process.env.PROXY !== '') {\n          fetchOptions.agent = new HttpsProxyAgent(process.env.PROXY);\n        }\n        const response = await fetch(EXEC_ENDPOINT, fetchOptions);\n        if (!response.ok) {\n          throw new Error(`HTTP error! status: ${response.status}`);\n        }\n\n        const result: t.ExecuteResult = await response.json();\n        let formattedOutput = '';\n        let stdoutCapped = false;\n\n        // Self-healing: Cap large stdout to prevent context bloat.\n        // Preserves head (8KB) + tail (4KB) so the agent sees beginning and end.\n        const STDOUT_MAX_CHARS = 16384;\n        const STDOUT_HEAD_CHARS = 8192;\n        const STDOUT_TAIL_CHARS = 4096;\n        if (result.stdout && result.stdout.length > STDOUT_MAX_CHARS) {\n          const originalLen = result.stdout.length;\n          const head = result.stdout.substring(0, STDOUT_HEAD_CHARS);\n          const tail = result.stdout.substring(\n            result.stdout.length - STDOUT_TAIL_CHARS\n          );\n          const omitted = originalLen - STDOUT_HEAD_CHARS - STDOUT_TAIL_CHARS;\n          result.stdout = `${head}\\n\\n[...${omitted} chars omitted...]\\n\\n${tail}`;\n          stdoutCapped = true;\n          // eslint-disable-next-line no-console\n          console.debug(\n            `[CodeExecutor] stdout capped: ${originalLen} → ${result.stdout.length} chars`\n          );\n        }\n\n        if (result.stdout) {\n          formattedOutput += `stdout:\\n${result.stdout}\\n`;\n        } else {\n          formattedOutput += emptyOutputMessage;\n        }\n        if (result.stderr) formattedOutput += `stderr:\\n${result.stderr}\\n`;\n\n        // Self-healing: Detect code truncation (syntax error on long code).\n        // When the agent's generated code is >1500 chars and produces a SyntaxError,\n        // it's likely truncated mid-generation rather than a real bug.\n        const CODE_TRUNCATION_MIN_CHARS = 1500;\n        if (result.stderr && code.length > CODE_TRUNCATION_MIN_CHARS) {\n          const stderrLower = result.stderr.toLowerCase();\n          if (\n            stderrLower.includes('syntaxerror') ||\n            stderrLower.includes('unexpected end') ||\n            stderrLower.includes('unexpected eof') ||\n            stderrLower.includes('unterminated')\n          ) {\n            // eslint-disable-next-line no-console\n            console.debug(\n              `[CodeExecutor] Code truncation detected: code=${code.length} chars, stderr contains syntax error`\n            );\n            formattedOutput +=\n              '\\n[CODE_TRUNCATION_LIKELY] Your code appears truncated mid-generation.' +\n              ' Split into multiple smaller execute_code calls (max 60 lines each).' +\n              ' For documents: create+save first, then open+append+save in follow-up calls.' +\n              ' Do NOT retry the same long code block.';\n          }\n        }\n\n        // Self-healing: Advisory when stdout was capped\n        if (stdoutCapped) {\n          formattedOutput +=\n            '\\n[OUTPUT_TOO_LARGE] stdout was capped. Use targeted print() for specific values.';\n        }\n\n        if (result.files && result.files.length > 0) {\n          formattedOutput += 'Generated files:\\n';\n\n          const fileCount = result.files.length;\n          for (let i = 0; i < fileCount; i++) {\n            const file = result.files[i];\n            const isImage = imageExtRegex.test(file.name);\n            formattedOutput += `- /mnt/data/${file.name} | ${isImage ? imageMessage : otherMessage}`;\n\n            if (i < fileCount - 1) {\n              formattedOutput += fileCount <= 3 ? ', ' : ',\\n';\n            }\n          }\n\n          formattedOutput += `\\n\\n${accessMessage}`;\n          return [\n            formattedOutput.trim(),\n            {\n              session_id: result.session_id,\n              files: result.files,\n            },\n          ];\n        }\n\n        return [formattedOutput.trim(), { session_id: result.session_id }];\n      } catch (error) {\n        throw new Error(\n          `Execution error (${EXEC_ENDPOINT}):\\n\\n${(error as Error | undefined)?.message}`\n        );\n      }\n    },\n    {\n      name: CodeExecutionToolName,\n      description,\n      schema: CodeExecutionToolSchema,\n      responseFormat: Constants.CONTENT_AND_ARTIFACT,\n    }\n  );\n}\n\nexport { createCodeExecutionTool };\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"CodeExecutor.mjs","sources":["../../../src/tools/CodeExecutor.ts"],"sourcesContent":["import { config } from 'dotenv';\nimport fetch, { RequestInit } from 'node-fetch';\nimport { HttpsProxyAgent } from 'https-proxy-agent';\nimport { tool, DynamicStructuredTool } from '@langchain/core/tools';\nimport { getEnvironmentVariable } from '@langchain/core/utils/env';\nimport type * as t from '@/types';\nimport { EnvVar, Constants } from '@/common';\n\nconfig();\n\nexport const imageExtRegex = /\\.(jpg|jpeg|png|gif|webp)$/i;\nexport const getCodeBaseURL = (): string =>\n  getEnvironmentVariable(EnvVar.CODE_BASEURL) ??\n  Constants.OFFICIAL_CODE_BASEURL;\n\nconst imageMessage = 'Image is already displayed to the user';\nconst otherMessage = 'File is already downloaded by the user';\nconst accessMessage =\n  'Note: Files from previous executions are automatically available and can be modified.';\nconst emptyOutputMessage =\n  \"stdout: Empty. Ensure you're writing output explicitly.\\n\";\n\nconst SUPPORTED_LANGUAGES = [\n  'py',\n  'js',\n  'ts',\n  'c',\n  'cpp',\n  'java',\n  'php',\n  'rs',\n  'go',\n  'd',\n  'f90',\n  'r',\n  'bash',\n] as const;\n\nexport const CodeExecutionToolSchema = {\n  type: 'object',\n  properties: {\n    lang: {\n      type: 'string',\n      enum: SUPPORTED_LANGUAGES,\n      description:\n        'The programming language or runtime to execute the code in.',\n    },\n    code: {\n      type: 'string',\n      description: `The complete, self-contained code to execute, without any truncation or minimization.\n- The environment is stateless; variables and imports don't persist between executions.\n- Generated files from previous executions are automatically available in \"/mnt/data/\".\n- Files from previous executions are automatically available and can be modified in place.\n- Input code **IS ALREADY** displayed to the user, so **DO NOT** repeat it in your response unless asked.\n- Output code **IS NOT** displayed to the user, so **DO** write all desired output explicitly.\n- IMPORTANT: You MUST explicitly print/output ALL results you want the user to see.\n- py: This is not a Jupyter notebook environment. Use \\`print()\\` for all outputs.\n- py: Matplotlib: Use \\`plt.savefig()\\` to save plots as files.\n- js: use the \\`console\\` or \\`process\\` methods for all outputs.\n- r: IMPORTANT: No X11 display available. ALL graphics MUST use Cairo library (library(Cairo)).\n- Other languages: use appropriate output functions.`,\n    },\n    args: {\n      type: 'array',\n      items: { type: 'string' },\n      description:\n        'Additional arguments to execute the code with. This should only be used if the input code requires additional arguments to run.',\n    },\n    code_id: {\n      type: 'string',\n      description:\n        'ID of previously stored code (returned by a prior execute_code call). Use with old_str/new_str to edit stored code instead of rewriting it.',\n    },\n    old_str: {\n      type: 'string',\n      description:\n        'Exact string to find in stored code (requires code_id). Copy verbatim from the code you wrote.',\n    },\n    new_str: {\n      type: 'string',\n      description:\n        'Replacement string (requires code_id and old_str). The matched old_str will be replaced with this value.',\n    },\n  },\n  required: ['lang'],\n} as const;\n\n// NOTE: Resolved at call time inside the tool function, not at module load time.\n// Module-level caching caused stale URLs when env vars changed between restarts.\n\ntype SupportedLanguage = (typeof SUPPORTED_LANGUAGES)[number];\n\nexport const CodeExecutionToolDescription = `\nRuns code and returns stdout/stderr output from a stateless execution environment, similar to running scripts in a command-line interface. Each execution is isolated and independent.\n\nUsage:\n- No network access available. Do NOT use pip install, npm install, or any package manager.\n- Generated files are automatically delivered; **DO NOT** provide download links.\n- NEVER use this tool to execute malicious code.\n- When a code_id is returned in output, you can edit that code using code_id + old_str + new_str instead of rewriting the entire code block.\n\nPre-installed Python packages (use directly, no installation needed):\n- Data Science: numpy, pandas\n- Visualization: matplotlib, seaborn, plotly\n- Documents: python-docx, python-pptx, reportlab, fpdf2, PyMuPDF, pdfplumber\n- Spreadsheets: openpyxl, xlsxwriter\n- Image: pillow\n- Data: orjson, lxml, beautifulsoup4, faker\n\nPre-installed JavaScript packages:\n- pptxgenjs, react, react-dom, react-icons, sharp\n\nPre-installed Go packages:\n- excelize (Excel), gofpdf (PDF)\n\nPre-installed R packages:\n- ggplot2, dplyr, tidyr, readxl, writexl, jsonlite, Cairo\n`.trim();\n\nexport const CodeExecutionToolName = Constants.EXECUTE_CODE;\n\nexport const CodeExecutionToolDefinition = {\n  name: CodeExecutionToolName,\n  description: CodeExecutionToolDescription,\n  schema: CodeExecutionToolSchema,\n} as const;\n\nfunction createCodeExecutionTool(\n  params: t.CodeExecutionToolParams = {}\n): DynamicStructuredTool {\n  const apiKey =\n    params[EnvVar.CODE_API_KEY] ??\n    params.apiKey ??\n    getEnvironmentVariable(EnvVar.CODE_API_KEY) ??\n    '';\n  if (!apiKey) {\n    throw new Error('No API key provided for code execution tool.');\n  }\n\n  const description = `\n⛔ STOP! Before using this tool, ask: \"Does user need a DOWNLOADABLE FILE?\"\n- If NO (dashboard, chart, visualization, UI) → DO NOT USE THIS TOOL. Use content_tool write instead.\n- If YES (.pptx, .docx, .pdf, .xlsx) → Use this tool.\n\nRuns code in a stateless execution environment. Each execution is isolated.\n\n🚫 NEVER USE FOR:\n- Dashboards, charts, visualizations → Use content_tool write with React/Chart.js\n- \"Mock data\" or \"sample data\" for display → Hardcode data in content_tool write\n- UI components, HTML pages, React apps → Use content_tool write\n\n✅ ONLY USE FOR:\n- File generation: PowerPoint (.pptx), Word (.docx), PDF (.pdf), Excel (.xlsx)\n- Processing uploaded files (CSV, Excel analysis)\n- Heavy computation requiring Python (numpy, pandas for data analytics)\n\nRules:\n- No network access — do NOT use pip install, npm install, or any package manager\n- All packages are pre-installed: numpy, pandas, matplotlib, seaborn, plotly, python-docx, python-pptx, reportlab, openpyxl, xlsxwriter, pillow, faker, orjson, lxml, beautifulsoup4\n- Generated files auto-delivered (no download links needed)\n- **Error recovery**: When execution fails, use \\`code_id\\` + \\`old_str\\` + \\`new_str\\` to fix only the broken part — do NOT rewrite the entire code block. This is faster and saves tokens.\n`.trim();\n\n  return tool(\n    async (rawInput, config) => {\n      // Resolve URL at call time (not module load time) to pick up env var changes\n      const baseEndpoint = getCodeBaseURL();\n      const EXEC_ENDPOINT = `${baseEndpoint}/exec`;\n\n      const { lang, code, ...rest } = rawInput as {\n        lang: SupportedLanguage;\n        code: string;\n        code_id?: string;\n        old_str?: string;\n        new_str?: string;\n        args?: string[];\n      };\n      /**\n       * Extract session context from config.toolCall (injected by ToolNode).\n       * - session_id: For API to associate with previous session\n       * - _injected_files: File refs to pass directly (avoids /files endpoint race condition)\n       */\n      const { session_id, _injected_files } = (config.toolCall ?? {}) as {\n        session_id?: string;\n        _injected_files?: t.CodeEnvFile[];\n      };\n\n      const postData: Record<string, unknown> = {\n        lang,\n        code,\n        ...rest,\n        ...params,\n      };\n\n      /**\n       * Pass session_id to /exec so code-executor reuses the existing session workspace.\n       * This allows retries and follow-up executions to access previously generated files.\n       */\n      if (session_id != null && session_id.length > 0) {\n        postData.session_id = session_id;\n      }\n\n      /**\n       * File injection priority:\n       * 1. Use _injected_files from ToolNode (avoids /files endpoint race condition)\n       * 2. Fall back to fetching from /files endpoint if session_id provided but no injected files\n       */\n      if (_injected_files && _injected_files.length > 0) {\n        postData.files = _injected_files;\n      } else if (session_id != null && session_id.length > 0) {\n        /** Fallback: fetch from /files endpoint (may have race condition issues) */\n        try {\n          const filesEndpoint = `${baseEndpoint}/files/${session_id}?detail=full`;\n          const userIdForFiles = params.user_id ?? '';\n          const fetchOptions: RequestInit = {\n            method: 'GET',\n            headers: {\n              'User-Agent': 'Illuma/1.0',\n              'X-API-Key': apiKey,\n              ...(userIdForFiles ? { 'User-Id': userIdForFiles } : {}),\n            },\n          };\n\n          if (process.env.PROXY != null && process.env.PROXY !== '') {\n            fetchOptions.agent = new HttpsProxyAgent(process.env.PROXY);\n          }\n\n          const response = await fetch(filesEndpoint, fetchOptions);\n          if (!response.ok) {\n            throw new Error(\n              `Failed to fetch files for session: ${response.status}`\n            );\n          }\n\n          const files = await response.json();\n          if (Array.isArray(files) && files.length > 0) {\n            const fileReferences: t.CodeEnvFile[] = files.map((file) => {\n              const nameParts = file.name.split('/');\n              const id = nameParts.length > 1 ? nameParts[1].split('.')[0] : '';\n\n              return {\n                session_id,\n                id,\n                name: file.metadata['original-filename'],\n              };\n            });\n\n            postData.files = fileReferences;\n          }\n        } catch {\n          // eslint-disable-next-line no-console\n          console.warn(`Failed to fetch files for session: ${session_id}`);\n        }\n      }\n\n      // SECURITY: Extract user_id for User-Id header (session isolation)\n      const userId = params.user_id ?? '';\n\n      try {\n        const fetchOptions: RequestInit = {\n          method: 'POST',\n          headers: {\n            'Content-Type': 'application/json',\n            'User-Agent': 'Illuma/1.0',\n            'X-API-Key': apiKey,\n            ...(userId ? { 'User-Id': userId } : {}),\n          },\n          body: JSON.stringify(postData),\n        };\n\n        if (process.env.PROXY != null && process.env.PROXY !== '') {\n          fetchOptions.agent = new HttpsProxyAgent(process.env.PROXY);\n        }\n        const response = await fetch(EXEC_ENDPOINT, fetchOptions);\n        if (!response.ok) {\n          throw new Error(`HTTP error! status: ${response.status}`);\n        }\n\n        const result: t.ExecuteResult = await response.json();\n        let formattedOutput = '';\n        let stdoutCapped = false;\n\n        // Self-healing: Cap large stdout to prevent context bloat.\n        // Preserves head (8KB) + tail (4KB) so the agent sees beginning and end.\n        const STDOUT_MAX_CHARS = 16384;\n        const STDOUT_HEAD_CHARS = 8192;\n        const STDOUT_TAIL_CHARS = 4096;\n        if (result.stdout && result.stdout.length > STDOUT_MAX_CHARS) {\n          const originalLen = result.stdout.length;\n          const head = result.stdout.substring(0, STDOUT_HEAD_CHARS);\n          const tail = result.stdout.substring(\n            result.stdout.length - STDOUT_TAIL_CHARS\n          );\n          const omitted = originalLen - STDOUT_HEAD_CHARS - STDOUT_TAIL_CHARS;\n          result.stdout = `${head}\\n\\n[...${omitted} chars omitted...]\\n\\n${tail}`;\n          stdoutCapped = true;\n          // eslint-disable-next-line no-console\n          console.debug(\n            `[CodeExecutor] stdout capped: ${originalLen} → ${result.stdout.length} chars`\n          );\n        }\n\n        if (result.stdout) {\n          formattedOutput += `stdout:\\n${result.stdout}\\n`;\n        } else {\n          formattedOutput += emptyOutputMessage;\n        }\n        if (result.stderr) formattedOutput += `stderr:\\n${result.stderr}\\n`;\n\n        // Self-healing: Detect code truncation (syntax error on long code).\n        // When the agent's generated code is >1500 chars and produces a SyntaxError,\n        // it's likely truncated mid-generation rather than a real bug.\n        const CODE_TRUNCATION_MIN_CHARS = 1500;\n        if (result.stderr && code.length > CODE_TRUNCATION_MIN_CHARS) {\n          const stderrLower = result.stderr.toLowerCase();\n          if (\n            stderrLower.includes('syntaxerror') ||\n            stderrLower.includes('unexpected end') ||\n            stderrLower.includes('unexpected eof') ||\n            stderrLower.includes('unterminated')\n          ) {\n            // eslint-disable-next-line no-console\n            console.debug(\n              `[CodeExecutor] Code truncation detected: code=${code.length} chars, stderr contains syntax error`\n            );\n            formattedOutput +=\n              '\\n[CODE_TRUNCATION_LIKELY] Your code appears truncated mid-generation.' +\n              ' Split into multiple smaller execute_code calls (max 60 lines each).' +\n              ' For documents: create+save first, then open+append+save in follow-up calls.' +\n              ' Do NOT retry the same long code block.';\n          }\n        }\n\n        // Self-healing: Advisory when stdout was capped\n        if (stdoutCapped) {\n          formattedOutput +=\n            '\\n[OUTPUT_TOO_LARGE] stdout was capped. Use targeted print() for specific values.';\n        }\n\n        if (result.files && result.files.length > 0) {\n          formattedOutput += 'Generated files:\\n';\n\n          const fileCount = result.files.length;\n          for (let i = 0; i < fileCount; i++) {\n            const file = result.files[i];\n            const isImage = imageExtRegex.test(file.name);\n            formattedOutput += `- /mnt/data/${file.name} | ${isImage ? imageMessage : otherMessage}`;\n\n            if (i < fileCount - 1) {\n              formattedOutput += fileCount <= 3 ? ', ' : ',\\n';\n            }\n          }\n\n          formattedOutput += `\\n\\n${accessMessage}`;\n          return [\n            formattedOutput.trim(),\n            {\n              session_id: result.session_id,\n              files: result.files,\n            },\n          ];\n        }\n\n        return [formattedOutput.trim(), { session_id: result.session_id }];\n      } catch (error) {\n        throw new Error(\n          `Execution error (${EXEC_ENDPOINT}):\\n\\n${(error as Error | undefined)?.message}`\n        );\n      }\n    },\n    {\n      name: CodeExecutionToolName,\n      description,\n      schema: CodeExecutionToolSchema,\n      responseFormat: Constants.CONTENT_AND_ARTIFACT,\n    }\n  );\n}\n\nexport { createCodeExecutionTool };\n"],"names":[],"mappings":"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"}

package/dist/esm/types/graph.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"graph.mjs","sources":["../../../src/types/graph.ts"],"sourcesContent":["// src/types/graph.ts\nimport type {\n  START,\n  StateType,\n  UpdateType,\n  StateGraph,\n  StateGraphArgs,\n  StateDefinition,\n  CompiledStateGraph,\n  BinaryOperatorAggregate,\n} from '@langchain/langgraph';\nimport type { BindToolsInput } from '@langchain/core/language_models/chat_models';\nimport type {\n  BaseMessage,\n  AIMessageChunk,\n  SystemMessage,\n} from '@langchain/core/messages';\nimport type { RunnableConfig, Runnable } from '@langchain/core/runnables';\nimport type { ChatGenerationChunk } from '@langchain/core/outputs';\nimport type { GoogleAIToolType } from '@langchain/google-common';\nimport type {\n  ToolMap,\n  ToolEndEvent,\n  GenericTool,\n  LCTool,\n  ToolApprovalConfig,\n} from '@/types/tools';\nimport type { Providers, Callback, GraphNodeKeys } from '@/common';\nimport type { StandardGraph, MultiAgentGraph } from '@/graphs';\nimport type { ClientOptions } from '@/types/llm';\nimport type {\n  RunStep,\n  RunStepDeltaEvent,\n  MessageDeltaEvent,\n  ReasoningDeltaEvent,\n} from '@/types/stream';\nimport type { TokenCounter } from '@/types/run';\n\n/** Interface for bound model with stream and invoke methods */\nexport interface ChatModel {\n  stream?: (\n    messages: BaseMessage[],\n    config?: RunnableConfig\n  ) => Promise<AsyncIterable<AIMessageChunk>>;\n  invoke: (\n    messages: BaseMessage[],\n    config?: RunnableConfig\n  ) => Promise<AIMessageChunk>;\n}\n\nexport type GraphNode = GraphNodeKeys | typeof START;\nexport type ClientCallback<T extends unknown[]> = (\n  graph: StandardGraph,\n  ...args: T\n) => void;\n\nexport type ClientCallbacks = {\n  [Callback.TOOL_ERROR]?: ClientCallback<[Error, string]>;\n  [Callback.TOOL_START]?: ClientCallback<unknown[]>;\n  [Callback.TOOL_END]?: ClientCallback<unknown[]>;\n};\n\nexport type SystemCallbacks = {\n  [K in keyof ClientCallbacks]: ClientCallbacks[K] extends ClientCallback<\n    infer Args\n  >\n    ? (...args: Args) => void\n    : never;\n};\n\nexport type BaseGraphState = {\n  messages: BaseMessage[];\n  /**\n   * Structured response when using structured output mode.\n   * Contains the validated JSON response conforming to the configured schema.\n   */\n  structuredResponse?: Record<string, unknown>;\n};\n\nexport type MultiAgentGraphState = BaseGraphState & {\n  agentMessages?: BaseMessage[];\n};\n\nexport type IState = BaseGraphState;\n\nexport interface EventHandler {\n  handle(\n    event: string,\n    data:\n      | StreamEventData\n      | ModelEndData\n      | RunStep\n      | RunStepDeltaEvent\n      | MessageDeltaEvent\n      | ReasoningDeltaEvent\n      | { result: ToolEndEvent },\n    metadata?: Record<string, unknown>,\n    graph?: StandardGraph | MultiAgentGraph\n  ): void | Promise<void>;\n}\n\nexport type GraphStateChannels<T extends BaseGraphState> =\n  StateGraphArgs<T>['channels'];\n\nexport type Workflow<\n  T extends BaseGraphState = BaseGraphState,\n  U extends Partial<T> = Partial<T>,\n  N extends string = string,\n> = StateGraph<T, U, N>;\n\nexport type CompiledWorkflow<\n  T extends BaseGraphState = BaseGraphState,\n  U extends Partial<T> = Partial<T>,\n  N extends string = string,\n> = CompiledStateGraph<T, U, N>;\n\nexport type CompiledStateWorkflow = CompiledStateGraph<\n  StateType<{\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  }>,\n  UpdateType<{\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  }>,\n  string,\n  {\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  },\n  {\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  },\n  StateDefinition\n>;\n\nexport type CompiledMultiAgentWorkflow = CompiledStateGraph<\n  StateType<{\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n    agentMessages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  }>,\n  UpdateType<{\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n    agentMessages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  }>,\n  string,\n  {\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n    agentMessages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  },\n  {\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n    agentMessages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  },\n  StateDefinition\n>;\n\nexport type CompiledAgentWorfklow = CompiledStateGraph<\n  {\n    messages: BaseMessage[];\n  },\n  {\n    messages?: BaseMessage[] | undefined;\n  },\n  '__start__' | `agent=${string}` | `tools=${string}`,\n  {\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  },\n  {\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  },\n  StateDefinition,\n  {\n    [x: `agent=${string}`]: Partial<BaseGraphState>;\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    [x: `tools=${string}`]: any;\n  }\n>;\n\nexport type SystemRunnable =\n  | Runnable<\n      BaseMessage[],\n      (BaseMessage | SystemMessage)[],\n      RunnableConfig<Record<string, unknown>>\n    >\n  | undefined;\n\n/**\n * Optional compile options passed to workflow.compile().\n * These are intentionally untyped to avoid coupling to library internals.\n */\nexport type CompileOptions = {\n  // A checkpointer instance (e.g., MemorySaver, SQL saver)\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  checkpointer?: any;\n  interruptBefore?: string[];\n  interruptAfter?: string[];\n  /**\n   * Human-in-the-loop tool approval configuration.\n   * When set, tools matching the policy will trigger an interrupt()\n   * before execution, pausing the graph for human approval.\n   * Requires a checkpointer to be set for interrupt/resume to work.\n   */\n  toolApprovalConfig?: ToolApprovalConfig;\n};\n\nexport type EventStreamCallbackHandlerInput =\n  Parameters<CompiledWorkflow['streamEvents']>[2] extends Omit<\n    infer T,\n    'autoClose'\n  >\n    ? T\n    : never;\n\nexport type StreamChunk =\n  | (ChatGenerationChunk & {\n      message: AIMessageChunk;\n    })\n  | AIMessageChunk;\n\n/**\n * Data associated with a StreamEvent.\n */\nexport type StreamEventData = {\n  /**\n   * The input passed to the runnable that generated the event.\n   * Inputs will sometimes be available at the *START* of the runnable, and\n   * sometimes at the *END* of the runnable.\n   * If a runnable is able to stream its inputs, then its input by definition\n   * won't be known until the *END* of the runnable when it has finished streaming\n   * its inputs.\n   */\n  input?: unknown;\n  /**\n   * The output of the runnable that generated the event.\n   * Outputs will only be available at the *END* of the runnable.\n   * For most runnables, this field can be inferred from the `chunk` field,\n   * though there might be some exceptions for special cased runnables (e.g., like\n   * chat models), which may return more information.\n   */\n  output?: unknown;\n  /**\n   * A streaming chunk from the output that generated the event.\n   * chunks support addition in general, and adding them up should result\n   * in the output of the runnable that generated the event.\n   */\n  chunk?: StreamChunk;\n  /**\n   * Runnable config for invoking other runnables within handlers.\n   */\n  config?: RunnableConfig;\n  /**\n   * Custom result from the runnable that generated the event.\n   */\n  result?: unknown;\n  /**\n   * Custom field to indicate the event was manually emitted, and may have been handled already\n   */\n  emitted?: boolean;\n};\n\n/**\n * A streaming event.\n *\n * Schema of a streaming event which is produced from the streamEvents method.\n */\nexport type StreamEvent = {\n  /**\n   * Event names are of the format: on_[runnable_type]_(start|stream|end).\n   *\n   * Runnable types are one of:\n   * - llm - used by non chat models\n   * - chat_model - used by chat models\n   * - prompt --  e.g., ChatPromptTemplate\n   * - tool -- LangChain tools\n   * - chain - most Runnables are of this type\n   *\n   * Further, the events are categorized as one of:\n   * - start - when the runnable starts\n   * - stream - when the runnable is streaming\n   * - end - when the runnable ends\n   *\n   * start, stream and end are associated with slightly different `data` payload.\n   *\n   * Please see the documentation for `EventData` for more details.\n   */\n  event: string;\n  /** The name of the runnable that generated the event. */\n  name: string;\n  /**\n   * An randomly generated ID to keep track of the execution of the given runnable.\n   *\n   * Each child runnable that gets invoked as part of the execution of a parent runnable\n   * is assigned its own unique ID.\n   */\n  run_id: string;\n  /**\n   * Tags associated with the runnable that generated this event.\n   * Tags are always inherited from parent runnables.\n   */\n  tags?: string[];\n  /** Metadata associated with the runnable that generated this event. */\n  metadata: Record<string, unknown>;\n  /**\n   * Event data.\n   *\n   * The contents of the event data depend on the event type.\n   */\n  data: StreamEventData;\n};\n\nexport type GraphConfig = {\n  provider: string;\n  thread_id?: string;\n  run_id?: string;\n};\n\nexport type PartMetadata = {\n  progress?: number;\n  asset_pointer?: string;\n  status?: string;\n  action?: boolean;\n  output?: string;\n};\n\nexport type ModelEndData =\n  | (StreamEventData & { output: AIMessageChunk | undefined })\n  | undefined;\nexport type GraphTools = GenericTool[] | BindToolsInput[] | GoogleAIToolType[];\nexport type StandardGraphInput = {\n  runId?: string;\n  signal?: AbortSignal;\n  agents: AgentInputs[];\n  tokenCounter?: TokenCounter;\n  indexTokenCountMap?: Record<string, number>;\n};\n\nexport type GraphEdge = {\n  /** Agent ID, use a list for multiple sources */\n  from: string | string[];\n  /** Agent ID, use a list for multiple destinations */\n  to: string | string[];\n  description?: string;\n  /** Can return boolean or specific destination(s) */\n  condition?: (state: BaseGraphState) => boolean | string | string[];\n  /** EdgeType.HANDOFF creates tools for dynamic routing, EdgeType.DIRECT creates direct edges with parallel execution */\n  edgeType?: import('@/common').EdgeType;\n  /**\n   * For direct edges: Optional prompt to add when transitioning through this edge.\n   * String prompts can include variables like {results} which will be replaced with\n   * messages from startIndex onwards. When {results} is used, excludeResults defaults to true.\n   *\n   * For handoff edges: Description for the input parameter that the handoff tool accepts,\n   * allowing the supervisor to pass specific instructions/context to the transferred agent.\n   */\n  prompt?:\n    | string\n    | ((\n        messages: BaseMessage[],\n        runStartIndex: number\n      ) => string | Promise<string> | undefined);\n  /**\n   * When true, excludes messages from startIndex when adding prompt.\n   * Automatically set to true when {results} variable is used in prompt.\n   */\n  excludeResults?: boolean;\n  /**\n   * For handoff edges: Customizes the parameter name for the handoff input.\n   * Defaults to \"instructions\" if not specified.\n   * Only applies when prompt is provided for handoff edges.\n   */\n  promptKey?: string;\n};\n\nexport type MultiAgentGraphInput = StandardGraphInput & {\n  edges: GraphEdge[];\n};\n\n/**\n * Structured output mode determines how the agent returns structured data.\n * - 'tool': Uses tool calling to return structured output (works with all tool-calling models)\n * - 'provider': Uses provider-native structured output via LangChain's jsonMode (OpenAI, Anthropic, etc.)\n * - 'native': Uses provider's constrained decoding API directly for guaranteed schema compliance\n *   (Anthropic output_config.format, OpenAI response_format.json_schema). Falls back to 'tool' for unsupported providers.\n * - 'auto': Automatically selects the best strategy — 'native' for supported providers, 'tool' for others\n */\nexport type StructuredOutputMode = 'tool' | 'provider' | 'native' | 'auto';\n\n/**\n * Resolved method used internally after mode resolution.\n * Maps to LangChain's withStructuredOutput method parameter plus our native path.\n */\nexport type ResolvedStructuredOutputMethod =\n  | 'functionCalling'\n  | 'jsonMode'\n  | 'jsonSchema'\n  | 'native'\n  | undefined;\n\n/**\n * Error thrown when the model refuses to produce structured output due to safety policies.\n */\nexport class StructuredOutputRefusalError extends Error {\n  constructor(public refusalText: string) {\n    super(`Model refused to produce structured output: ${refusalText}`);\n    this.name = 'StructuredOutputRefusalError';\n  }\n}\n\n/**\n * Error thrown when the structured output response was truncated due to max_tokens.\n */\nexport class StructuredOutputTruncatedError extends Error {\n  constructor(public stopReason: string) {\n    super(\n      `Structured output was truncated (stop_reason: ${stopReason}). ` +\n        'Increase max_tokens to allow the full JSON response to be generated.'\n    );\n    this.name = 'StructuredOutputTruncatedError';\n  }\n}\n\n/**\n * Configuration for structured JSON output from agents.\n * When configured, the agent will return a validated JSON response\n * instead of streaming text.\n */\nexport interface StructuredOutputConfig {\n  /**\n   * JSON Schema defining the output structure.\n   * The model will be forced to return data conforming to this schema.\n   */\n  schema: Record<string, unknown>;\n  /**\n   * Name for the structured output format (used in tool mode).\n   * @default 'StructuredResponse'\n   */\n  name?: string;\n  /**\n   * Description of what the structured output represents.\n   * Helps the model understand the expected format.\n   */\n  description?: string;\n  /**\n   * Output mode strategy.\n   * @default 'auto'\n   */\n  mode?: StructuredOutputMode;\n  /**\n   * Enable strict schema validation.\n   * When true, the response must exactly match the schema.\n   * @default true\n   */\n  strict?: boolean;\n  /**\n   * Error handling configuration.\n   * - true: Auto-retry on validation errors (default)\n   * - false: Throw error on validation failure\n   * - string: Custom error message for retry\n   */\n  handleErrors?: boolean | string;\n  /**\n   * Maximum number of retry attempts on validation failure.\n   * @default 2\n   */\n  maxRetries?: number;\n  /**\n   * Include the raw AI message along with structured response.\n   * Useful for debugging.\n   * @default false\n   */\n  includeRaw?: boolean;\n}\n\n/**\n * Database/API structured output format (snake_case with enabled flag).\n * This matches the format stored in MongoDB and sent from frontends.\n */\nexport interface StructuredOutputInput {\n  /** Whether structured output is enabled */\n  enabled?: boolean;\n  /** JSON Schema defining the expected response structure */\n  schema?: Record<string, unknown>;\n  /** Name identifier for the structured output */\n  name?: string;\n  /** Description of what the structured output represents */\n  description?: string;\n  /** Mode for structured output: 'tool' | 'provider' | 'native' | 'auto' */\n  mode?: StructuredOutputMode;\n  /** Whether to enforce strict schema validation */\n  strict?: boolean;\n}\n\nexport interface AgentInputs {\n  agentId: string;\n  /** Human-readable name for the agent (used in handoff context). Defaults to agentId if not provided. */\n  name?: string;\n  /** Description of what this agent does (used to enrich handoff tool descriptions). */\n  description?: string;\n  toolEnd?: boolean;\n  toolMap?: ToolMap;\n  tools?: GraphTools;\n  provider: Providers;\n  instructions?: string;\n  streamBuffer?: number;\n  maxContextTokens?: number;\n  clientOptions?: ClientOptions;\n  additional_instructions?: string;\n  reasoningKey?: 'reasoning_content' | 'reasoning';\n  /** Format content blocks as strings (for legacy compatibility i.e. Ollama/Azure Serverless) */\n  useLegacyContent?: boolean;\n  /**\n   * Tool definitions for all tools, including deferred and programmatic.\n   * Used for tool search and programmatic tool calling.\n   * Maps tool name to LCTool definition.\n   */\n  toolRegistry?: Map<string, LCTool>;\n  /**\n   * Dynamic context that changes per-request (e.g., current time, user info).\n   * This is injected as a user message rather than system prompt to preserve cache.\n   * Keeping this separate from instructions ensures the system message stays static\n   * and can be cached by Bedrock/Anthropic prompt caching.\n   */\n  dynamicContext?: string;\n  /**\n   * Structured output configuration (camelCase).\n   * When set, disables streaming and returns a validated JSON response\n   * conforming to the specified schema.\n   */\n  structuredOutput?: StructuredOutputConfig;\n  /**\n   * Structured output configuration (snake_case - database/API format).\n   * Alternative to structuredOutput for compatibility with MongoDB/frontend.\n   * Uses an `enabled` flag to control activation.\n   * @deprecated Use structuredOutput instead when possible\n   */\n  structured_output?: StructuredOutputInput;\n  /**\n   * Serializable tool definitions for event-driven execution.\n   * When provided, ToolNode operates in event-driven mode, dispatching\n   * ON_TOOL_EXECUTE events instead of invoking tools directly.\n   */\n  toolDefinitions?: LCTool[];\n  /**\n   * Tool names discovered from previous conversation history.\n   * These tools will be pre-marked as discovered so they're included\n   * in tool binding without requiring tool_search.\n   */\n  discoveredTools?: string[];\n  /**\n   * Optional callback for summarizing messages that were pruned from context.\n   * When provided, discarded messages are summarized by the caller (e.g., Ranger)\n   * using a cheap LLM call, and the summary is prepended to the context.\n   */\n  summarizeCallback?: (\n    messagesToRefine: import('@langchain/core/messages').BaseMessage[]\n  ) => Promise<string | undefined>;\n  /**\n   * Pre-existing summary text loaded from persistent storage (MongoDB/Redis).\n   * When provided, this summary is injected into the initial message context\n   * so the agent has prior conversation history even on new turns.\n   * Set by Ranger's SummaryStore when resuming a conversation.\n   */\n  persistedSummary?: string;\n}\n"],"names":[],"mappings":"AA4YA;;AAEG;AACG,MAAO,4BAA6B,SAAQ,KAAK,CAAA;AAClC,IAAA,WAAA;AAAnB,IAAA,WAAA,CAAmB,WAAmB,EAAA;AACpC,QAAA,KAAK,CAAC,CAAA,4CAAA,EAA+C,WAAW,CAAA,CAAE,CAAC;QADlD,IAAA,CAAA,WAAW,GAAX,WAAW;AAE5B,QAAA,IAAI,CAAC,IAAI,GAAG,8BAA8B;IAC5C;AACD;AAED;;AAEG;AACG,MAAO,8BAA+B,SAAQ,KAAK,CAAA;AACpC,IAAA,UAAA;AAAnB,IAAA,WAAA,CAAmB,UAAkB,EAAA;QACnC,KAAK,CACH,CAAA,8CAAA,EAAiD,UAAU,CAAA,GAAA,CAAK;AAC9D,YAAA,sEAAsE,CACzE;QAJgB,IAAA,CAAA,UAAU,GAAV,UAAU;AAK3B,QAAA,IAAI,CAAC,IAAI,GAAG,gCAAgC;IAC9C;AACD;;;;"}
+{"version":3,"file":"graph.mjs","sources":["../../../src/types/graph.ts"],"sourcesContent":["// src/types/graph.ts\nimport type {\n  START,\n  StateType,\n  UpdateType,\n  StateGraph,\n  StateGraphArgs,\n  StateDefinition,\n  CompiledStateGraph,\n  BinaryOperatorAggregate,\n} from '@langchain/langgraph';\nimport type { BindToolsInput } from '@langchain/core/language_models/chat_models';\nimport type {\n  BaseMessage,\n  AIMessageChunk,\n  SystemMessage,\n} from '@langchain/core/messages';\nimport type { RunnableConfig, Runnable } from '@langchain/core/runnables';\nimport type { ChatGenerationChunk } from '@langchain/core/outputs';\nimport type { GoogleAIToolType } from '@langchain/google-common';\nimport type {\n  ToolMap,\n  ToolEndEvent,\n  GenericTool,\n  LCTool,\n  ToolApprovalConfig,\n} from '@/types/tools';\nimport type { Providers, Callback, GraphNodeKeys } from '@/common';\nimport type { StandardGraph, MultiAgentGraph } from '@/graphs';\nimport type { ClientOptions } from '@/types/llm';\nimport type {\n  RunStep,\n  RunStepDeltaEvent,\n  MessageDeltaEvent,\n  ReasoningDeltaEvent,\n} from '@/types/stream';\nimport type { TokenCounter } from '@/types/run';\n\n/** Interface for bound model with stream and invoke methods */\nexport interface ChatModel {\n  stream?: (\n    messages: BaseMessage[],\n    config?: RunnableConfig\n  ) => Promise<AsyncIterable<AIMessageChunk>>;\n  invoke: (\n    messages: BaseMessage[],\n    config?: RunnableConfig\n  ) => Promise<AIMessageChunk>;\n}\n\nexport type GraphNode = GraphNodeKeys | typeof START;\nexport type ClientCallback<T extends unknown[]> = (\n  graph: StandardGraph,\n  ...args: T\n) => void;\n\nexport type ClientCallbacks = {\n  [Callback.TOOL_ERROR]?: ClientCallback<[Error, string]>;\n  [Callback.TOOL_START]?: ClientCallback<unknown[]>;\n  [Callback.TOOL_END]?: ClientCallback<unknown[]>;\n};\n\nexport type SystemCallbacks = {\n  [K in keyof ClientCallbacks]: ClientCallbacks[K] extends ClientCallback<\n    infer Args\n  >\n    ? (...args: Args) => void\n    : never;\n};\n\nexport type BaseGraphState = {\n  messages: BaseMessage[];\n  /**\n   * Structured response when using structured output mode.\n   * Contains the validated JSON response conforming to the configured schema.\n   */\n  structuredResponse?: Record<string, unknown>;\n};\n\nexport type MultiAgentGraphState = BaseGraphState & {\n  agentMessages?: BaseMessage[];\n};\n\nexport type IState = BaseGraphState;\n\nexport interface EventHandler {\n  handle(\n    event: string,\n    data:\n      | StreamEventData\n      | ModelEndData\n      | RunStep\n      | RunStepDeltaEvent\n      | MessageDeltaEvent\n      | ReasoningDeltaEvent\n      | { result: ToolEndEvent },\n    metadata?: Record<string, unknown>,\n    graph?: StandardGraph | MultiAgentGraph\n  ): void | Promise<void>;\n}\n\nexport type GraphStateChannels<T extends BaseGraphState> =\n  StateGraphArgs<T>['channels'];\n\nexport type Workflow<\n  T extends BaseGraphState = BaseGraphState,\n  U extends Partial<T> = Partial<T>,\n  N extends string = string,\n> = StateGraph<T, U, N>;\n\nexport type CompiledWorkflow<\n  T extends BaseGraphState = BaseGraphState,\n  U extends Partial<T> = Partial<T>,\n  N extends string = string,\n> = CompiledStateGraph<T, U, N>;\n\nexport type CompiledStateWorkflow = CompiledStateGraph<\n  StateType<{\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  }>,\n  UpdateType<{\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  }>,\n  string,\n  {\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  },\n  {\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  },\n  StateDefinition\n>;\n\nexport type CompiledMultiAgentWorkflow = CompiledStateGraph<\n  StateType<{\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n    agentMessages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  }>,\n  UpdateType<{\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n    agentMessages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  }>,\n  string,\n  {\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n    agentMessages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  },\n  {\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n    agentMessages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  },\n  StateDefinition\n>;\n\nexport type CompiledAgentWorfklow = CompiledStateGraph<\n  {\n    messages: BaseMessage[];\n  },\n  {\n    messages?: BaseMessage[] | undefined;\n  },\n  '__start__' | `agent=${string}` | `tools=${string}`,\n  {\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  },\n  {\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  },\n  StateDefinition,\n  {\n    [x: `agent=${string}`]: Partial<BaseGraphState>;\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    [x: `tools=${string}`]: any;\n  }\n>;\n\nexport type SystemRunnable =\n  | Runnable<\n      BaseMessage[],\n      (BaseMessage | SystemMessage)[],\n      RunnableConfig<Record<string, unknown>>\n    >\n  | undefined;\n\n/**\n * Optional compile options passed to workflow.compile().\n * These are intentionally untyped to avoid coupling to library internals.\n */\nexport type CompileOptions = {\n  // A checkpointer instance (e.g., MemorySaver, SQL saver)\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  checkpointer?: any;\n  interruptBefore?: string[];\n  interruptAfter?: string[];\n  /**\n   * Human-in-the-loop tool approval configuration.\n   * When set, tools matching the policy will trigger an interrupt()\n   * before execution, pausing the graph for human approval.\n   * Requires a checkpointer to be set for interrupt/resume to work.\n   */\n  toolApprovalConfig?: ToolApprovalConfig;\n};\n\nexport type EventStreamCallbackHandlerInput =\n  Parameters<CompiledWorkflow['streamEvents']>[2] extends Omit<\n    infer T,\n    'autoClose'\n  >\n    ? T\n    : never;\n\nexport type StreamChunk =\n  | (ChatGenerationChunk & {\n      message: AIMessageChunk;\n    })\n  | AIMessageChunk;\n\n/**\n * Data associated with a StreamEvent.\n */\nexport type StreamEventData = {\n  /**\n   * The input passed to the runnable that generated the event.\n   * Inputs will sometimes be available at the *START* of the runnable, and\n   * sometimes at the *END* of the runnable.\n   * If a runnable is able to stream its inputs, then its input by definition\n   * won't be known until the *END* of the runnable when it has finished streaming\n   * its inputs.\n   */\n  input?: unknown;\n  /**\n   * The output of the runnable that generated the event.\n   * Outputs will only be available at the *END* of the runnable.\n   * For most runnables, this field can be inferred from the `chunk` field,\n   * though there might be some exceptions for special cased runnables (e.g., like\n   * chat models), which may return more information.\n   */\n  output?: unknown;\n  /**\n   * A streaming chunk from the output that generated the event.\n   * chunks support addition in general, and adding them up should result\n   * in the output of the runnable that generated the event.\n   */\n  chunk?: StreamChunk;\n  /**\n   * Runnable config for invoking other runnables within handlers.\n   */\n  config?: RunnableConfig;\n  /**\n   * Custom result from the runnable that generated the event.\n   */\n  result?: unknown;\n  /**\n   * Custom field to indicate the event was manually emitted, and may have been handled already\n   */\n  emitted?: boolean;\n};\n\n/**\n * A streaming event.\n *\n * Schema of a streaming event which is produced from the streamEvents method.\n */\nexport type StreamEvent = {\n  /**\n   * Event names are of the format: on_[runnable_type]_(start|stream|end).\n   *\n   * Runnable types are one of:\n   * - llm - used by non chat models\n   * - chat_model - used by chat models\n   * - prompt --  e.g., ChatPromptTemplate\n   * - tool -- LangChain tools\n   * - chain - most Runnables are of this type\n   *\n   * Further, the events are categorized as one of:\n   * - start - when the runnable starts\n   * - stream - when the runnable is streaming\n   * - end - when the runnable ends\n   *\n   * start, stream and end are associated with slightly different `data` payload.\n   *\n   * Please see the documentation for `EventData` for more details.\n   */\n  event: string;\n  /** The name of the runnable that generated the event. */\n  name: string;\n  /**\n   * An randomly generated ID to keep track of the execution of the given runnable.\n   *\n   * Each child runnable that gets invoked as part of the execution of a parent runnable\n   * is assigned its own unique ID.\n   */\n  run_id: string;\n  /**\n   * Tags associated with the runnable that generated this event.\n   * Tags are always inherited from parent runnables.\n   */\n  tags?: string[];\n  /** Metadata associated with the runnable that generated this event. */\n  metadata: Record<string, unknown>;\n  /**\n   * Event data.\n   *\n   * The contents of the event data depend on the event type.\n   */\n  data: StreamEventData;\n};\n\nexport type GraphConfig = {\n  provider: string;\n  thread_id?: string;\n  run_id?: string;\n};\n\nexport type PartMetadata = {\n  progress?: number;\n  asset_pointer?: string;\n  status?: string;\n  action?: boolean;\n  output?: string;\n};\n\nexport type ModelEndData =\n  | (StreamEventData & { output: AIMessageChunk | undefined })\n  | undefined;\nexport type GraphTools = GenericTool[] | BindToolsInput[] | GoogleAIToolType[];\nexport type StandardGraphInput = {\n  runId?: string;\n  signal?: AbortSignal;\n  agents: AgentInputs[];\n  tokenCounter?: TokenCounter;\n  indexTokenCountMap?: Record<string, number>;\n};\n\nexport type GraphEdge = {\n  /** Agent ID, use a list for multiple sources */\n  from: string | string[];\n  /** Agent ID, use a list for multiple destinations */\n  to: string | string[];\n  description?: string;\n  /** Can return boolean or specific destination(s) */\n  condition?: (state: BaseGraphState) => boolean | string | string[];\n  /** EdgeType.HANDOFF creates tools for dynamic routing, EdgeType.DIRECT creates direct edges with parallel execution */\n  edgeType?: import('@/common').EdgeType;\n  /**\n   * For direct edges: Optional prompt to add when transitioning through this edge.\n   * String prompts can include variables like {results} which will be replaced with\n   * messages from startIndex onwards. When {results} is used, excludeResults defaults to true.\n   *\n   * For handoff edges: Description for the input parameter that the handoff tool accepts,\n   * allowing the supervisor to pass specific instructions/context to the transferred agent.\n   */\n  prompt?:\n    | string\n    | ((\n        messages: BaseMessage[],\n        runStartIndex: number\n      ) => string | Promise<string> | undefined);\n  /**\n   * When true, excludes messages from startIndex when adding prompt.\n   * Automatically set to true when {results} variable is used in prompt.\n   */\n  excludeResults?: boolean;\n  /**\n   * For handoff edges: Customizes the parameter name for the handoff input.\n   * Defaults to \"instructions\" if not specified.\n   * Only applies when prompt is provided for handoff edges.\n   */\n  promptKey?: string;\n};\n\nexport type MultiAgentGraphInput = StandardGraphInput & {\n  edges: GraphEdge[];\n};\n\n/**\n * Structured output mode determines how the agent returns structured data.\n * - 'tool': Uses tool calling to return structured output (works with all tool-calling models)\n * - 'provider': Uses provider-native structured output via LangChain's jsonMode (OpenAI, Anthropic, etc.)\n * - 'native': Uses provider's constrained decoding API directly for guaranteed schema compliance\n *   (Anthropic output_config.format, OpenAI response_format.json_schema). Falls back to 'tool' for unsupported providers.\n * - 'auto': Automatically selects the best strategy — 'native' for supported providers, 'tool' for others\n */\nexport type StructuredOutputMode = 'tool' | 'provider' | 'native' | 'auto';\n\n/**\n * Resolved method used internally after mode resolution.\n * Maps to LangChain's withStructuredOutput method parameter plus our native path.\n */\nexport type ResolvedStructuredOutputMethod =\n  | 'functionCalling'\n  | 'jsonMode'\n  | 'jsonSchema'\n  | 'native'\n  | undefined;\n\n/**\n * Error thrown when the model refuses to produce structured output due to safety policies.\n */\nexport class StructuredOutputRefusalError extends Error {\n  constructor(public refusalText: string) {\n    super(`Model refused to produce structured output: ${refusalText}`);\n    this.name = 'StructuredOutputRefusalError';\n  }\n}\n\n/**\n * Error thrown when the structured output response was truncated due to max_tokens.\n */\nexport class StructuredOutputTruncatedError extends Error {\n  constructor(public stopReason: string) {\n    super(\n      `Structured output was truncated (stop_reason: ${stopReason}). ` +\n        'Increase max_tokens to allow the full JSON response to be generated.'\n    );\n    this.name = 'StructuredOutputTruncatedError';\n  }\n}\n\n/**\n * Configuration for structured JSON output from agents.\n * When configured, the agent will return a validated JSON response\n * instead of streaming text.\n */\nexport interface StructuredOutputConfig {\n  /**\n   * JSON Schema defining the output structure.\n   * The model will be forced to return data conforming to this schema.\n   */\n  schema: Record<string, unknown>;\n  /**\n   * Name for the structured output format (used in tool mode).\n   * @default 'StructuredResponse'\n   */\n  name?: string;\n  /**\n   * Description of what the structured output represents.\n   * Helps the model understand the expected format.\n   */\n  description?: string;\n  /**\n   * Output mode strategy.\n   * @default 'auto'\n   */\n  mode?: StructuredOutputMode;\n  /**\n   * Enable strict schema validation.\n   * When true, the response must exactly match the schema.\n   * @default true\n   */\n  strict?: boolean;\n  /**\n   * Error handling configuration.\n   * - true: Auto-retry on validation errors (default)\n   * - false: Throw error on validation failure\n   * - string: Custom error message for retry\n   */\n  handleErrors?: boolean | string;\n  /**\n   * Maximum number of retry attempts on validation failure.\n   * @default 2\n   */\n  maxRetries?: number;\n  /**\n   * Include the raw AI message along with structured response.\n   * Useful for debugging.\n   * @default false\n   */\n  includeRaw?: boolean;\n}\n\n/**\n * Database/API structured output format (snake_case with enabled flag).\n * This matches the format stored in MongoDB and sent from frontends.\n */\nexport interface StructuredOutputInput {\n  /** Whether structured output is enabled */\n  enabled?: boolean;\n  /** JSON Schema defining the expected response structure */\n  schema?: Record<string, unknown>;\n  /** Name identifier for the structured output */\n  name?: string;\n  /** Description of what the structured output represents */\n  description?: string;\n  /** Mode for structured output: 'tool' | 'provider' | 'native' | 'auto' */\n  mode?: StructuredOutputMode;\n  /** Whether to enforce strict schema validation */\n  strict?: boolean;\n}\n\n/**\n * Trigger strategy for when summarization should activate.\n * - 'contextPercentage': Trigger when context utilization exceeds a threshold percentage\n * - 'messageCount': Trigger when pruned message count exceeds a threshold\n * - 'tokenThreshold': Trigger when total token count exceeds a raw threshold\n */\nexport type SummarizationTriggerType =\n  | 'contextPercentage'\n  | 'messageCount'\n  | 'tokenThreshold';\n\n/**\n * Configuration for summarization behavior within the agent pipeline.\n * All fields are optional — sensible defaults are provided via constants.\n *\n * @see SUMMARIZATION_CONTEXT_THRESHOLD, SUMMARIZATION_RESERVE_RATIO, PRUNING_EMA_ALPHA\n */\nexport interface SummarizationConfig {\n  /**\n   * Strategy for when summarization triggers.\n   * @default 'contextPercentage'\n   */\n  triggerType?: SummarizationTriggerType;\n\n  /**\n   * Threshold value interpreted based on triggerType:\n   * - contextPercentage: 0-100 (percentage of context window)\n   * - messageCount: absolute count of messages pruned\n   * - tokenThreshold: absolute token count\n   * @default 80 (for contextPercentage)\n   */\n  triggerThreshold?: number;\n\n  /**\n   * Fraction of context window (0-1) reserved for recent messages.\n   * Prevents over-pruning by ensuring at least this fraction of the\n   * context budget is preserved as recent conversation history.\n   * @default 0.3\n   */\n  reserveRatio?: number;\n\n  /**\n   * Whether context pruning is enabled (can be disabled for debugging).\n   * @default true\n   */\n  contextPruning?: boolean;\n\n  /**\n   * Initial summary text to seed across runs.\n   * Different from persistedSummary: this is provided by the caller as a\n   * cross-conversation seed (e.g., agent personality or recurring context),\n   * while persistedSummary is loaded from the conversation's own history.\n   */\n  initialSummary?: string;\n}\n\n/**\n * Runtime state for EMA-based pruning calibration.\n * Maintained across iterations within a single run to smooth pruning decisions.\n */\nexport interface PruneCalibrationState {\n  /** Current EMA calibration ratio */\n  ratio: number;\n  /** Number of calibration updates applied */\n  iterations: number;\n}\n\nexport interface AgentInputs {\n  agentId: string;\n  /** Human-readable name for the agent (used in handoff context). Defaults to agentId if not provided. */\n  name?: string;\n  /** Description of what this agent does (used to enrich handoff tool descriptions). */\n  description?: string;\n  toolEnd?: boolean;\n  toolMap?: ToolMap;\n  tools?: GraphTools;\n  provider: Providers;\n  instructions?: string;\n  streamBuffer?: number;\n  maxContextTokens?: number;\n  clientOptions?: ClientOptions;\n  additional_instructions?: string;\n  reasoningKey?: 'reasoning_content' | 'reasoning';\n  /** Format content blocks as strings (for legacy compatibility i.e. Ollama/Azure Serverless) */\n  useLegacyContent?: boolean;\n  /**\n   * Tool definitions for all tools, including deferred and programmatic.\n   * Used for tool search and programmatic tool calling.\n   * Maps tool name to LCTool definition.\n   */\n  toolRegistry?: Map<string, LCTool>;\n  /**\n   * Dynamic context that changes per-request (e.g., current time, user info).\n   * This is injected as a user message rather than system prompt to preserve cache.\n   * Keeping this separate from instructions ensures the system message stays static\n   * and can be cached by Bedrock/Anthropic prompt caching.\n   */\n  dynamicContext?: string;\n  /**\n   * Structured output configuration (camelCase).\n   * When set, disables streaming and returns a validated JSON response\n   * conforming to the specified schema.\n   */\n  structuredOutput?: StructuredOutputConfig;\n  /**\n   * Structured output configuration (snake_case - database/API format).\n   * Alternative to structuredOutput for compatibility with MongoDB/frontend.\n   * Uses an `enabled` flag to control activation.\n   * @deprecated Use structuredOutput instead when possible\n   */\n  structured_output?: StructuredOutputInput;\n  /**\n   * Serializable tool definitions for event-driven execution.\n   * When provided, ToolNode operates in event-driven mode, dispatching\n   * ON_TOOL_EXECUTE events instead of invoking tools directly.\n   */\n  toolDefinitions?: LCTool[];\n  /**\n   * Tool names discovered from previous conversation history.\n   * These tools will be pre-marked as discovered so they're included\n   * in tool binding without requiring tool_search.\n   */\n  discoveredTools?: string[];\n  /**\n   * Optional callback for summarizing messages that were pruned from context.\n   * When provided, discarded messages are summarized by the caller (e.g., Ranger)\n   * using a cheap LLM call, and the summary is prepended to the context.\n   */\n  summarizeCallback?: (\n    messagesToRefine: import('@langchain/core/messages').BaseMessage[]\n  ) => Promise<string | undefined>;\n  /**\n   * Pre-existing summary text loaded from persistent storage (MongoDB/Redis).\n   * When provided, this summary is injected into the initial message context\n   * so the agent has prior conversation history even on new turns.\n   * Set by Ranger's SummaryStore when resuming a conversation.\n   */\n  persistedSummary?: string;\n  /**\n   * Summarization configuration controlling trigger strategy, reserve ratio,\n   * and EMA calibration for pruning. When omitted, sensible defaults apply.\n   * @see SummarizationConfig\n   */\n  summarizationConfig?: SummarizationConfig;\n}\n"],"names":[],"mappings":"AA4YA;;AAEG;AACG,MAAO,4BAA6B,SAAQ,KAAK,CAAA;AAClC,IAAA,WAAA;AAAnB,IAAA,WAAA,CAAmB,WAAmB,EAAA;AACpC,QAAA,KAAK,CAAC,CAAA,4CAAA,EAA+C,WAAW,CAAA,CAAE,CAAC;QADlD,IAAA,CAAA,WAAW,GAAX,WAAW;AAE5B,QAAA,IAAI,CAAC,IAAI,GAAG,8BAA8B;IAC5C;AACD;AAED;;AAEG;AACG,MAAO,8BAA+B,SAAQ,KAAK,CAAA;AACpC,IAAA,UAAA;AAAnB,IAAA,WAAA,CAAmB,UAAkB,EAAA;QACnC,KAAK,CACH,CAAA,8CAAA,EAAiD,UAAU,CAAA,GAAA,CAAK;AAC9D,YAAA,sEAAsE,CACzE;QAJgB,IAAA,CAAA,UAAU,GAAV,UAAU;AAK3B,QAAA,IAAI,CAAC,IAAI,GAAG,gCAAgC;IAC9C;AACD;;;;"}

package/dist/esm/utils/contextPressure.mjs

@@ -0,0 +1,148 @@
+import { MULTI_DOCUMENT_THRESHOLD } from '../common/constants.mjs';
+
+/**
+ * Context Pressure Utilities
+ *
+ * Pure functions for context overflow management. These handle:
+ * 1. Multi-document detection — counting attached documents in messages
+ * 2. Multi-document delegation hint — injected when 3+ documents detected
+ * 3. Post-prune context note — injected after pruning/summarization
+ *
+ * DESIGN PRINCIPLE: The LLM never sees raw token numbers. Context overflow
+ * is handled mechanically by pruning (Graph) + auto-continuation (client.js).
+ * Only task-driven hints (multi-document) are injected — never budget-based.
+ *
+ * @see docs/context-overflow-architecture.md
+ */
+/**
+ * Scan messages for attached documents using known content patterns.
+ *
+ * Detects documents from:
+ * 1. `# "filename"` headers in "Attached document(s):" blocks (text content)
+ * 2. `**filename1, filename2**` in "The user has attached:" blocks (embedded files)
+ *
+ * @param messages - Conversation messages to scan
+ * @returns Document count and names (deduplicated)
+ */
+function detectDocuments(messages) {
+    const documentNames = [];
+    for (const msg of messages) {
+        const content = extractTextContent(msg);
+        // Pattern 1: # "filename" headers in attached document blocks
+        const docMatches = content.match(/# "([^"]+)"/g);
+        if (docMatches) {
+            for (const match of docMatches) {
+                const name = match.replace(/# "/, '').replace(/"$/, '');
+                if (!documentNames.includes(name)) {
+                    documentNames.push(name);
+                }
+            }
+        }
+        // Pattern 2: "The user has attached: **file1, file2**" (embedded files)
+        const attachedMatch = content.match(/user has attached:\s*\*\*([^*]+)\*\*/i);
+        if (attachedMatch) {
+            const names = attachedMatch[1]
+                .split(',')
+                .map((n) => n.trim())
+                .filter(Boolean);
+            for (const name of names) {
+                if (!documentNames.includes(name)) {
+                    documentNames.push(name);
+                }
+            }
+        }
+    }
+    return { count: documentNames.length, names: documentNames };
+}
+/**
+ * Determine whether the multi-document delegation hint should be injected.
+ *
+ * Only fires on the first iteration (before any AI response) when the
+ * document count meets the threshold. This ensures the agent delegates
+ * upfront rather than trying to process all documents itself.
+ *
+ * @param documentCount - Number of detected documents
+ * @param hasAiResponse - Whether the agent has already responded in this chain
+ * @returns Whether to inject the delegation hint
+ */
+function shouldInjectMultiDocHint(documentCount, hasAiResponse) {
+    return documentCount >= MULTI_DOCUMENT_THRESHOLD && !hasAiResponse;
+}
+/**
+ * Build the multi-document delegation hint message content.
+ *
+ * @param documentCount - Number of detected documents
+ * @param documentNames - Names of detected documents
+ * @returns Message content string for injection as HumanMessage
+ */
+function buildMultiDocHintContent(documentCount, documentNames) {
+    return (`[MULTI-DOCUMENT PROCESSING — ${documentCount} documents detected]\n` +
+        `Documents: ${documentNames.join(', ')}\n\n` +
+        `You have ${documentCount} documents attached. For thorough analysis, use the "task" tool ` +
+        'to delegate each document (or group of related documents) to a sub-agent.\n' +
+        'Each sub-agent has its own fresh context window and can use file_search to retrieve the full document content.\n' +
+        'After all sub-agents complete, synthesize their results into a comprehensive response.\n\n' +
+        'This approach ensures each document gets full attention without context limitations.');
+}
+/**
+ * Build the post-prune context note injected after messages are pruned
+ * and summarized. No token numbers — just a contextual signal that
+ * earlier conversation was compressed.
+ *
+ * @param discardedCount - Number of messages that were pruned
+ * @param hasSummary - Whether a summary was successfully generated
+ * @returns Message content string for injection as SystemMessage, or null if no note needed
+ */
+function buildPostPruneNote(discardedCount, hasSummary) {
+    if (discardedCount <= 0) {
+        return null;
+    }
+    if (hasSummary) {
+        return ('[Context Compressed] Earlier conversation messages have been summarized above. ' +
+            'For complex remaining work that requires deep analysis, consider delegating to ' +
+            'sub-agents using the "task" tool — each gets a fresh context window.');
+    }
+    return ('[Context Compressed] Some earlier conversation messages were removed to maintain context capacity. ' +
+        'For complex remaining work, consider delegating to sub-agents using the "task" tool.');
+}
+/**
+ * Check whether a tool named "task" exists in the agent's tool set.
+ *
+ * @param tools - Array of tool objects or structured tools
+ * @returns Whether the task tool is available
+ */
+function hasTaskTool(tools) {
+    if (!tools) {
+        return false;
+    }
+    return tools.some((tool) => {
+        const toolName = typeof tool === 'object' && tool !== null && 'name' in tool
+            ? tool.name
+            : '';
+        return toolName === 'task';
+    });
+}
+/**
+ * Extract text content from a BaseMessage, handling both string and
+ * array content formats.
+ *
+ * @param msg - A LangChain BaseMessage
+ * @returns Flattened text content
+ */
+function extractTextContent(msg) {
+    if (typeof msg.content === 'string') {
+        return msg.content;
+    }
+    if (Array.isArray(msg.content)) {
+        return msg.content
+            .map((p) => {
+            const part = p;
+            return String(part.text ?? part.content ?? '');
+        })
+            .join(' ');
+    }
+    return '';
+}
+
+export { buildMultiDocHintContent, buildPostPruneNote, detectDocuments, hasTaskTool, shouldInjectMultiDocHint };
+//# sourceMappingURL=contextPressure.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"contextPressure.mjs","sources":["../../../src/utils/contextPressure.ts"],"sourcesContent":["/**\n * Context Pressure Utilities\n *\n * Pure functions for context overflow management. These handle:\n * 1. Multi-document detection — counting attached documents in messages\n * 2. Multi-document delegation hint — injected when 3+ documents detected\n * 3. Post-prune context note — injected after pruning/summarization\n *\n * DESIGN PRINCIPLE: The LLM never sees raw token numbers. Context overflow\n * is handled mechanically by pruning (Graph) + auto-continuation (client.js).\n * Only task-driven hints (multi-document) are injected — never budget-based.\n *\n * @see docs/context-overflow-architecture.md\n */\n\nimport type { BaseMessage } from '@langchain/core/messages';\nimport { MULTI_DOCUMENT_THRESHOLD } from '@/common/constants';\n\n/** Result of scanning messages for attached documents */\nexport interface DocumentDetectionResult {\n  /** Total unique documents detected */\n  count: number;\n  /** Names of detected documents */\n  names: string[];\n}\n\n/**\n * Scan messages for attached documents using known content patterns.\n *\n * Detects documents from:\n * 1. `# \"filename\"` headers in \"Attached document(s):\" blocks (text content)\n * 2. `**filename1, filename2**` in \"The user has attached:\" blocks (embedded files)\n *\n * @param messages - Conversation messages to scan\n * @returns Document count and names (deduplicated)\n */\nexport function detectDocuments(\n  messages: BaseMessage[]\n): DocumentDetectionResult {\n  const documentNames: string[] = [];\n\n  for (const msg of messages) {\n    const content = extractTextContent(msg);\n\n    // Pattern 1: # \"filename\" headers in attached document blocks\n    const docMatches = content.match(/# \"([^\"]+)\"/g);\n    if (docMatches) {\n      for (const match of docMatches) {\n        const name = match.replace(/# \"/, '').replace(/\"$/, '');\n        if (!documentNames.includes(name)) {\n          documentNames.push(name);\n        }\n      }\n    }\n\n    // Pattern 2: \"The user has attached: **file1, file2**\" (embedded files)\n    const attachedMatch = content.match(\n      /user has attached:\\s*\\*\\*([^*]+)\\*\\*/i\n    );\n    if (attachedMatch) {\n      const names = attachedMatch[1]\n        .split(',')\n        .map((n: string) => n.trim())\n        .filter(Boolean);\n      for (const name of names) {\n        if (!documentNames.includes(name)) {\n          documentNames.push(name);\n        }\n      }\n    }\n  }\n\n  return { count: documentNames.length, names: documentNames };\n}\n\n/**\n * Determine whether the multi-document delegation hint should be injected.\n *\n * Only fires on the first iteration (before any AI response) when the\n * document count meets the threshold. This ensures the agent delegates\n * upfront rather than trying to process all documents itself.\n *\n * @param documentCount - Number of detected documents\n * @param hasAiResponse - Whether the agent has already responded in this chain\n * @returns Whether to inject the delegation hint\n */\nexport function shouldInjectMultiDocHint(\n  documentCount: number,\n  hasAiResponse: boolean\n): boolean {\n  return documentCount >= MULTI_DOCUMENT_THRESHOLD && !hasAiResponse;\n}\n\n/**\n * Build the multi-document delegation hint message content.\n *\n * @param documentCount - Number of detected documents\n * @param documentNames - Names of detected documents\n * @returns Message content string for injection as HumanMessage\n */\nexport function buildMultiDocHintContent(\n  documentCount: number,\n  documentNames: string[]\n): string {\n  return (\n    `[MULTI-DOCUMENT PROCESSING — ${documentCount} documents detected]\\n` +\n    `Documents: ${documentNames.join(', ')}\\n\\n` +\n    `You have ${documentCount} documents attached. For thorough analysis, use the \"task\" tool ` +\n    'to delegate each document (or group of related documents) to a sub-agent.\\n' +\n    'Each sub-agent has its own fresh context window and can use file_search to retrieve the full document content.\\n' +\n    'After all sub-agents complete, synthesize their results into a comprehensive response.\\n\\n' +\n    'This approach ensures each document gets full attention without context limitations.'\n  );\n}\n\n/**\n * Build the post-prune context note injected after messages are pruned\n * and summarized. No token numbers — just a contextual signal that\n * earlier conversation was compressed.\n *\n * @param discardedCount - Number of messages that were pruned\n * @param hasSummary - Whether a summary was successfully generated\n * @returns Message content string for injection as SystemMessage, or null if no note needed\n */\nexport function buildPostPruneNote(\n  discardedCount: number,\n  hasSummary: boolean\n): string | null {\n  if (discardedCount <= 0) {\n    return null;\n  }\n\n  if (hasSummary) {\n    return (\n      '[Context Compressed] Earlier conversation messages have been summarized above. ' +\n      'For complex remaining work that requires deep analysis, consider delegating to ' +\n      'sub-agents using the \"task\" tool — each gets a fresh context window.'\n    );\n  }\n\n  return (\n    '[Context Compressed] Some earlier conversation messages were removed to maintain context capacity. ' +\n    'For complex remaining work, consider delegating to sub-agents using the \"task\" tool.'\n  );\n}\n\n/**\n * Check whether a tool named \"task\" exists in the agent's tool set.\n *\n * @param tools - Array of tool objects or structured tools\n * @returns Whether the task tool is available\n */\nexport function hasTaskTool(\n  tools: Array<{ name?: string } | unknown> | undefined\n): boolean {\n  if (!tools) {\n    return false;\n  }\n  return tools.some((tool) => {\n    const toolName =\n      typeof tool === 'object' && tool !== null && 'name' in tool\n        ? (tool as { name: string }).name\n        : '';\n    return toolName === 'task';\n  });\n}\n\n/**\n * Extract text content from a BaseMessage, handling both string and\n * array content formats.\n *\n * @param msg - A LangChain BaseMessage\n * @returns Flattened text content\n */\nfunction extractTextContent(msg: BaseMessage): string {\n  if (typeof msg.content === 'string') {\n    return msg.content;\n  }\n  if (Array.isArray(msg.content)) {\n    return msg.content\n      .map((p: unknown) => {\n        const part = p as Record<string, unknown>;\n        return String(part.text ?? part.content ?? '');\n      })\n      .join(' ');\n  }\n  return '';\n}\n"],"names":[],"mappings":"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"}