fengming 0.3.9 → 0.3.11

package/docs/plugins/webhooks.md

@@ -1,192 +0,0 @@
----
-summary: "Webhooks plugin: authenticated TaskFlow ingress for trusted external automation"
-read_when:
-  - You want to trigger or drive TaskFlows from an external system
-  - You are configuring the bundled webhooks plugin
-title: "Webhooks plugin"
----
-
-The Webhooks plugin adds authenticated HTTP routes that bind external
-automation to FengMing TaskFlows.
-
-Use it when you want a trusted system such as Zapier, n8n, a CI job, or an
-internal service to create and drive managed TaskFlows without writing a custom
-plugin first.
-
-## Where it runs
-
-The Webhooks plugin runs inside the Gateway process.
-
-If your Gateway runs on another machine, install and configure the plugin on
-that Gateway host, then restart the Gateway.
-
-## Configure routes
-
-Set config under `plugins.entries.webhooks.config`:
-
-```json5
-{
-  plugins: {
-    entries: {
-      webhooks: {
-        enabled: true,
-        config: {
-          routes: {
-            zapier: {
-              path: "/plugins/webhooks/zapier",
-              sessionKey: "agent:main:main",
-              secret: {
-                source: "env",
-                provider: "default",
-                id: "FENGMING_WEBHOOK_SECRET",
-              },
-              controllerId: "webhooks/zapier",
-              description: "Zapier TaskFlow bridge",
-            },
-          },
-        },
-      },
-    },
-  },
-}
-```
-
-Route fields:
-
-- `enabled`: optional, defaults to `true`
-- `path`: optional, defaults to `/plugins/webhooks/<routeId>`
-- `sessionKey`: required session that owns the bound TaskFlows
-- `secret`: required shared secret or SecretRef
-- `controllerId`: optional controller id for created managed flows
-- `description`: optional operator note
-
-Supported `secret` inputs:
-
-- Plain string
-- SecretRef with `source: "env" | "file" | "exec"`
-
-If a secret-backed route cannot resolve its secret at startup, the plugin skips
-that route and logs a warning instead of exposing a broken endpoint.
-
-## Security model
-
-Each route is trusted to act with the TaskFlow authority of its configured
-`sessionKey`.
-
-This means the route can inspect and mutate TaskFlows owned by that session, so
-you should:
-
-- Use a strong unique secret per route
-- Prefer secret references over inline plaintext secrets
-- Bind routes to the narrowest session that fits the workflow
-- Expose only the specific webhook path you need
-
-The plugin applies:
-
-- Shared-secret authentication
-- Request body size and timeout guards
-- Fixed-window rate limiting
-- In-flight request limiting
-- Owner-bound TaskFlow access through `api.runtime.tasks.managedFlows.bindSession(...)`
-
-## Request format
-
-Send `POST` requests with:
-
-- `Content-Type: application/json`
-- `Authorization: Bearer <secret>` or `x-fengming-webhook-secret: <secret>`
-
-Example:
-
-```bash
-curl -X POST https://gateway.example.com/plugins/webhooks/zapier \
-  -H 'Content-Type: application/json' \
-  -H 'Authorization: Bearer YOUR_SHARED_SECRET' \
-  -d '{"action":"create_flow","goal":"Review inbound queue"}'
-```
-
-## Supported actions
-
-The plugin currently accepts these JSON `action` values:
-
-- `create_flow`
-- `get_flow`
-- `list_flows`
-- `find_latest_flow`
-- `resolve_flow`
-- `get_task_summary`
-- `set_waiting`
-- `resume_flow`
-- `finish_flow`
-- `fail_flow`
-- `request_cancel`
-- `cancel_flow`
-- `run_task`
-
-### `create_flow`
-
-Creates a managed TaskFlow for the route's bound session.
-
-Example:
-
-```json
-{
-  "action": "create_flow",
-  "goal": "Review inbound queue",
-  "status": "queued",
-  "notifyPolicy": "done_only"
-}
-```
-
-### `run_task`
-
-Creates a managed child task inside an existing managed TaskFlow.
-
-Allowed runtimes are:
-
-- `subagent`
-- `acp`
-
-Example:
-
-```json
-{
-  "action": "run_task",
-  "flowId": "flow_123",
-  "runtime": "acp",
-  "childSessionKey": "agent:main:acp:worker",
-  "task": "Inspect the next message batch"
-}
-```
-
-## Response shape
-
-Successful responses return:
-
-```json
-{
-  "ok": true,
-  "routeId": "zapier",
-  "result": {}
-}
-```
-
-Rejected requests return:
-
-```json
-{
-  "ok": false,
-  "routeId": "zapier",
-  "code": "not_found",
-  "error": "TaskFlow not found.",
-  "result": {}
-}
-```
-
-The plugin intentionally scrubs owner/session metadata from webhook responses.
-
-## Related docs
-
-- [Plugin runtime SDK](/plugins/sdk-runtime)
-- [Hooks and webhooks overview](/automation/hooks)
-- [CLI webhooks](/cli/webhooks)

package/docs/plugins/workboard.md

@@ -1,252 +0,0 @@
----
-summary: "Optional dashboard workboard for agent-owned cards and session handoff"
-read_when:
-  - You want a Kanban-style workboard in the Control UI
-  - You are enabling or disabling the bundled Workboard plugin
-  - You want to track planned agent work without an external project manager
-title: "Workboard plugin"
----
-
-The Workboard plugin adds an optional Kanban-style board to the
-[Control UI](/web/control-ui). Use it to collect agent-sized work cards, assign
-them to agents, and jump from a card into the linked dashboard session.
-
-Workboard is intentionally small. It tracks local operating work for an
-FengMing Gateway; it is not a replacement for GitHub Issues, Linear, Jira, or
-other team project management systems.
-
-## Default state
-
-Workboard is a bundled plugin and is disabled by default unless you enable it
-in plugin config.
-
-Enable it with:
-
-```bash
-fengming plugins enable workboard
-fengming gateway restart
-```
-
-Then open the dashboard:
-
-```bash
-fengming dashboard
-```
-
-The Workboard tab appears in the dashboard navigation. If the tab is visible
-but the plugin is disabled or blocked by `plugins.allow` / `plugins.deny`, the
-view shows a plugin-unavailable state instead of local card data.
-
-## What cards contain
-
-Each card stores:
-
-- title and notes
-- status: `triage`, `backlog`, `todo`, `scheduled`, `ready`, `running`,
-  `review`, `blocked`, or `done`
-- priority: `low`, `normal`, `high`, or `urgent`
-- labels
-- optional agent id
-- optional linked session, run, task, or source URL
-- optional execution metadata for a Codex or Claude session started from the card
-- compact metadata for attempts, comments, links, proof, artifacts, automation,
-  claims, diagnostics, notifications, templates, archive state, and
-  stale-session detection
-- recent card events such as created, moved, linked, claimed, heartbeat,
-  attempt, proof, artifact, diagnostic, notification, dispatch, archive, stale,
-  or agent-updated changes
-
-Cards are stored in the plugin's Gateway state. They are local to the Gateway
-state directory and move with the rest of that Gateway's FengMing state.
-
-Workboard keeps compact per-card metadata so operators can see how a card moved
-through the board without opening the linked session. Events, attempt summaries,
-proof snippets, related links, comments, archive markers, and stale-session
-markers are intentionally local metadata; they do not replace session
-transcripts or GitHub issue history.
-
-## Card executions
-
-Unlinked cards can start work from the card. Start uses the Gateway's configured
-default agent and model. Codex and Claude actions are optional explicit model
-choices:
-
-- Run Codex or Run Claude creates a dashboard session, sends the card prompt,
-  and marks the card `running`.
-- Open Codex or Open Claude creates a linked dashboard session without sending
-  the card prompt or moving the card, so you can work manually while it stays
-  attached to the board.
-
-Execution metadata stores the selected engine, mode, model ref, session key,
-run id, and lifecycle status on the card. Codex executions use
-`openai/gpt-5.5`; Claude executions use `anthropic/claude-sonnet-4-6`.
-
-Each linked execution also records an attempt summary on the same card record.
-The attempt summary keeps the engine, mode, model, run id, timestamps, status,
-and rolling failure count so repeated failures remain visible on the board.
-
-## Agent coordination
-
-Workboard also exposes optional agent tools for board-aware workflows:
-
-- `workboard_list` lists compact cards with claim and diagnostic state, with an
-  optional board filter.
-- `workboard_read` returns one card plus bounded worker context built from notes,
-  attempts, comments, links, proof, artifacts, parent results, recent assignee
-  work, and active diagnostics.
-- `workboard_create` creates a card with optional parents, tenant, skills,
-  board, workspace metadata, idempotency key, runtime limit, and retry budget.
-- `workboard_link` links a parent card to a child card. Children stay in `todo`
-  until every parent reaches `done`; then dispatch promotion moves them to
-  `ready`.
-- `workboard_claim` claims a card for the calling agent and moves backlog, todo,
-  or ready cards into `running`.
-- `workboard_heartbeat` refreshes the claim heartbeat during longer runs.
-- `workboard_release` releases the claim after completion, pause, or handoff and
-  can move the card to a next status.
-- `workboard_complete` and `workboard_block` are structured lifecycle tools for
-  final summaries, proof, artifacts, created-card manifests, and blocker
-  reasons. Created-card manifests must reference cards linked back to the
-  completed card, which keeps phantom children out of summaries.
-- `workboard_boards`, `workboard_stats`, `workboard_promote`,
-  `workboard_reassign`, `workboard_reclaim`, `workboard_comment`,
-  `workboard_proof`, `workboard_unblock`, and `workboard_dispatch` let an agent
-  inspect board namespaces, view queue stats, recover stuck work, add handoff
-  notes, attach proof or artifact references, move blocked work back to `todo`,
-  and nudge dependency promotion or stale-claim cleanup.
-
-Claimed cards reject agent-tool mutations from other agents unless the caller
-has the claim token returned by `workboard_claim`. Dashboard operators still use
-the normal Gateway RPC surface and can recover or reassign cards.
-
-Workboard diagnostics are computed from local card metadata. The built-in checks
-flag assigned cards that wait too long, running cards without recent heartbeat,
-blocked cards that need attention, repeated failures, done cards without proof,
-and running cards that only have a loose session link.
-
-Dispatch is intentionally Gateway-local. It does not spawn arbitrary operating
-system processes; normal FengMing sessions still own execution. A dispatch nudge
-promotes dependency-ready cards, records dispatch metadata on ready cards, and
-blocks expired claims or timed-out runs so operators can recover them from the
-board.
-
-## Session lifecycle sync
-
-Cards can be linked to existing dashboard sessions or to the session created
-when you start work from a card. Linked cards show the session lifecycle inline:
-running, stale, linked idle, done, failed, or missing.
-
-If the linked session is missing, the card stays linked for context and still
-offers start controls so you can restart work into a fresh dashboard session.
-If an active linked session stops reporting recent activity, Workboard marks the
-card stale and stores the marker as card metadata until the lifecycle clears it.
-
-You can also capture an existing dashboard session from the Sessions tab with
-Add to Workboard. The card is linked to that session, uses the session label or
-recent user prompt as the title, and seeds notes from the recent user prompt plus
-the latest assistant response when chat history is available.
-
-Workboard follows the linked session while the card is still in an active work
-state:
-
-- active linked session -> `running`
-- completed linked session -> `review`
-- failed, killed, timed out, or aborted linked session -> `blocked`
-
-Manual review states win. If you move a card to `review`, `blocked`, or `done`,
-Workboard stops auto-moving that card until you move it back to `todo` or
-`running`.
-
-## Dashboard workflow
-
-1. Open the Workboard tab in the Control UI.
-2. Create a card with a title, notes, priority, labels, optional agent, and
-   optional linked session.
-3. Or open Sessions and choose Add to Workboard for an existing session.
-4. Drag the card between columns or use the column controls.
-5. Start work from the card to create or reuse a dashboard session.
-6. Open the linked session from the card while the agent works.
-7. Let lifecycle sync move running work into review or blocked, then manually
-   move the card to done when accepted.
-
-Starting a card uses normal Gateway sessions. The Workboard plugin only stores
-card metadata and links; the conversation transcript, model selection, and run
-lifecycle stay owned by the regular session system.
-
-Use Stop on a live linked card to abort the active session run. Workboard marks
-that card `blocked` so it remains visible for follow-up.
-
-New cards can start from Workboard templates for bugfixes, docs, releases, PR
-reviews, or plugin work. Templates prefill title, notes, labels, and priority,
-and the selected template id is stored as card metadata.
-
-## Permissions
-
-The plugin registers Gateway RPC methods under the `workboard.*` namespace:
-
-- `workboard.cards.list` requires `operator.read`
-- `workboard.cards.export` requires `operator.read`
-- `workboard.cards.diagnostics` requires `operator.read`
-- `workboard.cards.diagnostics.refresh` requires `operator.write`
-- create, update, move, delete, comment, link, dependency link, proof, artifact,
-  claim, heartbeat, release, complete, block, unblock, dispatch, bulk, and
-  archive methods require `operator.write`
-
-Browsers connected with read-only operator access can inspect the board but
-cannot mutate cards.
-
-## Configuration
-
-Workboard has no plugin-specific config today. Enable or disable it with the
-standard plugin entry:
-
-```json5
-{
-  plugins: {
-    entries: {
-      workboard: {
-        enabled: true,
-        config: {},
-      },
-    },
-  },
-}
-```
-
-Disable it again with:
-
-```bash
-fengming plugins disable workboard
-fengming gateway restart
-```
-
-## Troubleshooting
-
-### The tab says Workboard is unavailable
-
-Check plugin policy:
-
-```bash
-fengming plugins inspect workboard --runtime --json
-```
-
-If `plugins.allow` is configured, add `workboard` to that allowlist. If
-`plugins.deny` contains `workboard`, remove it before enabling the plugin.
-
-### Cards do not save
-
-Confirm the browser connection has `operator.write` access. Read-only operator
-sessions can list cards but cannot create, edit, move, or delete them.
-
-### Starting a card does not open the expected session
-
-Workboard creates links to normal dashboard sessions. Check the card's agent id
-and linked session, then open the Sessions or Chat view to inspect the actual
-run state.
-
-## Related
-
-- [Control UI](/web/control-ui)
-- [Plugins](/tools/plugin)
-- [Manage plugins](/plugins/manage-plugins)
-- [Sessions](/concepts/session)

package/docs/plugins/zalouser.md

@@ -1,86 +0,0 @@
----
-summary: "Zalo Personal plugin: QR login + messaging via native zca-js (plugin install + channel config + tool)"
-read_when:
-  - You want Zalo Personal (unofficial) support in FengMing
-  - You are configuring or developing the zalouser plugin
-title: "Zalo personal plugin"
----
-
-Zalo Personal support for FengMing via a plugin, using native `zca-js` to automate a normal Zalo user account.
-
-<Warning>
-Unofficial automation may lead to account suspension or ban. Use at your own risk.
-</Warning>
-
-## Naming
-
-Channel id is `zalouser` to make it explicit this automates a **personal Zalo user account** (unofficial). We keep `zalo` reserved for a potential future official Zalo API integration.
-
-## Where it runs
-
-This plugin runs **inside the Gateway process**.
-
-If you use a remote Gateway, install/configure it on the **machine running the Gateway**, then restart the Gateway.
-
-No external `zca`/`openzca` CLI binary is required.
-
-## Install
-
-### Option A: install from npm
-
-```bash
-fengming plugins install @fengming/zalouser
-```
-
-Use the bare package to follow the current official release tag. Pin an exact
-version only when you need a reproducible install.
-
-Restart the Gateway afterwards.
-
-### Option B: install from a local folder (dev)
-
-```bash
-PLUGIN_SRC=./path/to/local/zalouser-plugin
-fengming plugins install "$PLUGIN_SRC"
-cd "$PLUGIN_SRC" && pnpm install
-```
-
-Restart the Gateway afterwards.
-
-## Config
-
-Channel config lives under `channels.zalouser` (not `plugins.entries.*`):
-
-```json5
-{
-  channels: {
-    zalouser: {
-      enabled: true,
-      dmPolicy: "pairing",
-    },
-  },
-}
-```
-
-## CLI
-
-```bash
-fengming channels login --channel zalouser
-fengming channels logout --channel zalouser
-fengming channels status --probe
-fengming message send --channel zalouser --target <threadId> --message "Hello from FengMing"
-fengming directory peers list --channel zalouser --query "name"
-```
-
-## Agent tool
-
-Tool name: `zalouser`
-
-Actions: `send`, `image`, `link`, `friends`, `groups`, `me`, `status`
-
-Channel message actions also support `react` for message reactions.
-
-## Related
-
-- [Building plugins](/plugins/building-plugins)
-- [ClawHub](/clawhub)

package/docs/prose.md

@@ -1,137 +0,0 @@
----
-summary: "OpenProse: .prose workflows, slash commands, and state in FengMing"
-read_when:
-  - You want to run or write .prose workflows
-  - You want to enable the OpenProse plugin
-  - You need to understand state storage
-title: "OpenProse"
----
-
-OpenProse is a portable, markdown-first workflow format for orchestrating AI sessions. In FengMing it ships as a plugin that installs an OpenProse skill pack plus a `/prose` slash command. Programs live in `.prose` files and can spawn multiple sub-agents with explicit control flow.
-
-Official site: [https://www.prose.md](https://www.prose.md)
-
-## What it can do
-
-- Multi-agent research + synthesis with explicit parallelism.
-- Repeatable approval-safe workflows (code review, incident triage, content pipelines).
-- Reusable `.prose` programs you can run across supported agent runtimes.
-
-## Install + enable
-
-Bundled plugins are disabled by default. Enable OpenProse:
-
-```bash
-fengming plugins enable open-prose
-```
-
-Restart the Gateway after enabling the plugin.
-
-Dev/local checkout: `fengming plugins install ./path/to/local/open-prose-plugin`
-
-Related docs: [Plugins](/tools/plugin), [Plugin manifest](/plugins/manifest), [Skills](/tools/skills).
-
-## Slash command
-
-OpenProse registers `/prose` as a user-invocable skill command. It routes to the OpenProse VM instructions and uses FengMing tools under the hood.
-
-Common commands:
-
-```
-/prose help
-/prose run <file.prose>
-/prose run <handle/slug>
-/prose run <https://example.com/file.prose>
-/prose compile <file.prose>
-/prose examples
-/prose update
-```
-
-## Example: a simple `.prose` file
-
-```prose
-# Research + synthesis with two agents running in parallel.
-
-input topic: "What should we research?"
-
-agent researcher:
-  model: sonnet
-  prompt: "You research thoroughly and cite sources."
-
-agent writer:
-  model: opus
-  prompt: "You write a concise summary."
-
-parallel:
-  findings = session: researcher
-    prompt: "Research {topic}."
-  draft = session: writer
-    prompt: "Summarize {topic}."
-
-session "Merge the findings + draft into a final answer."
-context: { findings, draft }
-```
-
-## File locations
-
-OpenProse keeps state under `.prose/` in your workspace:
-
-```
-.prose/
-├── .env
-├── runs/
-│   └── {YYYYMMDD}-{HHMMSS}-{random}/
-│       ├── program.prose
-│       ├── state.md
-│       ├── bindings/
-│       └── agents/
-└── agents/
-```
-
-User-level persistent agents live at:
-
-```
-~/.prose/agents/
-```
-
-## State modes
-
-OpenProse supports multiple state backends:
-
-- **filesystem** (default): `.prose/runs/...`
-- **in-context**: transient, for small programs
-- **sqlite** (experimental): requires `sqlite3` binary
-- **postgres** (experimental): requires `psql` and a connection string
-
-Notes:
-
-- sqlite/postgres are opt-in and experimental.
-- postgres credentials flow into subagent logs; use a dedicated, least-privileged DB.
-
-## Remote programs
-
-`/prose run <handle/slug>` resolves to `https://p.prose.md/<handle>/<slug>`.
-Direct URLs are fetched as-is. This uses the `web_fetch` tool (or `exec` for POST).
-
-## FengMing runtime mapping
-
-OpenProse programs map to FengMing primitives:
-
-| OpenProse concept         | FengMing tool    |
-| ------------------------- | ---------------- |
-| Spawn session / Task tool | `sessions_spawn` |
-| File read/write           | `read` / `write` |
-| Web fetch                 | `web_fetch`      |
-
-If your tool allowlist blocks these tools, OpenProse programs will fail. See [Skills config](/tools/skills-config).
-
-## Security + approvals
-
-Treat `.prose` files like code. Review before running. Use FengMing tool allowlists and approval gates to control side effects.
-
-For deterministic, approval-gated workflows, compare with [Lobster](/tools/lobster).
-
-## Related
-
-- [Text-to-speech](/tools/tts)
-- [Markdown formatting](/concepts/markdown-formatting)