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

package/dist/types/messages/prune.d.ts

@@ -1,6 +1,7 @@
 import { BaseMessage, UsageMetadata } from '@langchain/core/messages';
 import type { TokenCounter } from '@/types/run';
 import { ContentTypes, Providers } from '@/common';
+import type { ContextPruningConfig } from '@/types/graph';
 export type PruneMessagesFactoryParams = {
     provider?: Providers;
     maxTokens: number;
@@ -8,6 +9,15 @@ export type PruneMessagesFactoryParams = {
     tokenCounter: TokenCounter;
     indexTokenCountMap: Record<string, number | undefined>;
     thinkingEnabled?: boolean;
+    /**
+     * Optional position-based content degradation config. When `enabled: true`,
+     * tool result messages outside the protected zone (system + last N assistant
+     * turns + image content) are soft-trimmed (head + tail) once their
+     * position-age exceeds `softTrimRatio`, then hard-cleared with a placeholder
+     * once age exceeds `hardClearRatio`. Defaults disabled to preserve existing
+     * behavior — opt in per deployment.
+     */
+    contextPruningConfig?: ContextPruningConfig;
 };
 export type PruneMessagesParams = {
     messages: BaseMessage[];
@@ -27,7 +37,7 @@ export type PruningResult = {
     messagesToRefine: BaseMessage[];
     thinkingStartIndex?: number;
 };
-export declare function getMessagesWithinTokenLimit({ messages: _messages, maxContextTokens, indexTokenCountMap, startType: _startType, thinkingEnabled, tokenCounter, thinkingStartIndex: _thinkingStartIndex, reasoningType, }: {
+export declare function getMessagesWithinTokenLimit({ messages: _messages, maxContextTokens, indexTokenCountMap, startType: _startType, thinkingEnabled, tokenCounter, thinkingStartIndex: _thinkingStartIndex, reasoningType, instructionTokens: _instructionTokens, }: {
     messages: BaseMessage[];
     maxContextTokens: number;
     indexTokenCountMap: Record<string, number | undefined>;
@@ -36,12 +46,92 @@ export declare function getMessagesWithinTokenLimit({ messages: _messages, maxCo
     tokenCounter: TokenCounter;
     thinkingStartIndex?: number;
     reasoningType?: ContentTypes.THINKING | ContentTypes.REASONING_CONTENT;
+    /**
+     * Token overhead for instructions (system message + tool schemas + summary)
+     * that are NOT included in `messages`. When messages[0] is already a
+     * SystemMessage the budget is deducted from its indexTokenCountMap entry
+     * as before; otherwise this value is subtracted from the available budget.
+     */
+    instructionTokens?: number;
 }): PruningResult;
 export declare function checkValidNumber(value: unknown): value is number;
+/**
+ * Repairs orphan tool messages in a pruned context. Drops `ToolMessage`s whose
+ * matching `AIMessage` was pruned, and strips orphan `tool_use` content blocks
+ * (and `tool_calls` entries) from `AIMessage`s whose corresponding tool results
+ * are missing. Without this, Anthropic / Bedrock / OpenAI reject the request
+ * with a structural validation 400.
+ *
+ * Intended to run on the post-prune `context` array (not the pre-prune
+ * `allMessages`). The dropped messages are returned so the caller can append
+ * them to `messagesToRefine` for summarization fidelity.
+ */
+export declare function repairOrphanedToolMessages({ context, allMessages, tokenCounter, indexTokenCountMap, }: {
+    context: BaseMessage[];
+    allMessages: BaseMessage[];
+    tokenCounter: TokenCounter;
+    indexTokenCountMap: Record<string, number | undefined>;
+}): {
+    context: BaseMessage[];
+    reclaimedTokens: number;
+    droppedOrphanCount: number;
+    /** Messages removed from context during orphan repair.  These should be
+     *  appended to `messagesToRefine` so that summarization can still see them
+     *  (e.g. a ToolMessage whose parent AI was pruned). */
+    droppedMessages: BaseMessage[];
+};
+/**
+ * Lightweight structural cleanup: strips orphan tool_use blocks from AI messages
+ * and drops orphan ToolMessages whose AI counterpart is missing.
+ *
+ * Unlike `repairOrphanedToolMessages`, this does NOT track tokens — it is
+ * intended as a final safety net right before model invocation to prevent
+ * Anthropic / Bedrock structural validation errors.
+ *
+ * Uses duck-typing instead of `getType()` because messages at this stage
+ * may be plain objects (from LangGraph state serialization) rather than
+ * proper BaseMessage class instances.
+ *
+ * Includes a fast-path: if every tool_call has a matching tool_result and
+ * vice-versa, the original array is returned immediately with zero allocation.
+ */
+export declare function sanitizeOrphanToolBlocks(messages: BaseMessage[]): BaseMessage[];
+/**
+ * Pre-flight truncation: truncates oversized tool result string content before
+ * the budget walker runs. Older results get smaller budgets (recency factor),
+ * with a 200-char floor so even ancient entries keep diagnostic signal. Returns
+ * the number of ToolMessages truncated.
+ */
+export declare function preFlightTruncateToolResults(params: {
+    messages: BaseMessage[];
+    maxContextTokens: number;
+    indexTokenCountMap: Record<string, number | undefined>;
+    tokenCounter: TokenCounter;
+}): number;
+/**
+ * Pre-flight truncation: truncates oversized `tool_use` input fields in AI messages.
+ *
+ * Tool call inputs (arguments) can be very large — e.g., code evaluation payloads from
+ * MCP tools like chrome-devtools. Since these tool calls have already been executed,
+ * the model only needs a summary of what was called, not the full arguments. Truncating
+ * them before pruning can prevent entire messages from being dropped.
+ *
+ * Uses 15% of the context window (in estimated characters, ~4 chars/token) as the
+ * per-input cap, capped at 200K chars.
+ *
+ * @returns The number of AI messages that had tool_use inputs truncated.
+ */
+export declare function preFlightTruncateToolCallInputs(params: {
+    messages: BaseMessage[];
+    maxContextTokens: number;
+    indexTokenCountMap: Record<string, number | undefined>;
+    tokenCounter: TokenCounter;
+}): number;
 export declare function createPruneMessages(factoryParams: PruneMessagesFactoryParams): (params: PruneMessagesParams) => {
     context: BaseMessage[];
     indexTokenCountMap: Record<string, number | undefined>;
     messagesToRefine: BaseMessage[];
+    originalToolContent?: Map<number, string>;
 };
 /** Calculates context utilization as a percentage (0-100) */
 export declare function getContextUtilization(indexTokenCountMap: Record<string, number | undefined>, instructionTokens: number, maxContextTokens: number): number;

package/dist/types/run.d.ts

@@ -10,6 +10,8 @@ export declare class Run<_T extends t.BaseGraphState> {
     id: string;
     private tokenCounter?;
     private handlerRegistry?;
+    private hookRegistry?;
+    private toolOutputRegistry?;
     private indexTokenCountMap?;
     graphRunnable?: t.CompiledStateWorkflow;
     Graph: StandardGraph | MultiAgentGraph | undefined;

package/dist/types/tools/BashExecutor.d.ts

@@ -0,0 +1,76 @@
+import { DynamicStructuredTool } from '@langchain/core/tools';
+import type * as t from '@/types';
+import { Constants } from '@/common';
+export declare const BashExecutionToolSchema: {
+    readonly type: "object";
+    readonly properties: {
+        readonly command: {
+            readonly type: "string";
+            readonly description: "The bash command or script to execute.\n- The environment is stateless; variables and state 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- Use `echo`, `printf`, or `cat` for all outputs.";
+        };
+        readonly args: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+            readonly description: "Additional arguments to execute the command with. This should only be used if the input command requires additional arguments to run.";
+        };
+    };
+    readonly required: readonly ["command"];
+};
+export declare const BashExecutionToolDescription: string;
+/**
+ * Supplemental prompt documenting the tool-output reference feature.
+ *
+ * Hosts should append this (separated by a blank line) to the base
+ * {@link BashExecutionToolDescription} only when
+ * `RunConfig.toolOutputReferences.enabled` is `true`. When the feature
+ * is disabled, including this text would tell the LLM to emit
+ * `{{tool0turn0}}` placeholders that pass through unsubstituted and
+ * leak into the shell.
+ */
+export declare const BashToolOutputReferencesGuide: string;
+/**
+ * Composes the bash tool description, optionally appending the
+ * tool-output references guide. Hosts that enable
+ * `RunConfig.toolOutputReferences` should pass `enableToolOutputReferences: true`
+ * when registering the tool so the LLM learns the `{{…}}` syntax it
+ * will actually be able to use.
+ */
+export declare function buildBashExecutionToolDescription(options?: {
+    enableToolOutputReferences?: boolean;
+}): string;
+export declare const BashExecutionToolName = Constants.BASH_TOOL;
+/**
+ * Default bash tool definition using the base description.
+ *
+ * When `RunConfig.toolOutputReferences.enabled` is `true`, build a
+ * reference-aware description with
+ * {@link buildBashExecutionToolDescription}
+ * (`{ enableToolOutputReferences: true }`) and construct a custom
+ * definition using it — using this constant as-is leaves the LLM
+ * unaware of the `{{tool<i>turn<n>}}` syntax.
+ */
+export declare const BashExecutionToolDefinition: {
+    readonly name: Constants.BASH_TOOL;
+    readonly description: string;
+    readonly schema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly command: {
+                readonly type: "string";
+                readonly description: "The bash command or script to execute.\n- The environment is stateless; variables and state 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- Use `echo`, `printf`, or `cat` for all outputs.";
+            };
+            readonly args: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+                readonly description: "Additional arguments to execute the command with. This should only be used if the input command requires additional arguments to run.";
+            };
+        };
+        readonly required: readonly ["command"];
+    };
+};
+declare function createBashExecutionTool(params?: t.BashExecutionToolParams): DynamicStructuredTool;
+export { createBashExecutionTool };

package/dist/types/tools/BashProgrammaticToolCalling.d.ts

@@ -0,0 +1,72 @@
+import { DynamicStructuredTool } from '@langchain/core/tools';
+import type * as t from '@/types';
+import { Constants } from '@/common';
+export declare const BashProgrammaticToolCallingSchema: {
+    readonly type: "object";
+    readonly properties: {
+        readonly code: {
+            readonly type: "string";
+            readonly minLength: 1;
+            readonly description: "Bash code that calls tools programmatically. Tools are available as bash functions.\n\nCRITICAL - STATELESS EXECUTION:\nEach call is a fresh bash shell. Variables and state do NOT persist between calls.\nYou MUST complete your entire workflow in ONE code block.\nDO NOT split work across multiple calls expecting to reuse variables.\n\nEach tool function accepts a JSON string as its argument.\nExample: tool_name '{\"key\": \"value\"}'\n\nExample (Complete workflow in one call):\n  # Query data and process\n  data=$(query_database '{\"sql\": \"SELECT * FROM users\"}')\n  echo \"$data\" | jq '.[] | .name'\n\nExample (Parallel calls):\n  web_search '{\"query\": \"SF weather\"}' > /tmp/sf.txt &\n  web_search '{\"query\": \"NY weather\"}' > /tmp/ny.txt &\n  wait\n  echo \"SF: $(cat /tmp/sf.txt)\"\n  echo \"NY: $(cat /tmp/ny.txt)\"\n\nRules:\n- EVERYTHING in one call—no state persists between executions\n- Tools are pre-defined as bash functions—DO NOT redefine them\n- Each tool function accepts a JSON string argument\n- Only echo/printf output returns to the model\n- Generated files are automatically available in /mnt/data/ for subsequent executions";
+        };
+        readonly timeout: {
+            readonly type: "integer";
+            readonly minimum: 1000;
+            readonly maximum: 300000;
+            readonly default: 60000;
+            readonly description: "Maximum execution time in milliseconds. Default: 60 seconds. Max: 5 minutes.";
+        };
+    };
+    readonly required: readonly ["code"];
+};
+export declare const BashProgrammaticToolCallingName = Constants.BASH_PROGRAMMATIC_TOOL_CALLING;
+export declare const BashProgrammaticToolCallingDescription: string;
+export declare const BashProgrammaticToolCallingDefinition: {
+    readonly name: Constants.BASH_PROGRAMMATIC_TOOL_CALLING;
+    readonly description: string;
+    readonly schema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly code: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly description: "Bash code that calls tools programmatically. Tools are available as bash functions.\n\nCRITICAL - STATELESS EXECUTION:\nEach call is a fresh bash shell. Variables and state do NOT persist between calls.\nYou MUST complete your entire workflow in ONE code block.\nDO NOT split work across multiple calls expecting to reuse variables.\n\nEach tool function accepts a JSON string as its argument.\nExample: tool_name '{\"key\": \"value\"}'\n\nExample (Complete workflow in one call):\n  # Query data and process\n  data=$(query_database '{\"sql\": \"SELECT * FROM users\"}')\n  echo \"$data\" | jq '.[] | .name'\n\nExample (Parallel calls):\n  web_search '{\"query\": \"SF weather\"}' > /tmp/sf.txt &\n  web_search '{\"query\": \"NY weather\"}' > /tmp/ny.txt &\n  wait\n  echo \"SF: $(cat /tmp/sf.txt)\"\n  echo \"NY: $(cat /tmp/ny.txt)\"\n\nRules:\n- EVERYTHING in one call—no state persists between executions\n- Tools are pre-defined as bash functions—DO NOT redefine them\n- Each tool function accepts a JSON string argument\n- Only echo/printf output returns to the model\n- Generated files are automatically available in /mnt/data/ for subsequent executions";
+            };
+            readonly timeout: {
+                readonly type: "integer";
+                readonly minimum: 1000;
+                readonly maximum: 300000;
+                readonly default: 60000;
+                readonly description: "Maximum execution time in milliseconds. Default: 60 seconds. Max: 5 minutes.";
+            };
+        };
+        readonly required: readonly ["code"];
+    };
+};
+/**
+ * Normalizes a tool name to a valid bash function identifier.
+ * 1. Replace hyphens, spaces, dots with underscores
+ * 2. Remove any other invalid characters
+ * 3. Prefix with underscore if starts with number
+ * 4. Append `_tool` if it's a bash reserved word
+ */
+export declare function normalizeToBashIdentifier(name: string): string;
+/**
+ * Extracts tool names that are actually called in the bash code.
+ * Bash functions are invoked as commands (no parentheses), so we match
+ * the normalized name as a word boundary.
+ */
+export declare function extractUsedBashToolNames(code: string, toolNameMap: Map<string, string>): Set<string>;
+/**
+ * Filters tool definitions to only include tools actually used in the bash code.
+ */
+export declare function filterBashToolsByUsage(toolDefs: t.LCTool[], code: string, debug?: boolean): t.LCTool[];
+/**
+ * Creates a Bash Programmatic Tool Calling tool for multi-tool orchestration.
+ *
+ * This tool enables AI agents to write bash scripts that orchestrate multiple
+ * tool calls programmatically via the remote Code API, reducing LLM round-trips.
+ *
+ * The tool map must be provided at runtime via config.toolCall (injected by ToolNode).
+ */
+export declare function createBashProgrammaticToolCallingTool(initParams?: t.BashProgrammaticToolCallingParams): DynamicStructuredTool;

package/dist/types/tools/CodeExecutor.d.ts

@@ -3,6 +3,12 @@ import type * as t from '@/types';
 import { Constants } from '@/common';
 export declare const imageExtRegex: RegExp;
 export declare const getCodeBaseURL: () => string;
+/**
+ * Renders one section of the post-execution file listing. Used by the
+ * code/bash tool formatters to keep generated outputs and inherited
+ * inputs visually separated. See BashExecutor for full docs.
+ */
+export declare function renderFileSection(header: string, files: t.FileRefs, defaultMessage: string): string;
 export declare const CodeExecutionToolSchema: {
     readonly type: "object";
     readonly properties: {
@@ -22,20 +28,8 @@ export declare const CodeExecutionToolSchema: {
             };
             readonly description: "Additional arguments to execute the code with. This should only be used if the input code requires additional arguments to run.";
         };
-        readonly code_id: {
-            readonly type: "string";
-            readonly description: "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.";
-        };
-        readonly old_str: {
-            readonly type: "string";
-            readonly description: "Exact string to find in stored code (requires code_id). Copy verbatim from the code you wrote.";
-        };
-        readonly new_str: {
-            readonly type: "string";
-            readonly description: "Replacement string (requires code_id and old_str). The matched old_str will be replaced with this value.";
-        };
     };
-    readonly required: readonly ["lang"];
+    readonly required: readonly [];
 };
 export declare const CodeExecutionToolDescription: string;
 export declare const CodeExecutionToolName = Constants.EXECUTE_CODE;
@@ -61,20 +55,8 @@ export declare const CodeExecutionToolDefinition: {
                 };
                 readonly description: "Additional arguments to execute the code with. This should only be used if the input code requires additional arguments to run.";
             };
-            readonly code_id: {
-                readonly type: "string";
-                readonly description: "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.";
-            };
-            readonly old_str: {
-                readonly type: "string";
-                readonly description: "Exact string to find in stored code (requires code_id). Copy verbatim from the code you wrote.";
-            };
-            readonly new_str: {
-                readonly type: "string";
-                readonly description: "Replacement string (requires code_id and old_str). The matched old_str will be replaced with this value.";
-            };
         };
-        readonly required: readonly ["lang"];
+        readonly required: readonly [];
     };
 };
 declare function createCodeExecutionTool(params?: t.CodeExecutionToolParams): DynamicStructuredTool;

package/dist/types/tools/ReadFile.d.ts

@@ -0,0 +1,28 @@
+import { Constants } from '@/common';
+export declare const ReadFileToolName = Constants.READ_FILE;
+export declare const ReadFileToolDescription = "Read the contents of a file. Returns text content with line numbers for easy reference.\n\nFor skill files, use the path format: {skillName}/{filePath} (e.g. \"pdf-analyzer/src/utils.py\", \"code-review/SKILL.md\").\n\nBEHAVIOR:\n- Text files: returned with numbered lines.\n- Images (png, jpeg, gif, webp): returned as visual content the model can see.\n- PDFs: returned as document content.\n- Other binary files: metadata returned with a note to use bash for processing.\n- Large files (>256KB text, >10MB binary): metadata only.\n- SKILL.md: returns the skill's instructions directly.\n\nCONSTRAINTS:\n- Only files from invoked skills or code execution output are accessible.\n- Do not guess file paths. Use paths from the skill documentation or tool output.";
+export declare const ReadFileToolSchema: {
+    readonly type: "object";
+    readonly properties: {
+        readonly file_path: {
+            readonly type: "string";
+            readonly description: "Path to the file. For skill files: \"{skillName}/{path}\" (e.g. \"pdf-analyzer/src/utils.py\"). For code execution output: the path as returned by the execution tool.";
+        };
+    };
+    readonly required: readonly ["file_path"];
+};
+export declare const ReadFileToolDefinition: {
+    readonly name: Constants.READ_FILE;
+    readonly description: "Read the contents of a file. Returns text content with line numbers for easy reference.\n\nFor skill files, use the path format: {skillName}/{filePath} (e.g. \"pdf-analyzer/src/utils.py\", \"code-review/SKILL.md\").\n\nBEHAVIOR:\n- Text files: returned with numbered lines.\n- Images (png, jpeg, gif, webp): returned as visual content the model can see.\n- PDFs: returned as document content.\n- Other binary files: metadata returned with a note to use bash for processing.\n- Large files (>256KB text, >10MB binary): metadata only.\n- SKILL.md: returns the skill's instructions directly.\n\nCONSTRAINTS:\n- Only files from invoked skills or code execution output are accessible.\n- Do not guess file paths. Use paths from the skill documentation or tool output.";
+    readonly parameters: {
+        readonly type: "object";
+        readonly properties: {
+            readonly file_path: {
+                readonly type: "string";
+                readonly description: "Path to the file. For skill files: \"{skillName}/{path}\" (e.g. \"pdf-analyzer/src/utils.py\"). For code execution output: the path as returned by the execution tool.";
+            };
+        };
+        readonly required: readonly ["file_path"];
+    };
+    readonly responseFormat: "content_and_artifact";
+};

package/dist/types/tools/SkillTool.d.ts

@@ -0,0 +1,40 @@
+import { Constants } from '@/common';
+export declare const SkillToolName = Constants.SKILL_TOOL;
+export declare const SkillToolDescription = "Invoke a skill from the user's library. Skills provide domain-specific instructions loaded into the conversation context, and may also provide files accessible via available tools depending on the runtime environment.\n\nWHEN TO USE:\n- The user's request matches a skill listed in the \"Available Skills\" section of the system prompt.\n- You MUST invoke the matching skill BEFORE attempting the task yourself.\n\nWHAT HAPPENS:\n- The skill's full instructions are loaded into the conversation as context.\n- Files bundled with the skill may become accessible via available tools.\n- Follow the skill's instructions to complete the task.\n\nCONSTRAINTS:\n- Do not invoke a skill that is already active in this conversation.\n- Skill names come from the catalog only. Do not guess names.";
+/**
+ * JSON Schema for the SkillTool parameters.
+ * Single source of truth used by both SkillToolDefinition (LCTool registry)
+ * and createSkillTool() (DynamicStructuredTool instance).
+ */
+export declare const SkillToolSchema: {
+    readonly type: "object";
+    readonly properties: {
+        readonly skillName: {
+            readonly type: "string";
+            readonly description: "The kebab-case identifier of the skill to invoke (e.g. \"financial-analyzer\", \"meeting-notes\"). Must match a name from the \"Available Skills\" section.";
+        };
+        readonly args: {
+            readonly type: "string";
+            readonly description: "Optional freeform arguments string passed to the skill.";
+        };
+    };
+    readonly required: readonly ["skillName"];
+};
+export declare const SkillToolDefinition: {
+    readonly name: Constants.SKILL_TOOL;
+    readonly description: "Invoke a skill from the user's library. Skills provide domain-specific instructions loaded into the conversation context, and may also provide files accessible via available tools depending on the runtime environment.\n\nWHEN TO USE:\n- The user's request matches a skill listed in the \"Available Skills\" section of the system prompt.\n- You MUST invoke the matching skill BEFORE attempting the task yourself.\n\nWHAT HAPPENS:\n- The skill's full instructions are loaded into the conversation as context.\n- Files bundled with the skill may become accessible via available tools.\n- Follow the skill's instructions to complete the task.\n\nCONSTRAINTS:\n- Do not invoke a skill that is already active in this conversation.\n- Skill names come from the catalog only. Do not guess names.";
+    readonly parameters: {
+        readonly type: "object";
+        readonly properties: {
+            readonly skillName: {
+                readonly type: "string";
+                readonly description: "The kebab-case identifier of the skill to invoke (e.g. \"financial-analyzer\", \"meeting-notes\"). Must match a name from the \"Available Skills\" section.";
+            };
+            readonly args: {
+                readonly type: "string";
+                readonly description: "Optional freeform arguments string passed to the skill.";
+            };
+        };
+        readonly required: readonly ["skillName"];
+    };
+};

package/dist/types/tools/SubagentTool.d.ts

@@ -0,0 +1,36 @@
+import { Constants } from '@/common';
+import type { SubagentConfig } from '@/types';
+import type { JsonSchemaType, LCTool } from '@/types/tools';
+export declare const SubagentToolName = Constants.SUBAGENT;
+export declare const SubagentToolDescription = "Delegate a task to a specialized subagent that runs in an isolated context window. The subagent executes independently and returns only its final text result \u2014 all intermediate tool calls, reasoning, and context stay isolated.\n\nWHEN TO USE:\n- The task is self-contained and can be described in a single prompt.\n- You want to offload verbose or exploratory work without bloating your own context.\n- A specialized subagent is available for the task domain.\n\nWHAT HAPPENS:\n- A fresh agent is created with the task description as its only input.\n- The subagent runs to completion using its own tools and context.\n- Only the final text response is returned to you.\n\nCONSTRAINTS:\n- subagent_type must match one of the available types listed below.\n- The subagent cannot see your conversation history.";
+export declare const SubagentToolSchema: {
+    readonly type: "object";
+    readonly properties: {
+        readonly description: {
+            readonly type: "string";
+            readonly description: "Complete task description for the subagent. This is the ONLY information it receives — include all necessary context, requirements, and constraints.";
+        };
+        readonly subagent_type: {
+            readonly type: "string";
+            readonly description: "Which subagent type to delegate to. Must be one of the available types.";
+        };
+    };
+    readonly required: string[];
+};
+export declare const SubagentToolDefinition: LCTool;
+/**
+ * Build the name, schema, and description params for `tool()` from available configs.
+ * Used by `Graph.createAgentNode()` when constructing the runtime tool instance.
+ * Extends `SubagentToolSchema` by populating `subagent_type.enum` dynamically.
+ */
+export declare function buildSubagentToolParams(configs: SubagentConfig[]): {
+    name: string;
+    schema: JsonSchemaType;
+    description: string;
+};
+/**
+ * Create a SubagentTool LCTool definition with dynamic enum and description
+ * populated from the available subagent configs.
+ * Used for the tool registry in event-driven mode.
+ */
+export declare function createSubagentToolDefinition(configs: SubagentConfig[]): LCTool;

package/dist/types/tools/ToolNode.d.ts

@@ -4,6 +4,23 @@ import type { RunnableConfig } from '@langchain/core/runnables';
 import type { BaseMessage } from '@langchain/core/messages';
 import type * as t from '@/types';
 import { RunnableCallable } from '@/utils';
+import { ToolOutputReferenceRegistry } from '@/tools/toolOutputReferences';
+import type { ResolvedArgsByCallId } from '@/tools/toolOutputReferences';
+/**
+ * Per-call batch context for `runTool`. Bundles every optional batch-scoped
+ * value the method needs so the signature stays at three positional params
+ * even as new context fields are added. Upstream-aligned (PR #117).
+ */
+type RunToolBatchContext = {
+    /** Position of this call within the parent ToolNode batch. */
+    batchIndex?: number;
+    /** Batch turn shared across every call in the batch. */
+    turn?: number;
+    /** Registry partition scope (run id or anonymous batch id). */
+    batchScopeId?: string;
+    /** Batch-local sink for post-substitution args. */
+    resolvedArgsByCallId?: ResolvedArgsByCallId;
+};
 export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
     private toolMap;
     private loadRuntimeTools?;
@@ -30,7 +47,37 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
     private toolApprovalConfig?;
     /** Buffer for recovering truncated tool call arguments from streaming data */
     private streamingToolCallBuffer?;
-    constructor({ tools, toolMap, name, tags, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, toolRegistry, sessions, eventDrivenMode, agentId, directToolNames, streamingToolCallBuffer, toolApprovalConfig, }: t.ToolNodeConstructorParams);
+    /** Hook registry threaded down from Run for tool-lifecycle events. */
+    private hookRegistry?;
+    /**
+     * Tool output reference registry threaded down from Run / Graph
+     * (upstream PR #114). When set, dispatchToolEvents resolves
+     * `{{tool<i>turn<n>}}` placeholders in args before invoking each tool
+     * and stores successful outputs under their stable reference keys for
+     * subsequent calls in the same run to pipe through.
+     */
+    private toolOutputRegistry?;
+    /**
+     * Per-batch turn counter for the registry. Increments once per
+     * `dispatchToolEvents` invocation so `tool<i>turn<n>` keys remain
+     * unique across overlapping batches in a single run.
+     */
+    private toolOutputTurn;
+    /**
+     * Counter for synthesising scope ids when `run()` is called without a
+     * `run_id` in config. Each anonymous batch gets a unique
+     * `\0anon-<n>` scope so concurrent invocations don't collide on the
+     * shared `toolOutputRegistry`.
+     */
+    private anonBatchCounter;
+    constructor({ tools, toolMap, name, tags, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, toolRegistry, sessions, eventDrivenMode, agentId, directToolNames, streamingToolCallBuffer, toolApprovalConfig, hookRegistry, toolOutputRegistry, toolOutputReferences, maxToolResultChars: _maxToolResultChars, }: t.ToolNodeConstructorParams);
+    /**
+     * Test-observation accessor for the tool-output reference registry.
+     * @internal Exposed for test observation only. Host code should rely on
+     * `{{tool<i>turn<n>}}` substitution at tool-invocation time and not
+     * mutate the registry directly.
+     */
+    _unsafeGetToolOutputRegistry(): ToolOutputReferenceRegistry | undefined;
     /**
      * Returns cached programmatic tools, computing once on first access.
      * Single iteration builds both toolMap and toolDefs simultaneously.
@@ -63,9 +110,15 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      */
     private requestApproval;
     /**
-     * Runs a single tool call with error handling
+     * Runs a single tool call with error handling.
+     *
+     * @param batchContext  Optional per-batch context (upstream PR #117).
+     *   Threaded from `run()` for tool output reference annotation. The
+     *   `batchScopeId` field carries an anonymous synthetic scope when the
+     *   caller has no `run_id`, so concurrent batches don't collide on the
+     *   shared registry.
      */
-    protected runTool(call: ToolCall, config: RunnableConfig): Promise<BaseMessage | Command>;
+    protected runTool(call: ToolCall, config: RunnableConfig, batchContext?: RunToolBatchContext): Promise<BaseMessage | Command>;
     /**
      * Recover truncated tool call arguments using the raw streaming buffer.
      *
@@ -89,6 +142,14 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      * @returns The args with recovered fields merged in
      */
     private recoverTruncatedArgs;
+    /**
+     * Stores the raw, untruncated tool output in the registry under `refKey`
+     * (when registry + refKey are both present) and returns the metadata
+     * envelope to stamp on `ToolMessage.additional_kwargs`. The lazy
+     * annotation transform reads `_refKey` / `_refScope` / `_unresolvedRefs`
+     * at LLM request time to produce the transient annotated copy.
+     */
+    private recordOutputReference;
     /**
      * Builds code session context for injection into event-driven tool calls.
      * Mirrors the session injection logic in runTool() for direct execution.
@@ -110,8 +171,18 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      */
     private handleRunToolCompletions;
     /**
-     * Dispatches tool calls to the host via ON_TOOL_EXECUTE event and returns raw ToolMessages.
-     * Core logic for event-driven execution, separated from output shaping.
+     * Converts InjectedMessage entries into LangChain HumanMessages.
+     * 'user' and 'system' both become HumanMessage to avoid provider rejections
+     * (Anthropic/Google reject non-leading SystemMessages); the original role
+     * and metadata are preserved in additional_kwargs for downstream consumers.
+     */
+    private convertInjectedMessages;
+    /**
+     * Dispatches tool calls to the host via ON_TOOL_EXECUTE event and returns
+     * the resulting ToolMessages along with any injected messages emitted by
+     * the host (e.g. SkillTool body injection). Injected messages must be
+     * placed AFTER the ToolMessages so the AIMessage tool_calls -> ToolMessage
+     * adjacency required by some providers is preserved.
      */
     private dispatchToolEvents;
     /**
@@ -124,3 +195,4 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
     private isMessagesState;
 }
 export declare function toolsCondition<T extends string>(state: BaseMessage[] | typeof MessagesAnnotation.State, toolNode: T, invokedToolIds?: Set<string>): T | typeof END;
+export {};

package/dist/types/tools/search/tavily-scraper.d.ts

@@ -0,0 +1,19 @@
+import type * as t from './types';
+export declare class TavilyScraper implements t.BaseScraper {
+    private apiKey;
+    private apiUrl;
+    private timeout;
+    private payloadTimeout;
+    private logger;
+    private extractDepth;
+    private includeImages;
+    private includeFavicon;
+    private format;
+    constructor(config?: t.TavilyScraperConfig);
+    scrapeUrl(url: string, options?: t.TavilyScrapeOptions): Promise<[string, t.TavilyScrapeResponse]>;
+    scrapeUrls(urls: string[], options?: t.TavilyScrapeOptions): Promise<Array<[string, t.TavilyScrapeResponse]>>;
+    private extractBatch;
+    extractContent(response: t.TavilyScrapeResponse): [string, undefined | t.References];
+    extractMetadata(response: t.TavilyScrapeResponse): t.GenericScrapeMetadata;
+}
+export declare const createTavilyScraper: (config?: t.TavilyScraperConfig) => TavilyScraper;

package/dist/types/tools/search/tavily-search.d.ts

@@ -0,0 +1,4 @@
+import type * as t from './types';
+export declare const createTavilyAPI: (apiKey?: string, apiUrl?: string, options?: t.TavilySearchOptions) => {
+    getSources: (params: t.GetSourcesParams) => Promise<t.SearchResult>;
+};