fengming 0.3.10 → 0.3.12

package/docs/concepts/qa-matrix.md

@@ -1,139 +0,0 @@
----
-summary: "Maintainer reference for the Docker-backed Matrix live QA lane: CLI, profiles, env vars, scenarios, and output artifacts."
-read_when:
-  - Running pnpm fengming qa matrix locally
-  - Adding or selecting Matrix QA scenarios
-  - Triaging Matrix QA failures, timeouts, or stuck cleanup
-title: "Matrix QA"
----
-
-The Matrix QA lane runs the bundled `@fengming/matrix` plugin against a disposable Tuwunel homeserver in Docker, with temporary driver, SUT, and observer accounts plus seeded rooms. It is the live transport-real coverage for Matrix.
-
-This is maintainer-only tooling. Packaged FengMing releases intentionally omit `qa-lab`, so `fengming qa` is only available from a source checkout. Source checkouts load the bundled runner directly - no plugin install step is needed.
-
-For broader QA framework context, see [QA overview](/concepts/qa-e2e-automation).
-
-## Quick start
-
-```bash
-pnpm fengming qa matrix --profile fast --fail-fast
-```
-
-Plain `pnpm fengming qa matrix` runs `--profile all` and does not stop on first failure. Use `--profile fast --fail-fast` for a release gate; shard the catalog with `--profile transport|media|e2ee-smoke|e2ee-deep|e2ee-cli` when running the full inventory in parallel.
-
-## What the lane does
-
-1. Provisions a disposable Tuwunel homeserver in Docker (default image `ghcr.io/matrix-construct/tuwunel:v1.5.1`, server name `matrix-qa.test`, port `28008`).
-2. Registers three temporary users - `driver` (sends inbound traffic), `sut` (the FengMing Matrix account under test), `observer` (third-party traffic capture).
-3. Seeds rooms required by the selected scenarios (main, threading, media, restart, secondary, allowlist, E2EE, verification DM, etc.).
-4. Starts a child FengMing gateway with the real Matrix plugin scoped to the SUT account; `qa-channel` is not loaded in the child.
-5. Runs scenarios in sequence, observing events through the driver/observer Matrix clients.
-6. Tears down the homeserver, writes report and summary artifacts, then exits.
-
-## CLI
-
-```text
-pnpm fengming qa matrix [options]
-```
-
-### Common flags
-
-| Flag                  | Default                                       | Description                                                                                                            |
-| --------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| `--profile <profile>` | `all`                                         | Scenario profile. See [Profiles](#profiles).                                                                           |
-| `--fail-fast`         | off                                           | Stop after the first failed check or scenario.                                                                         |
-| `--scenario <id>`     | -                                             | Run only this scenario. Repeatable. See [Scenarios](#scenarios).                                                       |
-| `--output-dir <path>` | `<repo>/.artifacts/qa-e2e/matrix-<timestamp>` | Where reports, summary, observed events, and the output log are written. Relative paths resolve against `--repo-root`. |
-| `--repo-root <path>`  | `process.cwd()`                               | Repository root when invoking from a neutral working directory.                                                        |
-| `--sut-account <id>`  | `sut`                                         | Matrix account id inside the QA gateway config.                                                                        |
-
-### Provider flags
-
-The lane uses a real Matrix transport but the model provider is configurable:
-
-| Flag                     | Default          | Description                                                                                                                               |
-| ------------------------ | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| `--provider-mode <mode>` | `live-frontier`  | `mock-openai` for deterministic mock dispatch or `live-frontier` for live frontier providers. The legacy alias `live-openai` still works. |
-| `--model <ref>`          | provider default | Primary `provider/model` ref.                                                                                                             |
-| `--alt-model <ref>`      | provider default | Alternate `provider/model` ref where scenarios switch mid-run.                                                                            |
-| `--fast`                 | off              | Enable provider fast mode where supported.                                                                                                |
-
-Matrix QA does not accept `--credential-source` or `--credential-role`. The lane provisions disposable users locally; there is no shared credential pool to lease against.
-
-## Profiles
-
-The selected profile decides which scenarios run.
-
-| Profile         | Use it for                                                                                                                                                                                                                           |
-| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `all` (default) | Full catalog. Slow but exhaustive.                                                                                                                                                                                                   |
-| `fast`          | Release-gate subset that exercises the live transport contract: canary, mention gating, allowlist block, reply shape, restart resume, thread follow-up, thread isolation, reaction observation, and exec approval metadata delivery. |
-| `transport`     | Transport-level threading, DM, room, autojoin, mention/allowlist, approval, and reaction scenarios.                                                                                                                                  |
-| `media`         | Image, audio, video, PDF, EPUB attachment coverage.                                                                                                                                                                                  |
-| `e2ee-smoke`    | Minimum E2EE coverage - basic encrypted reply, thread follow-up, bootstrap success.                                                                                                                                                  |
-| `e2ee-deep`     | Exhaustive E2EE state-loss, backup, key, and recovery scenarios.                                                                                                                                                                     |
-| `e2ee-cli`      | `fengming matrix encryption setup` and `verify *` CLI scenarios driven through the QA harness.                                                                                                                                       |
-
-The exact mapping lives in `extensions/qa-matrix/src/runners/contract/scenario-catalog.ts`.
-
-## Scenarios
-
-The full scenario id list is the `MatrixQaScenarioId` union in `extensions/qa-matrix/src/runners/contract/scenario-catalog.ts:15`. Categories include:
-
-- threading - `matrix-thread-*`, `matrix-subagent-thread-spawn`
-- top-level / DM / room - `matrix-top-level-reply-shape`, `matrix-room-*`, `matrix-dm-*`
-- streaming and tool progress - `matrix-room-partial-streaming-preview`, `matrix-room-quiet-streaming-preview`, `matrix-room-tool-progress-*`, `matrix-room-block-streaming`
-- media - `matrix-media-type-coverage`, `matrix-room-image-understanding-attachment`, `matrix-attachment-only-ignored`, `matrix-unsupported-media-safe`
-- routing - `matrix-room-autojoin-invite`, `matrix-secondary-room-*`
-- reactions - `matrix-reaction-*`
-- approvals - `matrix-approval-*` (exec/plugin metadata, chunked fallback, deny reactions, threads, and `target: "both"` routing)
-- restart and replay - `matrix-restart-*`, `matrix-stale-sync-replay-dedupe`, `matrix-room-membership-loss`, `matrix-homeserver-restart-resume`, `matrix-initial-catchup-then-incremental`
-- mention gating, bot-to-bot, and allowlists - `matrix-mention-*`, `matrix-allowbots-*`, `matrix-allowlist-*`, `matrix-multi-actor-ordering`, `matrix-inbound-edit-*`, `matrix-mxid-prefixed-command-block`, `matrix-observer-allowlist-override`
-- E2EE - `matrix-e2ee-*` (basic reply, thread follow-up, bootstrap, recovery key lifecycle, state-loss variants, server backup behavior, device hygiene, SAS / QR / DM verification, restart, artifact redaction)
-- E2EE CLI - `matrix-e2ee-cli-*` (encryption setup, idempotent setup, bootstrap failure, recovery-key lifecycle, multi-account, gateway-reply round-trip, self-verification)
-
-Pass `--scenario <id>` (repeatable) to run a hand-picked set; combine with `--profile all` to ignore profile gating.
-
-## Environment variables
-
-| Variable                                | Default                                   | Effect                                                                                                                                                                                         |
-| --------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `FENGMING_QA_MATRIX_TIMEOUT_MS`         | `1800000` (30 min)                        | Hard upper bound on the entire run.                                                                                                                                                            |
-| `FENGMING_QA_MATRIX_CANARY_TIMEOUT_MS`  | `45000`                                   | Bound for the initial canary reply. Release CI raises this on shared runners so a slow first gateway turn does not fail before scenario coverage starts.                                       |
-| `FENGMING_QA_MATRIX_NO_REPLY_WINDOW_MS` | `8000`                                    | Quiet window for negative no-reply assertions. Clamped to `≤` the run timeout.                                                                                                                 |
-| `FENGMING_QA_MATRIX_CLEANUP_TIMEOUT_MS` | `90000`                                   | Bound for Docker teardown. Failure surfaces include the recovery `docker compose ... down --remove-orphans` command.                                                                           |
-| `FENGMING_QA_MATRIX_TUWUNEL_IMAGE`      | `ghcr.io/matrix-construct/tuwunel:v1.5.1` | Override the homeserver image when validating against a different Tuwunel version.                                                                                                             |
-| `FENGMING_QA_MATRIX_PROGRESS`           | on                                        | `0` silences `[matrix-qa] ...` progress lines on stderr. `1` forces them on.                                                                                                                   |
-| `FENGMING_QA_MATRIX_CAPTURE_CONTENT`    | redacted                                  | `1` keeps message body and `formatted_body` in `matrix-qa-observed-events.json`. Default redacts to keep CI artifacts safe.                                                                    |
-| `FENGMING_QA_MATRIX_DISABLE_FORCE_EXIT` | off                                       | `1` skips the deterministic `process.exit` after artifact write. The default forces exit because matrix-js-sdk's native crypto handles can keep the event loop alive past artifact completion. |
-| `FENGMING_RUN_NODE_OUTPUT_LOG`          | unset                                     | When set by an outer launcher (e.g. `scripts/run-node.mjs`), Matrix QA reuses that log path instead of starting its own tee.                                                                   |
-
-## Output artifacts
-
-Written to `--output-dir`:
-
-- `matrix-qa-report.md` - Markdown protocol report (what passed, failed, was skipped, and why).
-- `matrix-qa-summary.json` - Structured summary suitable for CI parsing and dashboards.
-- `matrix-qa-observed-events.json` - Observed Matrix events from the driver and observer clients. Bodies are redacted unless `FENGMING_QA_MATRIX_CAPTURE_CONTENT=1`; approval metadata is summarized with selected safe fields and truncated command preview.
-- `matrix-qa-output.log` - Combined stdout/stderr from the run. If `FENGMING_RUN_NODE_OUTPUT_LOG` is set, the outer launcher's log is reused instead.
-
-The default output dir is `<repo>/.artifacts/qa-e2e/matrix-<timestamp>` so successive runs do not overwrite each other.
-
-## Triage tips
-
-- **Run hangs near the end:** `matrix-js-sdk` native crypto handles can outlive the harness. The default forces a clean `process.exit` after artifact write; if you have unset `FENGMING_QA_MATRIX_DISABLE_FORCE_EXIT=1`, expect the process to linger.
-- **Cleanup error:** look for the printed recovery command (a `docker compose ... down --remove-orphans` invocation) and run it manually to release the homeserver port.
-- **Flaky negative-assertion windows in CI:** lower `FENGMING_QA_MATRIX_NO_REPLY_WINDOW_MS` (default 8 s) when CI is fast; raise it on slow shared runners.
-- **Need redacted bodies for a bug report:** rerun with `FENGMING_QA_MATRIX_CAPTURE_CONTENT=1` and attach `matrix-qa-observed-events.json`. Treat the resulting artifact as sensitive.
-- **Different Tuwunel version:** point `FENGMING_QA_MATRIX_TUWUNEL_IMAGE` at the version under test. The lane checks in only the pinned default image.
-
-## Live transport contract
-
-Matrix is one of three live transport lanes (Matrix, Telegram, Discord) that share a single contract checklist defined in [QA overview → Live transport coverage](/concepts/qa-e2e-automation#live-transport-coverage). `qa-channel` remains the broad synthetic suite and is intentionally not part of that matrix.
-
-## Related
-
-- [QA overview](/concepts/qa-e2e-automation) - overall QA stack and live transport contract
-- [QA Channel](/channels/qa-channel) - synthetic channel adapter for repo-backed scenarios
-- [Testing](/help/testing) - running tests and adding QA coverage
-- [Matrix](/channels/matrix) - the channel plugin under test

package/docs/concepts/queue-steering.md

@@ -1,90 +0,0 @@
----
-summary: "How active-run steering queues messages at runtime boundaries"
-read_when:
-  - Explaining how steer behaves while an agent is using tools
-  - Changing active-run queue behavior or runtime steering integration
-  - Comparing steering with followup, collect, and interrupt queue modes
-title: "Steering queue"
----
-
-When a normal prompt arrives while a session run is already streaming, FengMing
-tries to send that prompt into the active runtime by default when the queue mode
-is `steer`. No config entry and no queue directive are required for that default
-behavior. FengMing and the native Codex app-server harness implement the delivery
-details differently.
-
-## Runtime boundary
-
-Steering does not interrupt a tool call that is already running. FengMing checks for
-queued steering messages at model boundaries:
-
-1. The assistant asks for tool calls.
-2. FengMing executes the current assistant message's tool-call batch.
-3. FengMing emits the turn end event.
-4. FengMing drains queued steering messages.
-5. FengMing appends those messages as user messages before the next LLM call.
-
-This keeps tool results paired with the assistant message that requested them,
-then lets the next model call see the latest user input.
-
-The native Codex app-server harness exposes `turn/steer` instead of FengMing runtime's
-internal steering queue. FengMing batches queued prompts for the configured
-quiet window, then sends a single `turn/steer` request with all collected user
-input in arrival order.
-
-Codex review and manual compaction turns reject same-turn steering. When a
-runtime cannot accept steering in `steer` mode, FengMing waits for the active
-run to finish before starting the prompt.
-
-This page explains queue-mode steering for normal inbound messages when the mode
-is `steer`. If the mode is `followup` or `collect`, normal messages do not enter
-this steering path; they wait until the active run finishes. For the explicit
-`/steer <message>` command, see [Steer](/tools/steer).
-
-## Modes
-
-| Mode        | Active-run behavior                                    | Later behavior                                                                      |
-| ----------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------- |
-| `steer`     | Steers the prompt into the active runtime when it can. | Waits for the active run to finish if steering is unavailable.                      |
-| `followup`  | Does not steer.                                        | Runs queued messages later after the active run ends.                               |
-| `collect`   | Does not steer.                                        | Coalesces compatible queued messages into one later turn after the debounce window. |
-| `interrupt` | Aborts the active run instead of steering it.          | Starts the newest message after aborting.                                           |
-
-## Burst example
-
-If four users send messages while the agent is executing a tool call:
-
-- With default behavior, the active runtime receives all four messages in
-  arrival order before its next model decision. FengMing drains them at the next model
-  boundary; Codex receives them as one batched `turn/steer`.
-- With `/queue collect`, FengMing does not steer. It waits until the active run
-  ends, then creates a followup turn with compatible queued messages after the
-  debounce window.
-- With `/queue interrupt`, FengMing aborts the active run and starts the newest
-  message instead of steering.
-
-## Scope
-
-Steering always targets the current active session run. It does not create a new
-session, change the active run's tool policy, or split messages by sender. In
-multi-user channels, inbound prompts already include sender and route context, so
-the next model call can see who sent each message.
-
-Use `followup` or `collect` when you want messages to queue by default instead
-of steering the active run. Use `interrupt` when the newest prompt should
-replace the active run.
-
-## Debounce
-
-`messages.queue.debounceMs` applies to queued `followup` and `collect` delivery.
-In `steer` mode with the native Codex harness, it also sets the quiet window
-before sending batched `turn/steer`. For FengMing, active steering itself does not use
-the debounce timer because FengMing naturally batches messages until the next model
-boundary.
-
-## Related
-
-- [Command queue](/concepts/queue)
-- [Steer](/tools/steer)
-- [Messages](/concepts/messages)
-- [Agent loop](/concepts/agent-loop)

package/docs/concepts/queue.md

@@ -1,136 +0,0 @@
----
-summary: "Auto-reply queue modes, defaults, and per-session overrides"
-read_when:
-  - Changing auto-reply execution or concurrency
-  - Explaining /queue modes or message steering behavior
-title: "Command queue"
----
-
-We serialize inbound auto-reply runs (all channels) through a tiny in-process queue to prevent multiple agent runs from colliding, while still allowing safe parallelism across sessions.
-
-## Why
-
-- Auto-reply runs can be expensive (LLM calls) and can collide when multiple inbound messages arrive close together.
-- Serializing avoids competing for shared resources (session files, logs, CLI stdin) and reduces the chance of upstream rate limits.
-
-## How it works
-
-- A lane-aware FIFO queue drains each lane with a configurable concurrency cap (default 1 for unconfigured lanes; main defaults to 4, subagent to 8).
-- `runEmbeddedAgent` enqueues by **session key** (lane `session:<key>`) to guarantee only one active run per session.
-- Each session run is then queued into a **global lane** (`main` by default) so overall parallelism is capped by `agents.defaults.maxConcurrent`.
-- When verbose logging is enabled, queued runs emit a short notice if they waited more than ~2s before starting.
-- Typing indicators still fire immediately on enqueue (when supported by the channel) so user experience is unchanged while we wait our turn.
-
-## Defaults
-
-When unset, all inbound channel surfaces use:
-
-- `mode: "steer"`
-- `debounceMs: 500`
-- `cap: 20`
-- `drop: "summarize"`
-
-Same-turn steering is the default. A prompt that arrives mid-run is injected
-into the active runtime when the run can accept steering, so no second session
-run is started. If the active run cannot accept steering, FengMing waits for the
-active run to finish before starting the prompt.
-
-## Queue modes
-
-`/queue` controls what normal inbound messages do while a session already has
-an active run:
-
-- `steer`: inject messages into the active runtime. FengMing delivers all pending steering messages **after the current assistant turn finishes executing its tool calls**, before the next LLM call; Codex app-server receives one batched `turn/steer`. If the run is not actively streaming or steering is unavailable, FengMing waits until the active run ends before starting the prompt.
-- `followup`: do not steer. Enqueue each message for a later agent turn after the current run ends.
-- `collect`: do not steer. Coalesce queued messages into a **single** followup turn after the quiet window. If messages target different channels/threads, they drain individually to preserve routing.
-- `interrupt`: abort the active run for that session, then run the newest message.
-
-For runtime-specific timing and dependency behavior, see
-[Steering queue](/concepts/queue-steering). For the explicit `/steer <message>`
-command, see [Steer](/tools/steer).
-
-Configure globally or per channel via `messages.queue`:
-
-```json5
-{
-  messages: {
-    queue: {
-      mode: "steer",
-      debounceMs: 500,
-      cap: 20,
-      drop: "summarize",
-      byChannel: { discord: "collect" },
-    },
-  },
-}
-```
-
-## Queue options
-
-Options apply to queued delivery. `debounceMs` also sets the Codex steering
-quiet window in `steer` mode:
-
-- `debounceMs`: quiet window before draining queued followups or collect batches; in Codex `steer` mode, quiet window before sending batched `turn/steer`. Bare numbers are milliseconds; units `ms`, `s`, `m`, `h`, and `d` are accepted by `/queue` options.
-- `cap`: max queued messages per session. Values below `1` are ignored.
-- `drop: "summarize"`: default. Drop the oldest queued entries as needed, keep compact summaries, and inject them as a synthetic followup prompt.
-- `drop: "old"`: drop the oldest queued entries as needed, without preserving summaries.
-- `drop: "new"`: reject the newest message when the queue is already full.
-
-Defaults: `debounceMs: 500`, `cap: 20`, `drop: summarize`.
-
-## Steer and streaming
-
-When channel streaming is `partial` or `block`, steering can look like several
-short visible replies while the active run reaches runtime boundaries:
-
-- `partial`: the preview may finalize early, then a new preview starts after
-  steering is accepted.
-- `block`: draft-sized blocks can create the same sequential appearance.
-- Without streaming, steering falls back to a followup after the active run when
-  the runtime cannot accept same-turn steering.
-
-`steer` does not abort in-flight tools. Use `/queue interrupt` when the newest
-message should abort the current run.
-
-## Precedence
-
-For mode selection, FengMing resolves:
-
-1. Inline or stored per-session `/queue` override.
-2. `messages.queue.byChannel.<channel>`.
-3. `messages.queue.mode`.
-4. Default `steer`.
-
-For options, inline or stored `/queue` options win over config. Then
-channel-specific debounce (`messages.queue.debounceMsByChannel`), plugin
-debounce defaults, global `messages.queue` options, and built-in defaults are
-applied. `cap` and `drop` are global/session options, not per-channel config
-keys.
-
-## Per-session overrides
-
-- Send `/queue <steer|followup|collect|interrupt>` as a standalone command to store the queue mode for the current session.
-- Options can be combined: `/queue collect debounce:0.5s cap:25 drop:summarize`
-- `/queue default` or `/queue reset` clears the session override.
-
-## Scope and guarantees
-
-- Applies to auto-reply agent runs across all inbound channels that use the gateway reply pipeline (WhatsApp web, Telegram, Slack, Discord, Signal, iMessage, webchat, etc.).
-- Default lane (`main`) is process-wide for inbound + main heartbeats; set `agents.defaults.maxConcurrent` to allow multiple sessions in parallel.
-- Additional lanes may exist (e.g. `cron`, `cron-nested`, `nested`, `subagent`) so background jobs can run in parallel without blocking inbound replies. Isolated cron agent turns hold a `cron` slot while their inner agent execution uses `cron-nested`; both use `cron.maxConcurrentRuns`. Shared non-cron `nested` flows keep their own lane behavior. These detached runs are tracked as [background tasks](/automation/tasks).
-- Per-session lanes guarantee that only one agent run touches a given session at a time.
-- No external dependencies or background worker threads; pure TypeScript + promises.
-
-## Troubleshooting
-
-- If commands seem stuck, enable verbose logs and look for "queued for ...ms" lines to confirm the queue is draining.
-- If you need queue depth, enable verbose logs and watch for queue timing lines.
-- Codex app-server runs that accept a turn and then stop emitting progress are interrupted by the Codex adapter so the active session lane can release instead of waiting for the outer run timeout.
-- When diagnostics are enabled, sessions that remain in `processing` past `diagnostics.stuckSessionWarnMs` with no observed reply, tool, status, block, or ACP progress are classified by current activity. Active work logs as `session.long_running`; active work with no recent progress logs as `session.stalled`; `session.stuck` is reserved for recoverable stale session bookkeeping, including idle queued sessions with stale ownerless model/tool activity, and only that path can release the affected session lane so queued work drains. Repeated `session.stuck` diagnostics back off while the session remains unchanged.
-
-## Related
-
-- [Session management](/concepts/session)
-- [Steering queue](/concepts/queue-steering)
-- [Steer](/tools/steer)
-- [Retry policy](/concepts/retry)

package/docs/concepts/retry.md

@@ -1,86 +0,0 @@
----
-summary: "Retry policy for outbound provider calls"
-read_when:
-  - Updating provider retry behavior or defaults
-  - Debugging provider send errors or rate limits
-title: "Retry policy"
----
-
-## Goals
-
-- Retry per HTTP request, not per multi-step flow.
-- Preserve ordering by retrying only the current step.
-- Avoid duplicating non-idempotent operations.
-
-## Defaults
-
-- Attempts: 3
-- Max delay cap: 30000 ms
-- Jitter: 0.1 (10 percent)
-- Provider defaults:
-  - Telegram min delay: 400 ms
-  - Discord min delay: 500 ms
-
-## Behavior
-
-### Model providers
-
-- FengMing lets provider SDKs handle normal short retries.
-- For Stainless-based SDKs such as Anthropic and OpenAI, retryable responses
-  (`408`, `409`, `429`, and `5xx`) can include `retry-after-ms` or
-  `retry-after`. When that wait is longer than 60 seconds, FengMing injects
-  `x-should-retry: false` so the SDK surfaces the error immediately and model
-  failover can rotate to another auth profile or fallback model.
-- Override the cap with `FENGMING_SDK_RETRY_MAX_WAIT_SECONDS=<seconds>`.
-  Set it to `0`, `false`, `off`, `none`, or `disabled` to let SDKs honor long
-  `Retry-After` sleeps internally.
-
-### Discord
-
-- Retries on rate-limit errors (HTTP 429), request timeouts, HTTP 5xx responses,
-  and transient transport failures such as DNS lookup failures, connection
-  resets, socket closes, and fetch failures.
-- Uses Discord `retry_after` when available, otherwise exponential backoff.
-
-### Telegram
-
-- Retries on transient errors (429, timeout, connect/reset/closed, temporarily unavailable).
-- Uses `retry_after` when available, otherwise exponential backoff.
-- Markdown parse errors are not retried; they fall back to plain text.
-
-## Configuration
-
-Set retry policy per provider in `~/.fengming/fengming.json`:
-
-```json5
-{
-  channels: {
-    telegram: {
-      retry: {
-        attempts: 3,
-        minDelayMs: 400,
-        maxDelayMs: 30000,
-        jitter: 0.1,
-      },
-    },
-    discord: {
-      retry: {
-        attempts: 3,
-        minDelayMs: 500,
-        maxDelayMs: 30000,
-        jitter: 0.1,
-      },
-    },
-  },
-}
-```
-
-## Notes
-
-- Retries apply per request (message send, media upload, reaction, poll, sticker).
-- Composite flows do not retry completed steps.
-
-## Related
-
-- [Model failover](/concepts/model-failover)
-- [Command queue](/concepts/queue)

package/docs/concepts/session-pruning.md

@@ -1,104 +0,0 @@
----
-summary: "Trimming old tool results to keep context lean and caching efficient"
-title: "Session pruning"
-read_when:
-  - You want to reduce context growth from tool outputs
-  - You want to understand Anthropic prompt cache optimization
----
-
-Session pruning trims **old tool results** from the context before each LLM
-call. It reduces context bloat from accumulated tool outputs (exec results, file
-reads, search results) without rewriting normal conversation text.
-
-<Info>
-Pruning is in-memory only -- it does not modify the on-disk session transcript.
-Your full history is always preserved.
-</Info>
-
-## Why it matters
-
-Long sessions accumulate tool output that inflates the context window. This
-increases cost and can force [compaction](/concepts/compaction) sooner than
-necessary.
-
-Pruning is especially valuable for **Anthropic prompt caching**. After the cache
-TTL expires, the next request re-caches the full prompt. Pruning reduces the
-cache-write size, directly lowering cost.
-
-## How it works
-
-1. Wait for the cache TTL to expire (default 5 minutes).
-2. Find old tool results for normal pruning (conversation text is left alone).
-3. **Soft-trim** oversized results -- keep the head and tail, insert `...`.
-4. **Hard-clear** the rest -- replace with a placeholder.
-5. Reset the TTL so follow-up requests reuse the fresh cache.
-
-## Legacy image cleanup
-
-FengMing also builds a separate idempotent replay view for sessions that
-persist raw image blocks or prompt-hydration media markers in history.
-
-- It preserves the **3 most recent completed turns** byte-for-byte so prompt
-  cache prefixes for recent follow-ups stay stable.
-- In the replay view, older already-processed image blocks from `user` or
-  `toolResult` history can be replaced with
-  `[image data removed - already processed by model]`.
-- Older textual media references such as `[media attached: ...]`,
-  `[Image: source: ...]`, and `media://inbound/...` can be replaced with
-  `[media reference removed - already processed by model]`. Current-turn
-  attachment markers stay intact so vision models can still hydrate fresh
-  images.
-- The raw session transcript is not rewritten, so history viewers can still
-  render the original message entries and their images.
-- This is separate from normal cache-TTL pruning. It exists to stop repeated
-  image payloads or stale media refs from busting prompt caches on later turns.
-
-## Smart defaults
-
-FengMing auto-enables pruning for Anthropic profiles:
-
-| Profile type                                            | Pruning enabled | Heartbeat |
-| ------------------------------------------------------- | --------------- | --------- |
-| Anthropic OAuth/token auth (including Claude CLI reuse) | Yes             | 1 hour    |
-| API key                                                 | Yes             | 30 min    |
-
-If you set explicit values, FengMing does not override them.
-
-## Enable or disable
-
-Pruning is off by default for non-Anthropic providers. To enable:
-
-```json5
-{
-  agents: {
-    defaults: {
-      contextPruning: { mode: "cache-ttl", ttl: "5m" },
-    },
-  },
-}
-```
-
-To disable: set `mode: "off"`.
-
-## Pruning vs compaction
-
-|            | Pruning            | Compaction              |
-| ---------- | ------------------ | ----------------------- |
-| **What**   | Trims tool results | Summarizes conversation |
-| **Saved?** | No (per-request)   | Yes (in transcript)     |
-| **Scope**  | Tool results only  | Entire conversation     |
-
-They complement each other -- pruning keeps tool output lean between
-compaction cycles.
-
-## Further reading
-
-- [Compaction](/concepts/compaction) -- summarization-based context reduction
-- [Gateway Configuration](/gateway/configuration) -- all pruning config knobs
-  (`contextPruning.*`)
-
-## Related
-
-- [Session management](/concepts/session)
-- [Session tools](/concepts/session-tool)
-- [Context engine](/concepts/context-engine)