fengming 0.3.9 → 0.3.11

package/docs/tools/agent-send.md

@@ -1,130 +0,0 @@
----
-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"
----
-
-`fengming 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
-    fengming agent --agent main --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
-    fengming agent --agent ops --message "Summarize logs"
-
-    # Target a phone number (derives session key)
-    fengming agent --to +15555550123 --message "Status update"
-
-    # Reuse an existing session
-    fengming agent --session-id abc123 --message "Continue the task"
-
-    # Target an exact session key
-    fengming agent --session-key agent:ops:incident-42 --message "Summarize status"
-    ```
-
-  </Step>
-
-  <Step title="Deliver the reply to a channel">
-    ```bash
-    # Deliver to WhatsApp (default channel)
-    fengming agent --to +15555550123 --message "Report ready" --deliver
-
-    # Deliver to Slack
-    fengming 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)           |
-| `--session-key \<key\>`       | Use an explicit session key                                 |
-| `--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`).
-- `--session-key` selects an explicit key. Agent-prefixed keys must use
-  `agent:<agent-id>:<session-key>`, and `--agent` must match that agent id when
-  both are supplied. Bare non-sentinel keys are scoped to `--agent` when
-  supplied; for example, `--agent ops --session-key incident-42` routes to
-  `agent:ops:incident-42`. Without `--agent`, bare non-sentinel keys are scoped
-  to the configured default agent. Literal `global` and `unknown` remain
-  unscoped only when no `--agent` is supplied; in that case, embedded fallback
-  and store ownership use the configured default agent.
-- 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
-fengming agent --to +15555550123 --message "Trace logs" --verbose on --json
-
-# Turn with thinking level
-fengming agent --session-id 1234 --message "Summarize inbox" --thinking medium
-
-# Exact session key
-fengming agent --session-key agent:ops:incident-42 --message "Summarize status"
-
-# Legacy key scoped to an agent
-fengming agent --agent ops --session-key incident-42 --message "Summarize status"
-
-# Deliver to a different channel than the session
-fengming 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 `fengming 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

@@ -1,64 +0,0 @@
----
-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

@@ -1,139 +0,0 @@
----
-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"
----
-
-FengMing 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. FengMing 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
-
-- FengMing 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