feat: add first-class OpenRouter provider support

[wpfleger96]

Summary

First-class Provider::OpenRouter support joining the existing anthropic/openai/databricks providers. Reuses the Chat Completions path with targeted mutations for OpenRouter's routing contract.

Core (crates/buzz-agent):

• Provider::OpenRouter enum variant with OPENROUTER_API_KEY, BUZZ_AGENT_MODEL → OPENROUTER_MODEL fallback, OPENROUTER_BASE_URL env convention
• Body mutator: reasoning: {effort} when effort is configured, and max_completion_tokens translated to OpenRouter's max_tokens spelling; no provider.require_parameters filter (it routes only to endpoints advertising every parameter in the body, which hard-404s a valid model id); summaries get neither. openai_body is always called with effort=None on the OpenRouter path — the reasoning object is added by the mutator directly, so reasoning_effort is structurally absent.
• Attribution headers: HTTP-Referer: https://github.com/block/buzz, X-OpenRouter-Title: Buzz
• Error-inside-200 check in shared parse_openai (finish_reason == "error")
• 401 auth handling: static API keys (refresh_now returns the same token) fail terminal immediately with one wire request; PKCE/minting sources get one retry with the fresh token.
• Status+error_type retry matrix (4-arm collapsed form): 429 (honor Retry-After), 502 (retry), 503/provider_overloaded (honor Retry-After), everything else including untyped 503 (bounded retries → actionable routing message). 499 included matching shared post() (fix(timeout): unified turn-timeout fix — cap inheritance, steer renewal, activity-aware requeue, LLM stall surfacing #2175) for turn-timeout stall surfacing. Terminal failures wrapped in terminal_llm_error for duration+attempt-count context.
• anthropic/* cache_control injection (model-gated, mixed-content safe)
• Provider-agnostic reasoning_details opaque round-trip on HistoryItem::Assistant for tool-call continuations — captured verbatim in parse_openai_with_reasoning_details, replayed verbatim in openai_body, byte-accounting charged. provider_extra passthrough from make_tool_call composes independently.

Desktop:

• Readiness arms checking OPENROUTER_API_KEY + OPENROUTER_MODEL
• Model discovery via {OPENROUTER_BASE_URL}/models filtered on supported_parameters contains tools
• Picker entry, credential config, effort table 3-file sync

desktop/src/features/agents/AGENTS.md: no rules changed — the scoped rule requiring an explicit note is satisfied here.

Implements the gate-cleared plan from PLANS/OPENROUTER_PROVIDER_PLAN.md (rev 3).

[wesbillman]

Carl (AI agent) commenting on Wes’s behalf.

Re-reviewed the current PR head, 5baa132418411f73afe575c74b2b63c56b935e92, against current main, 005b5b819a98ce85d4d80cd81b258fb6f9b8d51e. The blocking issue remains unchanged: this single OpenRouter commit still modifies 50 files and carries 1,861 deletions, silently reverting nine unrelated merged PRs.

Concrete production regressions still present in the current diff:

• mobile/lib/shared/relay/relay_provider.dart removes the wss:// → https:// normalization from fix(mobile): keep TLS on relays joined by invite #3139. An invite-persisted wss:// URL then falls through wsUrl’s non-HTTPS arm and becomes plaintext ws://. The identity-scoped preference migration and its regression tests are also deleted.
• desktop/src-tauri/src/commands/personas/snapshot/import.rs removes the avatar materialization/upload from Fix shared agent avatar import profiles #3578, restoring inline data URLs in imported profiles and recreating oversized/unpublishable profile payloads.
• crates/buzz-relay/src/telemetry.rs removes the trace-context lookup and JSON trace/span correlation added by feat(tracing): correlate trace IDs in relay logs #3608.
• The diff also reverts merged work from chore(ci): bump Linux AppImage build container to ubuntu:24.04 #3602, feat(cli): mirror Desktop mention delivery #3330, fix(desktop): deduplicate relay outage notification #3579, fix(desktop): reconcile thread arrivals at bottom #3585, Improve emoji autocomplete matching #3571, and Fix inline raster avatars in agent catalog #3581.

CI being green does not make these reversions safe: the reverted implementations previously passed CI, and this branch deletes several of the regression tests that would catch them.

The OpenRouter-specific implementation itself looks careful and has strong coverage, but it needs to be rebuilt/rebased so the PR preserves current main and contains only the intended OpenRouter files. Princess Donut’s independent review identified one additional small fix in that clean rebuild: crates/buzz-agent/src/llm.rs:2050 should use OpenRouter’s documented X-Title attribution header rather than X-OpenRouter-Title, and the corresponding assertion should be updated.

Requested change: replace this head with a clean OpenRouter-only diff on current main, preserve all nine unrelated merged changes, correct the attribution header, and request re-review. Please do not merge the current head.

[wesbillman]

Carl (AI agent) commenting on Wes’s behalf.

Re-review update: the earlier blocking comment is fully resolved at head 7ca120a3d5c9350eac6d0358a80fdba6ba28d534.

• The diff is now limited to the intended 15 OpenRouter files; all nine unrelated reversions are gone.
• Two independent spot-checks agreed that the corrected diff preserves the previously reviewed OpenRouter implementation and has no remaining correctness blocker.
• Correction to the earlier attribution note: current OpenRouter documentation uses X-OpenRouter-Title as the primary header and accepts X-Title as an alias. The implementation is correct as written.
• All required checks on this exact PR head are now complete and green (with Mobile/Web skipped because those paths are untouched).
• main has advanced and now overlaps in agent.rs, llm.rs, and types.rs via feat(agent,acp): wire provider total_tokens through NIP-AM publish chain #3593, but Git’s current merge-tree resolves the branches cleanly, and GitHub reports the PR mergeable.

No remaining review findings from me. The optional comment documenting Anthropic’s four-cache-breakpoint ceiling remains a maintenance nit only and should not block this PR.