nodmix 2026.5.25

package/docs/tools/plugin.md

@@ -0,0 +1,327 @@
+---
+summary: "Install, configure, and manage Nodmix plugins"
+read_when:
+  - Installing or configuring plugins
+  - Understanding plugin discovery and load rules
+  - Working with Codex/Claude-compatible plugin bundles
+title: "Plugins"
+sidebarTitle: "Getting Started"
+doc-schema-version: 1
+---
+
+Plugins extend Nodmix with channels, model providers, agent harnesses, tools,
+skills, speech, realtime transcription, voice, media understanding, generation,
+web fetch, web search, and other runtime capabilities.
+
+Use this page when you want to install a plugin, restart the Gateway, verify
+that the runtime loaded it, and route common setup failures. For command-only
+examples, see [Manage plugins](/plugins/manage-plugins). For the full generated
+inventory of bundled, official external, and source-only plugins, see
+[Plugin inventory](/plugins/plugin-inventory).
+
+## Requirements
+
+Before installing a plugin, make sure you have:
+
+- an Nodmix checkout or installation with the `nodmix` CLI available
+- network access to the selected source, such as ClawHub, npm, or a git host
+- any plugin-specific credentials, config keys, or operating-system tools named
+  by that plugin's setup docs
+- permission for the Gateway that serves your channels to reload or restart
+
+## Quick start
+
+<Steps>
+  <Step title="Find the plugin">
+    Search [ClawHub](/clawhub) for public plugin packages:
+
+    ```bash
+    nodmix plugins search "calendar"
+    ```
+
+    ClawHub is the primary discovery surface for community plugins. During the
+    launch cutover, ordinary bare package specs still install from npm. Use an
+    explicit prefix when you need one source.
+
+  </Step>
+
+  <Step title="Install the plugin">
+    ```bash
+    # From ClawHub.
+    nodmix plugins install clawhub:<package>
+
+    # From npm.
+    nodmix plugins install npm:<package>
+
+    # From git.
+    nodmix plugins install git:github.com/<owner>/<repo>@<ref>
+
+    # From a local development checkout.
+    nodmix plugins install ./my-plugin
+    nodmix plugins install --link ./my-plugin
+    ```
+
+    Treat plugin installs like running code. Prefer pinned versions when you
+    need reproducible production installs.
+
+  </Step>
+
+  <Step title="Configure and enable it">
+    Configure plugin-specific settings under `plugins.entries.<id>.config`.
+    Enable the plugin when it is not already enabled:
+
+    ```bash
+    nodmix plugins enable <plugin-id>
+    ```
+
+    If your config uses a restrictive `plugins.allow` list, the installed plugin
+    id must be present there before the plugin can load.
+    `nodmix plugins install` adds the installed id to an existing
+    `plugins.allow` list and removes the same id from `plugins.deny` so the
+    explicit install can load after restart.
+
+  </Step>
+
+  <Step title="Let the Gateway reload">
+    Installing, updating, or uninstalling plugin code requires a Gateway
+    restart. When a managed Gateway is already running with config reload
+    enabled, Nodmix detects the changed plugin install record and restarts the
+    Gateway automatically. If the Gateway is not managed or reload is disabled,
+    restart it yourself:
+
+    ```bash
+    nodmix gateway restart
+    ```
+
+    Enable and disable operations update config and refresh the cold registry.
+    A runtime inspect is still the clearest verification path for live runtime
+    surfaces.
+
+  </Step>
+
+  <Step title="Verify runtime registration">
+    ```bash
+    nodmix plugins inspect <plugin-id> --runtime --json
+    ```
+
+    Use `--runtime` when you need to prove registered tools, hooks, services,
+    Gateway methods, or plugin-owned CLI commands. Plain `inspect` is a cold
+    manifest and registry check.
+
+  </Step>
+</Steps>
+
+## Configuration
+
+### Choose an install source
+
+| Source      | Use when                                                                       | Example                                                        |
+| ----------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------- |
+| ClawHub     | You want Nodmix-native discovery, scans, version metadata, and install hints | `nodmix plugins install clawhub:<package>`                   |
+| npm         | You need direct npm registry or dist-tag workflows                             | `nodmix plugins install npm:<package>`                       |
+| git         | You need a branch, tag, or commit from a repository                            | `nodmix plugins install git:github.com/<owner>/<repo>@<ref>` |
+| local path  | You are developing or testing a plugin on the same machine                     | `nodmix plugins install --link ./my-plugin`                  |
+| marketplace | You are installing a Claude-compatible marketplace plugin                      | `nodmix plugins install <plugin> --marketplace <source>`     |
+
+Bare package specs have special compatibility behavior. If the bare name matches
+a bundled plugin id, Nodmix uses that bundled source. If it matches an
+official external plugin id, Nodmix uses the official package catalog. Other
+ordinary bare package specs install through npm during the launch cutover. Use
+`clawhub:`, `npm:`, `git:`, or `npm-pack:` when you need deterministic source
+selection. See [`nodmix plugins`](/cli/plugins#install) for the full command
+contract.
+
+### Configure plugin policy
+
+The common plugin config shape is:
+
+```json5
+{
+  plugins: {
+    enabled: true,
+    allow: ["voice-call"],
+    deny: ["untrusted-plugin"],
+    load: { paths: ["~/Projects/oss/voice-call-plugin"] },
+    slots: { memory: "memory-core" },
+    entries: {
+      "voice-call": { enabled: true, config: { provider: "twilio" } },
+    },
+  },
+}
+```
+
+Key policy rules:
+
+- `plugins.enabled: false` disables all plugins and skips plugin discovery/load
+  work. Stale plugin references are inert while this is active; re-enable
+  plugins before running doctor cleanup when you want stale ids removed.
+- `plugins.deny` wins over allow and per-plugin enablement.
+- `plugins.allow` is an exclusive allowlist. Plugin-owned tools outside the
+  allowlist stay unavailable, even when `tools.allow` includes `"*"`.
+- `plugins.entries.<id>.enabled: false` disables one plugin while preserving its
+  config.
+- `plugins.load.paths` adds explicit local plugin files or directories.
+- Workspace-origin plugins are disabled by default; explicitly enable or
+  allowlist them before using local workspace code.
+- Bundled plugins follow their built-in default-on/default-off metadata unless
+  config explicitly overrides them.
+- `plugins.slots.<slot>` chooses one plugin for exclusive categories such as
+  memory and context engines. Slot selection force-enables the selected plugin
+  for that slot by counting as explicit activation; it can load even when it
+  would otherwise be opt-in. `plugins.deny` and
+  `plugins.entries.<id>.enabled: false` still block it.
+- Bundled opt-in plugins can auto-activate when config names one of their owned
+  surfaces, such as a provider/model ref, channel config, CLI backend, or agent
+  harness runtime.
+- OpenAI-family Codex routing keeps provider and runtime plugin boundaries
+  separate: `openai-codex/*` is legacy OpenAI-provider config, while the bundled
+  `codex` plugin owns Codex app-server runtime for canonical `openai/*` agent
+  refs, explicit `agentRuntime.id: "codex"`, and legacy `codex/*` refs.
+
+Run `nodmix doctor` or `nodmix doctor --fix` when config validation reports
+stale plugin ids, allowlist/tool mismatches, or legacy bundled plugin paths.
+
+## Understand plugin formats
+
+Nodmix recognizes two plugin formats:
+
+| Format                 | How it loads                                                                 | Use when                                                               |
+| ---------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| Native Nodmix plugin | `nodmix.plugin.json` plus a runtime module loaded in process               | You are installing or building Nodmix-specific runtime capabilities  |
+| Compatible bundle      | Codex, Claude, or Cursor plugin layout mapped into Nodmix plugin inventory | You are reusing compatible skills, commands, hooks, or bundle metadata |
+
+Both formats appear in `nodmix plugins list`, `nodmix plugins inspect`,
+`nodmix plugins enable`, and `nodmix plugins disable`. See
+[Plugin bundles](/plugins/bundles) for the bundle compatibility boundary and
+[Building plugins](/plugins/building-plugins) for native plugin authoring.
+
+## Verify the active Gateway
+
+`nodmix plugins list` and plain `nodmix plugins inspect` read cold config,
+manifest, and registry state. They do not prove that an already-running Gateway
+has imported the same plugin code.
+
+When a plugin appears installed but live chat traffic does not use it:
+
+```bash
+nodmix gateway status --deep --require-rpc
+nodmix plugins inspect <plugin-id> --runtime --json
+nodmix gateway restart
+```
+
+Managed Gateways restart automatically after plugin install, update, and
+uninstall changes that alter plugin source. On VPS or container installs, make
+sure any manual restart targets the actual `nodmix gateway run` child that
+serves your channels, not only a wrapper or supervisor.
+
+## Troubleshooting
+
+| Symptom                                                        | Check                                                                                                                                      | Fix                                                                                                     |
+| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
+| Plugin appears in `plugins list` but runtime hooks do not run  | Use `nodmix plugins inspect <id> --runtime --json` and confirm the active Gateway with `gateway status --deep --require-rpc`             | Restart the live Gateway after install, update, config, or source changes                               |
+| Duplicate channel or tool ownership diagnostics appear         | Run `nodmix plugins list --enabled --verbose`, inspect each suspected plugin with `--runtime --json`, and compare channel/tool ownership | Disable one owner, remove stale installs, or use manifest `preferOver` for intentional replacement      |
+| Config says a plugin is missing                                | Check [Plugin inventory](/plugins/plugin-inventory) for whether it is bundled, official external, or source-only                           | Install the external package, enable the bundled plugin, or remove stale config                         |
+| Config is invalid during install                               | Read the validation message and run `nodmix doctor --fix` when it points to stale plugin state                                           | Doctor can quarantine invalid plugin config by disabling the entry and removing the invalid payload     |
+| Plugin path is blocked for suspicious ownership or permissions | Inspect the diagnostic before the config error                                                                                             | Fix filesystem ownership/permissions, then run `nodmix plugins registry --refresh`                    |
+| `NODMIX_NIX_MODE=1` blocks lifecycle commands                | Confirm the install is managed by Nix                                                                                                      | Change plugin selection in the Nix source instead of using plugin mutator commands                      |
+| Dependency import fails at runtime                             | Check whether the plugin was installed through npm/git/ClawHub or loaded from a local path                                                 | Run `nodmix plugins update <id>`, reinstall the source, or install local plugin dependencies yourself |
+
+When stale plugin config still names a no-longer-discoverable channel plugin,
+Gateway startup skips that plugin-backed channel instead of blocking every
+other channel. Run `nodmix doctor --fix` to remove stale plugin and channel
+entries. Unknown channel keys without stale-plugin evidence still fail
+validation so typos stay visible.
+
+For intentional channel replacement, the preferred plugin should declare
+`channelConfigs.<channel-id>.preferOver` with the legacy or lower-priority
+plugin id. If both plugins are explicitly enabled, Nodmix keeps that request
+and reports duplicate channel or tool diagnostics instead of silently choosing
+one owner.
+
+If an installed package reports that it `requires compiled runtime output for
+TypeScript entry ...`, the package was published without the JavaScript files
+Nodmix needs at runtime. Update or reinstall after the publisher ships
+compiled JavaScript, or disable/uninstall the plugin until then.
+
+### Blocked plugin path ownership
+
+If plugin diagnostics say
+`blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root)`
+and config validation follows with `plugin present but blocked`, Nodmix found
+plugin files owned by a different Unix user than the process that is loading
+them. Keep the plugin config in place; fix the filesystem ownership or run
+Nodmix as the same user that owns the state directory.
+
+For Docker installs, the official image runs as `node` (uid `1000`), so the
+host bind-mounted Nodmix config and workspace directories should normally be
+owned by uid `1000`:
+
+```bash
+sudo chown -R 1000:1000 /path/to/nodmix-config /path/to/nodmix-workspace
+```
+
+If you intentionally run Nodmix as root, repair the managed plugin root to
+root ownership instead:
+
+```bash
+sudo chown -R root:root /path/to/nodmix-config/npm
+```
+
+After fixing ownership, rerun `nodmix doctor --fix` or
+`nodmix plugins registry --refresh` so the persisted plugin registry matches
+the repaired files.
+
+### Slow plugin tool setup
+
+If agent turns appear to stall while preparing tools, enable trace logging and
+check for plugin tool factory timing lines:
+
+```bash
+nodmix config set logging.level trace
+nodmix logs --follow
+```
+
+Look for:
+
+```text
+[trace:plugin-tools] factory timings ...
+```
+
+The summary lists total factory time and the slowest plugin tool factories,
+including plugin id, declared tool names, result shape, and whether the tool is
+optional. Slow lines are promoted to warnings when a single factory takes at
+least 1s or total plugin tool factory prep takes at least 5s.
+
+Nodmix caches successful plugin tool factory results for repeated resolutions
+with the same effective request context. The cache key includes the effective
+runtime config, workspace, agent/session ids, sandbox policy, browser settings,
+delivery context, requester identity, and ownership state, so factories that
+depend on those trusted fields are re-run when the context changes. If timings
+stay high, the plugin may be doing expensive work before returning its tool
+definitions.
+
+If one plugin dominates the timing, inspect its runtime registrations:
+
+```bash
+nodmix plugins inspect <plugin-id> --runtime --json
+```
+
+Then update, reinstall, or disable that plugin. Plugin authors should move
+expensive dependency loading behind the tool execution path instead of doing it
+inside the tool factory.
+
+For dependency roots, package metadata validation, registry records, startup
+reload behavior, and legacy cleanup, see
+[Plugin dependency resolution](/plugins/dependency-resolution).
+
+## Related
+
+- [Manage plugins](/plugins/manage-plugins) - command examples for list, install, update, uninstall, and publish
+- [`nodmix plugins`](/cli/plugins) - full CLI reference
+- [Plugin inventory](/plugins/plugin-inventory) - generated bundled and external plugin list
+- [Plugin reference](/plugins/reference) - generated per-plugin reference pages
+- [Community plugins](/plugins/community) - ClawHub discovery and docs PR policy
+- [Plugin dependency resolution](/plugins/dependency-resolution) - install roots, registry records, and runtime boundaries
+- [Building plugins](/plugins/building-plugins) - native plugin authoring guide
+- [Plugin SDK overview](/plugins/sdk-overview) - runtime registration, hooks, and API fields
+- [Plugin manifest](/plugins/manifest) - manifest and package metadata

package/docs/tools/reactions.md

@@ -0,0 +1,100 @@
+---
+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"
+---
+
+The agent can add and remove emoji reactions on messages using the `message`
+tool with the `react` action. Reaction behavior varies by channel and transport.
+
+## 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`).
+- On channels that support status reactions, `trackToolCalls: true` on a
+  reaction lets the runtime use that reacted message for subsequent tool
+  progress reactions during the same turn.
+
+## 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="Nextcloud Talk">
+    - Adding reactions only: `emoji` is required and must be non-empty.
+    - Reaction removal is not supported yet; calls with `remove: true` (or empty `emoji`) are rejected with a clear error rather than silently no-oping.
+    - Requires the Talk bot to be registered with the `reaction` feature (see [Nextcloud Talk channel docs](/channels/nextcloud-talk)).
+
+  </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).
+    - WhatsApp has one bot reaction slot per message; status reaction updates replace that slot rather than stacking multiple emoji.
+
+  </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>
+
+  <Accordion title="iMessage">
+    - Outbound reactions are iMessage tapbacks (`love`, `like`, `dislike`, `laugh`, `emphasize`, and `question`).
+    - Inbound tapback notifications are controlled by `channels.imessage.reactionNotifications`: `"off"` disables them, `"own"` (default) emits events when users react to bot-authored messages, and `"all"` emits events for all tapbacks from authorized senders.
+
+  </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#reaction-level) — `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

package/docs/tools/searxng-search.md

@@ -0,0 +1,141 @@
+---
+summary: "SearXNG web search -- self-hosted, key-free meta-search provider"
+read_when:
+  - You want a self-hosted web search provider
+  - You want to use SearXNG for web_search
+  - You need a privacy-focused or air-gapped search option
+title: "SearXNG search"
+---
+
+Nodmix supports [SearXNG](https://docs.searxng.org/) as a **self-hosted,
+key-free** `web_search` provider. SearXNG is an open-source meta-search engine
+that aggregates results from Google, Bing, DuckDuckGo, and other sources.
+
+Advantages:
+
+- **Free and unlimited** -- no API key or commercial subscription required
+- **Privacy / air-gap** -- queries never leave your network
+- **Works anywhere** -- no region restrictions on commercial search APIs
+
+## Setup
+
+<Steps>
+  <Step title="Run a SearXNG instance">
+    ```bash
+    docker run -d -p 8888:8080 searxng/searxng
+    ```
+
+    Or use any existing SearXNG deployment you have access to. See the
+    [SearXNG documentation](https://docs.searxng.org/) for production setup.
+
+  </Step>
+  <Step title="Configure">
+    ```bash
+    nodmix configure --section web
+    # Select "searxng" as the provider
+    ```
+
+    Or set the env var and let auto-detection find it:
+
+    ```bash
+    export SEARXNG_BASE_URL="http://localhost:8888"
+    ```
+
+  </Step>
+</Steps>
+
+## Config
+
+```json5
+{
+  tools: {
+    web: {
+      search: {
+        provider: "searxng",
+      },
+    },
+  },
+}
+```
+
+Plugin-level settings for the SearXNG instance:
+
+```json5
+{
+  plugins: {
+    entries: {
+      searxng: {
+        config: {
+          webSearch: {
+            baseUrl: "http://localhost:8888",
+            categories: "general,news", // optional
+            language: "en", // optional
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+The `baseUrl` field also accepts SecretRef objects.
+
+Transport rules:
+
+- `https://` works for public or private SearXNG hosts
+- `http://` is only accepted for trusted private-network or loopback hosts
+- public SearXNG hosts must use `https://`
+- private/internal hosts use the self-hosted network guard; public `https://`
+  hosts stay on the strict web-search guard and cannot redirect to private
+  addresses
+
+## Environment variable
+
+Set `SEARXNG_BASE_URL` as an alternative to config:
+
+```bash
+export SEARXNG_BASE_URL="http://localhost:8888"
+```
+
+When `SEARXNG_BASE_URL` is set and no explicit provider is configured, auto-detection
+picks SearXNG automatically (at the lowest priority -- any API-backed provider with a
+key wins first).
+
+## Plugin config reference
+
+| Field        | Description                                                        |
+| ------------ | ------------------------------------------------------------------ |
+| `baseUrl`    | Base URL of your SearXNG instance (required)                       |
+| `categories` | Comma-separated categories such as `general`, `news`, or `science` |
+| `language`   | Language code for results such as `en`, `de`, or `fr`              |
+
+## Notes
+
+- **JSON API** -- uses SearXNG's native `format=json` endpoint, not HTML scraping
+- **Image result URLs** -- image-category results include `img_src` when SearXNG
+  returns a direct image URL
+- **No API key** -- works with any SearXNG instance out of the box
+- **Base URL validation** -- `baseUrl` must be a valid `http://` or `https://`
+  URL; public hosts must use `https://`
+- **Network guard** -- private/internal SearXNG endpoints opt in to
+  private-network access; public `https://` SearXNG endpoints keep strict SSRF
+  protection
+- **Auto-detection order** -- SearXNG is checked last (order 200) in
+  auto-detection. API-backed providers with configured keys run first, then
+  DuckDuckGo (order 100), then Ollama Web Search (order 110)
+- **Self-hosted** -- you control the instance, queries, and upstream search engines
+- **Categories** default to `general` when not configured
+- **Category fallback** -- if a non-`general` category request succeeds but
+  returns zero results, Nodmix retries the same query once with `general`
+  before returning an empty result set
+
+<Tip>
+  For SearXNG JSON API to work, make sure your SearXNG instance has the `json`
+  format enabled in its `settings.yml` under `search.formats`.
+</Tip>
+
+## Related
+
+- [Web Search overview](/tools/web) -- all providers and auto-detection
+- [DuckDuckGo Search](/tools/duckduckgo-search) -- another key-free fallback
+- [Brave Search](/tools/brave-search) -- structured results with free tier