nodmix 2026.5.25

package/docs/tools/tavily.md

@@ -0,0 +1,162 @@
+---
+summary: "Tavily search and extract tools"
+read_when:
+  - You want Tavily-backed web search
+  - You need a Tavily API key
+  - You want Tavily as a web_search provider
+  - You want content extraction from URLs
+title: "Tavily"
+---
+
+[Tavily](https://tavily.com) is a search API designed for AI applications. Nodmix exposes it in two ways:
+
+- as the `web_search` provider for the generic search tool
+- as explicit plugin tools: `tavily_search` and `tavily_extract`
+
+Tavily returns structured results optimized for LLM consumption with configurable search depth, topic filtering, domain filters, AI-generated answer summaries, and content extraction from URLs (including JavaScript-rendered pages).
+
+| Property      | Value                               |
+| ------------- | ----------------------------------- |
+| Plugin id     | `tavily`                            |
+| Auth          | `TAVILY_API_KEY` or config `apiKey` |
+| Base URL      | `https://api.tavily.com` (default)  |
+| Bundled tools | `tavily_search`, `tavily_extract`   |
+
+## Getting started
+
+<Steps>
+  <Step title="Get an API key">
+    Create a Tavily account at [tavily.com](https://tavily.com), then generate an API key in the dashboard.
+  </Step>
+  <Step title="Configure the plugin and provider">
+    ```json5
+    {
+      plugins: {
+        entries: {
+          tavily: {
+            enabled: true,
+            config: {
+              webSearch: {
+                apiKey: "tvly-...", // optional if TAVILY_API_KEY is set
+                baseUrl: "https://api.tavily.com",
+              },
+            },
+          },
+        },
+      },
+      tools: {
+        web: {
+          search: {
+            provider: "tavily",
+          },
+        },
+      },
+    }
+    ```
+  </Step>
+  <Step title="Verify search runs">
+    Trigger a `web_search` from any agent, or call `tavily_search` directly.
+  </Step>
+</Steps>
+
+<Tip>
+Choosing Tavily in onboarding or `nodmix configure --section web` enables the bundled Tavily plugin automatically.
+</Tip>
+
+## Tool reference
+
+### `tavily_search`
+
+Use this when you want Tavily-specific search controls instead of generic `web_search`.
+
+| Parameter         | Type         | Constraints / default                  | Description                                     |
+| ----------------- | ------------ | -------------------------------------- | ----------------------------------------------- |
+| `query`           | string       | required                               | Search query string. Keep under 400 characters. |
+| `search_depth`    | enum         | `basic` (default), `advanced`          | `advanced` is slower but higher relevance.      |
+| `topic`           | enum         | `general` (default), `news`, `finance` | Filter by topic family.                         |
+| `max_results`     | integer      | 1-20                                   | Number of results.                              |
+| `include_answer`  | boolean      | default `false`                        | Include a Tavily AI-generated answer summary.   |
+| `time_range`      | enum         | `day`, `week`, `month`, `year`         | Filter results by recency.                      |
+| `include_domains` | string array | (none)                                 | Only include results from these domains.        |
+| `exclude_domains` | string array | (none)                                 | Exclude results from these domains.             |
+
+Search depth tradeoff:
+
+| Depth      | Speed  | Relevance | Best for                             |
+| ---------- | ------ | --------- | ------------------------------------ |
+| `basic`    | Faster | High      | General-purpose queries (default).   |
+| `advanced` | Slower | Highest   | Precision research and fact-finding. |
+
+### `tavily_extract`
+
+Use this to extract clean content from one or more URLs. Handles JavaScript-rendered pages and supports query-focused chunking for targeted extraction.
+
+| Parameter           | Type         | Constraints / default         | Description                                                 |
+| ------------------- | ------------ | ----------------------------- | ----------------------------------------------------------- |
+| `urls`              | string array | required, 1-20                | URLs to extract content from.                               |
+| `query`             | string       | (optional)                    | Rerank extracted chunks by relevance to this query.         |
+| `extract_depth`     | enum         | `basic` (default), `advanced` | Use `advanced` for JS-heavy pages, SPAs, or dynamic tables. |
+| `chunks_per_source` | integer      | 1-5; **requires `query`**     | Chunks returned per URL. Errors if set without `query`.     |
+| `include_images`    | boolean      | default `false`               | Include image URLs in results.                              |
+
+Extract depth tradeoff:
+
+| Depth      | When to use                                |
+| ---------- | ------------------------------------------ |
+| `basic`    | Simple pages. Try this first.              |
+| `advanced` | JS-rendered SPAs, dynamic content, tables. |
+
+<Tip>
+Batch larger URL lists into multiple `tavily_extract` calls (max 20 per request). Use `query` plus `chunks_per_source` to get only relevant content instead of full pages.
+</Tip>
+
+## Choosing the right tool
+
+| Need                                 | Tool             |
+| ------------------------------------ | ---------------- |
+| Quick web search, no special options | `web_search`     |
+| Search with depth, topic, AI answers | `tavily_search`  |
+| Extract content from specific URLs   | `tavily_extract` |
+
+<Note>
+The generic `web_search` tool with Tavily as provider supports `query` and `count` (up to 20 results). For Tavily-specific controls (`search_depth`, `topic`, `include_answer`, domain filters, time range), use `tavily_search` instead.
+</Note>
+
+## Advanced configuration
+
+<AccordionGroup>
+  <Accordion title="API key resolution order">
+    The Tavily client looks up its API key in this order:
+
+    1. `plugins.entries.tavily.config.webSearch.apiKey` (resolved through SecretRefs).
+    2. `TAVILY_API_KEY` from the gateway environment.
+
+    `tavily_extract` raises a setup error if neither is present.
+
+  </Accordion>
+
+  <Accordion title="Custom base URL">
+    Override `plugins.entries.tavily.config.webSearch.baseUrl` if you front Tavily through a proxy. The default is `https://api.tavily.com`.
+  </Accordion>
+
+  <Accordion title="`chunks_per_source` requires `query`">
+    `tavily_extract` rejects calls that pass `chunks_per_source` without a `query`. Tavily ranks chunks by query relevance, so the parameter is meaningless without one.
+  </Accordion>
+</AccordionGroup>
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Web Search overview" href="/tools/web" icon="magnifying-glass">
+    All providers and auto-detection rules.
+  </Card>
+  <Card title="Firecrawl" href="/tools/firecrawl" icon="fire">
+    Search plus scraping with content extraction.
+  </Card>
+  <Card title="Exa Search" href="/tools/exa-search" icon="binoculars">
+    Neural search with content extraction.
+  </Card>
+  <Card title="Configuration" href="/gateway/configuration" icon="gear">
+    Full config schema for plugin entries and tool routing.
+  </Card>
+</CardGroup>

package/docs/tools/thinking.md

@@ -0,0 +1,140 @@
+---
+summary: "Directive syntax for /think, /fast, /verbose, /trace, and reasoning visibility"
+read_when:
+  - Adjusting thinking, fast-mode, or verbose directive parsing or defaults
+title: "Thinking levels"
+---
+
+## What it does
+
+- Inline directive in any inbound body: `/t <level>`, `/think:<level>`, or `/thinking <level>`.
+- Levels (aliases): `off | minimal | low | medium | high | xhigh | adaptive | max`
+  - minimal → "think"
+  - low → "think hard"
+  - medium → "think harder"
+  - high → "ultrathink" (max budget)
+  - xhigh → "ultrathink+" (GPT-5.2+ and Codex models, plus Anthropic Claude Opus 4.7 effort)
+  - adaptive → provider-managed adaptive thinking (supported for Claude 4.6 on Anthropic/Bedrock, Anthropic Claude Opus 4.7, and Google Gemini dynamic thinking)
+  - max → provider max reasoning (Anthropic Claude Opus 4.7; Ollama maps this to its highest native `think` effort)
+  - `x-high`, `x_high`, `extra-high`, `extra high`, and `extra_high` map to `xhigh`.
+  - `highest` maps to `high`.
+- Provider notes:
+  - Thinking menus and pickers are provider-profile driven. Provider plugins declare the exact level set for the selected model, including labels such as binary `on`.
+  - `adaptive`, `xhigh`, and `max` are only advertised for provider/model profiles that support them. Typed directives for unsupported levels are rejected with that model's valid options.
+  - Existing stored unsupported levels are remapped by provider profile rank. `adaptive` falls back to `medium` on non-adaptive models, while `xhigh` and `max` fall back to the largest supported non-off level for the selected model.
+  - Anthropic Claude 4.6 models default to `adaptive` when no explicit thinking level is set.
+  - Anthropic Claude Opus 4.7 does not default to adaptive thinking. Its API effort default remains provider-owned unless you explicitly set a thinking level.
+  - Anthropic Claude Opus 4.7 maps `/think xhigh` to adaptive thinking plus `output_config.effort: "xhigh"`, because `/think` is a thinking directive and `xhigh` is the Opus 4.7 effort setting.
+  - Anthropic Claude Opus 4.7 also exposes `/think max`; it maps to the same provider-owned max effort path.
+  - Direct DeepSeek V4 models expose `/think xhigh|max`; both map to DeepSeek `reasoning_effort: "max"` while lower non-off levels map to `high`.
+  - OpenRouter-routed DeepSeek V4 models expose `/think xhigh` and send OpenRouter-supported `reasoning_effort` values. Stored `max` overrides fall back to `xhigh`.
+  - Ollama thinking-capable models expose `/think low|medium|high|max`; `max` maps to native `think: "high"` because Ollama's native API accepts `low`, `medium`, and `high` effort strings.
+  - OpenAI GPT models map `/think` through model-specific Responses API effort support. `/think off` sends `reasoning.effort: "none"` only when the target model supports it; otherwise Nodmix omits the disabled reasoning payload instead of sending an unsupported value.
+  - Custom OpenAI-compatible catalog entries can opt into `/think xhigh` by setting `models.providers.<provider>.models[].compat.supportedReasoningEfforts` to include `"xhigh"`. This uses the same compat metadata that maps outbound OpenAI reasoning effort payloads, so menus, session validation, agent CLI, and `llm-task` agree with transport behavior.
+  - Stale configured OpenRouter Hunter Alpha refs skip proxy reasoning injection because that retired route could return final answer text through reasoning fields.
+  - Google Gemini maps `/think adaptive` to Gemini's provider-owned dynamic thinking. Gemini 3 requests omit a fixed `thinkingLevel`, while Gemini 2.5 requests send `thinkingBudget: -1`; fixed levels still map to the closest Gemini `thinkingLevel` or budget for that model family.
+  - MiniMax (`minimax/*`) on the Anthropic-compatible streaming path defaults to `thinking: { type: "disabled" }` unless you explicitly set thinking in model params or request params. This avoids leaked `reasoning_content` deltas from MiniMax's non-native Anthropic stream format.
+  - Z.AI (`zai/*`) only supports binary thinking (`on`/`off`). Any non-`off` level is treated as `on` (mapped to `low`).
+  - Moonshot (`moonshot/*`) maps `/think off` to `thinking: { type: "disabled" }` and any non-`off` level to `thinking: { type: "enabled" }`. When thinking is enabled, Moonshot only accepts `tool_choice` `auto|none`; Nodmix normalizes incompatible values to `auto`.
+
+## Resolution order
+
+1. Inline directive on the message (applies only to that message).
+2. Session override (set by sending a directive-only message).
+3. Per-agent default (`agents.list[].thinkingDefault` in config).
+4. Global default (`agents.defaults.thinkingDefault` in config).
+5. Fallback: provider-declared default when available; otherwise reasoning-capable models resolve to `medium` or the nearest supported non-`off` level for that model, and non-reasoning models stay `off`.
+
+## Setting a session default
+
+- Send a message that is **only** the directive (whitespace allowed), e.g. `/think:medium` or `/t high`.
+- That sticks for the current session (per-sender by default). Use `/think default` to clear the session override and inherit the configured/provider default; aliases include `inherit`, `clear`, `reset`, and `unpin`.
+- `/think off` stores an explicit off override. It disables thinking until you change or clear the session override.
+- Confirmation reply is sent (`Thinking level set to high.` / `Thinking disabled.`). If the level is invalid (e.g. `/thinking big`), the command is rejected with a hint and the session state is left unchanged.
+- Send `/think` (or `/think:`) with no argument to see the current thinking level.
+
+## Application by agent
+
+- **Embedded Pi**: the resolved level is passed to the in-process Pi agent runtime.
+- **Claude CLI backend**: non-off levels are passed to Claude Code as `--effort` when using `claude-cli`; see [CLI backends](/gateway/cli-backends).
+
+## Fast mode (/fast)
+
+- Levels: `on|off|default`.
+- Directive-only message toggles a session fast-mode override and replies `Fast mode enabled.` / `Fast mode disabled.`. Use `/fast default` to clear the session override and inherit the configured default; aliases include `inherit`, `clear`, `reset`, and `unpin`.
+- Send `/fast` (or `/fast status`) with no mode to see the current effective fast-mode state.
+- Nodmix resolves fast mode in this order:
+  1. Inline/directive-only `/fast on|off` override (`/fast default` clears this layer)
+  2. Session override
+  3. Per-agent default (`agents.list[].fastModeDefault`)
+  4. Per-model config: `agents.defaults.models["<provider>/<model>"].params.fastMode`
+  5. Fallback: `off`
+- For `openai/*`, fast mode maps to OpenAI priority processing by sending `service_tier=priority` on supported Responses requests.
+- For `openai-codex/*`, fast mode sends the same `service_tier=priority` flag on Codex Responses. Nodmix keeps one shared `/fast` toggle across both auth paths.
+- For direct public `anthropic/*` requests, including OAuth-authenticated traffic sent to `api.anthropic.com`, fast mode maps to Anthropic service tiers: `/fast on` sets `service_tier=auto`, `/fast off` sets `service_tier=standard_only`.
+- For `minimax/*` on the Anthropic-compatible path, `/fast on` (or `params.fastMode: true`) rewrites `MiniMax-M2.7` to `MiniMax-M2.7-highspeed`.
+- Explicit Anthropic `serviceTier` / `service_tier` model params override the fast-mode default when both are set. Nodmix still skips Anthropic service-tier injection for non-Anthropic proxy base URLs.
+- `/status` shows `Fast` only when fast mode is enabled.
+
+## Verbose directives (/verbose or /v)
+
+- Levels: `on` (minimal) | `full` | `off` (default).
+- Directive-only message toggles session verbose and replies `Verbose logging enabled.` / `Verbose logging disabled.`; invalid levels return a hint without changing state.
+- `/verbose off` stores an explicit session override; clear it via the Sessions UI by choosing `inherit`.
+- Inline directive affects only that message; session/global defaults apply otherwise.
+- Send `/verbose` (or `/verbose:`) with no argument to see the current verbose level.
+- When verbose is on, agents that emit structured tool results (Pi, other JSON agents) send each tool call back as its own metadata-only message, prefixed with `<emoji> <tool-name>: <arg>` when available. These tool summaries are sent as soon as each tool starts (separate bubbles), not as streaming deltas.
+- Tool failure summaries remain visible in normal mode, but raw error detail suffixes are hidden unless verbose is `full`.
+- When verbose is `full`, tool outputs are also forwarded after completion (separate bubble, truncated to a safe length). If you toggle `/verbose on|full|off` while a run is in-flight, subsequent tool bubbles honor the new setting.
+- `agents.defaults.toolProgressDetail` controls the shape of `/verbose` tool summaries and progress-draft tool lines. Use `"explain"` (default) for compact human labels such as `🛠️ Exec: checking JS syntax`; use `"raw"` when you also want the raw command/detail appended for debugging. Per-agent `agents.list[].toolProgressDetail` overrides the default.
+  - `explain`: `🛠️ Exec: check JS syntax for /tmp/app.js`
+  - `raw`: `🛠️ Exec: check JS syntax for /tmp/app.js, node --check /tmp/app.js`
+
+## Plugin trace directives (/trace)
+
+- Levels: `on` | `off` (default).
+- Directive-only message toggles session plugin trace output and replies `Plugin trace enabled.` / `Plugin trace disabled.`.
+- Inline directive affects only that message; session/global defaults apply otherwise.
+- Send `/trace` (or `/trace:`) with no argument to see the current trace level.
+- `/trace` is narrower than `/verbose`: it only exposes plugin-owned trace/debug lines such as Active Memory debug summaries.
+- Trace lines can appear in `/status` and as a follow-up diagnostic message after the normal assistant reply.
+
+## Reasoning visibility (/reasoning)
+
+- Levels: `on|off|stream`.
+- Directive-only message toggles whether thinking blocks are shown in replies.
+- When enabled, reasoning is sent as a **separate message** prefixed with `Thinking`.
+- `stream` (Telegram only): streams reasoning into the Telegram draft bubble while the reply is generating, then sends the final answer without reasoning.
+- Alias: `/reason`.
+- Send `/reasoning` (or `/reasoning:`) with no argument to see the current reasoning level.
+- Resolution order: inline directive, then session override, then per-agent default (`agents.list[].reasoningDefault`), then global default (`agents.defaults.reasoningDefault`), then fallback (`off`).
+
+Malformed local-model reasoning tags are handled conservatively. Closed `<think>...</think>` blocks stay hidden on normal replies, and unclosed reasoning after already visible text is also hidden. If a reply is fully wrapped in a single unclosed opening tag and would otherwise deliver as empty text, Nodmix removes the malformed opening tag and delivers the remaining text.
+
+## Related
+
+- Elevated mode docs live in [Elevated mode](/tools/elevated).
+
+## Heartbeats
+
+- Heartbeat probe body is the configured heartbeat prompt (default: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Inline directives in a heartbeat message apply as usual (but avoid changing session defaults from heartbeats).
+- Heartbeat delivery defaults to the final payload only. To also send the separate `Thinking` message (when available), set `agents.defaults.heartbeat.includeReasoning: true` or per-agent `agents.list[].heartbeat.includeReasoning: true`.
+
+## Web chat UI
+
+- The web chat thinking selector mirrors the session's stored level from the inbound session store/config when the page loads.
+- Picking another level writes the session override immediately via `sessions.patch`; it does not wait for the next send and it is not a one-shot `thinkingOnce` override.
+- The first option is always the clear-override choice. It shows `Inherited: <resolved level>` when the session is inheriting a non-off effective default, or `Off` when inherited thinking is disabled.
+- Explicit picker choices are labeled as overrides, while preserving provider labels when present (for example `Override: maximum` for a provider-labeled `max` option).
+- The picker uses `thinkingLevels` returned by the gateway session row/defaults, with `thinkingOptions` kept as a legacy label list. The browser UI does not keep its own provider regex list; plugins own model-specific level sets.
+- `/think:<level>` still works and updates the same stored session level, so chat directives and the picker stay in sync.
+
+## Provider profiles
+
+- Provider plugins can expose `resolveThinkingProfile(ctx)` to define the model's supported levels and default.
+- Provider plugins that proxy Claude models should reuse `resolveClaudeThinkingProfile(modelId)` from `nodmix/plugin-sdk/provider-model-shared` so direct Anthropic and proxy catalogs stay aligned.
+- Each profile level has a stored canonical `id` (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `adaptive`, or `max`) and may include a display `label`. Binary providers use `{ id: "low", label: "on" }`.
+- Tool plugins that need to validate an explicit thinking override should use `api.runtime.agent.resolveThinkingPolicy({ provider, model })` plus `api.runtime.agent.normalizeThinkingLevel(...)`; they should not keep their own provider/model level lists.
+- Tool plugins with access to configured custom model metadata can pass `catalog` into `resolveThinkingPolicy` so `compat.supportedReasoningEfforts` opt-ins are reflected in plugin-side validation.
+- Published legacy hooks (`supportsXHighThinking`, `isBinaryThinking`, and `resolveDefaultThinkingLevel`) remain as compatibility adapters, but new custom level sets should use `resolveThinkingProfile`.
+- Gateway rows/defaults expose `thinkingLevels`, `thinkingOptions`, and `thinkingDefault` so ACP/chat clients render the same profile ids and labels that runtime validation uses.

package/docs/tools/tokenjuice.md

@@ -0,0 +1,81 @@
+---
+summary: "Compact noisy exec and bash tool results with an optional bundled plugin"
+title: "Tokenjuice"
+read_when:
+  - You want shorter `exec` or `bash` tool results in Nodmix
+  - You want to enable the bundled tokenjuice plugin
+  - You need to understand what tokenjuice changes and what it leaves raw
+---
+
+`tokenjuice` is an optional bundled plugin that compacts noisy `exec` and `bash`
+tool results after the command has already run.
+
+It changes the returned `tool_result`, not the command itself. Tokenjuice does
+not rewrite shell input, rerun commands, or change exit codes.
+
+Today this applies to PI embedded runs and Nodmix dynamic tools in the Codex
+app-server harness. Tokenjuice hooks Nodmix's tool-result middleware and
+trims the output before it goes back into the active harness session.
+
+## Enable the plugin
+
+Fast path:
+
+```bash
+nodmix config set plugins.entries.tokenjuice.enabled true
+```
+
+Equivalent:
+
+```bash
+nodmix plugins enable tokenjuice
+```
+
+Nodmix already ships the plugin. There is no separate `plugins install`
+or `tokenjuice install nodmix` step.
+
+If you prefer editing config directly:
+
+```json5
+{
+  plugins: {
+    entries: {
+      tokenjuice: {
+        enabled: true,
+      },
+    },
+  },
+}
+```
+
+## What tokenjuice changes
+
+- Compacts noisy `exec` and `bash` results before they are fed back into the session.
+- Keeps the original command execution untouched.
+- Preserves exact file-content reads and other commands that tokenjuice should leave raw.
+- Stays opt-in: disable the plugin if you want verbatim output everywhere.
+
+## Verify it is working
+
+1. Enable the plugin.
+2. Start a session that can call `exec`.
+3. Run a noisy command such as `git status`.
+4. Check that the returned tool result is shorter and more structured than the raw shell output.
+
+## Disable the plugin
+
+```bash
+nodmix config set plugins.entries.tokenjuice.enabled false
+```
+
+Or:
+
+```bash
+nodmix plugins disable tokenjuice
+```
+
+## Related
+
+- [Exec tool](/tools/exec)
+- [Thinking levels](/tools/thinking)
+- [Context engine](/concepts/context-engine)

package/docs/tools/tool-search.md

@@ -0,0 +1,269 @@
+---
+summary: "Tool Search: compact large PI tool catalogs behind search, describe, and call"
+title: "Tool Search"
+read_when:
+  - You want PI agents to use a large tool catalog without adding every tool schema to the prompt
+  - You want Nodmix tools, MCP tools, and client tools exposed through one compact PI surface
+  - You are implementing or debugging tool discovery for PI runs
+---
+
+Tool Search is an experimental Nodmix PI-agent feature. It gives PI agents one
+compact way to discover and call large tool catalogs. It is useful when the run
+has many available tools but the model is likely to need only a few of them.
+
+This page documents Nodmix PI Tool Search. It is not the Codex-native tool
+search or dynamic-tools surface. Codex-native code mode, tool search, deferred
+dynamic tools, and nested tool calls are stable Codex harness surfaces and do
+not depend on `tools.toolSearch`.
+
+When enabled for PI, the model receives one `tool_search_code` tool by default.
+That tool runs a short JavaScript body in an isolated Node subprocess with an
+`nodmix.tools` bridge:
+
+```js
+const hits = await nodmix.tools.search("create a GitHub issue");
+const tool = await nodmix.tools.describe(hits[0].id);
+return await nodmix.tools.call(tool.id, {
+  title: "Crash on startup",
+  body: "Steps to reproduce...",
+});
+```
+
+The catalog can include Nodmix tools, plugin tools, MCP tools, and
+client-provided tools. The model does not see every full schema up front.
+Instead, it searches compact descriptors, describes one selected tool when it
+needs the exact schema, and calls that tool through Nodmix.
+
+Codex harness runs do not receive these experimental Nodmix Tool Search
+controls. Nodmix passes product capabilities to Codex as dynamic tools, and
+Codex owns the stable native code mode, native tool search, deferred dynamic
+tools, and nested tool calls.
+
+## How a turn runs
+
+At planning time the PI embedded runner builds the effective catalog for the
+run:
+
+1. Resolve the active tool policy for the agent, profile, sandbox, and session.
+2. List eligible Nodmix and plugin tools.
+3. List eligible MCP tools through the session MCP runtime.
+4. Add eligible client tools supplied for the current run.
+5. Index compact descriptors for search.
+6. Expose either the PI code bridge or the structured fallback tools to the
+   model.
+
+At execution time every real tool call returns to Nodmix. The isolated Node
+runtime does not hold plugin implementations, MCP client objects, or secrets.
+`nodmix.tools.call(...)` crosses the bridge back into the Gateway, where the
+normal policy, approval, hook, logging, and result handling still apply.
+
+## Modes
+
+`tools.toolSearch` has two model-facing modes:
+
+- `code`: exposes `tool_search_code`, the default compact JavaScript bridge.
+- `tools`: exposes `tool_search`, `tool_describe`, and `tool_call` as plain
+  structured tools for providers that should not receive code.
+
+Both modes use the same catalog and execution path. The only difference is the
+shape the model sees. If the current runtime cannot launch the isolated Node
+code-mode child process, the default `code` mode falls back to `tools` before
+catalog compaction.
+
+Both modes are experimental. Prefer direct tool exposure for small PI tool
+catalogs, and prefer the Codex-native stable surfaces for Codex harness runs.
+
+There is no separate source-selection config. When Tool Search is enabled, the
+catalog includes eligible Nodmix, MCP, and client tools after normal policy
+filtering.
+
+## Why this exists
+
+Large catalogs are useful but expensive. Sending every tool schema to the model
+makes the request larger, slows planning, and increases accidental tool
+selection.
+
+Tool Search changes the shape:
+
+- direct tools: the model sees every selected schema before the first token
+- Tool Search code mode: the model sees one compact code tool and a short API
+  contract
+- Tool Search tools mode: the model sees three compact structured fallback
+  tools
+- during the turn: the model loads only the tool schemas it actually needs
+
+Direct tool exposure is still the right default for small catalogs. Tool Search
+is best when one run can see many tools, especially from MCP servers or
+client-provided app tools.
+
+## API
+
+`nodmix.tools.search(query, options?)`
+
+Searches the effective catalog for the current run. Results are compact and safe
+to put back into prompt context.
+
+```js
+const hits = await nodmix.tools.search("calendar event", { limit: 5 });
+```
+
+`nodmix.tools.describe(id)`
+
+Loads full metadata for one search result, including the exact input schema.
+
+```js
+const calendarCreate = await nodmix.tools.describe("mcp:calendar:create_event");
+```
+
+`nodmix.tools.call(id, args)`
+
+Calls a selected tool through Nodmix.
+
+```js
+await nodmix.tools.call(calendarCreate.id, {
+  summary: "Planning",
+  start: "2026-05-09T14:00:00Z",
+});
+```
+
+The structured fallback mode exposes the same operations as tools:
+
+- `tool_search`
+- `tool_describe`
+- `tool_call`
+
+## Runtime boundary
+
+The code bridge runs in a short-lived Node subprocess. The subprocess starts
+with Node permission mode enabled, an empty environment, no filesystem or
+network grants, and no child-process or worker grants. Nodmix enforces a
+parent-process wall-clock timeout and kills the subprocess on timeout, including
+after async continuations.
+
+The runtime exposes only:
+
+- `console.log`, `console.warn`, and `console.error`
+- `nodmix.tools.search`
+- `nodmix.tools.describe`
+- `nodmix.tools.call`
+
+Normal Nodmix behavior still applies to final calls:
+
+- tool allow and deny policies
+- per-agent and per-sandbox tool restrictions
+- channel/runtime tool policy
+- approval hooks
+- plugin `before_tool_call` hooks
+- session identity, logs, and telemetry
+
+## Config
+
+Enable Tool Search for PI runs with the default code bridge:
+
+```bash
+nodmix config set tools.toolSearch true
+```
+
+Equivalent JSON:
+
+```json5
+{
+  tools: {
+    toolSearch: true,
+  },
+}
+```
+
+Use the structured fallback tools instead for PI runs:
+
+```json5
+{
+  tools: {
+    toolSearch: {
+      mode: "tools",
+    },
+  },
+}
+```
+
+Tune code-mode timeout and search result limits:
+
+```json5
+{
+  tools: {
+    toolSearch: {
+      mode: "code",
+      codeTimeoutMs: 10000,
+      searchDefaultLimit: 8,
+      maxSearchLimit: 20,
+    },
+  },
+}
+```
+
+Disable it:
+
+```json5
+{
+  tools: {
+    toolSearch: false,
+  },
+}
+```
+
+## Prompt and telemetry
+
+Tool Search records enough telemetry to compare it with direct tool exposure:
+
+- total serialized tool and prompt bytes sent to the harness
+- catalog size and source breakdown
+- search, describe, and call counts
+- final tool calls executed through Nodmix
+- selected tool ids and sources
+
+Session logs should make it possible to answer:
+
+- how many tool schemas the model saw up front
+- how many search and describe operations it performed
+- which final tool was called
+- whether the result came from Nodmix, MCP, or a client tool
+
+## E2E validation
+
+The gateway E2E runner proves both paths with the PI harness:
+
+```bash
+node --import tsx scripts/tool-search-gateway-e2e.ts
+```
+
+It creates a temporary fake plugin with a large tool catalog, starts the mock
+OpenAI provider, starts a Gateway once in direct mode and once with Tool Search
+enabled, then compares provider request payloads and session logs.
+
+The regression proves:
+
+1. Direct mode can call the fake plugin tool.
+2. Tool Search can call the same fake plugin tool.
+3. Direct mode exposes the fake plugin tool schemas directly to the provider.
+4. Tool Search exposes only the compact bridge.
+5. The Tool Search request payload is smaller for the large fake catalog.
+6. Session logs show the expected tool-call counts and bridged call telemetry.
+
+## Failure behavior
+
+Tool Search should fail closed:
+
+- if a tool is not in the effective policy, search should not return it
+- if a selected tool becomes unavailable, `tool_call` should fail
+- if policy or approval blocks execution, the call result should report that
+  block instead of bypassing it
+- if the code bridge cannot create an isolated runtime, use `mode: "tools"` or
+  disable Tool Search for that deployment
+
+## Related
+
+- [Tools and plugins](/tools)
+- [Multi-agent sandbox and tools](/tools/multi-agent-sandbox-tools)
+- [Exec tool](/tools/exec)
+- [ACP agents setup](/tools/acp-agents-setup)
+- [Building plugins](/plugins/building-plugins)