auto-model-router 0.2.2 → 0.2.7

package/src/router/types.ts

@@ -7,7 +7,7 @@
 
 import type { CatalogModel } from "../catalog/types.ts";
 import type { CostForecast } from "../cost/types.ts";
-import type { NormRequest, ReasoningLevel } from "../wire/types.ts";
+import type { CompactionEdit, NormRequest, ReasoningLevel } from "../wire/types.ts";
 
 export type Tier = "trivial" | "simple" | "moderate" | "hard";
 
@@ -53,7 +53,27 @@ export interface Features {
 	lastToolFailed: boolean;
 	/** The same tool was called with identical arguments twice in a row. */
 	repeatedToolCall: boolean;
+	/**
+	 * A byte-identical tool call (same name AND args) was re-issued within the
+	 * last few assistant calls, adjacent or not — the agent is going in circles.
+	 * Generalizes `repeatedToolCall`; the classifier scores THIS, so a stuck
+	 * loop escalates even when the repeat is not back-to-back.
+	 */
+	circularToolCall: boolean;
+	/**
+	 * An image appears ANYWHERE in the conversation. Drives the model-capability
+	 * filter: the payload still carries that image every turn, so a served model
+	 * must accept image input even long after the image was introduced.
+	 */
 	hasImages: boolean;
+	/**
+	 * An image appears in the VOLATILE TAIL — the newest user-authored run. This
+	 * is what makes a turn genuinely visual WORK, as opposed to a mechanical
+	 * tool-loop continuation that merely carries a stale screenshot in context.
+	 * Task classification keys on this so an agentic coding loop is scored on the
+	 * coding axis, not pinned to the vision (intelligence) axis by an old image.
+	 */
+	hasNewImage: boolean;
 	/** Fenced code blocks in the newest user content. */
 	codeBlocks: number;
 	/** Bytes inside fenced code blocks in the newest user content. */
@@ -144,6 +164,14 @@ export interface ConversationState {
 	cacheWarmSlug: string | null;
 	/** When that cache was last touched; OpenRouter sticky sessions expire in 5-10 min. */
 	cacheWarmAtMs: number;
+	/**
+	 * agentdox context block pinned to this conversation. Held stable across
+	 * turns so the injected system prefix stays byte-identical and the prompt
+	 * cache survives; refreshed only when the cache is already cold.
+	 */
+	contextVersion: string | null;
+	/** When that block was fetched, for the staleness TTL. */
+	contextFetchedAtMs: number;
 	updatedAtMs: number;
 }
 
@@ -193,6 +221,10 @@ export interface Decision {
 	sticky: boolean;
 	/** Message indices to mark with cache breakpoints. */
 	cacheBreakpointMessageIndices: number[];
+	/** In-place tool-result shrink edits to apply before dispatch. Empty ⇒ none. */
+	compactionPlan: CompactionEdit[];
+	/** Estimated prompt tokens removed by `compactionPlan`, for the ledger. */
+	promptTokensSaved: number;
 	reasoning: ReasoningLevel | undefined;
 	maxTokens: number | undefined;
 	stripAssistantReasoning: boolean;

package/src/server/http.ts

@@ -2,6 +2,7 @@ import { mkdirSync } from "node:fs";
 import { dirname } from "node:path";
 import type { Server } from "bun";
 import { createCatalog } from "../catalog/openrouter-catalog.ts";
+import { createBridgeFromConfig } from "../context/index.ts";
 import { createLedger } from "../cost/ledger.ts";
 import type { Ledger, ModelTrust } from "../cost/types.ts";
 import { createRouter } from "../router/index.ts";
@@ -173,7 +174,16 @@ export function startServer(cfg: RouterConfig): StartedServer {
 	const catalog = createCatalog(cfg, upstream, db);
 	const conversations = createConversationStore(db);
 	const router = createRouter({ config: cfg, catalog, ledger, conversations, upstream });
-	const turnDeps = { config: cfg, router, upstream, ledger, conversations, catalog };
+	const context = createBridgeFromConfig(cfg, db);
+	const turnDeps = { config: cfg, router, upstream, ledger, conversations, catalog, context };
+
+	if (context.enabled) {
+		log.info("agentdox context bridge enabled", {
+			url: cfg.context.baseUrl,
+			defaultScope: cfg.context.defaultScope === "" ? "(per-request header only)" : cfg.context.defaultScope,
+			recordTurns: cfg.context.recordTurns,
+		});
+	}
 
 	if (cfg.openrouter.apiKey === "") {
 		log.warn("OPENROUTER_API_KEY is not set; /v1/chat/completions will fail at dispatch time");
@@ -313,6 +323,10 @@ export function startServer(cfg: RouterConfig): StartedServer {
 						apiKeyConfigured: cfg.openrouter.apiKey !== "",
 						// Provenance only; never the key itself.
 						apiKeySource: apiKeySource(cfg).source,
+						// Provenance only; never the agentdox token itself.
+						agentdox: context.enabled
+							? { url: cfg.context.baseUrl, defaultScope: cfg.context.defaultScope, recordTurns: cfg.context.recordTurns }
+							: null,
 						catalog: snap === null
 							? null
 							: {
@@ -337,6 +351,9 @@ export function startServer(cfg: RouterConfig): StartedServer {
 			clearInterval(pruneTimer);
 			clearInterval(catalogRefreshTimer);
 			await server.stop(true);
+			// Drain queued agentdox write-backs before the DB closes under them.
+			context.close();
+			await context.flush();
 			db.close();
 		},
 	};

package/src/server/turn.ts

@@ -9,6 +9,7 @@
  */
 
 import type { CatalogSource } from "../catalog/types.ts";
+import type { ContextBridge } from "../context/types.ts";
 import type { RouterConfig } from "../config/types.ts";
 import { EMPTY_USAGE, type Ledger, type UsageCounts } from "../cost/types.ts";
 import { createProbe, type Probe } from "../router/escalate.ts";
@@ -42,6 +43,8 @@ export interface TurnDeps {
 	ledger: Ledger;
 	conversations: ConversationStore;
 	catalog: CatalogSource;
+	/** agentdox bridge. The disabled bridge makes every call here a no-op. */
+	context: ContextBridge;
 }
 
 /** A dead client connection surfaces as the sink throwing mid-stream. */
@@ -52,16 +55,39 @@ class SinkError extends Error {
 	}
 }
 
+/** Latest user text, used to bias agentdox relevance ranking and as the recorded turn. */
+function lastUserText(req: NormRequest): string {
+	for (let i = req.messages.length - 1; i >= 0; i--) {
+		const m = req.messages[i];
+		if (m !== undefined && m.role === "user") return m.text;
+	}
+	return "";
+}
+
+/** Session title: the conversation's opening ask, truncated. */
+function sessionTitle(req: NormRequest): string {
+	for (const m of req.messages) {
+		if (m.role === "user" && m.text.trim() !== "") {
+			const t = m.text.trim().replace(/\s+/g, " ");
+			return t.length > 80 ? `${t.slice(0, 79)}…` : t;
+		}
+	}
+	return `omp ${req.conversationKey.slice(0, 8)}`;
+}
+
 export async function runTurn(
 	req: NormRequest,
 	sink: ResponseSink,
 	deps: TurnDeps,
 	signal: AbortSignal,
 ): Promise<void> {
-	const { config, router, upstream, ledger, conversations } = deps;
+	const { config, router, upstream, ledger, conversations, context: bridge } = deps;
 	const log = createLogger(config.logLevel);
 	const state = conversations.load(req.conversationKey);
 	const turnNumber = state.turn + 1;
+	// Request header wins; the configured default covers harnesses that send none.
+	const doxScope = req.agentdoxScope !== "" ? req.agentdoxScope : config.context.defaultScope;
+	const doxActive = bridge.enabled && doxScope !== "";
 
 	// The trigger list is the source of truth for enabled signals, except
 	// length_stop, which rides on its own toggle (escalation.escalateOnLengthStop).
@@ -101,6 +127,37 @@ export async function runTurn(
 			}
 		}
 
+		// Resolve the shared context block. The bridge refreshes only when this
+		// turn's prefix is already cold — a model switch or a retry — so the
+		// injected bytes stay identical while the cache is worth keeping.
+		let contextBlock: string | undefined;
+		if (doxActive) {
+			const pin = await bridge.resolve({
+				scope: doxScope,
+				conversationKey: req.conversationKey,
+				pinnedVersion: state.contextVersion,
+				pinnedFetchedAtMs: state.contextFetchedAtMs,
+				modelSwitching: state.currentSlug !== null && state.currentSlug !== decision.slug,
+				retrying: attempt > 0,
+				query: lastUserText(req),
+			});
+			if (pin !== null) {
+				contextBlock = pin.block;
+				// Pin immediately, even if this attempt later fails: the block was
+				// dispatched, so the next turn must re-send the same bytes to hit
+				// whatever cache this attempt warmed.
+				state.contextVersion = pin.version;
+				state.contextFetchedAtMs = pin.fetchedAtMs;
+			}
+		}
+
+		log.debug("agentdox context", {
+			active: doxActive,
+			scope: doxScope === "" ? "(none)" : doxScope,
+			injected: contextBlock !== undefined,
+			chars: contextBlock?.length ?? 0,
+		});
+
 		const body = req.renderUpstreamBody({
 			slug: decision.slug,
 			fallbacks: decision.fallbacks,
@@ -109,6 +166,8 @@ export async function runTurn(
 			reasoning: decision.reasoning,
 			maxTokens: decision.maxTokens,
 			stripAssistantReasoning: decision.stripAssistantReasoning,
+			...(contextBlock === undefined ? {} : { contextBlock }),
+			...(decision.compactionPlan.length > 0 ? { compactionPlan: decision.compactionPlan } : {}),
 		});
 
 		// Our own abort composes with the client's: escalation teardown and
@@ -121,6 +180,9 @@ export async function runTurn(
 		let servedSlug: string | null = null;
 		let finishReason: string | null = null;
 		let ttftMs: number | null = null;
+		// Accumulated only when the bridge is live; the transcript write-back is
+		// the sole consumer, and a dead bridge must cost nothing on the hot path.
+		let assistantText = "";
 		let committed = false;
 		let dispatch: Dispatch | null = null;
 		let probe: Probe | null = null;
@@ -166,6 +228,7 @@ export async function runTurn(
 				wasted: fields.wasted,
 				upstreamGenerationId: generationId,
 				error: fields.error,
+				promptTokensSaved: decision.promptTokensSaved,
 			});
 		};
 
@@ -262,6 +325,9 @@ export async function runTurn(
 								if (ev.generationId !== null) generationId = ev.generationId;
 								break;
 							case "text":
+								if (ttftMs === null) ttftMs = Date.now() - startedAt;
+								if (doxActive) assistantText += ev.delta;
+								break;
 							case "reasoning":
 								if (ttftMs === null) ttftMs = Date.now() - startedAt;
 								break;
@@ -380,6 +446,27 @@ export async function runTurn(
 		state.updatedAtMs = Date.now();
 		conversations.save(state);
 
+		// Record the settled turn into agentdox, attributed to the model that
+		// actually served it. Queued and never awaited: the transcript is an
+		// artifact of the turn, not a precondition for finishing it.
+		if (doxActive) {
+			log.debug("agentdox record turn", {
+				userChars: lastUserText(req).length,
+				assistantChars: assistantText.length,
+				messages: req.messages.length,
+				roles: req.messages.map((m) => m.role).join(","),
+			});
+			bridge.recordTurn({
+				scope: doxScope,
+				conversationKey: req.conversationKey,
+				title: sessionTitle(req),
+				userText: lastUserText(req),
+				assistantText,
+				slug: servedSlug ?? decision.slug,
+				tier: decision.tier,
+			});
+		}
+
 		const summary: TurnSummary = {
 			servedSlug: servedSlug ?? decision.slug,
 			tier: decision.tier,

package/src/upstream/openrouter.ts

@@ -34,9 +34,16 @@ function classifyStatus(status: number, body: unknown): UpstreamError {
 	const message = typeof msg === "string" && msg !== "" ? msg : `OpenRouter HTTP ${status}`;
 	const fail = (kind: UpstreamErrorKind, retryable: boolean): UpstreamError =>
 		new UpstreamError(kind, status, message, retryable, body);
-	if (status === 401 || status === 403) return fail("auth", false);
+	// 401 = missing/invalid key. Key-wide, so every model fails identically;
+	// retrying is pointless.
+	if (status === 401) return fail("auth", false);
 	// 402 = out of credits; retrying changes nothing, only topping up does.
 	if (status === 402) return fail("auth", false);
+	// 403 = provider content-moderation or per-model policy gate (prompt-injection
+	// block, age/data-policy confirmation). This indicts the model/provider, NOT
+	// the key: siblings routinely serve the same content. Retryable so the turn
+	// fails over to a different model instead of dying on the client.
+	if (status === 403) return fail("moderation", true);
 	if (status === 429) return fail("rate_limit", true);
 	if (status === 400) {
 		return CONTEXT_LENGTH_RE.test(message) ? fail("context_length", false) : fail("invalid_request", false);

package/src/util/sqlite.ts

@@ -18,7 +18,7 @@ import { mkdirSync } from "node:fs";
 import { dirname } from "node:path";
 
 /** Bump when a migration is added; guarded below so reopening never regresses it. */
-const USER_VERSION = 10;
+const USER_VERSION = 12;
 
 const MIGRATIONS = `
 CREATE TABLE IF NOT EXISTS catalog_cache (
@@ -94,6 +94,23 @@ CREATE TABLE IF NOT EXISTS conversations (
   updated_at_ms INTEGER NOT NULL DEFAULT 0
 );
 
+-- agentdox bridge. Blocks are content-addressed so many conversations on one
+-- project share a single copy, and so a restart can re-inject the SAME bytes a
+-- conversation was already using (OpenRouter's prompt cache outlives us).
+CREATE TABLE IF NOT EXISTS context_blocks (
+  version TEXT PRIMARY KEY,
+  scope TEXT NOT NULL,
+  block TEXT NOT NULL,
+  fetched_at_ms INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS agentdox_sessions (
+  conversation_key TEXT PRIMARY KEY,
+  scope TEXT NOT NULL,
+  session_id TEXT NOT NULL,
+  created_at_ms INTEGER NOT NULL
+);
+
 -- v2: catalog_cache gains key_scoped provenance. ALTER TABLE ADD COLUMN is
 -- idempotent only via a guard; SQLite has no IF NOT EXISTS for columns, so
 -- probe pragma_table_info and add when absent.
@@ -181,6 +198,19 @@ const MIGRATE_V8 = `
 ALTER TABLE ledger ADD COLUMN hold_arm INTEGER;
 `;
 
+// v11: conversations pin an agentdox context version. Storing the version (not
+// the block) keeps the row small; the block itself lives once in context_blocks.
+const MIGRATE_V11 = `
+ALTER TABLE conversations ADD COLUMN context_version TEXT;
+ALTER TABLE conversations ADD COLUMN context_fetched_at_ms INTEGER NOT NULL DEFAULT 0;
+`;
+
+// v12: ledger records prompt tokens removed by context compaction, so the
+// savings (and any over-aggressive elision) can be measured and tuned.
+const MIGRATE_V12 = `
+ALTER TABLE ledger ADD COLUMN prompt_tokens_saved INTEGER;
+`;
+
 // v9: benchmark_cache holds the external benchmark feeds (Artificial Analysis,
 // BenchLM) that backfill quality scores OpenRouter leaves unpublished. It is a
 // whole new table, created idempotently by the MIGRATIONS block above, so there
@@ -212,6 +242,9 @@ export function openDb(path: string): Database {
 		if (!ledgerCols.some((c) => c.name === "features")) db.exec(MIGRATE_V6);
 		if (!ledgerCols.some((c) => c.name === "explored_from")) db.exec(MIGRATE_V7);
 		if (!ledgerCols.some((c) => c.name === "hold_arm")) db.exec(MIGRATE_V8);
+		const convCols = db.query("PRAGMA table_info(conversations)").all() as { name: string }[];
+		if (!convCols.some((c) => c.name === "context_version")) db.exec(MIGRATE_V11);
+		if (!ledgerCols.some((c) => c.name === "prompt_tokens_saved")) db.exec(MIGRATE_V12);
 		db.exec(`PRAGMA user_version = ${USER_VERSION}`);
 	}
 	return db;

package/src/wire/openai/request.ts

@@ -1,4 +1,5 @@
 import type {
+	CompactionEdit,
 	NormMessage,
 	NormRequest,
 	NormTool,
@@ -136,6 +137,78 @@ function parseReasoning(b: { reasoning?: unknown; reasoning_effort?: unknown }):
 	return undefined;
 }
 
+/**
+ * Folds the agentdox context block into the system prefix.
+ *
+ * Appends to the LAST system/developer message rather than inserting a new
+ * one. Inserting would shift every cache-breakpoint index the core computed
+ * against the client's own array; appending keeps them valid AND lands the
+ * block inside the prefix `planCacheBreakpoints` already marks as cacheable.
+ *
+ * When the request has no system message at all, one is prepended and the
+ * breakpoint indices are shifted by one to compensate.
+ *
+ * Returns the (possibly shifted) breakpoint indices.
+ */
+function injectContextBlock(
+	messages: Record<string, unknown>[],
+	block: string,
+	breakpoints: number[],
+): number[] {
+	let lastSystem = -1;
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const role = messages[i]?.role;
+		if (role === "system" || role === "developer") {
+			lastSystem = i;
+			break;
+		}
+	}
+
+	if (lastSystem === -1) {
+		messages.unshift({ role: "system", content: block });
+		return breakpoints.map((i) => i + 1);
+	}
+
+	const msg = messages[lastSystem];
+	if (msg === undefined) return breakpoints;
+	const content = msg.content;
+	if (typeof content === "string") {
+		msg.content = `${content}
+
+${block}`;
+	} else if (Array.isArray(content)) {
+		// Append as a trailing text part. A later cache_control pass marks the
+		// LAST text part, so the block stays inside the cached prefix.
+		content.push({ type: "text", text: block });
+	} else {
+		msg.content = block;
+	}
+	return breakpoints;
+}
+
+/**
+ * Applies compaction edits in place: shrinks each targeted tool-result's string
+ * content, leaving a self-describing breadcrumb so the model can re-run the tool
+ * to restore what was elided. Non-string content (rare for tool results) is left
+ * untouched. Message count and order are preserved, so breakpoint indices and
+ * the context-block append computed against this array stay valid.
+ */
+function applyCompaction(messages: Record<string, unknown>[], edits: readonly CompactionEdit[]): void {
+	for (const edit of edits) {
+		const msg = messages[edit.index];
+		if (msg === undefined) continue;
+		const content = msg.content;
+		if (typeof content !== "string") continue;
+		if (edit.mode === "stub") {
+			msg.content = `[omp-router: ${edit.note} elided to save context; re-run the tool to restore]`;
+			continue;
+		}
+		if (content.length <= edit.keepHead + edit.keepTail) continue;
+		const elided = content.length - edit.keepHead - edit.keepTail;
+		msg.content = `${content.slice(0, edit.keepHead)}\n\n[omp-router: elided ${elided} chars — ${edit.note}; re-run the tool to restore]\n\n${content.slice(content.length - edit.keepTail)}`;
+	}
+}
+
 function renderUpstreamBody(
 	original: Record<string, unknown>,
 	m: UpstreamMutations,
@@ -165,6 +238,7 @@ function renderUpstreamBody(
 
 	// messages was validated to be an array of objects at parse time.
 	const messages = body.messages as Record<string, unknown>[];
+	if (m.compactionPlan !== undefined && m.compactionPlan.length > 0) applyCompaction(messages, m.compactionPlan);
 	if (m.stripAssistantReasoning) {
 		// omp replays reasoning fields for what it believes is a local backend;
 		// most OpenRouter upstreams reject every spelling.
@@ -175,7 +249,13 @@ function renderUpstreamBody(
 			delete msg.reasoning_details;
 		}
 	}
-	for (const idx of m.cacheBreakpointMessageIndices) {
+	// Context injection happens BEFORE breakpoints are applied, so the block is
+	// covered by the system-prefix breakpoint rather than left outside it.
+	let breakpoints = m.cacheBreakpointMessageIndices;
+	if (m.contextBlock !== undefined && m.contextBlock !== "") {
+		breakpoints = injectContextBlock(messages, m.contextBlock, breakpoints);
+	}
+	for (const idx of breakpoints) {
 		const msg = messages[idx];
 		if (!msg) continue;
 		const content = msg.content;
@@ -208,6 +288,10 @@ export function parseChatRequest(body: unknown, headers: Headers): NormRequest {
 	// this header to ctx.sessionManager.getSessionId(); absent ⇒ unknown session.
 	const ompSessionId = (headers.get("x-omp-session") ?? "").trim();
 
+	// agentdox project scope. Selects whose shared context is injected; absent
+	// ⇒ the server falls back to its configured default scope.
+	const agentdoxScope = (headers.get("x-agentdox-scope") ?? "").trim();
+
 	if (typeof b.model !== "string" || b.model.length === 0) {
 		throw invalidRequest("model must be a non-empty string");
 	}
@@ -267,6 +351,7 @@ export function parseChatRequest(body: unknown, headers: Headers): NormRequest {
 		conversationKey,
 		harnessId,
 		ompSessionId,
+		agentdoxScope,
 		requestedModel,
 		messages,
 		tools,

package/src/wire/types.ts

@@ -75,6 +75,13 @@ export interface NormRequest {
 	 * the client sends no header.
 	 */
 	ompSessionId: string;
+	/**
+	 * agentdox project scope from the `X-Agentdox-Scope` request header. Selects
+	 * which project's shared context is injected and which project's sessions
+	 * the turn is recorded into. Empty ⇒ fall back to `context.defaultScope`,
+	 * and if that is empty too the bridge stays inert for this request.
+	 */
+	agentdoxScope: string;
 	/** Virtual model the client selected, e.g. `auto`, `auto-cheap`, `auto-max`. */
 	requestedModel: string;
 	messages: NormMessage[];
@@ -112,6 +119,35 @@ export interface UpstreamMutations {
 	maxTokens: number | undefined;
 	/** Drop assistant reasoning-replay fields the target rejects. */
 	stripAssistantReasoning: boolean;
+	/**
+	 * agentdox project context to fold into the system prefix. Appended to the
+	 * LAST system message rather than inserted as a new one: inserting would
+	 * shift every `cacheBreakpointMessageIndices` entry, and appending puts the
+	 * block inside the prefix that `planCacheBreakpoints` already marks.
+	 * Undefined ⇒ inject nothing.
+	 */
+	contextBlock?: string;
+	/**
+	 * Deterministic compaction edits to apply to the message array before the
+	 * other mutations. Each edit shrinks ONE tool-result's content in place;
+	 * message count and order are preserved so cache-breakpoint indices and the
+	 * context-block append stay valid. Empty ⇒ compact nothing.
+	 */
+	compactionPlan?: CompactionEdit[];
+}
+
+/**
+ * One in-place shrink of a tool-result message's content. `stub` replaces the
+ * whole content with a breadcrumb; `truncate` keeps `keepHead`/`keepTail`
+ * characters around an elision breadcrumb. `note` describes why, for the
+ * breadcrumb the model reads.
+ */
+export interface CompactionEdit {
+	index: number;
+	mode: "truncate" | "stub";
+	keepHead: number;
+	keepTail: number;
+	note: string;
 }
 
 export type FinishReason = "stop" | "length" | "tool_calls" | "content_filter" | "error";

package/test/classify.test.ts

@@ -50,7 +50,9 @@ function contFeatures(toolLoopDepth: number, over: Partial<Features> = {}): Feat
 		distinctToolsUsed: 3,
 		lastToolFailed: false,
 		repeatedToolCall: false,
+		circularToolCall: false,
 		hasImages: false,
+		hasNewImage: false,
 		codeBlocks: 0,
 		codeBytes: 0,
 		looksLikeDiff: false,
@@ -211,11 +213,25 @@ describe("scoreHeuristic", () => {
 		}
 	});
 
-	test("pure loop depth tops out at simple; complexity signals stack to moderate", () => {
-		// Depth alone means competent-but-cheap (simple), not a frontier model.
-		const veryDeep = scoreHeuristic(contFeatures(90), BASE);
-		expect(tierIdx(veryDeep.tier)).toBeLessThanOrEqual(tierIdx("simple"));
-		// A failing tool result on top of a deep loop is genuinely hard.
+	test("pure loop depth ramps to moderate in the mid-range and hard only when runaway", () => {
+		// A sustained-but-not-runaway loop tops out in moderate: the calibrated
+		// ramp ceiling for ordinary deep work.
+		const midRange = scoreHeuristic(contFeatures(30), BASE);
+		expect(midRange.tier).toBe("moderate");
+		// A runaway loop of pure continuations (no other signal) must reach hard.
+		// moderate never swaps the cheapest coding model off — it clears the 60
+		// floor even after the latency penalty — so only hard's 72 floor breaks it.
+		const runaway = scoreHeuristic(contFeatures(90), BASE);
+		expect(runaway.tier).toBe("hard");
+	});
+
+	test("a circular tool call on a deep loop escalates to hard", () => {
+		// The stuck signal raw depth misses: a prior call re-issued verbatim.
+		const deepCircular = scoreHeuristic(contFeatures(90, { circularToolCall: true }), BASE);
+		expect(deepCircular.tier).toBe("hard");
+	});
+
+	test("a failing tool result on a deep loop is at least moderate", () => {
 		const deepAndFailing = scoreHeuristic(contFeatures(20, { lastToolFailed: true }), BASE);
 		expect(tierIdx(deepAndFailing.tier)).toBeGreaterThanOrEqual(tierIdx("moderate"));
 	});
@@ -309,6 +325,48 @@ describe("classifyTask", () => {
 		expect(classifyTask(f)).toBe("vision");
 	});
 
+	test("a stale image on a tool continuation is coding, not vision", () => {
+		const f = featuresFor(
+			[
+				SYSTEM,
+				{
+					role: "user",
+					content: [
+						{ type: "text", text: "build this UI" },
+						{ type: "image_url", image_url: { url: "data:image/png;base64,xxx" } },
+					],
+				},
+				{ role: "assistant", content: null, tool_calls: [{ id: "c1", type: "function", function: { name: "read", arguments: "{}" } }] },
+				{ role: "tool", tool_call_id: "c1", name: "read", content: "ok" },
+			],
+			TOOLS,
+		);
+		expect(f.hasImages).toBe(true);
+		expect(f.hasNewImage).toBe(false);
+		expect(classifyTask(f)).toBe("coding");
+	});
+
+	test("a freshly supplied image mid-loop is vision", () => {
+		const f = featuresFor(
+			[
+				SYSTEM,
+				{ role: "user", content: "start" },
+				{ role: "assistant", content: null, tool_calls: [{ id: "c1", type: "function", function: { name: "read", arguments: "{}" } }] },
+				{ role: "tool", tool_call_id: "c1", name: "read", content: "ok" },
+				{
+					role: "user",
+					content: [
+						{ type: "text", text: "here is the error" },
+						{ type: "image_url", image_url: { url: "data:image/png;base64,xxx" } },
+					],
+				},
+			],
+			TOOLS,
+		);
+		expect(f.hasNewImage).toBe(true);
+		expect(classifyTask(f)).toBe("vision");
+	});
+
 	test("code blocks and diffs are coding tasks", () => {
 		expect(classifyTask(featuresFor([SYSTEM, { role: "user", content: "```ts\nconst x = 1;\n```" }], []))).toBe("coding");
 		expect(classifyTask(featuresFor([SYSTEM, { role: "user", content: "diff --git a/x b/x\n@@ -1 +1 @@\n-old\n+new" }], []))).toBe("coding");