125 lines
4.8 KiB
Markdown
125 lines
4.8 KiB
Markdown
# Kugetsu vs Pi Feature Mapping
|
|
|
|
## Overview
|
|
|
|
This document maps Kugetsu's current functionality to what Pi (agent-core) provides, helping understand what to keep, what to modify, and what to build new.
|
|
|
|
---
|
|
|
|
## Kugetsu → Pi Feature Comparison
|
|
|
|
| Kugetsu Function | Pi Has It? | Notes |
|
|
|-----------------|------------|-------|
|
|
| **Queue system** | ❌ No | Pi is single-agent runtime |
|
|
| **Session tracking** | ⚠️ Partial | Events (`agent_end`, `turn_end`), but no built-in persistence |
|
|
| **Worktree management** | ❌ No | Git operations not included in Pi |
|
|
| **PM Agent logic** | ❌ No | Task coordination is your responsibility |
|
|
| **Parallel capacity control** | ❌ No | You control concurrency |
|
|
| **Resource monitoring** | ❌ No | You measure memory/CPU |
|
|
| **Context isolation** | ✅ Yes | Each `Agent` instance is separate |
|
|
| **Tool execution hooks** | ✅ Yes | `beforeToolCall`, `afterToolCall` |
|
|
| **Rich event stream** | ✅ Yes | Full lifecycle events |
|
|
| **Checkpoint/save state** | ❌ No | You build this |
|
|
|
|
---
|
|
|
|
## What Stays from Kugetsu
|
|
|
|
| Component | What You Keep | What Changes |
|
|
|-----------|--------------|--------------|
|
|
| **Queue/Orchestration** | ✅ Keep | Replace with simpler implementation since Pi is lighter |
|
|
| **Worktree logic** | ✅ Keep | Works the same |
|
|
| **PM Agent** | ✅ Keep | Runs as a Pi agent instead of OpenCode session |
|
|
| **Telegram/Hermes bridge** | ✅ Keep | No changes needed |
|
|
| **Capacity testing** | ✅ Keep | Retest with Pi for new benchmarks |
|
|
| **CODING_GUIDELINES.md** | ✅ Keep | Pi loads AGENTS.md or CLAUDE.md |
|
|
|
|
---
|
|
|
|
## What Changes
|
|
|
|
| Component | Before (OpenCode) | After (Pi) |
|
|
|-----------|-------------------|-------------|
|
|
| **Agent runtime** | ~340MB per agent | ~80MB per agent |
|
|
| **Session isolation** | Worktree-based | Worktree + context tagging |
|
|
| **Crash detection** | Missing/silent | Event subscription + heartbeats |
|
|
| **Checkpoint** | None | Built into Shadow class |
|
|
| **Message streaming** | Limited | Rich event stream |
|
|
|
|
---
|
|
|
|
## The New Architecture
|
|
|
|
```
|
|
Before:
|
|
┌─────────────────────────────────────────────┐
|
|
│ Kugetsu (Queue + Orchestration) │
|
|
│ ├── Queue system (custom) │
|
|
│ ├── Worktree management │
|
|
│ ├── PM Agent (OpenCode session) │
|
|
│ └── Coding Agents (OpenCode sessions) │
|
|
│ └── ~340MB each, context in session │
|
|
└─────────────────────────────────────────────┘
|
|
|
|
After:
|
|
┌─────────────────────────────────────────────┐
|
|
│ Kugetsu (Queue + Orchestration) │
|
|
│ ├── Queue system (simplified, lighter) │
|
|
│ ├── Worktree management │
|
|
│ ├── PM Agent (Pi agent) │
|
|
│ └── Coding Agents (Pi "Shadows") │
|
|
│ └── ~80MB each, context isolation │
|
|
│ ├── Event-driven tracking │
|
|
│ ├── Checkpoint support │
|
|
│ └── Rich hooks for UX │
|
|
└─────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## What You Build New
|
|
|
|
Since Pi doesn't include these, you add them in Kugetsu:
|
|
|
|
1. **Shadow Manager**
|
|
- Spawns Pi agents
|
|
- Tracks state
|
|
- Manages lifecycle
|
|
|
|
2. **Queue with Concurrency Control**
|
|
- Simpler than before (less resource contention)
|
|
- Parallel capacity: 15-20 shadows on 4GB RAM
|
|
|
|
3. **Event-Driven Session Tracking**
|
|
- Subscribe to `agent_end`, `agent_error`
|
|
- Know immediately when a session ends/crashes
|
|
- No more "silent death"
|
|
|
|
4. **Checkpoint System**
|
|
- Save state every N seconds
|
|
- Recover from last checkpoint on crash
|
|
|
|
5. **Resource Monitor**
|
|
- Track memory per shadow
|
|
- Auto-scale based on availability
|
|
|
|
---
|
|
|
|
## Why This Works Better
|
|
|
|
| Problem | Before (OpenCode) | After (Pi) |
|
|
|---------|-------------------|------------|
|
|
| **Session poisoning** | Context bleeds between agents | Strict `convertToLlm` filtering |
|
|
| **Silent crashes** | Process dies, no trace | Event subscription catches this |
|
|
| **Memory exhaustion** | 5 max, then queue | 15-20 max, more headroom |
|
|
| **UX in headless** | Limited streaming | Rich events rebuild TUI |
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
- **Keep**: Queue, worktree, PM agent logic, Hermes bridge
|
|
- **Modify**: Session isolation (add context tagging), event handling
|
|
- **Build**: Shadow manager, checkpointing, resource monitor
|
|
- **Gain**: 70% less memory, observable sessions, TUI-like headless UX
|