@librechat/agents 3.1.68 → 3.1.71-dev.0

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

@@ -0,0 +1,205 @@
+/**
+ * Tool output reference registry.
+ *
+ * When enabled via `RunConfig.toolOutputReferences.enabled`, ToolNode
+ * stores each successful tool output under a stable key
+ * (`tool<idx>turn<turn>`) where `idx` is the tool's position within a
+ * ToolNode batch and `turn` is the batch index within the run
+ * (incremented once per ToolNode invocation).
+ *
+ * Subsequent tool calls can pipe a previous output into their args by
+ * embedding `{{tool<idx>turn<turn>}}` inside any string argument;
+ * {@link ToolOutputReferenceRegistry.resolve} walks the args and
+ * substitutes the placeholders immediately before invocation.
+ *
+ * The registry stores the *raw, untruncated* tool output so a later
+ * `{{…}}` substitution pipes the full payload into the next tool —
+ * even when the LLM only saw a head+tail-truncated preview in
+ * `ToolMessage.content`. Outputs are stored without any annotation
+ * (the `_ref` key or the `[ref: ...]` prefix seen by the LLM is
+ * strictly a UX signal attached to `ToolMessage.content`). Keeping the
+ * registry pristine means downstream bash/jq piping receives the
+ * complete, verbatim output with no injected fields.
+ */
+/**
+ * Non-global matcher for a single `{{tool<i>turn<n>}}` placeholder.
+ * Exported for consumers that want to detect references (e.g., syntax
+ * highlighting, docs). The stateful `g` variant lives inside the
+ * registry so nobody trips on `lastIndex`.
+ */
+export declare const TOOL_OUTPUT_REF_PATTERN: RegExp;
+/** Object key used when a parsed-object output has `_ref` injected. */
+export declare const TOOL_OUTPUT_REF_KEY = "_ref";
+/**
+ * Object key used to carry unresolved reference warnings on a parsed-
+ * object output. Using a dedicated field instead of a trailing text
+ * line keeps the annotated `ToolMessage.content` parseable as JSON for
+ * downstream consumers that rely on the object shape.
+ */
+export declare const TOOL_OUTPUT_UNRESOLVED_KEY = "_unresolved_refs";
+/** Single-line prefix prepended to non-object tool outputs so the LLM sees the reference key. */
+export declare function buildReferencePrefix(key: string): string;
+/** Stable registry key for a tool output. */
+export declare function buildReferenceKey(toolIndex: number, turn: number): string;
+export type ToolOutputReferenceRegistryOptions = {
+    /** Maximum characters stored per registered output. */
+    maxOutputSize?: number;
+    /** Maximum total characters retained across all registered outputs. */
+    maxTotalSize?: number;
+    /**
+     * Upper bound on the number of concurrently-tracked runs. When
+     * exceeded, the oldest run bucket is evicted (FIFO). Defaults to 32.
+     */
+    maxActiveRuns?: number;
+};
+/**
+ * Result of resolving placeholders in tool args.
+ */
+export type ResolveResult<T> = {
+    /** Arguments with placeholders replaced. Same shape as the input. */
+    resolved: T;
+    /** Reference keys that were referenced but had no stored value. */
+    unresolved: string[];
+};
+/**
+ * Read-only view over a frozen registry snapshot. Returned by
+ * {@link ToolOutputReferenceRegistry.snapshot} for callers that need
+ * to resolve placeholders against the registry state at a specific
+ * point in time, ignoring any subsequent registrations.
+ */
+export interface ToolOutputResolveView {
+    resolve<T>(args: T): ResolveResult<T>;
+}
+/**
+ * Pre-resolved arg map keyed by `toolCallId`. Used by the mixed
+ * direct+event dispatch path to feed event calls' resolved args
+ * (captured pre-batch) into the dispatcher without re-resolving
+ * against the now-stale live registry.
+ */
+export type PreResolvedArgsMap = Map<string, {
+    resolved: Record<string, unknown>;
+    unresolved: string[];
+}>;
+/**
+ * Per-call sink for resolved args, keyed by `toolCallId`. Threaded
+ * as a per-batch local map so concurrent `ToolNode.run()` calls do
+ * not race on shared sink state.
+ */
+export type ResolvedArgsByCallId = Map<string, Record<string, unknown>>;
+/**
+ * Ordered map of reference-key → stored output, partitioned by run so
+ * concurrent / interleaved runs sharing one registry cannot leak
+ * outputs between each other.
+ *
+ * Each public method takes a `runId` which selects the run's bucket.
+ * Hosts typically get one registry per run via `Graph`, in which
+ * case only a single bucket is ever populated; the partitioning
+ * exists so the registry also behaves correctly when a single
+ * instance is reused directly.
+ */
+export declare class ToolOutputReferenceRegistry {
+    private runStates;
+    private readonly maxOutputSize;
+    private readonly maxTotalSize;
+    private readonly maxActiveRuns;
+    /**
+     * Local stateful matcher used only by `replaceInString`. Kept
+     * off-module so callers of the exported `TOOL_OUTPUT_REF_PATTERN`
+     * never see a stale `lastIndex`.
+     */
+    private static readonly PLACEHOLDER_MATCHER;
+    constructor(options?: ToolOutputReferenceRegistryOptions);
+    private keyFor;
+    private getOrCreate;
+    /** Registers (or replaces) the output stored under `key` for `runId`. */
+    set(runId: string | undefined, key: string, value: string): void;
+    /** Returns the stored value for `key` in `runId`'s bucket, or `undefined`. */
+    get(runId: string | undefined, key: string): string | undefined;
+    /** Total number of registered outputs across every run bucket. */
+    get size(): number;
+    /** Maximum characters retained per output (post-clip). */
+    get perOutputLimit(): number;
+    /** Maximum total characters retained *per run*. */
+    get totalLimit(): number;
+    /** Drops every run's state. */
+    clear(): void;
+    /**
+     * Explicitly release `runId`'s state. Safe to call when a run has
+     * finished. Hosts sharing one registry across runs should call this
+     * to reclaim memory deterministically; otherwise LRU eviction kicks
+     * in when `maxActiveRuns` runs accumulate.
+     */
+    releaseRun(runId: string | undefined): void;
+    /**
+     * Claims the next batch turn synchronously from `runId`'s bucket.
+     *
+     * Must be called once at the start of each ToolNode batch before
+     * any `await`, so concurrent invocations within the same run see
+     * distinct turn values (reads are effectively atomic by JS's
+     * single-threaded execution of the sync prefix).
+     *
+     * If `runId` is missing the anonymous bucket is dropped and a
+     * fresh one created so each anonymous call behaves as its own run.
+     */
+    nextTurn(runId: string | undefined): number;
+    /**
+     * Records that `toolName` has been warned about in `runId` (returns
+     * `true` on the first call per run, `false` after). Used by
+     * ToolNode to emit one log line per offending tool per run when a
+     * `ToolMessage.content` isn't a string.
+     */
+    claimWarnOnce(runId: string | undefined, toolName: string): boolean;
+    /**
+     * Walks `args` and replaces every `{{tool<i>turn<n>}}` placeholder in
+     * string values with the stored output *from `runId`'s bucket*. Non-
+     * string values and object keys are left untouched. Unresolved
+     * references are left in-place and reported so the caller can
+     * surface them to the LLM. When no placeholder appears anywhere in
+     * the serialized args, the original input is returned without
+     * walking the tree.
+     */
+    resolve<T>(runId: string | undefined, args: T): ResolveResult<T>;
+    /**
+     * Captures a frozen snapshot of `runId`'s current entries and
+     * returns a view that resolves placeholders against *only* that
+     * snapshot. The snapshot is decoupled from the live registry, so
+     * subsequent `set()` calls (for example, same-turn direct outputs
+     * registering while an event branch is still in flight) are
+     * invisible to the snapshot's `resolve`. Used by the mixed
+     * direct+event dispatch path to preserve same-turn isolation when
+     * a `PreToolUse` hook rewrites event args after directs have
+     * completed.
+     */
+    snapshot(runId: string | undefined): ToolOutputResolveView;
+    private resolveAgainst;
+    private transform;
+    private replaceInString;
+    private evictWithinBucket;
+}
+/**
+ * Annotates `content` with a reference key and/or unresolved-ref
+ * warnings so the LLM sees both alongside the tool output.
+ *
+ * Behavior:
+ *  - If `content` parses as a plain (non-array, non-null) JSON object
+ *    and the object does not already have a conflicting `_ref` key,
+ *    the reference key and (when present) `_unresolved_refs` array
+ *    are injected as object fields, preserving JSON validity for
+ *    downstream consumers that parse the output.
+ *  - Otherwise (string output, JSON array/primitive, parse failure,
+ *    or `_ref` collision), a `[ref: <key>]\n` prefix line is
+ *    prepended and unresolved refs are appended as a trailing
+ *    `[unresolved refs: …]` line.
+ *
+ * The annotated string is what the LLM sees as `ToolMessage.content`.
+ * The *original* (un-annotated) value is what gets stored in the
+ * registry, so downstream piping remains pristine.
+ *
+ * @param content     Raw (post-truncation) tool output.
+ * @param key         Reference key for this output, or undefined when
+ *                    there is nothing to register (errors etc.).
+ * @param unresolved  Reference keys that failed to resolve during
+ *                    argument substitution. Surfaced so the LLM can
+ *                    self-correct its next tool call.
+ */
+export declare function annotateToolOutputWithReference(content: string, key: string | undefined, unresolved?: string[]): string;

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, ToolOutputReferencesConfig } 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,20 @@ 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;
+    /**
+     * Run-scoped tool output reference configuration. When `enabled` is
+     * `true`, tool outputs are registered under stable keys
+     * (`tool<idx>turn<turn>`) and subsequent tool calls can pipe previous
+     * outputs into their arguments via `{{tool<idx>turn<turn>}}`
+     * placeholders. Disabled by default so existing runs are unaffected.
+     */
+    toolOutputReferences?: ToolOutputReferencesConfig;
 };
 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,9 @@
 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 { ToolOutputReferenceRegistry } from '@/tools/toolOutputReferences';
+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 +40,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;
     /**
@@ -46,6 +53,22 @@ export type ToolNodeOptions = {
      * When provided, takes precedence over the value computed from maxContextTokens.
      */
     maxToolResultChars?: number;
+    /**
+     * Run-scoped tool output reference configuration. When `enabled` is
+     * `true`, ToolNode registers successful outputs and substitutes
+     * `{{tool<idx>turn<turn>}}` placeholders found in string args.
+     *
+     * Ignored when `toolOutputRegistry` is also provided (host-supplied
+     * registry wins).
+     */
+    toolOutputReferences?: ToolOutputReferencesConfig;
+    /**
+     * Pre-constructed registry instance shared across ToolNodes for the
+     * run. Graphs pass the same registry to every ToolNode they compile
+     * so cross-agent `{{tool<i>turn<n>}}` substitutions resolve. Takes
+     * precedence over `toolOutputReferences` when both are set.
+     */
+    toolOutputRegistry?: ToolOutputReferenceRegistry;
 };
 export type ToolNodeConstructorParams = ToolRefs & ToolNodeOptions;
 export type ToolEndEvent = {
@@ -65,9 +88,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 +175,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,9 +206,69 @@ 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>;
+/**
+ * Run-scoped configuration for tool output references.
+ *
+ * When enabled, each successful tool result is registered under a stable
+ * key (`tool<idx>turn<turn>`). Later tool calls can pipe a previous
+ * output into their arguments by including the literal placeholder
+ * `{{tool<idx>turn<turn>}}` anywhere in a string argument; ToolNode
+ * substitutes it with the stored output immediately before invoking
+ * the tool.
+ *
+ * The registry stores the *raw, untruncated* tool output (subject to
+ * its own size caps) so a later substitution can pipe the full payload
+ * into the next tool even when the LLM only saw a head+tail-truncated
+ * preview in `ToolMessage.content`. Size limits are decoupled from the
+ * LLM-visible truncation budget and default to 5 MB total.
+ *
+ * Known limitations:
+ *  - Tools that return a `ToolMessage` with array-type content
+ *    (multi-part content blocks such as text + image) are not
+ *    registered and cannot be cited via `{{tool<i>turn<n>}}`. A
+ *    warning is logged so the missing reference is visible.
+ *  - When a `PostToolUse` hook replaces `ToolMessage.content`, the
+ *    *post-hook* content is what gets stored in the registry (and
+ *    what the model sees), so `{{…}}` substitutions deliver the
+ *    hooked output rather than the raw tool return. This matches the
+ *    hook's "authoritative" role for output shaping.
+ */
+export type ToolOutputReferencesConfig = {
+    /** Enable the registry and placeholder substitution. Defaults to `false`. */
+    enabled?: boolean;
+    /**
+     * Maximum characters stored (and substituted) per registered output.
+     * Applied to the *raw* output before storage. Defaults to
+     * `HARD_MAX_TOOL_RESULT_CHARS` (~400 KB) — matching the
+     * LLM-visible tool-result truncation budget, which is also a safe
+     * payload size for shell `ARG_MAX` limits when a `{{…}}` expansion
+     * gets piped into a bash `command`. Hosts that want to preserve
+     * fuller fidelity (for example for non-bash API consumers) can
+     * raise this up to `maxTotalSize` (defaults to 5 MB) — be aware
+     * that large single-output substitutions may exceed shell
+     * argument-size limits on typical Linux/macOS.
+     */
+    maxOutputSize?: number;
+    /**
+     * Hard cap on total characters retained across all registered outputs
+     * for the run. When exceeded, the oldest entries are evicted FIFO
+     * until the total fits. The effective per-output cap is
+     * `min(maxOutputSize, maxTotalSize)` so a single stored output can
+     * never exceed the aggregate bound. Defaults to
+     * `calculateMaxTotalToolOutputSize(maxOutputSize)` (5 MB).
+     */
+    maxTotalSize?: number;
+};
 export type ProgrammaticCache = {
     toolMap: ToolMap;
     toolDefs: LCTool[];
@@ -179,7 +279,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 +288,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 +364,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 +380,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/dist/types/utils/truncation.d.ts

@@ -10,6 +10,15 @@
  * larger than this is almost certainly a bug (e.g., dumping a binary file).
  */
 export declare const HARD_MAX_TOOL_RESULT_CHARS = 400000;
+/**
+ * Absolute hard cap on the aggregate size (characters) of all registered
+ * tool outputs kept for `{{tool<i>turn<n>}}` substitution. Set at 5 MB
+ * because the registry stores *raw, untruncated* tool output — full
+ * fidelity for piping into downstream bash/jq — so the budget needs
+ * enough headroom to keep a handful of large responses without
+ * ballooning unbounded.
+ */
+export declare const HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE = 5000000;
 /**
  * Computes the dynamic max tool result size based on the model's context window.
  * Uses 30% of the context window (in estimated characters, ~4 chars/token)
@@ -19,6 +28,18 @@ export declare const HARD_MAX_TOOL_RESULT_CHARS = 400000;
  * @returns Maximum allowed characters for a single tool result.
  */
 export declare function calculateMaxToolResultChars(contextWindowTokens?: number): number;
+/**
+ * Computes the default aggregate size (characters) for the tool output
+ * reference registry based on the per-output budget. Mirrors
+ * `calculateMaxToolResultChars`'s shape: a multiple of the per-output
+ * cap, clamped to `HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE`.
+ *
+ * @param maxOutputSize - Per-output maximum characters (e.g., the
+ *   ToolNode's `maxToolResultChars`). When omitted or non-positive,
+ *   falls back to the absolute total cap.
+ * @returns Maximum total characters retained across the registry.
+ */
+export declare function calculateMaxTotalToolOutputSize(maxOutputSize?: number): number;
 /**
  * Truncates a tool-call input (the arguments/payload of a tool_use block)
  * using head+tail strategy. Returns an object with `_truncated` (the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.1.68",
+  "version": "3.1.71-dev.0",
   "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",