@librechat/agents 3.1.68 → 3.1.70

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

@@ -28,7 +28,9 @@ 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?;
+    constructor({ tools, toolMap, name, tags, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, toolRegistry, sessions, eventDrivenMode, agentId, directToolNames, maxContextTokens, maxToolResultChars, hookRegistry, }: t.ToolNodeConstructorParams);
     /**
      * Returns cached programmatic tools, computing once on first access.
      * Single iteration builds both toolMap and toolDefs simultaneously.
@@ -66,11 +68,31 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
     /**
      * 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).
      */
     private executeViaEvent;
     protected run(input: any, config: RunnableConfig): Promise<T>;

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';

package/dist/types/types/graph.d.ts

@@ -4,7 +4,7 @@ import type { BaseMessage, AIMessageChunk, SystemMessage } from '@langchain/core
 import type { RunnableConfig, Runnable } from '@langchain/core/runnables';
 import type { ChatGenerationChunk } from '@langchain/core/outputs';
 import type { GoogleAIToolType } from '@langchain/google-common';
-import type { ToolMap, ToolEndEvent, GenericTool, LCTool } from '@/types/tools';
+import type { ToolMap, ToolEndEvent, GenericTool, LCTool, ToolExecuteBatchRequest } from '@/types/tools';
 import type { Providers, Callback, GraphNodeKeys } from '@/common';
 import type { StandardGraph, MultiAgentGraph } from '@/graphs';
 import type { ClientOptions } from '@/types/llm';
@@ -45,7 +45,7 @@ export interface AgentLogEvent {
     agentId?: string;
 }
 export interface EventHandler {
-    handle(event: string, data: StreamEventData | ModelEndData | RunStep | RunStepDeltaEvent | MessageDeltaEvent | ReasoningDeltaEvent | SummarizeStartEvent | SummarizeDeltaEvent | SummarizeCompleteEvent | AgentLogEvent | {
+    handle(event: string, data: StreamEventData | ModelEndData | RunStep | RunStepDeltaEvent | MessageDeltaEvent | ReasoningDeltaEvent | SummarizeStartEvent | SummarizeDeltaEvent | SummarizeCompleteEvent | SubagentUpdateEvent | AgentLogEvent | ToolExecuteBatchRequest | {
         result: ToolEndEvent;
     }, metadata?: Record<string, unknown>, graph?: StandardGraph | MultiAgentGraph): void | Promise<void>;
 }
@@ -248,6 +248,61 @@ export type GraphEdge = {
 export type MultiAgentGraphInput = StandardGraphInput & {
     edges: GraphEdge[];
 };
+/** Configuration for a subagent type that can be spawned by a parent agent. */
+export type SubagentConfig = {
+    /** Identifier used in the tool's `subagent_type` enum (e.g. 'researcher', 'coder'). */
+    type: string;
+    /** Human-readable display name. */
+    name: string;
+    /** What this subagent specializes in — shown to the LLM. */
+    description: string;
+    /** Full agent config for the child graph. Omit when `self` is true. */
+    agentInputs?: AgentInputs;
+    /** When true, reuse the parent's AgentInputs (context isolation without separate config). */
+    self?: boolean;
+    /** Max AGENT→TOOLS cycles before forced stop (default: 25). */
+    maxTurns?: number;
+    /** Allow this subagent to spawn its own subagents (default: false). */
+    allowNested?: boolean;
+};
+/** SubagentConfig with agentInputs guaranteed present (self-spawn resolved). */
+export type ResolvedSubagentConfig = SubagentConfig & {
+    agentInputs: AgentInputs;
+};
+/** Lifecycle phase carried on {@link SubagentUpdateEvent}. */
+export type SubagentUpdatePhase = 'start' | 'run_step' | 'run_step_delta' | 'run_step_completed' | 'message_delta' | 'reasoning_delta' | 'stop' | 'error';
+/**
+ * Wrapper event emitted when a subagent's child graph dispatches activity.
+ * Lets hosts show subagent progress in a UI surface separate from the parent
+ * conversation without having to untangle events by agent ID.
+ */
+export interface SubagentUpdateEvent {
+    /** Parent run ID. */
+    runId: string;
+    /** Child run ID (unique per subagent execution). */
+    subagentRunId: string;
+    /**
+     * Parent-side `tool_call_id` for the `subagent` tool invocation that
+     * triggered this run. Stable for the duration of the child; lets hosts
+     * correlate updates deterministically instead of inferring by ordering.
+     * Omitted when the executor was invoked outside of a tool-call context.
+     */
+    parentToolCallId?: string;
+    /** Subagent `type` identifier from the SubagentConfig. */
+    subagentType: string;
+    /** Child agent ID assigned to this subagent execution. */
+    subagentAgentId: string;
+    /** Parent agent ID that spawned this subagent. */
+    parentAgentId?: string;
+    /** Lifecycle phase carried by this update. */
+    phase: SubagentUpdatePhase;
+    /** Underlying event payload (shape depends on phase). */
+    data?: unknown;
+    /** Short human-readable description. Hosts can render this directly. */
+    label?: string;
+    /** ISO timestamp for ordering / display. */
+    timestamp: string;
+}
 export interface AgentInputs {
     agentId: string;
     /** Human-readable name for the agent (used in handoff context). Defaults to agentId if not provided. */
@@ -294,6 +349,10 @@ export interface AgentInputs {
     maxToolResultChars?: number;
     /** Pre-computed tool schema token count (from cache). Skips recalculation when provided. */
     toolSchemaTokens?: number;
+    /** Subagent configurations for hierarchical delegation. Each defines a child agent type. */
+    subagentConfigs?: SubagentConfig[];
+    /** Maximum subagent nesting depth. Default 1 means top-level agents can spawn subagents but subagents cannot nest further. */
+    maxSubagentDepth?: number;
 }
 export interface ContextPruningConfig {
     enabled?: boolean;

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

@@ -1,6 +1,7 @@
 export * from './graph';
 export * from './llm';
 export * from './run';
+export * from './skill';
 export * from './stream';
 export * from './tools';
 export * from './summarize';

package/dist/types/types/run.d.ts

@@ -7,6 +7,8 @@ import type * as s from '@/types/stream';
 import type * as e from '@/common/enum';
 import type * as g from '@/types/graph';
 import type * as l from '@/types/llm';
+import type { ToolSessionMap } from '@/types/tools';
+import type { HookRegistry } from '@/hooks';
 export type ZodObjectAny = z.ZodObject<any, any, any, any>;
 export type BaseGraphConfig = {
     llmConfig: l.LLMConfig;
@@ -100,6 +102,18 @@ export type RunConfig = {
     runId: string;
     graphConfig: LegacyGraphConfig | StandardGraphConfig | MultiAgentGraphConfig;
     customHandlers?: Record<string, g.EventHandler>;
+    /**
+     * Pre-constructed hook registry for this run. Hooks fire at lifecycle
+     * points in `processStream` (RunStart, UserPromptSubmit, Stop,
+     * StopFailure) and around tool calls (PreToolUse, PostToolUse,
+     * PostToolUseFailure, PermissionDenied).
+     *
+     * Pass `undefined` (the default) to skip all hook dispatch. When a
+     * registry is provided, the run attaches it to the `Graph` so internal
+     * nodes can fire hooks too, and clears the session in the `finally`
+     * block to prevent leaks.
+     */
+    hooks?: HookRegistry;
     returnContent?: boolean;
     tokenCounter?: TokenCounter;
     indexTokenCountMap?: Record<string, number>;
@@ -114,6 +128,12 @@ export type RunConfig = {
     calibrationRatio?: number;
     /** Skip post-stream cleanup (clearHeavyState) — useful for tests that inspect graph state after processStream */
     skipCleanup?: boolean;
+    /**
+     * Initial session state to seed the Graph's ToolSessionMap.
+     * Used to carry over code environment sessions from skill file priming
+     * at run start, so ToolNode can inject session_id + files into tool calls.
+     */
+    initialSessions?: ToolSessionMap;
 };
 export type ProvidedCallbacks = (BaseCallbackHandler | CallbackHandlerMethods)[] | undefined;
 export type TokenCounter = (message: BaseMessage) => number;

package/dist/types/types/skill.d.ts

@@ -0,0 +1,9 @@
+/** Minimal skill metadata for catalog assembly. The host provides these from its own data layer. */
+export type SkillCatalogEntry = {
+    /** Kebab-case identifier (what the model passes to SkillTool) */
+    name: string;
+    /** One-line description for the catalog listing */
+    description: string;
+    /** Optional human-readable label (UI only, not shown to model) */
+    displayTitle?: string;
+};

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

@@ -1,8 +1,8 @@
 import type { StructuredToolInterface } from '@langchain/core/tools';
 import type { RunnableToolLike } from '@langchain/core/runnables';
 import type { ToolCall } from '@langchain/core/messages/tool';
-import type { ToolErrorData } from './stream';
-import { EnvVar } from '@/common';
+import type { HookRegistry } from '@/hooks';
+import type { MessageContentComplex, ToolErrorData } from './stream';
 /** Replacement type for `import type { ToolCall } from '@langchain/core/messages/tool'` in order to have stringified args typed */
 export type CustomToolCall = {
     name: string;
@@ -39,6 +39,12 @@ export type ToolNodeOptions = {
     agentId?: string;
     /** Tool names that must be executed directly (via runTool) even in event-driven mode (e.g., graph-managed handoff tools) */
     directToolNames?: Set<string>;
+    /**
+     * Hook registry for PreToolUse/PostToolUse lifecycle hooks.
+     * Only fires for event-driven tool calls (`dispatchToolEvents`). Tools
+     * routed through `directToolNames` bypass hook dispatch entirely.
+     */
+    hookRegistry?: HookRegistry;
     /** Max context tokens for the agent — used to compute tool result truncation limits. */
     maxContextTokens?: number;
     /**
@@ -65,9 +71,7 @@ export type CodeEnvFile = {
 export type CodeExecutionToolParams = undefined | {
     session_id?: string;
     user_id?: string;
-    apiKey?: string;
     files?: CodeEnvFile[];
-    [EnvVar.CODE_API_KEY]?: string;
 };
 export type FileRef = {
     id: string;
@@ -154,6 +158,25 @@ export type ToolExecuteBatchRequest = {
     /** Promise rejector - handler calls this on fatal error */
     reject: (error: Error) => void;
 };
+/**
+ * A message injected into graph state by any tool execution handler.
+ * Generic mechanism: any tool returning `injectedMessages` in its `ToolExecuteResult`
+ * will have these appended to state after the ToolMessage for this call.
+ */
+export type InjectedMessage = {
+    /** 'user' for skill body injection, 'system' for context hints.
+     *  Both are converted to HumanMessage at runtime; the original role
+     *  is preserved in additional_kwargs.role. */
+    role: 'user' | 'system';
+    /** Message content: string for simple text, array for complex multi-part content */
+    content: string | MessageContentComplex[];
+    /** When true, the message is framework-internal: not shown in UI, not counted as a user turn */
+    isMeta?: boolean;
+    /** Origin tag for downstream consumers (UI, pruner, compaction) */
+    source?: 'skill' | 'hook' | 'system';
+    /** Only set when source is 'skill', for compaction preservation */
+    skillName?: string;
+};
 /** Result for a single tool call in event-driven execution */
 export type ToolExecuteResult = {
     /** Matches ToolCallRequest.id */
@@ -166,6 +189,13 @@ export type ToolExecuteResult = {
     status: 'success' | 'error';
     /** Error message if status is 'error' */
     errorMessage?: string;
+    /**
+     * Messages to inject into graph state after the ToolMessage for this call.
+     * Placed after tool results to respect provider message ordering (tool_call -> tool_result adjacency).
+     * The host's message formatter may merge injected user messages with the preceding tool_result turn.
+     * Generic mechanism: any tool execution handler can use this.
+     */
+    injectedMessages?: InjectedMessage[];
 };
 /** Map of tool names to tool definitions */
 export type LCToolRegistry = Map<string, LCTool>;
@@ -179,7 +209,6 @@ export type ToolSearchMode = 'code_interpreter' | 'local';
 export type McpNameFormat = 'full' | 'base';
 /** Parameters for creating a Tool Search tool */
 export type ToolSearchParams = {
-    apiKey?: string;
     toolRegistry?: LCToolRegistry;
     onlyDeferred?: boolean;
     baseUrl?: string;
@@ -189,7 +218,6 @@ export type ToolSearchParams = {
     mcpServer?: string | string[];
     /** Format for MCP tool names: 'full' (tool_mcp_server) or 'base' (tool only). Default: 'full' */
     mcpNameFormat?: McpNameFormat;
-    [key: string]: unknown;
 };
 /** Simplified tool metadata for search purposes */
 export type ToolMetadata = {
@@ -266,12 +294,14 @@ export type ProgrammaticExecutionArtifact = {
     session_id?: string;
     files?: FileRefs;
 };
+/** Parameters for creating a bash execution tool (same API as CodeExecutor, bash-only) */
+export type BashExecutionToolParams = CodeExecutionToolParams;
+/** Parameters for creating a bash programmatic tool calling tool (same API as PTC, bash-only) */
+export type BashProgrammaticToolCallingParams = ProgrammaticToolCallingParams;
 /**
  * Initialization parameters for the PTC tool
  */
 export type ProgrammaticToolCallingParams = {
-    /** Code API key (or use CODE_API_KEY env var) */
-    apiKey?: string;
     /** Code API base URL (or use CODE_BASEURL env var) */
     baseUrl?: string;
     /** Safety limit for round-trips (default: 20) */
@@ -280,8 +310,6 @@ export type ProgrammaticToolCallingParams = {
     proxy?: string;
     /** Enable debug logging (or set PTC_DEBUG=true env var) */
     debug?: boolean;
-    /** Environment variable key for API key */
-    [key: string]: unknown;
 };
 /**
  * Tracks code execution session state for automatic file persistence.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.1.68",
+  "version": "3.1.70",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",
@@ -61,6 +61,9 @@
     "tool": "node --trace-warnings -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/tools.ts --provider 'bedrock' --name 'Jo' --location 'New York, NY'",
     "search": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/search.ts --provider 'bedrock' --name 'Jo' --location 'New York, NY'",
     "tool_search": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/tool_search.ts",
+    "subagent": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/multi-agent-subagent.ts",
+    "subagent:events": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/subagent-event-driven-debug.ts",
+    "subagent:tools": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/subagent-tools-debug.ts",
     "programmatic_exec": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/programmatic_exec.ts",
     "code_exec_ptc": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/code_exec_ptc.ts --provider 'openAI' --name 'Jo' --location 'New York, NY'",
     "programmatic_exec_agent": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/programmatic_exec_agent.ts --provider 'openAI' --name 'Jo' --location 'New York, NY'",
@@ -77,6 +80,7 @@
     "multi-agent-chain": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/multi-agent-chain.ts",
     "multi-agent-sequence": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/multi-agent-sequence.ts",
     "multi-agent-conditional": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/multi-agent-conditional.ts",
+    "multi-agent-subagent": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/multi-agent-subagent.ts",
     "multi-agent-supervisor": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/multi-agent-supervisor.ts",
     "test-handoff-preamble": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/test-handoff-preamble.ts",
     "multi-agent-list-handoff": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/test-multi-agent-list-handoff.ts",

package/src/agents/AgentContext.ts

@@ -55,6 +55,8 @@ export class AgentContext {
       contextPruningConfig,
       maxToolResultChars,
       toolSchemaTokens,
+      subagentConfigs,
+      maxSubagentDepth,
     } = agentConfig;
 
     const agentContext = new AgentContext({
@@ -82,6 +84,10 @@ export class AgentContext {
       maxToolResultChars,
     });
 
+    agentContext._sourceInputs = agentConfig;
+    agentContext.subagentConfigs = subagentConfigs;
+    agentContext.maxSubagentDepth = maxSubagentDepth;
+
     if (initialSummary?.text != null && initialSummary.text !== '') {
       agentContext.setInitialSummary(
         initialSummary.text,
@@ -198,6 +204,12 @@ export class AgentContext {
   toolDefinitions?: t.LCTool[];
   /** Set of tool names discovered via tool search (to be loaded) */
   discoveredToolNames: Set<string> = new Set();
+  /** Original AgentInputs used to create this context — used for self-spawn subagent resolution. */
+  _sourceInputs?: t.AgentInputs;
+  /** Subagent configurations for hierarchical delegation. */
+  subagentConfigs?: t.SubagentConfig[];
+  /** Maximum subagent nesting depth. */
+  maxSubagentDepth?: number;
   /** Instructions for this agent */
   instructions?: string;
   /** Additional instructions for this agent */
@@ -685,8 +697,20 @@ export class AgentContext {
     let toolTokens = 0;
     const countedToolNames = new Set<string>();
 
-    if (this.tools && this.tools.length > 0) {
-      for (const tool of this.tools) {
+    /**
+     * Iterate both `tools` (user-provided instance tools) and `graphTools`
+     * (graph-managed tools like handoff + subagent). `graphTools` is often
+     * populated after `fromConfig()` kicks off the initial calculation, so
+     * callers that mutate `graphTools` must re-trigger this method to
+     * refresh `toolSchemaTokens`.
+     */
+    const instanceTools: t.GraphTools = [
+      ...((this.tools as t.GenericTool[] | undefined) ?? []),
+      ...((this.graphTools as t.GenericTool[] | undefined) ?? []),
+    ];
+
+    if (instanceTools.length > 0) {
+      for (const tool of instanceTools) {
         const genericTool = tool as Record<string, unknown>;
         if (
           genericTool.schema != null &&

package/src/common/enum.ts

@@ -27,6 +27,8 @@ export enum GraphEvents {
   ON_SUMMARIZE_DELTA = 'on_summarize_delta',
   /** [Custom] Emitted when the summarize node completes with the final summary */
   ON_SUMMARIZE_COMPLETE = 'on_summarize_complete',
+  /** [Custom] Progress update from a running subagent (wraps child-graph events so hosts can display activity separately from parent). */
+  ON_SUBAGENT_UPDATE = 'on_subagent_update',
   /** [Custom] Diagnostic logging event for context management observability */
   ON_AGENT_LOG = 'on_agent_log',
 
@@ -182,8 +184,21 @@ export enum Constants {
   MCP_DELIMITER = '_mcp_',
   /** Anthropic server tool ID prefix (web_search, code_execution, etc.) */
   ANTHROPIC_SERVER_TOOL_PREFIX = 'srvtoolu_',
+  SKILL_TOOL = 'skill',
+  READ_FILE = 'read_file',
+  BASH_TOOL = 'bash_tool',
+  BASH_PROGRAMMATIC_TOOL_CALLING = 'run_tools_with_bash',
+  SUBAGENT = 'subagent',
 }
 
+/** Tool names that use the code execution environment (shared session, file tracking). */
+export const CODE_EXECUTION_TOOLS: ReadonlySet<string> = new Set([
+  Constants.EXECUTE_CODE,
+  Constants.BASH_TOOL,
+  Constants.PROGRAMMATIC_TOOL_CALLING,
+  Constants.BASH_PROGRAMMATIC_TOOL_CALLING,
+]);
+
 export enum TitleMethod {
   STRUCTURED = 'structured',
   FUNCTIONS = 'functions',
@@ -191,6 +206,5 @@ export enum TitleMethod {
 }
 
 export enum EnvVar {
-  CODE_API_KEY = 'LIBRECHAT_CODE_API_KEY',
   CODE_BASEURL = 'LIBRECHAT_CODE_BASEURL',
 }