fengming 0.3.9 → 0.3.11

package/docs/tools/tavily.md

@@ -1,162 +0,0 @@
----
-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. FengMing 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 `fengming 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

@@ -1,142 +0,0 @@
----
-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.8 and Opus 4.7 keep thinking off unless you explicitly set a thinking level. Opus 4.8's provider-owned effort default is `high` after adaptive thinking is enabled.
-  - 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 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 FengMing 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`; FengMing 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 FengMing**: the resolved level is passed to the in-process FengMing 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.
-- FengMing 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 Codex-backed `openai/*` models, fast mode sends the same `service_tier=priority` flag on Codex Responses. FengMing 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. FengMing 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`.
-- Authorized external channel senders may persist the session verbose override. Internal gateway/webchat clients need `operator.admin` to persist it.
-- 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 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`: streams reasoning while the reply is generating when the active channel supports reasoning previews, 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, FengMing 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>`, including `Inherited: Off` when inherited thinking is disabled.
-- Explicit picker choices use their direct level labels while preserving provider labels when present (for example `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 `fengming/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" }`.
-- Profile hooks receive merged catalog facts when available, including `reasoning`, `compat.thinkingFormat`, and `compat.supportedReasoningEfforts`. Use those facts to expose binary or custom profiles only when the configured request contract supports the matching payload.
-- 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

@@ -1,84 +0,0 @@
----
-summary: "Compact noisy exec and bash tool results with the optional Tokenjuice plugin"
-title: "Tokenjuice"
-read_when:
-  - You want shorter `exec` or `bash` tool results in FengMing
-  - You want to install or enable the Tokenjuice plugin
-  - You need to understand what tokenjuice changes and what it leaves raw
----
-
-`tokenjuice` is an optional external 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 FengMing embedded runs and FengMing dynamic tools in the Codex
-app-server harness. Tokenjuice hooks FengMing's tool-result middleware and
-trims the output before it goes back into the active harness session.
-
-## Enable the plugin
-
-Install once:
-
-```bash
-fengming plugins install clawhub:@fengming/tokenjuice
-```
-
-Then enable it:
-
-```bash
-fengming config set plugins.entries.tokenjuice.enabled true
-```
-
-Equivalent:
-
-```bash
-fengming plugins enable tokenjuice
-```
-
-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
-fengming config set plugins.entries.tokenjuice.enabled false
-```
-
-Or:
-
-```bash
-fengming plugins disable tokenjuice
-```
-
-## Related
-
-- [Exec tool](/tools/exec)
-- [Thinking levels](/tools/thinking)
-- [Context engine](/concepts/context-engine)

package/docs/tools/tool-search.md

@@ -1,269 +0,0 @@
----
-summary: "Tool Search: compact large FengMing tool catalogs behind search, describe, and call"
-title: "Tool Search"
-read_when:
-  - You want FengMing agents to use a large tool catalog without adding every tool schema to the prompt
-  - You want FengMing tools, MCP tools, and client tools exposed through one compact runtime surface
-  - You are implementing or debugging tool discovery for FengMing runs
----
-
-Tool Search is an experimental FengMing agent runtime feature. It gives 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 FengMing 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 FengMing runs, the model receives one `tool_search_code` tool by default.
-That tool runs a short JavaScript body in an isolated Node subprocess with an
-`fengming.tools` bridge:
-
-```js
-const hits = await fengming.tools.search("create a GitHub issue");
-const tool = await fengming.tools.describe(hits[0].id);
-return await fengming.tools.call(tool.id, {
-  title: "Crash on startup",
-  body: "Steps to reproduce...",
-});
-```
-
-The catalog can include FengMing 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 FengMing.
-
-Codex harness runs do not receive these experimental FengMing Tool Search
-controls. FengMing 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 FengMing 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 FengMing 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 FengMing code bridge or the structured fallback tools to the
-   model.
-
-At execution time every real tool call returns to FengMing. The isolated Node
-runtime does not hold plugin implementations, MCP client objects, or secrets.
-`fengming.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 FengMing 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 FengMing, 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
-
-`fengming.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 fengming.tools.search("calendar event", { limit: 5 });
-```
-
-`fengming.tools.describe(id)`
-
-Loads full metadata for one search result, including the exact input schema.
-
-```js
-const calendarCreate = await fengming.tools.describe("mcp:calendar:create_event");
-```
-
-`fengming.tools.call(id, args)`
-
-Calls a selected tool through FengMing.
-
-```js
-await fengming.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. FengMing 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`
-- `fengming.tools.search`
-- `fengming.tools.describe`
-- `fengming.tools.call`
-
-Normal FengMing 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 FengMing runs with the default code bridge:
-
-```bash
-fengming config set tools.toolSearch true
-```
-
-Equivalent JSON:
-
-```json5
-{
-  tools: {
-    toolSearch: true,
-  },
-}
-```
-
-Use the structured fallback tools instead for FengMing 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 FengMing
-- 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 FengMing, MCP, or a client tool
-
-## E2E validation
-
-The gateway E2E runner proves both paths with the FengMing runtime:
-
-```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)