Acp

AI

Stdio ACP client for an external Agent Client Protocol agent.

Use Port for raw CLI tools. Use Mcp for newline-delimited MCP servers. Use Acp for newline-delimited ACP over stdio — Cursor agent acp, local bridges such as acp-bridge, or any other ACP agent binary. Inside Server.application, connect from init and drive call / reply from update; HTTP handle should reach the core with Process.call / Process.send, never call Acp directly.

connect runs initialize. If the agent advertises authMethods, the client sends authenticate (preferring cursor_login when listed). Agents with no auth (typical for local bridges) skip that step. After Connected, create a session with call "session/new" … and prompt with call "session/prompt" …. Answer inbound agent requests (session/request_permission, cursor/*) with reply.

Examples: Acp.connect "agent" [ Port.args [ "acp" ] ] or Acp.connect "acp-bridge" [ Port.env [ ("LLM_BASE_URL", "http://127.0.0.1:11434/v1") ] ].

To run several agents side by side, give each one a key: Acp.connectAs "claude" "npx" [ Port.args [ "-y", "@agentclientprotocol/claude-agent-acp" ] ], then use callOn, replyOn, and subscribeOn with the same key. The unkeyed functions use the key "default". A call on a key that is not connected resolves to Err "acp not connected".

Types

ClientEvent

type ClientEvent
= Connected Value
| SessionUpdate Value
| AgentRequest String Int Value
| Disconnected String

Lifecycle and async traffic from the ACP session.

Examples

Acp.Connected value

Values

connect

connect : String -> List Setting -> Cmd msg

Spawn the ACP agent process. Forces binary+stream; pass Port.args, Port.env, and Port.cd as needed (e.g. agent with ["acp"], or acp-bridge with LLM_* env).

Examples

Acp.connect "agent" [ Port.args [ "acp" ] ]

call

call : String -> Value -> (Result String Value -> msg) -> Cmd msg

JSON-RPC request. The reply is tagged into msg.

Examples

Acp.call "session/new" JE.null GotSession

notify

notify : String -> Value -> Cmd msg

JSON-RPC notification (no id, no reply). Use for ACP methods that are notifications, such as session/cancel.

Examples

Acp.notify "session/cancel" (JE.object [ ("sessionId", JE.string sid) ])

reply

reply : Int -> Value -> Cmd msg

Answer an inbound agent AgentRequest (permission / agent extensions).

Examples

Acp.reply id (JE.object [ ("outcome", JE.string "selected") ])

subscribe

subscribe : (ClientEvent -> msg) -> Sub msg

Deliver ClientEvent values into the running program.

Examples

Acp.subscribe GotAcp

connectAs

connectAs : String -> String -> List Setting -> Cmd msg

connect for the agent identified by a key.

Examples

Acp.connectAs "claude" "npx" [ Port.args [ "-y", "@agentclientprotocol/claude-agent-acp" ] ]

callOn

callOn : String -> String -> Value -> (Result String Value -> msg) -> Cmd msg

call on the agent identified by a key.

Examples

Acp.callOn "claude" "session/prompt" params GotPrompt

notifyOn

notifyOn : String -> String -> Value -> Cmd msg

notify on the agent identified by a key.

Examples

Acp.notifyOn "claude" "session/cancel" params

replyOn

replyOn : String -> Int -> Value -> Cmd msg

reply on the agent identified by a key.

Examples

Acp.replyOn "claude" id result

subscribeOn

subscribeOn : String -> (ClientEvent -> msg) -> Sub msg

subscribe to the agent identified by a key.

Examples

Acp.subscribeOn "claude" GotAcp