Initial commit: kage-research project files

implementation-plan.md

@@ -0,0 +1,118 @@
+# Implementation Plan: Pi Integration for Kugetsu
+
+## Overview
+
+This document outlines the implementation roadmap for replacing OpenCode with Pi (agent-core) in the Kugetsu orchestration system.
+
+---
+
+## Current Status: ✅ Levels 1-4 Complete
+
+All core implementation levels are complete. See `README.md` for summary.
+
+---
+
+## Implementation Levels
+
+### Level 1: Proof of Concept (POC) ✅ COMPLETE
+
+**Goal**: Validate Pi works in your environment
+
+**Results:**
+- Pi agent works ✅
+- Tool execution works ✅
+- Memory: ~130MB RSS ✅
+- stepfun free model works ✅
+
+**File**: `level1.ts`
+
+---
+
+### Level 2: Basic Integration ✅ COMPLETE
+
+**Goal**: Shadow + Manager + Tools
+
+**Results:**
+- Shadow class with context isolation ✅
+- Shadow Manager (spawn/terminate/track) ✅
+- Tool registry (read, write, edit, bash, grep, ls) ✅
+- Concurrency control ✅
+
+**File**: `level2.ts`
+
+---
+
+### Level 3: Production Features ✅ COMPLETE
+
+**Goal**: Queue + Checkpoint + Context Management
+
+**Completed:**
+- Task status tracking ✅
+- Retry with backoff ✅
+- Checkpoint save/load ✅
+- Context pruning ✅
+- Priority queue ✅
+- Backpressure ✅
+
+**Files**: `level3.ts`, `level3b.ts`, `level3c.ts`
+
+---
+
+### Level 4: Hermes Integration ✅ COMPLETE
+
+**Goal**: Connect to Hermes
+
+**Completed:**
+- HTTP server ✅
+- Webhook endpoint ✅
+- Tool implementation guide ✅
+- HTTP vs Direct Spawn comparison ✅
+
+**Files**: `level4.ts`, `pi_agent_tool.py`, `hermes-tool-guide.md`
+
+---
+
+## What's Left
+
+| Priority | Item | Notes |
+|----------|------|-------|
+| P2 | Full Hermes integration | Test with actual Hermes |
+| P2 | Direct spawn option | Alternative to HTTP |
+| P1 | Production hardening | Rate limiting, logging |
+
+---
+
+## Quick Reference
+
+### Run Tests
+
+```bash
+# Level 1: Basic agent
+npx tsx level1.ts
+
+# Level 2: Shadow + Manager
+npx tsx level2.ts
+
+# Level 3: Queue system
+npx tsx level3c.ts
+
+# Level 4: HTTP server
+npx tsx level4.ts
+```
+
+### Key Findings
+
+| Metric | OpenCode | Pi |
+|--------|----------|-----|
+| Memory/agent | 340MB | ~80MB |
+| Max concurrent | 5 | 15-20 |
+| Improvement | - | ~70% less memory |
+
+---
+
+## Document History
+
+| Date | Update |
+|------|--------|
+| 2026-04-08 | Initial plan created |
+| 2026-04-08 | Levels 1-4 complete |