auto-model-router 0.2.2 → 0.2.7

package/src/cost/ledger.ts

@@ -57,6 +57,7 @@ interface LedgerRow {
 	wasted: number;
 	upstream_generation_id: string | null;
 	error: string | null;
+	prompt_tokens_saved: number | null;
 }
 
 interface TrustRow {
@@ -70,6 +71,8 @@ interface TrustRow {
 interface LatencyRow {
 	samples: number;
 	ttft_ms: number | null;
+	ctok_sum: number | null;
+	elapsed_ms_sum: number | null;
 }
 
 interface CalibrationRow {
@@ -82,8 +85,11 @@ interface CalibrationRow {
  * Error kinds that say nothing about a MODEL's reliability, and so must not
  * count against its trust:
  *  - `aborted`: the client hung up (user pressed escape mid-turn).
- *  - `auth`: credential, credit, or account-policy refusal (age confirmation,
- *    prompt-injection blocking) — identical for every model on the key.
+ *  - `auth`: credential or credit refusal (401 invalid key, 402 out of credits)
+ *    — key-wide, identical for every model.
+ *  - `moderation`: a provider content-moderation or per-model policy gate (403:
+ *    prompt-injection block, age/data-policy confirmation). Per-model, not a
+ *    quality signal, and failover already handles it.
  *  - `model_unavailable`: the guardrail or data policy excludes the endpoint;
  *    an availability fact, not a quality one, and failover already handles it.
  *
@@ -92,7 +98,7 @@ interface CalibrationRow {
  * unclassifiable legacy row and stays attributable, preserving the old,
  * stricter behaviour rather than silently forgiving it.
  */
-const UNATTRIBUTABLE_KINDS = "('aborted', 'auth', 'model_unavailable')";
+const UNATTRIBUTABLE_KINDS = "('aborted', 'auth', 'moderation', 'model_unavailable')";
 
 const ATTRIBUTABLE_ERROR = `error IS NOT NULL AND (error_kind IS NULL OR error_kind NOT IN ${UNATTRIBUTABLE_KINDS})`;
 
@@ -104,14 +110,22 @@ const TRUST_SELECT = `COUNT(*) AS attempts,
 			THEN ABS(reported_usd - predicted_usd) / reported_usd END) AS mean_cost_error`;
 
 /**
- * Time-to-first-token, averaged over streamed, non-errored turns. TTFT (not
- * total latency) isolates model+provider responsiveness from answer length: a
- * model is "slow" when it takes a long time to START, not when it was asked for
- * a long answer. Errored/aborted rows and non-streaming rows (null ttft) are
- * excluded — they carry no responsiveness signal.
+ * Responsiveness over streamed, non-errored turns. TTFT (not total latency)
+ * isolates start latency from answer length: a model is "slow to start" when it
+ * takes a long time to emit the FIRST token. Throughput (aggregate completion
+ * tokens per post-TTFT second) captures the complementary axis — how fast the
+ * body streams once it starts. Errored/aborted and non-streaming rows (null
+ * ttft) are excluded; throughput additionally requires a positive completion
+ * count and elapsed time.
  */
 const LATENCY_SELECT = `COUNT(CASE WHEN ttft_ms IS NOT NULL AND ttft_ms > 0 AND error IS NULL THEN 1 END) AS samples,
-		AVG(CASE WHEN ttft_ms IS NOT NULL AND ttft_ms > 0 AND error IS NULL THEN ttft_ms END) AS ttft_ms`;
+		AVG(CASE WHEN ttft_ms IS NOT NULL AND ttft_ms > 0 AND error IS NULL THEN ttft_ms END) AS ttft_ms,
+		SUM(CASE WHEN ttft_ms IS NOT NULL AND ttft_ms > 0 AND error IS NULL AND latency_ms > ttft_ms
+			AND json_extract(usage, '$.completionTokens') > 0
+			THEN json_extract(usage, '$.completionTokens') END) AS ctok_sum,
+		SUM(CASE WHEN ttft_ms IS NOT NULL AND ttft_ms > 0 AND error IS NULL AND latency_ms > ttft_ms
+			AND json_extract(usage, '$.completionTokens') > 0
+			THEN latency_ms - ttft_ms END) AS elapsed_ms_sum`;
 
 /**
  * Recovers the `UpstreamErrorKind` from the text turn.ts stored.
@@ -144,7 +158,11 @@ function toTrust(slug: string, row: TrustRow): ModelTrust {
 
 function toLatency(slug: string, row: LatencyRow): ModelLatency | null {
 	if (row.samples <= 0 || row.ttft_ms === null) return null;
-	return { slug, samples: row.samples, ttftMs: row.ttft_ms };
+	const tokensPerSec =
+		row.elapsed_ms_sum !== null && row.elapsed_ms_sum > 0 && row.ctok_sum !== null
+			? (row.ctok_sum * 1000) / row.elapsed_ms_sum
+			: 0;
+	return { slug, samples: row.samples, ttftMs: row.ttft_ms, tokensPerSec };
 }
 
 function toEntry(row: LedgerRow): LedgerEntry {
@@ -180,6 +198,7 @@ function toEntry(row: LedgerRow): LedgerEntry {
 		wasted: row.wasted === 1,
 		upstreamGenerationId: row.upstream_generation_id,
 		error: row.error,
+		promptTokensSaved: row.prompt_tokens_saved ?? 0,
 	};
 }
 
@@ -190,8 +209,8 @@ export function createLedger(db: Database, cfg: RouterConfig): Ledger {
 			id, created_at_ms, conversation_key, session_id, turn, requested_model, harness_id, omp_session_id, slug, served_slug,
 			tier, classification_source, reasons, predicted_usd, reported_usd, usage, cost_breakdown,
 			attempt, escalation_signal, latency_ms, ttft_ms, finish_reason, wasted, upstream_generation_id, error,
-			error_kind, features, score, confidence, task, classifier_reasons, explored_from, hold_arm
-		) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+			error_kind, features, score, confidence, task, classifier_reasons, explored_from, hold_arm, prompt_tokens_saved
+		) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
 	);
 	const calibrationStmt = db.query(
 		`INSERT INTO token_calibration (tokenizer, est_bytes, actual_tokens, samples) VALUES (?, ?, ?, 1)
@@ -279,6 +298,7 @@ export function createLedger(db: Database, cfg: RouterConfig): Ledger {
 				entry.classifierReasons === null ? null : JSON.stringify(entry.classifierReasons),
 				entry.exploredFrom,
 				entry.holdArm,
+				entry.promptTokensSaved,
 			);
 			// Always consume the pending estimate, even when the turn failed, so a
 			// dead turn's bytes can never pair with a later turn's tokens. Only

package/src/cost/types.ts

@@ -128,6 +128,8 @@ export interface LedgerEntry {
 	wasted: boolean;
 	upstreamGenerationId: string | null;
 	error: string | null;
+	/** Prompt tokens removed by compaction before dispatch. 0 when none. NULL before v12. */
+	promptTokensSaved: number;
 }
 
 /** Rolling blended rate used to keep omp's cost display honest. */
@@ -165,6 +167,15 @@ export interface ModelLatency {
 	samples: number;
 	/** Mean time-to-first-token, ms, over streamed non-errored turns. */
 	ttftMs: number;
+	/**
+	 * Completion throughput, tokens/second, over streamed non-errored turns that
+	 * emitted tokens (aggregate: total completion tokens / total post-TTFT time).
+	 * 0 when no such row exists. Complements ttftMs: TTFT is how long the answer
+	 * takes to START, throughput is how long it takes to FINISH — a model can be
+	 * quick to first token yet stream the body slowly (e.g. deepseek-v4-flash:
+	 * ~2s TTFT but ~20 tok/s and ~38s total).
+	 */
+	tokensPerSec: number;
 }
 
 export interface Ledger {
@@ -181,10 +192,10 @@ export interface Ledger {
 	trust(slug: string, harnessId?: string): ModelTrust | null;
 	allTrust(): ModelTrust[];
 	/**
-	 * Per-model mean time-to-first-token (ms), optionally scoped to a harness.
-	 * Null until `filters.latencyMinSamples` streamed samples exist. TTFT, not
-	 * total latency: it measures model+provider responsiveness independent of
-	 * how many tokens the answer happened to need.
+	 * Per-model responsiveness (mean TTFT + completion throughput), optionally
+	 * scoped to a harness. Null until `filters.latencyMinSamples` streamed samples
+	 * exist. TTFT isolates start latency from answer length; throughput captures
+	 * how fast the body streams once it starts.
 	 */
 	latency(slug: string, harnessId?: string): ModelLatency | null;
 	/** Observed chars-per-token ratio for a tokenizer family; null until calibrated. */

package/src/router/candidates.ts

@@ -73,14 +73,23 @@ const LATENCY_EXCESS_CAP = 3;
 
 /**
  * Latency penalty as a multiplier on effective cost (>= 1; 1 = no penalty).
- * Mean TTFT above `latencyReferenceMs` inflates the model's effective cost, the
- * same lever trust uses for flakiness, so a faster model of equal quality and
- * price outranks a sluggish one. Inert when the weight is 0 or the model has
- * too few streamed samples to judge.
+ *
+ * Models the EXPECTED TOTAL WAIT the user experiences: time to first token, plus
+ * streaming the expected completion at the model's measured throughput. That wait
+ * above the reference (built from `latencyReferenceMs` + `latencyReferenceTokensPerSec`)
+ * inflates effective cost — the same lever trust uses for flakiness — so a faster
+ * model of equal quality and price outranks a sluggish one. Capturing throughput,
+ * not just TTFT, is what catches a model that starts fast but streams slowly
+ * (deepseek-v4-flash: ~2s TTFT yet ~20 tok/s → ~38s total). Inert when the weight
+ * is 0 or the model has too few streamed samples to judge; when throughput is
+ * unmeasured it degrades to a TTFT-only comparison against the reference wait.
  */
-function latencyMultiplier(latency: ModelLatency | null, filters: FilterConfig): number {
+function latencyMultiplier(latency: ModelLatency | null, filters: FilterConfig, expectedCompletionTokens: number): number {
 	if (latency === null || filters.latencyWeight <= 0 || latency.samples < filters.latencyMinSamples) return 1;
-	const excess = Math.max(0, (latency.ttftMs - filters.latencyReferenceMs) / filters.latencyReferenceMs);
+	const streamMs = latency.tokensPerSec > 0 ? (expectedCompletionTokens / latency.tokensPerSec) * 1000 : 0;
+	const waitMs = latency.ttftMs + streamMs;
+	const refWaitMs = filters.latencyReferenceMs + (expectedCompletionTokens / filters.latencyReferenceTokensPerSec) * 1000;
+	const excess = refWaitMs > 0 ? Math.max(0, (waitMs - refWaitMs) / refWaitMs) : 0;
 	return 1 + filters.latencyWeight * Math.min(excess, LATENCY_EXCESS_CAP);
 }
 
@@ -238,7 +247,7 @@ export function buildCandidates(args: BuildCandidatesArgs): { candidates: Candid
 			filters.latencyWeight > 0
 				? (ledger?.latency(slug, filters.trustScopedByHarness ? req.harnessId : undefined) ?? null)
 				: null;
-		const latencyMult = latencyMultiplier(latency, filters);
+		const latencyMult = latencyMultiplier(latency, filters, expectedCompletionTokens);
 		const effectiveUsd = (fc.expectedUsd / Math.max(trustScore, 0.5)) * latencyMult;
 		const score = Math.pow(qualityScore / 100, tierCfg.qualityExponent) / Math.max(effectiveUsd, 1e-9);
 
@@ -252,7 +261,9 @@ export function buildCandidates(args: BuildCandidatesArgs): { candidates: Candid
 			`expected $${fc.expectedUsd.toFixed(6)}`,
 		];
 		if (latencyMult > 1 && latency !== null) {
-			reasons.push(`latency penalty ×${latencyMult.toFixed(2)} (ttft ${Math.round(latency.ttftMs)}ms over ${latency.samples} samples)`);
+			reasons.push(
+				`latency penalty ×${latencyMult.toFixed(2)} (ttft ${Math.round(latency.ttftMs)}ms, ${latency.tokensPerSec.toFixed(0)} tok/s over ${latency.samples} samples)`,
+			);
 		}
 		if (pinned) reasons.push("pinned into tier");
 		candidates.push({ model, forecast: fc, qualityScore, trustScore, score, reasons });

package/src/router/classify.ts

@@ -32,7 +32,7 @@ const CAP_COMPLEXITY = 0.3;
 const W_TRIVIALITY_KEYWORD = -0.09;
 const CAP_TRIVIALITY = -0.27;
 const W_TOOL_FAILED = 0.26; // dominant positive: retry loops are expensive
-const W_REPEATED_CALL = 0.14; // the model is stuck
+const W_CIRCULAR_LOOP = 0.24; // a re-issued (circular) tool call: the model is stuck
 const W_TERSE = -0.1;
 const W_CODE_BLOCK = 0.04;
 const CAP_CODE = 0.08;
@@ -48,13 +48,20 @@ const CAP_LOOP_DEPTH = -0.06;
 // A sustained autonomous loop is the signal the underlying task is substantial:
 // the agent keeps grinding without human input. Unlike the mechanical-step
 // penalty above, this term ACCUMULATES with depth past the agentic threshold so
-// long/hard loops climb out of trivial instead of scoring like a one-line edit.
-// Capped so pure depth tops out in `simple` (a competent-but-cheap model);
-// reaching `moderate`/`hard` still requires real complexity signals (tool
-// failure, repeated call, keywords) to stack on top.
+// long loops climb out of trivial. The ramp slope is calibrated on recorded
+// coding turns; the cap governs the ceiling. `moderate` is NOT enough to break a
+// distinct-read loop: on the coding axis the cheapest model above the moderate
+// floor (deepseek-v4-flash, coding 69.1) also clears it after the latency
+// penalty, so escalating to moderate never swaps the weak model off — live
+// evidence (conv 888e5bddc1) is a loop grinding to depth 27+ on it. Only `hard`
+// (floor 72) excludes that model and forces a materially stronger, faster one.
+// So the cap lets a RUNAWAY loop (~depth 38 of pure continuations, no other
+// signal) reach `hard`; the calibrated mid-range still tops out in `moderate`,
+// and any corroborating stuck signal (circular call, tool failure, keywords)
+// reaches `hard` far sooner.
 const W_AUTONOMOUS_LOOP = 0.06; // base bonus at the threshold
 const W_AUTONOMOUS_LOOP_PER_DEPTH = 0.018; // added per loop step beyond the threshold
-const CAP_AUTONOMOUS_LOOP = 0.34;
+const CAP_AUTONOMOUS_LOOP = 0.7; // pure depth ramps through moderate into hard for a runaway loop
 const W_IMAGES = 0.04;
 const W_TOOLS_OFFERED = 0.03;
 
@@ -97,7 +104,7 @@ export function scoreHeuristic(f: Features, cfg: RouterConfig): Classification {
 		`triviality keywords [${f.trivialityKeywords.join(", ")}]`,
 	);
 	if (f.lastToolFailed) add(W_TOOL_FAILED, "last tool result failed");
-	if (f.repeatedToolCall) add(W_REPEATED_CALL, "repeated tool call (model is stuck)");
+	if (f.circularToolCall) add(W_CIRCULAR_LOOP, "circular tool call (re-issued a prior call; stuck)");
 	const rw = reasoningWeight(f.requestedReasoning);
 	if (rw > 0) add(rw, `client requested reasoning=${f.requestedReasoning ?? ""}`);
 	if (f.isTerseInstruction) add(W_TERSE, "terse instruction");
@@ -140,13 +147,20 @@ export function pickQualityAxis(f: Features, cfg: RouterConfig): QualityAxis {
 
 /**
  * Task-type classification: the KIND of work, orthogonal to complexity tier.
- * Cheap and deterministic — no tokenizer, no model call. Vision is the only
- * hard signal (image input); the rest are keyword/structural heuristics over
- * the newest user content. The task selects the quality axis and capability
- * filters; the tier still bounds cost.
+ * Cheap and deterministic — no tokenizer, no model call. A freshly supplied
+ * image is the only hard signal (vision); the rest are keyword/structural
+ * heuristics over the newest user content. The task selects the quality axis
+ * and capability filters; the tier still bounds cost.
  */
 export function classifyTask(f: Features): TaskType {
-	if (f.hasImages) return "vision";
+	// Vision is the KIND of work only when the human just supplied an image. A
+	// stale screenshot lingering in a long agent loop must not pin every
+	// mechanical tool-continuation to the vision (intelligence) axis, which
+	// systematically underscores cheap coding models and, at the moderate/hard
+	// floors, excludes them entirely in favour of frontier models. Capability
+	// (the payload still carries the image) is enforced separately via
+	// req.hasImages in buildCandidates, independent of the task axis.
+	if (f.hasNewImage) return "vision";
 	// Coding: code blocks, diffs, a tool loop, or tools offered — agent tool use
 	// is coding work. Bare chat (no tools, no code) falls through.
 	if (f.codeBlocks > 0 || f.looksLikeDiff || f.toolLoopDepth > 0 || f.toolCount > 0) return "coding";

package/src/router/compaction.ts

@@ -0,0 +1,163 @@
+/**
+ * Context compaction (Phase 1): deterministic pruning of stale, low-value bulk
+ * — chiefly old tool output — from a turn's history before dispatch.
+ *
+ * This module only DECIDES (a plan of per-message edits) from cheap NormMessage
+ * metadata; `renderUpstreamBody` APPLIES the edits to the raw message bytes.
+ * Every edit shrinks a single tool-result's CONTENT in place — never removes or
+ * reorders a message — so tool_call↔result pairing, cache-breakpoint indices,
+ * and the agentdox context-block append all stay valid. It is a pure function
+ * of its inputs, so `explain` still replays a past decision offline.
+ *
+ * See docs/context-optimization.md.
+ */
+
+import type { CompactionConfig } from "../config/types.ts";
+import type { CompactionEdit, NormMessage } from "../wire/types.ts";
+
+export interface CompactionResult {
+	edits: CompactionEdit[];
+	/** Estimated prompt bytes removed by the plan. */
+	savedBytes: number;
+}
+
+const EMPTY: CompactionResult = { edits: [], savedBytes: 0 };
+
+/** Approximate byte cost of an elision breadcrumb; savings are net of it. */
+const BREADCRUMB_BYTES = 120;
+
+/**
+ * First string value in a tool call's argument JSON — a schema-agnostic proxy
+ * for the resource a call operates on (a `path`, `id`, `query`, ...). Used to
+ * detect when a later call supersedes an earlier read of the same resource.
+ */
+function primaryArg(argsJson: string): string | null {
+	try {
+		const parsed: unknown = JSON.parse(argsJson);
+		if (parsed !== null && typeof parsed === "object") {
+			for (const value of Object.values(parsed)) if (typeof value === "string" && value.length > 0) return value;
+		}
+	} catch {
+		// Malformed args carry no resource key; fall through.
+	}
+	return null;
+}
+
+/**
+ * Index of the first message in the PROTECTED region: the last
+ * `protectRecentTurns` user/assistant turns and everything after them (the
+ * volatile tail). Messages before it are eligible for compaction. Returns 0
+ * (protect everything) when the conversation is shorter than the window.
+ */
+function protectFromIndex(messages: readonly NormMessage[], protectRecentTurns: number): number {
+	let turns = 0;
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const role = messages[i]?.role;
+		if (role === "user" || role === "assistant") {
+			turns++;
+			if (turns >= protectRecentTurns) return i;
+		}
+	}
+	return 0;
+}
+
+interface ToolResult {
+	index: number;
+	name: string;
+	text: string;
+	bytes: number;
+	/** Primary argument of the originating call, for supersede detection. */
+	key: string | null;
+}
+
+/**
+ * Plans compaction for a turn's messages toward `targetBytes` of total prompt.
+ * Duplicate and superseded elisions (pure stale-data wins) are always applied;
+ * large-result truncation (more lossy) runs largest-first only until the target
+ * is met. `promptBytes` is the whole prompt (messages + system + tool schemas),
+ * so the target is compared against the real dispatched size.
+ */
+export function planCompaction(
+	messages: readonly NormMessage[],
+	cfg: CompactionConfig,
+	targetBytes: number,
+	promptBytes: number,
+): CompactionResult {
+	if (!cfg.enabled) return EMPTY;
+
+	const protectStart = protectFromIndex(messages, cfg.protectRecentTurns);
+	if (protectStart <= 0) return EMPTY;
+
+	// Assistant tool_call id → name/args, to key tool results by their call.
+	const callById = new Map<string, { name: string; args: string }>();
+	for (const m of messages) {
+		if (m.role !== "assistant") continue;
+		for (const tc of m.toolCalls) callById.set(tc.id, { name: tc.name, args: tc.argsJson });
+	}
+
+	const tools: ToolResult[] = [];
+	for (let i = 0; i < protectStart; i++) {
+		const m = messages[i];
+		if (m === undefined || m.role !== "tool") continue;
+		const call = m.toolCallId === undefined ? undefined : callById.get(m.toolCallId);
+		tools.push({
+			index: i,
+			name: m.toolName ?? call?.name ?? "",
+			text: m.text,
+			bytes: m.textBytes,
+			key: call === undefined ? null : primaryArg(call.args),
+		});
+	}
+	if (tools.length === 0) return EMPTY;
+
+	const edits: CompactionEdit[] = [];
+	const done = new Set<number>();
+	let saved = 0;
+	const stub = (t: ToolResult, note: string): void => {
+		if (done.has(t.index)) return;
+		const gain = t.bytes - BREADCRUMB_BYTES;
+		if (gain <= 0) return; // already smaller than a breadcrumb
+		edits.push({ index: t.index, mode: "stub", keepHead: 0, keepTail: 0, note });
+		done.add(t.index);
+		saved += gain;
+	};
+
+	// Rule 1: collapse byte-identical duplicate results, keeping the LAST copy
+	// (consistent with supersede below, so a result that is both never loses
+	// every copy).
+	if (cfg.collapseDuplicateResults) {
+		const lastByContent = new Map<string, number>();
+		for (const t of tools) lastByContent.set(`${t.name}\u0000${t.text}`, t.index);
+		for (const t of tools) {
+			if (lastByContent.get(`${t.name}\u0000${t.text}`) !== t.index) stub(t, `identical repeated ${t.name || "tool"} result`);
+		}
+	}
+
+	// Rule 2: elide reads superseded by a newer call to the same resource,
+	// keeping the LAST (authoritative) one.
+	if (cfg.elideSupersededReads) {
+		const lastIndexByResource = new Map<string, number>();
+		for (const t of tools) if (t.key !== null) lastIndexByResource.set(`${t.name}\u0000${t.key}`, t.index);
+		for (const t of tools) {
+			if (t.key === null || done.has(t.index)) continue;
+			const last = lastIndexByResource.get(`${t.name}\u0000${t.key}`);
+			if (last !== undefined && last !== t.index) stub(t, `superseded by a newer ${t.name || "tool"} call`);
+		}
+	}
+
+	// Rule 3: truncate large stale results, largest first, until under target.
+	const keepBudget = cfg.keepHeadBytes + cfg.keepTailBytes + BREADCRUMB_BYTES;
+	const truncatable = tools
+		.filter((t) => !done.has(t.index) && t.bytes > cfg.maxToolResultBytes && t.bytes > keepBudget)
+		.sort((a, b) => b.bytes - a.bytes || a.index - b.index);
+	for (const t of truncatable) {
+		if (promptBytes - saved <= targetBytes) break;
+		edits.push({ index: t.index, mode: "truncate", keepHead: cfg.keepHeadBytes, keepTail: cfg.keepTailBytes, note: `large ${t.name || "tool"} result` });
+		done.add(t.index);
+		saved += t.bytes - keepBudget;
+	}
+
+	if (edits.length === 0) return EMPTY;
+	edits.sort((a, b) => a.index - b.index);
+	return { edits, savedBytes: saved };
+}

package/src/router/features.ts

@@ -95,6 +95,9 @@ export function extractFeatures(req: NormRequest, promptTokens: number): Feature
 	const isToolResultContinuation = tail?.role === "tool";
 	let newContentBytes = 0;
 	let newestUserText = "";
+	// Images in the volatile tail: an image the human just supplied is visual
+	// work; a tool-result continuation carries none of its own.
+	let newestRunImages = 0;
 	if (isToolResultContinuation) {
 		const start = trailingRunStart(messages, (m) => m.role === "tool");
 		for (let i = start; i < messages.length; i++) newContentBytes += messages[i]?.textBytes ?? 0;
@@ -105,6 +108,7 @@ export function extractFeatures(req: NormRequest, promptTokens: number): Feature
 			const m = messages[i];
 			if (m === undefined) continue;
 			newContentBytes += m.textBytes;
+			newestRunImages += m.images;
 			parts.push(m.text);
 		}
 		newestUserText = parts.join("\n");
@@ -136,28 +140,35 @@ export function extractFeatures(req: NormRequest, promptTokens: number): Feature
 		if (m.toolName !== undefined) toolNames.add(m.toolName);
 	}
 
-	// The last two assistant tool calls, in conversation order.
-	let lastName: string | null = null;
-	let lastArgs = "";
-	let prevName: string | null = null;
-	let prevArgs = "";
+	// The last few assistant tool calls, most-recent first, for stuck-loop
+	// detection. A byte-identical call re-issued within this window means the
+	// agent is going in circles even when the repeat is not adjacent — the case
+	// the strict "last two identical" check misses.
+	const RECENT_CALLS = 4;
+	const recentCalls: { name: string; args: string }[] = [];
 	scanCalls: for (let i = messages.length - 1; i >= 0; i--) {
 		const m = messages[i];
 		if (m === undefined || m.role !== "assistant") continue;
 		for (let j = m.toolCalls.length - 1; j >= 0; j--) {
 			const tc = m.toolCalls[j];
 			if (tc === undefined) continue;
-			if (lastName === null) {
-				lastName = tc.name;
-				lastArgs = tc.argsJson;
-			} else {
-				prevName = tc.name;
-				prevArgs = tc.argsJson;
-				break scanCalls;
+			recentCalls.push({ name: tc.name, args: tc.argsJson });
+			if (recentCalls.length >= RECENT_CALLS) break scanCalls;
+		}
+	}
+	const repeatedToolCall =
+		recentCalls.length >= 2 &&
+		recentCalls[0]?.name === recentCalls[1]?.name &&
+		recentCalls[0]?.args === recentCalls[1]?.args;
+	let circularToolCall = false;
+	for (let a = 0; a < recentCalls.length && !circularToolCall; a++) {
+		for (let b = a + 1; b < recentCalls.length; b++) {
+			if (recentCalls[a]?.name === recentCalls[b]?.name && recentCalls[a]?.args === recentCalls[b]?.args) {
+				circularToolCall = true;
+				break;
 			}
 		}
 	}
-	const repeatedToolCall = lastName !== null && lastName === prevName && lastArgs === prevArgs;
 
 	let lastToolFailed = false;
 	if (isToolResultContinuation) {
@@ -212,7 +223,9 @@ export function extractFeatures(req: NormRequest, promptTokens: number): Feature
 		distinctToolsUsed: toolNames.size,
 		lastToolFailed,
 		repeatedToolCall,
+		circularToolCall,
 		hasImages: req.hasImages,
+		hasNewImage: newestRunImages > 0,
 		codeBlocks,
 		codeBytes,
 		looksLikeDiff: DIFF_RE.test(newestUserText),

package/src/router/select.ts

@@ -11,7 +11,8 @@ import type { ProfileConfig, RouterConfig } from "../config/types.ts";
 import { priceAt } from "../cost/forecast.ts";
 import type { Ledger } from "../cost/types.ts";
 import { explorationDraw } from "./explore.ts";
-import type { NormRequest, ReasoningLevel } from "../wire/types.ts";
+import type { CompactionEdit, NormRequest, ReasoningLevel } from "../wire/types.ts";
+import { planCompaction } from "./compaction.ts";
 import { planCacheBreakpoints } from "./cache-control.ts";
 import { buildCandidates } from "./candidates.ts";
 import {
@@ -147,6 +148,36 @@ export function select(args: SelectArgs): Decision {
 	// exploration (2c) and candidate building (3) so both agree on the term.
 	const cacheWarm = state.cacheWarmSlug !== null && nowMs - state.cacheWarmAtMs <= cfg.hysteresis.cacheWarmTtlMs;
 
+	// 2b. Context compaction: shrink stale tool output before dispatch when the
+	//     prompt exceeds the token budget (or would overflow the profile window).
+	//     Deterministic and content-only (never removes a message), so downstream
+	//     forecasting, the context_too_small filter, cache breakpoints, and the
+	//     agentdox block append all operate on the compacted size / stay valid.
+	let compactionPlan: CompactionEdit[] = [];
+	let promptTokensSaved = 0;
+	let effFeatures = features;
+	if (cfg.compaction.enabled && req.promptBytes > 0 && features.promptTokens > 0) {
+		const headroom = cfg.filters.contextHeadroom;
+		const overBudget = features.promptTokens > cfg.compaction.budgetTokens;
+		const overWindow =
+			cfg.compaction.fitToWindow && features.promptTokens * headroom + EXPECTED_COMPLETION_TOKENS > profile.contextWindow;
+		if (overBudget || overWindow) {
+			const targets: number[] = [];
+			if (overBudget) targets.push(cfg.compaction.budgetTokens);
+			if (overWindow) targets.push(Math.max(1, Math.floor((profile.contextWindow - EXPECTED_COMPLETION_TOKENS) / headroom)));
+			const targetBytes = Math.min(...targets) * (req.promptBytes / features.promptTokens);
+			const plan = planCompaction(req.messages, cfg.compaction, targetBytes, req.promptBytes);
+			if (plan.edits.length > 0) {
+				compactionPlan = plan.edits;
+				promptTokensSaved = Math.min(features.promptTokens - 1, Math.round(features.promptTokens * (plan.savedBytes / req.promptBytes)));
+				effFeatures = { ...features, promptTokens: features.promptTokens - promptTokensSaved };
+				reasons.push(
+					`compaction: ${plan.edits.length} tool result(s) shrunk, ~${promptTokensSaved} tokens saved (prompt ${features.promptTokens}→${effFeatures.promptTokens})`,
+				);
+			}
+		}
+	}
+
 	// 2c. Epsilon-greedy exploration: on a small deterministic fraction of
 	//     turns, route one tier BELOW the tier we would otherwise use, so the
 	//     ledger witnesses whether the cheaper tier would have sufficed.
@@ -201,7 +232,7 @@ export function select(args: SelectArgs): Decision {
 	const build = (t: Tier, relaxLevel = 0): { candidates: Candidate[]; rejected: Rejection[] } =>
 		buildCandidates({
 			req,
-			features,
+			features: effFeatures,
 			tier: t,
 			task: classification.task,
 			snapshot,
@@ -283,9 +314,9 @@ export function select(args: SelectArgs): Decision {
 		const warm = candidates.find((c) => c.model.slug === warmSlug);
 		if (warm !== undefined) {
 			const warmPrice = priceAt(warm.model, Math.max(1, state.lastPromptTokens));
-			const newPrice = priceAt(chosen.model, Math.max(1, features.promptTokens));
+			const newPrice = priceAt(chosen.model, Math.max(1, effFeatures.promptTokens));
 			const stayCost = state.lastPromptTokens * (warmPrice.cacheRead ?? warmPrice.prompt);
-			const switchCost = features.promptTokens * (newPrice.prompt + (newPrice.cacheWrite ?? 0));
+			const switchCost = effFeatures.promptTokens * (newPrice.prompt + (newPrice.cacheWrite ?? 0));
 			if (stayCost > switchCost * cfg.hysteresis.switchMargin) {
 				reasons.push(
 					`cache: switch ${warmSlug} → ${chosen.model.slug} (stay $${stayCost.toFixed(4)} > switch $${switchCost.toFixed(4)} × ${cfg.hysteresis.switchMargin})`,
@@ -402,6 +433,8 @@ export function select(args: SelectArgs): Decision {
 		sessionId: state.sessionId,
 		sticky,
 		cacheBreakpointMessageIndices,
+		compactionPlan,
+		promptTokensSaved,
 		reasoning,
 		maxTokens,
 		stripAssistantReasoning,

package/src/router/state.ts

@@ -26,6 +26,8 @@ interface Row {
 	last_prompt_tokens: number;
 	cache_warm_slug: string | null;
 	cache_warm_at_ms: number;
+	context_version: string | null;
+	context_fetched_at_ms: number;
 	updated_at_ms: number;
 }
 
@@ -43,6 +45,8 @@ function toState(row: Row): ConversationState {
 		lastPromptTokens: row.last_prompt_tokens,
 		cacheWarmSlug: row.cache_warm_slug,
 		cacheWarmAtMs: row.cache_warm_at_ms,
+		contextVersion: row.context_version,
+		contextFetchedAtMs: row.context_fetched_at_ms,
 		updatedAtMs: row.updated_at_ms,
 	};
 }
@@ -56,9 +60,11 @@ export function createConversationStore(db: Database): ConversationStore {
 	const upsert = db.query(`
 		INSERT INTO conversations (
 			key, session_id, turn, current_slug, current_tier, sticky_until_turn,
-			escalations, spent_usd, last_prompt_tokens, cache_warm_slug, cache_warm_at_ms, updated_at_ms
+			escalations, spent_usd, last_prompt_tokens, cache_warm_slug, cache_warm_at_ms,
+			context_version, context_fetched_at_ms, updated_at_ms
 		) VALUES ($key, $sessionId, $turn, $currentSlug, $currentTier, $stickyUntilTurn,
-			$escalations, $spentUsd, $lastPromptTokens, $cacheWarmSlug, $cacheWarmAtMs, $updatedAtMs)
+			$escalations, $spentUsd, $lastPromptTokens, $cacheWarmSlug, $cacheWarmAtMs,
+			$contextVersion, $contextFetchedAtMs, $updatedAtMs)
 		ON CONFLICT(key) DO UPDATE SET
 			session_id = excluded.session_id,
 			turn = excluded.turn,
@@ -70,6 +76,8 @@ export function createConversationStore(db: Database): ConversationStore {
 			last_prompt_tokens = excluded.last_prompt_tokens,
 			cache_warm_slug = excluded.cache_warm_slug,
 			cache_warm_at_ms = excluded.cache_warm_at_ms,
+			context_version = excluded.context_version,
+			context_fetched_at_ms = excluded.context_fetched_at_ms,
 			updated_at_ms = excluded.updated_at_ms
 	`);
 	const deleteStale: Statement<unknown, [number]> = db.query("DELETE FROM conversations WHERE updated_at_ms < ?");
@@ -107,6 +115,8 @@ export function createConversationStore(db: Database): ConversationStore {
 				$lastPromptTokens: state.lastPromptTokens,
 				$cacheWarmSlug: state.cacheWarmSlug,
 				$cacheWarmAtMs: state.cacheWarmAtMs,
+				$contextVersion: state.contextVersion,
+				$contextFetchedAtMs: state.contextFetchedAtMs,
 				$updatedAtMs: Date.now(),
 			});
 		},