auto-model-router 0.2.1 → 0.2.7

package/src/cost/ledger.ts

@@ -18,7 +18,7 @@ import type { RouterConfig } from "../config/types.ts";
 import { consumePendingEstimate } from "../tokens/estimate.ts";
 import { computeBlendedRate } from "./blended.ts";
 import { computeCost } from "./forecast.ts";
-import type { BlendedRate, Ledger, LedgerEntry, ModelTrust, UsageCounts } from "./types.ts";
+import type { BlendedRate, Ledger, LedgerEntry, ModelLatency, ModelTrust, UsageCounts } from "./types.ts";
 
 /** Estimates below this many samples are noise; the default ratio is better. */
 const MIN_CALIBRATION_SAMPLES = 20;
@@ -57,6 +57,7 @@ interface LedgerRow {
 	wasted: number;
 	upstream_generation_id: string | null;
 	error: string | null;
+	prompt_tokens_saved: number | null;
 }
 
 interface TrustRow {
@@ -67,6 +68,13 @@ interface TrustRow {
 	mean_cost_error: number | null;
 }
 
+interface LatencyRow {
+	samples: number;
+	ttft_ms: number | null;
+	ctok_sum: number | null;
+	elapsed_ms_sum: number | null;
+}
+
 interface CalibrationRow {
 	est_bytes: number;
 	actual_tokens: number;
@@ -77,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.
  *
@@ -87,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})`;
 
@@ -98,6 +109,24 @@ const TRUST_SELECT = `COUNT(*) AS attempts,
 		AVG(CASE WHEN reported_usd IS NOT NULL AND reported_usd > 0
 			THEN ABS(reported_usd - predicted_usd) / reported_usd END) AS mean_cost_error`;
 
+/**
+ * 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,
+		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.
  *
@@ -127,6 +156,15 @@ 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;
+	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 {
 	return {
 		id: row.id,
@@ -160,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,
 	};
 }
 
@@ -170,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)
@@ -192,6 +231,8 @@ export function createLedger(db: Database, cfg: RouterConfig): Ledger {
 	const trustStmt = db.query(`SELECT ${TRUST_SELECT} FROM ledger WHERE slug = ?`);
 	const trustHarnessStmt = db.query(`SELECT ${TRUST_SELECT} FROM ledger WHERE slug = ? AND harness_id = ?`);
 	const allTrustStmt = db.query(`SELECT slug, ${TRUST_SELECT} FROM ledger GROUP BY slug`);
+	const latencyStmt = db.query(`SELECT ${LATENCY_SELECT} FROM ledger WHERE slug = ?`);
+	const latencyHarnessStmt = db.query(`SELECT ${LATENCY_SELECT} FROM ledger WHERE slug = ? AND harness_id = ?`);
 	const ratioStmt = db.query("SELECT est_bytes, actual_tokens, samples FROM token_calibration WHERE tokenizer = ?");
 	const recentStmt = db.query("SELECT * FROM ledger ORDER BY created_at_ms DESC LIMIT ?");
 	const cacheMetaStmt = db.query("SELECT fetched_at_ms FROM catalog_cache WHERE id = 1");
@@ -257,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
@@ -301,6 +343,15 @@ export function createLedger(db: Database, cfg: RouterConfig): Ledger {
 			return rows.map((row) => toTrust(row.slug, row));
 		},
 
+		latency(slug: string, harnessId?: string): ModelLatency | null {
+			const row =
+				harnessId !== undefined && harnessId !== ""
+					? (latencyHarnessStmt.get(slug, harnessId) as LatencyRow | null)
+					: (latencyStmt.get(slug) as LatencyRow | null);
+			if (row === null) return null;
+			return toLatency(slug, row);
+		},
+
 		tokenRatio(tokenizer: string): number | null {
 			const row = ratioStmt.get(tokenizer.trim().toLowerCase()) as CalibrationRow | null;
 			if (row === null || row.samples < MIN_CALIBRATION_SAMPLES || row.actual_tokens <= 0) return null;

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. */
@@ -159,6 +161,23 @@ export interface ModelTrust {
 	meanCostError: number;
 }
 
+/** Per-model responsiveness learned from our own traffic. Feeds candidate scoring. */
+export interface ModelLatency {
+	slug: string;
+	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 {
 	record(entry: LedgerEntry): void;
 	/** Total reported (or predicted, when reported is null) spend for a conversation. */
@@ -172,6 +191,13 @@ export interface Ledger {
 	/** Per-model reliability over the ledger, optionally scoped to a harness. */
 	trust(slug: string, harnessId?: string): ModelTrust | null;
 	allTrust(): ModelTrust[];
+	/**
+	 * 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. */
 	tokenRatio(tokenizer: string): number | null;
 	recentEntries(limit: number): LedgerEntry[];

package/src/router/candidates.ts

@@ -5,9 +5,9 @@
  */
 
 import type { CatalogModel, CatalogSnapshot } from "../catalog/types.ts";
-import type { QualityAxis, RouterConfig } from "../config/types.ts";
+import type { FilterConfig, QualityAxis, RouterConfig } from "../config/types.ts";
 import { forecast, priceAt } from "../cost/forecast.ts";
-import type { Ledger } from "../cost/types.ts";
+import type { Ledger, ModelLatency } from "../cost/types.ts";
 import type { NormRequest } from "../wire/types.ts";
 import { effectivePriceCeiling, effectiveQualityFloor, tierPlanFor } from "./tier-plan.ts";
 import type { Candidate, Features, Rejection, TaskType, Tier } from "./types.ts";
@@ -68,6 +68,31 @@ function resolveQuality(model: CatalogModel, axis: QualityAxis): { score: number
 /** Neutral trust prior for models our ledger has never observed. */
 const UNMEASURED_TRUST = 0.9;
 
+/** Excess-ratio cap so one very slow model cannot be penalised into oblivion. */
+const LATENCY_EXCESS_CAP = 3;
+
+/**
+ * Latency penalty as a multiplier on effective cost (>= 1; 1 = no penalty).
+ *
+ * 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, expectedCompletionTokens: number): number {
+	if (latency === null || filters.latencyWeight <= 0 || latency.samples < filters.latencyMinSamples) return 1;
+	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);
+}
+
 export function buildCandidates(args: BuildCandidatesArgs): { candidates: Candidate[]; rejected: Rejection[] } {
 	const { req, features, tier, task, snapshot, ledger, cfg, expectedCompletionTokens, warmSlug, relaxLevel = 0 } = args;
 	// A Set only when non-empty: the common path allocates nothing.
@@ -215,9 +240,15 @@ export function buildCandidates(args: BuildCandidatesArgs): { candidates: Candid
 		const trustScore = trust !== null && trust.attempts > 0 ? trust.successRate : UNMEASURED_TRUST;
 		const qualityScore = quality?.score ?? 0;
 		// Shared scoring: trust converts flakiness into money — a model failing
-		// 20% of the time really costs ~25% more in retries. qualityExponent 0
-		// makes this "cheapest above the floor"; the floor does the quality work.
-		const effectiveUsd = fc.expectedUsd / Math.max(trustScore, 0.5);
+		// 20% of the time really costs ~25% more in retries. Latency does the same
+		// for slowness (TTFT over the reference). qualityExponent 0 makes this
+		// "cheapest above the floor"; the floor does the quality work.
+		const latency =
+			filters.latencyWeight > 0
+				? (ledger?.latency(slug, filters.trustScopedByHarness ? req.harnessId : undefined) ?? null)
+				: null;
+		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);
 
 		const reasons: string[] = [
@@ -229,6 +260,11 @@ export function buildCandidates(args: BuildCandidatesArgs): { candidates: Candid
 				: `trust ${trustScore.toFixed(2)} over ${trust.attempts} attempts`,
 			`expected $${fc.expectedUsd.toFixed(6)}`,
 		];
+		if (latencyMult > 1 && latency !== null) {
+			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,