auto-model-router 0.2.28 → 0.2.30

package/CLAUDE.md

@@ -119,8 +119,9 @@ read/write client is `src/context/agentdox.ts` (assemble / createSession / appen
 Beyond consuming agentdox as an agent, `src/context/` is the **router↔agentdox bridge**: it
 injects shared project context into every routed turn and records turns back, attributed to
 the model that served them. See `docs/AGENTDOX-BRIDGE.md` for the current state, how to run
-it, and the open issue. Design rationale lives in
-`E:/projects/agentdox/docs/architecture/router-context-bridge.md`.
+it, and the open issue. Design rationale is the **decision log in the agentdox project brief**
+for scope `omp-router` (read it with `context_brief`) — the bridge decisions and the evidence
+behind them are recorded there as they are made.
 
 Turning the bridge on for the router itself (distinct from the MCP wiring above):
 

package/README.md

@@ -677,7 +677,7 @@ has none of the project knowledge the last one built up. Because every harness
 routes through this one provider, the router is the single place that can fix
 that for all of them at once.
 
-Point it at an [agentdox](https://github.com/…/agentdox) server and every turn —
+Point it at an [agentdox](https://github.com/drewappling/agentdox) server and every turn —
 whatever model wins the routing decision — carries the same project memory, docs,
 and brief:
 
@@ -744,8 +744,9 @@ not a dependency. If it is unreachable the turn routes and dispatches normally,
 and a pinned block keeps being served.
 
 `GET /health` reports the bridge's URL, default scope, and `recordTurns` — never
-the token. Design notes: `docs/architecture/router-context-bridge.md` in the
-agentdox repo. Live check: `bun tools/agentdox-e2e.ts`.
+the token. Design notes: [`docs/AGENTDOX-BRIDGE.md`](docs/AGENTDOX-BRIDGE.md).
+Server side: the [agentdox repo](https://github.com/drewappling/agentdox).
+Live check: `bun tools/agentdox-e2e.ts`.
 
 ---
 

package/docs/AGENTDOX-BRIDGE.md

@@ -1,10 +1,11 @@
 # agentdox bridge — handoff
 
-**Status:** implemented, typechecks clean, 439 tests pass, injection verified end-to-end
+**Status:** implemented, typechecks clean, 502 tests pass, injection verified end-to-end
 through omp. The write-back faults in §5 and §6 are **fixed**; `context.recordTurns` is on.
 
-Design rationale (why it is built this way):
-`E:/projects/agentdox/docs/architecture/router-context-bridge.md`.
+Design rationale (why it is built this way) is the decision log in the agentdox project
+brief for scope `omp-router` — read it with `context_brief`. The agentdox server itself:
+[github.com/drewappling/agentdox](https://github.com/drewappling/agentdox).
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auto-model-router",
-  "version": "0.2.28",
+  "version": "0.2.30",
   "private": false,
   "description": "Local cost/complexity-aware model router for Oh My Pi, backed by OpenRouter",
   "type": "module",

package/src/config/defaults.ts

@@ -98,6 +98,10 @@ export const DEFAULT_CONFIG: RouterConfig = {
 		toolAxis: "coding",
 		chatAxis: "intelligence",
 		agenticLoopDepth: 3,
+		// Shipped values, unchanged. See ClassifierConfig.reasoningWeights: a
+		// harness that pins the level for a whole session turns these into a
+		// constant tier offset, in which case `medium` belongs near 0.
+		reasoningWeights: { medium: 0.14, high: 0.24, xhigh: 0.3, max: 0.34 },
 	},
 	escalation: {
 		enabled: true,
@@ -131,6 +135,9 @@ export const DEFAULT_CONFIG: RouterConfig = {
 		// OpenRouter sticky sessions expire in 5-10 minutes.
 		cacheWarmTtlMs: 300_000,
 		maxDowngradePerTurn: 1,
+		// Off: breaking a hold means a model switch, which costs a cache write.
+		// Enable where the held tier is expensive; see HysteresisConfig.
+		breakHoldOnMechanical: false,
 	},
 	exploration: {
 		// Opt-in. Exploration knowingly routes some turns below the tier that

package/src/config/schema.ts

@@ -85,6 +85,14 @@ const classifier = z.strictObject({
 	toolAxis: qualityAxis.optional(),
 	chatAxis: qualityAxis.optional(),
 	agenticLoopDepth: z.number().int().nonnegative().optional(),
+	reasoningWeights: z
+		.strictObject({
+			medium: z.number().nonnegative().optional(),
+			high: z.number().nonnegative().optional(),
+			xhigh: z.number().nonnegative().optional(),
+			max: z.number().nonnegative().optional(),
+		})
+		.optional(),
 });
 
 const escalation = z.strictObject({
@@ -103,6 +111,7 @@ const hysteresis = z.strictObject({
 	switchMargin: z.number().positive().optional(),
 	cacheWarmTtlMs: z.number().nonnegative().optional(),
 	maxDowngradePerTurn: z.number().int().nonnegative().optional(),
+	breakHoldOnMechanical: z.boolean().optional(),
 });
 
 const exploration = z.strictObject({

package/src/config/types.ts

@@ -229,6 +229,28 @@ export interface ClassifierConfig {
 	chatAxis: QualityAxis;
 	/** Tool-loop depth above which the agentic axis takes over. */
 	agenticLoopDepth: number;
+	/**
+	 * Score added when the CLIENT asks for a reasoning effort, per level. The
+	 * premise is that asking for reasoning states expected difficulty directly.
+	 *
+	 * That premise fails when a harness sets the level once for a whole session:
+	 * a constant cannot discriminate difficulty between turns, but it still
+	 * shifts every turn's score. Measured on a live day: the requested level
+	 * never changed within 111 of 115 conversations, `medium` (+0.14, over half
+	 * of a 0.25-wide tier band) rode on 41.6% of dispatches, and 64 of 119
+	 * `hard` dispatches reached that tier ONLY because of it — $6.66 billed
+	 * against $0.16 for the same tokens on the moderate pick.
+	 *
+	 * Tune per deployment: a harness that raises the level deliberately for hard
+	 * turns wants these weights, one that pins it session-wide wants `medium`
+	 * near zero. Defaults preserve the shipped behaviour.
+	 */
+	reasoningWeights: {
+		medium: number;
+		high: number;
+		xhigh: number;
+		max: number;
+	};
 }
 
 export interface EscalationConfig {
@@ -265,6 +287,25 @@ export interface HysteresisConfig {
 	cacheWarmTtlMs: number;
 	/** Downgrade at most this many tiers per turn, so quality never falls off a cliff. */
 	maxDowngradePerTurn: number;
+	/**
+	 * Let a mechanical tool-result continuation escape a hold that sits above its
+	 * own classification.
+	 *
+	 * A hold bets that the next turn resembles the one that armed it, and it is
+	 * usually right — flapping cold-starts prompt caches. But a continuation the
+	 * classifier has already docked for being a mechanical next step, and whose
+	 * score lands below the held tier, is evidence against that bet. Measured on
+	 * 24h of live traffic: 37 of 44 sticky `hard` dispatches were exactly that,
+	 * one scoring 0.154 (trivial) yet served by claude-opus-5 — $2.66 billed
+	 * against $0.05 for the identical tokens on the moderate pick.
+	 *
+	 * Off by default: breaking a hold means a model switch, and switching costs a
+	 * cache write. Worth it when the held tier is expensive, not obviously worth
+	 * it when the tiers are close, so it is opt-in per deployment.
+	 * `maxDowngradePerTurn` still applies, so quality steps down rather than
+	 * falling off a cliff.
+	 */
+	breakHoldOnMechanical: boolean;
 }
 
 /**

package/src/router/classify.ts

@@ -76,17 +76,24 @@ const W_TOOLS_OFFERED = 0.03;
 /** Score bucket boundaries: [trivial, simple, moderate, hard]. */
 const BOUNDARIES: readonly [number, number, number] = [0.25, 0.5, 0.75];
 
-/** A client that asks for reasoning is stating expected difficulty directly. */
-function reasoningWeight(level: ReasoningLevel | undefined): number {
+/**
+ * Score for a client-stated reasoning effort. The premise is that asking for
+ * reasoning states expected difficulty — true when a harness raises the level
+ * for a hard turn, false when it pins one level for the whole session, where the
+ * "signal" is a constant that lifts every turn's score. Weights are therefore
+ * configurable per deployment; see ClassifierConfig.reasoningWeights.
+ */
+function reasoningWeight(level: ReasoningLevel | undefined, cfg: RouterConfig): number {
+	const w = cfg.classifier.reasoningWeights;
 	switch (level) {
 		case "medium":
-			return 0.14;
+			return w.medium;
 		case "high":
-			return 0.24;
+			return w.high;
 		case "xhigh":
-			return 0.3;
+			return w.xhigh;
 		case "max":
-			return 0.34;
+			return w.max;
 		default:
 			// off/minimal/low/undefined: no stated difficulty above the baseline.
 			return 0;
@@ -113,7 +120,7 @@ export function scoreHeuristic(f: Features, cfg: RouterConfig): Classification {
 	);
 	if (f.lastToolFailed) add(W_TOOL_FAILED, "last tool result failed");
 	if (f.circularToolCall) add(W_CIRCULAR_LOOP, "circular tool call (re-issued a prior call; stuck)");
-	const rw = reasoningWeight(f.requestedReasoning);
+	const rw = reasoningWeight(f.requestedReasoning, cfg);
 	if (rw > 0) add(rw, `client requested reasoning=${f.requestedReasoning ?? ""}`);
 	if (f.isTerseInstruction) add(W_TERSE, "terse instruction");
 	add(Math.min(f.codeBlocks * W_CODE_BLOCK, CAP_CODE), `${f.codeBlocks} code block(s) in new content`);

package/src/router/select.ts

@@ -117,10 +117,23 @@ export function select(args: SelectArgs): Decision {
 
 	// 2. Hysteresis: while the sticky window is open, never route below the
 	//    held tier — per-turn flapping would repeatedly cold-start prompt caches.
+	//
+	//    Exception, when `breakHoldOnMechanical` is on: a hold is a bet that the
+	//    NEXT turn resembles the one that armed it. A tool-result continuation
+	//    whose own score lands below the held tier is direct evidence against
+	//    that bet — the classifier already docks it for being a mechanical next
+	//    step — so paying the held tier for it buys nothing. Measured on 24h of
+	//    live traffic: 37 of 44 sticky `hard` dispatches were exactly this shape,
+	//    one scoring 0.154 (trivial) yet served by claude-opus-5; $2.66 billed
+	//    against $0.05 for the identical tokens on the moderate pick.
 	let cls = classification;
+	const mechanicalOverride =
+		cfg.hysteresis.breakHoldOnMechanical && features.isToolResultContinuation && tierIdx(effective) < tierIdx(clampTier(state.currentTier ?? effective));
 	if (state.stickyUntilTurn > state.turn && state.currentTier !== null && tierIdx(state.currentTier) >= tierIdx(effective)) {
 		const held = clampTier(state.currentTier);
-		if (held !== effective) {
+		if (mechanicalOverride) {
+			reasons.push(`hysteresis hold ${held} broken: mechanical tool-result continuation classified ${effective}`);
+		} else if (held !== effective) {
 			reasons.push(`hysteresis: holding ${held} until turn ${state.stickyUntilTurn} (classified ${effective})`);
 			cls = {
 				...classification,

package/test/classify.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from "bun:test";
 
+import { DEFAULT_CONFIG } from "../src/config/defaults.ts";
 import { loadConfig } from "../src/config/load.ts";
 import type { RouterConfig } from "../src/config/types.ts";
 import { classify, classifyTask, pickQualityAxis, scoreHeuristic } from "../src/router/classify.ts";
@@ -178,6 +179,35 @@ describe("scoreHeuristic", () => {
 		expect(thinking.score).toBeGreaterThan(plain.score);
 	});
 
+	test("the reasoning weight is configurable, so a session-wide level can be discounted", () => {
+		// A harness that pins one reasoning level for a whole session turns this
+		// "signal" into a constant that lifts every turn's score. Measured live:
+		// the level never changed within 111 of 115 conversations, and 64 of 119
+		// hard dispatches reached that tier ONLY via the weight — $6.66 billed
+		// against $0.16 for the same tokens on the moderate pick.
+		//
+		// DEFAULT_CONFIG, not BASE: BASE is loadConfig({}), which reads this
+		// machine's real config.yml, and this assertion is about shipped values.
+		const features = extractFeatures(
+			parseChatRequest(
+				{ model: "auto", tools: TOOLS, reasoning_effort: "medium", messages: [SYSTEM, { role: "user", content: "tidy this up" }] },
+				new Headers(),
+			),
+			5000,
+		);
+		const shipped = scoreHeuristic(features, DEFAULT_CONFIG);
+		const discounted = scoreHeuristic(features, {
+			...DEFAULT_CONFIG,
+			classifier: { ...DEFAULT_CONFIG.classifier, reasoningWeights: { ...DEFAULT_CONFIG.classifier.reasoningWeights, medium: 0 } },
+		});
+		expect(shipped.score - discounted.score).toBeCloseTo(DEFAULT_CONFIG.classifier.reasoningWeights.medium, 5);
+		expect(discounted.reasons.some((r) => /requested reasoning/.test(r))).toBe(false);
+	});
+
+	test("ships with the historical weights, so enabling a discount is opt-in", () => {
+		expect(DEFAULT_CONFIG.classifier.reasoningWeights).toEqual({ medium: 0.14, high: 0.24, xhigh: 0.3, max: 0.34 });
+	});
+
 	test("always produces a bounded score, a real tier, and its reasoning", () => {
 		const c = scoreHeuristic(featuresFor([SYSTEM, { role: "user", content: "hello" }]), BASE);
 		expect(c.score).toBeGreaterThanOrEqual(0);

package/test/failover.test.ts

@@ -55,6 +55,7 @@ function mkConfig(escalation: Partial<EscalationConfig> = {}): RouterConfig {
 			toolAxis: "coding",
 			chatAxis: "intelligence",
 			agenticLoopDepth: 3,
+			reasoningWeights: { medium: 0.14, high: 0.24, xhigh: 0.3, max: 0.34 },
 		},
 		escalation: {
 			enabled: true,
@@ -66,7 +67,7 @@ function mkConfig(escalation: Partial<EscalationConfig> = {}): RouterConfig {
 			escalateOnLengthStop: false,
 			...escalation,
 		},
-		hysteresis: { holdTurns: 2, holdTurnsAfterEscalation: 4, switchMargin: 1.5, cacheWarmTtlMs: 600_000, maxDowngradePerTurn: 1 },
+		hysteresis: { holdTurns: 2, holdTurnsAfterEscalation: 4, switchMargin: 1.5, cacheWarmTtlMs: 600_000, maxDowngradePerTurn: 1, breakHoldOnMechanical: false },
 		exploration: { enabled: false, rates: {}, stickyPolicy: "never", holdTurns: { enabled: false, values: [2, 3, 4] } },
 		cache: { injectBreakpoints: true, maxBreakpoints: 4, minPromptTokens: 1024, milestoneTokens: 20_000 },
 		context: { enabled: false, baseUrl: "", token: "", defaultScope: "", timeoutMs: 3_000, maxStalenessMs: 900_000, maxBlockChars: 24_000, memoryLimit: 8, docsLimit: 2, sessionLimit: 6, briefChars: 0, recordTurns: false, maxQueue: 64 },

package/test/select.test.ts

@@ -743,3 +743,81 @@ describe("context compaction", () => {
 		expect(tight.promptTokensSaved).toBeGreaterThan(loose.promptTokensSaved);
 	});
 });
+
+describe("hysteresis.breakHoldOnMechanical", () => {
+	// A hold bets the next turn resembles the one that armed it. A tool-result
+	// continuation the classifier has already docked, scoring below the held
+	// tier, is evidence against that bet. Measured on 24h of live traffic: 37 of
+	// 44 sticky `hard` dispatches were exactly that shape — one scoring 0.154
+	// (trivial) yet served by claude-opus-5 — $2.66 billed against $0.05 for the
+	// same tokens on the moderate pick.
+	function continuation(): NormRequest {
+		return parseChatRequest(
+			{
+				model: "auto",
+				tools: TOOLS,
+				messages: [
+					{ role: "system", content: "You are a coding agent." },
+					{ role: "user", content: "read the file" },
+					{ role: "assistant", content: null, tool_calls: [{ id: "c1", type: "function", function: { name: "read", arguments: '{"path":"a.ts"}' } }] },
+					{ role: "tool", tool_call_id: "c1", content: "export const x = 1;" },
+				],
+			},
+			new Headers(),
+		);
+	}
+
+	const held = state({ currentTier: "hard", currentSlug: "x-ai/grok-4.6", stickyUntilTurn: 9, turn: 1 });
+
+	function decide(req: NormRequest, breakHold: boolean) {
+		const cfg: RouterConfig = { ...BASE, hysteresis: { ...BASE.hysteresis, breakHoldOnMechanical: breakHold } };
+		const features = extractFeatures(req, 4_000);
+		return { d: select({ req, features, classification: scoreHeuristic(features, cfg), profile: PROFILE, state: held, snapshot: SNAPSHOT, ledger: null, cfg, nowMs: Date.now() }), features };
+	}
+
+	test("off by default, so a hold still pins the tier", () => {
+		expect(BASE.hysteresis.breakHoldOnMechanical).toBe(false);
+		const { d, features } = decide(continuation(), false);
+		expect(features.isToolResultContinuation).toBe(true);
+		expect(d.tier).toBe("hard");
+		expect(d.classification.source).toBe("sticky");
+	});
+
+	test("on, a mechanical continuation escapes the hold", () => {
+		const { d } = decide(continuation(), true);
+		expect(d.tier).not.toBe("hard");
+		expect(d.classification.source).not.toBe("sticky");
+		expect(d.reasons.some((r) => /hold hard broken/.test(r))).toBe(true);
+	});
+
+	test("a NON-mechanical turn still gets the hold, so flap protection survives", () => {
+		// This is the case hysteresis exists for: fresh user work mid-conversation
+		// must not bounce the model and cold-start its cache.
+		const { d, features } = decide(request("now refactor the retry helper"), true);
+		expect(features.isToolResultContinuation).toBe(false);
+		expect(d.tier).toBe("hard");
+		expect(d.classification.source).toBe("sticky");
+	});
+
+	test("the downgrade clamp still applies, so quality steps rather than falls", () => {
+		const cfg: RouterConfig = {
+			...BASE,
+			hysteresis: { ...BASE.hysteresis, breakHoldOnMechanical: true, maxDowngradePerTurn: 1 },
+		};
+		const req = continuation();
+		const features = extractFeatures(req, 4_000);
+		// Force the fresh classification far below the hold to exercise the clamp.
+		const d = select({
+			req,
+			features,
+			classification: { ...scoreHeuristic(features, cfg), tier: "trivial" },
+			profile: PROFILE,
+			state: held,
+			snapshot: SNAPSHOT,
+			ledger: null,
+			cfg,
+			nowMs: Date.now(),
+		});
+		expect(d.tier).toBe("moderate");
+	});
+});

package/test/turn.test.ts

@@ -56,6 +56,7 @@ function mkConfig(escalation: Partial<EscalationConfig> = {}): RouterConfig {
 			toolAxis: "coding",
 			chatAxis: "intelligence",
 			agenticLoopDepth: 3,
+			reasoningWeights: { medium: 0.14, high: 0.24, xhigh: 0.3, max: 0.34 },
 		},
 		escalation: {
 			enabled: true,
@@ -67,7 +68,7 @@ function mkConfig(escalation: Partial<EscalationConfig> = {}): RouterConfig {
 			escalateOnLengthStop: false,
 			...escalation,
 		},
-		hysteresis: { holdTurns: 2, holdTurnsAfterEscalation: 4, switchMargin: 1.5, cacheWarmTtlMs: 600_000, maxDowngradePerTurn: 1 },
+		hysteresis: { holdTurns: 2, holdTurnsAfterEscalation: 4, switchMargin: 1.5, cacheWarmTtlMs: 600_000, maxDowngradePerTurn: 1, breakHoldOnMechanical: false },
 		exploration: { enabled: false, rates: {}, stickyPolicy: "never", holdTurns: { enabled: false, values: [2, 3, 4] } },
 		cache: { injectBreakpoints: true, maxBreakpoints: 4, minPromptTokens: 1024, milestoneTokens: 20_000 },
 		context: { enabled: false, baseUrl: "", token: "", defaultScope: "", timeoutMs: 3_000, maxStalenessMs: 900_000, maxBlockChars: 24_000, memoryLimit: 8, docsLimit: 2, sessionLimit: 6, briefChars: 0, recordTurns: false, maxQueue: 64 },

package/tools/replay.ts

@@ -37,8 +37,10 @@
  *    size (`usage.promptTokens`), i.e. the prompt selection actually saw.
  *  - `stickyUntilTurn` was never persisted per turn, so the hysteresis hold
  *    window is absent. This is the main residual gap.
- *  - `requestedReasoning` is the one `Features` field the ledger omits; it
- *    replays as undefined.
+ *  - `requestedReasoning` IS recorded and is now used. It was previously forced
+ *    to undefined here on the belief the ledger omitted it, which under-scored
+ *    ~42% of dispatches and reproduced 27 hard decisions against 120 served.
+ *    Treat replay numbers produced before that fix as biased toward cheap tiers.
  *  - Module constants are not config, so things like CAP_AUTONOMOUS_LOOP cannot
  *    be A/B'd via `--set` — only `RouterConfig` paths can.
  *
@@ -140,10 +142,20 @@ interface Row {
 	created_at_ms: number;
 }
 
-/** Rebuilds the classifier input. The ledger stores 20 of 21 Features fields. */
+/**
+ * Rebuilds the classifier input from the recorded blob.
+ *
+ * `requestedReasoning` IS recorded (JSON.stringify only drops it when the client
+ * sent no level), and it must be used: it is worth up to +0.34 of score, rides
+ * on ~42% of dispatches, and forcing it to undefined — as this did, on the
+ * assumption the ledger omitted it — under-scored every one of those rows.
+ * Measured effect of the bug: replay reproduced 27 hard-tier decisions against
+ * 120 actually served, i.e. it silently biased every comparison toward cheaper
+ * tiers and made reasoning-weight changes look like no-ops.
+ */
 function featuresOf(row: Row, promptTokens: number): Features {
 	const f = JSON.parse(row.features) as Partial<Features>;
-	return { ...(f as Features), promptTokens, requestedReasoning: undefined };
+	return { ...(f as Features), promptTokens };
 }
 
 /**