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: