coderouter-cli 2.7.6__tar.gz → 2.7.8__tar.gz

{coderouter_cli-2.7.6 → coderouter_cli-2.7.8}/CHANGELOG.md

@@ -9,6 +9,183 @@ are kept verbatim where the Japanese text itself is the subject).
 
 ---
 
+## [v2.7.8] — 2026-07-10 (agent_cli Phase 1d: grok)
+
+Adds the second target to the `agent_cli` adapter: `agent: grok` (the xAI
+Grok CLI) is now implemented alongside `claude` from Phase 1a. The
+implementation was verified against the real CLI (grok v0.2.93, [stable]
+channel, 2026-07-10), and several design-time assumptions from the 2026-07
+research did not survive contact with it: the CLI now supports OAuth
+subscription login (the design assumed grok was API-key-only with no
+subscription path), `--sandbox` takes a profile value
+(`off|workspace|read-only|strict`) rather than being a bare flag, a
+Claude-Code-compatible `--permission-mode` exists, and `-p`/`--single` only
+accepts the prompt as an argv value (stdin is not accepted as the prompt) —
+so the adapter delivers the prompt via a temp file instead. The grok CLI is
+still early beta: version pinning is recommended, and the JSON output is
+parsed defensively so schema churn degrades into retryable fallback rather
+than hard failure. `codex` / `gemini` remain schema-declared but rejected
+(Phase 1b/1c pending).
+
+### Added
+
+- **`agent: grok` builder/parser in `AgentCliAdapter`**
+  (`coderouter/adapters/agent_cli.py`) — invokes the Grok CLI one-shot as
+  `grok --prompt-file <workdir>/.coderouter-prompt-<uuid>.txt
+  --output-format json -m <model> --cwd <workdir> --max-turns <N>
+  --no-memory --sandbox read-only --permission-mode plan` (read_only
+  default). Auth is subscription-first, same as claude: the CLI's OAuth
+  login (`grok login`, SuperGrok / X Premium+) stores credentials at
+  `~/.grok/auth.json` (7-day expiry, auto-refresh; `GROK_HOME` overrides),
+  which the adapter's `HOME` inheritance reaches with
+  `passthrough_env: []`. For CI/API-key use the CLI reads
+  `GROK_CODE_XAI_API_KEY` (not `XAI_API_KEY`) — list it in
+  `passthrough_env` only if needed; it takes precedence over OAuth.
+- **`sandbox_mode` → grok flag mapping** — `read_only` →
+  `--sandbox read-only --permission-mode plan`; `edit` →
+  `--sandbox workspace --permission-mode acceptEdits`; `full_auto` →
+  `--sandbox workspace --always-approve`. As with claude, the effective
+  mode is clamped to read-only whenever `allow_file_writes=false`,
+  regardless of `sandbox_mode` (defense in depth). Unlike claude,
+  `full_auto` maps distinctly from `edit`.
+- **Prompt delivery via `--prompt-file`** — grok's `-p`/`--single` requires
+  the prompt as an argv VALUE (verified on the real CLI: stdin is not
+  accepted as the prompt), and putting huge prompts on argv would hit
+  Linux's `MAX_ARG_STRLEN` (~128KiB) and expose the full prompt text to
+  `ps`. The adapter instead writes the prompt to a mode-`0600` temp file
+  inside the isolated workdir and passes `--prompt-file`; the file is
+  always deleted afterwards, including on the timeout and error paths.
+- **`--no-memory` always passed** — grok has a cross-session memory
+  feature; disabling it unconditionally preserves the
+  "one request = one stateless transformation" ethos (a previous call's
+  memory can never leak into the next response). Not configurable.
+- **grok JSON parsing + zero-usage reporting** — `--output-format json`
+  emits a single JSON object `{"text", "stopReason", "sessionId",
+  "requestId", "thought"?}` (verified on grok v0.2.93). `text` becomes the
+  final answer; `sessionId` surfaces as the `coderouter_session_id`
+  response metadata. There are NO token-usage or cost fields, so usage is
+  reported as zeros and `coderouter_cost_usd` stays 0 unless the operator
+  sets unit prices in `ProviderConfig.cost` (in contrast to claude's
+  direct `total_cost_usd`). Parsing is defensive: anything malformed
+  raises a retryable `AdapterError` and the fallback chain advances.
+  Runtime errors (exit 1 with the error text on stderr) surface a stderr
+  tail in the `AdapterError` message.
+
+### Changed
+
+- **Unsupported-agent error message** — constructing the adapter with a
+  not-yet-implemented agent now lists what IS implemented (e.g.
+  `agent 'codex' is not implemented yet (implemented: claude, grok)`)
+  instead of the Phase-1a-specific "claude only" wording. Still
+  `retryable=False` — a configuration error, not a fallback candidate.
+- **Schema docstrings** (`coderouter/config/schemas.py`) — `AgentCliConfig`
+  field descriptions updated for the two-agent reality; the design-time
+  "grok requires `XAI_API_KEY` in `passthrough_env`" validation note was
+  dropped as obsolete (grok now supports subscription OAuth).
+- **Docs & examples** — `docs/backends/external-agents.md`/`.en.md` gain a
+  full grok section (config example, adapter argv, sandbox mapping table,
+  prompt-file rationale, `--no-memory` rationale, JSON schema and
+  zero-usage note, OAuth setup steps, early-beta/version-pin caveat) and
+  updated implementation-status wording. The design doc
+  `docs/designs/external-agents-adapter.md` gets a new appendix §11.3
+  recording the verified deltas between the 2026-07 research and grok
+  v0.2.93 (body text left as the historical record).
+  `examples/providers-agent-cli.yaml` promotes grok out of the
+  not-implemented preview into a documented (still commented-out, so
+  copying the file doesn't require grok to be installed) block with the
+  corrected model (`grok-4.5` — `grok-code-fast-1` was retired
+  2026-05-15), `paid: false` for subscription OAuth, and
+  `passthrough_env: []`.
+
+## [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

{coderouter_cli-2.7.6 → coderouter_cli-2.7.8}/PKG-INFO

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