fengming 0.3.10 → 0.3.11

package/docs/platforms/windows.md

@@ -1,286 +0,0 @@
----
-summary: "Windows support: native and WSL2 install paths, daemon, and current caveats"
-read_when:
-  - Installing FengMing on Windows
-  - Choosing between native Windows and WSL2
-  - Looking for Windows companion app status
-title: "Windows"
----
-
-FengMing supports both **native Windows** and **WSL2**. WSL2 is the more
-stable path and recommended for the full experience — the CLI, Gateway, and
-tooling run inside Linux with full compatibility. Native Windows works for
-core CLI and Gateway use, with some caveats noted below.
-
-Native Windows companion apps are planned.
-
-## WSL2 (recommended)
-
-- [Getting Started](/start/getting-started) (use inside WSL)
-- [Install & updates](/install/updating)
-- Official WSL2 guide (Microsoft): [https://learn.microsoft.com/windows/wsl/install](https://learn.microsoft.com/windows/wsl/install)
-
-## Native Windows status
-
-Native Windows CLI flows are improving, but WSL2 is still the recommended path.
-
-What works well on native Windows today:
-
-- website installer via `install.ps1`
-- local CLI use such as `fengming --version`, `fengming doctor`, and `fengming plugins list --json`
-- embedded local-agent/provider smoke such as:
-
-```powershell
-fengming agent --local --agent main --thinking low -m "Reply with exactly WINDOWS-HATCH-OK."
-```
-
-Current caveats:
-
-- `fengming onboard --non-interactive` still expects a reachable local gateway unless you pass `--skip-health`
-- `fengming onboard --non-interactive --install-daemon` and `fengming gateway install` try Windows Scheduled Tasks first
-- if Scheduled Task creation is denied, FengMing falls back to a per-user Startup-folder login item and starts the gateway immediately
-- if `schtasks` itself wedges or stops responding, FengMing now aborts that path quickly and falls back instead of hanging forever
-- Scheduled Tasks are still preferred when available because they provide better supervisor status
-
-If you want the native CLI only, without gateway service install, use one of these:
-
-```powershell
-fengming onboard --non-interactive --skip-health
-fengming gateway run
-```
-
-If you do want managed startup on native Windows:
-
-```powershell
-fengming gateway install
-fengming gateway status --json
-```
-
-If Scheduled Task creation is blocked, the fallback service mode still auto-starts after login through the current user's Startup folder.
-
-## Gateway
-
-- [Gateway runbook](/gateway)
-- [Configuration](/gateway/configuration)
-
-## Gateway service install (CLI)
-
-Inside WSL2:
-
-```
-fengming onboard --install-daemon
-```
-
-Or:
-
-```
-fengming gateway install
-```
-
-Or:
-
-```
-fengming configure
-```
-
-Select **Gateway service** when prompted.
-
-Repair/migrate:
-
-```
-fengming doctor
-```
-
-## Gateway auto-start before Windows login
-
-For headless setups, ensure the full boot chain runs even when no one logs into
-Windows.
-
-### 1) Keep user services running without login
-
-Inside WSL:
-
-```bash
-sudo loginctl enable-linger "$(whoami)"
-```
-
-### 2) Install the FengMing gateway user service
-
-Inside WSL:
-
-```bash
-fengming gateway install
-```
-
-### 3) Start WSL automatically at Windows boot
-
-In PowerShell as Administrator:
-
-```powershell
-schtasks /create /tn "WSL Boot" /tr "wsl.exe -d Ubuntu --exec /bin/true" /sc onstart /ru SYSTEM
-```
-
-Replace `Ubuntu` with your distro name from:
-
-```powershell
-wsl --list --verbose
-```
-
-### Verify startup chain
-
-After a reboot (before Windows sign-in), check from WSL:
-
-```bash
-systemctl --user is-enabled fengming-gateway.service
-systemctl --user status fengming-gateway.service --no-pager
-```
-
-## Advanced: expose WSL services over LAN (portproxy)
-
-WSL has its own virtual network. If another machine needs to reach a service
-running **inside WSL** (SSH, a local TTS server, or the Gateway), you must
-forward a Windows port to the current WSL IP. The WSL IP changes after restarts,
-so you may need to refresh the forwarding rule.
-
-Example (PowerShell **as Administrator**):
-
-```powershell
-$Distro = "Ubuntu-24.04"
-$ListenPort = 2222
-$TargetPort = 22
-
-$WslIp = (wsl -d $Distro -- hostname -I).Trim().Split(" ")[0]
-if (-not $WslIp) { throw "WSL IP not found." }
-
-netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=$ListenPort `
-  connectaddress=$WslIp connectport=$TargetPort
-```
-
-Allow the port through Windows Firewall (one-time):
-
-```powershell
-New-NetFirewallRule -DisplayName "WSL SSH $ListenPort" -Direction Inbound `
-  -Protocol TCP -LocalPort $ListenPort -Action Allow
-```
-
-Refresh the portproxy after WSL restarts:
-
-```powershell
-netsh interface portproxy delete v4tov4 listenport=$ListenPort listenaddress=0.0.0.0 | Out-Null
-netsh interface portproxy add v4tov4 listenport=$ListenPort listenaddress=0.0.0.0 `
-  connectaddress=$WslIp connectport=$TargetPort | Out-Null
-```
-
-Notes:
-
-- SSH from another machine targets the **Windows host IP** (example: `ssh user@windows-host -p 2222`).
-- Remote nodes must point at a **reachable** Gateway URL (not `127.0.0.1`); use
-  `fengming status --all` to confirm.
-- Use `listenaddress=0.0.0.0` for LAN access; `127.0.0.1` keeps it local only.
-- If you want this automatic, register a Scheduled Task to run the refresh
-  step at login.
-
-## Step-by-step WSL2 install
-
-### 1) Install WSL2 + Ubuntu
-
-Open PowerShell (Admin):
-
-```powershell
-wsl --install
-# Or pick a distro explicitly:
-wsl --list --online
-wsl --install -d Ubuntu-24.04
-```
-
-Reboot if Windows asks.
-
-### 2) Enable systemd (required for gateway install)
-
-In your WSL terminal:
-
-```bash
-sudo tee /etc/wsl.conf >/dev/null <<'EOF'
-[boot]
-systemd=true
-EOF
-```
-
-Then from PowerShell:
-
-```powershell
-wsl --shutdown
-```
-
-Re-open Ubuntu, then verify:
-
-```bash
-systemctl --user status
-```
-
-### 3) Install FengMing (inside WSL)
-
-For a normal first-time setup inside WSL, follow the Linux Getting Started flow:
-
-```bash
-git clone https://github.com/fengming/fengming.git
-cd fengming
-pnpm install
-pnpm build
-pnpm ui:build
-pnpm fengming onboard --install-daemon
-```
-
-If you are developing from source instead of doing first-time onboarding, use the
-source dev loop from [Setup](/start/setup):
-
-```bash
-pnpm install
-# First run only (or after resetting local FengMing config/workspace)
-pnpm fengming setup
-pnpm gateway:watch
-```
-
-Full guide: [Getting Started](/start/getting-started)
-
-## Windows companion app
-
-We do not have a Windows companion app yet. Contributions are welcome if you want to
-help make it happen.
-
-## Git and GitHub connectivity (contributors)
-
-Some networks block or throttle HTTPS to GitHub. If `git clone` fails with timeouts
-or connection resets, try another network, a VPN, or an HTTP/HTTPS proxy your
-organization provides.
-
-If `gh auth login` fails during the browser device flow (for example a timeout
-reaching `github.com:443`), authenticate with a personal access token instead:
-
-1. Create a token with at least the `repo` scope (classic PAT) or equivalent
-   fine-grained access.
-2. In PowerShell for the current session:
-
-```powershell
-$env:GH_TOKEN="<your-token>"
-gh auth status
-gh auth setup-git
-```
-
-3. If `gh auth status` warns about missing `read:org`, mint a token that includes
-   that scope and re-assign the variable:
-
-```powershell
-$env:GH_TOKEN="<your-token-with-repo-and-read:org>"
-gh auth status
-```
-
-`gh auth refresh -s read:org` only applies when you authenticated via `gh auth login`
-and have stored credentials to refresh (not when using `GH_TOKEN`).
-
-Never commit tokens or paste them into issues or pull requests.
-
-## Related
-
-- [Install overview](/install)
-- [Platforms](/platforms)

package/docs/plugins/adding-capabilities.md

@@ -1,146 +0,0 @@
----
-summary: "Contributor guide for adding a new shared capability to the FengMing plugin system"
-read_when:
-  - Adding a new core capability and plugin registration surface
-  - Deciding whether code belongs in core, a vendor plugin, or a feature plugin
-  - Wiring a new runtime helper for channels or tools
-title: "Adding capabilities (contributor guide)"
-sidebarTitle: "Adding capabilities"
----
-
-<Info>
-  This is a **contributor guide** for FengMing core developers. If you are
-  building an external plugin, see [Building plugins](/plugins/building-plugins)
-  instead. For the deep architecture reference (capability model, ownership,
-  load pipeline, runtime helpers), see [Plugin internals](/plugins/architecture).
-</Info>
-
-Use this when FengMing needs a new shared domain such as embeddings, image
-generation, video generation, or some future vendor-backed feature area.
-
-The rule:
-
-- **plugin** = ownership boundary
-- **capability** = shared core contract
-
-Do not start by wiring a vendor directly into a channel or a tool. Start by defining the capability.
-
-## When to create a capability
-
-Create a new capability when **all** of these are true:
-
-1. More than one vendor could plausibly implement it.
-2. Channels, tools, or feature plugins should consume it without caring about the vendor.
-3. Core needs to own fallback, policy, config, or delivery behavior.
-
-If the work is vendor-only and no shared contract exists yet, stop and define the contract first.
-
-## The standard sequence
-
-1. Define the typed core contract.
-2. Add plugin registration for that contract.
-3. Add a shared runtime helper.
-4. Wire one real vendor plugin as proof.
-5. Move feature/channel consumers onto the runtime helper.
-6. Add contract tests.
-7. Document the operator-facing config and ownership model.
-
-## What goes where
-
-**Core:**
-
-- Request/response types.
-- Provider registry + resolution.
-- Fallback behavior.
-- Config schema with propagated `title` / `description` docs metadata on nested object, wildcard, array-item, and composition nodes.
-- Runtime helper surface.
-
-**Vendor plugin:**
-
-- Vendor API calls.
-- Vendor auth handling.
-- Vendor-specific request normalization.
-- Registration of the capability implementation.
-
-**Feature/channel plugin:**
-
-- Calls `api.runtime.*` or the matching `plugin-sdk/*-runtime` helper.
-- Never calls a vendor implementation directly.
-
-## Provider and harness seams
-
-Use **provider hooks** when the behavior belongs to the model provider contract rather than the generic agent loop. Examples include provider-specific request params after transport selection, auth-profile preference, prompt overlays, and follow-up fallback routing after model/profile failover.
-
-Use **agent harness hooks** when the behavior belongs to the runtime that is executing a turn. Harnesses can classify successful-but-unusable attempt results such as empty, reasoning-only, or planning-only responses so the outer model fallback policy can make the retry decision.
-
-Keep both seams narrow:
-
-- Core owns the retry/fallback policy.
-- Provider plugins own provider-specific request/auth/routing hints.
-- Harness plugins own runtime-specific attempt classification.
-- Third-party plugins return hints, not direct mutations of core state.
-
-## File checklist
-
-For a new capability, expect to touch these areas:
-
-- `src/<capability>/types.ts`
-- `src/<capability>/...registry/runtime.ts`
-- `src/plugins/types.ts`
-- `src/plugins/registry.ts`
-- `src/plugins/captured-registration.ts`
-- `src/plugins/contracts/registry.ts`
-- `src/plugins/runtime/types-core.ts`
-- `src/plugins/runtime/index.ts`
-- `src/plugin-sdk/<capability>.ts`
-- `src/plugin-sdk/<capability>-runtime.ts`
-- One or more bundled plugin packages.
-- Config, docs, tests.
-
-## Worked example: image generation
-
-Image generation follows the standard shape:
-
-1. Core defines `ImageGenerationProvider`.
-2. Core exposes `registerImageGenerationProvider(...)`.
-3. Core exposes `runtime.imageGeneration.generate(...)`.
-4. The `openai`, `google`, `fal`, and `minimax` plugins register vendor-backed implementations.
-5. Future vendors register the same contract without changing channels/tools.
-
-The config key is intentionally separate from vision-analysis routing:
-
-- `agents.defaults.imageModel` analyzes images.
-- `agents.defaults.imageGenerationModel` generates images.
-
-Keep those separate so fallback and policy remain explicit.
-
-## Embedding providers
-
-Use `embeddingProviders` for reusable vector embedding providers. This contract
-is intentionally broader than memory: tools, search, retrieval, importers, or
-future feature plugins can consume embeddings without depending on the memory
-engine.
-
-Memory search can consume generic `embeddingProviders`. The older
-`memoryEmbeddingProviders` contract is deprecated compatibility while existing
-memory-specific providers migrate; new reusable embedding providers should use
-`embeddingProviders`.
-
-## Review checklist
-
-Before shipping a new capability, verify:
-
-- No channel/tool imports vendor code directly.
-- The runtime helper is the shared path.
-- At least one contract test asserts bundled ownership.
-- Config docs name the new model/config key.
-- Plugin docs explain the ownership boundary.
-
-If a PR skips the capability layer and hardcodes vendor behavior into a channel/tool, send it back and define the contract first.
-
-## Related
-
-- [Plugin internals](/plugins/architecture) — capability model, ownership, load pipeline, runtime helpers.
-- [Building plugins](/plugins/building-plugins) — first-plugin tutorial.
-- [SDK overview](/plugins/sdk-overview) — import map and registration API reference.
-- [Creating skills](/tools/creating-skills) — companion contributor surface.

package/docs/plugins/admin-http-rpc.md

@@ -1,216 +0,0 @@
----
-summary: "Expose selected Gateway control-plane methods through the bundled, opt-in admin-http-rpc plugin"
-read_when:
-  - Building host tooling that cannot use the Gateway WebSocket RPC client
-  - Exposing Gateway admin automation behind a private trusted ingress
-  - Auditing the security model for HTTP access to Gateway methods
-title: "Admin HTTP RPC plugin"
----
-
-The bundled `admin-http-rpc` plugin exposes selected Gateway control-plane methods over HTTP for trusted host automation that cannot use the normal Gateway WebSocket RPC client.
-
-The plugin is included with FengMing, but it is off by default. When disabled, the route is not registered. When enabled, it adds:
-
-- `POST /api/v1/admin/rpc`
-- same listener as the Gateway: `http://<gateway-host>:<port>/api/v1/admin/rpc`
-
-Enable it only for private host tooling, tailnet automation, or a trusted internal ingress. Do not expose this route directly to the public internet.
-
-## Before you enable it
-
-Admin HTTP RPC is a full operator control-plane surface. Any caller that passes Gateway HTTP auth can invoke the allowlisted methods on this page.
-
-Use it when all of these are true:
-
-- The caller is trusted to operate the Gateway.
-- The caller cannot use the WebSocket RPC client.
-- The route is reachable only on loopback, a tailnet, or a private authenticated ingress.
-- You have reviewed the allowed methods and they match the automation you plan to run.
-
-Use the WebSocket RPC path for FengMing clients and interactive tools that can keep a Gateway WebSocket connection open.
-
-## Enable
-
-Enable the bundled plugin:
-
-<Tabs>
-  <Tab title="CLI">
-    ```bash
-    fengming plugins enable admin-http-rpc
-    fengming gateway restart
-    ```
-  </Tab>
-  <Tab title="Config">
-    ```json5
-    {
-      plugins: {
-        entries: {
-          "admin-http-rpc": { enabled: true },
-        },
-      },
-    }
-    ```
-  </Tab>
-</Tabs>
-
-The route is registered during plugin startup. Restart the Gateway after changing plugin config.
-
-Disable it when you no longer need the HTTP surface:
-
-```bash
-fengming plugins disable admin-http-rpc
-fengming gateway restart
-```
-
-## Verify the route
-
-Use `health` as the smallest safe request:
-
-```bash
-curl -sS http://<gateway-host>:<port>/api/v1/admin/rpc \
-  -H 'Authorization: Bearer <gateway-token>' \
-  -H 'Content-Type: application/json' \
-  -d '{"method":"health","params":{}}'
-```
-
-A successful response has `ok: true`:
-
-```json
-{
-  "id": "generated-request-id",
-  "ok": true,
-  "payload": {
-    "status": "ok"
-  }
-}
-```
-
-When the plugin is disabled, the route returns `404` because it is not registered.
-
-## Authentication
-
-The plugin route uses Gateway HTTP auth.
-
-Common authentication paths:
-
-- shared-secret auth (`gateway.auth.mode="token"` or `"password"`): `Authorization: Bearer <token-or-password>`
-- trusted identity-bearing HTTP auth (`gateway.auth.mode="trusted-proxy"`): route through the configured identity-aware proxy and let it inject the required identity headers
-- private-ingress open auth (`gateway.auth.mode="none"`): no auth header required
-
-## Security model
-
-Treat this plugin as a full Gateway operator surface.
-
-- Enabling the plugin intentionally offers access to the allowlisted admin RPC methods at `/api/v1/admin/rpc`.
-- The plugin declares the reserved `contracts.gatewayMethodDispatch: ["authenticated-request"]` manifest contract so its Gateway-authenticated HTTP route can dispatch control-plane methods in process.
-- Shared-secret bearer auth proves possession of the gateway operator secret.
-- For `token` and `password` auth, narrower `x-fengming-scopes` headers are ignored and the normal full operator defaults are restored.
-- Trusted identity-bearing HTTP modes honor `x-fengming-scopes` when present.
-- `gateway.auth.mode="none"` means this route is unauthenticated if the plugin is enabled. Use that only behind a private ingress you fully trust.
-- Requests dispatch through the same Gateway method handlers and scope checks as WebSocket RPC after the plugin route auth passes.
-- Keep this route on loopback, tailnet, or a private trusted ingress. Do not expose it directly to the public internet.
-- Plugin manifest contracts are not a sandbox. They prevent accidental use of reserved SDK helpers; trusted plugins still run in the Gateway process.
-
-Use separate gateways when callers cross trust boundaries.
-
-## Request
-
-```http
-POST /api/v1/admin/rpc
-Authorization: Bearer <gateway-token>
-Content-Type: application/json
-```
-
-```json
-{
-  "id": "optional-request-id",
-  "method": "health",
-  "params": {}
-}
-```
-
-Fields:
-
-- `id` (string, optional): copied into the response. A UUID is generated when omitted.
-- `method` (string, required): allowed Gateway method name.
-- `params` (any, optional): method-specific params.
-
-The default max request body size is 1 MB.
-
-## Response
-
-Success responses use the Gateway RPC shape:
-
-```json
-{
-  "id": "optional-request-id",
-  "ok": true,
-  "payload": {}
-}
-```
-
-Gateway method errors use:
-
-```json
-{
-  "id": "optional-request-id",
-  "ok": false,
-  "error": {
-    "code": "INVALID_REQUEST",
-    "message": "bad params"
-  }
-}
-```
-
-HTTP status follows the Gateway error when possible. For example, `INVALID_REQUEST` returns `400`, and `UNAVAILABLE` returns `503`.
-
-## Allowed methods
-
-- discovery: `commands.list`
-  Returns the HTTP RPC method names allowed by this plugin.
-- gateway: `health`, `status`, `logs.tail`, `usage.status`, `usage.cost`, `gateway.restart.request`
-- config: `config.get`, `config.schema`, `config.schema.lookup`, `config.set`, `config.patch`, `config.apply`
-- channels: `channels.status`, `channels.start`, `channels.stop`, `channels.logout`
-- web: `web.login.start`, `web.login.wait`
-- models: `models.list`, `models.authStatus`
-- agents: `agents.list`, `agents.create`, `agents.update`, `agents.delete`
-- approvals: `exec.approvals.get`, `exec.approvals.set`, `exec.approvals.node.get`, `exec.approvals.node.set`
-- cron: `cron.status`, `cron.list`, `cron.get`, `cron.runs`, `cron.add`, `cron.update`, `cron.remove`, `cron.run`
-- devices: `device.pair.list`, `device.pair.approve`, `device.pair.reject`, `device.pair.remove`
-- nodes: `node.list`, `node.describe`, `node.pair.list`, `node.pair.approve`, `node.pair.reject`, `node.pair.remove`, `node.rename`
-- tasks: `tasks.list`, `tasks.get`, `tasks.cancel`
-- diagnostics: `doctor.memory.status`, `update.status`
-
-Other Gateway methods are blocked until they are intentionally added.
-
-## WebSocket comparison
-
-The normal Gateway WebSocket RPC path remains the preferred control-plane API for FengMing clients. Use admin HTTP RPC only for host tooling that needs a request/response HTTP surface.
-
-Shared-token WebSocket clients without a trusted device identity cannot self-declare admin scopes during connect. Admin HTTP RPC deliberately follows the existing trusted HTTP operator model: when the plugin is enabled, shared-secret bearer auth is treated as full operator access for this admin surface.
-
-## Troubleshooting
-
-`404 Not Found`
-
-: The plugin is disabled, the Gateway has not restarted since enabling it, or the request is going to a different Gateway process.
-
-`401 Unauthorized`
-
-: The request did not satisfy Gateway HTTP auth. Check the bearer token or the trusted-proxy identity headers.
-
-`400 INVALID_REQUEST`
-
-: The request body is not valid JSON, the `method` field is missing, or the method is not in the plugin allowlist.
-
-`503 UNAVAILABLE`
-
-: The Gateway method handler is unavailable. Check Gateway logs and retry after the Gateway finishes startup.
-
-## Related
-
-- [Operator scopes](/gateway/operator-scopes)
-- [Gateway security](/gateway/security)
-- [Remote access](/gateway/remote)
-- [Plugin manifest](/plugins/manifest#contracts)
-- [SDK subpaths](/plugins/sdk-subpaths)

package/docs/plugins/agent-tools.md

@@ -1,13 +0,0 @@
----
-summary: "Redirects to Building Plugins (registering tools section)"
-read_when:
-  - Legacy link to agent-tools
-title: "Registering tools"
----
-
-This page has moved. See [Building Plugins: Registering agent tools](/plugins/building-plugins#registering-agent-tools).
-
-## Related
-
-- [Building plugins](/plugins/building-plugins)
-- [Plugin SDK setup](/plugins/sdk-setup)