Docskurby Tracepawl

Target: @codepawl/tracepawl (Failure diagnosis and replay for coding agents) Core Identity: Offline, deterministic postmortem engine for coding agent runs. Uses rule-based JSON trace analysis to pinpoint failure onset, classify error categories, and suggest recovery actions without mandatory LLMs.

---

🚀 Quick Start / Ingestion

• Install: npm install @codepawl/tracepawl
• CLI Analysis: npx tracepawl analyze trace.json (analyzes a run deterministically).
• CLI Recording: npx tracepawl run -- bun run my-agent.ts (wraps a local command and captures latest.json).
• Demo Sandbox: npx tracepawl demo --open generates a local, open-source diagnostic report of a mock failing agent.

---

💡 Best Practices (Patterns)

• Atomic Finalization: Always wrap execution in a try/finally block that calls writer.finalize() and await writer.writeToFile(outputPath). finalize is idempotent and “first-call-wins”.
• Cross-Referencing Events: Capture the EventId returned by record*() methods. Inject these IDs into subsequent events via the raw passthrough object to map relational causality (e.g., linking a file_edit to a prior file_read).
• Stable Identifiers: Allow TraceWriter to own Event IDs (evt_001, evt_002) and use crypto.randomUUID() for Run IDs. These are load-bearing strings for analyzer evidence pointers.
• Narrow Scoped Edits: Ensure agents read target files immediately before patching. Limit edits to <5 distinct files and <200 LOC per targeted task to avoid triggering the unsafe_or_broad_edit warning.

---

🚨 Anti-Patterns (What NOT to do)

• Reminting IDs on Parse: Do not regenerate event IDs when parsing or moving a trace. Modifying IDs severs the analyzer’s evidence pointers.
• Out-of-Order Logging: Do not record events retrospectively. TraceWriter assumes events are recorded in execution order; logging an earlier file_edit after a subsequent tool_call finishes will corrupt the parser’s timeline logic.
• Stale Context Editing: Do not let the agent execute a file_edit without a preceding file_read. Doing so triggers the stale_context_edit failure rule (old_string not found, context mismatch).
• Blind Looping: Do not loop identical tool_call payloads or failing shell commands >3 times without adapting arguments. This triggers the loop_or_stall analyzer rule.
• Misdirected Test Fixes: Do not let the agent edit unrelated files or silence failing assertions. This triggers the test_failure_misdiagnosis rule.

---

🔧 TraceWriter SDK (Manual Implementation)

• No Auto-instrumentation: TracePawl does not monkey-patch node:fs or child_process. All telemetry must be explicitly passed to TraceWriter via recordModelCall, recordToolCall, recordFileRead, recordFileEdit, recordCommandRun, recordTestRun, or recordGitDiff.
• Atomic File Writes: writer.writeToFile(path) uses atomic temp files (path.tmp.uuid) and fs.rename to prevent partial-write corruption on agent crashes.
• Event Schema Fields: Requires id, agent, userGoal, startedAt, and events[]. Custom adapter metadata can be dumped into the generic raw passthrough field without strict validation.

---

🚨 Gotchas / Warnings

• LLM is Strictly Advisory: Diagnosis uses pre-written deterministic rules (src/analyzer/rules/*.ts) by default. Passing --llm-review sends a heavily redacted prompt (stripping bearer tokens and clipping stdout) to OpenAI-compatible endpoints or Ollama, but the deterministic rule remains the primary source of truth.
• No Epoch Timestamps: The event schema strictly requires ISO 8601 strings (new Date().toISOString()). Integer epoch milliseconds are not automatically normalized.
• First Call Wins: finalize(endedAt?) ignores subsequent calls. If multiple termination conditions exist, the first captured timestamp solidifies the trace completion.