fengming 0.3.9 → 0.3.11

package/docs/tools/trajectory.md

@@ -1,229 +0,0 @@
----
-summary: "Export redacted trajectory bundles for debugging an FengMing agent session"
-read_when:
-  - Debugging why an agent answered, failed, or called tools a certain way
-  - Exporting a support bundle for an FengMing session
-  - Investigating prompt context, tool calls, runtime errors, or usage metadata
-  - Disabling or relocating trajectory capture
-title: "Trajectory bundles"
----
-
-Trajectory capture is FengMing's per-session flight recorder. It records a
-structured timeline for each agent run, then `/export-trajectory` packages the
-current session into a redacted support bundle.
-
-Use it when you need to answer questions like:
-
-- What prompt, system prompt, and tools were sent to the model?
-- Which transcript messages and tool calls led to this answer?
-- Did the run time out, abort, compact, or hit a provider error?
-- Which model, plugins, skills, and runtime settings were active?
-- What usage and prompt-cache metadata did the provider return?
-
-If you are filing a broad support report for a live Gateway issue, start with
-[`/diagnostics`](/gateway/diagnostics#chat-command). Diagnostics collects the
-sanitized Gateway bundle and, for OpenAI Codex harness sessions, can also send
-Codex feedback to OpenAI servers after approval. Use `/export-trajectory` when
-you specifically need the detailed per-session prompt, tool, and transcript
-timeline.
-
-## Quick start
-
-Send this in the active session:
-
-```text
-/export-trajectory
-```
-
-Alias:
-
-```text
-/trajectory
-```
-
-FengMing writes the bundle under the workspace:
-
-```text
-.fengming/trajectory-exports/fengming-trajectory-<session>-<timestamp>/
-```
-
-You can choose a relative output directory name:
-
-```text
-/export-trajectory bug-1234
-```
-
-The custom path is resolved inside `.fengming/trajectory-exports/`. Absolute
-paths and `~` paths are rejected.
-
-Trajectory bundles can contain prompts, model messages, tool schemas, tool
-results, runtime events, and local paths. The chat slash command therefore runs
-through exec approval every time. Approve the export once when you intend to
-create the bundle; do not use allow-all. In group chats, FengMing sends the
-approval prompt and export result to the owner privately instead of posting the
-trajectory details back to the shared room.
-
-For local inspection or support workflows, you can also run the approved command
-path directly:
-
-```bash
-fengming sessions export-trajectory --session-key "agent:main:telegram:direct:123" --workspace .
-```
-
-## Access
-
-Trajectory export is an owner command. The sender must pass the normal command
-authorization checks and owner checks for the channel.
-
-## What gets recorded
-
-Trajectory capture is on by default for FengMing agent runs.
-
-Runtime events include:
-
-- `session.started`
-- `trace.metadata`
-- `context.compiled`
-- `prompt.submitted`
-- `model.fallback_step`, including the source model, next model, failure reason/detail, chain position, and whether fallback advanced, succeeded, or exhausted the chain
-- `model.completed`
-- `trace.artifacts`
-- `session.ended`
-
-Transcript events are also reconstructed from the active session branch:
-
-- user messages
-- assistant messages
-- tool calls
-- tool results
-- compactions
-- model changes
-- labels and custom session entries
-
-Events are written as JSON Lines with this schema marker:
-
-```json
-{
-  "traceSchema": "fengming-trajectory",
-  "schemaVersion": 1
-}
-```
-
-## Bundle files
-
-An exported bundle can contain:
-
-| File                  | Contents                                                                                       |
-| --------------------- | ---------------------------------------------------------------------------------------------- |
-| `manifest.json`       | Bundle schema, source files, event counts, and generated file list                             |
-| `events.jsonl`        | Ordered runtime and transcript timeline                                                        |
-| `session-branch.json` | Redacted active transcript branch and session header                                           |
-| `metadata.json`       | FengMing version, OS/runtime, model, config snapshot, plugins, skills, and prompt metadata     |
-| `artifacts.json`      | Final status, errors, usage, prompt cache, compaction count, assistant text, and tool metadata |
-| `prompts.json`        | Submitted prompts and selected prompt-building details                                         |
-| `system-prompt.txt`   | Latest compiled system prompt, when captured                                                   |
-| `tools.json`          | Tool definitions sent to the model, when captured                                              |
-
-`manifest.json` lists the files present in that bundle. Some files are omitted
-when the session did not capture the corresponding runtime data.
-
-## Capture location
-
-By default, runtime trajectory events are written beside the session file:
-
-```text
-<session>.trajectory.jsonl
-```
-
-FengMing also writes a best-effort pointer file beside the session:
-
-```text
-<session>.trajectory-path.json
-```
-
-Set `FENGMING_TRAJECTORY_DIR` to store runtime trajectory sidecars in a
-dedicated directory:
-
-```bash
-export FENGMING_TRAJECTORY_DIR=/var/lib/fengming/trajectories
-```
-
-When this variable is set, FengMing writes one JSONL file per session id in that
-directory.
-
-Session maintenance removes trajectory sidecars when their owning session entry
-is pruned, capped, or evicted by the sessions disk budget. Runtime files outside
-the sessions directory are removed only when the pointer target still proves it
-belongs to that session.
-
-## Disable capture
-
-Set `FENGMING_TRAJECTORY=0` before starting FengMing:
-
-```bash
-export FENGMING_TRAJECTORY=0
-```
-
-This disables runtime trajectory capture. `/export-trajectory` can still export
-the transcript branch, but runtime-only files such as compiled context,
-provider artifacts, and prompt metadata may be missing.
-
-## Tune flush timeout
-
-FengMing flushes runtime trajectory sidecars during agent cleanup. The default
-cleanup timeout is 10,000 ms. On slow disks or large stores, set
-`FENGMING_TRAJECTORY_FLUSH_TIMEOUT_MS` before starting FengMing:
-
-```bash
-export FENGMING_TRAJECTORY_FLUSH_TIMEOUT_MS=30000
-```
-
-This controls when FengMing logs an `fengming-trajectory-flush` timeout and continues.
-It does not change the trajectory size caps. To tune all agent cleanup steps
-that do not pass an explicit timeout, set `FENGMING_AGENT_CLEANUP_TIMEOUT_MS`.
-
-## Privacy and limits
-
-Trajectory bundles are designed for support and debugging, not public posting.
-FengMing redacts sensitive values before writing export files:
-
-- credentials and known secret-like payload fields
-- image data
-- local state paths
-- workspace paths, replaced with `$WORKSPACE_DIR`
-- home directory paths, where detected
-
-The exporter also bounds input size:
-
-- runtime sidecar files: live capture stops at 10 MiB and records a truncation event when space remains; export accepts existing runtime sidecars up to 50 MiB
-- session files: 50 MiB
-- runtime events: 200,000
-- total exported events: 250,000
-- individual runtime event lines are truncated above 256 KiB
-
-Review bundles before sharing them outside your team. Redaction is best-effort
-and cannot know every application-specific secret.
-
-## Troubleshooting
-
-If the export has no runtime events:
-
-- confirm FengMing was started without `FENGMING_TRAJECTORY=0`
-- check whether `FENGMING_TRAJECTORY_DIR` points to a writable directory
-- run another message in the session, then export again
-- inspect `manifest.json` for `runtimeEventCount`
-
-If the command rejects the output path:
-
-- use a relative name like `bug-1234`
-- do not pass `/tmp/...` or `~/...`
-- keep the export inside `.fengming/trajectory-exports/`
-
-If the export fails with a size error, the session or sidecar exceeded the
-export safety limits. Start a new session or export a smaller reproduction.
-
-## Related
-
-- [Diffs](/tools/diffs)
-- [Session management](/concepts/session)
-- [Exec tool](/tools/exec)