durar-ai 2026.4.4

package/docs/cli/logs.md

@@ -0,0 +1,59 @@
+---
+summary: "CLI reference for `Durar logs` (tail gateway logs via RPC)"
+read_when:
+  - You need to tail Gateway logs remotely (without SSH)
+  - You want JSON log lines for tooling
+title: "logs"
+---
+
+# `Durar logs`
+
+Tail Gateway file logs over RPC (works in remote mode).
+
+Related:
+
+- Logging overview: [Logging](/logging)
+- Gateway CLI: [gateway](/cli/gateway)
+
+## Options
+
+- `--limit <n>`: maximum number of log lines to return (default `200`)
+- `--max-bytes <n>`: maximum bytes to read from the log file (default `250000`)
+- `--follow`: follow the log stream
+- `--interval <ms>`: polling interval while following (default `1000`)
+- `--json`: emit line-delimited JSON events
+- `--plain`: plain text output without styled formatting
+- `--no-color`: disable ANSI colors
+- `--local-time`: render timestamps in your local timezone
+
+## Shared Gateway RPC options
+
+`Durar logs` also accepts the standard Gateway client flags:
+
+- `--url <url>`: Gateway WebSocket URL
+- `--token <token>`: Gateway token
+- `--timeout <ms>`: timeout in ms (default `30000`)
+- `--expect-final`: wait for a final response when the Gateway call is agent-backed
+
+When you pass `--url`, the CLI does not auto-apply config or environment credentials. Include `--token` explicitly if the target Gateway requires auth.
+
+## Examples
+
+```bash
+Durar logs
+Durar logs --follow
+Durar logs --follow --interval 2000
+Durar logs --limit 500 --max-bytes 500000
+Durar logs --json
+Durar logs --plain
+Durar logs --no-color
+Durar logs --limit 500
+Durar logs --local-time
+Durar logs --follow --local-time
+Durar logs --url ws://127.0.0.1:18789 --token "$Durar_GATEWAY_TOKEN"
+```
+
+## Notes
+
+- Use `--local-time` to render timestamps in your local timezone.
+- If the local loopback Gateway asks for pairing, `Durar logs` falls back to the configured local log file automatically. Explicit `--url` targets do not use this fallback.

package/docs/cli/mcp.md

@@ -0,0 +1,505 @@
+---
+summary: "Expose Durar channel conversations over MCP and manage saved MCP server definitions"
+read_when:
+  - Connecting Codex, Claude Code, or another MCP client to Durar-backed channels
+  - Running `Durar mcp serve`
+  - Managing Durar-saved MCP server definitions
+title: "mcp"
+---
+
+# mcp
+
+`Durar mcp` has two jobs:
+
+- run Durar as an MCP server with `Durar mcp serve`
+- manage Durar-owned outbound MCP server definitions with `list`, `show`,
+  `set`, and `unset`
+
+In other words:
+
+- `serve` is Durar acting as an MCP server
+- `list` / `show` / `set` / `unset` is Durar acting as an MCP client-side
+  registry for other MCP servers its runtimes may consume later
+
+Use [`Durar acp`](/cli/acp) when Durar should host a coding harness
+session itself and route that runtime through ACP.
+
+## Durar as an MCP server
+
+This is the `Durar mcp serve` path.
+
+## When to use `serve`
+
+Use `Durar mcp serve` when:
+
+- Codex, Claude Code, or another MCP client should talk directly to
+  Durar-backed channel conversations
+- you already have a local or remote Durar Gateway with routed sessions
+- you want one MCP server that works across Durar's channel backends instead
+  of running separate per-channel bridges
+
+Use [`Durar acp`](/cli/acp) instead when Durar should host the coding
+runtime itself and keep the agent session inside Durar.
+
+## How it works
+
+`Durar mcp serve` starts a stdio MCP server. The MCP client owns that
+process. While the client keeps the stdio session open, the bridge connects to a
+local or remote Durar Gateway over WebSocket and exposes routed channel
+conversations over MCP.
+
+Lifecycle:
+
+1. the MCP client spawns `Durar mcp serve`
+2. the bridge connects to Gateway
+3. routed sessions become MCP conversations and transcript/history tools
+4. live events are queued in memory while the bridge is connected
+5. if Claude channel mode is enabled, the same session can also receive
+   Claude-specific push notifications
+
+Important behavior:
+
+- live queue state starts when the bridge connects
+- older transcript history is read with `messages_read`
+- Claude push notifications only exist while the MCP session is alive
+- when the client disconnects, the bridge exits and the live queue is gone
+
+## Choose a client mode
+
+Use the same bridge in two different ways:
+
+- Generic MCP clients: standard MCP tools only. Use `conversations_list`,
+  `messages_read`, `events_poll`, `events_wait`, `messages_send`, and the
+  approval tools.
+- Claude Code: standard MCP tools plus the Claude-specific channel adapter.
+  Enable `--claude-channel-mode on` or leave the default `auto`.
+
+Today, `auto` behaves the same as `on`. There is no client capability detection
+yet.
+
+## What `serve` exposes
+
+The bridge uses existing Gateway session route metadata to expose channel-backed
+conversations. A conversation appears when Durar already has session state
+with a known route such as:
+
+- `channel`
+- recipient or destination metadata
+- optional `accountId`
+- optional `threadId`
+
+This gives MCP clients one place to:
+
+- list recent routed conversations
+- read recent transcript history
+- wait for new inbound events
+- send a reply back through the same route
+- see approval requests that arrive while the bridge is connected
+
+## Usage
+
+```bash
+# Local Gateway
+Durar mcp serve
+
+# Remote Gateway
+Durar mcp serve --url wss://gateway-host:18789 --token-file ~/.Durar/gateway.token
+
+# Remote Gateway with password auth
+Durar mcp serve --url wss://gateway-host:18789 --password-file ~/.Durar/gateway.password
+
+# Enable verbose bridge logs
+Durar mcp serve --verbose
+
+# Disable Claude-specific push notifications
+Durar mcp serve --claude-channel-mode off
+```
+
+## Bridge tools
+
+The current bridge exposes these MCP tools:
+
+- `conversations_list`
+- `conversation_get`
+- `messages_read`
+- `attachments_fetch`
+- `events_poll`
+- `events_wait`
+- `messages_send`
+- `permissions_list_open`
+- `permissions_respond`
+
+### `conversations_list`
+
+Lists recent session-backed conversations that already have route metadata in
+Gateway session state.
+
+Useful filters:
+
+- `limit`
+- `search`
+- `channel`
+- `includeDerivedTitles`
+- `includeLastMessage`
+
+### `conversation_get`
+
+Returns one conversation by `session_key`.
+
+### `messages_read`
+
+Reads recent transcript messages for one session-backed conversation.
+
+### `attachments_fetch`
+
+Extracts non-text message content blocks from one transcript message. This is a
+metadata view over transcript content, not a standalone durable attachment blob
+store.
+
+### `events_poll`
+
+Reads queued live events since a numeric cursor.
+
+### `events_wait`
+
+Long-polls until the next matching queued event arrives or a timeout expires.
+
+Use this when a generic MCP client needs near-real-time delivery without a
+Claude-specific push protocol.
+
+### `messages_send`
+
+Sends text back through the same route already recorded on the session.
+
+Current behavior:
+
+- requires an existing conversation route
+- uses the session's channel, recipient, account id, and thread id
+- sends text only
+
+### `permissions_list_open`
+
+Lists pending exec/plugin approval requests the bridge has observed since it
+connected to the Gateway.
+
+### `permissions_respond`
+
+Resolves one pending exec/plugin approval request with:
+
+- `allow-once`
+- `allow-always`
+- `deny`
+
+## Event model
+
+The bridge keeps an in-memory event queue while it is connected.
+
+Current event types:
+
+- `message`
+- `exec_approval_requested`
+- `exec_approval_resolved`
+- `plugin_approval_requested`
+- `plugin_approval_resolved`
+- `claude_permission_request`
+
+Important limits:
+
+- the queue is live-only; it starts when the MCP bridge starts
+- `events_poll` and `events_wait` do not replay older Gateway history by
+  themselves
+- durable backlog should be read with `messages_read`
+
+## Claude channel notifications
+
+The bridge can also expose Claude-specific channel notifications. This is the
+Durar equivalent of a Claude Code channel adapter: standard MCP tools remain
+available, but live inbound messages can also arrive as Claude-specific MCP
+notifications.
+
+Flags:
+
+- `--claude-channel-mode off`: standard MCP tools only
+- `--claude-channel-mode on`: enable Claude channel notifications
+- `--claude-channel-mode auto`: current default; same bridge behavior as `on`
+
+When Claude channel mode is enabled, the server advertises Claude experimental
+capabilities and can emit:
+
+- `notifications/claude/channel`
+- `notifications/claude/channel/permission`
+
+Current bridge behavior:
+
+- inbound `user` transcript messages are forwarded as
+  `notifications/claude/channel`
+- Claude permission requests received over MCP are tracked in-memory
+- if the linked conversation later sends `yes abcde` or `no abcde`, the bridge
+  converts that to `notifications/claude/channel/permission`
+- these notifications are live-session only; if the MCP client disconnects,
+  there is no push target
+
+This is intentionally client-specific. Generic MCP clients should rely on the
+standard polling tools.
+
+## MCP client config
+
+Example stdio client config:
+
+```json
+{
+  "mcpServers": {
+    "Durar": {
+      "command": "Durar",
+      "args": [
+        "mcp",
+        "serve",
+        "--url",
+        "wss://gateway-host:18789",
+        "--token-file",
+        "/path/to/gateway.token"
+      ]
+    }
+  }
+}
+```
+
+For most generic MCP clients, start with the standard tool surface and ignore
+Claude mode. Turn Claude mode on only for clients that actually understand the
+Claude-specific notification methods.
+
+## Options
+
+`Durar mcp serve` supports:
+
+- `--url <url>`: Gateway WebSocket URL
+- `--token <token>`: Gateway token
+- `--token-file <path>`: read token from file
+- `--password <password>`: Gateway password
+- `--password-file <path>`: read password from file
+- `--claude-channel-mode <auto|on|off>`: Claude notification mode
+- `-v`, `--verbose`: verbose logs on stderr
+
+Prefer `--token-file` or `--password-file` over inline secrets when possible.
+
+## Security and trust boundary
+
+The bridge does not invent routing. It only exposes conversations that Gateway
+already knows how to route.
+
+That means:
+
+- sender allowlists, pairing, and channel-level trust still belong to the
+  underlying Durar channel configuration
+- `messages_send` can only reply through an existing stored route
+- approval state is live/in-memory only for the current bridge session
+- bridge auth should use the same Gateway token or password controls you would
+  trust for any other remote Gateway client
+
+If a conversation is missing from `conversations_list`, the usual cause is not
+MCP configuration. It is missing or incomplete route metadata in the underlying
+Gateway session.
+
+## Testing
+
+Durar ships a deterministic Docker smoke for this bridge:
+
+```bash
+pnpm test:docker:mcp-channels
+```
+
+That smoke:
+
+- starts a seeded Gateway container
+- starts a second container that spawns `Durar mcp serve`
+- verifies conversation discovery, transcript reads, attachment metadata reads,
+  live event queue behavior, and outbound send routing
+- validates Claude-style channel and permission notifications over the real
+  stdio MCP bridge
+
+This is the fastest way to prove the bridge works without wiring a real
+Telegram, Discord, or iMessage account into the test run.
+
+For broader testing context, see [Testing](/help/testing).
+
+## Troubleshooting
+
+### No conversations returned
+
+Usually means the Gateway session is not already routable. Confirm that the
+underlying session has stored channel/provider, recipient, and optional
+account/thread route metadata.
+
+### `events_poll` or `events_wait` misses older messages
+
+Expected. The live queue starts when the bridge connects. Read older transcript
+history with `messages_read`.
+
+### Claude notifications do not show up
+
+Check all of these:
+
+- the client kept the stdio MCP session open
+- `--claude-channel-mode` is `on` or `auto`
+- the client actually understands the Claude-specific notification methods
+- the inbound message happened after the bridge connected
+
+### Approvals are missing
+
+`permissions_list_open` only shows approval requests observed while the bridge
+was connected. It is not a durable approval history API.
+
+## Durar as an MCP client registry
+
+This is the `Durar mcp list`, `show`, `set`, and `unset` path.
+
+These commands do not expose Durar over MCP. They manage Durar-owned MCP
+server definitions under `mcp.servers` in Durar config.
+
+Those saved definitions are for runtimes that Durar launches or configures
+later, such as embedded Pi and other runtime adapters. Durar stores the
+definitions centrally so those runtimes do not need to keep their own duplicate
+MCP server lists.
+
+Important behavior:
+
+- these commands only read or write Durar config
+- they do not connect to the target MCP server
+- they do not validate whether the command, URL, or remote transport is
+  reachable right now
+- runtime adapters decide which transport shapes they actually support at
+  execution time
+
+## Saved MCP server definitions
+
+Durar also stores a lightweight MCP server registry in config for surfaces
+that want Durar-managed MCP definitions.
+
+Commands:
+
+- `Durar mcp list`
+- `Durar mcp show [name]`
+- `Durar mcp set <name> <json>`
+- `Durar mcp unset <name>`
+
+Notes:
+
+- `list` sorts server names.
+- `show` without a name prints the full configured MCP server object.
+- `set` expects one JSON object value on the command line.
+- `unset` fails if the named server does not exist.
+
+Examples:
+
+```bash
+Durar mcp list
+Durar mcp show context7 --json
+Durar mcp set context7 '{"command":"uvx","args":["context7-mcp"]}'
+Durar mcp set docs '{"url":"https://mcp.example.com"}'
+Durar mcp unset context7
+```
+
+Example config shape:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "context7": {
+        "command": "uvx",
+        "args": ["context7-mcp"]
+      },
+      "docs": {
+        "url": "https://mcp.example.com"
+      }
+    }
+  }
+}
+```
+
+### Stdio transport
+
+Launches a local child process and communicates over stdin/stdout.
+
+| Field                      | Description                       |
+| -------------------------- | --------------------------------- |
+| `command`                  | Executable to spawn (required)    |
+| `args`                     | Array of command-line arguments   |
+| `env`                      | Extra environment variables       |
+| `cwd` / `workingDirectory` | Working directory for the process |
+
+### SSE / HTTP transport
+
+Connects to a remote MCP server over HTTP Server-Sent Events.
+
+| Field                 | Description                                                      |
+| --------------------- | ---------------------------------------------------------------- |
+| `url`                 | HTTP or HTTPS URL of the remote server (required)                |
+| `headers`             | Optional key-value map of HTTP headers (for example auth tokens) |
+| `connectionTimeoutMs` | Per-server connection timeout in ms (optional)                   |
+
+Example:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "remote-tools": {
+        "url": "https://mcp.example.com",
+        "headers": {
+          "Authorization": "Bearer <token>"
+        }
+      }
+    }
+  }
+}
+```
+
+Sensitive values in `url` (userinfo) and `headers` are redacted in logs and
+status output.
+
+### Streamable HTTP transport
+
+`streamable-http` is an additional transport option alongside `sse` and `stdio`. It uses HTTP streaming for bidirectional communication with remote MCP servers.
+
+| Field                 | Description                                                                            |
+| --------------------- | -------------------------------------------------------------------------------------- |
+| `url`                 | HTTP or HTTPS URL of the remote server (required)                                      |
+| `transport`           | Set to `"streamable-http"` to select this transport; when omitted, Durar uses `sse` |
+| `headers`             | Optional key-value map of HTTP headers (for example auth tokens)                       |
+| `connectionTimeoutMs` | Per-server connection timeout in ms (optional)                                         |
+
+Example:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "streaming-tools": {
+        "url": "https://mcp.example.com/stream",
+        "transport": "streamable-http",
+        "connectionTimeoutMs": 10000,
+        "headers": {
+          "Authorization": "Bearer <token>"
+        }
+      }
+    }
+  }
+}
+```
+
+These commands manage saved config only. They do not start the channel bridge,
+open a live MCP client session, or prove the target server is reachable.
+
+## Current limits
+
+This page documents the bridge as shipped today.
+
+Current limits:
+
+- conversation discovery depends on existing Gateway session route metadata
+- no generic push protocol beyond the Claude-specific adapter
+- no message edit or react tools yet
+- HTTP/SSE/streamable-http transport connects to a single remote server; no multiplexed upstream yet
+- `permissions_list_open` only includes approvals observed while the bridge is
+  connected

package/docs/cli/memory.md

@@ -0,0 +1,139 @@
+---
+summary: "CLI reference for `Durar memory` (status/index/search/promote)"
+read_when:
+  - You want to index or search semantic memory
+  - You’re debugging memory availability or indexing
+  - You want to promote recalled short-term memory into `MEMORY.md`
+title: "memory"
+---
+
+# `Durar memory`
+
+Manage semantic memory indexing and search.
+Provided by the active memory plugin (default: `memory-core`; set `plugins.slots.memory = "none"` to disable).
+
+Related:
+
+- Memory concept: [Memory](/concepts/memory)
+- Plugins: [Plugins](/tools/plugin)
+
+## Examples
+
+```bash
+Durar memory status
+Durar memory status --deep
+Durar memory status --fix
+Durar memory index --force
+Durar memory search "meeting notes"
+Durar memory search --query "deployment" --max-results 20
+Durar memory promote --limit 10 --min-score 0.75
+Durar memory promote --apply
+Durar memory promote --json --min-recall-count 0 --min-unique-queries 0
+Durar memory status --json
+Durar memory status --deep --index
+Durar memory status --deep --index --verbose
+Durar memory status --agent main
+Durar memory index --agent main --verbose
+```
+
+## Options
+
+`memory status` and `memory index`:
+
+- `--agent <id>`: scope to a single agent. Without it, these commands run for each configured agent; if no agent list is configured, they fall back to the default agent.
+- `--verbose`: emit detailed logs during probes and indexing.
+
+`memory status`:
+
+- `--deep`: probe vector + embedding availability.
+- `--index`: run a reindex if the store is dirty (implies `--deep`).
+- `--fix`: repair stale recall locks and normalize promotion metadata.
+- `--json`: print JSON output.
+
+`memory index`:
+
+- `--force`: force a full reindex.
+
+`memory search`:
+
+- Query input: pass either positional `[query]` or `--query <text>`.
+- If both are provided, `--query` wins.
+- If neither is provided, the command exits with an error.
+- `--agent <id>`: scope to a single agent (default: the default agent).
+- `--max-results <n>`: limit the number of results returned.
+- `--min-score <n>`: filter out low-score matches.
+- `--json`: print JSON results.
+
+`memory promote`:
+
+Preview and apply short-term memory promotions.
+
+```bash
+Durar memory promote [--apply] [--limit <n>] [--include-promoted]
+```
+
+- `--apply` -- write promotions to `MEMORY.md` (default: preview only).
+- `--limit <n>` -- cap the number of candidates shown.
+- `--include-promoted` -- include entries already promoted in previous cycles.
+
+Full options:
+
+- Ranks short-term candidates from `memory/YYYY-MM-DD.md` using weighted recall signals (`frequency`, `relevance`, `query diversity`, `recency`).
+- Uses recall events captured when `memory_search` returns daily-memory hits.
+- Optional auto-dreaming mode: when `plugins.entries.memory-core.config.dreaming.mode` is `core`, `deep`, or `rem`, `memory-core` auto-manages a cron job that triggers promotion in the background (no manual `Durar cron add` required).
+- `--agent <id>`: scope to a single agent (default: the default agent).
+- `--limit <n>`: max candidates to return/apply.
+- `--min-score <n>`: minimum weighted promotion score.
+- `--min-recall-count <n>`: minimum recall count required for a candidate.
+- `--min-unique-queries <n>`: minimum distinct query count required for a candidate.
+- `--apply`: append selected candidates into `MEMORY.md` and mark them promoted.
+- `--include-promoted`: include already promoted candidates in output.
+- `--json`: print JSON output.
+
+## Dreaming (experimental)
+
+Dreaming is the overnight reflection pass for memory. It is called "dreaming" because the system revisits what was recalled during the day and decides what is worth keeping long-term.
+
+- It is opt-in and disabled by default.
+- Enable it with `plugins.entries.memory-core.config.dreaming.mode`.
+- You can toggle modes from chat with `/dreaming off|core|rem|deep`. Run `/dreaming` (or `/dreaming options`) to see what each mode does.
+- When enabled, `memory-core` automatically creates and maintains a managed cron job.
+- Set `dreaming.limit` to `0` if you want dreaming enabled but automatic promotion effectively paused.
+- Ranking uses weighted signals: recall frequency, retrieval relevance, query diversity, temporal recency, cross-day consolidation, and derived concept richness.
+- Promotion into `MEMORY.md` only happens when quality thresholds are met, so long-term memory stays high signal instead of collecting one-off details.
+- Automatic runs fan out across configured memory workspaces, so one agent's sessions consolidate into that agent's memory workspace instead of only the default session.
+- Promotion re-reads the live daily note before writing to `MEMORY.md`, so edited or deleted short-term snippets do not get promoted from stale recall-store snapshots.
+- Scheduled and manual `memory promote` runs share the same dreaming defaults unless you pass CLI threshold overrides.
+
+Default mode presets:
+
+- `core`: daily at `0 3 * * *`, `minScore=0.75`, `minRecallCount=3`, `minUniqueQueries=2`, `recencyHalfLifeDays=14`
+- `deep`: every 12 hours (`0 */12 * * *`), `minScore=0.8`, `minRecallCount=3`, `minUniqueQueries=3`, `recencyHalfLifeDays=14`
+- `rem`: every 6 hours (`0 */6 * * *`), `minScore=0.85`, `minRecallCount=4`, `minUniqueQueries=3`, `recencyHalfLifeDays=14`
+
+Example:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "memory-core": {
+        "config": {
+          "dreaming": {
+            "mode": "core"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Notes:
+
+- `memory index --verbose` prints per-phase details (provider, model, sources, batch activity).
+- `memory status` includes any extra paths configured via `memorySearch.extraPaths`.
+- If effectively active memory remote API key fields are configured as SecretRefs, the command resolves those values from the active gateway snapshot. If gateway is unavailable, the command fails fast.
+- Gateway version skew note: this command path requires a gateway that supports `secrets.resolve`; older gateways return an unknown-method error.
+- Dreaming cadence defaults to each mode's preset schedule. Override cadence with `plugins.entries.memory-core.config.dreaming.cron` as a cron expression (for example `0 3 * * *`) and fine-tune with `timezone`, `limit`, `minScore`, `minRecallCount`, `minUniqueQueries`, `recencyHalfLifeDays`, and `maxAgeDays`.
+- Set `plugins.entries.memory-core.config.dreaming.verboseLogging` to `true` to emit per-run candidate and apply details into the normal gateway logs while tuning the feature.