@alexeiled/claude-router 0.8.0 → 1.1.0

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.
Files changed (48) hide show
  1. package/.claude-plugin/plugin.json +11 -7
  2. package/CHANGELOG.md +43 -0
  3. package/README.md +55 -98
  4. package/docs/architecture.md +55 -419
  5. package/docs/configuration.md +88 -182
  6. package/docs/evaluation.md +62 -81
  7. package/docs/native-router.md +80 -0
  8. package/docs/router-band.svg +119 -0
  9. package/docs/router-pane-now.svg +85 -0
  10. package/docs/router-pane-tiers.svg +62 -0
  11. package/docs/user-guide.md +127 -172
  12. package/hooks/hooks.json +1 -26
  13. package/hooks/native-router.mjs +701 -0
  14. package/lib/config.mjs +97 -63
  15. package/lib/{facts.mjs → facts-pure.mjs} +2 -23
  16. package/lib/{jev.mjs → jev-contract.mjs} +17 -38
  17. package/lib/native-band.mjs +206 -0
  18. package/lib/native-cost.mjs +88 -0
  19. package/lib/native-display.mjs +122 -0
  20. package/lib/native-jev.mjs +125 -0
  21. package/lib/native-panel.mjs +492 -0
  22. package/lib/native-router.mjs +221 -0
  23. package/lib/policy.mjs +17 -21
  24. package/package.json +10 -8
  25. package/scripts/migrate-config.mjs +57 -0
  26. package/types/index.d.ts +112 -0
  27. package/lib/cost.mjs +0 -93
  28. package/lib/gateway.mjs +0 -221
  29. package/lib/idle.mjs +0 -41
  30. package/lib/rewrite.mjs +0 -130
  31. package/lib/router.mjs +0 -276
  32. package/lib/runtime.mjs +0 -78
  33. package/lib/sse.mjs +0 -57
  34. package/lib/status.mjs +0 -152
  35. package/lib/store.mjs +0 -76
  36. package/scripts/ensure-gateway.mjs +0 -143
  37. package/scripts/gateway.mjs +0 -81
  38. package/scripts/git-hooks/pre-commit +0 -41
  39. package/scripts/git-hooks/pre-push +0 -34
  40. package/scripts/status.mjs +0 -20
  41. package/scripts/statusline.mjs +0 -45
  42. package/scripts/transcript-models.sh +0 -4
  43. package/skills/high/SKILL.md +0 -9
  44. package/skills/low/SKILL.md +0 -7
  45. package/skills/medium/SKILL.md +0 -8
  46. package/skills/micro/SKILL.md +0 -7
  47. package/skills/setup/SKILL.md +0 -31
  48. package/skills/status/SKILL.md +0 -12
@@ -1,20 +0,0 @@
1
- #!/usr/bin/env node
2
- // /router:status: routes, key state and the last routed turn of a session, as markdown.
3
- // Usage: status.mjs [session id] [--config <path>]. It reads the configuration and starts nothing, so it is also
4
- // the way to see why a router.json does not load.
5
- import { cliArg, loadRuntime } from '../lib/runtime.mjs';
6
- import { fetchStatus, statusReport } from '../lib/status.mjs';
7
-
8
- const argv = process.argv.slice(2);
9
- const configPath = cliArg(argv, '--config');
10
- const session = argv.find((arg, i) => !arg.startsWith('--') && argv[i - 1] !== '--config');
11
-
12
- let config;
13
- try {
14
- ({ config } = loadRuntime(process.env, { configPath }));
15
- } catch (error) {
16
- // Exit 0: /router:status injects this output into a skill, and Claude Code drops a skill whose command fails.
17
- process.stdout.write(`router: invalid configuration: ${error.message}\n`);
18
- process.exit(0);
19
- }
20
- process.stdout.write(`${statusReport(await fetchStatus(config.gateway.port, session))}\n`);
@@ -1,45 +0,0 @@
1
- #!/usr/bin/env node
2
- // Status line: prints the model and effort that served the last routed turn.
3
- // Usage in settings.json: "statusLine": { "command": "node <plugin>/scripts/statusline.mjs [wrapped command ...]" }.
4
- // A wrapped command (for example claude-powerline) gets the same stdin; its output comes first.
5
- import { spawn } from 'node:child_process';
6
- import { text } from 'node:stream/consumers';
7
- import { LEGACY_ALIAS } from '../lib/config.mjs';
8
- import { loadRuntime } from '../lib/runtime.mjs';
9
- import { fetchStatus, ROUTER_DISPLAY_NAME, statusSegment } from '../lib/status.mjs';
10
-
11
- const input = await text(process.stdin);
12
- const [command, ...args] = process.argv.slice(2);
13
- // A broken router.json must not break the status line: skip the router segment, still run a wrapped command.
14
- let config = null;
15
- try {
16
- ({ config } = loadRuntime(process.env));
17
- } catch {}
18
- let payload = {};
19
- try {
20
- payload = JSON.parse(input);
21
- } catch {}
22
-
23
- const names = config ? [config.gateway.alias, LEGACY_ALIAS, ROUTER_DISPLAY_NAME] : [];
24
- // `jev-router[1m]`: the suffix only tells Claude Code the window size.
25
- const routed = [payload.model?.id, payload.model?.display_name].some((name) =>
26
- names.includes(name?.replace(/\[1m\]$/, '')),
27
- );
28
- const [status] = await Promise.all([
29
- routed ? fetchStatus(config.gateway.port, payload.session_id) : null,
30
- command ? runWrapped(command, args, input) : null,
31
- ]);
32
- if (routed) process.stdout.write(`${statusSegment(status)}\n`);
33
-
34
- function runWrapped(cmd, argv, stdin) {
35
- return new Promise((resolve) => {
36
- const child = spawn(cmd, argv, { stdio: ['pipe', 'inherit', 'inherit'] });
37
- child.on('error', (error) => {
38
- process.stdout.write(`statusline: ${cmd}: ${error.message}\n`);
39
- resolve();
40
- });
41
- child.on('close', resolve);
42
- child.stdin.on('error', () => {}); // the wrapped command may exit without reading stdin
43
- child.stdin.end(stdin);
44
- });
45
- }
@@ -1,4 +0,0 @@
1
- #!/bin/sh
2
- # Print model, session effort, per-turn effort, active skill and block types per assistant line.
3
- # Usage: spike-check.sh ~/.claude/projects/<project>/<session>.jsonl
4
- jq -r 'select(.type=="assistant") | [.timestamp[11:19], .message.model, (.effort // "-"), (.perTurnEffort // "-"), (.attributionSkill // "-"), ([.message.content[]?.type] | join(","))] | @tsv' "$1"
@@ -1,9 +0,0 @@
1
- ---
2
- name: high
3
- disable-model-invocation: true
4
- description: Manual pin: run this turn on opus at xhigh effort. Use as /router:high <prompt>.
5
- model: opus
6
- effort: xhigh
7
- ---
8
-
9
- Routing tier applied. Continue with the user's request as written. Do not mention the router.
@@ -1,7 +0,0 @@
1
- ---
2
- name: low
3
- disable-model-invocation: true
4
- description: Manual pin: run this turn on sonnet. Use as /router:low <prompt>.
5
- model: sonnet
6
- ---
7
- Routing tier applied. Continue with the user's request as written. Do not mention the router.
@@ -1,8 +0,0 @@
1
- ---
2
- name: medium
3
- disable-model-invocation: true
4
- description: Manual pin: run this turn on sonnet at xhigh effort. Use as /router:medium <prompt>.
5
- model: sonnet
6
- effort: xhigh
7
- ---
8
- Routing tier applied. Continue with the user's request as written. Do not mention the router.
@@ -1,7 +0,0 @@
1
- ---
2
- name: micro
3
- disable-model-invocation: true
4
- description: Manual pin: run this turn on haiku. Use as /router:micro <prompt>.
5
- model: haiku
6
- ---
7
- Routing tier applied. Continue with the user's request as written. Do not mention the router.
@@ -1,31 +0,0 @@
1
- ---
2
- name: setup
3
- description: Point Claude Code at the router gateway. Adds `model` with the 1M window, `ANTHROPIC_BASE_URL`, tool search and the `/model` picker row to the user settings, and offers the status line.
4
- disable-model-invocation: true
5
- allowed-tools: Read, Edit, Write
6
- ---
7
-
8
- Configure Claude Code for the router gateway. This session does not use the gateway until Claude Code restarts. When the file has `model: "jev-router[1m]"`, this session can fail its next request. So ask all questions first, write the file once, and write it last.
9
-
10
- 1. Read `~/.claude/settings.json`. If the file does not exist, start from `{}`. Read `~/.claude/router.json` if it exists.
11
- 2. The status line can show the model and effort of the last routed turn. The command is `node ${CLAUDE_PLUGIN_ROOT}/scripts/statusline.mjs`, followed by the current status line command if there is one (for example `node ${CLAUDE_PLUGIN_ROOT}/scripts/statusline.mjs claude-powerline`). Show the user the current `statusLine` value and the new one, and ask. Change `statusLine.command` only if the user agrees. Keep the other `statusLine` keys.
12
- 3. Prepare the new settings object in memory:
13
- - `model`: `"jev-router[1m]"`. Claude Code does not know the model `jev-router` and assumes a 200K window; the `[1m]` suffix declares 1M. Claude Code strips the suffix before it sends the request. If `router.json` routes no model with a 1M `contextWindow`, use `"jev-router"`.
14
- - `env.ANTHROPIC_BASE_URL`: `"http://127.0.0.1:43170"`. If `router.json` sets `gateway.port`, use that port.
15
- - `env.ENABLE_TOOL_SEARCH`: `"true"`. With a custom `ANTHROPIC_BASE_URL`, Claude Code turns tool search off and loads every MCP tool schema into each request (about 50K tokens with the claude.ai connectors). This key keeps the schemas deferred, as with the Anthropic API.
16
- - `env.CLAUDE_CODE_GATEWAY_HINT_HEADERS`: `"1"`. Claude Code then tells the gateway the class of each request (main turn, subagent, side request, compaction) instead of the gateway guessing it from the body.
17
- - Remove `env.CLAUDE_CODE_MAX_CONTEXT_TOKENS`. Older versions of this setup wrote it; Claude Code ignores it for `jev-router`. The gateway sends a turn only to a model whose window holds the context, and drops the 1M beta header for a model with a smaller window.
18
- - The `/model` picker row. In `modelPicker.options`, replace the row whose `model` is `"jev-router[1m]"`, `"jev-router"` or `"router"` (the name before 0.4.2), or append it if there is none:
19
- `{ "model": "jev-router[1m]", "label": "Jev Router (auto)", "description": "Auto-selects the model and effort for each turn", "behavesAs": "claude-opus-5-5" }`.
20
- If `modelPicker` does not exist, set it to `{ "options": [<the row>] }`. Keep the other rows and `replaceBuiltInOptions`. `behavesAs` names a model that Claude Code knows; without it, Claude Code rejects `jev-router` as a model that is not in its catalog. If `router.json` changes the `high` route, use the `id` of its model.
21
- - Remove `env.ANTHROPIC_CUSTOM_MODEL_OPTION`, `env.ANTHROPIC_CUSTOM_MODEL_OPTION_NAME` and `env.ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION`. Older versions of this setup wrote them; the `modelPicker` row replaces them.
22
- - The `statusLine` change from step 2, if the user agreed.
23
- - Keep every other key unchanged.
24
- 4. Tell the user, before you write the file:
25
- - Restart Claude Code now. Until the restart, this session can show "There's an issue with the selected model (jev-router[1m])", because it still sends requests to Anthropic and not to the gateway.
26
- - After the restart, the router serves each turn, and `/router:status` shows the routes and the last turn.
27
- - The status line path contains the plugin version. After a plugin update, run `/router:setup` again.
28
- - To stop the routing, remove `model`, `env.ANTHROPIC_BASE_URL`, `env.ENABLE_TOOL_SEARCH`, `env.CLAUDE_CODE_GATEWAY_HINT_HEADERS` and the `jev-router[1m]` row of `modelPicker.options`, and restore the status line command.
29
- 5. Write the whole object to `~/.claude/settings.json` with one Write call. Do not use a sequence of edits. Do nothing after this step.
30
-
31
- Do not change any other file.
@@ -1,12 +0,0 @@
1
- ---
2
- name: status
3
- description: Show which model served the last turn, whether Jev routing is active, and the routing config.
4
- disable-model-invocation: true
5
- allowed-tools: Bash(node ${CLAUDE_PLUGIN_ROOT}/scripts/status.mjs *)
6
- ---
7
-
8
- Router status:
9
-
10
- !`node ${CLAUDE_PLUGIN_ROOT}/scripts/status.mjs ${CLAUDE_SESSION_ID}`
11
-
12
- Show this status to the user as written. Do not add commentary.