durar-ai 2026.4.4

package/docs/concepts/oauth.md

@@ -0,0 +1,225 @@
+---
+summary: "OAuth in Durar: token exchange, storage, and multi-account patterns"
+read_when:
+  - You want to understand Durar OAuth end-to-end
+  - You hit token invalidation / logout issues
+  - You want Claude CLI or OAuth auth flows
+  - You want multiple accounts or profile routing
+title: "OAuth"
+---
+
+# OAuth
+
+Durar supports “subscription auth” via OAuth for providers that offer it
+(notably **OpenAI Codex (ChatGPT OAuth)**). For Anthropic subscriptions, new
+setup should use the local **Claude CLI** login path on the gateway host, but
+Anthropic distinguishes between direct Claude Code usage and Durar's reuse
+path. Anthropic's public Claude Code docs say direct Claude Code use stays
+inside Claude subscription limits. Separately, Anthropic notified Durar
+users on **April 4, 2026 at 12:00 PM PT / 8:00 PM BST** that Durar counts as
+a third-party harness and now requires **Extra Usage** for that traffic.
+OpenAI Codex OAuth is explicitly supported for use in external tools like
+Durar. This page explains:
+
+For Anthropic in production, API key auth is the safer recommended path.
+
+- how the OAuth **token exchange** works (PKCE)
+- where tokens are **stored** (and why)
+- how to handle **multiple accounts** (profiles + per-session overrides)
+
+Durar also supports **provider plugins** that ship their own OAuth or API‑key
+flows. Run them via:
+
+```bash
+Durar models auth login --provider <id>
+```
+
+## The token sink (why it exists)
+
+OAuth providers commonly mint a **new refresh token** during login/refresh flows. Some providers (or OAuth clients) can invalidate older refresh tokens when a new one is issued for the same user/app.
+
+Practical symptom:
+
+- you log in via Durar _and_ via Claude Code / Codex CLI → one of them randomly gets “logged out” later
+
+To reduce that, Durar treats `auth-profiles.json` as a **token sink**:
+
+- the runtime reads credentials from **one place**
+- we can keep multiple profiles and route them deterministically
+- when credentials are reused from an external CLI like Codex CLI, Durar
+  mirrors them with provenance and re-reads that external source instead of
+  rotating the refresh token itself
+
+## Storage (where tokens live)
+
+Secrets are stored **per-agent**:
+
+- Auth profiles (OAuth + API keys + optional value-level refs): `~/.Durar/agents/<agentId>/agent/auth-profiles.json`
+- Legacy compatibility file: `~/.Durar/agents/<agentId>/agent/auth.json`
+  (static `api_key` entries are scrubbed when discovered)
+
+Legacy import-only file (still supported, but not the main store):
+
+- `~/.Durar/credentials/oauth.json` (imported into `auth-profiles.json` on first use)
+
+All of the above also respect `$Durar_STATE_DIR` (state dir override). Full reference: [/gateway/configuration](/gateway/configuration-reference#auth-storage)
+
+For static secret refs and runtime snapshot activation behavior, see [Secrets Management](/gateway/secrets).
+
+## Anthropic legacy token compatibility
+
+<Warning>
+Anthropic's public Claude Code docs say direct Claude Code use stays within
+Claude subscription limits. Separately, Anthropic told Durar users on
+**April 4, 2026 at 12:00 PM PT / 8:00 PM BST** that **Durar counts as a
+third-party harness**. Existing Anthropic token profiles remain technically
+usable in Durar, but Anthropic says the Durar path now requires **Extra
+Usage** (pay-as-you-go billed separately from the subscription) for that
+traffic.
+
+For Anthropic's current direct-Claude-Code plan docs, see [Using Claude Code
+with your Pro or Max
+plan](https://support.claude.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan)
+and [Using Claude Code with your Team or Enterprise
+plan](https://support.anthropic.com/en/articles/11845131-using-claude-code-with-your-team-or-enterprise-plan/).
+
+If you want other subscription-style options in Durar, see [OpenAI
+Codex](/providers/openai), [Qwen Cloud Coding
+Plan](/providers/qwen), [MiniMax Coding Plan](/providers/minimax),
+and [Z.AI / GLM Coding Plan](/providers/glm).
+</Warning>
+
+Durar now exposes Anthropic setup-token again as a legacy/manual path.
+Anthropic's Durar-specific billing notice still applies to that path, so
+use it with the expectation that Anthropic requires **Extra Usage** for
+Durar-driven Claude-login traffic.
+
+## Anthropic Claude CLI migration
+
+If Claude CLI is already installed and signed in on the gateway host, you can
+switch Anthropic model selection over to the local CLI backend. This is a
+supported Durar path when you want to reuse a local Claude CLI login on the
+same host.
+
+Prerequisites:
+
+- the `claude` binary is installed on the gateway host
+- Claude CLI is already authenticated there via `claude auth login`
+
+Migration command:
+
+```bash
+Durar models auth login --provider anthropic --method cli --set-default
+```
+
+Onboarding shortcut:
+
+```bash
+Durar onboard --auth-choice anthropic-cli
+```
+
+This keeps existing Anthropic auth profiles for rollback, but rewrites the main
+default-model path from `anthropic/...` to `claude-cli/...`, rewrites matching
+Anthropic Claude fallbacks, and adds matching `claude-cli/...` allowlist
+entries under `agents.defaults.models`.
+
+Verify:
+
+```bash
+Durar models status
+```
+
+## OAuth exchange (how login works)
+
+Durar’s interactive login flows are implemented in `@mariozechner/pi-ai` and wired into the wizards/commands.
+
+### Anthropic Claude CLI
+
+Flow shape:
+
+Claude CLI path:
+
+1. sign in with `claude auth login` on the gateway host
+2. run `Durar models auth login --provider anthropic --method cli --set-default`
+3. store no new auth profile; switch model selection to `claude-cli/...`
+4. keep existing Anthropic auth profiles for rollback
+
+Anthropic's public Claude Code docs describe this direct Claude subscription
+login flow for `claude` itself. Durar can reuse that local login, but
+Anthropic separately classifies the Durar-controlled path as third-party
+harness usage for billing purposes.
+
+Interactive assistant path:
+
+- `Durar onboard` / `Durar configure` → auth choice `anthropic-cli`
+
+### OpenAI Codex (ChatGPT OAuth)
+
+OpenAI Codex OAuth is explicitly supported for use outside the Codex CLI, including Durar workflows.
+
+Flow shape (PKCE):
+
+1. generate PKCE verifier/challenge + random `state`
+2. open `https://auth.openai.com/oauth/authorize?...`
+3. try to capture callback on `http://127.0.0.1:1455/auth/callback`
+4. if callback can’t bind (or you’re remote/headless), paste the redirect URL/code
+5. exchange at `https://auth.openai.com/oauth/token`
+6. extract `accountId` from the access token and store `{ access, refresh, expires, accountId }`
+
+Wizard path is `Durar onboard` → auth choice `openai-codex`.
+
+## Refresh + expiry
+
+Profiles store an `expires` timestamp.
+
+At runtime:
+
+- if `expires` is in the future → use the stored access token
+- if expired → refresh (under a file lock) and overwrite the stored credentials
+- exception: reused external CLI credentials stay externally managed; Durar
+  re-reads the CLI auth store and never spends the copied refresh token itself
+
+The refresh flow is automatic; you generally don't need to manage tokens manually.
+
+## Multiple accounts (profiles) + routing
+
+Two patterns:
+
+### 1) Preferred: separate agents
+
+If you want “personal” and “work” to never interact, use isolated agents (separate sessions + credentials + workspace):
+
+```bash
+Durar agents add work
+Durar agents add personal
+```
+
+Then configure auth per-agent (wizard) and route chats to the right agent.
+
+### 2) Advanced: multiple profiles in one agent
+
+`auth-profiles.json` supports multiple profile IDs for the same provider.
+
+Pick which profile is used:
+
+- globally via config ordering (`auth.order`)
+- per-session via `/model ...@<profileId>`
+
+Example (session override):
+
+- `/model Opus@anthropic:work`
+
+How to see what profile IDs exist:
+
+- `Durar channels list --json` (shows `auth[]`)
+
+Related docs:
+
+- [/concepts/model-failover](/concepts/model-failover) (rotation + cooldown rules)
+- [/tools/slash-commands](/tools/slash-commands) (command surface)
+
+## Related
+
+- [Authentication](/gateway/authentication) — model provider auth overview
+- [Secrets](/gateway/secrets) — credential storage and SecretRef
+- [Configuration Reference](/gateway/configuration-reference#auth-storage) — auth config keys

package/docs/concepts/presence.md

@@ -0,0 +1,102 @@
+---
+summary: "How Durar presence entries are produced, merged, and displayed"
+read_when:
+  - Debugging the Instances tab
+  - Investigating duplicate or stale instance rows
+  - Changing gateway WS connect or system-event beacons
+title: "Presence"
+---
+
+# Presence
+
+Durar “presence” is a lightweight, best‑effort view of:
+
+- the **Gateway** itself, and
+- **clients connected to the Gateway** (mac app, WebChat, CLI, etc.)
+
+Presence is used primarily to render the macOS app’s **Instances** tab and to
+provide quick operator visibility.
+
+## Presence fields (what shows up)
+
+Presence entries are structured objects with fields like:
+
+- `instanceId` (optional but strongly recommended): stable client identity (usually `connect.client.instanceId`)
+- `host`: human‑friendly host name
+- `ip`: best‑effort IP address
+- `version`: client version string
+- `deviceFamily` / `modelIdentifier`: hardware hints
+- `mode`: `ui`, `webchat`, `cli`, `backend`, `probe`, `test`, `node`, ...
+- `lastInputSeconds`: “seconds since last user input” (if known)
+- `reason`: `self`, `connect`, `node-connected`, `periodic`, ...
+- `ts`: last update timestamp (ms since epoch)
+
+## Producers (where presence comes from)
+
+Presence entries are produced by multiple sources and **merged**.
+
+### 1) Gateway self entry
+
+The Gateway always seeds a “self” entry at startup so UIs show the gateway host
+even before any clients connect.
+
+### 2) WebSocket connect
+
+Every WS client begins with a `connect` request. On successful handshake the
+Gateway upserts a presence entry for that connection.
+
+#### Why one-off CLI commands do not show up
+
+The CLI often connects for short, one‑off commands. To avoid spamming the
+Instances list, `client.mode === "cli"` is **not** turned into a presence entry.
+
+### 3) `system-event` beacons
+
+Clients can send richer periodic beacons via the `system-event` method. The mac
+app uses this to report host name, IP, and `lastInputSeconds`.
+
+### 4) Node connects (role: node)
+
+When a node connects over the Gateway WebSocket with `role: node`, the Gateway
+upserts a presence entry for that node (same flow as other WS clients).
+
+## Merge + dedupe rules (why `instanceId` matters)
+
+Presence entries are stored in a single in‑memory map:
+
+- Entries are keyed by a **presence key**.
+- The best key is a stable `instanceId` (from `connect.client.instanceId`) that survives restarts.
+- Keys are case‑insensitive.
+
+If a client reconnects without a stable `instanceId`, it may show up as a
+**duplicate** row.
+
+## TTL and bounded size
+
+Presence is intentionally ephemeral:
+
+- **TTL:** entries older than 5 minutes are pruned
+- **Max entries:** 200 (oldest dropped first)
+
+This keeps the list fresh and avoids unbounded memory growth.
+
+## Remote/tunnel caveat (loopback IPs)
+
+When a client connects over an SSH tunnel / local port forward, the Gateway may
+see the remote address as `127.0.0.1`. To avoid overwriting a good client‑reported
+IP, loopback remote addresses are ignored.
+
+## Consumers
+
+### macOS Instances tab
+
+The macOS app renders the output of `system-presence` and applies a small status
+indicator (Active/Idle/Stale) based on the age of the last update.
+
+## Debugging tips
+
+- To see the raw list, call `system-presence` against the Gateway.
+- If you see duplicates:
+  - confirm clients send a stable `client.instanceId` in the handshake
+  - confirm periodic beacons use the same `instanceId`
+  - check whether the connection‑derived entry is missing `instanceId` (duplicates are expected)

package/docs/concepts/queue.md

@@ -0,0 +1,89 @@
+---
+summary: "Command queue design that serializes inbound auto-reply runs"
+read_when:
+  - Changing auto-reply execution or concurrency
+title: "Command Queue"
+---
+
+# Command Queue (2026-01-16)
+
+We serialize inbound auto-reply runs (all channels) through a tiny in-process queue to prevent multiple agent runs from colliding, while still allowing safe parallelism across sessions.
+
+## Why
+
+- Auto-reply runs can be expensive (LLM calls) and can collide when multiple inbound messages arrive close together.
+- Serializing avoids competing for shared resources (session files, logs, CLI stdin) and reduces the chance of upstream rate limits.
+
+## How it works
+
+- A lane-aware FIFO queue drains each lane with a configurable concurrency cap (default 1 for unconfigured lanes; main defaults to 4, subagent to 8).
+- `runEmbeddedPiAgent` enqueues by **session key** (lane `session:<key>`) to guarantee only one active run per session.
+- Each session run is then queued into a **global lane** (`main` by default) so overall parallelism is capped by `agents.defaults.maxConcurrent`.
+- When verbose logging is enabled, queued runs emit a short notice if they waited more than ~2s before starting.
+- Typing indicators still fire immediately on enqueue (when supported by the channel) so user experience is unchanged while we wait our turn.
+
+## Queue modes (per channel)
+
+Inbound messages can steer the current run, wait for a followup turn, or do both:
+
+- `steer`: inject immediately into the current run (cancels pending tool calls after the next tool boundary). If not streaming, falls back to followup.
+- `followup`: enqueue for the next agent turn after the current run ends.
+- `collect`: coalesce all queued messages into a **single** followup turn (default). If messages target different channels/threads, they drain individually to preserve routing.
+- `steer-backlog` (aka `steer+backlog`): steer now **and** preserve the message for a followup turn.
+- `interrupt` (legacy): abort the active run for that session, then run the newest message.
+- `queue` (legacy alias): same as `steer`.
+
+Steer-backlog means you can get a followup response after the steered run, so
+streaming surfaces can look like duplicates. Prefer `collect`/`steer` if you want
+one response per inbound message.
+Send `/queue collect` as a standalone command (per-session) or set `messages.queue.byChannel.discord: "collect"`.
+
+Defaults (when unset in config):
+
+- All surfaces → `collect`
+
+Configure globally or per channel via `messages.queue`:
+
+```json5
+{
+  messages: {
+    queue: {
+      mode: "collect",
+      debounceMs: 1000,
+      cap: 20,
+      drop: "summarize",
+      byChannel: { discord: "collect" },
+    },
+  },
+}
+```
+
+## Queue options
+
+Options apply to `followup`, `collect`, and `steer-backlog` (and to `steer` when it falls back to followup):
+
+- `debounceMs`: wait for quiet before starting a followup turn (prevents “continue, continue”).
+- `cap`: max queued messages per session.
+- `drop`: overflow policy (`old`, `new`, `summarize`).
+
+Summarize keeps a short bullet list of dropped messages and injects it as a synthetic followup prompt.
+Defaults: `debounceMs: 1000`, `cap: 20`, `drop: summarize`.
+
+## Per-session overrides
+
+- Send `/queue <mode>` as a standalone command to store the mode for the current session.
+- Options can be combined: `/queue collect debounce:2s cap:25 drop:summarize`
+- `/queue default` or `/queue reset` clears the session override.
+
+## Scope and guarantees
+
+- Applies to auto-reply agent runs across all inbound channels that use the gateway reply pipeline (WhatsApp web, Telegram, Slack, Discord, Signal, iMessage, webchat, etc.).
+- Default lane (`main`) is process-wide for inbound + main heartbeats; set `agents.defaults.maxConcurrent` to allow multiple sessions in parallel.
+- Additional lanes may exist (e.g. `cron`, `subagent`) so background jobs can run in parallel without blocking inbound replies. These detached runs are tracked as [background tasks](/automation/tasks).
+- Per-session lanes guarantee that only one agent run touches a given session at a time.
+- No external dependencies or background worker threads; pure TypeScript + promises.
+
+## Troubleshooting
+
+- If commands seem stuck, enable verbose logs and look for “queued for …ms” lines to confirm the queue is draining.
+- If you need queue depth, enable verbose logs and watch for queue timing lines.

package/docs/concepts/retry.md

@@ -0,0 +1,69 @@
+---
+summary: "Retry policy for outbound provider calls"
+read_when:
+  - Updating provider retry behavior or defaults
+  - Debugging provider send errors or rate limits
+title: "Retry Policy"
+---
+
+# Retry policy
+
+## Goals
+
+- Retry per HTTP request, not per multi-step flow.
+- Preserve ordering by retrying only the current step.
+- Avoid duplicating non-idempotent operations.
+
+## Defaults
+
+- Attempts: 3
+- Max delay cap: 30000 ms
+- Jitter: 0.1 (10 percent)
+- Provider defaults:
+  - Telegram min delay: 400 ms
+  - Discord min delay: 500 ms
+
+## Behavior
+
+### Discord
+
+- Retries only on rate-limit errors (HTTP 429).
+- Uses Discord `retry_after` when available, otherwise exponential backoff.
+
+### Telegram
+
+- Retries on transient errors (429, timeout, connect/reset/closed, temporarily unavailable).
+- Uses `retry_after` when available, otherwise exponential backoff.
+- Markdown parse errors are not retried; they fall back to plain text.
+
+## Configuration
+
+Set retry policy per provider in `~/.Durar/Durar.json`:
+
+```json5
+{
+  channels: {
+    telegram: {
+      retry: {
+        attempts: 3,
+        minDelayMs: 400,
+        maxDelayMs: 30000,
+        jitter: 0.1,
+      },
+    },
+    discord: {
+      retry: {
+        attempts: 3,
+        minDelayMs: 500,
+        maxDelayMs: 30000,
+        jitter: 0.1,
+      },
+    },
+  },
+}
+```
+
+## Notes
+
+- Retries apply per request (message send, media upload, reaction, poll, sticker).
+- Composite flows do not retry completed steps.

package/docs/concepts/session-pruning.md

@@ -0,0 +1,92 @@
+---
+title: "Session Pruning"
+summary: "Trimming old tool results to keep context lean and caching efficient"
+read_when:
+  - You want to reduce context growth from tool outputs
+  - You want to understand Anthropic prompt cache optimization
+---
+
+# Session Pruning
+
+Session pruning trims **old tool results** from the context before each LLM
+call. It reduces context bloat from accumulated tool outputs (exec results, file
+reads, search results) without rewriting normal conversation text.
+
+<Info>
+Pruning is in-memory only -- it does not modify the on-disk session transcript.
+Your full history is always preserved.
+</Info>
+
+## Why it matters
+
+Long sessions accumulate tool output that inflates the context window. This
+increases cost and can force [compaction](/concepts/compaction) sooner than
+necessary.
+
+Pruning is especially valuable for **Anthropic prompt caching**. After the cache
+TTL expires, the next request re-caches the full prompt. Pruning reduces the
+cache-write size, directly lowering cost.
+
+## How it works
+
+1. Wait for the cache TTL to expire (default 5 minutes).
+2. Find old tool results for normal pruning (conversation text is left alone).
+3. **Soft-trim** oversized results -- keep the head and tail, insert `...`.
+4. **Hard-clear** the rest -- replace with a placeholder.
+5. Reset the TTL so follow-up requests reuse the fresh cache.
+
+## Legacy image cleanup
+
+Durar also runs a separate idempotent cleanup for older legacy sessions that
+persisted raw image blocks in history.
+
+- It preserves the **3 most recent completed turns** byte-for-byte so prompt
+  cache prefixes for recent follow-ups stay stable.
+- Older already-processed image blocks in `user` or `toolResult` history can be
+  replaced with `[image data removed - already processed by model]`.
+- This is separate from normal cache-TTL pruning. It exists to stop repeated
+  image payloads from busting prompt caches on later turns.
+
+## Smart defaults
+
+Durar auto-enables pruning for Anthropic profiles:
+
+| Profile type                                            | Pruning enabled | Heartbeat |
+| ------------------------------------------------------- | --------------- | --------- |
+| Anthropic OAuth/token auth (including Claude CLI reuse) | Yes             | 1 hour    |
+| API key                                                 | Yes             | 30 min    |
+
+If you set explicit values, Durar does not override them.
+
+## Enable or disable
+
+Pruning is off by default for non-Anthropic providers. To enable:
+
+```json5
+{
+  agents: {
+    defaults: {
+      contextPruning: { mode: "cache-ttl", ttl: "5m" },
+    },
+  },
+}
+```
+
+To disable: set `mode: "off"`.
+
+## Pruning vs compaction
+
+|            | Pruning            | Compaction              |
+| ---------- | ------------------ | ----------------------- |
+| **What**   | Trims tool results | Summarizes conversation |
+| **Saved?** | No (per-request)   | Yes (in transcript)     |
+| **Scope**  | Tool results only  | Entire conversation     |
+
+They complement each other -- pruning keeps tool output lean between
+compaction cycles.
+
+## Further reading
+
+- [Compaction](/concepts/compaction) -- summarization-based context reduction
+- [Gateway Configuration](/gateway/configuration) -- all pruning config knobs
+  (`contextPruning.*`)