auto-model-router 0.2.2 → 0.2.8

package/docs/context-optimization.md

@@ -0,0 +1,362 @@
+# Context optimization (compaction)
+
+Status: **design, not implemented.** Decisions locked 2026-08-28. Phase 1 is the
+build target; Phase 2 is documented so the schema and pipeline reserve room for it.
+
+## Goal
+
+Before dispatching a turn to the chosen model, the router transforms the outgoing
+message history to remove **stale, low-value bulk** — chiefly old tool output —
+so that:
+
+1. long agentic conversations keep **fitting the candidate pool** (a smaller
+   prompt stops `candidates.ts` from rejecting narrower-window models with
+   `context_too_small`, which today silently shrinks the pool as a conversation
+   grows), and
+2. per-turn **spend drops** on the 100k-token loops we actually observe (glm-5.3-flash
+   routinely serves turns at 67k–105k prompt tokens; the bulk is re-sent every turn).
+
+A smaller haystack is also a mild mitigation for the weak-model loop failure
+(fewer tokens for a cheap model to lose the thread in), but that is a side effect,
+not the objective.
+
+## Non-goals
+
+- Not a replacement for tier escalation on runaway loops (tracked separately).
+- Not summarizing or dropping the user's actual current intent or recent turns.
+- Not a lossy digest of the whole conversation (see Phase 2 for bounded, pinned
+  summarization; rolling whole-history digests are explicitly rejected — a coding
+  agent lives on exact tool state).
+
+## Motivation (observed)
+
+From the live ledger (post-restart window):
+
+- Prompts of 67k–105k tokens are normal on deep loops; the dominant mass is tool
+  results (file reads, `bash`/grep dumps) that the model already consumed turns ago.
+- Loops reach tool-loop depth 200+ on cheap tiers, re-sending the full transcript
+  each turn.
+- `context_too_small` rejections remove otherwise-good models from long
+  conversations, forcing escalation or pool exhaustion on model switches.
+
+## Constraints and invariants (from the codebase)
+
+These are hard; the design is shaped by them.
+
+- **Single hook.** `renderUpstreamBody` (`src/wire/openai/request.ts`) owns the exact
+  bytes sent upstream via `structuredClone(original)`. `NormMessage`
+  (`src/wire/types.ts`) is explicitly a *lossy* view "never dispatched." Compaction
+  therefore **decides** using `NormMessage` per-index metadata (`role`, `textBytes`,
+  `images`, `toolCalls`, `toolCallId`, `toolName`) and **applies** edits to the raw
+  original messages by index.
+- **Tool-call pairing is load-bearing.** Every `role:"tool"` message must keep its
+  matching `assistant` `tool_call` id, or OpenRouter rejects the request (400).
+  Compaction may shrink a tool **result's content**, but must never remove a tool
+  result without its call, nor an assistant tool_call without its result, nor
+  reorder the pair.
+- **Never touch:** system/developer messages (they carry the system prompt and the
+  agentdox-injected block), the **volatile tail** (newest user-authored run, or the
+  trailing tool-result run of the current loop — the same window
+  `features.ts`/`cache-control.ts` treat as fresh), and image parts (they are
+  capability-relevant; see Edge cases).
+- **Determinism.** `auto-model-router explain` replays a past decision offline.
+  Phase 1 is a pure function of `(messages, target budget, model window)` →
+  replayable. Phase 2 breaks this unless the summary is **pinned and persisted**
+  (see Phase 2), exactly as the agentdox bridge already does.
+- **Prompt cache.** Editing early messages busts the OpenRouter prompt-cache prefix.
+  The governing law is already stated for the agentdox bridge
+  (`src/context/bridge.ts`): *the same bytes are re-injected verbatim and the cache
+  survives; a refresh rides on a cache miss that was happening anyway.* Compaction
+  obeys it — Phase 1 rules are **stable** (identical input → identical elision each
+  turn), so a message elided last turn is elided byte-identically this turn and the
+  prefix does not churn; Phase 2 summaries are pinned per conversation and refreshed
+  only when the cache is already cold.
+
+## Precedent to reuse
+
+The agentdox bridge (`src/context/`) already manipulates context under exactly these
+constraints: content-addressed blocks in `context_blocks`, a per-conversation
+version in `conversations.context_version`, cache-cold-only refresh, and graceful
+degradation to a no-op when unavailable. Phase 2 mirrors this machinery.
+
+## Pipeline placement
+
+Compaction follows the codebase's existing division of labour: **the core computes a
+plan; the wire applies bytes.** `cacheBreakpointMessageIndices` and the agentdox
+`contextBlock` are already computed during routing / in `turn.ts` and applied inside
+`renderUpstreamBody`. Compaction is the same shape: a **`compactionPlan`** on the
+`Decision` (which tool-result indices to shrink, and to what head/tail), computed
+during routing, applied in `renderUpstreamBody`.
+
+```
+request → classify (on ORIGINAL turn)
+       → compute compaction FLOOR (model-agnostic safe elision when over budget)
+           recomputes compactedPromptTokens
+       → candidate selection + forecast        ← use compactedPromptTokens
+           context_too_small filter uses the FLOOR, so a narrow-window model is
+           not rejected when safe compaction would make it fit
+       → chosen model known → finalize compactionPlan (fit trigger may extend it)
+       → renderUpstreamBody:
+           clone → APPLY compactionPlan (shrink tool-result content)
+                 → stripAssistantReasoning
+                 → injectContextBlock (agentdox, appends to last system msg)
+                 → apply cache_control at breakpoint indices
+       → dispatch
+```
+
+- **Classification runs on the original turn.** Compacting old tool output must not
+  change the tier: the human's intent and the loop/continuation structure are
+  unchanged. `promptTokens` shrinks, but the tier scorer keys on the tail
+  (`isToolResultContinuation`, `toolLoopDepth`, `newContentTokens`), so the effect
+  is negligible and intentionally not fed back into scoring.
+- **Selection and forecast use `compactedPromptTokens`** so spend predictions and the
+  `context_too_small` filter reflect what is really sent — restoring narrower-window
+  models that fit *after* safe compaction. A model rejected against the floor is
+  genuinely too small (even max-safe compaction cannot fit it) and is correctly dropped.
+- **Breakpoint indices are NOT recomputed for Phase 1.** They are computed in
+  `select()` on the original array and adjusted by `injectContextBlock`. Because
+  Phase 1 shrinks *content only* (never adds or removes a message), every index stays
+  valid — the same reason `injectContextBlock` appends instead of inserts. Phase 2,
+  which changes message count, MUST return adjusted indices (see Phase 2).
+
+## Trigger (locked: fit + cost budget)
+
+Two conditions arm compaction; both compact to the same safe floor, they differ only
+in *whether* to bother:
+
+- **Budget:** `estimateTokens(promptBytes + injectedBlockBytes) > compaction.budgetTokens`.
+  The injected agentdox block counts toward the budget (it is resolved before render
+  and bounded by `context.maxBlockChars`).
+- **Fit:** the estimate exceeds `model.contextLength × filters.contextHeadroom` (minus
+  expected completion) for a model under consideration — so the `context_too_small`
+  filter tests each model against the compacted floor rather than the raw size.
+
+Requests below `budgetTokens` and within every viable window are dispatched untouched —
+the common small-prompt path allocates nothing.
+
+## Interaction with the agentdox bridge
+
+The router already has a shipped context subsystem (`src/context/`, see
+`docs/AGENTDOX-BRIDGE.md`). Compaction must cooperate with it, not fight it.
+
+- **Complementary regions.** agentdox *adds* a pinned project-context block to the
+  system prefix (`injectContextBlock` appends to the last system message); compaction
+  *shrinks* stale tool-result content in the history. Different regions — they compose.
+- **Same cache law, one cold turn.** `bridge.ts shouldRefresh` fires on
+  `pin === null || modelSwitching || retrying || staleness`. Phase 2's summary refresh
+  MUST key off the same signals (already carried on `ContextResolveInput`) so the block
+  refresh and the summary refresh land on the *same* cache miss — "the refresh rides a
+  miss that was happening anyway," once, for both mutations.
+- **Never touch the injected block.** It lives in a system message, which the safety
+  boundary already excludes. Reaffirmed.
+- **Budget includes the block.** See Trigger.
+- **Apply order in `renderUpstreamBody`:** clone → apply `compactionPlan` → strip
+  reasoning → `injectContextBlock` → cache_control. Phase 1 preserves message
+  count/order, so `injectContextBlock`'s breakpoint bookkeeping is unaffected.
+- **Write-back is orthogonal.** agentdox records user+assistant prose, not tool
+  results, so compacting tool output does not degrade the recorded transcript. (The
+  bridge's open write-back bug, AGENTDOX-BRIDGE §5, is unrelated.)
+- **Phase 3 synergy (flag only, not committed):** agentdox durably stores project
+  memory/history, so elided tool content could eventually be recoverable from project
+  memory rather than solely by re-running the tool.
+
+## Phase 1 — deterministic pruning (build target)
+
+A pure function `compact(messages, target, protectFrom) → { messages, saved, notes }`.
+
+### Safety boundary
+
+- `protectRecentTurns` (default 4): the last N user/assistant turns and the entire
+  volatile tail are never modified.
+- System/developer messages are never modified.
+- A message is never **removed**; only a tool **result's content** is shortened.
+  Structure (roles, ordering, tool_call↔result ids) is invariant.
+
+### Rules, applied cheapest-and-safest first, stopping once under `target`
+
+1. **Collapse duplicates** (`collapseDuplicateResults`): byte-identical tool results
+   for the same `toolName` → keep the first occurrence, replace later copies with a
+   one-line breadcrumb.
+2. **Elide superseded reads** (`elideSupersededReads`): when the same resource is
+   fetched twice (same `toolName` + same primary argument, e.g. a `path`/`key`
+   parsed from the tool_call args JSON — schema-agnostic heuristic), the **older**
+   result's content is elided down to a breadcrumb pointing forward. The latest
+   fetch is authoritative.
+3. **Truncate large stale results** (`maxToolResultBytes`): remaining tool results
+   outside the protected window whose content exceeds `maxToolResultBytes` are
+   reduced to `keepHeadBytes` + breadcrumb + `keepTailBytes`. Applied to the
+   **largest/oldest first** until under `target` or exhausted.
+4. **Age-drop assistant reasoning:** reasoning fields on assistant messages outside
+   the protected window are dropped. (Largely redundant with the model-driven
+   `stripAssistantReasoning`; matters only for reasoning-replay authors.)
+
+### Recoverability contract (the single most important safety rule)
+
+Elisions are **never silent**. Every elision leaves a self-describing, in-band
+breadcrumb in the tool result content, e.g.:
+
+```
+[omp-router: elided 1180 of 1200 lines to save context. Re-run this tool to restore.]
+<first keepHeadBytes…>
+…
+<last keepTailBytes…>
+```
+
+This converts a hard context loss into a **recoverable** one: if the model actually
+needs the elided content, it re-issues the tool call and the fresh full result
+returns (uncompacted, because it is now in the protected recent window). A rising
+"re-fetch after elision" rate is the tuning signal that compaction is too
+aggressive.
+
+### Idempotence / stability
+
+Because omp re-sends the full original history every turn, Phase 1 re-derives the
+same elisions deterministically each turn → the dispatched prefix is byte-identical
+turn-over-turn → the prompt cache survives without pinning.
+
+## Observability
+
+- `decision.reasons` gains a line, e.g.
+  `compaction: 6 tool results elided, ~38k tokens saved (prompt 104k→66k)`, surfaced
+  by `explain` and the toast extension.
+- Ledger migration (mirrors the `v7`/`v8` additive pattern in `src/util/sqlite.ts`):
+  add `prompt_tokens_saved INTEGER` (and optionally `messages_elided INTEGER`) so
+  savings, re-fetch rate, and any upstream 400s can be measured and tuned.
+
+## Configuration (proposed; off by default)
+
+A new top-level `compaction` section (distinct from `cache` and the agentdox
+`context`). Off by default — like every behavior-changing feature here, it is never
+implicit.
+
+```yaml
+compaction:
+  enabled: false
+  # Trigger
+  budgetTokens: 40000        # Stage 1: compact when estimated prompt exceeds this
+  fitToWindow: true          # Stage 2: also compact to fit chosen model window×headroom
+  # Safety boundary
+  protectRecentTurns: 4      # never touch the last N user/assistant turns or the tail
+  # Rules
+  maxToolResultBytes: 4096   # stale tool results larger than this are truncated
+  keepHeadBytes: 512
+  keepTailBytes: 512
+  elideSupersededReads: true
+  collapseDuplicateResults: true
+  # Phase 2 (documented, not built)
+  summarize:
+    enabled: false
+    model: ""                # cheap summarizer slug; empty ⇒ Phase 1 only
+    triggerTokens: 80000     # only after Phase-1 rules, still above this
+    maxSummaryTokens: 2000
+```
+
+Schema lands in `src/config/schema.ts` (a `z.strictObject`, all fields optional),
+types in `src/config/types.ts`, defaults in `src/config/defaults.ts`, and — per the
+existing pattern — a small set of fields in the config wizard (`src/cli/config-wizard.ts`).
+
+## Testing strategy
+
+Unit (`test/compaction.test.ts`):
+- tool_call↔result pairing preserved after every rule;
+- breadcrumb present and content non-empty after truncation;
+- deterministic + idempotent (compact(compact(x)) == compact(x) for stable input);
+- `target` respected (result ≤ budget when achievable) and never over-shrinks the
+  protected window;
+- superseded-read detection matches same-resource, spares different resources;
+- images/multimodal parts are never elided.
+
+Integration (extend `test/select.test.ts` / a new fixture):
+- a 100k-token fixture compacts under `budgetTokens`;
+- a narrow-window model that was `context_too_small` becomes eligible after Stage 1;
+- `explain` replays byte-identical dispatched messages for the same input.
+
+## Rollout
+
+1. Ship Phase 1 off by default.
+2. Enable **budget-only** first (`fitToWindow: false`) on the live install; watch
+   `prompt_tokens_saved`, re-fetch rate, upstream 400s (pairing regressions), and
+   loop/abort rates.
+3. Enable `fitToWindow` once pairing is proven clean.
+4. Reassess Phase 2 only if prose-heavy history (not tool output) is still the
+   dominant residual cost after Phase 1.
+
+### Testing & deployment gotchas (from AGENTDOX-BRIDGE §3–4, §6)
+
+Verifying compaction *through omp* hits the same traps that cost hours on the bridge:
+
+- **Headless omp does not bind its own router.** `omp -p` reads
+  `$AUTO_MODEL_ROUTER_HOME/embed.port` and routes to whatever router already holds
+  that port — possibly stale code. To test *this* build, point `embed.port` at your
+  standalone `serve` and restore it after.
+- **Windows port-kill:** `pkill -f "src/index.ts serve"` does not work in Git Bash;
+  free the port via `Get-NetTCPConnection -LocalPort <p> -State Listen` →
+  `Stop-Process -Force`.
+- **Multiple installed copies exist** (repo, marketplace cache, global npm). This is
+  the same reason the deep-loop scorer fix "never landed" live. Before trusting any
+  compaction e2e result, confirm which router process is actually serving.
+- Use `AUTO_MODEL_ROUTER_DB=<scratch>.db` so tests never touch the live ledger.
+
+## Phase 2 — pinned, persisted LLM summarization (documented, not built)
+
+Phase 1 cannot safely compress genuinely-needed long **prose** (dense reasoning,
+multi-turn design discussion). Phase 2 adds bounded summarization, gated behind
+Phase 1 and behind the same cache/determinism discipline the agentdox bridge uses.
+
+### Mechanism
+
+- Runs only when, **after** Phase-1 rules, the estimate still exceeds
+  `summarize.triggerTokens`.
+- Summarizes the **oldest** compactable region (from just after the system/injected
+  block up to the edge of the protected window) into a single bounded note
+  (`maxSummaryTokens`), produced by `summarize.model` (a cheap slug).
+- The note **replaces** that region's messages; tool_call↔result pairs inside the
+  region are summarized as facts ("read src/foo.ts (480 lines); edited lines 12–20"),
+  never left dangling.
+
+### Determinism and cache — restored by pinning (the agentdox pattern)
+
+- The summary is **content-addressed** (hash of the covered region) and **persisted**
+  in a new `compaction_summaries` table, with the active version pinned on the
+  conversation row (a `compaction_version` column, alongside `context_version`).
+- Subsequent turns re-inject the **same** summary bytes verbatim → cache-stable and
+  `explain`-replayable (replay reads the pinned summary from the store; it never
+  re-summarizes).
+- The summary is refreshed (recomputed to cover more history) **only when the cache
+  is already cold**, reusing the *same* cold-turn signal as `bridge.ts shouldRefresh`
+  (`pin === null || modelSwitching || retrying || staleness`) so the agentdox block
+  refresh and the summary refresh share one cache miss rather than each causing their own.
+- **Breakpoint indices are adjusted, not stale.** A summary that replaces a message
+  range changes message count, so — exactly like `injectContextBlock` does when it
+  prepends a system message — Phase 2 returns adjusted `cacheBreakpointMessageIndices`
+  (shift the trailing indices by the count delta), or recomputes them on the collapsed
+  array. This is the one place Phase-1's "indices stay valid" guarantee does not hold.
+
+### Degradation
+
+Summarization is enrichment, not a dependency: if the summarizer errors, times out,
+or is unconfigured, the turn falls back to Phase-1 output and dispatches normally —
+mirroring the agentdox bridge's "degrade to null, never throw" contract.
+
+### Risks and mitigations
+
+- **A bad pinned summary persists** and poisons later turns → versioned + hashed so it
+  can be invalidated; never covers the protected recent window or tool structure;
+  Phase-1 breadcrumbs remain, so the model can still re-fetch elided specifics.
+- **Detail loss induces re-derivation loops** → summaries state actions and outcomes,
+  never replace the *latest* authoritative tool results; recent window is untouched.
+- **Added latency/cost** on the compute turn → amortized by pinning + cache-cold-only
+  refresh.
+
+## Open questions
+
+- Primary-argument extraction for superseded-read detection across arbitrary tool
+  schemas (heuristic: first string arg that looks like a path/id; configurable
+  per-tool later if needed).
+- Token-estimate accuracy at the budget boundary (uses `estimateTokens` +
+  `token_calibration`; acceptable — the budget is a soft threshold, not a hard limit).
+- Protocol coverage: OpenAI wire (`src/wire/openai/`) first; other protocols reuse the
+  same `compact()` core behind their own `renderUpstreamBody`.
+- Interaction with `forcedToolChoice` turns (rare; compaction of history is still
+  safe, but verify the forced call is in the protected window).
+```

package/omp-extension/embed-logic.ts

@@ -52,6 +52,30 @@ export interface EmbedConfig {
 	baseUrl: string;
 	models: EmbedModelSpec[];
 	harnessId?: string;
+	/**
+	 * agentdox project scope sent as `X-Agentdox-Scope`. Selects which
+	 * project's shared context is injected into every turn, so switching
+	 * models never loses the project's memory/docs/brief.
+	 */
+	agentdoxScope?: string;
+}
+
+/**
+ * Derives an agentdox project slug from the omp workspace directory.
+ *
+ * The workspace basename is the one identifier that is already stable, already
+ * per-project, and requires no configuration — the same convention agentdox's
+ * own `project_ensure` slugs follow. An explicitly configured
+ * `context.defaultScope` always wins over this.
+ */
+export function deriveAgentdoxScope(cwd: string): string {
+	// Both separators: omp reports a Windows cwd with backslashes.
+	const cleaned = cwd.replace(/[\\/]+$/, "");
+	const base = cleaned.split(/[\\/]/).pop() ?? "";
+	return base
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "-")
+		.replace(/^-+|-+$/g, "");
 }
 
 /**
@@ -113,7 +137,10 @@ export function buildProviderConfig(
 		server: { host: string; harnessId?: string };
 		profiles: Array<{ id: string; name: string; contextWindow: number; maxTokens: number }>;
 		ledger: { fallbackBlend: { inputPerMtok: number; outputPerMtok: number } };
+		context?: { enabled: boolean; defaultScope: string };
 	},
+	/** omp's workspace directory, used to derive a scope when none is configured. */
+	cwd?: string,
 ): EmbedConfig {
 	const host = cfg.server.host === "0.0.0.0" || cfg.server.host === "::" ? "127.0.0.1" : cfg.server.host;
 	const round = (v: number): number => Math.round(v * 1e4) / 1e4;
@@ -137,5 +164,9 @@ export function buildProviderConfig(
 	if (cfg.server.harnessId !== undefined && cfg.server.harnessId !== "") {
 		out.harnessId = cfg.server.harnessId;
 	}
+	if (cfg.context?.enabled === true) {
+		const scope = cfg.context.defaultScope !== "" ? cfg.context.defaultScope : deriveAgentdoxScope(cwd ?? "");
+		if (scope !== "") out.agentdoxScope = scope;
+	}
 	return out;
 }

package/omp-extension/router-embed.ts

@@ -44,7 +44,9 @@ import {
  * registry at a specific bound port.
  */
 function registerRouterProvider(pi: ExtensionAPI, port: number, cfg: RouterConfig, sessionId: string): void {
-	const providerConfig = buildProviderConfig(port, cfg);
+	// cwd is omp's workspace, which is what the agentdox scope is derived from
+	// when none is configured explicitly.
+	const providerConfig = buildProviderConfig(port, cfg, process.cwd());
 	const headers: Record<string, string> = {};
 	if (providerConfig.harnessId !== undefined && providerConfig.harnessId !== "") {
 		headers["X-Omp-Harness"] = providerConfig.harnessId;
@@ -52,6 +54,10 @@ function registerRouterProvider(pi: ExtensionAPI, port: number, cfg: RouterConfi
 	// Per-session scoping: lets the toast surface only this session's decisions
 	// even when several omp sessions share one embedded router's ledger.
 	if (sessionId !== "") headers["X-Omp-Session"] = sessionId;
+	// Which agentdox project's shared context this workspace's turns draw on.
+	if (providerConfig.agentdoxScope !== undefined && providerConfig.agentdoxScope !== "") {
+		headers["X-Agentdox-Scope"] = providerConfig.agentdoxScope;
+	}
 	pi.registerProvider(EMBED_PROVIDER_ID, {
 		baseUrl: providerConfig.baseUrl,
 		api: "openai-completions",

package/package.json

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

package/src/cli/config-cmd.ts

@@ -57,6 +57,22 @@ export interface SpliceResult {
  * `cost` is in omp's units: USD per MILLION tokens. The catalog works in
  * per-token rates, so everything is scaled by 1e6 exactly once, here.
  */
+/**
+ * Headers omp attaches to every request through this provider. Both are
+ * optional: absent harness id ⇒ single-harness defaults, absent agentdox scope
+ * ⇒ the router falls back to its own `context.defaultScope`.
+ */
+function providerHeaders(cfg: RouterConfig): Record<string, string> {
+	const headers: Record<string, string> = {};
+	if (cfg.server.harnessId !== undefined && cfg.server.harnessId !== "") {
+		headers["X-Omp-Harness"] = cfg.server.harnessId;
+	}
+	if (cfg.context.enabled && cfg.context.defaultScope !== "") {
+		headers["X-Agentdox-Scope"] = cfg.context.defaultScope;
+	}
+	return headers;
+}
+
 export function renderProviderBlock(cfg: RouterConfig, blend: BlendedRate | null): string {
 	const input = blend?.inputPerMtok ?? cfg.ledger.fallbackBlend.inputPerMtok;
 	const output = blend?.outputPerMtok ?? cfg.ledger.fallbackBlend.outputPerMtok;
@@ -71,11 +87,10 @@ export function renderProviderBlock(cfg: RouterConfig, blend: BlendedRate | null
 			baseUrl: `http://${host}:${cfg.server.port}/v1`,
 			api: "openai-completions",
 			auth: "none",
-			// When a harness id is configured, tag every request so the router can
-			// scope daily budgets and toasts per harness.
-			...(cfg.server.harnessId !== undefined && cfg.server.harnessId !== ""
-				? { headers: { "X-Omp-Harness": cfg.server.harnessId } }
-				: {}),
+			// Per-request tags. Harness id scopes daily budgets and toasts;
+			// agentdox scope selects which project's shared context is injected
+			// and which project's sessions the turns are recorded into.
+			...(Object.keys(providerHeaders(cfg)).length > 0 ? { headers: providerHeaders(cfg) } : {}),
 			models: cfg.profiles.map((p) => ({
 				id: p.id,
 				name: p.name,

package/src/cli/explain.ts

@@ -38,6 +38,7 @@ const ALWAYS_SHOW: Record<string, true> = {
 	toolLoopDepth: true,
 	lastToolFailed: true,
 	repeatedToolCall: true,
+	circularToolCall: true,
 	turnDepth: true,
 };
 

package/src/config/defaults.ts

@@ -69,9 +69,13 @@ export const DEFAULT_CONFIG: RouterConfig = {
 		trustScopedByHarness: false,
 		contextHeadroom: 1.25,
 		// Latency scoring is off by default (weight 0): opt in after establishing a
-		// baseline. TTFT above the reference inflates a model's effective cost.
+		// baseline. Expected total wait (TTFT + expected completion / throughput)
+		// above the references inflates a model's effective cost.
 		latencyWeight: 0,
 		latencyReferenceMs: 5000,
+		// 30 tok/s: below this a model streams noticeably slowly. Only genuinely
+		// slow models (e.g. deepseek-v4-flash ~20 tok/s) fall under it.
+		latencyReferenceTokensPerSec: 30,
 		latencyMinSamples: 20,
 	},
 	classifier: {
@@ -141,6 +145,34 @@ export const DEFAULT_CONFIG: RouterConfig = {
 		maxBreakpoints: 4,
 		minPromptTokens: 2_048,
 	},
+	context: {
+		// Off until an agentdox URL + token are configured. Enabling this changes
+		// what every model sees, so it is never implicit.
+		enabled: false,
+		baseUrl: "",
+		token: "",
+		defaultScope: "",
+		timeoutMs: 3_000,
+		// Matches agentdox's own auto-context job cadence (900s): refreshing
+		// faster than the server reassembles buys nothing but cache misses.
+		maxStalenessMs: 900_000,
+		maxBlockChars: 24_000,
+		recordTurns: true,
+		maxQueue: 64,
+	},
+	compaction: {
+		// Off by default: shrinking context is behavior-changing, never implicit.
+		enabled: false,
+		// ~40k tokens: above this the prompt is dominated by re-sent tool output.
+		budgetTokens: 40_000,
+		fitToWindow: true,
+		protectRecentTurns: 4,
+		maxToolResultBytes: 4_096,
+		keepHeadBytes: 512,
+		keepTailBytes: 512,
+		elideSupersededReads: true,
+		collapseDuplicateResults: true,
+	},
 	budget: {
 		// No caps by default; at a configured ceiling, downgrade rather than fail.
 		onExceeded: "downgrade",

package/src/config/load.ts

@@ -108,6 +108,19 @@ export function loadConfig(opts?: { path?: string; overrides?: Partial<RouterCon
 	}
 	const envDb = process.env.AUTO_MODEL_ROUTER_DB;
 	if (envDb !== undefined && envDb !== "") putSection("ledger", "path", envDb);
+
+	// agentdox bridge. A URL + token are enough to turn it on: requiring
+	// `context.enabled` in a config file as well would make the common case
+	// (export two vars, restart) silently do nothing.
+	const envDoxUrl = process.env.AGENTDOX_URL;
+	const envDoxToken = process.env.AGENTDOX_TOKEN;
+	const envDoxScope = process.env.AGENTDOX_SCOPE;
+	if (envDoxUrl !== undefined && envDoxUrl !== "") putSection("context", "baseUrl", envDoxUrl);
+	if (envDoxToken !== undefined && envDoxToken !== "") putSection("context", "token", envDoxToken);
+	if (envDoxScope !== undefined && envDoxScope !== "") putSection("context", "defaultScope", envDoxScope);
+	if (envDoxUrl !== undefined && envDoxUrl !== "" && envDoxToken !== undefined && envDoxToken !== "") {
+		putSection("context", "enabled", true);
+	}
 	cfg = deepMerge(cfg, envInput);
 
 	// Explicit programmatic overrides win last.

package/src/config/schema.ts

@@ -67,6 +67,7 @@ const filters = z.strictObject({
 	contextHeadroom: z.number().positive().optional(),
 	latencyWeight: z.number().nonnegative().optional(),
 	latencyReferenceMs: z.number().positive().optional(),
+	latencyReferenceTokensPerSec: z.number().positive().optional(),
 	latencyMinSamples: z.number().int().nonnegative().optional(),
 });
 
@@ -128,6 +129,30 @@ const cache = z.strictObject({
 	minPromptTokens: z.number().int().nonnegative().optional(),
 });
 
+const context = z.strictObject({
+	enabled: z.boolean().optional(),
+	baseUrl: z.string().optional(),
+	token: z.string().optional(),
+	defaultScope: z.string().optional(),
+	timeoutMs: z.number().int().positive().optional(),
+	maxStalenessMs: z.number().int().nonnegative().optional(),
+	maxBlockChars: z.number().int().positive().optional(),
+	recordTurns: z.boolean().optional(),
+	maxQueue: z.number().int().positive().optional(),
+});
+
+const compaction = z.strictObject({
+	enabled: z.boolean().optional(),
+	budgetTokens: z.number().int().positive().optional(),
+	fitToWindow: z.boolean().optional(),
+	protectRecentTurns: z.number().int().positive().optional(),
+	maxToolResultBytes: z.number().int().positive().optional(),
+	keepHeadBytes: z.number().int().nonnegative().optional(),
+	keepTailBytes: z.number().int().nonnegative().optional(),
+	elideSupersededReads: z.boolean().optional(),
+	collapseDuplicateResults: z.boolean().optional(),
+});
+
 const budget = z.strictObject({
 	perTurnUsd: z.number().nonnegative().optional(),
 	perConversationUsd: z.number().nonnegative().optional(),
@@ -187,6 +212,8 @@ export const configInputSchema = z.strictObject({
 	hysteresis: hysteresis.optional(),
 	exploration: exploration.optional(),
 	cache: cache.optional(),
+	context: context.optional(),
+	compaction: compaction.optional(),
 	budget: budget.optional(),
 	profiles: z.array(profile).optional(),
 	ledger: ledger.optional(),