aisdk.acp

Agent Client Protocol (ACP) client for R. Drive external, ready-made coding agents (Claude Code, Codex, dsh, ...) over the ACP v1 stdio transport (JSON-RPC 2.0 with NDJSON framing) directly from an R session.

Status: first development version. The protocol core (sessions, prompts, streaming updates, cancellation, restore, permissions, resource limits) is implemented and tested against a scriptable fake agent. The context bridge is implemented: with bridge = TRUE (the default) the spawned agent gets read-only MCP tools (r_session_info, r_ls, r_inspect, r_last_plot) into the live R session — token-protected on loopback, never evaluating user code, served from the pump/poll cycles. Unix only (serverSocket is unavailable on Windows, where the bridge degrades to a warning); requires the aisdk.mcp and aisdk packages to be resolvable by the bridge child (R_LIBS_USER).

Install

# not yet on CRAN
remotes::install_github("YuLab-SMU/aisdk.acp")

Quick start

library(aisdk.acp)

agent <- AcpAgent$new(agent = "claude", cwd = ".")
agent$spawn()
turn <- agent$prompt("Summarize the files in this project.")
turn$outcome   # completed / failed / stopped / unknown
turn$text      # visible text produced by the agent
agent$close()

Long-running tasks use the background mode:

turn <- agent$prompt_async("Refactor the tests.")
# ... do other work ...
turn <- agent$poll()   # idempotent: reaping an already-final turn is a no-op

Session identity is persisted under <project>/.aisdk/acp/ before any prompt is dispatched, so a turn can always be attributed and resumed:

agent2 <- acp_resume(agent$id(), cwd = ".")

Design notes

• Capability-driven: agent differences (session restore style, close support, permission option shapes) are inferred from the initialize capability advertisement, never hard-coded per agent.
• Trust boundary: cwd, model, MCP server list, executable and environment variables are trusted caller configuration only; values that originate from agent output never flow back into these slots.
• Outcome vocabulary: completed, failed, stopped, unknown, plus not_dispatched for turns that failed before the prompt was sent. unknown is a legitimate outcome, not an error status.