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.

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 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."