pi_harness/packages/agent/learning

Pi Agent Learning Resources

This folder contains comprehensive learning materials for understanding the Pi Agent architecture.

---

📚 Documentation Files

File	Description	Time
00-README.md	This file	5 min
01-ARCHITECTURE-OVERVIEW.md	Top-down architecture overview with diagrams	30 min
02-AGENT-LOOP-DETAILED.md	Core agent loop implementation details	45 min
03-HOOK-SYSTEM.md	Complete hook system reference	45 min
04-SESSION-ARCHITECTURE.md	Session persistence and tree structure	45 min
05-TOOL-EXECUTION.md	Tool execution mechanics	45 min
06-AGENTHARNESS-REFERENCE.md	High-level API reference	45 min
07-DATA-FLOW-STATE.md	Data flow and state management	45 min
08-LEARNING-PATH.md	Step-by-step learning guide	2 hrs
09-DIAGRAMS.md	Visual diagrams and flowcharts	30 min
10-QUICK-START.md	Quick start guide for Julia reimplementation	30 min
11-COMPLETE-SUMMARY.md	Complete reference summary	20 min

---

🎯 Learning Paths

Path 1: Fast Track (4-5 hours)

Goal: Understand enough to start implementing

1. 01-ARCHITECTURE-OVERVIEW.md - Big picture
2. 10-QUICK-START.md - Quick start guide
3. 02-AGENT-LOOP-DETAILED.md - Core loop (skim)
4. 11-COMPLETE-SUMMARY.md - Reference

Then: Start implementing in Julia

Path 2: Thorough (10-12 hours)

Goal: Deep understanding before implementation

1. 01-ARCHITECTURE-OVERVIEW.md - 30 min
2. 02-AGENT-LOOP-DETAILED.md - 45 min
3. 03-HOOK-SYSTEM.md - 45 min
4. 04-SESSION-ARCHITECTURE.md - 45 min
5. 05-TOOL-EXECUTION.md - 45 min
6. 06-AGENTHARNESS-REFERENCE.md - 45 min
7. 07-DATA-FLOW-STATE.md - 45 min
8. 09-DIAGRAMS.md - Reference throughout

Then: Follow 08-LEARNING-PATH.md for implementation

Path 3: Comprehensive (15-20 hours)

Goal: Master the entire system

1. 01-ARCHITECTURE-OVERVIEW.md - 30 min
2. 02-AGENT-LOOP-DETAILED.md - 2 hrs
3. 03-HOOK-SYSTEM.md - 2 hrs
4. 04-SESSION-ARCHITECTURE.md - 2 hrs
5. 05-TOOL-EXECUTION.md - 2 hrs
6. 06-AGENTHARNESS-REFERENCE.md - 2 hrs
7. 07-DATA-FLOW-STATE.md - 2 hrs
8. 08-LEARNING-PATH.md - Follow implementation guide
9. Read source files - src/agent.ts, src/agent-loop.ts, etc.

---

🏗️ Architecture Overview

┌───────────────────────────────────────────────────────────────────────────────┐
│                           APPLICATION LAYER                                    │
│  ┌──────────────┐    ┌──────────────────┐    ┌──────────────────────────┐    │
│  │   Agent      │    │  AgentHarness    │    │     Your Custom App      │    │
│  │  (Core)      │    │  (High-Level)    │    │                          │    │
│  └───────┬──────┘    └────────┬─────────┘    └───────────┬──────────────┘    │
└──────────┼─────────────────────┼──────────────────────────┼──────────────────┘
           │                     │                          │
           ▼                     ▼                          ▼
┌───────────────────┐  ┌─────────────────────┐  ┌───────────────────────────┐
│   Agent Core      │  │   Session System    │  │      Tool System          │
│  • agent-loop.ts  │  │  • session/         │  │  • tools/                 │
│  • agent.ts       │  │  • compaction/      │  │  • bash.ts                │
│  • types.ts       │  │  • session.ts       │  │  • read.ts                │
└─────────┬─────────┘  └──────────┬──────────┘  │  • write.ts               │
          │                        │             │  • edit.ts                │
          ▼                        ▼             └──────────┬──────────────┘
┌───────────────────────────────────────────────────────────┼──────────────────┐
│                    AGENT CORE LAYER                        │                  │
│  • Async iteration                                         │                  │
│  • Event streaming                                         │                  │
│  • Hook execution                                          │                  │
│  • Tool execution                                          │                  │
└────────────────────────────────────────────────────────────┴──────────────────┘

---

🔑 Key Concepts

1. Agent Core

• Low-level async iteration
• Message-based communication
• Event-driven state changes
• Hook system for customization

2. AgentHarness

• High-level API
• Session persistence (tree structure)
• Branching support
• Context compaction
• Tool context binding

3. Hooks

• Before/after tool execution
• Message transformation
• Context manipulation
• Queue draining

4. Session Tree

• Persistent conversation history
• Branchable conversation paths
• Context building from tree
• Compaction for efficiency

---

🎓 How to Use This Guide

For Top-Down Learning

1. Start with 01-ARCHITECTURE-OVERVIEW.md
2. Study 09-DIAGRAMS.md for visual understanding
3. Read 02-AGENT-LOOP-DETAILED.md for core implementation
4. Explore 03-HOOK-SYSTEM.md for customization
5. Understand 04-SESSION-ARCHITECTURE.md for persistence

For Quick Start

1. Read 10-QUICK-START.md
2. Use 11-COMPLETE-SUMMARY.md as reference
3. Implement while referencing other docs

For Deep Dive

1. Follow the learning path in 08-LEARNING-PATH.md
2. Read source files alongside documentation
3. Implement incrementally
4. Test each component

---

📝 Implementation Checklist

Phase 1: Data Types (Julia)

• AgentMessage type
• AgentEvent types
• AgentTool interface
• AgentContext
• AgentState

Phase 2: Core Agent

• Agent class
• State management
• Event streaming
• Queue management

Phase 3: Agent Loop

• runAgentLoop()
• streamAssistantResponse()
• executeToolCalls()
• prepareToolCall()
• Event emission

Phase 4: Hooks

• Hook registration
• Hook execution
• Return value handling

Phase 5: Session

• Tree structure
• Entry types
• Context building
• Persistence

Phase 6: AgentHarness

• High-level API
• Queue methods
• Branching
• Compaction

---

🛠️ Recommended Implementation Order

1. Data Types - Define all types in Julia
2. Core Agent - Implement Agent class with basic state
3. Event System - Implement event streaming
4. Agent Loop - Implement the main loop
5. Tool System - Implement tool execution
6. Hooks - Add hook system
7. Session - Implement session persistence
8. Harness - Add high-level API

---

📚 Related Files

• packages/agent/src/ - Source files
  • agent.ts - Agent class
  • agent-loop.ts - Core loop
  • types.ts - Type definitions
  • proxy.ts - Proxy utilities
  • stream-fn.ts - Default stream function
  • harness/ - Harness implementation

---

💡 Tips

For Julia Implementation

1. Start simple - Implement basic types first
2. Test incrementally - Test each component
3. Follow patterns - Use Julia's type system
4. Use idioms - Follow Julia conventions
5. Refer to docs - Use this guide as reference

Common Patterns

• Event-driven - Use Julia's event system
• Immutable data - Prefer immutable structures
• Multiple dispatch - Leverage Julia's dispatch
• Async/await - Use Julia's async for streaming

---

🎯 Success Criteria

After learning, you should be able to:

✅ Explain the two-layer architecture
✅ Trace a message through the system
✅ Identify when each hook is called
✅ Explain how session persistence works
✅ Describe the tool execution flow
✅ Implement a custom tool
✅ Create a conversation branch
✅ Compress conversation history

---

📞 Getting Help

• Read the documentation files
• Check the diagrams for visual understanding
• Follow the learning path for structured learning
• Refer to the complete summary for reference

---

Happy Learning! 🚀

Start with 01-ARCHITECTURE-OVERVIEW.md and 09-DIAGRAMS.md for the big picture.