terraphim / terraphim/terraphim-ai

Epic: Migrate ADF Claude agents to Agent SDK

Aperta
#689 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

enhancement
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
  1. Create thin Python wrapper per agent that calls Agent SDK query() and forwards typed JSONL events to stdout using the RPC envelope (#688)
  2. Migrate one agent at a time: product-development first (lowest risk), then security-sentinel
  3. 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 (ClaudeSDKClient handles 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

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. 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

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.