Initial commit: kage-research project files

2026-04-09 00:39:52 +00:00
commit 71fc8b4495
19 changed files with 5303 additions and 0 deletions
--- a/kugetsu-pi-feature-mapping.md
+++ b/kugetsu-pi-feature-mapping.md
@@ -0,0 +1,124 @@
+# 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