Opening Pi Along the Call Chain

Having finished Part I · Concepts, Xiao A felt he "understood": how a model generates, how tools get called, how the loop turns, how sessions are stored. He shut the concepts book, opened the pi-mono source directory, and meant to pick one real Agent to look at.

Ten minutes later he was staring blankly at a screenful of packages/ directories. ai, agent, coding-agent, tui, protocol... more than a dozen folders. Which one is the entry point? Which one is the main road?

He went to Lao Z. "I can recite the concepts, but I can't tell where to start with this code."

Lao Z laughed. "Concepts answer 'how this kind of thing usually works'. The question you have to answer now is different: where a real Agent creates its request, how it moves state forward, and when it interrupts or saves a session. That needs a source snapshot you can re-check, not guesses from impression. We pick pi-mono, and we read it by package boundaries and by one end-to-end call chain."

"Then which version am I looking at? Will it change again in a couple of days?"

The baseline and the evidence rules for this part

• Repository: earendil-works/pi (formerly badlogic/pi-mono; this book still calls it pi-mono)
• Pinned tag and commit: v1.0.0, a13d35a742c6ef8462812a28fbe1d8c8b7431c32
• Version boundary: root repository 0.0.3; the eight packages selected by this book 1.0.0
• Commit date: 2026-10-01

pi/ at the root of this book's repository is a source snapshot of that tag. Every TypeScript file in it carries added Chinese comments, and the snapshot has no git history of its own. Paths and symbols match upstream. Line numbers follow the upstream tag and shift inside the snapshot because of the comments. To check the original, clone upstream elsewhere and check out v1.0.0.

Xiao A pressed: "How do I check the code and the conclusions in the book?"

"Remember three evidence rules. They apply wherever you read," Lao Z said.

Evidence rules

• A confirmed fact must trace back to a file path or symbol name in that snapshot, or to official primary material. A line number is only a locator within that snapshot.
• An inference from source says "this means" or "one can infer" only from structure and call relationships. It is never written as the author's intent.
• Illustrative or simplified pseudocode, abridged code, flow diagrams, and hypothetical scenarios are labelled as such. They are not complete real source.

"One more thing," Lao Z added. "'Making the source clear' is not the same as going through every source line. This part promises to make the core entry points, the key types, the main call chains, the state changes, the error paths, and the design costs clear, and to give you a walkthrough route you can keep following on your own."

Xiao A guessed: "So should I first go through the names of all those folders?"

"Don't rush to memorize names. What to hold onto is one more concrete question." Lao Z typed a line on the screen. "How does a single user input enter the system from the command line and become a model stream, a tool execution, a session record, and a terminal update? The answer is hidden in that chain."

What this part solves

After reading Part II · Pi in Source, you can walk pi-mono's call chain on your own: from the entry point, find how a model request gets sent, how the stream passes through the adapter layer, how the loop moves state forward, how a session outlives a process restart, how the terminal refreshes, how tools and extensions plug in, how the protocol becomes bytes, how a remote session stays consistent, and how an evaluation judges one change. The core is to build a verifiable map: when you hit a bug or want to extend something, you know which file to look at.

This part does not do three things: explain every source line, cover every edge feature, or promote a limited sample into a global conclusion. What is not covered gets stated in the relevant chapter, and is never implied to have been fully explained.

"Why not pick another repository? Why must it be pi-mono?"

"Because it is a real TypeScript Agent repository that runs end to end, and its package boundaries line up with the boundaries Part I · Concepts drew," Lao Z said. "Provider, loop, session, tool, protocol, evaluation — for everything Part I · Concepts talks about, pi-mono has a matching package and call chain. Only with one concrete repository can you point at a line and say 'this is where it is implemented', instead of talking abstractly about concepts."

"Is there a general method for reading source?" Xiao A asked.

"There is. Three habits are enough to get started," Lao Z said.

Three habits for reading source

1. Entry points before details: come in through the exports of index.ts and some create* / run* function. See the main path clearly before drilling into branches.
2. Contracts before implementations: read a module's types.ts or its interface definitions first. Implementation detail is needed only when you suspect a bug.
3. State before logic: what members a class has, and who changes them when, matter ten times more than how cleverly one if is written.

Eight Packages, Not Eight Islands

Xiao A opened the packages/ directory and counted 13 folders. Lao Z reminded him:

"Ignore the extras for now. This book selects eight of the 13 packages: pi-ai, pi-agent-core, pi-coding-agent, pi-tui, pi-protocol, pi-server, pi-client, and pi-evals. They are not eight isolated directories; they are different responsibility boundaries on one end-to-end call chain. chord and telemetry get named only where they are used; codemode and mcp get their own appendices (Appendix 10 and Appendix 11); durable is the subject of Part II Chapter 13. Extension examples and the other workspaces are not on this list either."

The 13-Chapter Source Route

1. Part II Chapter 1: The Map's Scale — pi-mono: build the map of the repository, the package boundaries, the dependency direction, and the main call chain.
2. Part II Chapter 2: The Catalog and the Household Register — pi-ai: trace the Providers, model catalog, auth, and request entry points of pi-ai.
3. Part II Chapter 3: Issue the Ticket First, Do the Work After — pi-ai: examine message transformation, event streams, retries, aborts, errors, and the compatibility layer.
4. Part II Chapter 4: The Double Loop — pi-agent-core: read the Agent, loop, message queue, tool events, and stop paths of pi-agent-core.
5. Part II Chapter 5: The Dispatch Desk — pi-coding-agent: analyse how AgentSession plugs into Agent's socket, together with JSONL sessions, fork, compaction, and skills, and make clear that a session fork is not a Git worktree.
6. Part II Chapter 6: The Dispatch Desk and the Workstations — pi-tui: walk the component tree, diff rendering, width computation, input handling, and fallbacks of pi-tui.
7. Part II Chapter 7: The Address on the Household Register — pi-coding-agent: go from the arguments, configuration, and resource loading of pi-coding-agent through to model, session, and interaction assembly.
8. Part II Chapter 8: Queuing at the Checkout — pi-coding-agent: examine the built-in tools, the file concurrency queue, output truncation, the extension runner, Hooks, project trust, and the sandbox boundaries.
9. Part II Chapter 9: Shipping and Customs Clearance — pi-protocol: read the envelope schema, CBOR, framing, versions, and error semantics of pi-protocol.
10. Part II Chapter 10: The Blackboard and the Sticky Notes — pi-server + pi-client: trace the connections, handshakes, request routing, session attachment, subscription snapshots, and reconnection boundaries of pi-server and pi-client.
11. Part II Chapter 11: A New Exam Hall Every Time — pi-evals: tell apart the behaviour checks, the docs-controlled experiments, the judge results, and the subjective-quality limits of pi-evals.
12. Part II Chapter 12: The Relay Race — End-to-End: bring CLI input, model stream, tool execution, session record, and TUI update together into one control flow and one data flow.

Xiao A scanned the list. "How is each chapter meant to be read?"

"Every chapter starts from one main path you can walk, and checks at least one error, interruption, or boundary path along the way. It does not replace reading every file in the repository yourself."

"If time is short and I read only the trunk, which chapters should I read?"

"Pick one thread that runs all the way through," Lao Z said. "Part II Chapter 1 for the map, Part II Chapter 2 for how a model request gets sent, Part II Chapter 4 for how the loop turns, Part II Chapter 5 for how a session outlives the process, Part II Chapter 12 for how one complete request travels from the CLI to the TUI. String those five together and you have the trunk of Part II · Pi in Source. The other chapters are branches off that trunk; come back to them as needed."

The trunk reading line of Part II · Pi in Source

Part II Chapter 1 map → Part II Chapter 2 model request → Part II Chapter 4 loop → Part II Chapter 5 session → Part II Chapter 12 end to end

With more time, spread sideways from the trunk: Part II Chapter 3 streaming adapters, Chapters 23–24 terminal and startup, Part II Chapter 8 tools and extensions, Chapters 26–27 protocol and remote, Part II Chapter 11 evaluation.

"What is the difference between reading this part and not having read it?"

"The difference is whether you can point at a line of code and say clearly why it exists," Lao Z said. "Part I · Concepts told you how the boundaries should be drawn. Part II · Pi in Source lets you see a real system actually drawing them, and lets you see what goes wrong when it draws them only halfway. Only after this part do the concepts in your hand move from 'heard of' to 'checked'."

Lao Z closed with a reminder: "Every conclusion in Part II · Pi in Source is anchored to one commit. The line numbers, symbols, and call relationships you read all take v1.0.0 (a13d35a7) as their baseline. If you go and read a newer version of the code, the structure may already have changed. That is not a flaw in the book; it is an inherent property of reading source. Keeping 'true in this snapshot' apart from 'always true' is the basic skill of source reading."

Start here: Part II Chapter 1: The Map's Scale — pi-mono