fengming 0.3.9 → 0.3.11

package/docs/specs/claw-supervisor.md

@@ -1,247 +0,0 @@
----
-title: Claw Supervisor
-description: Fleet supervision plan for Codex app-server sessions controlled by FengMing.
-readWhen:
-  - Designing Codex fleet supervision
-  - Building FengMing tools that read, steer, or spawn Codex sessions
-  - Choosing between local, Cloudflare, and VPS deployment for supervised Codex
----
-
-# Claw Supervisor
-
-## Goal
-
-Claw Supervisor lets one always-on FengMing instance monitor and drive a fleet of Codex sessions without changing the normal Codex user experience. A user can SSH into a host, start Codex, work in the TUI, and still have the supervisor read the session, steer it, interrupt it, spawn related sessions, and accept handoffs. Codex sessions can also call back into FengMing through MCP.
-
-## Product Model
-
-Codex remains the primary work surface. FengMing supervises Codex rather than hiding Codex inside an opaque FengMing subagent.
-
-The FengMing plugin is named `codex-supervisor`. `crabfleet` remains the deployment
-and host-fleet profile for CRAB machines rather than the reusable plugin name.
-
-The model has three roles:
-
-- Human-attached Codex: a normal interactive Codex TUI launched through a shared app-server.
-- Autonomous Codex: a Codex app-server thread spawned by the supervisor that a human can later attach to.
-- Supervisor Claw: an always-on FengMing agent with tools for fleet state, transcript reads, steering, interruption, spawning, and handoff.
-
-FengMing may use its existing subagent machinery internally, but the external contract is an attachable Codex session with a Codex thread id.
-
-## Architecture
-
-```text
-user SSH session
-  -> codex --remote unix://... or ws://...
-      -> local codex app-server daemon
-          <-> host sidecar / supervisor connector
-              <-> FengMing fleet supervisor
-                  <-> supervisor MCP exposed back to Codex
-```
-
-Each Codex-capable host runs:
-
-- Codex app-server daemon.
-- A launcher that always starts interactive Codex with `--remote`.
-- A connector that registers app-server endpoints and live threads with the supervisor.
-
-The supervisor runs:
-
-- Endpoint registry.
-- Session registry.
-- Codex app-server JSON-RPC client pool.
-- MCP server for Codex-to-Claw calls.
-- FengMing tools for Claw-to-Codex control.
-- Policy engine for autonomous actions, approvals, and loop prevention.
-
-## Codex App-Server Contract
-
-Use Codex app-server APIs as the canonical control plane:
-
-- `initialize`, `initialized`
-- `thread/loaded/list`
-- `thread/list`
-- `thread/read`
-- `thread/resume`
-- `thread/start`
-- `turn/start`
-- `turn/steer`
-- `turn/interrupt`
-- `model/list`
-
-Interactive Codex must be launched with `codex --remote <endpoint>` so the TUI and supervisor connect to the same app-server. Standalone `codex exec` is not a live-shared session today; use app-server APIs for autonomous work until Codex supports `exec --remote`.
-
-## Session Registry
-
-Supervisor stores one record per observed Codex thread:
-
-```json
-{
-  "sessionId": "codex-thread-id",
-  "endpointId": "host-a",
-  "host": "host-a.example",
-  "workspace": "/workspace/repo",
-  "repo": "owner/repo",
-  "branch": "feature/example",
-  "source": "vscode",
-  "status": "idle",
-  "humanAttached": true,
-  "lastSeenAt": "2026-05-28T10:00:00.000Z",
-  "summary": "Short working-state summary"
-}
-```
-
-The local implementation can derive most fields from Codex thread metadata. Fleet deployment should enrich records with host identity, user attachment state, git state, and sidecar health.
-
-## MCP Surface For Codex
-
-Every supervised Codex gets an MCP server named `fengming-codex-supervisor`.
-
-Tools:
-
-- `codex_sessions_list`: list visible Codex sessions.
-- `codex_session_read`: read one transcript.
-- `codex_session_send`: send a message to an idle thread or steer an active thread.
-- `codex_session_interrupt`: interrupt the active turn.
-- `codex_endpoint_probe`: verify endpoint connectivity.
-- `claw_report_progress`: publish current task state to the supervisor.
-- `claw_ask`: ask the supervisor for help or delegation.
-- `codex_spawn`: create a new autonomous Codex session.
-- `codex_handoff`: request human or peer takeover.
-
-Resources:
-
-- `codex://sessions`
-- `codex://sessions/{sessionId}`
-- `codex://sessions/{sessionId}/transcript`
-
-## Claw Control Surface
-
-The always-on Claw gets the same primitives as internal tools:
-
-- list sessions and endpoints
-- read transcripts
-- send/steer text
-- interrupt active work
-- spawn new sessions
-- summarize and assign sessions
-- broadcast instructions to a filtered group
-- mark sessions blocked, done, or abandoned
-
-Tool behavior:
-
-- If a target thread is idle, `codex_session_send` maps to `turn/start`.
-- If a target thread is active and an in-progress turn id is visible, it maps to `turn/steer`.
-- If the active turn cannot be identified, the tool fails closed instead of creating an unrelated turn.
-- Codex-exposed MCP write controls stay disabled unless a trusted supervisor-only policy enables them.
-- Raw transcript reads stay disabled unless a trusted supervisor-only policy enables them.
-- Autonomous approval defaults deny tool/file approvals unless an explicit policy says otherwise.
-
-## Launch Flow
-
-Interactive host login:
-
-1. User SSHes into a CRAB host.
-2. SSH service starts or verifies `codex app-server daemon start`.
-3. Login wrapper launches `codex --remote unix:// --cd <workspace>`.
-4. Host connector registers endpoint and loaded thread.
-5. Supervisor emits a high-priority fleet event: new Codex session, workspace, human-attached state, current task preview.
-6. Supervisor Claw can read and steer immediately.
-
-Autonomous spawn:
-
-1. Supervisor selects host and workspace.
-2. Host connector opens or resumes a Codex app-server thread.
-3. Supervisor starts the first turn with task text and MCP config.
-4. Session registry marks it autonomous and attachable.
-5. Human can later attach with `codex --remote <endpoint> resume <threadId>` once Codex supports that exact UX, or via current resume flow on the same app-server.
-
-## Deployment
-
-Preferred control plane:
-
-- Host connectors keep outbound WebSocket connections to the supervisor.
-- Supervisor state lives in FengMing Gateway storage.
-- Codex app-server remains local to each host; never expose a raw unauthenticated app-server to the public internet.
-
-Cloudflare viability:
-
-- Good for registry, durable objects, WebSocket fan-in, lightweight event routing, and public MCP/gateway endpoints.
-- Not enough by itself for direct private host control because Workers cannot dial arbitrary private Unix sockets or local loopback app-servers.
-- Use Cloudflare when every host connector phones home over outbound WebSocket.
-
-VPS fallback:
-
-- Use a Hetzner service when long-lived process control, SSH tunnels, private network routing, or local filesystem access is needed.
-- Keep the same protocol: host connectors outbound, supervisor registry central, Codex app-server local.
-
-## Security
-
-- Default bind is local Unix socket.
-- Remote app-server uses token or signed bearer auth.
-- Host connector authenticates to supervisor with a scoped host token.
-- Supervisor tools enforce per-session policy: read, steer, interrupt, spawn, approval.
-- Cross-agent messages include `originSessionId`; self-echo is dropped.
-- Broadcast requires an explicit filter and bounded target count.
-- Transcript reads redact secrets at FengMing boundary.
-- Approval requests default to deny for supervisor-originated turns unless policy allows them.
-
-## Implementation Plan
-
-Phase 1: Local supervisor MVP
-
-- Add Codex app-server JSON-RPC client for stdio proxy and WebSocket endpoints.
-- Add supervisor endpoint/session registry.
-- Add MCP tools: list, read, send, interrupt, probe.
-- Add local env config for endpoints.
-- Add fake app-server tests and one live local app-server smoke.
-
-Phase 2: FengMing integration
-
-- Register supervisor tools in the `codex-supervisor` plugin.
-- Inject supervisor MCP into Codex thread config.
-- Add session summaries to agent context.
-- Add event notifications when new Codex threads appear.
-- Add policy config for autonomous send/interrupt/spawn.
-
-Phase 3: Fleet connector
-
-- Host sidecar registers app-server endpoint, host metadata, git/workspace metadata, and human attachment state.
-- Add outbound WebSocket connector for Cloudflare or VPS control plane.
-- Add reconnect, heartbeat, and stale-session cleanup.
-- Add CRAB SSH launcher wrapper.
-
-Phase 4: Autonomous operation
-
-- Add spawn/resume/takeover flows.
-- Add broadcast and delegation.
-- Add progress reports and task-state summaries.
-- Add loop prevention and rate limits.
-- Add dashboard views.
-
-Phase 5: Multi-Claw
-
-- Shard sessions by group.
-- Add leadership/lease for each session.
-- Add audit log and replay.
-- Add escalation between Claw groups.
-
-## Acceptance Tests
-
-- A human launches Codex TUI through a shared app-server.
-- Supervisor lists the live thread via `thread/loaded/list`.
-- Supervisor reads transcript via `thread/read`.
-- Supervisor sends text to an idle thread via `turn/start`.
-- Supervisor steers an active thread via `turn/steer`.
-- Supervisor interrupt stops an active turn via `turn/interrupt`.
-- Codex calls supervisor MCP and lists peer sessions.
-- An autonomous Codex is spawned and later human-attached.
-- Lost host connector marks sessions stale without deleting history.
-
-## Open Questions
-
-- Exact Codex TUI attach UX for an app-server thread spawned without a TUI.
-- Whether Codex should add `exec --remote` for headless live-shared runs.
-- Durable state owner: FengMing Gateway DB, Cloudflare Durable Object, or VPS database.
-- Approval policy granularity for supervisor-originated turns.
-- How much transcript summary should be injected into the always-on Claw context versus kept as a tool/resource.

package/docs/start/bootstrapping.md

@@ -1,49 +0,0 @@
----
-summary: "Agent bootstrapping ritual that seeds the workspace and identity files"
-read_when:
-  - Understanding what happens on the first agent run
-  - Explaining where bootstrapping files live
-  - Debugging onboarding identity setup
-title: "Agent bootstrapping"
-sidebarTitle: "Bootstrapping"
----
-
-Bootstrapping is the **first-run** ritual that prepares an agent workspace and
-collects identity details. It happens after onboarding, when the agent starts
-for the first time.
-
-## What bootstrapping does
-
-On the first agent run, FengMing bootstraps the workspace (default
-`~/.fengming/workspace`):
-
-- Seeds `AGENTS.md`, `BOOTSTRAP.md`, `IDENTITY.md`, `USER.md`.
-- Runs a short Q&A ritual (one question at a time).
-- Writes identity + preferences to `IDENTITY.md`, `USER.md`, `SOUL.md`.
-- Removes `BOOTSTRAP.md` when finished so it only runs once.
-
-For embedded/local model runs, FengMing keeps `BOOTSTRAP.md` out of the
-privileged system context. On the primary interactive first run, it still passes
-the file contents in the user prompt so models that do not reliably call the
-`read` tool can complete the ritual. If the current run cannot safely access the
-workspace, the agent gets a limited bootstrap note instead of a generic greeting.
-
-## Skipping bootstrapping
-
-To skip this for a pre-seeded workspace, run `fengming onboard --skip-bootstrap`.
-
-## Where it runs
-
-Bootstrapping always runs on the **gateway host**. If the macOS app connects to
-a remote Gateway, the workspace and bootstrapping files live on that remote
-machine.
-
-<Note>
-When the Gateway runs on another machine, edit workspace files on the gateway
-host (for example, `user@gateway-host:~/.fengming/workspace`).
-</Note>
-
-## Related docs
-
-- macOS app onboarding: [Onboarding](/start/onboarding)
-- Workspace layout: [Agent workspace](/concepts/agent-workspace)

package/docs/start/docs-directory.md

@@ -1,69 +0,0 @@
----
-summary: "Curated links to the most used FengMing docs."
-read_when:
-  - You want quick access to key docs pages
-title: "Docs directory"
----
-
-<Note>
-This page is a curated index. If you are new, start with [Getting Started](/start/getting-started).
-For a complete map of the docs, see [Docs hubs](/start/hubs).
-</Note>
-
-## Start here
-
-- [Docs hubs (all pages linked)](/start/hubs)
-- [Help](/help)
-- [Configuration](/gateway/configuration)
-- [Configuration examples](/gateway/configuration-examples)
-- [Slash commands](/tools/slash-commands)
-- [Multi-agent routing](/concepts/multi-agent)
-- [Updating and rollback](/install/updating)
-- [Pairing (DM and nodes)](/channels/pairing)
-- [Nix mode](/install/nix)
-- [FengMing assistant setup](/start/fengming)
-- [Skills](/tools/skills)
-- [Skills config](/tools/skills-config)
-- [Workspace templates](/reference/templates/AGENTS)
-- [RPC adapters](/reference/rpc)
-- [Gateway runbook](/gateway)
-- [Nodes (iOS and Android)](/nodes)
-- [Web surfaces (Control UI)](/web)
-- [Discovery and transports](/gateway/discovery)
-- [Remote access](/gateway/remote)
-
-## Providers and UX
-
-- [WebChat](/web/webchat)
-- [Control UI (browser)](/web/control-ui)
-- [Telegram](/channels/telegram)
-- [Discord](/channels/discord)
-- [Mattermost](/channels/mattermost)
-- [QQ Bot](/channels/qqbot)
-- [iMessage](/channels/imessage)
-- [Groups](/channels/groups)
-- [WhatsApp group messages](/channels/group-messages)
-- [Media images](/nodes/images)
-- [Media audio](/nodes/audio)
-
-## Companion apps
-
-- [macOS app](/platforms/macos)
-- [iOS app](/platforms/ios)
-- [Android app](/platforms/android)
-- [Windows (WSL2)](/platforms/windows)
-- [Linux app](/platforms/linux)
-
-## Operations and safety
-
-- [Sessions](/concepts/session)
-- [Cron jobs](/automation/cron-jobs)
-- [Webhooks](/automation/cron-jobs#webhooks)
-- [Gmail hooks (Pub/Sub)](/automation/cron-jobs#gmail-pubsub-integration)
-- [Security](/gateway/security)
-- [Troubleshooting](/gateway/troubleshooting)
-
-## Related
-
-- [Getting started](/start/getting-started)
-- [Docs hubs](/start/hubs)

package/docs/start/fengming.md

@@ -1,252 +0,0 @@
----
-summary: "End-to-end guide for running FengMing as a personal assistant with safety cautions"
-read_when:
-  - Onboarding a new assistant instance
-  - Reviewing safety/permission implications
-title: "Personal assistant setup"
----
-
-FengMing is a self-hosted gateway that connects Discord, Google Chat, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp, Zalo, and more to AI agents. This guide covers the "personal assistant" setup: a dedicated WhatsApp number that behaves like your always-on AI assistant.
-
-## ⚠️ Safety first
-
-You're putting an agent in a position to:
-
-- run commands on your machine (depending on your tool policy)
-- read/write files in your workspace
-- send messages back out via WhatsApp/Telegram/Discord/Mattermost and other bundled channels
-
-Start conservative:
-
-- Always set `channels.whatsapp.allowFrom` (never run open-to-the-world on your personal Mac).
-- Use a dedicated WhatsApp number for the assistant.
-- Heartbeats now default to every 30 minutes. Disable until you trust the setup by setting `agents.defaults.heartbeat.every: "0m"`.
-
-## Prerequisites
-
-- FengMing installed and onboarded - see [Getting Started](/start/getting-started) if you haven't done this yet
-- A second phone number (SIM/eSIM/prepaid) for the assistant
-
-## The two-phone setup (recommended)
-
-You want this:
-
-```mermaid
-flowchart TB
-    A["<b>Your Phone (personal)<br></b><br>Your WhatsApp<br>+1-555-YOU"] -- message --> B["<b>Second Phone (assistant)<br></b><br>Assistant WA<br>+1-555-ASSIST"]
-    B -- linked via QR --> C["<b>Your Mac (fengming)<br></b><br>AI agent"]
-```
-
-If you link your personal WhatsApp to FengMing, every message to you becomes "agent input". That's rarely what you want.
-
-## 5-minute quick start
-
-1. Pair WhatsApp Web (shows QR; scan with the assistant phone):
-
-```bash
-fengming channels login
-```
-
-2. Start the Gateway (leave it running):
-
-```bash
-fengming gateway --port 18789
-```
-
-3. Put a minimal config in `~/.fengming/fengming.json`:
-
-```json5
-{
-  gateway: { mode: "local" },
-  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
-}
-```
-
-Now message the assistant number from your allowlisted phone.
-
-When onboarding finishes, FengMing auto-opens the dashboard and prints a clean (non-tokenized) link. If the dashboard prompts for auth, paste the configured shared secret into Control UI settings. Onboarding uses a token by default (`gateway.auth.token`), but password auth works too if you switched `gateway.auth.mode` to `password`. To reopen later: `fengming dashboard`.
-
-## Give the agent a workspace (AGENTS)
-
-FengMing reads operating instructions and "memory" from its workspace directory.
-
-By default, FengMing uses `~/.fengming/workspace` as the agent workspace, and will create it (plus starter `AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`) automatically on setup/first agent run. `BOOTSTRAP.md` is only created when the workspace is brand new (it should not come back after you delete it). `MEMORY.md` is optional (not auto-created); when present, it is loaded for normal sessions. Subagent sessions only inject `AGENTS.md` and `TOOLS.md`.
-
-<Tip>
-Treat this folder like FengMing's memory and make it a git repo (ideally private) so your `AGENTS.md` and memory files are backed up. If git is installed, brand-new workspaces are auto-initialized.
-</Tip>
-
-```bash
-fengming setup
-```
-
-Full workspace layout + backup guide: [Agent workspace](/concepts/agent-workspace)
-Memory workflow: [Memory](/concepts/memory)
-
-Optional: choose a different workspace with `agents.defaults.workspace` (supports `~`).
-
-```json5
-{
-  agents: {
-    defaults: {
-      workspace: "~/.fengming/workspace",
-    },
-  },
-}
-```
-
-If you already ship your own workspace files from a repo, you can disable bootstrap file creation entirely:
-
-```json5
-{
-  agents: {
-    defaults: {
-      skipBootstrap: true,
-    },
-  },
-}
-```
-
-## The config that turns it into "an assistant"
-
-FengMing defaults to a good assistant setup, but you'll usually want to tune:
-
-- persona/instructions in [`SOUL.md`](/concepts/soul)
-- thinking defaults (if desired)
-- heartbeats (once you trust it)
-
-Example:
-
-```json5
-{
-  logging: { level: "info" },
-  agents: {
-    defaults: {
-      model: { primary: "anthropic/claude-opus-4-6" },
-      workspace: "~/.fengming/workspace",
-      thinkingDefault: "high",
-      timeoutSeconds: 1800,
-      // Start with 0; enable later.
-      heartbeat: { every: "0m" },
-    },
-    list: [
-      {
-        id: "main",
-        default: true,
-        groupChat: {
-          mentionPatterns: ["@fengming", "fengming"],
-        },
-      },
-    ],
-  },
-  channels: {
-    whatsapp: {
-      allowFrom: ["+15555550123"],
-      groups: {
-        "*": { requireMention: true },
-      },
-    },
-  },
-  session: {
-    scope: "per-sender",
-    resetTriggers: ["/new", "/reset"],
-    reset: {
-      mode: "daily",
-      atHour: 4,
-      idleMinutes: 10080,
-    },
-  },
-}
-```
-
-## Sessions and memory
-
-- Session files: `~/.fengming/agents/<agentId>/sessions/{{SessionId}}.jsonl`
-- Session metadata (token usage, last route, etc): `~/.fengming/agents/<agentId>/sessions/sessions.json` (legacy: `~/.fengming/sessions/sessions.json`)
-- `/new` or `/reset` starts a fresh session for that chat (configurable via `resetTriggers`). If sent alone, FengMing acknowledges the reset without invoking the model.
-- `/compact [instructions]` compacts the session context and reports the remaining context budget.
-
-## Heartbeats (proactive mode)
-
-By default, FengMing runs a heartbeat every 30 minutes with the prompt:
-`Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`
-Set `agents.defaults.heartbeat.every: "0m"` to disable.
-
-- If `HEARTBEAT.md` exists but is effectively empty (only blank lines and markdown headers like `# Heading`), FengMing skips the heartbeat run to save API calls.
-- If the file is missing, the heartbeat still runs and the model decides what to do.
-- If the agent replies with `HEARTBEAT_OK` (optionally with short padding; see `agents.defaults.heartbeat.ackMaxChars`), FengMing suppresses outbound delivery for that heartbeat.
-- By default, heartbeat delivery to DM-style `user:<id>` targets is allowed. Set `agents.defaults.heartbeat.directPolicy: "block"` to suppress direct-target delivery while keeping heartbeat runs active.
-- Heartbeats run full agent turns - shorter intervals burn more tokens.
-
-```json5
-{
-  agents: {
-    defaults: {
-      heartbeat: { every: "30m" },
-    },
-  },
-}
-```
-
-## Media in and out
-
-Inbound attachments (images/audio/docs) can be surfaced to your command via templates:
-
-- `{{MediaPath}}` (local temp file path)
-- `{{MediaUrl}}` (pseudo-URL)
-- `{{Transcript}}` (if audio transcription is enabled)
-
-Outbound attachments from the agent: include `MEDIA:<path-or-url>` on its own line (no spaces). The directive must start the line as plain text, outside code fences and without Markdown wrappers such as bold or inline code. Example:
-
-```
-Here's the screenshot.
-MEDIA:https://example.com/screenshot.png
-```
-
-FengMing extracts these and sends them as media alongside the text.
-
-These forms are not attachment directives and are sent as normal text:
-
-```md
-**MEDIA:https://example.com/screenshot.png**
-`MEDIA:https://example.com/screenshot.png`
-Here is the screenshot: MEDIA:https://example.com/screenshot.png
-```
-
-Local-path behavior follows the same file-read trust model as the agent:
-
-- If `tools.fs.workspaceOnly` is `true`, outbound `MEDIA:` local paths stay restricted to the FengMing temp root, the media cache, agent workspace paths, and sandbox-generated files.
-- If `tools.fs.workspaceOnly` is `false`, outbound `MEDIA:` can use host-local files the agent is already allowed to read.
-- Local paths can be absolute, workspace-relative, or home-relative with `~/`.
-- Host-local sends still only allow media and safe document types (images, audio, video, PDF, and Office documents). Plain text and secret-like files are not treated as sendable media.
-
-That means generated images/files outside the workspace can now send when your fs policy already allows those reads, without reopening arbitrary host-text attachment exfiltration.
-
-## Operations checklist
-
-```bash
-fengming status          # local status (creds, sessions, queued events)
-fengming status --all    # full diagnosis (read-only, pasteable)
-fengming status --deep   # asks the gateway for a live health probe with channel probes when supported
-fengming health --json   # gateway health snapshot (WS; default can return a fresh cached snapshot)
-```
-
-Logs live under `/tmp/fengming/` (default: `fengming-YYYY-MM-DD.log`).
-
-## Next steps
-
-- WebChat: [WebChat](/web/webchat)
-- Gateway ops: [Gateway runbook](/gateway)
-- Cron + wakeups: [Cron jobs](/automation/cron-jobs)
-- macOS menu bar companion: [FengMing macOS app](/platforms/macos)
-- iOS node app: [iOS app](/platforms/ios)
-- Android node app: [Android app](/platforms/android)
-- Windows status: [Windows (WSL2)](/platforms/windows)
-- Linux status: [Linux app](/platforms/linux)
-- Security: [Security](/gateway/security)
-
-## Related
-
-- [Getting started](/start/getting-started)
-- [Setup](/start/setup)
-- [Channels overview](/channels)