Repository navigation
Commit 9c394a6
committed
feat(providers): phase 02 03-openrouter — OpenRouter + router + gate + pool + docs
Phase 02 ✅ COMPLETE.
Executed via a 5-agent parallel team for the independent modules, then
reconciled in the main session (barrel exports, engine/src/index.ts glue,
linter misfires on async generators in tests).
New modules:
- engine/src/providers/openrouter.ts (659) — OpenRouterProvider with:
* Hand-rolled SSE parser, no new deps. Ignores `: OPENROUTER PROCESSING`
comments; stops on `data: [DONE]`.
* Recursive stripCacheControl on the entire outbound body. Test walks
the captured body and asserts zero cache_control survives
(research-notes §7.3 — issue #1245 silent-drop, #17910 400-on-OAuth).
* OpenAI-compat body translation: `system[]` → prepended system msgs;
Anthropic tool_use/tool_result blocks ↔ OpenAI tool_calls + tool role;
`input_schema` → `function.parameters`; `tool_use.input` object →
`function.arguments` JSON string.
* Emits chunks in the Anthropic `RawMessageStreamEvent` shape
(synthetic message_start + content_block_start/delta/stop +
message_delta + message_stop) so the Phase 03 event adapter can stay
provider-agnostic.
* Module-level `warned` flag + `__resetOpenRouterWarningForTests`.
Warning emitted EXACTLY ONCE per process when routing an
`anthropic/*` model; the full SPEC §6.2 string with issues #1245
and #17910 cited.
* Mirror Anthropic retry matrix (3 attempts / 30s / jitter /
Retry-After honored), plus 402 added to non-retryable (OR-specific
credit-exhausted). Mid-stream errors never retry.
* HTTP-Referer + X-Title default to repo URL + "jellyclaw".
- engine/src/providers/router.ts (147) — ProviderRouter implements
Provider. Pre-stream-only failover (tracks `yieldedFromPrimary` to
avoid duplicate/interleaved output after first chunk). `shouldFailover`
duck-types errors (provider-agnostic — no @anthropic-ai/sdk import):
status in {429,500,502,503,504}, code in {ECONNRESET,ETIMEDOUT,EPIPE},
Connection/APIConnection error name. AbortError propagates without
failover. Logger emits `provider.failover {from, to, reason}`.
- engine/src/providers/gate.ts (40) — enforceCachingGate(config, model)
takes an EXPLICIT model arg for dispatch-time overrides. Reuses
CachingGateError from config/loader.ts. Complements
assertCachingGate(config) which runs at config-load.
- engine/src/providers/credential-pool.ts (216) — Contiguous
`ANTHROPIC_API_KEY_1..N` / `OPENROUTER_API_KEY_1..N` scan. configKey
wins over pool. Round-robin skipping dead slots. rotateOnRateLimit
force-advances; markCurrentDead(reason) flips a slot; AllKeysDeadError
when all dead. Keys held in CLOSURE so JSON.stringify(pool) cannot
leak them (test verifies).
- docs/providers.md (658) — User-facing docs. Selection matrix, caching
matrix with updated min-cacheable-token table (Opus 4.6=4096,
Sonnet 4.6=2048, Haiku 4.5=4096), 4-breakpoint rules with invalidation
hierarchy, `anthropic-beta: extended-cache-ttl-2025-04-11` header,
OpenRouter caveat section citing anomalyco/opencode#1245 +
OpenRouterTeam/ai-sdk-provider#35 + anomalyco/opencode#17910,
acknowledgeCachingLimits gate decision table, pooling semantics,
retry/failover, 3 JSON config examples, 8-item pitfalls list, 10-Q FAQ.
Adjacent changes:
- engine/src/providers/types.ts — Provider.name union now includes
"router" so ProviderRouter implements Provider typechecks.
- engine/src/providers/index.ts — barrel exports all new modules
(OpenRouterProvider, ProviderRouter, shouldFailover, enforceCachingGate,
CachingGateError, resolveCredentials, AllKeysDeadError, CredentialPool).
- engine/src/index.ts — makeProvider now constructs OpenRouterProvider
with the new {apiKey, baseURL, logger} shape (Phase 0 stub tolerates
missing key; Phase 10 replaces this glue).
Tests: 147/147 (54 new in Prompt 03): 14 openrouter + 13 router + 15
gate + 12 credential-pool. `bun run typecheck` ✅; `bun run test` ✅
(incl. live opencode-ai e2e from Phase 01); biome ✅ on all provider
files + 4 targeted biome-ignore comments on async generators in tests
where the useAwait rule misfires (generators yielding canned chunks
don't need await); build ✅.
Phase 02 closed. Next: Phase 03 (Event stream adapter).1 parent 252c9e8 commit 9c394a6
14 files changed
Lines changed: 3069 additions & 85 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | 1 | | |
2 | 2 | | |
3 | 3 | | |
4 | | - | |
| 4 | + | |
5 | 5 | | |
6 | 6 | | |
7 | 7 | | |
8 | | - | |
| 8 | + | |
9 | 9 | | |
10 | 10 | | |
11 | 11 | | |
12 | 12 | | |
13 | 13 | | |
14 | 14 | | |
15 | | - | |
| 15 | + | |
16 | 16 | | |
17 | 17 | | |
18 | 18 | | |
| |||
117 | 117 | | |
118 | 118 | | |
119 | 119 | | |
120 | | - | |
| 120 | + | |
121 | 121 | | |
122 | | - | |
123 | | - | |
124 | | - | |
125 | | - | |
126 | | - | |
| 122 | + | |
| 123 | + | |
| 124 | + | |
| 125 | + | |
| 126 | + | |
127 | 127 | | |
128 | 128 | | |
129 | 129 | | |
| |||
163 | 163 | | |
164 | 164 | | |
165 | 165 | | |
166 | | - | |
167 | | - | |
168 | | - | |
| 166 | + | |
| 167 | + | |
| 168 | + | |
| 169 | + | |
| 170 | + | |
| 171 | + | |
| 172 | + | |
| 173 | + | |
| 174 | + | |
| 175 | + | |
| 176 | + | |
| 177 | + | |
| 178 | + | |
| 179 | + | |
| 180 | + | |
| 181 | + | |
| 182 | + | |
| 183 | + | |
| 184 | + | |
| 185 | + | |
| 186 | + | |
| 187 | + | |
| 188 | + | |
| 189 | + | |
| 190 | + | |
| 191 | + | |
| 192 | + | |
| 193 | + | |
| 194 | + | |
| 195 | + | |
| 196 | + | |
| 197 | + | |
169 | 198 | | |
170 | 199 | | |
171 | 200 | | |
| |||
343 | 372 | | |
344 | 373 | | |
345 | 374 | | |
| 375 | + | |
346 | 376 | | |
347 | 377 | | |
348 | 378 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
3 | 3 | | |
4 | 4 | | |
5 | 5 | | |
6 | | - | |
7 | | - | |
| 6 | + | |
| 7 | + | |
8 | 8 | | |
9 | 9 | | |
10 | 10 | | |
| |||
55 | 55 | | |
56 | 56 | | |
57 | 57 | | |
58 | | - | |
| 58 | + | |
59 | 59 | | |
60 | 60 | | |
61 | 61 | | |
| |||
79 | 79 | | |
80 | 80 | | |
81 | 81 | | |
82 | | - | |
| 82 | + | |
83 | 83 | | |
84 | 84 | | |
85 | 85 | | |
| |||
129 | 129 | | |
130 | 130 | | |
131 | 131 | | |
132 | | - | |
133 | | - | |
| 132 | + | |
| 133 | + | |
| 134 | + | |
| 135 | + | |
| 136 | + | |
| 137 | + | |
| 138 | + | |
0 commit comments