@librechat/agents 3.1.70 → 3.1.71-dev.0

package/dist/types/run.d.ts

@@ -10,6 +10,7 @@ export declare class Run<_T extends t.BaseGraphState> {
     private tokenCounter?;
     private handlerRegistry?;
     private hookRegistry?;
+    private toolOutputReferences?;
     private indexTokenCountMap?;
     calibrationRatio: number;
     graphRunnable?: t.CompiledStateWorkflow;

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

@@ -19,7 +19,38 @@ export declare const BashExecutionToolSchema: {
     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;

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?;
@@ -30,7 +47,36 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
     private maxToolResultChars;
     /** 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);
+    /**
+     * 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.
@@ -42,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): Promise<BaseMessage | Command>;
+    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.
+     */
+    private applyOutputReference;
     /**
      * Builds code session context for injection into event-driven tool calls.
      * Mirrors the session injection logic in runTool() for direct execution.
@@ -63,6 +136,10 @@ 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;
     /**
@@ -93,6 +170,11 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      * 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>;
@@ -100,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/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/run.d.ts

@@ -7,7 +7,7 @@ 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 { ToolSessionMap, ToolOutputReferencesConfig } from '@/types/tools';
 import type { HookRegistry } from '@/hooks';
 export type ZodObjectAny = z.ZodObject<any, any, any, any>;
 export type BaseGraphConfig = {
@@ -134,6 +134,14 @@ export type RunConfig = {
      * 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/tools.d.ts

@@ -2,6 +2,7 @@ import type { StructuredToolInterface } from '@langchain/core/tools';
 import type { RunnableToolLike } from '@langchain/core/runnables';
 import type { ToolCall } from '@langchain/core/messages/tool';
 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 = {
@@ -52,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 = {
@@ -199,6 +216,59 @@ export type ToolExecuteResult = {
 };
 /** 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[];

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.70",
+  "version": "3.1.71-dev.0",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",

package/src/graphs/Graph.ts

@@ -43,6 +43,7 @@ import {
 import { SubagentExecutor, resolveSubagentConfigs } from '@/tools/subagent';
 import { buildSubagentToolParams } from '@/tools/SubagentTool';
 import { ToolNode as CustomToolNode, toolsCondition } from '@/tools/ToolNode';
+import { ToolOutputReferenceRegistry } from '@/tools/toolOutputReferences';
 import { safeDispatchCustomEvent, emitAgentLog } from '@/utils/events';
 import { attemptInvoke, tryFallbackProviders } from '@/llm/invoke';
 import { shouldTriggerSummarization } from '@/summarization';
@@ -128,6 +129,19 @@ export abstract class Graph<
   invokedToolIds?: Set<string>;
   handlerRegistry: HandlerRegistry | undefined;
   hookRegistry: HookRegistry | undefined;
+  /**
+   * Run-scoped config for the tool output reference registry. Threaded
+   * from `RunConfig.toolOutputReferences` down into every ToolNode this
+   * graph compiles.
+   */
+  toolOutputReferences: t.ToolOutputReferencesConfig | undefined;
+  /**
+   * Shared registry instance used by every ToolNode compiled from this
+   * graph. Lazily constructed on first access so multi-agent graphs
+   * produce one registry per run (not one per agent), letting cross-
+   * agent `{{tool<i>turn<n>}}` substitutions resolve.
+   */
+  private _toolOutputRegistry?: ToolOutputReferenceRegistry;
   /**
    * Tool session contexts for automatic state persistence across tool invocations.
    * Keyed by tool name (e.g., Constants.EXECUTE_CODE).
@@ -153,8 +167,40 @@ export abstract class Graph<
     this.invokedToolIds = undefined;
     this.handlerRegistry = undefined;
     this.hookRegistry = undefined;
+    this.toolOutputReferences = undefined;
+    /**
+     * ToolNodes compiled from this graph captured the registry
+     * instance at construction time, so simply dropping the Graph's
+     * own reference would leave their captured reference — and every
+     * stored `tool<i>turn<n>` entry, plus up to `maxTotalSize` of raw
+     * output — alive across subsequent `processStream()` calls. Wipe
+     * the registry's contents first so subsequent runs start fresh.
+     */
+    this._toolOutputRegistry?.clear();
+    this._toolOutputRegistry = undefined;
     this.sessions.clear();
   }
+
+  /**
+   * Returns the shared `ToolOutputReferenceRegistry` for this run,
+   * constructing it on first access. Returns `undefined` when the
+   * feature is disabled. All ToolNodes compiled from this graph share
+   * this single instance so cross-agent `{{…}}` references resolve.
+   */
+  protected getOrCreateToolOutputRegistry():
+    | ToolOutputReferenceRegistry
+    | undefined {
+    if (this.toolOutputReferences?.enabled !== true) {
+      return undefined;
+    }
+    if (this._toolOutputRegistry == null) {
+      this._toolOutputRegistry = new ToolOutputReferenceRegistry({
+        maxOutputSize: this.toolOutputReferences.maxOutputSize,
+        maxTotalSize: this.toolOutputReferences.maxTotalSize,
+      });
+    }
+    return this._toolOutputRegistry;
+  }
 }
 
 export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
@@ -516,6 +562,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         directToolNames: directToolNames.size > 0 ? directToolNames : undefined,
         maxContextTokens: agentContext?.maxContextTokens,
         maxToolResultChars: agentContext?.maxToolResultChars,
+        toolOutputRegistry: this.getOrCreateToolOutputRegistry(),
         errorHandler: (data, metadata) =>
           StandardGraph.handleToolCallErrorStatic(this, data, metadata),
       });
@@ -547,6 +594,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       sessions: this.sessions,
       maxContextTokens: agentContext?.maxContextTokens,
       maxToolResultChars: agentContext?.maxToolResultChars,
+      toolOutputRegistry: this.getOrCreateToolOutputRegistry(),
     });
   }
 

package/src/messages/prune.ts

@@ -683,10 +683,17 @@ export function getMessagesWithinTokenLimit({
         ) as ThinkingContentText | undefined;
         thinkingStartIndex = thinkingBlock != null ? currentIndex : -1;
       }
-      /** False start, the latest message was not part of a multi-assistant/tool sequence of messages */
+      /**
+       * Exited the trailing assistant/tool sequence without finding a
+       * thinking block. Anthropic does not require Claude to emit a
+       * thinking block before every tool call, so the absence of one is
+       * a valid sequence — clear thinkingEndIndex so the pruner does not
+       * treat it as malformed.
+       */
       if (
         thinkingEndIndex > -1 &&
-        currentIndex === thinkingEndIndex - 1 &&
+        thinkingStartIndex < 0 &&
+        !thinkingBlock &&
         messageType !== 'ai' &&
         messageType !== 'tool'
       ) {