coderouter-cli 2.17.0__tar.gz → 2.19.0__tar.gz

{coderouter_cli-2.17.0 → coderouter_cli-2.19.0}/CHANGELOG.md

@@ -9,6 +9,110 @@ are kept verbatim where the Japanese text itself is the subject).
 
 ---
 
+## [v2.19.0] — 2026-10-24 (OpenAI Responses API for the Codex CLI)
+
+### Added
+
+- **`POST /v1/responses`** — the OpenAI Responses API, so the current Codex
+  CLI (Responses-only since 2026-02) can use CodeRouter as a custom
+  provider (`wire_api = "responses"`, `base_url = http://127.0.0.1:8088/v1`;
+  see `docs/start/quickstart.md` Pattern B). The request is translated to an
+  Anthropic Messages request and runs through the same fallback engine as
+  `/v1/messages`, so fallback, tool-call repair, the guards, the TTFT
+  cut-off and the chain-failure error mapping all apply; the result is
+  translated back (`coderouter/translation/responses.py`). Built against
+  the wire contract in openai/codex `970111f` (2026-10-23):
+  - `developer` / `system` messages (Codex sends its system prompt as the
+    first `developer` input item, not `instructions`) become Anthropic
+    `system` text; `instructions` is honoured for other clients.
+  - Tools: `function` → `function_call` with a JSON-string `arguments`;
+    `custom` grammar tools such as `apply_patch` → `custom_tool_call` with
+    the raw `input` string (Codex rejects a `function_call` for those; the
+    grammar is passed to the model in the tool description); `namespace`
+    (MCP) tools are flattened per request and answered with `namespace` +
+    the inner `name`. Hosted tools (`web_search`, …) are dropped.
+  - History: `function_call` / `custom_tool_call` and their outputs become
+    `tool_use` / `tool_result`; orphan outputs are dropped and calls with no
+    output get a synthetic `"aborted"` result so the Anthropic pairing rules
+    hold. `reasoning` and hosted-tool items are dropped.
+  - Stream: `response.created` → per item `output_item.added` (text deltas
+    only inside an open item) → `output_item.done` → `response.completed`
+    with `response.id` and complete usage details (`cached_tokens`,
+    `reasoning_tokens`). `max_tokens` stops become `response.incomplete`
+    (`max_output_tokens`).
+  - Errors: pre-content failures get an OpenAI-style error body with a real
+    status (400 / 429 with `Retry-After`, which Codex needs to retry a 429 /
+    502). A context overflow on a streaming request — upstream overflow or
+    `context_budget_action: reject` — becomes `response.failed` with code
+    `context_length_exceeded`, the only overflow signal Codex recognizes. A
+    failure after the stream started is `response.failed` (`server_error`),
+    which Codex retries.
+  - Profile selection as on the other routes (body `profile` >
+    `X-CodeRouter-Profile` > `X-CodeRouter-Mode` > auto router > default);
+    Codex's `session-id` header feeds llama-server slot affinity.
+  - Non-streaming JSON responses are supported for other clients.
+  - Tool outputs that carry images (Codex `view_image`, MCP image results)
+    become image blocks, not base64 text. Usage reports OpenAI semantics —
+    `input_tokens` includes cache reads and writes — so Codex's
+    context-window accounting (and its auto-compaction) sees the real
+    prompt size. A stream that ends without `message_stop`, or with a block
+    still open, is reported as `response.failed` (retryable) rather than a
+    `response.completed` that would silently drop the partial item.
+    Flattened tool names are capped at 64 characters (hash suffix) for
+    strict OpenAI-compatible backends, and a custom-tool call whose
+    arguments hold a single string under another key still reaches
+    `apply_patch` as raw text.
+
+### Changed
+
+- Docs: quickstart Pattern B (ja/en) now configures Codex through
+  CodeRouter; README and the "do I need CodeRouter?" guide updated.
+
+### Known limits
+
+- Reasoning items are not produced or round-tripped; hosted tools are not
+  emulated; `previous_response_id` (server-side conversation state) is not
+  supported — Codex does not use it on HTTP.
+
+---
+
+## [v2.18.0] — 2026-10-24 (route on Claude Code's own request hints)
+
+### Added
+
+- **auto_router matchers on Claude Code's gateway hint headers.** With
+  `CLAUDE_CODE_GATEWAY_HINT_HEADERS=1` (Claude Code 2.1.273+), every request
+  says what it is. Three new `RuleMatcher` fields read those headers:
+  - `request_class` — `x-claude-code-request-class` (`main` / `subagent` /
+    `workflow` / `compaction` / `auxiliary`), case-insensitive;
+  - `agent_type` — `x-claude-code-agent-type` (e.g. `Explore`),
+    case-insensitive;
+  - `compaction: true` — `x-claude-code-compaction` is truthy (`false` is
+    rejected at load, like the other boolean matchers).
+  Typical use: auto-mode classifier / title calls (`auxiliary`) to the
+  smallest local model, compaction to a long-context profile, `Explore`
+  sub-agents to a fast one. Without the headers these matchers never match,
+  so existing rule sets behave exactly as before. `classify()` gained an
+  optional `hints` argument; both `/v1/messages` and `/v1/chat/completions`
+  pass the headers through. Docs: `docs/guides/subagent-routing.md` / `.en.md`.
+- **`slot_affinity_slots` (provider; llama.cpp only).** For
+  `llama-server --parallel N`: requests carrying a conversation key
+  (`x-claude-code-session-id`) get `id_slot = sha256(key) % N`, so every
+  turn of a conversation reuses the same slot's prompt cache instead of
+  re-prefilling on whichever slot is free. Stable across restarts; an
+  explicit `id_slot` in `extra_body` wins; off by default. Works on both the
+  native (`kind: anthropic`) and translated (`kind: openai_compat`) paths,
+  and survives every internal request rebuild (thinking strip for backends
+  without thinking, `tool_choice` emulation, `cache_control` strip,
+  OpenAI→Anthropic translation). The main conversation and its compaction
+  share a key; sub-agents and auxiliary calls get `<session>:<class>:<agent>`
+  so they do not queue on — or evict — the main conversation's slot.
+  Docs: `docs/backends/llamacpp-direct.md` / `.en.md`.
+- **`vscode-init` also writes `CLAUDE_CODE_GATEWAY_HINT_HEADERS=1`**, and
+  `doctor --check-claude-code` reports (as info) when it is missing.
+
+---
+
 ## [v2.17.0] — 2026-10-24 (time-to-first-token cut-off, retry signals)
 
 ### Added

{coderouter_cli-2.17.0 → coderouter_cli-2.19.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: coderouter-cli
-Version: 2.17.0
+Version: 2.19.0
 Summary: Local-first, free-first, fallback-built-in LLM router. Claude Code / OpenAI compatible.
 Project-URL: Homepage, https://github.com/zephel01/CodeRouter
 Project-URL: Repository, https://github.com/zephel01/CodeRouter
@@ -66,7 +66,7 @@ Description-Content-Type: text/markdown
 ## 何ができるか — 30 秒で
 
 ```
-あなたのエージェント (Claude Code / agy ほか ※)
+あなたのエージェント (Claude Code / codex / agy)
         │
         ▼
   ┌─ CodeRouter ─┐
@@ -76,8 +76,6 @@ Description-Content-Type: text/markdown
   └──────────────┘
 ```
 
-※ 現行の codex CLI は Responses API（`/v1/responses`）専用になったため、CodeRouter 経由ではまだ使えません（対応予定）。直結の代替手順 → [quickstart Pattern B](./docs/start/quickstart.md#pattern-b-codex-cli-で使う)
-
 **やってくれること:**
 
 - ローカルモデルが壊した tool calling を Claude Code に届く前に修復する
@@ -147,7 +145,7 @@ ANTHROPIC_BASE_URL=http://localhost:8088 ANTHROPIC_AUTH_TOKEN=dummy claude
 | Claude Code + ローカル Ollama で tool calling が壊れる | **必須** — tool 修復 (+ 必要なら wire 変換) |
 | Claude Code + ローカルで長時間回すと止まる | **必須級** — 6 系統ガード + self-healing |
 | Ollama v0.14+ / LM Studio にネイティブ直結で動いてる | **便利** — 直結に無い fallback / ガード / 診断を追加 (passthrough で翻訳ゼロ) |
-| codex / agy + Ollama 直繋ぎで動いてる | オプション — フォールバックが欲しいなら(codex は `/v1/responses` 対応後) |
+| codex / agy + Ollama 直繋ぎで動いてる | オプション — フォールバックが欲しいなら(codex は v2.19.0 の `/v1/responses` 経由) |
 | Claude API を直接叩いてて問題ない | 不要 |
 
 詳細は → [要否判定ガイド](./docs/start/when-do-i-need-coderouter.md)

{coderouter_cli-2.17.0 → coderouter_cli-2.19.0}/README.en.md

@@ -21,7 +21,7 @@
 ## What it does — in 30 seconds
 
 ```
-Your agent (Claude Code / agy, etc. *)
+Your agent (Claude Code / codex / agy)
         │
         ▼
   ┌─ CodeRouter ──┐
@@ -31,7 +31,6 @@ Your agent (Claude Code / agy, etc. *)
   └────────────────┘
 ```
 
-\* Current codex CLI speaks only the Responses API (`/v1/responses`), so it cannot go through CodeRouter yet (planned). Direct-connect workaround → [quickstart Pattern B](./docs/start/quickstart.en.md#pattern-b-use-it-with-the-codex-cli)
 
 **What it does for you:**
 
@@ -83,7 +82,7 @@ That's it. Claude Code works as usual, but your local Ollama is answering behind
 |---|---|
 | Claude Code + local Ollama, tool calling breaks | **Yes** — wire translation + tool repair |
 | Claude Code + local, dies after long sessions | **Helpful** — 6 guards + self-healing |
-| codex / agy + Ollama works fine | Optional — if you want fallback (codex: once `/v1/responses` lands) |
+| codex / agy + Ollama works fine | Optional — if you want fallback (codex: via `/v1/responses`, v2.19.0+) |
 | Using Claude API directly, no issues | Not needed |
 
 Full decision matrix → [Do I need CodeRouter?](./docs/start/when-do-i-need-coderouter.en.md)

{coderouter_cli-2.17.0 → coderouter_cli-2.19.0}/README.md

@@ -21,7 +21,7 @@
 ## 何ができるか — 30 秒で
 
 ```
-あなたのエージェント (Claude Code / agy ほか ※)
+あなたのエージェント (Claude Code / codex / agy)
         │
         ▼
   ┌─ CodeRouter ─┐
@@ -31,8 +31,6 @@
   └──────────────┘
 ```
 
-※ 現行の codex CLI は Responses API（`/v1/responses`）専用になったため、CodeRouter 経由ではまだ使えません（対応予定）。直結の代替手順 → [quickstart Pattern B](./docs/start/quickstart.md#pattern-b-codex-cli-で使う)
-
 **やってくれること:**
 
 - ローカルモデルが壊した tool calling を Claude Code に届く前に修復する
@@ -102,7 +100,7 @@ ANTHROPIC_BASE_URL=http://localhost:8088 ANTHROPIC_AUTH_TOKEN=dummy claude
 | Claude Code + ローカル Ollama で tool calling が壊れる | **必須** — tool 修復 (+ 必要なら wire 変換) |
 | Claude Code + ローカルで長時間回すと止まる | **必須級** — 6 系統ガード + self-healing |
 | Ollama v0.14+ / LM Studio にネイティブ直結で動いてる | **便利** — 直結に無い fallback / ガード / 診断を追加 (passthrough で翻訳ゼロ) |
-| codex / agy + Ollama 直繋ぎで動いてる | オプション — フォールバックが欲しいなら(codex は `/v1/responses` 対応後) |
+| codex / agy + Ollama 直繋ぎで動いてる | オプション — フォールバックが欲しいなら(codex は v2.19.0 の `/v1/responses` 経由) |
 | Claude API を直接叩いてて問題ない | 不要 |
 
 詳細は → [要否判定ガイド](./docs/start/when-do-i-need-coderouter.md)

{coderouter_cli-2.17.0 → coderouter_cli-2.19.0}/coderouter/adapters/anthropic_native.py

@@ -46,6 +46,7 @@ from coderouter.adapters.base import (
     StreamChunk,
     StreamTruncatedError,
 )
+from coderouter.adapters.slot_affinity import apply_slot_affinity
 from coderouter.credentials import resolve_provider_credential
 from coderouter.logging import (
     get_logger,
@@ -243,6 +244,9 @@ class AnthropicAdapter(BaseAdapter):
         body.update(dumped)
         body["model"] = self.config.model
         body["stream"] = stream
+        apply_slot_affinity(
+            body, slots=self.config.slot_affinity_slots, key=req.session_key
+        )
         return body
 
     # ------------------------------------------------------------------

{coderouter_cli-2.17.0 → coderouter_cli-2.19.0}/coderouter/adapters/base.py

@@ -65,6 +65,9 @@ class ChatRequest(BaseModel):
 
     # CodeRouter-specific extension (not sent upstream)
     profile: str | None = Field(default=None, exclude=True)
+    # v2.18.0: conversation key for KV-slot affinity (see
+    # ``ProviderConfig.slot_affinity_slots``). Never serialized.
+    session_key: str | None = Field(default=None, exclude=True)
 
 
 class ChatResponse(BaseModel):

{coderouter_cli-2.17.0 → coderouter_cli-2.19.0}/coderouter/adapters/openai_compat.py

@@ -30,6 +30,7 @@ from coderouter.adapters.base import (
     StreamChunk,
     StreamTruncatedError,
 )
+from coderouter.adapters.slot_affinity import apply_slot_affinity
 from coderouter.credentials import resolve_provider_credential
 from coderouter.logging import (
     get_logger,
@@ -182,6 +183,11 @@ class OpenAICompatAdapter(BaseAdapter):
             value = getattr(request, field, None)
             if value is not None:
                 body[field] = value
+        apply_slot_affinity(
+            body,
+            slots=self.config.slot_affinity_slots,
+            key=getattr(request, "session_key", None),
+        )
         if stream:
             # Request a terminal usage chunk. Providers that honor this
             # (OpenAI, OpenRouter, Ollama >=0.x) will send one extra chunk

coderouter_cli-2.19.0/coderouter/adapters/slot_affinity.py

@@ -0,0 +1,54 @@
+"""v2.18.0: KV-slot affinity for llama-server (``id_slot``).
+
+llama-server started with ``--parallel N`` serves N slots, each holding its
+own prompt cache. Without a hint it picks a free slot, so consecutive turns
+of one conversation can land on different slots and re-prefill the whole
+prompt. Sending ``id_slot`` pins a conversation to one slot.
+
+The slot is ``sha256(key) % N`` — stable across processes and restarts
+(Python's ``hash`` is salted per process).
+"""
+
+from __future__ import annotations
+
+import hashlib
+from collections.abc import Mapping
+from typing import Any
+
+# Request classes whose prompt shares the main conversation's prefix: they
+# belong on the main conversation's slot. Everything else (sub-agents,
+# auxiliary calls such as the auto-mode classifier or titles, workflows) has
+# its own prompt and gets its own key, so it neither waits on the main slot
+# nor evicts its cache.
+_MAIN_CLASSES = frozenset({"", "main", "compaction"})
+
+
+def affinity_key(hints: Mapping[str, str]) -> str | None:
+    """Conversation key for slot affinity, from Claude Code's hint headers.
+
+    ``None`` when there is no session id. ``main`` / ``compaction`` (and a
+    missing class) share ``<session>``; other classes get
+    ``<session>:<class>:<agent_type>``.
+    """
+    session = hints.get("session_id")
+    if not session:
+        return None
+    request_class = hints.get("request_class", "").lower()
+    if request_class in _MAIN_CLASSES:
+        return session
+    return f"{session}:{request_class}:{hints.get('agent_type', '').lower()}"
+
+
+def slot_for(key: str, slots: int) -> int:
+    digest = hashlib.sha256(key.encode("utf-8")).digest()
+    return int.from_bytes(digest[:8], "big") % slots
+
+
+def apply_slot_affinity(body: dict[str, Any], *, slots: int | None, key: str | None) -> None:
+    """Set ``body["id_slot"]`` when affinity is configured and a key exists.
+
+    An ``id_slot`` already present (e.g. from ``extra_body``) wins.
+    """
+    if not slots or not key or "id_slot" in body:
+        return
+    body["id_slot"] = slot_for(key, slots)

{coderouter_cli-2.17.0 → coderouter_cli-2.19.0}/coderouter/cli.py

@@ -483,7 +483,8 @@ def _build_parser() -> argparse.ArgumentParser:
         help=(
             "v2.16.0: do not write the Claude Code gateway settings "
             "(ENABLE_TOOL_SEARCH=false, CLAUDE_CODE_AUTO_MODE_SERVER=0, "
-            "and --max-context-tokens). Use when the chain is "
+            "CLAUDE_CODE_GATEWAY_HINT_HEADERS=1 and --max-context-tokens). "
+            "Use when the chain is "
             "api.anthropic.com only."
         ),
     )

{coderouter_cli-2.17.0 → coderouter_cli-2.19.0}/coderouter/config/schemas.py

@@ -562,6 +562,23 @@ class ProviderConfig(BaseModel):
     # withholds those opening events from the client. ``None`` (default)
     # disables it. Typical use: a local llama-server still loading a model
     # or chewing through a long prompt while a cloud fallback could answer.
+    # v2.18.0: KV-slot affinity for llama-server started with
+    # ``--parallel N``. When set to N and the request carries a conversation
+    # key (Claude Code's ``x-claude-code-session-id`` hint header), the body
+    # gets ``id_slot = stable_hash(key) % N`` so every turn of a conversation
+    # lands on the same slot and reuses its prompt cache instead of
+    # re-prefilling on whichever slot is free. llama.cpp only (other servers
+    # ignore or reject ``id_slot``); ``None`` (default) sends nothing.
+    slot_affinity_slots: int | None = Field(
+        default=None,
+        ge=1,
+        le=256,
+        description=(
+            "v2.18.0: llama-server --parallel N. Pins each conversation to "
+            "slot hash(session) % N via id_slot so its KV cache is reused. "
+            "llama.cpp only. None disables."
+        ),
+    )
     ttft_timeout_s: float | None = Field(
         default=None,
         gt=0.0,
@@ -1639,6 +1656,21 @@ class RuleMatcher(BaseModel):
     # declares any tools); ``False`` is rejected by ``_exactly_one``
     # since a "no-tools" rule would shadow the default fall-through.
     has_tools: bool | None = None
+    # v2.18.0: Claude Code gateway hint headers. Claude Code 2.1.273+ sends
+    # these to a custom ANTHROPIC_BASE_URL when
+    # ``CLAUDE_CODE_GATEWAY_HINT_HEADERS=1`` is set (``coderouter
+    # vscode-init`` sets it). They say what a request *is* — something the
+    # body heuristics above can only guess:
+    #   * ``request_class`` — ``x-claude-code-request-class``: ``main`` /
+    #     ``subagent`` / ``workflow`` / ``compaction`` / ``auxiliary``
+    #     (auto-mode classifier, titles, …). Case-insensitive exact match.
+    #   * ``agent_type`` — ``x-claude-code-agent-type`` (e.g. ``Explore``),
+    #     case-insensitive exact match.
+    #   * ``compaction: True`` — ``x-claude-code-compaction`` is truthy.
+    # Without the headers these matchers simply never match.
+    request_class: str | None = None
+    agent_type: str | None = None
+    compaction: bool | None = None
 
     _MATCHER_FIELDS: tuple[str, ...] = (
         "has_image",
@@ -1649,12 +1681,15 @@ class RuleMatcher(BaseModel):
         "content_token_count_min",
         "has_tools",
         "cjk_ratio_min",
+        "request_class",
+        "agent_type",
+        "compaction",
     )
 
     # Boolean matcher fields carry meaning only at ``True`` — the runtime
     # evaluator uses ``is True`` — so a ``False`` value is a dead rule that
     # never matches. ``_exactly_one`` rejects it explicitly (see below).
-    _BOOL_MATCHER_FIELDS: tuple[str, ...] = ("has_image", "has_tools")
+    _BOOL_MATCHER_FIELDS: tuple[str, ...] = ("has_image", "has_tools", "compaction")
 
     @model_validator(mode="after")
     def _exactly_one(self) -> Self:

{coderouter_cli-2.17.0 → coderouter_cli-2.19.0}/coderouter/doctor_claude_code.py

@@ -125,6 +125,18 @@ def check(version: Version | None, env: Mapping[str, str]) -> list[ClaudeCodeFin
             )
         )
 
+    if env.get("CLAUDE_CODE_GATEWAY_HINT_HEADERS", "").lower() in ("1", "true"):
+        out.append(ClaudeCodeFinding("ok", "CLAUDE_CODE_GATEWAY_HINT_HEADERS=1"))
+    else:
+        out.append(
+            ClaudeCodeFinding(
+                "info",
+                "CLAUDE_CODE_GATEWAY_HINT_HEADERS is not set: auto_router rules "
+                "on request_class / agent_type / compaction (v2.18.0) never "
+                "match without it.",
+            )
+        )
+
     if env.get("CLAUDE_CODE_AUTO_MODE_SERVER") == "0":
         out.append(ClaudeCodeFinding("ok", "CLAUDE_CODE_AUTO_MODE_SERVER=0"))
     else:

{coderouter_cli-2.17.0 → coderouter_cli-2.19.0}/coderouter/ingress/anthropic_routes.py

@@ -31,6 +31,7 @@ from fastapi import APIRouter, Header, HTTPException, Request
 from fastapi.responses import JSONResponse, Response, StreamingResponse
 
 from coderouter.adapters.base import StreamTruncatedError
+from coderouter.adapters.slot_affinity import affinity_key
 from coderouter.guards.context_budget import ContextBudgetRejectError
 from coderouter.guards.tool_loop import ToolCountExceededError, ToolLoopBreakError
 from coderouter.ingress.anthropic_errors import (
@@ -49,7 +50,7 @@ from coderouter.routing import (
     MidStreamError,
     NoProvidersAvailableError,
 )
-from coderouter.routing.auto_router import RESERVED_PROFILE_NAME, classify
+from coderouter.routing.auto_router import RESERVED_PROFILE_NAME, classify, extract_gateway_hints
 from coderouter.routing.fallback_trace import (
     SSE_FALLBACK_EVENT,
     current_fallback_trace,
@@ -226,6 +227,11 @@ async def messages(
     if anthropic_beta:
         anth_req.anthropic_beta = anthropic_beta
 
+    # v2.18.0: Claude Code gateway hint headers — routing matchers below,
+    # and the conversation key for llama-server KV-slot affinity.
+    gateway_hints = extract_gateway_hints(request.headers)
+    anth_req.session_key = affinity_key(gateway_hints)
+
     # Profile selection — body field wins over header (same policy as OpenAI route).
     if anth_req.profile is None and x_coderouter_profile:
         anth_req.profile = x_coderouter_profile
@@ -253,7 +259,7 @@ async def messages(
     # AnthropicRequest), so both OpenAI and Anthropic ingress use the same
     # classifier without a shared request shim.
     if anth_req.profile is None and config.default_profile == RESERVED_PROFILE_NAME:
-        anth_req.profile = classify(payload, config)
+        anth_req.profile = classify(payload, config, gateway_hints)
 
     if anth_req.profile is not None:
         try:

{coderouter_cli-2.17.0 → coderouter_cli-2.19.0}/coderouter/ingress/app.py

@@ -19,6 +19,7 @@ from coderouter.ingress.dashboard_routes import router as dashboard_router
 from coderouter.ingress.launcher_routes import router as launcher_router
 from coderouter.ingress.metrics_routes import router as metrics_router
 from coderouter.ingress.openai_routes import router as openai_router
+from coderouter.ingress.responses_routes import router as responses_router
 from coderouter.logging import configure_logging, get_logger
 from coderouter.metrics import install_collector
 from coderouter.plugins import discover_and_load
@@ -491,6 +492,8 @@ def create_app(config_path: str | None = None) -> FastAPI:
 
     app.include_router(openai_router, prefix="/v1", tags=["openai-compat"])
     app.include_router(anthropic_router, prefix="/v1", tags=["anthropic-compat"])
+    # v2.19.0: OpenAI Responses API (Codex CLI).
+    app.include_router(responses_router, prefix="/v1", tags=["openai-responses"])
     # v1.5-A: /metrics.json sits at the root (no /v1 prefix) — metrics are not
     # part of the OpenAI / Anthropic API surface, and Prometheus-style
     # endpoints conventionally live at the root in v1.5-B.

{coderouter_cli-2.17.0 → coderouter_cli-2.19.0}/coderouter/ingress/openai_routes.py

@@ -32,9 +32,10 @@ from fastapi import APIRouter, Header, HTTPException, Request
 from fastapi.responses import JSONResponse, StreamingResponse
 
 from coderouter.adapters.base import ChatRequest
+from coderouter.adapters.slot_affinity import affinity_key
 from coderouter.logging import get_logger
 from coderouter.routing import FallbackEngine, NoProvidersAvailableError
-from coderouter.routing.auto_router import RESERVED_PROFILE_NAME, classify
+from coderouter.routing.auto_router import RESERVED_PROFILE_NAME, classify, extract_gateway_hints
 from coderouter.routing.fallback_trace import current_fallback_trace
 
 router = APIRouter()
@@ -199,6 +200,10 @@ async def chat_completions(
     except Exception as exc:  # pydantic.ValidationError, etc.
         raise HTTPException(status_code=422, detail=str(exc)) from exc
 
+    # v2.18.0: gateway hint headers (routing matchers + KV-slot affinity key).
+    gateway_hints = extract_gateway_hints(request.headers)
+    chat_req.session_key = affinity_key(gateway_hints)
+
     # Header-based override (body wins if both are set — see module docstring)
     if chat_req.profile is None and x_coderouter_profile:
         chat_req.profile = x_coderouter_profile
@@ -226,7 +231,7 @@ async def chat_completions(
     # When inactive, the engine still falls through to
     # ``config.default_profile`` on its own — same semantics as pre-v1.6.
     if chat_req.profile is None and config.default_profile == RESERVED_PROFILE_NAME:
-        chat_req.profile = classify(payload, config)
+        chat_req.profile = classify(payload, config, gateway_hints)
 
     # Validate profile exists before we kick off any upstream call
     if chat_req.profile is not None: