fengming 0.3.10 → 0.3.12

package/docs/tools/kimi-search.md

@@ -1,105 +0,0 @@
----
-summary: "Kimi web search via Moonshot web search"
-read_when:
-  - You want to use Kimi for web_search
-  - You need a KIMI_API_KEY or MOONSHOT_API_KEY
-title: "Kimi search"
----
-
-FengMing supports Kimi as a `web_search` provider, using Moonshot web search
-to produce AI-synthesized answers with citations.
-
-## Get an API key
-
-<Steps>
-  <Step title="Create a key">
-    Get an API key from [Moonshot AI](https://platform.moonshot.cn/).
-  </Step>
-  <Step title="Store the key">
-    Set `KIMI_API_KEY` or `MOONSHOT_API_KEY` in the Gateway environment, or
-    configure via:
-
-    ```bash
-    fengming configure --section web
-    ```
-
-  </Step>
-</Steps>
-
-When you choose **Kimi** during `fengming onboard` or
-`fengming configure --section web`, FengMing can also ask for:
-
-- the Moonshot API region:
-  - `https://api.moonshot.ai/v1`
-  - `https://api.moonshot.cn/v1`
-- the default Kimi web-search model (defaults to `kimi-k2.6`)
-
-## Config
-
-```json5
-{
-  plugins: {
-    entries: {
-      moonshot: {
-        config: {
-          webSearch: {
-            apiKey: "sk-...", // optional if KIMI_API_KEY or MOONSHOT_API_KEY is set
-            baseUrl: "https://api.moonshot.ai/v1",
-            model: "kimi-k2.6",
-          },
-        },
-      },
-    },
-  },
-  tools: {
-    web: {
-      search: {
-        provider: "kimi",
-      },
-    },
-  },
-}
-```
-
-If you use the China API host for chat (`models.providers.moonshot.baseUrl`:
-`https://api.moonshot.cn/v1`), FengMing reuses that same host for Kimi
-`web_search` when `tools.web.search.kimi.baseUrl` is omitted, so keys from
-[platform.moonshot.cn](https://platform.moonshot.cn/) do not hit the
-international endpoint by mistake (which often returns HTTP 401). Override
-with `tools.web.search.kimi.baseUrl` when you need a different search base URL.
-
-**Environment alternative:** set `KIMI_API_KEY` or `MOONSHOT_API_KEY` in the
-Gateway environment. For a gateway install, put it in `~/.fengming/.env`.
-
-If you omit `baseUrl`, FengMing defaults to `https://api.moonshot.ai/v1`.
-If you omit `model`, FengMing defaults to `kimi-k2.6`.
-
-## How it works
-
-Kimi uses Moonshot web search to synthesize answers with inline citations,
-similar to Gemini and Grok's grounded response approach.
-
-FengMing treats Kimi `web_search` as successful only after Moonshot returns
-native web-search grounding evidence, such as a replayable `$web_search` tool
-payload, `search_results`, or citation URLs. If Kimi stops immediately with a
-plain chat answer like "I cannot browse the internet" and no grounding evidence,
-FengMing returns a structured `kimi_web_search_ungrounded` error instead of
-wrapping that text as a search result. Retry the query, switch to a structured
-provider such as Brave, or use `web_fetch` / the browser tool when you already
-have a target URL.
-
-## Supported parameters
-
-Kimi search supports `query`.
-
-`count` is accepted for shared `web_search` compatibility, but Kimi still
-returns one synthesized answer with citations rather than an N-result list.
-
-Provider-specific filters are not currently supported.
-
-## Related
-
-- [Web Search overview](/tools/web) -- all providers and auto-detection
-- [Moonshot AI](/providers/moonshot) -- Moonshot model + Kimi Coding provider docs
-- [Gemini Search](/tools/gemini-search) -- AI-synthesized answers via Google grounding
-- [Grok Search](/tools/grok-search) -- AI-synthesized answers via xAI grounding

package/docs/tools/llm-task.md

@@ -1,137 +0,0 @@
----
-summary: "JSON-only LLM tasks for workflows (optional plugin tool)"
-read_when:
-  - You want a JSON-only LLM step inside workflows
-  - You need schema-validated LLM output for automation
-title: "LLM task"
----
-
-`llm-task` is an **optional plugin tool** that runs a JSON-only LLM task and
-returns structured output (optionally validated against JSON Schema).
-
-This is ideal for workflow engines like Lobster: you can add a single LLM step
-without writing custom FengMing code for each workflow.
-
-## Enable the plugin
-
-1. Enable the plugin:
-
-```json
-{
-  "plugins": {
-    "entries": {
-      "llm-task": { "enabled": true }
-    }
-  }
-}
-```
-
-2. Allow the optional tool:
-
-```json
-{
-  "tools": {
-    "alsoAllow": ["llm-task"]
-  }
-}
-```
-
-Use `tools.allow` only when you want restrictive allowlist mode.
-
-## Config (optional)
-
-```json
-{
-  "plugins": {
-    "entries": {
-      "llm-task": {
-        "enabled": true,
-        "config": {
-          "defaultProvider": "openai",
-          "defaultModel": "gpt-5.5",
-          "defaultAuthProfileId": "main",
-          "allowedModels": ["openai/gpt-5.5"],
-          "maxTokens": 800,
-          "timeoutMs": 30000
-        }
-      }
-    }
-  }
-}
-```
-
-`allowedModels` is an allowlist of `provider/model` strings. If set, any request
-outside the list is rejected.
-
-## Tool parameters
-
-- `prompt` (string, required)
-- `input` (any, optional)
-- `schema` (object, optional JSON Schema)
-- `provider` (string, optional)
-- `model` (string, optional)
-- `thinking` (string, optional)
-- `authProfileId` (string, optional)
-- `temperature` (number, optional)
-- `maxTokens` (number, optional)
-- `timeoutMs` (number, optional)
-
-`thinking` accepts the standard FengMing reasoning presets, such as `low` or `medium`.
-
-## Output
-
-Returns `details.json` containing the parsed JSON (and validates against
-`schema` when provided).
-
-## Example: Lobster workflow step
-
-### Important limitation
-
-The example below assumes the **standalone Lobster CLI** is running in an environment where `fengming.invoke` already has the correct gateway URL/auth context.
-
-For the bundled **embedded** Lobster runner inside FengMing, this nested CLI pattern is **not currently reliable**:
-
-```lobster
-fengming.invoke --tool llm-task --action json --args-json '{ ... }'
-```
-
-Until embedded Lobster has a supported bridge for this flow, prefer either:
-
-- direct `llm-task` tool calls outside Lobster, or
-- Lobster steps that do not rely on nested `fengming.invoke` calls.
-
-Standalone Lobster CLI example:
-
-```lobster
-fengming.invoke --tool llm-task --action json --args-json '{
-  "prompt": "Given the input email, return intent and draft.",
-  "thinking": "low",
-  "input": {
-    "subject": "Hello",
-    "body": "Can you help?"
-  },
-  "schema": {
-    "type": "object",
-    "properties": {
-      "intent": { "type": "string" },
-      "draft": { "type": "string" }
-    },
-    "required": ["intent", "draft"],
-    "additionalProperties": false
-  }
-}'
-```
-
-## Safety notes
-
-- The tool is **JSON-only** and instructs the model to output only JSON (no
-  code fences, no commentary).
-- No tools are exposed to the model for this run.
-- Treat output as untrusted unless you validate with `schema`.
-- Put approvals before any side-effecting step (send, post, exec).
-
-## Related
-
-- [Thinking levels](/tools/thinking)
-- [Sub-agents](/tools/subagents)
-- [Slash commands](/tools/slash-commands)

package/docs/tools/lobster.md

@@ -1,365 +0,0 @@
----
-summary: "Typed workflow runtime for FengMing with resumable approval gates."
-title: Lobster
-read_when:
-  - You want deterministic multi-step workflows with explicit approvals
-  - You need to resume a workflow without re-running earlier steps
----
-
-Lobster is a workflow shell that lets FengMing run multi-step tool sequences as a single, deterministic operation with explicit approval checkpoints.
-
-Lobster is one authoring layer above detached background work. For flow orchestration above individual tasks, see [Task Flow](/automation/taskflow) (`fengming tasks flow`). For the task activity ledger, see [`fengming tasks`](/automation/tasks).
-
-## Hook
-
-Your assistant can build the tools that manage itself. Ask for a workflow, and 30 minutes later you have a CLI plus pipelines that run as one call. Lobster is the missing piece: deterministic pipelines, explicit approvals, and resumable state.
-
-## Why
-
-Today, complex workflows require many back-and-forth tool calls. Each call costs tokens, and the LLM has to orchestrate every step. Lobster moves that orchestration into a typed runtime:
-
-- **One call instead of many**: FengMing runs one Lobster tool call and gets a structured result.
-- **Approvals built in**: Side effects (send email, post comment) halt the workflow until explicitly approved.
-- **Resumable**: Halted workflows return a token; approve and resume without re-running everything.
-
-## Why a DSL instead of plain programs?
-
-Lobster is intentionally small. The goal is not "a new language," it's a predictable, AI-friendly pipeline spec with first-class approvals and resume tokens.
-
-- **Approve/resume is built in**: A normal program can prompt a human, but it can't _pause and resume_ with a durable token without you inventing that runtime yourself.
-- **Determinism + auditability**: Pipelines are data, so they're easy to log, diff, replay, and review.
-- **Constrained surface for AI**: A tiny grammar + JSON piping reduces "creative" code paths and makes validation realistic.
-- **Safety policy baked in**: Timeouts, output caps, sandbox checks, and allowlists are enforced by the runtime, not each script.
-- **Still programmable**: Each step can call any CLI or script. If you want JS/TS, generate `.lobster` files from code.
-
-## How it works
-
-FengMing runs Lobster workflows **in-process** using an embedded runner. No external CLI subprocess is spawned; the workflow engine executes inside the gateway process and returns a JSON envelope directly.
-If the pipeline pauses for approval, the tool returns a `resumeToken` so you can continue later.
-
-## Pattern: small CLI + JSON pipes + approvals
-
-Build tiny commands that speak JSON, then chain them into a single Lobster call. (Example command names below - swap in your own.)
-
-```bash
-inbox list --json
-inbox categorize --json
-inbox apply --json
-```
-
-```json
-{
-  "action": "run",
-  "pipeline": "exec --json --shell 'inbox list --json' | exec --stdin json --shell 'inbox categorize --json' | exec --stdin json --shell 'inbox apply --json' | approve --preview-from-stdin --limit 5 --prompt 'Apply changes?'",
-  "timeoutMs": 30000
-}
-```
-
-If the pipeline requests approval, resume with the token:
-
-```json
-{
-  "action": "resume",
-  "token": "<resumeToken>",
-  "approve": true
-}
-```
-
-AI triggers the workflow; Lobster executes the steps. Approval gates keep side effects explicit and auditable.
-
-Example: map input items into tool calls:
-
-```bash
-gog.gmail.search --query 'newer_than:1d' \
-  | fengming.invoke --tool message --action send --each --item-key message --args-json '{"provider":"telegram","to":"..."}'
-```
-
-## JSON-only LLM steps (llm-task)
-
-For workflows that need a **structured LLM step**, enable the optional
-`llm-task` plugin tool and call it from Lobster. This keeps the workflow
-deterministic while still letting you classify/summarize/draft with a model.
-
-Enable the tool:
-
-```json
-{
-  "plugins": {
-    "entries": {
-      "llm-task": { "enabled": true }
-    }
-  },
-  "agents": {
-    "list": [
-      {
-        "id": "main",
-        "tools": { "alsoAllow": ["llm-task"] }
-      }
-    ]
-  }
-}
-```
-
-### Important limitation: embedded Lobster vs `fengming.invoke`
-
-The bundled Lobster plugin runs workflows **in-process** inside the gateway. In that embedded mode, `fengming.invoke` does **not** automatically inherit a gateway URL/auth context for nested FengMing CLI tool calls.
-
-That means this pattern is **not currently reliable in the embedded runner**:
-
-```lobster
-fengming.invoke --tool llm-task --action json --args-json '{ ... }'
-```
-
-Use the example below only when running the **standalone Lobster CLI** in an environment where `fengming.invoke` is already configured with the correct gateway/auth context.
-
-Use it in a standalone Lobster CLI pipeline:
-
-```lobster
-fengming.invoke --tool llm-task --action json --args-json '{
-  "prompt": "Given the input email, return intent and draft.",
-  "thinking": "low",
-  "input": { "subject": "Hello", "body": "Can you help?" },
-  "schema": {
-    "type": "object",
-    "properties": {
-      "intent": { "type": "string" },
-      "draft": { "type": "string" }
-    },
-    "required": ["intent", "draft"],
-    "additionalProperties": false
-  }
-}'
-```
-
-If you are using the embedded Lobster plugin today, prefer either:
-
-- a direct `llm-task` tool call outside Lobster, or
-- non-`fengming.invoke` steps inside the Lobster pipeline until a supported embedded bridge is added.
-
-See [LLM Task](/tools/llm-task) for details and configuration options.
-
-## Workflow files (.lobster)
-
-Lobster can run YAML/JSON workflow files with `name`, `args`, `steps`, `env`, `condition`, and `approval` fields. In FengMing tool calls, set `pipeline` to the file path.
-
-```yaml
-name: inbox-triage
-args:
-  tag:
-    default: "family"
-steps:
-  - id: collect
-    command: inbox list --json
-  - id: categorize
-    command: inbox categorize --json
-    stdin: $collect.stdout
-  - id: approve
-    command: inbox apply --approve
-    stdin: $categorize.stdout
-    approval: required
-  - id: execute
-    command: inbox apply --execute
-    stdin: $categorize.stdout
-    condition: $approve.approved
-```
-
-Notes:
-
-- `stdin: $step.stdout` and `stdin: $step.json` pass a prior step's output.
-- `condition` (or `when`) can gate steps on `$step.approved`.
-
-## Install Lobster
-
-Bundled Lobster workflows run in-process; no separate `lobster` binary is required. The embedded runner ships with the Lobster plugin.
-
-If you need the standalone Lobster CLI for development or external pipelines, install it from the [Lobster repo](https://github.com/fengming/lobster) and ensure `lobster` is on `PATH`.
-
-## Enable the tool
-
-Lobster is an **optional** plugin tool (not enabled by default).
-
-Recommended (additive, safe):
-
-```json
-{
-  "tools": {
-    "alsoAllow": ["lobster"]
-  }
-}
-```
-
-Or per-agent:
-
-```json
-{
-  "agents": {
-    "list": [
-      {
-        "id": "main",
-        "tools": {
-          "alsoAllow": ["lobster"]
-        }
-      }
-    ]
-  }
-}
-```
-
-Avoid using `tools.allow: ["lobster"]` unless you intend to run in restrictive allowlist mode.
-
-<Note>
-Allowlists are opt-in for optional plugins. `alsoAllow` enables only the named optional plugin tools while preserving the normal core tool set. To restrict core tools, use `tools.allow` with the core tools or groups you want.
-</Note>
-
-## Example: Email triage
-
-Without Lobster:
-
-```
-User: "Check my email and draft replies"
-→ fengming calls gmail.list
-→ LLM summarizes
-→ User: "draft replies to #2 and #5"
-→ LLM drafts
-→ User: "send #2"
-→ fengming calls gmail.send
-(repeat daily, no memory of what was triaged)
-```
-
-With Lobster:
-
-```json
-{
-  "action": "run",
-  "pipeline": "email.triage --limit 20",
-  "timeoutMs": 30000
-}
-```
-
-Returns a JSON envelope (truncated):
-
-```json
-{
-  "ok": true,
-  "status": "needs_approval",
-  "output": [{ "summary": "5 need replies, 2 need action" }],
-  "requiresApproval": {
-    "type": "approval_request",
-    "prompt": "Send 2 draft replies?",
-    "items": [],
-    "resumeToken": "..."
-  }
-}
-```
-
-User approves → resume:
-
-```json
-{
-  "action": "resume",
-  "token": "<resumeToken>",
-  "approve": true
-}
-```
-
-One workflow. Deterministic. Safe.
-
-## Tool parameters
-
-### `run`
-
-Run a pipeline in tool mode.
-
-```json
-{
-  "action": "run",
-  "pipeline": "gog.gmail.search --query 'newer_than:1d' | email.triage",
-  "cwd": "workspace",
-  "timeoutMs": 30000,
-  "maxStdoutBytes": 512000
-}
-```
-
-Run a workflow file with args:
-
-```json
-{
-  "action": "run",
-  "pipeline": "/path/to/inbox-triage.lobster",
-  "argsJson": "{\"tag\":\"family\"}"
-}
-```
-
-### `resume`
-
-Continue a halted workflow after approval.
-
-```json
-{
-  "action": "resume",
-  "token": "<resumeToken>",
-  "approve": true
-}
-```
-
-### Optional inputs
-
-- `cwd`: Relative working directory for the pipeline (must stay within the gateway working directory).
-- `timeoutMs`: Abort the workflow if it exceeds this duration (default: 20000).
-- `maxStdoutBytes`: Abort the workflow if output exceeds this size (default: 512000).
-- `argsJson`: JSON string passed to `lobster run --args-json` (workflow files only).
-
-## Output envelope
-
-Lobster returns a JSON envelope with one of three statuses:
-
-- `ok` → finished successfully
-- `needs_approval` → paused; `requiresApproval.resumeToken` is required to resume
-- `cancelled` → explicitly denied or cancelled
-
-The tool surfaces the envelope in both `content` (pretty JSON) and `details` (raw object).
-
-## Approvals
-
-If `requiresApproval` is present, inspect the prompt and decide:
-
-- `approve: true` → resume and continue side effects
-- `approve: false` → cancel and finalize the workflow
-
-Use `approve --preview-from-stdin --limit N` to attach a JSON preview to approval requests without custom jq/heredoc glue. Resume tokens are now compact: Lobster stores workflow resume state under its state dir and hands back a small token key.
-
-## OpenProse
-
-OpenProse pairs well with Lobster: use `/prose` to orchestrate multi-agent prep, then run a Lobster pipeline for deterministic approvals. If a Prose program needs Lobster, allow the `lobster` tool for sub-agents via `tools.subagents.tools`. See [OpenProse](/prose).
-
-## Safety
-
-- **Local in-process only** - workflows execute inside the gateway process; no network calls from the plugin itself.
-- **No secrets** - Lobster doesn't manage OAuth; it calls FengMing tools that do.
-- **Sandbox-aware** - disabled when the tool context is sandboxed.
-- **Hardened** - timeouts and output caps enforced by the embedded runner.
-
-## Troubleshooting
-
-- **`lobster timed out`** → increase `timeoutMs`, or split a long pipeline.
-- **`lobster output exceeded maxStdoutBytes`** → raise `maxStdoutBytes` or reduce output size.
-- **`lobster returned invalid JSON`** → ensure the pipeline runs in tool mode and prints only JSON.
-- **`lobster failed`** → check gateway logs for the embedded runner error details.
-
-## Learn more
-
-- [Plugins](/tools/plugin)
-- [Plugin tool authoring](/plugins/building-plugins#registering-agent-tools)
-
-## Case study: community workflows
-
-One public example: a "second brain" CLI + Lobster pipelines that manage three Markdown vaults (personal, partner, shared). The CLI emits JSON for stats, inbox listings, and stale scans; Lobster chains those commands into workflows like `weekly-review`, `inbox-triage`, `memory-consolidation`, and `shared-task-sync`, each with approval gates. AI handles judgment (categorization) when available and falls back to deterministic rules when not.
-
-- Thread: [https://x.com/plattenschieber/status/2014508656335770033](https://x.com/plattenschieber/status/2014508656335770033)
-- Repo: [https://github.com/bloomedai/brain-cli](https://github.com/bloomedai/brain-cli)
-
-## Related
-
-- [Automation](/automation) - scheduling Lobster workflows
-- [Automation Overview](/automation) - all automation mechanisms
-- [Tools Overview](/tools) - all available agent tools