137 lines
2.6 KiB
Markdown
137 lines
2.6 KiB
Markdown
# Project Summary: Pi Integration for Kugetsu
|
|
|
|
## Overview
|
|
|
|
This project explores replacing OpenCode with Pi (agent-core) in the Kugetsu orchestration system.
|
|
|
|
---
|
|
|
|
## Documents
|
|
|
|
### Research Documents
|
|
|
|
| Document | Description |
|
|
|----------|-------------|
|
|
| `research.md` | Initial agent framework comparison |
|
|
| `pi-integration-research.md` | Deep dive on Pi architecture |
|
|
| `kugetsu-pi-feature-mapping.md` | What stays vs what changes |
|
|
| `queue-research.md` | Queue system options |
|
|
| `llm-compression-research.md` | LLMs for context compression |
|
|
| `hermes-tool-guide.md` | Hermes tool implementation |
|
|
|
|
### Implementation Documents
|
|
|
|
| Document | Description |
|
|
|----------|-------------|
|
|
| `implementation-plan.md` | Roadmap with progress |
|
|
| `level1.ts` | Basic Pi agent (working) |
|
|
| `level2.ts` | Shadow + Manager + Tools |
|
|
| `level3.ts` | Task queue + checkpoint/recovery |
|
|
| `level3b.ts` | Context management |
|
|
| `level3c.ts` | Queue system |
|
|
| `level4.ts` | Hermes HTTP server |
|
|
| `pi_agent_tool.py` | Hermes tool (HTTP approach) |
|
|
|
|
---
|
|
|
|
## Completed Levels
|
|
|
|
### Level 1: Basic Agent ✅
|
|
- Pi agent works
|
|
- Tool execution works
|
|
- Memory: ~130MB RSS
|
|
|
|
### Level 2: Shadow + Manager ✅
|
|
- Shadow class with isolation
|
|
- Shadow Manager
|
|
- Tool registry (read, write, edit, bash, grep, ls)
|
|
- Concurrency control
|
|
|
|
### Level 3: Checkpoint/Recovery + Context + Queue ✅
|
|
- Task status tracking
|
|
- Retry with backoff
|
|
- Checkpoint save/load
|
|
- Context pruning
|
|
- Priority queue
|
|
- Backpressure
|
|
|
|
### Level 4: Hermes Integration ✅
|
|
- HTTP server
|
|
- Webhook endpoint
|
|
- Tool integration guide
|
|
- HTTP vs Direct Spawn comparison
|
|
|
|
---
|
|
|
|
## Key Findings
|
|
|
|
### Memory Usage
|
|
|
|
| Component | Memory |
|
|
|-----------|---------|
|
|
| OpenCode | ~340MB |
|
|
| Pi Agent | ~80-100MB |
|
|
| Improvement | ~70% reduction |
|
|
|
|
### Concurrency
|
|
|
|
| Setup | Max Concurrent |
|
|
|-------|-----------------|
|
|
| OpenCode | ~5 |
|
|
| Pi | ~15-20 |
|
|
|
|
### Queue Options
|
|
|
|
For production: **Priority Queue + Rate Limiting**
|
|
|
|
---
|
|
|
|
## Architecture Options
|
|
|
|
### Current (OpenCode)
|
|
```
|
|
Telegram → Hermes → Kugetsu → OpenCode → Worktree
|
|
```
|
|
|
|
### Proposed (Pi)
|
|
```
|
|
Telegram → Hermes → Kugetsu-Pi → Shadows → Worktrees
|
|
```
|
|
|
|
### Alternative (HTTP Server)
|
|
```
|
|
Telegram → Hermes → HTTP Tool → Pi Server → Shadows
|
|
```
|
|
|
|
---
|
|
|
|
## Next Steps
|
|
|
|
1. **Test with Hermes** - Try the tool integration
|
|
2. **Direct spawn option** - Implement alternative approach
|
|
3. **Full integration** - Replace OpenCode in Kugetsu
|
|
|
|
---
|
|
|
|
## Quick Commands
|
|
|
|
```bash
|
|
# Test Level 1
|
|
npx tsx level1.ts
|
|
|
|
# Test Level 2
|
|
npx tsx level2.ts
|
|
|
|
# Test Level 3 (queue)
|
|
npx tsx level3.ts
|
|
|
|
# Test Level 4 (HTTP server)
|
|
npx tsx level4.ts
|
|
```
|
|
|
|
---
|
|
|
|
## Last Updated
|
|
|
|
2026-04-08
|