[Shabonasar]

Summary

With tool output references on, ToolNode labels each tool result with [ref: tool<i>turn<n>] in the request it sends live. The label was shown only while the key was in the current run's registry, and every run restarted at turn0. As a result, a restored history lost the labels: the first request of each later turn missed the prompt cache, and Claude dropped thinking blocks bound to the old prefix. Keys also repeated between turns, so {{tool0turn0}} from an old turn silently resolved to the current turn's output. With this PR the label is the stored name of the output: it is saved with the result, restored with the history, and turn numbers continue across runs.

Fixes #627

Related to LibreChat-AI/LibreChat#17102. Base: main, no dependency on other PRs. LibreChat needs no change: the fields ride in the stored tool_call part.

How it works

live:     ToolNode key tool0turn7 -> ON_RUN_STEP_COMPLETED.tool_call { output, ref, unresolved_refs? } -> host stores it
restore:  formatAgentMessages: ref -> ToolMessage.additional_kwargs._refKey
          Run: turn counter = highest restored turn + 1   (keys never repeat)
request:  annotateMessagesForLLM labels by _refKey, no registry lookup, after truncation (byte-equal to live)

• The completion event carries ref / unresolved_refs for direct tools, event-driven tools (batch and early completion) and eager executions.
• An old key is not in the registry, so it stays literal with the existing [unresolved refs: ...] warning.
• Handoff agents share one registry (one seed); subagents have their own run and history.
• Tests that expected "no label when the key is missing from the registry" now expect the label.
• Not changed: a placeholder in the same parallel batch as the call it names stays literal without a warning.

Type of change

• Bug fix

Testing

Tested environments/configuration:

The table comes from an earlier run on a head with the same code. Real Anthropic API through LibreChat, 6 turns, adaptive thinking, code interpreter running code, chained bash_tool calls, MCP tool, restart after turn 3, turn 5 references a key from turn 1. "series" is the LibreChat series plus agents #613, #614, #615, #619 (LibreChat-AI/LibreChat#17102); dev is LibreChat dev with agents main. "before" used a 1h cache TTL, "after" 5m.

model	LibreChat	agents	cache hit	misses	dropped thinking blocks	400
Haiku 5.5	series	before	87.9%	4	28	0
Haiku 5.5	series	this PR	92.9%	0	0 (2nd run: 1, from #618)	0
Sonnet 5.5	series	before	86.1-88.4%	3	10	0
Sonnet 5.5	series	this PR	90.8%	0	0	0
Haiku 5.5	dev	before	88.6%	5	0	0
Haiku 5.5	dev	this PR	87.5%	5	0	0

With the series, keys run tool0turn0...tool0turn8 without repeats, and the turn-5 probe returns [unresolved refs: tool0turn0] instead of a wrong output. On dev the labels are now stable too; its misses come from other restore differences that the series fixes.

Automated tests:

npx jest src/messages src/llm src/graphs src/tools src/agents src/summarization
npx tsc --noEmit

• This PR: 4803 passed. 3 suites fail because they need API keys (anthropic, google, vertexai llm.spec.ts).
• ToolNode.outputReferences.test.ts: key and unresolved refs on the completed tool_call (direct and event-driven), none when the feature is off, an earlier run's key reported as unresolved, a run seeded from the keys in its input history. invoke.test.ts: hydrated run 1 messages labelled, run 2 keys not repeating them.
• formatAgentMessages.tools.test.ts: stored key and unresolved refs restored and labelled as live, including the parts stored by the content aggregator. toolOutputReferences.test.ts, annotateMessagesForLLM.test.ts: turn counter continuity, labelling by _refKey without a registry entry.
• All five SDK PRs together (fix: Keep Per-Conversation Context and the Summary at a Fixed System Position #613, feat: Add a Fixed Tool Dispatcher for Mid-Conversation Tools #614, fix: Restore Tool Rounds Exactly as the Live Request Sent Them #615, feat: Replay Signed Reasoning in Restored History #619, fix(tools): persist tool output reference labels and keep keys unique across runs #629): 6987 passed. Failing: the 3 suites above, plus durability-checkpoint.integration.test.ts and persistent-handoffs.test.ts, which need MongoDB and fail on main too. LibreChat agent suites against all five: packages/api src/agents 6913 passed (1 failure in handlers.shutdown.spec.ts, a shutdown timing test); api server/controllers/agents 1371 passed.

Risk / compatibility

• Only with tool output references on. A restored history now carries the labels the live request had. A history stored before this change has no ref and stays unlabelled, as it is today.

Checklist

• I reviewed my own changes
• Relevant tests have been added or updated
• Existing relevant tests pass
• The change does not introduce new warnings or errors
• Required dependency changes have been merged/published (none)

[Shabonasar]

Updated to current main and reduced to simplify the review: no dependency on other PRs, +546 -> +480 lines.

• Code unchanged (one block in stream.ts written shorter, same behaviour); tests consolidated: the separate ToolNode.persistedReferences.test.ts is folded into the existing ToolNode.outputReferences, formatAgentMessages.tools and toolOutputReferences suites.
• Checked: SDK suites (4803 passed, the 3 llm.spec.ts suites need API keys); all five SDK PRs together 6987 passed; LibreChat agent suites against all five.