pi-config/extensions/pi-crew/docs/research-pi-coding-agent.md

# Research: pi-mono coding-agent Deep Read

> Ngày: 2026-04-29 | Read-only research | Source: `source/pi-mono/packages/coding-agent/`

## 1. Vai trò trong monorepo

`@mariozechner/pi-coding-agent` là package trung tâm nhất của pi-mono. Nó chứa CLI binary `pi`,
toàn bộ agent session lifecycle, extension host system, 3 run modes, 7 built-in tools, session
persistence, compaction, branch summarization, và SDK cho programmatic usage.

Package version: `0.70.5` (lockstep với toàn bộ monorepo).

## 2. Cấu trúc source

```
src/
├── cli.ts                        # Binary entry point (shebang #!/usr/bin/env node)
├── main.ts                       # CLI logic: parse args, dispatch mode (731 dòng)
├── index.ts                      # Public API exports (~250 dòng re-exports)
├── config.ts                     # Path constants (agentDir, VERSION, APP_NAME)
├── cli/                          # CLI subsystems
│   ├── args.ts                   # Argument parsing (yargs-style)
│   ├── file-processor.ts         # @file argument expansion
│   ├── initial-message.ts        # Build initial prompt from args/stdin
│   ├── list-models.ts            # --list-models output
│   └── session-picker.ts         # Interactive session selection
├── core/                         # ═══ CORE LAYER ═══
│   ├── agent-session.ts          # AgentSession class (3099 dòng) — TRUNG TÂM
│   ├── agent-session-runtime.ts  # AgentSessionRuntime wrapper (session replacement)
│   ├── agent-session-services.ts # Dịch vụ tạo cwd-bound runtime
│   ├── sdk.ts                    # createAgentSession() public factory (~408 dòng)
│   ├── session-manager.ts        # Session file I/O, entries, tree (1425 dòng)
│   ├── settings-manager.ts       # settings.json manager (~1069 dòng)
│   ├── system-prompt.ts          # System prompt builder (172 dòng)
│   ├── resource-loader.ts        # Load extensions/skills/prompts/themes (~920 dòng)
│   ├── model-registry.ts         # Model + auth registry
│   ├── model-resolver.ts         # Model resolution / scope / fallback
│   ├── keybindings.ts            # Keybinding manager (KeybindingsManager)
│   ├── messages.ts               # AgentMessage type definitions + converters
│   ├── bash-executor.ts          # Bash execution abstraction layer
│   ├── prompt-templates.ts       # File-based prompt templates (@file expansion)
│   ├── skills.ts                 # Skill loading + formatting for system prompt
│   ├── slash-commands.ts         # 21 built-in slash commands
│   ├── event-bus.ts              # Shared event bus for cross-extension communication
│   ├── footer-data-provider.ts   # Footer data provider (git branch + extension statuses)
│   ├── auth-storage.ts           # API key / OAuth credential storage
│   ├── auth-guidance.ts          # User-facing auth error messages
│   ├── extensions/               # ═══ EXTENSION SYSTEM ═══
│   │   ├── types.ts              # Type surface (1545 dòng)
│   │   ├── loader.ts             # jiti-based extension loader (~607 dòng)
│   │   ├── runner.ts             # ExtensionRunner lifecycle manager (~1024 dòng)
│   │   ├── wrapper.ts            # Tool wrapping utilities
│   │   └── index.ts              # Re-exports (~170 dòng)
│   ├── compaction/               # ═══ COMPACTION ═══
│   │   ├── compaction.ts         # Context compaction logic (~840 dòng)
│   │   ├── branch-summarization.ts # Tree navigation summarization (~356 dòng)
│   │   ├── utils.ts              # File ops tracking + serialization
│   │   └── index.ts
│   └── tools/                    # ═══ BUILT-IN TOOLS ═══
│       ├── index.ts              # Tool registry + factories (~198 dòng)
│       ├── read.ts               # File reading with truncation
│       ├── bash.ts               # Shell command execution
│       ├── edit.ts               # Exact text replacement
│       ├── write.ts              # File creation/overwrite
│       ├── grep.ts               # Regex search
│       ├── find.ts               # File name search
│       ├── ls.ts                 # Directory listing
│       ├── file-mutation-queue.ts # Serialized file writes
│       ├── truncate.ts           # Output truncation strategies
│       └── render-utils.ts
├── modes/                        # ═══ RUN MODES ═══
│   ├── index.ts                  # Re-exports
│   ├── interactive/              # Interactive TUI mode (5470 dòng)
│   │   ├── interactive-mode.ts   # Main TUI loop + all slash commands
│   │   ├── components/           # 30+ TUI components (assistant messages, diffs, editors...)
│   │   └── theme/                # Theme engine (JSON-based, hot-reload)
│   ├── print-mode.ts             # Non-interactive / JSON output mode
│   └── rpc/                      # JSON-RPC mode for embedding (parent-child protocol)
│       ├── rpc-mode.ts           # RPC server loop
│       ├── rpc-client.ts         # RPC client for SDK/programmatic use
│       ├── rpc-types.ts          # JSON-RPC message types
│       └── jsonl.ts              # JSONL output formatting
└── utils/                        # Shared utilities
    ├── clipboard.ts              # Clipboard integration
    ├── frontmatter.ts            # YAML frontmatter parser
    ├── shell.ts                  # Shell detection/config
    ├── paths.ts                  # Path utilities
    └── sleep.ts                  # Promise-based sleep
```

## 3. Các file chính - số dòng

| File | Dòng | Mô tả |
|---|---|---|
| `modes/interactive/interactive-mode.ts` | 5470 | Interactive TUI + tất cả 21 slash command handlers |
| `core/agent-session.ts` | 3099 | AgentSession class: prompt, compaction, bash, model management |
| `core/extensions/types.ts` | 1545 | Toàn bộ type surface cho extension system |
| `core/session-manager.ts` | 1425 | Session file I/O, entry types, tree operations |
| `core/settings-manager.ts` | ~1069 | JSON settings management (global + project) |
| `core/extensions/runner.ts` | ~1024 | ExtensionRunner: event emission, context binding |
| `core/resource-loader.ts` | ~920 | Unified loader for extensions/skills/prompts/themes |
| `core/compaction/compaction.ts` | ~840 | Compaction logic + cut-point detection |
| `main.ts` | 731 | CLI entry: arg parsing → mode dispatch |
| `core/extensions/loader.ts` | ~607 | jiti-based TypeScript module loading |

## 4. Luồng thực thi chính

### 4.1 Startup sequence (`main.ts`)

```
main(args)
  ├── parseArgs(args)                          # Parse CLI flags
  ├── resolveAppMode()                         # interactive | print | json | rpc
  ├── runMigrations()                          # Upgrade old session formats
  ├── createSessionManager()                   # new/fork/continue/resume/in-memory
  ├── createAgentSessionRuntime(createRuntime) # Build full runtime
  │     └── createRuntime(cwd, agentDir, sessionManager)
  │           ├── createAgentSessionServices()  # authStorage, modelRegistry, resourceLoader
  │           ├── resolveModelScope()           # --models flag → scoped models
  │           ├── buildSessionOptions()         # model, thinking, tools, scopedModels
  │           └── createAgentSessionFromServices() → AgentSession
  ├── readPipedStdin()                         # Pipe support
  ├── prepareInitialMessage()                  # text + images
  └── dispatch:
        ├── interactive → new InteractiveMode(runtime).run()
        ├── print/json  → runPrintMode(runtime, {...})
        └── rpc         → runRpcMode(runtime)
```

### 4.2 AgentSession.prompt() lifecycle

```
session.prompt(text)
  ├── parseSkillBlock()                  # <skill name="..." location="...">
  ├── expandPromptTemplate()             # @file expansion
  ├── emitInput()                        # Extension can transform/block input
  ├── emitBeforeAgentStart()             # Extension can inject custom message / swap system prompt
  ├── agent.runAgentLoop()
  │     ├── context → extension transform messages
  │     ├── before_provider_request → extension modify payload
  │     ├── streamSimple(model, context, ...)
  │     ├── after_provider_response → extension observe response
  │     ├── tool_call → extension intercept/block/mutate args
  │     ├── tool_execution_start/update/end
  │     ├── tool_result → extension modify result
  │     └── auto-compaction check (after turn_end)
  └── emitAgentEnd()
```

### 4.3 Run modes

| Mode | Class/Function | Đặc điểm |
|---|---|---|
| **Interactive** | `InteractiveMode` (5470 dòng) | Full TUI: chat history, editor, widgets, themes, overlays, keybindings |
| **Print/JSON** | `runPrintMode()` | Pipe/script: plain text or JSON mode, no TUI |
| **RPC** | `runRpcMode()` | JSON-RPC 2.0 over stdin/stdout — dùng làm child process protocol |

## 5. AgentSession class chi tiết

### 5.1 Properties

```typescript
class AgentSession {
  readonly agent: Agent;                    // Core agent instance
  readonly sessionManager: SessionManager;  // Session file I/O
  readonly settingsManager: SettingsManager;// Settings

  // Model access
  get model(): Model<any> | undefined;
  get thinkingLevel(): ThinkingLevel;
  get scopedModels(): Array<{model, thinkingLevel}>;

  // Tool access
  get toolNames(): string[];               // Currently active tools
  get tools(): ToolInfo[];                 // All registered tools with metadata
  getAllTools(): ToolInfo[];

  // Context
  getContextUsage(): ContextUsage | undefined;
  isIdle(): boolean;

  // Core operations
  prompt(text, options?): Promise<void>;   // Send user message
  abort(): void;                           // Abort current operation
  shutdown(): void;                        // Graceful shutdown

  // Model management
  cycleModel(forward?): ModelCycleResult;  // Ctrl+P cycling
  setModel(model): Promise<boolean>;       // Switch model
  setThinkingLevel(level): void;

  // Compaction
  compact(options?): void;                 // Manual compaction
  getSessionStats(): SessionStats;         // Usage stats
}
```

### 5.2 Internal state machine

Key internal flags:
- `_steeringMessages[]` / `_followUpMessages[]`: Queued messages
- `_compactionAbortController` / `_autoCompactionAbortController`: Compaction control
- `_overflowRecoveryAttempted`: Context overflow recovery flag
- `_retryAttempt` / `_retryPromise`: Auto-retry state
- `_bashAbortController` / `_pendingBashMessages[]`: Bash execution state
- `_turnIndex`: Current turn counter

### 5.3 Tool hooks

`_installAgentToolHooks()` installs interceptors on the Agent instance:
- `beforeToolCall`: Check if extension wants to intercept/block
- `onToolResult`: Check if extension wants to modify result

## 6. Session Persistence (`session-manager.ts`)

### 6.1 Session file format

JSONL file (`.pi/sessions/{id}.jsonl`) với các entry types:

| Entry Type | Purpose | Fields |
|---|---|---|
| `session` | Header | version, id, timestamp, cwd, parentSession |
| `message` | AgentMessage (user/assistant/toolResult) | message |
| `thinking_level_change` | Thinking level change | thinkingLevel |
| `model_change` | Model switch | provider, modelId |
| `compaction` | Compaction summary | summary, firstKeptEntryId, tokensBefore, details |
| `branch_summary` | Branch navigation | summary, fromId, details |
| `custom_message` | Extension-defined for LLM context | customType, content, display, details |
| `custom` | Extension state (not in LLM context) | customType, data |

Current version: `CURRENT_SESSION_VERSION = 3`

### 6.2 Session tree

- Mỗi session có `parentSession` reference (khi fork)
- `SessionManager.forkFrom()` tạo session mới
- `buildSessionContext()` dựng messages từ entries (cả compaction + branch summary)
- `navigateTree()` di chuyển giữa các branch trong cùng session

## 7. Compaction System

### 7.1 Auto-compaction (`compaction/compaction.ts`)

Default settings:
```
reserveTokens: 16384    # Dành cho system prompt + LLM response
keepRecentTokens: 20000 # Giữ các messages gần đây
```

Process:
1. `shouldCompact()` — kiểm tra context usage sau mỗi turn
2. `findCutPoint()` — tìm vị trí cắt dựa vào file operations
3. `prepareCompaction()` — build messagesToSummarize + turnPrefixMessages
4. `compact()` — serialize → LLM summarize → return CompactionResult
5. SessionManager lưu `CompactionEntry` + tạo session mới (reload)

### 7.2 Branch summarization (`compaction/branch-summarization.ts`)

Khi user navigate session tree, tạo summary của branch hiện tại:
- `collectEntriesForBranchSummary()` — thu thập entries cần summarize
- `prepareBranchEntries()` — extract messages + file operations
- `generateBranchSummary()` — gọi LLM tạo summary

### 7.3 Cut-point strategy

Tìm cut-point dựa trên:
- File operations: ưu tiên cắt ở điểm không có pending file modifications
- Assistant messages: không cắt giữa tool calls
- Keep recent tokens: giữ ít nhất `keepRecentTokens` cuối cùng

## 8. Built-in Tools

7 tools, mỗi tool có 2 representations:
- `AgentTool` — runtime execution contract
- `ToolDefinition` — type-safe definition với schema + render

| Tool | File | Key params | Đặc điểm |
|---|---|---|---|
| `read` | `tools/read.ts` | path, offset, limit | Head/tail truncation, image support |
| `bash` | `tools/bash.ts` | command, timeout | AbortController, timeout |
| `edit` | `tools/edit.ts` | path, edits[{oldText,newText}] | Exact replacement, multi-edit |
| `write` | `tools/write.ts` | path, content | Overwrite/create |
| `grep` | `tools/grep.ts` | pattern, path | Regex search |
| `find` | `tools/find.ts` | pattern, path | File name glob |
| `ls` | `tools/ls.ts` | path | Directory listing |

**File mutation queue** (`file-mutation-queue.ts`): Serializes write operations to prevent
parallel tool conflicts. Used internally by edit/write tools.

## 9. Settings Manager (`settings-manager.ts`)

Quản lý `settings.json` với các section:

| Section | Key settings | Default |
|---|---|---|
| `compaction` | enabled, reserveTokens, keepRecentTokens | true, 16384, 20000 |
| `retry` | enabled, maxRetries, baseDelayMs | true, 3, 2000 |
| `retry.provider` | timeoutMs, maxRetries, maxRetryDelayMs | (SDK defaults) |
| `terminal` | showImages, imageWidthCells, clearOnShrink, showTerminalProgress | true, 60, false, false |
| `images` | autoResize, blockImages | true, false |
| `thinkingBudgets` | minimal, low, medium, high | (per-level defaults) |
| `markdown` | codeBlockIndent | "  " |

Scope: global (`~/.pi/agent/settings.json`) + project-local (`.pi/settings.json`).

## 10. Slash Commands

21 built-in commands (`slash-commands.ts`):

| Command | Purpose |
|---|---|
| `settings` | Open settings menu |
| `model` | Select model (selector UI) |
| `scoped-models` | Enable/disable models for Ctrl+P |
| `export` | Export session (HTML/JSONL) |
| `import` | Import session from JSONL |
| `share` | Share as GitHub gist |
| `copy` | Copy last message |
| `name` | Set session display name |
| `session` | Show session info + stats |
| `changelog` | Show changelog |
| `hotkeys` | Show keyboard shortcuts |
| `fork` | Fork from previous message |
| `clone` | Duplicate session |
| `tree` | Navigate session tree |
| `login`/`logout` | Auth management |
| `new` | Start new session |
| `compact` | Manual compaction |
| `resume` | Resume different session |
| `reload` | Reload extensions/skills/themes |
| `quit` | Exit |

## 11. RPC Mode

JSON-RPC 2.0 protocol qua stdin/stdout:

```typescript
// Request
{ "jsonrpc": "2.0", "id": 1, "method": "prompt", "params": { "text": "..." } }

// Response
{ "jsonrpc": "2.0", "id": 1, "result": { "messages": [...], "usage": {...} } }

// Notification (no id)
{ "jsonrpc": "2.0", "method": "event", "params": { "type": "message_start", ... } }
```

Đây là protocol chính cho parent-child communication trong pi-subagents và pi-crew.

## 12. Các điểm đáng chú ý

1. **Interactive mode quá lớn** (5470 dòng) — chứa hầu hết slash command implementations
2. **AgentSession quá lớn** (3099 dòng) — mixed concerns: prompt, compaction, bash, lifecycle
3. **Extension type surface** (1545 dòng) — rất comprehensive nhưng complex
4. **Lockstep versioning** — tất cả packages cùng version 0.70.5
5. **jiti-based extension loading** — cho phép TypeScript extensions không cần compile
6. **Virtual modules** — cho Bun compiled binary, bundle sẵn các dependencies