@tanstack/ai-acp weekly downloads statistics

@tanstack/ai-acp

Shared Agent Client Protocol (ACP) plumbing for TanStack AI harness adapters — the code that turns a coding-agent CLI (grok, gemini --acp, …) into a chat() backend inside a sandbox.

Most apps should use a harness package directly (@tanstack/ai-grok-build, …). Reach for @tanstack/ai-acp when:

• you want to plug an ACP agent that has no dedicated adapter package into a sandbox — use acpCompatible (the openaiCompatible of harnesses), or • you are building or extending a harness adapter and need the transport, session, permission, and stream-translation layers in one place.

Installation

Peer dependencies: @tanstack/ai, @tanstack/ai-sandbox. The package also depends on @agentclientprotocol/sdk for the JSON-RPC client.

What it does

Harness CLIs that support ACP expose a long-lived JSON-RPC session. They stream session updates (text chunks, tool calls, planning, permissions) while the orchestrator drives the turn with prompt. TanStack AI speaks AG-UI StreamChunks (RUN_STARTED, TEXT_MESSAGE_CONTENT, TOOL_CALL_*, RUN_FINISHED, …).

@tanstack/ai-acp sits in the middle:

Responsibilities split roughly as:

| Layer | Module | Role |

| Transport | transport/* | Bytes ↔ JSON-RPC: stdio (NDJSON) or WebSocket | | Session | session/acp-client | initialize → authenticate → newSession / loadSession → prompt | | Sandbox server | session/sandbox-server | Boot an in-sandbox serve process and connect over an exposed port | | Translation | stream/translate | ACP sessionUpdate events → TanStack StreamChunks | | Permissions | permissions | Map harness permission prompts to allow/reject (and optional approval ids) |

Plug in any ACP agent (acpCompatible)

acpCompatible is the easy path: it builds a chat() text adapter for any ACP-compliant agent CLI without a dedicated package — the harness equivalent of openaiCompatible. Configure the harness once, select a model per call, pass it into a sandbox.

You get the full ACP flow for free: sandbox resolution, chat()-tool → MCP bridging, session resume (via modelOptions.sessionId), permission modes, abort, and AG-UI translation.

Configuration

| Field | Purpose |

| name (required) | Provider label, log prefix, and the .session-id CUSTOM event name. | | models | Model ids the harness accepts — declaring them makes harness('id') type-safe. Omit to accept any string. | | modelOptions | Type-only brand ({} as { … }) for the per-call options of chat({ modelOptions }); merged with the base options and exposed on ctx.modelOptions. | | command | Build the stdio launch command (({ model, cwd, harnessCwd, sandbox, env, modelOptions, signal }) => string). Required unless openTransport is given. | | openTransport | Full transport escape hatch — open any AcpSessionTransport yourself (e.g. boot a serve process and connect over WebSocket). Overrides command. | | cwd | Working directory inside the sandbox (default /workspace). | | skillsDir | The harness's skills dir relative to the workspace root (e.g. '.pi/skills') — withSandbox workspace gitSkills are linked here. MCP skills ride ACP natively, so they need no path. | | env | Extra environment variables for the harness process. | | authMethodId | ACP auth method to select before the session starts. | | permissionMode | 'default' \| 'acceptEdits' \| 'bypassPermissions' (default). | | permissions | 'headless' (auto-resolve, default) or 'interactive' (emit approval-requested events for ask prompts). | | onPermissionRequest | Custom PermissionHandler; overrides permissions/permissionMode. | | refusalMessage | RUN_ERROR message when the harness refuses. | | planEventName | Emit ACP plan updates as a CUSTOM event under this name. | | emitDiff | Emit the post-run git diff of cwd as a file.changed CUSTOM event (off by default). | | onExtNotification | Handle vendor _x/… JSON-RPC notifications. | | buildPrompt | Override how chat history maps to the harness prompt (defaults to buildAcpPrompt). |

For WebSocket/serve harnesses, return your own transport from openTransport (see how @tanstack/ai-grok-build boots grok agent serve with startAcpServerInSandbox + connectAcpWebSocket). Use `acpCompatibleText(model, config)` for a one-shot single-model adapter.

Protocol coverage

This is a compliant minimal client for the orchestration role — it drives a full prompt turn, not the entire spec surface. Everything it omits is either capability-gated (advertising non-support _is_ the spec-defined behavior) or a rendering choice, not a violation.

• Covered: initialize (with clientInfo + version negotiation), authenticate, session/new, session/load, session/prompt, session/cancel, session/request_permission (all four option kinds), the turn-output updates (agent_message_chunk, agent_thought_chunk, tool_call, tool_call_update, plan), and all five stop reasons. • Surfaced as CUSTOM events (the AG-UI chat-event protocol has no first-class event for non-text assistant _output_): .session-id, the plan event, and .message-content for non-text agent content (image / audio / resource blocks). Non-text tool content is preserved inside the TOOL_CALL_RESULT payload. • Workspace projection: MCP skills → ACP mcpServers natively; gitSkills → linked into skillsDir; fileSkill/instructions/secrets → handled by bootstrap. agentSkill/plugins are warned-and-skipped. • Not implemented (by design): fs/read_text_file, fs/write_text_file, terminal/* (advertised unsupported — the agent has direct sandbox FS/shell access); sending multimodal _prompts_ (text only); incremental usage_update (final usage is reported); available_commands_update / current_mode_update; and experimental features (elicitation, NES, providers, session modes).

Quick start (building a harness adapter)

If acpCompatible doesn't fit (you need a typed provider-options surface, custom structured output, vendor projections, …), build the adapter by hand. The pattern every ACP harness adapter follows:…

Description from the npm listing.