Inside Pi: The Coding Agent Depicted by UML Diagrams

Chapter 1 —- The Loop

1. Figure 1.1 —- Where This Chapter Lives
2. Figure 1.2 —- A Concrete Trace
3. What the Loop Is Not
4. The Entry Points
5. Figure 1.3 —- The Two Loops
6. Figure 1.4 —- The Turn, Step by Step
7. AgentContext: The Loop’s View of the World
8. AgentLoopConfig: The Loop’s Extension Points
9. Events: The Only Observable Output
10. Design Note: Why a Pure Function?
11. Summary: What the Loop Actually Does

Chapter 2 —- The Stateful Agent

1. Figure 2.1 —- Who Owns What
2. Figure 2.2 —- Two Messages, Two Queues
3. Before the Code: The Problem with a Pure Function
4. What Agent Owns
5. subscribe and processEvents
6. prompt() vs continue()
7. The Dual-Queue Model
8. abort() and What Happens to In-Flight Tool Calls
9. runWithLifecycle: The Run Boundary
10. Failure Handling: handleRunFailure
11. createContextSnapshot and createLoopConfig
12. Figure 2.3 —- One Run, Start to Finish
13. Design Note: Why Not Subclass Agent?
14. Summary

Chapter 2.5 —- The Session Layer (AgentSession)

1. Figure 2.5.1 —- The Full Stack, Top to Bottom
2. The Gap Between the Kernel and a Real Application
3. The Package Boundary
4. What AgentSession Owns
5. Constructor: Wiring the Kernel
6. _installAgentToolHooks
7. _handleAgentEvent: The Session’s View of Every Event
8. prompt() at the Session Layer
9. _rebuildSystemPrompt: What Goes Into Every Prompt
10. AgentSessionEvent: A Richer Event Union
11. createAgentSession and createAgentSessionServices
12. Design Note: Why Composition, Not Subclassing
13. Summary: The Layer Stack

Chapter 3 —- The Tool Call Cycle

1. Figure 3.1 —- One Tool Call, Start to Finish
2. Figure 3.2 —- A Batch of Tool Calls
3. Before the Code: A Concrete bash Trace
4. Phase 1: Argument Arrival (Streaming Deltas)
5. Phase 2: Routing — Sequential or Parallel?
6. Phase 3: prepareToolCall — Validation and the beforeToolCall Hook
7. Phase 4: executePreparedToolCall — Execution and Streaming Updates
8. Phase 5: finalizeExecutedToolCall — The afterToolCall Hook
9. Phase 6: Emitting the Result
10. Phase 7: Truncated-Message Safety
11. The terminate Pattern
12. Parallel Execution: How Events Interleave
13. Design Note: Tool Errors as First-Class Results
14. Summary: The Seven Phases

Chapter 3.5 —- The Streaming Pipeline

1. Figure 3.5.1 —- Where the Pipeline Sits
2. Figure 3.5.2 —- One Tool Call, Every Event
3. Why the LLM Produces Tool Call Blocks At All
4. The StreamFn Contract
5. AssistantMessageEventStream Internals
6. The Event Protocol
7. How streamAssistantResponse Consumes the Stream
8. convertToLlm: Projecting the Transcript
9. transformContext: Pre-Projection Rewriting
10. stopReason and Loop Branching
11. A Concrete Trace: Single Tool Call
12. What Happens If the Stream Is Cut Mid-Token
13. Design Note: Why “Never Throw” Is a Hard Contract
14. Summary

Chapter 4 —- Defining Tools

1. A Tool Call Arrives: What the Loop Needs
2. Figure 4.1 —- Two Levels of Tool Abstraction
3. Two Levels: AgentTool vs ToolDefinition
4. AgentToolResult: What execute Returns
5. The Seven Built-In Tools: Design Case Studies
6. executionMode: When Sequential Ordering Matters
7. promptSnippet and promptGuidelines: Tools Advertising Themselves
8. Design Principle: execute Is Arbitrary Code
9. Closing Pattern: Sub-Agents as a Tool
10. Summary

Chapter 5 —- The System Prompt as a Living Document

1. Figure 5.1 —- Where Each Section Comes From
2. The Problem with a Fixed System Prompt
3. What buildSystemPrompt Assembles
4. The Guidelines Deduplication Rule
5. Context Files: AGENTS.md as Project-Scoped Instructions
6. Skills: Progressive Disclosure via the System Prompt
7. _rebuildSystemPrompt: Assembling from Live State
8. The Three Prompt Sources: Base, Append, Override
9. A Concrete Walk-Through: What the Model Sees
10. Design Note: Why Rebuild Rather Than Patch
11. Summary

Chapter 6 —- Provider Abstraction

1. A Concrete Failure to Open With
2. Figure 6.1 —- The Three Layers
3. Provider: The Unit of Stream Behaviour
4. Models: Auth Resolution and Dispatch
5. ModelRuntime: The Coding-Agent Layer
6. Auto-Retry and Backoff
7. Design Note: Two Layers, Not One
8. Summary

Chapter 7 —- Authentication

1. A Concrete Failure: OAuth Token Expired Mid-Session
2. The Credential Resolution Chain
3. OAuth: Double-Checked Locking for Token Refresh
4. API Keys: Stored, Ambient, and Interpolated
5. RuntimeCredentials: Session-Scoped Key Overlay
6. AuthStorage: The auth.json File Store
7. The Two ModelsError Codes
8. Design Note: Why Auth Lives in packages/ai, Not the Agent
9. Summary

Chapter 8 —- Session Persistence

1. A Concrete Failure: Losing the Conversation
2. Figure 8.1 —- Who Owns the Session
3. The File Format: A Minimal Two-Turn Session
4. Entry Types
5. The DAG: Why a Tree, Not a List
6. The Lazy-Write Contract
7. buildSessionContext(): Reconstructing the Conversation
8. Compaction Entries and the firstKeptEntryId Pointer
9. Session Discovery and the Directory Convention
10. Session Forking and Cross-Project History
11. Version Migrations
12. Design Note: Append-Only vs. Mutable State
13. Summary

Chapter 9 —- Compaction: Managing the Context Window

1. A Concrete Overflow: The Session That Stops Itself
2. The Three Triggers
3. prepareCompaction: Choosing What to Summarise
4. compact(): Generating the Summary
5. Applying the Compaction: appendCompaction and State Rebuild
6. The session_before_compact Extension Hook
7. Token Estimation: When the Provider Doesn’t Report Usage
8. Design Note: Incremental Summaries vs Full Regeneration
9. Summary

Chapter 10 —- The Extension System

1. A Concrete Extension: Auto-commit After Every Turn
2. What an Extension Is
3. The Hook Phase Table
4. ExtensionRunner: Routing Events to Multiple Extensions
5. invalidate(): Stale Context Detection
6. Registered Tools: The Same Hook Chain
7. Provider Registration
8. Design Note: Why One ExtensionContext Per Call
9. Summary

Chapter 11 —- The Skill System

1. The Problem: Context Is Finite
2. Figure 11.1 —- The Layers
3. A Concrete Trace
4. Skill File Format
5. Discovery: Where Pi Looks
6. Injecting Skills into the System Prompt
7. Explicit Invocation: /skill:name
8. Name Collision Resolution
9. Skills vs Extensions
10. Design Note: Why Descriptions, Not Keywords
11. Summary

Chapter 11.5 —- Building a Real Skill: Auto-Downloading Udemy Courses

1. The Problem: Automation Meets External Tooling
2. A Concrete Trace
3. Anatomy of the Udemy Skill
4. What Makes This a Good Skill
5. The Token Budget Trade-off
6. disableModelInvocation: Opt-In Only Skills
7. Extending the Skill: Listing and Searching
8. Skill Placement: Project vs Global
9. Pattern: The Skill as a Thin Orchestration Layer
10. Summary

Chapter 12 —- Three Run Modes

1. The Same Session, Three Surfaces
2. Figure 12.1 —- One Session, Three Dispatchers
3. Mode Resolution
4. Print Mode (runPrintMode)
5. RPC Mode (runRpcMode)
6. Interactive Mode
7. The Shared Contract
8. Design Note: Why One AgentSession, Not Three
9. Summary

Chapter 13 —- Sandboxing and Safety

1. What an Unsandboxed Agent Can Do
2. The BashOperations Abstraction
3. Three Containment Patterns
4. Threat/Mitigation Matrix
5. The tool_call Hook as a Policy Layer
6. Why No Built-in Sandbox
7. Summary

Chapter 14 —- Supply Chain and Release Hardening

1. The Threat Model
2. Figure 14.1 —- The Defence Layers
3. Exact-Version Pinning
4. The Age Gate
5. npm-shrinkwrap.json and the Lifecycle-Script Allowlist
6. The Release Script
7. CI: OIDC Trusted Publishing
8. The R2 Version Marker
9. Lockfile Commit Policy
10. Why All of This Together
11. Summary

Chapter 15 —- Use Case 1: Context Engineering

1. The Model Has No Memory
2. A Concrete Trace: What the Model Sees
3. The Six Levers
4. How the Levers Compose
5. The !-Prefix Escape Hatch
6. Practical Patterns
7. Summary

Chapter 16 —- How Pi’s AgentHarness Actually Works

1. 1. The Five Problems a Harness Solves
2. 2. AgentHarness — The Entry Point
3. 3. ExecutionEnv — The Capability Boundary
4. 4. Session, SessionStorage, SessionTree — The Storage Abstraction
5. 5. Records and reduceLaneState —- Crash Recovery
6. 6. The Agent Loop vs. The Harness Executor
7. 7. Hooks and Events — Observability Without Coupling
8. 8. Result, TaggedError, and the Two Error Layers
9. 9. Synthesis: A Dependency Inversion Checklist
10. 10. Summary

Chapter 17 —- Integrating Pi into Organizational Workflows

1. The Integration Problem
2. What Pi Provides
3. Three Levels of Pi Integration
4. Where Intelligence Belongs
5. Workflow Patterns
6. Workflow 1: Automated PR Review
7. Workflow 2: Spec -> Code -> Test
8. Workflow 3: Planner + Editors
9. Workflow 4: SonicWall Engineering Agent
10. Declarative Workflow vs Programmatic Orchestration
11. Human Approval as a First-Class Workflow Stage
12. Cross-Cutting Patterns for Programmatic Integrations
13. Observability
14. What Pi Does Not Provide
15. Designing an Agentic Workflow
16. Automation and Intelligence
17. SonicWall Target Architecture
18. Summary

Chapter 18 —- Turning Domain Knowledge into Agent Capabilities

1. The Generic/Correct Gap
2. Gap-First Diagnosis
3. When Not to Write a Skill
4. What a Skill Actually Encodes
5. Use Cases
6. Skill Granularity
7. Measuring Whether a Skill Works
8. Skill Maintenance
9. Connecting Skills, Tools, Policies, and Workflows
10. Designing a Skill Portfolio
11. Summary

Chapter 19 —- MCP and External Tools: A Case Study

1. Why Pi Has No Built-In MCP
2. The Tool Integration Decision
3. Case Study: Jira Search
4. Get one issue
5. Use JQL directly

jira-search.py

Usage: ./jira-search.py “”

Requires: JIRA_URL, JIRA_USER, JIRA_API_TOKEN env vars

1. name: jira-search description: Search Jira issues using JQL. Use when the user asks about open issues, bug assignments, sprint status, or anything in Jira. Requires JIRA_URL, JIRA_USER, and JIRA_API_TOKEN environment variables.

Jira Search

1. Search for issues
2. Typical queries

Interactive mode (both stdin and stdout must be a TTY)

Single prompt, non-interactive

Print mode (no TUI)

RPC mode (JSONL framing on stdin/stdout)

Strip all API keys from the environment first

Then configure it in ~/.pi/agent/config.json or .pi/config.json:

{ “extensions”: [{ “path”: “/abs/path/to/sandbox” }] }

From the repo root

Or from packages/coding-agent

One regression test