ACP Integration

ACP Integration

The single most important — and highest-risk — subsystem. Read before touching core/acp/.

The boundary (do not cross)

Vellum runs on first-party, sanctioned paths only:

• Claude → claude-code-acp, drawing from the Agent-SDK credit bundled in the user's Pro/Max plan (official since 2026-06-15).
• Codex → codex-acp, drawing from the user's ChatGPT plan (Codex sign-in).

Banned: bridging subscription OAuth tokens into a third-party harness. Anthropic prohibited this (Feb 2026) and actively blocks it (since Apr 2026). This is why tools like OpenCode/Cline had to fall back to API keys. Vellum must never attempt an OAuth bridge or a raw ANTHROPIC_API_KEY / OPENAI_API_KEY path. If the sanctioned adapter can't authenticate, that's a user-side CLI sign-in problem — surface it, don't work around it.

Reality check to set expectations: this is plan-bundled credit, not infinite free AI. Heavy synthesis can exhaust it. Surface usage where sensible.

How it works

Vellum is an ACP client; each backend is an ACP server subprocess spoken to over stdio via JSON-RPC (session/new, session/prompt, streaming updates, tool-call + permission events). This mirrors how Zed runs Claude Agent + Codex + Gemini concurrently.

Contract: core/acp/client.ts (AcpClient, AcpSession, AcpBackend, AcpPromptRequest, AcpUpdate).

Status — implemented + on-plan verified (2026-07-21)

StdioAcpClient shipped in PR #1, hardened in PR #8. Realities found:

• Dep: the canonical lib is @agentclientprotocol/sdk (v1.2.1). The older @zed-industries/agent-client-protocol name is deprecated / renamed to it — verify on npm, don't use the old name.
• Claude backend: VERIFIED on-plan. npm run smoke:acp -- claude streamed a real reply ending in done against the signed-in plan. The full ingest loop (arXiv 1706.03762) ran agent extraction on-plan successfully.
• Codex backend: UNVERIFIED. @zed-industries/codex-acp@0.16.0 is too old for the current Codex CLI model (gpt-5.6-luna requires a newer version of Codex). User-side upgrade needed, then npm run smoke:acp -- codex. Not a Vellum bug — surface adapter/CLI version gaps, don't work around them.
• Two gotchas handled in PR #8: (1) claude-code-acp refuses to launch when CLAUDECODE is set (nested Claude Code session) — the client strips CLAUDECODE/CLAUDE_CODE_SSE_PORT from the adapter's child env. (2) A stalled turn used to hang forever — now bounded by 60s handshake/turn timeouts.
• Cold start is slow: session/new for claude-code-acp takes ~16s (loads a large skill/command set), so timeouts must stay generous.

First tasks (in order — see Phase-1-MVP)

1. Pick the ACP dep. Check npm for the current canonical ACP TypeScript client lib (likely @zed-industries/agent-client-protocol — verify, don't guess). Add to package.json.
2. Implement StdioAcpClient. Spawn the adapter subprocess, speak ACP over stdio, map events onto AcpUpdate.
3. Smoke test both backends respond over stdio on the local signed-in plan, in isolation, before any UI wiring. This de-risks the whole project.

Grounding

No RAG. Chat passes the paper's data/papers/<slug>/paper.md path as a context file; the agent reads/greps it with its own tools. Single papers fit in context directly; corpus questions let the agent grep across data/papers/.