feat(plugin): add session options hook

fix(ai): parse compatible reasoning deltas (#37558 )
Co-authored-by: Aiden Cline <63023139+rekram1-node@users.noreply.github.com>
2026-10-21 20:50:09 +08:00 · 2026-07-18 17:00:43 +00:00 · 2026-07-18 10:57:10 -05:00 · 2026-07-18 13:24:47 +00:00 · 2026-07-17 23:22:09 -05:00 · 2026-07-17 22:56:52 -05:00
51 changed files with 1560 additions and 275 deletions
@@ -1,6 +1,6 @@
 # LLM Provider Parity Status

-Last reviewed: 2026-07-16
+Last reviewed: 2026-07-17

 This file tracks the gap between the native `@opencode-ai/ai` package and the AI SDK provider packages that opencode still depends on for many catalog/runtime paths.

@@ -20,7 +20,7 @@ This file tracks the gap between the native `@opencode-ai/ai` package and the AI
 | OpenAI Responses WebSocket         | `src/protocols/openai-responses.ts`, `src/route/transport/websocket.ts`                        | Present as `OpenAI.responsesWebSocket(...)`.                                                                                                                             | Runner/catalog support explicitly must not downgrade WebSocket routes; broader runtime selection is not complete.                                                                                                                                         |
 | OpenAI-compatible Chat             | `src/protocols/openai-compatible-chat.ts`, `src/providers/openai-compatible.ts`                | Usable for generic Chat and several profiles: Baseten, Cerebras, DeepInfra, DeepSeek, Fireworks, Groq, TogetherAI.                                                       | Family quirks are mostly endpoint defaults, not full typed behavior.                                                                                                                                                                                      |
 | OpenAI-compatible Responses        | `src/protocols/openai-compatible-responses.ts`, `src/providers/openai-compatible-responses.ts` | Usable for deployments that implement the OpenAI Responses wire protocol.                                                                                                | No named family profiles or recorded deployment coverage yet.                                                                                                                                                                                             |
-| Anthropic-compatible Messages      | `src/protocols/anthropic-messages.ts`, `src/providers/anthropic-compatible.ts`                 | Usable for deployments that implement the Anthropic Messages wire protocol. Named Anthropic composes this base.                                                          | No named compatible family profiles or recorded deployment coverage yet.                                                                                                                                                                                  |
+| Anthropic-compatible Messages      | `src/protocols/anthropic-messages.ts`, `src/providers/anthropic-compatible.ts`                 | Usable for deployments that implement the Anthropic Messages wire protocol. Named Anthropic composes this base; MiniMax M3 has recorded text and tool-loop coverage.       | No named compatible family profiles yet.                                                                                                                                                                                                                  |
 | Anthropic Messages                 | `src/protocols/anthropic-messages.ts`, `src/providers/anthropic.ts`                            | Usable. Supports tools, thinking, cache control, images, server-hosted tool events, and usage.                                                                           | Provider option surface is small. Beta/header handling, metadata, and newer Messages fields need a typed parity pass.                                                                                                                                     |
 | Gemini Developer API               | `src/protocols/gemini.ts`, `src/providers/google.ts`                                           | Usable for Google API key flow. Supports text, images, tools, thinking signatures, and cache usage.                                                                      | This is not Vertex. Typed provider options are narrow; many Gemini request fields currently require raw `http.body` overlays.                                                                                                                             |
 | Vertex Gemini                      | `src/protocols/gemini.ts`, `src/providers/google-vertex.ts`                                    | Usable through API-key express mode, explicit OAuth tokens, or ADC with project/location endpoint derivation, including tuned `endpoints/...` deployments.               | Core runner/catalog mapping and recorded provider coverage are missing.                                                                                                                                                                                   |
@@ -161,6 +161,18 @@ const PROVIDERS: ReadonlyArray<Provider> = [
    vars: [{ name: "TOGETHER_AI_API_KEY" }],
    validate: (env) => validateBearer("https://api.together.xyz/v1/models", Redacted.make(env.TOGETHER_AI_API_KEY)),
  },
+  {
+    id: "minimax",
+    label: "MiniMax",
+    tier: "compatible",
+    note: "Anthropic-compatible Messages text/tool recorded tests",
+    vars: [{ name: "MINIMAX_API_KEY" }],
+    validate: (env) =>
+      HttpClientRequest.get("https://api.minimax.io/anthropic/v1/models").pipe(
+        HttpClientRequest.setHeader("x-api-key", Redacted.value(Redacted.make(env.MINIMAX_API_KEY))),
+        executeRequest,
+      ),
+  },
  {
    id: "mistral",
    label: "Mistral",
@@ -75,6 +75,8 @@ const OpenAIChatMessage = Schema.Union([
    content: Schema.NullOr(Schema.String),
    tool_calls: optionalArray(OpenAIChatAssistantToolCall),
    reasoning_content: Schema.optional(Schema.String),
+    reasoning: Schema.optional(Schema.String),
+    reasoning_text: Schema.optional(Schema.String),
  }),
  Schema.Struct({ role: Schema.Literal("tool"), tool_call_id: Schema.String, content: Schema.String }),
 ]).pipe(Schema.toTaggedUnion("role"))
@@ -145,6 +147,8 @@ type OpenAIChatToolCallDelta = Schema.Schema.Type<typeof OpenAIChatToolCallDelta
 const OpenAIChatDelta = Schema.Struct({
  content: optionalNull(Schema.String),
  reasoning_content: optionalNull(Schema.String),
+  reasoning: optionalNull(Schema.String),
+  reasoning_text: optionalNull(Schema.String),
  tool_calls: optionalNull(Schema.Array(OpenAIChatToolCallDelta)),
 })

@@ -166,6 +170,7 @@ export interface ParserState {
  readonly usage?: Usage
  readonly finishReason?: FinishReason
  readonly lifecycle: Lifecycle.State
+  readonly reasoningField?: "reasoning" | "reasoning_content" | "reasoning_text"
 }

 // =============================================================================
@@ -208,6 +213,12 @@ const lowerMedia = Effect.fn("OpenAIChat.lowerMedia")(function* (part: MediaPart
 const openAICompatibleReasoningContent = (native: unknown) =>
  isRecord(native) && typeof native.reasoning_content === "string" ? native.reasoning_content : undefined

+const reasoningField = (part: ReasoningPart) => {
+  const field = part.providerMetadata?.openai?.reasoningField
+  if (field === "reasoning" || field === "reasoning_content" || field === "reasoning_text") return field
+  return "reasoning_content"
+}
+
 const lowerUserMessage = Effect.fn("OpenAIChat.lowerUserMessage")(function* (message: OpenAIChatRequestMessage) {
  const content: Array<Schema.Schema.Type<typeof OpenAIChatUserContent>> = []
  for (const part of message.content) {
@@ -248,14 +259,20 @@ const lowerAssistantMessage = Effect.fn("OpenAIChat.lowerAssistantMessage")(func
      continue
    }
  }
+  const text = reasoning.map((part) => part.text).join("")
+  const field = reasoning[0] ? reasoningField(reasoning[0]) : "reasoning_content"
  return {
    role: "assistant" as const,
    content: content.length === 0 ? null : ProviderShared.joinText(content),
    tool_calls: toolCalls.length === 0 ? undefined : toolCalls,
    reasoning_content:
-      reasoning.length > 0
-        ? reasoning.map((part) => part.text).join("")
-        : openAICompatibleReasoningContent(message.native?.openaiCompatible),
+      reasoning.length === 0
+        ? openAICompatibleReasoningContent(message.native?.openaiCompatible)
+        : field === "reasoning_content"
+          ? text
+          : undefined,
+    reasoning: reasoning.length > 0 && field === "reasoning" ? text : undefined,
+    reasoning_text: reasoning.length > 0 && field === "reasoning_text" ? text : undefined,
  }
 })

@@ -400,6 +417,12 @@ const mapUsage = (usage: OpenAIChatEvent["usage"]): Usage | undefined => {
  })
 }

+const reasoningDelta = (delta: Schema.Schema.Type<typeof OpenAIChatDelta> | null | undefined) => {
+  if (delta?.reasoning_content) return { field: "reasoning_content", text: delta.reasoning_content } as const
+  if (delta?.reasoning) return { field: "reasoning", text: delta.reasoning } as const
+  if (delta?.reasoning_text) return { field: "reasoning_text", text: delta.reasoning_text } as const
+}
+
 const step = (state: ParserState, event: OpenAIChatEvent) =>
  Effect.gen(function* () {
    const events: LLMEvent[] = []
@@ -412,8 +435,12 @@ const step = (state: ParserState, event: OpenAIChatEvent) =>

    let lifecycle = state.lifecycle

-    if (delta?.reasoning_content)
-      lifecycle = Lifecycle.reasoningDelta(lifecycle, events, "reasoning-0", delta.reasoning_content)
+    const reasoning = reasoningDelta(delta)
+    const reasoningField = state.reasoningField ?? reasoning?.field
+    if (reasoning)
+      lifecycle = Lifecycle.reasoningDelta(lifecycle, events, "reasoning-0", reasoning.text, {
+        openai: { reasoningField: reasoningField ?? reasoning.field },
+      })

    if (delta?.content) {
      lifecycle = Lifecycle.reasoningEnd(lifecycle, events, "reasoning-0")
@@ -450,6 +477,7 @@ const step = (state: ParserState, event: OpenAIChatEvent) =>
        usage,
        finishReason,
        lifecycle,
+        reasoningField,
      },
      events,
    ] as const
@@ -482,7 +510,12 @@ export const protocol = Protocol.make({
  },
  stream: {
    event: Protocol.jsonEvent(OpenAIChatEvent),
-    initial: () => ({ tools: ToolStream.empty<number>(), toolCallEvents: [], lifecycle: Lifecycle.initial() }),
+    initial: () => ({
+      tools: ToolStream.empty<number>(),
+      toolCallEvents: [],
+      lifecycle: Lifecycle.initial(),
+      reasoningField: undefined,
+    }),
    step,
    onHalt: finishEvents,
  },
@@ -155,8 +155,11 @@ export interface Interface {
  readonly prepare: <Body = unknown>(request: LLMRequest) => Effect.Effect<PreparedRequestOf<Body>, LLMError>
  readonly stream: StreamMethod
  readonly generate: GenerateMethod
+  readonly withOptionsTransform: (transform: OptionsTransform) => Interface
 }

+export type OptionsTransform = (request: LLMRequest) => Effect.Effect<LLMRequest, LLMError>
+
 export interface StreamMethod {
  (request: LLMRequest): Stream.Stream<LLMEvent, LLMError>
 }
@@ -373,43 +376,59 @@ export function make<Body, Prepared, Frame, Event, State>(
 // `compile` is the important boundary: it turns a common `LLMRequest` into a
 // validated provider body plus transport-private prepared data, but does not
 // execute transport.
-const compile = Effect.fn("LLM.compile")(function* (request: LLMRequest) {
-  const resolved = applyCachePolicy(resolveRequestOptions(request))
-  const route = resolved.model.route
+const compileWith = (transform?: OptionsTransform) =>
+  Effect.fn("LLM.compile")(function* (request: LLMRequest) {
+    const options = resolveRequestOptions(request)
+    const resolved = applyCachePolicy(transform ? yield* transform(options) : options)
+    const route = resolved.model.route

-  const body = yield* route.body
-    .from(resolved)
-    .pipe(Effect.flatMap(ProviderShared.validateWith(Schema.decodeUnknownEffect(route.body.schema))))
-  const prepared = yield* route.prepareTransport(body, resolved)
+    const body = yield* route.body
+      .from(resolved)
+      .pipe(Effect.flatMap(ProviderShared.validateWith(Schema.decodeUnknownEffect(route.body.schema))))
+    const prepared = yield* route.prepareTransport(body, resolved)

-  return {
-    request: resolved,
-    route,
-    body,
-    prepared,
-  }
-})
-
-const prepareWith = Effect.fn("LLMClient.prepare")(function* (request: LLMRequest) {
-  const compiled = yield* compile(request)
-
-  return new PreparedRequest({
-    id: compiled.request.id ?? "request",
-    route: compiled.route.id,
-    protocol: compiled.route.protocol,
-    model: compiled.request.model,
-    body: compiled.body,
-    metadata: { transport: compiled.route.transport.id },
+    return {
+      request: resolved,
+      route,
+      body,
+      prepared,
+    }
  })
-})

-const streamRequestWith = (runtime: TransportRuntime) => (request: LLMRequest) =>
-  Stream.unwrap(
-    Effect.gen(function* () {
-      const compiled = yield* compile(request)
-      return compiled.route.streamPrepared(compiled.prepared, compiled.request, runtime)
-    }),
-  )
+const prepareWith = (compile: ReturnType<typeof compileWith>) =>
+  Effect.fn("LLMClient.prepare")(function* (request: LLMRequest) {
+    const compiled = yield* compile(request)
+
+    return new PreparedRequest({
+      id: compiled.request.id ?? "request",
+      route: compiled.route.id,
+      protocol: compiled.route.protocol,
+      model: compiled.request.model,
+      body: compiled.body,
+      metadata: { transport: compiled.route.transport.id },
+    })
+  })
+
+const streamRequestWith =
+  (runtime: TransportRuntime, compile: ReturnType<typeof compileWith>) => (request: LLMRequest) =>
+    Stream.unwrap(
+      Effect.gen(function* () {
+        const compiled = yield* compile(request)
+        return compiled.route.streamPrepared(compiled.prepared, compiled.request, runtime)
+      }),
+    )
+
+const makeClient = (runtime: TransportRuntime, transform?: OptionsTransform): Interface => {
+  const compile = compileWith(transform)
+  const stream = streamRequestWith(runtime, compile)
+  return {
+    prepare: prepareWith(compile) as Interface["prepare"],
+    stream,
+    generate: generateWith(stream),
+    withOptionsTransform: (next) =>
+      makeClient(runtime, transform ? (request) => transform(request).pipe(Effect.flatMap(next)) : next),
+  }
+}

 const generateWith = (stream: Interface["stream"]) =>
  Effect.fn("LLM.generate")(function* (request: LLMRequest) {
@@ -423,7 +442,7 @@ const generateWith = (stream: Interface["stream"]) =>
  })

 export const prepare = <Body = unknown>(request: LLMRequest) =>
-  prepareWith(request) as Effect.Effect<PreparedRequestOf<Body>, LLMError>
+  prepareWith(compileWith())(request) as Effect.Effect<PreparedRequestOf<Body>, LLMError>

 export function stream(request: LLMRequest): Stream.Stream<LLMEvent, LLMError> {
  return Stream.unwrap(
@@ -449,11 +468,12 @@ export const streamRequest = (request: LLMRequest) =>
 export const layer: Layer.Layer<Service, never, RequestExecutor.Service> = Layer.effect(
  Service,
  Effect.gen(function* () {
-    const stream = streamRequestWith({
-      http: yield* RequestExecutor.Service,
-      webSocket: Option.getOrUndefined(yield* Effect.serviceOption(WebSocketExecutor.Service)),
-    })
-    return Service.of({ prepare: prepareWith as Interface["prepare"], stream, generate: generateWith(stream) })
+    return Service.of(
+      makeClient({
+        http: yield* RequestExecutor.Service,
+        webSocket: Option.getOrUndefined(yield* Effect.serviceOption(WebSocketExecutor.Service)),
+      }),
+    )
  }),
 )

@@ -7,6 +7,7 @@ export type {
  RouteDefaultsInput,
  AnyRoute,
  Interface as LLMClientShape,
+  OptionsTransform,
  Service as LLMClientService,
 } from "./client"
 export * from "./executor"
@@ -0,0 +1,40 @@
+{
+  "version": 1,
+  "metadata": {
+    "provider": "minimax",
+    "protocol": "anthropic-messages",
+    "route": "anthropic-messages",
+    "transport": "http",
+    "model": "MiniMax-M3",
+    "tags": [
+      "prefix:anthropic-compatible-messages",
+      "provider:minimax",
+      "protocol:anthropic-messages",
+      "text",
+      "golden"
+    ],
+    "name": "anthropic-compatible-messages/minimax-m3-anthropic-compatible-text",
+    "recordedAt": "2026-07-18T03:42:22.893Z"
+  },
+  "interactions": [
+    {
+      "transport": "http",
+      "request": {
+        "method": "POST",
+        "url": "https://api.minimax.io/anthropic/v1/messages",
+        "headers": {
+          "anthropic-version": "2023-06-01",
+          "content-type": "application/json"
+        },
+        "body": "{\"model\":\"MiniMax-M3\",\"system\":[{\"type\":\"text\",\"text\":\"You are concise.\"}],\"messages\":[{\"role\":\"user\",\"content\":[{\"type\":\"text\",\"text\":\"Reply exactly with: Hello!\"}]}],\"stream\":true,\"max_tokens\":40,\"temperature\":0}"
+      },
+      "response": {
+        "status": 200,
+        "headers": {
+          "content-type": "text/event-stream; charset=utf-8"
+        },
+        "body": "event: message_start\ndata: {\"type\":\"message_start\",\"message\":{\"id\":\"1a0b363d0882af316faebcec4d4855a8\",\"type\":\"message\",\"role\":\"assistant\",\"content\":[],\"model\":\"MiniMax-M3\",\"stop_reason\":null,\"stop_sequence\":null,\"usage\":{\"input_tokens\":53,\"output_tokens\":0,\"cache_creation_input_tokens\":0,\"cache_read_input_tokens\":114,\"service_tier\":\"standard\"},\"service_tier\":\"standard\"}}\n\nevent: ping\ndata: {\"type\":\"ping\"}\n\nevent: content_block_start\ndata: {\"type\":\"content_block_start\",\"index\":0,\"content_block\":{\"type\":\"text\",\"text\":\"\"}}\n\nevent: content_block_delta\ndata: {\"type\":\"content_block_delta\",\"index\":0,\"delta\":{\"type\":\"text_delta\",\"text\":\"Hello\"}}\n\nevent: content_block_delta\ndata: {\"type\":\"content_block_delta\",\"index\":0,\"delta\":{\"type\":\"text_delta\",\"text\":\"!\"}}\n\nevent: content_block_stop\ndata: {\"type\":\"content_block_stop\",\"index\":0}\n\nevent: message_delta\ndata: {\"type\":\"message_delta\",\"delta\":{\"stop_reason\":\"end_turn\"},\"usage\":{\"input_tokens\":53,\"output_tokens\":2,\"cache_read_input_tokens\":114,\"service_tier\":\"standard\"}}\n\nevent: message_stop\ndata: {\"type\":\"message_stop\"}\n\n"
+      }
+    }
+  ]
+}
@@ -0,0 +1,41 @@
+{
+  "version": 1,
+  "metadata": {
+    "provider": "minimax",
+    "protocol": "anthropic-messages",
+    "route": "anthropic-messages",
+    "transport": "http",
+    "model": "MiniMax-M3",
+    "tags": [
+      "prefix:anthropic-compatible-messages",
+      "provider:minimax",
+      "protocol:anthropic-messages",
+      "tool",
+      "tool-call",
+      "golden"
+    ],
+    "name": "anthropic-compatible-messages/minimax-m3-anthropic-compatible-tool-call",
+    "recordedAt": "2026-07-18T03:42:23.876Z"
+  },
+  "interactions": [
+    {
+      "transport": "http",
+      "request": {
+        "method": "POST",
+        "url": "https://api.minimax.io/anthropic/v1/messages",
+        "headers": {
+          "anthropic-version": "2023-06-01",
+          "content-type": "application/json"
+        },
+        "body": "{\"model\":\"MiniMax-M3\",\"system\":[{\"type\":\"text\",\"text\":\"Call tools exactly as requested.\"}],\"messages\":[{\"role\":\"user\",\"content\":[{\"type\":\"text\",\"text\":\"Call get_weather with city exactly Paris.\"}]}],\"tools\":[{\"name\":\"get_weather\",\"description\":\"Get current weather for a city.\",\"input_schema\":{\"type\":\"object\",\"properties\":{\"city\":{\"type\":\"string\"}},\"required\":[\"city\"],\"additionalProperties\":false}}],\"tool_choice\":{\"type\":\"tool\",\"name\":\"get_weather\"},\"stream\":true,\"max_tokens\":80,\"temperature\":0}"
+      },
+      "response": {
+        "status": 200,
+        "headers": {
+          "content-type": "text/event-stream; charset=utf-8"
+        },
+        "body": "event: message_start\ndata: {\"type\":\"message_start\",\"message\":{\"id\":\"6731ecc323233459d1792df9a733dd98\",\"type\":\"message\",\"role\":\"assistant\",\"content\":[],\"model\":\"MiniMax-M3\",\"stop_reason\":null,\"stop_sequence\":null,\"usage\":{\"input_tokens\":0,\"output_tokens\":0,\"cache_creation_input_tokens\":0,\"cache_read_input_tokens\":404,\"service_tier\":\"standard\"},\"service_tier\":\"standard\"}}\n\nevent: ping\ndata: {\"type\":\"ping\"}\n\nevent: content_block_start\ndata: {\"type\":\"content_block_start\",\"index\":0,\"content_block\":{\"type\":\"tool_use\",\"id\":\"call_function_vkxtif4epmvm_1\",\"name\":\"get_weather\",\"input\":{}}}\n\nevent: content_block_delta\ndata: {\"type\":\"content_block_delta\",\"index\":0,\"delta\":{\"type\":\"input_json_delta\",\"partial_json\":\"{\\\"city\\\": \\\"Paris\"}}\n\nevent: content_block_delta\ndata: {\"type\":\"content_block_delta\",\"index\":0,\"delta\":{\"type\":\"input_json_delta\",\"partial_json\":\"\\\"}\"}}\n\nevent: content_block_stop\ndata: {\"type\":\"content_block_stop\",\"index\":0}\n\nevent: message_delta\ndata: {\"type\":\"message_delta\",\"delta\":{\"stop_reason\":\"tool_use\"},\"usage\":{\"input_tokens\":290,\"output_tokens\":27,\"cache_read_input_tokens\":114,\"service_tier\":\"standard\"}}\n\nevent: message_stop\ndata: {\"type\":\"message_stop\"}\n\n"
+      }
+    }
+  ]
+}
@@ -0,0 +1,60 @@
+{
+  "version": 1,
+  "metadata": {
+    "provider": "minimax",
+    "protocol": "anthropic-messages",
+    "route": "anthropic-messages",
+    "transport": "http",
+    "model": "MiniMax-M3",
+    "tags": [
+      "prefix:anthropic-compatible-messages",
+      "provider:minimax",
+      "protocol:anthropic-messages",
+      "tool",
+      "tool-loop",
+      "golden"
+    ],
+    "name": "anthropic-compatible-messages/minimax-m3-anthropic-compatible-tool-loop",
+    "recordedAt": "2026-07-18T03:42:25.248Z"
+  },
+  "interactions": [
+    {
+      "transport": "http",
+      "request": {
+        "method": "POST",
+        "url": "https://api.minimax.io/anthropic/v1/messages",
+        "headers": {
+          "anthropic-version": "2023-06-01",
+          "content-type": "application/json"
+        },
+        "body": "{\"model\":\"MiniMax-M3\",\"system\":[{\"type\":\"text\",\"text\":\"Use the get_weather tool exactly once. After the tool result, reply exactly: Paris is sunny.\"}],\"messages\":[{\"role\":\"user\",\"content\":[{\"type\":\"text\",\"text\":\"What is the weather in Paris?\"}]}],\"tools\":[{\"name\":\"get_weather\",\"description\":\"Get current weather for a city.\",\"input_schema\":{\"type\":\"object\",\"properties\":{\"city\":{\"type\":\"string\"}},\"required\":[\"city\"],\"additionalProperties\":false}}],\"stream\":true,\"max_tokens\":80,\"temperature\":0}"
+      },
+      "response": {
+        "status": 200,
+        "headers": {
+          "content-type": "text/event-stream; charset=utf-8"
+        },
+        "body": "event: message_start\ndata: {\"type\":\"message_start\",\"message\":{\"id\":\"3807fa12f9ecb9357df511e099da6da0\",\"type\":\"message\",\"role\":\"assistant\",\"content\":[],\"model\":\"MiniMax-M3\",\"stop_reason\":null,\"stop_sequence\":null,\"usage\":{\"input_tokens\":0,\"output_tokens\":0,\"cache_creation_input_tokens\":0,\"cache_read_input_tokens\":417,\"service_tier\":\"standard\"},\"service_tier\":\"standard\"}}\n\nevent: ping\ndata: {\"type\":\"ping\"}\n\nevent: content_block_start\ndata: {\"type\":\"content_block_start\",\"index\":0,\"content_block\":{\"type\":\"tool_use\",\"id\":\"call_function_yr64rwmre4gr_1\",\"name\":\"get_weather\",\"input\":{}}}\n\nevent: content_block_delta\ndata: {\"type\":\"content_block_delta\",\"index\":0,\"delta\":{\"type\":\"input_json_delta\",\"partial_json\":\"{\\\"city\\\": \\\"Paris\"}}\n\nevent: content_block_delta\ndata: {\"type\":\"content_block_delta\",\"index\":0,\"delta\":{\"type\":\"input_json_delta\",\"partial_json\":\"\\\"}\"}}\n\nevent: content_block_stop\ndata: {\"type\":\"content_block_stop\",\"index\":0}\n\nevent: message_delta\ndata: {\"type\":\"message_delta\",\"delta\":{\"stop_reason\":\"tool_use\"},\"usage\":{\"input_tokens\":303,\"output_tokens\":27,\"cache_read_input_tokens\":114,\"service_tier\":\"standard\"}}\n\nevent: message_stop\ndata: {\"type\":\"message_stop\"}\n\n"
+      }
+    },
+    {
+      "transport": "http",
+      "request": {
+        "method": "POST",
+        "url": "https://api.minimax.io/anthropic/v1/messages",
+        "headers": {
+          "anthropic-version": "2023-06-01",
+          "content-type": "application/json"
+        },
+        "body": "{\"model\":\"MiniMax-M3\",\"system\":[{\"type\":\"text\",\"text\":\"Use the get_weather tool exactly once. After the tool result, reply exactly: Paris is sunny.\"}],\"messages\":[{\"role\":\"user\",\"content\":[{\"type\":\"text\",\"text\":\"What is the weather in Paris?\"}]},{\"role\":\"assistant\",\"content\":[{\"type\":\"tool_use\",\"id\":\"call_function_yr64rwmre4gr_1\",\"name\":\"get_weather\",\"input\":{\"city\":\"Paris\"}}]},{\"role\":\"user\",\"content\":[{\"type\":\"tool_result\",\"tool_use_id\":\"call_function_yr64rwmre4gr_1\",\"content\":\"{\\\"temperature\\\":22,\\\"condition\\\":\\\"sunny\\\"}\"}]}],\"tools\":[{\"name\":\"get_weather\",\"description\":\"Get current weather for a city.\",\"input_schema\":{\"type\":\"object\",\"properties\":{\"city\":{\"type\":\"string\"}},\"required\":[\"city\"],\"additionalProperties\":false}}],\"stream\":true,\"max_tokens\":80,\"temperature\":0}"
+      },
+      "response": {
+        "status": 200,
+        "headers": {
+          "content-type": "text/event-stream; charset=utf-8"
+        },
+        "body": "event: message_start\ndata: {\"type\":\"message_start\",\"message\":{\"id\":\"92f8a1e86f29946eb2699d40a088fc08\",\"type\":\"message\",\"role\":\"assistant\",\"content\":[],\"model\":\"MiniMax-M3\",\"stop_reason\":null,\"stop_sequence\":null,\"usage\":{\"input_tokens\":41,\"output_tokens\":0,\"cache_creation_input_tokens\":0,\"cache_read_input_tokens\":430,\"service_tier\":\"standard\"},\"service_tier\":\"standard\"}}\n\nevent: ping\ndata: {\"type\":\"ping\"}\n\nevent: content_block_start\ndata: {\"type\":\"content_block_start\",\"index\":0,\"content_block\":{\"type\":\"text\",\"text\":\"\"}}\n\nevent: content_block_delta\ndata: {\"type\":\"content_block_delta\",\"index\":0,\"delta\":{\"type\":\"text_delta\",\"text\":\"Paris\"}}\n\nevent: content_block_delta\ndata: {\"type\":\"content_block_delta\",\"index\":0,\"delta\":{\"type\":\"text_delta\",\"text\":\" is sunny.\"}}\n\nevent: content_block_stop\ndata: {\"type\":\"content_block_stop\",\"index\":0}\n\nevent: message_delta\ndata: {\"type\":\"message_delta\",\"delta\":{\"stop_reason\":\"end_turn\"},\"usage\":{\"input_tokens\":41,\"output_tokens\":4,\"cache_read_input_tokens\":430,\"service_tier\":\"standard\"}}\n\nevent: message_stop\ndata: {\"type\":\"message_stop\"}\n\n"
+      }
+    }
+  ]
+}
@@ -0,0 +1,34 @@
+{
+  "version": 1,
+  "metadata": {
+    "model": "anthropic/claude-sonnet-4.6",
+    "tags": [
+      "prefix:openai-compatible-chat",
+      "provider:openrouter",
+      "protocol:openai-chat",
+      "reasoning"
+    ],
+    "name": "openrouter-reasoning",
+    "recordedAt": "2026-07-18T11:28:39.267Z"
+  },
+  "interactions": [
+    {
+      "transport": "http",
+      "request": {
+        "method": "POST",
+        "url": "https://openrouter.ai/api/v1/chat/completions",
+        "headers": {
+          "content-type": "application/json"
+        },
+        "body": "{\"model\":\"anthropic/claude-sonnet-4.6\",\"messages\":[{\"role\":\"system\",\"content\":\"Think through the arithmetic, then reply with only the final integer.\"},{\"role\":\"user\",\"content\":\"What is 173 multiplied by 219?\"}],\"stream\":true,\"stream_options\":{\"include_usage\":true},\"max_tokens\":1536,\"temperature\":0,\"reasoning\":{\"max_tokens\":1024}}"
+      },
+      "response": {
+        "status": 200,
+        "headers": {
+          "content-type": "text/event-stream"
+        },
+        "body": ": OPENROUTER PROCESSING\n\n: OPENROUTER PROCESSING\n\ndata: {\"id\":\"gen-1784374117-AXXPsQRoclZeQGx2uHeK\",\"object\":\"chat.completion.chunk\",\"created\":1784374117,\"model\":\"anthropic/claude-sonnet-4.6\",\"provider\":\"Anthropic\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"\",\"role\":\"assistant\",\"reasoning\":\"173\",\"reasoning_details\":[{\"type\":\"reasoning.text\",\"text\":\"173\",\"format\":\"anthropic-claude-v1\",\"index\":0}]},\"finish_reason\":null,\"native_finish_reason\":null}]}\n\n: OPENROUTER PROCESSING\n\ndata: {\"id\":\"gen-1784374117-AXXPsQRoclZeQGx2uHeK\",\"object\":\"chat.completion.chunk\",\"created\":1784374117,\"model\":\"anthropic/claude-sonnet-4.6\",\"provider\":\"Anthropic\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"\",\"role\":\"assistant\",\"reasoning\":\" × 219\\n\\n173 × 200 = 34,600\\n173 × 19 = 173 × 20 - 173 = 3,460 - 173 = 3,287\",\"reasoning_details\":[{\"type\":\"reasoning.text\",\"text\":\" × 219\\n\\n173 × 200 = 34,600\\n173 × 19 = 173 × 20 - 173 = 3,460 - 173 = 3,287\",\"format\":\"anthropic-claude-v1\",\"index\":0}]},\"finish_reason\":null,\"native_finish_reason\":null}]}\n\ndata: {\"id\":\"gen-1784374117-AXXPsQRoclZeQGx2uHeK\",\"object\":\"chat.completion.chunk\",\"created\":1784374117,\"model\":\"anthropic/claude-sonnet-4.6\",\"provider\":\"Anthropic\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"\",\"role\":\"assistant\",\"reasoning\":\"\\n\\n34,600 + 3,287 = 37,887\",\"reasoning_details\":[{\"type\":\"reasoning.text\",\"text\":\"\\n\\n34,600 + 3,287 = 37,887\",\"format\":\"anthropic-claude-v1\",\"index\":0}]},\"finish_reason\":null,\"native_finish_reason\":null}]}\n\ndata: {\"id\":\"gen-1784374117-AXXPsQRoclZeQGx2uHeK\",\"object\":\"chat.completion.chunk\",\"created\":1784374117,\"model\":\"anthropic/claude-sonnet-4.6\",\"provider\":\"Anthropic\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"\",\"role\":\"assistant\",\"reasoning_details\":[{\"type\":\"reasoning.text\",\"signature\":\"EtgCCosBCA8YAipA0W4viH3kgBs43Cl5ewwVBPXTQElvzfbA2TLF4iSbKy9ZZDCSDjjAlF3Bs4ELEnP3vrrTuTioC6OB380lXQdyIDIRY2xhdWRlLXNvbm5ldC00LTY4AEIIdGhpbmtpbmdaJDRjMGYwNDZmLTI1ZmQtNDVmYi1iZmIzLWEwOGE4ZTI0OWNhNxIMMiUlJC3x/5p5PuTwGgwlc8eipZyoM94BHwMiMO45uQx/ymeOjbugi7RDVPZ4jZXSIiEbVi2CD7zPjAK5fFQoVGP1HD55v9CER823JCp6Dg5Xb7Lrk6NUd1XN2KTKrttK7mATE+IBrDTFmor/1cNeg+9gjIbxM/jn/6L5HPmh3/esEVu24Q0IGLZVoE7cTgGgxsrceKMD71Jp2XQgIWD8ltsPfWw3gSc4p+z18UuPN6LuR0mHHENTnClHrAPnOrxbDIl4ZwZgMX8YAQ==\",\"format\":\"anthropic-claude-v1\",\"index\":0}]},\"finish_reason\":null,\"native_finish_reason\":null}]}\n\ndata: {\"id\":\"gen-1784374117-AXXPsQRoclZeQGx2uHeK\",\"object\":\"chat.completion.chunk\",\"created\":1784374117,\"model\":\"anthropic/claude-sonnet-4.6\",\"provider\":\"Anthropic\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"37887\",\"role\":\"assistant\"},\"finish_reason\":null,\"native_finish_reason\":null}]}\n\ndata: {\"id\":\"gen-1784374117-AXXPsQRoclZeQGx2uHeK\",\"object\":\"chat.completion.chunk\",\"created\":1784374117,\"model\":\"anthropic/claude-sonnet-4.6\",\"provider\":\"Anthropic\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"\",\"role\":\"assistant\",\"reasoning\":null},\"finish_reason\":\"stop\",\"native_finish_reason\":\"end_turn\"}]}\n\ndata: {\"id\":\"gen-1784374117-AXXPsQRoclZeQGx2uHeK\",\"object\":\"chat.completion.chunk\",\"created\":1784374117,\"model\":\"anthropic/claude-sonnet-4.6\",\"provider\":\"Anthropic\",\"service_tier\":\"default\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"\",\"role\":\"assistant\"},\"finish_reason\":\"stop\",\"native_finish_reason\":\"end_turn\"}],\"usage\":{\"prompt_tokens\":61,\"completion_tokens\":80,\"total_tokens\":141,\"cost\":0.001383,\"is_byok\":false,\"prompt_tokens_details\":{\"cached_tokens\":0,\"cache_write_tokens\":0,\"audio_tokens\":0,\"video_tokens\":0},\"cache_creation\":{\"ephemeral_5m_input_tokens\":0,\"ephemeral_1h_input_tokens\":0},\"cost_details\":{\"upstream_inference_cost\":0.001383,\"upstream_inference_prompt_cost\":0.000183,\"upstream_inference_completions_cost\":0.0012},\"completion_tokens_details\":{\"reasoning_tokens\":29,\"image_tokens\":0,\"audio_tokens\":0}}}\n\ndata: [DONE]\n\n"
+      }
+    }
+  ]
+}
@@ -1,4 +1,5 @@
 import * as Anthropic from "../../src/providers/anthropic"
+import * as AnthropicCompatible from "../../src/providers/anthropic-compatible"
 import { CloudflareAIGateway, CloudflareWorkersAI } from "../../src/providers/cloudflare"
 import * as Google from "../../src/providers/google"
 import * as OpenAI from "../../src/providers/openai"
@@ -17,6 +18,11 @@ const anthropic = Anthropic.configure({
 })
 const anthropicHaiku = anthropic.model("claude-haiku-4-5-20251001")
 const anthropicOpus = anthropic.model("claude-opus-4-7")
+const minimax = AnthropicCompatible.configure({
+  apiKey: process.env.MINIMAX_API_KEY ?? "fixture",
+  baseURL: "https://api.minimax.io/anthropic/v1",
+  provider: "minimax",
+}).model("MiniMax-M3")
 const google = Google.configure({ apiKey: process.env.GOOGLE_GENERATIVE_AI_API_KEY ?? "fixture" })
 const gemini = google.model("gemini-2.5-flash")
 const xai = XAI.configure({ apiKey: process.env.XAI_API_KEY ?? "fixture" })
@@ -108,6 +114,15 @@ describeRecordedGoldenScenarios([
      { id: "image-tool-result", temperature: false, maxTokens: 40 },
    ],
  },
+  {
+    name: "MiniMax M3 Anthropic-compatible",
+    prefix: "anthropic-compatible-messages",
+    protocol: "anthropic-messages",
+    model: minimax,
+    requires: ["MINIMAX_API_KEY"],
+    options: { redact: { allowRequestHeaders: ["anthropic-version"] } },
+    scenarios: ["text", "tool-call", "tool-loop"],
+  },
  {
    name: "Gemini 2.5 Flash",
    prefix: "gemini",
@@ -0,0 +1,67 @@
+import { describe, expect } from "bun:test"
+import { Effect } from "effect"
+import { LLM, LLMEvent } from "../../src"
+import * as OpenAICompatible from "../../src/providers/openai-compatible"
+import * as OpenRouter from "../../src/providers/openrouter"
+import { LLMClient } from "../../src/route"
+import { recordedTests } from "../recorded-test"
+
+const cases = [
+  {
+    name: "OpenRouter",
+    model: OpenRouter.configure({
+      apiKey: process.env.OPENROUTER_API_KEY ?? "fixture",
+      providerOptions: { openrouter: { reasoning: { max_tokens: 1024 } } },
+    }).model("anthropic/claude-sonnet-4.6"),
+    requires: ["OPENROUTER_API_KEY"],
+    cassette: "openrouter-reasoning",
+  },
+  {
+    name: "Vercel AI Gateway",
+    model: OpenAICompatible.configure({
+      provider: "vercel-ai-gateway",
+      baseURL: "https://ai-gateway.vercel.sh/v1",
+      apiKey: process.env.AI_GATEWAY_API_KEY ?? "fixture",
+      http: { body: { reasoning: { enabled: true, max_tokens: 1024 } } },
+    }).model("anthropic/claude-sonnet-4.6"),
+    requires: ["AI_GATEWAY_API_KEY"],
+    cassette: "vercel-ai-gateway-reasoning",
+  },
+] as const
+
+for (const item of cases) {
+  const recorded = recordedTests({
+    prefix: "openai-compatible-chat",
+    provider: item.model.provider,
+    protocol: "openai-chat",
+    requires: item.requires,
+    tags: ["reasoning"],
+    metadata: { model: item.model.id },
+  })
+
+  describe(`${item.name} reasoning recorded`, () => {
+    recorded.effect.with(
+      "streams scalar reasoning",
+      { cassette: item.cassette },
+      () =>
+        Effect.gen(function* () {
+          const response = yield* LLMClient.generate(
+            LLM.request({
+              model: item.model,
+              system: "Think through the arithmetic, then reply with only the final integer.",
+              prompt: "What is 173 multiplied by 219?",
+              generation: { maxTokens: 1536, temperature: 0 },
+            }),
+          )
+
+          expect(response.text.replaceAll(",", "").trim()).toBe("37887")
+          expect(response.reasoning.length).toBeGreaterThan(0)
+          expect(response.events.some(LLMEvent.is.reasoningDelta)).toBe(true)
+          expect(response.message.content.find((part) => part.type === "reasoning")?.providerMetadata).toEqual({
+            openai: { reasoningField: "reasoning" },
+          })
+        }),
+      30_000,
+    )
+  })
+}
@@ -540,29 +540,33 @@ describe("OpenAI Chat route", () => {
    }),
  )

-  it.effect("parses OpenAI-compatible reasoning content deltas", () =>
+  it.effect("parses and replays OpenAI-compatible reasoning fields", () =>
    Effect.gen(function* () {
-      const body = sseEvents(
-        { choices: [{ delta: { reasoning_content: "thinking" } }] },
-        { choices: [{ delta: { content: "Hello" } }] },
-        { choices: [{ delta: {}, finish_reason: "stop" }] },
-      )
+      const fields = ["reasoning_content", "reasoning", "reasoning_text"] as const
+      for (const field of fields) {
+        const response = yield* LLMClient.generate(request).pipe(
+          Effect.provide(
+            fixedResponse(
+              sseEvents(
+                { choices: [{ delta: { [field]: "thinking" } }] },
+                { choices: [{ delta: { content: "Hello" } }] },
+                { choices: [{ delta: {}, finish_reason: "stop" }] },
+              ),
+            ),
+          ),
+        )

-      const response = yield* LLMClient.generate(request).pipe(Effect.provide(fixedResponse(body)))
+        expect(response.reasoning).toBe("thinking")
+        expect(response.text).toBe("Hello")
+        expect(response.message.content.find((part) => part.type === "reasoning")?.providerMetadata).toEqual({
+          openai: { reasoningField: field },
+        })

-      expect(response.reasoning).toBe("thinking")
-      expect(response.text).toBe("Hello")
-      expect(response.events).toMatchObject([
-        { type: "step-start", index: 0 },
-        { type: "reasoning-start", id: "reasoning-0" },
-        { type: "reasoning-delta", id: "reasoning-0", text: "thinking" },
-        { type: "reasoning-end", id: "reasoning-0" },
-        { type: "text-start", id: "text-0" },
-        { type: "text-delta", id: "text-0", text: "Hello" },
-        { type: "text-end", id: "text-0" },
-        { type: "step-finish", index: 0, reason: "stop" },
-        { type: "finish", reason: "stop" },
-      ])
+        const replay = yield* LLMClient.prepare<OpenAIChat.OpenAIChatBody>(
+          LLM.request({ model, messages: [response.message] }),
+        )
+        expect(replay.body.messages).toEqual([{ role: "assistant", content: "Hello", [field]: "thinking" }])
+      }
    }),
  )

@@ -690,4 +694,47 @@ describe("OpenAI Chat route", () => {
      expect(events.map((event) => event.type)).toEqual(["step-start"])
    }),
  )
+
+  it.effect("transforms resolved options before provider lowering", () =>
+    Effect.gen(function* () {
+      const llm = yield* LLMClient.Service
+      const resolvedModel = OpenAIChat.route
+        .with({
+          endpoint: { baseURL: "https://api.openai.test/v1/" },
+          auth: Auth.bearer("test"),
+          generation: { topP: 0.8 },
+        })
+        .model({ id: "gpt-4o-mini", defaults: { generation: { topK: 4 } } })
+      let seen: typeof request.generation
+      const transformed = LLM.request({
+        model: resolvedModel,
+        prompt: "Say hello.",
+        generation: { maxTokens: 20, temperature: 0.1 },
+      })
+
+      yield* llm
+        .withOptionsTransform((request) =>
+          Effect.sync(() => {
+            seen = request.generation
+            const generation = { ...request.generation, temperature: 0.7 }
+            delete generation.topP
+            return LLM.updateRequest(request, { generation })
+          }),
+        )
+        .stream(transformed)
+        .pipe(Stream.runDrain)
+
+      expect(seen).toMatchObject({ maxTokens: 20, temperature: 0.1, topP: 0.8, topK: 4 })
+    }).pipe(
+      Effect.provide(
+        dynamicResponse((input) => {
+          expect(JSON.parse(input.text)).toMatchObject({ max_tokens: 20, temperature: 0.7 })
+          expect(JSON.parse(input.text)).not.toHaveProperty("top_p")
+          return Effect.succeed(
+            input.respond(sseEvents(deltaChunk({}, "stop")), { headers: { "content-type": "text/event-stream" } }),
+          )
+        }),
+      ),
+    ),
+  )
 })
@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+
+import childProcess from "node:child_process"
+import fs from "node:fs"
+import os from "node:os"
+import path from "node:path"
+import { createRequire } from "node:module"
+import { fileURLToPath } from "node:url"
+
+const directory = path.dirname(fileURLToPath(import.meta.url))
+const require = createRequire(import.meta.url)
+const packageJson = JSON.parse(fs.readFileSync(path.join(directory, "package.json"), "utf8"))
+const command = Object.keys(packageJson.bin ?? {})[0]
+if (!command) throw new Error("OpenCode package does not declare a binary")
+
+const platform = { darwin: "darwin", linux: "linux", win32: "windows" }[os.platform()] ?? os.platform()
+const arch = { x64: "x64", arm64: "arm64", arm: "arm" }[os.arch()] ?? os.arch()
+const sourceBinary = platform === "windows" ? `${command}.exe` : command
+const targetBinary = path.resolve(directory, packageJson.bin[command])
+const dependencies = packageJson.optionalDependencies ?? {}
+const base = Object.keys(dependencies).find((name) => name.endsWith(`-${platform}-${arch}`))
+if (!base) throw new Error(`OpenCode does not provide a binary for ${platform}-${arch}`)
+
+function supportsAvx2() {
+  if (arch !== "x64") return false
+  if (platform === "linux") {
+    try {
+      return /(^|\s)avx2(\s|$)/i.test(fs.readFileSync("/proc/cpuinfo", "utf8"))
+    } catch {
+      return false
+    }
+  }
+  if (platform === "darwin") {
+    try {
+      const result = childProcess.spawnSync("sysctl", ["-n", "hw.optional.avx2_0"], {
+        encoding: "utf8",
+        timeout: 1500,
+      })
+      return result.status === 0 && (result.stdout || "").trim() === "1"
+    } catch {
+      return false
+    }
+  }
+  if (platform === "windows") {
+    const script =
+      '(Add-Type -MemberDefinition "[DllImport(""kernel32.dll"")] public static extern bool IsProcessorFeaturePresent(int ProcessorFeature);" -Name Kernel32 -Namespace Win32 -PassThru)::IsProcessorFeaturePresent(40)'
+    for (const executable of ["powershell.exe", "pwsh.exe", "pwsh", "powershell"]) {
+      try {
+        const result = childProcess.spawnSync(executable, ["-NoProfile", "-NonInteractive", "-Command", script], {
+          encoding: "utf8",
+          timeout: 3000,
+          windowsHide: true,
+        })
+        if (result.status !== 0) continue
+        const output = (result.stdout || "").trim().toLowerCase()
+        if (output === "true" || output === "1") return true
+        if (output === "false" || output === "0") return false
+      } catch {
+        continue
+      }
+    }
+  }
+  return false
+}
+
+function isMusl() {
+  if (platform !== "linux") return false
+  try {
+    if (fs.existsSync("/etc/alpine-release")) return true
+    const result = childProcess.spawnSync("ldd", ["--version"], { encoding: "utf8" })
+    return `${result.stdout || ""}${result.stderr || ""}`.toLowerCase().includes("musl")
+  } catch {
+    return false
+  }
+}
+
+function packageNames() {
+  const baseline = arch === "x64" && !supportsAvx2()
+  const names =
+    platform === "linux"
+      ? isMusl()
+        ? arch === "x64"
+          ? baseline
+            ? [`${base}-baseline-musl`, `${base}-musl`, `${base}-baseline`, base]
+            : [`${base}-musl`, `${base}-baseline-musl`, base, `${base}-baseline`]
+          : [`${base}-musl`, base]
+        : arch === "x64"
+          ? baseline
+            ? [`${base}-baseline`, base, `${base}-baseline-musl`, `${base}-musl`]
+            : [base, `${base}-baseline`, `${base}-musl`, `${base}-baseline-musl`]
+          : [base, `${base}-musl`]
+      : arch === "x64"
+        ? baseline
+          ? [`${base}-baseline`, base]
+          : [base, `${base}-baseline`]
+        : [base]
+  return names.filter((name) => dependencies[name])
+}
+
+function copyBinary(source) {
+  if (!fs.existsSync(source)) throw new Error(`Binary not found at ${source}`)
+  fs.mkdirSync(path.dirname(targetBinary), { recursive: true })
+  if (fs.existsSync(targetBinary)) fs.unlinkSync(targetBinary)
+  try {
+    fs.linkSync(source, targetBinary)
+  } catch {
+    fs.copyFileSync(source, targetBinary)
+  }
+  fs.chmodSync(targetBinary, 0o755)
+}
+
+function resolveBinary(name) {
+  const packagePath = require.resolve(`${name}/package.json`)
+  return path.join(path.dirname(packagePath), "bin", sourceBinary)
+}
+
+function installPackage(name) {
+  const temp = fs.mkdtempSync(path.join(os.tmpdir(), "opencode-install-"))
+  try {
+    const result = childProcess.spawnSync(
+      "npm",
+      ["install", "--ignore-scripts", "--no-save", "--loglevel=error", "--prefix", temp, `${name}@${dependencies[name]}`],
+      { stdio: "inherit", windowsHide: true },
+    )
+    if (result.status !== 0) return false
+    copyBinary(path.join(temp, "node_modules", name, "bin", sourceBinary))
+    return true
+  } finally {
+    fs.rmSync(temp, { recursive: true, force: true })
+  }
+}
+
+function verifyBinary() {
+  return (
+    childProcess.spawnSync(targetBinary, ["--version"], {
+      stdio: "ignore",
+      windowsHide: true,
+    }).status === 0
+  )
+}
+
+function main() {
+  const names = packageNames()
+  for (const name of names) {
+    try {
+      copyBinary(resolveBinary(name))
+      if (verifyBinary()) return
+    } catch {
+      if (installPackage(name) && verifyBinary()) return
+    }
+  }
+
+  throw new Error(`Failed to install OpenCode. Try manually installing ${names.map((name) => JSON.stringify(name)).join(" or ")}.`)
+}
+
+try {
+  main()
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error))
+  process.exit(1)
+}
@@ -32,12 +32,23 @@ async function publishDistribution(input: { root: string; name: string; binary:
  if (!version) throw new Error(`No binary packages found for ${input.name}`)

  await $`mkdir -p ${input.root}/${input.name}/bin`
-  await $`cp ./bin/opencode2.cjs ${input.root}/${input.name}/bin/${input.binary}`
+  await $`cp ./script/postinstall.mjs ${input.root}/${input.name}/postinstall.mjs`
+  await Bun.file(`${input.root}/${input.name}/bin/${input.binary}.exe`).write(
+    [
+      `echo "Error: ${input.name}'s postinstall script was not run." >&2`,
+      'echo "" >&2',
+      'echo "This occurs when installation scripts are disabled." >&2',
+      'echo "Run the package postinstall script or reinstall with scripts enabled." >&2',
+      "exit 1",
+      "",
+    ].join("\n"),
+  )
  await Bun.file(`${input.root}/${input.name}/package.json`).write(
    JSON.stringify(
      {
        name: input.name,
-        bin: { [input.binary]: `./bin/${input.binary}` },
+        bin: { [input.binary]: `./bin/${input.binary}.exe` },
+        scripts: { postinstall: "node ./postinstall.mjs" },
        version,
        license: pkg.license,
        repository: { type: "git", url: "git+https://github.com/anomalyco/opencode.git" },
@@ -1,4 +1,4 @@
-import { AppNodeBuilder } from "@opencode-ai/core/effect/app-node-builder"
+import { LayerNode } from "@opencode-ai/core/effect/layer-node"
 import { Global } from "@opencode-ai/core/global"
 import { run } from "@opencode-ai/tui"
 import { Commands } from "../commands"
@@ -75,6 +75,6 @@ export default Runtime.handler(Commands, (input) =>
                : Effect.logInfo(message, tags)
        runFork(effect)
      },
-    }).pipe(Effect.provide(AppNodeBuilder.build(Global.node)))
+    }).pipe(Effect.provide(LayerNode.compile(Global.node)))
  }),
 )
@@ -7,7 +7,6 @@ import { Runtime } from "./framework/runtime"
 import { Observability } from "@opencode-ai/core/observability"
 import { Updater } from "./services/updater"
 import { InstallationChannel, InstallationVersion, InstallationLocal } from "@opencode-ai/core/installation/version"
-import { AppNodeBuilder } from "@opencode-ai/core/effect/app-node-builder"
 import { LayerNode } from "@opencode-ai/core/effect/layer-node"
 import { Global } from "@opencode-ai/core/global"
 import { AppProcess } from "@opencode-ai/core/process"
@@ -61,7 +60,7 @@ Effect.logInfo("cli starting", {
  Effect.annotateLogs({ role: "cli" }),
  Effect.provide(Config.layer),
  Effect.provide(Updater.layer),
-  Effect.provide(AppNodeBuilder.build(LayerNode.group([Global.node, AppProcess.node, Npm.node]))),
+  Effect.provide(LayerNode.compile(LayerNode.group([Global.node, AppProcess.node, Npm.node]))),
  Effect.provide(Observability.layer),
  Effect.provide(NodeServices.layer),
  Effect.scoped,
@@ -7,8 +7,8 @@
 // none block each other.
 import { Context, Effect, Layer } from "effect"
 import { resolve } from "@opencode-ai/tui/config/v1"
-import { AppNodeBuilder } from "@opencode-ai/core/effect/app-node-builder"
 import { makeGlobalNode } from "@opencode-ai/core/effect/app-node"
+import { LayerNode } from "@opencode-ai/core/effect/layer-node"
 import { makeRuntime } from "@opencode-ai/core/effect/runtime"
 import { loadRunProviders } from "./catalog.shared"
 import { resolveCurrentSession, sessionHistory } from "./session.shared"
@@ -130,7 +130,7 @@ const layer = Layer.effect(
 )

 const node = makeGlobalNode({ service: Service, layer, deps: [] })
-const runtime = makeRuntime(Service, AppNodeBuilder.build(node))
+const runtime = makeRuntime(Service, LayerNode.compile(node))

 // Fetches available variants and context limits for every provider/model pair.
 export async function resolveModelInfo(
@@ -8,7 +8,6 @@
 // variant and the persisted file.
 import path from "path"
 import { FSUtil } from "@opencode-ai/core/fs-util"
-import { AppNodeBuilder } from "@opencode-ai/core/effect/app-node-builder"
 import { Context, Effect, Layer } from "effect"
 import { LayerNode } from "@opencode-ai/core/effect/layer-node"
 import { makeGlobalNode } from "@opencode-ai/core/effect/app-node"
@@ -203,7 +202,7 @@ const node = makeGlobalNode({ service: Service, layer, deps: [FSUtil.node] })

 /** @internal Exported for testing. */
 export function createVariantRuntime(replacements?: readonly LayerNode.Replacement[]): VariantRuntime {
-  const runtime = makeRuntime(Service, AppNodeBuilder.build(node, replacements))
+  const runtime = makeRuntime(Service, LayerNode.compile(node, replacements))
  return {
    resolveSavedVariant: (model) => runtime.runPromise((svc) => svc.resolveSavedVariant(model)).catch(() => undefined),
    saveVariant: (model, variant) => runtime.runPromise((svc) => svc.saveVariant(model, variant)).catch(() => {}),
@@ -1,13 +1,11 @@
 export * as ServerProcess from "./server-process"

 import { NodeServices } from "@effect/platform-node"
-import { Service } from "@opencode-ai/client/effect/service"
-import { AppNodeBuilder } from "@opencode-ai/core/effect/app-node-builder"
+import { Service, type DiscoverOptions, type Info } from "@opencode-ai/client/effect/service"
 import { LayerNode } from "@opencode-ai/core/effect/layer-node"
 import { Global } from "@opencode-ai/core/global"
 import { InstallationVersion } from "@opencode-ai/core/installation/version"
 import { AppProcess } from "@opencode-ai/core/process"
-import { ProcessLock } from "@opencode-ai/core/util/process-lock"
 import { randomBytes, randomUUID } from "node:crypto"
 import path from "node:path"
 import { Effect, FileSystem, Logger, Option, Redacted, Schedule, Schema } from "effect"
@@ -28,7 +26,7 @@ export type Options = {
 export const run = Effect.fnUntraced(function* (options: Options) {
  return yield* processEffect(options).pipe(
    Effect.provide(Updater.layer),
-    Effect.provide(AppNodeBuilder.build(LayerNode.group([Global.node, AppProcess.node]))),
+    Effect.provide(LayerNode.compile(LayerNode.group([Global.node, AppProcess.node]))),
    Effect.provide(NodeServices.layer),
  )
 })
@@ -38,14 +36,15 @@ const processEffect = Effect.fnUntraced(function* (options: Options) {
  return yield* Effect.scoped(
    Effect.gen(function* () {
      const serviceOptions = options.mode === "service" ? yield* ServiceConfig.options() : undefined
-      if (serviceOptions !== undefined) {
-        const acquired = yield* ProcessLock.acquire(serviceOptions.file + ".lock").pipe(
-          Effect.as(true),
-          Effect.catchTag("ProcessLockHeldError", () => Effect.succeed(false)),
-        )
-        if (!acquired) return yield* Effect.void
-        if ((yield* Service.discover(serviceOptions)) !== undefined) return yield* Effect.void
-      }
+      const config = options.mode === "service" ? yield* ServiceConfig.read() : {}
+      const hostname = options.hostname ?? config.hostname ?? "127.0.0.1"
+      const port = options.port ?? config.port ?? (options.mode === "service" ? ServiceConfig.defaultPort() : undefined)
+      if (
+        serviceOptions !== undefined &&
+        port !== undefined &&
+        (yield* Service.incumbent({ ...serviceOptions, url: serviceURL(hostname, port) })) !== undefined
+      )
+        return
      const { start } = yield* Effect.promise(() => import("@opencode-ai/server/process"))
      const environmentPassword = yield* Env.password
      // Keep the lease credential out of the environment inherited by tools.
@@ -53,7 +52,6 @@ const processEffect = Effect.fnUntraced(function* (options: Options) {
        delete process.env.OPENCODE_PASSWORD
        delete process.env.OPENCODE_SERVER_PASSWORD
      }
-      const config = options.mode === "service" ? yield* ServiceConfig.read() : {}
      const password =
        options.mode === "service"
          ? yield* ServiceConfig.password()
@@ -63,15 +61,36 @@ const processEffect = Effect.fnUntraced(function* (options: Options) {
      if (!password) return yield* Effect.fail(new Error("Missing server password"))
      const instanceID = randomUUID()
      const server = yield* start({
-        hostname: options.hostname ?? config.hostname ?? "127.0.0.1",
-        port: Option.fromNullishOr(options.port ?? config.port),
+        hostname,
+        port: Option.fromNullishOr(port),
        password,
        instanceID,
        service:
          serviceOptions === undefined
            ? undefined
-            : { onListen: (address) => register(address, password, instanceID, serviceOptions.file) },
-      }).pipe(Effect.provide(Logger.layer([], { mergeWithExisting: false })))
+            : {
+                onListen: (address, shutdown) => register(address, password, instanceID, serviceOptions.file, shutdown),
+              },
+      }).pipe(
+        Effect.provide(Logger.layer([], { mergeWithExisting: false })),
+        Effect.catch((error) => {
+          if (serviceOptions === undefined || port === undefined || !addressInUse(error)) return Effect.fail(error)
+          return recognizeIncumbent(serviceOptions, hostname, port).pipe(
+            Effect.flatMap((found) =>
+              found
+                ? Effect.void
+                : Effect.fail(
+                    new Error(
+                      `Managed service port ${port} on ${hostname} is already in use by another process. ` +
+                        "Configure another port with `opencode service set port <port>` and start the service again.",
+                      { cause: error },
+                    ),
+                  ),
+            ),
+          )
+        }),
+      )
+      if (server === undefined) return
      const url = HttpServer.formatAddress(server.address)
      console.log(options.mode === "stdio" ? JSON.stringify({ url }) : `server listening on ${url}`)
      if (options.mode === "default" && !environmentPassword) console.log(`server password ${password}`)
@@ -95,6 +114,7 @@ const register = Effect.fnUntraced(function* (
  password: string,
  id: string,
  file: string,
+  shutdown: Effect.Effect<void>,
 ) {
  const fs = yield* FileSystem.FileSystem
  const temp = file + "." + id + ".tmp"
@@ -107,38 +127,49 @@ const register = Effect.fnUntraced(function* (
    password,
  }
  const encoded = yield* encodeInfo(info)
-  const publish = fs.writeFileString(temp, encoded, { mode: 0o600 }).pipe(Effect.andThen(fs.rename(temp, file)))
-  yield* publish
  const current = fs.readFileString(file).pipe(
    Effect.flatMap(decodeInfo),
    Effect.orElseSucceed(() => undefined),
  )
-  const assertRegistration = Effect.gen(function* () {
-    const found = yield* current
-    if (
-      found !== undefined &&
-      found.id === info.id &&
-      found.version === info.version &&
-      found.url === info.url &&
-      found.pid === info.pid &&
-      found.password === info.password
-    )
-      return
-    yield* publish
-  })
-  yield* Effect.addFinalizer(() =>
-    current.pipe(
-      Effect.flatMap((current) => (current?.id === id ? fs.remove(file) : Effect.void)),
-      Effect.ignore,
-    ),
-  )
-  yield* assertRegistration.pipe(
-    Effect.catchCause((cause) => Effect.logWarning("failed to reassert service registration", { cause })),
+  const owns = (found: Info | undefined) =>
+    found?.id === info.id &&
+    found.version === info.version &&
+    found.url === info.url &&
+    found.pid === info.pid &&
+    found.password === info.password
+  yield* fs.writeFileString(temp, encoded, { mode: 0o600 }).pipe(Effect.andThen(fs.rename(temp, file)))
+  yield* current.pipe(
+    Effect.filterOrFail(owns),
    Effect.repeat(Schedule.spaced("5 seconds")),
+    Effect.ignore,
+    Effect.andThen(shutdown),
    Effect.forkScoped,
  )
+  return current.pipe(
+    Effect.flatMap((found) => (owns(found) ? fs.remove(file) : Effect.void)),
+    Effect.ignore,
+  )
 })

+const recognizeIncumbent = Effect.fnUntraced(function* (options: DiscoverOptions, hostname: string, port: number) {
+  const found = yield* Service.incumbent({ ...options, url: serviceURL(hostname, port) }).pipe(
+    Effect.filterOrFail((value) => value !== undefined),
+    Effect.retry(Schedule.max([Schedule.spaced("100 millis"), Schedule.recurs(60)])),
+    Effect.option,
+  )
+  return Option.isSome(found)
+})
+
+function serviceURL(hostname: string, port: number) {
+  return `http://${hostname.includes(":") ? `[${hostname}]` : hostname}:${port}`
+}
+
+function addressInUse(error: unknown): boolean {
+  if (typeof error !== "object" || error === null) return false
+  if ("code" in error && error.code === "EADDRINUSE") return true
+  return "cause" in error && addressInUse(error.cause)
+}
+
 function waitForStdinClose() {
  return Effect.callback<void>((resume) => {
    const close = () => resume(Effect.void)
@@ -30,6 +30,12 @@ export function filename(channel = InstallationChannel) {
  return `service-${Hash.fast(channel)}.json`
 }

+export function defaultPort(channel = InstallationChannel) {
+  if (channel === "latest") return 0xc0de
+  if (channel === "local") return 0xc0df
+  return 10_000 + (Number.parseInt(Hash.fast(channel).slice(0, 8), 16) % 50_000)
+}
+
 export function versionBelongsToChannel(
  version: string | undefined,
  channel = InstallationChannel,
@@ -1,6 +1,6 @@
 import { Service, type Endpoint } from "@opencode-ai/client/effect/service"
 import { CrossSpawnSpawner } from "@opencode-ai/core/cross-spawn-spawner"
-import { AppNodeBuilder } from "@opencode-ai/core/effect/app-node-builder"
+import { LayerNode } from "@opencode-ai/core/effect/layer-node"
 import { Deferred, Effect, Schema, Stream } from "effect"
 import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process"
 import { randomBytes } from "node:crypto"
@@ -53,7 +53,7 @@ const makeEndpoint = Effect.fn("cli.standalone.endpoint")(
      pid: proc.pid,
    } satisfies Endpoint & { readonly pid: number }
  },
-  Effect.provide(AppNodeBuilder.build(CrossSpawnSpawner.node)),
+  Effect.provide(LayerNode.compile(CrossSpawnSpawner.node)),
 )

 export function start(options: Options = {}) {
@@ -1,5 +1,5 @@
 import { NodeFileSystem } from "@effect/platform-node"
-import { Service } from "@opencode-ai/client/effect/service"
+import { Service, type Info } from "@opencode-ai/client/effect/service"
 import { Database } from "@opencode-ai/core/database/database"
 import { EventV2 } from "@opencode-ai/core/event"
 import { EventTable } from "@opencode-ai/core/event/sql"
@@ -17,6 +17,13 @@ import os from "node:os"
 import path from "node:path"
 import { ServiceConfig } from "../src/services/service-config"

+test("managed service ports are stable per installation channel", () => {
+  expect(ServiceConfig.defaultPort("latest")).toBe(0xc0de)
+  expect(ServiceConfig.defaultPort("local")).toBe(0xc0df)
+  expect(ServiceConfig.defaultPort("preview-a")).toBe(ServiceConfig.defaultPort("preview-a"))
+  expect(ServiceConfig.defaultPort("preview-a")).not.toBe(ServiceConfig.defaultPort("preview-b"))
+})
+
 test("local channel stores service config with the local service filename", async () => {
  const root = await fs.mkdtemp(path.join(os.tmpdir(), "opencode-service-"))
  try {
@@ -90,6 +97,80 @@ test("preview registration migration never moves stable discovery", async () =>
  }
 })

+test("managed service writes its registration once", async () => {
+  const service = await startManagedService("opencode-service-once-")
+  try {
+    const before = await fs.stat(service.registration)
+    await Bun.sleep(6_000)
+    const after = await fs.stat(service.registration)
+    expect(after.ino).toBe(before.ino)
+    expect(after.mtimeMs).toBe(before.mtimeMs)
+    expect(await Bun.file(service.registration).json()).toEqual(service.info)
+  } finally {
+    await stopManagedService(service)
+  }
+}, 30_000)
+
+test("deleting a managed service registration stops its owner", async () => {
+  const service = await startManagedService("opencode-service-delete-")
+  try {
+    await fs.rm(service.registration)
+    expect(await waitForExit(service.owner)).toBe(true)
+    expect(await Bun.file(service.registration).exists()).toBe(false)
+    await expectPortAvailable(service.port)
+  } finally {
+    await stopManagedService(service)
+  }
+}, 30_000)
+
+test("deleting a failed service registration stops its owner", async () => {
+  const service = await startManagedService("opencode-service-failed-delete-", true)
+  try {
+    await waitForFailed(service.info)
+    await fs.rm(service.registration)
+    expect(await waitForExit(service.owner)).toBe(true)
+    await expectPortAvailable(service.port)
+  } finally {
+    await stopManagedService(service)
+  }
+}, 30_000)
+
+test("corrupting a managed service registration stops its owner", async () => {
+  const service = await startManagedService("opencode-service-corrupt-")
+  try {
+    await fs.writeFile(service.registration, "not-json")
+    expect(await waitForExit(service.owner)).toBe(true)
+    expect(await Bun.file(service.registration).text()).toBe("not-json")
+    await expectPortAvailable(service.port)
+  } finally {
+    await stopManagedService(service)
+  }
+}, 30_000)
+
+test("replacing a managed service registration stops its owner and preserves the foreign owner", async () => {
+  const service = await startManagedService("opencode-service-foreign-")
+  const foreign = { ...service.info, id: "foreign-owner", pid: process.pid }
+  try {
+    await fs.writeFile(service.registration, JSON.stringify(foreign))
+    expect(await waitForExit(service.owner)).toBe(true)
+    expect(await Bun.file(service.registration).json()).toEqual(foreign)
+    await expectPortAvailable(service.port)
+  } finally {
+    await stopManagedService(service)
+  }
+}, 30_000)
+
+test("clean managed service shutdown removes its registration", async () => {
+  const service = await startManagedService("opencode-service-clean-")
+  try {
+    await Effect.runPromise(Service.stop({ file: service.registration }).pipe(Effect.provide(NodeFileSystem.layer)))
+    expect(await waitForExit(service.owner)).toBe(true)
+    expect(await Bun.file(service.registration).exists()).toBe(false)
+  } finally {
+    await stopManagedService(service)
+  }
+}, 30_000)
+
 test("concurrent service processes elect one server", async () => {
  const root = await fs.mkdtemp(path.join(os.tmpdir(), "opencode-service-election-"))
  const database = path.join(root, "opencode.db")
@@ -130,6 +211,9 @@ test("concurrent service processes elect one server", async () => {
  )
  const command = [process.execPath, path.join(import.meta.dir, "../src/index.ts"), "serve", "--service"]
  const registration = path.join(root, "state", "opencode", "service-local.json")
+  const port = await availablePort()
+  await fs.mkdir(path.join(root, "config", "opencode"), { recursive: true })
+  await fs.writeFile(path.join(root, "config", "opencode", "service-local.json"), JSON.stringify({ port }))
  const processes = Array.from({ length: 10 }, () => Bun.spawn(command, { env, stderr: "pipe", stdout: "ignore" }))

  try {
@@ -137,11 +221,13 @@ test("concurrent service processes elect one server", async () => {
    const winner = processes.find((process) => process.pid === info.pid)
    const losers = processes.filter((process) => process.pid !== info.pid)
    const exited = await Promise.all(
-      losers.map((process) => Promise.race([process.exited.then(() => true), Bun.sleep(10_000).then(() => false)])),
+      losers.map((process) => Promise.race([process.exited.then(() => true), Bun.sleep(60_000).then(() => false)])),
    )

    expect(exited).toEqual(losers.map(() => true))
    expect(winner?.exitCode).toBe(null)
+    expect(new URL(info.url).port).toBe(String(port))
+    expect(await Bun.file(registration + ".lock").exists()).toBe(false)
    expect(
      await fetch(new URL("/api/health", info.url), {
        headers: { authorization: "Basic " + btoa(`opencode:${info.password}`) },
@@ -151,20 +237,6 @@ test("concurrent service processes elect one server", async () => {
      version: info.version,
      pid: info.pid,
    })
-    const blockedTemp = registration + "." + info.id + ".tmp"
-    await fs.mkdir(blockedTemp)
-    await fs.rm(registration)
-    await Bun.sleep(6_000)
-    expect(await Bun.file(registration).exists()).toBe(false)
-    await fs.rm(blockedTemp, { recursive: true })
-    const restored = await waitForInfo(registration)
-    expect(restored.id).toBe(info.id)
-    expect(restored.pid).toBe(info.pid)
-    await fs.writeFile(registration, "not-json")
-    const repaired = await waitForInfo(registration)
-    expect(repaired.id).toBe(info.id)
-    expect(repaired.pid).toBe(info.pid)
-
    const contender = Bun.spawn(command, { env, stderr: "pipe", stdout: "ignore" })
    try {
      const contenderExited = await Promise.race([
@@ -202,9 +274,88 @@ test("concurrent service processes elect one server", async () => {
      await fs.rm(root, { recursive: true, force: true })
    }
  }
-}, 60_000)
+}, 120_000)

-test("a failed service stays registered and owns the lock until stopped", async () => {
+test("configured managed service port overrides the channel default", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "opencode-service-port-"))
+  const port = await availablePort()
+  const env = serviceEnv(root)
+  const registration = path.join(root, "state", "opencode", "service-local.json")
+  await fs.mkdir(path.join(root, "config", "opencode"), { recursive: true })
+  await fs.writeFile(path.join(root, "config", "opencode", "service-local.json"), JSON.stringify({ port }))
+  const owner = Bun.spawn([process.execPath, path.join(import.meta.dir, "../src/index.ts"), "serve", "--service"], {
+    env,
+    stderr: "pipe",
+    stdout: "ignore",
+  })
+  try {
+    const info = await waitForInfo(registration)
+    expect(new URL(info.url).port).toBe(String(port))
+    await Effect.runPromise(Service.stop({ file: registration }).pipe(Effect.provide(NodeFileSystem.layer)))
+    await owner.exited
+  } finally {
+    owner.kill("SIGTERM")
+    await owner.exited
+    await fs.rm(root, { recursive: true, force: true })
+  }
+}, 30_000)
+
+test("unrelated managed port occupancy reports an actionable conflict", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "opencode-service-conflict-"))
+  const listener = Bun.serve({ port: 0, fetch: () => new Response("unrelated") })
+  const port = listener.port
+  const registration = path.join(root, "state", "opencode", "service-local.json")
+  await fs.mkdir(path.join(root, "config", "opencode"), { recursive: true })
+  await fs.writeFile(path.join(root, "config", "opencode", "service-local.json"), JSON.stringify({ port }))
+  const contender = Bun.spawn([process.execPath, path.join(import.meta.dir, "../src/index.ts"), "serve", "--service"], {
+    env: serviceEnv(root),
+    stderr: "pipe",
+    stdout: "pipe",
+  })
+  try {
+    expect(await contender.exited).not.toBe(0)
+    const output = (await new Response(contender.stdout).text()) + (await new Response(contender.stderr).text())
+    expect(output).toContain(`Managed service port ${port} on 127.0.0.1 is already in use by another process`)
+    expect(output).toContain("opencode service set port <port>")
+    expect(await Bun.file(registration).exists()).toBe(false)
+  } finally {
+    listener.stop(true)
+    contender.kill("SIGTERM")
+    await contender.exited
+    await fs.rm(root, { recursive: true, force: true })
+  }
+}, 30_000)
+
+test("stale dead registration is replaced after binding the selected port", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "opencode-service-stale-"))
+  const port = await availablePort()
+  const registration = path.join(root, "state", "opencode", "service-local.json")
+  await fs.mkdir(path.join(root, "config", "opencode"), { recursive: true })
+  await fs.mkdir(path.dirname(registration), { recursive: true })
+  await fs.writeFile(path.join(root, "config", "opencode", "service-local.json"), JSON.stringify({ port }))
+  await fs.writeFile(
+    registration,
+    JSON.stringify({ id: "dead", version: "dead", url: `http://127.0.0.1:${port}`, pid: 2_147_483_647 }),
+  )
+  const owner = Bun.spawn([process.execPath, path.join(import.meta.dir, "../src/index.ts"), "serve", "--service"], {
+    env: serviceEnv(root),
+    stderr: "pipe",
+    stdout: "ignore",
+  })
+  try {
+    const info = await waitForInfo(registration, (value) => value.id !== "dead")
+    expect(new URL(info.url).port).toBe(String(port))
+    expect(info.pid).toBe(owner.pid)
+    await Effect.runPromise(Service.stop({ file: registration }).pipe(Effect.provide(NodeFileSystem.layer)))
+    await owner.exited
+  } finally {
+    owner.kill("SIGTERM")
+    await owner.exited
+    await fs.rm(root, { recursive: true, force: true })
+  }
+}, 30_000)
+
+test("a failed service stays registered and owns the selected port until stopped", async () => {
  const root = await fs.mkdtemp(path.join(os.tmpdir(), "opencode-service-failed-"))
  const database = path.join(root, "database")
  await fs.mkdir(database)
@@ -275,13 +426,86 @@ function waitForExecutionStart(file: string, sessionID: SessionV2.ID) {
  )
 }

-async function waitForInfo(file: string) {
+async function waitForInfo(file: string, accept: (info: Info) => boolean = () => true) {
  for (let attempt = 0; attempt < 400; attempt++) {
    const value = await Bun.file(file)
      .json()
      .catch(() => undefined)
-    if (value !== undefined) return Schema.decodeUnknownPromise(Service.Info)(value)
+    if (value !== undefined) {
+      const info = await Schema.decodeUnknownPromise(Service.Info)(value)
+      if (accept(info)) return info
+    }
    await Bun.sleep(50)
  }
  throw new Error("Timed out waiting for service registration")
 }
+
+async function waitForFailed(info: Info) {
+  for (let attempt = 0; attempt < 400; attempt++) {
+    const status = await fetch(new URL("/api/health", info.url), {
+      headers: { authorization: "Basic " + btoa(`opencode:${info.password}`) },
+    })
+      .then((response) => response.status)
+      .catch(() => undefined)
+    if (status === 500) return
+    await Bun.sleep(50)
+  }
+  throw new Error("Timed out waiting for service boot failure")
+}
+
+async function availablePort() {
+  const server = Bun.serve({ port: 0, fetch: () => new Response() })
+  const port = server.port
+  await server.stop(true)
+  if (port === undefined) throw new Error("Server did not bind a port")
+  return port
+}
+
+function serviceEnv(root: string) {
+  return {
+    ...process.env,
+    HOME: root,
+    OPENCODE_DB: path.join(root, "opencode.db"),
+    OPENCODE_TEST_HOME: root,
+    XDG_CACHE_HOME: path.join(root, "cache"),
+    XDG_CONFIG_HOME: path.join(root, "config"),
+    XDG_DATA_HOME: path.join(root, "data"),
+    XDG_STATE_HOME: path.join(root, "state"),
+  }
+}
+
+async function startManagedService(prefix: string, failBoot = false) {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), prefix))
+  const port = await availablePort()
+  const registration = path.join(root, "state", "opencode", "service-local.json")
+  await fs.mkdir(path.join(root, "config", "opencode"), { recursive: true })
+  if (failBoot) await fs.mkdir(path.join(root, "database"))
+  await fs.writeFile(path.join(root, "config", "opencode", "service-local.json"), JSON.stringify({ port }))
+  const owner = Bun.spawn([process.execPath, path.join(import.meta.dir, "../src/index.ts"), "serve", "--service"], {
+    env: failBoot ? { ...serviceEnv(root), OPENCODE_DB: path.join(root, "database") } : serviceEnv(root),
+    stderr: "pipe",
+    stdout: "ignore",
+  })
+  const info = await waitForInfo(registration).catch(async (cause) => {
+    owner.kill("SIGTERM")
+    await owner.exited
+    await fs.rm(root, { recursive: true, force: true })
+    throw cause
+  })
+  return { root, port, registration, owner, info }
+}
+
+async function stopManagedService(service: Awaited<ReturnType<typeof startManagedService>>) {
+  service.owner.kill("SIGTERM")
+  await service.owner.exited
+  await fs.rm(service.root, { recursive: true, force: true })
+}
+
+function waitForExit(process: Bun.Subprocess, timeout = 10_000) {
+  return Promise.race([process.exited.then(() => true), Bun.sleep(timeout).then(() => false)])
+}
+
+async function expectPortAvailable(port: number) {
+  const server = Bun.serve({ hostname: "127.0.0.1", port, fetch: () => new Response() })
+  await server.stop(true)
+}
@@ -29,6 +29,17 @@ export const discover = Effect.fn("service.discover")(function* (options: Discov
  return (yield* discoverLocal(options))?.endpoint
 })

+/** Recognize an authenticated compatible service bound to an expected URL, including while it starts or fails. */
+export const incumbent = Effect.fn("service.incumbent")(function* (
+  options: DiscoverOptions & { readonly url: string },
+) {
+  const info = yield* read(options.file)
+  const found = info === undefined ? undefined : yield* probe({ ...info, url: options.url })
+  if (found === undefined || found.legacy) return undefined
+  if (options.version !== undefined && found.version !== options.version) return undefined
+  return { endpoint: found.endpoint, state: found.state }
+})
+
 const discoverLocal = Effect.fnUntraced(function* (options: DiscoverOptions) {
  const found = (yield* registered(options.file)).service
  if (found?.state !== "ready") return undefined
@@ -101,8 +112,15 @@ export const ensure = Effect.fn("service.ensure")(function* (options: EnsureOpti
      lastSpawn = Date.now()
    }
    return Option.none<LocalService>()
-  }).pipe(Effect.repeat({ until: Option.isSome, schedule: Schedule.spaced("1 second") }))
-  return Option.getOrThrow(found).endpoint
+  }).pipe(
+    Effect.repeat({
+      until: Option.isSome,
+      schedule: Schedule.max([Schedule.spaced("1 second"), Schedule.recurs(120)]),
+    }),
+  )
+  if (Option.isNone(found))
+    return yield* Effect.fail(new Error("Timed out waiting for the background service to start"))
+  return found.value.endpoint
 })

 function contenderFailure(contender: Contender) {
@@ -273,4 +291,4 @@ const requestStop = Effect.fnUntraced(function* (service: LocalService) {
 })

 /** Effect-based local service lifecycle operations. */
-export const Service = { discover, ensure, stop, headers, Info }
+export const Service = { discover, incumbent, ensure, stop, headers, Info }
@@ -2,13 +2,7 @@ import { readFile } from "node:fs/promises"
 import { spawn, type ChildProcess } from "node:child_process"
 import { homedir } from "node:os"
 import { join } from "node:path"
-import type {
-  DiscoverOptions,
-  Endpoint,
-  Info,
-  EnsureOptions,
-  StopOptions,
-} from "../service.js"
+import type { DiscoverOptions, Endpoint, Info, EnsureOptions, StopOptions } from "../service.js"
 import type { ServiceHealth, ServiceStopResponse } from "./generated/types.js"

 export * from "../service.js"
@@ -38,6 +32,7 @@ async function discoverLocal(options: DiscoverOptions) {

 /** Ensure a healthy, compatible local service is running. */
 export async function ensure(options: EnsureOptions = {}): Promise<Endpoint> {
+  const deadline = Date.now() + 120_000
  const contenders = new Set<Contender>()
  let announced = false
  let lastSpawn = 0
@@ -66,6 +61,7 @@ export async function ensure(options: EnsureOptions = {}): Promise<Endpoint> {
  }

  while (true) {
+    if (Date.now() >= deadline) throw new Error("Timed out waiting for the background service to start")
    const registration = await registered(options.file, true)

    if (registration.service !== undefined) {
@@ -128,7 +124,9 @@ function fallback() {
 /** Create HTTP authentication headers for a service endpoint. */
 export function headers(endpoint: Endpoint) {
  if (endpoint.auth === undefined) return undefined
-  return { authorization: "Basic " + Buffer.from(endpoint.auth.username + ":" + endpoint.auth.password).toString("base64") }
+  return {
+    authorization: "Basic " + Buffer.from(endpoint.auth.username + ":" + endpoint.auth.password).toString("base64"),
+  }
 }

 async function read(file?: string) {
@@ -227,7 +225,8 @@ async function kill(service: LocalService, options: { readonly file?: string })
  const latest = await find(options)
  if (latest === undefined || !same(latest.info, service.info)) return
  signal(service.info.pid, "SIGKILL")
-  if (!(await waitUntilStopped(service.info.pid))) throw new Error(`Server process ${service.info.pid} is still running`)
+  if (!(await waitUntilStopped(service.info.pid)))
+    throw new Error(`Server process ${service.info.pid} is still running`)
 }

 async function requestStop(service: LocalService) {
@@ -13,8 +13,10 @@ import { EventV2 } from "../event"
 import { Form } from "../form"
 import { Integration } from "../integration"
 import { IntegrationConnection } from "../integration/connection"
+import { KeyedMutex } from "../effect/keyed-mutex"
 import { Location } from "../location"
 import { waitForAbort } from "../process"
+import { State } from "../state"
 import { MCPClient } from "./client"
 import { MCPOAuth } from "./oauth"

@@ -118,6 +120,7 @@ type ServerEntry = {
  prompts?: ReadonlyArray<Prompt>
  // Set when a remote server is registered as an OAuth integration; the credential lives in the global store.
  integrationID?: Integration.ID
+  registration?: State.Registration
 }

 // MCP elicitations are Location-scoped, not Session-scoped: the server cannot attribute them to a
@@ -127,6 +130,10 @@ const URL_ELICITATION_FIELD_KEY = "elicitation"

 export interface Interface {
  readonly servers: () => Effect.Effect<ServerInfo[]>
+  readonly add: (server: ServerName | string, config: typeof ConfigMCP.Server.Type) => Effect.Effect<void>
+  readonly connect: (server: ServerName | string) => Effect.Effect<void, NotFoundError>
+  readonly disconnect: (server: ServerName | string) => Effect.Effect<void, NotFoundError>
+  readonly remove: (server: ServerName | string) => Effect.Effect<void, NotFoundError>
  readonly tools: () => Effect.Effect<Tool[]>
  readonly callTool: (input: {
    readonly server: ServerName | string
@@ -170,6 +177,9 @@ export const layer = Layer.effect(
    )
    // Later config files win for duplicate server names; per-server timeout overrides globals.
    const runtime = new Map<ServerName, ServerEntry>()
+    // Serializes lifecycle operations per server. Anything taking this lock from a connection
+    // callback must stay forked: lifecycle operations close scopes while holding it, firing onClose.
+    const locks = KeyedMutex.makeUnsafe<ServerName>()
    const urlElicitations = new Map<string, Form.ID>()
    for (const entry of documents) {
      for (const [name, server] of Object.entries(entry.info.mcp?.servers ?? {})) {
@@ -183,14 +193,9 @@ export const layer = Layer.effect(

    // Register every remote server as an OAuth integration so credentials live in the global store
    // rather than in committed config. Servers that connect anonymously simply never use the method.
-    const registrations: Array<{
-      readonly name: ServerName
-      readonly remote: typeof ConfigMCP.Remote.Type
-      readonly integrationID: Integration.ID
-      readonly methodID: Integration.MethodID
-    }> = []
-    for (const [name, entry] of runtime) {
-      if (entry.config.type !== "remote" || entry.config.oauth === false) continue
+    const owned = new Set<Integration.ID>()
+    const register = Effect.fnUntraced(function* (name: ServerName, entry: ServerEntry) {
+      if (entry.config.type !== "remote" || entry.config.oauth === false) return
      const remote = entry.config
      // Key identity on name + url, not url alone: two configs for the same url under different names are
      // distinct logical servers that may hold different accounts, so they must not share a credential row.
@@ -200,27 +205,24 @@ export const layer = Layer.effect(
          .update(name + "\u0000" + remote.url)
          .digest("hex")
          .slice(0, 16)
-      entry.integrationID = Integration.ID.make(suffix)
-      registrations.push({
-        name,
-        remote,
-        integrationID: entry.integrationID,
-        methodID: Integration.MethodID.make(suffix),
-      })
-    }
-    if (registrations.length > 0)
-      yield* integration.transform((draft) => {
-        for (const reg of registrations) {
-          draft.update(reg.integrationID, (ref) => {
-            ref.name = reg.name
+      const integrationID = Integration.ID.make(suffix)
+      entry.integrationID = integrationID
+      owned.add(integrationID)
+      const methodID = Integration.MethodID.make(suffix)
+      entry.registration = yield* integration
+        .transform((draft) => {
+          draft.update(integrationID, (ref) => {
+            ref.name = name
          })
          draft.method.update({
-            integrationID: reg.integrationID,
-            method: { id: reg.methodID, type: "oauth", label: reg.name },
-            authorize: () => MCPOAuth.authorize({ name: reg.name, config: reg.remote, methodID: reg.methodID }),
+            integrationID,
+            method: { id: methodID, type: "oauth", label: name },
+            authorize: () => MCPOAuth.authorize({ name, config: remote, methodID }),
          })
-        }
-      })
+        })
+        .pipe(Scope.provide(root))
+    })
+    yield* Effect.forEach(runtime, ([name, entry]) => register(name, entry), { discard: true })

    const requireServer = Effect.fnUntraced(function* (server: ServerName | string) {
      const name = ServerName.make(server)
@@ -420,36 +422,44 @@ export const layer = Layer.effect(
        ),
      )

-    const watch = (name: ServerName, entry: ServerEntry, connection: MCPClient.Connection) => {
-      connection.onClose(() => {
-        // A reconnect closes the previous scope, but the SDK may fire this onclose after the new
-        // connection is already assigned; ignore the stale close so it can't null out the live client.
-        if (entry.client !== connection) return
-        entry.client = undefined
-        entry.tools = undefined
-        entry.prompts = undefined
-        entry.status = { status: "failed", error: "Connection closed" }
-        fork(events.publish(McpEvent.ToolsChanged, { server: name }).pipe(Effect.ignore))
-        fork(events.publish(McpEvent.ResourcesChanged, { server: name }).pipe(Effect.ignore))
-        fork(events.publish(Command.Event.Updated, {}).pipe(Effect.ignore))
-        fork(events.publish(McpEvent.StatusChanged, { server: name }).pipe(Effect.ignore))
-      })
-      connection.onLog((message) => fork(serverLog(name, message).pipe(Effect.ignore)))
-      connection.onToolsChanged(() => {
+    // Runs a connection callback under the server lock, dropping it if the connection is no longer
+    // the entry's live client, so late SDK callbacks cannot commit obsolete state.
+    const whenLive =
+      (name: ServerName, entry: ServerEntry, connection: MCPClient.Connection) =>
+      <E>(effect: Effect.Effect<void, E>) =>
        fork(
-          refreshTools(name, entry, connection).pipe(
-            Effect.andThen(events.publish(McpEvent.ToolsChanged, { server: name })),
+          Effect.suspend(() => (entry.client === connection ? effect : Effect.void)).pipe(
+            locks.withLock(name),
            Effect.ignore,
          ),
        )
-      })
-      connection.onPromptsChanged(() => {
-        fork(refreshPrompts(name, entry, connection).pipe(Effect.ignore))
-      })
-      connection.onResourcesChanged(() => {
-        if (entry.client !== connection) return
-        fork(events.publish(McpEvent.ResourcesChanged, { server: name }).pipe(Effect.ignore))
-      })
+
+    const watch = (name: ServerName, entry: ServerEntry, connection: MCPClient.Connection) => {
+      const live = whenLive(name, entry, connection)
+      connection.onClose(() =>
+        live(
+          Effect.gen(function* () {
+            entry.client = undefined
+            entry.tools = undefined
+            entry.prompts = undefined
+            entry.status = { status: "failed", error: "Connection closed" }
+            yield* events.publish(McpEvent.ToolsChanged, { server: name }).pipe(Effect.ignore)
+            yield* events.publish(McpEvent.ResourcesChanged, { server: name }).pipe(Effect.ignore)
+            yield* events.publish(Command.Event.Updated, {}).pipe(Effect.ignore)
+            yield* events.publish(McpEvent.StatusChanged, { server: name }).pipe(Effect.ignore)
+          }),
+        ),
+      )
+      connection.onLog((message) => fork(serverLog(name, message).pipe(Effect.ignore)))
+      connection.onToolsChanged(() =>
+        live(
+          refreshTools(name, entry, connection).pipe(
+            Effect.andThen(events.publish(McpEvent.ToolsChanged, { server: name })),
+          ),
+        ),
+      )
+      connection.onPromptsChanged(() => live(refreshPrompts(name, entry, connection)))
+      connection.onResourcesChanged(() => live(events.publish(McpEvent.ResourcesChanged, { server: name })))
    }

    const serverLog = (server: ServerName, message: MCPClient.LogMessage) => {
@@ -495,7 +505,7 @@ export const layer = Layer.effect(
          yield* events.publish(McpEvent.ToolsChanged, { server: name }).pipe(Effect.ignore)
          yield* events.publish(McpEvent.ResourcesChanged, { server: name }).pipe(Effect.ignore)
          yield* events.publish(McpEvent.StatusChanged, { server: name }).pipe(Effect.ignore)
-          fork(refreshPrompts(name, entry, result.value.connection).pipe(Effect.ignore))
+          whenLive(name, entry, result.value.connection)(refreshPrompts(name, entry, result.value.connection))
          return
        }
        yield* Scope.close(scope, Exit.void)
@@ -509,6 +519,19 @@ export const layer = Layer.effect(
        yield* events.publish(McpEvent.StatusChanged, { server: name }).pipe(Effect.ignore)
      }).pipe(Effect.ensuring(Deferred.succeed(entry.startup, undefined)))

+    const stopServer = Effect.fnUntraced(function* (name: ServerName, entry: ServerEntry) {
+      const scope = entry.scope
+      if (!scope) return
+      entry.scope = undefined
+      entry.client = undefined
+      entry.tools = undefined
+      entry.prompts = undefined
+      yield* Scope.close(scope, Exit.void)
+      yield* events.publish(McpEvent.ToolsChanged, { server: name }).pipe(Effect.ignore)
+      yield* events.publish(McpEvent.ResourcesChanged, { server: name }).pipe(Effect.ignore)
+      yield* events.publish(Command.Event.Updated, {}).pipe(Effect.ignore)
+    })
+
    // Disabled servers settle their startup immediately so queries never block on them.
    for (const [name, entry] of runtime) {
      if (entry.config.disabled) {
@@ -516,27 +539,24 @@ export const layer = Layer.effect(
        Deferred.doneUnsafe(entry.startup, Exit.void)
        continue
      }
-      fork(startServer(name, entry))
+      fork(startServer(name, entry).pipe(locks.withLock(name)))
    }

    // Bring a server online (or back to needs_auth) when its integration's credential changes, so an
    // OAuth login takes effect without a restart. Only fires for the integrations we registered.
-    const owned = new Set(registrations.map((reg) => reg.integrationID))
    const reconnect = (integrationID: Integration.ID) =>
      Effect.gen(function* () {
        const match = Array.from(runtime).find(([, entry]) => entry.integrationID === integrationID)
        if (!match) return
-        const [name, entry] = match
-        if (entry.config.disabled) return
-        if (entry.scope) {
-          yield* Scope.close(entry.scope, Exit.void)
-          entry.scope = undefined
-          entry.client = undefined
-          entry.tools = undefined
-          entry.prompts = undefined
-          yield* events.publish(Command.Event.Updated, {}).pipe(Effect.ignore)
-        }
-        yield* startServer(name, entry)
+        const name = match[0]
+        yield* Effect.gen(function* () {
+          // add() or remove() may have replaced or deleted the entry while we waited for the lock.
+          const entry = runtime.get(name)
+          if (!entry || entry.integrationID !== integrationID) return
+          if (entry.status.status === "disabled") return
+          yield* stopServer(name, entry)
+          yield* startServer(name, entry)
+        }).pipe(locks.withLock(name))
      })
    fork(
      events.subscribe(Integration.Event.ConnectionUpdated).pipe(
@@ -546,10 +566,13 @@ export const layer = Layer.effect(
      ),
    )

-    const whenAllReady = Effect.forEach(runtime.values(), (entry) => Deferred.await(entry.startup), {
-      concurrency: "unbounded",
-      discard: true,
-    })
+    // Suspend so each await sees current entries; a bare Map iterator is exhausted after one run.
+    const whenAllReady = Effect.suspend(() =>
+      Effect.forEach(Array.from(runtime.values()), (entry) => Deferred.await(entry.startup), {
+        concurrency: "unbounded",
+        discard: true,
+      }),
+    )
    return Service.of({
      servers: Effect.fn("MCP.servers")(function* () {
        const entries = Array.from(runtime).toSorted(([a], [b]) => a.localeCompare(b))
@@ -562,6 +585,66 @@ export const layer = Layer.effect(
          }),
        )
      }),
+      add: Effect.fn("MCP.add")(function* (server, config) {
+        const name = ServerName.make(server)
+        yield* Effect.gen(function* () {
+          const previous = runtime.get(name)
+          if (previous) {
+            yield* stopServer(name, previous)
+            if (previous.integrationID) owned.delete(previous.integrationID)
+            if (previous.registration) yield* previous.registration.dispose
+          }
+          const entry: ServerEntry = {
+            config: { ...config, timeout: { ...timeout, ...config.timeout } },
+            status: { status: "pending" },
+            startup: Deferred.makeUnsafe<void>(),
+          }
+          runtime.set(name, entry)
+          yield* Effect.gen(function* () {
+            yield* register(name, entry)
+            if (config.disabled) {
+              entry.status = { status: "disabled" }
+              yield* events.publish(McpEvent.StatusChanged, { server: name }).pipe(Effect.ignore)
+              return
+            }
+            yield* startServer(name, entry)
+          }).pipe(
+            // Settle startup even when register fails or add is interrupted, so an entry that made it
+            // into runtime can never hang readers awaiting its startup.
+            Effect.ensuring(Effect.sync(() => Deferred.doneUnsafe(entry.startup, Exit.void))),
+          )
+        }).pipe(locks.withLock(name))
+      }),
+      connect: Effect.fn("MCP.connect")(function* (server) {
+        const name = ServerName.make(server)
+        yield* Effect.gen(function* () {
+          const target = yield* requireServer(name)
+          yield* stopServer(name, target.entry)
+          yield* startServer(name, target.entry)
+        }).pipe(locks.withLock(name))
+      }),
+      disconnect: Effect.fn("MCP.disconnect")(function* (server) {
+        const name = ServerName.make(server)
+        yield* Effect.gen(function* () {
+          const target = yield* requireServer(name)
+          yield* stopServer(name, target.entry)
+          target.entry.status = { status: "disabled" }
+          yield* events.publish(McpEvent.StatusChanged, { server: name }).pipe(Effect.ignore)
+        }).pipe(locks.withLock(name))
+      }),
+      remove: Effect.fn("MCP.remove")(function* (server) {
+        const name = ServerName.make(server)
+        yield* Effect.gen(function* () {
+          const target = yield* requireServer(name)
+          yield* stopServer(name, target.entry)
+          if (target.entry.integrationID) owned.delete(target.entry.integrationID)
+          if (target.entry.registration) yield* target.entry.registration.dispose
+          // Credentials are kept: they are keyed by name + url, so re-adding the same server
+          // reuses them without forcing re-auth, matching add()'s replacement semantics.
+          runtime.delete(name)
+          yield* events.publish(McpEvent.StatusChanged, { server: name }).pipe(Effect.ignore)
+        }).pipe(locks.withLock(name))
+      }),
      tools: Effect.fn("MCP.tools")(function* () {
        yield* whenAllReady
        return Array.from(runtime.values())
@@ -6,7 +6,8 @@ import { Permission } from "@opencode-ai/schema/permission"
 import { EventV2 } from "./event"
 import { Location } from "./location"
 import { AgentV2 } from "./agent"
-import { SessionV2 } from "./session"
+import { SessionErrors } from "./session/error"
+import { SessionSchema } from "./session/schema"
 import { SessionStore } from "./session/store"
 import { Wildcard } from "./util/wildcard"
 import { PermissionSaved } from "./permission/saved"
@@ -98,11 +99,11 @@ export function merge(...rulesets: Permission.Ruleset[]): Permission.Ruleset {
 }

 export interface Interface {
-  readonly ask: (input: AssertInput) => Effect.Effect<AskResult, SessionV2.NotFoundError>
-  readonly assert: (input: AssertInput) => Effect.Effect<void, Error | SessionV2.NotFoundError>
+  readonly ask: (input: AssertInput) => Effect.Effect<AskResult, SessionErrors.NotFoundError>
+  readonly assert: (input: AssertInput) => Effect.Effect<void, Error | SessionErrors.NotFoundError>
  readonly reply: (input: ReplyInput) => Effect.Effect<void, NotFoundError>
  readonly get: (id: ID) => Effect.Effect<Request | undefined>
-  readonly forSession: (sessionID: SessionV2.ID) => Effect.Effect<ReadonlyArray<Request>>
+  readonly forSession: (sessionID: SessionSchema.ID) => Effect.Effect<ReadonlyArray<Request>>
  readonly list: () => Effect.Effect<ReadonlyArray<Request>>
 }

@@ -142,9 +143,12 @@ const layer = Layer.effect(
      )
    })

-    const configured = Effect.fn("PermissionV2.configured")(function* (sessionID: SessionV2.ID, agentID?: AgentV2.ID) {
+    const configured = Effect.fn("PermissionV2.configured")(function* (
+      sessionID: SessionSchema.ID,
+      agentID?: AgentV2.ID,
+    ) {
      const session = yield* sessions.get(sessionID)
-      if (!session) return yield* new SessionV2.NotFoundError({ sessionID })
+      if (!session) return yield* new SessionErrors.NotFoundError({ sessionID })
      const agent = yield* agents.resolve(agentID ?? session.agent)
      return agent?.permissions ?? missingAgentPermissions
    })
@@ -301,7 +305,7 @@ const layer = Layer.effect(
      return pending.get(id)?.request
    })

-    const forSession = Effect.fn("PermissionV2.forSession")(function* (sessionID: SessionV2.ID) {
+    const forSession = Effect.fn("PermissionV2.forSession")(function* (sessionID: SessionSchema.ID) {
      return Array.from(pending.values(), (item) => item.request).filter((request) => request.sessionID === sessionID)
    })

@@ -16,6 +16,10 @@ export interface Domains {
 type Callback<Event> = (event: Event) => Effect.Effect<void>

 export interface Interface {
+  readonly has: <Domain extends keyof Domains, Name extends keyof Domains[Domain]>(
+    domain: Domain,
+    name: Name,
+  ) => boolean
  readonly register: <Domain extends keyof Domains, Name extends keyof Domains[Domain]>(
    domain: Domain,
    name: Name,
@@ -60,7 +64,7 @@ const layer = Layer.effect(
      return event
    })

-    return Service.of({ register, trigger })
+    return Service.of({ has: (domain, name) => callbacks.has(key(domain, name)), register, trigger })
  }),
 )

@@ -28,9 +28,9 @@ import { fromRow } from "./session/info"
 import { SessionRunner } from "./session/runner/index"
 import { SessionStore } from "./session/store"
 import { SessionExecution } from "./session/execution"
+import { MessageDecodeError, NotFoundError } from "./session/error"
 import { makeGlobalNode } from "./effect/app-node"
 import { LocationServiceMap } from "./location-service-map"
-import { MessageDecodeError } from "./session/error"
 import { SessionEvent } from "./session/event"
 import { SessionPending } from "./session/pending"
 import { SessionGenerate } from "./session/generate"
@@ -108,10 +108,6 @@ type ForkInput = {
  messageID?: SessionMessage.ID
 }

-export class NotFoundError extends Schema.TaggedErrorClass<NotFoundError>()("Session.NotFoundError", {
-  sessionID: SessionSchema.ID,
-}) {}
-
 export class OperationUnavailableError extends Schema.TaggedErrorClass<OperationUnavailableError>()(
  "Session.OperationUnavailableError",
  {
@@ -119,7 +115,7 @@ export class OperationUnavailableError extends Schema.TaggedErrorClass<Operation
  },
 ) {}

-export { MessageDecodeError } from "./session/error"
+export { MessageDecodeError, NotFoundError }

 export class PromptConflictError extends Schema.TaggedErrorClass<PromptConflictError>()("Session.PromptConflictError", {
  sessionID: SessionSchema.ID,
@@ -1,9 +1,15 @@
+export * as SessionErrors from "./error"
+
 import { Schema } from "effect"
 import { Agent } from "@opencode-ai/schema/agent"
 import { SessionMessage } from "./message"
 import { SessionSchema } from "./schema"
 import { SessionError } from "@opencode-ai/schema/session-error"

+export class NotFoundError extends Schema.TaggedErrorClass<NotFoundError>()("Session.NotFoundError", {
+  sessionID: SessionSchema.ID,
+}) {}
+
 export class MessageDecodeError extends Schema.TaggedErrorClass<MessageDecodeError>()("Session.MessageDecodeError", {
  sessionID: SessionSchema.ID,
  messageID: SessionMessage.ID,
@@ -10,6 +10,7 @@ import { SessionContext } from "./context"
 import { SessionGenerate } from "./generate"
 import { SessionHistory } from "./history"
 import { SessionModelHeaders } from "./model-headers"
+import { SessionOptionsHook } from "./options-hook"
 import { SessionRunnerModel } from "./runner/model"
 import PROMPT_DEFAULT from "./runner/prompt/base.txt"
 import { toLLMMessages } from "./runner/to-llm-message"
@@ -46,7 +47,11 @@ const layer = Layer.effect(
          ],
          tools: {},
        })
-        return (yield* llm.generate(
+        return (yield* SessionOptionsHook.client(llm, hooks, {
+          sessionID: selection.session.id,
+          agent: selection.agent.id,
+          model: model.ref,
+        }).generate(
          LLM.request({
            model: model.model,
            http: { headers: SessionModelHeaders.make(selection.session) },
@@ -0,0 +1,26 @@
+export * as SessionOptionsHook from "./options-hook"
+
+import { LLM } from "@opencode-ai/ai"
+import type { LLMClientShape } from "@opencode-ai/ai/route"
+import type { SessionHooks } from "@opencode-ai/plugin/v2/effect/session"
+import { Effect } from "effect"
+import { PluginHooks } from "../plugin/hooks"
+
+type Identity = Pick<SessionHooks["options"], "sessionID" | "agent" | "model">
+
+export const client = (llm: LLMClientShape, hooks: PluginHooks.Interface, identity: Identity) =>
+  hooks.has("session", "options")
+    ? llm.withOptionsTransform((request) =>
+        Effect.gen(function* () {
+          const event = yield* hooks.trigger("session", "options", {
+            ...identity,
+            generation: { ...request.generation },
+            providerOptions: structuredClone(request.providerOptions ?? {}),
+          })
+          return LLM.updateRequest(request, {
+            generation: event.generation,
+            providerOptions: event.providerOptions,
+          })
+        }),
+      )
+    : llm
@@ -6,6 +6,7 @@ import { Cause, Effect, Exit, Fiber, FiberSet, Layer, Option, Semaphore, Stream
 import { Database } from "../../database/database"
 import { EventV2 } from "../../event"
 import { PermissionV2 } from "../../permission"
+import { PluginHooks } from "../../plugin/hooks"
 import { QuestionTool } from "../../tool/question"
 import { ToolOutputStore } from "../../tool-output-store"
 import { InstructionState } from "../instruction-state"
@@ -13,6 +14,7 @@ import { SessionCompaction } from "../compaction"
 import { SessionContext } from "../context"
 import { SessionEvent } from "../event"
 import { SessionPending } from "../pending"
+import { SessionOptionsHook } from "../options-hook"
 import { SessionModelRequest } from "../model-request"
 import { SessionMessage } from "../message"
 import { SessionSchema } from "../schema"
@@ -40,6 +42,7 @@ const layer = Layer.effect(
    const db = (yield* Database.Service).db
    const compaction = yield* SessionCompaction.Service
    const title = yield* SessionTitle.Service
+    const hooks = yield* PluginHooks.Service
    // Title generation is a side effect of the first step; it must not delay step continuation.
    // Tracked per process so repeated wakes before the second user message arrives don't
    // re-fire a redundant LLM call; `SessionTitle` itself is idempotent based on durable history.
@@ -132,7 +135,12 @@ const layer = Layer.effect(
      const serialized = <A, E, R>(effect: Effect.Effect<A, E, R>) => publication.withPermit(effect)
      const publish = (event: LLMEvent, error?: SessionError.Error) => serialized(publisher.publish(event, error))
      let overflowFailure: ProviderErrorEvent | undefined
-      const providerStream = llm.stream(prepared.request).pipe(
+      const sessionLLM = SessionOptionsHook.client(llm, hooks, {
+        sessionID: session.id,
+        agent: agent.id,
+        model: resolved.ref,
+      })
+      const providerStream = sessionLLM.stream(prepared.request).pipe(
        Stream.runForEach((event) =>
          Effect.gen(function* () {
            if (overflowFailure || publisher.hasProviderError()) return
@@ -482,5 +490,6 @@ export const node = makeLocationNode({
    SessionTitle.node,
    Snapshot.node,
    Database.node,
+    PluginHooks.node,
  ],
 })
@@ -9,6 +9,10 @@ export const emptyMcpLayer = Layer.succeed(
  MCP.Service,
  MCP.Service.of({
    servers: () => Effect.succeed([]),
+    add: () => Effect.die("unused mcp.add"),
+    connect: () => Effect.die("unused mcp.connect"),
+    disconnect: () => Effect.die("unused mcp.disconnect"),
+    remove: () => Effect.die("unused mcp.remove"),
    tools: () => Effect.succeed([]),
    callTool: () => Effect.die("unused mcp.callTool"),
    instructions: () => Effect.succeed([]),
@@ -148,7 +148,10 @@ function resourceServer(
  )
 }

-function resourceMcpLayer(url: string, onFormCreated?: (form: Form.Info) => Effect.Effect<void>) {
+function resourceMcpLayer(
+  server: string | typeof ConfigMCP.Server.Type,
+  onFormCreated?: (form: Form.Info) => Effect.Effect<void>,
+) {
  const directory = AbsolutePath.make(import.meta.dir)
  const unusedIntegration = () => Effect.die("unused integration service")
  return MCP.layer.pipe(
@@ -164,7 +167,12 @@ function resourceMcpLayer(url: string, onFormCreated?: (form: Form.Info) => Effe
                  type: "document",
                  info: new Config.Info({
                    mcp: new ConfigMCP.Info({
-                      servers: { resources: new ConfigMCP.Remote({ type: "remote", url, oauth: false }) },
+                      servers: {
+                        resources:
+                          typeof server === "string"
+                            ? new ConfigMCP.Remote({ type: "remote", url: server, oauth: false })
+                            : server,
+                      },
                    }),
                  }),
                }),
@@ -634,6 +642,120 @@ test("loads and reads MCP resources", async () => {
  )
 })

+test("adds, disconnects, and reconnects MCP servers at runtime", async () => {
+  await Effect.runPromise(
+    Effect.scoped(
+      Effect.gen(function* () {
+        yield* Effect.gen(function* () {
+          const service = yield* MCP.Service
+
+          expect((yield* service.servers())[0]?.status).toEqual({ status: "disabled" })
+          expect(yield* service.connect("missing").pipe(Effect.flip)).toBeInstanceOf(MCP.NotFoundError)
+          expect(yield* service.disconnect("missing").pipe(Effect.flip)).toBeInstanceOf(MCP.NotFoundError)
+          yield* service.add(
+            "dynamic",
+            new ConfigMCP.Local({
+              type: "local",
+              command: [process.execPath, path.join(import.meta.dir, "fixture/mcp-output-schema.ts")],
+            }),
+          )
+          expect((yield* service.servers()).find((server) => server.name === "dynamic")?.status).toEqual({
+            status: "connected",
+          })
+
+          yield* service.add(
+            "dynamic",
+            new ConfigMCP.Local({
+              type: "local",
+              command: [process.execPath, path.join(import.meta.dir, "fixture/mcp-output-schema.ts")],
+              disabled: true,
+            }),
+          )
+          expect((yield* service.servers()).find((server) => server.name === "dynamic")?.status).toEqual({
+            status: "disabled",
+          })
+          expect(yield* service.tools()).toEqual([])
+
+          yield* service.connect("dynamic")
+          expect((yield* service.servers()).find((server) => server.name === "dynamic")?.status).toEqual({
+            status: "connected",
+          })
+          yield* service.disconnect("dynamic")
+          expect((yield* service.servers()).find((server) => server.name === "dynamic")?.status).toEqual({
+            status: "disabled",
+          })
+          expect(yield* service.tools()).toEqual([])
+
+          yield* service.connect("dynamic")
+          expect((yield* service.servers()).find((server) => server.name === "dynamic")?.status).toEqual({
+            status: "connected",
+          })
+
+          yield* service.remove("dynamic")
+          expect((yield* service.servers()).some((server) => server.name === "dynamic")).toBe(false)
+          expect(yield* service.tools()).toEqual([])
+          expect(yield* service.remove("dynamic").pipe(Effect.flip)).toBeInstanceOf(MCP.NotFoundError)
+        }).pipe(
+          Effect.provide(
+            resourceMcpLayer(
+              new ConfigMCP.Local({
+                type: "local",
+                command: [process.execPath, path.join(import.meta.dir, "fixture/mcp-output-schema.ts")],
+                disabled: true,
+              }),
+            ),
+          ),
+        )
+      }),
+    ),
+  )
+})
+
+test("serializes concurrent MCP lifecycle operations", async () => {
+  await Effect.runPromise(
+    Effect.scoped(
+      Effect.gen(function* () {
+        yield* Effect.gen(function* () {
+          const service = yield* MCP.Service
+
+          // Whatever order the racing operations land in, the resulting state must be consistent.
+          yield* Effect.all(
+            [
+              service.connect("resources"),
+              service.connect("resources"),
+              service.disconnect("resources"),
+              service.connect("resources"),
+            ],
+            { concurrency: "unbounded", discard: true },
+          )
+          const status = (yield* service.servers()).find((server) => server.name === "resources")?.status
+          const tools = yield* service.tools()
+          expect(status?.status === "connected" || status?.status === "disabled").toBe(true)
+          if (status?.status === "disabled") expect(tools).toEqual([])
+          if (status?.status === "connected") expect(tools.length).toBeGreaterThan(0)
+
+          yield* service.disconnect("resources")
+          expect((yield* service.servers())[0]?.status).toEqual({ status: "disabled" })
+          expect(yield* service.tools()).toEqual([])
+          yield* service.connect("resources")
+          expect((yield* service.servers())[0]?.status).toEqual({ status: "connected" })
+          expect((yield* service.tools()).length).toBeGreaterThan(0)
+        }).pipe(
+          Effect.provide(
+            resourceMcpLayer(
+              new ConfigMCP.Local({
+                type: "local",
+                command: [process.execPath, path.join(import.meta.dir, "fixture/mcp-output-schema.ts")],
+                disabled: true,
+              }),
+            ),
+          ),
+        )
+      }),
+    ),
+  )
+})
+
 it.effect("advertises MCP output schemas to Code Mode", () =>
  Effect.gen(function* () {
    const registry = yield* ToolRegistry.Service
@@ -218,6 +218,38 @@ describe("fromPromise", () => {
    }),
  )

+  it.effect("forwards session option hooks", () =>
+    Effect.gen(function* () {
+      const plugin = yield* PluginV2.Service
+      const hooks = yield* PluginHooks.Service
+      const host = yield* PluginHost.make(plugin)
+      yield* PluginPromise.fromPromise(
+        Plugin.define({
+          id: "promise-session-options",
+          setup: async (ctx) => {
+            await ctx.session.hook("options", (event) => {
+              event.generation.temperature = 0.3
+              event.providerOptions.openai ??= {}
+              event.providerOptions.openai.reasoningEffort = "high"
+            })
+          },
+        }),
+      ).effect(host)
+      const event: SessionHooks["options"] = {
+        sessionID: SessionV2.ID.make("ses_promise_session_options"),
+        agent: AgentV2.ID.make("build"),
+        model: Model.Ref.make({ providerID: Provider.ID.make("test"), id: Model.ID.make("model") }),
+        generation: { temperature: 0.7 },
+        providerOptions: {},
+      }
+
+      yield* hooks.trigger("session", "options", event)
+
+      expect(event.generation.temperature).toBe(0.3)
+      expect(event.providerOptions).toEqual({ openai: { reasoningEffort: "high" } })
+    }),
+  )
+
  it.effect("disposes a hook registration on request", () =>
    Effect.gen(function* () {
      const agents = yield* AgentV2.Service
@@ -1,6 +1,7 @@
 import { describe, expect } from "bun:test"
 import { LLMClient, LLMEvent, Model, type LLMRequest } from "@opencode-ai/ai"
 import { OpenAIChat } from "@opencode-ai/ai/protocols"
+import type { LLMClientShape } from "@opencode-ai/ai/route"
 import { Config } from "@opencode-ai/core/config"
 import { Database } from "@opencode-ai/core/database/database"
 import { AppNodeBuilder } from "@opencode-ai/core/effect/app-node-builder"
@@ -40,14 +41,16 @@ const projects = Layer.succeed(
  }),
 )
 let requests: LLMRequest[] = []
-const client = Layer.mock(LLMClient.Service)({
+const clientValue: LLMClientShape = {
  prepare: () => Effect.die("unused"),
  stream: (request: LLMRequest) => {
    requests.push(request)
    return Stream.make(LLMEvent.textDelta({ id: "summary", text: "manual session summary" }))
  },
  generate: () => Effect.die("unused"),
-})
+  withOptionsTransform: () => clientValue,
+}
+const client = Layer.mock(LLMClient.Service)(clientValue)
 const config = Layer.mock(Config.Service)({ entries: () => Effect.succeed([]) })
 const models = SessionRunnerModel.layerWith(() => Effect.succeed(SessionRunnerModel.resolved(model)))
 const locations = Layer.effect(
@@ -1,6 +1,7 @@
 import { expect, test } from "bun:test"
 import { LLMClient, LLMEvent, Model, type LLMRequest } from "@opencode-ai/ai"
 import { OpenAIChat } from "@opencode-ai/ai/protocols"
+import type { LLMClientShape } from "@opencode-ai/ai/route"
 import { Config } from "@opencode-ai/core/config"
 import { Database } from "@opencode-ai/core/database/database"
 import { AppNodeBuilder } from "@opencode-ai/core/effect/app-node-builder"
@@ -42,7 +43,7 @@ const cost = [
    },
  },
 ]
-const client = Layer.mock(LLMClient.Service)({
+const clientValue: LLMClientShape = {
  prepare: () => Effect.die("unused"),
  stream: (request: LLMRequest) => {
    requests.push(request)
@@ -66,7 +67,9 @@ const client = Layer.mock(LLMClient.Service)({
    )
  },
  generate: () => Effect.die("unused"),
-})
+  withOptionsTransform: () => clientValue,
+}
+const client = Layer.mock(LLMClient.Service)(clientValue)
 const config = Layer.mock(Config.Service)({ entries: () => Effect.succeed([]) })
 const models = Layer.mock(SessionRunnerModel.Service)({
  resolve: () => Effect.succeed(SessionRunnerModel.resolved(model, undefined, cost)),
@@ -1,6 +1,7 @@
 import { expect } from "bun:test"
 import { LLMClient, LLMEvent, LLMResponse, Model, SystemPart, type LLMRequest } from "@opencode-ai/ai"
 import { OpenAIChat } from "@opencode-ai/ai/protocols"
+import type { LLMClientShape } from "@opencode-ai/ai/route"
 import { AgentV2 } from "@opencode-ai/core/agent"
 import { Database } from "@opencode-ai/core/database/database"
 import { AppNodeBuilder } from "@opencode-ai/core/effect/app-node-builder"
@@ -47,7 +48,7 @@ let instruction: string | Instructions.Unavailable = "Initial context"
 const sessionID = SessionSchema.ID.make("ses_generate_test")

 const model = Model.make({ id: "generate-model", provider: "test", route: OpenAIChat.route })
-const client = Layer.mock(LLMClient.Service)({
+const clientValue: LLMClientShape = {
  prepare: () => Effect.die(new Error("unused")),
  stream: () => Stream.die(new Error("unused")),
  generate: (request) =>
@@ -64,7 +65,9 @@ const client = Layer.mock(LLMClient.Service)({
      if (!response) throw new Error("Incomplete generate response")
      return response
    }),
-})
+  withOptionsTransform: () => clientValue,
+}
+const client = Layer.mock(LLMClient.Service)(clientValue)
 const models = SessionRunnerModel.layerWith(() => Effect.succeed(SessionRunnerModel.resolved(model)))
 const builtins = Layer.mock(InstructionBuiltIns.Service, {
  load: () =>
@@ -0,0 +1,57 @@
+import { expect } from "bun:test"
+import { LLM, LLMClient, Model as LLMModel } from "@opencode-ai/ai"
+import { OpenAIChat } from "@opencode-ai/ai/protocols"
+import type { LLMClientShape, OptionsTransform } from "@opencode-ai/ai/route"
+import { Agent } from "@opencode-ai/schema/agent"
+import { Model } from "@opencode-ai/schema/model"
+import { Provider } from "@opencode-ai/schema/provider"
+import { Session } from "@opencode-ai/schema/session"
+import { Effect, Layer, Stream } from "effect"
+import { PluginHooks } from "../src/plugin/hooks"
+import { SessionOptionsHook } from "../src/session/options-hook"
+import { testEffect } from "./lib/effect"
+
+const layer = PluginHooks.node.implementation as Layer.Layer<PluginHooks.Service>
+const it = testEffect(layer)
+
+it.effect("applies session option hooks to resolved model options", () =>
+  Effect.gen(function* () {
+    const hooks = yield* PluginHooks.Service
+    const sessionID = Session.ID.make("ses_options")
+    const agent = Agent.ID.make("build")
+    const model = Model.Ref.make({ providerID: Provider.ID.make("test"), id: Model.ID.make("model") })
+    yield* hooks.register("session", "options", (event) =>
+      Effect.sync(() => {
+        expect(event).toMatchObject({ sessionID, agent, model })
+        event.generation.temperature = 0.2
+        delete event.generation.topP
+        event.providerOptions.openai ??= {}
+        event.providerOptions.openai.reasoningEffort = "high"
+      }),
+    )
+    let transform: OptionsTransform | undefined
+    const llm: LLMClientShape = {
+      prepare: () => Effect.die("unused"),
+      stream: () => Stream.die("unused"),
+      generate: () => Effect.die("unused"),
+      withOptionsTransform: (next) => {
+        transform = next
+        return llm
+      },
+    }
+
+    SessionOptionsHook.client(llm, hooks, { sessionID, agent, model })
+    if (!transform) return yield* Effect.die("options transform was not installed")
+    const result = yield* transform(
+      LLM.request({
+        model: LLMModel.make({ id: "model", provider: "test", route: OpenAIChat.route }),
+        generation: { temperature: 0.7, topP: 0.9 },
+        providerOptions: { openai: { promptCacheKey: "cache" } },
+      }),
+    )
+
+    expect(result.generation).toMatchObject({ temperature: 0.2 })
+    expect(result.generation?.topP).toBeUndefined()
+    expect(result.providerOptions).toEqual({ openai: { promptCacheKey: "cache", reasoningEffort: "high" } })
+  }),
+)
@@ -90,9 +90,7 @@ let toolExecutionsStarted: Deferred.Deferred<void> | undefined
 let toolExecutionsReady = 5
 let activeToolExecutions = 0
 let maxActiveToolExecutions = 0
-const client = Layer.succeed(
-  LLMClient.Service,
-  LLMClient.Service.of({
+const clientValue: LLMClientShape = LLMClient.Service.of({
    prepare: () => Effect.die("unused"),
    stream: ((request: LLMRequest) => {
      requests.push(request)
@@ -114,8 +112,9 @@ const client = Layer.succeed(
      )
    }) as unknown as LLMClientShape["stream"],
    generate: () => Effect.die("unused"),
-  }),
-)
+    withOptionsTransform: () => clientValue,
+  })
+const client = Layer.succeed(LLMClient.Service, clientValue)
 const reply = {
  stop: () => [
    LLMEvent.stepStart({ index: 0 }),
@@ -1,6 +1,7 @@
 import { expect } from "bun:test"
 import { LLMClient, LLMEvent, Model, type LLMRequest } from "@opencode-ai/ai"
 import { OpenAIChat } from "@opencode-ai/ai/protocols"
+import type { LLMClientShape } from "@opencode-ai/ai/route"
 import { AgentV2 } from "@opencode-ai/core/agent"
 import { Database } from "@opencode-ai/core/database/database"
 import { AppNodeBuilder } from "@opencode-ai/core/effect/app-node-builder"
@@ -40,7 +41,7 @@ const cost = [
    },
  },
 ]
-const client = Layer.mock(LLMClient.Service)({
+const clientValue: LLMClientShape = {
  prepare: () => Effect.die("unused"),
  stream: (request: LLMRequest) => {
    requests.push(request)
@@ -64,7 +65,9 @@ const client = Layer.mock(LLMClient.Service)({
    )
  },
  generate: () => Effect.die("unused"),
-})
+  withOptionsTransform: () => clientValue,
+}
+const client = Layer.mock(LLMClient.Service)(clientValue)
 const models = Layer.mock(SessionRunnerModel.Service)({
  resolve: () => Effect.succeed(SessionRunnerModel.resolved(model, undefined, cost)),
 })
@@ -22,12 +22,12 @@ You can also install it with the following package managers.
  </Tab>
  <Tab title="bun">
    ```bash
-    bun install -g @opencode-ai/cli@next
+    bun install -g --trust @opencode-ai/cli@next
    ```
  </Tab>
  <Tab title="pnpm">
    ```bash
-    pnpm install -g @opencode-ai/cli@next
+    pnpm add -g --allow-build=@opencode-ai/cli @opencode-ai/cli@next
    ```
  </Tab>
  <Tab title="Yarn">
@@ -37,6 +37,9 @@ You can also install it with the following package managers.
  </Tab>
 </Tabs>

+The package uses a trusted postinstall script to select the native binary for your platform. The Bun and pnpm commands
+above explicitly allow that script to run.
+
 <Note>During beta, the binary is called `opencode2`.</Note>

 ### Homebrew
@@ -92,6 +92,20 @@ yield *
  )
 ```

+Resolved generation and provider options are mutable before provider lowering:
+
+```ts
+yield *
+  ctx.session.hook("options", (event) =>
+    Effect.sync(() => {
+      event.generation.temperature = 0.2
+      event.generation.topP = 0.9
+      event.providerOptions.openai ??= {}
+      event.providerOptions.openai.reasoningEffort = "high"
+    }),
+  )
+```
+
 ## Reloading A Domain

 When data captured by a transform changes, reload the affected domain:
@@ -1,5 +1,5 @@
 import type { SessionApi } from "@opencode-ai/client/effect/api"
-import type { Message, SystemPart } from "@opencode-ai/ai"
+import type { GenerationOptionsFields, Message, SystemPart } from "@opencode-ai/ai"
 import type { Agent } from "@opencode-ai/schema/agent"
 import type { Model } from "@opencode-ai/schema/model"
 import type { Session } from "@opencode-ai/schema/session"
@@ -15,8 +15,23 @@ export interface SessionContext {
  tools: Record<string, { description: string; input: JsonSchema.JsonSchema }>
 }

+export type SessionGenerationOptions = {
+  -readonly [Key in keyof GenerationOptionsFields]: GenerationOptionsFields[Key]
+}
+
+export type SessionProviderOptions = Record<string, Record<string, unknown>>
+
+export interface SessionOptions {
+  readonly sessionID: Session.ID
+  readonly agent: Agent.ID
+  readonly model: Model.Ref
+  generation: SessionGenerationOptions
+  providerOptions: SessionProviderOptions
+}
+
 export interface SessionHooks {
  readonly context: SessionContext
+  readonly options: SessionOptions
 }

 export type SessionDomain = Pick<
@@ -94,6 +94,17 @@ await ctx.session.hook("context", (event) => {
 })
 ```

+Resolved generation and provider options are mutable before provider lowering:
+
+```ts
+await ctx.session.hook("options", (event) => {
+  event.generation.temperature = 0.2
+  event.generation.topP = 0.9
+  event.providerOptions.openai ??= {}
+  event.providerOptions.openai.reasoningEffort = "high"
+})
+```
+
 Promise tools use plain object declarations with async executors:

 ```ts
@@ -1,5 +1,5 @@
 import type { SessionApi } from "@opencode-ai/client/promise/api"
-import type { Message, SystemPart } from "@opencode-ai/ai"
+import type { GenerationOptionsFields, Message, SystemPart } from "@opencode-ai/ai"
 import type { Agent } from "@opencode-ai/schema/agent"
 import type { Model } from "@opencode-ai/schema/model"
 import type { Session } from "@opencode-ai/schema/session"
@@ -15,8 +15,23 @@ export interface SessionContext {
  tools: Record<string, { description: string; input: JsonSchema.JsonSchema }>
 }

+export type SessionGenerationOptions = {
+  -readonly [Key in keyof GenerationOptionsFields]: GenerationOptionsFields[Key]
+}
+
+export type SessionProviderOptions = Record<string, Record<string, unknown>>
+
+export interface SessionOptions {
+  readonly sessionID: Session.ID
+  readonly agent: Agent.ID
+  readonly model: Model.Ref
+  generation: SessionGenerationOptions
+  providerOptions: SessionProviderOptions
+}
+
 export interface SessionHooks {
  readonly context: SessionContext
+  readonly options: SessionOptions
 }

 export type SessionDomain = Pick<
@@ -21,7 +21,10 @@ export type Options<E = never, R = never> = {
  readonly password: string
  readonly instanceID: string
  readonly service?: {
-    readonly onListen: (address: HttpServer.Address) => Effect.Effect<void, E, R>
+    readonly onListen: (
+      address: HttpServer.Address,
+      shutdown: Effect.Effect<void>,
+    ) => Effect.Effect<Effect.Effect<void>, E, R>
  }
 }

@@ -44,17 +47,21 @@ export const start = Effect.fn("ServerProcess.start")(function* <E, R>(options:
  yield* bound.http
    .serve(dispatch(options.password, status, application, shutdown), HttpMiddleware.logger)
    .pipe(withoutParentSpan)
-  if (options.service) yield* options.service.onListen(bound.http.address)
+  if (options.service)
+    yield* options.service.onListen(bound.http.address, Deferred.succeed(shutdown, undefined).pipe(Effect.asVoid)).pipe(
+      Effect.flatMap((cleanup) =>
+        Effect.addFinalizer(() => Scope.close(bound.scope, Exit.void).pipe(Effect.andThen(cleanup))),
+      ),
+      Effect.uninterruptible,
+    )

  const parentScope = yield* Scope.Scope
  const applicationScope = yield* Scope.fork(parentScope)
  yield* Effect.addFinalizer(() =>
-    status
-      .beginStopping
-      .pipe(
-        Effect.andThen(Ref.set(application, Option.none())),
-        Effect.andThen(Effect.sync(() => bound.server.closeAllConnections())),
-      ),
+    status.beginStopping.pipe(
+      Effect.andThen(Ref.set(application, Option.none())),
+      Effect.andThen(Effect.sync(() => bound.server.closeAllConnections())),
+    ),
  )

  const boot = Effect.gen(function* () {
@@ -112,7 +119,7 @@ function bind(hostname: string, port: number) {
    return yield* Effect.gen(function* () {
      const http = yield* NodeHttpServer.make(() => server, { port, host: hostname })
      yield* Effect.addFinalizer(() => Effect.sync(() => server.closeAllConnections()))
-      return { http, server }
+      return { http, server, scope: serverScope }
    }).pipe(
      Effect.provideService(Scope.Scope, serverScope),
      Effect.onError((cause) => Scope.close(serverScope, Exit.failCause(cause))),
@@ -190,10 +197,13 @@ const control = Effect.fnUntraced(function* (

 const healthResponse = Effect.fnUntraced(function* (status: Status.Interface) {
  const state = yield* status.current
-  return HttpServerResponse.jsonUnsafe({ healthy: true, version: InstallationVersion, pid: process.pid }, {
-    status: state.type === "ready" ? 200 : state.type === "failed" ? 500 : 503,
-    headers: state.type === "starting" || state.type === "stopping" ? { "retry-after": "1" } : undefined,
-  })
+  return HttpServerResponse.jsonUnsafe(
+    { healthy: true, version: InstallationVersion, pid: process.pid },
+    {
+      status: state.type === "ready" ? 200 : state.type === "failed" ? 500 : 503,
+      headers: state.type === "starting" || state.type === "stopping" ? { "retry-after": "1" } : undefined,
+    },
+  )
 })

 function unavailable(status: Status.State) {
@@ -22,6 +22,7 @@ interface Tab {
 const ComposerContext = createContext<{
  register: (tab: Tab) => () => void
  active: (id: string) => boolean
+  close: () => void
 }>()

 export function useComposerTab() {
@@ -73,6 +74,7 @@ export function Composer(props: ComposerProps) {
    active(id: string) {
      return props.open && store.active === id
    },
+    close,
  }

  const keymap = Keymap.use()
@@ -59,9 +59,11 @@ export function ShellTab(props: { sessionID: string }) {
        group: "Composer",
        bind: "up",
        run() {
-          const list = entries()
-          if (list.length === 0) return
-          setStore("selected", (prev) => (prev - 1 + list.length) % list.length)
+          if (store.selected === 0) {
+            composer.close()
+            return
+          }
+          setStore("selected", (prev) => prev - 1)
        },
      },
      {
@@ -160,9 +160,11 @@ export function SubagentsTab(props: { sessionID: string }) {
        group: "Composer",
        bind: "up",
        run() {
-          const list = entries()
-          if (list.length === 0) return
-          moveTo((store.selected - 1 + list.length) % list.length, true)
+          if (store.selected === 0) {
+            composer.close()
+            return
+          }
+          moveTo(store.selected - 1, true)
        },
      },
      {
Author	SHA1	Message	Date
Aiden Cline	d927f6fa8d	feat(plugin): add session options hook	2026-07-18 17:00:43 +00:00
opencode-agent[bot]	1f2de535aa	fix(ai): parse compatible reasoning deltas (#37558 ) Co-authored-by: Aiden Cline <63023139+rekram1-node@users.noreply.github.com>	2026-07-18 10:57:10 -05:00
opencode-agent[bot]	529d55b1c3	fix(core): remove session import cycle (#37596 ) Co-authored-by: James Long <17031+jlongster@users.noreply.github.com>	2026-07-18 13:24:47 +00:00
Aiden Cline	deb5b144c3	test(ai): record MiniMax messages compatibility (#37604 )	2026-07-17 23:22:09 -05:00
opencode-agent[bot]	cd3cca0006	feat(core): add runtime MCP controls (#37308 ) Co-authored-by: Aiden Cline <rekram1-node@users.noreply.github.com> Co-authored-by: Aiden Cline <aidenpcline@gmail.com>	2026-07-17 22:56:52 -05:00
Aiden Cline	08a7080e11	fix(tui): exit composer picker with up arrow (#37601 )	2026-07-17 22:22:00 -05:00
Dax Raad	f2579c41b6	docs: allow trusted cli installation	2026-07-17 20:49:42 -04:00
Dax Raad	c4830c147d	fix(core): defer cyclic layer dependencies	2026-07-17 20:25:21 -04:00
Dax Raad	22c23cb44c	fix(cli): reduce startup overhead	2026-07-17 20:14:04 -04:00
opencode-agent[bot]	60ce33cde8	fix(cli): simplify service registration lease (#37576 ) Co-authored-by: Dax Raad <826656+thdxr@users.noreply.github.com>	2026-07-17 19:47:17 -04:00
opencode-agent[bot]	6ea8247e0f	fix(cli): elect managed service by port bind (#37572 ) Co-authored-by: Dax Raad <thdxr@users.noreply.github.com>	2026-07-17 23:12:36 +00:00