fengming 0.3.10 → 0.3.11

package/docs/cli/crestodian.md

@@ -1,337 +0,0 @@
----
-summary: "CLI reference and security model for Crestodian, the configless-safe setup and repair helper"
-read_when:
-  - You run fengming with no command after setup and want to understand Crestodian
-  - You need a configless-safe way to inspect or repair FengMing
-  - You are designing or enabling message-channel rescue mode
-title: "Crestodian"
----
-
-# `fengming crestodian`
-
-Crestodian is FengMing's local setup, repair, and configuration helper. It is
-designed to stay reachable when the normal agent path is broken.
-
-Running `fengming` with no command starts classic onboarding first when the
-active config file is missing or has no authored settings (empty or
-metadata-only). After a config file has authored settings, running `fengming`
-with no command starts Crestodian in an interactive terminal. Running
-`fengming crestodian` starts the same helper explicitly.
-
-## What Crestodian shows
-
-On startup, interactive Crestodian opens the same TUI shell used by
-`fengming tui`, with a Crestodian chat backend. The chat log starts with a short
-greeting:
-
-- when to start Crestodian
-- the model or deterministic planner path Crestodian is actually using
-- config validity and the default agent
-- Gateway reachability from the first startup probe
-- the next debug action Crestodian can take
-
-It does not dump secrets or load plugin CLI commands just to start. The TUI
-still provides the normal header, chat log, status line, footer, autocomplete,
-and editor controls.
-
-Use `status` for the detailed inventory with config path, docs/source paths,
-local CLI probes, API-key presence, agents, model, and Gateway details.
-
-Crestodian uses the same FengMing reference discovery as regular agents. In a Git checkout,
-it points itself at local `docs/` and the local source tree. In an npm package install, it
-uses the bundled package docs and links to
-[https://github.com/fengming/fengming](https://github.com/fengming/fengming), with explicit
-guidance to review source whenever the docs are not enough.
-
-## Examples
-
-```bash
-fengming
-fengming crestodian
-fengming crestodian --json
-fengming crestodian --message "models"
-fengming crestodian --message "validate config"
-fengming crestodian --message "setup workspace ~/Projects/work model openai/gpt-5.5" --yes
-fengming crestodian --message "set default model openai/gpt-5.5" --yes
-fengming onboard --modern
-```
-
-Inside the Crestodian TUI:
-
-```text
-status
-health
-doctor
-doctor fix
-validate config
-setup
-setup workspace ~/Projects/work model openai/gpt-5.5
-config set gateway.port 19001
-config set-ref gateway.auth.token env FENGMING_GATEWAY_TOKEN
-gateway status
-restart gateway
-agents
-create agent work workspace ~/Projects/work
-models
-set default model openai/gpt-5.5
-plugins list
-plugins search slack
-plugin install clawhub:fengming-codex-app-server
-plugin uninstall fengming-codex-app-server
-talk to work agent
-talk to agent for ~/Projects/work
-audit
-quit
-```
-
-## Safe startup
-
-Crestodian's startup path is deliberately small. It can run when:
-
-- `fengming.json` is missing
-- `fengming.json` is invalid
-- the Gateway is down
-- plugin command registration is unavailable
-- no agent has been configured yet
-
-`fengming --help` and `fengming --version` still use the normal fast paths.
-Noninteractive bare `fengming` exits with a short message instead of printing
-root help. On a fresh install, the message points to non-interactive onboarding;
-after setup, it points to one-shot Crestodian commands.
-
-## Operations and approval
-
-Crestodian uses typed operations instead of editing config ad hoc.
-
-Read-only operations can run immediately:
-
-- show overview
-- list agents
-- list installed plugins
-- search ClawHub plugins
-- show model/backend status
-- run status or health checks
-- check Gateway reachability
-- run doctor without interactive fixes
-- validate config
-- show the audit-log path
-
-Persistent operations require conversational approval in interactive mode unless
-you pass `--yes` for a direct command:
-
-- write config
-- run `config set`
-- set supported SecretRef values through `config set-ref`
-- run setup/onboarding bootstrap
-- change the default model
-- start, stop, or restart the Gateway
-- create agents
-- install plugins from ClawHub or npm
-- uninstall plugins
-- run doctor repairs that rewrite config or state
-
-Applied writes are recorded in:
-
-```text
-~/.fengming/audit/crestodian.jsonl
-```
-
-Discovery is not audited. Only applied operations and writes are logged.
-
-`fengming onboard --modern` starts Crestodian as the modern onboarding preview.
-Plain `fengming onboard` still runs classic onboarding.
-
-## Setup bootstrap
-
-`setup` is the chat-first onboarding bootstrap. It writes only through typed
-config operations and asks for approval first.
-
-```text
-setup
-setup workspace ~/Projects/work
-setup workspace ~/Projects/work model openai/gpt-5.5
-```
-
-When no model is configured, setup selects the first usable backend in this
-order and tells you what it chose:
-
-- existing explicit model, if already configured
-- `OPENAI_API_KEY` -> `openai/gpt-5.5`
-- `ANTHROPIC_API_KEY` -> `anthropic/claude-opus-4-8`
-- Claude Code CLI -> `claude-cli/claude-opus-4-8`
-- Codex -> `openai/gpt-5.5` through the Codex app-server harness
-
-If none are available, setup still writes the default workspace and leaves the
-model unset. Install or log into Codex/Claude Code, or expose
-`OPENAI_API_KEY`/`ANTHROPIC_API_KEY`, then run setup again.
-
-## Model-Assisted Planner
-
-Crestodian always starts in deterministic mode. For fuzzy commands that the
-deterministic parser does not understand, local Crestodian can make one bounded
-planner turn through FengMing's normal runtime paths. It first uses the
-configured FengMing model. If no configured model is usable yet, it can fall
-back to local runtimes already present on the machine:
-
-- Claude Code CLI: `claude-cli/claude-opus-4-8`
-- Codex app-server harness: `openai/gpt-5.5`
-
-The model-assisted planner cannot mutate config directly. It must translate the
-request into one of Crestodian's typed commands, then the normal approval and
-audit rules apply. Crestodian prints the model it used and the interpreted
-command before it runs anything. Configless fallback planner turns are
-temporary, tool-disabled where the runtime supports it, and use a temporary
-workspace/session.
-
-Message-channel rescue mode does not use the model-assisted planner. Remote
-rescue stays deterministic so a broken or compromised normal agent path cannot
-be used as a config editor.
-
-## Switching to an agent
-
-Use a natural-language selector to leave Crestodian and open the normal TUI:
-
-```text
-talk to agent
-talk to work agent
-switch to main agent
-```
-
-`fengming tui`, `fengming chat`, and `fengming terminal` still open the normal
-agent TUI directly. They do not start Crestodian.
-
-After switching into the normal TUI, use `/crestodian` to return to Crestodian.
-You can include a follow-up request:
-
-```text
-/crestodian
-/crestodian restart gateway
-```
-
-Agent switches inside the TUI leave a breadcrumb that `/crestodian` is available.
-
-## Message rescue mode
-
-Message rescue mode is the message-channel entrypoint for Crestodian. It is for
-the case where your normal agent is dead, but a trusted channel such as WhatsApp
-still receives commands.
-
-Supported text command:
-
-- `/crestodian <request>`
-
-Operator flow:
-
-```text
-You, in a trusted owner DM: /crestodian status
-FengMing: Crestodian rescue mode. Gateway reachable: no. Config valid: no.
-You: /crestodian restart gateway
-FengMing: Plan: restart the Gateway. Reply /crestodian yes to apply.
-You: /crestodian yes
-FengMing: Applied. Audit entry written.
-```
-
-Agent creation can also be queued from the local prompt or rescue mode:
-
-```text
-create agent work workspace ~/Projects/work model openai/gpt-5.5
-/crestodian create agent work workspace ~/Projects/work
-```
-
-Remote rescue mode is an admin surface. It must be treated like remote config
-repair, not like normal chat.
-
-Security contract for remote rescue:
-
-- Disabled when sandboxing is active. If an agent/session is sandboxed,
-  Crestodian must refuse remote rescue and explain that local CLI repair is
-  required.
-- Default effective state is `auto`: allow remote rescue only in trusted YOLO
-  operation, where the runtime already has unsandboxed local authority.
-- Require an explicit owner identity. Rescue must not accept wildcard sender
-  rules, open group policy, unauthenticated webhooks, or anonymous channels.
-- Owner DMs only by default. Group/channel rescue requires explicit opt-in.
-- Plugin search and list are read-only. Plugin install is local-only by default
-  because it downloads executable code. Plugin uninstall can be allowed as an
-  approved repair operation when rescue policy permits persistent writes.
-- Remote rescue cannot open the local TUI or switch into an interactive agent
-  session. Use local `fengming` for agent handoff.
-- Persistent writes still require approval, even in rescue mode.
-- Audit every applied rescue operation. Message-channel rescue records channel,
-  account, sender, and source-address metadata. Config-mutating operations also
-  record config hashes before and after.
-- Never echo secrets. SecretRef inspection should report availability, not
-  values.
-- If the Gateway is alive, prefer Gateway typed operations. If the Gateway is
-  dead, use only the minimal local repair surface that does not depend on the
-  normal agent loop.
-
-Config shape:
-
-```jsonc
-{
-  "crestodian": {
-    "rescue": {
-      "enabled": "auto",
-      "ownerDmOnly": true,
-    },
-  },
-}
-```
-
-`enabled` should accept:
-
-- `"auto"`: default. Allow only when the effective runtime is YOLO and
-  sandboxing is off.
-- `false`: never allow message-channel rescue.
-- `true`: explicitly allow rescue when the owner/channel checks pass. This
-  still must not bypass the sandboxing denial.
-
-The default `"auto"` YOLO posture is:
-
-- sandbox mode resolves to `off`
-- `tools.exec.security` resolves to `full`
-- `tools.exec.ask` resolves to `off`
-
-Remote rescue is covered by the Docker lane:
-
-```bash
-pnpm test:docker:crestodian-rescue
-```
-
-Configless local planner fallback is covered by:
-
-```bash
-pnpm test:docker:crestodian-planner
-```
-
-An opt-in live channel command-surface smoke checks `/crestodian status` plus a
-persistent approval roundtrip through the rescue handler:
-
-```bash
-pnpm test:live:crestodian-rescue-channel
-```
-
-Configless setup through explicit Crestodian commands is covered by:
-
-```bash
-pnpm test:docker:crestodian-first-run
-```
-
-That lane starts with an empty state dir, verifies the modern onboard Crestodian
-entrypoint, sets the default model, creates an additional agent, configures
-Discord through a plugin enablement plus token SecretRef, validates config, and
-checks the audit log. QA Lab also has a repo-backed scenario for the same Ring 0
-flow:
-
-```bash
-pnpm fengming qa suite --scenario crestodian-ring-zero-setup
-```
-
-## Related
-
-- [CLI reference](/cli)
-- [Doctor](/cli/doctor)
-- [TUI](/cli/tui)
-- [Sandbox](/cli/sandbox)
-- [Security](/cli/security)

package/docs/cli/cron.md

@@ -1,304 +0,0 @@
----
-summary: "CLI reference for `fengming cron` (schedule and run background jobs)"
-read_when:
-  - You want scheduled jobs and wakeups
-  - You are debugging cron execution and logs
-title: "Cron"
----
-
-# `fengming cron`
-
-Manage cron jobs for the Gateway scheduler.
-
-<Tip>
-Run `fengming cron --help` for the full command surface. See [Cron jobs](/automation/cron-jobs) for the conceptual guide.
-</Tip>
-
-## Create jobs quickly
-
-`fengming cron create` is an alias for `fengming cron add`. For new jobs, put the schedule first and the prompt second:
-
-```bash
-fengming cron create "0 7 * * *" \
-  "Summarize overnight updates." \
-  --name "Morning brief" \
-  --agent ops
-```
-
-Use `--webhook <url>` when the job should POST the finished payload instead of delivering to a chat target:
-
-```bash
-fengming cron create "0 18 * * 1-5" \
-  "Summarize today's deploys as JSON." \
-  --name "Deploy digest" \
-  --webhook "https://example.invalid/fengming/cron"
-```
-
-## Sessions
-
-`--session` accepts `main`, `isolated`, `current`, or `session:<id>`.
-
-<AccordionGroup>
-  <Accordion title="Session keys">
-    - `main` binds to the agent's main session.
-    - `isolated` creates a fresh transcript and session id for each run.
-    - `current` binds to the active session at creation time.
-    - `session:<id>` pins to an explicit persistent session key.
-
-  </Accordion>
-  <Accordion title="Isolated session semantics">
-    Isolated runs reset ambient conversation context. Channel and group routing, send/queue policy, elevation, origin, and ACP runtime binding are reset for the new run. Safe preferences and explicit user-selected model or auth overrides can carry across runs.
-  </Accordion>
-</AccordionGroup>
-
-## Delivery
-
-`fengming cron list` and `fengming cron show <job-id>` preview the resolved delivery route. For `channel: "last"`, the preview shows whether the route resolved from the main or current session, or will fail closed.
-
-Provider-prefixed targets can disambiguate unresolved announce channels. For example, `to: "telegram:123"` selects Telegram when `delivery.channel` is omitted or `last`. Only prefixes advertised by the loaded plugin are provider selectors. If `delivery.channel` is explicit, the prefix must match that channel; `channel: "whatsapp"` with `to: "telegram:123"` is rejected. Service prefixes such as `imessage:` and `sms:` remain channel-owned target syntax.
-
-<Note>
-Isolated `cron add` jobs default to `--announce` delivery. Use `--no-deliver` to keep output internal. `--deliver` remains as a deprecated alias for `--announce`.
-</Note>
-
-### Delivery ownership
-
-Isolated cron chat delivery is shared between the agent and the runner:
-
-- The agent can send directly using the `message` tool when a chat route is available.
-- `announce` fallback-delivers the final reply only when the agent did not send directly to the resolved target.
-- `webhook` posts the finished payload to a URL.
-- `none` disables runner fallback delivery.
-
-Use `cron add|create --webhook <url>` or `cron edit <job-id> --webhook <url>` to set webhook delivery. Do not combine `--webhook` with chat delivery flags such as `--announce`, `--no-deliver`, `--channel`, `--to`, `--thread-id`, or `--account`.
-
-`--announce` is runner fallback delivery for the final reply. `--no-deliver` disables that fallback but does not remove the agent's `message` tool when a chat route is available.
-
-Reminders created from an active chat preserve the live chat delivery target for fallback announce delivery. Internal session keys may be lowercase; do not use them as a source of truth for case-sensitive provider IDs such as Matrix room IDs.
-
-### Failure delivery
-
-Failure notifications resolve in this order:
-
-1. `delivery.failureDestination` on the job.
-2. Global `cron.failureDestination`.
-3. The job's primary announce target (when no explicit failure destination is set).
-
-<Note>
-Main-session jobs may only use `delivery.failureDestination` when primary delivery mode is `webhook`. Isolated jobs accept it in all modes.
-</Note>
-
-Note: isolated cron runs treat run-level agent failures as job errors even when
-no reply payload is produced, so model/provider failures still increment error
-counters and trigger failure notifications.
-
-If an isolated run times out before the first model request, `fengming cron show`
-and `fengming cron runs` include a phase-specific error such as
-`setup timed out before runner start` or
-`stalled before first model call (last phase: context-engine)`.
-For CLI-backed providers, the pre-model watchdog stays active until the external
-CLI turn starts, so session lookup, hook, auth, prompt, and CLI setup stalls are
-reported as pre-model cron failures.
-
-## Scheduling
-
-### One-shot jobs
-
-`--at <datetime>` schedules a one-shot run. Offset-less datetimes are treated as UTC unless you also pass `--tz <iana>`, which interprets the wall-clock time in the given timezone.
-
-<Note>
-One-shot jobs delete after success by default. Use `--keep-after-run` to preserve them.
-</Note>
-
-### Recurring jobs
-
-Recurring jobs use exponential retry backoff after consecutive errors: 30s, 1m, 5m, 15m, 60m. The schedule returns to normal after the next successful run.
-
-Skipped runs are tracked separately from execution errors. They do not affect retry backoff, but `fengming cron edit <job-id> --failure-alert-include-skipped` can opt failure alerts into repeated skipped-run notifications.
-
-For isolated jobs that target a local configured model provider, cron runs a lightweight provider preflight before starting the agent turn. Loopback, private-network, and `.local` `api: "ollama"` providers are probed at `/api/tags`; local OpenAI-compatible providers such as vLLM, SGLang, and LM Studio are probed at `/models`. If the endpoint is unreachable, the run is recorded as `skipped` and retried on a later schedule; matching dead endpoints are cached for 5 minutes to avoid many jobs hammering the same local server.
-
-Note: cron job definitions live in `jobs.json`, while pending runtime state lives in `jobs-state.json`. If `jobs.json` is edited externally, the Gateway reloads changed schedules and clears stale pending slots; formatting-only rewrites do not clear the pending slot. Malformed job rows are removed from active `jobs.json` at load time after their raw contents are copied to `jobs-quarantine.json`.
-
-### Manual runs
-
-`fengming cron run <job-id>` force-runs by default and returns as soon as the manual run is queued. Successful responses include `{ ok: true, enqueued: true, runId }`. Use the returned `runId` to inspect the later result:
-
-```bash
-fengming cron run <job-id>
-fengming cron runs --id <job-id> --run-id <run-id>
-```
-
-Add `--wait` when a script should block until that exact queued run records a terminal status:
-
-```bash
-fengming cron run <job-id> --wait --wait-timeout 10m --poll-interval 2s
-```
-
-With `--wait`, the CLI still calls `cron.run` first, then polls `cron.runs` for the returned `runId`. The command exits `0` only when the run finishes with status `ok`. It exits non-zero when the run finishes with `error` or `skipped`, when the Gateway response does not include a `runId`, or when `--wait-timeout` expires. `--poll-interval` must be greater than zero.
-
-<Note>
-Use `--due` when you want the manual command to run only if the job is currently due. If `--due --wait` does not enqueue a run, the command returns the normal non-run response instead of polling.
-</Note>
-
-## Models
-
-`cron add|edit --model <ref>` selects an allowed model for the job.
-
-<Warning>
-If the model is not allowed or cannot be resolved, cron fails the run with an explicit validation error instead of falling back to the job's agent or default model selection.
-</Warning>
-
-Cron `--model` is a **job primary**, not a chat-session `/model` override. That means:
-
-- Configured model fallbacks still apply when the selected job model fails.
-- Per-job payload `fallbacks` replaces the configured fallback list when present.
-- An empty per-job fallback list (`fallbacks: []` in the job payload/API) makes the cron run strict.
-- When a job has `--model` but no fallback list is configured, FengMing passes an explicit empty fallback override so the agent primary is not appended as a hidden retry target.
-- Local-provider preflight checks walk configured fallbacks before marking a cron run `skipped`.
-
-`fengming doctor` reports jobs that already have `payload.model` set, including provider namespace counts and mismatches against `agents.defaults.model`. Use that check when auth, provider, or billing behavior looks different between live chat and scheduled jobs.
-
-### Isolated cron model precedence
-
-Isolated cron resolves the active model in this order:
-
-1. Gmail-hook override.
-2. Per-job `--model`.
-3. Stored cron-session model override (when the user selected one).
-4. Agent or default model selection.
-
-### Fast mode
-
-Isolated cron fast mode follows the resolved live model selection. Model config `params.fastMode` applies by default, but a stored session `fastMode` override still wins over config.
-
-### Live model switch retries
-
-If an isolated run throws `LiveSessionModelSwitchError`, cron persists the switched provider and model (and switched auth profile override when present) for the active run before retrying. The outer retry loop is bounded to two switch retries after the initial attempt, then aborts instead of looping forever.
-
-## Run output and denials
-
-### Stale acknowledgement suppression
-
-Isolated cron turns suppress stale acknowledgement-only replies. If the first result is just an interim status update and no descendant subagent run is responsible for the eventual answer, cron re-prompts once for the real result before delivery.
-
-### Silent token suppression
-
-If an isolated cron run returns only the silent token (`NO_REPLY` or `no_reply`), cron suppresses both direct outbound delivery and the fallback queued summary path, so nothing is posted back to chat.
-
-### Structured denials
-
-Isolated cron runs use structured execution-denial metadata from the embedded run as the authoritative denial signal. They also honor node-host `UNAVAILABLE` wrappers when the nested structured error message starts with `SYSTEM_RUN_DENIED` or `INVALID_REQUEST`.
-
-Cron does not classify final-output prose or approval-looking refusal phrases as denials unless the embedded run also provides structured denial metadata, so ordinary assistant text is not treated as a blocked command.
-
-`cron list` and run history surface the denial reason instead of reporting a blocked command as `ok`.
-
-## Retention
-
-Retention and pruning are controlled in config:
-
-- `cron.sessionRetention` (default `24h`) prunes completed isolated run sessions.
-- `cron.runLog.maxBytes` and `cron.runLog.keepLines` prune `~/.fengming/cron/runs/<jobId>.jsonl`.
-
-## Migrating older jobs
-
-<Note>
-If you have cron jobs from before the current delivery and store format, run `fengming doctor --fix`. Doctor normalizes legacy cron fields (`jobId`, `schedule.cron`, top-level delivery fields including legacy `threadId`, payload `provider` delivery aliases) and migrates simple `notify: true` webhook fallback jobs to explicit webhook delivery when `cron.webhook` is configured.
-</Note>
-
-## Common edits
-
-Update delivery settings without changing the message:
-
-```bash
-fengming cron edit <job-id> --announce --channel telegram --to "123456789"
-```
-
-Disable delivery for an isolated job:
-
-```bash
-fengming cron edit <job-id> --no-deliver
-```
-
-Enable lightweight bootstrap context for an isolated job:
-
-```bash
-fengming cron edit <job-id> --light-context
-```
-
-Announce to a specific channel:
-
-```bash
-fengming cron edit <job-id> --announce --channel slack --to "channel:C1234567890"
-```
-
-Announce to a Telegram forum topic:
-
-```bash
-fengming cron edit <job-id> --announce --channel telegram --to "-1001234567890" --thread-id 42
-```
-
-Create an isolated job with lightweight bootstrap context:
-
-```bash
-fengming cron create "0 7 * * *" \
-  "Summarize overnight updates." \
-  --name "Lightweight morning brief" \
-  --session isolated \
-  --light-context \
-  --no-deliver
-```
-
-`--light-context` applies to isolated agent-turn jobs only. For cron runs, lightweight mode keeps bootstrap context empty instead of injecting the full workspace bootstrap set.
-
-## Common admin commands
-
-Manual run and inspection:
-
-```bash
-fengming cron list
-fengming cron list --agent ops
-fengming cron get <job-id>
-fengming cron show <job-id>
-fengming cron run <job-id>
-fengming cron run <job-id> --due
-fengming cron run <job-id> --wait --wait-timeout 10m
-fengming cron run <job-id> --wait --wait-timeout 10m --poll-interval 2s
-fengming cron runs --id <job-id> --limit 50
-fengming cron runs --id <job-id> --run-id <run-id>
-```
-
-`fengming cron list` shows all matching jobs by default. Pass `--agent <id>` to show only jobs whose effective normalized agent id matches; jobs without a stored agent id count as the configured default agent.
-
-`fengming cron get <job-id>` returns the stored job JSON directly. Use `cron show <job-id>` when you want the human-readable view with delivery-route preview.
-
-`cron list --json` and `cron show <job-id> --json` include a top-level `status` field on each job, computed from `enabled`, `state.runningAtMs`, and `state.lastRunStatus`. Values: `disabled`, `running`, `ok`, `error`, `skipped`, or `idle`. This mirrors the human-readable status column so external tooling can read job state without re-deriving it.
-
-`cron runs` entries include delivery diagnostics with the intended cron target, the resolved target, message-tool sends, fallback use, and delivered state.
-
-Agent and session retargeting:
-
-```bash
-fengming cron edit <job-id> --agent ops
-fengming cron edit <job-id> --clear-agent
-fengming cron edit <job-id> --session current
-fengming cron edit <job-id> --session "session:daily-brief"
-```
-
-`fengming cron add` warns when `--agent` is omitted on agent-turn jobs and falls back to the default agent (`main`). Pass `--agent <id>` at create time to pin a specific agent.
-
-Delivery tweaks:
-
-```bash
-fengming cron edit <job-id> --announce --channel slack --to "channel:C1234567890"
-fengming cron edit <job-id> --webhook "https://example.invalid/fengming/cron"
-fengming cron edit <job-id> --best-effort-deliver
-fengming cron edit <job-id> --no-best-effort-deliver
-fengming cron edit <job-id> --no-deliver
-```
-
-## Related
-
-- [CLI reference](/cli)
-- [Scheduled tasks](/automation/cron-jobs)