# How Feynman Manages the Pi Runtime: Embedded Subprocess Architecture and Session Orchestration

> Discover how Feynman manages its Pi runtime using an embedded subprocess architecture and session orchestration. Learn about lifecycle management and state extraction for seamless interaction management.

- Repository: [Advait Paliwal/feynman](https://github.com/advaitpaliwal/feynman)
- Tags: internals
- Published: 2026-09-08

---

**Feynman runs the Pi coding agent as an embedded, long-lived subprocess that records every interaction in a persistent Pi session, enabling the workbench to resume, replay, and archive agent interactions through coordinated lifecycle management and state extraction modules.**

The Feynman workbench integrates the Pi coding agent as a core component, requiring sophisticated **Pi runtime** management to maintain persistent sessions across workbench restarts. According to the advaitpaliwal/feynman source code, the runtime architecture coordinates session lifecycle, state extraction, and command discovery to provide a reliable, resumable view of the underlying agent.

## Core Components of Pi Runtime Management

Feynman's **Pi runtime** architecture rests on three primary pillars that coordinate between the embedded agent and the workbench interface.

### Session Lifecycle Orchestration

The **Pi runtime** lifecycle begins with the `SessionManager` from `@earendil-works/pi-coding-agent`, which creates, lists, and opens persisted session directories under the workbench's data root. Each workbench session maps to a unique Pi session ID via the `workbenchPiSessionId` function, ensuring that all agent interactions remain isolated and recoverable. This allows Feynman to maintain continuity across workbench restarts by referencing the persistent session storage.

### State Extraction and Timeline Construction

Once a session exists on disk, [`src/workbench/pi-session.ts`](https://github.com/advaitpaliwal/feynman/blob/main/src/workbench/pi-session.ts) handles **Pi runtime** state extraction through the `readWorkbenchPiSessionInfo` function. This module aggregates critical statistics including message counts, model used, thinking level, and branch points, then constructs a **timeline** and **tool-summary** that the workbench UI renders. The function reads from the session directory defined in the workbench configuration, typically located under the `sessions/` folder.

### Command Discovery and Resource Integration

During active **Pi runtime** operations, the agent publishes live slash commands via RPC. The [`src/workbench/pi-commands.ts`](https://github.com/advaitpaliwal/feynman/blob/main/src/workbench/pi-commands.ts) module captures these through `normalizePiCommands`, which standardizes the raw command data and extracts source information. The `buildPiCommandResourceGroup` function then creates a `WorkbenchResourceGroup` containing these commands, which `mergePiCommandResourceGroup` integrates into the workbench's existing resource view for immediate UI availability.

## Runtime Patching and Security Hardening

Before the **Pi runtime** initializes, Feynman executes a series of runtime-patch scripts located in `scripts/lib/pi-subagents-patch.mjs`. These scripts perform critical integration tasks:

- Apply security-hardening fixes including proxy-routing and TUI patches
- Wire Pi's telemetry streams to Feynman's centralized logging layer
- Ensure live commands, tools, and extensions remain discoverable by the workbench resource system

This patching layer ensures the embedded agent operates securely within the Feynman environment while maintaining full observability.

## Session Data Flow and Persistence

The **Pi runtime** follows a strict persistence model that enables historical replay and archiving:

1. **Workbench start** triggers the patch scripts to launch Pi
2. **Pi initialization** creates a session directory via `SessionManager`
3. **State synchronization** occurs when `readWorkbenchPiSessionInfo` reads the on-disk session to build the timeline and tool summary
4. **Live command streaming** feeds through `normalizePiCommands` into the resource group system

All session data resides under the workbench's `sessions/` folder, with each session maintaining independent directories identified by the mapped Pi session ID.

## Implementation Examples

The following TypeScript examples demonstrate how to interact with the **Pi runtime** programmatically.

Reading a Pi session for a given workbench session ID:

```typescript
import { readWorkbenchPiSessionInfo, workbenchPiSessionId } from "./src/workbench/pi-session.js";

async function getSessionInfo(workbenchSessionId: string) {
  const piSessionId = workbenchPiSessionId(workbenchSessionId);
  const info = await readWorkbenchPiSessionInfo({
    workingDir: "/path/to/workbench",
    sessionDir: "sessions",
    piSessionId,
  });
  console.log(info);
}

```

Normalizing live Pi commands and creating a resource group:

```typescript
import { normalizePiCommands, buildPiCommandResourceGroup } from "./src/workbench/pi-commands.js";

function createCommandGroup(workingDir: string, rawPiData: unknown) {
  const commands = normalizePiCommands(rawPiData);
  const group = buildPiCommandResourceGroup(workingDir, commands);
  return group;       // → { id: "commands", resources: [ … ] }
}

```

Merging the Pi command group into the workbench's existing resource groups:

```typescript
import { mergePiCommandResourceGroup } from "./src/workbench/pi-commands.js";

function integrateCommands(existingGroups, piGroup) {
  return mergePiCommandResourceGroup(existingGroups, piGroup);
}

```

## Critical Source Files for Pi Runtime Operations

| Component | File | Description |
|-----------|------|-------------|
| Session management | [`src/workbench/pi-session.ts`](https://github.com/advaitpaliwal/feynman/blob/main/src/workbench/pi-session.ts) | Reads and normalises Pi session files, builds timeline and tool summary. |
| Command handling | [`src/workbench/pi-commands.ts`](https://github.com/advaitpaliwal/feynman/blob/main/src/workbench/pi-commands.ts) | Normalises live Pi commands and creates UI resource groups. |
| Runtime patching | `scripts/lib/pi-subagents-patch.mjs` | Applies security and integration patches when Pi starts. |
| Runtime tests | [`tests/pi-runtime.test.ts`](https://github.com/advaitpaliwal/feynman/blob/main/tests/pi-runtime.test.ts) | Verifies that the Pi session is correctly discovered and parsed. |
| Patch verification | [`tests/pi-runtime-patches.test.ts`](https://github.com/advaitpaliwal/feynman/blob/main/tests/pi-runtime-patches.test.ts) | Ensures all runtime patches remain effective across releases. |

## Summary

- **Feynman** manages the Pi coding agent as an embedded, long-lived subprocess with full session persistence.
- The `SessionManager` from `@earendil-works/pi-coding-agent` creates persisted session directories under the workbench data root.
- `readWorkbenchPiSessionInfo` in [`src/workbench/pi-session.ts`](https://github.com/advaitpaliwal/feynman/blob/main/src/workbench/pi-session.ts) extracts state, statistics, and timeline data from on-disk sessions.
- Live commands are normalized via `normalizePiCommands` in [`src/workbench/pi-commands.ts`](https://github.com/advaitpaliwal/feynman/blob/main/src/workbench/pi-commands.ts) and merged into the workbench resource view.
- Runtime patching scripts in `scripts/lib/pi-subagents-patch.mjs` apply security hardening and telemetry integration at startup.
- All **Pi runtime** data persists under the workbench's `sessions/` folder, enabling resume, replay, and archival capabilities.

## Frequently Asked Questions

### How does Feynman maintain Pi sessions across workbench restarts?

Feynman utilizes the `SessionManager` from `@earendil-works/pi-coding-agent` to create persisted session directories under the workbench's data root. The `readWorkbenchPiSessionInfo` function in [`src/workbench/pi-session.ts`](https://github.com/advaitpaliwal/feynman/blob/main/src/workbench/pi-session.ts) reads these on-disk representations, allowing the workbench to rebuild the complete **Pi runtime** state including timelines, tool summaries, and conversation history.

### What is the purpose of the runtime patch scripts in Feynman's Pi integration?

The `scripts/lib/pi-subagents-patch.mjs` file applies critical security-hardening fixes such as proxy-routing and TUI patches while wiring Pi's telemetry to Feynman's logging layer. These patches execute during **Pi runtime** initialization to ensure the agent operates securely and remains discoverable by the workbench's resource management system.

### How are Pi slash commands integrated into the Feynman UI?

When the **Pi runtime** publishes live slash commands during active RPC sessions, the `normalizePiCommands` function in [`src/workbench/pi-commands.ts`](https://github.com/advaitpaliwal/feynman/blob/main/src/workbench/pi-commands.ts) standardizes the raw data. The `buildPiCommandResourceGroup` function then creates a `WorkbenchResourceGroup` that `mergePiCommandResourceGroup` integrates into the existing resource view, making commands immediately available in the workbench interface.

### Where does Feynman store Pi session data?

All **Pi runtime** session data resides under the workbench's `sessions/` folder, with each session identified by a unique ID generated via `workbenchPiSessionId`. This directory structure enables the workbench to aggregate statistics, construct interaction timelines, and archive historical agent runs for future reference.