From 813eaf5c28a86654161552c911ecb733a86b9cc2 Mon Sep 17 00:00:00 2001 From: Aiden Cline Date: Sun, 15 Nov 2026 14:31:40 -0600 Subject: [PATCH 1/2] feat(server): report plugin readiness on plugin.list --- packages/client/src/effect/api/api.ts | 6 +- .../client/src/promise/generated/types.ts | 2 +- packages/core/src/plugin.ts | 19 ++++-- packages/core/src/plugin/host.ts | 7 +- packages/core/src/plugin/service.ts | 4 ++ packages/core/test/plugin.test.ts | 3 +- packages/protocol/openapi.json | 12 +++- packages/protocol/src/groups/plugin.ts | 13 +++- packages/server/src/handlers/plugin.ts | 4 +- packages/server/test/plugin-ready.test.ts | 68 +++++++++++++++++++ 10 files changed, 125 insertions(+), 13 deletions(-) create mode 100644 packages/server/test/plugin-ready.test.ts diff --git a/packages/client/src/effect/api/api.ts b/packages/client/src/effect/api/api.ts index f65ec052c2b3..f494cfb42be3 100644 --- a/packages/client/src/effect/api/api.ts +++ b/packages/client/src/effect/api/api.ts @@ -99,7 +99,11 @@ export interface AgentApi { } export type PluginListInput = { readonly location?: { readonly directory?: string | undefined } | undefined } -export type PluginListOutput = { readonly location: Location.PublicRef; readonly data: ReadonlyArray } +export type PluginListOutput = { + readonly location: Location.PublicRef + readonly ready?: boolean | undefined + readonly data: ReadonlyArray +} export type PluginListOperation = (input?: PluginListInput) => Effect.Effect export type PluginGuiInput = { diff --git a/packages/client/src/promise/generated/types.ts b/packages/client/src/promise/generated/types.ts index fc8133fb489c..3779257d7dbb 100644 --- a/packages/client/src/promise/generated/types.ts +++ b/packages/client/src/promise/generated/types.ts @@ -3333,7 +3333,7 @@ export type AgentGetOutput = { location: LocationPublicRef; data: AgentInfo } export type PluginListInput = { readonly location?: { readonly directory?: string | undefined } | undefined } -export type PluginListOutput = { location: LocationPublicRef; data: Array } +export type PluginListOutput = { location: LocationPublicRef; ready?: boolean | null; data: Array } export type PluginGuiInput = { readonly location?: { readonly directory?: string | undefined } | undefined diff --git a/packages/core/src/plugin.ts b/packages/core/src/plugin.ts index d6b11356ed18..83d67e1f2015 100644 --- a/packages/core/src/plugin.ts +++ b/packages/core/src/plugin.ts @@ -27,16 +27,26 @@ const layer = Layer.effect( const ready = yield* Latch.make(true) const pending = new Set() let closed = false + // `plugin.list` reports readiness, so its flips are announced like inventory changes. + const announce = bus.publish(Plugin.Event.Updated, {}).pipe(Effect.asVoid) const holdUnsafe = () => { if (closed) return Effect.void const token = {} pending.add(token) ready.closeUnsafe() - return Effect.sync(() => { - if (pending.delete(token) && pending.size === 0) ready.openUnsafe() + return Effect.suspend(() => { + if (!pending.delete(token) || pending.size > 0) return Effect.void + ready.openUnsafe() + return announce }) } - const hold = () => Effect.sync(holdUnsafe) + const isReady = Effect.sync(() => pending.size === 0) + const hold = () => + Effect.suspend(() => { + const settled = pending.size === 0 + const release = holdUnsafe() + return settled && !closed ? announce.pipe(Effect.as(release)) : Effect.succeed(release) + }) const pendingFailures = yield* Queue.unbounded() let discovered: readonly Failure[] = [] let inventory: Plugin.Info[] = [] @@ -76,7 +86,7 @@ const layer = Layer.effect( release: holdUnsafe(), }) }) - const host = yield* PluginHost.make({ list }, plugin.id).pipe(Effect.provideContext(hostContext)) + const host = yield* PluginHost.make({ list, ready: isReady }, plugin.id).pipe(Effect.provideContext(hostContext)) const exit = yield* Effect.suspend(() => plugin.effect(host)).pipe( grouped, inherit, @@ -269,6 +279,7 @@ const layer = Layer.effect( activate, close, awaitActivation: ready.await, + ready: isReady, hold, list, gui, diff --git a/packages/core/src/plugin/host.ts b/packages/core/src/plugin/host.ts index 19a163d9aee0..5893eefce51b 100644 --- a/packages/core/src/plugin/host.ts +++ b/packages/core/src/plugin/host.ts @@ -50,7 +50,7 @@ const isRpcType = (type: string): type is RpcEvent["type"] => type.startsWith("r const isRpcEvent = (event: Event.Payload): event is RpcEvent => isRpcType(event.type) const isPublicEvent = (event: Event.Payload): event is EventManifest.ServerEvent | RpcEvent => EventManifest.isServer(event) || isRpcEvent(event) -export const make = Effect.fn("PluginHost.make")(function* (plugin: Pick, pluginID: string) { +export const make = Effect.fn("PluginHost.make")(function* (plugin: Pick, pluginID: string) { const app = yield* App.Service const agents = yield* Agent.Service const artifacts = yield* Artifact.Service @@ -466,7 +466,10 @@ export const make = Effect.fn("PluginHost.make")(function* (plugin: Pick response(plugin.list()), + list: () => + Effect.all([response(plugin.list()), plugin.ready]).pipe( + Effect.map(([listed, ready]) => ({ ...listed, ready })), + ), }, reference: { list: () => response(reference.list()), diff --git a/packages/core/src/plugin/service.ts b/packages/core/src/plugin/service.ts index d647969c8ab3..0f31a474e21b 100644 --- a/packages/core/src/plugin/service.ts +++ b/packages/core/src/plugin/service.ts @@ -14,6 +14,10 @@ export interface Interface { readonly close: (exit: Exit.Exit) => Effect.Effect /** Wait for announced updates and activation to settle; failures remain in the inventory. */ readonly awaitActivation: Effect.Effect + /** + * Whether activation has settled right now, without waiting. `plugin.updated` is published whenever it flips. + */ + readonly ready: Effect.Effect /** Keep readiness pending while preparing an update. Run the returned Effect to release it. */ readonly hold: () => Effect.Effect> } diff --git a/packages/core/test/plugin.test.ts b/packages/core/test/plugin.test.ts index e4731c8bc7da..393b9fa7478c 100644 --- a/packages/core/test/plugin.test.ts +++ b/packages/core/test/plugin.test.ts @@ -163,7 +163,8 @@ it.live("serves a local plugin's GUI bundle, and reloads it alone when only the expect(edited.revision).toBe(first.revision) expect((yield* plugins.gui(id))?.revision).not.toBe(served?.revision) - expect(updates.length).toBe(published + 1) + // The new bundle, plus readiness flipping to false and back to true around the activation. + expect(updates.length).toBe(published + 3) expect(yield* Effect.promise(() => Bun.file(starts).text())).toBe("x") }).pipe(Effect.scoped), ) diff --git a/packages/protocol/openapi.json b/packages/protocol/openapi.json index 8a95ff085ceb..7f7034c0253c 100644 --- a/packages/protocol/openapi.json +++ b/packages/protocol/openapi.json @@ -493,6 +493,16 @@ "location": { "$ref": "#/components/schemas/Location.PublicRef" }, + "ready": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "null" + } + ] + }, "data": { "type": "array", "items": { @@ -537,7 +547,7 @@ } } }, - "description": "Retrieve enabled server plugins and their current status.", + "description": "Retrieve enabled server plugins and their current status. `ready` is false while the location's plugins are still loading, so lists such as models, agents and skills may be partial; `plugin.updated` is published whenever it flips.", "summary": "List plugins" } }, diff --git a/packages/protocol/src/groups/plugin.ts b/packages/protocol/src/groups/plugin.ts index 3245b3438475..94d23c2ae06c 100644 --- a/packages/protocol/src/groups/plugin.ts +++ b/packages/protocol/src/groups/plugin.ts @@ -9,14 +9,23 @@ export const PluginGroup = HttpApiGroup.make("server.plugin") .add( HttpApiEndpoint.get("plugin.list", "/api/plugin", { query: LocationQuery, - success: Location.response(Schema.Array(Plugin.Info)), + success: Schema.Struct({ + location: Location.PublicRef, + /** + * False while the location's plugins are still loading; lists such as models and agents may be partial. Servers + * from before this field omit it. + */ + ready: Schema.optional(Schema.Boolean), + data: Schema.Array(Plugin.Info), + }), }) .annotateMerge(locationQueryOpenApi) .annotateMerge( OpenApi.annotations({ identifier: "plugin.list", summary: "List plugins", - description: "Retrieve enabled server plugins and their current status.", + description: + "Retrieve enabled server plugins and their current status. `ready` is false while the location's plugins are still loading, so lists such as models, agents and skills may be partial; `plugin.updated` is published whenever it flips.", }), ), ) diff --git a/packages/server/src/handlers/plugin.ts b/packages/server/src/handlers/plugin.ts index c083faa100a3..d878e98c8226 100644 --- a/packages/server/src/handlers/plugin.ts +++ b/packages/server/src/handlers/plugin.ts @@ -10,7 +10,9 @@ export const PluginHandler = HttpApiBuilder.group(Api, "server.plugin", (handler handlers .handle("plugin.list", () => Effect.gen(function* () { - return yield* response(Plugin.Service.use((plugin) => plugin.list())) + const plugins = yield* Plugin.Service + const ready = yield* plugins.ready + return { ...(yield* response(plugins.list())), ready } }), ) .handle("plugin.gui", (ctx) => diff --git a/packages/server/test/plugin-ready.test.ts b/packages/server/test/plugin-ready.test.ts new file mode 100644 index 000000000000..9a49e662fb6a --- /dev/null +++ b/packages/server/test/plugin-ready.test.ts @@ -0,0 +1,68 @@ +import { expect } from "bun:test" +import { Bus } from "@opencode/core/bus" +import { SdkPlugins } from "@opencode/core/plugin/sdk" +import { Plugin as PluginSchema } from "@opencode/schema/plugin" +import { Plugin } from "@opencode/plugin/effect" +import { Context, Deferred, Effect, Fiber, Layer, Stream } from "effect" +import { HttpEffect, HttpRouter, HttpServer } from "effect/http" +import { tmpdirScoped } from "../../core/test/fixture/tmpdir" +import { it } from "../../core/test/lib/effect" +import { createRoutes } from "../src/routes" + +it.live( + "plugin.list reports readiness without waiting and plugin.updated announces when it flips", + () => + Effect.gen(function* () { + const tmp = yield* tmpdirScoped("opencode-plugin-ready-") + const started = yield* Deferred.make() + const release = yield* Deferred.make() + const context = yield* Layer.build( + createRoutes({ + password: "secret", + database: { path: ":memory:" }, + models: { fetch: false }, + fs: { filewatcher: false }, + config: { directory: tmp.path, project: false }, + }).pipe(Layer.provide(HttpServer.layerServices)), + ) + yield* Context.get(context, SdkPlugins.Service).register( + Plugin.define({ + id: "slow-plugin", + effect: () => + Effect.gen(function* () { + yield* Deferred.succeed(started, undefined) + yield* Deferred.await(release) + }), + }), + ) + const handler = Context.get(context, HttpRouter.HttpRouter) + .asHttpEffect() + .pipe(HttpEffect.toWebHandlerWith(context)) + const ready = Effect.promise(async () => { + const url = new URL("/api/plugin", "http://opencode.local") + url.searchParams.set("location[directory]", tmp.path) + const response = await handler( + new Request(url, { headers: { authorization: `Basic ${btoa("opencode:secret")}` } }), + ) + return ((await response.json()) as { ready: boolean }).ready + }) + + expect(yield* ready.pipe(Effect.timeout("2 seconds"))).toBe(false) + yield* Deferred.await(started) + expect(yield* ready.pipe(Effect.timeout("2 seconds"))).toBe(false) + + // A client re-reads plugin.list on each plugin.updated, so the last one must come after it turns true. + const settled = yield* Context.get(context, Bus.Service) + .subscribe([PluginSchema.Event.Updated]) + .pipe( + Stream.mapEffect(() => ready), + Stream.takeUntil((value) => value), + Stream.runDrain, + Effect.forkScoped({ startImmediately: true }), + ) + yield* Deferred.succeed(release, undefined) + yield* Fiber.join(settled).pipe(Effect.timeout("5 seconds")) + expect(yield* ready).toBe(true) + }), + 15_000, +) From 9eb97fe67928240df18efb3d8f611346516849df Mon Sep 17 00:00:00 2001 From: Aiden Cline Date: Tue, 17 Nov 2026 11:36:31 -0600 Subject: [PATCH 2/2] fix(core): isolate plugin readiness announcements --- .../client/src/promise/generated/types.ts | 2 +- packages/core/src/plugin.ts | 31 ++++++++++++++----- packages/core/src/plugin/host.ts | 5 +-- packages/core/src/plugin/supervisor.ts | 7 ++++- packages/core/test/plugin.test.ts | 27 ++++++++++++++++ packages/protocol/openapi.json | 9 +----- packages/protocol/src/groups/plugin.ts | 3 +- 7 files changed, 64 insertions(+), 20 deletions(-) diff --git a/packages/client/src/promise/generated/types.ts b/packages/client/src/promise/generated/types.ts index 3779257d7dbb..bfc59f657058 100644 --- a/packages/client/src/promise/generated/types.ts +++ b/packages/client/src/promise/generated/types.ts @@ -3333,7 +3333,7 @@ export type AgentGetOutput = { location: LocationPublicRef; data: AgentInfo } export type PluginListInput = { readonly location?: { readonly directory?: string | undefined } | undefined } -export type PluginListOutput = { location: LocationPublicRef; ready?: boolean | null; data: Array } +export type PluginListOutput = { location: LocationPublicRef; ready?: boolean; data: Array } export type PluginGuiInput = { readonly location?: { readonly directory?: string | undefined } | undefined diff --git a/packages/core/src/plugin.ts b/packages/core/src/plugin.ts index 83d67e1f2015..7d0ba1c0eb44 100644 --- a/packages/core/src/plugin.ts +++ b/packages/core/src/plugin.ts @@ -9,6 +9,7 @@ import { LayerNode } from "@opencode/util/effect/layer-node" import type { PersistentPty } from "./persistent-pty.js" import { Cause, Context, Effect, Exit, Latch, Layer, Logger, Queue, References, Scope, Semaphore } from "effect" import { Bus } from "./bus.js" +import { Location } from "./location.js" import { PluginHost } from "./plugin/host.js" import { type Failure, type Generation, Service } from "./plugin/service.js" import { State } from "./state.js" @@ -19,6 +20,7 @@ const layer = Layer.effect( Service, Effect.gen(function* () { const bus = yield* Bus.Service + const location = yield* Location.Service const scope = yield* Scope.make() // One slot per requested definition in activation order, including ones whose setup failed, so // the prefix diff below stays index-aligned and a failed revision is not retried until it changes. @@ -27,8 +29,21 @@ const layer = Layer.effect( const ready = yield* Latch.make(true) const pending = new Set() let closed = false - // `plugin.list` reports readiness, so its flips are announced like inventory changes. - const announce = bus.publish(Plugin.Event.Updated, {}).pipe(Effect.asVoid) + // `plugin.list` reports readiness, so its flips are announced like inventory changes. A failing listener must not + // keep a hold pending or end the worker that releases one. + const announce = bus + .publish( + Plugin.Event.Updated, + {}, + { location: { directory: location.directory, workspaceID: location.workspaceID } }, + ) + .pipe( + Effect.asVoid, + Effect.catchCauseIf( + (cause) => !Cause.hasInterrupts(cause), + (cause) => Effect.logError("failed to announce plugin readiness", { cause }), + ), + ) const holdUnsafe = () => { if (closed) return Effect.void const token = {} @@ -42,11 +57,13 @@ const layer = Layer.effect( } const isReady = Effect.sync(() => pending.size === 0) const hold = () => - Effect.suspend(() => { - const settled = pending.size === 0 - const release = holdUnsafe() - return settled && !closed ? announce.pipe(Effect.as(release)) : Effect.succeed(release) - }) + Effect.uninterruptible( + Effect.suspend(() => { + const settled = pending.size === 0 + const release = holdUnsafe() + return settled && !closed ? announce.pipe(Effect.as(release)) : Effect.succeed(release) + }), + ) const pendingFailures = yield* Queue.unbounded() let discovered: readonly Failure[] = [] let inventory: Plugin.Info[] = [] diff --git a/packages/core/src/plugin/host.ts b/packages/core/src/plugin/host.ts index 5893eefce51b..8e08779e6840 100644 --- a/packages/core/src/plugin/host.ts +++ b/packages/core/src/plugin/host.ts @@ -467,8 +467,9 @@ export const make = Effect.fn("PluginHost.make")(function* (plugin: Pick - Effect.all([response(plugin.list()), plugin.ready]).pipe( - Effect.map(([listed, ready]) => ({ ...listed, ready })), + // Readiness first, so a list read after it is never older than a `true`. + Effect.all([plugin.ready, response(plugin.list())]).pipe( + Effect.map(([ready, listed]) => ({ ...listed, ready })), ), }, reference: { diff --git a/packages/core/src/plugin/supervisor.ts b/packages/core/src/plugin/supervisor.ts index c5f320e4c800..9dd418aebfd8 100644 --- a/packages/core/src/plugin/supervisor.ts +++ b/packages/core/src/plugin/supervisor.ts @@ -194,7 +194,12 @@ export const layer = Layer.effectDiscard( // Make accepted work visible to awaitActivation before coalescing the burst. const notify = Effect.gen(function* () { observed++ - if (!release) release = yield* registry.hold() + // Another source can take the hold while this one waits on it; keep one and give the extra back. + if (!release) { + const held = yield* registry.hold() + if (release) yield* held + else release = held + } yield* Queue.offer(triggers, observed) }) const watch = (stream: Stream.Stream) => diff --git a/packages/core/test/plugin.test.ts b/packages/core/test/plugin.test.ts index 393b9fa7478c..b91eb49ec0c6 100644 --- a/packages/core/test/plugin.test.ts +++ b/packages/core/test/plugin.test.ts @@ -92,6 +92,33 @@ it.effect("updates inventory metadata without restarting an unchanged generation }), ) +it.effect("reports readiness, announcing each flip, and overlapping holds flip it once", () => + Effect.gen(function* () { + const plugins = yield* Plugin.Service + const bus = yield* Bus.Service + const seen: boolean[] = [] + yield* Effect.acquireRelease( + bus.listen((event) => + event.type === Plugin.Event.Updated.type + ? plugins.ready.pipe(Effect.map((ready) => void seen.push(ready))) + : Effect.void, + ), + (unsubscribe) => unsubscribe, + ) + yield* plugins.awaitActivation + expect(yield* plugins.ready).toBe(true) + + const first = yield* plugins.hold() + const second = yield* plugins.hold() + expect(yield* plugins.ready).toBe(false) + yield* first + expect(yield* plugins.ready).toBe(false) + yield* second + expect(yield* plugins.ready).toBe(true) + expect(seen).toEqual([false, true]) + }), +) + it.live("loads a local plugin with its configured options", () => Effect.gen(function* () { const plugins = yield* Plugin.Service diff --git a/packages/protocol/openapi.json b/packages/protocol/openapi.json index 7f7034c0253c..acfbbcf40274 100644 --- a/packages/protocol/openapi.json +++ b/packages/protocol/openapi.json @@ -494,14 +494,7 @@ "$ref": "#/components/schemas/Location.PublicRef" }, "ready": { - "anyOf": [ - { - "type": "boolean" - }, - { - "type": "null" - } - ] + "type": "boolean" }, "data": { "type": "array", diff --git a/packages/protocol/src/groups/plugin.ts b/packages/protocol/src/groups/plugin.ts index 94d23c2ae06c..f12332beba63 100644 --- a/packages/protocol/src/groups/plugin.ts +++ b/packages/protocol/src/groups/plugin.ts @@ -1,5 +1,6 @@ import { Location } from "@opencode/schema/location" import { Plugin } from "@opencode/schema/plugin" +import { optional } from "@opencode/schema/schema" import { Schema } from "effect" import { HttpApiEndpoint, HttpApiGroup, HttpApiSchema, OpenApi } from "effect/http-api" import { InvalidRequestError, PluginNotFoundError, ServiceUnavailableError } from "../errors.js" @@ -15,7 +16,7 @@ export const PluginGroup = HttpApiGroup.make("server.plugin") * False while the location's plugins are still loading; lists such as models and agents may be partial. Servers * from before this field omit it. */ - ready: Schema.optional(Schema.Boolean), + ready: optional(Schema.Boolean), data: Schema.Array(Plugin.Info), }), })