pi-agent-trace

A small Pi extension that writes complete provider requests and assembled assistant responses to JSONL. It is designed for batch agent runs where Pi uses --no-session and the caller owns trace file naming.

Install

pi install npm:pi-agent-trace

Usage

Both variables are required. TRACE_DIR must be absolute and TRACE_FILENAME must be a basename. If either value is missing or invalid, tracing is disabled.

TRACE_DIR=/tmp/traces \
TRACE_FILENAME=agent-123 \
pi --no-session --print "Explain this repository"

This writes /tmp/traces/agent-123.jsonl. Existing files are replaced when the extension first writes, then rows are appended during the run.

Each provider call produces two rows sharing the same _id:

{"model":"...","messages":[],"tools":[],"_id":1,"_kind":"request","_ts":"..."}
{"role":"assistant","content":[],"usage":{},"_id":1,"_kind":"response","_ts":"...","_status":200}

Requests are the final provider-specific payload from Pi, so system prompts, messages, tool schemas, and model parameters are preserved without truncation. Responses are Pi's assembled assistant messages after streaming completes.

Trace files can contain prompts, source code, tool output, and model reasoning. Store them accordingly.

Tracing is fail-open: missing configuration and filesystem errors never interrupt Pi.