fengming 0.3.9 → 0.3.11

package/docs/reference/templates/USER.md

@@ -1,28 +0,0 @@
----
-summary: "User profile record"
-title: "USER template"
-read_when:
-  - Bootstrapping a workspace manually
----
-
-# USER.md - About Your Human
-
-_Learn about the person you're helping. Update this as you go._
-
-- **Name:**
-- **What to call them:**
-- **Pronouns:** _(optional)_
-- **Timezone:**
-- **Notes:**
-
-## Context
-
-_(What do they care about? What projects are they working on? What annoys them? What makes them laugh? Build this over time.)_
-
----
-
-The more you know, the better you can help. But remember — you're learning about a person, not building a dossier. Respect the difference.
-
-## Related
-
-- [Agent workspace](/concepts/agent-workspace)

package/docs/reference/test.md

@@ -1,247 +0,0 @@
----
-summary: "How to run tests locally (vitest) and when to use force/coverage modes"
-read_when:
-  - Running or fixing tests
-title: "Tests"
----
-
-- Full testing kit (suites, live, Docker): [Testing](/help/testing)
-- Update and plugin package validation: [Testing updates and plugins](/help/testing-updates-plugins)
-
-- Routine local test order:
-  1. `pnpm test:changed` for changed-scope Vitest proof.
-  2. `pnpm test <path-or-filter>` for one file, directory, or explicit target.
-  3. `pnpm test` only when you intentionally need the full local Vitest suite.
-- `pnpm test:force`: Kills any lingering gateway process holding the default control port, then runs the full Vitest suite with an isolated gateway port so server tests don't collide with a running instance. Use this when a prior gateway run left port 18789 occupied.
-- `pnpm test:coverage`: Runs the unit suite with V8 coverage (via `vitest.unit.config.ts`). This is a default-unit-lane coverage gate, not whole-repo all-file coverage. Thresholds are 70% lines/functions/statements and 55% branches. Because `coverage.all` is false and the default lane scopes coverage includes to non-fast unit tests with sibling source files, the gate measures source owned by this lane instead of every transitive import it happens to load.
-- `pnpm test:coverage:changed`: Runs unit coverage only for files changed since `origin/main`.
-- `pnpm test:changed`: cheap smart changed test run. It runs precise targets from direct test edits, sibling `*.test.ts` files, explicit source mappings, and the local import graph. Broad/config/package changes are skipped unless they map to precise tests.
-- `FENGMING_TEST_CHANGED_BROAD=1 pnpm test:changed`: explicit broad changed test run. Use it when a test harness/config/package edit should fall back to Vitest's broader changed-test behavior.
-- `pnpm changed:lanes`: shows the architectural lanes triggered by the diff against `origin/main`.
-- `pnpm check:changed`: runs the smart changed check gate for the diff against `origin/main`. It runs typecheck, lint, and guard commands for the affected architectural lanes, but does not run Vitest tests. Use `pnpm test:changed` or explicit `pnpm test <target>` for test proof.
-- Codex worktrees and linked/sparse checkouts: avoid direct local `pnpm test*`, `pnpm check*`, and `pnpm crabbox:run` unless you have verified pnpm will not reconcile dependencies. For tiny explicit-file proof use `node scripts/run-vitest.mjs <path-or-filter>`; for changed gates or broad proof use `node scripts/crabbox-wrapper.mjs run --provider blacksmith-testbox ... --shell -- "pnpm check:changed"` so pnpm runs inside Testbox.
-- `FENGMING_HEAVY_CHECK_LOCK_SCOPE=worktree <local-heavy-check command>`: keeps heavy-check serialization inside the current worktree instead of the Git common dir for commands such as `pnpm check:changed` and targeted `pnpm test ...`. Use it only on high-capacity local hosts when you intentionally run independent checks across linked worktrees.
-- `pnpm test`: routes explicit file/directory targets through scoped Vitest lanes. Untargeted runs are full-suite proof: they use fixed shard groups, expand to leaf configs for local parallel execution, and print the expected local shard fanout before starting. The extension group always expands to the per-extension shard configs instead of one giant root-project process.
-- Test wrapper runs end with a short `[test] passed|failed|skipped ... in ...` summary. Vitest's own duration line stays the per-shard detail.
-- Shared FengMing test state: use `src/test-utils/fengming-test-state.ts` from Vitest when a test needs an isolated `HOME`, `FENGMING_STATE_DIR`, `FENGMING_CONFIG_PATH`, config fixture, workspace, agent dir, or auth-profile store.
-- Control UI mocked E2E: use `pnpm test:ui:e2e` for the Vitest + Playwright lane that starts the Vite Control UI and drives a real Chromium page against a mocked Gateway WebSocket. Tests live in `ui/src/**/*.e2e.test.ts`; shared mocks and controls live in `ui/src/test-helpers/control-ui-e2e.ts`. `pnpm test:e2e` includes this lane. In Codex worktrees, prefer `node scripts/run-vitest.mjs run --config test/vitest/vitest.ui-e2e.config.ts --configLoader runner ui/src/ui/e2e/chat-flow.e2e.test.ts` for tiny targeted proof after dependencies are installed, or Testbox/Crabbox for broader GUI proof.
-- Process E2E helpers: use `test/helpers/fengming-test-instance.ts` when a Vitest process-level E2E test needs a running Gateway, CLI env, log capture, and cleanup in one place.
-- TUI PTY tests: use `node scripts/run-vitest.mjs run --config test/vitest/vitest.tui-pty.config.ts` for the fast fake-backend PTY lane. Use `FENGMING_TUI_PTY_INCLUDE_LOCAL=1` or `pnpm tui:pty:test:watch --mode local` for the slower `tui --local` smoke, which mocks only the external model endpoint. Assert stable visible text or fixture calls, not raw ANSI snapshots.
-- Docker/Bash E2E helpers: lanes that source `scripts/lib/docker-e2e-image.sh` can pass `docker_e2e_test_state_shell_b64 <label> <scenario>` into the container and decode it with `scripts/lib/fengming-e2e-instance.sh`; multi-home scripts can pass `docker_e2e_test_state_function_b64` and call `fengming_test_state_create <label> <scenario>` in each flow. Lower-level callers can use `scripts/lib/fengming-test-state.mjs shell --label <name> --scenario <name>` for an in-container shell snippet, or `node scripts/lib/fengming-test-state.mjs -- create --label <name> --scenario <name> --env-file <path> --json` for a sourceable host env file. The `--` before `create` keeps newer Node runtimes from treating `--env-file` as a Node flag. Docker/Bash lanes that launch a Gateway can source `scripts/lib/fengming-e2e-instance.sh` inside the container for entrypoint resolution, mock OpenAI startup, Gateway foreground/background launch, readiness probes, state env export, log dumps, and process cleanup.
-- Full, extension, and include-pattern shard runs update local timing data in `.artifacts/vitest-shard-timings.json`; later whole-config runs use those timings to balance slow and fast shards. Include-pattern CI shards append the shard name to the timing key, which keeps filtered shard timings visible without replacing whole-config timing data. Set `FENGMING_TEST_PROJECTS_TIMINGS=0` to ignore the local timing artifact.
-- Selected `plugin-sdk` and `commands` test files now route through dedicated light lanes that keep only `test/setup.ts`, leaving runtime-heavy cases on their existing lanes.
-- Source files with sibling tests map to that sibling before falling back to wider directory globs. Helper edits under `src/channels/plugins/contracts/test-helpers`, `src/plugin-sdk/test-helpers`, and `src/plugins/contracts` use a local import graph to run importing tests instead of broad-running every shard when the dependency path is precise.
-- `auto-reply` now also splits into three dedicated configs (`core`, `top-level`, `reply`) so the reply harness does not dominate the lighter top-level status/token/helper tests.
-- Base Vitest config now defaults to `pool: "threads"` and `isolate: false`, with the shared non-isolated runner enabled across the repo configs.
-- `pnpm test:channels` runs `vitest.channels.config.ts`.
-- `pnpm test:extensions` and `pnpm test extensions` run all extension/plugin shards. Heavy channel plugins, the browser plugin, and OpenAI run as dedicated shards; other plugin groups stay batched. Use `pnpm test extensions/<id>` for one bundled plugin lane.
-- `pnpm test:perf:imports`: enables Vitest import-duration + import-breakdown reporting, while still using scoped lane routing for explicit file/directory targets.
-- `pnpm test:perf:imports:changed`: same import profiling, but only for files changed since `origin/main`.
-- `pnpm test:perf:changed:bench -- --ref <git-ref>` benchmarks the routed changed-mode path against the native root-project run for the same committed git diff.
-- `pnpm test:perf:changed:bench -- --worktree` benchmarks the current worktree change set without committing first.
-- `pnpm test:perf:profile:main`: writes a CPU profile for the Vitest main thread (`.artifacts/vitest-main-profile`).
-- `pnpm test:perf:profile:runner`: writes CPU + heap profiles for the unit runner (`.artifacts/vitest-runner-profile`).
-- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`: runs every full-suite Vitest leaf config serially and writes grouped duration data plus per-config JSON/log artifacts. The Test Performance Agent uses this as its baseline before attempting slow-test fixes.
-- `pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json`: compares grouped reports after a performance-focused change.
-- `pnpm test:docker:timings <summary.json>` inspects slow Docker lanes after a Docker all run; use `pnpm test:docker:rerun <run-id|summary.json|failures.json>` to print cheap targeted rerun commands from the same artifacts.
-- Gateway integration: opt-in via `FENGMING_TEST_INCLUDE_GATEWAY=1 pnpm test` or `pnpm test:gateway`.
-- `pnpm test:e2e`: Runs the repo E2E aggregate: gateway end-to-end smoke tests plus the Control UI mocked browser E2E lane.
-- `pnpm test:e2e:gateway`: Runs gateway end-to-end smoke tests (multi-instance WS/HTTP/node pairing). Defaults to `threads` + `isolate: false` with adaptive workers in `vitest.e2e.config.ts`; tune with `FENGMING_E2E_WORKERS=<n>` and set `FENGMING_E2E_VERBOSE=1` for verbose logs.
-- `pnpm test:live`: Runs provider live tests (minimax/zai). Requires API keys and `LIVE=1` (or provider-specific `*_LIVE_TEST=1`) to unskip.
-- `pnpm test:docker:all`: Builds the shared live-test image, packs FengMing once as an npm tarball, builds/reuses a bare Node/Git runner image plus a functional image that installs that tarball into `/app`, then runs Docker smoke lanes with `FENGMING_SKIP_DOCKER_BUILD=1` through a weighted scheduler. The bare image (`FENGMING_DOCKER_E2E_BARE_IMAGE`) is used for installer/update/plugin-dependency lanes; those lanes mount the prebuilt tarball instead of using copied repo sources. The functional image (`FENGMING_DOCKER_E2E_FUNCTIONAL_IMAGE`) is used for normal built-app functionality lanes. `scripts/package-fengming-for-docker.mjs` is the single local/CI package packer and validates the tarball plus `dist/postinstall-inventory.json` before Docker consumes it. Docker lane definitions live in `scripts/lib/docker-e2e-scenarios.mjs`; planner logic lives in `scripts/lib/docker-e2e-plan.mjs`; `scripts/test-docker-all.mjs` executes the selected plan. `node scripts/test-docker-all.mjs --plan-json` emits the scheduler-owned CI plan for selected lanes, image kinds, package/live-image needs, state scenarios, and credential checks without building or running Docker. `FENGMING_DOCKER_ALL_PARALLELISM=<n>` controls process slots and defaults to 10; `FENGMING_DOCKER_ALL_TAIL_PARALLELISM=<n>` controls the provider-sensitive tail pool and defaults to 10. Heavy lane caps default to `FENGMING_DOCKER_ALL_LIVE_LIMIT=9`, `FENGMING_DOCKER_ALL_NPM_LIMIT=10`, and `FENGMING_DOCKER_ALL_SERVICE_LIMIT=7`; provider caps default to one heavy lane per provider via `FENGMING_DOCKER_ALL_LIVE_CLAUDE_LIMIT=4`, `FENGMING_DOCKER_ALL_LIVE_CODEX_LIMIT=4`, and `FENGMING_DOCKER_ALL_LIVE_GEMINI_LIMIT=4`. Use `FENGMING_DOCKER_ALL_WEIGHT_LIMIT` or `FENGMING_DOCKER_ALL_DOCKER_LIMIT` for larger hosts. If one lane exceeds the effective weight or resource cap on a low-parallelism host, it can still start from an empty pool and will run alone until it releases capacity. Lane starts are staggered by 2 seconds by default to avoid local Docker daemon create storms; override with `FENGMING_DOCKER_ALL_START_STAGGER_MS=<ms>`. The runner preflights Docker by default, cleans stale FengMing E2E containers, emits active-lane status every 30 seconds, shares provider CLI tool caches between compatible lanes, retries transient live-provider failures once by default (`FENGMING_DOCKER_ALL_LIVE_RETRIES=<n>`), and stores lane timings in `.artifacts/docker-tests/lane-timings.json` for longest-first ordering on later runs. Use `FENGMING_DOCKER_ALL_DRY_RUN=1` to print the lane manifest without running Docker, `FENGMING_DOCKER_ALL_STATUS_INTERVAL_MS=<ms>` to tune status output, or `FENGMING_DOCKER_ALL_TIMINGS=0` to disable timing reuse. Use `FENGMING_DOCKER_ALL_LIVE_MODE=skip` for deterministic/local lanes only or `FENGMING_DOCKER_ALL_LIVE_MODE=only` for live-provider lanes only; package aliases are `pnpm test:docker:local:all` and `pnpm test:docker:live:all`. Live-only mode merges main and tail live lanes into one longest-first pool so provider buckets can pack Claude, Codex, and Gemini work together. The runner stops scheduling new pooled lanes after the first failure unless `FENGMING_DOCKER_ALL_FAIL_FAST=0` is set, and each lane has a 120-minute fallback timeout overridable with `FENGMING_DOCKER_ALL_LANE_TIMEOUT_MS`; selected live/tail lanes use tighter per-lane caps. CLI backend Docker setup commands have their own timeout via `FENGMING_LIVE_CLI_BACKEND_SETUP_TIMEOUT_SECONDS` (default 180). Per-lane logs, `summary.json`, `failures.json`, and phase timings are written under `.artifacts/docker-tests/<run-id>/`; use `pnpm test:docker:timings <summary.json>` to inspect slow lanes and `pnpm test:docker:rerun <run-id|summary.json|failures.json>` to print cheap targeted rerun commands.
-- `pnpm test:docker:browser-cdp-snapshot`: Builds a Chromium-backed source E2E container, starts raw CDP plus an isolated Gateway, runs `browser doctor --deep`, and verifies CDP role snapshots include link URLs, cursor-promoted clickables, iframe refs, and frame metadata.
-- `pnpm test:docker:skill-install`: Installs the packed FengMing tarball in a bare Docker runner, disables `skills.install.allowUploadedArchives`, resolves a current skill slug from live ClawHub search, installs it through `fengming skills install`, and verifies `SKILL.md`, `.clawhub/origin.json`, `.clawhub/lock.json`, and `skills info --json`.
-- CLI backend live Docker probes can be run as focused lanes, for example `pnpm test:docker:live-cli-backend:claude`, `pnpm test:docker:live-cli-backend:claude:resume`, or `pnpm test:docker:live-cli-backend:claude:mcp`. Gemini has matching `:resume` and `:mcp` aliases.
-- `pnpm test:docker:openwebui`: Starts Dockerized FengMing + Open WebUI, signs in through Open WebUI, checks `/api/models`, then runs a real proxied chat through `/api/chat/completions`. Requires a usable live model key, pulls an external Open WebUI image, and is not expected to be CI-stable like the normal unit/e2e suites.
-- `pnpm test:docker:mcp-channels`: Starts a seeded Gateway container and a second client container that spawns `fengming mcp serve`, then verifies routed conversation discovery, transcript reads, attachment metadata, live event queue behavior, outbound send routing, and Claude-style channel + permission notifications over the real stdio bridge. The Claude notification assertion reads the raw stdio MCP frames directly so the smoke reflects what the bridge actually emits.
-- `pnpm test:docker:upgrade-survivor`: Installs the packed FengMing tarball over a dirty old-user fixture, runs package update plus non-interactive doctor without live provider or channel keys, then starts a loopback Gateway and checks that agents, channel config, plugin allowlists, workspace/session files, stale legacy plugin dependency state, startup, and RPC status survive.
-- `pnpm test:docker:published-upgrade-survivor`: Installs `fengming@latest` by default, seeds realistic existing-user files without live provider or channel keys, configures that baseline with a baked `fengming config set` command recipe, updates that published install to the packed FengMing tarball, runs non-interactive doctor, writes `.artifacts/upgrade-survivor/summary.json`, then starts a loopback Gateway and checks that configured intents, workspace/session files, stale plugin config and legacy dependency state, startup, `/healthz`, `/readyz`, and RPC status survive or repair cleanly. Override one baseline with `FENGMING_UPGRADE_SURVIVOR_BASELINE_SPEC`, expand an exact local matrix with `FENGMING_UPGRADE_SURVIVOR_BASELINE_SPECS` such as `fengming@2026.5.2 fengming@2026.4.23 fengming@2026.4.15`, or add scenario fixtures with `FENGMING_UPGRADE_SURVIVOR_SCENARIOS=reported-issues`; the reported-issues set includes `configured-plugin-installs` to verify configured external FengMing plugins install automatically during upgrade and `stale-source-plugin-shadow` to keep source-only plugin shadows from breaking startup. Package Acceptance exposes those as `published_upgrade_survivor_baseline`, `published_upgrade_survivor_baselines`, and `published_upgrade_survivor_scenarios`, and resolves meta baseline tokens such as `last-stable-4` or `all-since-2026.4.23` before handing exact package specs to Docker lanes.
-- `pnpm test:docker:update-migration`: Runs the published-upgrade survivor harness in the cleanup-heavy `plugin-deps-cleanup` scenario, starting at `fengming@2026.4.23` by default. The separate `Update Migration` workflow expands this lane with `baselines=all-since-2026.4.23` so every stable published package from `.23` onward updates to the candidate and proves configured-plugin dependency cleanup outside Full Release CI.
-- `pnpm test:docker:plugins`: Runs install/update smoke for local path, `file:`, npm registry packages with hoisted dependencies, git moving refs, ClawHub fixtures, marketplace updates, and Claude-bundle enable/inspect.
-
-## Local PR gate
-
-For local PR land/gate checks, run:
-
-- `pnpm check:changed`
-- `pnpm check`
-- `pnpm check:test-types`
-- `pnpm build`
-- `pnpm test`
-- `pnpm check:docs`
-
-If `pnpm test` flakes on a loaded host, rerun once before treating it as a regression, then isolate with `pnpm test <path/to/test>`. For memory-constrained hosts, use:
-
-- `FENGMING_VITEST_MAX_WORKERS=1 pnpm test`
-- `FENGMING_VITEST_FS_MODULE_CACHE_PATH=/tmp/fengming-vitest-cache pnpm test:changed`
-
-## Model latency bench (local keys)
-
-Script: [`scripts/bench-model.ts`](https://github.com/fengming/fengming/blob/main/scripts/bench-model.ts)
-
-Usage:
-
-- `pnpm tsx scripts/bench-model.ts --runs 10`
-- Optional env: `MINIMAX_API_KEY`, `MINIMAX_BASE_URL`, `MINIMAX_MODEL`, `ANTHROPIC_API_KEY`
-- Default prompt: "Reply with a single word: ok. No punctuation or extra text."
-
-Last run (2025-12-31, 20 runs):
-
-- minimax median 1279ms (min 1114, max 2431)
-- opus median 2454ms (min 1224, max 3170)
-
-## CLI startup bench
-
-Script: [`scripts/bench-cli-startup.ts`](https://github.com/fengming/fengming/blob/main/scripts/bench-cli-startup.ts)
-
-Usage:
-
-- `pnpm test:startup:bench`
-- `pnpm test:startup:bench:smoke`
-- `pnpm test:startup:bench:save`
-- `pnpm test:startup:bench:update`
-- `pnpm test:startup:bench:check`
-- `pnpm tsx scripts/bench-cli-startup.ts`
-- `pnpm tsx scripts/bench-cli-startup.ts --runs 12`
-- `pnpm tsx scripts/bench-cli-startup.ts --preset real`
-- `pnpm tsx scripts/bench-cli-startup.ts --preset real --case status --case gatewayStatus --runs 3`
-- `pnpm tsx scripts/bench-cli-startup.ts --preset real --case tasksJson --case tasksListJson --case tasksAuditJson --runs 3`
-- `pnpm tsx scripts/bench-cli-startup.ts --entry fengming.mjs --entry-secondary dist/entry.js --preset all`
-- `pnpm tsx scripts/bench-cli-startup.ts --preset all --output .artifacts/cli-startup-bench-all.json`
-- `pnpm tsx scripts/bench-cli-startup.ts --preset real --case gatewayStatusJson --output .artifacts/cli-startup-bench-smoke.json`
-- `pnpm tsx scripts/bench-cli-startup.ts --preset real --cpu-prof-dir .artifacts/cli-cpu`
-- `pnpm tsx scripts/bench-cli-startup.ts --json`
-
-Presets:
-
-- `startup`: `--version`, `--help`, `health`, `health --json`, `status --json`, `status`
-- `real`: `health`, `status`, `status --json`, `sessions`, `sessions --json`, `tasks --json`, `tasks list --json`, `tasks audit --json`, `agents list --json`, `gateway status`, `gateway status --json`, `gateway health --json`, `config get gateway.port`
-- `all`: both presets
-
-Output includes `sampleCount`, avg, p50, p95, min/max, exit-code/signal distribution, and max RSS summaries for each command. Optional `--cpu-prof-dir` / `--heap-prof-dir` writes V8 profiles per run so timing and profile capture use the same harness.
-
-Saved output conventions:
-
-- `pnpm test:startup:bench:smoke` writes the targeted smoke artifact at `.artifacts/cli-startup-bench-smoke.json`
-- `pnpm test:startup:bench:save` writes the full-suite artifact at `.artifacts/cli-startup-bench-all.json` using `runs=5` and `warmup=1`
-- `pnpm test:startup:bench:update` refreshes the checked-in baseline fixture at `test/fixtures/cli-startup-bench.json` using `runs=5` and `warmup=1`
-
-Checked-in fixture:
-
-- `test/fixtures/cli-startup-bench.json`
-- Refresh with `pnpm test:startup:bench:update`
-- Compare current results against the fixture with `pnpm test:startup:bench:check`
-
-## Gateway startup bench
-
-Script: [`scripts/bench-gateway-startup.ts`](https://github.com/fengming/fengming/blob/main/scripts/bench-gateway-startup.ts)
-
-The benchmark defaults to the built CLI entry at `dist/entry.js`; run
-`pnpm build` before using the package-script commands. To measure the source
-runner instead, pass `--entry scripts/run-node.mjs` and keep those results
-separate from built-entry baselines.
-
-Usage:
-
-- `pnpm test:startup:gateway -- --runs 5 --warmup 1`
-- `pnpm test:startup:gateway -- --case default --runs 10 --warmup 1`
-- `pnpm test:startup:gateway -- --case skipChannels --case fiftyPlugins --runs 5`
-- `node --import tsx scripts/bench-gateway-startup.ts --case default --runs 5 --output .artifacts/gateway-startup.json`
-- `node --import tsx scripts/bench-gateway-startup.ts --case default --runs 3 --cpu-prof-dir .artifacts/gateway-startup-cpu`
-
-Case ids:
-
-- `default`: normal Gateway startup.
-- `skipChannels`: Gateway startup with channel startup skipped.
-- `oneInternalHook`: one configured internal hook.
-- `allInternalHooks`: all internal hooks.
-- `fiftyPlugins`: 50 manifest plugins.
-- `fiftyStartupLazyPlugins`: 50 startup-lazy manifest plugins.
-
-Output includes first process output, `/healthz`, `/readyz`, HTTP listen log time,
-Gateway ready log time, CPU time, CPU core ratio, max RSS, heap, startup trace
-metrics, event-loop delay, and plugin lookup-table detail metrics. The script
-enables `FENGMING_GATEWAY_STARTUP_TRACE=1` in the child Gateway environment.
-
-Read `/healthz` as liveness: the HTTP server can answer. Read `/readyz` as
-usable readiness: startup plugin sidecars, channels, and ready-critical
-post-attach work have settled. Gateway startup hooks are dispatched
-asynchronously and are not part of the readiness guarantee. Ready log time is the
-Gateway's internal ready log timestamp; it is useful for process-side
-attribution but is not a substitute for the external `/readyz` probe.
-
-Use JSON output or `--output` when comparing changes. Use `--cpu-prof-dir` only
-after the trace output points at import, compile, or CPU-bound work that cannot
-be explained from phase timings alone. Do not compare source-runner results with
-built `dist/entry.js` results as the same baseline.
-
-## Gateway restart bench
-
-Script: [`scripts/bench-gateway-restart.ts`](https://github.com/fengming/fengming/blob/main/scripts/bench-gateway-restart.ts)
-
-The restart benchmark is supported on macOS and Linux only. It uses SIGUSR1 for
-in-process restarts and fails immediately on Windows.
-
-The benchmark defaults to the built CLI entry at `dist/entry.js`; run
-`pnpm build` before using the package-script commands. To measure the source
-runner instead, pass `--entry scripts/run-node.mjs` and keep those results
-separate from built-entry baselines.
-
-Usage:
-
-- `pnpm test:restart:gateway -- --case skipChannels --runs 1 --restarts 5`
-- `pnpm test:restart:gateway -- --case default --runs 3 --restarts 3 --warmup 1`
-- `pnpm test:restart:gateway -- --case skipChannelsAcpxProbe --case skipChannelsNoAcpxProbe --runs 1 --restarts 5`
-- `node --import tsx scripts/bench-gateway-restart.ts --case fiftyPlugins --runs 1 --restarts 5 --output .artifacts/gateway-restart.json`
-- `node --import tsx scripts/bench-gateway-restart.ts --json`
-
-Case ids:
-
-- `skipChannels`: restart with channels skipped.
-- `skipChannelsAcpxProbe`: restart with channels skipped and ACPX startup probe on.
-- `skipChannelsNoAcpxProbe`: restart with channels skipped and ACPX startup probe off.
-- `default`: normal restart.
-- `fiftyPlugins`: restart with 50 manifest plugins.
-
-Output includes next `/healthz`, next `/readyz`, downtime, restart ready timing,
-CPU, RSS, startup trace metrics for the replacement process, and restart trace
-metrics for signal handling, active-work drain, close phases, next start, ready
-timing, and memory snapshots. The script enables
-`FENGMING_GATEWAY_STARTUP_TRACE=1` and `FENGMING_GATEWAY_RESTART_TRACE=1` in the
-child Gateway environment.
-
-Use this benchmark when a change touches restart signaling, close handlers,
-startup-after-restart, sidecar shutdown, service handoff, or readiness after
-restart. Start with `skipChannels` when isolating Gateway mechanics from channel
-startup. Use `default` or plugin-heavy cases only after the narrow case explains
-the restart path.
-
-Trace metrics are attribution hints, not verdicts. A restart change should be
-judged from multiple samples, the matching owner span, `/healthz` and `/readyz`
-behavior, and the user-visible restart contract.
-
-## Onboarding E2E (Docker)
-
-Docker is optional; this is only needed for containerized onboarding smoke tests.
-
-Full cold-start flow in a clean Linux container:
-
-```bash
-scripts/e2e/onboard-docker.sh
-```
-
-This script drives the interactive wizard via a pseudo-tty, verifies config/workspace/session files, then starts the gateway and runs `fengming health`.
-
-## QR import smoke (Docker)
-
-Ensures the maintained QR runtime helper loads under the supported Docker Node runtimes (Node 24 default, Node 22 compatible):
-
-```bash
-pnpm test:docker:qr
-```
-
-## Related
-
-- [Testing](/help/testing)
-- [Testing live](/help/testing-live)
-- [Testing updates and plugins](/help/testing-updates-plugins)

package/docs/reference/token-use.md

@@ -1,246 +0,0 @@
----
-summary: "How FengMing builds prompt context and reports token usage + costs"
-read_when:
-  - Explaining token usage, costs, or context windows
-  - Debugging context growth or compaction behavior
-title: "Token use and costs"
----
-
-FengMing tracks **tokens**, not characters. Tokens are model-specific, but most
-OpenAI-style models average ~4 characters per token for English text.
-
-## How the system prompt is built
-
-FengMing assembles its own system prompt on every run. It includes:
-
-- Tool list + short descriptions
-- Skills list (only metadata; instructions are loaded on demand with `read`).
-  Native Codex turns receive the compact skills block as turn-scoped
-  collaboration developer instructions; other harnesses receive it in the normal
-  prompt surface. It is bounded by `skills.limits.maxSkillsPromptChars`, with
-  optional per-agent override at `agents.list[].skillsLimits.maxSkillsPromptChars`.
-- Self-update instructions
-- Workspace + bootstrap files (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md` when new, plus `MEMORY.md` when present). Native Codex turns do not paste raw `MEMORY.md` from the configured agent workspace when memory tools are available for that workspace; they include a small memory pointer in turn-scoped collaboration developer instructions and use memory tools on demand. If tools are disabled, memory search is unavailable, or the active workspace differs from the agent memory workspace, `MEMORY.md` uses the normal bounded turn-context path. Lowercase root `memory.md` is not injected; it is legacy repair input for `fengming doctor --fix` when paired with `MEMORY.md`. Large injected files are truncated by `agents.defaults.bootstrapMaxChars` (default: 12000), and total bootstrap injection is capped by `agents.defaults.bootstrapTotalMaxChars` (default: 60000). `memory/*.md` daily files are not part of the normal bootstrap prompt; they remain on-demand via memory tools on ordinary turns, but reset/startup model runs can prepend a one-shot startup-context block with recent daily memory for that first turn. Bare chat `/new` and `/reset` commands are acknowledged without invoking the model. The startup prelude is controlled by `agents.defaults.startupContext`. Post-compaction AGENTS.md excerpts are separate and require explicit `agents.defaults.compaction.postCompactionSections` opt-in.
-- Time (UTC + user timezone)
-- Reply tags + heartbeat behavior
-- Runtime metadata (host/OS/model/thinking)
-
-See the full breakdown in [System Prompt](/concepts/system-prompt).
-
-When documenting credentials or auth snippets, use the
-[Secret Placeholder Conventions](/reference/secret-placeholder-conventions) to
-avoid secret-scanner false positives in docs-only changes.
-
-## What counts in the context window
-
-Everything the model receives counts toward the context limit:
-
-- System prompt (all sections listed above)
-- Conversation history (user + assistant messages)
-- Tool calls and tool results
-- Attachments/transcripts (images, audio, files)
-- Compaction summaries and pruning artifacts
-- Provider wrappers or safety headers (not visible, but still counted)
-
-Some runtime-heavy surfaces have their own explicit caps:
-
-- `agents.defaults.contextLimits.memoryGetMaxChars`
-- `agents.defaults.contextLimits.memoryGetDefaultLines`
-- `agents.defaults.contextLimits.toolResultMaxChars`
-- `agents.defaults.contextLimits.postCompactionMaxChars`
-
-Per-agent overrides live under `agents.list[].contextLimits`. These knobs are
-for bounded runtime excerpts and injected runtime-owned blocks. They are
-separate from bootstrap limits, startup-context limits, and skills prompt
-limits.
-
-`toolResultMaxChars` is an advanced ceiling. When it is unset, FengMing chooses
-the live tool-result cap from the effective model context window: `16000` chars
-below 100K tokens, `32000` chars at 100K+ tokens, and `64000` chars at 200K+
-tokens, still bounded by the runtime context-share guard.
-
-For images, FengMing downscales transcript/tool image payloads before provider calls.
-Use `agents.defaults.imageMaxDimensionPx` (default: `1200`) to tune this:
-
-- Lower values usually reduce vision-token usage and payload size.
-- Higher values preserve more visual detail for OCR/UI-heavy screenshots.
-
-For a practical breakdown (per injected file, tools, skills, and system prompt size), use `/context list` or `/context detail`. See [Context](/concepts/context).
-
-## How to see current token usage
-
-Use these in chat:
-
-- `/status` → **emoji-rich status card** with the session model, context usage,
-  last response input/output tokens, and **estimated cost** when local pricing is
-  configured for the active model.
-- `/usage off|tokens|full` → appends a **per-response usage footer** to every reply.
-  - Persists per session (stored as `responseUsage`).
-  - `/usage full` shows estimated cost only when FengMing has usage metadata and
-    local pricing for the active model. Otherwise it shows tokens only.
-- `/usage cost` → shows a local cost summary from FengMing session logs.
-
-Other surfaces:
-
-- **TUI/Web TUI:** `/status` + `/usage` are supported.
-- **CLI:** `fengming status --usage` and `fengming channels list` show
-  normalized provider quota windows (`X% left`, not per-response costs).
-  Current usage-window providers: Anthropic, GitHub Copilot, Gemini CLI,
-  OpenAI Codex, MiniMax, Xiaomi, and z.ai.
-
-Usage surfaces normalize common provider-native field aliases before display.
-For OpenAI-family Responses traffic, that includes both `input_tokens` /
-`output_tokens` and `prompt_tokens` / `completion_tokens`, so transport-specific
-field names do not change `/status`, `/usage`, or session summaries.
-Gemini CLI JSON usage is normalized too: reply text comes from `response`, and
-`stats.cached` maps to `cacheRead` with `stats.input_tokens - stats.cached`
-used when the CLI omits an explicit `stats.input` field.
-For native OpenAI-family Responses traffic, WebSocket/SSE usage aliases are
-normalized the same way, and totals fall back to normalized input + output when
-`total_tokens` is missing or `0`.
-When the current session snapshot is sparse, `/status` and `session_status` can
-also recover token/cache counters and the active runtime model label from the
-most recent transcript usage log. Existing nonzero live values still take
-precedence over transcript fallback values, and larger prompt-oriented
-transcript totals can win when stored totals are missing or smaller.
-Usage auth for provider quota windows comes from provider-specific hooks when
-available; otherwise FengMing falls back to matching OAuth/API-key credentials
-from auth profiles, env, or config.
-Assistant transcript entries persist the same normalized usage shape, including
-`usage.cost` when the active model has pricing configured and the provider
-returns usage metadata. This gives `/usage cost` and transcript-backed session
-status a stable source even after the live runtime state is gone.
-
-FengMing keeps provider usage accounting separate from the current context
-snapshot. Provider `usage.total` can include cached input, output, and multiple
-tool-loop model calls, so it is useful for cost and telemetry but can overstate
-the live context window. Context displays and diagnostics use the latest prompt
-snapshot (`promptTokens`, or the last model call when no prompt snapshot is
-available) for `context.used`.
-
-## Cost estimation (when shown)
-
-Costs are estimated from your model pricing config:
-
-```
-models.providers.<provider>.models[].cost
-```
-
-These are **USD per 1M tokens** for `input`, `output`, `cacheRead`, and
-`cacheWrite`. If pricing is missing, FengMing shows tokens only. Cost display is
-not limited to API-key auth: non-API-key providers such as `aws-sdk` can show
-estimated cost when their configured model entry includes local pricing and the
-provider returns usage metadata.
-
-After sidecars and channels reach the Gateway ready path, FengMing starts an
-optional background pricing bootstrap for configured model refs that do not
-already have local pricing. That bootstrap fetches remote OpenRouter and LiteLLM
-pricing catalogs. Set `models.pricing.enabled: false` to skip those catalog
-fetches on offline or restricted networks; explicit
-`models.providers.*.models[].cost` entries continue to drive local cost
-estimates.
-
-## Cache TTL and pruning impact
-
-Provider prompt caching only applies within the cache TTL window. FengMing can
-optionally run **cache-ttl pruning**: it prunes the session once the cache TTL
-has expired, then resets the cache window so subsequent requests can re-use the
-freshly cached context instead of re-caching the full history. This keeps cache
-write costs lower when a session goes idle past the TTL.
-
-Configure it in [Gateway configuration](/gateway/configuration) and see the
-behavior details in [Session pruning](/concepts/session-pruning).
-
-Heartbeat can keep the cache **warm** across idle gaps. If your model cache TTL
-is `1h`, setting the heartbeat interval just under that (e.g., `55m`) can avoid
-re-caching the full prompt, reducing cache write costs.
-
-In multi-agent setups, you can keep one shared model config and tune cache behavior
-per agent with `agents.list[].params.cacheRetention`.
-
-For a full knob-by-knob guide, see [Prompt Caching](/reference/prompt-caching).
-
-For Anthropic API pricing, cache reads are significantly cheaper than input
-tokens, while cache writes are billed at a higher multiplier. See Anthropic's
-prompt caching pricing for the latest rates and TTL multipliers:
-[https://docs.anthropic.com/docs/build-with-claude/prompt-caching](https://docs.anthropic.com/docs/build-with-claude/prompt-caching)
-
-### Example: keep 1h cache warm with heartbeat
-
-```yaml
-agents:
-  defaults:
-    model:
-      primary: "anthropic/claude-opus-4-6"
-    models:
-      "anthropic/claude-opus-4-6":
-        params:
-          cacheRetention: "long"
-    heartbeat:
-      every: "55m"
-```
-
-### Example: mixed traffic with per-agent cache strategy
-
-```yaml
-agents:
-  defaults:
-    model:
-      primary: "anthropic/claude-opus-4-6"
-    models:
-      "anthropic/claude-opus-4-6":
-        params:
-          cacheRetention: "long" # default baseline for most agents
-  list:
-    - id: "research"
-      default: true
-      heartbeat:
-        every: "55m" # keep long cache warm for deep sessions
-    - id: "alerts"
-      params:
-        cacheRetention: "none" # avoid cache writes for bursty notifications
-```
-
-`agents.list[].params` merges on top of the selected model's `params`, so you can
-override only `cacheRetention` and inherit other model defaults unchanged.
-
-### Anthropic 1M context
-
-FengMing sizes GA-capable Claude 4.x models such as Opus 4.8, Opus 4.7, Opus 4.6, and
-Sonnet 4.6 with Anthropic's 1M context window. You do not need
-`params.context1m: true` for those models.
-
-```yaml
-agents:
-  defaults:
-    models:
-      "anthropic/claude-opus-4-6":
-        alias: opus
-```
-
-Older configs can keep `context1m: true`, but FengMing no longer sends
-Anthropic's retired `context-1m-2025-08-07` beta header for this setting and
-does not expand unsupported older Claude models to 1M.
-
-Requirement: the credential must be eligible for long-context usage. If not,
-Anthropic responds with a provider-side rate limit error for that request.
-
-If you authenticate Anthropic with OAuth/subscription tokens (`sk-ant-oat-*`),
-FengMing preserves the OAuth-required Anthropic beta headers while stripping the
-retired `context-1m-*` beta if it remains in older config.
-
-## Tips for reducing token pressure
-
-- Use `/compact` to summarize long sessions.
-- Trim large tool outputs in your workflows.
-- Lower `agents.defaults.imageMaxDimensionPx` for screenshot-heavy sessions.
-- Keep skill descriptions short (skill list is injected into the prompt).
-- Prefer smaller models for verbose, exploratory work.
-
-See [Skills](/tools/skills) for the exact skill list overhead formula.
-
-## Related
-
-- [API usage and costs](/reference/api-usage-costs)
-- [Prompt caching](/reference/prompt-caching)
-- [Usage tracking](/concepts/usage-tracking)