feat: add debug trace viewer (picoclaw-tracer)

[aruntcet2010]

Summary

Adds picoclaw-tracer, a standalone web UI that reads the gateway JSON-Lines log and renders per-turn LLM traces in real time — system prompt, full messages array, available tools, tool executions, and response metadata for every LLM call within a turn.

• Fully separate binary at cmd/tracer — no CGO, no libolm, no picoclaw core imports. Build with go build ./cmd/tracer.
• Passive consumer — only reads ~/.picoclaw/logs/gateway.log from disk. Does not talk to the gateway, share state, or affect the picoclaw process in any way. Crashing/removing the tracer has zero impact on picoclaw.
• Zero changes to picoclaw core (cmd/picoclaw/, pkg/) — verifiable with git diff main..feat/tracer -- cmd/picoclaw/ pkg/ returning empty.
• Embedded frontend via go:embed behind a build tag, so a single binary serves the UI. Dev mode reads from disk for hot reload.

What it shows

For each turn:

• Metadata (time, channel, sender, status, duration, iterations)
• Tool executions (with duration, byte counts, error status)
• One collapsible card per LLM call (iteration) containing the exact messages array sent to the LLM: [0] SYSTEM, [1] USER, [2] ASSISTANT, [3] TOOL, ... — captured per-call so you can see when system prompt or tool list changes mid-turn
• Per-call Available Tools, nested inside each LLM call

Threads are grouped by chat_id and chat threads can be browsed in a three-pane layout (threads → turns → detail).

Architecture

tracer/                      # library (stdlib only)
  tracer.go                  # Run(port, logPath, frontendDir) entry
  parser.go                  # JSON-Lines gateway log → []*Turn
  server.go                  # HTTP API (/api/traces, /api/health)
  types.go                   # Turn, LLMCall, Message, Tool, ToolExec
  frontend_dev.go            # disk-served UI (build tag !embed)
  frontend_embed.go          # embedded UI (build tag embed)
  frontend/                  # React + Vite + TypeScript SPA

cmd/tracer/main.go           # standalone binary

Running

# Run picoclaw with debug logging so per-LLM-call messages get captured
picoclaw gateway --debug --no-truncate

# In another terminal, build and run the tracer
go build -tags embed -o picoclaw-tracer ./cmd/tracer
./picoclaw-tracer --port 7331
# → open http://localhost:7331

See tracer/README.md for details on dev mode and the Makefile targets.

Test plan

• go build ./tracer/... ./cmd/tracer/... succeeds without CGO
• Run ./picoclaw-tracer against a populated ~/.picoclaw/logs/gateway.log and confirm:
  • Threads list groups turns by chat_id
  • Single-iteration turns show 1 LLM call with full messages array
  • Multi-iteration turns (tool use) show N LLM calls, each with its own messages + tools
  • System prompt is visible per-call at index [0]
  • Available Tools (collapsed) is per-call so changes between iterations are visible
  • Gateway restart (turn_id reuse) doesn't crash the parser or duplicate turns
• git diff main..feat/tracer -- cmd/picoclaw/ pkg/ is empty (picoclaw core untouched)

🤖 Generated with Claude Code

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.

---

Arun Thulasidharan seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}