Official

acp

ACP agents from the ACP registry (Gemini, Cursor, Droid, Kilo, pi, ...), Oh My Pi, and your own entries (custom.json in the plugin's data folder). Agents are discovered at runtime.

The app opens the listing; nothing installs until an agent in your Plugins workspace has read the files and you enable the plugin. In a terminal: dvg install divergence/acp@0.2.5

Permissions in 0.2.5

Take care. This plugin asks for permissions that can do anything your account can. The app asks you to hold Enable for two seconds or to type the plugin's name before it turns on.
  • Run any command process.anyDangerousStarts any program or shell command. This is as strong as your own account.Start the ACP agents, which the registry launches by path or through package runners such as npx and uvx, and run the terminal commands an agent asks for
  • Provide agents agents.provideMediumAdds agents to the app.Provide the agents of the ACP registry, and serve plugin tools to them through the host's loopback MCP server
  • Network access netMediumConnects to the listed hosts.Download the ACP registry and the agents' marks once a dayHosts: cdn.agentclientprotocol.com
  • Read files fs.readMediumReads files in the listed places.Read the files an agent asks for (ACP fs/read_text_file), only inside the chat's workspace, and your own agents from custom.json in this plugin's data folderPlaces: the open workspaceits own data folder
  • Write files fs.writeMediumCreates, changes and deletes files in the listed places.Write the files an agent asks to write (ACP fs/write_text_file), only inside the chat's workspace, and move the custom agents of the old ACP plugin into custom.json oncePlaces: the open workspaceits own data folder
  • Environment variables envMediumReads the listed environment variables.Sign Grok in with your xAI API key when you set one, and tell which Windows build of an agent to runVariables: XAI_API_KEYPROCESSOR_ARCHITECTURE

Files

NOTES.md18.5 KB
# ACP provider protocol notes

The provider runs any Agent Client Protocol agent over newline-delimited JSON-RPC on stdio. It follows ACP schema v1.32.0 and ACP v2 2.0.0-alpha.16, checked against the specification and TypeScript SDK 2.7.0 supplied for the provider audit. The v2 draft is selected only when the agent answers `initialize` with `protocolVersion: 2`; unstable features have their own capability gates. Embedded MCP Apps are supported when the host lists `mcpApps`.

## Module ownership

`agent.ts` owns process and host-session orchestration. `connection.ts` selects the negotiated wire handler. `v1.ts` owns v1 streaming, and `v2.ts` owns the alpha's request shapes, response schemas, identified entities, display terminals, and asynchronous completion. `requests.ts` handles agent-to-client requests and user answers. `session-options.ts` owns optional setup fields, option discovery, and authentication status. `history.ts` records v1 chunks, `replay.ts` nests replayed sessions, `entities.ts` retains compactions and session-directed messages, and `subagents.ts` owns restricted child associations. `apps.ts` maps embedded MCP pages and retains v1 partial tool state. `map.ts` contains the remaining pure host mappings, and `throttle.ts` bounds and coalesces v1 tool output.

`registry.ts`, `plugin.ts`, `main.ts`, `icons.ts`, and `maintenance.ts` retain registry discovery, scoped registration, launch resolution, marks, and updates. `files.ts` and `terminal.ts` implement the v1 client file and terminal APIs. `quirks.ts` contains the documented interoperability behavior for individual registry agents.

## Registry, launch, and permissions

Each registry entry becomes `acp:<registry id>`. Cached registry entries are combined with known entries and the user's `custom.json`; later sources replace earlier entries by ID. The registry excludes the agents served by Divergence's native providers. The known Oh My Pi entry uses `omp acp`. A fresh cache is used immediately; stale caches refresh in the background, with an hourly check for the daily refresh. Removed registry agents are unregistered. Marks are fetched from the registry CDN and retained in plugin storage.

Custom entries accept `id`, `name`, `command`, `args`, `env`, `directories`, and `mcpServers`. They are read from the plugin's data folder and from its `custom` storage key. Reload the plugin after editing `custom.json`. The legacy custom file is migrated once. There is no custom-entry settings page.

Launch resolution checks the login PATH, then the package's CLI, then its `npx` or `uvx` distribution. Archive-only entries report an installation hint rather than downloading binaries. Agents start in the requested workspace. A process has one permission mode; a chat requiring different process arguments waits until other chats' turns end before the process can restart. Session IDs remain addressable through a host-to-native mapping after restart or fresh-session recovery.

The manifest's existing `agents.provide`, `process.any`, CDN network, workspace/data filesystem, and environment grants suffice. No permissions were added. Native tools run with the agent's own authority; the v1 client filesystem and terminal requests still go through the host broker. Maintenance proves which installer owns a binary before offering an update, and stops the old process after updating it.

## Initialization and version negotiation

The client offers protocol version 2 with the v2 `info` and `capabilities` fields. The request also carries the v1 `clientInfo` and `clientCapabilities` fields as forward-compatible extra fields. A legacy v1 agent therefore receives its filesystem, terminal, authentication, elicitation, boolean-option and notice capabilities without requiring a second initialization or restarting its process. The selected response is parsed using that version's schema. Unsupported selections fail initialization before any session request.

V1 advertises `session.configOptions.boolean` and `session.notices`. Cursor alone receives `_meta.parameterizedModelPicker: true`. V2 uses its own capability layout: the presence of `capabilities.session` enables the baseline new/list/resume/close/prompt/cancel methods, and prompt and MCP extensions use object support markers. The client advertises form and URL elicitation in v2. It does not advertise v2 terminal authentication because the host cannot reproduce the agent invocation interactively; unsolicited terminal methods are not offered as supported sign-in actions.

V2 never implements the removed client filesystem or terminal-execution methods. Agent-owned display terminals are independent entities, not execution handles. V1 retains its five client terminal methods, including terminal tasks whose output and lifetime can outlast a prompt.

## Authentication and URL consent

Logout is sent only when the selected protocol advertises it. In v1 this requires non-null `agentCapabilities.auth.logout`. In v2 a nonempty native `authMethods` list advertises `auth/login` and `auth/logout`. V2 method IDs come from `methodId`; v1 IDs still come from `id`. Unsupported logout fails clearly without sending a request. V1 terminal methods continue to show the command the user can run manually.

When `auth.status` is advertised, the provider queries `auth/status` after connecting and after login or logout, and handles `auth/status_update`. `authenticated` and `not_required` clear the sign-in requirement; `unauthenticated` sets it. Unknown states preserve the last observed readiness. A changed state refreshes the existing host agent row through `host/agents.changed`. Account details are neither stored in host metadata nor displayed. Ordinary authentication-required errors remain the fallback for agents without status support.

A session URL elicitation becomes a question containing the URL and explicit accept and decline choices. The user's answer immediately returns `accept`, `decline`, or `cancel`; it never waits for `elicitation/complete`. Optional external completion is tracked separately and cannot grant consent. The user follows the question's link. Requests outside a chat, including during Settings sign-in, are declined with a visible explanation because the existing Settings button does not display the eventual target host or provide URL-specific consent. A general question outside a chat needs a shared host affordance before arbitrary request-scoped URL or form interaction can be supported.

`$/cancel_request` withdraws pending approvals and questions, replies with the native cancelled outcome, and resolves their host cards. Cancelling foreground work leaves v2 requests associated with reported background work pending.

## Session setup and options

Trusted plugin instructions use `systemPrompt: { mode: "append", content: [{ type: "text", text }] }` on new, load, resume, and fork requests only when the agent advertises system-prompt support. Older agents retain the first-user-prompt instructions block, which replay strips out. Reattaching an unchanged native-system session does not insert that block again, and changed instructions use a supported native resume or load request. A session that cannot update its native instructions reports the limitation without pretending the change was applied.

An advertised `sessionCapabilities.options` in v1, or `session.options` in v2, enables `session/options`. Option discovery then makes no throwaway session. Initial native choices are sent as `configOptions` on supported setup requests, excluding the provider's permission option. The setup response remains authoritative; ignored initial choices produce a warning rather than a fabricated selection. Legacy synthesized mode/model selectors still use their legacy setters when needed. Agents without this extension retain throwaway discovery and post-creation setters.

Every published native config option, including one whose ID is `mode`, uses `session/set_config_option`. Only a synthesized legacy mode selector uses `session/set_mode`. V2 maps `configId` and `groupId` to the host's option IDs and groups and sends the required setter `type` of `id` or `boolean`. Setup responses replace v2 config and command lists, including omission as an empty list. Command variants and input variants unknown to the client are not presented as executable slash commands.

Plugin tools are served through the host's loopback HTTP MCP server only when HTTP MCP support is advertised. Custom v2 MCP servers carry explicit transport discriminators and must use advertised transports; SSE is not a v2 transport. Additional directories are sent only when advertised. Existing tool-server claim and close behavior is retained.

## Runs and replay

V1 keeps `session/prompt` pending until its response ends the turn, with the existing out-of-band completion extension for agents that use it. V2's prompt response acknowledges insertion and supplies the native user-message ID. It consumes the host input but does not finish the run. The provider waits for an active-to-idle `state_update`; idle setup/resume snapshots and repeated idle snapshots do not create completions. Completion received before acknowledgement is retained. Native error stop reasons fail the run and can refresh sign-in state without resubmitting an inserted message. Agent-initiated work publishes a host run when the native state becomes active.

Both versions emit one `run_finished` for each run. Cancel is a notification and waits for native completion; v2 confirms it through idle, while v1 confirms it through the prompt response. Existing cancellation timeout and simulated-steering behavior remains. Background display tasks retain their independent lifetimes.

V1 history uses `session/load`; its existing quiet-replay fallback and hard load timeout remain. V2 uses `session/resume` with `replayFrom: { type: "start" }`. Each session's `replay_complete` separates its own history from subsequent live updates, including child sessions. V2 never treats a quiet replay as successful completion. A successful response without the marker still certifies the replay as specified; an error or disconnect before certification fails the load. Replayed entity state is retained for later live patches. V2 resume snapshots can report active work and are not reset to idle by the response.

History retains native identities and nested task transcripts. Listed `updatedAt` values provide the existing unchanged-history optimization. Session listing handles pagination, including an empty-string cursor, and filters results to the requested workspace. Native titles become `session_info` on both live and load paths.

## Messages, tools, terminals, and compaction

V2 messages, thoughts, tools, terminals, and plans are keyed by entity type and native ID. First appearance fixes timeline position. Chunks append, concrete snapshots replace, omission preserves, and null clears the retained native value. Metadata patches replace individual top-level keys and remove keys set to null. V1 association and session-message metadata retain v1's whole-object replacement semantics. Unknown update variants are ignored safely; malformed known required envelopes are logged rather than treated as future variants.

Tool names come from native `name`, including later corrections. Both live and replay updates retain renames. Older hosts ignore the optional update name. Tool kinds use structured native categories. V1 whole-file diffs retain `oldText` and `newText`; v2 diffs use authoritative `changes` paths and optional `git_patch` text. Display terminal snapshots replace bytes; chunks decode independently, preserve split UTF-8 characters, and retain a bounded tail. Invalid base64 leaves prior output intact without discarding other terminal fields. Terminal exit, tool completion, and foreground completion are independent.

Compaction IDs retain ordered summary append/replacement/clear patches and terminal status. Live progress maps to `compacting` and `compacted`; failures also produce a notice. Replay retains one compaction or failure item per ID with its final retained summary. The host's live compaction events have no ID, status, or patch operation, so arbitrary later corrections and interleaved compactions cannot be represented faithfully there. Consequently v1 `session.compaction` is not advertised: its empty capability marker promises the full contract. V2 baseline compaction updates are handled with the same available host events and exact replay state.

## Embedded MCP Apps

The host's `agent/initialize` feature list is retained per registered agent. Only hosts listing `mcpApps` receive `mcp_app` content. Hosts without that feature keep the previous content mapping. Both wires recognize a tool content item shaped as `{ type: "content", content: { type: "resource", resource } }` whose resource URI starts with `ui://` and whose MIME type is `text/html;profile=mcp-app` or `text/html`. Text and base64 UTF-8 blobs become inline `html`, and the resource's `_meta.ui` becomes `meta`. Invalid blobs produce a warning and retain the existing fallback. App blocks precede the existing text, image, diff, and terminal content.

ACP defines no standard server identity on a tool call. The provider recognizes explicit `{ server, tool }` string pairs in the call's `_meta.mcp`, then `_meta`, then `rawInput`. It also recognizes an exact `mcp__server__tool` string in native `name`, then `title`. These are recognized conventions within schema-permitted values, not ACP fields or capabilities. Calls without an identifiable server and tool retain their fallback without an app. Server identity is never inferred from the page URI or registry entry.

When a completed, failed, or cancelled call exposes an MCP result in `rawOutput` with a `content` array, the entire native result becomes `result`, preserving `structuredContent`, `_meta`, and `isError` when present. ACP does not require that raw output be an MCP result. Ordinary raw output and ACP display content cannot establish the server's original result, so no result is fabricated from them. Live patches and replay use the same mapping, including later identity or result updates and v2 content chunks and null clears.

Neither ACP version gives the client an operation to read resources or call tools on the agent's MCP servers. MCP-over-ACP serves client-provided servers to the agent in the opposite direction. The provider therefore leaves `capabilities.mcpApps` off and does not implement `mcp_read_resource` or `mcp_call_tool`. No new capability is sent to the agent because neither client capability schema defines MCP Apps support. Embedded pages can display, but app requests for server resources or tools remain unsupported.

## Restricted subagents

Native `subagent_update` establishes the immediate parent before child traffic. V1 requires the client `subagents` capability; upstream defines no corresponding agent capability. The provider leaves that indivisible marker unadvertised until the host has an unconfirmed task state, because omitting a task status currently defaults to running. V2 makes these updates baseline. Tasks keep reusable running, waiting, and idle state, optional model and reasoning metadata, and explicit tool session references. Nested parent IDs are retained. Unknown or cleared activity is not converted into a successful completion.

Child text, reasoning, tools, approvals, questions, and usage carry `taskId` under the root host session. Child commands and configuration controls are not offered as parent controls. Child sessions cannot be prompted, independently resumed, loaded, forked, closed, or configured through ordinary host methods. `cancel_task` sends cancellation only if that specific child currently advertises it. Root cancellation respects reported background requests.

Session-directed messages retain their own IDs and append/replacement/clear semantics. They display explicit sender and recipient session IDs when supplied and a generic inter-session label otherwise. Incoming messages are never synthesized from outgoing ones. Replay nests each child's transcript at its announcement position.

## Host limits and deliberate omissions

The shared host needs an ID-addressed compaction contract before v1 compaction can be advertised fully, a question affordance outside chats for arbitrary request-scoped interactions, and an unconfirmed task status to distinguish native unknown activity from the host's default running state before v1 subagents can be advertised. The provider retains native unknown state and does not invent a successful or failed outcome. Per-child control availability is checked before sending any native mutation; the host currently exposes cancellation capability at the agent level rather than per task.

The v2 native projection applies null clears to raw tool input/output and usage cost, but the existing optional host fields cannot express every such clear to an already displayed live row. Exact native state remains in replay. Structured file operations, terminal sizes, and terminal signals have richer native metadata than the current host display contract. The host also clears pending approvals when a foreground run finishes, so a native background permission request needs shared retention support to keep its card answerable across that boundary. These need shared protocol work for complete live fidelity.

Native title notifications and listing are supported. User-initiated native title changes, archive/unarchive, prompt suggestions, and account details have no fitting host method or event and are not advertised or fabricated. `session/status` has a parsed wire shape but is not polled: existing load/resume responses remain authoritative for recovery. Session deletion, provider/MCP management, plan-operation extensions, NES, and document synchronization remain outside this provider's host contract.

## Verification

Run `node --import ./plugins/testing/register.mjs --test plugins/acp/*.test.ts`, `pnpm typecheck:plugins`, and `node scripts/slop/check.mjs` from the repository root. The Node resolver flag is required for the host's built-in modules. Scripted peers cover both negotiated wires, consent and cancellation, option provenance and setup, authentication refresh, tool renames, compaction patches, restricted nested children, v2 acceptance/completion ordering, replay boundaries, display-terminal bytes, and permission subjects. `apps.test.ts` covers host feature gates, unchanged agent capabilities, inline HTML and metadata, native result fidelity, partial updates, nested replay, null clears, and malformed resource fallbacks.

The run model and its five invariants are in `docs/features/providers/models/AcpRun.tla`. The existing ignored host end-to-end tests can additionally exercise an installed ACP agent through the loopback tools server; no live-agent result is claimed by the scripted suite.

Versions

VersionPublishedPlugin APISizePermissionsStatus
0.2.5latestNov 21, 2026>=5 <6134 KB6 permissionsListed
0.2.4Nov 16, 2026>=5 <6132.8 KB6 permissionsListed
0.2.3Nov 11, 2026>=5 <6108.9 KB6 permissionsListed
0.2.2Nov 9, 2026>=5 <6105.6 KB6 permissionsListed
0.2.1Oct 27, 2026>=2 <4105.3 KB6 permissionsListed

Reviews and comments

0 threads · 0 reviews

No comments yet.