Skip to content

Commit 963afe0

Browse files
committed
fix(cli): expose retryable ACP plugin activation readiness errors
1 parent b6d958c commit 963afe0

5 files changed

Lines changed: 63 additions & 5 deletions

File tree

‎packages/cli/src/acp/agent.ts‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,13 @@ export const connect = Effect.fnUntraced(function* (client: OpenCodeClient, stre
4747
Effect.catchTags({
4848
ACPCatalogLoadError: (error) => ACPClient.classify(error.cause),
4949
ACPCatalogNotReadyError: (error) =>
50-
Effect.fail(new ACPError.ServiceFailureError({ safeMessage: error.message, errorName: "CatalogNotReady" })),
50+
Effect.fail(
51+
new ACPError.ServiceFailureError({
52+
safeMessage: error.message,
53+
errorName: "CatalogNotReady",
54+
...(error.reason === "plugins" ? { service: "plugin", retryable: true } : {}),
55+
}),
56+
),
5157
}),
5258
Effect.mapError((error) => (error instanceof RequestError ? error : ACPError.toRequestError(error))),
5359
Effect.tapCauseIf(Cause.hasDies, (cause) => Effect.logError("ACP request failed", cause)),

‎packages/cli/src/acp/catalog.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -146,6 +146,13 @@ const load = Effect.fn("cli.acp.catalog.load")(function* (client: OpenCodeClient
146146
error.cause.service === "plugin"),
147147
schedule: poll,
148148
}),
149+
Effect.mapError((error) =>
150+
error._tag === "ACPCatalogLoadError" &&
151+
error.cause instanceof ServiceUnavailableError &&
152+
error.cause.service === "plugin"
153+
? new ACPError.CatalogNotReadyError({ reason: "plugins" })
154+
: error,
155+
),
149156
)
150157
})
151158

‎packages/cli/src/acp/error.ts‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,7 @@ export class ServiceFailureError extends Schema.TaggedError<ServiceFailureError>
4848
safeMessage: Schema.String,
4949
service: Schema.optional(Schema.String),
5050
errorName: Schema.optional(Schema.String),
51+
retryable: Schema.optional(Schema.Boolean),
5152
}) {}
5253

5354
export class ServerUnavailableError extends Schema.TaggedError<ServerUnavailableError>()(
@@ -56,9 +57,10 @@ export class ServerUnavailableError extends Schema.TaggedError<ServerUnavailable
5657
) {}
5758

5859
export class CatalogNotReadyError extends Schema.TaggedError<CatalogNotReadyError>()("ACPCatalogNotReadyError", {
59-
reason: Schema.Literals(["models", "agents"]),
60+
reason: Schema.Literals(["models", "agents", "plugins"]),
6061
}) {
6162
override get message() {
63+
if (this.reason === "plugins") return "Location plugins are still activating; retry this request"
6264
return this.reason === "models" ? "No models are available" : "No primary agents are available"
6365
}
6466
}
@@ -121,6 +123,7 @@ export function toRequestError(error: Error): RequestError {
121123
{
122124
...(error.service ? { service: error.service } : {}),
123125
...(error.errorName ? { errorName: error.errorName } : {}),
126+
...(error.retryable !== undefined ? { retryable: error.retryable } : {}),
124127
},
125128
error.safeMessage,
126129
)

‎packages/cli/test/acp/catalog.test.ts‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -126,6 +126,32 @@ describe("ACP transient plugin activation failures", () => {
126126
})
127127
}
128128

129+
test("reports retryable activation exhaustion and can resume the same session later", async () => {
130+
let activating = true
131+
await using acp = await startWire({
132+
fetch(request) {
133+
if (request.path !== "/api/model" || !activating) return
134+
return Response.json(
135+
{ _tag: "ServiceUnavailableError", service: "plugin", message: "Location plugins did not finish activating" },
136+
{ status: 503 },
137+
)
138+
},
139+
})
140+
const session = makeSession("ses_pending")
141+
acp.server.sessions.set(session.id, session)
142+
await acp.initialize()
143+
const params = { cwd: "/workspace", sessionId: session.id, mcpServers: [] }
144+
expect(await rpcError(acp.request("session/resume", params))).toEqual({
145+
code: -32603,
146+
message: "Internal error: Location plugins are still activating; retry this request",
147+
data: { errorName: "CatalogNotReady", service: "plugin", retryable: true },
148+
})
149+
expect(acp.server.sessions.get(session.id)).toEqual(session)
150+
activating = false
151+
expect(await acp.request("session/resume", params)).toHaveProperty("configOptions")
152+
expect(acp.server.sessions.size).toBe(1)
153+
}, 10000)
154+
129155
test("closing ACP cancels a catalog load that is retrying activation", async () => {
130156
let reads = 0
131157
const acp = await startWire({

‎services/www/src/docs/content/cli/acp.mdx‎

Lines changed: 19 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -223,10 +223,10 @@ OpenCode adds them to the session's directory for the life of the `opencode acp`
223223
directory can use them. OpenCode passes HTTP headers through and doesn't use OAuth for these servers. It doesn't
224224
advertise MCP over SSE, and it doesn't support MCP over ACP.
225225

226-
| Case | Behavior |
227-
| -------------------------------- | ------------------------------------------------------------------- |
226+
| Case | Behavior |
227+
| -------------------------------- | ------------------------------------------------------------------ |
228228
| Same name as a configured server | The client's server replaces the configured one in that directory. |
229-
| [Policies](/policies) | `integration.use` rules still apply. |
229+
| [Policies](/policies) | `integration.use` rules still apply. |
230230

231231
```json
232232
{ "type": "http", "name": "docs", "url": "https://mcp.example.com", "headers": [] }
@@ -335,6 +335,22 @@ session. Each update carries `_meta["opencode/child-session"]`. OpenCode prefixe
335335
Permission requests from a child session carry the same key on `toolCall._meta`. After the prompt ends, OpenCode stops
336336
sending child session updates. Permission requests and questions from child sessions still reach the client.
337337

338+
### Plugin activation readiness
339+
340+
If Location plugins are still activating after the bounded catalog wait, `session/new`, `session/load`, and
341+
`session/resume` return this error. Clients can retry the same request later; a failed resume does not delete the session.
342+
343+
```json
344+
{
345+
"code": -32603,
346+
"message": "Internal error: Location plugins are still activating; retry this request",
347+
"data": { "errorName": "CatalogNotReady", "service": "plugin", "retryable": true }
348+
}
349+
```
350+
351+
Check the error data rather than the message text. Other service failures do not carry this activation retry marker.
352+
Closing the ACP connection cancels its pending catalog wait.
353+
338354
### Retry status
339355

340356
When a model call fails and OpenCode schedules a retry, it sends `session_info_update` with `_meta["opencode/retry"]`.

0 commit comments

Comments
 (0)