@librechat/agents 3.1.68 → 3.1.71-dev.0

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/ProgrammaticToolCalling.d.ts

@@ -75,21 +75,19 @@ export declare function filterToolsByUsage(toolDefs: t.LCTool[], code: string, d
  * Fetches files from a previous session to make them available for the current execution.
  * Files are returned as CodeEnvFile references to be included in the request.
  * @param baseUrl - The base URL for the Code API
- * @param apiKey - The API key for authentication
  * @param sessionId - The session ID to fetch files from
  * @param proxy - Optional HTTP proxy URL
  * @returns Array of CodeEnvFile references, or empty array if fetch fails
  */
-export declare function fetchSessionFiles(baseUrl: string, apiKey: string, sessionId: string, proxy?: string): Promise<t.CodeEnvFile[]>;
+export declare function fetchSessionFiles(baseUrl: string, sessionId: string, proxy?: string): Promise<t.CodeEnvFile[]>;
 /**
  * Makes an HTTP request to the Code API.
  * @param endpoint - The API endpoint URL
- * @param apiKey - The API key for authentication
  * @param body - The request body
  * @param proxy - Optional HTTP proxy URL
  * @returns The parsed API response
  */
-export declare function makeRequest(endpoint: string, apiKey: string, body: Record<string, unknown>, proxy?: string): Promise<t.ProgrammaticExecutionResponse>;
+export declare function makeRequest(endpoint: string, body: Record<string, unknown>, proxy?: string): Promise<t.ProgrammaticExecutionResponse>;
 /**
  * Unwraps tool responses that may be formatted as tuples or content blocks.
  * MCP tools return [content, artifacts], we need to extract the raw data.
@@ -121,14 +119,11 @@ export declare function formatCompletedResponse(response: t.ProgrammaticExecutio
  *
  * The tool map must be provided at runtime via config.configurable.toolMap.
  *
- * @param params - Configuration parameters (apiKey, baseUrl, maxRoundTrips, proxy)
+ * @param params - Configuration parameters (baseUrl, maxRoundTrips, proxy)
  * @returns A LangChain DynamicStructuredTool for programmatic tool calling
  *
  * @example
- * const ptcTool = createProgrammaticToolCallingTool({
- *   apiKey: process.env.CODE_API_KEY,
- *   maxRoundTrips: 20
- * });
+ * const ptcTool = createProgrammaticToolCallingTool({ maxRoundTrips: 20 });
  *
  * const [output, artifact] = await ptcTool.invoke(
  *   { code, tools },

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

@@ -2,8 +2,25 @@ import { ToolCall } from '@langchain/core/messages/tool';
 import { END, Command, MessagesAnnotation } from '@langchain/langgraph';
 import type { RunnableConfig } from '@langchain/core/runnables';
 import type { BaseMessage } from '@langchain/core/messages';
+import type { ResolvedArgsByCallId } from '@/tools/toolOutputReferences';
 import type * as t from '@/types';
 import { RunnableCallable } from '@/utils';
+import { ToolOutputReferenceRegistry } 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 parameters even as new context fields are added.
+ */
+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?;
@@ -28,7 +45,38 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
     private directToolNames?;
     /** Maximum characters allowed in a single tool result before truncation. */
     private maxToolResultChars;
-    constructor({ tools, toolMap, name, tags, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, toolRegistry, sessions, eventDrivenMode, agentId, directToolNames, maxContextTokens, maxToolResultChars, }: t.ToolNodeConstructorParams);
+    /** Hook registry for PreToolUse/PostToolUse lifecycle hooks */
+    private hookRegistry?;
+    /**
+     * Registry of tool outputs keyed by `tool<idx>turn<turn>`.
+     *
+     * Populated only when `toolOutputReferences.enabled` is true. The
+     * registry owns the run-scoped state (turn counter, last-seen runId,
+     * warn-once memo, stored outputs), so sharing a single instance
+     * across multiple ToolNodes in a run lets cross-agent `{{…}}`
+     * references resolve — which is why multi-agent graphs pass the
+     * *same* instance to every ToolNode they compile rather than each
+     * ToolNode building its own.
+     */
+    private toolOutputRegistry?;
+    /**
+     * Monotonic counter used to mint a unique scope id for anonymous
+     * batches (ones invoked without a `run_id` in
+     * `config.configurable`). Each such batch gets its own registry
+     * partition so concurrent anonymous invocations can't delete each
+     * other's in-flight state.
+     */
+    private anonBatchCounter;
+    constructor({ tools, toolMap, name, tags, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, toolRegistry, sessions, eventDrivenMode, agentId, directToolNames, maxContextTokens, maxToolResultChars, hookRegistry, toolOutputReferences, toolOutputRegistry, }: t.ToolNodeConstructorParams);
+    /**
+     * Returns the run-scoped tool output registry, or `undefined` when
+     * the feature is disabled.
+     *
+     * @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.
@@ -40,9 +88,36 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      */
     getToolUsageCounts(): ReadonlyMap<string, number>;
     /**
-     * Runs a single tool call with error handling
+     * Runs a single tool call with error handling.
+     *
+     * `batchIndex` is the tool's position within the current ToolNode
+     * batch and, together with `this.currentTurn`, forms the key used to
+     * register the output for future `{{tool<idx>turn<turn>}}`
+     * substitutions. Omit when no registration should occur.
+     */
+    protected runTool(call: ToolCall, config: RunnableConfig, batchContext?: RunToolBatchContext): Promise<BaseMessage | Command>;
+    /**
+     * Finalizes the LLM-visible content for a tool call and (when a
+     * `refKey` is provided) registers the full, raw output under that
+     * key.
+     *
+     * @param llmContent  The content string the LLM will see. This is
+     *   the already-truncated, post-hook view; the annotation is
+     *   applied on top of it.
+     * @param registryContent  The full, untruncated output to store in
+     *   the registry so `{{tool<i>turn<n>}}` substitutions deliver the
+     *   complete payload. Ignored when `refKey` is undefined.
+     * @param refKey  Precomputed `tool<i>turn<n>` key, or undefined when
+     *   the output is not to be registered (errors, disabled feature,
+     *   unavailable batch/turn).
+     * @param unresolved  Placeholder keys that did not resolve; appended
+     *   as `[unresolved refs: …]` so the LLM can self-correct.
+     *
+     * `refKey` is passed in (rather than built from `this.currentTurn`)
+     * so parallel `invoke()` calls on the same ToolNode cannot race on
+     * the shared turn field.
      */
-    protected runTool(call: ToolCall, config: RunnableConfig): Promise<BaseMessage | Command>;
+    private applyOutputReference;
     /**
      * Builds code session context for injection into event-driven tool calls.
      * Mirrors the session injection logic in runTool() for direct execution.
@@ -61,16 +136,45 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      * By handling completions here in graph context (rather than in the
      * stream consumer via ToolEndHandler), the race between the stream
      * consumer and graph execution is eliminated.
+     *
+     * @param resolvedArgsByCallId  Per-batch resolved-args sink populated
+     *   by `runTool`. Threaded as a local map (instead of instance state)
+     *   so concurrent batches cannot read each other's entries.
      */
     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.
+     *
+     * Hook lifecycle (when `hookRegistry` is set):
+     * 1. **PreToolUse** fires per call in parallel before dispatch. Denied
+     *    calls produce error ToolMessages and fire **PermissionDenied**;
+     *    surviving calls proceed with optional `updatedInput`.
+     * 2. Surviving calls are dispatched to the host via `ON_TOOL_EXECUTE`.
+     * 3. **PostToolUse** / **PostToolUseFailure** fire per result. Post hooks
+     *    can replace tool output via `updatedOutput`.
+     * 4. Injected messages from results are collected and returned alongside
+     *    ToolMessages (appended AFTER to respect provider ordering).
      */
     private dispatchToolEvents;
+    private dispatchStepCompleted;
+    /**
+     * Converts InjectedMessage instances to LangChain HumanMessage objects.
+     * Both 'user' and 'system' roles become HumanMessage to avoid provider
+     * rejections (Anthropic/Google reject non-leading SystemMessages).
+     * The original role is preserved in additional_kwargs for downstream consumers.
+     */
+    private convertInjectedMessages;
     /**
      * Execute all tool calls via ON_TOOL_EXECUTE event dispatch.
-     * Used in event-driven mode where the host handles actual tool execution.
+     * Injected messages are placed AFTER ToolMessages to respect provider
+     * message ordering (AIMessage tool_calls must be immediately followed
+     * by their ToolMessage results).
+     *
+     * `batchIndices` mirrors `toolCalls` and carries each call's position
+     * within the parent batch. `turn` is the per-`run()` batch index
+     * captured locally by the caller. Both are threaded so concurrent
+     * invocations cannot race on shared mutable state.
      */
     private executeViaEvent;
     protected run(input: any, config: RunnableConfig): Promise<T>;
@@ -78,3 +182,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/ToolSearch.d.ts

@@ -211,11 +211,11 @@ declare function formatServerListing(tools: t.ToolMetadata[], serverNames: strin
  *
  * @example
  * // Option 1: Code interpreter mode (regex via sandbox)
- * const tool = createToolSearch({ apiKey, toolRegistry });
+ * const tool = createToolSearch({ toolRegistry });
  * await tool.invoke({ query: 'expense.*report' });
  *
  * @example
- * // Option 2: Local mode (safe substring search, no API key needed)
+ * // Option 2: Local mode (safe substring search)
  * const tool = createToolSearch({ mode: 'local', toolRegistry });
  * await tool.invoke({ query: 'expense' });
  */

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

@@ -0,0 +1,19 @@
+import type { SkillCatalogEntry } from '@/types';
+export type SkillCatalogOptions = {
+    /** Total context window in tokens. Default: 200_000 */
+    contextWindowTokens?: number;
+    /** Fraction of context budget for catalog. Default: 0.01 (1%) */
+    budgetPercent?: number;
+    /** Max chars per entry description. Default: 250 */
+    maxEntryChars?: number;
+    /** Descriptions below this length trigger names-only fallback. Default: 20 */
+    minDescLength?: number;
+    /** Approximate chars per token for budget calculation. Default: 4 */
+    charsPerToken?: number;
+};
+/**
+ * Formats a skill catalog for injection into agent context.
+ * Uses a truncation ladder: full descriptions, proportional truncation, names-only.
+ * Returns empty string for empty input.
+ */
+export declare function formatSkillCatalog(skills: SkillCatalogEntry[], opts?: SkillCatalogOptions): string;

package/dist/types/tools/subagent/SubagentExecutor.d.ts

@@ -0,0 +1,137 @@
+import type { BaseMessage } from '@langchain/core/messages';
+import type { AgentInputs, StandardGraphInput, ResolvedSubagentConfig, SubagentConfig, TokenCounter } from '@/types';
+import type { HookRegistry } from '@/hooks';
+import type { AgentContext } from '@/agents/AgentContext';
+import type { StandardGraph } from '@/graphs/Graph';
+import type { HandlerRegistry } from '@/events';
+export type SubagentExecuteParams = {
+    description: string;
+    subagentType: string;
+    threadId?: string;
+    /**
+     * Parent-side `tool_call_id` of the `subagent` tool invocation that
+     * triggered this execution. Surfaced on {@link SubagentUpdateEvent} so
+     * hosts can correlate child updates back to the originating tool call
+     * without relying on event ordering heuristics.
+     */
+    parentToolCallId?: string;
+};
+export type SubagentExecuteResult = {
+    content: string;
+    messages: BaseMessage[];
+};
+/**
+ * Factory that constructs a child graph for subagent execution. Injected
+ * rather than imported so that `SubagentExecutor` does not have a runtime
+ * dependency on `StandardGraph` — this avoids a circular dependency between
+ * `src/graphs/Graph.ts` and `src/tools/subagent/` that would otherwise break
+ * Rollup's chunking under `preserveModules`.
+ */
+export type ChildGraphFactory = (input: StandardGraphInput) => StandardGraph;
+export type SubagentExecutorOptions = {
+    configs: Map<string, ResolvedSubagentConfig>;
+    parentSignal?: AbortSignal;
+    hookRegistry?: HookRegistry;
+    parentRunId: string;
+    parentAgentId?: string;
+    tokenCounter?: TokenCounter;
+    /** Remaining nesting budget. 0 or negative blocks execution. */
+    maxDepth?: number;
+    /**
+     * Factory for constructing the isolated child graph. Callers pass
+     * `(input) => new StandardGraph(input)` — injected to break a circular
+     * module dependency.
+     */
+    createChildGraph: ChildGraphFactory;
+    /**
+     * Parent's event handler registry. When provided, child-graph events are
+     * forwarded through this registry so hosts can:
+     *   (a) execute event-driven tools (`ON_TOOL_EXECUTE` routed to parent's handler),
+     *   (b) surface child activity to a UI via wrapped {@link GraphEvents.ON_SUBAGENT_UPDATE}.
+     * When omitted, the child runs fully isolated (legacy behavior).
+     *
+     * Can be a direct `HandlerRegistry` or a zero-arg getter — use the getter
+     * form when the registry is assigned to the graph AFTER the executor is
+     * constructed (the current `Run.create` flow sets `handlerRegistry`
+     * post-`createWorkflow`, so `createAgentNode` must capture lazily).
+     */
+    parentHandlerRegistry?: HandlerRegistry | (() => HandlerRegistry | undefined);
+};
+export declare class SubagentExecutor {
+    private readonly configs;
+    private readonly parentSignal?;
+    private readonly hookRegistry?;
+    private readonly parentRunId;
+    private readonly parentAgentId?;
+    private readonly tokenCounter?;
+    private readonly maxDepth;
+    private readonly createChildGraph;
+    private readonly resolveParentHandlerRegistry?;
+    constructor(options: SubagentExecutorOptions);
+    /** Snapshot of the parent's registry at the moment a subagent is dispatched. */
+    private getParentHandlerRegistry;
+    execute(params: SubagentExecuteParams): Promise<SubagentExecuteResult>;
+    /**
+     * Emits a single {@link GraphEvents.ON_SUBAGENT_UPDATE} envelope through the
+     * parent's handler registry. Silent no-op when no parent registry is set.
+     * Errors are swallowed — update events are observational.
+     */
+    private emitSubagentUpdate;
+    /**
+     * Builds a BaseCallbackHandler that intercepts the child graph's custom
+     * events. Routing rules:
+     *   - `ON_TOOL_EXECUTE` → forwarded as-is to the parent's ON_TOOL_EXECUTE
+     *     handler (so event-driven tools work identically for child and parent).
+     *   - `ON_RUN_STEP` / `ON_RUN_STEP_DELTA` / `ON_RUN_STEP_COMPLETED` /
+     *     `ON_MESSAGE_DELTA` / `ON_REASONING_DELTA` → wrapped in a
+     *     {@link GraphEvents.ON_SUBAGENT_UPDATE} envelope with a human-readable
+     *     label, delivered to the parent's subagent-update handler.
+     *   - Everything else → ignored (keeps parent's UI scoped to the events it
+     *     cares about; host apps can extend by registering more phases).
+     */
+    private createForwarderCallback;
+}
+/**
+ * Produces a short single-line label for an arbitrary forwarded child event.
+ * Used to populate {@link SubagentUpdateEvent.label} so the host UI can show
+ * a compact status ticker without parsing the raw payload.
+ */
+export declare function summarizeEvent(eventName: string, data: unknown): string;
+/**
+ * Walk messages from last to first, returning the text content of the most
+ * recent AIMessage that has any. Non-text blocks (tool_use, thinking,
+ * redacted_thinking, tool_result) are stripped. If the last AIMessage is
+ * pure tool_use (e.g. the subagent hit `maxTurns` mid-tool-call), the walk
+ * continues to earlier AIMessages so partial progress is salvaged — this
+ * matches Claude Code's behavior in `agentToolUtils.finalizeAgentTool`.
+ * Returns "Task completed" only when no AIMessage in the history contains
+ * any text.
+ */
+export declare function filterSubagentResult(messages: BaseMessage[]): string;
+/**
+ * Resolve self-spawn configs by filling in agentInputs from the parent context.
+ * Returns configs with agentInputs guaranteed present. Throws on duplicate
+ * `type` values to prevent silent config shadowing.
+ */
+export declare function resolveSubagentConfigs(configs: SubagentConfig[], parentContext: AgentContext): ResolvedSubagentConfig[];
+/**
+ * Build child AgentInputs from a resolved config, stripping nesting and
+ * (optionally) event-driven fields. When `allowNested: true`, the child's
+ * `maxSubagentDepth` is decremented so that depth is consumed as the call
+ * chain deepens across graph boundaries — the parent's executor-level check
+ * alone cannot see into the child graph's separate executor.
+ *
+ * When `keepToolDefinitions` is `true`, the child retains the parent's
+ * `toolDefinitions` so event-driven tools remain usable. This is only safe
+ * when the caller has wired a forwarder for `ON_TOOL_EXECUTE` to a
+ * registered handler — otherwise the child will hang on tool dispatch.
+ *
+ * @remarks Advanced utility: exported primarily for testing and by
+ * {@link SubagentExecutor}. Host applications configuring subagents should
+ * not need to call this directly — it is invoked internally when a subagent
+ * tool is dispatched. The depth-countdown contract (parent's `maxDepth` in,
+ * child's decremented `maxSubagentDepth` on the returned inputs) is the
+ * mechanism that bounds nesting across graph boundaries; callers must
+ * respect it.
+ */
+export declare function buildChildInputs(config: ResolvedSubagentConfig, childAgentId: string, parentMaxDepth: number, keepToolDefinitions?: boolean): AgentInputs;

package/dist/types/tools/subagent/index.d.ts

@@ -0,0 +1,2 @@
+export { SubagentExecutor, filterSubagentResult, resolveSubagentConfigs, buildChildInputs, summarizeEvent, } from './SubagentExecutor';
+export type { SubagentExecuteParams, SubagentExecuteResult, SubagentExecutorOptions, ChildGraphFactory, } from './SubagentExecutor';