Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,21 @@ plugin contract.

## [Unreleased]

### Added

- Native OpenCode shell, read, list, search, edit, write, web, todo and task
presentation for recognised ACP tool activity, with structured ACP metadata
retained on fallback cards.
- Cursor, Claude, Codex and Grok subagent activity projection, plus the shared
ACP task-shape fallback used by Hermes and custom agents.

### Fixed

- Preserve OpenCode provider whitelist/blacklist settings when injecting an ACP
provider, including base-ID expansion for parameterised Cursor model IDs.
- Correlate session-less Cursor task notifications by tool-call ID and suppress
redundant control-tool cards for informational task/todo extensions.

## [0.1.0] - 2026-08-15

### Added
Expand Down
14 changes: 10 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,9 @@ callbacks required for full-fidelity ACP operation.
fallback.
- One durable ACP conversation per OpenCode session, server and worktree.
- Streaming assistant text, thought/reasoning, usage, plans and provider-owned
tool calls without re-executing those tools in OpenCode.
tool calls without re-executing those tools in OpenCode. Standard ACP tool
kinds are projected onto OpenCode's native shell, read, list, grep, glob,
edit, write, web and task cards when the agent supplies enough metadata.
- OpenCode-native permission prompts with exact ACP `allow_once`,
`allow_always`, `reject_once` and cancellation correlation.
- Standard form elicitation and Cursor questions through OpenCode's built-in
Expand All @@ -28,7 +30,10 @@ callbacks required for full-fidelity ACP operation.
authentication metadata retained on the private worker event channel.
- Native agent skills, rules, hooks, MCP servers, memory and subagents remain
active in the ACP agent. Advertised commands and invocable skills are added
to OpenCode's startup command catalogue when available.
to OpenCode's startup command catalogue when available. Cursor task events,
Claude/Codex subagent calls and Grok subagent lifecycle notifications are
rendered as native OpenCode task activity; other agents receive the shared
ACP task-shape fallback.
- Bounded, authenticated NDJSON IPC between the OpenCode plugin and a
plugin-owned Node worker, including parent-death and idle cleanup.

Expand Down Expand Up @@ -229,8 +234,9 @@ See [testing](docs/testing.md) for the complete matrix and release procedure.
internal to that agent.
- OpenCode-native tools are not injected into the ACP agent as MCP tools.
- Rewind/fork creates a fresh binding when the selected agent cannot fork.
- Rich agent-specific timeline cards degrade to generic provider-executed tool
cards with structured metadata.
- Native timeline projection is best-effort: incomplete or unknown agent tool
shapes degrade to generic provider-executed cards with structured ACP
metadata, while the private worker channel retains the complete event.
- Hermes is supported through its legacy ACP model surface; its own advertised
and upstream limitations still apply.

Expand Down
15 changes: 13 additions & 2 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -89,8 +89,19 @@ calls. The provider therefore segments one ACP turn:
6. emit the final `finish` only when ACP completes.

ACP-native tool calls are marked `providerExecuted: true`; OpenCode renders but
does not execute them. Reserved interaction calls are host-executed and use
unguessable, expiring tokens bound to the OpenCode and ACP sessions.
does not execute them. A shared projector maps ACP `execute`, `read`, `search`,
`edit` and `fetch` events onto native OpenCode presentation contracts while
retaining ACP status, locations, raw input/output and content as provider
metadata. Unknown shapes keep a namespaced generic tool name. Reserved
interaction calls are host-executed and use unguessable, expiring tokens bound
to the OpenCode and ACP sessions.

Subagent activity follows the same rule. Standard task-shaped calls cover
Claude, Codex and compatible agents. Cursor's session-less `cursor/task`
notification is correlated back to the active turn by its ACP tool-call ID;
Grok's spawn/progress/finish notifications maintain one synthetic native task
lifecycle. ACP child identifiers remain metadata because they are not OpenCode
child-session identifiers and must not become broken UI links.

## Discovery

Expand Down
42 changes: 27 additions & 15 deletions docs/compatibility.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,21 +6,22 @@ default.

## Shared feature mapping

| ACP feature | OpenCode representation |
| ----------------------------------------- | -------------------------------------------------------------------- |
| Model config option or legacy model state | Provider model catalogue |
| Model parameters and thought level | Model options/variants and session config |
| Agent mode | Session control and configured default |
| Agent text | Assistant text |
| Agent thought | Reasoning |
| Agent-native tool | Provider-executed dynamic tool |
| Plan | ACP update retained on the private worker event channel |
| Permission request | Reserved plugin tool and OpenCode permission UI |
| Form or URL elicitation | Question/control tool when representable; otherwise cancel |
| Available command | Startup OpenCode command snapshot |
| Agent-native skill | Remains available inside the agent |
| Session lifecycle | Persistent Acpx binding with capability-gated load/resume/close/fork |
| MCP server | ACP session MCP definition, capability-gated by transport |
| ACP feature | OpenCode representation |
| ----------------------------------------- | ------------------------------------------------------------------------- |
| Model config option or legacy model state | Provider model catalogue |
| Model parameters and thought level | Model options/variants and session config |
| Agent mode | Session control and configured default |
| Agent text | Assistant text |
| Agent thought | Reasoning |
| Agent-native tool | Provider-executed native OpenCode card where recognised; generic fallback |
| Subagent activity | Native OpenCode task card where standard/vendor metadata permits |
| Plan | ACP update retained on the private worker event channel |
| Permission request | Reserved plugin tool and OpenCode permission UI |
| Form or URL elicitation | Question/control tool when representable; otherwise cancel |
| Available command | Startup OpenCode command snapshot |
| Agent-native skill | Remains available inside the agent |
| Session lifecycle | Persistent Acpx binding with capability-gated load/resume/close/fork |
| MCP server | ACP session MCP definition, capability-gated by transport |

ACP v1 has no global model or skill catalogue. Discovery is session-scoped and
dynamic. Catalogue entries are therefore per-instance snapshots;
Expand All @@ -41,6 +42,9 @@ re-authentication or an agent update may require an OpenCode reload.
- Native rules, skills, commands, plugins, hooks, MCP, code index and subagents
remain active. Advertised commands are surfaced where OpenCode permits.
- Cursor ask/plan/todo/task/image extension methods are version-gated.
- Standard task tool calls and `cursor/task` completion notifications are
correlated into one native OpenCode task card without inventing a host child
session link.

### Claude Agent ACP

Expand All @@ -51,6 +55,8 @@ re-authentication or an agent update may require an OpenCode reload.
- AskUserQuestion requires form elicitation; device/remote login may require URL
elicitation or a terminal-auth action.
- Native Claude commands and skills arrive through available-command updates.
- Claude Task/Agent calls with prompt, description and subagent type metadata
are projected as native OpenCode task cards.

### Codex ACP

Expand All @@ -62,6 +68,8 @@ re-authentication or an agent update may require an OpenCode reload.
- Codex slash commands and `$skill` entries are surfaced from runtime updates.
- Standard form/URL elicitation covers request-user-input and device auth where
advertised.
- Codex collaboration and sub-agent activity calls are projected as native
OpenCode task cards while preserving thread identifiers in ACP metadata.

### Grok Build

Expand All @@ -71,6 +79,8 @@ re-authentication or an agent update may require an OpenCode reload.
applied before the first prompt.
- Native skills, workflows, plugins, hooks, memory, MCP and subagents remain in
Grok. `x.ai/*` extensions are handled only when their schemas are recognised.
- Recognised `subagent_spawned`, `subagent_progress` and `subagent_finished`
notifications produce one running native task card and its final result.
- The current CLI remains alpha; every exact build receives a capability
fingerprint and newer builds warn until tested.

Expand All @@ -84,6 +94,8 @@ re-authentication or an agent update may require an OpenCode reload.
- Modes: `default`, `accept_edits`, `dont_ask` when advertised.
- Native tools, memory and skills remain active, but installed skills are not
individually advertised as ACP commands in Hermes 0.20.1.
- Hermes subagent-like calls use the shared ACP task-shape detector; the current
adapter does not advertise a separate subagent lifecycle extension.
- The current agent accepts session MCP servers without advertising MCP
capabilities; this is reported as a compatibility warning.

Expand Down
21 changes: 21 additions & 0 deletions docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -105,6 +105,27 @@ identifiers or vendor-qualified IDs. A zero limit means unknown and disables
OpenCode context-overflow handling; the ACP agent remains responsible for its
own context.

### OpenCode model filters

Normal OpenCode provider filters apply after ACP discovery:

```jsonc
{
"provider": {
"acp.cursor": {
"whitelist": ["grok-4.6"],
},
},
}
```

The plugin preserves both `whitelist` and `blacklist`. An exact opaque model ID
is used unchanged. A convenient base ID such as `grok-4.6` expands to currently
discovered parameterised IDs such as
`grok-4.6[effort=high,fast=true]`; it does not act as a substring match. This
keeps the filter usable across Cursor catalogue refreshes without discarding
the exact ID that ACP needs for selection.

### MCP servers

Stdio:
Expand Down
2 changes: 2 additions & 0 deletions docs/testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,8 @@ Unit tests cover:
- prompt extraction and attachment validation;
- balanced AI SDK text/reasoning events;
- provider-executed ACP tool lifecycles;
- native shell/read/search/edit/web projection with generic fallbacks;
- Cursor, Claude, Codex and Grok subagent task projection and de-duplication;
- finish reason and usage mapping;
- interaction segmentation and cursor replay;
- exact permission/question correlation;
Expand Down
37 changes: 35 additions & 2 deletions src/provider.ts
Original file line number Diff line number Diff line change
Expand Up @@ -79,7 +79,7 @@ interface TurnState {

interface RuntimeHub {
turns: Map<string, TurnState>;
orphans: Map<string, (ElicitationInteraction | ExtensionInteraction)[]>;
orphans: Map<string, RuntimeWorkerEvent[]>;
unsubscribe: () => void;
}

Expand Down Expand Up @@ -128,7 +128,8 @@ function runtimeHub(runtime: ProviderRuntime): RuntimeHub {
hub.unsubscribe = runtime.client.subscribe((event) => {
if (
(event.type !== "interaction.elicitation" &&
event.type !== "interaction.extension") ||
event.type !== "interaction.extension" &&
event.type !== "extension.notification") ||
event.turnId === undefined
) {
return;
Expand Down Expand Up @@ -385,6 +386,12 @@ function failClosedGenericInteraction(
});
}

function isInformationalCursorExtension(event: ExtensionInteraction): boolean {
return (
event.method === "cursor/task" || event.method === "cursor/update_todos"
);
}

function updateState(
state: TurnState,
event: RuntimeWorkerEvent,
Expand Down Expand Up @@ -470,6 +477,27 @@ function streamTurn(
event.type === "interaction.elicitation" ||
event.type === "interaction.extension"
) {
if (
event.type === "interaction.extension" &&
isInformationalCursorExtension(event)
) {
for (const part of translator.extensionNotification({
type: "extension.notification",
serverId: event.serverId,
...(event.sessionKey === undefined
? {}
: { sessionKey: event.sessionKey }),
...(event.turnId === undefined ? {} : { turnId: event.turnId }),
method: event.method,
params: event.params,
}))
controller.enqueue(part);
await runtime.client.respondExtension({
interactionId: event.interactionId,
result: {},
});
continue;
}
const projection = translator.interaction(event);
if (projection === undefined) {
await failClosedGenericInteraction(runtime, event);
Expand All @@ -486,6 +514,11 @@ function streamTurn(
controller.close();
return;
}
if (event.type === "extension.notification") {
for (const part of translator.extensionNotification(event))
controller.enqueue(part);
continue;
}
if (event.type === "turn.result") {
for (const part of translator.terminal(event.result))
controller.enqueue(part);
Expand Down
33 changes: 31 additions & 2 deletions src/server.ts
Original file line number Diff line number Diff line change
Expand Up @@ -328,11 +328,24 @@ function injectConfiguration(
if (!server.enabled) continue;
const id = providerId(serverId);
addedProviderIds.push(id);
const existing = config.provider[id];
const models = buildProviderModels(
serverId,
server,
catalogues.get(serverId),
);
config.provider[id] = {
...existing,
name: `${resolvePreset(server)?.title ?? serverId} through ACP`,
npm: providerUrl.href,
options: { pluginInstanceId, serverId },
models: buildProviderModels(serverId, server, catalogues.get(serverId)),
options: { ...existing?.options, pluginInstanceId, serverId },
models,
...(existing?.whitelist === undefined
? {}
: { whitelist: expandModelFilter(existing.whitelist, models) }),
...(existing?.blacklist === undefined
? {}
: { blacklist: expandModelFilter(existing.blacklist, models) }),
};
const commandName = `acp-${serverId}`;
config.command[commandName] ??= {
Expand Down Expand Up @@ -471,6 +484,22 @@ function unique(values: string[]): string[] {
return [...new Set(values)];
}

function expandModelFilter(
configured: string[],
models: Record<string, ProviderModelConfig>,
): string[] {
const modelIds = Object.keys(models);
return unique(
configured.flatMap((configuredId) => {
if (models[configuredId] !== undefined) return [configuredId];
const parameterised = modelIds.filter((modelId) =>
modelId.startsWith(`${configuredId}[`),
);
return parameterised.length === 0 ? [configuredId] : parameterised;
}),
);
}

function serverWorkingDirectory(
server: ServerConfig,
fallback: string,
Expand Down
Loading
Loading