@alexeiled/claude-router 0.1.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "router",
+  "displayName": "Router",
+  "version": "0.1.0",
+  "description": "Local gateway that selects a model and an effort level for each user turn with a TypeSafe Jev Choice.",
+  "author": { "name": "Alexei Ledenev", "url": "https://github.com/alexei-led" },
+  "repository": "https://github.com/alexei-led/claude-router",
+  "license": "MIT",
+  "keywords": ["router", "jev", "typesafe", "effort", "gateway"],
+  "userConfig": {
+    "typesafe_api_key": {
+      "type": "string",
+      "title": "TypeSafe API key",
+      "description": "Jev key for the routing decision. Stored in the Keychain. Leave empty to run on the baseline tier.",
+      "sensitive": true
+    }
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexei Ledenev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,76 @@
+# claude-router
+
+A Claude Code plugin that selects a model and an effort level for each user turn.
+
+A local gateway on `127.0.0.1` receives each request from Claude Code. For a
+new user turn, the gateway asks TypeSafe Jev which tier the turn needs. Then
+the gateway changes `model`, `effort` and `thinking` in the request and sends
+it to Anthropic. All other data goes through unchanged. The gateway has no
+runtime dependencies and needs Node 22 or later.
+
+## How it works
+
+```
+Claude Code  --model router  ──▶  gateway 127.0.0.1:43170  ──▶  api.anthropic.com
+                                   │
+   only requests for `router`:     ├─ facts.mjs    prompt, continuation, failures
+                                   ├─ jev.mjs      one Choice (tier) + one Noul (continuation?)
+                                   ├─ policy.mjs   stickiness, escalation, cost-gated votes
+                                   ├─ rewrite.mjs  model, effort, thinking per model family
+                                   └─ store.mjs    session memory, decisions.jsonl
+   responses go through unchanged; the gateway reads `usage` (context size, cache TTL)
+```
+
+The tiers are `micro` (haiku), `low` (sonnet, the baseline), `medium` (opus at
+high effort) and `high` (fable at xhigh effort).
+
+A tool continuation is a request whose last message is a `tool_result`. It
+keeps the route of the turn, and the gateway does not ask Jev. Side requests,
+for example session titles, get the baseline tier. A request for any other
+model goes through unchanged. This is how `/router:<tier>` pins and subagents
+with their own `model` work.
+
+Module dependencies point in one direction: `gateway.mjs` (HTTP) →
+`router.mjs` (orchestration) → `facts`, `jev`, `policy` → `cost`, `rewrite`,
+`store`. The modules `facts`, `cost`, `rewrite`, `sse` and `policy` are pure.
+Only `store` writes files. The Jev transport is injected.
+
+## Install
+
+1. Add the marketplace and install the plugin:
+
+   ```sh
+   claude plugin marketplace add alexei-led/claude-router
+   claude plugin install router@alexei-led-claude-router
+   ```
+
+2. When Claude Code asks, enter the TypeSafe API key. The key goes to the
+   macOS Keychain.
+3. In Claude Code, run `/router:setup`. It writes two keys to
+   `~/.claude/settings.json`: `model` and `env.ANTHROPIC_BASE_URL`.
+4. Restart Claude Code.
+
+The `SessionStart` hook of the plugin starts the gateway when the port does not
+answer. A claude.ai login continues to work: the gateway sends the
+authorization header and the OAuth value of `anthropic-beta` unchanged.
+
+## Documentation
+
+- [User guide](docs/user-guide.md): daily use, pins, decision log, troubleshooting.
+- [Configuration](docs/configuration.md): each key, and where the API key and the configuration file are.
+- [Design](docs/design.md): decisions, the switching policy, test results.
+
+## Develop
+
+```sh
+npm install
+npm test          # node:test
+npm run check     # biome lint and format
+npm run validate  # claude plugin validate
+claude --plugin-dir . --model router   # with ANTHROPIC_BASE_URL and TYPESAFE_API_KEY set
+```
+
+Releases: push a signed tag `v<version>` that matches `package.json`. The
+release workflow publishes `@alexeiled/claude-router` to npm with trusted
+publishing and creates the GitHub release. See
+[docs/design.md](docs/design.md#release).

package/docs/configuration.md

@@ -0,0 +1,112 @@
+# Configuration
+
+## Where each value is
+
+| Value | Location | Reason |
+| ----- | -------- | ------ |
+| TypeSafe API key | `TYPESAFE_API_KEY` in the environment of the gateway | One name in all places. The key is never in a file. |
+| The key for an installed plugin | The plugin option `typesafe_api_key`. Claude Code asks for it when you enable the plugin and stores it in the macOS Keychain. The `SessionStart` hook gives it to the gateway as `TYPESAFE_API_KEY`. | Claude Code exports plugin options as `CLAUDE_PLUGIN_OPTION_<KEY>`. The gateway does not read that name. |
+| Claude Code settings | `~/.claude/settings.json`: `model` and `env.ANTHROPIC_BASE_URL`. `/router:setup` writes them. | Claude Code reads the base URL at start. A plugin cannot set it. |
+| Routing configuration | `~/.claude/router.json`, user scope only | A cloned repository must not change your routing or your spend. |
+
+The gateway ignores project files. To use another file, set
+`ROUTER_CONFIG=/path/to/file.json`. The gateway reads the file at start. After
+an edit, stop the gateway with `pkill -f scripts/gateway.mjs`. The next session
+starts it again.
+
+## Claude Code settings
+
+`/router:setup` writes this to `~/.claude/settings.json`:
+
+```json
+{
+  "model": "router",
+  "env": { "ANTHROPIC_BASE_URL": "http://127.0.0.1:43170" }
+}
+```
+
+Two optional keys in `env`:
+
+- `CLAUDE_CODE_GATEWAY_HINT_HEADERS: "1"`. Claude Code then tells the gateway
+  the class of each request. Requests of the class `main` get routing. All
+  other classes (`auxiliary`, `subagent`, `workflow`, `compaction`) get
+  `gateway.auxiliaryTier`. A subagent with `model: inherit` runs on that tier.
+  Without the header, the gateway identifies side requests by their shape, and
+  subagents get routing like the main conversation.
+- `ANTHROPIC_CUSTOM_MODEL_OPTION: "router"`. The `/model` picker then shows a
+  `router` row.
+
+## Configuration file
+
+Each key is optional. A key in the file replaces the default with the same
+path. Nested objects merge.
+
+```json
+{
+  "gateway": { "port": 43170, "alias": "router", "baselineTier": "low", "auxiliaryTier": "low" },
+  "routes": {
+    "high":   { "model": "fable",  "effort": "xhigh" },
+    "medium": { "model": "opus",   "effort": "high" },
+    "low":    { "model": "sonnet" },
+    "micro":  { "model": "haiku" }
+  },
+  "models": {
+    "sonnet": { "id": "claude-sonnet-4-6", "input": 3, "cacheRead": 0.3, "contextWindow": 1000000, "billing": "plan", "efforts": ["low", "medium", "high", "max"] }
+  },
+  "policy": {
+    "upgradeVotes": 2,
+    "upgradeBase": 0.75,
+    "upgradeSlope": 0.15,
+    "upgradePivotUsd": 0.5,
+    "jumpConfidence": 0.95,
+    "downgradeVotes": 2,
+    "downgradeMass": 0.9,
+    "continuationMass": 0.7,
+    "escalationHoldTurns": 2,
+    "cashCapUsd": 2
+  },
+  "jev": { "model": "jev-1.13.0", "timeoutMs": 1500 },
+  "context": { "recentTurns": 6, "maxTextChars": 1200 },
+  "log": true
+}
+```
+
+### routes
+
+`routes.<tier>.model` is a key of `models`. `effort` is one of `low`, `medium`,
+`high`, `xhigh`, `max`, or absent. When `effort` is absent, the gateway keeps
+the effort that Claude Code sent. If you change a route, also change the
+frontmatter of `skills/<tier>/SKILL.md`. A test makes sure that they agree.
+
+### models
+
+`id` is the model id that the gateway sends to Anthropic. `input` and
+`cacheRead` are list prices in USD per million tokens. `contextWindow` is the
+size of the context window in tokens. `billing` is `plan` for models that use
+the subscription limits, or `credits` for models that bill usage credits.
+`policy.cashCapUsd` applies to `credits` models only. `efforts` lists the
+levels that the model accepts. An empty list means that the gateway removes
+effort and thinking from the request.
+
+### policy
+
+| Key | Meaning |
+| --- | ------- |
+| `gateway.baselineTier` | The tier when nothing else decides: Jev abstains, Jev fails, or the session is new. |
+| `gateway.auxiliaryTier` | The tier for side requests, for example session titles. |
+| `upgradeVotes` | The number of consecutive votes above the current tier before an upgrade of one tier. |
+| `upgradeBase`, `upgradeSlope`, `upgradePivotUsd` | The required probability mass: `base + slope * tax / (tax + pivot)`. The `tax` is the extra input cost to read the context on the new model. |
+| `jumpConfidence` | The mass that lets a jump of two tiers skip the vote delay. |
+| `downgradeVotes`, `downgradeMass` | The number of consecutive votes, and the mass at or below the candidate, for a downgrade. |
+| `continuationMass` | The Jev probability for "this prompt continues the task" that keeps the current route. |
+| `escalationHoldTurns` | The number of turns to hold one tier up after two failed repairs of the same error. |
+| `cashCapUsd` | The cold cache-write cost above which the gateway refuses an automatic route to a `credits` model. |
+
+## Environment variables
+
+| Variable | Effect |
+| -------- | ------ |
+| `TYPESAFE_API_KEY` | The Jev key. |
+| `ROUTER_CONFIG` | The path of the configuration file. |
+| `ROUTER_FORCE_TIER` | `micro`, `low`, `medium` or `high`. Skips Jev and the policy and always routes to that tier. For tests. |
+| `CLAUDE_PLUGIN_DATA` | Set by Claude Code for hooks. The directory holds `sessions/`, `decisions.jsonl` and `gateway.log`. |

package/docs/design.md

@@ -0,0 +1,192 @@
+# Design record
+
+Each decision has the date when the owner took it.
+
+## Goal
+
+Select a model and an effort level for each user turn, from the models that
+Claude Code offers, with one TypeSafe Jev Choice. Stay inside the Claude Code
+terminal interface.
+
+## Mechanism: local gateway (2026-09-22)
+
+Claude Code runs with `--model router`. `ANTHROPIC_BASE_URL` points at a
+gateway on `127.0.0.1`. The gateway sends each request to `api.anthropic.com`
+unchanged, except a request whose `model` is the alias. For that request, the
+gateway reads facts from the body, asks Jev once for each new user turn, runs
+the policy, and changes `model`, `output_config.effort` and `thinking`.
+Responses go through unchanged. The gateway reads `usage` from the response to
+get the context size, the cache reads and the cache TTL.
+
+The gateway never changes `system`, `tools` or `messages`. Thus preserved
+thinking and prompt caching work as if Claude Code talked to Anthropic. Claude
+Code documents this gateway mode, including the OAuth value for a claude.ai
+login. See [llm-gateway](https://code.claude.com/docs/en/llm-gateway) and
+[protocol](https://code.claude.com/docs/en/llm-gateway-protocol).
+
+The `SessionStart` hook of the plugin starts the gateway when the port does not
+answer. `/router:setup` writes `model` and `ANTHROPIC_BASE_URL` to the user settings
+once. A plugin cannot set them by itself.
+
+### Why not the native skill path
+
+The first design used a `UserPromptSubmit` hook. The hook asked Claude to call
+a tier skill. The frontmatter `model:` and `effort:` of the skill were to serve
+the rest of the turn.
+
+The test on Claude Code 2.1.278 gave this result. A skill that the user types
+(`/router:medium …`) changes the model for the turn. The same skill,
+called by Claude through the Skill tool, does not change the model. The
+transcript records `attributionSkill`, but the session model answers. The test
+ran in three sessions, in auto mode and in `acceptEdits` mode, with Opus and
+Fable targets. The documentation says "when this skill is active". The
+behavior is user invocation only. A feedback report is filed. The skills stay
+as manual pins.
+
+This result also removed the "Sonnet session model" argument from the peer
+review. The gateway has no bootstrap request and no cache drop for a turn that
+keeps its route. The baseline is a configuration value.
+
+## Tiers
+
+| Tier   | model  | effort   | id sent to Anthropic |
+| ------ | ------ | -------- | -------------------- |
+| high   | fable  | xhigh    | claude-fable-5-1     |
+| medium | opus   | high     | claude-opus-5        |
+| low    | sonnet | as sent  | claude-sonnet-4-6    |
+| micro  | haiku  | none     | claude-haiku-4-5     |
+
+The gateway lowers the effort to a level that the model family accepts. Sonnet
+4.6 has no `xhigh`. Haiku gets no effort and no adaptive thinking. The ids are
+configuration. `sonnet` is 4.6 because the alias resolved to 4.6 on the test
+account.
+
+## Request classes
+
+- New user turn (the last message has no `tool_result`): Jev and the policy.
+- Tool continuation: the route of the turn, without a Jev call.
+- Every request class other than `main`, from the header
+  `x-claude-code-request-class`: `auxiliaryTier`, and the memory stays
+  unchanged. Without the header, a body with `thinking: disabled` and a
+  `format` is a side request.
+- Any other `model`: unchanged. This covers `/router:<tier>` pins,
+  `/model` changes and subagents with their own model.
+
+## Cache and cost inputs
+
+All inputs come from the traffic of the gateway. The gateway does not read
+transcripts.
+
+| Input | Source |
+| ----- | ------ |
+| Context of the last request, cache reads, output | `usage` in the response (`message_start` and `message_delta`) |
+| Granted TTL | `usage.cache_creation.ephemeral_1h_input_tokens` or the `5m` field |
+| Cache warmth of a model | The time of the last response of that model, plus the TTL, minus 30 s |
+| Reusable prefix of a model | The context plus the output at the last response of that model. Cleared when the context shrinks by more than 20% (compaction). |
+| Failure signal | Two `tool_result` blocks with `is_error` and the same signature, with an edit tool call between them |
+| Continuation | The last message contains a `tool_result`. For a new prompt, a Jev Noul answers "does this prompt continue the task". |
+
+Prices are a list-price table in the configuration. `modelPricing` is a
+managed setting and is not readable. The switching tax for a candidate `c`
+against the current route `i` is:
+
+```
+input_cost(m) = P_read(m) * W_m + P_write(m) * (N - W_m)
+tax = max(0, input_cost(c) - input_cost(i))
+```
+
+The subscription economics are not symmetric. Sonnet, Opus and Haiku use the
+plan limits. Dollars give the order between them. Fable bills usage credits in
+cash, on the 5m TTL, and behind the gateway without the consent prompt of
+Claude Code. A Claude Code turn starts at about 100k tokens (system prompt and
+159 tool definitions). A cold Fable write costs about $1.25 before any history.
+`policy.cashCapUsd` is $2 by default.
+
+## Switching policy v0
+
+Agreed with Codex on 2026-09-22. The thresholds are start values.
+
+1. Pins win. A request for a real model id goes through unchanged.
+2. To stay is a decision. The current route is the route that served the last
+   turn. A prompt that continues the task keeps it and never votes for a
+   downgrade.
+3. Escalation floor. Two failed repairs of the same failure signature, with an
+   edit between them, move the route one tier up. The route holds for two
+   turns, once for each signature.
+4. Votes keep the Jev probabilities. `U` is the mass above the current tier.
+   `D` is the mass at or below the candidate. The `uncertain` mass supports
+   neither. An upgrade needs two consecutive votes above the current tier and
+   `U >= 0.75 + 0.15 * tax / (tax + 0.5)`. A jump of two tiers with
+   `U >= 0.95` skips the delay. A downgrade needs `D >= 0.90` and two
+   consecutive votes.
+5. Cash gate. An automatic route to a `credits` model needs a warm cache, or a
+   cold write below the cap. Otherwise the strongest `plan` tier serves.
+6. No cooldown on upgrades. Plan, then execute, then hard again is sometimes
+   the correct routing. The log separates reversals from real changes in the
+   required capability.
+7. Logs. The tier, the reason, the estimates, and the observed model, tokens
+   and cache reads of each routed response. The memory changes only from
+   responses that the gateway sent.
+
+## Test results (2026-09-22, Max plan, Claude Code 2.1.278)
+
+- Easy prompt: Jev gave `micro` at confidence 1. It was the first vote, so
+  `low` served (`claude-sonnet-4-6`, 103,799 context tokens on the first
+  request).
+- Hard prompt: Jev gave `high` at 0.66. A cold Fable write cost $1.30 against
+  the cap of $0.50 at that time, so `medium` served (`claude-opus-5`). Four
+  tool continuations kept the route, with cache reads within 1% of the
+  context.
+- Claude Code accepted `message_start.model` with the real model. The status
+  line showed the alias at all times.
+- Cold start: the `SessionStart` hook started the gateway before the first
+  request.
+
+## Layout
+
+```
+  .claude-plugin/plugin.json   userConfig.typesafe_api_key (Keychain)
+  .claude-plugin/marketplace.json  npm source @alexeiled/claude-router
+  hooks/hooks.json             SessionStart -> scripts/ensure-gateway.mjs
+  scripts/gateway.mjs          daemon entry
+  scripts/ensure-gateway.mjs   port probe, detached spawn
+  scripts/transcript-models.sh model for each assistant line of a transcript
+  lib/runtime.mjs              configuration and data directory from the environment
+  lib/config.mjs               defaults, user file, validation
+  lib/facts.mjs                request body and memory -> facts (pure)
+  lib/jev.mjs                  request, injected transport, parse
+  lib/cost.mjs                 warmth, input cost, switching tax
+  lib/policy.mjs               switching policy v0
+  lib/rewrite.mjs              model, effort, thinking per model family
+  lib/sse.mjs                  usage reader for SSE and JSON bodies
+  lib/router.mjs               orchestration for one request, session memory
+  lib/gateway.mjs              HTTP passthrough and rewrite
+  lib/store.mjs                files: configuration, memory, decisions.jsonl
+  skills/<tier>/SKILL.md       manual pins (model and effort frontmatter)
+  skills/setup/SKILL.md        writes model and ANTHROPIC_BASE_URL to the user settings
+  test/                        node:test, builders in helpers.mjs
+```
+
+## Open questions
+
+- The exit from plan mode is not visible in the request body. The policy has
+  no boundary rule.
+- The thresholds are not tuned. The estimated and the observed cache reads in
+  `decisions.jsonl` are the input for the tuning.
+- The gateway reads the configuration once. A reload without a restart is not
+  implemented.
+- Without `CLAUDE_CODE_GATEWAY_HINT_HEADERS=1`, subagents with `model: inherit`
+  get routing like the main conversation.
+
+## Release
+
+The repository root is the plugin and the npm package `@alexeiled/claude-router`.
+The marketplace `alexei-led-claude-router` in `.claude-plugin/marketplace.json`
+points at that package. Local development uses `claude --plugin-dir .`.
+
+A release is a signed annotated tag `v<version>` on `main`, where the version
+matches `package.json`. The `release.yml` workflow makes sure that the tag is
+signed and on `main`, runs the checks and the tests, publishes to npm with
+trusted publishing (`npm publish --provenance`, no token), and creates the
+GitHub release. The `ci.yml` workflow runs the checks and the tests for each
+push and pull request on `main`.

package/docs/user-guide.md

@@ -0,0 +1,87 @@
+# User guide
+
+## Start a session
+
+After the install steps in the README, run `claude` as usual. The status line
+shows `router` as the model. The transcript records the model that answered
+each message. The first session starts the gateway. The gateway continues to
+run after the session ends.
+
+To try the gateway in one session without a change to the configuration:
+
+```sh
+TYPESAFE_API_KEY=… node scripts/gateway.mjs &
+ANTHROPIC_BASE_URL=http://127.0.0.1:43170 claude --plugin-dir . --model router
+```
+
+## What happens at each prompt
+
+- A new prompt causes one Jev call. The call takes about one second and gives
+  a tier. Then the policy decides if it acts on the tier.
+- Tool calls inside the turn keep the route. The gateway does not ask Jev, and
+  the cache of the model continues to hit.
+- A prompt that continues the task keeps the route. Examples: "continue",
+  "yes", "now fix the tests".
+- After two failed repairs of the same error, the route goes up one tier. The
+  route stays there for two turns. A repair is an edit between the two errors.
+- An upgrade needs two consecutive votes for a higher tier. A jump of two
+  tiers with high confidence happens at once. The required confidence goes up
+  with the cost to read the context again on the new model.
+- A downgrade needs two consecutive confident votes.
+- A cold switch to Fable is refused when the cache write costs more than
+  `policy.cashCapUsd`. Then Opus serves the turn. Fable bills usage credits.
+  Behind the gateway, Claude Code does not show its consent prompt for these
+  credits. The cap is the only guard.
+- When Jev fails or times out, or when there is no key, the baseline tier
+  serves the turn.
+- Jev receives the prompt and the last six turns of text. Tool results are not
+  sent. No other data leaves the machine, except the usual Anthropic request.
+
+A Claude Code turn starts at about 100k tokens of system prompt and tool
+definitions. A cold Fable cache write costs about $1.25 before any history.
+
+## Pin a tier by hand
+
+Type the tier skill as a command. The turn runs on the model of that skill.
+The gateway sends the real model id unchanged.
+
+```
+/router:high  redesign the auth flow
+/router:micro rename foo to bar in this file
+```
+
+`/model <name>` also works. It stops the routing for the rest of the session.
+
+## Read the decisions
+
+The gateway writes one line for each routed request to `decisions.jsonl` in
+the plugin data directory. The directory is
+`~/.claude/plugins/data/router-<marketplace>/`. For a gateway that you started
+by hand, the directory is `$TMPDIR/router/`.
+
+```sh
+tail -n 20 ~/.claude/plugins/data/router-*/decisions.jsonl | jq -c '{tier, reason, estimate, observed}'
+```
+
+`tier` is the selected tier. `reason` is the rule that decided. The `observed`
+lines carry the model that answered, the context tokens and the cache reads
+from the response. Compare the estimated and the observed cache reads to tune
+the thresholds.
+
+`scripts/transcript-models.sh <transcript.jsonl>` shows the model for each
+assistant message in a Claude Code transcript.
+
+## Troubleshooting
+
+- If Claude Code does not accept `router` as a model, make sure that the
+  gateway runs and that `ANTHROPIC_BASE_URL` is set. The command
+  `curl http://127.0.0.1:43170/v1/models` lists the alias.
+- If Claude Code reports that it does not use the gateway, run
+  `/router:setup` and restart Claude Code.
+- If each turn runs on Sonnet, make sure that the key is set. Read the
+  `router:` lines in `gateway.log` next to `decisions.jsonl`.
+- If the effort is not what you set, read the `efforts` list of the model. The
+  gateway lowers the effort to a level that the model accepts. Sonnet 4.6 has
+  no `xhigh`. Haiku has no effort and no thinking.
+- To stop the gateway, run `pkill -f scripts/gateway.mjs`. The next session
+  starts it again.

package/hooks/hooks.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/ensure-gateway.mjs"],
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/lib/config.mjs

@@ -0,0 +1,129 @@
+// Defaults, user overrides and validation. Pure: callers pass env and the parsed user file.
+
+export const TIERS = ['micro', 'low', 'medium', 'high'];
+export const EFFORTS = ['low', 'medium', 'high', 'xhigh', 'max'];
+
+export const DEFAULTS = {
+  gateway: { port: 43170, alias: 'router', baselineTier: 'low', auxiliaryTier: 'low' },
+  routes: {
+    high: { model: 'fable', effort: 'xhigh' },
+    medium: { model: 'opus', effort: 'high' },
+    low: { model: 'sonnet' },
+    micro: { model: 'haiku' },
+  },
+  // `id` is sent upstream verbatim. List prices in USD per million tokens; `cacheRead` is absolute,
+  // not a multiplier: Fable 5.1 reads are billed at 0.25 (Claude API reference, verify when prices move).
+  // `efforts` lists what the model accepts; an empty list means no effort field and no adaptive thinking.
+  models: {
+    fable: {
+      id: 'claude-fable-5-1',
+      input: 10,
+      cacheRead: 0.25,
+      contextWindow: 1_000_000,
+      billing: 'credits',
+      efforts: EFFORTS,
+    },
+    opus: {
+      id: 'claude-opus-5',
+      input: 5,
+      cacheRead: 0.5,
+      contextWindow: 1_000_000,
+      billing: 'plan',
+      efforts: EFFORTS,
+    },
+    sonnet: {
+      id: 'claude-sonnet-4-6',
+      input: 3,
+      cacheRead: 0.3,
+      contextWindow: 1_000_000,
+      billing: 'plan',
+      efforts: ['low', 'medium', 'high', 'max'],
+    },
+    haiku: { id: 'claude-haiku-4-5', input: 1, cacheRead: 0.1, contextWindow: 200_000, billing: 'plan', efforts: [] },
+  },
+  cache: {
+    writeMultiplier: { '5m': 1.25, '1h': 2 },
+    ttlMs: { '5m': 300_000, '1h': 3_600_000 },
+    warmMarginMs: 30_000,
+  },
+  policy: {
+    upgradeVotes: 2,
+    upgradeBase: 0.75,
+    upgradeSlope: 0.15,
+    upgradePivotUsd: 0.5, // tax at which half the slope applies: $0.20 of tax raises the bar to ~0.79, $4 to ~0.88
+    jumpConfidence: 0.95,
+    downgradeVotes: 2,
+    downgradeMass: 0.9,
+    continuationMass: 0.7,
+    escalationHoldTurns: 2,
+    cashCapUsd: 2, // a Claude Code turn starts near 100k tokens (system prompt + tools): cold Fable is ~$1.25 before any history
+  },
+  jev: { endpoint: 'https://api.typesafe.ai/v1/systemone', model: 'jev-1.13.0', timeoutMs: 1500 },
+  context: { recentTurns: 6, maxTextChars: 1200 },
+  log: true,
+};
+
+const API_KEY_VAR = 'TYPESAFE_API_KEY';
+
+export function loadConfig({ env = {}, userFile = null } = {}) {
+  const config = merge(DEFAULTS, userFile ?? {});
+  validate(config);
+  const apiKey = env[API_KEY_VAR]?.trim() || null;
+  const forcedTier = env.ROUTER_FORCE_TIER ?? null;
+  if (forcedTier && !TIERS.includes(forcedTier))
+    throw new Error(`ROUTER_FORCE_TIER must be one of ${TIERS.join(', ')}`);
+  return { ...config, apiKey, forcedTier };
+}
+
+export function rank(tier) {
+  return TIERS.indexOf(tier);
+}
+
+function merge(base, override) {
+  if (Array.isArray(base) || typeof base !== 'object' || base === null) return override;
+  const out = { ...base };
+  for (const [key, value] of Object.entries(override)) {
+    out[key] =
+      key in base && typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? merge(base[key], value)
+        : value;
+  }
+  return out;
+}
+
+function validate(config) {
+  for (const tier of TIERS) {
+    const route = config.routes[tier];
+    if (!route || typeof route.model !== 'string') throw new Error(`routes.${tier}.model is required`);
+    const model = config.models[route.model];
+    if (!model) throw new Error(`routes.${tier}.model "${route.model}" is not in models`);
+    if (route.effort !== undefined && !EFFORTS.includes(route.effort))
+      throw new Error(`routes.${tier}.effort "${route.effort}" is invalid`);
+  }
+  for (const [alias, model] of Object.entries(config.models)) {
+    for (const field of ['input', 'cacheRead', 'contextWindow']) {
+      if (!Number.isFinite(model[field]) || model[field] < 0)
+        throw new Error(`models.${alias}.${field} must be a non-negative number`);
+    }
+    if (typeof model.id !== 'string' || !model.id) throw new Error(`models.${alias}.id is required`);
+    if (!['plan', 'credits'].includes(model.billing))
+      throw new Error(`models.${alias}.billing must be plan or credits`);
+    if (!Array.isArray(model.efforts) || model.efforts.some((e) => !EFFORTS.includes(e)))
+      throw new Error(`models.${alias}.efforts must list valid effort levels`);
+  }
+  for (const key of ['baselineTier', 'auxiliaryTier']) {
+    if (!TIERS.includes(config.gateway[key])) throw new Error(`gateway.${key} must be one of ${TIERS.join(', ')}`);
+  }
+  if (!Number.isInteger(config.gateway.port) || config.gateway.port < 1 || config.gateway.port > 65535)
+    throw new Error('gateway.port must be a port number');
+  if (typeof config.gateway.alias !== 'string' || !config.gateway.alias) throw new Error('gateway.alias is required');
+  const p = config.policy;
+  for (const field of ['upgradeBase', 'jumpConfidence', 'downgradeMass', 'continuationMass']) {
+    if (!(p[field] >= 0 && p[field] <= 1)) throw new Error(`policy.${field} must be between 0 and 1`);
+  }
+  for (const field of ['upgradeVotes', 'downgradeVotes', 'escalationHoldTurns']) {
+    if (!Number.isInteger(p[field]) || p[field] < 1) throw new Error(`policy.${field} must be a positive integer`);
+  }
+  if (!(p.cashCapUsd >= 0)) throw new Error('policy.cashCapUsd must be a non-negative number');
+  if (!(config.jev.timeoutMs > 0)) throw new Error('jev.timeoutMs must be positive');
+}