feat: add 'session dump' command for universal debugging output

[zawakin]

Problem

Debugging specific issues (token monotonicity, event ordering, parsing errors) requires manual JSON navigation and custom scripts. No unified way to export session data for analysis with standard tools (jq, awk, pandas).

Proposed Solution

Add agtrace session dump <id> command with two phases:

Phase 1: Normalized JSONL output

agtrace session dump <session_id> --format jsonl

Output: One AgentEvent per line (JSONL)

{"seq":0,"timestamp":"2025-01-01T00:00:00Z","type":"User","content":{"text":"Hello"},"turn_idx":0,"step_idx":null}
{"seq":1,"timestamp":"2025-01-01T00:00:01Z","type":"TokenUsage","content":{"fresh_input":1000,"cache_read":500,"output":100,"total":1600},"turn_idx":0,"step_idx":0}
{"seq":2,"timestamp":"2025-01-01T00:00:02Z","type":"ToolCall","content":{"name":"Read","arguments":{"file_path":"..."}},"turn_idx":0,"step_idx":0}

Use cases:

• Token monotonicity verification: dump <id> --format jsonl | jq -s 'map(select(.type == "TokenUsage")) | map(.content.total)'
• Tool usage patterns: dump <id> --format jsonl | jq -r 'select(.type == "ToolCall") | .content.name' | sort | uniq -c
• Turn boundaries: dump <id> --format jsonl | jq -r 'select(.type == "User") | .timestamp'

Phase 2: Add --raw flag for normalization verification

agtrace session dump <session_id> --raw --format jsonl

Output: Normalized content + provider raw metadata

{
  "seq": 1,
  "type": "TokenUsage",
  "normalized": {"fresh_input": 1000, "cache_read": 500, "output": 100, "total": 1600},
  "provider": {
    "name": "claude_code",
    "raw_payload": {"input_tokens": 1000, "cache_read_input_tokens": 500, "output_tokens": 100}
  },
  "turn_idx": 0
}

Use cases:

• Verify normalization: dump <id> --raw | jq 'select(.normalized.total != (.provider.raw_payload.input_tokens + .provider.raw_payload.output_tokens))'
• Debug parser rules for specific providers
• Investigate schema-on-read edge cases

Implementation Notes

• Phase 1: Flatten assembled session into event stream with sequence numbers
• Phase 2: Include AgentEvent.metadata field in output
• Support --format {jsonl,json} (jsonl = one event per line, json = array)

Related

This addresses the token monotonicity investigation where 40% of sessions showed violations. Universal dump output enables ad-hoc analysis without adding specialized commands for each issue type.