Pi Coding Agent SDK (tracing)

The Pi Coding Agent SDK (@earendil-works/pi-coding-agent) runs pi coding agents programmatically from TypeScript. Use @respan/instrumentation-pi to trace every session.prompt() as a Respan trace: the user prompt, each LLM call with prompts, completions, token, cache and cost usage, each tool execution, and compactions. Nothing is written to disk; spans are batched in memory and sent to Respan.

Setup

$
npm install @earendil-works/pi-coding-agent @respan/respan @respan/instrumentation-pi

$
export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"

1
import {
2
  createAgentSession,
3
  DefaultResourceLoader,
4
  getAgentDir,
5
} from "@earendil-works/pi-coding-agent";
6
import { Respan } from "@respan/respan";
7
import { PiInstrumentor } from "@respan/instrumentation-pi";
8
9
const instrumentor = new PiInstrumentor({ workflowName: "mail-agent" });
10
const respan = new Respan({
11
  apiKey: process.env.RESPAN_API_KEY,
12
  instrumentations: [instrumentor],
13
});
14
await respan.initialize();
15
16
const loader = new DefaultResourceLoader({
17
  cwd: process.cwd(),
18
  agentDir: getAgentDir(),
19
  extensionFactories: [instrumentor.extension],
20
});
21
await loader.reload();
22
23
const { session } = await createAgentSession({ resourceLoader: loader });
24
await session.prompt("Summarize the latest email in the thread");
25
await respan.flush();

1
const { session } = await createAgentSession();
2
const detach = instrumentor.attach(session, {
3
  threadIdentifier: emailChainId, // default: the pi session id
4
  customerIdentifier: mailboxOwnerId,
5
  metadata: { mailbox: "support" },
6
});
7
await session.prompt("Draft a reply");
8
detach();

Trace shape

Each agent run (one session.prompt() → agent_end) is one root agent span, pi.turn-<n>.agent, displayed as agent.turn-<n> — n is the prompt’s number within the pi session, so a resumed session continues at the next turn. Chat and tool spans hang directly off it.

pi.turn-1.agent (agent)                         one per agent run, shown as agent.turn-1
├── pi.chat (chat)                              one per assistant message
│     prompts, completion, tool_calls, usage, TTFT, cost
├── bash.tool (tool)                            one per tool execution
├── read.tool (tool)                            skill usage detected from SKILL.md
├── pi.chat (chat)
└── pi.compaction (task)                        when compaction happens mid-run

Chat and tool spans are emitted the moment they complete, so an hour-long run streams into the dashboard while it is still running; the turn span arrives when the run ends. Every span carries the pi session id as its thread, session and trace-group identifier.

Captured data

Options

new PiInstrumentor(options) accepts:

One trace per run or per session

A pi session that is resumed over days or weeks (an email thread handled by an always-on agent, for example) can be viewed two ways:

• traceScope: "session" (default): every run of the session joins one trace whose id is derived from the pi session id, so a session reopened in another process (SessionManager.open(file)) or after a week-long pause keeps adding turns to the same trace. Respan groups the runs as multiple roots under one synthetic root, ordered by time; the trace’s duration then spans from the first to the latest run. No span is ever held open across idle time. If you keep sessions in memory (SessionManager.inMemory()), every wake is a new session: pass your own threadIdentifier (for example the email-chain id) to keep them grouped in Threads.
• traceScope: "run": every prompt is its own trace with its own cost and latency, nested under an active OpenTelemetry span when there is one. All traces of the session still share thread_identifier = the pi session id, so the Threads view shows the whole session in order.

Long-running sessions and volume

The instrumentation keeps only the state of the current run in memory and writes nothing to disk, so idle sessions cost nothing and a process that handles thousands of sessions a day stays bounded. Full context capture is quadratic in the number of LLM calls per run; for very high-volume deployments use promptCapture: "delta" (the full conversation is still reconstructable from the trace) or maxContentChars.

For at-least-once delivery across Respan outages and restarts, run the Respan Collector next to the application and set RESPAN_BASE_URL=http://127.0.0.1:4318. The collector’s queue is bounded and drains as soon as Respan acknowledges the data, so nothing accumulates on the machine.

Attributes

Use Respan attributes to group runs by user or conversation.

1
await respan.propagateAttributes(
2
  {
3
    customer_identifier: "user_123",
4
    thread_identifier: "email-chain-abc",
5
    metadata: { mailbox: "support" },
6
  },
7
  async () => {
8
    await session.prompt("Draft a reply");
9
  }
10
);

Resources

• @respan/instrumentation-pi on npm
• Package README — full option reference
• pi — trace interactive pi sessions in the terminal
• Delivery guarantees & Collector
• Pi Coding Agent SDK on npm · pi documentation