Skip to content

feat(server): report plugin readiness on plugin.list - #64029

Merged
rekram1-node merged 2 commits into
devfrom
plugin-ready
Nov 17, 2026
Merged

rekram1-node merged 2 commits into
devfrom
plugin-ready

Conversation

@rekram1-node

@rekram1-node rekram1-node commented Nov 15, 2026 •

Copy link
Copy Markdown
Collaborator

Issue for this PR

Follow-up to #62796. Implements the readiness part of Kit's proposal in the #core thread on async plugins.

Type of change

  • Bug fix
  • New feature
  • Refactor / code improvement
  • Documentation

What does this PR do?

The server never waits for plugins, so catalog reads can be partial on a cold Location, and clients couldn't tell when loading was done. plugin.list now says so, and plugin.updated fires when it changes:

GET /api/plugin → { location, ready: false, data: [...] }   still loading
                  { location, ready: true,  data: [...] }   settled
plugin.updated  → also fires when ready flips

Clients already re-read plugin.list on plugin.updated, so one read tells them both what's loaded and whether that's everything.

  • ready is the signal Plugin.awaitActivation waits on (no holds pending), read without waiting. It covers the whole activation, including npm installs and later reloads.
  • It's optional in the schema: servers from before it omit it, so a new client still decodes their plugin.list.
  • Plugins see the same ready through ctx.plugin.list().
  • A failing plugin.updated listener is logged and can't leave a hold pending.
  • Each activation now publishes two more plugin.updated events (ready flipping to false and back). Listeners only re-read plugin.list, which is in memory, and the plugin supervisor doesn't react to it, so there's no reload loop.

Not in this PR, from the same proposal: a client helper that waits for ready, and flipping ready to false before config and credential changes respond.

How did you verify your code works?

  • New server test: with a plugin stuck in activation, plugin.list reports ready: false; once it finishes, re-reading plugin.list on each plugin.updated ends at ready: true. It fails without the announcement when activation settles.
  • New core test: overlapping holds flip ready to false once and back to true once, announcing each flip.
  • packages/core plugin tests (630), packages/server (128), packages/cli (399), packages/client (262), packages/sdk (40), packages/protocol (14), packages/plugin (37) and packages/tui (1,675) pass. bun run check, check:generated, and typecheck:tsc for core, server, client, protocol and cli pass.

Checklist

  • I have tested my changes locally
  • I have not included unrelated changes in this PR

Added by the opencode bot (AI-generated).

Related: #63221

Public API: adds optional ready to plugin.list (HTTP, SDK, plugin ctx); plugin.updated also fires when readiness flips (backwards compatible)

@opencodejr opencodejr Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I found no blocking problems. The new endpoint works as described. On a live opencode serve, a cold Location returned ready: false and then ready: true within a few seconds, and opencode models --server … gave the same output as the base. The new server test, the core plugin tests and typecheck:tsc for core, server, cli and client all pass. The CLI suite has 5 server/service lifecycle failures, and the base has the same 5.

The settle announcement fires only when the last hold is released and not after close. The supervisor doesn't re-activate on plugin.updated, so the extra event can't cause a reload loop. The existing listeners in the TUI, desktop app and app only re-read the plugin list.

Public API (all additive and backwards compatible):

  • New GET /api/experimental/plugin/ready (operation experimental.plugin.ready).
  • New SDK method client.experimental.plugin.ready() with types ExperimentalPluginReadyInput and ExperimentalPluginReadyOutput. The code generator also adds client.plugin.ready and the PluginReady* types, already marked deprecated.
  • New ready on the core Plugin.Interface.
  • plugin.updated now fires once more each time an activation settles.

One inline note: when the CLI talks to an older server, it no longer waits for plugins at all.

Related: #63221

// reports its plugins have finished loading, npm installs included.
export const waitForPlugins = (client: OpenCodeClient, directory: string) =>
Effect.tryPromise((signal) => client.plugin.list({ location: { directory } }, { signal })).pipe(
Effect.tryPromise((signal) => client.experimental.plugin.ready({ location: { directory } }, { signal })).pipe(

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Against a server that doesn't have this endpoint yet (for example an older server passed with --server), this call gets a 404. Effect.repeat stops on that error and Effect.ignore swallows it, so models, debug agents and auth don't wait at all. Before, they waited for a non-empty plugin list. Falling back to the old plugin.list check when ready fails would keep that case working.

@opencodejr opencodejr Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My earlier point is addressed: if the readiness route fails, waitForPlugins now falls back to waiting for a non-empty plugin.list. I pointed this PR's CLI at a base server, where the route returns 404, and models --server … printed the full model list on a cold location. Against this PR's server, the route returned ready: false and then true. The route now lives in server.experimental, so the deprecated client.plugin.ready alias is gone. The server, client and core tests I ran pass, typecheck:tsc passes for server, cli, client and protocol, and check:generated is clean.

Public API (all additions, all backwards compatible):

  • GET /api/experimental/plugin/ready
  • client.experimental.plugin.ready()
  • ready on the core Plugin.Interface
  • one more plugin.updated event each time plugin loading settles

I found nothing new that needs changing.

@opencodejr opencodejr Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The new commit puts waitForPlugins back to the base version, so the CLI no longer calls the readiness route and the problem with older servers from my earlier comment no longer applies. I checked that packages/cli now has no diff from the base, the server readiness test passes, and typecheck:tsc passes for the CLI.

Public API (all additions, all backwards compatible):

  • GET /api/experimental/plugin/ready
  • client.experimental.plugin.ready()
  • ready on the core Plugin.Interface
  • one more plugin.updated event each time plugin loading settles

The CLI's behaviour is unchanged. I have no new concerns.

@rekram1-node rekram1-node changed the title feat(server): report whether a location's plugins have finished loading feat(server): report plugin readiness on plugin.list Nov 15, 2026

@opencodejr opencodejr Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Moving readiness onto plugin.list works as described, and I have no blocking concerns. My earlier point about older servers no longer applies, because this version doesn't touch the CLI.

On a live serve, GET /api/plugin on a cold location returned ready: false with an empty list, then ready: true with the full list. The base CLI's models --server … against this server printed the full list, so older clients still read the new response. The server handler reads ready before the list, so a response can't combine a partial list with ready: true. The server, core plugin and packages/plugin tests pass, typecheck:tsc passes for core, server, client, protocol, plugin and cli, and check:generated is clean.

Public API (backwards compatible):

  • GET /api/plugin (plugin.list) gains an optional ready field, in the OpenAPI spec and in the SDK's PluginListOutput. Servers from before this change leave it out.
  • Plugins see the same ready through ctx.plugin.list().
  • plugin.updated now also fires when readiness flips, which adds two events per activation.
  • The core Plugin.Interface gains ready.
  • The experimental /api/experimental/plugin/ready route from the earlier version is gone.

@opencodejr opencodejr Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The new commits look sound and I have no new concerns. A failing plugin.updated listener is now logged and can't leave a hold pending. The supervisor gives back the extra hold when two sources ask for one at the same time. ctx.plugin.list() for plugins now reads ready before the list, matching the HTTP handler. ready is now an optional boolean with no null option.

On a live serve, GET /api/plugin on a cold location returned ready: false and then true. The core plugin tests (630, including the new overlapping-holds test) and the server readiness test pass, typecheck:tsc passes for core, server, client, protocol and plugin, and check:generated is clean.

Public API (same as my last review, backwards compatible):

  • GET /api/plugin (plugin.list) gains an optional boolean ready, in the HTTP API, the SDK and ctx.plugin.list().
  • plugin.updated also fires when readiness flips.
  • The core Plugin.Interface gains ready.

@rekram1-node
rekram1-node merged commit 133f24a into dev Nov 17, 2026
13 checks passed
@rekram1-node
rekram1-node deleted the plugin-ready branch November 17, 2026 20:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant