durar-ai 2026.4.4

package/docs/gateway/authentication.md

@@ -0,0 +1,218 @@
+---
+summary: "Model authentication: OAuth, API keys, and Claude CLI reuse"
+read_when:
+  - Debugging model auth or OAuth expiry
+  - Documenting authentication or credential storage
+title: "Authentication"
+---
+
+# Authentication (Model Providers)
+
+<Note>
+This page covers **model provider** authentication (API keys, OAuth, Claude CLI reuse). For **gateway connection** authentication (token, password, trusted-proxy), see [Configuration](/gateway/configuration) and [Trusted Proxy Auth](/gateway/trusted-proxy-auth).
+</Note>
+
+Durar supports OAuth and API keys for model providers. For always-on gateway
+hosts, API keys are usually the most predictable option. Subscription/OAuth
+flows are also supported when they match your provider account model.
+
+See [/concepts/oauth](/concepts/oauth) for the full OAuth flow and storage
+layout.
+For SecretRef-based auth (`env`/`file`/`exec` providers), see [Secrets Management](/gateway/secrets).
+For credential eligibility/reason-code rules used by `models status --probe`, see
+[Auth Credential Semantics](/auth-credential-semantics).
+
+## Recommended setup (API key, any provider)
+
+If you’re running a long-lived gateway, start with an API key for your chosen
+provider.
+For Anthropic specifically, API key auth is the safe path. Claude CLI reuse is
+the other supported subscription-style setup path.
+
+1. Create an API key in your provider console.
+2. Put it on the **gateway host** (the machine running `Durar gateway`).
+
+```bash
+export <PROVIDER>_API_KEY="..."
+Durar models status
+```
+
+3. If the Gateway runs under systemd/launchd, prefer putting the key in
+   `~/.Durar/.env` so the daemon can read it:
+
+```bash
+cat >> ~/.Durar/.env <<'EOF'
+<PROVIDER>_API_KEY=...
+EOF
+```
+
+Then restart the daemon (or restart your Gateway process) and re-check:
+
+```bash
+Durar models status
+Durar doctor
+```
+
+If you’d rather not manage env vars yourself, onboarding can store
+API keys for daemon use: `Durar onboard`.
+
+See [Help](/help) for details on env inheritance (`env.shellEnv`,
+`~/.Durar/.env`, systemd/launchd).
+
+## Anthropic: legacy token compatibility
+
+Anthropic setup-token auth is still available in Durar as a
+legacy/manual path. Anthropic's public Claude Code docs still cover direct
+Claude Code terminal use under Claude plans, but Anthropic separately told
+Durar users that the **Durar** Claude-login path counts as third-party
+harness usage and requires **Extra Usage** billed separately from the
+subscription.
+
+For the clearest setup path, use an Anthropic API key or migrate to Claude CLI
+on the gateway host.
+
+Manual token entry (any provider; writes `auth-profiles.json` + updates config):
+
+```bash
+Durar models auth paste-token --provider openrouter
+```
+
+Auth profile refs are also supported for static credentials:
+
+- `api_key` credentials can use `keyRef: { source, provider, id }`
+- `token` credentials can use `tokenRef: { source, provider, id }`
+- OAuth-mode profiles do not support SecretRef credentials; if `auth.profiles.<id>.mode` is set to `"oauth"`, SecretRef-backed `keyRef`/`tokenRef` input for that profile is rejected.
+
+Automation-friendly check (exit `1` when expired/missing, `2` when expiring):
+
+```bash
+Durar models status --check
+```
+
+Live auth probes:
+
+```bash
+Durar models status --probe
+```
+
+Notes:
+
+- Probe rows can come from auth profiles, env credentials, or `models.json`.
+- If explicit `auth.order.<provider>` omits a stored profile, probe reports
+  `excluded_by_auth_order` for that profile instead of trying it.
+- If auth exists but Durar cannot resolve a probeable model candidate for
+  that provider, probe reports `status: no_model`.
+- Rate-limit cooldowns can be model-scoped. A profile cooling down for one
+  model can still be usable for a sibling model on the same provider.
+
+Optional ops scripts (systemd/Termux) are documented here:
+[Auth monitoring scripts](/help/scripts#auth-monitoring-scripts)
+
+## Anthropic: Claude CLI migration
+
+If Claude CLI is already installed and signed in on the gateway host, you can
+switch an existing Anthropic setup over to the CLI backend. This is a
+supported Durar migration path for reusing a local Claude CLI login on that
+host.
+
+Prerequisites:
+
+- `claude` installed on the gateway host
+- Claude CLI already signed in there with `claude auth login`
+
+```bash
+Durar models auth login --provider anthropic --method cli --set-default
+```
+
+This keeps your existing Anthropic auth profiles for rollback, but changes the
+default model selection to `claude-cli/...` and adds matching Claude CLI
+allowlist entries under `agents.defaults.models`.
+
+Verify:
+
+```bash
+Durar models status
+```
+
+Onboarding shortcut:
+
+```bash
+Durar onboard --auth-choice anthropic-cli
+```
+
+Interactive `Durar onboard` and `Durar configure` still prefer Claude CLI
+for Anthropic, but Anthropic setup-token is available again as a
+legacy/manual path and should be used with the Extra Usage billing expectation.
+
+## Checking model auth status
+
+```bash
+Durar models status
+Durar doctor
+```
+
+## API key rotation behavior (gateway)
+
+Some providers support retrying a request with alternative keys when an API call
+hits a provider rate limit.
+
+- Priority order:
+  - `Durar_LIVE_<PROVIDER>_KEY` (single override)
+  - `<PROVIDER>_API_KEYS`
+  - `<PROVIDER>_API_KEY`
+  - `<PROVIDER>_API_KEY_*`
+- Google providers also include `GOOGLE_API_KEY` as an additional fallback.
+- The same key list is deduplicated before use.
+- Durar retries with the next key only for rate-limit errors (for example
+  `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many concurrent
+requests`, `ThrottlingException`, `concurrency limit reached`, or
+  `workers_ai ... quota limit exceeded`).
+- Non-rate-limit errors are not retried with alternate keys.
+- If all keys fail, the final error from the last attempt is returned.
+
+## Controlling which credential is used
+
+### Per-session (chat command)
+
+Use `/model <alias-or-id>@<profileId>` to pin a specific provider credential for the current session (example profile ids: `anthropic:default`, `anthropic:work`).
+
+Use `/model` (or `/model list`) for a compact picker; use `/model status` for the full view (candidates + next auth profile, plus provider endpoint details when configured).
+
+### Per-agent (CLI override)
+
+Set an explicit auth profile order override for an agent (stored in that agent’s `auth-profiles.json`):
+
+```bash
+Durar models auth order get --provider anthropic
+Durar models auth order set --provider anthropic anthropic:default
+Durar models auth order clear --provider anthropic
+```
+
+Use `--agent <id>` to target a specific agent; omit it to use the configured default agent.
+When you debug order issues, `Durar models status --probe` shows omitted
+stored profiles as `excluded_by_auth_order` instead of silently skipping them.
+When you debug cooldown issues, remember that rate-limit cooldowns can be tied
+to one model id rather than the whole provider profile.
+
+## Troubleshooting
+
+### "No credentials found"
+
+If the Anthropic profile is missing, migrate that setup to Claude CLI or an API
+key on the **gateway host**, then re-check:
+
+```bash
+Durar models status
+```
+
+### Token expiring/expired
+
+Run `Durar models status` to confirm which profile is expiring. If a legacy
+Anthropic token profile is missing or expired, migrate that setup to Claude CLI
+or an API key.
+
+## Claude CLI requirements
+
+Only needed for the Anthropic Claude CLI reuse path:
+
+- Claude Code CLI installed (`claude` command available)

package/docs/gateway/background-process.md

@@ -0,0 +1,131 @@
+---
+summary: "Background exec execution and process management"
+read_when:
+  - Adding or modifying background exec behavior
+  - Debugging long-running exec tasks
+title: "Background Exec and Process Tool"
+---
+
+# Background Exec + Process Tool
+
+Durar runs shell commands through the `exec` tool and keeps long‑running tasks in memory. The `process` tool manages those background sessions.
+
+## exec tool
+
+Key parameters:
+
+- `command` (required)
+- `yieldMs` (default 10000): auto‑background after this delay
+- `background` (bool): background immediately
+- `timeout` (seconds, default 1800): kill the process after this timeout
+- `elevated` (bool): run outside the sandbox if elevated mode is enabled/allowed (`gateway` by default, or `node` when the exec target is `node`)
+- Need a real TTY? Set `pty: true`.
+- `workdir`, `env`
+
+Behavior:
+
+- Foreground runs return output directly.
+- When backgrounded (explicit or timeout), the tool returns `status: "running"` + `sessionId` and a short tail.
+- Output is kept in memory until the session is polled or cleared.
+- If the `process` tool is disallowed, `exec` runs synchronously and ignores `yieldMs`/`background`.
+- Spawned exec commands receive `Durar_SHELL=exec` for context-aware shell/profile rules.
+- For long-running work that starts now, start it once and rely on automatic
+  completion wake when it is enabled and the command emits output or fails.
+- If automatic completion wake is unavailable, or you need quiet-success
+  confirmation for a command that exited cleanly without output, use `process`
+  to confirm completion.
+- Do not emulate reminders or delayed follow-ups with `sleep` loops or repeated
+  polling; use cron for future work.
+
+## Child process bridging
+
+When spawning long-running child processes outside the exec/process tools (for example, CLI respawns or gateway helpers), attach the child-process bridge helper so termination signals are forwarded and listeners are detached on exit/error. This avoids orphaned processes on systemd and keeps shutdown behavior consistent across platforms.
+
+Environment overrides:
+
+- `PI_BASH_YIELD_MS`: default yield (ms)
+- `PI_BASH_MAX_OUTPUT_CHARS`: in‑memory output cap (chars)
+- `Durar_BASH_PENDING_MAX_OUTPUT_CHARS`: pending stdout/stderr cap per stream (chars)
+- `PI_BASH_JOB_TTL_MS`: TTL for finished sessions (ms, bounded to 1m–3h)
+
+Config (preferred):
+
+- `tools.exec.backgroundMs` (default 10000)
+- `tools.exec.timeoutSec` (default 1800)
+- `tools.exec.cleanupMs` (default 1800000)
+- `tools.exec.notifyOnExit` (default true): enqueue a system event + request heartbeat when a backgrounded exec exits.
+- `tools.exec.notifyOnExitEmptySuccess` (default false): when true, also enqueue completion events for successful backgrounded runs that produced no output.
+
+## process tool
+
+Actions:
+
+- `list`: running + finished sessions
+- `poll`: drain new output for a session (also reports exit status)
+- `log`: read the aggregated output (supports `offset` + `limit`)
+- `write`: send stdin (`data`, optional `eof`)
+- `send-keys`: send explicit key tokens or bytes to a PTY-backed session
+- `submit`: send Enter / carriage return to a PTY-backed session
+- `paste`: send literal text, optionally wrapped in bracketed paste mode
+- `kill`: terminate a background session
+- `clear`: remove a finished session from memory
+- `remove`: kill if running, otherwise clear if finished
+
+Notes:
+
+- Only backgrounded sessions are listed/persisted in memory.
+- Sessions are lost on process restart (no disk persistence).
+- Session logs are only saved to chat history if you run `process poll/log` and the tool result is recorded.
+- `process` is scoped per agent; it only sees sessions started by that agent.
+- Use `poll` / `log` for status, logs, quiet-success confirmation, or
+  completion confirmation when automatic completion wake is unavailable.
+- Use `write` / `send-keys` / `submit` / `paste` / `kill` when you need input
+  or intervention.
+- `process list` includes a derived `name` (command verb + target) for quick scans.
+- `process log` uses line-based `offset`/`limit`.
+- When both `offset` and `limit` are omitted, it returns the last 200 lines and includes a paging hint.
+- When `offset` is provided and `limit` is omitted, it returns from `offset` to the end (not capped to 200).
+- Polling is for on-demand status, not wait-loop scheduling. If the work should
+  happen later, use cron instead.
+
+## Examples
+
+Run a long task and poll later:
+
+```json
+{ "tool": "exec", "command": "sleep 5 && echo done", "yieldMs": 1000 }
+```
+
+```json
+{ "tool": "process", "action": "poll", "sessionId": "<id>" }
+```
+
+Start immediately in background:
+
+```json
+{ "tool": "exec", "command": "npm run build", "background": true }
+```
+
+Send stdin:
+
+```json
+{ "tool": "process", "action": "write", "sessionId": "<id>", "data": "y\n" }
+```
+
+Send PTY keys:
+
+```json
+{ "tool": "process", "action": "send-keys", "sessionId": "<id>", "keys": ["C-c"] }
+```
+
+Submit current line:
+
+```json
+{ "tool": "process", "action": "submit", "sessionId": "<id>" }
+```
+
+Paste literal text:
+
+```json
+{ "tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1\nline2\n" }
+```

package/docs/gateway/bonjour.md

@@ -0,0 +1,179 @@
+---
+summary: "Bonjour/mDNS discovery + debugging (Gateway beacons, clients, and common failure modes)"
+read_when:
+  - Debugging Bonjour discovery issues on macOS/iOS
+  - Changing mDNS service types, TXT records, or discovery UX
+title: "Bonjour Discovery"
+---
+
+# Bonjour / mDNS discovery
+
+Durar uses Bonjour (mDNS / DNS‑SD) to discover an active Gateway (WebSocket endpoint).
+Multicast `local.` browsing is a **LAN-only convenience**. For cross-network discovery, the
+same beacon can also be published through a configured wide-area DNS-SD domain. Discovery is
+still best-effort and does **not** replace SSH or Tailnet-based connectivity.
+
+## Wide-area Bonjour (Unicast DNS-SD) over Tailscale
+
+If the node and gateway are on different networks, multicast mDNS won’t cross the
+boundary. You can keep the same discovery UX by switching to **unicast DNS‑SD**
+("Wide‑Area Bonjour") over Tailscale.
+
+High‑level steps:
+
+1. Run a DNS server on the gateway host (reachable over Tailnet).
+2. Publish DNS‑SD records for `_Durar-gw._tcp` under a dedicated zone
+   (example: `Durar.internal.`).
+3. Configure Tailscale **split DNS** so your chosen domain resolves via that
+   DNS server for clients (including iOS).
+
+Durar supports any discovery domain; `Durar.internal.` is just an example.
+iOS/Android nodes browse both `local.` and your configured wide‑area domain.
+
+### Gateway config (recommended)
+
+```json5
+{
+  gateway: { bind: "tailnet" }, // tailnet-only (recommended)
+  discovery: { wideArea: { enabled: true } }, // enables wide-area DNS-SD publishing
+}
+```
+
+### One-time DNS server setup (gateway host)
+
+```bash
+Durar dns setup --apply
+```
+
+This installs CoreDNS and configures it to:
+
+- listen on port 53 only on the gateway’s Tailscale interfaces
+- serve your chosen domain (example: `Durar.internal.`) from `~/.Durar/dns/<domain>.db`
+
+Validate from a tailnet‑connected machine:
+
+```bash
+dns-sd -B _Durar-gw._tcp Durar.internal.
+dig @<TAILNET_IPV4> -p 53 _Durar-gw._tcp.Durar.internal PTR +short
+```
+
+### Tailscale DNS settings
+
+In the Tailscale admin console:
+
+- Add a nameserver pointing at the gateway’s tailnet IP (UDP/TCP 53).
+- Add split DNS so your discovery domain uses that nameserver.
+
+Once clients accept tailnet DNS, iOS nodes and CLI discovery can browse
+`_Durar-gw._tcp` in your discovery domain without multicast.
+
+### Gateway listener security (recommended)
+
+The Gateway WS port (default `18789`) binds to loopback by default. For LAN/tailnet
+access, bind explicitly and keep auth enabled.
+
+For tailnet‑only setups:
+
+- Set `gateway.bind: "tailnet"` in `~/.Durar/Durar.json`.
+- Restart the Gateway (or restart the macOS menubar app).
+
+## What advertises
+
+Only the Gateway advertises `_Durar-gw._tcp`.
+
+## Service types
+
+- `_Durar-gw._tcp` — gateway transport beacon (used by macOS/iOS/Android nodes).
+
+## TXT keys (non-secret hints)
+
+The Gateway advertises small non‑secret hints to make UI flows convenient:
+
+- `role=gateway`
+- `displayName=<friendly name>`
+- `lanHost=<hostname>.local`
+- `gatewayPort=<port>` (Gateway WS + HTTP)
+- `gatewayTls=1` (only when TLS is enabled)
+- `gatewayTlsSha256=<sha256>` (only when TLS is enabled and fingerprint is available)
+- `canvasPort=<port>` (only when the canvas host is enabled; currently the same as `gatewayPort`)
+- `transport=gateway`
+- `tailnetDns=<magicdns>` (optional hint when Tailnet is available)
+- `sshPort=<port>` (mDNS full mode only; wide-area DNS-SD may omit it)
+- `cliPath=<path>` (mDNS full mode only; wide-area DNS-SD still writes it as a remote-install hint)
+
+Security notes:
+
+- Bonjour/mDNS TXT records are **unauthenticated**. Clients must not treat TXT as authoritative routing.
+- Clients should route using the resolved service endpoint (SRV + A/AAAA). Treat `lanHost`, `tailnetDns`, `gatewayPort`, and `gatewayTlsSha256` as hints only.
+- SSH auto-targeting should likewise use the resolved service host, not TXT-only hints.
+- TLS pinning must never allow an advertised `gatewayTlsSha256` to override a previously stored pin.
+- iOS/Android nodes should treat discovery-based direct connects as **TLS-only** and require explicit user confirmation before trusting a first-time fingerprint.
+
+## Debugging on macOS
+
+Useful built‑in tools:
+
+- Browse instances:
+
+  ```bash
+  dns-sd -B _Durar-gw._tcp local.
+  ```
+
+- Resolve one instance (replace `<instance>`):
+
+  ```bash
+  dns-sd -L "<instance>" _Durar-gw._tcp local.
+  ```
+
+If browsing works but resolving fails, you’re usually hitting a LAN policy or
+mDNS resolver issue.
+
+## Debugging in Gateway logs
+
+The Gateway writes a rolling log file (printed on startup as
+`gateway log file: ...`). Look for `bonjour:` lines, especially:
+
+- `bonjour: advertise failed ...`
+- `bonjour: ... name conflict resolved` / `hostname conflict resolved`
+- `bonjour: watchdog detected non-announced service ...`
+
+## Debugging on iOS node
+
+The iOS node uses `NWBrowser` to discover `_Durar-gw._tcp`.
+
+To capture logs:
+
+- Settings → Gateway → Advanced → **Discovery Debug Logs**
+- Settings → Gateway → Advanced → **Discovery Logs** → reproduce → **Copy**
+
+The log includes browser state transitions and result‑set changes.
+
+## Common failure modes
+
+- **Bonjour doesn’t cross networks**: use Tailnet or SSH.
+- **Multicast blocked**: some Wi‑Fi networks disable mDNS.
+- **Sleep / interface churn**: macOS may temporarily drop mDNS results; retry.
+- **Browse works but resolve fails**: keep machine names simple (avoid emojis or
+  punctuation), then restart the Gateway. The service instance name derives from
+  the host name, so overly complex names can confuse some resolvers.
+
+## Escaped instance names (`\032`)
+
+Bonjour/DNS‑SD often escapes bytes in service instance names as decimal `\DDD`
+sequences (e.g. spaces become `\032`).
+
+- This is normal at the protocol level.
+- UIs should decode for display (iOS uses `BonjourEscapes.decode`).
+
+## Disabling / configuration
+
+- `Durar_DISABLE_BONJOUR=1` disables advertising (legacy: `Durar_DISABLE_BONJOUR`).
+- `gateway.bind` in `~/.Durar/Durar.json` controls the Gateway bind mode.
+- `Durar_SSH_PORT` overrides the SSH port when `sshPort` is advertised (legacy: `Durar_SSH_PORT`).
+- `Durar_TAILNET_DNS` publishes a MagicDNS hint in TXT (legacy: `Durar_TAILNET_DNS`).
+- `Durar_CLI_PATH` overrides the advertised CLI path (legacy: `Durar_CLI_PATH`).
+
+## Related docs
+
+- Discovery policy and transport selection: [Discovery](/gateway/discovery)
+- Node pairing + approvals: [Gateway pairing](/gateway/pairing)

package/docs/gateway/bridge-protocol.md

@@ -0,0 +1,89 @@
+---
+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"
+---
+
+# Bridge protocol (legacy node transport)
+
+<Warning>
+The TCP bridge has been **removed**. Current Durar 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` and could include
+`canvasHostUrl`.
+
+## 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
+  `~/.Durar/Durar.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).