fengming 0.3.9 → 0.3.11

package/docs/tools/loop-detection.md

@@ -1,154 +0,0 @@
----
-summary: "How to enable and tune guardrails that detect repetitive tool-call loops"
-title: "Tool-loop detection"
-read_when:
-  - A user reports agents getting stuck repeating tool calls
-  - You need to tune repetitive-call protection
-  - You are editing agent tool/runtime policies
-  - You hit `compaction_loop_persisted` aborts after a context-overflow retry
----
-
-FengMing has two cooperating guardrails for repetitive tool-call patterns:
-
-1. **Loop detection** (`tools.loopDetection.enabled`) — disabled by default. Watches the rolling tool-call history for repeated patterns and unknown-tool retries.
-2. **Post-compaction guard** (`tools.loopDetection.postCompactionGuard`) — enabled by default unless `tools.loopDetection.enabled` is explicitly `false`. Arms after every compaction-retry and aborts the run when the agent emits the same `(tool, args, result)` triple within the window.
-
-Both are configured under the same `tools.loopDetection` block, but the post-compaction guard runs whenever the master switch is not explicitly off. Set `tools.loopDetection.enabled: false` to silence both surfaces.
-
-## Why this exists
-
-- Detect repetitive sequences that do not make progress.
-- Detect high-frequency no-result loops (same tool, same inputs, repeated errors).
-- Detect specific repeated-call patterns for known polling tools.
-- Prevent context-overflow then compaction then same-loop cycles from running indefinitely.
-
-## Configuration block
-
-Global defaults, with every documented field shown:
-
-```json5
-{
-  tools: {
-    loopDetection: {
-      enabled: false, // master switch for the rolling-history detectors
-      historySize: 30,
-      warningThreshold: 10,
-      criticalThreshold: 20,
-      unknownToolThreshold: 10,
-      globalCircuitBreakerThreshold: 30,
-      detectors: {
-        genericRepeat: true,
-        knownPollNoProgress: true,
-        pingPong: true,
-      },
-      postCompactionGuard: {
-        windowSize: 3, // armed after compaction-retry; runs unless enabled is explicitly false
-      },
-    },
-  },
-}
-```
-
-Per-agent override (optional):
-
-```json5
-{
-  agents: {
-    list: [
-      {
-        id: "safe-runner",
-        tools: {
-          loopDetection: {
-            enabled: true,
-            warningThreshold: 8,
-            criticalThreshold: 16,
-          },
-        },
-      },
-    ],
-  },
-}
-```
-
-### Field behavior
-
-| Field                            | Default | Effect                                                                                                                          |
-| -------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| `enabled`                        | `false` | Master switch for the rolling-history detectors. Setting `false` also disables the post-compaction guard.                       |
-| `historySize`                    | `30`    | Number of recent tool calls kept for analysis.                                                                                  |
-| `warningThreshold`               | `10`    | Threshold before a pattern is classified as warning-only.                                                                       |
-| `criticalThreshold`              | `20`    | Threshold for blocking repetitive no-progress loop patterns.                                                                    |
-| `unknownToolThreshold`           | `10`    | Block repeated calls to the same unavailable tool after this many misses.                                                       |
-| `globalCircuitBreakerThreshold`  | `30`    | Global no-progress breaker threshold across all detectors.                                                                      |
-| `detectors.genericRepeat`        | `true`  | Warns on repeated same-tool + same-params patterns and blocks when the same calls also return identical outcomes.               |
-| `detectors.knownPollNoProgress`  | `true`  | Detects known polling-like patterns with no state change.                                                                       |
-| `detectors.pingPong`             | `true`  | Detects alternating ping-pong patterns.                                                                                         |
-| `postCompactionGuard.windowSize` | `3`     | Number of post-compaction tool calls during which the guard stays armed and the count of identical triples that aborts the run. |
-
-For `exec`, no-progress checks compare stable command outcomes and ignore volatile runtime metadata such as duration, PID, session ID, and working directory. When a run id is available, recent tool-call history is evaluated only within that run so scheduled heartbeat cycles and fresh runs do not inherit stale loop counts from earlier runs.
-
-## Recommended setup
-
-- For smaller models, set `enabled: true` and leave the thresholds at their defaults. Flagship models rarely need rolling-history detection and can leave the master switch at `false` while still benefiting from the post-compaction guard.
-- Keep thresholds ordered as `warningThreshold < criticalThreshold < globalCircuitBreakerThreshold`.
-- If false positives occur:
-  - Raise `warningThreshold` and/or `criticalThreshold`.
-  - Optionally raise `globalCircuitBreakerThreshold`.
-  - Disable only the specific detector causing issues (`detectors.<name>: false`).
-  - Reduce `historySize` for less strict historical context.
-- To disable everything (including the post-compaction guard), set `tools.loopDetection.enabled: false` explicitly.
-
-## Post-compaction guard
-
-When the runner completes a compaction-retry after a context-overflow, it arms a short-window guard that watches the next few tool calls. If the agent emits the same `(toolName, argsHash, resultHash)` triple multiple times within the window, the guard concludes that compaction did not break the loop and aborts the run with a `compaction_loop_persisted` error.
-
-The guard is gated by the master `tools.loopDetection.enabled` flag with one twist: it stays **enabled when the flag is unset or `true`** and only deactivates when the flag is explicitly `false`. This is intentional. The guard exists to escape compaction loops that would otherwise burn unbounded tokens, so a no-config user still gets the protection.
-
-```json5
-{
-  tools: {
-    loopDetection: {
-      // master switch; set false to disable the guard along with the rolling detectors
-      enabled: true,
-      postCompactionGuard: {
-        windowSize: 3, // default
-      },
-    },
-  },
-}
-```
-
-- Lower `windowSize` is stricter (fewer attempts before abort).
-- Higher `windowSize` gives the agent more recovery attempts.
-- The guard never aborts when results are changing, only when results are byte-identical across the window.
-- It is intentionally narrow: it fires only in the immediate aftermath of a compaction-retry.
-
-<Note>
-  The post-compaction guard runs whenever the master flag is not explicitly `false`, even if you never wrote a `tools.loopDetection` block. To verify, look for `post-compaction guard armed for N attempts` in the gateway log immediately after a compaction event.
-</Note>
-
-## Logs and expected behavior
-
-When a loop is detected, FengMing reports a loop event and either dampens or blocks the next tool-cycle depending on severity. This protects users from runaway token spend and lockups while preserving normal tool access.
-
-- Warnings come first.
-- Suppression follows when patterns persist past the warning threshold.
-- Critical thresholds block the next tool-cycle and surface a clear loop-detection reason in the run record.
-- The post-compaction guard emits `compaction_loop_persisted` errors with the offending tool name and identical-call count.
-
-## Related
-
-<CardGroup cols={2}>
-  <Card title="Exec approvals" href="/tools/exec-approvals" icon="shield">
-    Allow/deny policy for shell execution.
-  </Card>
-  <Card title="Thinking levels" href="/tools/thinking" icon="brain">
-    Reasoning effort levels and provider-policy interaction.
-  </Card>
-  <Card title="Sub-agents" href="/tools/subagents" icon="users">
-    Spawning isolated agents to bound runaway behavior.
-  </Card>
-  <Card title="Configuration reference" href="/gateway/configuration-reference" icon="gear">
-    Full `tools.loopDetection` schema and merging semantics.
-  </Card>
-</CardGroup>

package/docs/tools/media-overview.md

@@ -1,160 +0,0 @@
----
-summary: "Image, video, music, speech, and media-understanding capabilities at a glance"
-read_when:
-  - Looking for an overview of FengMing's media capabilities
-  - Deciding which media provider to configure
-  - Understanding how async media generation works
-title: "Media overview"
-sidebarTitle: "Media overview"
----
-
-FengMing generates images, videos, and music, understands inbound media
-(images, audio, video), and speaks replies aloud with text-to-speech. All
-media capabilities are tool-driven: the agent decides when to use them based
-on the conversation, and each tool only appears when at least one backing
-provider is configured.
-
-Live speech uses the Talk session contract instead of the one-shot media tool
-path. Talk has three modes: provider-native `realtime`, local or streaming
-`stt-tts`, and `transcription` for observe-only speech capture. Those modes
-share provider catalogs, event envelopes, and cancellation semantics with
-telephony, meetings, browser realtime, and native push-to-talk clients.
-
-## Capabilities
-
-<CardGroup cols={2}>
-  <Card title="Image generation" href="/tools/image-generation" icon="image">
-    Create and edit images from text prompts or reference images via
-    `image_generate`. Async in chat sessions — runs in the background and
-    posts the result when ready.
-  </Card>
-  <Card title="Video generation" href="/tools/video-generation" icon="video">
-    Text-to-video, image-to-video, and video-to-video via `video_generate`.
-    Async — runs in the background and posts the result when ready.
-  </Card>
-  <Card title="Music generation" href="/tools/music-generation" icon="music">
-    Generate music or audio tracks via `music_generate`. Async in chat
-    sessions on the shared media-generation task lifecycle.
-  </Card>
-  <Card title="Text-to-speech" href="/tools/tts" icon="microphone">
-    Convert outbound replies to spoken audio via the `tts` tool plus
-    `messages.tts` config. Synchronous.
-  </Card>
-  <Card title="Media understanding" href="/nodes/media-understanding" icon="eye">
-    Summarize inbound images, audio, and video using vision-capable model
-    providers and dedicated media-understanding plugins.
-  </Card>
-  <Card title="Speech-to-text" href="/nodes/audio" icon="ear-listen">
-    Transcribe inbound voice messages through batch STT or Voice Call
-    streaming STT providers.
-  </Card>
-</CardGroup>
-
-## Provider capability matrix
-
-| Provider    | Image | Video | Music | TTS | STT | Realtime voice | Media understanding |
-| ----------- | :---: | :---: | :---: | :-: | :-: | :------------: | :-----------------: |
-| Alibaba     |       |   ✓   |       |     |     |                |                     |
-| BytePlus    |       |   ✓   |       |     |     |                |                     |
-| ComfyUI     |   ✓   |   ✓   |   ✓   |     |     |                |                     |
-| DeepInfra   |   ✓   |   ✓   |       |  ✓  |  ✓  |                |          ✓          |
-| Deepgram    |       |       |       |     |  ✓  |       ✓        |                     |
-| ElevenLabs  |       |       |       |  ✓  |  ✓  |                |                     |
-| fal         |   ✓   |   ✓   |   ✓   |     |     |                |                     |
-| Google      |   ✓   |   ✓   |   ✓   |  ✓  |     |       ✓        |          ✓          |
-| Gradium     |       |       |       |  ✓  |     |                |                     |
-| Local CLI   |       |       |       |  ✓  |     |                |                     |
-| Microsoft   |       |       |       |  ✓  |     |                |                     |
-| MiniMax     |   ✓   |   ✓   |   ✓   |  ✓  |     |                |                     |
-| Mistral     |       |       |       |     |  ✓  |                |                     |
-| OpenAI      |   ✓   |   ✓   |       |  ✓  |  ✓  |       ✓        |          ✓          |
-| OpenRouter  |   ✓   |   ✓   |   ✓   |  ✓  |  ✓  |                |          ✓          |
-| Qwen        |       |   ✓   |       |     |     |                |                     |
-| Runway      |       |   ✓   |       |     |     |                |                     |
-| SenseAudio  |       |       |       |     |  ✓  |                |                     |
-| Together    |       |   ✓   |       |     |     |                |                     |
-| Vydra       |   ✓   |   ✓   |       |  ✓  |     |                |                     |
-| xAI         |   ✓   |   ✓   |       |  ✓  |  ✓  |                |          ✓          |
-| Xiaomi MiMo |   ✓   |       |       |  ✓  |     |                |          ✓          |
-
-<Note>
-Media understanding uses any vision-capable or audio-capable model registered
-in your provider config. The matrix above lists providers with dedicated
-media-understanding support; most multimodal LLM providers (Anthropic, Google,
-OpenAI, etc.) can also understand inbound media when configured as the active
-reply model.
-</Note>
-
-## Async vs synchronous
-
-| Capability     | Mode         | Why                                                                                                  |
-| -------------- | ------------ | ---------------------------------------------------------------------------------------------------- |
-| Image          | Asynchronous | Provider processing can outlive a chat turn; generated attachments use the shared completion path.   |
-| Text-to-speech | Synchronous  | Provider responses return in seconds; attached to the reply audio.                                   |
-| Video          | Asynchronous | Provider processing takes 30 s to several minutes; slow queues can run up to the configured timeout. |
-| Music          | Asynchronous | Same provider-processing characteristic as video.                                                    |
-
-For async tools, FengMing submits the request to the provider, returns a task
-id immediately, and tracks the job in the task ledger. The agent continues
-responding to other messages while the job runs. When the provider finishes,
-FengMing wakes the agent with the generated media paths so it can tell the
-user through the session's normal visible-reply mode: automatic final reply
-delivery when configured, or `message(action="send")` when the session requires
-the message tool. If the requester session is inactive or its active wake
-fails, and some generated media is still missing from the completion reply,
-FengMing sends an idempotent direct fallback with only the missing media. Media
-already delivered by the completion reply is not posted again.
-
-## Speech-to-text and Voice Call
-
-Deepgram, DeepInfra, ElevenLabs, Mistral, OpenAI, OpenRouter, SenseAudio, and xAI can all transcribe
-inbound audio through the batch `tools.media.audio` path when configured.
-Channel plugins that preflight a voice note for mention gating or command
-parsing mark the transcribed attachment on the inbound context, so the shared
-media-understanding pass reuses that transcript instead of making a second
-STT call for the same audio.
-
-Deepgram, ElevenLabs, Mistral, OpenAI, and xAI also register Voice Call
-streaming STT providers, so live phone audio can be forwarded to the selected
-vendor without waiting for a completed recording.
-
-For live user conversations, prefer [Talk mode](/nodes/talk). Batch audio
-attachments stay on the media path; browser realtime, native push-to-talk,
-telephony, and meeting audio should use Talk events and the session-scoped
-catalogs returned by the Gateway.
-
-## Provider mappings (how vendors split across surfaces)
-
-<AccordionGroup>
-  <Accordion title="Google">
-    Image, video, music, batch TTS, backend realtime voice, and
-    media-understanding surfaces.
-  </Accordion>
-  <Accordion title="OpenAI">
-    Image, video, batch TTS, batch STT, Voice Call streaming STT, backend
-    realtime voice, and memory-embedding surfaces.
-  </Accordion>
-  <Accordion title="DeepInfra">
-    Chat/model routing, image generation/editing, text-to-video, batch TTS,
-    batch STT, image media understanding, and memory-embedding surfaces.
-    DeepInfra-native rerank/classification/object-detection models are not
-    registered until FengMing has dedicated provider contracts for those
-    categories.
-  </Accordion>
-  <Accordion title="xAI">
-    Image, video, search, code-execution, batch TTS, batch STT, and Voice
-    Call streaming STT. xAI Realtime voice is an upstream capability but is
-    not registered in FengMing until the shared realtime-voice contract can
-    represent it.
-  </Accordion>
-</AccordionGroup>
-
-## Related
-
-- [Image generation](/tools/image-generation)
-- [Video generation](/tools/video-generation)
-- [Music generation](/tools/music-generation)
-- [Text-to-speech](/tools/tts)
-- [Media understanding](/nodes/media-understanding)
-- [Audio nodes](/nodes/audio)
-- [Talk mode](/nodes/talk)

package/docs/tools/minimax-search.md

@@ -1,102 +0,0 @@
----
-summary: "MiniMax Search via the Token Plan search API"
-read_when:
-  - You want to use MiniMax for web_search
-  - You need a MiniMax Token Plan key or OAuth token
-  - You want MiniMax CN/global search host guidance
-title: "MiniMax search"
----
-
-FengMing supports MiniMax as a `web_search` provider through the MiniMax
-Token Plan search API. It returns structured search results with titles, URLs,
-snippets, and related queries.
-
-## Get a Token Plan credential
-
-<Steps>
-  <Step title="Create a key">
-    Create or copy a MiniMax Token Plan key from
-    [MiniMax Platform](https://platform.minimax.io/user-center/basic-information/interface-key).
-    OAuth setups can reuse `MINIMAX_OAUTH_TOKEN` instead.
-  </Step>
-  <Step title="Store the key">
-    Set `MINIMAX_CODE_PLAN_KEY` in the Gateway environment, or configure via:
-
-    ```bash
-    fengming configure --section web
-    ```
-
-  </Step>
-</Steps>
-
-FengMing also accepts `MINIMAX_CODING_API_KEY`, `MINIMAX_OAUTH_TOKEN`, and
-`MINIMAX_API_KEY` as env aliases. `MINIMAX_API_KEY` should point at a
-search-enabled Token Plan credential; ordinary MiniMax model API keys may not
-be accepted by the Token Plan search endpoint.
-
-## Config
-
-```json5
-{
-  plugins: {
-    entries: {
-      minimax: {
-        config: {
-          webSearch: {
-            apiKey: "sk-cp-...", // optional if a MiniMax Token Plan env var is set
-            region: "global", // or "cn"
-          },
-        },
-      },
-    },
-  },
-  tools: {
-    web: {
-      search: {
-        provider: "minimax",
-      },
-    },
-  },
-}
-```
-
-**Environment alternative:** set `MINIMAX_CODE_PLAN_KEY`, `MINIMAX_CODING_API_KEY`,
-`MINIMAX_OAUTH_TOKEN`, or `MINIMAX_API_KEY` in the Gateway environment.
-For a gateway install, put it in `~/.fengming/.env`.
-
-## Region selection
-
-MiniMax Search uses these endpoints:
-
-- Global: `https://api.minimax.io/v1/coding_plan/search`
-- CN: `https://api.minimaxi.com/v1/coding_plan/search`
-
-If `plugins.entries.minimax.config.webSearch.region` is unset, FengMing resolves
-the region in this order:
-
-1. `tools.web.search.minimax.region` / plugin-owned `webSearch.region`
-2. `MINIMAX_API_HOST`
-3. `models.providers.minimax.baseUrl`
-4. `models.providers.minimax-portal.baseUrl`
-
-That means CN onboarding or `MINIMAX_API_HOST=https://api.minimaxi.com/...`
-automatically keeps MiniMax Search on the CN host too.
-
-Even when you authenticated MiniMax through the OAuth `minimax-portal` path,
-web search still registers as provider id `minimax`; the OAuth provider base URL
-is used as a region hint for CN/global host selection, and `MINIMAX_OAUTH_TOKEN`
-can satisfy the MiniMax Search bearer credential.
-
-## Supported parameters
-
-| Parameter | Type    | Constraints | Description                                                                 |
-| --------- | ------- | ----------- | --------------------------------------------------------------------------- |
-| `query`   | string  | required    | Search query string.                                                        |
-| `count`   | integer | 1-10        | Number of results to return. FengMing trims the returned list to this size. |
-
-Provider-specific filters are not currently supported.
-
-## Related
-
-- [Web Search overview](/tools/web) -- all providers and auto-detection
-- [MiniMax](/providers/minimax) -- model, image, speech, and auth setup