Sessions, Inspect, Logs, Replay, Metrics, Compact

Every fh run and every dev-server invocation persists a session under .fabricharness/sessions/ (or your configured store). The CLI ships several commands for reading those sessions. With store: { backend: 'memory' } nothing is persisted. The run says so on stderr and fh sessions stays empty; that is expected, not data loss. To continue a persisted session, re-run with the same --id (or --resume <id>); see fh run.

fh sessions

fabric-harness sessions

Lists persisted sessions. Output includes session id, agent name, last update time, and entry counts.

fh inspect

fabric-harness inspect <session-id>

Shows the full structured session. Prompts, assistant messages, tool calls, tool results, shell commands, task starts/ends, approvals, compactions, checkpoints, and artifacts.

fh logs

fabric-harness logs <session-id> [--events]

Prints a readable timeline. Use --events to include the lower-level event stream (text_delta, tool_start, tool_end, etc.).

fh metrics

fabric-harness metrics <session-id> [--json] [--breakdown]

Aggregate token, tool, shell, and artifact metrics for the session. Anthropic prompt-cache tokens (Cache: read=N write=N) are surfaced when present. When the SDK was able to estimate USD cost from the static price table (or the provider supplied it directly), a Cost: $0.XXXX line is printed.

Pass --breakdown to print per-provider/model cost line items.

Cost: $0.012450
  openai/gpt-4o: $0.011200
  anthropic/claude-haiku-4-5-20251001: $0.001250

The cost catalog is a static table shipped in the SDK. Override or extend it with registerModelPrices() when you have custom-rate contracts. Real-time billing reconciliation is out of scope; use vendor invoices for billing.

fh export-audit

fabric-harness export-audit <session-id> [--format jsonl|csv] [--output <path>|-]

Streams every entry in the session log out as one row per line, JSONL by default, CSV via --format csv. Each row carries normalized columns. Timestamp, type, entryId, parentId, tool, command, model, provider, durationMs, inputTokens, outputTokens, cachedInputTokens, cacheWriteTokens, costUsd, approvalId, audience, eventType, idempotencyKey, errorMessage.

Pipe straight into your SIEM / data warehouse.

fh export-audit ask-1f4f... --format jsonl | jq -c 'select(.type == "model_attempt")'
fh export-audit ask-1f4f... --format csv --output audit.csv

--output - writes to stdout (default when --output is omitted). Big sessions stream line-by-line, no full-session buffering.

fh replay

fabric-harness replay <session-id>

Read-only view of the session's active path (post-compaction) and the model context that would be sent on the next turn. Useful for debugging compactions and prompt drift.

fh checkpoints

fabric-harness checkpoints <session-id>

Lists checkpoints in a persisted session. Checkpoints are not created automatically. Create them from agent code with session.checkpoint.create(...), or per task with session.task(text, { checkpoint: true }). When a session has none, the command says so and prints this hint.

fh compact

fabric-harness compact <session-id> [--keep <n>] [--summary <text>]

Append a compaction entry to a persisted session. --keep <n> keeps the last n entries verbatim, --summary <text> provides an explicit summary instead of running the model.

Example session lifecycle

fh run ask --question "What is Temporal?"
# Session id: ask-1f4f...

fh inspect ask-1f4f...
fh logs ask-1f4f...
fh metrics ask-1f4f...
fh replay ask-1f4f...
fh compact ask-1f4f... --keep 2 --summary "User asked about Temporal."