@librechat/agents 3.1.70 → 3.1.71-dev.1

package/src/types/index.ts

@@ -1,6 +1,7 @@
 // src/types/index.ts
 export * from './graph';
 export * from './llm';
+export * from './messages';
 export * from './run';
 export * from './skill';
 export * from './stream';

package/src/types/messages.ts

@@ -2,3 +2,30 @@ import type Anthropic from '@anthropic-ai/sdk';
 import type { BaseMessage } from '@langchain/core/messages';
 export type AnthropicMessages = Array<AnthropicMessage | BaseMessage>;
 export type AnthropicMessage = Anthropic.MessageParam;
+
+/**
+ * Per-message ref metadata stamped onto a `ToolMessage` at execution
+ * time. Read by `annotateMessagesForLLM` to apply transient annotation
+ * to a copy of the message right before it goes on the wire to the
+ * provider. Never read after the run-scoped registry has been cleared.
+ *
+ * Lives in `ToolMessage.additional_kwargs`. LangChain's provider
+ * serializers don't transmit `additional_kwargs` to provider APIs, so
+ * the metadata never leaks even if you forget to clean it.
+ */
+export interface ToolMessageRefMetadata {
+  /** Key under which this message's untruncated output was registered. */
+  _refKey?: string;
+  /**
+   * Registry bucket scope under which `_refKey` was stored. For named
+   * runs this equals `config.configurable.run_id`; for anonymous
+   * invocations (no `run_id`) ToolNode mints a per-batch synthetic
+   * scope (`\0anon-<n>`) so concurrent batches don't collide. Stamping
+   * the scope on the message itself lets `annotateMessagesForLLM`
+   * recover it without re-deriving from config — which is impossible
+   * for the anonymous case, since the scope is internal to ToolNode.
+   */
+  _refScope?: string;
+  /** Placeholders the model used that could not be resolved this batch. */
+  _unresolvedRefs?: string[];
+}

package/src/types/run.ts

@@ -11,7 +11,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';
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -146,6 +146,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 =

package/src/types/tools.ts

@@ -3,6 +3,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 */
@@ -62,6 +63,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;
@@ -234,6 +251,60 @@ 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[] };
 
 /** Search mode: code_interpreter uses external sandbox, local uses safe substring matching */

package/src/utils/__tests__/truncation.test.ts

@@ -0,0 +1,66 @@
+import { describe, it, expect } from '@jest/globals';
+import {
+  HARD_MAX_TOOL_RESULT_CHARS,
+  HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE,
+  calculateMaxToolResultChars,
+  calculateMaxTotalToolOutputSize,
+} from '@/utils/truncation';
+
+describe('truncation helpers', () => {
+  describe('calculateMaxToolResultChars', () => {
+    it('returns the hard cap when context tokens are missing', () => {
+      expect(calculateMaxToolResultChars()).toBe(HARD_MAX_TOOL_RESULT_CHARS);
+      expect(calculateMaxToolResultChars(undefined)).toBe(
+        HARD_MAX_TOOL_RESULT_CHARS
+      );
+      expect(calculateMaxToolResultChars(0)).toBe(HARD_MAX_TOOL_RESULT_CHARS);
+      expect(calculateMaxToolResultChars(-100)).toBe(
+        HARD_MAX_TOOL_RESULT_CHARS
+      );
+    });
+
+    it('computes 30% of context-window characters for normal inputs', () => {
+      // 100k tokens * 0.3 = 30k tokens * 4 chars/token = 120k chars
+      expect(calculateMaxToolResultChars(100_000)).toBe(120_000);
+    });
+
+    it('clamps to the hard cap for large context windows', () => {
+      // 1M tokens * 0.3 * 4 = 1.2M chars, exceeds 400k cap
+      expect(calculateMaxToolResultChars(1_000_000)).toBe(
+        HARD_MAX_TOOL_RESULT_CHARS
+      );
+    });
+  });
+
+  describe('calculateMaxTotalToolOutputSize', () => {
+    it('returns the absolute hard cap when no per-output is provided', () => {
+      expect(calculateMaxTotalToolOutputSize()).toBe(
+        HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE
+      );
+      expect(calculateMaxTotalToolOutputSize(0)).toBe(
+        HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE
+      );
+      expect(calculateMaxTotalToolOutputSize(-1)).toBe(
+        HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE
+      );
+    });
+
+    it('doubles the per-output cap by default', () => {
+      expect(calculateMaxTotalToolOutputSize(100_000)).toBe(200_000);
+      expect(calculateMaxTotalToolOutputSize(1)).toBe(2);
+    });
+
+    it('clamps the doubled value to HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE', () => {
+      // 4M * 2 = 8M, exceeds 5M
+      expect(calculateMaxTotalToolOutputSize(4_000_000)).toBe(
+        HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE
+      );
+      // Right at the boundary: 2.5M * 2 = 5M (no clamp).
+      expect(calculateMaxTotalToolOutputSize(2_500_000)).toBe(5_000_000);
+      // Just past it: 2_500_001 * 2 = 5_000_002 -> clamped.
+      expect(calculateMaxTotalToolOutputSize(2_500_001)).toBe(
+        HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE
+      );
+    });
+  });
+});

package/src/utils/truncation.ts

@@ -12,6 +12,16 @@
  */
 export const HARD_MAX_TOOL_RESULT_CHARS = 400_000;
 
+/**
+ * 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 const HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE = 5_000_000;
+
 /**
  * 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)
@@ -32,6 +42,26 @@ export function calculateMaxToolResultChars(
   );
 }
 
+/**
+ * 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 function calculateMaxTotalToolOutputSize(
+  maxOutputSize?: number
+): number {
+  if (maxOutputSize == null || maxOutputSize <= 0) {
+    return HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE;
+  }
+  return Math.min(maxOutputSize * 2, HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE);
+}
+
 /**
  * Truncates a tool-call input (the arguments/payload of a tool_use block)
  * using head+tail strategy. Returns an object with `_truncated` (the