nodmix 2026.5.25

package/docs/tools/agent-send.md

@@ -0,0 +1,112 @@
+---
+summary: "Run agent turns from the CLI and optionally deliver replies to channels"
+read_when:
+  - You want to trigger agent runs from scripts or the command line
+  - You need to deliver agent replies to a chat channel programmatically
+title: "Agent send"
+---
+
+`nodmix agent` runs a single agent turn from the command line without needing
+an inbound chat message. Use it for scripted workflows, testing, and
+programmatic delivery.
+
+## Quick start
+
+<Steps>
+  <Step title="Run a simple agent turn">
+    ```bash
+    nodmix agent --message "What is the weather today?"
+    ```
+
+    This sends the message through the Gateway and prints the reply.
+
+  </Step>
+
+  <Step title="Target a specific agent or session">
+    ```bash
+    # Target a specific agent
+    nodmix agent --agent ops --message "Summarize logs"
+
+    # Target a phone number (derives session key)
+    nodmix agent --to +15555550123 --message "Status update"
+
+    # Reuse an existing session
+    nodmix agent --session-id abc123 --message "Continue the task"
+    ```
+
+  </Step>
+
+  <Step title="Deliver the reply to a channel">
+    ```bash
+    # Deliver to WhatsApp (default channel)
+    nodmix agent --to +15555550123 --message "Report ready" --deliver
+
+    # Deliver to Slack
+    nodmix agent --agent ops --message "Generate report" \
+      --deliver --reply-channel slack --reply-to "#reports"
+    ```
+
+  </Step>
+</Steps>
+
+## Flags
+
+| Flag                          | Description                                                 |
+| ----------------------------- | ----------------------------------------------------------- |
+| `--message \<text\>`          | Message to send (required)                                  |
+| `--to \<dest\>`               | Derive session key from a target (phone, chat id)           |
+| `--agent \<id\>`              | Target a configured agent (uses its `main` session)         |
+| `--session-id \<id\>`         | Reuse an existing session by id                             |
+| `--local`                     | Force local embedded runtime (skip Gateway)                 |
+| `--deliver`                   | Send the reply to a chat channel                            |
+| `--channel \<name\>`          | Delivery channel (whatsapp, telegram, discord, slack, etc.) |
+| `--reply-to \<target\>`       | Delivery target override                                    |
+| `--reply-channel \<name\>`    | Delivery channel override                                   |
+| `--reply-account \<id\>`      | Delivery account id override                                |
+| `--thinking \<level\>`        | Set thinking level for the selected model profile           |
+| `--verbose \<on\|full\|off\>` | Set verbose level                                           |
+| `--timeout \<seconds\>`       | Override agent timeout                                      |
+| `--json`                      | Output structured JSON                                      |
+
+## Behavior
+
+- By default, the CLI goes **through the Gateway**. Add `--local` to force the
+  embedded runtime on the current machine.
+- If the Gateway is unreachable, the CLI **falls back** to the local embedded run.
+- Session selection: `--to` derives the session key (group/channel targets
+  preserve isolation; direct chats collapse to `main`).
+- Thinking and verbose flags persist into the session store.
+- Output: plain text by default, or `--json` for structured payload + metadata.
+- With `--json --deliver`, the JSON includes delivery status for sent,
+  suppressed, partial, and failed sends. See
+  [JSON delivery status](/cli/agent#json-delivery-status).
+
+## Examples
+
+```bash
+# Simple turn with JSON output
+nodmix agent --to +15555550123 --message "Trace logs" --verbose on --json
+
+# Turn with thinking level
+nodmix agent --session-id 1234 --message "Summarize inbox" --thinking medium
+
+# Deliver to a different channel than the session
+nodmix agent --agent ops --message "Alert" --deliver --reply-channel telegram --reply-to "@admin"
+```
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Agent CLI reference" href="/cli/agent" icon="terminal">
+    Full `nodmix agent` flag and option reference.
+  </Card>
+  <Card title="Sub-agents" href="/tools/subagents" icon="users">
+    Background sub-agent spawning.
+  </Card>
+  <Card title="Sessions" href="/concepts/session" icon="comments">
+    How session keys work and how `--to`, `--agent`, and `--session-id` resolve them.
+  </Card>
+  <Card title="Slash commands" href="/tools/slash-commands" icon="slash">
+    Native command catalog used inside agent sessions.
+  </Card>
+</CardGroup>

package/docs/tools/apply-patch.md

@@ -0,0 +1,64 @@
+---
+summary: "Apply multi-file patches with the apply_patch tool"
+read_when:
+  - You need structured file edits across multiple files
+  - You want to document or debug patch-based edits
+title: "apply_patch tool"
+---
+
+Apply file changes using a structured patch format. This is ideal for multi-file
+or multi-hunk edits where a single `edit` call would be brittle.
+
+The tool accepts a single `input` string that wraps one or more file operations:
+
+```
+*** Begin Patch
+*** Add File: path/to/file.txt
++line 1
++line 2
+*** Update File: src/app.ts
+@@
+-old line
++new line
+*** Delete File: obsolete.txt
+*** End Patch
+```
+
+## Parameters
+
+- `input` (required): Full patch contents including `*** Begin Patch` and `*** End Patch`.
+
+## Notes
+
+- Patch paths support relative paths (from the workspace directory) and absolute paths.
+- `tools.exec.applyPatch.workspaceOnly` defaults to `true` (workspace-contained). Set it to `false` only if you intentionally want `apply_patch` to write/delete outside the workspace directory.
+- Use `*** Move to:` within an `*** Update File:` hunk to rename files.
+- `*** End of File` marks an EOF-only insert when needed.
+- Available by default for OpenAI and OpenAI Codex models. Set
+  `tools.exec.applyPatch.enabled: false` to disable it.
+- Optionally gate by model via
+  `tools.exec.applyPatch.allowModels`.
+- Config is only under `tools.exec`.
+
+## Example
+
+```json
+{
+  "tool": "apply_patch",
+  "input": "*** Begin Patch\n*** Update File: src/index.ts\n@@\n-const foo = 1\n+const foo = 2\n*** End Patch"
+}
+```
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Diffs" href="/tools/diffs" icon="code-compare">
+    Read-only diff viewer for change presentation.
+  </Card>
+  <Card title="Exec tool" href="/tools/exec" icon="terminal">
+    Shell command execution from the agent.
+  </Card>
+  <Card title="Code execution" href="/tools/code-execution" icon="square-code">
+    Sandboxed remote Python analysis with xAI.
+  </Card>
+</CardGroup>

package/docs/tools/brave-search.md

@@ -0,0 +1,139 @@
+---
+summary: "Brave Search API setup for web_search"
+read_when:
+  - You want to use Brave Search for web_search
+  - You need a BRAVE_API_KEY or plan details
+title: "Brave search"
+---
+
+Nodmix supports Brave Search API as a `web_search` provider.
+
+## Get an API key
+
+1. Create a Brave Search API account at [https://brave.com/search/api/](https://brave.com/search/api/)
+2. In the dashboard, choose the **Search** plan and generate an API key.
+3. Store the key in config or set `BRAVE_API_KEY` in the Gateway environment.
+
+## Config example
+
+```json5
+{
+  plugins: {
+    entries: {
+      brave: {
+        config: {
+          webSearch: {
+            apiKey: "BRAVE_API_KEY_HERE",
+            mode: "web", // or "llm-context"
+            baseUrl: "https://api.search.brave.com", // optional proxy/base URL override
+          },
+        },
+      },
+    },
+  },
+  tools: {
+    web: {
+      search: {
+        provider: "brave",
+        maxResults: 5,
+        timeoutSeconds: 30,
+      },
+    },
+  },
+}
+```
+
+Provider-specific Brave search settings now live under `plugins.entries.brave.config.webSearch.*`.
+Legacy `tools.web.search.apiKey` still loads through the compatibility shim, but it is no longer the canonical config path.
+
+`webSearch.mode` controls the Brave transport:
+
+- `web` (default): normal Brave web search with titles, URLs, and snippets
+- `llm-context`: Brave LLM Context API with pre-extracted text chunks and sources for grounding
+
+`webSearch.baseUrl` can point Brave requests at a trusted Brave-compatible proxy
+or gateway. Nodmix appends `/res/v1/web/search` or `/res/v1/llm/context` to
+the configured base URL and keeps the base URL in the cache key. Public
+endpoints must use `https://`; `http://` is accepted only for trusted loopback
+or private-network proxy hosts.
+
+## Tool parameters
+
+<ParamField path="query" type="string" required>
+Search query.
+</ParamField>
+
+<ParamField path="count" type="number" default="5">
+Number of results to return (1–10).
+</ParamField>
+
+<ParamField path="country" type="string">
+2-letter ISO country code (e.g. `US`, `DE`).
+</ParamField>
+
+<ParamField path="language" type="string">
+ISO 639-1 language code for search results (e.g. `en`, `de`, `fr`).
+</ParamField>
+
+<ParamField path="search_lang" type="string">
+Brave search-language code (e.g. `en`, `en-gb`, `zh-hans`).
+</ParamField>
+
+<ParamField path="ui_lang" type="string">
+ISO language code for UI elements.
+</ParamField>
+
+<ParamField path="freshness" type="'day' | 'week' | 'month' | 'year'">
+Time filter — `day` is 24 hours.
+</ParamField>
+
+<ParamField path="date_after" type="string">
+Only results published after this date (`YYYY-MM-DD`).
+</ParamField>
+
+<ParamField path="date_before" type="string">
+Only results published before this date (`YYYY-MM-DD`).
+</ParamField>
+
+**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",
+});
+```
+
+## Notes
+
+- Nodmix uses the Brave **Search** plan. If you have a legacy subscription (e.g. the original Free plan with 2,000 queries/month), it remains valid but does not include newer features like LLM Context or higher rate limits.
+- Each Brave plan includes **\$5/month in free credit** (renewing). The Search plan costs \$5 per 1,000 requests, so the credit covers 1,000 queries/month. Set your usage limit in the Brave dashboard to avoid unexpected charges. See the [Brave API portal](https://brave.com/search/api/) for current plans.
+- The Search plan includes the LLM Context endpoint and AI inference rights. Storing results to train or tune models requires a plan with explicit storage rights. See the Brave [Terms of Service](https://api-dashboard.search.brave.com/terms-of-service).
+- `llm-context` mode returns grounded source entries instead of the normal web-search snippet shape.
+- `llm-context` mode supports `freshness` and bounded `date_after` + `date_before` ranges. It does not support `ui_lang`; `date_before` without `date_after` is rejected because Brave requires custom freshness ranges to include both start and end dates.
+- `ui_lang` must include a region subtag like `en-US`.
+- Results are cached for 15 minutes by default (configurable via `cacheTtlMinutes`).
+- Custom `webSearch.baseUrl` values are included in Brave cache identity, so
+  proxy-specific responses do not collide.
+- Enable the `brave.http` diagnostics flag to log Brave request URLs/query params, response status/timing, and search-cache hit/miss/write events while troubleshooting. The flag never logs the API key or response bodies, but search queries can be sensitive.
+
+## Related
+
+- [Web Search overview](/tools/web) -- all providers and auto-detection
+- [Perplexity Search](/tools/perplexity-search) -- structured results with domain filtering
+- [Exa Search](/tools/exa-search) -- neural search with content extraction