terraphim / terraphim/terraphim-ai
Epic: Migrate ADF Claude agents to Agent SDK
Nessuno ha ancora preso questa issue.
- Lingua principale
- Rust
- Stelle
- 62
- Fork
- 5
- Merge medio
- 2h 27m
- PR unite (30g)
- 1
Descrizione
Context
ADF spawns Claude agents as claude -p subprocesses with stdout/stderr capture. This causes SIGPIPE bugs, fragile output parsing, cold-start waste, and no native cost tracking. The Claude Agent SDK (renamed from Claude Code SDK) provides query() async iterator with typed hooks, native session resume/fork, and in-process cost tracking.
Proposal
Replace subprocess spawning for Claude-based agents with Agent SDK query() calls. Codex agents remain as subprocesses (no SDK equivalent).
Migration Strategy
- Create thin Python wrapper per agent that calls Agent SDK
query()and forwards typed JSONL events to stdout using the RPC envelope (#688) - Migrate one agent at a time: product-development first (lowest risk), then security-sentinel
- Preserve orchestrator reconciliation loop, Safety/Core/Growth layers, NightwatchMonitor
What This Eliminates
- SIGPIPE bug (async iterator, no pipes)
- Stdout/stderr parsing fragility (typed message stream)
- Cold-start waste (native
resume=session_id) - Cost tracking complexity (hooks on every API call vs output parsing)
- Session management complexity (
ClaudeSDKClienthandles state)
Open Question: Bridge Architecture
- Option A: Rust orchestrator -> thin Python wrapper (subprocess) -> Agent SDK
- Option B: Rust orchestrator -> local HTTP server running Agent SDK -> typed responses
- Option C: Implement Agent SDK protocol directly in Rust (high effort, fragile)
- Spike needed to determine which approach best preserves Rust orchestrator while gaining SDK benefits
Sub-issues (to be created during design phase)
- Spike: validate Agent SDK wrapper bridge pattern
- Migrate product-development agent to Agent SDK
- Implement cost tracking via Agent SDK hooks (supersedes #638 approach)
- Implement session resume via Agent SDK (supersedes #639 approach)
- Migrate security-sentinel agent to Agent SDK
References
- Agent SDK reference:
cto-executive-system/knowledge/claude-agent-sdk-reference.md - Current ADF subprocess model:
crates/terraphim_spawner/src/lib.rs - Comparison table: Agent SDK reference, "Comparison with Current ADF Setup" section
- Plan:
cto-executive-system/plans/adf-architecture-improvements.md(item 2.1) - Depends on: #688 (RPC envelope)
- Related: #637 (Paperclip epic), #638, #639
Guida per i contributori
Apri la guida per i contributori
Come iniziare
- Leggi tutta la issue e poi la guida ai contributi del progetto.
- Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
- Fai un fork del repository e lavora su un branch.
- Apri una pull request che faccia riferimento al numero della issue.
Direzione di ricerca
Start with cto-executive-system/knowledge/claude-agent-sdk-reference.md and cto-executive-system/plans/adf-architecture-improvements.md, then inspect crates/terraphim_spawner/src/lib.rs and dependency #688. The first deliverable is a spike comparing the three bridge options while preserving the Rust orchestrator; document the selected approach and split implementation work into the listed sub-issues.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Valutazione
- Stack tecnologico
- python, rust
- Ambito
- ai, backend
- Tipo di issue
- Funzionalità
- Difficoltà
- 5/5
- Tempo stimato
- Più di una settimana
- Stato di attività
- Ferma
- Chiarezza
- Da chiarire
- Idoneità per principianti
- 25/100