durar-ai 2026.4.4

package/docs/cli/acp.md

@@ -0,0 +1,316 @@
+---
+summary: "Run the ACP bridge for IDE integrations"
+read_when:
+  - Setting up ACP-based IDE integrations
+  - Debugging ACP session routing to the Gateway
+title: "acp"
+---
+
+# acp
+
+Run the [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) bridge that talks to an Durar Gateway.
+
+This command speaks ACP over stdio for IDEs and forwards prompts to the Gateway
+over WebSocket. It keeps ACP sessions mapped to Gateway session keys.
+
+`Durar acp` is a Gateway-backed ACP bridge, not a full ACP-native editor
+runtime. It focuses on session routing, prompt delivery, and basic streaming
+updates.
+
+If you want an external MCP client to talk directly to Durar channel
+conversations instead of hosting an ACP harness session, use
+[`Durar mcp serve`](/cli/mcp) instead.
+
+## What this is not
+
+This page is often confused with ACP harness sessions.
+
+`Durar acp` means:
+
+- Durar acts as an ACP server
+- an IDE or ACP client connects to Durar
+- Durar forwards that work into a Gateway session
+
+This is different from [ACP Agents](/tools/acp-agents), where Durar runs an
+external harness such as Codex or Claude Code through `acpx`.
+
+Quick rule:
+
+- editor/client wants to talk ACP to Durar: use `Durar acp`
+- Durar should launch Codex/Claude/Gemini as an ACP harness: use `/acp spawn` and [ACP Agents](/tools/acp-agents)
+
+## Compatibility Matrix
+
+| ACP area                                                              | Status      | Notes                                                                                                                                                                                                                                            |
+| --------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `initialize`, `newSession`, `prompt`, `cancel`                        | Implemented | Core bridge flow over stdio to Gateway chat/send + abort.                                                                                                                                                                                        |
+| `listSessions`, slash commands                                        | Implemented | Session list works against Gateway session state; commands are advertised via `available_commands_update`.                                                                                                                                       |
+| `loadSession`                                                         | Partial     | Rebinds the ACP session to a Gateway session key and replays stored user/assistant text history. Tool/system history is not reconstructed yet.                                                                                                   |
+| Prompt content (`text`, embedded `resource`, images)                  | Partial     | Text/resources are flattened into chat input; images become Gateway attachments.                                                                                                                                                                 |
+| Session modes                                                         | Partial     | `session/set_mode` is supported and the bridge exposes initial Gateway-backed session controls for thought level, tool verbosity, reasoning, usage detail, and elevated actions. Broader ACP-native mode/config surfaces are still out of scope. |
+| Session info and usage updates                                        | Partial     | The bridge emits `session_info_update` and best-effort `usage_update` notifications from cached Gateway session snapshots. Usage is approximate and only sent when Gateway token totals are marked fresh.                                        |
+| Tool streaming                                                        | Partial     | `tool_call` / `tool_call_update` events include raw I/O, text content, and best-effort file locations when Gateway tool args/results expose them. Embedded terminals and richer diff-native output are still not exposed.                        |
+| Per-session MCP servers (`mcpServers`)                                | Unsupported | Bridge mode rejects per-session MCP server requests. Configure MCP on the Durar gateway or agent instead.                                                                                                                                     |
+| Client filesystem methods (`fs/read_text_file`, `fs/write_text_file`) | Unsupported | The bridge does not call ACP client filesystem methods.                                                                                                                                                                                          |
+| Client terminal methods (`terminal/*`)                                | Unsupported | The bridge does not create ACP client terminals or stream terminal ids through tool calls.                                                                                                                                                       |
+| Session plans / thought streaming                                     | Unsupported | The bridge currently emits output text and tool status, not ACP plan or thought updates.                                                                                                                                                         |
+
+## Known Limitations
+
+- `loadSession` replays stored user and assistant text history, but it does not
+  reconstruct historic tool calls, system notices, or richer ACP-native event
+  types.
+- If multiple ACP clients share the same Gateway session key, event and cancel
+  routing are best-effort rather than strictly isolated per client. Prefer the
+  default isolated `acp:<uuid>` sessions when you need clean editor-local
+  turns.
+- Gateway stop states are translated into ACP stop reasons, but that mapping is
+  less expressive than a fully ACP-native runtime.
+- Initial session controls currently surface a focused subset of Gateway knobs:
+  thought level, tool verbosity, reasoning, usage detail, and elevated
+  actions. Model selection and exec-host controls are not yet exposed as ACP
+  config options.
+- `session_info_update` and `usage_update` are derived from Gateway session
+  snapshots, not live ACP-native runtime accounting. Usage is approximate,
+  carries no cost data, and is only emitted when the Gateway marks total token
+  data as fresh.
+- Tool follow-along data is best-effort. The bridge can surface file paths that
+  appear in known tool args/results, but it does not yet emit ACP terminals or
+  structured file diffs.
+
+## Usage
+
+```bash
+Durar acp
+
+# Remote Gateway
+Durar acp --url wss://gateway-host:18789 --token <token>
+
+# Remote Gateway (token from file)
+Durar acp --url wss://gateway-host:18789 --token-file ~/.Durar/gateway.token
+
+# Attach to an existing session key
+Durar acp --session agent:main:main
+
+# Attach by label (must already exist)
+Durar acp --session-label "support inbox"
+
+# Reset the session key before the first prompt
+Durar acp --session agent:main:main --reset-session
+```
+
+## ACP client (debug)
+
+Use the built-in ACP client to sanity-check the bridge without an IDE.
+It spawns the ACP bridge and lets you type prompts interactively.
+
+```bash
+Durar acp client
+
+# Point the spawned bridge at a remote Gateway
+Durar acp client --server-args --url wss://gateway-host:18789 --token-file ~/.Durar/gateway.token
+
+# Override the server command (default: Durar)
+Durar acp client --server "node" --server-args Durar.mjs acp --url ws://127.0.0.1:19001
+```
+
+Permission model (client debug mode):
+
+- Auto-approval is allowlist-based and only applies to trusted core tool IDs.
+- `read` auto-approval is scoped to the current working directory (`--cwd` when set).
+- ACP only auto-approves narrow readonly classes: scoped `read` calls under the active cwd plus readonly search tools (`search`, `web_search`, `memory_search`). Unknown/non-core tools, out-of-scope reads, exec-capable tools, control-plane tools, mutating tools, and interactive flows always require explicit prompt approval.
+- Server-provided `toolCall.kind` is treated as untrusted metadata (not an authorization source).
+- This ACP bridge policy is separate from ACPX harness permissions. If you run Durar through the `acpx` backend, `plugins.entries.acpx.config.permissionMode=approve-all` is the break-glass “yolo” switch for that harness session.
+
+## How to use this
+
+Use ACP when an IDE (or other client) speaks Agent Client Protocol and you want
+it to drive an Durar Gateway session.
+
+1. Ensure the Gateway is running (local or remote).
+2. Configure the Gateway target (config or flags).
+3. Point your IDE to run `Durar acp` over stdio.
+
+Example config (persisted):
+
+```bash
+Durar config set gateway.remote.url wss://gateway-host:18789
+Durar config set gateway.remote.token <token>
+```
+
+Example direct run (no config write):
+
+```bash
+Durar acp --url wss://gateway-host:18789 --token <token>
+# preferred for local process safety
+Durar acp --url wss://gateway-host:18789 --token-file ~/.Durar/gateway.token
+```
+
+## Selecting agents
+
+ACP does not pick agents directly. It routes by the Gateway session key.
+
+Use agent-scoped session keys to target a specific agent:
+
+```bash
+Durar acp --session agent:main:main
+Durar acp --session agent:design:main
+Durar acp --session agent:qa:bug-123
+```
+
+Each ACP session maps to a single Gateway session key. One agent can have many
+sessions; ACP defaults to an isolated `acp:<uuid>` session unless you override
+the key or label.
+
+Per-session `mcpServers` are not supported in bridge mode. If an ACP client
+sends them during `newSession` or `loadSession`, the bridge returns a clear
+error instead of silently ignoring them.
+
+If you want ACPX-backed sessions to see Durar plugin tools, enable the
+gateway-side ACPX plugin bridge instead of trying to pass per-session
+`mcpServers`. See [ACP Agents](/tools/acp-agents#plugin-tools-mcp-bridge).
+
+## Use from `acpx` (Codex, Claude, other ACP clients)
+
+If you want a coding agent such as Codex or Claude Code to talk to your
+Durar bot over ACP, use `acpx` with its built-in `Durar` target.
+
+Typical flow:
+
+1. Run the Gateway and make sure the ACP bridge can reach it.
+2. Point `acpx Durar` at `Durar acp`.
+3. Target the Durar session key you want the coding agent to use.
+
+Examples:
+
+```bash
+# One-shot request into your default Durar ACP session
+acpx Durar exec "Summarize the active Durar session state."
+
+# Persistent named session for follow-up turns
+acpx Durar sessions ensure --name codex-bridge
+acpx Durar -s codex-bridge --cwd /path/to/repo \
+  "Ask my Durar work agent for recent context relevant to this repo."
+```
+
+If you want `acpx Durar` to target a specific Gateway and session key every
+time, override the `Durar` agent command in `~/.acpx/config.json`:
+
+```json
+{
+  "agents": {
+    "Durar": {
+      "command": "env Durar_HIDE_BANNER=1 Durar_SUPPRESS_NOTES=1 Durar acp --url ws://127.0.0.1:18789 --token-file ~/.Durar/gateway.token --session agent:main:main"
+    }
+  }
+}
+```
+
+For a repo-local Durar checkout, use the direct CLI entrypoint instead of the
+dev runner so the ACP stream stays clean. For example:
+
+```bash
+env Durar_HIDE_BANNER=1 Durar_SUPPRESS_NOTES=1 node Durar.mjs acp ...
+```
+
+This is the easiest way to let Codex, Claude Code, or another ACP-aware client
+pull contextual information from an Durar agent without scraping a terminal.
+
+## Zed editor setup
+
+Add a custom ACP agent in `~/.config/zed/settings.json` (or use Zed’s Settings UI):
+
+```json
+{
+  "agent_servers": {
+    "Durar ACP": {
+      "type": "custom",
+      "command": "Durar",
+      "args": ["acp"],
+      "env": {}
+    }
+  }
+}
+```
+
+To target a specific Gateway or agent:
+
+```json
+{
+  "agent_servers": {
+    "Durar ACP": {
+      "type": "custom",
+      "command": "Durar",
+      "args": [
+        "acp",
+        "--url",
+        "wss://gateway-host:18789",
+        "--token",
+        "<token>",
+        "--session",
+        "agent:design:main"
+      ],
+      "env": {}
+    }
+  }
+}
+```
+
+In Zed, open the Agent panel and select “Durar ACP” to start a thread.
+
+## Session mapping
+
+By default, ACP sessions get an isolated Gateway session key with an `acp:` prefix.
+To reuse a known session, pass a session key or label:
+
+- `--session <key>`: use a specific Gateway session key.
+- `--session-label <label>`: resolve an existing session by label.
+- `--reset-session`: mint a fresh session id for that key (same key, new transcript).
+
+If your ACP client supports metadata, you can override per session:
+
+```json
+{
+  "_meta": {
+    "sessionKey": "agent:main:main",
+    "sessionLabel": "support inbox",
+    "resetSession": true
+  }
+}
+```
+
+Learn more about session keys at [/concepts/session](/concepts/session).
+
+## Options
+
+- `--url <url>`: Gateway WebSocket URL (defaults to gateway.remote.url when configured).
+- `--token <token>`: Gateway auth token.
+- `--token-file <path>`: read Gateway auth token from file.
+- `--password <password>`: Gateway auth password.
+- `--password-file <path>`: read Gateway auth password from file.
+- `--session <key>`: default session key.
+- `--session-label <label>`: default session label to resolve.
+- `--require-existing`: fail if the session key/label does not exist.
+- `--reset-session`: reset the session key before first use.
+- `--no-prefix-cwd`: do not prefix prompts with the working directory.
+- `--provenance <off|meta|meta+receipt>`: include ACP provenance metadata or receipts.
+- `--verbose, -v`: verbose logging to stderr.
+
+Security note:
+
+- `--token` and `--password` can be visible in local process listings on some systems.
+- Prefer `--token-file`/`--password-file` or environment variables (`Durar_GATEWAY_TOKEN`, `Durar_GATEWAY_PASSWORD`).
+- Gateway auth resolution follows the shared contract used by other Gateway clients:
+  - local mode: env (`Durar_GATEWAY_*`) -> `gateway.auth.*` -> `gateway.remote.*` fallback only when `gateway.auth.*` is unset (configured-but-unresolved local SecretRefs fail closed)
+  - remote mode: `gateway.remote.*` with env/config fallback per remote precedence rules
+  - `--url` is override-safe and does not reuse implicit config/env credentials; pass explicit `--token`/`--password` (or file variants)
+- ACP runtime backend child processes receive `Durar_SHELL=acp`, which can be used for context-specific shell/profile rules.
+- `Durar acp client` sets `Durar_SHELL=acp-client` on the spawned bridge process.
+
+### `acp client` options
+
+- `--cwd <dir>`: working directory for the ACP session.
+- `--server <command>`: ACP server command (default: `Durar`).
+- `--server-args <args...>`: extra arguments passed to the ACP server.
+- `--server-verbose`: enable verbose logging on the ACP server.
+- `--verbose, -v`: verbose client logging.

package/docs/cli/agent.md

@@ -0,0 +1,57 @@
+---
+summary: "CLI reference for `Durar agent` (send one agent turn via the Gateway)"
+read_when:
+  - You want to run one agent turn from scripts (optionally deliver reply)
+title: "agent"
+---
+
+# `Durar agent`
+
+Run an agent turn via the Gateway (use `--local` for embedded).
+Use `--agent <id>` to target a configured agent directly.
+
+Pass at least one session selector:
+
+- `--to <dest>`
+- `--session-id <id>`
+- `--agent <id>`
+
+Related:
+
+- Agent send tool: [Agent send](/tools/agent-send)
+
+## Options
+
+- `-m, --message <text>`: required message body
+- `-t, --to <dest>`: recipient used to derive the session key
+- `--session-id <id>`: explicit session id
+- `--agent <id>`: agent id; overrides routing bindings
+- `--thinking <off|minimal|low|medium|high|xhigh>`: agent thinking level
+- `--verbose <on|off>`: persist verbose level for the session
+- `--channel <channel>`: delivery channel; omit to use the main session channel
+- `--reply-to <target>`: delivery target override
+- `--reply-channel <channel>`: delivery channel override
+- `--reply-account <id>`: delivery account override
+- `--local`: run the embedded agent directly (after plugin registry preload)
+- `--deliver`: send the reply back to the selected channel/target
+- `--timeout <seconds>`: override agent timeout (default 600 or config value)
+- `--json`: output JSON
+
+## Examples
+
+```bash
+Durar agent --to +15555550123 --message "status update" --deliver
+Durar agent --agent ops --message "Summarize logs"
+Durar agent --session-id 1234 --message "Summarize inbox" --thinking medium
+Durar agent --to +15555550123 --message "Trace logs" --verbose on --json
+Durar agent --agent ops --message "Generate report" --deliver --reply-channel slack --reply-to "#reports"
+Durar agent --agent ops --message "Run locally" --local
+```
+
+## Notes
+
+- Gateway mode falls back to the embedded agent when the Gateway request fails. Use `--local` to force embedded execution up front.
+- `--local` still preloads the plugin registry first, so plugin-provided providers, tools, and channels stay available during embedded runs.
+- `--channel`, `--reply-channel`, and `--reply-account` affect reply delivery, not session routing.
+- When this command triggers `models.json` regeneration, SecretRef-managed provider credentials are persisted as non-secret markers (for example env var names, `secretref-env:ENV_VAR_NAME`, or `secretref-managed`), not resolved secret plaintext.
+- Marker writes are source-authoritative: Durar persists markers from the active source config snapshot, not from resolved runtime secret values.

package/docs/cli/agents.md

@@ -0,0 +1,220 @@
+---
+summary: "CLI reference for `Durar agents` (list/add/delete/bindings/bind/unbind/set identity)"
+read_when:
+  - You want multiple isolated agents (workspaces + routing + auth)
+title: "agents"
+---
+
+# `Durar agents`
+
+Manage isolated agents (workspaces + auth + routing).
+
+Related:
+
+- Multi-agent routing: [Multi-Agent Routing](/concepts/multi-agent)
+- Agent workspace: [Agent workspace](/concepts/agent-workspace)
+- Skill visibility config: [Skills config](/tools/skills-config)
+
+## Examples
+
+```bash
+Durar agents list
+Durar agents list --bindings
+Durar agents add work --workspace ~/.Durar/workspace-work
+Durar agents add ops --workspace ~/.Durar/workspace-ops --bind telegram:ops --non-interactive
+Durar agents bindings
+Durar agents bind --agent work --bind telegram:ops
+Durar agents unbind --agent work --bind telegram:ops
+Durar agents set-identity --workspace ~/.Durar/workspace --from-identity
+Durar agents set-identity --agent main --avatar avatars/Durar.png
+Durar agents delete work
+```
+
+## Routing bindings
+
+Use routing bindings to pin inbound channel traffic to a specific agent.
+
+If you also want different visible skills per agent, configure
+`agents.defaults.skills` and `agents.list[].skills` in `Durar.json`. See
+[Skills config](/tools/skills-config) and
+[Configuration Reference](/gateway/configuration-reference#agentsdefaultsskills).
+
+List bindings:
+
+```bash
+Durar agents bindings
+Durar agents bindings --agent work
+Durar agents bindings --json
+```
+
+Add bindings:
+
+```bash
+Durar agents bind --agent work --bind telegram:ops --bind discord:guild-a
+```
+
+If you omit `accountId` (`--bind <channel>`), Durar resolves it from channel defaults and plugin setup hooks when available.
+
+If you omit `--agent` for `bind` or `unbind`, Durar targets the current default agent.
+
+### Binding scope behavior
+
+- A binding without `accountId` matches the channel default account only.
+- `accountId: "*"` is the channel-wide fallback (all accounts) and is less specific than an explicit account binding.
+- If the same agent already has a matching channel binding without `accountId`, and you later bind with an explicit or resolved `accountId`, Durar upgrades that existing binding in place instead of adding a duplicate.
+
+Example:
+
+```bash
+# initial channel-only binding
+Durar agents bind --agent work --bind telegram
+
+# later upgrade to account-scoped binding
+Durar agents bind --agent work --bind telegram:ops
+```
+
+After the upgrade, routing for that binding is scoped to `telegram:ops`. If you also want default-account routing, add it explicitly (for example `--bind telegram:default`).
+
+Remove bindings:
+
+```bash
+Durar agents unbind --agent work --bind telegram:ops
+Durar agents unbind --agent work --all
+```
+
+`unbind` accepts either `--all` or one or more `--bind` values, not both.
+
+## Command surface
+
+### `agents`
+
+Running `Durar agents` with no subcommand is equivalent to `Durar agents list`.
+
+### `agents list`
+
+Options:
+
+- `--json`
+- `--bindings`: include full routing rules, not only per-agent counts/summaries
+
+### `agents add [name]`
+
+Options:
+
+- `--workspace <dir>`
+- `--model <id>`
+- `--agent-dir <dir>`
+- `--bind <channel[:accountId]>` (repeatable)
+- `--non-interactive`
+- `--json`
+
+Notes:
+
+- Passing any explicit add flags switches the command into the non-interactive path.
+- Non-interactive mode requires both an agent name and `--workspace`.
+- `main` is reserved and cannot be used as the new agent id.
+
+### `agents bindings`
+
+Options:
+
+- `--agent <id>`
+- `--json`
+
+### `agents bind`
+
+Options:
+
+- `--agent <id>` (defaults to the current default agent)
+- `--bind <channel[:accountId]>` (repeatable)
+- `--json`
+
+### `agents unbind`
+
+Options:
+
+- `--agent <id>` (defaults to the current default agent)
+- `--bind <channel[:accountId]>` (repeatable)
+- `--all`
+- `--json`
+
+### `agents delete <id>`
+
+Options:
+
+- `--force`
+- `--json`
+
+Notes:
+
+- `main` cannot be deleted.
+- Without `--force`, interactive confirmation is required.
+- Workspace, agent state, and session transcript directories are moved to Trash, not hard-deleted.
+
+## Identity files
+
+Each agent workspace can include an `IDENTITY.md` at the workspace root:
+
+- Example path: `~/.Durar/workspace/IDENTITY.md`
+- `set-identity --from-identity` reads from the workspace root (or an explicit `--identity-file`)
+
+Avatar paths resolve relative to the workspace root.
+
+## Set identity
+
+`set-identity` writes fields into `agents.list[].identity`:
+
+- `name`
+- `theme`
+- `emoji`
+- `avatar` (workspace-relative path, http(s) URL, or data URI)
+
+Options:
+
+- `--agent <id>`
+- `--workspace <dir>`
+- `--identity-file <path>`
+- `--from-identity`
+- `--name <name>`
+- `--theme <theme>`
+- `--emoji <emoji>`
+- `--avatar <value>`
+- `--json`
+
+Notes:
+
+- `--agent` or `--workspace` can be used to select the target agent.
+- If you rely on `--workspace` and multiple agents share that workspace, the command fails and asks you to pass `--agent`.
+- When no explicit identity fields are provided, the command reads identity data from `IDENTITY.md`.
+
+Load from `IDENTITY.md`:
+
+```bash
+Durar agents set-identity --workspace ~/.Durar/workspace --from-identity
+```
+
+Override fields explicitly:
+
+```bash
+Durar agents set-identity --agent main --name "Durar" --emoji "🦞" --avatar avatars/Durar.png
+```
+
+Config sample:
+
+```json5
+{
+  agents: {
+    list: [
+      {
+        id: "main",
+        identity: {
+          name: "Durar",
+          theme: "space lobster",
+          emoji: "🦞",
+          avatar: "avatars/Durar.png",
+        },
+      },
+    ],
+  },
+}
+```