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

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

@@ -9,6 +9,73 @@ 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: coderouter-cli
-Version: 2.18.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.18.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.18.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.18.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.19.0/coderouter/ingress/responses_routes.py

@@ -0,0 +1,269 @@
+"""OpenAI Responses API route: ``POST /v1/responses`` (v2.19.0).
+
+Lets the OpenAI Codex CLI (Responses-only since 2026-02) use CodeRouter as a
+custom provider::
+
+    [model_providers.coderouter]
+    name = "CodeRouter"
+    base_url = "http://127.0.0.1:8088/v1"
+    wire_api = "responses"
+
+The request is translated to an Anthropic Messages request
+(:mod:`coderouter.translation.responses`) and run through the same fallback
+engine as ``/v1/messages`` — tool-call repair, guards, fallback and the
+v2.16.0 error mapping all apply. Profile selection mirrors the other
+routes: body ``profile`` > ``X-CodeRouter-Profile`` > ``X-CodeRouter-Mode``
+> auto router > default.
+
+Failures are reported the way Codex reads them:
+
+- before the response commits: an OpenAI-style error body with a real
+  HTTP status (400 non-retryable / 429 with ``Retry-After`` / 502);
+- a context overflow on a streaming request: ``response.failed`` with code
+  ``context_length_exceeded`` — the only overflow signal Codex recognizes
+  (an HTTP 400 is treated as a plain invalid request);
+- after the stream started: ``response.failed`` (``server_error``), then end
+  of stream, which Codex retries.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+from collections.abc import AsyncIterator
+
+from fastapi import APIRouter, Header, Request
+from fastapi.responses import JSONResponse, Response, StreamingResponse
+
+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 (
+    PROMPT_TOO_LONG_PREFIX,
+    AnthropicErrorResponse,
+    map_no_providers_error,
+)
+from coderouter.ingress.anthropic_routes import (
+    _DisconnectWatcher,
+    _resolve_stream_timeout_s,
+)
+from coderouter.logging import get_logger
+from coderouter.routing import FallbackEngine, MidStreamError, NoProvidersAvailableError
+from coderouter.routing.auto_router import (
+    RESERVED_PROFILE_NAME,
+    classify,
+    extract_gateway_hints,
+)
+from coderouter.translation import AnthropicStreamEvent
+from coderouter.translation.responses import (
+    ResponsesStreamTranslator,
+    anthropic_response_to_responses,
+    format_sse,
+    responses_to_anthropic,
+)
+
+router = APIRouter()
+logger = get_logger(__name__)
+
+_PROFILE_HEADER = "x-coderouter-profile"
+_MODE_HEADER = "x-coderouter-mode"
+
+_OPENAI_TYPE = {
+    "invalid_request_error": "invalid_request_error",
+    "request_too_large": "invalid_request_error",
+    "rate_limit_error": "rate_limit_error",
+    "timeout_error": "server_error",
+    "api_error": "server_error",
+}
+
+
+def _openai_error(
+    status: int,
+    message: str,
+    *,
+    etype: str,
+    code: str | None = None,
+    headers: dict[str, str] | None = None,
+) -> JSONResponse:
+    return JSONResponse(
+        status_code=status,
+        content={"error": {"message": message, "type": etype, "param": None, "code": code}},
+        headers=headers or None,
+    )
+
+
+def _is_overflow(mapped: AnthropicErrorResponse) -> bool:
+    return mapped.status_code == 400 and mapped.message.lower().startswith(PROMPT_TOO_LONG_PREFIX)
+
+
+def _mapped_to_http(mapped: AnthropicErrorResponse) -> JSONResponse:
+    code = None
+    if _is_overflow(mapped):
+        code = "context_length_exceeded"
+    elif mapped.status_code == 429:
+        code = "rate_limit_exceeded"
+    return _openai_error(
+        mapped.status_code,
+        mapped.message,
+        etype=_OPENAI_TYPE.get(mapped.error_type, "server_error"),
+        code=code,
+        headers=dict(mapped.headers),
+    )
+
+
+def _failed_stream(translator: ResponsesStreamTranslator, code: str, message: str) -> StreamingResponse:
+    async def gen() -> AsyncIterator[str]:
+        for ev in translator.start():
+            yield format_sse(ev)
+        for ev in translator.failed(code, message):
+            yield format_sse(ev)
+
+    return StreamingResponse(gen(), media_type="text/event-stream", headers={"Cache-Control": "no-cache"})
+
+
+@router.post("/responses", response_model=None)
+async def responses(
+    request: Request,
+    x_coderouter_profile: str | None = Header(default=None, alias=_PROFILE_HEADER),
+    x_coderouter_mode: str | None = Header(default=None, alias=_MODE_HEADER),
+) -> Response:
+    """OpenAI Responses API endpoint (streaming and non-streaming)."""
+    engine: FallbackEngine = request.app.state.engine
+    config = request.app.state.config
+
+    try:
+        body = await request.json()
+    except (json.JSONDecodeError, ValueError):
+        return _openai_error(400, "request body must be JSON", etype="invalid_request_error")
+    if not isinstance(body, dict):
+        return _openai_error(400, "request body must be a JSON object", etype="invalid_request_error")
+
+    try:
+        anth_req, tool_map = responses_to_anthropic(body)
+    except Exception as exc:  # pydantic ValidationError and shape errors
+        return _openai_error(400, f"could not translate request: {exc}", etype="invalid_request_error")
+
+    model = body.get("model") if isinstance(body.get("model"), str) else "coderouter"
+
+    # Conversation key for llama-server slot affinity: Claude-style hint
+    # headers when present, else Codex's own ``session-id`` header.
+    hints = extract_gateway_hints(request.headers)
+    anth_req.session_key = affinity_key(hints) or request.headers.get("session-id") or None
+
+    if anth_req.profile is None and x_coderouter_profile:
+        anth_req.profile = x_coderouter_profile
+    if anth_req.profile is None and x_coderouter_mode:
+        try:
+            anth_req.profile = config.resolve_mode(x_coderouter_mode)
+        except KeyError:
+            return _openai_error(
+                400, f"unknown mode {x_coderouter_mode!r}", etype="invalid_request_error"
+            )
+    if anth_req.profile is None and config.default_profile == RESERVED_PROFILE_NAME:
+        anth_req.profile = classify(anth_req.model_dump(), config, hints)
+    if anth_req.profile is not None:
+        try:
+            config.profile_by_name(anth_req.profile)
+        except KeyError:
+            return _openai_error(
+                400, f"unknown profile {anth_req.profile!r}", etype="invalid_request_error"
+            )
+
+    translator = ResponsesStreamTranslator(tool_map, model=model)
+
+    try:
+        anth_req, _ctx = engine.apply_context_budget(anth_req)
+    except ContextBudgetRejectError as exc:
+        if anth_req.stream:
+            return _failed_stream(translator, "context_length_exceeded", str(exc))
+        return _openai_error(400, str(exc), etype="invalid_request_error", code="context_length_exceeded")
+
+    if not anth_req.stream:
+        try:
+            resp = await engine.generate_anthropic(anth_req)
+        except NoProvidersAvailableError as exc:
+            return _mapped_to_http(map_no_providers_error(exc))
+        except ContextBudgetRejectError as exc:
+            return _openai_error(400, str(exc), etype="invalid_request_error", code="context_length_exceeded")
+        except (ToolLoopBreakError, ToolCountExceededError) as exc:
+            return _openai_error(400, str(exc), etype="invalid_request_error")
+        return JSONResponse(
+            anthropic_response_to_responses(resp.model_dump(exclude_none=True), tool_map, model=model)
+        )
+
+    # Streaming: pull the first engine event before committing, like
+    # /v1/messages (v2.16.0), so pre-content failures get a real status.
+    timeout_s = _resolve_stream_timeout_s(engine, anth_req.profile)
+    deadline = asyncio.get_running_loop().time() + timeout_s
+    source = engine.stream_anthropic(anth_req)
+    first: AnthropicStreamEvent | None = None
+    watcher = _DisconnectWatcher(request)
+    watcher.start()
+
+    async def _close() -> None:
+        with contextlib.suppress(Exception):
+            await source.aclose()  # type: ignore[attr-defined]
+
+    try:
+        async with asyncio.timeout_at(deadline) as scope:
+            first = await anext(source)
+    except StopAsyncIteration:
+        first = None
+    except NoProvidersAvailableError as exc:
+        await _close()
+        mapped = map_no_providers_error(exc)
+        if _is_overflow(mapped):
+            return _failed_stream(translator, "context_length_exceeded", mapped.message)
+        return _mapped_to_http(mapped)
+    except ContextBudgetRejectError as exc:
+        await _close()
+        return _failed_stream(translator, "context_length_exceeded", str(exc))
+    except (ToolLoopBreakError, ToolCountExceededError) as exc:
+        await _close()
+        return _openai_error(400, str(exc), etype="invalid_request_error")
+    except MidStreamError as exc:
+        await _close()
+        return _failed_stream(translator, "server_error", str(exc))
+    except TimeoutError:
+        await _close()
+        if not scope.expired():
+            raise
+        return _openai_error(504, f"no upstream event within {timeout_s:.0f}s", etype="server_error")
+    except asyncio.CancelledError:
+        await _close()
+        if watcher.fired:
+            watcher.uncancel()
+            return Response(status_code=499)
+        raise
+    except BaseException:
+        await _close()
+        raise
+    finally:
+        await watcher.stop()
+
+    async def gen() -> AsyncIterator[str]:
+        try:
+            async with asyncio.timeout_at(deadline):
+                for ev in translator.start():
+                    yield format_sse(ev)
+                if first is not None:
+                    for out in translator.feed(first):
+                        yield format_sse(out)
+                async for ev in source:
+                    for out in translator.feed(ev):
+                        yield format_sse(out)
+            for out in translator.finish():
+                yield format_sse(out)
+        except TimeoutError:
+            logger.warning("responses-stream-timeout", extra={"timeout_s": timeout_s})
+            for out in translator.failed("server_error", f"stream exceeded {timeout_s:.0f}s ceiling"):
+                yield format_sse(out)
+        except (MidStreamError, NoProvidersAvailableError) as exc:
+            logger.warning("responses-stream-failed", extra={"error": str(exc)[:300]})
+            for out in translator.failed("server_error", str(exc)):
+                yield format_sse(out)
+        finally:
+            await _close()
+
+    return StreamingResponse(gen(), media_type="text/event-stream", headers={"Cache-Control": "no-cache"})