Pi Session Tracing with Future AGI

Pi is an open-source coding agent that runs in your terminal (binary pi). Pi has no built-in OpenTelemetry exporter, but it loads TypeScript extensions that receive its session, agent, turn, message, and tool events. This page adds a small extension that turns those events into OTLP traces and sends them to Future AGI. You see each Pi session as one trace, with every prompt, model call, and tool execution inside it.

This is not the same as:

• The Pi Coding Agent SDK. Code that embeds Pi with createAgentSession() is traced with the @traceai/pi-coding-agent package, which has its own page in this section.
• Oh My Pi (omp, the omp.sh fork). It is a different binary with its own hook API and has its own page. This extension is for upstream Pi only.
• Model SDK tracing. A traceAI instrumentor on a provider SDK shows model calls without Pi’s session, turns, or tools. Pi makes its model calls itself.
• pi-trace-extension and other local trace viewers. They write files on your machine. This extension sends traces to Future AGI and writes nothing to disk.

This recipe installs Pi 1.2.0. The extension has no npm dependencies. See the Pi extension documentation and extension source.

What you get

pi.session                  AGENT   one per Pi session id
  pi.prompt                 CHAIN   one per prompt you submit (an agent run)
    pi.turn                 CHAIN   one per Pi turn: a model request and the tools it called
      chat gpt-6-luna       LLM     model, provider, token counts, stop reason
      execute_tool bash     TOOL    tool name, call id, duration, error flag
      execute_tool read     TOOL
    pi.turn                 CHAIN
      chat gpt-6-luna       LLM     the turn that wrote the answer

The trace id is derived from Pi’s session id, so continuing a session (pi -c, pi --session <id>, /resume) adds new prompts to the same trace. /new and /fork start a new session and a new trace. Every span carries session.id, so the session also appears under Sessions.

Set up

npm install -g @earendil-works/pi-coding-agent@1.2.0
pi --version

mkdir -p ~/.pi/agent/extensions
curl -fsSL https://raw.githubusercontent.com/future-agi/docs/main/examples/coding-agents/pi/futureagi-otlp.ts \
  -o ~/.pi/agent/extensions/futureagi-otlp.ts

mkdir -p .pi/extensions
curl -fsSL https://raw.githubusercontent.com/future-agi/docs/main/examples/coding-agents/pi/futureagi-otlp.ts \
  -o .pi/extensions/futureagi-otlp.ts

export FI_API_KEY="YOUR_API_KEY"
export FI_SECRET_KEY="YOUR_SECRET_KEY"
export FI_PROJECT_NAME="my-pi-project"

pi
# or, non-interactively:
pi -p "List the files in this folder and read README.md"

Configuration

The extension posts OTLP/HTTP JSON with traces only, one request at a time. It subscribes to session_start, session_info_changed, session_shutdown, agent_start, agent_end, agent_settled, turn_start, message_end, tool_execution_start, and tool_execution_end. Of these, only message_end is actionable in Pi (a handler may return a replacement message). The extension returns nothing from any handler, so Pi keeps every message as it is. It does not subscribe to turn_end, an actionable boundary that makes Pi rebuild its session view after every turn, nor to before_provider_request, before_provider_headers, tool_call, or tool_result, so it never blocks or rewrites a tool call or a provider request. It never reads or writes Pi’s session files. If an export fails, its spans are retried once with a later export and then dropped. Pi keeps working either way.

What is captured

Model call timing comes from the assistant message (timestamp and durationMs). Tool calls that another tool makes through ctx.executeTool(), for example codemode scripts, nest under the calling tool’s span.

Errors set the span status to ERROR with the message error details omitted by default:

• a model call that ends with stop reason error in a run you did not cancel (error.type=ProviderError), its turn (error.type=TurnError), and its prompt (error.type=ProviderError). If Pi retries and the retry succeeds, the prompt is OK;
• a tool execution that Pi reports with isError (error.type=ToolError). The prompt stays OK if the model recovers;
• the pi.session span, when any prompt failed in the current Pi process or since the last /reload (error.type=PromptError).

Cancelling a run (Escape, or /new, /resume, or /fork while Pi is working) is not an error. The prompt gets pi.prompt.aborted=true and stays OK. The model call and turn that were cut off get pi.incomplete=true and stay OK, and the model call keeps the finish reason Pi reported: aborted, or error when you cancel while a tool runs and Pi’s next model request is cancelled before it is sent. The extension tells that case apart from a provider error by the run’s abort signal, as Pi’s providers do. A tool that was running or queued when you cancelled is reported by Pi itself as failed (isError), so its span is ERROR.

If Pi exits in the middle of a turn, the open spans are closed and marked pi.incomplete=true. They are not marked as errors.

What is not available

• The model request. The extension does not read before_provider_request, so the system prompt, history, and tool schemas Pi sends to the model are never exported, even with content capture on.
• Streaming detail. Token deltas (message_update) and time to first token are not exported.
• Model calls outside the agent loop. Compaction summaries, branch summaries, and nested model calls made by other extensions do not produce assistant messages in the session, so they have no span.
• Cost for custom models. pi.usage.cost comes from Pi’s pricing. Models added in models.json without prices report 0 and get no cost attribute.
• Tokens in the trace list. The trace list’s Tokens column reads the root span. Tokens are on each chat span and are summed on the session as pi.usage.*.
• Hard kills. SIGTERM and SIGHUP let Pi shut the session down, so the extension sends its last spans. A SIGKILL loses whatever was not sent yet.
• Session counters across processes. Continuing a session in a new Pi process adds its prompts to the same trace, and /reload replaces the extension inside one process. The counters and summed usage on pi.session (and, with content capture on, its first prompt and latest answer) describe the latest Pi process or extension reload.
• Oh My Pi. Loading this file in omp is not supported. Use the Oh My Pi page.

Privacy

By default the extension exports ids, model and provider names, token counts, cost, timings, stop reasons, tool names, status, and byte sizes. It does not export:

• your prompt text or the assistant’s answers;
• tool arguments or tool results;
• the session name you set with /name or --name;
• error messages: neither a failed tool’s error text nor the provider’s error message, only the error type;
• local paths: the working directory (pi.cwd) is not exported, because it usually contains your OS user name.

To export content, set FI_CAPTURE_CONTENT=true before starting Pi. The message that started each run and the run’s final answer go to input.value and output.value on the pi.prompt span. The first prompt and latest answer of the current Pi process or extension reload also go on pi.session (so they show in the trace list). Answer text goes on each chat span. Tool arguments and results go on the tool span, and a failed tool’s result is its error text. A provider error message becomes the status message of the failed chat span. The session name goes to pi.session.name, and the working directory goes to pi.cwd on the session span. Tool arguments and results can contain local paths too. Each field is capped at 4096 characters (tool arguments cut at the cap are labeled text/plain instead of application/json), and strings that look like sk-... keys, Bearer tokens, or api_key=... values are replaced with [REDACTED].

Pi extensions run inside the Pi process with your user’s permissions and can see prompts, files, and credentials. This extension is written to export only what the tables above list. Read it before you install it, as you would any extension.

Troubleshooting

Related guides