auto-model-router 0.2.29 → 0.2.30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auto-model-router",
-  "version": "0.2.29",
+  "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

@@ -135,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

@@ -111,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

@@ -287,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/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/failover.test.ts

@@ -67,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

@@ -68,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 },