Add a Pi runtime adapter

[raphant]

Goal

Visualize Pi sessions and subagent activity beside Claude Code and Codex sessions.

Proposed change

Define a runtime adapter boundary and implement a Pi adapter that emits the existing Agent Flow protocol.
Keep Pi-specific parsing outside the shared visualization code.

Acceptance criteria

• The adapter discovers active Pi sessions from a configured Pi directory.
• The adapter emits sessions, agents, tool calls, results, errors, messages, and usage when Pi records them.
• The runtime badge identifies Pi sessions.
• A configuration option can watch Pi only or watch all supported runtimes.
• Fixture tests cover a main agent, one subagent, tool failure, and session completion.

Related upstream work

• patoles/agent-flow#53 tracks OpenCode support.
• patoles/agent-flow#67 tracks Cursor support.
• patoles/agent-flow#52 proposes a Strands runtime.

Source

• extension/src/session-runtime.ts defines the current runtime interface.
• extension/src/claude-runtime.ts and extension/src/codex-runtime.ts implement the existing adapters.

[raphant]

Pi runtime reconnaissance (Pi 0.84.1)

I checked the existing adapter boundary, Pi's persisted format, and Pi's official subagent example.
I also sampled 20 recent local Pi sessions with 5,109 valid JSONL entries.
Unless marked as a decision, each finding below comes from the cited source or the local sample.

The adapter boundary already exists

Agent Flow already defines AgentSessionWatcher and AgentRuntime in session-runtime.ts.
extension.ts selects the extension runtime implementation.
The standalone relay.ts still wires runtime-specific watchers itself.

A Pi implementation should use the current boundary instead of adding a second abstraction.
It should follow the Codex shape: parser, watcher, runtime launcher, and relay wiring.

A file watcher can emit most requested data

Pi session JSONL records messages, thinking, tool calls, tool results, tool failures, model changes, timestamps, and usage.
Usage includes input, output, cache, total tokens, and cost.
Source: Pi's session-format.md and the local sample.

The parser must follow Pi's id and parentId tree.
It must not assume that every entry belongs to one linear conversation.
Source: Pi's session-format.md.

Agent Flow's context_update event carries only context tokens.
The cost overlay estimates cost from model and context size.
Full Pi token, cache, and cost data needs a protocol and UI change.
Source: protocol.ts and draw-cost.ts.

Agent Flow defines a standalone error event, but the simulation reducer does not consume it.
The minimum adapter can use tool_call_end.isError for tool failures, as the current runtimes do.
Source: handle-message-events.ts and protocol.ts.

Exact completion is not persisted

Pi exposes exact completion through live extension events.
agent_settled means no automatic retry, compaction, or follow-up remains.
session_shutdown reports quit, reload, new, resume, and fork transitions.
Source: Pi's extensions.md and session_shutdown.

Pi does not write these events to normal session JSONL.
A file-only adapter cannot distinguish an idle open session from a closed session.
Source: Pi's session-format.md and the local sample.

The minimum implementation can reuse Agent Flow's Codex heuristic.
It marks a session inactive after five minutes and discovers files modified within ten minutes.
Source: constants.ts and codex-session-watcher.ts.

This policy supports a completion fixture, but it does not provide exact completion.
Exact completion needs a small Pi extension that forwards live lifecycle events.

Subagent support needs an explicit scope

Pi core does not define a native subagent contract.
Source: Pi's README.md.

Pi's official subagent example starts children with --no-session.
The parent can record the subagent tool call and final result, but no child session file exists to tail.
Source: Pi's subagent example.

The installed pi-subagents package uses a different convention.
It writes nested child files under this shape:

<parent-session-stem>/<run-id>/run-0/session.jsonl

I found five such child files in the local sample.
Their headers do not contain parentSession.
The package-specific directory structure supplies the parent relationship.

A generic file adapter cannot promise live subagent activity.
The issue must select one of these contracts:

1. Show the generic subagent tool call and its final result after completion.
2. Add explicit support for the installed pi-subagents directory convention.
3. Add a Pi extension that forwards live child lifecycle events.

The minimum file-only scope is option 1.
A live subagent graph requires option 2 or option 3.

Session discovery has defined precedence

Pi selects its session directory in this order:

1. --session-dir
2. PI_CODING_AGENT_SESSION_DIR
3. sessionDir in settings.json

PI_CODING_AGENT_DIR changes the config root and defaults to ~/.pi/agent.
Source: Pi's environment-variables.md and settings.md.

Agent Flow must either mirror this resolution or add an explicit Pi session-directory setting.
An explicit Agent Flow setting should take precedence if we add one.

Runtime identity needs web changes

The runtime type currently accepts only claude | codex.
Source: agent-types.ts.

The event handler treats every non-Codex runtime as Claude.
Source: handle-agent-events.ts.

Canvas logos, transcript labels, and chat labels also use Claude-or-Codex branches.
Session metadata does not carry a runtime identity.
The Pi badge therefore needs changes in the shared protocol, bridge types, simulation state, and labels.

Minimum implementation surface

Core files:

• Add a Pi JSONL parser.
• Add a Pi session watcher.
• Add a Pi runtime launcher.
• Extend session-runtime.ts.
• Wire Pi into extension.ts and relay.ts.
• Extend the runtime setting in extension/package.json.

Web files:

• Extend agent-types.ts.
• Preserve Pi identity in handle-agent-events.ts.
• Add the Pi badge, logo, transcript label, and chat label.
• Carry runtime identity in session metadata.

Tests and documentation:

• Add a main-session fixture.
• Add a tool-failure fixture.
• Add a completion-policy fixture.
• Add a subagent fixture only after the issue selects a subagent contract.
• Update the README, changelog, runtime setting text, and telemetry runtime description.

Official Pi target

This issue targets the official Pi distribution.
Pi v0.84.1 publishes as @earendil-works/pi-coding-agent from earendil-works/pi.
The previous badlogic/pi-mono URL redirects to the same GitHub repository.
No separate Pi-variant decision is needed.

Decisions required before implementation

1. Should subagent support target the installed pi-subagents package?
2. Is five-minute inactivity acceptable as session completion?
3. Should Agent Flow add a Pi directory setting or only use Pi's environment and settings rules?
4. Does usage mean the current context gauge or Pi's full token, cache, and cost data?
5. Should branched Pi sessions show all recorded branches or only the active branch?

Until these remaining decisions are made, the current acceptance criteria overpromise live subagent activity and exact session completion.

[raphant]

Pi proof of concept and implementation contract

I ran isolated probes against official Pi 0.84.1 and pi-subagents 0.47.1.
I also tested Agent Flow's current incremental reader against Pi-specific file behavior.
The probes used temporary extensions and session directories under .git.
They did not change Agent Flow source.

What the PoC proved

Pi JSONL covers the main session

A real file-only parser can emit the main agent, messages, thinking, tools, failures, models, and context usage.

One active session sample contained:

• 748 valid entries and no malformed lines.
• 353 tool calls and 351 results.
• No duplicate call IDs, duplicate result IDs, or orphan results.
• 27 tool results with isError: true.
• Two pending calls because the session was still active during the scan.
• Three compactions and two tree leaves.

The parser must keep pending calls across reads.
It must use toolCall.id and toolResult.toolCallId for correlation.
It must use toolResult.isError instead of guessing from result text.
It must treat assistant stopReason: "error" separately from "aborted".

Source: Pi session-format.md and session-manager.ts.

Live lifecycle events do not persist

A real print-mode run emitted this live sequence:

session_start
before_agent_start
agent_start
turn_start
message_start(user)
message_end(user)
message_start(assistant)
message_update(text_start)
message_update(text_delta)
message_update(text_end)
message_end(assistant)
turn_end
agent_end
agent_settled
session_shutdown(quit)

The same session file contained only these record types:

session
model_change
thinking_level_change
message(user)
message(assistant)

agent_settled and session_shutdown therefore require a live Pi extension.
A file-only adapter must use inactivity for completion.

Source: Pi extensions.md and rpc.md.

Tool failures have an authoritative persisted flag

A temporary tool threw one fixed test error.
The live tool_result and tool_execution_end events both reported isError: true.
The persisted toolResult message also reported isError: true.
The Pi process recovered and wrote a later assistant message.

This satisfies the tool-failure acceptance criterion without a standalone Agent Flow error event.

Discovery must scan the workspace, not one encoded directory

Pi creates one encoded directory per exact working directory.
A synthetic SessionManager probe created one session at a workspace root and one in a descendant directory.
Exact-directory discovery found one session.
Header-based workspace filtering found both sessions.

The default scanner must inspect the Pi sessions/ directory and filter top-level headers by workspace containment.
It must not compute only the encoded directory for the Agent Flow startup path.

Pi also delays file creation until the first assistant message.
The probe confirmed that a user-only session had no file.
The file appeared after the first assistant message.

Source: Pi getDefaultSessionDir() and _persist().

The existing incremental reader is not safe for Pi unchanged

I exercised Agent Flow's real readNewFileLines().

It failed two probes:

• A UTF-8 code point split across reads parsed as replacement characters.
• A same-size in-place rewrite produced no change event.

Pi can rewrite a session during version migration.
pi-subagents also rewrites a forked file while it sanitizes thinking blocks and aligns the child working directory.

A buffer-based prototype passed these checks:

• Preserve a UTF-8 code point split across reads.
• Detect a same-size rewrite with stable prefix and tail anchors.
• Reset on rewrite and suppress duplicate entry IDs during replay.

The Pi watcher needs this reader behavior.
It should read bounded chunks and cap an unfinished line.
The largest line in the 28-file sample was 67,494 bytes.
No sampled line exceeded 1 MiB.

Source: Pi session-manager.ts and pi-subagents fork-context.ts.

pi-subagents findings

Fresh children have a reliable directory relationship

Eight sampled fresh children used this layout:

<parent-session-stem>/<child-run-id>/run-<index>/session.jsonl

None of their headers had parentSession.
All eight wrote a session_info name in this form:

subagent-<agent>-<child-run-id>-<index>

The default intercom bridge creates that name.
The directory still identifies a child if a user disables the bridge and the name is absent.

Source: pi-subagents getSubagentSessionRoot(), subagent-executor.ts, and intercom-bridge.ts.

A child can use a different working directory

All eight sampled children had a working directory different from their parent.
The launches intentionally targeted another repository.

The scanner must include a child because of its parent relationship.
It must not reject the child because its header cwd falls outside the watched workspace.

Fork-context children copy parent history

One fork-context child had native parentSession metadata.
It contained 643 entries, of which 639 reused entry IDs from the parent.
It also had a subagent-* session name.

A naive parser would replay almost the entire parent as child activity.
The adapter must subtract copied parent entry IDs before it emits child events.

A normal user /fork also writes parentSession.
The adapter must not classify every native fork as a subagent.
It can classify the observed pi-subagents fork only when the subagent-* session name or live metadata confirms it.

Source: Pi createBranchedSession() and pi-subagents fork-context.ts.

The parent can exit while an async child continues

In print mode, the parent emitted session_shutdown before the async child finished.
The child session file changed about 6.8 seconds after the parent file stopped.
The parent did not persist a completion notification.

The root session's last activity must include descendant file activity.
A parent-only inactivity timer would end the graph while the child still runs.

A sibling Pi extension helps, but it cannot replace file watching

A long-lived RPC parent let a temporary observer receive subagent:async-complete.
The completion payload contained workflow and per-child success state.
The parent also persisted a custom_message with customType: "subagent-notify".

The observer did not receive subagent:async-started in either print or RPC mode.
The direct subagent tool result reported asyncId, asyncDir, and runId.
Current opi sessions call pi-subagents through fabric_exec, so Agent Flow sees the outer tool call instead.

File discovery is therefore the only start path that works for direct tools, Fabric-wrapped tools, and children that outlive print-mode parents.
A live observer can be a later latency and completion enhancement.

Source: pi-subagents shared/types.ts, async-execution.ts, and result-watcher.ts.

Core Pi's example remains ephemeral

The official example starts children with --no-session.
A file watcher cannot show the child's internal activity.
It can show only the parent subagent tool call and final tool result.

Source: Pi's official subagent example.

Usage semantics

Pi's latest valid assistant usage gives the current context estimate.
Pi calculates it from usage.totalTokens, with a component fallback.
After compaction, Pi considers context unknown until a later valid assistant response.

Cumulative billing also includes assistant usage, nested tool-result usage, compaction usage, and branch-summary usage.
Agent Flow's current protocol has no billing-cost field.

The first implementation should emit the existing context gauge only.
It should not add a cost protocol or estimate Pi billing.
The current UI can derive a context-window fallback from the model ID.
A later live integration can report Pi's exact model context window.

Source: Pi agent-session.ts and compaction.ts.

Implementation contract

The first implementation should be file-first and hybrid-ready.
It should not install a Pi extension yet.

Build now

1. Add an explicit Agent Flow Pi session-directory override.
2. Otherwise follow Pi's environment, project setting, global setting, and default directory rules.
3. Scan all default encoded project directories and filter main headers by workspace containment.
4. Discover related children regardless of child cwd.
5. Add a byte-buffered incremental reader with rewrite detection and entry-ID replay suppression.
6. Parse entries in append order because Agent Flow shows work that occurred, including abandoned branches.
7. Correlate tools by ID and use persisted isError.
8. Emit current context tokens only after a valid assistant usage record.
9. Support fresh pi-subagents children from their nested directory layout.
10. Support forked pi-subagents children only when the session name confirms them.
11. Remove copied parent IDs before replaying a forked child.
12. Use descendant activity for root-session activity and the existing five-minute completion policy.
13. Reactivate a completed session if any related file receives a later entry.
14. Preserve entry timestamps during reload and replay.

Defer

• A Pi observer extension for exact agent_settled, session_shutdown, and subagent:async-complete events.
• Child graphs for the official ephemeral subagent example.
• Full token billing and cost UI.
• Special rendering for Pi branch trees.

Revised PoC-backed checks

• A main fixture covers text, thinking, model changes, tool correlation, context usage, and an assistant error.
• A failure fixture proves toolResult.isError reaches tool_call_end.isError.
• Reader tests cover partial lines, split UTF-8, truncation, same-size rewrite, and replay deduplication.
• Discovery tests cover an exact workspace, a descendant workspace, a custom session directory, and a child with another cwd.
• A fresh-child fixture covers the nested pi-subagents layout and session name.
• A fork-child fixture proves copied parent entries do not replay.
• Completion tests use newest related entry time, five-minute inactivity, and later reactivation.
• A browser probe confirms the Pi runtime badge and one parent-child graph.

This contract removes the remaining implementation ambiguity without adding a second runtime abstraction.

[raphant]

Pi adapter implemented

The file-first Pi runtime adapter is on feat/pi-runtime-adapter at commit afb1c6b.

Included

• Pi runtime registration for the VS Code extension, development relay, and standalone app.
• Default, environment, settings, and explicit Pi session-directory discovery.
• Workspace descendant filtering across Pi's encoded project directories.
• A byte-buffered JSONL reader with split UTF-8, truncation, replacement, and same-size rewrite handling.
• Persisted timestamps for session activity, completion, and later reactivation.
• Text, thinking, model, tool, authoritative tool-error, assistant-error, and context-usage events.
• Fresh pi-subagents child discovery from nested session files.
• Named fork-child discovery with copied parent-entry suppression.
• Related child activity in the root session inactivity calculation.
• Pi transcript labels and a π canvas badge.
• agentVisualizer.piSessionDir, AGENT_FLOW_PI_SESSION_DIR, and --pi-session-dir overrides.

Verification

All repository checks passed:

• Root tests: 36 passed, 0 failed.
• Extension tests: 39 passed, 0 failed.
• Extension source and test TypeScript checks passed.
• Web, webview, extension, and standalone builds passed.
• git diff --check passed before commit.

Real-session probe against Pi 0.84.1 and the current ~/.opi data:

• One Pi main agent.
• Ten persisted child agents.
• 643 message events.
• 475 tool starts and 473 correlated tool results.
• 33 authoritative tool failures.
• 500 authoritative context updates.
• Two persisted assistant errors.

The browser probe used synthetic data.
It confirmed the session rendered, the empty state disappeared, and the canvas called fillText("π") for the main agent badge.

The built branch now runs at http://127.0.0.1:3001 from the seveneleven workspace.

Still deferred

• A live Pi observer for exact settlement and shutdown events.
• Child graphs for subagents that use --no-session.
• Billing and cost UI.

I left issue #11 open because the implementation has not merged to main.

[raphant]

Merged to main at afb1c6b.

The final live acceptance used the running source dashboard at http://127.0.0.1:3001.
New Pi activity appeared without a dashboard reload.
A fresh persisted Pi subagent increased the selected graph from one agent to two.
A controlled failed tool call appeared as Error in the execution timeline.
Session switching returned to the current Pi graph and retained both agents.
A full browser reload retained the two-agent graph.
Completed sessions retained their historical activity ages instead of changing to now.

Detailed token and cost reporting remains tracked separately in issue #5.
Live lifecycle hooks and --no-session child graphs remain optional follow-up work rather than issue #11 acceptance requirements.