@librechat/agents 3.1.71-dev.0 → 3.1.71-dev.1

package/src/tools/__tests__/annotateMessagesForLLM.test.ts

@@ -0,0 +1,419 @@
+import { AIMessage, HumanMessage, ToolMessage } from '@langchain/core/messages';
+import { describe, it, expect } from '@jest/globals';
+import {
+  annotateMessagesForLLM,
+  ToolOutputReferenceRegistry,
+  TOOL_OUTPUT_REF_KEY,
+  TOOL_OUTPUT_UNRESOLVED_KEY,
+} from '../toolOutputReferences';
+
+function makeToolMessage(fields: {
+  content: ToolMessage['content'];
+  name?: string;
+  tool_call_id?: string;
+  status?: 'success' | 'error';
+  additional_kwargs?: Record<string, unknown>;
+}): ToolMessage {
+  return new ToolMessage({
+    name: fields.name ?? 'echo',
+    tool_call_id: fields.tool_call_id ?? 'tc1',
+    status: fields.status ?? 'success',
+    additional_kwargs: fields.additional_kwargs,
+    content: fields.content,
+  });
+}
+
+describe('annotateMessagesForLLM', () => {
+  it('returns the input array reference when registry is undefined', () => {
+    const messages = [
+      new HumanMessage('hi'),
+      makeToolMessage({
+        content: 'data',
+        additional_kwargs: { _refKey: 'tool0turn0' },
+      }),
+    ];
+    const out = annotateMessagesForLLM(messages, undefined, 'r1');
+    expect(out).toBe(messages);
+  });
+
+  it('does not iterate any message when the feature is disabled (registry undefined)', () => {
+    /**
+     * Hard guarantee: when the host hasn't enabled
+     * `RunConfig.toolOutputReferences`, calling
+     * `annotateMessagesForLLM` must short-circuit at O(1) without
+     * touching a single ToolMessage. We assert by spying on
+     * `_getType` — the first per-message call inside the loop — and
+     * confirming it was never invoked.
+     */
+    const messages = [
+      makeToolMessage({ content: 'a' }),
+      makeToolMessage({ content: 'b' }),
+      makeToolMessage({
+        content: 'c',
+        additional_kwargs: { _refKey: 'tool0turn0' },
+      }),
+    ];
+    const spies = messages.map((m) => jest.spyOn(m, '_getType'));
+    const out = annotateMessagesForLLM(messages, undefined, undefined);
+    expect(out).toBe(messages);
+    for (const spy of spies) {
+      expect(spy).not.toHaveBeenCalled();
+      spy.mockRestore();
+    }
+  });
+
+  it('returns the input array reference when no ToolMessage carries metadata', () => {
+    const registry = new ToolOutputReferenceRegistry();
+    registry.set('r1', 'tool0turn0', 'stored');
+    const messages = [
+      new HumanMessage('hi'),
+      makeToolMessage({ content: 'data' }),
+      new AIMessage('answer'),
+    ];
+    const out = annotateMessagesForLLM(messages, registry, 'r1');
+    expect(out).toBe(messages);
+  });
+
+  it('annotates string content when _refKey is live in the registry', () => {
+    const registry = new ToolOutputReferenceRegistry();
+    registry.set('r1', 'tool0turn0', 'stored-raw');
+    const tm = makeToolMessage({
+      content: 'output',
+      additional_kwargs: { _refKey: 'tool0turn0' },
+    });
+    const out = annotateMessagesForLLM([tm], registry, 'r1');
+    expect(out[0].content).toBe('[ref: tool0turn0]\noutput');
+    expect(tm.content).toBe('output');
+    expect(out).not.toBe([tm]);
+    expect(out[0]).not.toBe(tm);
+  });
+
+  it('leaves content untouched but strips framework metadata when _refKey is stale', () => {
+    /**
+     * Stale `_refKey` (not in registry) doesn't trigger annotation,
+     * but the message still gets projected so framework keys are
+     * removed from `additional_kwargs` before the bytes leave for the
+     * provider. This protects against custom or future serializers
+     * that transmit `additional_kwargs`.
+     */
+    const registry = new ToolOutputReferenceRegistry();
+    const tm = makeToolMessage({
+      content: 'output',
+      additional_kwargs: { _refKey: 'tool0turn0', userField: 'preserved' },
+    });
+    const out = annotateMessagesForLLM([tm], registry, 'r1');
+    expect(out[0].content).toBe('output');
+    expect(out[0]).not.toBe(tm);
+    const projectedKwargs = (out[0] as ToolMessage).additional_kwargs;
+    expect(projectedKwargs._refKey).toBeUndefined();
+    expect(projectedKwargs.userField).toBe('preserved');
+    expect(tm.additional_kwargs._refKey).toBe('tool0turn0');
+  });
+
+  it('always applies _unresolvedRefs even when there is no registry entry', () => {
+    const registry = new ToolOutputReferenceRegistry();
+    const tm = makeToolMessage({
+      content: 'output',
+      additional_kwargs: { _unresolvedRefs: ['tool9turn9'] },
+    });
+    const out = annotateMessagesForLLM([tm], registry, 'r1');
+    expect(out[0].content).toBe('output\n[unresolved refs: tool9turn9]');
+  });
+
+  it('injects _ref into JSON-object string content', () => {
+    const registry = new ToolOutputReferenceRegistry();
+    registry.set('r1', 'tool0turn0', '{"a":1}');
+    const tm = makeToolMessage({
+      content: '{"a":1,"b":"x"}',
+      additional_kwargs: { _refKey: 'tool0turn0' },
+    });
+    const out = annotateMessagesForLLM([tm], registry, 'r1');
+    const parsed = JSON.parse(out[0].content as string);
+    expect(parsed[TOOL_OUTPUT_REF_KEY]).toBe('tool0turn0');
+    expect(parsed.a).toBe(1);
+    expect(parsed.b).toBe('x');
+  });
+
+  it('injects both _ref and _unresolved_refs into JSON-object content', () => {
+    /**
+     * Combined path: when a ToolMessage carries both a live `_refKey`
+     * and unresolved-ref hints, JSON-object content should receive
+     * both `_ref` and `_unresolved_refs` fields rather than falling
+     * back to the prefix/trailer form. Exercises
+     * `annotateToolOutputWithReference`'s collision-detection logic
+     * through the projection entry point.
+     */
+    const registry = new ToolOutputReferenceRegistry();
+    registry.set('r1', 'tool0turn0', '{"a":1}');
+    const tm = makeToolMessage({
+      content: '{"a":1,"b":"x"}',
+      additional_kwargs: {
+        _refKey: 'tool0turn0',
+        _unresolvedRefs: ['tool9turn9'],
+      },
+    });
+    const out = annotateMessagesForLLM([tm], registry, 'r1');
+    const parsed = JSON.parse(out[0].content as string);
+    expect(parsed[TOOL_OUTPUT_REF_KEY]).toBe('tool0turn0');
+    expect(parsed[TOOL_OUTPUT_UNRESOLVED_KEY]).toEqual(['tool9turn9']);
+    expect(parsed.a).toBe(1);
+    expect(parsed.b).toBe('x');
+  });
+
+  it('uses [ref: …] prefix for non-JSON string content', () => {
+    const registry = new ToolOutputReferenceRegistry();
+    registry.set('r1', 'tool0turn0', 'raw');
+    const tm = makeToolMessage({
+      content: 'plain output',
+      additional_kwargs: { _refKey: 'tool0turn0' },
+    });
+    const out = annotateMessagesForLLM([tm], registry, 'r1');
+    expect(out[0].content).toBe('[ref: tool0turn0]\nplain output');
+  });
+
+  it('prepends an unresolved-refs warning text block to multi-part content', () => {
+    const registry = new ToolOutputReferenceRegistry();
+    const tm = makeToolMessage({
+      content: [
+        { type: 'text', text: 'data' },
+        { type: 'image_url', image_url: { url: 'data:...' } },
+      ] as unknown as ToolMessage['content'],
+      additional_kwargs: { _unresolvedRefs: ['tool9turn9'] },
+    });
+    const out = annotateMessagesForLLM([tm], registry, 'r1');
+    const blocks = out[0].content as Array<{ type: string; text?: string }>;
+    expect(blocks).toHaveLength(3);
+    expect(blocks[0].type).toBe('text');
+    expect(blocks[0].text).toBe('[unresolved refs: tool9turn9]');
+    expect(blocks[1].type).toBe('text');
+    expect(blocks[1].text).toBe('data');
+    expect(blocks[2].type).toBe('image_url');
+  });
+
+  it('does not mutate the original ToolMessage instance or its content', () => {
+    const registry = new ToolOutputReferenceRegistry();
+    registry.set('r1', 'tool0turn0', 'raw');
+    const tm = makeToolMessage({
+      content: 'output',
+      additional_kwargs: { _refKey: 'tool0turn0' },
+    });
+    const originalContent = tm.content;
+    const originalKwargs = { ...tm.additional_kwargs };
+    annotateMessagesForLLM([tm], registry, 'r1');
+    expect(tm.content).toBe(originalContent);
+    expect(tm.additional_kwargs).toEqual(originalKwargs);
+  });
+
+  it('strips framework ref metadata from the projected additional_kwargs but preserves other fields', () => {
+    /**
+     * Defensive: even though LangChain's standard provider serializers
+     * do not transmit `additional_kwargs`, a custom adapter or future
+     * LangChain change could. Strip our three framework-owned keys on
+     * the projection so the metadata never reaches the wire under any
+     * serializer behavior. Non-framework fields stay put.
+     */
+    const registry = new ToolOutputReferenceRegistry();
+    registry.set('r1', 'tool0turn0', 'raw');
+    const tm = makeToolMessage({
+      content: 'output',
+      additional_kwargs: {
+        _refKey: 'tool0turn0',
+        _refScope: 'r1',
+        _unresolvedRefs: ['tool9turn9'],
+        someOtherField: 'preserved',
+      },
+    });
+    const out = annotateMessagesForLLM([tm], registry, 'r1');
+    const projected = out[0] as ToolMessage;
+    expect(projected.additional_kwargs._refKey).toBeUndefined();
+    expect(projected.additional_kwargs._refScope).toBeUndefined();
+    expect(projected.additional_kwargs._unresolvedRefs).toBeUndefined();
+    expect(projected.additional_kwargs.someOtherField).toBe('preserved');
+    expect(tm.additional_kwargs._refKey).toBe('tool0turn0');
+    expect(tm.additional_kwargs._refScope).toBe('r1');
+  });
+
+  it('leaves additional_kwargs empty when stripping removed every framework key', () => {
+    /**
+     * `stripFrameworkRefMetadata` returns `undefined` when no non-
+     * framework keys remain, and the LangChain `ToolMessage`
+     * constructor normalizes that to `{}` — so the projected message
+     * exposes an empty object, not the original kwargs.
+     */
+    const registry = new ToolOutputReferenceRegistry();
+    registry.set('r1', 'tool0turn0', 'raw');
+    const tm = makeToolMessage({
+      content: 'output',
+      additional_kwargs: {
+        _refKey: 'tool0turn0',
+        _refScope: 'r1',
+      },
+    });
+    const out = annotateMessagesForLLM([tm], registry, 'r1');
+    const projected = out[0] as ToolMessage;
+    expect(projected.additional_kwargs).toEqual({});
+  });
+
+  it('passes through non-ToolMessages unchanged in the projected array', () => {
+    const registry = new ToolOutputReferenceRegistry();
+    registry.set('r1', 'tool0turn0', 'raw');
+    const human = new HumanMessage('hi');
+    const ai = new AIMessage('answer');
+    const tm = makeToolMessage({
+      content: 'output',
+      additional_kwargs: { _refKey: 'tool0turn0' },
+    });
+    const out = annotateMessagesForLLM([human, ai, tm], registry, 'r1');
+    expect(out[0]).toBe(human);
+    expect(out[1]).toBe(ai);
+    expect(out[2]).not.toBe(tm);
+  });
+
+  it('projects (to strip metadata) but does not annotate when only stale _refKey is present', () => {
+    const registry = new ToolOutputReferenceRegistry();
+    registry.set('r1', 'tool1turn0', 'somethingelse');
+    const tm = makeToolMessage({
+      content: 'output',
+      additional_kwargs: { _refKey: 'tool0turn0' },
+    });
+    const messages = [tm];
+    const out = annotateMessagesForLLM(messages, registry, 'r1');
+    expect(out).not.toBe(messages);
+    expect(out[0].content).toBe('output');
+    expect((out[0] as ToolMessage).additional_kwargs._refKey).toBeUndefined();
+  });
+
+  it('returns the input array reference-equal when no ToolMessage carries any framework metadata', () => {
+    const registry = new ToolOutputReferenceRegistry();
+    registry.set('r1', 'tool0turn0', 'stored');
+    const messages = [
+      new HumanMessage('hi'),
+      makeToolMessage({
+        content: 'output',
+        additional_kwargs: { unrelated: 'value' },
+      }),
+      new AIMessage('answer'),
+    ];
+    const out = annotateMessagesForLLM(messages, registry, 'r1');
+    expect(out).toBe(messages);
+  });
+
+  it('annotates only the live ref when both ref and unresolved are present', () => {
+    const registry = new ToolOutputReferenceRegistry();
+    registry.set('r1', 'tool0turn0', 'raw');
+    const tm = makeToolMessage({
+      content: 'output',
+      additional_kwargs: {
+        _refKey: 'tool0turn0',
+        _unresolvedRefs: ['tool9turn9'],
+      },
+    });
+    const out = annotateMessagesForLLM([tm], registry, 'r1');
+    expect(out[0].content).toBe(
+      '[ref: tool0turn0]\noutput\n[unresolved refs: tool9turn9]'
+    );
+  });
+
+  it('uses _refScope for the registry lookup when present, ignoring runId', () => {
+    /**
+     * Anonymous ToolNode batches register under a synthetic scope
+     * (`\0anon-<n>`) that `config.configurable.run_id` cannot recover.
+     * The transform must follow the message-stamped `_refScope`
+     * instead of the config-derived runId.
+     */
+    const registry = new ToolOutputReferenceRegistry();
+    const anonScope = '\0anon-3';
+    registry.set(anonScope, 'tool0turn0', 'raw');
+
+    const tm = makeToolMessage({
+      content: 'output',
+      additional_kwargs: {
+        _refKey: 'tool0turn0',
+        _refScope: anonScope,
+      },
+    });
+    const out = annotateMessagesForLLM([tm], registry, undefined);
+    expect(out[0].content).toBe('[ref: tool0turn0]\noutput');
+  });
+
+  it('falls back to runId when _refScope is absent (legacy / pre-scope messages)', () => {
+    const registry = new ToolOutputReferenceRegistry();
+    registry.set('r1', 'tool0turn0', 'raw');
+    const tm = makeToolMessage({
+      content: 'output',
+      additional_kwargs: { _refKey: 'tool0turn0' },
+    });
+    const out = annotateMessagesForLLM([tm], registry, 'r1');
+    expect(out[0].content).toBe('[ref: tool0turn0]\noutput');
+  });
+
+  it('coerces a non-array _unresolvedRefs to empty without throwing', () => {
+    /**
+     * Defensive against malformed hydrated messages:
+     * `additional_kwargs._unresolvedRefs` is untyped at the LangChain
+     * layer, so a persisted message could carry a string/object/null
+     * by mistake. The transform must not crash the run on
+     * `.length` / `.join` — coerce to an empty list, strip the
+     * malformed key, and proceed.
+     */
+    const registry = new ToolOutputReferenceRegistry();
+    const tm = makeToolMessage({
+      content: 'output',
+      additional_kwargs: {
+        _unresolvedRefs: 'tool9turn9' as unknown as string[],
+      },
+    });
+    const out = annotateMessagesForLLM([tm], registry, 'r1');
+    expect(out[0].content).toBe('output');
+    expect(
+      (out[0] as ToolMessage).additional_kwargs._unresolvedRefs
+    ).toBeUndefined();
+  });
+
+  it('filters non-string entries out of _unresolvedRefs', () => {
+    const registry = new ToolOutputReferenceRegistry();
+    const tm = makeToolMessage({
+      content: 'output',
+      additional_kwargs: {
+        _unresolvedRefs: [
+          'tool9turn9',
+          42,
+          null,
+          { not: 'a string' },
+          'tool8turn8',
+        ] as unknown as string[],
+      },
+    });
+    const out = annotateMessagesForLLM([tm], registry, 'r1');
+    expect(out[0].content).toBe(
+      'output\n[unresolved refs: tool9turn9, tool8turn8]'
+    );
+  });
+
+  it('ignores a non-string _refKey rather than poisoning the registry lookup', () => {
+    const registry = new ToolOutputReferenceRegistry();
+    registry.set('r1', 'tool0turn0', 'raw');
+    const tm = makeToolMessage({
+      content: 'output',
+      additional_kwargs: {
+        _refKey: { malformed: true } as unknown as string,
+      },
+    });
+    const out = annotateMessagesForLLM([tm], registry, 'r1');
+    expect(out[0].content).toBe('output');
+    expect((out[0] as ToolMessage).additional_kwargs._refKey).toBeUndefined();
+  });
+
+  it('treats stale _refKey but live unresolved as unresolved-only', () => {
+    const registry = new ToolOutputReferenceRegistry();
+    const tm = makeToolMessage({
+      content: 'output',
+      additional_kwargs: {
+        _refKey: 'tool0turn0',
+        _unresolvedRefs: ['tool9turn9'],
+      },
+    });
+    const out = annotateMessagesForLLM([tm], registry, 'r1');
+    expect(out[0].content).toBe('output\n[unresolved refs: tool9turn9]');
+  });
+});

package/src/tools/toolOutputReferences.ts

@@ -22,6 +22,8 @@
  * complete, verbatim output with no injected fields.
  */
 
+import { ToolMessage } from '@langchain/core/messages';
+import type { BaseMessage } from '@langchain/core/messages';
 import {
   calculateMaxTotalToolOutputSize,
   HARD_MAX_TOOL_RESULT_CHARS,
@@ -243,6 +245,16 @@ export class ToolOutputReferenceRegistry {
     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: string | undefined, key: string): boolean {
+    return this.runStates.get(this.keyFor(runId))?.entries.has(key) ?? false;
+  }
+
   /** Total number of registered outputs across every run bucket. */
   get size(): number {
     let n = 0;
@@ -588,3 +600,214 @@ function arraysShallowEqual(a: unknown, b: readonly string[]): boolean {
   }
   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.
+ */
+export function annotateMessagesForLLM(
+  messages: BaseMessage[],
+  registry: ToolOutputReferenceRegistry | undefined,
+  runId: string | undefined
+): BaseMessage[] {
+  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: BaseMessage[] | undefined;
+  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 under our framework
+     * keys. Treat them as untrusted input and coerce defensively
+     * before any array operation — a malformed field on a single
+     * hydrated message must not crash `attemptInvoke` before the
+     * provider call.
+     */
+    const meta = m.additional_kwargs as Record<string, unknown> | undefined;
+    const hasRefKey = meta != null && '_refKey' in meta;
+    const hasRefScope = meta != null && '_refScope' in meta;
+    const hasUnresolvedField = meta != null && '_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 as ToolMessage;
+    let nextContent: ToolMessage['content'] = 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' as const,
+        text: `[unresolved refs: ${unresolved.join(', ')}]`,
+      };
+      nextContent = [
+        warningBlock,
+        ...tm.content,
+      ] as unknown as ToolMessage['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: Record<string, unknown> | undefined
+): string | undefined {
+  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: Record<string, unknown> | undefined
+): string | undefined {
+  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: Record<string, unknown> | undefined
+): string[] {
+  const v = meta?._unresolvedRefs;
+  if (!Array.isArray(v)) return [];
+  const out: string[] = [];
+  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: ToolMessage,
+  content: ToolMessage['content']
+): ToolMessage {
+  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: Record<string, unknown> | undefined
+): Record<string, unknown> | undefined {
+  if (kwargs == null) return undefined;
+  if (
+    !('_refKey' in kwargs) &&
+    !('_refScope' in kwargs) &&
+    !('_unresolvedRefs' in kwargs)
+  ) {
+    return kwargs;
+  }
+  const { _refKey, _refScope, _unresolvedRefs, ...rest } = kwargs as Record<
+    string,
+    unknown
+  > & {
+    _refKey?: unknown;
+    _refScope?: unknown;
+    _unresolvedRefs?: unknown;
+  };
+  void _refKey;
+  void _refScope;
+  void _unresolvedRefs;
+  return Object.keys(rest).length === 0 ? undefined : rest;
+}

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[];
+}