nodmix 2026.5.25

package/docs/gateway/bridge-protocol.md

@@ -0,0 +1,94 @@
+---
+summary: "Historical bridge protocol (legacy nodes): TCP JSONL, pairing, scoped RPC"
+read_when:
+  - Building or debugging node clients (iOS/Android/macOS node mode)
+  - Investigating pairing or bridge auth failures
+  - Auditing the node surface exposed by the gateway
+title: "Bridge protocol"
+---
+
+<Warning>
+The TCP bridge has been **removed**. Current Nodmix builds do not ship the bridge listener and `bridge.*` config keys are no longer in the schema. This page is kept for historical reference only. Use the [Gateway Protocol](/gateway/protocol) for all node/operator clients.
+</Warning>
+
+## Why it existed
+
+- **Security boundary**: the bridge exposes a small allowlist instead of the
+  full gateway API surface.
+- **Pairing + node identity**: node admission is owned by the gateway and tied
+  to a per-node token.
+- **Discovery UX**: nodes can discover gateways via Bonjour on LAN, or connect
+  directly over a tailnet.
+- **Loopback WS**: the full WS control plane stays local unless tunneled via SSH.
+
+## Transport
+
+- TCP, one JSON object per line (JSONL).
+- Optional TLS (when `bridge.tls.enabled` is true).
+- Historical default listener port was `18790` (current builds do not start a
+  TCP bridge).
+
+When TLS is enabled, discovery TXT records include `bridgeTls=1` plus
+`bridgeTlsSha256` as a non-secret hint. Note that Bonjour/mDNS TXT records are
+unauthenticated; clients must not treat the advertised fingerprint as an
+authoritative pin without explicit user intent or other out-of-band verification.
+
+## Handshake + pairing
+
+1. Client sends `hello` with node metadata + token (if already paired).
+2. If not paired, gateway replies `error` (`NOT_PAIRED`/`UNAUTHORIZED`).
+3. Client sends `pair-request`.
+4. Gateway waits for approval, then sends `pair-ok` and `hello-ok`.
+
+Historically, `hello-ok` returned `serverName`; hosted plugin surfaces are now
+advertised through `pluginSurfaceUrls`. Canvas/A2UI uses
+`pluginSurfaceUrls.canvas`; the deprecated `canvasHostUrl` alias is not part of
+the refactored protocol.
+
+## Frames
+
+Client → Gateway:
+
+- `req` / `res`: scoped gateway RPC (chat, sessions, config, health, voicewake, skills.bins)
+- `event`: node signals (voice transcript, agent request, chat subscribe, exec lifecycle)
+
+Gateway → Client:
+
+- `invoke` / `invoke-res`: node commands (`canvas.*`, `camera.*`, `screen.record`,
+  `location.get`, `sms.send`)
+- `event`: chat updates for subscribed sessions
+- `ping` / `pong`: keepalive
+
+Legacy allowlist enforcement lived in `src/gateway/server-bridge.ts` (removed).
+
+## Exec lifecycle events
+
+Nodes can emit `exec.finished` or `exec.denied` events to surface system.run activity.
+These are mapped to system events in the gateway. (Legacy nodes may still emit `exec.started`.)
+
+Payload fields (all optional unless noted):
+
+- `sessionKey` (required): agent session to receive the system event.
+- `runId`: unique exec id for grouping.
+- `command`: raw or formatted command string.
+- `exitCode`, `timedOut`, `success`, `output`: completion details (finished only).
+- `reason`: denial reason (denied only).
+
+## Historical tailnet usage
+
+- Bind the bridge to a tailnet IP: `bridge.bind: "tailnet"` in
+  `~/.nodmix/nodmix.json` (historical only; `bridge.*` is no longer valid).
+- Clients connect via MagicDNS name or tailnet IP.
+- Bonjour does **not** cross networks; use manual host/port or wide-area DNS-SD
+  when needed.
+
+## Versioning
+
+The bridge was **implicit v1** (no min/max negotiation). This section is
+historical reference only; current node/operator clients use the WebSocket
+[Gateway Protocol](/gateway/protocol).
+
+## Related
+
+- [Gateway protocol](/gateway/protocol)
+- [Nodes](/nodes)

package/docs/gateway/cli-backends.md

@@ -0,0 +1,420 @@
+---
+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 local AI CLIs and want to reuse them
+  - You want to understand the MCP loopback bridge for CLI backend tool access
+title: "CLI backends"
+---
+
+Nodmix can run **local AI CLIs** as a **text-only fallback** when API providers are down,
+rate-limited, or temporarily misbehaving. This is intentionally conservative:
+
+- **Nodmix tools are not injected directly**, but backends with `bundleMcp: true`
+  can receive gateway tools via a loopback MCP bridge.
+- **JSONL streaming** for CLIs that support it.
+- **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.
+
+<Tip>
+  Building a new backend plugin? Use
+  [CLI backend plugins](/plugins/cli-backend-plugins). This page is for users
+  configuring and operating an already registered backend.
+</Tip>
+
+## Beginner-friendly quick start
+
+You can use Claude Code CLI **without any config** (the bundled Anthropic plugin
+registers a default backend):
+
+```bash
+nodmix agent --message "hi" --model claude-cli/claude-sonnet-4-6
+```
+
+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, Nodmix 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"],
+      },
+      models: {
+        "anthropic/claude-opus-4-6": { alias: "Opus" },
+        "claude-cli/claude-sonnet-4-6": {},
+      },
+    },
+  },
+}
+```
+
+Notes:
+
+- If you use `agents.defaults.models` (allowlist), you must include your CLI backend models there too.
+- If the primary provider fails (auth, rate limits, timeouts), Nodmix will
+  try the CLI backend next.
+
+## 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: {
+        "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",
+          // For CLIs with a dedicated prompt-file flag:
+          // systemPromptFileArg: "--system-file",
+          // Codex-style CLIs can point at a prompt file instead:
+          // systemPromptFileConfigArg: "-c",
+          // systemPromptFileConfigKey: "model_instructions_file",
+          systemPromptWhen: "first",
+          imageArg: "--image",
+          imageMode: "repeat",
+          // Opt in only if this backend may reseed safe invalidated sessions
+          // from bounded raw Nodmix transcript history before compaction.
+          reseedFromRawTranscriptWhenUncompacted: true,
+          serialize: true,
+        },
+      },
+    },
+  },
+}
+```
+
+## How it works
+
+1. **Selects a backend** based on the provider prefix (`claude-cli/...`).
+2. **Builds a system prompt** using the same Nodmix prompt + workspace context.
+3. **Executes the CLI** with a session id (if supported) so history stays consistent.
+   The bundled `claude-cli` backend keeps a Claude stdio process alive per
+   Nodmix session and sends follow-up turns over stream-json stdin.
+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.
+
+<Note>
+The bundled Anthropic `claude-cli` backend is supported again. Anthropic staff
+told us Nodmix-style Claude CLI usage is allowed again, so Nodmix treats
+`claude -p` usage as sanctioned for this integration unless Anthropic publishes
+a new policy.
+</Note>
+
+The bundled Anthropic `claude-cli` backend receives the Nodmix skills snapshot
+two ways: the compact Nodmix skills catalog in the appended system prompt, and
+a temporary Claude Code plugin passed with `--plugin-dir`. The plugin contains
+only the eligible skills for that agent/session, so Claude Code's native skill
+resolver sees the same filtered set that Nodmix would otherwise advertise in
+the prompt. Skill env/API key overrides are still applied by Nodmix to the
+child process environment for the run.
+
+Claude CLI also has its own noninteractive permission mode. Nodmix maps that
+to the existing exec policy instead of adding Claude-specific config: when the
+effective requested exec policy is YOLO (`tools.exec.security: "full"` and
+`tools.exec.ask: "off"`), Nodmix adds `--permission-mode bypassPermissions`.
+Per-agent `agents.list[].tools.exec` settings override global `tools.exec` for
+that agent. To force a different Claude mode, set explicit raw backend args
+such as `--permission-mode default` or `--permission-mode acceptEdits` under
+`agents.defaults.cliBackends.claude-cli.args` and matching `resumeArgs`.
+
+The bundled Anthropic `claude-cli` backend also maps Nodmix `/think` levels
+to Claude Code's native `--effort` flag for non-off levels. `minimal` and
+`low` map to `low`, `adaptive` and `medium` map to `medium`, and `high`,
+`xhigh`, and `max` map directly. Other CLI backends need their owning plugin to
+declare an equivalent argv mapper before `/think` can affect the spawned CLI.
+
+Before Nodmix can use the bundled `claude-cli` backend, Claude Code itself
+must already be logged in on the same host:
+
+```bash
+claude auth login
+claude auth status --text
+nodmix models auth login --provider anthropic --method cli --set-default
+```
+
+Use `agents.defaults.cliBackends.claude-cli.command` only when the `claude`
+binary is not already on `PATH`.
+
+## 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.
+- `claude-cli` defaults to `liveSession: "claude-stdio"`, `output: "jsonl"`,
+  and `input: "stdin"` so follow-up turns reuse the live Claude process while
+  it is active. Warm stdio is the default now, including for custom configs
+  that omit transport fields. If the Gateway restarts or the idle process
+  exits, Nodmix resumes from the stored Claude session id. Stored session
+  ids are verified against an existing readable project transcript before
+  resume, so phantom bindings are cleared with `reason=transcript-missing`
+  instead of silently starting a fresh Claude CLI session under `--resume`.
+- Claude live sessions keep bounded JSONL output guards. Defaults allow up to
+  8 MiB and 20,000 raw JSONL lines per turn. Tool-heavy Claude turns can raise
+  them per backend with
+  `agents.defaults.cliBackends.claude-cli.reliability.outputLimits.maxTurnRawChars`
+  and `maxTurnLines`; Nodmix clamps those settings to 64 MiB and 100,000
+  lines.
+- Stored CLI sessions are provider-owned continuity. The implicit daily session
+  reset does not cut them; `/reset` and explicit `session.reset` policies still
+  do.
+- Fresh CLI sessions normally reseed only from Nodmix's compaction summary
+  plus post-compaction tail. To recover short sessions that are invalidated
+  before compaction, a backend can opt in with
+  `reseedFromRawTranscriptWhenUncompacted: true`. Nodmix still keeps raw
+  transcript reseed bounded and limits it to safe invalidations such as missing
+  CLI transcripts, system-prompt/MCP changes, or session-expired retry; auth
+  profile or credential-epoch changes never reseed raw transcript history.
+
+Serialization notes:
+
+- `serialize: true` keeps same-lane runs ordered.
+- Most CLIs serialize on one provider lane.
+- Nodmix drops stored CLI session reuse when the selected auth identity changes,
+  including a changed auth profile id, static API key, static token, or OAuth
+  account identity when the CLI exposes one. OAuth access and refresh token
+  rotation does not cut the stored CLI session. If a CLI does not expose a
+  stable OAuth account id, Nodmix lets that CLI enforce resume permissions.
+
+## Fallback prelude from claude-cli sessions
+
+When a `claude-cli` attempt fails over to a non-CLI candidate in
+[`agents.defaults.model.fallbacks`](/concepts/model-failover), Nodmix seeds
+the next attempt with a context prelude harvested from Claude Code's local
+JSONL transcript at `~/.claude/projects/`. Without this seed, the fallback
+provider would start cold because Nodmix's own session transcript is empty
+for `claude-cli` runs.
+
+- The prelude prefers the latest `/compact` summary or `compact_boundary`
+  marker, then appends the most recent post-boundary turns up to a char
+  budget. Pre-boundary turns are dropped because the summary already represents
+  them.
+- Tool blocks are coalesced to compact `(tool call: name)` and
+  `(tool result: …)` hints to keep the prompt budget honest. The summary is
+  labeled `(truncated)` if it overflows.
+- Same-provider `claude-cli` to `claude-cli` fallbacks rely on Claude's own
+  `--resume` and skip the prelude.
+- The seed reuses the existing Claude session-file path validation, so
+  arbitrary paths cannot be read.
+
+## Images (pass-through)
+
+If your CLI accepts image paths, set `imageArg`:
+
+```json5
+imageArg: "--image",
+imageMode: "repeat"
+```
+
+Nodmix will write base64 images to temp files. If `imageArg` is set, those
+paths are passed as CLI args. If `imageArg` is missing, Nodmix appends the
+file paths to the prompt (path injection), which is enough for CLIs that auto-
+load local files from plain paths.
+
+## Inputs / outputs
+
+- `output: "json"` (default) tries to parse JSON and extract text + session id.
+- For Gemini CLI JSON output, Nodmix reads reply text from `response` and
+  usage from `stats` when `usage` is missing or empty.
+- `output: "jsonl"` parses JSONL streams 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)
+
+Bundled CLI backend defaults live with their owning plugin. For example,
+Anthropic owns `claude-cli` and Google owns `google-gemini-cli`. OpenAI Codex
+agent runs use the Codex app-server harness through `openai/*`; Nodmix no
+longer registers a bundled `codex-cli` backend.
+
+The bundled Anthropic plugin registers a default for `claude-cli`:
+
+- `command: "claude"`
+- `args: ["-p","--output-format","stream-json","--include-partial-messages","--verbose", ...]`
+- `output: "jsonl"`
+- `input: "stdin"`
+- `modelArg: "--model"`
+- `sessionMode: "always"`
+
+The bundled Google plugin also registers a default for `google-gemini-cli`:
+
+- `command: "gemini"`
+- `args: ["--output-format", "json", "--prompt", "{prompt}"]`
+- `resumeArgs: ["--resume", "{sessionId}", "--output-format", "json", "--prompt", "{prompt}"]`
+- `imageArg: "@"`
+- `imagePathScope: "workspace"`
+- `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 Nodmix `cacheRead`.
+- If `stats.input` is missing, Nodmix 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.
+
+Plugins that need tiny prompt/message compatibility shims can declare
+bidirectional text transforms without replacing a provider or CLI backend:
+
+```typescript
+api.registerTextTransforms({
+  input: [
+    { from: /red basket/g, to: "blue basket" },
+    { from: /paper ticket/g, to: "digital ticket" },
+    { from: /left shelf/g, to: "right shelf" },
+  ],
+  output: [
+    { from: /blue basket/g, to: "red basket" },
+    { from: /digital ticket/g, to: "paper ticket" },
+    { from: /right shelf/g, to: "left shelf" },
+  ],
+});
+```
+
+`input` rewrites the system prompt and user prompt passed to the CLI. `output`
+rewrites streamed assistant deltas and parsed final text before Nodmix handles
+its own control markers and channel delivery.
+
+For CLIs that emit Claude Code stream-json compatible JSONL, set
+`jsonlDialect: "claude-stream-json"` on that backend's config.
+
+## Bundle MCP overlays
+
+CLI backends do **not** receive Nodmix tool calls directly, but a backend can
+opt into a generated MCP config overlay with `bundleMcp: true`.
+
+Current bundled behavior:
+
+- `claude-cli`: generated strict MCP config file
+- `google-gemini-cli`: generated Gemini system settings file
+
+When bundle MCP is enabled, Nodmix:
+
+- spawns a loopback HTTP MCP server that exposes gateway tools to the CLI process
+- authenticates the bridge with a per-session token (`NODMIX_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/settings shape
+- rewrites the launch config using the backend-owned integration mode from the owning extension
+
+If no MCP servers are enabled, Nodmix still injects a strict config when a
+backend opts into bundle MCP so background runs stay isolated.
+
+Session-scoped bundled MCP runtimes are cached for reuse within a session, then
+reaped after `mcp.sessionIdleTtlMs` milliseconds of idle time (default 10
+minutes; set `0` to disable). One-shot embedded runs such as auth probes,
+slug generation, and active-memory recall request cleanup at run end so stdio
+children and Streamable HTTP/SSE streams do not outlive the run.
+
+## Limitations
+
+- **No direct Nodmix tool calls.** Nodmix does not inject tool calls into
+  the CLI backend protocol. Backends only see gateway tools when they opt into
+  `bundleMcp: true`.
+- **Streaming is backend-specific.** Some backends stream JSONL; others buffer
+  until exit.
+- **Structured outputs** depend on the CLI's JSON format.
+
+## 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`.
+- **Images ignored**: set `imageArg` (and verify CLI supports file paths).
+
+## Related
+
+- [Gateway runbook](/gateway)
+- [Local models](/gateway/local-models)