Feature/agent cache adding OpenAI anthropic llamaindex adapters

[KIvanow]

Summary

Adds multi-modal support to @betterdb/agent-cache via three new SDK adapters (OpenAI Chat, Anthropic, LlamaIndex), a new OpenAI Responses adapter, a pluggable binary normalizer for content-addressed image/audio/document hashing,
and a storeMultipart() method on the LLM cache tier. All four adapters normalize to a shared intermediate representation, so the same cached response can be served regardless of which SDK the caller uses.

Changes

• src/normalizer.ts - New pluggable binary normalizer API: hashBase64, hashBytes, hashUrl, fetchAndHash, passthrough, composeNormalizer, defaultNormalizer. Allows callers to control how image/audio/document bytes are reduced to
  a stable cache key ref.
• src/adapters/openai-chat.ts - prepareParams() for OpenAI Chat Completions. Handles all 6 message roles, image/audio/file content parts, parallel tool calls, and __raw fallback for malformed tool arguments.
• src/adapters/anthropic.ts - prepareParams() for Anthropic Messages API. Splits tool_result blocks into separate IR tool messages, preserves cache_control as hints.anthropicCacheControl, maps thinking/redacted-thinking to
  ReasoningBlock.
• src/adapters/llamaindex.ts - prepareParams() for LlamaIndex ChatMessage[]. Dispatches on options.toolCall / options.toolResult, maps memory role to system.
• src/adapters/openai-responses.ts - prepareParams() for OpenAI Responses API. State machine groups consecutive function_call items into one assistant block, handles reasoning items with encrypted_content.
• src/utils.ts - Widened llmCacheHash with new optional params (toolChoice, seed, stop, responseFormat, reasoningEffort, promptCacheKey). Added ContentBlock union and sub-types (TextBlock, BinaryBlock, ToolCallBlock,
  ToolResultBlock, ReasoningBlock, BlockHints). Backward compatible - text-only callers produce identical hashes to v0.2.0.
• src/tiers/LlmCache.ts - Added contentBlocks? to stored entries and new storeMultipart() method. check() now surfaces contentBlocks on hits.
• src/types.ts - Added LlmCacheMessage, widened LlmCacheParams with 6 new optional fields, extended LlmCacheResult with contentBlocks, model, storedAt, tokens, cost.
• package.json - Added openai, @anthropic-ai/sdk, @llamaindex/core as optional peer dependencies. Added ./openai, ./anthropic, ./llamaindex, ./openai-responses export paths.
• examples/openai/, examples/anthropic/, examples/llamaindex/ - Runnable examples with standalone + cluster support, vision, tool calls, and cost savings display.
• 29 new tests across hash-backcompat, normalizer, openai-chat, anthropic, llamaindex, openai-responses, and cross-provider test files.

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
Moderate risk because it expands the public API and changes the LLM cache entry shape/hashing logic (new optional fields and contentBlocks), which could affect cache hit rates and interoperability across SDKs.

Overview
Adds multi-modal LLM caching to @betterdb/agent-cache by introducing a shared content-block IR (text/binary/tool_call/reasoning), a pluggable binary normalizer (composeNormalizer, hashBase64/hashUrl/etc.), and a new llm.storeMultipart() path that stores both flattened text and structured contentBlocks (with check() now returning them on hits).

Introduces new provider adapters and exports for OpenAI Chat, OpenAI Responses, Anthropic, and LlamaIndex (prepareParams), plus cross-provider fixtures/tests to ensure these adapters normalize to the same params+hash. Updates package exports/peers, bumps version to 0.3.0, adds runnable examples for the new adapters, and extends the release workflow build verification to include the new adapter artifacts.

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

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 53ff629. Configure here.}

[cursor]

Local parseInput duplicates shared parseToolCallArgs utility

Low Severity

The private parseInput function in llamaindex.ts duplicates the logic of the exported parseToolCallArgs in utils.ts. Both parse a JSON string with a { __raw: ... } fallback, but they differ subtly for empty-string inputs: parseToolCallArgs coalesces "" to "{}" yielding {}, while parseInput would let JSON.parse("") throw and return { __raw: "" }. This hidden inconsistency means empty tool-call arguments hash differently depending on which adapter produced them. The LlamaIndex adapter could delegate to parseToolCallArgs for string inputs and only add the pass-through for non-string inputs.

Additional Locations (1)

• packages/agent-cache/src/utils.ts#L139-L146

 

^{Reviewed by Cursor Bugbot for commit 53ff629. Configure here.}

[cursor]

storeMultipart missing cache.model span attribute

Low Severity

The storeMultipart method doesn't set span.setAttribute('cache.model', params.model) like the existing store method does (which sets it at line 169). This omission causes the OpenTelemetry span for multipart stores to lack the model attribute, making traces harder to filter and analyze. The fallback value for the TTL attribute also differs: store uses ttl ?? -1 while storeMultipart uses ttl ?? 0, creating an inconsistent sentinel for "no TTL."

 

^{Reviewed by Cursor Bugbot for commit 53ff629. Configure here.}