@alexeiled/claude-router 1.15.0 → 1.17.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.
@@ -0,0 +1,116 @@
1
+ // Execution presets, not classifier services. Prices are API list-price estimates, never a plan bill.
2
+ // Sources and the limits of these starting routes are in docs/configuration.md#provider-profiles.
3
+ const EFFORTS = ['low', 'high', 'max'];
4
+ const AUTOMATIC = {
5
+ mode: 'automatic',
6
+ effortScope: 'unknown',
7
+ writeMultiplier: {},
8
+ ttlMs: {},
9
+ warmMarginMs: 0,
10
+ };
11
+ const route = (model, effort) => ({ model, effort });
12
+ const agents = (light, heavy) => ({
13
+ types: { Explore: light, Plan: 'classify', 'general-purpose': 'classify' },
14
+ light,
15
+ standard: heavy,
16
+ heavy,
17
+ heavyMass: 0.8,
18
+ });
19
+
20
+ export const PROVIDER_DEFAULTS = {
21
+ deepseek: {
22
+ models: {
23
+ flash: {
24
+ id: 'deepseek-flash[1m]',
25
+ input: 0.3,
26
+ output: 1.2,
27
+ cacheRead: 0.006,
28
+ contextWindow: 1_000_000,
29
+ billing: 'credits',
30
+ efforts: EFFORTS,
31
+ strength: 1,
32
+ imageInput: true,
33
+ },
34
+ },
35
+ routes: {
36
+ micro: route('flash', 'low'),
37
+ low: route('flash', 'high'),
38
+ medium: route('flash', 'high'),
39
+ high: route('flash', 'max'),
40
+ },
41
+ activities: Object.fromEntries(
42
+ ['code', 'debug', 'plan', 'review'].map((a) => [a, { medium: route('flash', 'max') }]),
43
+ ),
44
+ subagents: agents('flash', 'flash'),
45
+ cache: AUTOMATIC,
46
+ },
47
+ zai: {
48
+ models: {
49
+ flash: {
50
+ id: 'glm-5.3-flash[1m]',
51
+ input: 0.15,
52
+ output: 0.5,
53
+ cacheRead: 0.03,
54
+ contextWindow: 1_000_000,
55
+ billing: 'credits',
56
+ efforts: EFFORTS,
57
+ strength: 1,
58
+ imageInput: true,
59
+ },
60
+ glm: {
61
+ id: 'glm-5.3[1m]',
62
+ input: 1.4,
63
+ output: 4.4,
64
+ cacheRead: 0.26,
65
+ contextWindow: 1_000_000,
66
+ billing: 'credits',
67
+ efforts: EFFORTS,
68
+ strength: 2,
69
+ imageInput: false,
70
+ },
71
+ },
72
+ routes: {
73
+ micro: route('flash', 'low'),
74
+ low: route('flash', 'high'),
75
+ medium: route('glm', 'high'),
76
+ high: route('glm', 'max'),
77
+ },
78
+ activities: {
79
+ ...Object.fromEntries(['code', 'debug', 'plan', 'review'].map((a) => [a, { medium: route('glm', 'max') }])),
80
+ ...Object.fromEntries(
81
+ ['ops', 'explore', 'docs'].map((a) => [a, { medium: route('flash', 'high'), high: route('flash', 'max') }]),
82
+ ),
83
+ },
84
+ subagents: agents('flash', 'glm'),
85
+ cache: AUTOMATIC,
86
+ },
87
+ };
88
+
89
+ // A provider is an identifier, never a path. Unknown providers may supply a complete standalone profile.
90
+ export function providerName(value) {
91
+ if (value == null || value === '') return 'anthropic';
92
+ if (typeof value !== 'string' || !/^[a-z][a-z0-9-]{0,63}$/.test(value))
93
+ throw new Error('invalid router provider identifier');
94
+ return value;
95
+ }
96
+
97
+ export function providerFile(value) {
98
+ const provider = providerName(value);
99
+ return provider === 'anthropic' ? 'router.json' : `${provider}-router.json`;
100
+ }
101
+
102
+ export const canonicalModel = (id) => (typeof id === 'string' ? id.replace(/\[1m\]$/, '') : id);
103
+
104
+ export function executionDefaults(provider, defaults) {
105
+ if (provider === 'anthropic') return defaults;
106
+ return {
107
+ ...defaults,
108
+ models: {},
109
+ routes: {},
110
+ activities: {},
111
+ subagentRouting: 'off',
112
+ subagents: { types: {}, light: '', standard: '', heavy: '', heavyMass: 0.8 },
113
+ cache: AUTOMATIC,
114
+ ...(Object.hasOwn(PROVIDER_DEFAULTS, provider) ? { subagentRouting: 'on', ...PROVIDER_DEFAULTS[provider] } : {}),
115
+ };
116
+ }
package/lib/route.mjs CHANGED
@@ -1,8 +1,9 @@
1
1
  import { chooseActivity, compareRoutes, lateralMove, sameRequest } from './activity.mjs';
2
2
  import { ACTIVITIES, rank, resolveRoute, routeSpec, sameRoute, TIERS } from './config.mjs';
3
3
  import * as costs from './cost.mjs';
4
- import { clip, extractFacts, verifiedSince } from './facts.mjs';
4
+ import { clip, completedSince, extractFacts } from './facts.mjs';
5
5
  import { CONTEXT_FILL, decide, fitTier, initialState, sameTaskOf } from './policy.mjs';
6
+ import { canonicalModel } from './providers.mjs';
6
7
 
7
8
  // Exact observed API snapshot, not a rule that merges different dated versions.
8
9
  const SNAPSHOTS = { 'claude-haiku-4-5': 'claude-haiku-4-5-20251001' };
@@ -13,7 +14,9 @@ export const HISTORY_SHRINK = 0.8;
13
14
 
14
15
  // Whether the engine served the requested model, allowing for a dated snapshot of it.
15
16
  export function isSameModel(requested, served) {
16
- return requested === served || SNAPSHOTS[requested] === served;
17
+ if (typeof requested !== 'string' || typeof served !== 'string') return false;
18
+ const [a, b] = [canonicalModel(requested), canonicalModel(served)];
19
+ return a === b || SNAPSHOTS[a] === b;
17
20
  }
18
21
 
19
22
  // The engine may echo our own routed model on a continuation; any third model is its fallback.
@@ -103,11 +106,12 @@ export function prepareLoop(loop, messageCount) {
103
106
  export function nativeFacts(config, loop, { messages, prompt, effort, turnId, contextTokens }) {
104
107
  const facts = extractFacts({ messages, output_config: { effort } }, loop, config.context);
105
108
  if (typeof prompt === 'string') facts.prompt = clip(prompt, config.context.maxTextChars);
106
- // A move down on the same task waits out the dwell and for a passed verification since the last model change.
109
+ // A move down on the same task waits out the dwell and for a checkpoint since the last model change: a passed check,
110
+ // or the success the running route's activity can show (completedSince).
107
111
  const since = loop.switchedAt ?? { requests: 0, messageCount: 0 };
108
112
  const downAllowed =
109
113
  (loop.requests ?? 0) - since.requests >= config.policy.minDwellRequests &&
110
- verifiedSince(messages, since.messageCount);
114
+ completedSince(messages, since.messageCount, activityOf(config, loop));
111
115
  // A loop saved without the field counts as measured, keeping the vote streak.
112
116
  return {
113
117
  ...facts,
@@ -119,14 +123,19 @@ export function nativeFacts(config, loop, { messages, prompt, effort, turnId, co
119
123
  };
120
124
  }
121
125
 
122
- export function isModelAllowed(id, available, nativeModel) {
123
- if (available === undefined) return true;
124
- if (!Array.isArray(available) || !available.every((v) => typeof v === 'string')) return false;
126
+ export function isModelAllowed(requested, allowed, native) {
127
+ if (allowed === undefined) return true;
128
+ if (!Array.isArray(allowed) || !allowed.every((v) => typeof v === 'string')) return false;
129
+ const id = canonicalModel(requested);
130
+ const nativeModel = canonicalModel(native);
131
+ const available = allowed.map(canonicalModel);
125
132
  if (available.includes('default') && id === nativeModel) return true;
126
133
  const family = /^claude-(opus|sonnet|haiku)-/.exec(id)?.[1];
127
134
  const specific = available.filter((v) => family && v.startsWith(`claude-${family}-`));
128
135
  if (specific.length) return specific.some((v) => id === v || id.startsWith(`${v}-`));
129
- return available.some((v) => id === v || id.startsWith(`${v}-`) || (family && v === family));
136
+ return available.some(
137
+ (v) => id === v || (id.startsWith('claude-') && id.startsWith(`${v}-`)) || (family && v === family),
138
+ );
130
139
  }
131
140
 
132
141
  function economicConfig(config, loop) {
@@ -213,6 +222,7 @@ function routeTurn(config, loop, { facts, advice, pin, nativeModel, contextKnown
213
222
  const model = specOf(cell);
214
223
  return (
215
224
  !shrinksUnmeasured(cell) &&
225
+ (!facts.hasImages || model.imageInput !== false) &&
216
226
  isModelAllowed(model.id, availableModels, nativeModel) &&
217
227
  !loop.ineligible.includes(model.id) &&
218
228
  (!contextKnown || costs.nextContextTokens(facts) <= model.contextWindow * CONTEXT_FILL)
@@ -364,7 +374,11 @@ export function observedMove(config, loop, { observed, facts, contextKnown, now
364
374
 
365
375
  // A tool continuation keeps the turn's route and activity; only the context, the model list, or the turn's own tool
366
376
  // calls (observedMove) can move it.
367
- export function continueRoute(config, loop, { nativeModel, contextTokens, contextKnown, availableModels, effort }) {
377
+ export function continueRoute(
378
+ config,
379
+ loop,
380
+ { nativeModel, contextTokens, contextKnown, availableModels, effort, hasImages = false },
381
+ ) {
368
382
  if (!loop.decision) return loop;
369
383
  // A fit to another tier serves this turn only: `loop.route` stays the route of `lastRoute`, as the tier does.
370
384
  let decision = loop.decision;
@@ -387,6 +401,27 @@ export function continueRoute(config, loop, { nativeModel, contextTokens, contex
387
401
  };
388
402
  }
389
403
  }
404
+ if (hasImages && decision.tier && routeSpec(config, runningRoute(config, decision))?.imageInput === false) {
405
+ const runningWindow = routeSpec(config, runningRoute(config, decision)).contextWindow;
406
+ const tier = [...TIERS].reverse().find((t) => {
407
+ const model = routeSpec(config, resolveRoute(config, t, decision.activity));
408
+ return (
409
+ model.imageInput !== false &&
410
+ isModelAllowed(model.id, availableModels, nativeModel) &&
411
+ !loop.ineligible.includes(model.id) &&
412
+ (contextKnown ? contextTokens <= model.contextWindow * CONTEXT_FILL : model.contextWindow >= runningWindow)
413
+ );
414
+ });
415
+ const route = tier ? resolveRoute(config, tier, decision.activity) : null;
416
+ decision = {
417
+ ...decision,
418
+ tier: tier ?? null,
419
+ route,
420
+ model: route ? routeSpec(config, route).id : nativeModel,
421
+ effort: route ? costs.routeEffort(config, route, effort) : effort,
422
+ reason: 'model-unavailable',
423
+ };
424
+ }
390
425
  if (!isModelAllowed(decision.model, availableModels, nativeModel) || loop.ineligible.includes(decision.model)) {
391
426
  decision = {
392
427
  ...decision,
package/lib/savings.mjs CHANGED
@@ -4,6 +4,7 @@
4
4
  // records. The records under SAVINGS_PREFIX are undated history from before those, read and never written.
5
5
 
6
6
  import { effortSharesCache, ratesAt } from './cost.mjs';
7
+ import { canonicalModel } from './providers.mjs';
7
8
  import { afterResetOf, earlierSince, isRecord } from './records.mjs';
8
9
  import { HISTORY_SHRINK, isSameModel } from './route.mjs';
9
10
 
@@ -20,8 +21,9 @@ const TTLS = ['5m', '1h'];
20
21
  // suffix such as `[1m]`. Null when no entry prices it.
21
22
  export function modelSpec(config, id) {
22
23
  if (typeof id !== 'string') return null;
23
- const bare = id.replace(/\[[^\]]*\]$/, '');
24
- const dated = (model) => bare.startsWith(model.id) && /^-\d{8}$/.test(bare.slice(model.id.length));
24
+ const bare = canonicalModel(id);
25
+ const dated = (model) =>
26
+ model.id.startsWith('claude-') && bare.startsWith(model.id) && /^-\d{8}$/.test(bare.slice(model.id.length));
25
27
  return Object.values(config.models).find((model) => isSameModel(model.id, bare) || dated(model)) ?? null;
26
28
  }
27
29
 
@@ -38,11 +40,33 @@ export function modelAlias(config, id) {
38
40
 
39
41
  // One request's list price in USD: `counts` are its uncached input, cache read, cache write and output tokens, the
40
42
  // writes at `writeMultiplier` times input. Long-context rates follow the whole prompt.
41
- export function requestUsd(model, { input, cacheRead, cacheWrite, output }, writeMultiplier) {
43
+ export function requestUsd(model, { input, cacheRead, cacheWrite, output }, writeMultiplier, cacheMode = 'explicit') {
42
44
  const rates = ratesAt(model, input + cacheRead + cacheWrite);
43
- return (
44
- (rates.input * (input + cacheWrite * writeMultiplier) + rates.cacheRead * cacheRead + rates.output * output) / 1e6
45
- );
45
+ const inputUsd =
46
+ cacheMode === 'disabled'
47
+ ? rates.input * (input + cacheRead + cacheWrite)
48
+ : rates.input * (input + cacheWrite * writeMultiplier) + rates.cacheRead * cacheRead;
49
+ return (inputUsd + rates.output * output) / 1e6;
50
+ }
51
+
52
+ // Actual observed counters can be priced without inventing the cache on another route.
53
+ export function observedReplyUsd(config, usage, ttl) {
54
+ const counts = {
55
+ input: usage?.input_tokens,
56
+ cacheRead: usage?.cache_read_input_tokens,
57
+ cacheWrite: usage?.cache_creation_input_tokens,
58
+ output: usage?.output_tokens,
59
+ };
60
+ const model = modelSpec(config, usage?.model);
61
+ const write = config.cache.mode === 'explicit' ? config.cache.writeMultiplier[ttl] : 1;
62
+ if (
63
+ !model ||
64
+ !Number.isFinite(model.output) ||
65
+ !Number.isFinite(write) ||
66
+ !Object.values(counts).every((n) => Number.isFinite(n) && n >= 0)
67
+ )
68
+ return null;
69
+ return requestUsd(model, counts, write, config.cache.mode);
46
70
  }
47
71
 
48
72
  const truthy = (value) => /^(1|true|yes|on)$/i.test(String(value ?? '').trim());
@@ -100,7 +124,7 @@ export function compareReply(config, state, { usage, served, yours, ttl, now })
100
124
  const next = { total, at: now, onYours, ...identity };
101
125
  // A cache simulated for another model or effort of yours is none of this one's: the new one starts cold.
102
126
  const prior = state?.model === identity.model && (sharedEffort || state.effort === identity.effort) ? state : null;
103
- const write = config.cache.writeMultiplier[ttl];
127
+ const write = config.cache.mode === 'explicit' ? config.cache.writeMultiplier[ttl] : 1;
104
128
  if (
105
129
  !servedSpec ||
106
130
  !yoursSpec ||
@@ -109,16 +133,22 @@ export function compareReply(config, state, { usage, served, yours, ttl, now })
109
133
  !Number.isFinite(write)
110
134
  )
111
135
  return { state: next, reply: null };
112
- const routedUsd = requestUsd(servedSpec, counts, write);
136
+ // Implicit caches have no guaranteed TTL or cross-effort hit rate. Only identical observed routes compare exactly.
137
+ if (config.cache.mode === 'automatic' && !(onYours && (prior?.onYours ?? true))) return { state: next, reply: null };
138
+ const routedUsd = requestUsd(servedSpec, counts, write, config.cache.mode);
113
139
  let yoursUsd = routedUsd;
114
140
  let servedOnYoursUsd = routedUsd;
115
141
  if (!(onYours && (prior?.onYours ?? true))) {
116
142
  const warm =
117
- prior && now - prior.at < config.cache.ttlMs[ttl] && total >= prior.total * HISTORY_SHRINK && prior.total > 0;
143
+ config.cache.mode !== 'disabled' &&
144
+ prior &&
145
+ now - prior.at < config.cache.ttlMs[ttl] &&
146
+ total >= prior.total * HISTORY_SHRINK &&
147
+ prior.total > 0;
118
148
  const cacheRead = Math.max(counts.cacheRead, warm ? Math.min(prior.total, total - counts.input) : 0);
119
149
  const single = { ...counts, cacheRead, cacheWrite: total - counts.input - cacheRead };
120
- yoursUsd = requestUsd(yoursSpec, single, write);
121
- servedOnYoursUsd = requestUsd(servedSpec, single, write);
150
+ yoursUsd = requestUsd(yoursSpec, single, write, config.cache.mode);
151
+ servedOnYoursUsd = requestUsd(servedSpec, single, write, config.cache.mode);
122
152
  }
123
153
  const modelUsd = servedOnYoursUsd - yoursUsd;
124
154
  return {
@@ -135,6 +165,24 @@ export function compareReply(config, state, { usage, served, yours, ttl, now })
135
165
  };
136
166
  }
137
167
 
168
+ // Why a routed reply gets no price, by compareReply's checks in its order, or null when it prices it: the usage or its
169
+ // model id is missing or its counts do not read (`usage`; the hook drops a usage without a model before compareReply), the served model or your model has no configured price (`model`), or the cache
170
+ // lifetime is unknown (`ttl`). The usage record keeps priced replies only; this names what it leaves out.
171
+ export function unpricedCause(config, { usage, served, yours, ttl }) {
172
+ const counts = [
173
+ usage?.input_tokens,
174
+ usage?.cache_read_input_tokens,
175
+ usage?.cache_creation_input_tokens,
176
+ usage?.output_tokens,
177
+ ];
178
+ if (!usage?.model || !counts.every(isCount)) return 'usage';
179
+ const [servedSpec, yoursSpec] = [modelSpec(config, served.model), modelSpec(config, yours.model)];
180
+ if (!servedSpec || !yoursSpec || !Number.isFinite(servedSpec.output) || !Number.isFinite(yoursSpec.output))
181
+ return 'model';
182
+ if (config.cache.mode === 'automatic') return 'ttl';
183
+ return config.cache.mode === 'disabled' || Number.isFinite(config.cache.writeMultiplier[ttl]) ? null : 'ttl';
184
+ }
185
+
138
186
  // One main reply against every configured model as yours, at your effort, so the session readout can follow a
139
187
  // `/model` change without replaying the session: `states` and `replies` by models key, each as compareReply returns,
140
188
  // and `reply`, the prices against `yours`, the API model id /model selects now, or null.
package/lib/subagents.mjs CHANGED
@@ -180,15 +180,16 @@ export function addAgentReply(config, agent, usage, ttl) {
180
180
  output: usage?.output_tokens,
181
181
  };
182
182
  const next = { ...agent, requests: agent.requests + 1 };
183
- const write = config.cache.writeMultiplier[ttl];
183
+ const write = config.cache.mode === 'explicit' ? config.cache.writeMultiplier[ttl] : 1;
184
184
  const actual = modelSpec(config, usage?.model);
185
185
  const other = agent.pass ? null : modelSpec(config, agent.coreModel);
186
186
  const priced = (spec) => spec && Number.isFinite(spec.output);
187
187
  if (!Object.values(counts).every(isCount) || !Number.isFinite(write) || !priced(actual)) return next;
188
188
  if (!agent.pass && !priced(other)) return next;
189
+ if (config.cache.mode === 'automatic' && other && actual !== other) return next;
189
190
  next.pricedRequests += 1;
190
- next.actualUsd += requestUsd(actual, counts, write);
191
- if (other) next.otherUsd += requestUsd(other, counts, write);
191
+ next.actualUsd += requestUsd(actual, counts, write, config.cache.mode);
192
+ if (other) next.otherUsd += requestUsd(other, counts, write, config.cache.mode);
192
193
  return next;
193
194
  }
194
195
 
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@alexeiled/claude-router",
3
- "version": "1.15.0",
4
- "description": "Native Claude Code Mod: model and effort routing for the main conversation, advised by Jev, Clef, Clef Flash, Clef Omni, OpenAI or Ollama.",
3
+ "version": "1.17.0",
4
+ "description": "Native Claude Code model and effort routing with Anthropic, DeepSeek and z.ai defaults, custom provider profiles, and classifier advice.",
5
5
  "license": "MIT",
6
6
  "author": "Alexei Ledenev",
7
7
  "repository": {
@@ -34,6 +34,7 @@
34
34
  "typecheck": "tools/node_modules/.bin/tsc -p tsconfig.json",
35
35
  "validate": "claude plugin validate .claude-plugin/plugin.json && claude plugin validate .claude-plugin/marketplace.json",
36
36
  "test:plugin": "bash scripts/plugin-test.sh",
37
+ "test:providers": "node experiments/mod-router/scripts/provider-acceptance.mjs",
37
38
  "format": "tools/node_modules/.bin/biome format --write .",
38
39
  "docs:images": "node scripts/render-doc-images.mjs",
39
40
  "docs:modes": "node scripts/mode-matrix.mjs",