fix(agent-cache): include tool definitions in cache key for Vercel an…

[KIvanow]

Summary

Include tool definitions (and other missing generation parameters) in the cache key for the Vercel AI SDK and LlamaIndex adapters. Previously, identical messages with different tools could return the same cached response on these adapters.

Changes

• Vercel AI SDK adapter (ai.ts): Added tools, seed, stopSequences, responseFormat, and toolChoice to the local params interface and pass them through to the cache key path. Tools are converted from the AI SDK flat shape ({ type, name, inputSchema }) to the core canonical shape ({ type, function: { name, parameters } }).
• LlamaIndex adapter (llamaindex.ts + llamaindex.py): Added a tools field to LlamaIndexPrepareOptions / prepare_params. Tool metadata (name, description, parameters) is extracted from each tool object; the non-serializable call closure is never included. Omitting tools falls back to messages-only keying (prior behavior).
• No changes to langchain.ts logic. The framework's BaseCache interface only exposes (prompt, llm_string), so tool definitions are structurally unreachable. Documented as a known limitation.
• Key divergence tests for all three fixed paths (Vercel TS, LlamaIndex TS, LlamaIndex Python) covering tool sensitivity, order-invariant stability, tools-absent baseline, extra param sensitivity (Vercel), canonical-shape parity (Vercel), and closure safety (LlamaIndex).
• Docs updated for all three adapters in docs/packages/agent-cache.md.
• Changelogs updated for both TS and Python packages (0.7.0).

Breaking/behavioral note: tool-using requests on these adapters will produce different keys than before, so existing cached entries for those requests will be a one-time miss after upgrade. This is intended -- the prior entries were not safe to reuse across differing tool sets.

Checklist

• Unit / integration tests added
• Docs added / updated
• Roborev review passed — run roborev review --branch or /roborev-review-branch in Claude Code (internal)
• Competitive analysis done / discussed (internal)
• Blog post about it discussed (internal)

---

Note

Medium Risk
Changes cache key semantics for tool-using LLM requests (intentional one-time misses); incorrect keys previously risked stale wrong answers, so rollout should be monitored on cached agent paths.

Overview
Fixes incorrect LLM cache hits where the same messages could share a cached response despite different tools or generation settings on the Vercel AI SDK and LlamaIndex adapters (TS and Python).

The Vercel middleware now maps tools, toolChoice, seed, stopSequences, and responseFormat (plus maxOutputTokens) into LlmCacheParams, converting AI SDK tool shapes to the canonical { type, function: { name, parameters } } form. LlamaIndex prepareParams / prepare_params gains an optional tools argument that serializes only tool metadata (name, description, parameters), not call closures.

0.7.0 changelogs and agent-cache docs note a one-time cache miss for tool-using requests after upgrade (old keys were unsafe). LangChain is unchanged; docs call out that BaseCache cannot include tools in the key. New adapter key-divergence tests cover tool sensitivity, order invariance (via core hash sorting), and closure safety.

^{Reviewed by Cursor Bugbot for commit 52068ba. Bugbot is set up for automated code reviews on this repo. Configure here.}