Stable prompt prefix for agents (fix for #16877): approach and split plan

[Shabonasar]

Asking for approval of the approach before any further review: the fix for the prompt-cache regression in #16877 and for the other cache breakers below, designed and measured in #17102. The regression itself is one row of the table; the rest of the series removes the others.

Problem

Provider prompt caches (Anthropic, Bedrock, OpenAI, OpenRouter, vLLM/SGLang prefix caching) reuse a request only up to its first changed byte. Agent requests change early bytes on almost every turn, so the whole prompt is processed again:

what changes	where
timestamp, every turn (#15419)	system prompt
memory, files, project re-read every request	system prompt
MCP servers, actions, built-ins switched mid-chat	tools, reordered
tool rounds, Responses items, compaction summary, signed thinking	history restored differently from the live request

Approach

[tools: fixed set + call_tool][system: stable part][history: as sent live][context events][user]
       added mid-chat -> event       anchored at conversation start    date change, memory diff

• Time anchored to the conversation start; a date change arrives as an event in the history.
• Memory, files and project are snapshotted at Send and stored on the user message; changes arrive as <context_update> in the user message.
• Fixed tool set; tools enabled mid-chat are reached through a call_tool dispatcher.
• Restored history equals the live request byte for byte.

Changes to what the model sees sit behind endpoints.agents.promptCache.stableContext (default false). Fixes that only make the restored history equal to the live one need no setting.

Result

Uncached prompt tokens over three scenarios (plain chat, tools toggled, compaction): Anthropic -58%, OpenAI -61%, Kimi -45%, GLM -39%, self-hosted vLLM -27%. Plain chat goes from 0% cached to 80-88%. Details and the kit to repeat: #17102.

Plan

The open PRs are already reduced to these steps; each keeps its regression tests, full test matrices are in the measurement kit. Some of them are independent and can be reviewed in any order; the others build on them, which is why they form a series. One at a time is fine.

step	PR	scope	based on	setting
1	LibreChat-AI/agents#615	restored tool rounds and Responses items equal the live request	main	no
2	LibreChat-AI/agents#613	fixed position for per-conversation instructions; Bedrock tail behind the cached history	main	no
3	#16369	the setting, stable system prompt, date as event	dev	yes
4	#17146	memory, files, project as send-time events	#16369	yes
5	LibreChat-AI/agents#614, #17147	fixed tool set with call_tool dispatcher	main; #17146	yes
6	#17149	provider output items stored and replayed	dev, needs step 1	no
7	LibreChat-AI/agents#619, #17189	signed thinking stored and replayed, direct Anthropic API (based on #14547 and LibreChat-AI/agents#371 by @upman); Bedrock in a follow-up	step 1; #17149 + #16369	yes
8	#17514	stable context passed as the SDK conversation block	#17146, needs step 2	yes

Based directly on main / dev: steps 1, 2, 3, 6 and LibreChat-AI/agents#614; step 6 is a no-op until step 1 is released. Ready-made builds of the whole series: integration/prompt-cache in both forks (see #17102).

Questions

1. Is this approach acceptable, in particular the setting and context changes as events in the history?
2. Can [Bug]: web_search runtime context stamps the system prompt, defeating prompt caching (regression) #16877 (the regression, fixed by step 3) and Tracking: stable prompt prefix cache across turns, conversations and providers #17102 (the tracking issue for the rest of the series) be assigned to me?