fix(openrouter): restore reliable prompt caching

[navedmerchant]

Related GitHub Issue

Closes: #1277

Description

Restores reliable OpenRouter prompt caching for agentic, multi-turn tasks.

• Sends the stable Zoo task ID as OpenRouter's top-level session_id, enabling provider sticky routing after the first successful request so later turns return to the endpoint holding the warm cache.
• Uses live model capability metadata to enable explicit cache breakpoints for newly released Anthropic models, while retaining the existing static allowlist as a fallback for stale cached metadata.
• Preserves the existing explicit-breakpoint behavior for allowlisted Gemini models; newer implicitly cached Gemini models are not given unnecessary explicit markers.
• Maps OpenRouter's prompt_tokens_details.cache_write_tokens into Zoo's cache-write usage field.
• Adds regression coverage for new Anthropic models, task-based session affinity, and cache read/write accounting.

Reviewers should pay particular attention to using metadata.taskId as the session-affinity key. It is stable across turns in one Zoo task and stays within OpenRouter's documented 256-character limit.

Test Procedure

From src/:

npx vitest run api/providers/__tests__/openrouter.spec.ts
pnpm exec eslint --prune-suppressions --max-warnings=0 api/providers/openrouter.ts
pnpm exec prettier --check api/providers/openrouter.ts api/providers/__tests__/openrouter.spec.ts

Results:

• OpenRouter provider tests: 27 passed.
• Repository pre-commit lint: all 11 Turbo lint tasks passed.
• Production-file ESLint: passed with zero warnings and no suppression-count increase.
• Prettier: passed.
• git diff --check: passed.

A full TypeScript check was attempted but is currently blocked by unrelated missing existing workspace dependencies used by Bedrock: @smithy/node-http-handler, http-proxy-agent, and https-proxy-agent.

Pre-Submission Checklist

• Issue Linked: This PR is linked to an approved GitHub Issue (see "Related GitHub Issue" above).
• Scope: My changes are focused on the linked issue (one major feature/fix per PR).
• Self-Review: I have performed a thorough self-review of my code.
• Testing: New and/or updated tests have been added to cover my changes (if applicable).
• Visual Snapshot (UI changes only): Not applicable; this PR has no UI changes.
• Documentation Impact: I have considered if my changes require documentation updates (see "Documentation Updates" section below).
• Contribution Guidelines: I have read and agree to the Contributor Guidelines.

Visual Snapshots

Not applicable; no UI changes.

Videos (interaction / animation only)

Not applicable; no interaction or animation changes.

Documentation Updates

• No documentation updates are required.
• Yes, documentation updates are required.

Additional Notes

OpenRouter prompt caching itself remains available. The reported behavior was caused by Zoo not supplying the session affinity OpenRouter now recommends for agent workflows, combined with a stale static model allowlist and incomplete cache-write accounting.

Get in Touch

GitHub: @navedmerchant

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: e1b7e699-4f52-4ea2-949e-f86d3c9a9e7b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

❌ Patch coverage is 33.33333% with 4 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/api/providers/openrouter.ts	33.33%	2 Missing and 2 partials ⚠️

📢 Thoughts on this report? Let us know!