durar-ai 2026.4.4

package/docs/tools/perplexity-search.md

@@ -0,0 +1,185 @@
+---
+summary: "Perplexity Search API and Sonar/OpenRouter compatibility for web_search"
+read_when:
+  - You want to use Perplexity Search for web search
+  - You need PERPLEXITY_API_KEY or OPENROUTER_API_KEY setup
+title: "Perplexity Search"
+---
+
+# Perplexity Search API
+
+Durar supports Perplexity Search API as a `web_search` provider.
+It returns structured results with `title`, `url`, and `snippet` fields.
+
+For compatibility, Durar also supports legacy Perplexity Sonar/OpenRouter setups.
+If you use `OPENROUTER_API_KEY`, an `sk-or-...` key in `plugins.entries.perplexity.config.webSearch.apiKey`, or set `plugins.entries.perplexity.config.webSearch.baseUrl` / `model`, the provider switches to the chat-completions path and returns AI-synthesized answers with citations instead of structured Search API results.
+
+## Getting a Perplexity API key
+
+1. Create a Perplexity account at [perplexity.ai/settings/api](https://www.perplexity.ai/settings/api)
+2. Generate an API key in the dashboard
+3. Store the key in config or set `PERPLEXITY_API_KEY` in the Gateway environment.
+
+## OpenRouter compatibility
+
+If you were already using OpenRouter for Perplexity Sonar, keep `provider: "perplexity"` and set `OPENROUTER_API_KEY` in the Gateway environment, or store an `sk-or-...` key in `plugins.entries.perplexity.config.webSearch.apiKey`.
+
+Optional compatibility controls:
+
+- `plugins.entries.perplexity.config.webSearch.baseUrl`
+- `plugins.entries.perplexity.config.webSearch.model`
+
+## Config examples
+
+### Native Perplexity Search API
+
+```json5
+{
+  plugins: {
+    entries: {
+      perplexity: {
+        config: {
+          webSearch: {
+            apiKey: "pplx-...",
+          },
+        },
+      },
+    },
+  },
+  tools: {
+    web: {
+      search: {
+        provider: "perplexity",
+      },
+    },
+  },
+}
+```
+
+### OpenRouter / Sonar compatibility
+
+```json5
+{
+  plugins: {
+    entries: {
+      perplexity: {
+        config: {
+          webSearch: {
+            apiKey: "<openrouter-api-key>",
+            baseUrl: "https://openrouter.ai/api/v1",
+            model: "perplexity/sonar-pro",
+          },
+        },
+      },
+    },
+  },
+  tools: {
+    web: {
+      search: {
+        provider: "perplexity",
+      },
+    },
+  },
+}
+```
+
+## Where to set the key
+
+**Via config:** run `Durar configure --section web`. It stores the key in
+`~/.Durar/Durar.json` under `plugins.entries.perplexity.config.webSearch.apiKey`.
+That field also accepts SecretRef objects.
+
+**Via environment:** set `PERPLEXITY_API_KEY` or `OPENROUTER_API_KEY`
+in the Gateway process environment. For a gateway install, put it in
+`~/.Durar/.env` (or your service environment). See [Env vars](/help/faq#env-vars-and-env-loading).
+
+If `provider: "perplexity"` is configured and the Perplexity key SecretRef is unresolved with no env fallback, startup/reload fails fast.
+
+## Tool parameters
+
+These parameters apply to the native Perplexity Search API path.
+
+| Parameter             | Description                                          |
+| --------------------- | ---------------------------------------------------- |
+| `query`               | Search query (required)                              |
+| `count`               | Number of results to return (1-10, default: 5)       |
+| `country`             | 2-letter ISO country code (e.g., "US", "DE")         |
+| `language`            | ISO 639-1 language code (e.g., "en", "de", "fr")     |
+| `freshness`           | Time filter: `day` (24h), `week`, `month`, or `year` |
+| `date_after`          | Only results published after this date (YYYY-MM-DD)  |
+| `date_before`         | Only results published before this date (YYYY-MM-DD) |
+| `domain_filter`       | Domain allowlist/denylist array (max 20)             |
+| `max_tokens`          | Total content budget (default: 25000, max: 1000000)  |
+| `max_tokens_per_page` | Per-page token limit (default: 2048)                 |
+
+For the legacy Sonar/OpenRouter compatibility path:
+
+- `query`, `count`, and `freshness` are accepted
+- `count` is compatibility-only there; the response is still one synthesized
+  answer with citations rather than an N-result list
+- Search API-only filters such as `country`, `language`, `date_after`,
+  `date_before`, `domain_filter`, `max_tokens`, and `max_tokens_per_page`
+  return explicit errors
+
+**Examples:**
+
+```javascript
+// Country and language-specific search
+await web_search({
+  query: "renewable energy",
+  country: "DE",
+  language: "de",
+});
+
+// Recent results (past week)
+await web_search({
+  query: "AI news",
+  freshness: "week",
+});
+
+// Date range search
+await web_search({
+  query: "AI developments",
+  date_after: "2024-01-01",
+  date_before: "2024-06-30",
+});
+
+// Domain filtering (allowlist)
+await web_search({
+  query: "climate research",
+  domain_filter: ["nature.com", "science.org", ".edu"],
+});
+
+// Domain filtering (denylist - prefix with -)
+await web_search({
+  query: "product reviews",
+  domain_filter: ["-reddit.com", "-pinterest.com"],
+});
+
+// More content extraction
+await web_search({
+  query: "detailed AI research",
+  max_tokens: 50000,
+  max_tokens_per_page: 4096,
+});
+```
+
+### Domain filter rules
+
+- Maximum 20 domains per filter
+- Cannot mix allowlist and denylist in the same request
+- Use `-` prefix for denylist entries (e.g., `["-reddit.com"]`)
+
+## Notes
+
+- Perplexity Search API returns structured web search results (`title`, `url`, `snippet`)
+- OpenRouter or explicit `plugins.entries.perplexity.config.webSearch.baseUrl` / `model` switches Perplexity back to Sonar chat completions for compatibility
+- Sonar/OpenRouter compatibility returns one synthesized answer with citations, not structured result rows
+- Results are cached for 15 minutes by default (configurable via `cacheTtlMinutes`)
+
+## Related
+
+- [Web Search overview](/tools/web) -- all providers and auto-detection
+- [Perplexity Search API docs](https://docs.perplexity.ai/docs/search/quickstart) -- official Perplexity documentation
+- [Brave Search](/tools/brave-search) -- structured results with country/language filters
+- [Exa Search](/tools/exa-search) -- neural search with content extraction

package/docs/tools/plugin.md

@@ -0,0 +1,348 @@
+---
+summary: "Install, configure, and manage Durar plugins"
+read_when:
+  - Installing or configuring plugins
+  - Understanding plugin discovery and load rules
+  - Working with Codex/Claude-compatible plugin bundles
+title: "Plugins"
+sidebarTitle: "Install and Configure"
+---
+
+# Plugins
+
+Plugins extend Durar with new capabilities: channels, model providers,
+tools, skills, speech, realtime transcription, realtime voice,
+media-understanding, image generation, video generation, web fetch, web
+search, and more. Some plugins are **core** (shipped with Durar), others
+are **external** (published on npm by the community).
+
+## Quick start
+
+<Steps>
+  <Step title="See what is loaded">
+    ```bash
+    Durar plugins list
+    ```
+  </Step>
+
+  <Step title="Install a plugin">
+    ```bash
+    # From npm
+    Durar plugins install @Durar/voice-call
+
+    # From a local directory or archive
+    Durar plugins install ./my-plugin
+    Durar plugins install ./my-plugin.tgz
+    ```
+
+  </Step>
+
+  <Step title="Restart the Gateway">
+    ```bash
+    Durar gateway restart
+    ```
+
+    Then configure under `plugins.entries.\<id\>.config` in your config file.
+
+  </Step>
+</Steps>
+
+If you prefer chat-native control, enable `commands.plugins: true` and use:
+
+```text
+/plugin install Durar Gateway:@Durar/voice-call
+/plugin show voice-call
+/plugin enable voice-call
+```
+
+The install path uses the same resolver as the CLI: local path/archive, explicit
+`Durar Gateway:<pkg>`, or bare package spec (Durar Gateway first, then npm fallback).
+
+If config is invalid, install normally fails closed and points you at
+`Durar doctor --fix`. The only recovery exception is a narrow bundled-plugin
+reinstall path for plugins that opt into
+`Durar.install.allowInvalidConfigRecovery`.
+
+## Plugin types
+
+Durar recognizes two plugin formats:
+
+| Format     | How it works                                                       | Examples                                               |
+| ---------- | ------------------------------------------------------------------ | ------------------------------------------------------ |
+| **Native** | `Durar.plugin.json` + runtime module; executes in-process       | Official plugins, community npm packages               |
+| **Bundle** | Codex/Claude/Cursor-compatible layout; mapped to Durar features | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` |
+
+Both show up under `Durar plugins list`. See [Plugin Bundles](/plugins/bundles) for bundle details.
+
+If you are writing a native plugin, start with [Building Plugins](/plugins/building-plugins)
+and the [Plugin SDK Overview](/plugins/sdk-overview).
+
+## Official plugins
+
+### Installable (npm)
+
+| Plugin          | Package                | Docs                                 |
+| --------------- | ---------------------- | ------------------------------------ |
+| Matrix          | `@Durar/matrix`     | [Matrix](/channels/matrix)           |
+| Microsoft Teams | `@Durar/msteams`    | [Microsoft Teams](/channels/msteams) |
+| Nostr           | `@Durar/nostr`      | [Nostr](/channels/nostr)             |
+| Voice Call      | `@Durar/voice-call` | [Voice Call](/plugins/voice-call)    |
+| Zalo            | `@Durar/zalo`       | [Zalo](/channels/zalo)               |
+| Zalo Personal   | `@Durar/zalouser`   | [Zalo Personal](/plugins/zalouser)   |
+
+### Core (shipped with Durar)
+
+<AccordionGroup>
+  <Accordion title="Model providers (enabled by default)">
+    `anthropic`, `byteplus`, `cloudflare-ai-gateway`, `github-copilot`, `google`,
+    `huggingface`, `kilocode`, `kimi-coding`, `minimax`, `mistral`, `qwen`,
+    `moonshot`, `nvidia`, `openai`, `opencode`, `opencode-go`, `openrouter`,
+    `qianfan`, `synthetic`, `together`, `venice`,
+    `vercel-ai-gateway`, `volcengine`, `xiaomi`, `zai`
+  </Accordion>
+
+  <Accordion title="Memory plugins">
+    - `memory-core` — bundled memory search (default via `plugins.slots.memory`)
+    - `memory-lancedb` — install-on-demand long-term memory with auto-recall/capture (set `plugins.slots.memory = "memory-lancedb"`)
+  </Accordion>
+
+  <Accordion title="Speech providers (enabled by default)">
+    `elevenlabs`, `microsoft`
+  </Accordion>
+
+  <Accordion title="Other">
+    - `browser` — bundled browser plugin for the browser tool, `Durar browser` CLI, `browser.request` gateway method, browser runtime, and default browser control service (enabled by default; disable before replacing it)
+    - `copilot-proxy` — VS Code Copilot Proxy bridge (disabled by default)
+  </Accordion>
+</AccordionGroup>
+
+Looking for third-party plugins? See [Community Plugins](/plugins/community).
+
+## Configuration
+
+```json5
+{
+  plugins: {
+    enabled: true,
+    allow: ["voice-call"],
+    deny: ["untrusted-plugin"],
+    load: { paths: ["~/Projects/oss/voice-call-extension"] },
+    entries: {
+      "voice-call": { enabled: true, config: { provider: "twilio" } },
+    },
+  },
+}
+```
+
+| Field            | Description                                               |
+| ---------------- | --------------------------------------------------------- |
+| `enabled`        | Master toggle (default: `true`)                           |
+| `allow`          | Plugin allowlist (optional)                               |
+| `deny`           | Plugin denylist (optional; deny wins)                     |
+| `load.paths`     | Extra plugin files/directories                            |
+| `slots`          | Exclusive slot selectors (e.g. `memory`, `contextEngine`) |
+| `entries.\<id\>` | Per-plugin toggles + config                               |
+
+Config changes **require a gateway restart**. If the Gateway is running with config
+watch + in-process restart enabled (the default `Durar gateway` path), that
+restart is usually performed automatically a moment after the config write lands.
+
+<Accordion title="Plugin states: disabled vs missing vs invalid">
+  - **Disabled**: plugin exists but enablement rules turned it off. Config is preserved.
+  - **Missing**: config references a plugin id that discovery did not find.
+  - **Invalid**: plugin exists but its config does not match the declared schema.
+</Accordion>
+
+## Discovery and precedence
+
+Durar scans for plugins in this order (first match wins):
+
+<Steps>
+  <Step title="Config paths">
+    `plugins.load.paths` — explicit file or directory paths.
+  </Step>
+
+  <Step title="Workspace extensions">
+    `\<workspace\>/.Durar/<plugin-root>/*.ts` and `\<workspace\>/.Durar/<plugin-root>/*/index.ts`.
+  </Step>
+
+  <Step title="Global extensions">
+    `~/.Durar/<plugin-root>/*.ts` and `~/.Durar/<plugin-root>/*/index.ts`.
+  </Step>
+
+  <Step title="Bundled plugins">
+    Shipped with Durar. Many are enabled by default (model providers, speech).
+    Others require explicit enablement.
+  </Step>
+</Steps>
+
+### Enablement rules
+
+- `plugins.enabled: false` disables all plugins
+- `plugins.deny` always wins over allow
+- `plugins.entries.\<id\>.enabled: false` disables that plugin
+- Workspace-origin plugins are **disabled by default** (must be explicitly enabled)
+- Bundled plugins follow the built-in default-on set unless overridden
+- Exclusive slots can force-enable the selected plugin for that slot
+
+## Plugin slots (exclusive categories)
+
+Some categories are exclusive (only one active at a time):
+
+```json5
+{
+  plugins: {
+    slots: {
+      memory: "memory-core", // or "none" to disable
+      contextEngine: "legacy", // or a plugin id
+    },
+  },
+}
+```
+
+| Slot            | What it controls      | Default             |
+| --------------- | --------------------- | ------------------- |
+| `memory`        | Active memory plugin  | `memory-core`       |
+| `contextEngine` | Active context engine | `legacy` (built-in) |
+
+## CLI reference
+
+```bash
+Durar plugins list                       # compact inventory
+Durar plugins list --enabled            # only loaded plugins
+Durar plugins list --verbose            # per-plugin detail lines
+Durar plugins list --json               # machine-readable inventory
+Durar plugins inspect <id>              # deep detail
+Durar plugins inspect <id> --json       # machine-readable
+Durar plugins inspect --all             # fleet-wide table
+Durar plugins info <id>                 # inspect alias
+Durar plugins doctor                    # diagnostics
+
+Durar plugins install <package>         # install (Durar Gateway first, then npm)
+Durar plugins install Durar Gateway:<pkg>     # install from Durar Gateway only
+Durar plugins install <spec> --force    # overwrite existing install
+Durar plugins install <path>            # install from local path
+Durar plugins install -l <path>         # link (no copy) for dev
+Durar plugins install <plugin> --marketplace <source>
+Durar plugins install <plugin> --marketplace https://github.com/<owner>/<repo>
+Durar plugins install <spec> --pin      # record exact resolved npm spec
+Durar plugins install <spec> --dangerously-force-unsafe-install
+Durar plugins update <id>             # update one plugin
+Durar plugins update <id> --dangerously-force-unsafe-install
+Durar plugins update --all            # update all
+Durar plugins uninstall <id>          # remove config/install records
+Durar plugins uninstall <id> --keep-files
+Durar plugins marketplace list <source>
+Durar plugins marketplace list <source> --json
+
+Durar plugins enable <id>
+Durar plugins disable <id>
+```
+
+Bundled plugins ship with Durar. Many are enabled by default (for example
+bundled model providers, bundled speech providers, and the bundled browser
+plugin). Other bundled plugins still need `Durar plugins enable <id>`.
+
+`--force` overwrites an existing installed plugin or hook pack in place.
+It is not supported with `--link`, which reuses the source path instead of
+copying over a managed install target.
+
+`--pin` is npm-only. It is not supported with `--marketplace`, because
+marketplace installs persist marketplace source metadata instead of an npm spec.
+
+`--dangerously-force-unsafe-install` is a break-glass override for false
+positives from the built-in dangerous-code scanner. It allows plugin installs
+and plugin updates to continue past built-in `critical` findings, but it still
+does not bypass plugin `before_install` policy blocks or scan-failure blocking.
+
+This CLI flag applies to plugin install/update flows only. Gateway-backed skill
+dependency installs use the matching `dangerouslyForceUnsafeInstall` request
+override instead, while `Durar skills install` remains the separate Durar Gateway
+skill download/install flow.
+
+Compatible bundles participate in the same plugin list/inspect/enable/disable
+flow. Current runtime support includes bundle skills, Claude command-skills,
+Claude `settings.json` defaults, Claude `.lsp.json` and manifest-declared
+`lspServers` defaults, Cursor command-skills, and compatible Codex hook
+directories.
+
+`Durar plugins inspect <id>` also reports detected bundle capabilities plus
+supported or unsupported MCP and LSP server entries for bundle-backed plugins.
+
+Marketplace sources can be a Claude known-marketplace name from
+`~/.claude/plugins/known_marketplaces.json`, a local marketplace root or
+`marketplace.json` path, a GitHub shorthand like `owner/repo`, a GitHub repo
+URL, or a git URL. For remote marketplaces, plugin entries must stay inside the
+cloned marketplace repo and use relative path sources only.
+
+See [`Durar plugins` CLI reference](/cli/plugins) for full details.
+
+## Plugin API overview
+
+Native plugins export an entry object that exposes `register(api)`. Older
+plugins may still use `activate(api)` as a legacy alias, but new plugins should
+use `register`.
+
+```typescript
+export default definePluginEntry({
+  id: "my-plugin",
+  name: "My Plugin",
+  register(api) {
+    api.registerProvider({
+      /* ... */
+    });
+    api.registerTool({
+      /* ... */
+    });
+    api.registerChannel({
+      /* ... */
+    });
+  },
+});
+```
+
+Durar loads the entry object and calls `register(api)` during plugin
+activation. The loader still falls back to `activate(api)` for older plugins,
+but bundled plugins and new external plugins should treat `register` as the
+public contract.
+
+Common registration methods:
+
+| Method                                  | What it registers           |
+| --------------------------------------- | --------------------------- |
+| `registerProvider`                      | Model provider (LLM)        |
+| `registerChannel`                       | Chat channel                |
+| `registerTool`                          | Agent tool                  |
+| `registerHook` / `on(...)`              | Lifecycle hooks             |
+| `registerSpeechProvider`                | Text-to-speech / STT        |
+| `registerRealtimeTranscriptionProvider` | Streaming STT               |
+| `registerRealtimeVoiceProvider`         | Duplex realtime voice       |
+| `registerMediaUnderstandingProvider`    | Image/audio analysis        |
+| `registerImageGenerationProvider`       | Image generation            |
+| `registerVideoGenerationProvider`       | Video generation            |
+| `registerWebFetchProvider`              | Web fetch / scrape provider |
+| `registerWebSearchProvider`             | Web search                  |
+| `registerHttpRoute`                     | HTTP endpoint               |
+| `registerCommand` / `registerCli`       | CLI commands                |
+| `registerContextEngine`                 | Context engine              |
+| `registerService`                       | Background service          |
+
+Hook guard behavior for typed lifecycle hooks:
+
+- `before_tool_call`: `{ block: true }` is terminal; lower-priority handlers are skipped.
+- `before_tool_call`: `{ block: false }` is a no-op and does not clear an earlier block.
+- `before_install`: `{ block: true }` is terminal; lower-priority handlers are skipped.
+- `before_install`: `{ block: false }` is a no-op and does not clear an earlier block.
+- `message_sending`: `{ cancel: true }` is terminal; lower-priority handlers are skipped.
+- `message_sending`: `{ cancel: false }` is a no-op and does not clear an earlier cancel.
+
+For full typed hook behavior, see [SDK Overview](/plugins/sdk-overview#hook-decision-semantics).
+
+## Related
+
+- [Building Plugins](/plugins/building-plugins) — create your own plugin
+- [Plugin Bundles](/plugins/bundles) — Codex/Claude/Cursor bundle compatibility
+- [Plugin Manifest](/plugins/manifest) — manifest schema
+- [Registering Tools](/plugins/building-plugins#registering-agent-tools) — add agent tools in a plugin
+- [Plugin Internals](/plugins/architecture) — capability model and load pipeline
+- [Community Plugins](/plugins/community) — third-party listings

package/docs/tools/reactions.md

@@ -0,0 +1,78 @@
+---
+summary: "Reaction tool semantics across all supported channels"
+read_when:
+  - Working on reactions in any channel
+  - Understanding how emoji reactions differ across platforms
+title: "Reactions"
+---
+
+# Reactions
+
+The agent can add and remove emoji reactions on messages using the `message`
+tool with the `react` action. Reaction behavior varies by channel.
+
+## How it works
+
+```json
+{
+  "action": "react",
+  "messageId": "msg-123",
+  "emoji": "thumbsup"
+}
+```
+
+- `emoji` is required when adding a reaction.
+- Set `emoji` to an empty string (`""`) to remove the bot's reaction(s).
+- Set `remove: true` to remove a specific emoji (requires non-empty `emoji`).
+
+## Channel behavior
+
+<AccordionGroup>
+  <Accordion title="Discord and Slack">
+    - Empty `emoji` removes all of the bot's reactions on the message.
+    - `remove: true` removes just the specified emoji.
+  </Accordion>
+
+  <Accordion title="Google Chat">
+    - Empty `emoji` removes the app's reactions on the message.
+    - `remove: true` removes just the specified emoji.
+  </Accordion>
+
+  <Accordion title="Telegram">
+    - Empty `emoji` removes the bot's reactions.
+    - `remove: true` also removes reactions but still requires a non-empty `emoji` for tool validation.
+  </Accordion>
+
+  <Accordion title="WhatsApp">
+    - Empty `emoji` removes the bot reaction.
+    - `remove: true` maps to empty emoji internally (still requires `emoji` in the tool call).
+  </Accordion>
+
+  <Accordion title="Zalo Personal (zalouser)">
+    - Requires non-empty `emoji`.
+    - `remove: true` removes that specific emoji reaction.
+  </Accordion>
+
+  <Accordion title="Feishu/Lark">
+    - Use the `feishu_reaction` tool with actions `add`, `remove`, and `list`.
+    - Add/remove requires `emoji_type`; remove also requires `reaction_id`.
+  </Accordion>
+
+  <Accordion title="Signal">
+    - Inbound reaction notifications are controlled by `channels.signal.reactionNotifications`: `"off"` disables them, `"own"` (default) emits events when users react to bot messages, and `"all"` emits events for all reactions.
+  </Accordion>
+</AccordionGroup>
+
+## Reaction level
+
+Per-channel `reactionLevel` config controls how broadly the agent uses reactions. Values are typically `off`, `ack`, `minimal`, or `extensive`.
+
+- [Telegram reactionLevel](/channels/telegram#reaction-notifications) — `channels.telegram.reactionLevel`
+- [WhatsApp reactionLevel](/channels/whatsapp#reactions) — `channels.whatsapp.reactionLevel`
+
+Set `reactionLevel` on individual channels to tune how actively the agent reacts to messages on each platform.
+
+## Related
+
+- [Agent Send](/tools/agent-send) — the `message` tool that includes `react`
+- [Channels](/channels) — channel-specific configuration