@librechat/agents 3.1.71-dev.0 → 3.1.71

package/dist/esm/tools/toolOutputReferences.mjs

@@ -1,3 +1,4 @@
+import { ToolMessage } from '@langchain/core/messages';
 import { HARD_MAX_TOOL_RESULT_CHARS, HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE, calculateMaxTotalToolOutputSize } from '../utils/truncation.mjs';
 
 /**
@@ -163,6 +164,15 @@ class ToolOutputReferenceRegistry {
     get(runId, key) {
         return this.runStates.get(this.keyFor(runId))?.entries.get(key);
     }
+    /**
+     * Returns `true` when `key` is currently stored in `runId`'s bucket.
+     * Used by {@link annotateMessagesForLLM} to gate transient annotation
+     * on whether the registry still owns the referenced output (a stale
+     * `_refKey` from a prior run silently no-ops here).
+     */
+    has(runId, key) {
+        return this.runStates.get(this.keyFor(runId))?.entries.has(key) ?? false;
+    }
     /** Total number of registered outputs across every run bucket. */
     get size() {
         let n = 0;
@@ -463,6 +473,190 @@ function arraysShallowEqual(a, b) {
     }
     return true;
 }
+/**
+ * Lazy projection that, given a registry and a runId, returns a new
+ * `messages` array where each `ToolMessage` carrying ref metadata is
+ * projected into a transient copy with annotated content (when the ref
+ * is live in the registry) and with the framework-owned `additional_
+ * kwargs` keys (`_refKey`, `_refScope`, `_unresolvedRefs`) stripped
+ * regardless of whether annotation applied. The original input array
+ * and its messages are never mutated.
+ *
+ * Annotation is gated on registry presence: a stale `_refKey` from a
+ * prior run (e.g. one that survived in persisted history) silently
+ * no-ops on the *content* side. The strip-metadata side still runs so
+ * stale framework keys never leak onto the wire under any custom or
+ * future provider serializer that might transmit `additional_kwargs`.
+ * `_unresolvedRefs` is always meaningful and is not gated.
+ *
+ * **Feature-disabled fast path:** when the host hasn't enabled the
+ * tool-output-reference feature, the registry is `undefined` and this
+ * function returns the input array reference-equal *without iterating
+ * a single message*. The loop is exclusive to the feature-enabled
+ * code path.
+ */
+function annotateMessagesForLLM(messages, registry, runId) {
+    if (registry == null)
+        return messages;
+    /**
+     * Lazy-allocate the output array so the common case (no ToolMessage
+     * carries framework metadata) returns the input reference-equal with
+     * zero allocations beyond the per-message predicate checks.
+     */
+    let out;
+    for (let i = 0; i < messages.length; i++) {
+        const m = messages[i];
+        if (m._getType() !== 'tool')
+            continue;
+        /**
+         * `additional_kwargs` is untyped at the LangChain layer
+         * (`Record<string, unknown>`), so persisted or client-supplied
+         * ToolMessages can carry arbitrary shapes — including primitives
+         * (a malformed serializer might write a string, or `null`).
+         * Guard with a runtime object check before the `in` probes
+         * because the `in` operator throws `TypeError` on primitives.
+         * A single malformed message must never crash the provider call
+         * path; skip its annotation/strip and continue.
+         */
+        const rawMeta = m.additional_kwargs;
+        if (rawMeta == null || typeof rawMeta !== 'object')
+            continue;
+        const meta = rawMeta;
+        const hasRefKey = '_refKey' in meta;
+        const hasRefScope = '_refScope' in meta;
+        const hasUnresolvedField = '_unresolvedRefs' in meta;
+        if (!hasRefKey && !hasRefScope && !hasUnresolvedField)
+            continue;
+        const refKey = readRefKey(meta);
+        const unresolved = readUnresolvedRefs(meta);
+        /**
+         * Prefer the message-stamped `_refScope` for the registry lookup.
+         * For named runs it equals the current `runId`; for anonymous
+         * invocations it carries the per-batch synthetic scope minted by
+         * ToolNode (`\0anon-<n>`), which `runId` from config cannot
+         * recover. Falling back to `runId` keeps backward compatibility
+         * with messages stamped before this field existed.
+         */
+        const lookupScope = readRefScope(meta) ?? runId;
+        const liveRef = refKey != null && registry.has(lookupScope, refKey) ? refKey : undefined;
+        const annotates = liveRef != null || unresolved.length > 0;
+        const tm = m;
+        let nextContent = tm.content;
+        if (annotates && typeof tm.content === 'string') {
+            nextContent = annotateToolOutputWithReference(tm.content, liveRef, unresolved);
+        }
+        else if (annotates &&
+            Array.isArray(tm.content) &&
+            unresolved.length > 0) {
+            const warningBlock = {
+                type: 'text',
+                text: `[unresolved refs: ${unresolved.join(', ')}]`,
+            };
+            /**
+             * `as unknown as ToolMessage['content']` is unavoidable here:
+             * LangChain's content union (`MessageContentComplex[] |
+             * DataContentBlock[] | string`) does not accept a freshly built
+             * mixed array literal even though the structural shape is valid
+             * at runtime. The double-cast is structurally safe — we
+             * preserve every block from `tm.content` and prepend a single
+             * `{ type: 'text', text }` block that all providers accept.
+             */
+            nextContent = [
+                warningBlock,
+                ...tm.content,
+            ];
+        }
+        /**
+         * Project unconditionally: even when no annotation applies (stale
+         * `_refKey` or non-annotatable content), `cloneToolMessageWithContent`
+         * runs `stripFrameworkRefMetadata` on `additional_kwargs` so the
+         * framework-owned keys never reach the wire.
+         */
+        out ??= messages.slice();
+        out[i] = cloneToolMessageWithContent(tm, nextContent);
+    }
+    return out ?? messages;
+}
+/**
+ * Reads `_refKey` defensively from untyped `additional_kwargs`. Returns
+ * undefined for non-string values so a malformed field cannot poison
+ * the registry lookup or downstream string operations.
+ */
+function readRefKey(meta) {
+    const v = meta?._refKey;
+    return typeof v === 'string' ? v : undefined;
+}
+/**
+ * Reads `_refScope` defensively from untyped `additional_kwargs`.
+ * Mirrors {@link readRefKey} — non-string scopes are dropped (the
+ * caller falls back to the run-derived scope) rather than passed into
+ * the registry as a malformed key.
+ */
+function readRefScope(meta) {
+    const v = meta?._refScope;
+    return typeof v === 'string' ? v : undefined;
+}
+/**
+ * Reads `_unresolvedRefs` defensively from untyped `additional_kwargs`.
+ * Returns an empty array for any non-array value, and filters out
+ * non-string entries from a real array. Without this guard, a hydrated
+ * ToolMessage carrying e.g. `_unresolvedRefs: 'tool0turn0'` would crash
+ * `attemptInvoke` on the eventual `.length` / `.join(...)` call.
+ */
+function readUnresolvedRefs(meta) {
+    const v = meta?._unresolvedRefs;
+    if (!Array.isArray(v))
+        return [];
+    const out = [];
+    for (const item of v) {
+        if (typeof item === 'string')
+            out.push(item);
+    }
+    return out;
+}
+/**
+ * Builds a fresh `ToolMessage` that mirrors `tm`'s identity fields with
+ * the supplied `content`. Every `ToolMessage` field but `content` is
+ * carried over so the projection is structurally identical to the
+ * original from a LangChain serializer's perspective.
+ *
+ * `additional_kwargs` is rebuilt with the framework-owned ref keys
+ * stripped. Defensive: LangChain's standard provider serializers do not
+ * transmit `additional_kwargs` to provider HTTP APIs, but a custom
+ * adapter or future LangChain change could. Stripping keeps the
+ * implementation correct under any serializer behavior at the cost of a
+ * shallow object spread per annotated message.
+ */
+function cloneToolMessageWithContent(tm, content) {
+    return new ToolMessage({
+        id: tm.id,
+        name: tm.name,
+        status: tm.status,
+        artifact: tm.artifact,
+        tool_call_id: tm.tool_call_id,
+        response_metadata: tm.response_metadata,
+        additional_kwargs: stripFrameworkRefMetadata(tm.additional_kwargs),
+        content,
+    });
+}
+/**
+ * Returns a copy of `kwargs` with `_refKey`, `_refScope`, and
+ * `_unresolvedRefs` removed. Returns the input reference-equal when
+ * none of those keys are present so the no-strip path stays cheap;
+ * returns `undefined` when stripping leaves the object empty so the
+ * caller can drop the field entirely.
+ */
+function stripFrameworkRefMetadata(kwargs) {
+    if (kwargs == null)
+        return undefined;
+    if (!('_refKey' in kwargs) &&
+        !('_refScope' in kwargs) &&
+        !('_unresolvedRefs' in kwargs)) {
+        return kwargs;
+    }
+    const { _refKey, _refScope, _unresolvedRefs, ...rest } = kwargs;
+    return Object.keys(rest).length === 0 ? undefined : rest;
+}
 
-export { TOOL_OUTPUT_REF_KEY, TOOL_OUTPUT_UNRESOLVED_KEY, ToolOutputReferenceRegistry, annotateToolOutputWithReference, buildReferenceKey, buildReferencePrefix };
+export { TOOL_OUTPUT_REF_KEY, TOOL_OUTPUT_UNRESOLVED_KEY, ToolOutputReferenceRegistry, annotateMessagesForLLM, annotateToolOutputWithReference, buildReferenceKey, buildReferencePrefix };
 //# sourceMappingURL=toolOutputReferences.mjs.map

package/dist/esm/tools/toolOutputReferences.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"toolOutputReferences.mjs","sources":["../../../src/tools/toolOutputReferences.ts"],"sourcesContent":["/**\n * Tool output reference registry.\n *\n * When enabled via `RunConfig.toolOutputReferences.enabled`, ToolNode\n * stores each successful tool output under a stable key\n * (`tool<idx>turn<turn>`) where `idx` is the tool's position within a\n * ToolNode batch and `turn` is the batch index within the run\n * (incremented once per ToolNode invocation).\n *\n * Subsequent tool calls can pipe a previous output into their args by\n * embedding `{{tool<idx>turn<turn>}}` inside any string argument;\n * {@link ToolOutputReferenceRegistry.resolve} walks the args and\n * substitutes the placeholders immediately before invocation.\n *\n * The registry stores the *raw, untruncated* tool output so a later\n * `{{…}}` substitution pipes the full payload into the next tool —\n * even when the LLM only saw a head+tail-truncated preview in\n * `ToolMessage.content`. Outputs are stored without any annotation\n * (the `_ref` key or the `[ref: ...]` prefix seen by the LLM is\n * strictly a UX signal attached to `ToolMessage.content`). Keeping the\n * registry pristine means downstream bash/jq piping receives the\n * complete, verbatim output with no injected fields.\n */\n\nimport {\n  calculateMaxTotalToolOutputSize,\n  HARD_MAX_TOOL_RESULT_CHARS,\n  HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE,\n} from '@/utils/truncation';\n\n/**\n * Non-global matcher for a single `{{tool<i>turn<n>}}` placeholder.\n * Exported for consumers that want to detect references (e.g., syntax\n * highlighting, docs). The stateful `g` variant lives inside the\n * registry so nobody trips on `lastIndex`.\n */\nexport const TOOL_OUTPUT_REF_PATTERN = /\\{\\{(tool\\d+turn\\d+)\\}\\}/;\n\n/** Object key used when a parsed-object output has `_ref` injected. */\nexport const TOOL_OUTPUT_REF_KEY = '_ref';\n\n/**\n * Object key used to carry unresolved reference warnings on a parsed-\n * object output. Using a dedicated field instead of a trailing text\n * line keeps the annotated `ToolMessage.content` parseable as JSON for\n * downstream consumers that rely on the object shape.\n */\nexport const TOOL_OUTPUT_UNRESOLVED_KEY = '_unresolved_refs';\n\n/** Single-line prefix prepended to non-object tool outputs so the LLM sees the reference key. */\nexport function buildReferencePrefix(key: string): string {\n  return `[ref: ${key}]`;\n}\n\n/** Stable registry key for a tool output. */\nexport function buildReferenceKey(toolIndex: number, turn: number): string {\n  return `tool${toolIndex}turn${turn}`;\n}\n\nexport type ToolOutputReferenceRegistryOptions = {\n  /** Maximum characters stored per registered output. */\n  maxOutputSize?: number;\n  /** Maximum total characters retained across all registered outputs. */\n  maxTotalSize?: number;\n  /**\n   * Upper bound on the number of concurrently-tracked runs. When\n   * exceeded, the oldest run bucket is evicted (FIFO). Defaults to 32.\n   */\n  maxActiveRuns?: number;\n};\n\n/**\n * Result of resolving placeholders in tool args.\n */\nexport type ResolveResult<T> = {\n  /** Arguments with placeholders replaced. Same shape as the input. */\n  resolved: T;\n  /** Reference keys that were referenced but had no stored value. */\n  unresolved: string[];\n};\n\n/**\n * Read-only view over a frozen registry snapshot. Returned by\n * {@link ToolOutputReferenceRegistry.snapshot} for callers that need\n * to resolve placeholders against the registry state at a specific\n * point in time, ignoring any subsequent registrations.\n */\nexport interface ToolOutputResolveView {\n  resolve<T>(args: T): ResolveResult<T>;\n}\n\n/**\n * Pre-resolved arg map keyed by `toolCallId`. Used by the mixed\n * direct+event dispatch path to feed event calls' resolved args\n * (captured pre-batch) into the dispatcher without re-resolving\n * against the now-stale live registry.\n */\nexport type PreResolvedArgsMap = Map<\n  string,\n  { resolved: Record<string, unknown>; unresolved: string[] }\n>;\n\n/**\n * Per-call sink for resolved args, keyed by `toolCallId`. Threaded\n * as a per-batch local map so concurrent `ToolNode.run()` calls do\n * not race on shared sink state.\n */\nexport type ResolvedArgsByCallId = Map<string, Record<string, unknown>>;\n\nconst EMPTY_ENTRIES: ReadonlyMap<string, string> = new Map<string, string>();\n\n/**\n * Per-run state bucket held inside the registry. Each distinct\n * `run_id` gets its own bucket so overlapping concurrent runs on a\n * shared registry cannot leak outputs, turn counters, or warn-memos\n * into one another.\n */\nclass RunStateBucket {\n  entries: Map<string, string> = new Map();\n  totalSize: number = 0;\n  turnCounter: number = 0;\n  warnedNonStringTools: Set<string> = new Set();\n}\n\n/**\n * Anonymous (`run_id` absent) bucket key. Anonymous batches are\n * treated as fresh runs on every invocation — see `nextTurn`.\n */\nconst ANON_RUN_KEY = '\\0anon';\n\n/**\n * Default upper bound on the number of concurrently-tracked runs per\n * registry. When exceeded, the oldest run's bucket (by insertion\n * order) is evicted. Keeps memory bounded when a ToolNode is reused\n * across many runs without explicit `releaseRun` calls.\n */\nconst DEFAULT_MAX_ACTIVE_RUNS = 32;\n\n/**\n * Ordered map of reference-key → stored output, partitioned by run so\n * concurrent / interleaved runs sharing one registry cannot leak\n * outputs between each other.\n *\n * Each public method takes a `runId` which selects the run's bucket.\n * Hosts typically get one registry per run via `Graph`, in which\n * case only a single bucket is ever populated; the partitioning\n * exists so the registry also behaves correctly when a single\n * instance is reused directly.\n */\nexport class ToolOutputReferenceRegistry {\n  private runStates: Map<string, RunStateBucket> = new Map();\n  private readonly maxOutputSize: number;\n  private readonly maxTotalSize: number;\n  private readonly maxActiveRuns: number;\n  /**\n   * Local stateful matcher used only by `replaceInString`. Kept\n   * off-module so callers of the exported `TOOL_OUTPUT_REF_PATTERN`\n   * never see a stale `lastIndex`.\n   */\n  private static readonly PLACEHOLDER_MATCHER = /\\{\\{(tool\\d+turn\\d+)\\}\\}/g;\n\n  constructor(options: ToolOutputReferenceRegistryOptions = {}) {\n    /**\n     * Per-output default is the same ~400 KB budget as the standard\n     * tool-result truncation (`HARD_MAX_TOOL_RESULT_CHARS`). This\n     * keeps a single `{{…}}` substitution at a size that is safe to\n     * pass through typical shell `ARG_MAX` limits and matches what\n     * the LLM would otherwise have seen. Hosts that want larger per-\n     * output payloads (API consumers, long JSON streams) can raise\n     * the cap explicitly up to the 5 MB total budget.\n     */\n    const perOutput =\n      options.maxOutputSize != null && options.maxOutputSize > 0\n        ? options.maxOutputSize\n        : HARD_MAX_TOOL_RESULT_CHARS;\n    /**\n     * Clamp a caller-supplied `maxTotalSize` to\n     * `HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE` (5 MB) so the documented\n     * absolute cap is enforced regardless of host config —\n     * `calculateMaxTotalToolOutputSize` already applies the same\n     * upper bound on its computed default, but the user-provided\n     * branch was bypassing it.\n     */\n    const totalRaw =\n      options.maxTotalSize != null && options.maxTotalSize > 0\n        ? Math.min(options.maxTotalSize, HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE)\n        : calculateMaxTotalToolOutputSize(perOutput);\n    this.maxTotalSize = totalRaw;\n    /**\n     * The per-output cap can never exceed the per-run aggregate cap:\n     * if a single entry were allowed to be larger than `maxTotalSize`,\n     * the eviction loop would either blow the cap (to keep the entry)\n     * or self-evict a just-stored value. Clamping here turns\n     * `maxTotalSize` into a hard upper bound on *any* state the\n     * registry retains per run.\n     */\n    this.maxOutputSize = Math.min(perOutput, totalRaw);\n    this.maxActiveRuns =\n      options.maxActiveRuns != null && options.maxActiveRuns > 0\n        ? options.maxActiveRuns\n        : DEFAULT_MAX_ACTIVE_RUNS;\n  }\n\n  private keyFor(runId: string | undefined): string {\n    return runId ?? ANON_RUN_KEY;\n  }\n\n  private getOrCreate(runId: string | undefined): RunStateBucket {\n    const key = this.keyFor(runId);\n    let state = this.runStates.get(key);\n    if (state == null) {\n      state = new RunStateBucket();\n      this.runStates.set(key, state);\n      if (this.runStates.size > this.maxActiveRuns) {\n        const oldest = this.runStates.keys().next().value;\n        if (oldest != null && oldest !== key) {\n          this.runStates.delete(oldest);\n        }\n      }\n    }\n    return state;\n  }\n\n  /** Registers (or replaces) the output stored under `key` for `runId`. */\n  set(runId: string | undefined, key: string, value: string): void {\n    const bucket = this.getOrCreate(runId);\n    const clipped =\n      value.length > this.maxOutputSize\n        ? value.slice(0, this.maxOutputSize)\n        : value;\n    const existing = bucket.entries.get(key);\n    if (existing != null) {\n      bucket.totalSize -= existing.length;\n      bucket.entries.delete(key);\n    }\n    bucket.entries.set(key, clipped);\n    bucket.totalSize += clipped.length;\n    this.evictWithinBucket(bucket);\n  }\n\n  /** Returns the stored value for `key` in `runId`'s bucket, or `undefined`. */\n  get(runId: string | undefined, key: string): string | undefined {\n    return this.runStates.get(this.keyFor(runId))?.entries.get(key);\n  }\n\n  /** Total number of registered outputs across every run bucket. */\n  get size(): number {\n    let n = 0;\n    for (const bucket of this.runStates.values()) {\n      n += bucket.entries.size;\n    }\n    return n;\n  }\n\n  /** Maximum characters retained per output (post-clip). */\n  get perOutputLimit(): number {\n    return this.maxOutputSize;\n  }\n\n  /** Maximum total characters retained *per run*. */\n  get totalLimit(): number {\n    return this.maxTotalSize;\n  }\n\n  /** Drops every run's state. */\n  clear(): void {\n    this.runStates.clear();\n  }\n\n  /**\n   * Explicitly release `runId`'s state. Safe to call when a run has\n   * finished. Hosts sharing one registry across runs should call this\n   * to reclaim memory deterministically; otherwise LRU eviction kicks\n   * in when `maxActiveRuns` runs accumulate.\n   */\n  releaseRun(runId: string | undefined): void {\n    this.runStates.delete(this.keyFor(runId));\n  }\n\n  /**\n   * Claims the next batch turn synchronously from `runId`'s bucket.\n   *\n   * Must be called once at the start of each ToolNode batch before\n   * any `await`, so concurrent invocations within the same run see\n   * distinct turn values (reads are effectively atomic by JS's\n   * single-threaded execution of the sync prefix).\n   *\n   * If `runId` is missing the anonymous bucket is dropped and a\n   * fresh one created so each anonymous call behaves as its own run.\n   */\n  nextTurn(runId: string | undefined): number {\n    if (runId == null) {\n      this.runStates.delete(ANON_RUN_KEY);\n    }\n    const bucket = this.getOrCreate(runId);\n    return bucket.turnCounter++;\n  }\n\n  /**\n   * Records that `toolName` has been warned about in `runId` (returns\n   * `true` on the first call per run, `false` after). Used by\n   * ToolNode to emit one log line per offending tool per run when a\n   * `ToolMessage.content` isn't a string.\n   */\n  claimWarnOnce(runId: string | undefined, toolName: string): boolean {\n    const bucket = this.getOrCreate(runId);\n    if (bucket.warnedNonStringTools.has(toolName)) {\n      return false;\n    }\n    bucket.warnedNonStringTools.add(toolName);\n    return true;\n  }\n\n  /**\n   * Walks `args` and replaces every `{{tool<i>turn<n>}}` placeholder in\n   * string values with the stored output *from `runId`'s bucket*. Non-\n   * string values and object keys are left untouched. Unresolved\n   * references are left in-place and reported so the caller can\n   * surface them to the LLM. When no placeholder appears anywhere in\n   * the serialized args, the original input is returned without\n   * walking the tree.\n   */\n  resolve<T>(runId: string | undefined, args: T): ResolveResult<T> {\n    if (!hasAnyPlaceholder(args)) {\n      return { resolved: args, unresolved: [] };\n    }\n    const bucket = this.runStates.get(this.keyFor(runId));\n    return this.resolveAgainst(bucket?.entries ?? EMPTY_ENTRIES, args);\n  }\n\n  /**\n   * Captures a frozen snapshot of `runId`'s current entries and\n   * returns a view that resolves placeholders against *only* that\n   * snapshot. The snapshot is decoupled from the live registry, so\n   * subsequent `set()` calls (for example, same-turn direct outputs\n   * registering while an event branch is still in flight) are\n   * invisible to the snapshot's `resolve`. Used by the mixed\n   * direct+event dispatch path to preserve same-turn isolation when\n   * a `PreToolUse` hook rewrites event args after directs have\n   * completed.\n   */\n  snapshot(runId: string | undefined): ToolOutputResolveView {\n    const bucket = this.runStates.get(this.keyFor(runId));\n    const entries: ReadonlyMap<string, string> = bucket\n      ? new Map(bucket.entries)\n      : EMPTY_ENTRIES;\n    return {\n      resolve: <T>(args: T): ResolveResult<T> =>\n        this.resolveAgainst(entries, args),\n    };\n  }\n\n  private resolveAgainst<T>(\n    entries: ReadonlyMap<string, string>,\n    args: T\n  ): ResolveResult<T> {\n    if (!hasAnyPlaceholder(args)) {\n      return { resolved: args, unresolved: [] };\n    }\n    const unresolved = new Set<string>();\n    const resolved = this.transform(entries, args, unresolved) as T;\n    return { resolved, unresolved: Array.from(unresolved) };\n  }\n\n  private transform(\n    entries: ReadonlyMap<string, string>,\n    value: unknown,\n    unresolved: Set<string>\n  ): unknown {\n    if (typeof value === 'string') {\n      return this.replaceInString(entries, value, unresolved);\n    }\n    if (Array.isArray(value)) {\n      return value.map((item) => this.transform(entries, item, unresolved));\n    }\n    if (value !== null && typeof value === 'object') {\n      const source = value as Record<string, unknown>;\n      const next: Record<string, unknown> = {};\n      for (const [key, item] of Object.entries(source)) {\n        next[key] = this.transform(entries, item, unresolved);\n      }\n      return next;\n    }\n    return value;\n  }\n\n  private replaceInString(\n    entries: ReadonlyMap<string, string>,\n    input: string,\n    unresolved: Set<string>\n  ): string {\n    if (input.indexOf('{{tool') === -1) {\n      return input;\n    }\n    return input.replace(\n      ToolOutputReferenceRegistry.PLACEHOLDER_MATCHER,\n      (match, key: string) => {\n        const stored = entries.get(key);\n        if (stored == null) {\n          unresolved.add(key);\n          return match;\n        }\n        return stored;\n      }\n    );\n  }\n\n  private evictWithinBucket(bucket: RunStateBucket): void {\n    if (bucket.totalSize <= this.maxTotalSize) {\n      return;\n    }\n    for (const key of bucket.entries.keys()) {\n      if (bucket.totalSize <= this.maxTotalSize) {\n        return;\n      }\n      const entry = bucket.entries.get(key);\n      if (entry == null) {\n        continue;\n      }\n      bucket.totalSize -= entry.length;\n      bucket.entries.delete(key);\n    }\n  }\n}\n\n/**\n * Cheap pre-check: returns true if any string value in `args` contains\n * the `{{tool` substring. Lets `resolve()` skip the deep tree walk (and\n * its object allocations) for the common case of plain args.\n */\nfunction hasAnyPlaceholder(value: unknown): boolean {\n  if (typeof value === 'string') {\n    return value.indexOf('{{tool') !== -1;\n  }\n  if (Array.isArray(value)) {\n    for (const item of value) {\n      if (hasAnyPlaceholder(item)) {\n        return true;\n      }\n    }\n    return false;\n  }\n  if (value !== null && typeof value === 'object') {\n    for (const item of Object.values(value as Record<string, unknown>)) {\n      if (hasAnyPlaceholder(item)) {\n        return true;\n      }\n    }\n    return false;\n  }\n  return false;\n}\n\n/**\n * Annotates `content` with a reference key and/or unresolved-ref\n * warnings so the LLM sees both alongside the tool output.\n *\n * Behavior:\n *  - If `content` parses as a plain (non-array, non-null) JSON object\n *    and the object does not already have a conflicting `_ref` key,\n *    the reference key and (when present) `_unresolved_refs` array\n *    are injected as object fields, preserving JSON validity for\n *    downstream consumers that parse the output.\n *  - Otherwise (string output, JSON array/primitive, parse failure,\n *    or `_ref` collision), a `[ref: <key>]\\n` prefix line is\n *    prepended and unresolved refs are appended as a trailing\n *    `[unresolved refs: …]` line.\n *\n * The annotated string is what the LLM sees as `ToolMessage.content`.\n * The *original* (un-annotated) value is what gets stored in the\n * registry, so downstream piping remains pristine.\n *\n * @param content     Raw (post-truncation) tool output.\n * @param key         Reference key for this output, or undefined when\n *                    there is nothing to register (errors etc.).\n * @param unresolved  Reference keys that failed to resolve during\n *                    argument substitution. Surfaced so the LLM can\n *                    self-correct its next tool call.\n */\nexport function annotateToolOutputWithReference(\n  content: string,\n  key: string | undefined,\n  unresolved: string[] = []\n): string {\n  const hasRefKey = key != null;\n  const hasUnresolved = unresolved.length > 0;\n  if (!hasRefKey && !hasUnresolved) {\n    return content;\n  }\n  const trimmed = content.trimStart();\n  if (trimmed.startsWith('{')) {\n    const annotated = tryInjectRefIntoJsonObject(content, key, unresolved);\n    if (annotated != null) {\n      return annotated;\n    }\n  }\n  const prefix = hasRefKey ? `${buildReferencePrefix(key!)}\\n` : '';\n  const trailer = hasUnresolved\n    ? `\\n[unresolved refs: ${unresolved.join(', ')}]`\n    : '';\n  return `${prefix}${content}${trailer}`;\n}\n\nfunction tryInjectRefIntoJsonObject(\n  content: string,\n  key: string | undefined,\n  unresolved: string[]\n): string | null {\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(content);\n  } catch {\n    return null;\n  }\n\n  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {\n    return null;\n  }\n\n  const obj = parsed as Record<string, unknown>;\n  const injectingRef = key != null;\n  const injectingUnresolved = unresolved.length > 0;\n\n  /**\n   * Reject the JSON-injection path (fall back to prefix form) when\n   * either of our keys collides with real payload data:\n   *  - `_ref` collision: existing value is non-null and differs from\n   *    the key we're about to inject.\n   *  - `_unresolved_refs` collision: existing value is non-null and\n   *    is not a deep-equal match for the array we'd inject.\n   * This keeps us from silently overwriting legitimate tool output.\n   */\n  if (\n    injectingRef &&\n    TOOL_OUTPUT_REF_KEY in obj &&\n    obj[TOOL_OUTPUT_REF_KEY] !== key &&\n    obj[TOOL_OUTPUT_REF_KEY] != null\n  ) {\n    return null;\n  }\n  if (\n    injectingUnresolved &&\n    TOOL_OUTPUT_UNRESOLVED_KEY in obj &&\n    obj[TOOL_OUTPUT_UNRESOLVED_KEY] != null &&\n    !arraysShallowEqual(obj[TOOL_OUTPUT_UNRESOLVED_KEY], unresolved)\n  ) {\n    return null;\n  }\n\n  /**\n   * Only strip the framework-owned key we're actually injecting —\n   * leave everything else (including a pre-existing `_ref` on the\n   * unresolved-only path, or a pre-existing `_unresolved_refs` on a\n   * plain-annotation path) untouched so we annotate rather than\n   * mutate downstream payload data. Our injected keys land first in\n   * the serialized JSON so the LLM sees them before the body.\n   */\n  const omitKeys = new Set<string>();\n  if (injectingRef) omitKeys.add(TOOL_OUTPUT_REF_KEY);\n  if (injectingUnresolved) omitKeys.add(TOOL_OUTPUT_UNRESOLVED_KEY);\n  const rest: Record<string, unknown> = {};\n  for (const [k, v] of Object.entries(obj)) {\n    if (!omitKeys.has(k)) {\n      rest[k] = v;\n    }\n  }\n  const injected: Record<string, unknown> = {};\n  if (injectingRef) {\n    injected[TOOL_OUTPUT_REF_KEY] = key;\n  }\n  if (injectingUnresolved) {\n    injected[TOOL_OUTPUT_UNRESOLVED_KEY] = unresolved;\n  }\n  Object.assign(injected, rest);\n\n  const pretty = /^\\{\\s*\\n/.test(content);\n  return pretty ? JSON.stringify(injected, null, 2) : JSON.stringify(injected);\n}\n\nfunction arraysShallowEqual(a: unknown, b: readonly string[]): boolean {\n  if (!Array.isArray(a) || a.length !== b.length) {\n    return false;\n  }\n  for (let i = 0; i < a.length; i++) {\n    if (a[i] !== b[i]) {\n      return false;\n    }\n  }\n  return true;\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"toolOutputReferences.mjs","sources":["../../../src/tools/toolOutputReferences.ts"],"sourcesContent":["/**\n * Tool output reference registry.\n *\n * When enabled via `RunConfig.toolOutputReferences.enabled`, ToolNode\n * stores each successful tool output under a stable key\n * (`tool<idx>turn<turn>`) where `idx` is the tool's position within a\n * ToolNode batch and `turn` is the batch index within the run\n * (incremented once per ToolNode invocation).\n *\n * Subsequent tool calls can pipe a previous output into their args by\n * embedding `{{tool<idx>turn<turn>}}` inside any string argument;\n * {@link ToolOutputReferenceRegistry.resolve} walks the args and\n * substitutes the placeholders immediately before invocation.\n *\n * The registry stores the *raw, untruncated* tool output so a later\n * `{{…}}` substitution pipes the full payload into the next tool —\n * even when the LLM only saw a head+tail-truncated preview in\n * `ToolMessage.content`. Outputs are stored without any annotation\n * (the `_ref` key or the `[ref: ...]` prefix seen by the LLM is\n * strictly a UX signal attached to `ToolMessage.content`). Keeping the\n * registry pristine means downstream bash/jq piping receives the\n * complete, verbatim output with no injected fields.\n */\n\nimport { ToolMessage } from '@langchain/core/messages';\nimport type { BaseMessage } from '@langchain/core/messages';\nimport {\n  calculateMaxTotalToolOutputSize,\n  HARD_MAX_TOOL_RESULT_CHARS,\n  HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE,\n} from '@/utils/truncation';\n\n/**\n * Non-global matcher for a single `{{tool<i>turn<n>}}` placeholder.\n * Exported for consumers that want to detect references (e.g., syntax\n * highlighting, docs). The stateful `g` variant lives inside the\n * registry so nobody trips on `lastIndex`.\n */\nexport const TOOL_OUTPUT_REF_PATTERN = /\\{\\{(tool\\d+turn\\d+)\\}\\}/;\n\n/** Object key used when a parsed-object output has `_ref` injected. */\nexport const TOOL_OUTPUT_REF_KEY = '_ref';\n\n/**\n * Object key used to carry unresolved reference warnings on a parsed-\n * object output. Using a dedicated field instead of a trailing text\n * line keeps the annotated `ToolMessage.content` parseable as JSON for\n * downstream consumers that rely on the object shape.\n */\nexport const TOOL_OUTPUT_UNRESOLVED_KEY = '_unresolved_refs';\n\n/** Single-line prefix prepended to non-object tool outputs so the LLM sees the reference key. */\nexport function buildReferencePrefix(key: string): string {\n  return `[ref: ${key}]`;\n}\n\n/** Stable registry key for a tool output. */\nexport function buildReferenceKey(toolIndex: number, turn: number): string {\n  return `tool${toolIndex}turn${turn}`;\n}\n\nexport type ToolOutputReferenceRegistryOptions = {\n  /** Maximum characters stored per registered output. */\n  maxOutputSize?: number;\n  /** Maximum total characters retained across all registered outputs. */\n  maxTotalSize?: number;\n  /**\n   * Upper bound on the number of concurrently-tracked runs. When\n   * exceeded, the oldest run bucket is evicted (FIFO). Defaults to 32.\n   */\n  maxActiveRuns?: number;\n};\n\n/**\n * Result of resolving placeholders in tool args.\n */\nexport type ResolveResult<T> = {\n  /** Arguments with placeholders replaced. Same shape as the input. */\n  resolved: T;\n  /** Reference keys that were referenced but had no stored value. */\n  unresolved: string[];\n};\n\n/**\n * Read-only view over a frozen registry snapshot. Returned by\n * {@link ToolOutputReferenceRegistry.snapshot} for callers that need\n * to resolve placeholders against the registry state at a specific\n * point in time, ignoring any subsequent registrations.\n */\nexport interface ToolOutputResolveView {\n  resolve<T>(args: T): ResolveResult<T>;\n}\n\n/**\n * Pre-resolved arg map keyed by `toolCallId`. Used by the mixed\n * direct+event dispatch path to feed event calls' resolved args\n * (captured pre-batch) into the dispatcher without re-resolving\n * against the now-stale live registry.\n */\nexport type PreResolvedArgsMap = Map<\n  string,\n  { resolved: Record<string, unknown>; unresolved: string[] }\n>;\n\n/**\n * Per-call sink for resolved args, keyed by `toolCallId`. Threaded\n * as a per-batch local map so concurrent `ToolNode.run()` calls do\n * not race on shared sink state.\n */\nexport type ResolvedArgsByCallId = Map<string, Record<string, unknown>>;\n\nconst EMPTY_ENTRIES: ReadonlyMap<string, string> = new Map<string, string>();\n\n/**\n * Per-run state bucket held inside the registry. Each distinct\n * `run_id` gets its own bucket so overlapping concurrent runs on a\n * shared registry cannot leak outputs, turn counters, or warn-memos\n * into one another.\n */\nclass RunStateBucket {\n  entries: Map<string, string> = new Map();\n  totalSize: number = 0;\n  turnCounter: number = 0;\n  warnedNonStringTools: Set<string> = new Set();\n}\n\n/**\n * Anonymous (`run_id` absent) bucket key. Anonymous batches are\n * treated as fresh runs on every invocation — see `nextTurn`.\n */\nconst ANON_RUN_KEY = '\\0anon';\n\n/**\n * Default upper bound on the number of concurrently-tracked runs per\n * registry. When exceeded, the oldest run's bucket (by insertion\n * order) is evicted. Keeps memory bounded when a ToolNode is reused\n * across many runs without explicit `releaseRun` calls.\n */\nconst DEFAULT_MAX_ACTIVE_RUNS = 32;\n\n/**\n * Ordered map of reference-key → stored output, partitioned by run so\n * concurrent / interleaved runs sharing one registry cannot leak\n * outputs between each other.\n *\n * Each public method takes a `runId` which selects the run's bucket.\n * Hosts typically get one registry per run via `Graph`, in which\n * case only a single bucket is ever populated; the partitioning\n * exists so the registry also behaves correctly when a single\n * instance is reused directly.\n */\nexport class ToolOutputReferenceRegistry {\n  private runStates: Map<string, RunStateBucket> = new Map();\n  private readonly maxOutputSize: number;\n  private readonly maxTotalSize: number;\n  private readonly maxActiveRuns: number;\n  /**\n   * Local stateful matcher used only by `replaceInString`. Kept\n   * off-module so callers of the exported `TOOL_OUTPUT_REF_PATTERN`\n   * never see a stale `lastIndex`.\n   */\n  private static readonly PLACEHOLDER_MATCHER = /\\{\\{(tool\\d+turn\\d+)\\}\\}/g;\n\n  constructor(options: ToolOutputReferenceRegistryOptions = {}) {\n    /**\n     * Per-output default is the same ~400 KB budget as the standard\n     * tool-result truncation (`HARD_MAX_TOOL_RESULT_CHARS`). This\n     * keeps a single `{{…}}` substitution at a size that is safe to\n     * pass through typical shell `ARG_MAX` limits and matches what\n     * the LLM would otherwise have seen. Hosts that want larger per-\n     * output payloads (API consumers, long JSON streams) can raise\n     * the cap explicitly up to the 5 MB total budget.\n     */\n    const perOutput =\n      options.maxOutputSize != null && options.maxOutputSize > 0\n        ? options.maxOutputSize\n        : HARD_MAX_TOOL_RESULT_CHARS;\n    /**\n     * Clamp a caller-supplied `maxTotalSize` to\n     * `HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE` (5 MB) so the documented\n     * absolute cap is enforced regardless of host config —\n     * `calculateMaxTotalToolOutputSize` already applies the same\n     * upper bound on its computed default, but the user-provided\n     * branch was bypassing it.\n     */\n    const totalRaw =\n      options.maxTotalSize != null && options.maxTotalSize > 0\n        ? Math.min(options.maxTotalSize, HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE)\n        : calculateMaxTotalToolOutputSize(perOutput);\n    this.maxTotalSize = totalRaw;\n    /**\n     * The per-output cap can never exceed the per-run aggregate cap:\n     * if a single entry were allowed to be larger than `maxTotalSize`,\n     * the eviction loop would either blow the cap (to keep the entry)\n     * or self-evict a just-stored value. Clamping here turns\n     * `maxTotalSize` into a hard upper bound on *any* state the\n     * registry retains per run.\n     */\n    this.maxOutputSize = Math.min(perOutput, totalRaw);\n    this.maxActiveRuns =\n      options.maxActiveRuns != null && options.maxActiveRuns > 0\n        ? options.maxActiveRuns\n        : DEFAULT_MAX_ACTIVE_RUNS;\n  }\n\n  private keyFor(runId: string | undefined): string {\n    return runId ?? ANON_RUN_KEY;\n  }\n\n  private getOrCreate(runId: string | undefined): RunStateBucket {\n    const key = this.keyFor(runId);\n    let state = this.runStates.get(key);\n    if (state == null) {\n      state = new RunStateBucket();\n      this.runStates.set(key, state);\n      if (this.runStates.size > this.maxActiveRuns) {\n        const oldest = this.runStates.keys().next().value;\n        if (oldest != null && oldest !== key) {\n          this.runStates.delete(oldest);\n        }\n      }\n    }\n    return state;\n  }\n\n  /** Registers (or replaces) the output stored under `key` for `runId`. */\n  set(runId: string | undefined, key: string, value: string): void {\n    const bucket = this.getOrCreate(runId);\n    const clipped =\n      value.length > this.maxOutputSize\n        ? value.slice(0, this.maxOutputSize)\n        : value;\n    const existing = bucket.entries.get(key);\n    if (existing != null) {\n      bucket.totalSize -= existing.length;\n      bucket.entries.delete(key);\n    }\n    bucket.entries.set(key, clipped);\n    bucket.totalSize += clipped.length;\n    this.evictWithinBucket(bucket);\n  }\n\n  /** Returns the stored value for `key` in `runId`'s bucket, or `undefined`. */\n  get(runId: string | undefined, key: string): string | undefined {\n    return this.runStates.get(this.keyFor(runId))?.entries.get(key);\n  }\n\n  /**\n   * Returns `true` when `key` is currently stored in `runId`'s bucket.\n   * Used by {@link annotateMessagesForLLM} to gate transient annotation\n   * on whether the registry still owns the referenced output (a stale\n   * `_refKey` from a prior run silently no-ops here).\n   */\n  has(runId: string | undefined, key: string): boolean {\n    return this.runStates.get(this.keyFor(runId))?.entries.has(key) ?? false;\n  }\n\n  /** Total number of registered outputs across every run bucket. */\n  get size(): number {\n    let n = 0;\n    for (const bucket of this.runStates.values()) {\n      n += bucket.entries.size;\n    }\n    return n;\n  }\n\n  /** Maximum characters retained per output (post-clip). */\n  get perOutputLimit(): number {\n    return this.maxOutputSize;\n  }\n\n  /** Maximum total characters retained *per run*. */\n  get totalLimit(): number {\n    return this.maxTotalSize;\n  }\n\n  /** Drops every run's state. */\n  clear(): void {\n    this.runStates.clear();\n  }\n\n  /**\n   * Explicitly release `runId`'s state. Safe to call when a run has\n   * finished. Hosts sharing one registry across runs should call this\n   * to reclaim memory deterministically; otherwise LRU eviction kicks\n   * in when `maxActiveRuns` runs accumulate.\n   */\n  releaseRun(runId: string | undefined): void {\n    this.runStates.delete(this.keyFor(runId));\n  }\n\n  /**\n   * Claims the next batch turn synchronously from `runId`'s bucket.\n   *\n   * Must be called once at the start of each ToolNode batch before\n   * any `await`, so concurrent invocations within the same run see\n   * distinct turn values (reads are effectively atomic by JS's\n   * single-threaded execution of the sync prefix).\n   *\n   * If `runId` is missing the anonymous bucket is dropped and a\n   * fresh one created so each anonymous call behaves as its own run.\n   */\n  nextTurn(runId: string | undefined): number {\n    if (runId == null) {\n      this.runStates.delete(ANON_RUN_KEY);\n    }\n    const bucket = this.getOrCreate(runId);\n    return bucket.turnCounter++;\n  }\n\n  /**\n   * Records that `toolName` has been warned about in `runId` (returns\n   * `true` on the first call per run, `false` after). Used by\n   * ToolNode to emit one log line per offending tool per run when a\n   * `ToolMessage.content` isn't a string.\n   */\n  claimWarnOnce(runId: string | undefined, toolName: string): boolean {\n    const bucket = this.getOrCreate(runId);\n    if (bucket.warnedNonStringTools.has(toolName)) {\n      return false;\n    }\n    bucket.warnedNonStringTools.add(toolName);\n    return true;\n  }\n\n  /**\n   * Walks `args` and replaces every `{{tool<i>turn<n>}}` placeholder in\n   * string values with the stored output *from `runId`'s bucket*. Non-\n   * string values and object keys are left untouched. Unresolved\n   * references are left in-place and reported so the caller can\n   * surface them to the LLM. When no placeholder appears anywhere in\n   * the serialized args, the original input is returned without\n   * walking the tree.\n   */\n  resolve<T>(runId: string | undefined, args: T): ResolveResult<T> {\n    if (!hasAnyPlaceholder(args)) {\n      return { resolved: args, unresolved: [] };\n    }\n    const bucket = this.runStates.get(this.keyFor(runId));\n    return this.resolveAgainst(bucket?.entries ?? EMPTY_ENTRIES, args);\n  }\n\n  /**\n   * Captures a frozen snapshot of `runId`'s current entries and\n   * returns a view that resolves placeholders against *only* that\n   * snapshot. The snapshot is decoupled from the live registry, so\n   * subsequent `set()` calls (for example, same-turn direct outputs\n   * registering while an event branch is still in flight) are\n   * invisible to the snapshot's `resolve`. Used by the mixed\n   * direct+event dispatch path to preserve same-turn isolation when\n   * a `PreToolUse` hook rewrites event args after directs have\n   * completed.\n   */\n  snapshot(runId: string | undefined): ToolOutputResolveView {\n    const bucket = this.runStates.get(this.keyFor(runId));\n    const entries: ReadonlyMap<string, string> = bucket\n      ? new Map(bucket.entries)\n      : EMPTY_ENTRIES;\n    return {\n      resolve: <T>(args: T): ResolveResult<T> =>\n        this.resolveAgainst(entries, args),\n    };\n  }\n\n  private resolveAgainst<T>(\n    entries: ReadonlyMap<string, string>,\n    args: T\n  ): ResolveResult<T> {\n    if (!hasAnyPlaceholder(args)) {\n      return { resolved: args, unresolved: [] };\n    }\n    const unresolved = new Set<string>();\n    const resolved = this.transform(entries, args, unresolved) as T;\n    return { resolved, unresolved: Array.from(unresolved) };\n  }\n\n  private transform(\n    entries: ReadonlyMap<string, string>,\n    value: unknown,\n    unresolved: Set<string>\n  ): unknown {\n    if (typeof value === 'string') {\n      return this.replaceInString(entries, value, unresolved);\n    }\n    if (Array.isArray(value)) {\n      return value.map((item) => this.transform(entries, item, unresolved));\n    }\n    if (value !== null && typeof value === 'object') {\n      const source = value as Record<string, unknown>;\n      const next: Record<string, unknown> = {};\n      for (const [key, item] of Object.entries(source)) {\n        next[key] = this.transform(entries, item, unresolved);\n      }\n      return next;\n    }\n    return value;\n  }\n\n  private replaceInString(\n    entries: ReadonlyMap<string, string>,\n    input: string,\n    unresolved: Set<string>\n  ): string {\n    if (input.indexOf('{{tool') === -1) {\n      return input;\n    }\n    return input.replace(\n      ToolOutputReferenceRegistry.PLACEHOLDER_MATCHER,\n      (match, key: string) => {\n        const stored = entries.get(key);\n        if (stored == null) {\n          unresolved.add(key);\n          return match;\n        }\n        return stored;\n      }\n    );\n  }\n\n  private evictWithinBucket(bucket: RunStateBucket): void {\n    if (bucket.totalSize <= this.maxTotalSize) {\n      return;\n    }\n    for (const key of bucket.entries.keys()) {\n      if (bucket.totalSize <= this.maxTotalSize) {\n        return;\n      }\n      const entry = bucket.entries.get(key);\n      if (entry == null) {\n        continue;\n      }\n      bucket.totalSize -= entry.length;\n      bucket.entries.delete(key);\n    }\n  }\n}\n\n/**\n * Cheap pre-check: returns true if any string value in `args` contains\n * the `{{tool` substring. Lets `resolve()` skip the deep tree walk (and\n * its object allocations) for the common case of plain args.\n */\nfunction hasAnyPlaceholder(value: unknown): boolean {\n  if (typeof value === 'string') {\n    return value.indexOf('{{tool') !== -1;\n  }\n  if (Array.isArray(value)) {\n    for (const item of value) {\n      if (hasAnyPlaceholder(item)) {\n        return true;\n      }\n    }\n    return false;\n  }\n  if (value !== null && typeof value === 'object') {\n    for (const item of Object.values(value as Record<string, unknown>)) {\n      if (hasAnyPlaceholder(item)) {\n        return true;\n      }\n    }\n    return false;\n  }\n  return false;\n}\n\n/**\n * Annotates `content` with a reference key and/or unresolved-ref\n * warnings so the LLM sees both alongside the tool output.\n *\n * Behavior:\n *  - If `content` parses as a plain (non-array, non-null) JSON object\n *    and the object does not already have a conflicting `_ref` key,\n *    the reference key and (when present) `_unresolved_refs` array\n *    are injected as object fields, preserving JSON validity for\n *    downstream consumers that parse the output.\n *  - Otherwise (string output, JSON array/primitive, parse failure,\n *    or `_ref` collision), a `[ref: <key>]\\n` prefix line is\n *    prepended and unresolved refs are appended as a trailing\n *    `[unresolved refs: …]` line.\n *\n * The annotated string is what the LLM sees as `ToolMessage.content`.\n * The *original* (un-annotated) value is what gets stored in the\n * registry, so downstream piping remains pristine.\n *\n * @param content     Raw (post-truncation) tool output.\n * @param key         Reference key for this output, or undefined when\n *                    there is nothing to register (errors etc.).\n * @param unresolved  Reference keys that failed to resolve during\n *                    argument substitution. Surfaced so the LLM can\n *                    self-correct its next tool call.\n */\nexport function annotateToolOutputWithReference(\n  content: string,\n  key: string | undefined,\n  unresolved: string[] = []\n): string {\n  const hasRefKey = key != null;\n  const hasUnresolved = unresolved.length > 0;\n  if (!hasRefKey && !hasUnresolved) {\n    return content;\n  }\n  const trimmed = content.trimStart();\n  if (trimmed.startsWith('{')) {\n    const annotated = tryInjectRefIntoJsonObject(content, key, unresolved);\n    if (annotated != null) {\n      return annotated;\n    }\n  }\n  const prefix = hasRefKey ? `${buildReferencePrefix(key!)}\\n` : '';\n  const trailer = hasUnresolved\n    ? `\\n[unresolved refs: ${unresolved.join(', ')}]`\n    : '';\n  return `${prefix}${content}${trailer}`;\n}\n\nfunction tryInjectRefIntoJsonObject(\n  content: string,\n  key: string | undefined,\n  unresolved: string[]\n): string | null {\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(content);\n  } catch {\n    return null;\n  }\n\n  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {\n    return null;\n  }\n\n  const obj = parsed as Record<string, unknown>;\n  const injectingRef = key != null;\n  const injectingUnresolved = unresolved.length > 0;\n\n  /**\n   * Reject the JSON-injection path (fall back to prefix form) when\n   * either of our keys collides with real payload data:\n   *  - `_ref` collision: existing value is non-null and differs from\n   *    the key we're about to inject.\n   *  - `_unresolved_refs` collision: existing value is non-null and\n   *    is not a deep-equal match for the array we'd inject.\n   * This keeps us from silently overwriting legitimate tool output.\n   */\n  if (\n    injectingRef &&\n    TOOL_OUTPUT_REF_KEY in obj &&\n    obj[TOOL_OUTPUT_REF_KEY] !== key &&\n    obj[TOOL_OUTPUT_REF_KEY] != null\n  ) {\n    return null;\n  }\n  if (\n    injectingUnresolved &&\n    TOOL_OUTPUT_UNRESOLVED_KEY in obj &&\n    obj[TOOL_OUTPUT_UNRESOLVED_KEY] != null &&\n    !arraysShallowEqual(obj[TOOL_OUTPUT_UNRESOLVED_KEY], unresolved)\n  ) {\n    return null;\n  }\n\n  /**\n   * Only strip the framework-owned key we're actually injecting —\n   * leave everything else (including a pre-existing `_ref` on the\n   * unresolved-only path, or a pre-existing `_unresolved_refs` on a\n   * plain-annotation path) untouched so we annotate rather than\n   * mutate downstream payload data. Our injected keys land first in\n   * the serialized JSON so the LLM sees them before the body.\n   */\n  const omitKeys = new Set<string>();\n  if (injectingRef) omitKeys.add(TOOL_OUTPUT_REF_KEY);\n  if (injectingUnresolved) omitKeys.add(TOOL_OUTPUT_UNRESOLVED_KEY);\n  const rest: Record<string, unknown> = {};\n  for (const [k, v] of Object.entries(obj)) {\n    if (!omitKeys.has(k)) {\n      rest[k] = v;\n    }\n  }\n  const injected: Record<string, unknown> = {};\n  if (injectingRef) {\n    injected[TOOL_OUTPUT_REF_KEY] = key;\n  }\n  if (injectingUnresolved) {\n    injected[TOOL_OUTPUT_UNRESOLVED_KEY] = unresolved;\n  }\n  Object.assign(injected, rest);\n\n  const pretty = /^\\{\\s*\\n/.test(content);\n  return pretty ? JSON.stringify(injected, null, 2) : JSON.stringify(injected);\n}\n\nfunction arraysShallowEqual(a: unknown, b: readonly string[]): boolean {\n  if (!Array.isArray(a) || a.length !== b.length) {\n    return false;\n  }\n  for (let i = 0; i < a.length; i++) {\n    if (a[i] !== b[i]) {\n      return false;\n    }\n  }\n  return true;\n}\n\n/**\n * Lazy projection that, given a registry and a runId, returns a new\n * `messages` array where each `ToolMessage` carrying ref metadata is\n * projected into a transient copy with annotated content (when the ref\n * is live in the registry) and with the framework-owned `additional_\n * kwargs` keys (`_refKey`, `_refScope`, `_unresolvedRefs`) stripped\n * regardless of whether annotation applied. The original input array\n * and its messages are never mutated.\n *\n * Annotation is gated on registry presence: a stale `_refKey` from a\n * prior run (e.g. one that survived in persisted history) silently\n * no-ops on the *content* side. The strip-metadata side still runs so\n * stale framework keys never leak onto the wire under any custom or\n * future provider serializer that might transmit `additional_kwargs`.\n * `_unresolvedRefs` is always meaningful and is not gated.\n *\n * **Feature-disabled fast path:** when the host hasn't enabled the\n * tool-output-reference feature, the registry is `undefined` and this\n * function returns the input array reference-equal *without iterating\n * a single message*. The loop is exclusive to the feature-enabled\n * code path.\n */\nexport function annotateMessagesForLLM(\n  messages: BaseMessage[],\n  registry: ToolOutputReferenceRegistry | undefined,\n  runId: string | undefined\n): BaseMessage[] {\n  if (registry == null) return messages;\n\n  /**\n   * Lazy-allocate the output array so the common case (no ToolMessage\n   * carries framework metadata) returns the input reference-equal with\n   * zero allocations beyond the per-message predicate checks.\n   */\n  let out: BaseMessage[] | undefined;\n  for (let i = 0; i < messages.length; i++) {\n    const m = messages[i];\n    if (m._getType() !== 'tool') continue;\n    /**\n     * `additional_kwargs` is untyped at the LangChain layer\n     * (`Record<string, unknown>`), so persisted or client-supplied\n     * ToolMessages can carry arbitrary shapes — including primitives\n     * (a malformed serializer might write a string, or `null`).\n     * Guard with a runtime object check before the `in` probes\n     * because the `in` operator throws `TypeError` on primitives.\n     * A single malformed message must never crash the provider call\n     * path; skip its annotation/strip and continue.\n     */\n    const rawMeta = m.additional_kwargs as unknown;\n    if (rawMeta == null || typeof rawMeta !== 'object') continue;\n    const meta = rawMeta as Record<string, unknown>;\n    const hasRefKey = '_refKey' in meta;\n    const hasRefScope = '_refScope' in meta;\n    const hasUnresolvedField = '_unresolvedRefs' in meta;\n    if (!hasRefKey && !hasRefScope && !hasUnresolvedField) continue;\n\n    const refKey = readRefKey(meta);\n    const unresolved = readUnresolvedRefs(meta);\n\n    /**\n     * Prefer the message-stamped `_refScope` for the registry lookup.\n     * For named runs it equals the current `runId`; for anonymous\n     * invocations it carries the per-batch synthetic scope minted by\n     * ToolNode (`\\0anon-<n>`), which `runId` from config cannot\n     * recover. Falling back to `runId` keeps backward compatibility\n     * with messages stamped before this field existed.\n     */\n    const lookupScope = readRefScope(meta) ?? runId;\n    const liveRef =\n      refKey != null && registry.has(lookupScope, refKey) ? refKey : undefined;\n    const annotates = liveRef != null || unresolved.length > 0;\n\n    const tm = m as ToolMessage;\n    let nextContent: ToolMessage['content'] = tm.content;\n\n    if (annotates && typeof tm.content === 'string') {\n      nextContent = annotateToolOutputWithReference(\n        tm.content,\n        liveRef,\n        unresolved\n      );\n    } else if (\n      annotates &&\n      Array.isArray(tm.content) &&\n      unresolved.length > 0\n    ) {\n      const warningBlock = {\n        type: 'text' as const,\n        text: `[unresolved refs: ${unresolved.join(', ')}]`,\n      };\n      /**\n       * `as unknown as ToolMessage['content']` is unavoidable here:\n       * LangChain's content union (`MessageContentComplex[] |\n       * DataContentBlock[] | string`) does not accept a freshly built\n       * mixed array literal even though the structural shape is valid\n       * at runtime. The double-cast is structurally safe — we\n       * preserve every block from `tm.content` and prepend a single\n       * `{ type: 'text', text }` block that all providers accept.\n       */\n      nextContent = [\n        warningBlock,\n        ...tm.content,\n      ] as unknown as ToolMessage['content'];\n    }\n\n    /**\n     * Project unconditionally: even when no annotation applies (stale\n     * `_refKey` or non-annotatable content), `cloneToolMessageWithContent`\n     * runs `stripFrameworkRefMetadata` on `additional_kwargs` so the\n     * framework-owned keys never reach the wire.\n     */\n    out ??= messages.slice();\n    out[i] = cloneToolMessageWithContent(tm, nextContent);\n  }\n\n  return out ?? messages;\n}\n\n/**\n * Reads `_refKey` defensively from untyped `additional_kwargs`. Returns\n * undefined for non-string values so a malformed field cannot poison\n * the registry lookup or downstream string operations.\n */\nfunction readRefKey(\n  meta: Record<string, unknown> | undefined\n): string | undefined {\n  const v = meta?._refKey;\n  return typeof v === 'string' ? v : undefined;\n}\n\n/**\n * Reads `_refScope` defensively from untyped `additional_kwargs`.\n * Mirrors {@link readRefKey} — non-string scopes are dropped (the\n * caller falls back to the run-derived scope) rather than passed into\n * the registry as a malformed key.\n */\nfunction readRefScope(\n  meta: Record<string, unknown> | undefined\n): string | undefined {\n  const v = meta?._refScope;\n  return typeof v === 'string' ? v : undefined;\n}\n\n/**\n * Reads `_unresolvedRefs` defensively from untyped `additional_kwargs`.\n * Returns an empty array for any non-array value, and filters out\n * non-string entries from a real array. Without this guard, a hydrated\n * ToolMessage carrying e.g. `_unresolvedRefs: 'tool0turn0'` would crash\n * `attemptInvoke` on the eventual `.length` / `.join(...)` call.\n */\nfunction readUnresolvedRefs(\n  meta: Record<string, unknown> | undefined\n): string[] {\n  const v = meta?._unresolvedRefs;\n  if (!Array.isArray(v)) return [];\n  const out: string[] = [];\n  for (const item of v) {\n    if (typeof item === 'string') out.push(item);\n  }\n  return out;\n}\n\n/**\n * Builds a fresh `ToolMessage` that mirrors `tm`'s identity fields with\n * the supplied `content`. Every `ToolMessage` field but `content` is\n * carried over so the projection is structurally identical to the\n * original from a LangChain serializer's perspective.\n *\n * `additional_kwargs` is rebuilt with the framework-owned ref keys\n * stripped. Defensive: LangChain's standard provider serializers do not\n * transmit `additional_kwargs` to provider HTTP APIs, but a custom\n * adapter or future LangChain change could. Stripping keeps the\n * implementation correct under any serializer behavior at the cost of a\n * shallow object spread per annotated message.\n */\nfunction cloneToolMessageWithContent(\n  tm: ToolMessage,\n  content: ToolMessage['content']\n): ToolMessage {\n  return new ToolMessage({\n    id: tm.id,\n    name: tm.name,\n    status: tm.status,\n    artifact: tm.artifact,\n    tool_call_id: tm.tool_call_id,\n    response_metadata: tm.response_metadata,\n    additional_kwargs: stripFrameworkRefMetadata(tm.additional_kwargs),\n    content,\n  });\n}\n\n/**\n * Returns a copy of `kwargs` with `_refKey`, `_refScope`, and\n * `_unresolvedRefs` removed. Returns the input reference-equal when\n * none of those keys are present so the no-strip path stays cheap;\n * returns `undefined` when stripping leaves the object empty so the\n * caller can drop the field entirely.\n */\nfunction stripFrameworkRefMetadata(\n  kwargs: Record<string, unknown> | undefined\n): Record<string, unknown> | undefined {\n  if (kwargs == null) return undefined;\n  if (\n    !('_refKey' in kwargs) &&\n    !('_refScope' in kwargs) &&\n    !('_unresolvedRefs' in kwargs)\n  ) {\n    return kwargs;\n  }\n  const { _refKey, _refScope, _unresolvedRefs, ...rest } = kwargs as Record<\n    string,\n    unknown\n  > & {\n    _refKey?: unknown;\n    _refScope?: unknown;\n    _unresolvedRefs?: unknown;\n  };\n  void _refKey;\n  void _refScope;\n  void _unresolvedRefs;\n  return Object.keys(rest).length === 0 ? undefined : rest;\n}\n"],"names":[],"mappings":"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"}

package/dist/types/graphs/Graph.d.ts

@@ -76,8 +76,15 @@ export declare abstract class Graph<T extends t.BaseGraphState = t.BaseGraphStat
      * 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;
+     *
+     * @internal Public so `attemptInvoke` can read it through the typed
+     * `InvokeContext` and project ToolMessages into LLM-facing annotated
+     * copies right before each provider call (see
+     * `annotateMessagesForLLM`). Host code should not call this directly
+     * — registry mutations outside the ToolNode lifecycle break the
+     * partitioning, eviction, and turn-counter invariants.
+     */
+    getOrCreateToolOutputRegistry(): ToolOutputReferenceRegistry | undefined;
 }
 export declare class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     overrideModel?: t.ChatModel;

package/dist/types/llm/invoke.d.ts

@@ -1,14 +1,40 @@
 import { AIMessageChunk } from '@langchain/core/messages';
 import type { RunnableConfig } from '@langchain/core/runnables';
 import type { BaseMessage } from '@langchain/core/messages';
+import type { ToolOutputReferenceRegistry } from '@/tools/toolOutputReferences';
 import type * as t from '@/types';
 import { ChatModelStreamHandler } from '@/stream';
 import { Providers } from '@/common';
 /**
- * Context passed to `attemptInvoke` for the default stream handler.
- * Matches the subset of Graph that `ChatModelStreamHandler.handle` needs.
+ * Context passed to `attemptInvoke`. Matches the subset of Graph that
+ * `ChatModelStreamHandler.handle` needs *plus* the explicit
+ * `getOrCreateToolOutputRegistry()` accessor that `attemptInvoke`
+ * itself calls to pull the run-scoped tool-output registry off the
+ * graph and project each relevant ToolMessage into a transient
+ * annotated copy before the provider call.
+ *
+ * The intersection is intentional: `Parameters<...>[3]` resolves
+ * indirectly through the stream handler's signature (which returns
+ * `StandardGraph` and already exposes the accessor since #117), but
+ * stating it explicitly here surfaces the contract at the call site —
+ * a developer reading `attemptInvoke` doesn't have to chase the
+ * upstream handler's parameter list to discover that
+ * `context?.getOrCreateToolOutputRegistry()` is a real thing. Single
+ * optional chain only — the method itself is required on the
+ * `StandardGraph` branch of the intersection, so the second `?.` is
+ * unnecessary at the call site.
+ *
+ * `NonNullable<...>` strips `undefined` from the upstream parameter
+ * type so the intersection doesn't collapse to `never` on the
+ * undefined branch; callers express optionality via `context?:
+ * InvokeContext` on the function signature instead.
+ *
+ * Callers without a registry (e.g. summarization) simply pass no
+ * `context` and the transform safely no-ops.
  */
-export type InvokeContext = Parameters<ChatModelStreamHandler['handle']>[3];
+export type InvokeContext = NonNullable<Parameters<ChatModelStreamHandler['handle']>[3]> & {
+    getOrCreateToolOutputRegistry?(): ToolOutputReferenceRegistry | undefined;
+};
 /**
  * Per-chunk callback for custom stream processing.
  * When provided, replaces the default `ChatModelStreamHandler`.

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

@@ -97,27 +97,25 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      */
     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.
+     * Registers the full, raw output under `refKey` (when provided) and
+     * builds the per-message ref metadata stamped onto the resulting
+     * `ToolMessage.additional_kwargs`. The metadata is read at LLM-
+     * request time by `annotateMessagesForLLM` to produce a transient
+     * annotated copy of the message — the persisted `content` itself
+     * stays clean.
      *
-     * @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.
+     * @param unresolved  Placeholder keys that did not resolve; surfaced
+     *   to the LLM lazily so it can self-correct.
+     * @returns A `ToolMessageRefMetadata` object when there is anything
+     *   to stamp, otherwise `undefined`.
      */
-    private applyOutputReference;
+    private recordOutputReference;
     /**
      * Builds code session context for injection into event-driven tool calls.
      * Mirrors the session injection logic in runTool() for direct execution.

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

@@ -21,6 +21,7 @@
  * registry pristine means downstream bash/jq piping receives the
  * complete, verbatim output with no injected fields.
  */
+import type { BaseMessage } from '@langchain/core/messages';
 /**
  * Non-global matcher for a single `{{tool<i>turn<n>}}` placeholder.
  * Exported for consumers that want to detect references (e.g., syntax
@@ -115,6 +116,13 @@ export declare class ToolOutputReferenceRegistry {
     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;
+    /**
+     * Returns `true` when `key` is currently stored in `runId`'s bucket.
+     * Used by {@link annotateMessagesForLLM} to gate transient annotation
+     * on whether the registry still owns the referenced output (a stale
+     * `_refKey` from a prior run silently no-ops here).
+     */
+    has(runId: string | undefined, key: string): boolean;
     /** Total number of registered outputs across every run bucket. */
     get size(): number;
     /** Maximum characters retained per output (post-clip). */
@@ -203,3 +211,26 @@ export declare class ToolOutputReferenceRegistry {
  *                    self-correct its next tool call.
  */
 export declare function annotateToolOutputWithReference(content: string, key: string | undefined, unresolved?: string[]): string;
+/**
+ * Lazy projection that, given a registry and a runId, returns a new
+ * `messages` array where each `ToolMessage` carrying ref metadata is
+ * projected into a transient copy with annotated content (when the ref
+ * is live in the registry) and with the framework-owned `additional_
+ * kwargs` keys (`_refKey`, `_refScope`, `_unresolvedRefs`) stripped
+ * regardless of whether annotation applied. The original input array
+ * and its messages are never mutated.
+ *
+ * Annotation is gated on registry presence: a stale `_refKey` from a
+ * prior run (e.g. one that survived in persisted history) silently
+ * no-ops on the *content* side. The strip-metadata side still runs so
+ * stale framework keys never leak onto the wire under any custom or
+ * future provider serializer that might transmit `additional_kwargs`.
+ * `_unresolvedRefs` is always meaningful and is not gated.
+ *
+ * **Feature-disabled fast path:** when the host hasn't enabled the
+ * tool-output-reference feature, the registry is `undefined` and this
+ * function returns the input array reference-equal *without iterating
+ * a single message*. The loop is exclusive to the feature-enabled
+ * code path.
+ */
+export declare function annotateMessagesForLLM(messages: BaseMessage[], registry: ToolOutputReferenceRegistry | undefined, runId: string | undefined): BaseMessage[];

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

@@ -1,5 +1,6 @@
 export * from './graph';
 export * from './llm';
+export * from './messages';
 export * from './run';
 export * from './skill';
 export * from './stream';

package/dist/types/types/messages.d.ts

@@ -2,3 +2,29 @@ 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.1.71-dev.0",
+  "version": "3.1.71",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",

package/src/graphs/Graph.ts

@@ -186,8 +186,15 @@ export abstract class Graph<
    * 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.
+   *
+   * @internal Public so `attemptInvoke` can read it through the typed
+   * `InvokeContext` and project ToolMessages into LLM-facing annotated
+   * copies right before each provider call (see
+   * `annotateMessagesForLLM`). Host code should not call this directly
+   * — registry mutations outside the ToolNode lifecycle break the
+   * partitioning, eviction, and turn-counter invariants.
    */
-  protected getOrCreateToolOutputRegistry():
+  public getOrCreateToolOutputRegistry():
     | ToolOutputReferenceRegistry
     | undefined {
     if (this.toolOutputReferences?.enabled !== true) {