pi-crew 0.1.51 → 0.2.0

package/docs/research/AGENT-EXECUTION-ARCHITECTURE.md

@@ -1,261 +0,0 @@
-# pi-crew vs oh-my-pi: Agent Execution Architecture Comparison
-
-> **Ngày**: 2026-05-07
-> **Mục đích**: Tài liệu nghiên cứu để quyết định hybrid execution model
-
----
-
-## 1. Kiến trúc execution hiện tại
-
-### oh-my-pi: In-process
-
-```
-User → TaskTool.execute()
-  → mapWithConcurrencyLimit(tasks, maxConcurrency, runSubprocess)
-    → Worker 1: createAgentSession() → session.prompt(task)
-    → Worker 2: createAgentSession() → session.prompt(task)
-    → Worker 3: createAgentSession() → session.prompt(task)
-  → Collect results via EventBus subscription
-```
-
-**Key files:**
-- `Source/oh-my-pi/packages/coding-agent/src/task/executor.ts` (1291 dòng) — `runSubprocess()`
-- `Source/oh-my-pi/packages/coding-agent/src/task/parallel.ts` — `mapWithConcurrencyLimit()` + `Semaphore`
-- `Source/oh-my-pi/packages/coding-agent/src/sdk.ts` — `createAgentSession()` factory
-
-**Flow chi tiết:**
-1. `createAgentSession({ cwd, model, tools, systemPrompt, ... })` — tạo AgentSession mới
-2. `session.prompt(task)` — gửi task text, agent loop chạy trong process
-3. EventBus subscription lắng nghe events (tool_execution_start/end, message, yield)
-4. Worker **phải** gọi `yield` tool đúng 1 lần → result extraction
-5. Nếu không yield → gửi reminder prompt (tối đa 3 lần)
-6. `session.waitForIdle()` → collect final result
-
-### pi-crew: Child-process (default) + Live-session (in-process)
-
-```
-User → team tool → handleRun()
-  → executeTeamRun()
-    → mapConcurrent(batchTasks, concurrency, runTeamTask)
-      → Task 1: runChildPi() → spawn("pi", [...args]) → parse stdout JSONL
-      → Task 2: runChildPi() → spawn("pi", [...args]) → parse stdout JSONL
-      → Task 3: runLiveSession() → createAgentSession() → session.prompt()
-```
-
-**Key files:**
-- `src/runtime/child-pi.ts` (458 dòng) — child process spawn + stdout capture
-- `src/runtime/live-session-runtime.ts` (245 dòng) — in-process execution via Pi SDK
-- `src/runtime/parallel-utils.ts` — `mapConcurrent()` worker pool
-- `src/runtime/runtime-resolver.ts` — chọn child-process vs live-session
-
-**2 execution modes:**
-| Mode | Khi nào dùng | File |
-|------|-------------|------|
-| `child-process` | Default, production | `child-pi.ts` |
-| `live-session` | Khi Pi host expose SDK | `live-session-runtime.ts` |
-
----
-
-## 2. So sánh chi tiết
-
-### 2.1 Performance & Overhead
-
-| Metric | oh-my-pi (in-process) | pi-crew (child-process) | pi-crew (live-session) |
-|--------|----------------------|------------------------|----------------------|
-| Worker startup | ~50ms (createAgentSession) | ~2-5s (spawn pi CLI) | ~50ms (createAgentSession) |
-| IPC overhead | Zero (function calls) | JSON parse mỗi line | Zero (function calls) |
-| MCP connections | Share parent's | Mỗi worker tự discover | Share parent's |
-| Memory per worker | ~10-50MB (AgentSession) | ~100-200MB (full pi process) | ~10-50MB |
-| Model registry | Shared | Separate | Shared |
-
-### 2.2 Fault Isolation
-
-| Scenario | oh-my-pi | pi-crew (child-process) | pi-crew (live-session) |
-|----------|----------|------------------------|----------------------|
-| Worker throws unhandled | ❌ Crash toàn process | ✅ Chỉ worker chết | ❌ Crash toàn process |
-| Worker infinite loop | ❌ Block event loop | ✅ Timeout + kill | ❌ Block event loop |
-| Worker memory leak | ❌ Accumulate | ✅ OS cleanup khi exit | ❌ Accumulate |
-| Worker segfault | ❌ Process die | ✅ Isolated | ❌ Process die |
-
-### 2.3 Result Collection
-
-| Aspect | oh-my-pi | pi-crew (child-process) | pi-crew (live-session) |
-|--------|----------|------------------------|----------------------|
-| Contract | Yield tool (mandatory, 1 lần) | Parse stdout JSONL (ad-hoc) | TBD (chưa enforce) |
-| Validation | JTD/JSON Schema on yield | Không có | TBD |
-| Reminder | 3 reminders nếu quên yield | Không có | Không có |
-| Extraction | SubprocessToolRegistry (extensible) | SubprocessToolRegistry (mới thêm) | SubprocessToolRegistry |
-
-### 2.4 Communication
-
-| Channel | oh-my-pi | pi-crew |
-|---------|----------|---------|
-| Parent → Worker | `session.abort()`, AbortSignal | `child.kill()`, AbortSignal, stdin |
-| Worker → Parent | EventBus (in-process, typed channels) | stdout JSONL + RunEventBus (5 channels) |
-| Inter-agent | IRC tool (DM/broadcast) | Mailbox (task-scoped) |
-| Mid-turn steering | ✅ `session.abort()` + continue | ✅ Live-session: steer; Child: cancel only |
-| Progress | EventBus typed channels | RunEventBus typed channels |
-
-### 2.5 Parallel Execution
-
-| Aspect | oh-my-pi | pi-crew |
-|--------|----------|---------|
-| Pool primitive | `Semaphore` (explicit acquire/release) | `mapConcurrent` (implicit worker pool) |
-| Fail-fast | `Promise.race([all, firstError])` | Worker loop + signal check |
-| Max concurrency | Config `task.maxConcurrency` | `MAX_PARALLEL_CONCURRENCY = 4` |
-| Cancellation | AbortSignal per worker | AbortSignal + cancel events |
-| Host dispatch | 1 call → N workers (in-process) | 1 call → N child processes hoặc `parallel` action |
-
----
-
-## 3. pi-crew đã có gì từ oh-my-pi
-
-| Feature | oh-my-pi | pi-crew status |
-|---------|----------|---------------|
-| In-process execution | ✅ Core design | ✅ `live-session-runtime.ts` (đã có) |
-| Yield-based completion | ✅ Mandatory | ✅ `yield-handler.ts` (mới thêm, chưa enforce) |
-| SubprocessToolRegistry | ✅ Extensible | ✅ `subprocess-tool-registry.ts` (mới thêm) |
-| Typed event channels | ✅ 3 channels | ✅ 5 channels (mới thêm) |
-| Semaphore concurrency | ✅ Explicit | ✅ Via `mapConcurrent` |
-| MCP proxy tools | ✅ Share parent MCP | ❌ Mỗi worker tự discover |
-| IRC inter-agent | ✅ DM/broadcast | ❌ Chỉ mailbox |
-| Human-readable names | ✅ AdjectiveNoun | ✅ `task-name-generator.ts` |
-| Handlebars templates | ✅ | ❌ String concatenation |
-| FUSE/ProjFS isolation | ✅ 3 backends | ❌ Chỉ worktree |
-
-## 4. pi-crew features mà oh-my-pi KHÔNG có
-
-| Feature | Detail |
-|---------|--------|
-| Process isolation | Child-process mode → fault boundary |
-| Crash recovery | Manifest + event sourcing → resume sau crash |
-| Adaptive planning | Planner agent quyết định fanout dynamically |
-| Policy engine | Configurable rules cho effectiveness, concurrency, etc. |
-| Deadletter tracking | Permanently failed task tracking |
-| Event log rotation | Auto-compact over 5MB/50k events |
-| Blob artifact store | SHA-256 content-addressed storage |
-| Hook lifecycle | 8/9 typed hooks with blocking support |
-| Incremental reader | Seek-based JSONL reading |
-| Parallel dispatch action | `team action='parallel'` for multi-task fanout |
-
----
-
-## 5. Nghiên cứu tiếp theo
-
-### 5.1 Hybrid model: Best of both worlds
-
-**Ý tưởng**: Chọn execution mode tự động per-task thay vì global config.
-
-```
-executeTeamRun()
-  → resolveCrewRuntime() → check live-session available
-  → for each task:
-      if (lightweight, trusted agent) → live-session (in-process, fast)
-      if (heavy, untrusted, risky) → child-process (isolated, safe)
-```
-
-**Implementation plan:**
-1. Extend `runtime-resolver.ts` → per-task runtime selection
-2. Add `agent.trustLevel` field → "trusted" (in-process) / "untrusted" (child-process)
-3. Wire `live-session-runtime.ts` into `task-runner.ts` as alternative to `child-pi.ts`
-4. Add fallback: if live-session crashes → retry with child-process
-
-### 5.2 MCP proxy cho child-process mode
-
-Hiện mỗi child process tự discover MCP connections → chậm.
-
-**Ý tưởng**: Parent discover MCP → serialize config → pass cho child via env/args.
-
-```
-Parent:
-  mcpManager = discoverMCPConnections()
-  mcpConfig = mcpManager.serialize()
-  child = spawn("pi", [...args, `--mcp-config=${base64(mcpConfig)}`])
-```
-
-### 5.3 Yield enforcement cho live-session
-
-Live-session đã dùng `session.prompt()` nhưng chưa enforce yield.
-
-**Ý tưởng**: 
-1. Register `submit_result` as required tool khi tạo live-session
-2. Sau `session.prompt()` + `waitForIdle()`, check yieldCalled
-3. Nếu chưa yield → gửi reminder (giống oh-my-pi)
-
-### 5.4 Semaphore thay mapConcurrent
-
-`mapConcurrent` hiện tại là simple worker pool. `Semaphore` explicit hơn cho:
-- Dynamic acquire/release
-- Rate limiting across multiple scheduling points
-- Priority queue (future)
-
-### 5.5 Handlebars templates cho prompts
-
-Hiện `prompt-builder.ts` dùng string concatenation. Template engine sẽ dễ maintain:
-```
-{{#if hasSkills}}
-## Available Skills
-{{#each skills}}
-- {{name}}: {{description}}
-{{/each}}
-{{/if}}
-```
-
-### 5.6 IRC-style inter-agent messaging
-
-Hiện chỉ có mailbox (task-scoped). Cần thêm:
-- Broadcast: agent gửi message cho tất cả agents trong run
-- DM: agent gửi cho agent cụ thể
-- Pub/sub channel: subscribe theo topic
-
----
-
-## 6. Decision matrix: Khi nào dùng mode nào
-
-| Criteria | child-process | live-session (in-process) |
-|----------|--------------|--------------------------|
-| Production safety | ✅ Preferred | ⚠️ Chỉ khi trust agents |
-| Speed critical tasks | ❌ Slow startup | ✅ Preferred |
-| Many parallel workers | ⚠️ Memory heavy | ✅ Lightweight |
-| Untrusted/third-party agents | ✅ Isolated | ❌ Never |
-| Debugging | ⚠️ Hard (separate process) | ✅ Easy (same process) |
-| Crash recovery | ✅ Manifest-based | ❌ State lost on crash |
-| MCP sharing | ❌ Separate discovery | ✅ Share parent's |
-| Steering mid-turn | ❌ Cancel only | ✅ Full control |
-
-**Recommended default**: child-process (safe) với opt-in live-session cho trusted agents.
-
----
-
-## 7. Key source files cho reference
-
-### oh-my-pi (Source/oh-my-pi/packages/coding-agent/src/)
-| File | Lines | Purpose |
-|------|-------|---------|
-| `task/executor.ts` | 1291 | In-process subagent execution |
-| `task/parallel.ts` | 100 | Semaphore + mapWithConcurrencyLimit |
-| `task/index.ts` | 1275 | Task tool entry point, parallel orchestration |
-| `task/subprocess-tool-registry.ts` | 80 | Extensible tool event handlers |
-| `task/types.ts` | 230 | Core types, event channel constants |
-| `sdk.ts` | 1900 | AgentSession factory |
-| `session/agent-session.ts` | 7500 | Core agent session (GOD OBJECT) |
-| `tools/yield.ts` | 170 | Submit result tool with schema validation |
-| `tools/irc.ts` | 250 | Inter-agent messaging |
-| `config/settings-schema.ts` | 2700 | Single source of truth cho all settings |
-
-### pi-crew (pi-crew/src/)
-| File | Lines | Purpose |
-|------|-------|---------|
-| `runtime/child-pi.ts` | 458 | Child process execution |
-| `runtime/live-session-runtime.ts` | 245 | In-process execution via Pi SDK |
-| `runtime/runtime-resolver.ts` | 100 | Mode selection |
-| `runtime/parallel-utils.ts` | 100 | mapConcurrent worker pool |
-| `runtime/team-runner.ts` | 800 | Workflow scheduler |
-| `runtime/task-runner.ts` | 430 | Per-task execution |
-| `runtime/yield-handler.ts` | 100 | Yield-based completion |
-| `runtime/subprocess-tool-registry.ts` | 55 | Tool event handlers |
-| `ui/run-event-bus.ts` | 207 | Typed event channels |
-| `extension/team-tool/parallel-dispatch.ts` | 120 | Parallel action dispatcher |
-| `state/event-log-rotation.ts` | 115 | Event log compaction |
-| `utils/incremental-reader.ts` | 93 | Seek-based file reading |
-| `utils/task-name-generator.ts` | 224 | Human-readable task names |

package/docs/research/AGENT-LIFECYCLE-COMPARISON.md

@@ -1,111 +0,0 @@
-# Agent Lifecycle: pi-crew vs oh-my-pi
-
-## Architecture Fundamental Difference
-
-| Aspect | oh-my-pi | pi-crew |
-|--------|----------|---------|
-| **Execution model** | In-process (`createAgentSession()`) | Child process (`child_process.spawn()`) |
-| **Agent tracking** | In-memory `Map<string, AgentRef>` | File-based `active-run-index.json` |
-| **Lifetime** = Process lifetime | ✅ Yes (GC + process exit cleans everything) | ❌ No (files persist after process exit) |
-| **Abort mechanism** | `AbortController` → `session.abort()` | File-based status + process kill |
-
-## Edge Case Matrix
-
-### Case 1: Normal session exit (user types /exit or Pi quits normally)
-
-| | oh-my-pi | pi-crew |
-|--|----------|---------|
-| **Path** | `shutdown()` → `dispose()` → `session_shutdown` event | Same — Pi calls `session_shutdown` → `cleanupRuntime()` |
-| **Subagents** | `session.dispose()` kills all in-process agents | `stopSessionBoundSubagents()` → `terminateActiveChildPiProcesses()` kills child procs |
-| **State cleanup** | In-memory Map → auto-clean by GC | **❌ `cleanupRuntime()` does NOT call `unregisterActiveRun()`** |
-| **Result** | ✅ Clean | ⚠️ Child procs killed, but active-run-index.json still has entries pointing to cancelled manifests |
-
-### Case 2: SIGTERM (kill <pid>)
-
-| | oh-my-pi | pi-crew |
-|--|----------|---------|
-| **Path** | Signal handler → `shutdown()` → `dispose()` | Same — Pi calls `session_shutdown` |
-| **Result** | ✅ Clean | ⚠️ Same as Case 1 — child procs killed, index stale |
-
-### Case 3: SIGINT (Ctrl+C)
-
-| | oh-my-pi | pi-crew |
-|--|----------|---------|
-| **Path** | Pi's Ctrl+C handler (not SIGINT signal) — asks confirm, then `shutdown()` | Same |
-| **Result** | ✅ Clean (if user confirms) | ⚠️ Same as Case 1 |
-
-### Case 4: SIGKILL / kill -9 / taskkill /f
-
-| | oh-my-pi | pi-crew |
-|--|----------|---------|
-| **Path** | Process dies instantly. No handlers fire. | Same |
-| **Child processes** | In-process → die with parent ✅ | **❌ Child Pi processes become ORPHANS** |
-| **State** | In-memory → gone ✅ | **❌ active-run-index.json has zombie entries, manifests stuck at "running"** |
-| **Recovery** | Not needed | **Session start `purgeStaleActiveRunIndex()` + `cancelOrphanedRuns()`** — NOW implemented ✅ |
-
-### Case 5: Terminal closed (SIGHUP / window X button)
-
-| | oh-my-pi | pi-crew |
-|--|----------|---------|
-| **Path** | `emergencyTerminalExit()` → `killTrackedDetachedChildren()` → `process.exit(129)` | Same |
-| **Extension events** | **❌ `session_shutdown` NOT fired** | **❌ `cleanupRuntime()` NOT called** |
-| **Child processes** | In-process → die ✅ | **❌ Child procs NOT killed** (only `killTrackedDetachedChildren()` which is Pi's own tracked children, not pi-crew's) |
-| **Result** | ✅ Clean (in-process) | **❌ Total zombie — child procs alive, index stale, manifests stuck** |
-
-### Case 6: Computer crash / power loss
-
-| | oh-my-pi | pi-crew |
-|--|----------|---------|
-| **Result** | ✅ Clean (everything in-memory) | **❌ File-based state corrupted/inconsistent** |
-
-### Case 7: Out of Memory (OOM kill)
-
-| | oh-my-pi | pi-crew |
-|--|----------|---------|
-| **Result** | Same as SIGKILL | Same as SIGKILL |
-
-### Case 8: Node.js uncaught exception
-
-| | oh-my-pi | pi-crew |
-|--|----------|---------|
-| **Path** | Depends on Pi's uncaughtException handler | Same |
-| **Result** | In-process agents may leak | **❌ Child procs may survive as orphans** |
-
-### Case 9: Test runs that create state
-
-| | oh-my-pi | pi-crew |
-|--|----------|---------|
-| **State creation** | No persistent state | `createRunManifest()` + `registerActiveRun()` |
-| **Cleanup** | Automatic (in-process) | **❌ Many tests don't call `unregisterActiveRun()`** |
-| **Result** | ✅ Clean | **❌ active-run-index.json accumulates test garbage** |
-
-## Summary: What's Fixed and What's Not
-
-### Fixed in this session:
-1. ✅ `purgeStaleActiveRunIndex()` — scans global active-run-index at session_start AND cleanupRuntime
-2. ✅ Removes entries with: missing manifest, missing cwd, terminal status, dead PID + stale
-3. ✅ `cancelOrphanedRuns()` — cancels project-scoped orphaned runs
-4. ✅ **`parent-guard.ts`** — workers self-monitor parent PID, auto-exit if parent dies
-5. ✅ **`PI_CREW_PARENT_PID`** env var injected into all child spawns (child-pi + async-runner)
-6. ✅ **`background-runner.ts`** calls `startParentGuard()` at startup
-7. ✅ **`cleanupRuntime()`** now calls `purgeStaleActiveRunIndex()` on session end
-8. ✅ **`executeTeamRun`** wrapped in try/catch — unhandled errors set manifest to "failed"
-
-### What oh-my-pi does that pi-crew can never match:
-- oh-my-pi agents are **in-process** → process death = guaranteed cleanup
-- pi-crew agents are **child processes** → parent-guard + stale purge covers all cases
-
-## The parent-guard solution
-
-```
-Parent Pi process (PID 100)
-├── background-runner.ts (PID 200) ← env PI_CREW_PARENT_PID=100
-│   ├── startParentGuard(100)  ← polls every 3s: is PID 100 alive?
-│   ├── ... runs workflow ...
-│   └── if PID 100 dies → process.exit(124) ← SELF-TERMINATE
-└── child-pi.ts worker (PID 300) ← env PI_CREW_PARENT_PID=100
-    └── (Pi itself checks PI_CREW_PARENT_PID in its own entry point)
-```
-
-**Key**: Workers check parent liveness THEMSELVES. No external sentinel needed.
-If parent dies (SIGKILL, crash, power loss) → workers detect within 3s and exit.

package/docs/research/AUDIT_OH_MY_PI.md

@@ -1,261 +0,0 @@
-# 🔍 Oh-My-Pi Codebase Deep Audit
-
-> **Ngày**: 2026-05-07  
-> **Phiên bản**: v14.7.3 (`e8caad723`)  
-> **Codebase**: `source/oh-my-pi/` — chủ yếu `packages/coding-agent/src/`
-
----
-
-## 1. Tổng quan Architecture
-
-### End-to-End Flow
-
-```
-User Prompt → Main AgentSession → TaskTool.execute()
-  ├── discoverAgents() → merge bundled + user + project agents
-  ├── validate agent, check disabled/spawns
-  ├── allocate unique IDs (AgentOutputManager)
-  ├── For each task:
-  │   ├── If isolated → create worktree/overlay → runSubprocess()
-  │   └── If not → runSubprocess() in same cwd
-  │       ├── createAgentSession() → new in-process AgentSession
-  │       ├── Subscribe to AgentEvents → progress tracking
-  │       ├── session.prompt(task) → agent loop runs
-  │       ├── Wait for yield tool call (3 retries)
-  │       └── Return SingleResult
-  └── Merge results (patch apply or branch merge)
-```
-
-### Quyết định kiến trúc chính
-
-1. **In-process subagents**: Chạy subagent như `AgentSession` instances trong cùng process. Tránh IPC overhead, cho phép sharing MCP connections, settings, model registry.
-
-2. **Yield-based completion**: Subagent **phải** gọi `yield` tool đúng 1 lần. Executor gửi tối đa 3 reminders nếu agent thoát mà không yield. Contract mạnh — ngăn agent "quên" return results.
-
-3. **Isolation backends**: 3 mode — `worktree` (git worktree), `fuse-overlay` (COW overlayfs Unix), `fuse-projfs` (ProjFS Windows). Mỗi isolated task có sandboxed filesystem view.
-
-4. **EventBus pub/sub**: 3 channel — `task:subagent:event` (raw events), `task:subagent:progress` (aggregated), `task:subagent:lifecycle` (start/end). Decouple UI rendering từ execution.
-
-5. **Agent discovery cascade**: Bundled → user (`~/.omp/agent/agents/*.md`) → project (`.omp/agents/*.md`) → Claude Code marketplace plugins. First name match wins.
-
----
-
-## 2. Key Files & Responsibilities
-
-### Task System Core
-
-| File | ~Lines | Responsibility |
-|------|--------|----------------|
-| `task/index.ts` | ~750 | **TaskTool class** — entry point. Agent discovery, validation, parallel execution orchestration, isolation/merge, result formatting |
-| `task/executor.ts` | ~620 | **runSubprocess()** — chạy 1 subagent in-process. Progress tracking, yield handling, usage accumulation, MCP proxy tools |
-| `task/types.ts` | ~230 | Core types: `AgentDefinition`, `AgentProgress`, `SingleResult`, `TaskParams`, `TaskToolDetails`, event channel constants |
-| `task/agents.ts` | ~150 | Bundled agent definitions (explore, plan, designer, reviewer, librarian, task, quick_task). Parses from embedded markdown + frontmatter |
-| `task/discovery.ts` | ~130 | Agent discovery từ filesystem. Merge user/project/bundled/Claude plugin agents với precedence rules |
-| `task/parallel.ts` | ~100 | `mapWithConcurrencyLimit()` — worker pool với fail-fast. `Semaphore` cho async concurrency control |
-| `task/worktree.ts` | ~580 | Git worktree creation/cleanup, baseline capture, patch generation/apply, branch commit/merge, nested repo handling |
-| `task/render.ts` | ~1020 | TUI rendering cho task tool — call preview, result display, progress indicators, tree view, review finding badges |
-| `task/template.ts` | ~40 | Renders context + assignment thành full subagent prompt dùng Handlebars templates |
-| `task/subprocess-tool-registry.ts` | ~80 | Registry pattern cho extracting data từ tool events (yield, report_finding). Extensible handler system |
-| `task/output-manager.ts` | ~100 | Sequential ID allocation với parent prefix support (e.g., `0-Auth.1-Subtask`). Scans existing artifacts on resume |
-| `task/simple-mode.ts` | ~35 | Three modes: `default` (context + schema), `schema-free` (context only), `independent` (neither) |
-| `task/isolation-backend.ts` | ~100 | Platform detection cho isolation mode (Win/Unix/ARM64), probe ProjFS availability |
-| `task/name-generator.ts` | ~340 | AdjectiveNoun generator (426,710 combinations) cho human-readable task names |
-
-### Session & Agent Runtime
-
-| File | ~Lines | Responsibility |
-|------|--------|----------------|
-| `session/agent-session.ts` | **~7500** | **Core agent session** — model management, tool dispatch, streaming, compaction, bash execution, extension runner. **GOD OBJECT** — quá lớn |
-| `sdk.ts` | ~1900 | Factory cho `AgentSession` and `SessionManager`. Loads tools, skills, extensions, MCP, slash commands |
-| `registry/agent-registry.ts` | ~140 | Process-global registry của live agent sessions. Dùng bởi IRC tool cho peer discovery |
-
-### Tools
-
-| File | ~Lines | Responsibility |
-|------|--------|----------------|
-| `tools/irc.ts` | ~250 | IRC tool — agent-to-agent messaging. DM/broadcast với optional reply qua `respondAsBackground()` |
-| `tools/yield.ts` | ~170 | Submit result tool. JTD/JSON Schema validation với override sau first failure. Registers subprocess handler |
-| `tools/review.ts` | ~240 | `report_finding` tool cho structured code review. Priority (P0-P3), file/line tracking |
-
-### UI Components
-
-| File | ~Lines | Responsibility |
-|------|--------|----------------|
-| `modes/components/agent-dashboard.ts` | ~900 | Interactive agent management: enable/disable, model overrides, AI-powered agent creation |
-| `modes/components/session-observer-overlay.ts` | ~650 | Real-time subagent transcript viewer với expand/collapse, breadcrumb navigation, incremental file reading |
-| `modes/session-observer-registry.ts` | ~140 | Tracks observable sessions, subscribes to EventBus cho lifecycle/progress updates |
-
-### Configuration
-
-| File | ~Lines | Responsibility |
-|------|--------|----------------|
-| `config/settings-schema.ts` | ~2700 | Single source of truth cho all settings. Typed schema với UI metadata, tabs, conditions |
-| `config/model-resolver.ts` | — | Model pattern resolution (agent → settings → session → fallback) |
-
-### Tool Discovery
-
-| File | ~Lines | Responsibility |
-|------|--------|----------------|
-| `tool-discovery/tool-index.ts` | ~400 | BM25-based search index over all tools. Generic `DiscoverableTool` type covers builtin, MCP, extension, custom sources |
-
----
-
-## 3. Patterns đáng học hỏi cho pi-crew
-
-### 3.1 Yield-Based Completion Contract
-**File**: `tools/yield.ts`, `task/executor.ts` (lines ~380-420)
-
-Subagent **phải** gọi `yield` đúng 1 lần. Executor:
-1. Detects `yield` qua `subprocessToolRegistry` handler
-2. Sends up to 3 reminder prompts nếu agent exits without yielding
-3. Extracts và validates structured data từ yield result
-4. Falls back to raw output parsing nếu no yield
-
-**pi-crew takeaway**: Result collection hiện tại ad-hoc. Formal "submit result" tool với schema validation + retry reminders sẽ tăng reliability đáng kể.
-
-### 3.2 SubprocessToolRegistry — Extensible Tool Event Handling
-**File**: `task/subprocess-tool-registry.ts`
-
-Tools register handlers cho:
-- `extractData()` — pull structured data từ tool results
-- `shouldTerminate()` — signal agent completion
-- `renderInline()` / `renderFinal()` — custom TUI rendering
-
-**pi-crew takeaway**: Worker result extraction có thể dùng registry pattern tương tự, cho phép different tool types contribute structured data without coupling to executor.
-
-### 3.3 EventBus Pub/Sub cho Progress
-**File**: `task/types.ts` (channel constants), `task/executor.ts` (emission)
-
-3 dedicated channels với typed payloads tách biệt raw events, aggregated progress, lifecycle transitions. Cho phép:
-- Multiple UI components subscribe independently
-- Session observer gets updates without polling
-- Clean separation of concerns
-
-**pi-crew takeaway**: pi-crew đã có `RunEventBus` (từ Phase 1), nhưng chưa có typed channels. Có thể tách thành `worker:progress`, `worker:lifecycle`, `worker:stream`.
-
-### 3.4 Isolation Backends — FUSE/ProjFS
-**File**: `task/isolation-backend.ts`, `task/worktree.ts`
-
-3 isolation modes:
-- `worktree` — git worktree per task (cross-platform)
-- `fuse-overlay` — Copy-on-Write overlayfs (Unix)
-- `fuse-projfs` — Windows ProjFS
-
-**pi-crew takeaway**: Chỉ có worktree. Thêm FUSE/ProjFS isolation cho environments cần true filesystem isolation.
-
-### 3.5 Agent Dashboard — Interactive Configuration UI
-**File**: `modes/components/agent-dashboard.ts` (~900 lines)
-
-Full interactive UI cho agent management:
-- Enable/disable agents
-- Model override per agent
-- AI-powered agent creation (nhập description → generate agent)
-- Source filtering (builtin/user/project)
-
-**pi-crew takeaway**: pi-crew đã có `agent-management-overlay.ts` (read-only). Cần thêm enable/disable toggle + model override editing.
-
-### 3.6 Session Observer — Incremental Transcript Reading
-**File**: `modes/components/session-observer-overlay.ts` (~650 lines)
-
-- Incremental JSONL reading (không load toàn bộ file)
-- Expand/collapse per entry
-- Breadcrumb navigation cho nested subagent transcripts
-- Auto-scroll to bottom unless user scrolled up
-
-**pi-crew takeaway**: pi-crew đã có `transcript-entries.ts`. Cần thêm breadcrumb navigation + incremental reading.
-
-### 3.7 Name Generator — Human-Readable Task Names
-**File**: `task/name-generator.ts` (~340 lines)
-
-`AdjectiveNoun` generator → 426,710 combinations. Thay vì `task_01`, dùng `BraveFalcon`. Dễ nhận diện trong UI.
-
-**pi-crew takeaway**: pi-crew dùng task IDs như `01_discover`. Human-readable names sẽ tốt hơn cho UX.
-
-### 3.8 Semaphore Concurrency Control
-**File**: `task/parallel.ts`
-
-```typescript
-class Semaphore {
-  private queue: (() => void)[] = [];
-  private running = 0;
-  constructor(private max: number) {}
-  async acquire(): Promise<void> { ... }
-  release(): void { ... }
-}
-```
-
-Clean async concurrency primitive. pi-crew dùng `mapConcurrent` từ `parallel-utils.ts` — tương đương nhưng Semaphore explicit hơn.
-
-### 3.9 Handlebars Template Rendering
-**File**: `task/template.ts`
-
-Handlebars templates cho subagent prompts. Cho phép customization dễ dàng.
-
-**pi-crew takeaway**: pi-crew dùng string concatenation trong `prompt-builder.ts`. Templates sẽ dễ maintain hơn.
-
-### 3.10 MCP Proxy Tools
-**File**: `task/executor.ts` (~line 280)
-
-Subagents reuse parent's MCP connections qua `createMCPProxyTools()`. Tránh mỗi subagent phải setup riêng.
-
-**pi-crew takeaway**: pi-crew chưa có MCP proxy. Mỗi child Pi process tự discover MCP connections. Thêm proxy sẽ giảm startup time.
-
----
-
-## 4. Anti-patterns & Vấn đề trong oh-my-pi
-
-### 4.1 God Object — `agent-session.ts` (~7500 lines)
-Một file duy nhất chứa model management, tool dispatch, streaming, compaction, bash execution, extension runner. Quá khó maintain. Nên tách thành multiple modules.
-
-### 4.2 No Process Isolation
-Crashed subagent → potential full process crash. Không có fault boundary. pi-crew's child process approach an toàn hơn cho production.
-
-### 4.3 Settings Schema Monolith — `settings-schema.ts` (~2700 lines)
-Single source of truth cho all settings, nhưng 2700 dòng là quá lớn. Nên tách theo domain (agent settings, UI settings, task settings, etc.).
-
-### 4.4 Hardcoded Bundled Agents
-`task/agents.ts` embeds agent definitions as multiline string literals. Khó edit, khó test. pi-crew's file-based approach (agents/*.md) linh hoạt hơn.
-
----
-
-## 5. Recent Changes (git log)
-
-```
-e8caad723 feat: v14.7.3
-... (56 commits since v14.6.6)
-```
-
-Key changes since last review:
-- Isolation backend improvements (ProjFS support)
-- Agent dashboard UI enhancements
-- Yield tool schema validation improvements
-- IRC tool anti-deadlock side-channel
-- Session observer incremental reading
-- BM25 tool discovery index
-
----
-
-## 6. Feature Matrix (so với pi-crew)
-
-| Feature | oh-my-pi | pi-crew | Gap |
-|---------|:--------:|:-------:|-----|
-| In-process execution | ✅ | ❌ | pi-crew dùng child process |
-| Process isolation | ❌ | ✅ | oh-my-pi crash cascade risk |
-| Yield tool enforcement | ✅ | ❌ | pi-crew cần implement |
-| IRC messaging | ✅ | ❌ | pi-crew chỉ có mailbox |
-| Broadcast messaging | ✅ | ❌ | pi-crew không có |
-| Steering mid-turn | ✅ | ❌ | pi-crew chỉ cancel/respond |
-| EventBus typed channels | ✅ | 🔶 | pi-crew có RunEventBus nhưng chưa typed |
-| FUSE/ProjFS isolation | ✅ | ❌ | pi-crew chỉ worktree |
-| Agent dashboard UI | ✅ | 🔶 | pi-crew có read-only overlay |
-| Session observer | ✅ | 🔶 | pi-crew có transcript-entries |
-| MCP proxy | ✅ | ❌ | pi-crew mỗi child tự discover |
-| Human-readable task names | ✅ | ❌ | pi-crew dùng IDs |
-| Handlebars templates | ✅ | ❌ | pi-crew dùng string concat |
-| Adaptive planning | ❌ | ✅ | oh-my-pi không có |
-| Retry policy | ❌ | ✅ | oh-my-pi chỉ yield reminder |
-| Policy engine | ❌ | ✅ | oh-my-pi không có |
-| Crash recovery | ❌ | ✅ | oh-my-pi không có |
-| Dependency context | ❌ | ✅ | oh-my-pi chỉ context.md |
-| Effectiveness guard | ❌ | ✅ | oh-my-pi không có |
-| Deadletter tracking | ❌ | ✅ | oh-my-pi không có |