@alexeiled/claude-router 0.7.0 → 0.7.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/plugin.json +1 -1
- package/CHANGELOG.md +13 -1
- package/docs/architecture.md +44 -42
- package/docs/configuration.md +70 -68
- package/lib/config.mjs +2 -0
- package/lib/policy.mjs +7 -2
- package/package.json +1 -1
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "router",
|
|
3
3
|
"displayName": "jev-router",
|
|
4
|
-
"version": "0.7.
|
|
4
|
+
"version": "0.7.1",
|
|
5
5
|
"description": "Auto-picks the right Claude model for each turn — small models for quick edits, mid-tier for code, frontier for hard problems. Uses Jev to classify each request.",
|
|
6
6
|
"author": { "name": "Alexei Ledenev", "url": "https://github.com/alexei-led" },
|
|
7
7
|
"repository": "https://github.com/alexei-led/claude-router",
|
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,17 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.7.1 (2026-09-24)
|
|
4
|
+
|
|
5
|
+
### Fixed
|
|
6
|
+
|
|
7
|
+
- A downgrade paid no attention to its own cost. The switching policy
|
|
8
|
+
checked confidence and vote count for a lower tier, never the price of
|
|
9
|
+
getting there: a candidate whose cache was cold next to a warm incumbent
|
|
10
|
+
could downgrade into a full cache write bigger than what the smaller
|
|
11
|
+
model saved. The downgrade bar now grows with the switching tax the same
|
|
12
|
+
way the upgrade bar does: `0.90 + 0.08 × tax / (tax + $0.50)`, up to
|
|
13
|
+
0.98. A downgrade to an already-warm candidate is unaffected.
|
|
14
|
+
|
|
3
15
|
## 0.7.0 (2026-09-24)
|
|
4
16
|
|
|
5
17
|
### Upgrade requirements
|
|
@@ -71,7 +83,7 @@
|
|
|
71
83
|
asked, a tool continuation looked like a new turn, and a request that Claude
|
|
72
84
|
Code resent after a 400 was decided again.
|
|
73
85
|
- The first Haiku turn of a session failed with `400 role 'system' is not
|
|
74
|
-
|
|
86
|
+
supported on this model`, and a later one made Claude Code flatten the
|
|
75
87
|
history for the rest of the session: Opus then lost its features, and the
|
|
76
88
|
router saw a shorter history and reset its votes. Sonnet answered the first
|
|
77
89
|
turn with two 400s before Claude Code retried without the features.
|
package/docs/architecture.md
CHANGED
|
@@ -67,8 +67,8 @@ flowchart TB
|
|
|
67
67
|
`output_config` on messages (the effort of each turn) go;
|
|
68
68
|
- no `mid-conversation-system` (Haiku): each `system` message becomes a
|
|
69
69
|
`<system-reminder>` text in the user message next to it.
|
|
70
|
-
|
|
71
|
-
|
|
70
|
+
The same history adapts the same way on every turn, so the cached prefix
|
|
71
|
+
holds.
|
|
72
72
|
- On a model with `per-turn-control`, the effort of each turn overrides the
|
|
73
73
|
request's effort. A route with its own effort (`medium`, `high`) therefore
|
|
74
74
|
sets it in every message's `output_config` too.
|
|
@@ -152,17 +152,17 @@ flowchart TD
|
|
|
152
152
|
class RESET,KEEP,POL,FIT act
|
|
153
153
|
```
|
|
154
154
|
|
|
155
|
-
| Check | How the gateway decides
|
|
156
|
-
| --------------- |
|
|
157
|
-
| Pass through | Any other model: `/model`, subagents with their own model.
|
|
158
|
-
| Pin | The current message starts with the `/router:<tier>` command block. That tier serves the turn and its tool calls, reason `pinned`. No Jev call.
|
|
159
|
-
| Not a turn | `count_tokens` and other endpoints get the last route of the session.
|
|
160
|
-
| Side request | Header `x-claude-code-request-class` is `auxiliary` or `compaction`. Without the header: thinking disabled or an output format in the body.
|
|
161
|
-
| History break | Fewer messages than the last main request (a compaction or a rewind), or the header `x-claude-code-context-compacted`.
|
|
155
|
+
| Check | How the gateway decides |
|
|
156
|
+
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
157
|
+
| Pass through | Any other model: `/model`, subagents with their own model. |
|
|
158
|
+
| Pin | The current message starts with the `/router:<tier>` command block. That tier serves the turn and its tool calls, reason `pinned`. No Jev call. |
|
|
159
|
+
| Not a turn | `count_tokens` and other endpoints get the last route of the session. |
|
|
160
|
+
| Side request | Header `x-claude-code-request-class` is `auxiliary` or `compaction`. Without the header: thinking disabled or an output format in the body. |
|
|
161
|
+
| History break | Fewer messages than the last main request (a compaction or a rewind), or the header `x-claude-code-context-compacted`. |
|
|
162
162
|
| Resent request | Same last user message at the same position. Claude Code resends after a 429, a 529, a dropped stream, or a 400 that it answers by dropping a feature. No Jev call, no vote. |
|
|
163
|
-
| System messages | Claude Code sends hook output and tool additions as `system` messages after the prompt. The turn is the last user or assistant message; Jev never receives `system` text.
|
|
164
|
-
| Context fit | The route moves to a model whose window holds the next context at 80% fill. Reason `context-fit`.
|
|
165
|
-
| Session memory | Key `x-claude-code-session-id`. A subagent adds its agent id: `<session>.<agent id>`. Its turns do not change the route of the main conversation.
|
|
163
|
+
| System messages | Claude Code sends hook output and tool additions as `system` messages after the prompt. The turn is the last user or assistant message; Jev never receives `system` text. |
|
|
164
|
+
| Context fit | The route moves to a model whose window holds the next context at 80% fill. Reason `context-fit`. |
|
|
165
|
+
| Session memory | Key `x-claude-code-session-id`. A subagent adds its agent id: `<session>.<agent id>`. Its turns do not change the route of the main conversation. |
|
|
166
166
|
|
|
167
167
|
## Switching policy
|
|
168
168
|
|
|
@@ -185,7 +185,7 @@ flowchart TD
|
|
|
185
185
|
JMP -- no --> UPQ{"2 votes,<br/>U ≥ bar?"}
|
|
186
186
|
UPQ -- yes --> UP["upgrade"]
|
|
187
187
|
UPQ -- no --> R5["upgrade-pending"]
|
|
188
|
-
DIR -- lower --> DNQ{"2 votes,<br/>D ≥
|
|
188
|
+
DIR -- lower --> DNQ{"2 votes,<br/>D ≥ bar?"}
|
|
189
189
|
DNQ -- yes --> DOWN["downgrade"]
|
|
190
190
|
DNQ -- no --> R6["downgrade-pending"]
|
|
191
191
|
|
|
@@ -205,9 +205,11 @@ only when that tier is above the current route.
|
|
|
205
205
|
or below the candidate. The `uncertain` mass supports neither.
|
|
206
206
|
- The upgrade bar grows with the switching tax:
|
|
207
207
|
`bar = 0.75 + 0.15 × tax / (tax + $0.50)`. It stays between 0.75 and 0.90.
|
|
208
|
+
- The downgrade bar grows the same way, from the other side: a candidate
|
|
209
|
+
colder than the incumbent pays a cache write, not just a smaller model.
|
|
210
|
+
`bar = 0.90 + 0.08 × tax / (tax + $0.50)`. It stays between 0.90 and 0.98.
|
|
208
211
|
- A prompt continues the task when the Jev continuation answer is 0.7 or
|
|
209
212
|
more. A continuing prompt never votes for a downgrade.
|
|
210
|
-
- A downgrade has no tax term.
|
|
211
213
|
- Upgrades have no cooldown. Plan, then execute, then hard work again is a
|
|
212
214
|
valid sequence.
|
|
213
215
|
- A failure signal is two `tool_result` errors with the same text and an edit
|
|
@@ -239,11 +241,11 @@ input_cost = P_read × W + P_write × (N − W)
|
|
|
239
241
|
tax = max(0, input_cost(candidate) − input_cost(current))
|
|
240
242
|
```
|
|
241
243
|
|
|
242
|
-
| Symbol | Source
|
|
243
|
-
| --------- |
|
|
244
|
-
| `N` | Next context: tokens and output of the last response.
|
|
245
|
-
| `W` | Warm prefix of the candidate cache. Zero when the cache is `expired` or `unknown`.
|
|
246
|
-
| `P_read` | List price for cache reads.
|
|
244
|
+
| Symbol | Source |
|
|
245
|
+
| --------- | ------------------------------------------------------------------------------------------------------ |
|
|
246
|
+
| `N` | Next context: tokens and output of the last response. |
|
|
247
|
+
| `W` | Warm prefix of the candidate cache. Zero when the cache is `expired` or `unknown`. |
|
|
248
|
+
| `P_read` | List price for cache reads. |
|
|
247
249
|
| `P_write` | Input list price × 1.25 (5-minute TTL) or × 2 (1-hour TTL). The TTL comes from `usage.cache_creation`. |
|
|
248
250
|
|
|
249
251
|
- **Upper bound.** An effort change counts the whole prefix as lost. On some
|
|
@@ -314,19 +316,19 @@ so tests run without a network. `gateway` imports one pure function from
|
|
|
314
316
|
`router`, the side-request test, not the router itself. Modules that need
|
|
315
317
|
settings or tier names import `config.mjs` (not drawn).
|
|
316
318
|
|
|
317
|
-
| Module | Responsibility
|
|
318
|
-
| --------- |
|
|
319
|
-
| `gateway` | HTTP server, loopback checks, relay with `pipeline()`, status endpoint.
|
|
320
|
-
| `router` | One request: class, facts, advice, policy, rewrite, session memory, log.
|
|
321
|
-
| `facts` | Prompt, recent turns, continuation, failure signal, resend key.
|
|
322
|
-
| `jev` | One bounded Jev request with a Choice (tier) and a Noul (continuation).
|
|
323
|
-
| `policy` | Switching policy, context fit, cold-write guard.
|
|
324
|
-
| `cost` | Cache key, warmth, input cost, switching tax, shadow estimate.
|
|
325
|
-
| `rewrite` | Model, effort, thinking and output limit for each model family.
|
|
326
|
-
| `sse` | `usage` from SSE and JSON responses.
|
|
327
|
-
| `idle` | When the daemon can exit.
|
|
328
|
-
| `status` | Status snapshot, status line segment, `/router:status` report.
|
|
329
|
-
| `store` | Session memory, `decisions.jsonl`, rotation.
|
|
319
|
+
| Module | Responsibility |
|
|
320
|
+
| --------- | ---------------------------------------------------------------------------------------------- |
|
|
321
|
+
| `gateway` | HTTP server, loopback checks, relay with `pipeline()`, status endpoint. |
|
|
322
|
+
| `router` | One request: class, facts, advice, policy, rewrite, session memory, log. |
|
|
323
|
+
| `facts` | Prompt, recent turns, continuation, failure signal, resend key. |
|
|
324
|
+
| `jev` | One bounded Jev request with a Choice (tier) and a Noul (continuation). |
|
|
325
|
+
| `policy` | Switching policy, context fit, cold-write guard. |
|
|
326
|
+
| `cost` | Cache key, warmth, input cost, switching tax, shadow estimate. |
|
|
327
|
+
| `rewrite` | Model, effort, thinking and output limit for each model family. |
|
|
328
|
+
| `sse` | `usage` from SSE and JSON responses. |
|
|
329
|
+
| `idle` | When the daemon can exit. |
|
|
330
|
+
| `status` | Status snapshot, status line segment, `/router:status` report. |
|
|
331
|
+
| `store` | Session memory, `decisions.jsonl`, rotation. |
|
|
330
332
|
| `runtime` | Configuration path (anchored under `~/.claude`), data directory, flags, gateway process check. |
|
|
331
333
|
|
|
332
334
|
## Gateway lifecycle
|
|
@@ -353,16 +355,16 @@ stateDiagram-v2
|
|
|
353
355
|
|
|
354
356
|
## Failure handling
|
|
355
357
|
|
|
356
|
-
| Failure
|
|
357
|
-
|
|
|
358
|
-
| Anthropic 429, 529, 5xx
|
|
359
|
-
| Upstream reset during a stream
|
|
360
|
-
| Client leaves (Esc)
|
|
361
|
-
| Jev error or timeout
|
|
362
|
-
| Three Jev failures in a row
|
|
363
|
-
| Routing error
|
|
364
|
-
| Disk error
|
|
365
|
-
| Unexpected exception
|
|
358
|
+
| Failure | Behavior |
|
|
359
|
+
| ------------------------------ | ---------------------------------------------------------------- |
|
|
360
|
+
| Anthropic 429, 529, 5xx | Pass through with `Retry-After`. Claude Code owns retries. |
|
|
361
|
+
| Upstream reset during a stream | The client connection resets, and Claude Code retries at once. |
|
|
362
|
+
| Client leaves (Esc) | The gateway stops the upstream request. |
|
|
363
|
+
| Jev error or timeout | One retry inside the 1.5 s budget. Then the current route stays. |
|
|
364
|
+
| Three Jev failures in a row | New turns skip Jev for one minute, then try once. |
|
|
365
|
+
| Routing error | The baseline tier serves. The alias never goes to Anthropic. |
|
|
366
|
+
| Disk error | Logged. The routing decision stays. |
|
|
367
|
+
| Unexpected exception | Logged. The daemon continues. |
|
|
366
368
|
|
|
367
369
|
## Security and privacy
|
|
368
370
|
|
package/docs/configuration.md
CHANGED
|
@@ -2,12 +2,12 @@
|
|
|
2
2
|
|
|
3
3
|
## Where the settings are
|
|
4
4
|
|
|
5
|
-
| Setting
|
|
6
|
-
|
|
|
7
|
-
| Jev API key
|
|
8
|
-
| Claude Code settings
|
|
9
|
-
| Router configuration
|
|
10
|
-
| Data and logs
|
|
5
|
+
| Setting | Location | Written by |
|
|
6
|
+
| -------------------- | --------------------------------------------------------- | --------------------------------------- |
|
|
7
|
+
| Jev API key | macOS Keychain, plugin option `typesafe_api_key` | Claude Code, when you enable the plugin |
|
|
8
|
+
| Claude Code settings | `~/.claude/settings.json` | `/router:setup` |
|
|
9
|
+
| Router configuration | `~/.claude/router.json` | You |
|
|
10
|
+
| Data and logs | `~/.claude/plugins/data/router-alexei-led-claude-router/` | The gateway |
|
|
11
11
|
|
|
12
12
|
- The hooks give the key to the gateway as `TYPESAFE_API_KEY`. The key is
|
|
13
13
|
never in a file.
|
|
@@ -48,14 +48,14 @@
|
|
|
48
48
|
}
|
|
49
49
|
```
|
|
50
50
|
|
|
51
|
-
| Key | Why
|
|
52
|
-
| -------------------------------------- |
|
|
53
|
-
| `model` | The `[1m]` suffix tells Claude Code that the window is 1M tokens. Claude Code removes the suffix before the request.
|
|
54
|
-
| `env.ANTHROPIC_BASE_URL` | Sends the traffic of Claude Code to the gateway.
|
|
51
|
+
| Key | Why |
|
|
52
|
+
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
|
|
53
|
+
| `model` | The `[1m]` suffix tells Claude Code that the window is 1M tokens. Claude Code removes the suffix before the request. |
|
|
54
|
+
| `env.ANTHROPIC_BASE_URL` | Sends the traffic of Claude Code to the gateway. |
|
|
55
55
|
| `env.ENABLE_TOOL_SEARCH` | Keeps MCP tool schemas deferred. Without it, each request carries all schemas: about 50K tokens with the claude.ai connectors. |
|
|
56
|
-
| `env.CLAUDE_CODE_GATEWAY_HINT_HEADERS` | Claude Code sends the [class of each request](architecture.md#request-classes).
|
|
57
|
-
| `modelPicker` row | Adds `Jev Router (auto)` to `/model`. `behavesAs` names a known model. Without it, Claude Code rejects the alias.
|
|
58
|
-
| `statusLine` (optional) | Runs your status line command, then adds the route of the last turn.
|
|
56
|
+
| `env.CLAUDE_CODE_GATEWAY_HINT_HEADERS` | Claude Code sends the [class of each request](architecture.md#request-classes). |
|
|
57
|
+
| `modelPicker` row | Adds `Jev Router (auto)` to `/model`. `behavesAs` names a known model. Without it, Claude Code rejects the alias. |
|
|
58
|
+
| `statusLine` (optional) | Runs your status line command, then adds the route of the last turn. |
|
|
59
59
|
|
|
60
60
|
Setup writes the file once, as its last step. Restart Claude Code after it.
|
|
61
61
|
Until the restart, the session shows "There's an issue with the selected
|
|
@@ -85,22 +85,22 @@ For example, to run `low` on Sonnet at `high` effort and give Jev more time:
|
|
|
85
85
|
|
|
86
86
|
### gateway
|
|
87
87
|
|
|
88
|
-
| Key | Default | Meaning
|
|
89
|
-
| ---------------- | ------------ |
|
|
90
|
-
| `port` | `43170` | The loopback port of the gateway.
|
|
91
|
-
| `alias` | `jev-router` | The model name that Claude Code sends.
|
|
92
|
-
| `baselineTier` | `low` | The tier when nothing else decides: a new session, or no Jev answer.
|
|
93
|
-
| `auxiliaryTier` | `low` | The tier for side requests, for example session titles.
|
|
94
|
-
| `idleShutdownMs` | `7200000` | The gateway exits after this time without requests. `0` keeps it running.
|
|
88
|
+
| Key | Default | Meaning |
|
|
89
|
+
| ---------------- | ------------ | ------------------------------------------------------------------------- |
|
|
90
|
+
| `port` | `43170` | The loopback port of the gateway. |
|
|
91
|
+
| `alias` | `jev-router` | The model name that Claude Code sends. |
|
|
92
|
+
| `baselineTier` | `low` | The tier when nothing else decides: a new session, or no Jev answer. |
|
|
93
|
+
| `auxiliaryTier` | `low` | The tier for side requests, for example session titles. |
|
|
94
|
+
| `idleShutdownMs` | `7200000` | The gateway exits after this time without requests. `0` keeps it running. |
|
|
95
95
|
|
|
96
96
|
### routes
|
|
97
97
|
|
|
98
|
-
| Tier | Default
|
|
99
|
-
| -------- |
|
|
98
|
+
| Tier | Default |
|
|
99
|
+
| -------- | ---------------------------------------- |
|
|
100
100
|
| `high` | `{ "model": "opus", "effort": "xhigh" }` |
|
|
101
101
|
| `medium` | `{ "model": "opus", "effort": "high" }` |
|
|
102
|
-
| `low` | `{ "model": "sonnet" }`
|
|
103
|
-
| `micro` | `{ "model": "haiku" }`
|
|
102
|
+
| `low` | `{ "model": "sonnet" }` |
|
|
103
|
+
| `micro` | `{ "model": "haiku" }` |
|
|
104
104
|
|
|
105
105
|
`model` is a key of `models`. `effort` is `low`, `medium`, `high`, `xhigh` or
|
|
106
106
|
`max`. Without `effort`, the gateway keeps the effort that Claude Code sent.
|
|
@@ -115,15 +115,15 @@ A test makes sure that they agree.
|
|
|
115
115
|
| `sonnet` | `claude-sonnet-5` | 2 | 10 | 0.2 | 1,000,000 | — | `plan` | all five | `mid-conversation-system` |
|
|
116
116
|
| `haiku` | `claude-haiku-4-5` | 1 | 5 | 0.1 | 200,000 | 64,000 | `plan` | none | none |
|
|
117
117
|
|
|
118
|
-
| Field
|
|
119
|
-
|
|
|
120
|
-
| `id`
|
|
121
|
-
| `input`, `output`, `cacheRead` | List prices in USD per million tokens. `output` is optional. Only the `shadow` estimate uses it.
|
|
122
|
-
| `contextWindow`
|
|
123
|
-
| `maxOutput`
|
|
124
|
-
| `billing`
|
|
125
|
-
| `efforts`
|
|
126
|
-
| `features`
|
|
118
|
+
| Field | Meaning |
|
|
119
|
+
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
120
|
+
| `id` | The model id that the gateway sends to Anthropic. |
|
|
121
|
+
| `input`, `output`, `cacheRead` | List prices in USD per million tokens. `output` is optional. Only the `shadow` estimate uses it. |
|
|
122
|
+
| `contextWindow` | The window in tokens. A turn goes only to a model that holds the context at 80% fill. |
|
|
123
|
+
| `maxOutput` | Optional limit for `max_tokens`. Haiku 4.5 rejects more than 64K. |
|
|
124
|
+
| `billing` | `plan` for the subscription limits. `credits` for models that bill usage credits. |
|
|
125
|
+
| `efforts` | The effort levels that the model accepts. An empty list removes effort and thinking. |
|
|
126
|
+
| `features` | The request features of Claude Code that the model accepts: `mid-conversation-system`, `per-turn-control`, `mid-conversation-tool-changes`. The gateway removes the others ([architecture](architecture.md#system-context)). Without the field: none. |
|
|
127
127
|
|
|
128
128
|
The default prices match `test/fixtures/list-prices.json`, which names its
|
|
129
129
|
source and date. The default `efforts` match `test/fixtures/effort-support.json`,
|
|
@@ -133,50 +133,52 @@ from a probe against the real API. A test fails when they differ.
|
|
|
133
133
|
|
|
134
134
|
The [switching policy](architecture.md#switching-policy) uses these values.
|
|
135
135
|
|
|
136
|
-
| Key | Default | Meaning
|
|
137
|
-
| --------------------- | ------- |
|
|
138
|
-
| `upgradeVotes` | `2` | Consecutive votes above the current tier before an upgrade.
|
|
139
|
-
| `upgradeBase` | `0.75` | The upgrade bar when a switch costs nothing.
|
|
140
|
-
| `upgradeSlope` | `0.15` | How much a switching cost can raise the bar: `base + slope × tax / (tax + pivot)`.
|
|
141
|
-
| `upgradePivotUsd` | `0.5` | The switching cost that adds half of the slope.
|
|
142
|
-
| `jumpConfidence` | `0.95` | The confidence for a jump of two tiers without the vote delay.
|
|
143
|
-
| `downgradeVotes` | `2` | Consecutive votes for a lower tier before a downgrade.
|
|
144
|
-
| `downgradeMass` | `0.9` | The
|
|
145
|
-
| `
|
|
146
|
-
| `
|
|
136
|
+
| Key | Default | Meaning |
|
|
137
|
+
| --------------------- | ------- | -------------------------------------------------------------------------------------- |
|
|
138
|
+
| `upgradeVotes` | `2` | Consecutive votes above the current tier before an upgrade. |
|
|
139
|
+
| `upgradeBase` | `0.75` | The upgrade bar when a switch costs nothing. |
|
|
140
|
+
| `upgradeSlope` | `0.15` | How much a switching cost can raise the bar: `base + slope × tax / (tax + pivot)`. |
|
|
141
|
+
| `upgradePivotUsd` | `0.5` | The switching cost that adds half of the slope. |
|
|
142
|
+
| `jumpConfidence` | `0.95` | The confidence for a jump of two tiers without the vote delay. |
|
|
143
|
+
| `downgradeVotes` | `2` | Consecutive votes for a lower tier before a downgrade. |
|
|
144
|
+
| `downgradeMass` | `0.9` | The downgrade bar when the candidate's cache is already warm. |
|
|
145
|
+
| `downgradeSlope` | `0.08` | How much a cold candidate's cache write can raise the bar, same formula as upgrade. |
|
|
146
|
+
| `downgradePivotUsd` | `0.5` | The switching cost that adds half of the slope. |
|
|
147
|
+
| `continuationMass` | `0.7` | The Jev probability for "continues the task" that keeps the route. |
|
|
148
|
+
| `escalationHoldTurns` | `2` | Turns that the route stays up after an escalation. |
|
|
147
149
|
| `cashCapUsd` | `2` | The cold-write guard: the largest first cache write for a switch to a `credits` model. |
|
|
148
150
|
|
|
149
151
|
### cache, jev, context, log
|
|
150
152
|
|
|
151
|
-
| Key
|
|
152
|
-
|
|
|
153
|
-
| `cache.writeMultiplier`
|
|
154
|
-
| `cache.ttlMs`
|
|
155
|
-
| `cache.warmMarginMs`
|
|
156
|
-
| `jev.endpoint`
|
|
157
|
-
| `jev.model`
|
|
158
|
-
| `jev.timeoutMs`
|
|
159
|
-
| `context.recentTurns`
|
|
160
|
-
| `context.maxTextChars`
|
|
161
|
-
| `log`
|
|
153
|
+
| Key | Default | Meaning |
|
|
154
|
+
| ----------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------- |
|
|
155
|
+
| `cache.writeMultiplier` | `{ "5m": 1.25, "1h": 2 }` | The price of a cache write, as a multiple of `input`. |
|
|
156
|
+
| `cache.ttlMs` | `{ "5m": 300000, "1h": 3600000 }` | The lifetime of each cache TTL. |
|
|
157
|
+
| `cache.warmMarginMs` | `30000` | A cache counts as cold this long before it expires. |
|
|
158
|
+
| `jev.endpoint` | `https://api.typesafe.ai/v1/systemone` | The Jev API. |
|
|
159
|
+
| `jev.model` | `jev-1.13.0` | The Jev model. |
|
|
160
|
+
| `jev.timeoutMs` | `1500` | The total time for one Jev answer, one retry included. |
|
|
161
|
+
| `context.recentTurns` | `6` | The number of recent turns that Jev receives. |
|
|
162
|
+
| `context.maxTextChars` | `1200` | The characters of the prompt and of each turn that Jev receives. A longer text keeps its start and end. |
|
|
163
|
+
| `log` | `true` | Write `decisions.jsonl`. |
|
|
162
164
|
|
|
163
165
|
## Environment variables
|
|
164
166
|
|
|
165
|
-
| Variable | Effect
|
|
166
|
-
| -------------------- |
|
|
167
|
-
| `TYPESAFE_API_KEY` | The Jev key. The hooks set it from the plugin option.
|
|
167
|
+
| Variable | Effect |
|
|
168
|
+
| -------------------- | ------------------------------------------------------------------------------------------------------------ |
|
|
169
|
+
| `TYPESAFE_API_KEY` | The Jev key. The hooks set it from the plugin option. |
|
|
168
170
|
| `ROUTER_CONFIG` | Another path for the router configuration, under `~/.claude/` only. Another path is ignored, with a warning. |
|
|
169
|
-
| `CLAUDE_PLUGIN_DATA` | The data directory. Claude Code sets it for the plugin hooks.
|
|
171
|
+
| `CLAUDE_PLUGIN_DATA` | The data directory. Claude Code sets it for the plugin hooks. |
|
|
170
172
|
|
|
171
173
|
## Command-line flags
|
|
172
174
|
|
|
173
175
|
A project cannot change these: they are part of the command, not of the
|
|
174
176
|
environment.
|
|
175
177
|
|
|
176
|
-
| Flag | Script
|
|
177
|
-
| --------------------- |
|
|
178
|
-
| `--config <path>` | `gateway.mjs`, `ensure-gateway.mjs`, `status.mjs` | The router configuration, at any path.
|
|
179
|
-
| `--force-tier <tier>` | `gateway.mjs`
|
|
178
|
+
| Flag | Script | Effect |
|
|
179
|
+
| --------------------- | ------------------------------------------------- | ------------------------------------------------------------------------ |
|
|
180
|
+
| `--config <path>` | `gateway.mjs`, `ensure-gateway.mjs`, `status.mjs` | The router configuration, at any path. |
|
|
181
|
+
| `--force-tier <tier>` | `gateway.mjs` | `micro`, `low`, `medium` or `high`. Skips Jev and the policy. For tests. |
|
|
180
182
|
|
|
181
183
|
The flags are for a gateway that you start by hand. The hooks and the status
|
|
182
184
|
line do not pass them. To use another file with the hooks, keep it under
|
|
@@ -193,8 +195,8 @@ CLAUDE_PLUGIN_DATA=~/.claude/plugins/data/router-alexei-led-claude-router \
|
|
|
193
195
|
|
|
194
196
|
## Data directory
|
|
195
197
|
|
|
196
|
-
| File | Content
|
|
197
|
-
| ----------------- |
|
|
198
|
-
| `decisions.jsonl` | One line for each decision and each response. | Moves to `.1` above 20 MB.
|
|
199
|
-
| `gateway.log` | Gateway events with timestamps.
|
|
200
|
-
| `sessions/` | The routing memory of each session.
|
|
198
|
+
| File | Content | Retention |
|
|
199
|
+
| ----------------- | --------------------------------------------- | -------------------------------------------- |
|
|
200
|
+
| `decisions.jsonl` | One line for each decision and each response. | Moves to `.1` above 20 MB. |
|
|
201
|
+
| `gateway.log` | Gateway events with timestamps. | Moves to `.1` above 20 MB, at gateway start. |
|
|
202
|
+
| `sessions/` | The routing memory of each session. | Removed after 30 days without use. |
|
package/lib/config.mjs
CHANGED
|
@@ -77,6 +77,8 @@ export const DEFAULTS = {
|
|
|
77
77
|
jumpConfidence: 0.95,
|
|
78
78
|
downgradeVotes: 2,
|
|
79
79
|
downgradeMass: 0.9,
|
|
80
|
+
downgradeSlope: 0.08, // a cold candidate raises the bar toward ~0.98, same shape as the upgrade bar
|
|
81
|
+
downgradePivotUsd: 0.5,
|
|
80
82
|
continuationMass: 0.7,
|
|
81
83
|
escalationHoldTurns: 2,
|
|
82
84
|
// Ceiling on a cold cache write to a `credits` model. No default model bills credits, so this is
|
package/lib/policy.mjs
CHANGED
|
@@ -48,8 +48,13 @@ export function decide({ config, facts, advice, state, baseline, now }) {
|
|
|
48
48
|
|
|
49
49
|
const support = massAtOrBelow(advice.probabilities, choice);
|
|
50
50
|
const streak = trailing(next.votes, (v) => rank(v.tier) <= rank(choice));
|
|
51
|
-
|
|
52
|
-
|
|
51
|
+
// A downgrade is not always cheaper this turn: a cold candidate next to a warm incumbent can pay a bigger cache
|
|
52
|
+
// write than it saves. The bar rises with that cost the same way the upgrade bar does.
|
|
53
|
+
const tax = Math.max(0, switchingTaxUsd(config, choice, incumbent, facts, now));
|
|
54
|
+
const threshold =
|
|
55
|
+
config.policy.downgradeMass + config.policy.downgradeSlope * (tax / (tax + config.policy.downgradePivotUsd));
|
|
56
|
+
const estimate = { downgradeMass: support, streak, taxUsd: tax, threshold };
|
|
57
|
+
if (support >= threshold && streak >= config.policy.downgradeVotes)
|
|
53
58
|
return result(choice, 'downgrade', next, estimate);
|
|
54
59
|
return stay('downgrade-pending', estimate);
|
|
55
60
|
}
|
package/package.json
CHANGED