docs(adr): openab-agent — native Rust coding agent

[chaodu-agent]

Summary

Proposes openab-agent — a single Rust binary that is both the ACP server and the coding agent, eliminating the adapter/wrapper layer entirely.

Architecture

┌─ Single Rust Binary ─────────────────────────┐
│                                               │
│  openab-agent                                 │
│  ├─ ACP server (stdin/stdout JSON-RPC)        │
│  ├─ LLM client (reqwest + SSE)                │
│  ├─ Tools: read, write, edit, bash            │
│  └─ Session tree (branching history)          │
│                                               │
└───────────────────────────────────────────────┘

Comparison with Existing Agents

	Existing agents	openab-agent
Architecture	openab → stdio → adapter → CLI → LLM	openab → stdio → agent → LLM
Layers	3-4	1
Runtime	Node.js / Python / Go	None (static binary)
Image size	300-800MB	~20MB (distroless)
Cold start	1-3s	<50ms
ACP	Requires wrapper (pi-acp, codex-acp, agy-acp)	Native, zero overhead

Required Crates

• reqwest — HTTP client (LLM API calls)
• serde / serde_json — JSON serialization
• tokio — async runtime (already used in openab)
• tokio-process — bash tool execution

Nothing else needed. Can even share code with openab core (ACP types, session pool logic).

Key Advantage

Because we own the agent, deep integration is possible — future library mode can bypass stdio entirely, using in-process function calls to eliminate all IPC overhead.

Key Design Decisions

• 4 tools only: read, write, edit, bash (inspired by Pi's minimal approach)
• No external runtime: no Node.js, no npm, no Python — single static binary (~20MB image)
• Native ACP: built-in JSON-RPC over stdio, no wrapper needed
• Multi-model: thin HTTP client supports OpenAI, Anthropic, Google (no SDK dependency)
• Session trees: branching conversation history for code exploration
• Future library mode: same language as openab core enables in-process integration

ADR Location

docs/adr/openab-agent.md

Discussion

Discord thread: https://discord.com/channels/1486155598964719616/1508241504945045577

[chaodu-agent]

CHANGES REQUESTED ⚠️ — Solid native Rust ADR; critical Rust trait compile issues and dependency errors have been fixed in latest commit. Remaining items are non-blocking.

What This PR Does

Proposes an ADR for openab-agent — a native Rust coding agent binary with built-in ACP support, eliminating Node.js/Python adapter layers.

How It Works

Single Rust binary implementing ACP over stdio JSON-RPC, with 4 tools (read/write/edit/bash), multi-provider LLM client via HTTP+SSE, and a session tree for branching conversation history.

Findings

#	Severity	Finding	Location	Status
1	🔴	LlmProvider trait returned bare Stream (a trait, not a type) — would not compile	§3 LLM Client Design	✅ Fixed (now uses BoxStream)
2	🔴	Path traversal attack possible if paths not canonicalized	§4 Tool Implementation	✅ Already addressed (canonicalize + boundary check)
3	🔴	Env var leakage — child processes could exfiltrate API keys	§4 Bash Tool	✅ Already addressed (allow-list filtering)
4	🔴	Child process orphan leak on timeout	§4 Sandboxing	✅ Already addressed (setsid + kill(-pgid))
5	🟡	tokio-process crate is deprecated (merged into tokio::process)	§2 Required Crates	✅ Fixed
6	🟡	No testing strategy defined	—	✅ Fixed (added §9 Testing Strategy)
7	🟡	sandbox-exec on macOS is deprecated by Apple	§4 Cross-Platform	✅ Fixed (removed reliance, use env filtering as primary)
8	🟡	Session tree GC / unbounded growth risk	§5 Session Tree	✅ Already addressed (GC section with TTL, depth cap, pruning)
9	🟢	Excellent native Rust architecture — cold start <50ms, image ~20MB	Overall	—
10	🟢	Clean session tree branching model	§5	—

Finding Details

🔴 F1: LlmProvider Stream Trait Compile Error (FIXED)

Stream<Event> is a trait, not a concrete type. Returning it from a trait method requires boxing. Fixed by using BoxStream<'a, Event> (i.e., Pin<Box<dyn Stream<Item = Event> + Send + 'a>>). Also desugared async fn to boxed future for object safety.

🔴 F2–F4: Security Findings (Already Addressed)

Path traversal, env var leakage, and child process cleanup were already addressed in the ADR with canonicalization, allow-list env filtering, and setsid+kill(-pgid) respectively.

🟡 F5: tokio-process Deprecation (FIXED)

Replaced tokio-process with tokio::process (merged since tokio 0.2). Added futures crate for Stream/BoxStream.

🟡 F6: Testing Strategy (FIXED)

Added §9 Testing Strategy covering unit test boundaries, hand-written mock pattern for LlmProvider, integration test tagging, and CI pipeline structure.

🟡 F7: sandbox-exec Deprecation (FIXED)

Removed reliance on sandbox-exec. macOS now uses process group isolation + env filtering as primary mechanism.

What's Good (🟢)

• Native Rust architecture eliminates 3-4 layers of indirection, achieving <50ms cold start and ~20MB image size
• Session tree model enables branching exploration without losing context
• Minimal tool surface (4 tools) keeps the design focused and auditable
• Provider-agnostic LLM client with version pinning and CI canary is well thought out

---

Reviewers: <@普渡法師> <@覺渡法師>

Latest commit: 447ee89 — addresses all 🔴 critical and 🟡 important findings.

All critical issues are now resolved. Remaining open questions (§10) are non-blocking design decisions for implementation phase.

---

1️⃣ Approve PR
2️⃣ Request contributor changes and re-review
3️⃣ Close PR
4️⃣ I'll fix it myself, then have 法師團隊 review again