feat: add Auto Router for per-task model selection

Adds an optional "Auto (smart routing)" picker entry (slug codex-auto) that
routes each Codex task to the cheapest configured model that can handle it. A
cheap classifier model scores every candidate 0.0-1.0 from a capability card;
the shim picks the cheapest candidate whose score clears a threshold (default
0.7), caches the decision per task, and falls back safely on any error so a
request never breaks. The classifier never sees price, so it can't be biased
toward expensive models.

- codex_shim/router.py: config loading, task-signal extraction, classifier
  prompt, score parsing, cheapest-among-viable selection, per-task cache.
- server.py: applies the router on /v1/responses, /v1/responses/compact, and
  /v1/chat/completions; runs the classifier over the configured backend; gates
  the virtual model in /v1/models, /api/models, /health, and the picker.
- catalog.py + cli.py: catalog entry and `codex-shim list`/`model use` support.
- Configured via an optional `router` block in ~/.codex-shim/models.json. Env
  knobs: CODEX_SHIM_DISABLE_ROUTER, CODEX_SHIM_ROUTER_TIMEOUT,
  CODEX_SHIM_ROUTER_MAX_TOKENS, CODEX_SHIM_ROUTER_LOG.
- docs/AUTO_ROUTER.md, README section, and a runnable offline proof at
  examples/auto_router_demo.py.

Verification:
- python3 -m pytest tests/ -q  (113 passed)
- python3 -m compileall codex_shim/ examples/ -q
- python3 examples/auto_router_demo.py  (RESULT: PASS)

Generated with [Devin](https://cli.devin.ai/docs)

Author: terp

CHANGELOG.md

@@ -9,6 +9,18 @@ and this project does not yet follow semantic versioning (pre-1.0).
 
 ### Added
 
+- Auto Router (`codex_shim/router.py`): an optional `Auto (smart routing)` picker
+  entry (slug `codex-auto`) that routes each task to the cheapest configured
+  model that can handle it. A cheap classifier model scores every candidate
+  `0.0–1.0` from a capability card, the shim picks the cheapest candidate whose
+  score clears `threshold` (default `0.7`), caches the decision per task, and
+  falls back safely on any error. Configured via an optional `router` block in
+  `~/.codex-shim/models.json`; gated in `/health`, `/v1/models`, `/api/models`,
+  the generated catalog, and `codex-shim list`. Env knobs:
+  `CODEX_SHIM_DISABLE_ROUTER`, `CODEX_SHIM_ROUTER_TIMEOUT`,
+  `CODEX_SHIM_ROUTER_MAX_TOKENS`, `CODEX_SHIM_ROUTER_LOG`. Documented in
+  `docs/AUTO_ROUTER.md` with a runnable offline proof at
+  `examples/auto_router_demo.py`.
 - Cursor/Composer subscription passthrough for slug `composer-2-5`. When
   `cursor-agent login` is active, the shim spawns `cursor-agent --print` with
   CLI OAuth (no Dashboard API key). The slug is auth-gated in `/health`,

README.md

@@ -39,6 +39,10 @@ local:
   exposes `composer-2-5` and routes through your Cursor subscription — no
   Dashboard API key (`crsr_…`) required. See
   [`docs/subscription-integration.md`](docs/subscription-integration.md).
+- **Auto Router (optional).** Add an `Auto (smart routing)` picker entry that
+  uses a cheap classifier model to route each task to the cheapest configured
+  model that can handle it — trivial turns stay cheap, hard turns escalate. See
+  [`docs/AUTO_ROUTER.md`](docs/AUTO_ROUTER.md).
 - **Prompt-catching/proxy-friendly architecture.** Put a local proxy in front
   of the shim to dedupe boilerplate, inject stable instructions, repair
   pseudo-tool text, or route prompts by policy before they hit an upstream.
@@ -564,6 +568,53 @@ GLM, etc.) round-trip through `reasoning.encrypted_content` items.
 
 ---
 
+## Auto Router (smart routing)
+
+Optionally add one extra picker entry — **`Auto (smart routing)`** (slug
+`codex-auto`) — that chooses the right model *per task*: trivial turns go to a
+cheap model, hard turns escalate to your strongest one. It runs entirely on the
+models you already configure.
+
+On each new task the shim asks a cheap **classifier** model you nominate to score
+every candidate `0.0–1.0` (how likely it nails the task first try), reading a
+short **capability card** per candidate. It then routes to the **cheapest
+candidate whose score clears `threshold`** (default `0.7`), caches that decision
+for the task's tool-call round-trips, and falls back safely on any error. The
+classifier never sees price, so it can't be biased toward expensive models.
+
+Turn it on by adding a `router` block to `~/.codex-shim/models.json`:
+
+```jsonc
+"router": {
+  "enabled": true,
+  "slug": "codex-auto",
+  "classifier": "minimax-m3",        // slug of a cheap configured model
+  "threshold": 0.7,
+  "default": "minimax-m3",
+  "cache": true,
+  "candidates": [
+    { "slug": "minimax-m3", "cost": 0.3, "supports_images": false,
+      "card": "Cheap, fast. Single-file edits, codegen, simple refactors." },
+    { "slug": "opus", "cost": 5.0, "supports_images": true,
+      "card": "Frontier. Big multi-file refactors, hard debugging, images." }
+  ]
+}
+```
+
+Prove it end to end with no keys and no network:
+
+```bash
+python3 examples/auto_router_demo.py
+```
+
+It spins up a mock multi-backend server, starts the **real** shim with the router
+on, and shows trivial→cheap, medium→mid, hard→strong, image→image-capable, and a
+repeat served from cache. Full configuration, env knobs (`CODEX_SHIM_ROUTER_LOG`,
+`CODEX_SHIM_DISABLE_ROUTER`, …), and failure behavior are in
+[`docs/AUTO_ROUTER.md`](docs/AUTO_ROUTER.md).
+
+---
+
 ## Tool calls and agent loops
 
 Codex expects Responses-API output items. Most BYOK upstreams speak either

codex_shim/catalog.py

@@ -3,10 +3,12 @@
 import json
 from pathlib import Path
 
+from . import router as router_module
 from .settings import (
     CHATGPT_MODEL_SLUG,
     PROVIDER_NAME,
     ShimModel,
+    available_model_slugs,
     chatgpt_passthrough_available,
     default_model_slug,
     load_chatgpt_passthrough_catalog_models,
@@ -94,9 +96,11 @@ def chatgpt_passthrough_entry() -> dict:
     return chatgpt_passthrough_entries()[0]
 
 
-def write_catalog(models: list[ShimModel], path: Path) -> Path:
+def write_catalog(models: list[ShimModel], path: Path, router_config=None) -> Path:
     path.parent.mkdir(parents=True, exist_ok=True)
     entries: list[dict] = []
+    if router_config is not None and router_module.router_is_active(router_config, available_model_slugs(models)):
+        entries.append(router_module.router_catalog_entry(router_config))
     if chatgpt_passthrough_available():
         entries.extend(chatgpt_passthrough_entries())
     if cursor_passthrough_available():

codex_shim/cli.py

@@ -14,6 +14,7 @@
 import struct
 from urllib.request import urlopen
 
+from . import router as router_module
 from .catalog import _toml_escape, codex_config_overrides, write_catalog, write_config
 from .cursor_passthrough import (
     cursor_passthrough_available,
@@ -27,6 +28,7 @@
     DEFAULT_PORT,
     PROVIDER_NAME,
     ModelSettings,
+    available_model_slugs,
     chatgpt_passthrough_available,
     chatgpt_passthrough_display_names,
     chatgpt_passthrough_slugs,
@@ -159,23 +161,35 @@ def _load_models(settings_path: Path):
         raise SystemExit(f"Settings file is not valid JSON: {expanded}: {exc}") from exc
 
 
+def _active_router(models, settings_path: Path):
+    """RouterConfig when the Auto Router is enabled and has a usable candidate."""
+    config = router_module.load_router_config(Path(settings_path).expanduser())
+    if config and router_module.router_is_active(config, available_model_slugs(models)):
+        return config
+    return None
+
+
 def generate(settings_path: Path, port: int) -> None:
     models = _load_models(settings_path)
     try:
         default_model_slug(models)
     except ValueError as exc:
         raise SystemExit(str(exc)) from exc
-    write_catalog(models, CATALOG_PATH)
+    router_config = router_module.load_router_config(Path(settings_path).expanduser())
+    write_catalog(models, CATALOG_PATH, router_config=router_config)
     write_config(models, CONFIG_PATH, CATALOG_PATH, port)
     print(f"Generated {len(models)} model entries:")
+    if _active_router(models, settings_path) is not None:
+        print(f"  auto router: {router_config.slug} ({router_config.display_name})")
     print(f"  catalog: {CATALOG_PATH}")
     print(f"  config:  {CONFIG_PATH}")
     print("No files under ~/.codex were modified.")
 
 
 def install_codex_config(settings_path: Path, port: int, model_slug: str | None = None) -> None:
     models = _load_models(settings_path)
-    default_slug = _resolve_model_slug(models, model_slug)
+    router_config = _active_router(models, settings_path)
+    default_slug = _resolve_model_slug(models, model_slug, router_config)
     CODEX_CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
     RUNTIME_DIR.mkdir(parents=True, exist_ok=True)
     original = CODEX_CONFIG_PATH.read_text() if CODEX_CONFIG_PATH.exists() else ""
@@ -189,7 +203,7 @@ def install_codex_config(settings_path: Path, port: int, model_slug: str | None
         previous_top_level = _extract_top_level_key_lines(CODEX_CONFIG_BACKUP_PATH.read_text(), MANAGED_TOP_LEVEL_KEYS)
     cleaned = _remove_top_level_keys(cleaned, MANAGED_TOP_LEVEL_KEYS)
     cleaned = _remove_section(cleaned, f"model_providers.{PROVIDER_NAME}")
-    provider_name = _provider_display_name(models, default_slug)
+    provider_name = _provider_display_name(models, default_slug, router_config)
     top_block, provider_block = _managed_config_blocks(
         default_slug, port, previous_top_level, provider_name=provider_name
     )
@@ -200,6 +214,9 @@ def install_codex_config(settings_path: Path, port: int, model_slug: str | None
 def list_models(settings_path: Path) -> int:
     models = _load_models(settings_path)
     rows: list[tuple[str, str, str, str]] = []
+    router_config = _active_router(models, settings_path)
+    if router_config is not None:
+        rows.append((router_config.slug, router_config.display_name, "per-task pick", "auto"))
     if chatgpt_passthrough_available():
         for slug, display_name in chatgpt_passthrough_display_names().items():
             rows.append((slug, display_name, slug, "chatgpt"))
@@ -611,7 +628,9 @@ def _foreground_codex_app() -> None:
         pass
 
 
-def _provider_display_name(models, slug: str) -> str:
+def _provider_display_name(models, slug: str, router_config=None) -> str:
+    if router_config is not None and slug == router_config.slug:
+        return router_config.display_name
     if chatgpt_passthrough_available():
         display_name = chatgpt_passthrough_display_names().get(slug)
         if display_name:
@@ -783,15 +802,17 @@ def _override_args(settings_path: Path, port: int) -> list[str]:
     return args
 
 
-def _resolve_model_slug(models, requested: str | None) -> str:
+def _resolve_model_slug(models, requested: str | None, router_config=None) -> str:
     if requested is None:
         current = _current_managed_model()
-        if current in _valid_model_slugs(models):
+        if current in _valid_model_slugs(models, router_config):
             return current
         try:
             return default_model_slug(models)
         except ValueError as exc:
             raise SystemExit(str(exc)) from exc
+    if router_config is not None and requested == router_config.slug:
+        return requested
     if is_chatgpt_passthrough_slug(requested):
         if not chatgpt_passthrough_available():
             raise SystemExit(
@@ -853,8 +874,10 @@ def _current_managed_model() -> str | None:
     return None
 
 
-def _valid_model_slugs(models) -> set[str]:
+def _valid_model_slugs(models, router_config=None) -> set[str]:
     slugs = {model.slug for model in usable_byok_models(models)}
+    if router_config is not None:
+        slugs.add(router_config.slug)
     if chatgpt_passthrough_available():
         slugs.update(chatgpt_passthrough_slugs())
     if cursor_passthrough_available():