coderouter-cli 2.7.5__tar.gz → 2.7.7__tar.gz

{coderouter_cli-2.7.5 → coderouter_cli-2.7.7}/CHANGELOG.md

@@ -9,6 +9,164 @@ are kept verbatim where the Japanese text itself is the subject).
 
 ---
 
+## [v2.7.7] — 2026-07-10 (External coding agents: agent_cli adapter, Phase 1a claude)
+
+**PR #62 / #63**. Adds a new adapter kind, `agent_cli`, that lets CodeRouter front an external
+coding-agent CLI (Claude Code / Codex / Gemini / Grok) as a single one-shot
+`prompt in → text out` transformation, keeping the "one request = one
+stateless transformation" ethos intact even though the underlying CLI is a
+stateful, multi-turn, filesystem-editing control loop. Phase 1a implements
+only the `claude` target (Claude Code CLI) — the most stable of the four and
+the only one that emits `total_cost_usd` directly, making it the reference
+implementation for the parser and cost path. `codex` / `gemini` / `grok` are
+declared in the config schema for forward compatibility but rejected with a
+clear error until their phase lands (Phase 1b-1d).
+
+### Added
+
+- **`kind: "agent_cli"` + `AgentCliAdapter`** (`coderouter/adapters/agent_cli.py`,
+  new) — invokes the Claude Code CLI one-shot via
+  `claude -p --output-format json` (prompt fed on stdin, never on argv, so
+  it is never subject to shell interpretation; `shell=True` is never used).
+  Key behaviors:
+  - Subscription-first OAuth: the child process does NOT inherit the parent
+    environment. A minimal env is built explicitly (fixed safe `PATH`,
+    `NO_COLOR=1`, `TERM=dumb`, inherited `HOME` for credential-dir
+    discovery); `ANTHROPIC_API_KEY` is never forwarded unless the operator
+    explicitly lists it in `passthrough_env` (prevents a stray key from
+    silently overriding subscription auth). `--bare` is deliberately never
+    added — it would skip OAuth/keychain reads.
+  - `CODEROUTER_AGENT_DEPTH` recursion guard: the depth is read from the
+    environment, incremented, and propagated into the child; `generate()`
+    refuses with a non-retryable error once the current depth reaches
+    `agent_depth_limit` (default 2).
+  - `exec_timeout_s` is enforced independently of `ProviderConfig.timeout_s`
+    via `asyncio.wait_for`; on expiry the whole child process *group* is
+    `SIGKILL`ed (`start_new_session=True` + `os.killpg`) so the CLI's real
+    LLM-call subprocess is never orphaned.
+  - Default `read_only` sandbox: `allow_file_writes=False` /
+    `sandbox_mode="read_only"` map to claude's `--permission-mode plan`.
+    The permission-mode mapping is clamped to read-only whenever
+    `allow_file_writes` is False, regardless of `sandbox_mode` (defense in
+    depth). `edit` / `full_auto` both map to `acceptEdits`.
+  - Pseudo-streaming: no CLI in Phase 1a exposes a stable token stream, so
+    `stream()` runs `generate()` once and chunks the final answer into
+    content `StreamChunk`s followed by a terminal `finish_reason="stop"`
+    chunk carrying usage.
+  - `total_cost_usd` (claude's JSON output) propagates to the response as
+    the `coderouter_cost_usd` metadata field, feeding the cost dashboard;
+    `session_id` similarly surfaces as `coderouter_session_id`.
+- **`AgentCliConfig` schema** (`coderouter/config/schemas.py`) — new
+  `ProviderConfig.agent_cli` sub-config (`agent`, `command`, `workdir`,
+  `exec_timeout_s`, `allow_file_writes`, `sandbox_mode`, `model`,
+  `max_turns`, `passthrough_env`, `agent_depth_limit`), `extra="forbid"`
+  like the rest of the module. `ProviderConfig.base_url` is relaxed to
+  optional so `agent_cli` providers (which shell out to a local CLI rather
+  than calling a URL) can omit it; a `model_validator` restores the
+  required-ness of `base_url` for `openai_compat` / `anthropic` and
+  requires the `agent_cli` sub-config whenever `kind == "agent_cli"`.
+- **30 new tests** (`tests/test_agent_cli.py`) covering argv construction
+  (model/max-turns/permission-mode mapping and the write-clamp), claude JSON
+  parsing (success / `is_error` / malformed / missing-field paths), a
+  stubbed-subprocess `generate()` path, timeout → process-group kill,
+  child-env isolation (no `ANTHROPIC_API_KEY` leak, `passthrough_env`
+  allowlist, depth increment), the recursion depth limit, and a TestClient
+  end-to-end run through `POST /v1/chat/completions`.
+- New example config: `examples/providers-agent-cli.yaml` — a runnable
+  single-provider `agent_cli` setup for `claude`, plus a commented-out
+  preview of the future `codex` / `gemini` / `grok` provider blocks.
+- Design doc: `docs/designs/external-agents-adapter.md` — the full Phase 1
+  design (architecture, security requirements, per-CLI argv/JSON tables,
+  auth policy, test plan). `codex` / `gemini` / `grok` remain Phase
+  1b-1d — configuring `agent_cli.agent` to any of them is accepted at
+  config-load time but rejected with a clear, non-retryable error
+  (`"agent 'codex' is not implemented in Phase 1a (claude only)"`) when the
+  adapter is constructed.
+
+---
+
+### Fixed
+
+- **Paid gate blocked the example config** (PR #63): the `ALLOW_PAID` env var
+  overrides the yaml `allow_paid`, so the example's `allow_paid: true` was
+  silently defeated. Subscription-OAuth claude has zero incremental cost —
+  the example now marks the provider `paid: false` (grok stays `paid: true`,
+  API-metered).
+- **`Not logged in` under the minimal child env** (PR #63): on macOS the
+  Claude Code CLI resolves its Keychain credential via `USER`; the child env
+  now inherits `USER`/`LOGNAME` alongside `HOME`. Failures reported as an
+  `is_error` result JSON on stdout (exit 1, empty stderr) now surface the
+  actual `result` text in provider-failed logs instead of an empty tail.
+
+## [v2.7.6] — 2026-07-09 (Launcher MTP / speculative-decoding support)
+
+**PR #59 / #60**. Adds Multi-Token Prediction (MTP) / speculative-decoding
+support to the llama.cpp launcher (both the Web UI and the desktop GUI), closing the
+gap where operators had to hand-assemble `--spec-type` / `--model-draft`
+flags. Fully backward compatible: the new fields default to auto-detection
+with a silent no-op fallback, no config-schema changes, no new dependencies.
+
+### Added
+
+- **`resolve_speculative()` / `find_draft_companion()`**
+  (`coderouter/launcher_speculative.py`) — shared decision logic for both
+  launchers. `mtp_mode="auto"` (default) first checks the selected gguf's
+  own metadata for embedded nextn layers (`{arch}.nextn_predict_layers > 0`)
+  and, if present, emits `--spec-type draft-mtp` with no separate draft
+  model; otherwise it scans the *same folder* as the main gguf for a
+  companion draft/MTP file (name hint or shared prefix, size under 50% of
+  the main model, architecture-matched when readable) and wires up
+  `--spec-type draft-mtp|draft-simple --model-draft <path>`; otherwise it
+  starts normally and logs that no companion was found. An explicit
+  `draft_model_path` skips detection entirely (400 if the path doesn't
+  exist); `mtp_mode="off"` never emits speculative flags. When the operator
+  supplies `--spec-type` in extra args, auto-detection defers to it and
+  adds nothing.
+  Both knobs are llama.cpp-only — vllm/mlx reject them with a 400.
+- **`POST /api/launcher/start`**: new optional `draft_model_path` and
+  `mtp_mode` (`"auto"` / `"off"`) fields; the response now carries the
+  resolved flags as `"speculative"`. `-md` / `--model-draft` /
+  `--spec-draft-model` join the existing `-m`/`--model` denylist for
+  `options`/`extra_args` (llama.cpp) — the draft model can only be set via
+  `draft_model_path`. The remaining spec knobs (`--spec-type`,
+  `--spec-draft-n-max/-n-min/-p-min`, `-ngld`, `-devd`) stay free-form.
+- **GGUF introspection** (`coderouter/gguf_introspect.py`): `GGUFInfo` now
+  reports `n_nextn` and the derived `supports_mtp` property, read from
+  `{arch}.nextn_predict_layers`.
+- **`--split-mode tensor` crash warning**: known llama.cpp issue #24309 —
+  a nextn-embedded model combined with tensor split can crash. The launcher
+  detects the combination and logs a warning recommending `--split-mode
+  layer` without blocking the launch.
+- **UI**: Web LAUNCH form gets "MTP/draft gguf (空欄で自動検出)" text field
+  + "MTP" `auto`/`off` select. Desktop GUI (`launcher_gui.py`) gets the
+  matching Entry + a "MTP自動検出" checkbox (default on).
+- **Automatic MTP startup-crash fallback**: when speculative flags were added
+  by AUTO detection (`mtp_mode="auto"`, no explicit `draft_model_path`) and the
+  backend dies during startup (non-zero exit within ~3 min), the launcher
+  relaunches it ONCE without the speculative flags and logs
+  `[launcher] MTP startup failure detected (exit code ...); retrying without
+  speculative decoding` plus the flag-free command. This covers architectures
+  whose `draft-mtp` support in llama.cpp is still immature (detection is right
+  but the MTP context fails to initialize, e.g. `failed to measure MTP context
+  memory`). Explicit `draft_model_path` / operator-supplied `--spec-type` are
+  never auto-retried, and the retry can never loop (single-shot, guarded).
+  Implemented in both the Web launcher (`launcher_routes.py`) and the desktop
+  GUI (`launcher_gui.py`).
+
+### Docs
+
+- `docs/backends/launcher.md`/`.en.md`: new "MTP / speculative decoding"
+  section (auto-detection order, companion-file convention, `mtp_mode=off`,
+  extra-args deferral, `-md` denylist, issue #24309 caveat, API fields), plus
+  the LAUNCH form field table and denylist note updated.
+- `docs/backends/llamacpp-direct.md`/`.en.md`: manual `--spec-type
+  draft-mtp` / `--model-draft` / `--spec-draft-n-max` usage example, with a
+  pointer to the launcher's auto-detection.
+- `docs/backends/launcher-quickstart.md`/`.en.md`: one-line pointer to the
+  new MTP section.
+
+---
+
 ## [v2.7.5] — 2026-07-06 (External-bind startup warning + remote-access guide + docs i18n)
 
 Driven by the first field report against the v2.7.0 Host-validation

{coderouter_cli-2.7.5 → coderouter_cli-2.7.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coderouter-cli
-Version: 2.7.5
+Version: 2.7.7
 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