Skip to content

Commit 9c394a6

Browse files
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

‎COMPLETION-LOG.md‎

Lines changed: 42 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,18 @@
11
# Jellyclaw Engine — Completion Log
22

33
**Last updated:** 2026-04-15
4-
**Current phase:** Phase 02 — Config + provider layer (next)
4+
**Current phase:** Phase 03 — Event stream adapter (next)
55

66
## Overall progress
77

8-
[██░░░░░░░░░░░░░░░░░░] 2/20 phases complete (10%)
8+
[███░░░░░░░░░░░░░░░░░] 3/20 phases complete (15%)
99

1010
## Phase checklist
1111

1212
### Foundation
1313
- [x] ✅ Phase 00 — Repo scaffolding
1414
- [x] ✅ Phase 01 — OpenCode pinning and patching
15-
- [ ] Phase 02 — Config + provider layer
15+
- [x] ✅ Phase 02 — Config + provider layer
1616
- [ ] Phase 03 — Event stream adapter
1717
- [ ] Phase 04 — Tool parity
1818
- [ ] Phase 05 — Skills system
@@ -117,13 +117,13 @@
117117
what the name suggests in this binary.
118118

119119
### Phase 02 — Config + provider layer
120-
- **Status:** 🔄 In progress (Prompts 01+02 ✅; 03 remaining)
120+
- **Status:** ✅ Complete
121121
- **Started:** 2026-04-15
122-
- **Completed:** —
123-
- **Duration (actual):** —
124-
- **Session count:** 2 (ongoing)
125-
- **Commits:** 53cf19d (research), (this commit: anthropic provider)
126-
- **Tests passing:** 93/93 (45 new in Prompt 02: 24 schema/loader, 13 cache-breakpoints, 8 anthropic provider)
122+
- **Completed:** 2026-04-15
123+
- **Duration (actual):** 1 day (3 sessions — research + anthropic + openrouter-via-team)
124+
- **Session count:** 3
125+
- **Commits:** 53cf19d (research), ca2ec15 (anthropic), (this commit: openrouter + router + gate + pool + docs)
126+
- **Tests passing:** 147/147 (99 new in Phase 02 total: 24 schema/loader, 13 cache-breakpoints, 8 anthropic provider, 14 openrouter, 13 router, 15 gate, 12 credential-pool)
127127
- **Notes:**
128128
- ✅ Prompt 02 (anthropic provider) — `engine/src/config/{schema,loader}.ts`
129129
+ `engine/src/providers/{types,cache-breakpoints,anthropic,index}.ts`
@@ -163,9 +163,38 @@
163163
radius. §10 decision table: `acknowledgeCachingLimits` gate (default
164164
false) blocks `anthropic/*` models via OR unless explicitly flipped;
165165
non-Anthropic via OR proceeds with cache_control strip.
166-
- Prompts 02 (anthropic provider), 03 (openrouter provider), 04
167-
(router/fallback), 05 (config schema + loader), 06 (tests + docs)
168-
remain.
166+
- ✅ Prompt 03 (openrouter provider + router/fallback + gate + pool + docs)
167+
— executed via a 5-agent team in parallel:
168+
- `engine/src/providers/openrouter.ts` (659 lines) — `OpenRouterProvider`
169+
with hand-rolled SSE parser (no new deps), recursive `stripCacheControl`
170+
(zero emits — test walks the captured body and asserts), OpenAI-compat
171+
body translation (tool schema `input_schema`→`parameters`, tool_use↔
172+
tool_calls, tool_result→tool role), Anthropic-shape chunk emission so
173+
the Phase 03 event adapter doesn't branch, module-level `warned` guard
174+
with exported reset for tests, 402-added-to-non-retryable, mirror
175+
Anthropic retry loop (3/30s/jitter/Retry-After).
176+
- `engine/src/providers/router.ts` (147 lines) — provider-agnostic
177+
`ProviderRouter` with pre-stream-only failover (tracks
178+
`yieldedFromPrimary`), duck-typed error classification, AbortError
179+
propagation without failover, `shouldFailover(err)` helper exported.
180+
- `engine/src/providers/gate.ts` (40 lines) — `enforceCachingGate(config,
181+
model)` with explicit model arg (not config.model) for
182+
dispatch-time override checks. Reuses existing `CachingGateError` from
183+
`config/loader.ts`.
184+
- `engine/src/providers/credential-pool.ts` (216 lines) — contiguous
185+
`_1..N` scan, config-key beats env-pool, round-robin skipping dead
186+
slots, `rotateOnRateLimit()` + `markCurrentDead()`, `AllKeysDeadError`,
187+
keys in closure so `JSON.stringify(pool)` cannot leak.
188+
- `docs/providers.md` (658 lines) — selection matrix, caching matrix,
189+
breakpoint rules, `anthropic-beta` header, OR caveat with issue URLs,
190+
`acknowledgeCachingLimits` gate decision table, pooling docs,
191+
retry/failover rules, 3 JSON config examples, 8 pitfalls, 10 FAQ.
192+
- `engine/src/providers/index.ts` (barrel) extended. `engine/src/types.ts`
193+
gained `"router"` to the provider name union. `engine/src/index.ts`
194+
`makeProvider` now maps openrouter the same way it maps anthropic.
195+
- Gates: typecheck ✅, biome ✅ (clean on all provider files post-autofix
196+
+ a handful of biome-ignore comments on async generators in tests where
197+
the rule misfires), vitest 147/147 ✅ (incl. live opencode-ai e2e), build ✅.
169198

170199
### Phase 03 — Event stream adapter
171200
- **Status:** ⏳ Not started
@@ -343,6 +372,7 @@
343372
|---|---|---|---|---|
344373
| 2026-04-15 | 1 | 00 | 01-verify-scaffolding | ✅ Phase 00 complete — toolchain green, tag v0.0.0-scaffold, commit 6644aaf |
345374
| 2026-04-15 | 2 | 01 | 01-research | 🔄 Research note landed (engine/opencode-research-notes.md, 950 lines). Commit dcb0601. Phase 01 NOT complete — awaits Prompt 02 implementation. |
375+
| 2026-04-15 | 6 | 02 | 03-openrouter-provider | ✅ Phase 02 COMPLETE. 5-agent parallel team produced `openrouter.ts` (with SSE parser + cache_control strip + warn-once) + `router.ts` + `gate.ts` + `credential-pool.ts` + `docs/providers.md`. Main session reconciled barrel exports, updated `engine/src/index.ts` `makeProvider`, fixed 5 linter misfires on async generators in tests. 147/147 tests green (54 new). Typecheck ✅, build ✅, biome ✅. |
346376
| 2026-04-15 | 5 | 02 | 02-anthropic-provider | 🔄 Config schema+loader, Provider interface, pure `planBreakpoints`, `AnthropicProvider` with real SDK streaming + SPEC §7 cache_control placement + `anthropic-beta` 1h header + own retry loop all landed. 93/93 tests green (45 new). Phase 02 still open — Prompt 03 (OpenRouter + router/fallback + docs) remains. |
347377
| 2026-04-15 | 4 | 02 | 01-research | 🔄 `engine/provider-research-notes.md` landed (1753 lines). Beta header `extended-cache-ttl-2025-04-11` verified current. Min-cache-tokens table refreshed. OR #1245 + #17910 deep-dives completed with primary + mirror citations. `acknowledgeCachingLimits` gate decision table authored (§10). Phase 02 NOT complete — Prompts 02-06 still ahead. |
348378
| 2026-04-15 | 3 | 01 | 02-implement | ✅ Phase 01 complete via PIVOT. [email protected] is a compiled binary → three planned source patches reimplemented as engine/src/plugin/{agent-context,secret-scrub}.ts + engine/src/bootstrap/opencode-server.ts. 48/48 tests green (incl. live e2e against opencode-ai child). SPEC §5.1/§15 + CVE-MITIGATION §1.4/§2.1 + patches/README + phases/PHASE-01 synced. Commits 06d7d8a (pin+lock), 8a380dd (code), (this commit) (docs+log). |

‎STATUS.md‎

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,8 @@
33
> Living doc. Update at the start and end of every working day.
44
> If this file is stale, don't trust it.
55
6-
**Last updated:** 2026-04-15 (Phase 02 research ✅ + Anthropic provider ✅; OpenRouter pending)
7-
**Current phase:** Phase 02 — Config + provider layer (Prompts 01+02 ✅, Prompt 03 ⏳)
6+
**Last updated:** 2026-04-15 (Phase 02 ✅ complete)
7+
**Current phase:** Phase 03 — Event stream adapter (next)
88
**Current milestone target:** M1 (Engine works) — projected week of May 18
99
**Engine on:** n/a (not yet bootable)
1010
**Genie dispatcher:** Claurst (unchanged)
@@ -55,7 +55,7 @@ Budget ceiling for v1.0 (Phases 00–18): **TBD — pending Q2 answer.**
5555

5656
| Metric | Count |
5757
|--------|-------|
58-
| Unit tests passing | 93 |
58+
| Unit tests passing | 147 |
5959
| Unit tests failing | 0 |
6060
| Integration tests passing | 0 |
6161
| Golden-prompt regression tests | 0 / 5 target |
@@ -79,7 +79,7 @@ Budget ceiling for v1.0 (Phases 00–18): **TBD — pending Q2 answer.**
7979

8080
- [x] ✅ Phase 00 — Repo scaffolding
8181
- [x] ✅ Phase 01 — OpenCode pinning + patching
82-
- [ ] Phase 02 — Config + provider layer
82+
- [x] ✅ Phase 02 — Config + provider layer
8383
- [ ] Phase 03 — Event stream adapter
8484
- [ ] Phase 04 — Tool parity
8585
- [ ] Phase 05 — Skills system
@@ -129,5 +129,10 @@ Budget ceiling for v1.0 (Phases 00–18): **TBD — pending Q2 answer.**
129129
SPEC §9 config shape authoritative; SPEC §7 cache_control plan pure-function;
130130
`anthropic-beta: extended-cache-ttl-2025-04-11` header auto-set on 1h TTL;
131131
own retry loop (3 attempts / 30s / jitter / Retry-After honored). 93/93 tests.
132-
- Next action: Phase 02 Prompt 03 — OpenRouter provider + router/fallback + docs.
133-
Fresh Claude session.
132+
- Phase 02 Prompt 03 (OpenRouter provider + router/fallback + gate + pool + docs)
133+
landed via a 5-agent parallel team. `openrouter.ts` (SSE hand-parsed,
134+
cache_control stripped unconditionally, warn-once for anthropic/* models),
135+
`router.ts` (pre-stream-only failover), `gate.ts`, `credential-pool.ts`,
136+
`docs/providers.md` (658 lines). 147/147 tests ✅. **Phase 02 ✅ COMPLETE.**
137+
- Next action: Phase 03 — Event stream adapter.
138+
Fresh Claude session. Run `prompts/phase-03/01-<name>.md`.

0 commit comments

Comments
 (0)