durar-ai 2026.4.4

package/docs/gateway/cli-backends.md

@@ -0,0 +1,310 @@
+---
+summary: "CLI backends: local AI CLI fallback with optional MCP tool bridge"
+read_when:
+  - You want a reliable fallback when API providers fail
+  - You are running Claude CLI or other local AI CLIs and want to reuse them
+  - You want to understand the MCP loopback bridge for CLI backend tool access
+title: "CLI Backends"
+---
+
+# CLI backends (fallback runtime)
+
+Durar can run **local AI CLIs** as a **text-only fallback** when API providers are down,
+rate-limited, or temporarily misbehaving. This is intentionally conservative:
+
+- **Durar tools are not injected directly**, but backends with `bundleMcp: true`
+  (the Claude CLI default) can receive gateway tools via a loopback MCP bridge.
+- **JSONL streaming** (Claude CLI uses `--output-format stream-json` with
+  `--include-partial-messages`; prompts are sent via stdin).
+- **Sessions are supported** (so follow-up turns stay coherent).
+- **Images can be passed through** if the CLI accepts image paths.
+
+This is designed as a **safety net** rather than a primary path. Use it when you
+want “always works” text responses without relying on external APIs.
+
+If you want a full harness runtime with ACP session controls, background tasks,
+thread/conversation binding, and persistent external coding sessions, use
+[ACP Agents](/tools/acp-agents) instead. CLI backends are not ACP.
+
+## Beginner-friendly quick start
+
+You can use Claude CLI **without any config** (the bundled Anthropic plugin
+registers a default backend):
+
+```bash
+Durar agent --message "hi" --model claude-cli/claude-sonnet-4-6
+```
+
+Codex CLI also works out of the box (via the bundled OpenAI plugin):
+
+```bash
+Durar agent --message "hi" --model codex-cli/gpt-5.4
+```
+
+If your gateway runs under launchd/systemd and PATH is minimal, add just the
+command path:
+
+```json5
+{
+  agents: {
+    defaults: {
+      cliBackends: {
+        "claude-cli": {
+          command: "/opt/homebrew/bin/claude",
+        },
+      },
+    },
+  },
+}
+```
+
+That’s it. No keys, no extra auth config needed beyond the CLI itself.
+
+If you use a bundled CLI backend as the **primary message provider** on a
+gateway host, Durar now auto-loads the owning bundled plugin when your config
+explicitly references that backend in a model ref or under
+`agents.defaults.cliBackends`.
+
+## Using it as a fallback
+
+Add a CLI backend to your fallback list so it only runs when primary models fail:
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: {
+        primary: "anthropic/claude-opus-4-6",
+        fallbacks: ["claude-cli/claude-sonnet-4-6", "claude-cli/claude-opus-4-6"],
+      },
+      models: {
+        "anthropic/claude-opus-4-6": { alias: "Opus" },
+        "claude-cli/claude-sonnet-4-6": {},
+        "claude-cli/claude-opus-4-6": {},
+      },
+    },
+  },
+}
+```
+
+Notes:
+
+- If you use `agents.defaults.models` (allowlist), you must include `claude-cli/...`.
+- If the primary provider fails (auth, rate limits, timeouts), Durar will
+  try the CLI backend next.
+- The bundled Claude CLI backend still accepts shorter aliases like
+  `claude-cli/opus`, `claude-cli/opus-4.6`, or `claude-cli/sonnet`, but docs
+  and config examples use the canonical `claude-cli/claude-*` refs.
+
+## Configuration overview
+
+All CLI backends live under:
+
+```
+agents.defaults.cliBackends
+```
+
+Each entry is keyed by a **provider id** (e.g. `claude-cli`, `my-cli`).
+The provider id becomes the left side of your model ref:
+
+```
+<provider>/<model>
+```
+
+### Example configuration
+
+```json5
+{
+  agents: {
+    defaults: {
+      cliBackends: {
+        "claude-cli": {
+          command: "/opt/homebrew/bin/claude",
+        },
+        "my-cli": {
+          command: "my-cli",
+          args: ["--json"],
+          output: "json",
+          input: "arg",
+          modelArg: "--model",
+          modelAliases: {
+            "claude-opus-4-6": "opus",
+            "claude-sonnet-4-6": "sonnet",
+          },
+          sessionArg: "--session",
+          sessionMode: "existing",
+          sessionIdFields: ["session_id", "conversation_id"],
+          systemPromptArg: "--system",
+          systemPromptWhen: "first",
+          imageArg: "--image",
+          imageMode: "repeat",
+          serialize: true,
+        },
+      },
+    },
+  },
+}
+```
+
+## How it works
+
+1. **Selects a backend** based on the provider prefix (`claude-cli/...`).
+2. **Builds a system prompt** using the same Durar prompt + workspace context.
+3. **Executes the CLI** with a session id (if supported) so history stays consistent.
+4. **Parses output** (JSON or plain text) and returns the final text.
+5. **Persists session ids** per backend, so follow-ups reuse the same CLI session.
+
+## Sessions
+
+- If the CLI supports sessions, set `sessionArg` (e.g. `--session-id`) or
+  `sessionArgs` (placeholder `{sessionId}`) when the ID needs to be inserted
+  into multiple flags.
+- If the CLI uses a **resume subcommand** with different flags, set
+  `resumeArgs` (replaces `args` when resuming) and optionally `resumeOutput`
+  (for non-JSON resumes).
+- `sessionMode`:
+  - `always`: always send a session id (new UUID if none stored).
+  - `existing`: only send a session id if one was stored before.
+  - `none`: never send a session id.
+
+Serialization notes:
+
+- `serialize: true` keeps same-lane runs ordered.
+- Most CLIs serialize on one provider lane.
+- `claude-cli` is narrower: resumed runs serialize per Claude session id, and fresh runs serialize per workspace path. Independent workspaces can run in parallel.
+- Durar drops stored CLI session reuse when the backend auth state changes, including relogin, token rotation, or a changed auth profile credential.
+
+## Images (pass-through)
+
+If your CLI accepts image paths, set `imageArg`:
+
+```json5
+imageArg: "--image",
+imageMode: "repeat"
+```
+
+Durar will write base64 images to temp files. If `imageArg` is set, those
+paths are passed as CLI args. If `imageArg` is missing, Durar appends the
+file paths to the prompt (path injection), which is enough for CLIs that auto-
+load local files from plain paths (Claude CLI behavior).
+
+## Inputs / outputs
+
+- `output: "json"` (default) tries to parse JSON and extract text + session id.
+- For Gemini CLI JSON output, Durar reads reply text from `response` and
+  usage from `stats` when `usage` is missing or empty.
+- `output: "jsonl"` parses JSONL streams (for example Claude CLI `stream-json`
+  and Codex CLI `--json`) and extracts the final agent message plus session
+  identifiers when present.
+- `output: "text"` treats stdout as the final response.
+
+Input modes:
+
+- `input: "arg"` (default) passes the prompt as the last CLI arg.
+- `input: "stdin"` sends the prompt via stdin.
+- If the prompt is very long and `maxPromptArgChars` is set, stdin is used.
+
+## Defaults (plugin-owned)
+
+The bundled Anthropic plugin registers a default for `claude-cli`:
+
+- `command: "claude"`
+- `args: ["-p", "--output-format", "stream-json", "--include-partial-messages", "--verbose", "--permission-mode", "bypassPermissions"]`
+- `resumeArgs: ["-p", "--output-format", "stream-json", "--include-partial-messages", "--verbose", "--permission-mode", "bypassPermissions", "--resume", "{sessionId}"]`
+- `output: "jsonl"`
+- `input: "stdin"`
+- `modelArg: "--model"`
+- `systemPromptArg: "--append-system-prompt"`
+- `sessionArg: "--session-id"`
+- `systemPromptWhen: "first"`
+- `sessionMode: "always"`
+
+The bundled OpenAI plugin also registers a default for `codex-cli`:
+
+- `command: "codex"`
+- `args: ["exec","--json","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]`
+- `resumeArgs: ["exec","resume","{sessionId}","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]`
+- `output: "jsonl"`
+- `resumeOutput: "text"`
+- `modelArg: "--model"`
+- `imageArg: "--image"`
+- `sessionMode: "existing"`
+
+The bundled Google plugin also registers a default for `google-gemini-cli`:
+
+- `command: "gemini"`
+- `args: ["--prompt", "--output-format", "json"]`
+- `resumeArgs: ["--resume", "{sessionId}", "--prompt", "--output-format", "json"]`
+- `modelArg: "--model"`
+- `sessionMode: "existing"`
+- `sessionIdFields: ["session_id", "sessionId"]`
+
+Prerequisite: the local Gemini CLI must be installed and available as
+`gemini` on `PATH` (`brew install gemini-cli` or
+`npm install -g @google/gemini-cli`).
+
+Gemini CLI JSON notes:
+
+- Reply text is read from the JSON `response` field.
+- Usage falls back to `stats` when `usage` is absent or empty.
+- `stats.cached` is normalized into Durar `cacheRead`.
+- If `stats.input` is missing, Durar derives input tokens from
+  `stats.input_tokens - stats.cached`.
+
+Override only if needed (common: absolute `command` path).
+
+## Plugin-owned defaults
+
+CLI backend defaults are now part of the plugin surface:
+
+- Plugins register them with `api.registerCliBackend(...)`.
+- The backend `id` becomes the provider prefix in model refs.
+- User config in `agents.defaults.cliBackends.<id>` still overrides the plugin default.
+- Backend-specific config cleanup stays plugin-owned through the optional
+  `normalizeConfig` hook.
+
+## Bundle MCP overlays
+
+CLI backends do **not** receive Durar tool calls directly, but a backend can
+opt into a generated MCP config overlay with `bundleMcp: true`.
+
+Current bundled behavior:
+
+- `claude-cli`: `bundleMcp: true` (default)
+- `codex-cli`: no bundle MCP overlay
+- `google-gemini-cli`: no bundle MCP overlay
+
+When bundle MCP is enabled, Durar:
+
+- spawns a loopback HTTP MCP server that exposes gateway tools to the CLI process
+- authenticates the bridge with a per-session token (`Durar_MCP_TOKEN`)
+- scopes tool access to the current session, account, and channel context
+- loads enabled bundle-MCP servers for the current workspace
+- merges them with any existing backend `--mcp-config`
+- rewrites the CLI args to pass `--strict-mcp-config --mcp-config <generated-file>`
+
+The `--strict-mcp-config` flag prevents Claude CLI from inheriting ambient
+user-level or global MCP servers. If no MCP servers are enabled, Durar still
+injects a strict empty config so background runs stay isolated.
+
+## Limitations
+
+- **No direct Durar tool calls.** Durar does not inject tool calls into
+  the CLI backend protocol. However, backends with `bundleMcp: true` (the
+  Claude CLI default) receive gateway tools through a loopback MCP bridge,
+  so Claude CLI can invoke Durar tools via its native MCP support.
+- **Streaming is backend-specific.** Claude CLI uses JSONL streaming
+  (`stream-json` with `--include-partial-messages`); other CLI backends may
+  still be buffered until exit.
+- **Structured outputs** depend on the CLI’s JSON format.
+- **Codex CLI sessions** resume via text output (no JSONL), which is less
+  structured than the initial `--json` run. Durar sessions still work
+  normally.
+
+## Troubleshooting
+
+- **CLI not found**: set `command` to a full path.
+- **Wrong model name**: use `modelAliases` to map `provider/model` → CLI model.
+- **No session continuity**: ensure `sessionArg` is set and `sessionMode` is not
+  `none` (Codex CLI currently cannot resume with JSON output).
+- **Images ignored**: set `imageArg` (and verify CLI supports file paths).