From c06b1365d03610ef96cb4ae93f44b1ef6e64ed9c Mon Sep 17 00:00:00 2001 From: Amr Karam Date: Tue, 17 Nov 2026 11:46:51 +0200 Subject: [PATCH] fix(server): make plugin activation timeout configurable The wait for a cold Location'"'"'s plugins to activate is a fixed five seconds. Every --standalone call starts a private server, so each one pays that cold cost, and on Windows the measured failure latency was ~9s (issue #63273): the budget does not cover process spawn plus npm package resolution for package plugins. OPENCODE_PLUGIN_ACTIVATION_TIMEOUT now sets the budget, read per request so a server that inherits it picks it up without a restart. An unreadable or non-positive value keeps the five-second default. This revives the approach of #57917, which closed procedurally for missing the 72-hour guideline window. --- packages/server/src/handlers/generate.ts | 6 +- packages/server/src/handlers/model.ts | 4 +- packages/server/src/handlers/provider.ts | 2 +- packages/server/src/handlers/voice.ts | 4 +- packages/server/src/handlers/websearch.ts | 2 +- packages/server/src/location.ts | 55 +++++++++++++++---- .../test/plugin-activation-timeout.test.ts | 36 ++++++++++++ services/site/src/docs/content/cli/config.mdx | 16 ++++++ 8 files changed, 104 insertions(+), 21 deletions(-) create mode 100644 packages/server/test/plugin-activation-timeout.test.ts diff --git a/packages/server/src/handlers/generate.ts b/packages/server/src/handlers/generate.ts index 73b916fea9d7..0d184495f7a9 100644 --- a/packages/server/src/handlers/generate.ts +++ b/packages/server/src/handlers/generate.ts @@ -24,7 +24,7 @@ export const GenerateHandler = HttpApiBuilder.group(Api, "server.generate", (han const services = locations.get(Location.Ref.make({ directory: AbsolutePath.make(global.config) })) const text = Effect.fn("server.generate.text")( function* (request: { readonly payload: { readonly prompt: string; readonly model?: Model.Ref } }) { - yield* awaitPlugins + yield* awaitPlugins() const generate = yield* Generate.Service return { data: { text: yield* generate.text(request.payload).pipe(Effect.mapError(generateError)) } } }, @@ -33,7 +33,7 @@ export const GenerateHandler = HttpApiBuilder.group(Api, "server.generate", (han ) const image = Effect.fn("server.generate.image")( function* (request: { readonly payload: ImageRequest }) { - yield* awaitPlugins + yield* awaitPlugins() const generate = yield* Generate.Service return { data: yield* generate.image(request.payload).pipe(Effect.mapError(generateError)) } }, @@ -48,7 +48,7 @@ export const GenerateHandler = HttpApiBuilder.group(Api, "server.generate", (han message: "Decision question names must be unique", field: "questions", }) - yield* awaitPlugins + yield* awaitPlugins() const generate = yield* Generate.Service return { data: yield* generate.decisions(request.payload).pipe(Effect.mapError(generateError)) } }, diff --git a/packages/server/src/handlers/model.ts b/packages/server/src/handlers/model.ts index eb5517449947..61bed7a58197 100644 --- a/packages/server/src/handlers/model.ts +++ b/packages/server/src/handlers/model.ts @@ -10,7 +10,7 @@ export const ModelHandler = HttpApiBuilder.group(Api, "server.model", (handlers) .handle( "model.list", Effect.fn(function* (ctx) { - yield* awaitPlugins + yield* awaitPlugins() const models = yield* Model.Service return yield* response(models.available(ctx.query.types)) }), @@ -18,7 +18,7 @@ export const ModelHandler = HttpApiBuilder.group(Api, "server.model", (handlers) .handle( "model.default", Effect.fn(function* () { - yield* awaitPlugins + yield* awaitPlugins() const models = yield* Model.Service return yield* response(models.default()) }), diff --git a/packages/server/src/handlers/provider.ts b/packages/server/src/handlers/provider.ts index 3b0bdf4a4956..3acbe70b2c58 100644 --- a/packages/server/src/handlers/provider.ts +++ b/packages/server/src/handlers/provider.ts @@ -11,7 +11,7 @@ export const ProviderHandler = HttpApiBuilder.group(Api, "server.provider", (han .handle( "provider.list", Effect.fn(function* () { - yield* awaitPlugins + yield* awaitPlugins() const providers = yield* Provider.Service return yield* response(providers.available()) }), diff --git a/packages/server/src/handlers/voice.ts b/packages/server/src/handlers/voice.ts index f9507a98c335..5f548c683e29 100644 --- a/packages/server/src/handlers/voice.ts +++ b/packages/server/src/handlers/voice.ts @@ -19,7 +19,7 @@ export const VoiceHandler = HttpApiBuilder.group(Api, "server.voice", (handlers) "voice.models", Effect.fn("server.voice.models")( function* () { - yield* awaitPlugins + yield* awaitPlugins() const voice = yield* Voice.Service return { data: yield* voice.models() } }, @@ -31,7 +31,7 @@ export const VoiceHandler = HttpApiBuilder.group(Api, "server.voice", (handlers) "voice.session", Effect.fn("server.voice.session")( function* (request) { - yield* awaitPlugins + yield* awaitPlugins() const voice = yield* Voice.Service const transport = yield* voice .session(request.payload) diff --git a/packages/server/src/handlers/websearch.ts b/packages/server/src/handlers/websearch.ts index 853e223d54b0..9c46bf1ec549 100644 --- a/packages/server/src/handlers/websearch.ts +++ b/packages/server/src/handlers/websearch.ts @@ -19,7 +19,7 @@ export const WebSearchHandler = HttpApiBuilder.group(Api, "server.websearch", (h "websearch.query", Effect.fn("server.websearch.query")(function* (request) { // A cold Location must finish activating plugins before their providers can be resolved. - yield* awaitPlugins + yield* awaitPlugins() const websearch = yield* WebSearch.Service return yield* response( websearch.query(request.payload).pipe( diff --git a/packages/server/src/location.ts b/packages/server/src/location.ts index 25fecc82f52c..69c4980d9abb 100644 --- a/packages/server/src/location.ts +++ b/packages/server/src/location.ts @@ -36,18 +36,49 @@ export function locationErrors(effect: Effect.Effect) { // Temporary: managed policy is applied by the last internal plugin, and State shows each registration as soon as it is // made, so until activation finishes a provider the policy denies is still listed and usable. Only the endpoints that // list or use providers wait. Remove once a plugin batch becomes visible only when it ends. -export const awaitPlugins = Plugin.awaitActivation.pipe( - Effect.timeoutOrElse({ - duration: "5 seconds", - orElse: () => - Effect.fail( - new ServiceUnavailableError({ - message: "Location plugins did not finish activating", - service: "plugin", - }), - ), - }), -) + +const DEFAULT_PLUGIN_ACTIVATION_TIMEOUT_MS = 5_000 + +const DURATION_UNITS: Record = { + ms: 1, + millisecond: 1, + milliseconds: 1, + s: 1_000, + sec: 1_000, + secs: 1_000, + second: 1_000, + seconds: 1_000, + m: 60_000, + min: 60_000, + mins: 60_000, + minute: 60_000, + minutes: 60_000, +} + +export function pluginActivationTimeoutMs() { + const raw = process.env.OPENCODE_PLUGIN_ACTIVATION_TIMEOUT + if (!raw) return DEFAULT_PLUGIN_ACTIVATION_TIMEOUT_MS + const match = /^\s*(\d+(?:\.\d+)?)\s*([a-z]+)?\s*$/i.exec(raw) + const scale = DURATION_UNITS[(match?.[2] ?? "ms").toLowerCase()] + const value = match && scale !== undefined ? Number(match[1]) * scale : undefined + // An unreadable or non-positive value keeps the default rather than failing every request. + return value !== undefined && Number.isFinite(value) && value > 0 ? value : DEFAULT_PLUGIN_ACTIVATION_TIMEOUT_MS +} + +// Read per request so a server that inherits the variable from its parent picks it up without a restart. +export const awaitPlugins = () => + Plugin.awaitActivation.pipe( + Effect.timeoutOrElse({ + duration: pluginActivationTimeoutMs(), + orElse: () => + Effect.fail( + new ServiceUnavailableError({ + message: "Location plugins did not finish activating", + service: "plugin", + }), + ), + }), + ) export function response(data: Effect.Effect) { return Effect.gen(function* () { diff --git a/packages/server/test/plugin-activation-timeout.test.ts b/packages/server/test/plugin-activation-timeout.test.ts new file mode 100644 index 000000000000..ee06d1c43f4f --- /dev/null +++ b/packages/server/test/plugin-activation-timeout.test.ts @@ -0,0 +1,36 @@ +import { afterEach, describe, expect, it } from "bun:test" +import { pluginActivationTimeoutMs } from "../src/location" + +const VARIABLE = "OPENCODE_PLUGIN_ACTIVATION_TIMEOUT" +const original = process.env[VARIABLE] + +afterEach(() => { + if (original === undefined) delete process.env[VARIABLE] + else process.env[VARIABLE] = original +}) + +describe("pluginActivationTimeoutMs", () => { + it("defaults to five seconds when the variable is unset", () => { + delete process.env[VARIABLE] + expect(pluginActivationTimeoutMs()).toBe(5_000) + }) + + it.each([ + ["30 seconds", 30_000], + ["10s", 10_000], + ["500ms", 500], + ["2 minutes", 120_000], + ["750", 750], + ] as const)("parses %p as milliseconds", (raw, expected) => { + process.env[VARIABLE] = raw + expect(pluginActivationTimeoutMs()).toBe(expected) + }) + + it.each([["soon"], ["0 seconds"], ["-5 seconds"], ["5 fortune cookies"]] as const)( + "keeps the default for the unreadable value %p", + (raw) => { + process.env[VARIABLE] = raw + expect(pluginActivationTimeoutMs()).toBe(5_000) + }, + ) +}) \ No newline at end of file diff --git a/services/site/src/docs/content/cli/config.mdx b/services/site/src/docs/content/cli/config.mdx index cf21a6aef5f8..b44e95ba484b 100644 --- a/services/site/src/docs/content/cli/config.mdx +++ b/services/site/src/docs/content/cli/config.mdx @@ -47,6 +47,22 @@ OPENCODE_CLI_CONFIG_CONTENT='{"tabs":{"mode":"off"}}' opencode OpenCode merges the inline settings over the global `cli.json`. Nested objects are merged, while arrays and scalar values from the environment replace global values. Inline settings remain authoritative while the variable is set. +## Plugin activation timeout + +Endpoints that need the model catalog wait for a location's plugins to activate, and answer `503` when activation +exceeds the budget. A `--standalone` call starts a private server, so every call pays the cold activation cost, and +slow plugin setups can exceed the default budget of five seconds. + +Set `OPENCODE_PLUGIN_ACTIVATION_TIMEOUT` to raise the budget: + +```sh +OPENCODE_PLUGIN_ACTIVATION_TIMEOUT="30 seconds" opencode serve +``` + +The value is a duration such as `500ms`, `10 seconds`, or `2 minutes`; a bare number counts as milliseconds. The +variable is read per request, so a server that inherits it picks it up without a restart. An unreadable or +non-positive value keeps the five-second default. + ## Appearance Choose a theme, control interface motion, and override the terminal cursor: