fix(ai): preserve response reasoning items

Co-authored-by: rekram1-node <rekram1-node@users.noreply.github.com>
Co-authored-by: Andreas Holt <6665487+AndreasHolt@users.noreply.github.com>

bun.lock

@@ -969,6 +969,7 @@
         "mime-types": "3.0.2",
         "minimatch": "10.2.5",
         "npm-package-arg": "13.0.2",
+        "pacote": "21.5.1",
         "resolve.exports": "catalog:",
       },
       "devDependencies": {
@@ -978,6 +979,7 @@
         "@types/node": "catalog:",
         "@types/npm-package-arg": "6.1.4",
         "@types/npmcli__arborist": "6.3.3",
+        "@types/pacote": "11.1.8",
         "@typescript/native-preview": "catalog:",
       },
     },

package.json

@@ -5,10 +5,10 @@
   "version": "0.0.0",
   "private": true,
   "type": "module",
-  "packageManager": "bun@1.3.14",
+  "packageManager": "bun@1.4.0",
   "scripts": {
     "dev": "bun run --cwd packages/cli --conditions=browser src/index.ts",
-    "dev:live": "OPENCODE_TUI_CHANNEL=dev OPENCODE_PASSWORD=\"$(opencode2 service get password)\" bun run dev --server \"$(opencode2 service status)\"",
+    "dev:live": "sh -c 'OPENCODE_TUI_CHANNEL=dev OPENCODE_PASSWORD=\"$(opencode2 service get password)\" exec bun run dev \"$@\" --server \"$(opencode2 service status)\"' --",
     "dev:desktop": "bun --cwd packages/desktop dev",
     "dev:web": "bun --cwd packages/app dev",
     "dev:console": "ulimit -n 10240 2>/dev/null; bun run --cwd packages/console/app dev",

packages/ai/src/protocols/bedrock-converse.ts

@@ -510,9 +510,10 @@ interface ParserState {
   readonly tools: ToolStream.State<number>
   readonly finishedTools: ReadonlySet<number>
   // Bedrock splits the finish into `messageStop` (carries `stopReason`) and
-  // `metadata` (carries usage). Hold the terminal event in state so `onHalt`
-  // can emit exactly one finish after both chunks have had a chance to arrive.
-  readonly pendingFinish: { readonly reason: FinishReasonDetails; readonly usage?: Usage } | undefined
+  // `metadata` (carries usage). Hold both in state so `onHalt` can emit exactly
+  // one finish after both chunks have had a chance to arrive.
+  readonly finishReason: FinishReasonDetails | undefined
+  readonly usage: Usage | undefined
   readonly hasToolCalls: boolean
   readonly lifecycle: Lifecycle.State
   readonly reasoningSignatures: Readonly<Record<number, string>>
@@ -692,12 +693,9 @@ const step = (state: ParserState, event: BedrockEvent) =>
       return [
         {
           ...state,
-          pendingFinish: {
-            reason: {
-              normalized: mapFinishReason(event.messageStop.stopReason),
-              raw: event.messageStop.stopReason,
-            },
-            usage: state.pendingFinish?.usage,
+          finishReason: {
+            normalized: mapFinishReason(event.messageStop.stopReason),
+            raw: event.messageStop.stopReason,
           },
         },
         [],
@@ -705,14 +703,11 @@ const step = (state: ParserState, event: BedrockEvent) =>
     }
 
     if (event.metadata) {
-      const usage = mapUsage(event.metadata.usage, state.providerMetadataKey) ?? state.pendingFinish?.usage
+      const usage = mapUsage(event.metadata.usage, state.providerMetadataKey) ?? state.usage
       return [
         {
           ...state,
-          pendingFinish: {
-            reason: state.pendingFinish?.reason ?? { normalized: "stop" },
-            usage,
-          },
+          usage,
         },
         [],
       ] as const
@@ -736,18 +731,18 @@ const step = (state: ParserState, event: BedrockEvent) =>
 const framing = BedrockEventStream.framing(ADAPTER)
 
 const onHalt = (state: ParserState): ReadonlyArray<LLMEvent> => {
-  if (!state.pendingFinish) return []
+  if (!state.finishReason) return []
   const normalized = (() => {
-    if (state.pendingFinish.reason.normalized === "stop" && state.hasToolCalls) return "tool-calls"
-    return state.pendingFinish.reason.normalized
+    if (state.finishReason.normalized === "stop" && state.hasToolCalls) return "tool-calls"
+    return state.finishReason.normalized
   })()
   const events: LLMEvent[] = []
   Lifecycle.finish(state.lifecycle, events, {
     reason: {
-      ...state.pendingFinish.reason,
+      ...state.finishReason,
       normalized,
     },
-    usage: state.pendingFinish.usage,
+    usage: state.usage,
   })
   return events
 }
@@ -771,7 +766,8 @@ export const protocol = Protocol.make({
       providerMetadataKey: request.model.route.providerMetadataKey ?? String(request.model.provider),
       tools: ToolStream.empty<number>(),
       finishedTools: new Set<number>(),
-      pendingFinish: undefined,
+      finishReason: undefined,
+      usage: undefined,
       hasToolCalls: false,
       lifecycle: Lifecycle.initial(),
       reasoningSignatures: {},

packages/ai/src/protocols/gemini.ts

@@ -609,18 +609,27 @@ const finish = (state: ParserState): ReadonlyArray<LLMEvent> => {
 }
 
 const step = (state: ParserState, event: GeminiEvent) => {
-  if (ProviderShared.isRecord(event.error) && typeof event.error.message === "string") {
+  if (ProviderShared.isRecord(event.error)) {
     const body = ProviderShared.encodeJson(event)
     return Effect.fail(
       new AIError({
         reason: classifyProviderFailure({
-          message: event.error.message,
+          message:
+            typeof event.error.message === "string" && event.error.message.length > 0
+              ? event.error.message
+              : typeof event.error.status === "string" && event.error.status.length > 0
+                ? event.error.status
+                : "Gemini provider error",
           status: typeof event.error.code === "number" ? event.error.code : undefined,
           rawBody: body,
         }),
       }),
     )
   }
+  if ("error" in event)
+    return Effect.fail(
+      ProviderShared.eventError(state.route, `Invalid ${state.route} stream event`, ProviderShared.encodeJson(event)),
+    )
   const nextState = {
     ...state,
     promptFeedback: event.promptFeedback ?? state.promptFeedback,

packages/ai/src/protocols/open-responses.ts

@@ -72,6 +72,11 @@ const OpenResponsesReasoningSummaryText = Schema.Struct({
   text: Schema.String,
 })
 
+const OpenResponsesReasoningText = Schema.Struct({
+  type: Schema.tag("reasoning_text"),
+  text: Schema.String,
+})
+
 const OpenResponsesReasoningItem = Schema.Struct({
   type: Schema.tag("reasoning"),
   id: Schema.optionalKey(Schema.String),
@@ -79,6 +84,18 @@ const OpenResponsesReasoningItem = Schema.Struct({
   encrypted_content: optionalNull(Schema.String),
 })
 
+export const CompletedReasoningItem = Schema.StructWithRest(
+  Schema.Struct({
+    type: Schema.tag("reasoning"),
+    id: Schema.String,
+    summary: Schema.Array(OpenResponsesReasoningSummaryText),
+    content: Schema.optional(Schema.Array(OpenResponsesReasoningText)),
+    encrypted_content: optionalNull(Schema.String),
+  }),
+  [Schema.Record(Schema.String, Schema.Unknown)],
+)
+export type CompletedReasoningItem = Schema.Schema.Type<typeof CompletedReasoningItem>
+
 const OpenResponsesWebSearchCall = Schema.StructWithRest(
   Schema.Struct({
     type: Schema.tag("web_search_call"),
@@ -176,14 +193,15 @@ export const InputItem = Schema.Union([
   HostedToolItem,
 ])
 type OpenResponsesInputItem = Schema.Schema.Type<typeof InputItem>
-export type ExtendedHostedToolItem = {
+export type HostedToolReplayItem = {
   readonly type: string
   readonly id: string
   readonly [key: string]: unknown
 }
 type LoweredInputItem =
   | OpenResponsesInputItem
-  | ExtendedHostedToolItem
+  | HostedToolReplayItem
+  | CompletedReasoningItem
   | {
       readonly type: "message"
       readonly id?: string
@@ -345,6 +363,7 @@ export const Event = Schema.StructWithRest(
     text: Schema.optional(Schema.String),
     item_id: Schema.optional(Schema.String),
     output_index: Schema.optional(Schema.Number),
+    content_index: Schema.optional(Schema.Number),
     summary_index: Schema.optional(Schema.Number),
     // OutputItemAdded/Done permit a null item in the Open Responses OpenAPI schema.
     item: optionalNull(StreamItem),
@@ -373,7 +392,7 @@ export const Event = Schema.StructWithRest(
 )
 export type Event = Schema.Schema.Type<typeof Event>
 
-export interface Extension {
+export interface ProviderAdapter {
   readonly id: string
   readonly name: string
   readonly lowerMedia?: (input: {
@@ -381,10 +400,11 @@ export interface Extension {
     readonly media: ProviderShared.NormalizedMedia
     readonly request: LLMRequest
   }) => MediaInput | undefined
-  readonly lowerHostedToolItem?: (item: unknown) => ExtendedHostedToolItem | undefined
+  readonly restoreHostedToolItem?: (item: unknown) => HostedToolReplayItem | undefined
+  readonly restoreReasoningItem?: (item: unknown) => CompletedReasoningItem | undefined
 }
 
-const BASE: Extension = { id: ADAPTER, name: NAME }
+const BASE_ADAPTER: ProviderAdapter = { id: ADAPTER, name: NAME }
 
 export interface ParserState {
   readonly id: string
@@ -397,22 +417,18 @@ export interface ParserState {
   readonly lifecycle: Lifecycle.State
   readonly outputItems: Readonly<Record<number, string>>
   readonly message: { readonly id: string; readonly phase: MessagePhase | null | undefined } | undefined
+  // Item ids are response-scoped identities. Keep completed ids tombstoned so
+  // reconnect replay cannot reopen fragments already emitted downstream.
+  readonly completedMessages: ReadonlySet<string>
   readonly reasoningItems: Readonly<Record<string, ReasoningStreamItem>>
 }
 
-type ReasoningSummaryStatus = "active" | "can-conclude" | "concluded"
-
 interface ReasoningStreamItem {
   readonly open: boolean
   readonly encryptedContent: string | null | undefined
-  // Keyed by the wire protocol's numeric `summary_index`. JS object keys coerce to
-  // strings, but typing the map as `Record<number, ...>` documents intent
-  // and matches the wire field.
-  readonly summaryParts: Readonly<Record<number, ReasoningSummaryStatus>>
-  // Summary indexes that received at least one streamed delta. The `:0` block
-  // is started eagerly when the item opens, so block existence cannot tell
-  // whether a `.done` final would duplicate streamed text.
-  readonly deltaIndexes: ReadonlySet<number>
+  readonly streamedText: string
+  readonly emittedRawIndexes: ReadonlySet<number>
+  readonly emittedSummaryIndexes: ReadonlySet<number>
 }
 
 // =============================================================================
@@ -463,9 +479,22 @@ const lowerToolCall = (part: ToolCallPart, providerMetadataKey: string): OpenRes
   }
 }
 
-const lowerReasoning = (part: ReasoningPart, providerMetadataKey: string): OpenResponsesReasoningInput | undefined => {
+const lowerReasoning = (
+  part: ReasoningPart,
+  providerMetadataKey: string,
+  adapter: ProviderAdapter,
+): OpenResponsesReasoningInput | CompletedReasoningItem | undefined => {
   const metadata = part.providerMetadata?.[providerMetadataKey]
   if (!ProviderShared.isRecord(metadata)) return undefined
+  const restored = adapter.restoreReasoningItem?.(metadata.reasoningItem)
+  if (restored) return restored
+  if (!adapter.restoreReasoningItem && Schema.is(CompletedReasoningItem)(metadata.reasoningItem))
+    return {
+      type: "reasoning",
+      id: metadata.reasoningItem.id,
+      summary: [...metadata.reasoningItem.summary],
+      encrypted_content: metadata.reasoningItem.encrypted_content,
+    }
   const id = itemID(part.providerMetadata, providerMetadataKey)
   const encryptedContent =
     typeof metadata.reasoningEncryptedContent === "string" || metadata.reasoningEncryptedContent === null
@@ -482,12 +511,12 @@ const lowerReasoning = (part: ReasoningPart, providerMetadataKey: string): OpenR
 const lowerMedia = Effect.fn("OpenResponses.lowerMedia")(function* (
   part: MediaPart,
   request: LLMRequest,
-  extension: Extension,
+  adapter: ProviderAdapter,
   target: "message" | "tool-result",
 ) {
   const media = ProviderShared.normalizeMedia(part)
-  const extended = extension.lowerMedia?.({ part, media, request })
-  if (extended) return extended
+  const providerMedia = adapter.lowerMedia?.({ part, media, request })
+  if (providerMedia) return providerMedia
   const url =
     typeof part.data === "string" && (part.data.startsWith("https://") || part.data.startsWith("http://"))
       ? part.data
@@ -507,17 +536,17 @@ const lowerMedia = Effect.fn("OpenResponses.lowerMedia")(function* (
 const lowerUserContent = Effect.fnUntraced(function* (
   part: LLMRequest["messages"][number]["content"][number],
   request: LLMRequest,
-  extension: Extension,
+  adapter: ProviderAdapter,
 ) {
   if (part.type === "text") return { type: "input_text" as const, text: part.text }
-  if (part.type === "media") return yield* lowerMessageMedia(part, request, extension)
-  return yield* ProviderShared.unsupportedContent(extension.name, "user", ["text", "media"])
+  if (part.type === "media") return yield* lowerMessageMedia(part, request, adapter)
+  return yield* ProviderShared.unsupportedContent(adapter.name, "user", ["text", "media"])
 })
 
-const lowerMessageMedia = Effect.fnUntraced(function* (part: MediaPart, request: LLMRequest, extension: Extension) {
-  const lowered = yield* lowerMedia(part, request, extension, "message")
+const lowerMessageMedia = Effect.fnUntraced(function* (part: MediaPart, request: LLMRequest, adapter: ProviderAdapter) {
+  const lowered = yield* lowerMedia(part, request, adapter, "message")
   if (lowered.type === "input_video")
-    return yield* ProviderShared.invalidRequest(`${extension.name} user messages do not support input_video`)
+    return yield* ProviderShared.invalidRequest(`${adapter.name} user messages do not support input_video`)
   return lowered
 })
 
@@ -526,13 +555,13 @@ const lowerMessageMedia = Effect.fnUntraced(function* (part: MediaPart, request:
 const lowerToolResultContentItem = Effect.fnUntraced(function* (
   item: Content,
   request: LLMRequest,
-  extension: Extension,
+  adapter: ProviderAdapter,
 ) {
   if (item.type === "text") return { type: "input_text" as const, text: item.text }
   return yield* lowerMedia(
     { type: "media", mediaType: item.mime, data: item.uri, filename: item.name },
     request,
-    extension,
+    adapter,
     "tool-result",
   )
 })
@@ -540,30 +569,33 @@ const lowerToolResultContentItem = Effect.fnUntraced(function* (
 const lowerHostedToolResultContentItem = Effect.fnUntraced(function* (
   item: Content,
   request: LLMRequest,
-  extension: Extension,
+  adapter: ProviderAdapter,
 ) {
   if (item.type === "text") return { type: "input_text" as const, text: item.text }
   return yield* lowerMessageMedia(
     { type: "media", mediaType: item.mime, data: item.uri, filename: item.name },
     request,
-    extension,
+    adapter,
   )
 })
 
 const lowerToolResultOutput = Effect.fnUntraced(function* (
   part: ToolResultPart,
   request: LLMRequest,
-  extension: Extension,
+  adapter: ProviderAdapter,
 ) {
   // Text/json/error results are encoded as a plain string for backward
   // compatibility with existing cassettes and provider expectations.
   if (part.result.type !== "content") return ProviderShared.toolResultText(part)
   // Preserve the narrowed array element type when compiled through a consumer package.
   const content: ReadonlyArray<Content> = part.result.value
-  return yield* Effect.forEach(content, (item) => lowerToolResultContentItem(item, request, extension))
+  return yield* Effect.forEach(content, (item) => lowerToolResultContentItem(item, request, adapter))
 })
 
-const lowerMessages = Effect.fn("OpenResponses.lowerMessages")(function* (request: LLMRequest, extension: Extension) {
+const lowerMessages = Effect.fn("OpenResponses.lowerMessages")(function* (
+  request: LLMRequest,
+  adapter: ProviderAdapter,
+) {
   const input: LoweredInputItem[] = []
   const providerMetadataKey = request.model.route.providerMetadataKey ?? "openresponses"
 
@@ -571,13 +603,13 @@ const lowerMessages = Effect.fn("OpenResponses.lowerMessages")(function* (reques
     if (message.role === "system") {
       input.push({
         role: "developer",
-        content: ProviderShared.joinText(yield* ProviderShared.systemUpdateText(extension.name, message)),
+        content: ProviderShared.joinText(yield* ProviderShared.systemUpdateText(adapter.name, message)),
       })
       continue
     }
 
     if (message.role === "user") {
-      const content = yield* Effect.forEach(message.content, (part) => lowerUserContent(part, request, extension))
+      const content = yield* Effect.forEach(message.content, (part) => lowerUserContent(part, request, adapter))
       if (content.length > 0) input.push({ role: "user", content })
       continue
     }
@@ -617,17 +649,18 @@ const lowerMessages = Effect.fn("OpenResponses.lowerMessages")(function* (reques
         }
         if (part.type === "reasoning") {
           flushText()
-          const reasoning = lowerReasoning(part, providerMetadataKey)
+          const reasoning = lowerReasoning(part, providerMetadataKey, adapter)
           if (!reasoning) continue
           const existing = reasoning.id === undefined ? undefined : reasoningItems[reasoning.id]
           if (existing) {
             existing.summary.push(...reasoning.summary)
-            if (typeof reasoning.encrypted_content === "string")
+            if (reasoning.encrypted_content === null || typeof reasoning.encrypted_content === "string")
               existing.encrypted_content = reasoning.encrypted_content
             continue
           }
-          if (reasoning.id !== undefined) reasoningItems[reasoning.id] = reasoning
-          input.push(reasoning)
+          const converted = { ...reasoning, summary: [...reasoning.summary] }
+          if (reasoning.id !== undefined) reasoningItems[reasoning.id] = converted
+          input.push(converted)
           continue
         }
         if (part.type === "tool-call") {
@@ -644,7 +677,7 @@ const lowerMessages = Effect.fn("OpenResponses.lowerMessages")(function* (reques
               ? undefined
               : Schema.is(HostedToolItem)(part.result.value)
                 ? part.result.value
-                : extension.lowerHostedToolItem?.(part.result.value)
+                : adapter.restoreHostedToolItem?.(part.result.value)
           if (id !== undefined && hosted?.id === id) {
             if (!hostedToolItems.has(id)) {
               input.push(hosted)
@@ -658,13 +691,11 @@ const lowerMessages = Effect.fn("OpenResponses.lowerMessages")(function* (reques
               : [{ type: "text", text: ProviderShared.toolResultText(part) }]
           input.push({
             role: "user",
-            content: yield* Effect.forEach(content, (item) =>
-              lowerHostedToolResultContentItem(item, request, extension),
-            ),
+            content: yield* Effect.forEach(content, (item) => lowerHostedToolResultContentItem(item, request, adapter)),
           })
           continue
         }
-        return yield* ProviderShared.unsupportedContent(extension.name, "assistant", [
+        return yield* ProviderShared.unsupportedContent(adapter.name, "assistant", [
           "text",
           "reasoning",
           "tool-call",
@@ -677,11 +708,11 @@ const lowerMessages = Effect.fn("OpenResponses.lowerMessages")(function* (reques
 
     for (const part of message.content) {
       if (!ProviderShared.supportsContent(part, ["tool-result"]))
-        return yield* ProviderShared.unsupportedContent(extension.name, "tool", ["tool-result"])
+        return yield* ProviderShared.unsupportedContent(adapter.name, "tool", ["tool-result"])
       input.push({
         type: "function_call_output",
         call_id: part.id,
-        output: yield* lowerToolResultOutput(part, request, extension),
+        output: yield* lowerToolResultOutput(part, request, adapter),
       })
     }
   }
@@ -733,28 +764,28 @@ const allowedToolChoice = (request: LLMRequest) => {
   }
 }
 
-export const fromRequestWithExtension = Effect.fn("OpenResponses.fromRequestWithExtension")(function* (
+export const fromRequestWithAdapter = Effect.fn("OpenResponses.fromRequestWithAdapter")(function* (
   request: LLMRequest,
-  extension: Extension,
+  adapter: ProviderAdapter,
 ) {
   const generation = request.generation
   const toolSchemaCompatibility = request.model.compatibility?.toolSchema
   return {
     model: request.model.id,
-    input: yield* lowerMessages(request, extension),
+    input: yield* lowerMessages(request, adapter),
     tools:
       request.tools.length === 0
         ? undefined
         : yield* Effect.forEach(request.tools, (tool) =>
             lowerTool(
-              extension.name,
+              adapter.name,
               tool,
               ToolSchemaProjection.modelCompatibility(tool.inputSchema, toolSchemaCompatibility),
             ),
           ),
     tool_choice:
       allowedToolChoice(request) ??
-      (request.toolChoice ? yield* lowerToolChoice(extension.name, request.toolChoice) : undefined),
+      (request.toolChoice ? yield* lowerToolChoice(adapter.name, request.toolChoice) : undefined),
     stream: true as const,
     max_output_tokens: generation?.maxTokens,
     temperature: generation?.temperature,
@@ -768,7 +799,7 @@ export const fromRequestWithExtension = Effect.fn("OpenResponses.fromRequestWith
 const decodeBody = ProviderShared.validateWith(Schema.decodeUnknownEffect(OpenResponsesBody))
 
 export const fromRequest = Effect.fn("OpenResponses.fromRequest")(function* (request: LLMRequest) {
-  return yield* decodeBody(yield* fromRequestWithExtension(request, BASE))
+  return yield* decodeBody(yield* fromRequestWithAdapter(request, BASE_ADAPTER))
 })
 
 // =============================================================================
@@ -861,39 +892,22 @@ const joinReasoningText = (parts: ReadonlyArray<string | undefined>) => {
 export const outputItemID = (state: ParserState, event: Event) =>
   event.output_index === undefined ? event.item_id : (state.outputItems[event.output_index] ?? event.item_id)
 
-const startReasoningSummaryPart = (state: ParserState, itemID: string, index: number): StepResult => {
-  const item = state.reasoningItems[itemID]
-  if (!item?.open || index === 0 || item.summaryParts[index] !== undefined) return [state, NO_EVENTS]
-
+const appendReasoningText = (
+  state: ParserState,
+  itemID: string,
+  item: ReasoningStreamItem,
+  text: string,
+): StepResult => {
   const events: LLMEvent[] = []
-  const lifecycle = Object.entries(item.summaryParts)
-    .filter((entry) => entry[1] !== "concluded")
-    .reduce(
-      (lifecycle, entry) =>
-        Lifecycle.reasoningEnd(lifecycle, events, `${itemID}:${entry[0]}`, providerMetadata(state, { itemId: itemID })),
-      state.lifecycle,
-    )
   return [
     {
       ...state,
-      lifecycle: Lifecycle.reasoningStart(
-        lifecycle,
-        events,
-        `${itemID}:${index}`,
-        providerMetadata(state, { itemId: itemID, reasoningEncryptedContent: item.encryptedContent ?? null }),
-      ),
+      lifecycle: Lifecycle.reasoningDelta(state.lifecycle, events, itemID, text),
       reasoningItems: {
         ...state.reasoningItems,
         [itemID]: {
           ...item,
-          summaryParts: {
-            ...Object.fromEntries(
-              Object.entries(item.summaryParts).map((entry) =>
-                entry[1] === "concluded" ? entry : [entry[0], "concluded" as const],
-              ),
-            ),
-            [index]: "active",
-          },
+          streamedText: item.streamedText + text,
         },
       },
     },
@@ -901,41 +915,58 @@ const startReasoningSummaryPart = (state: ParserState, itemID: string, index: nu
   ]
 }
 
-export const onReasoningDelta = (state: ParserState, event: Event, itemID: string): StepResult => {
+type ReasoningRawDeltaEvent = Pick<Event, "content_index" | "delta">
+type ReasoningRawDoneEvent = Pick<Event, "content_index" | "text">
+type ReasoningSummaryDeltaEvent = Pick<Event, "delta" | "summary_index">
+type ReasoningSummaryDoneEvent = Pick<Event, "summary_index" | "text">
+
+const onReasoningRawDelta = (state: ParserState, event: ReasoningRawDeltaEvent, itemID: string): StepResult => {
   const item = state.reasoningItems[itemID]
   if (!event.delta || !item?.open) return [state, NO_EVENTS]
-  const index = event.summary_index ?? 0
-  if (item.summaryParts[index] === "concluded") return [state, NO_EVENTS]
-  const [started, emitted] = startReasoningSummaryPart(state, itemID, index)
-  const current = started.reasoningItems[itemID]
-  if (!current) return [started, emitted]
-  const events: LLMEvent[] = [...emitted]
-  return [
-    {
-      ...started,
-      lifecycle: Lifecycle.reasoningDelta(started.lifecycle, events, `${itemID}:${index}`, event.delta),
-      reasoningItems: {
-        ...started.reasoningItems,
-        [itemID]: { ...current, deltaIndexes: new Set([...current.deltaIndexes, index]) },
-      },
-    },
-    events,
-  ]
+  return appendReasoningText(
+    state,
+    itemID,
+    { ...item, emittedRawIndexes: new Set([...item.emittedRawIndexes, event.content_index ?? 0]) },
+    event.delta,
+  )
 }
 
-// Some compatible gateways emit a reasoning final without streaming any
-// deltas, mirroring `response.output_text.done`. Reconcile the complete text
-// as a single delta unless that summary index already streamed one.
-export const onReasoningDone = (state: ParserState, event: Event, itemID: string): StepResult => {
+const onReasoningRawDone = (state: ParserState, event: ReasoningRawDoneEvent, itemID: string): StepResult => {
   const item = state.reasoningItems[itemID]
-  if (!item?.open || typeof event.text !== "string") return [state, NO_EVENTS]
-  const index = event.summary_index ?? 0
-  if (item.deltaIndexes.has(index)) return [state, NO_EVENTS]
-  return onReasoningDelta(state, { ...event, delta: event.text }, itemID)
+  if (!event.text || !item?.open) return [state, NO_EVENTS]
+  const index = event.content_index ?? 0
+  if (item.emittedRawIndexes.has(index)) return [state, NO_EVENTS]
+  return appendReasoningText(
+    state,
+    itemID,
+    { ...item, emittedRawIndexes: new Set([...item.emittedRawIndexes, index]) },
+    event.text,
+  )
 }
 
-const reasoningMetadata = (state: ParserState, item: StreamItem & { id: string }) =>
-  providerMetadata(state, { itemId: item.id, reasoningEncryptedContent: item.encrypted_content ?? null })
+const onReasoningSummaryDelta = (state: ParserState, event: ReasoningSummaryDeltaEvent, itemID: string): StepResult => {
+  const item = state.reasoningItems[itemID]
+  if (!event.delta || !item?.open) return [state, NO_EVENTS]
+  return appendReasoningText(
+    state,
+    itemID,
+    { ...item, emittedSummaryIndexes: new Set([...item.emittedSummaryIndexes, event.summary_index ?? 0]) },
+    event.delta,
+  )
+}
+
+const onReasoningSummaryDone = (state: ParserState, event: ReasoningSummaryDoneEvent, itemID: string): StepResult => {
+  const item = state.reasoningItems[itemID]
+  if (!event.text || !item?.open) return [state, NO_EVENTS]
+  const index = event.summary_index ?? 0
+  if (item.emittedSummaryIndexes.has(index)) return [state, NO_EVENTS]
+  return appendReasoningText(
+    state,
+    itemID,
+    { ...item, emittedSummaryIndexes: new Set([...item.emittedSummaryIndexes, index]) },
+    event.text,
+  )
+}
 
 // Responses APIs normally stream reasoning items in this order:
 //   `output_item.added` (reasoning) →
@@ -944,19 +975,21 @@ const reasoningMetadata = (state: ParserState, item: StreamItem & { id: string }
 //     `reasoning_summary_part.done` (index=0) →
 //     (repeat for index>0) →
 //   `output_item.done` (reasoning).
-// `onOutputItemAdded` seeds the per-item entry, while each later part start is
-// also an implicit boundary for the previous part. This keeps the common event
-// lifecycle ordered when a compatible provider omits or delays a part-done event.
+// `onOutputItemAdded` seeds one lifecycle for the complete provider item.
 const onOutputItemAdded = (state: ParserState, event: Event): StepResult => {
   const item = event.item
   if (item?.type === "message" && item.id !== undefined) {
     const itemID = item.id
+    if (state.completedMessages.has(itemID)) return [state, NO_EVENTS]
     const phase = messagePhase(item.phase)
+    const completedMessages = new Set(state.completedMessages)
+    if (state.message !== undefined && state.message.id !== itemID) completedMessages.add(state.message.id)
     // A new message closes earlier messages, including ones that never streamed.
     const events: LLMEvent[] = []
     const lifecycle = [...state.lifecycle.text]
       .filter((id) => id !== itemID)
       .reduce((lifecycle, id) => {
+        completedMessages.add(id)
         const openPhase = state.message?.id === id ? state.message.phase : undefined
         return Lifecycle.textEnd(
           lifecycle,
@@ -969,6 +1002,7 @@ const onOutputItemAdded = (state: ParserState, event: Event): StepResult => {
       {
         ...state,
         lifecycle,
+        completedMessages,
         message: {
           id: itemID,
           phase: phase === undefined && state.message?.id === itemID ? state.message.phase : phase,
@@ -983,14 +1017,15 @@ const onOutputItemAdded = (state: ParserState, event: Event): StepResult => {
     return [
       {
         ...state,
-        lifecycle: Lifecycle.reasoningStart(state.lifecycle, events, `${item.id}:0`, reasoningMetadata(state, item)),
+        lifecycle: Lifecycle.reasoningStart(state.lifecycle, events, item.id),
         reasoningItems: {
           ...state.reasoningItems,
           [item.id]: {
             open: true,
             encryptedContent: item.encrypted_content,
-            summaryParts: { 0: "active" },
-            deltaIndexes: new Set(),
+            streamedText: "",
+            emittedRawIndexes: new Set(),
+            emittedSummaryIndexes: new Set(),
           },
         },
       },
@@ -1019,34 +1054,6 @@ const onOutputItemAdded = (state: ParserState, event: Event): StepResult => {
   ]
 }
 
-const onReasoningSummaryPartAdded = (state: ParserState, event: Event): StepResult => {
-  if (event.item_id === undefined || event.summary_index === undefined) return [state, NO_EVENTS]
-  return startReasoningSummaryPart(state, event.item_id, event.summary_index)
-}
-
-const onReasoningSummaryPartDone = (state: ParserState, event: Event): StepResult => {
-  if (event.item_id === undefined || event.summary_index === undefined) return [state, NO_EVENTS]
-  const item = state.reasoningItems[event.item_id]
-  if (!item?.open) return [state, NO_EVENTS]
-  if (item.summaryParts[event.summary_index] !== "active") return [state, NO_EVENTS]
-  return [
-    {
-      ...state,
-      reasoningItems: {
-        ...state.reasoningItems,
-        [event.item_id]: {
-          ...item,
-          summaryParts: {
-            ...item.summaryParts,
-            [event.summary_index]: "can-conclude",
-          },
-        },
-      },
-    },
-    NO_EVENTS,
-  ]
-}
-
 const onFunctionCallArgumentsDelta = Effect.fn("OpenResponses.onFunctionCallArgumentsDelta")(function* (
   state: ParserState,
   event: Event,
@@ -1085,7 +1092,12 @@ const onOutputItemDone = Effect.fn("OpenResponses.onOutputItemDone")(function* (
   if (!item) return [state, NO_EVENTS] satisfies StepResult
 
   if (item.type === "message" && item.id !== undefined) {
-    const message = state.message?.id === item.id ? state.message : undefined
+    if (state.completedMessages.has(item.id)) return [state, NO_EVENTS] satisfies StepResult
+    const completedMessages = new Set(state.completedMessages)
+    completedMessages.add(item.id)
+    if (state.message !== undefined && state.message.id !== item.id)
+      return [{ ...state, completedMessages }, NO_EVENTS] satisfies StepResult
+    const message = state.message
     const itemPhase = messagePhase(item.phase)
     const phase = itemPhase === undefined ? message?.phase : itemPhase
     const parts: ReadonlyArray<unknown> = Array.isArray(item.content) ? item.content : []
@@ -1098,13 +1110,13 @@ const onOutputItemDone = Effect.fn("OpenResponses.onOutputItemDone")(function* (
     const text = content.length > 0 ? content.join("") : undefined
     const metadata = providerMetadata(state, { itemId: item.id, ...(phase === undefined ? {} : { phase }) })
     const events: LLMEvent[] = []
-    const lifecycle =
-      message && text ? Lifecycle.textStart(state.lifecycle, events, item.id, metadata) : state.lifecycle
+    const lifecycle = text ? Lifecycle.textStart(state.lifecycle, events, item.id, metadata) : state.lifecycle
     return [
       {
         ...state,
         lifecycle: Lifecycle.textEnd(lifecycle, events, item.id, metadata, text),
-        message: message ? undefined : state.message,
+        completedMessages,
+        message: undefined,
       },
       events,
     ] satisfies StepResult
@@ -1160,7 +1172,15 @@ const onOutputItemDone = Effect.fn("OpenResponses.onOutputItemDone")(function* (
 
   if (isReasoningItem(item)) {
     if (state.reasoningItems[item.id]?.open === false) return [state, NO_EVENTS] satisfies StepResult
-    const metadata = reasoningMetadata(state, item)
+    const tracked = state.reasoningItems[item.id]
+    if (!tracked && state.lifecycle.reasoning.size > 0)
+      return yield* ProviderShared.eventError(state.id, "reasoning completed before the previous item ended")
+    const completed = Schema.is(CompletedReasoningItem)(item) ? item : undefined
+    const metadata = providerMetadata(state, {
+      itemId: item.id,
+      reasoningEncryptedContent: item.encrypted_content ?? tracked?.encryptedContent ?? null,
+      ...(completed ? { reasoningItem: completed } : {}),
+    })
     const summaryParts: ReadonlyArray<unknown> = Array.isArray(item.summary) ? item.summary : []
     const summary: Array<string | undefined> = []
     for (const part of summaryParts) {
@@ -1174,63 +1194,41 @@ const onOutputItemDone = Effect.fn("OpenResponses.onOutputItemDone")(function* (
       const decoded = Option.getOrUndefined(decodeReasoningPart(part))
       if (decoded) content.push(decoded.text)
     }
-    const itemText = joinReasoningText(summary) ?? joinReasoningText(content)
+    const text = joinReasoningText(summary) ?? joinReasoningText(content) ?? tracked?.streamedText
     const events: LLMEvent[] = []
-    const reasoningItem = state.reasoningItems[item.id]
-    if (reasoningItem) {
-      const fragments = Object.entries(reasoningItem.summaryParts)
-      let lifecycle = state.lifecycle
-      for (const [index, status] of fragments) {
-        if (status === "concluded") continue
-        // Do not repeat earlier summaries that were already emitted as separate fragments.
-        const finalText = fragments.length === 1 ? itemText : summary[Number(index)]
-        lifecycle = Lifecycle.reasoningEnd(lifecycle, events, `${item.id}:${index}`, metadata, finalText || undefined)
-      }
+    if (tracked) {
       return [
         {
           ...state,
-          lifecycle,
+          lifecycle: Lifecycle.reasoningEnd(state.lifecycle, events, item.id, metadata, text),
           reasoningItems: {
             ...state.reasoningItems,
             [item.id]: {
-              ...reasoningItem,
+              ...tracked,
               open: false,
-              encryptedContent: item.encrypted_content ?? reasoningItem.encryptedContent,
-            },
-          },
-        },
-        events,
-      ] satisfies StepResult
-    }
-    if (!state.lifecycle.reasoning.has(item.id)) {
-      const lifecycle = Lifecycle.stepStart(state.lifecycle, events)
-      events.push(LLMEvent.reasoningStart({ id: item.id, providerMetadata: metadata }))
-      events.push(
-        LLMEvent.reasoningEnd({
-          id: item.id,
-          providerMetadata: metadata,
-          text: itemText,
-        }),
-      )
-      return [
-        {
-          ...state,
-          lifecycle,
-          reasoningItems: {
-            ...state.reasoningItems,
-            [item.id]: {
-              open: false,
-              encryptedContent: item.encrypted_content,
-              summaryParts: { 0: "concluded" },
-              deltaIndexes: new Set(),
+              encryptedContent: item.encrypted_content ?? tracked.encryptedContent,
             },
           },
         },
         events,
       ] satisfies StepResult
     }
+    const started = Lifecycle.reasoningStart(state.lifecycle, events, item.id)
     return [
-      { ...state, lifecycle: Lifecycle.reasoningEnd(state.lifecycle, events, item.id, metadata) },
+      {
+        ...state,
+        lifecycle: Lifecycle.reasoningEnd(started, events, item.id, metadata, text),
+        reasoningItems: {
+          ...state.reasoningItems,
+          [item.id]: {
+            open: false,
+            encryptedContent: item.encrypted_content,
+            streamedText: text ?? "",
+            emittedRawIndexes: new Set(),
+            emittedSummaryIndexes: new Set(),
+          },
+        },
+      },
       events,
     ] satisfies StepResult
   }
@@ -1335,25 +1333,29 @@ export const step = (state: ParserState, input: Event) => {
         : onOutputTextDone(state, { ...event, text: value }, event.item_id),
     )
   }
-  if (event.type === "response.reasoning.delta" || event.type === "response.reasoning_summary_text.delta") {
+  if (event.type === "response.reasoning.delta" || event.type === "response.reasoning_text.delta") {
     if (event.item_id === undefined) return ProviderShared.eventError(state.id, `${event.type} is missing item_id`)
-    return Effect.succeed(onReasoningDelta(state, event, event.item_id))
+    return Effect.succeed(onReasoningRawDelta(state, event, event.item_id))
   }
-  if (
-    event.type === "response.reasoning.done" ||
-    event.type === "response.reasoning_summary_text.done" ||
-    event.type === "response.reasoning_text.done"
-  ) {
+  if (event.type === "response.reasoning.done" || event.type === "response.reasoning_text.done") {
     if (event.item_id === undefined) return ProviderShared.eventError(state.id, `${event.type} is missing item_id`)
-    return Effect.succeed(onReasoningDone(state, event, event.item_id))
+    return Effect.succeed(onReasoningRawDone(state, event, event.item_id))
+  }
+  if (event.type === "response.reasoning_summary_text.delta") {
+    if (event.item_id === undefined) return ProviderShared.eventError(state.id, `${event.type} is missing item_id`)
+    return Effect.succeed(onReasoningSummaryDelta(state, event, event.item_id))
+  }
+  if (event.type === "response.reasoning_summary_text.done") {
+    if (event.item_id === undefined) return ProviderShared.eventError(state.id, `${event.type} is missing item_id`)
+    return Effect.succeed(onReasoningSummaryDone(state, event, event.item_id))
   }
   if (event.type === "response.reasoning_summary_part.added")
     return event.item_id !== undefined
-      ? Effect.succeed(onReasoningSummaryPartAdded(state, event))
+      ? Effect.succeed<StepResult>([state, NO_EVENTS])
       : ProviderShared.eventError(state.id, `${event.type} is missing item_id`)
   if (event.type === "response.reasoning_summary_part.done")
     return event.item_id !== undefined
-      ? Effect.succeed(onReasoningSummaryPartDone(state, event))
+      ? Effect.succeed<StepResult>([state, NO_EVENTS])
       : ProviderShared.eventError(state.id, `${event.type} is missing item_id`)
   if (event.type === "response.output_item.added") {
     if (event.item?.type === "message" && event.item.id === undefined)
@@ -1408,9 +1410,9 @@ export const step = (state: ParserState, input: Event) => {
  * The provider-neutral Open Responses protocol. Provider-specific Responses
  * implementations compose this baseline with their own tools and event variants.
  */
-export const initial = (request: LLMRequest, extension: Extension = BASE): ParserState => ({
-  id: extension.id,
-  name: extension.name,
+export const initial = (request: LLMRequest, adapter: ProviderAdapter = BASE_ADAPTER): ParserState => ({
+  id: adapter.id,
+  name: adapter.name,
   providerMetadataKey: request.model.route.providerMetadataKey ?? "openresponses",
   hasFunctionCall: false,
   tools: ToolStream.empty<string>(),
@@ -1418,6 +1420,7 @@ export const initial = (request: LLMRequest, extension: Extension = BASE): Parse
   lifecycle: Lifecycle.initial(),
   outputItems: {},
   message: undefined,
+  completedMessages: new Set<string>(),
   reasoningItems: {},
 })
 

packages/ai/src/protocols/openai-responses.ts

@@ -75,7 +75,9 @@ const OpenAIResponsesToolChoice = Schema.Union([
 
 const OpenAIResponsesCoreFields = {
   ...OpenResponses.coreFields,
-  input: Schema.Array(Schema.Union([OpenResponses.InputItem, OpenAIResponsesHostedToolItem])),
+  input: Schema.Array(
+    Schema.Union([OpenResponses.CompletedReasoningItem, OpenResponses.InputItem, OpenAIResponsesHostedToolItem]),
+  ),
   tools: optionalArray(OpenAIResponsesTools),
   tool_choice: Schema.optional(OpenAIResponsesToolChoice),
 }
@@ -86,11 +88,17 @@ const OpenAIResponsesBody = Schema.Struct({
 })
 export type OpenAIResponsesBody = Schema.Schema.Type<typeof OpenAIResponsesBody>
 
-const extension = {
+const restoreReasoningItem = (item: unknown) => {
+  if (!Schema.is(OpenResponses.CompletedReasoningItem)(item)) return undefined
+  return item.content?.length === 0 ? { ...item, content: undefined } : item
+}
+
+const adapter = {
   id: ADAPTER,
   name: NAME,
-  lowerHostedToolItem: (item: unknown) => (Schema.is(OpenAIResponsesHostedToolItem)(item) ? item : undefined),
-} satisfies OpenResponses.Extension
+  restoreHostedToolItem: (item: unknown) => (Schema.is(OpenAIResponsesHostedToolItem)(item) ? item : undefined),
+  restoreReasoningItem,
+} satisfies OpenResponses.ProviderAdapter
 
 const nativeImageToolInput = (tool: ToolDefinition) => {
   const native = tool.native?.openai
@@ -125,9 +133,9 @@ const lowerToolChoice = (toolChoice: NonNullable<LLMRequest["toolChoice"]>, tool
 const decodeBody = ProviderShared.validateWith(Schema.decodeUnknownEffect(OpenAIResponsesBody))
 
 const fromRequest = Effect.fn("OpenAIResponses.fromRequest")(function* (request: LLMRequest) {
-  const body = yield* OpenResponses.fromRequestWithExtension(
+  const body = yield* OpenResponses.fromRequestWithAdapter(
     LLMRequest.update(request, { tools: [], toolChoice: undefined }),
-    extension,
+    adapter,
   )
   const toolSchemaCompatibility = request.model.compatibility?.toolSchema
   const parallelToolCalls = OpenResponses.resolveParallelToolCalls(request)
@@ -185,12 +193,6 @@ const HOSTED_TOOLS = {
 } as const satisfies ResponsesHostedTools.Definitions
 
 const step = (state: OpenResponses.ParserState, event: OpenResponses.Event) => {
-  if (event.type === "response.reasoning_text.delta")
-    return event.item_id !== undefined
-      ? Effect.succeed(
-          OpenResponses.onReasoningDelta(state, event, OpenResponses.outputItemID(state, event) ?? event.item_id),
-        )
-      : ProviderShared.eventError(ADAPTER, `${event.type} is missing item_id`)
   if (event.type === "response.output_item.done" && event.item && ResponsesHostedTools.isItem(event.item, HOSTED_TOOLS))
     return ResponsesHostedTools.onDone(state, event.item, HOSTED_TOOLS)
   return OpenResponses.step(state, event)
@@ -204,7 +206,7 @@ export const protocol = Protocol.make({
   },
   stream: {
     event: OpenResponses.protocol.stream.event,
-    initial: (request) => OpenResponses.initial(request, extension),
+    initial: (request) => OpenResponses.initial(request, adapter),
     step,
     terminal: OpenResponses.terminal,
   },

packages/ai/src/protocols/xai-responses.ts

@@ -36,15 +36,15 @@ const XAIResponsesBody = Schema.Struct({
   stream: Schema.Literal(true),
 })
 
-const extension = {
+const adapter = {
   id: ADAPTER,
   name: NAME,
-  lowerHostedToolItem: (item: unknown) => (Schema.is(XAIResponsesHostedToolItem)(item) ? item : undefined),
-} satisfies OpenResponses.Extension
+  restoreHostedToolItem: (item: unknown) => (Schema.is(XAIResponsesHostedToolItem)(item) ? item : undefined),
+} satisfies OpenResponses.ProviderAdapter
 
 const decodeBody = ProviderShared.validateWith(Schema.decodeUnknownEffect(XAIResponsesBody))
 const fromRequest = Effect.fn("XAIResponses.fromRequest")(function* (request: LLMRequest) {
-  return yield* decodeBody(yield* OpenResponses.fromRequestWithExtension(request, extension))
+  return yield* decodeBody(yield* OpenResponses.fromRequestWithAdapter(request, adapter))
 })
 
 const HOSTED_TOOLS = {
@@ -78,7 +78,7 @@ export const protocol = Protocol.make({
   },
   stream: {
     event: OpenResponses.protocol.stream.event,
-    initial: (request) => OpenResponses.initial(request, extension),
+    initial: (request) => OpenResponses.initial(request, adapter),
     step,
     terminal: OpenResponses.terminal,
   },

packages/ai/test/provider/bedrock-converse.test.ts

@@ -631,10 +631,45 @@ describe("Bedrock Converse route", () => {
       )
       const response = yield* LLMClient.generate(baseRequest).pipe(Effect.provide(fixedBytes(body)))
 
+      expect(response.events.filter((event) => event.type === "finish")).toHaveLength(1)
       expect(response.usage).toMatchObject({ inputTokens: 5, outputTokens: 2, totalTokens: 7 })
     }),
   )
 
+  it.effect("retains metadata usage that arrives before messageStop", () =>
+    Effect.gen(function* () {
+      const body = eventStreamBody(
+        ["metadata", { usage: { inputTokens: 5, outputTokens: 2, totalTokens: 7 } }],
+        ["messageStop", { stopReason: "end_turn" }],
+      )
+      const response = yield* LLMClient.generate(baseRequest).pipe(Effect.provide(fixedBytes(body)))
+
+      expect(response.events.filter((event) => event.type === "finish")).toHaveLength(1)
+      expect(response.finishReason).toEqual({ normalized: "stop", raw: "end_turn" })
+      expect(response.usage).toMatchObject({ inputTokens: 5, outputTokens: 2, totalTokens: 7 })
+    }),
+  )
+
+  it.effect("rejects metadata-only streams as incomplete with HTTP context", () =>
+    Effect.gen(function* () {
+      const error = yield* LLMClient.generate(baseRequest).pipe(
+        Effect.provide(
+          fixedBytes(eventStreamBody(["metadata", { usage: { inputTokens: 5, outputTokens: 2, totalTokens: 7 } }])),
+        ),
+        Effect.flip,
+      )
+
+      expect(error.reason).toMatchObject({
+        _tag: "InvalidProviderOutput",
+        classification: "incomplete-stream",
+        http: {
+          status: 200,
+          headers: { "content-type": "application/vnd.amazon.eventstream" },
+        },
+      })
+    }),
+  )
+
   it.effect("assembles streamed tool call input", () =>
     Effect.gen(function* () {
       const body = eventStreamBody(

packages/ai/test/provider/error-retention.test.ts

@@ -62,6 +62,62 @@ describe("provider error retention", () => {
     )
   }
 
+  it.effect("classifies a message-less Gemini 429 and retains its event and HTTP context", () =>
+    Effect.gen(function* () {
+      const body = JSON.stringify({
+        error: { code: 429, status: "RESOURCE_EXHAUSTED", details: { opaque: [1, 2] } },
+        trace: { opaque: "outer" },
+      })
+      const error = yield* LLMClient.generate(
+        LLM.request({ model: Google.configure(options).model("gemini"), prompt: "hello" }),
+      ).pipe(
+        Effect.provide(
+          fixedResponse(sseEvents(body), {
+            headers: { "content-type": "text/event-stream", "x-provider-trace": "trace-1" },
+          }),
+        ),
+        Effect.flip,
+      )
+
+      expect(error.message).toBe("RESOURCE_EXHAUSTED")
+      expect(error.reason._tag).toBe("RateLimit")
+      expect(error.reason.body).toBe(body)
+      expect(error.reason.http).toMatchObject({ status: 200, headers: { "x-provider-trace": "trace-1" } })
+      expect(error.reason.http?.url).toStartWith("https://provider.test/")
+    }),
+  )
+
+  it.effect("rejects a malformed non-record Gemini error", () =>
+    Effect.gen(function* () {
+      const body = JSON.stringify({ error: "RESOURCE_EXHAUSTED", trace: { opaque: "outer" } })
+      const error = yield* LLMClient.generate(
+        LLM.request({ model: Google.configure(options).model("gemini"), prompt: "hello" }),
+      ).pipe(Effect.provide(fixedResponse(sseEvents(body))), Effect.flip)
+
+      expect(error.reason._tag).toBe("InvalidProviderOutput")
+      expect(error.message).toContain("Invalid google/gemini stream event")
+      expect(error.reason.body).toBe(body)
+      expect(error.reason.http?.status).toBe(200)
+    }),
+  )
+
+  it.effect("rejects and retains an explicit null Gemini error", () =>
+    Effect.gen(function* () {
+      const body = JSON.stringify({ error: null, trace: { opaque: "outer" } })
+      const error = yield* LLMClient.generate(
+        LLM.request({ model: Google.configure(options).model("gemini"), prompt: "hello" }),
+      ).pipe(
+        Effect.provide(fixedResponse(sseEvents(body), { headers: { "x-provider-trace": "trace-null" } })),
+        Effect.flip,
+      )
+
+      expect(error.reason._tag).toBe("InvalidProviderOutput")
+      expect(error.reason.body).toBe(body)
+      expect(error.reason.http).toMatchObject({ status: 200, headers: { "x-provider-trace": "trace-null" } })
+      expect(error.reason.http?.url).toStartWith("https://provider.test/")
+    }),
+  )
+
   it.effect("retains malformed provider frames and the original decode cause", () =>
     Effect.gen(function* () {
       const body = '{"type":"error","error":{"message":42,"opaque":{"nested":true}},"trace":"outer"}'

packages/ai/test/provider/open-responses-finals.test.ts

@@ -82,6 +82,32 @@ describe("Open Responses completed item text", () => {
       expect(response.events.filter(LLMEvent.is.textStart)).toEqual([])
     }),
   )
+
+  it.effect("assembles a done-only message once across replayed item events", () =>
+    Effect.gen(function* () {
+      const item = {
+        type: "message",
+        id: "msg_1",
+        content: [{ type: "output_text", text: "Recovered" }],
+      }
+      const response = yield* generate(
+        { type: "response.output_text.delta", item_id: "msg_1", delta: "Ignored after resume" },
+        { type: "response.output_item.done", item },
+        { type: "response.output_item.added", item },
+        { type: "response.output_item.done", item },
+        completed,
+      )
+      expect(response.text).toBe("Recovered")
+      expect(response.message.content).toEqual([
+        {
+          type: "text",
+          text: "Recovered",
+          providerMetadata: { "openai-compatible": { itemId: "msg_1" } },
+        },
+      ])
+      expect(response.events.filter(LLMEvent.is.textEnd)).toHaveLength(1)
+    }),
+  )
 })
 
 describe("Open Responses completed item reasoning", () => {
@@ -138,13 +164,23 @@ describe("Open Responses completed item reasoning", () => {
         expect(response.reasoning).toBe(fixture.text)
         expect(response.events.filter(LLMEvent.is.reasoningEnd)).toHaveLength(1)
         expect(response.message.content.find((part) => part.type === "reasoning")?.providerMetadata).toEqual({
-          "openai-compatible": { itemId: "rs_1", reasoningEncryptedContent: "encrypted" },
+          "openai-compatible": {
+            itemId: "rs_1",
+            reasoningEncryptedContent: "encrypted",
+            reasoningItem: {
+              type: "reasoning",
+              id: "rs_1",
+              summary: fixture.summary,
+              content: fixture.content,
+              encrypted_content: "encrypted",
+            },
+          },
         })
       }),
     )
   })
 
-  it.effect("replaces only the still-open summary without repeating earlier text", () =>
+  it.effect("replaces streamed reasoning with the completed summary", () =>
     Effect.gen(function* () {
       const response = yield* generate(
         { type: "response.output_item.added", item: { type: "reasoning", id: "rs_1" } },
@@ -164,8 +200,32 @@ describe("Open Responses completed item reasoning", () => {
         },
         completed,
       )
-      expect(response.reasoning).toBe("First final")
-      expect(response.events.filter(LLMEvent.is.reasoningEnd).map((event) => event.text)).toEqual([undefined, "final"])
+      expect(response.reasoning).toBe("First \n\nfinal")
+      expect(response.events.filter(LLMEvent.is.reasoningEnd).map((event) => event.text)).toEqual(["First \n\nfinal"])
+    }),
+  )
+
+  it.effect("does not store malformed completed reasoning items", () =>
+    Effect.gen(function* () {
+      const response = yield* generate(
+        { type: "response.output_item.added", item: { type: "reasoning", id: "rs_1" } },
+        { type: "response.reasoning_summary_text.delta", item_id: "rs_1", delta: "Draft" },
+        {
+          type: "response.output_item.done",
+          item: {
+            type: "reasoning",
+            id: "rs_1",
+            content: [{ type: "reasoning_text", text: "Raw" }],
+            encrypted_content: "encrypted",
+          },
+        },
+        completed,
+      )
+
+      expect(response.reasoning).toBe("Raw")
+      expect(response.message.content.find((part) => part.type === "reasoning")?.providerMetadata).toEqual({
+        "openai-compatible": { itemId: "rs_1", reasoningEncryptedContent: "encrypted" },
+      })
     }),
   )
 })
@@ -204,6 +264,7 @@ describe("Open Responses completed item reasoning", () => {
       expect(response.reasoning).toBe("Draft")
       expect(response.events.filter(LLMEvent.is.textEnd).map((event) => event.text)).toEqual([undefined])
       expect(response.events.filter(LLMEvent.is.reasoningEnd).map((event) => event.text)).toEqual([undefined])
+      expect(response.message.content.find((part) => part.type === "reasoning")?.providerMetadata).toBeUndefined()
     }),
   )
 })

packages/ai/test/provider/open-responses-lifecycle.test.ts

@@ -71,59 +71,61 @@ function expectLifecycle(events: ReadonlyArray<LLMEvent>, completed: boolean) {
 }
 
 describe("Open Responses basic-item lifecycles", () => {
-  it.effect("closes implicit summary boundaries and ignores late events for completed reasoning", () =>
+  it.effect("streams mixed reasoning in one lifecycle and ignores late events", () =>
     Effect.gen(function* () {
-      const item = { type: "reasoning", id: "rs_1", encrypted_content: "encrypted-state" }
+      const item = {
+        type: "reasoning",
+        id: "rs_1",
+        summary: [{ type: "summary_text", text: "Completed" }],
+        encrypted_content: "encrypted-state",
+      }
       const events = yield* collect(
         { type: "response.output_item.added", output_index: 0, item: { ...item, encrypted_content: null } },
         { type: "response.output_item.added", item: { ...item, encrypted_content: null } },
-        { type: "response.reasoning_summary_text.delta", item_id: "rs_1", summary_index: 0, delta: "First" },
-        { type: "response.reasoning_summary_part.added", item_id: "rs_1", summary_index: 1 },
-        { type: "response.reasoning_summary_part.done", item_id: "rs_1", summary_index: 0 },
-        { type: "response.reasoning_summary_text.done", item_id: "rs_1", summary_index: 1, text: "Second" },
-        // The third part omits both explicit summary boundaries.
+        { type: "response.reasoning.delta", item_id: "rs_1", content_index: 0, delta: "Raw " },
+        { type: "response.reasoning_summary_text.delta", item_id: "rs_1", summary_index: 0, delta: "summary " },
+        { type: "response.reasoning.done", item_id: "rs_1", content_index: 0, text: "ignored raw final" },
         {
-          type: "response.reasoning_summary_text.delta",
+          type: "response.reasoning_summary_text.done",
+          item_id: "rs_1",
+          summary_index: 0,
+          text: "ignored summary final",
+        },
+        {
+          type: "response.reasoning_text.done",
           output_index: 0,
           item_id: "wrong",
-          summary_index: 2,
-          delta: "Third",
+          content_index: 1,
+          text: "raw final ",
         },
+        { type: "response.reasoning_summary_text.done", item_id: "rs_1", summary_index: 1, text: "summary final" },
         { type: "response.output_item.done", item },
         { type: "response.output_item.done", item },
         { type: "response.output_item.added", item },
-        { type: "response.reasoning_summary_part.added", item_id: "rs_1", summary_index: 3 },
-        { type: "response.reasoning_summary_text.delta", item_id: "rs_1", summary_index: 3, delta: "late" },
-        { type: "response.reasoning_summary_text.done", item_id: "rs_1", summary_index: 2, text: "late final" },
-        { type: "response.reasoning_summary_part.done", item_id: "rs_1", summary_index: 3 },
+        { type: "response.reasoning.delta", item_id: "rs_1", content_index: 2, delta: "late raw" },
+        { type: "response.reasoning_summary_text.delta", item_id: "rs_1", summary_index: 2, delta: "late summary" },
+        { type: "response.reasoning.done", item_id: "rs_1", content_index: 3, text: "late raw final" },
+        { type: "response.reasoning_summary_text.done", item_id: "rs_1", summary_index: 3, text: "late final" },
         completed,
       )
 
       expect(events.filter((event) => event.type.startsWith("reasoning-"))).toEqual([
-        {
-          type: "reasoning-start",
-          id: "rs_1:0",
-          providerMetadata: { "openai-compatible": { itemId: "rs_1", reasoningEncryptedContent: null } },
-        },
-        { type: "reasoning-delta", id: "rs_1:0", text: "First" },
-        { type: "reasoning-end", id: "rs_1:0", providerMetadata: { "openai-compatible": { itemId: "rs_1" } } },
-        {
-          type: "reasoning-start",
-          id: "rs_1:1",
-          providerMetadata: { "openai-compatible": { itemId: "rs_1", reasoningEncryptedContent: null } },
-        },
-        { type: "reasoning-delta", id: "rs_1:1", text: "Second" },
-        { type: "reasoning-end", id: "rs_1:1", providerMetadata: { "openai-compatible": { itemId: "rs_1" } } },
-        {
-          type: "reasoning-start",
-          id: "rs_1:2",
-          providerMetadata: { "openai-compatible": { itemId: "rs_1", reasoningEncryptedContent: null } },
-        },
-        { type: "reasoning-delta", id: "rs_1:2", text: "Third" },
+        { type: "reasoning-start", id: "rs_1" },
+        { type: "reasoning-delta", id: "rs_1", text: "Raw " },
+        { type: "reasoning-delta", id: "rs_1", text: "summary " },
+        { type: "reasoning-delta", id: "rs_1", text: "raw final " },
+        { type: "reasoning-delta", id: "rs_1", text: "summary final" },
         {
           type: "reasoning-end",
-          id: "rs_1:2",
-          providerMetadata: { "openai-compatible": { itemId: "rs_1", reasoningEncryptedContent: "encrypted-state" } },
+          id: "rs_1",
+          text: "Completed",
+          providerMetadata: {
+            "openai-compatible": {
+              itemId: "rs_1",
+              reasoningEncryptedContent: "encrypted-state",
+              reasoningItem: item,
+            },
+          },
         },
       ])
     }),
@@ -152,13 +154,18 @@ describe("Open Responses basic-item lifecycles", () => {
         {
           type: "reasoning-start",
           id: "rs_1",
-          providerMetadata: { "openai-compatible": { itemId: "rs_1", reasoningEncryptedContent: "encrypted-state" } },
         },
         {
           type: "reasoning-end",
           id: "rs_1",
           text: "Not streamed",
-          providerMetadata: { "openai-compatible": { itemId: "rs_1", reasoningEncryptedContent: "encrypted-state" } },
+          providerMetadata: {
+            "openai-compatible": {
+              itemId: "rs_1",
+              reasoningEncryptedContent: "encrypted-state",
+              reasoningItem: item,
+            },
+          },
         },
       ])
     }),
@@ -216,7 +223,63 @@ describe("Open Responses basic-item lifecycles", () => {
       ])
     }),
   )
-  it.effect("allows a message to be registered again without inheriting its previous phase", () =>
+
+  it.effect("preserves non-empty done-only message content without replaying duplicates", () =>
+    Effect.gen(function* () {
+      const text = {
+        type: "message",
+        id: "msg_text",
+        content: [{ type: "output_text", text: "Done-only text." }],
+      }
+      const refusal = {
+        type: "message",
+        id: "msg_refusal",
+        content: [{ type: "refusal", refusal: "Done-only refusal." }],
+      }
+      const events = yield* collect(
+        { type: "response.output_item.done", item: text },
+        { type: "response.output_item.done", item: text },
+        {
+          type: "response.output_item.done",
+          item: { type: "message", id: "msg_empty", content: [{ type: "output_text", text: "" }] },
+        },
+        {
+          type: "response.output_item.done",
+          item: { type: "message", id: "msg_empty", content: [{ type: "output_text", text: "Late" }] },
+        },
+        { type: "response.output_item.done", item: refusal },
+        { type: "response.output_item.done", item: refusal },
+        completed,
+      )
+
+      expect(events.filter((event) => event.type.startsWith("text-"))).toEqual([
+        {
+          type: "text-start",
+          id: "msg_text",
+          providerMetadata: { "openai-compatible": { itemId: "msg_text" } },
+        },
+        {
+          type: "text-end",
+          id: "msg_text",
+          text: "Done-only text.",
+          providerMetadata: { "openai-compatible": { itemId: "msg_text" } },
+        },
+        {
+          type: "text-start",
+          id: "msg_refusal",
+          providerMetadata: { "openai-compatible": { itemId: "msg_refusal" } },
+        },
+        {
+          type: "text-end",
+          id: "msg_refusal",
+          text: "Done-only refusal.",
+          providerMetadata: { "openai-compatible": { itemId: "msg_refusal" } },
+        },
+      ])
+    }),
+  )
+
+  it.effect("treats a repeated message lifecycle as replay", () =>
     Effect.gen(function* () {
       const events = yield* collect(
         { type: "response.output_item.added", item: { type: "message", id: "msg_1", phase: "commentary" } },
@@ -233,9 +296,44 @@ describe("Open Responses basic-item lifecycles", () => {
           id: "msg_1",
           providerMetadata: { "openai-compatible": { itemId: "msg_1", phase: "commentary" } },
         },
-        { type: "text-end", id: "msg_1", providerMetadata: { "openai-compatible": { itemId: "msg_1" } } },
       ])
-      expect(events.filter(LLMEvent.is.textDelta).map((event) => event.text)).toEqual(["First", "Second"])
+      expect(events.filter(LLMEvent.is.textDelta).map((event) => event.text)).toEqual(["First"])
+    }),
+  )
+
+  it.effect("ignores a stale done-only message while another message is active", () =>
+    Effect.gen(function* () {
+      const events = yield* collect(
+        { type: "response.output_item.added", item: { type: "message", id: "msg_1", phase: "commentary" } },
+        { type: "response.output_text.delta", item_id: "msg_1", delta: "Draft" },
+        {
+          type: "response.output_item.done",
+          item: { type: "message", id: "msg_2", content: [{ type: "output_text", text: "Recovered" }] },
+        },
+        {
+          type: "response.output_item.done",
+          item: { type: "message", id: "msg_1", content: [{ type: "output_text", text: "Final" }] },
+        },
+        {
+          type: "response.output_item.done",
+          item: { type: "message", id: "msg_2", content: [{ type: "output_text", text: "Late" }] },
+        },
+        completed,
+      )
+      expect(events.filter((event) => event.type.startsWith("text-"))).toEqual([
+        {
+          type: "text-start",
+          id: "msg_1",
+          providerMetadata: { "openai-compatible": { itemId: "msg_1", phase: "commentary" } },
+        },
+        { type: "text-delta", id: "msg_1", text: "Draft" },
+        {
+          type: "text-end",
+          id: "msg_1",
+          text: "Final",
+          providerMetadata: { "openai-compatible": { itemId: "msg_1", phase: "commentary" } },
+        },
+      ])
     }),
   )
   ;[undefined, "fc_1"].forEach((id) => {
@@ -340,7 +438,7 @@ describe("Open Responses basic-item lifecycles", () => {
           providerExecuted: undefined,
           providerMetadata: { "openai-compatible": { itemId: "fc_1" } },
         },
-        { type: "reasoning-end", id: "rs_1:0" },
+        { type: "reasoning-end", id: "rs_1" },
       ])
     }),
   )
@@ -377,7 +475,8 @@ describe("Open Responses basic-item lifecycles", () => {
       expect(events.filter(LLMEvent.is.reasoningEnd)).toEqual([
         {
           type: "reasoning-end",
-          id: ":0",
+          id: "",
+          text: "Thinking",
           providerMetadata: { "openai-compatible": { itemId: "", reasoningEncryptedContent: "state" } },
         },
       ])
@@ -452,7 +551,7 @@ describe("Open Responses basic-item lifecycles", () => {
       )
       expect(events.filter(LLMEvent.is.toolInputEnd)).toEqual([])
       expect(events.filter(LLMEvent.is.toolCall)).toEqual([])
-      expect(events.filter(LLMEvent.is.reasoningEnd)).toEqual([{ type: "reasoning-end", id: "rs_1:0" }])
+      expect(events.filter(LLMEvent.is.reasoningEnd)).toEqual([{ type: "reasoning-end", id: "rs_1" }])
       expect(events.filter(LLMEvent.is.finish)).toEqual([
         {
           type: "finish",

packages/ai/test/provider/openai-compatible-responses.test.ts

@@ -303,6 +303,49 @@ describe("Open Responses-compatible route", () => {
     }),
   )
 
+  it.effect("projects completed reasoning items through the shared protocol", () =>
+    Effect.gen(function* () {
+      const model = configure({
+        apiKey: "test-key",
+        baseURL: "https://responses.example.test/v1",
+        provider: "example",
+      }).model("example-model")
+      const prepared = yield* compileRequest(
+        LLM.request({
+          model,
+          messages: [
+            Message.assistant({
+              type: "reasoning",
+              text: "Portable summary",
+              providerMetadata: {
+                example: {
+                  reasoningItem: {
+                    type: "reasoning",
+                    id: "rs_1",
+                    summary: [{ type: "summary_text", text: "Summary" }],
+                    content: [{ type: "reasoning_text", text: "Raw" }],
+                    encrypted_content: "state",
+                    status: "completed",
+                    future_field: { retained: true },
+                  },
+                },
+              },
+            }),
+          ],
+        }),
+      )
+
+      expect(prepared.body.input).toEqual([
+        {
+          type: "reasoning",
+          id: "rs_1",
+          summary: [{ type: "summary_text", text: "Summary" }],
+          encrypted_content: "state",
+        },
+      ])
+    }),
+  )
+
   it.effect("routes response deltas by output index", () =>
     Effect.gen(function* () {
       const model = configure({
@@ -427,7 +470,7 @@ describe("Open Responses-compatible route", () => {
     })
 
     routings.forEach((routing) => {
-      it.effect(`preserves reasoning summary boundaries without terminal reconciliation with ${routing.name}`, () =>
+      it.effect(`keeps one reasoning lifecycle without item completion with ${routing.name}`, () =>
         Effect.gen(function* () {
           const address = { item_id: routing.item_id, output_index: routing.output_index }
           const response = yield* LLMClient.generate(request).pipe(
@@ -458,26 +501,10 @@ describe("Open Responses-compatible route", () => {
           expect(response.message.content).toEqual([
             {
               type: "reasoning",
-              text: "First.",
-              providerMetadata: { "openai-compatible": { itemId: routing.id } },
-            },
-            {
-              type: "reasoning",
-              text: "Second.",
-              providerMetadata: {
-                "openai-compatible": { itemId: routing.id, reasoningEncryptedContent: null },
-              },
+              text: "First.Second.",
             },
           ])
-          expect(response.events.filter(LLMEvent.is.reasoningEnd)).toEqual([
-            {
-              type: "reasoning-end",
-              id: `${routing.id}:0`,
-              text: undefined,
-              providerMetadata: { "openai-compatible": { itemId: routing.id } },
-            },
-            { type: "reasoning-end", id: `${routing.id}:1` },
-          ])
+          expect(response.events.filter(LLMEvent.is.reasoningEnd)).toEqual([{ type: "reasoning-end", id: routing.id }])
         }),
       )
     })
@@ -717,7 +744,7 @@ describe("Open Responses-compatible route", () => {
 
       expect(response.events.find((event) => event.type === "reasoning-end")).toEqual({
         type: "reasoning-end",
-        id: "rs_raw:0",
+        id: "rs_raw",
       })
     }),
   )

packages/ai/test/provider/openai-responses.test.ts

@@ -2500,11 +2500,11 @@ describe("OpenAI Responses route", () => {
       expect(response.text).toBe("Hello")
       expect(response.events).toMatchObject([
         { type: "step-start", index: 0 },
-        { type: "reasoning-start", id: "rs_1:0" },
-        { type: "reasoning-delta", id: "rs_1:0", text: "thinking" },
+        { type: "reasoning-start", id: "rs_1" },
+        { type: "reasoning-delta", id: "rs_1", text: "thinking" },
         { type: "text-start", id: "msg_1" },
         { type: "text-delta", id: "msg_1", text: "Hello" },
-        { type: "reasoning-end", id: "rs_1:0" },
+        { type: "reasoning-end", id: "rs_1" },
         { type: "text-end", id: "msg_1" },
         { type: "step-finish", index: 0, reason: { normalized: "stop", raw: undefined } },
         { type: "finish", reason: { normalized: "stop", raw: undefined } },
@@ -2514,7 +2514,6 @@ describe("OpenAI Responses route", () => {
         {
           type: "reasoning",
           text: "thinking",
-          providerMetadata: { openai: { itemId: "rs_1", reasoningEncryptedContent: null } },
         },
         { type: "text", text: "Hello", providerMetadata: { openai: { itemId: "msg_1" } } },
       ])
@@ -2547,8 +2546,19 @@ describe("OpenAI Responses route", () => {
       expect(response.events).toContainEqual(
         expect.objectContaining({
           type: "reasoning-end",
-          id: "rs_1:0",
-          providerMetadata: { openai: { itemId: "rs_1", reasoningEncryptedContent: "encrypted-state" } },
+          id: "rs_1",
+          providerMetadata: {
+            openai: {
+              itemId: "rs_1",
+              reasoningEncryptedContent: "encrypted-state",
+              reasoningItem: {
+                type: "reasoning",
+                id: "rs_1",
+                encrypted_content: "encrypted-state",
+                summary: [{ type: "summary_text", text: "thinking" }],
+              },
+            },
+          },
         }),
       )
     }),
@@ -2595,12 +2605,11 @@ describe("OpenAI Responses route", () => {
 
       expect(response.reasoning).toBe("Checked the diff.")
       expect(response.events.filter((event) => event.type === "reasoning-end")).toEqual([
-        { type: "reasoning-end", id: "rs_1:0" },
+        { type: "reasoning-end", id: "rs_1" },
       ])
       expect(response.message.content).toContainEqual({
         type: "reasoning",
         text: "Checked the diff.",
-        providerMetadata: { openai: { itemId: "rs_1", reasoningEncryptedContent: null } },
       })
     }),
   )
@@ -2668,7 +2677,7 @@ describe("OpenAI Responses route", () => {
 
       expect(response.events.find((event) => event.type === "reasoning-end")).toEqual({
         type: "reasoning-end",
-        id: "rs_1:0",
+        id: "rs_1",
       })
       expect(response.events.filter(LLMEvent.is.toolCall)).toEqual([
         expect.objectContaining({ id: "call_1", input: { query: "weather" } }),
@@ -2680,7 +2689,7 @@ describe("OpenAI Responses route", () => {
     }),
   )
 
-  it.effect("streams each reasoning summary part as a separate block", () =>
+  it.effect("streams reasoning summary parts in wire order in one lifecycle", () =>
     Effect.gen(function* () {
       const response = yield* LLMClient.generate(
         LLMRequest.update(request, { providerOptions: { store: false } }),
@@ -2711,22 +2720,13 @@ describe("OpenAI Responses route", () => {
       expect(response.reasoning).toBe("FirstSecond")
       expect(response.events).toMatchObject([
         { type: "step-start", index: 0 },
-        {
-          type: "reasoning-start",
-          id: "rs_1:0",
-          providerMetadata: { openai: { itemId: "rs_1", reasoningEncryptedContent: null } },
-        },
-        { type: "reasoning-delta", id: "rs_1:0", text: "First" },
-        { type: "reasoning-end", id: "rs_1:0", providerMetadata: { openai: { itemId: "rs_1" } } },
-        {
-          type: "reasoning-start",
-          id: "rs_1:1",
-          providerMetadata: { openai: { itemId: "rs_1", reasoningEncryptedContent: null } },
-        },
-        { type: "reasoning-delta", id: "rs_1:1", text: "Second" },
+        { type: "reasoning-start", id: "rs_1" },
+        { type: "reasoning-delta", id: "rs_1", text: "First" },
+        { type: "reasoning-delta", id: "rs_1", text: "Second" },
         {
           type: "reasoning-end",
-          id: "rs_1:1",
+          id: "rs_1",
+          text: "FirstSecond",
           providerMetadata: { openai: { itemId: "rs_1", reasoningEncryptedContent: "encrypted-state" } },
         },
         { type: "step-finish", index: 0, reason: { normalized: "stop", raw: undefined } },
@@ -2735,73 +2735,6 @@ describe("OpenAI Responses route", () => {
     }),
   )
 
-  it.effect("concludes reasoning at implicit summary boundaries", () =>
-    Effect.gen(function* () {
-      const response = yield* LLMClient.generate(
-        LLMRequest.update(request, { providerOptions: { store: false } }),
-      ).pipe(
-        Effect.provide(
-          fixedResponse(
-            sseEvents(
-              {
-                type: "response.output_item.added",
-                item: { type: "reasoning", id: "rs_1", encrypted_content: null },
-              },
-              { type: "response.reasoning_summary_part.added", item_id: "rs_1", summary_index: 0 },
-              { type: "response.reasoning_summary_text.delta", item_id: "rs_1", summary_index: 0, delta: "First" },
-              // The next part is enough to conclude the previous one even when
-              // its done event is delayed.
-              { type: "response.reasoning_summary_part.added", item_id: "rs_1", summary_index: 1 },
-              { type: "response.reasoning_summary_part.done", item_id: "rs_1", summary_index: 0 },
-              { type: "response.reasoning_summary_text.delta", item_id: "rs_1", summary_index: 1, delta: "Second" },
-              { type: "response.reasoning_summary_part.done", item_id: "rs_1", summary_index: 1 },
-              // Some compatible providers begin the next part with its first delta.
-              { type: "response.reasoning_summary_text.delta", item_id: "rs_1", summary_index: 2, delta: "Third" },
-              {
-                type: "response.output_item.done",
-                item: { type: "reasoning", id: "rs_1", encrypted_content: "encrypted-state" },
-              },
-              { type: "response.completed", response: { id: "resp_1" } },
-            ),
-          ),
-        ),
-      )
-
-      expect(response.reasoning).toBe("FirstSecondThird")
-      expect(response.events.filter((event) => event.type.startsWith("reasoning-"))).toEqual([
-        {
-          type: "reasoning-start",
-          id: "rs_1:0",
-          providerMetadata: { openai: { itemId: "rs_1", reasoningEncryptedContent: null } },
-        },
-        { type: "reasoning-delta", id: "rs_1:0", text: "First", providerMetadata: undefined },
-        { type: "reasoning-end", id: "rs_1:0", providerMetadata: { openai: { itemId: "rs_1" } } },
-        {
-          type: "reasoning-start",
-          id: "rs_1:1",
-          providerMetadata: { openai: { itemId: "rs_1", reasoningEncryptedContent: null } },
-        },
-        { type: "reasoning-delta", id: "rs_1:1", text: "Second", providerMetadata: undefined },
-        {
-          type: "reasoning-end",
-          id: "rs_1:1",
-          providerMetadata: { openai: { itemId: "rs_1" } },
-        },
-        {
-          type: "reasoning-start",
-          id: "rs_1:2",
-          providerMetadata: { openai: { itemId: "rs_1", reasoningEncryptedContent: null } },
-        },
-        { type: "reasoning-delta", id: "rs_1:2", text: "Third", providerMetadata: undefined },
-        {
-          type: "reasoning-end",
-          id: "rs_1:2",
-          providerMetadata: { openai: { itemId: "rs_1", reasoningEncryptedContent: "encrypted-state" } },
-        },
-      ])
-    }),
-  )
-
   it.effect("rejects a reasoning item that starts before the previous item ends", () =>
     Effect.gen(function* () {
       const error = yield* LLMClient.generate(request).pipe(
@@ -2997,15 +2930,26 @@ describe("OpenAI Responses route", () => {
       expect(response.events.filter((event) => event.type.startsWith("reasoning-"))).toEqual([
         {
           type: "reasoning-start",
-          id: "rs_1:0",
-          providerMetadata: { openai: { itemId: "rs_1", reasoningEncryptedContent: null } },
+          id: "rs_1",
+          providerMetadata: undefined,
         },
-        { type: "reasoning-delta", id: "rs_1:0", text: "Checked the diff.", providerMetadata: undefined },
+        { type: "reasoning-delta", id: "rs_1", text: "Checked the diff.", providerMetadata: undefined },
         {
           type: "reasoning-end",
-          id: "rs_1:0",
+          id: "rs_1",
           text: "Checked the diff.",
-          providerMetadata: { openai: { itemId: "rs_1", reasoningEncryptedContent: "encrypted-state" } },
+          providerMetadata: {
+            openai: {
+              itemId: "rs_1",
+              reasoningEncryptedContent: "encrypted-state",
+              reasoningItem: {
+                type: "reasoning",
+                id: "rs_1",
+                summary: [{ type: "summary_text", text: "Checked the diff." }],
+                encrypted_content: "encrypted-state",
+              },
+            },
+          },
         },
       ])
 
@@ -3051,7 +2995,7 @@ describe("OpenAI Responses route", () => {
 
       expect(response.reasoning).toBe("Streamed")
       expect(response.events.filter((event) => event.type === "reasoning-delta")).toEqual([
-        { type: "reasoning-delta", id: "rs_1:0", text: "Streamed", providerMetadata: undefined },
+        { type: "reasoning-delta", id: "rs_1", text: "Streamed", providerMetadata: undefined },
       ])
     }),
   )
@@ -3074,7 +3018,15 @@ describe("OpenAI Responses route", () => {
               { type: "response.reasoning_summary_part.done", item_id: "rs_1", summary_index: 1 },
               {
                 type: "response.output_item.done",
-                item: { type: "reasoning", id: "rs_1", encrypted_content: "encrypted-state" },
+                item: {
+                  type: "reasoning",
+                  id: "rs_1",
+                  summary: [
+                    { type: "summary_text", text: "First" },
+                    { type: "summary_text", text: "Second" },
+                  ],
+                  encrypted_content: "encrypted-state",
+                },
               },
               { type: "response.completed", response: { id: "resp_1" } },
             ),
@@ -3083,11 +3035,25 @@ describe("OpenAI Responses route", () => {
       )
 
       expect(response.events.filter((event) => event.type === "reasoning-end")).toEqual([
-        { type: "reasoning-end", id: "rs_1:0", providerMetadata: { openai: { itemId: "rs_1" } } },
         {
           type: "reasoning-end",
-          id: "rs_1:1",
-          providerMetadata: { openai: { itemId: "rs_1", reasoningEncryptedContent: "encrypted-state" } },
+          id: "rs_1",
+          text: "First\n\nSecond",
+          providerMetadata: {
+            openai: {
+              itemId: "rs_1",
+              reasoningEncryptedContent: "encrypted-state",
+              reasoningItem: {
+                type: "reasoning",
+                id: "rs_1",
+                summary: [
+                  { type: "summary_text", text: "First" },
+                  { type: "summary_text", text: "Second" },
+                ],
+                encrypted_content: "encrypted-state",
+              },
+            },
+          },
         },
       ])
     }),
@@ -3195,6 +3161,15 @@ describe("OpenAI Responses route", () => {
 
   it.effect("replays complete reasoning items when storage is enabled", () =>
     Effect.gen(function* () {
+      const item = {
+        type: "reasoning",
+        id: "rs_1",
+        summary: [{ type: "summary_text", text: "Checked the previous diff." }],
+        content: [{ type: "reasoning_text", text: "Provider reasoning" }],
+        encrypted_content: "encrypted-state",
+        status: "completed",
+        provider_field: { retained: true },
+      }
       const prepared = yield* compileRequest(
         LLM.request({
           model,
@@ -3203,7 +3178,13 @@ describe("OpenAI Responses route", () => {
               {
                 type: "reasoning",
                 text: "Checked the previous diff.",
-                providerMetadata: { openai: { itemId: "rs_1", reasoningEncryptedContent: "encrypted-state" } },
+                providerMetadata: {
+                  openai: {
+                    itemId: "rs_1",
+                    reasoningEncryptedContent: "encrypted-state",
+                    reasoningItem: item,
+                  },
+                },
               },
             ]),
           ],
@@ -3211,14 +3192,7 @@ describe("OpenAI Responses route", () => {
         }),
       )
 
-      expect(prepared.body.input).toEqual([
-        {
-          type: "reasoning",
-          id: "rs_1",
-          summary: [{ type: "summary_text", text: "Checked the previous diff." }],
-          encrypted_content: "encrypted-state",
-        },
-      ])
+      expect(prepared.body.input[0]).toEqual(item)
     }),
   )
 

packages/app/component-tests/composer.spec.ts

@@ -1,5 +1,16 @@
 import { expect, story } from "../../storybook/playwright/story"
 
+story("raises the docked composer only in dark mode", async ({ mount, page }) => {
+  const component = await mount("opencode-composer-flow--empty-draft")
+  const composer = component.locator('[data-component="composer"]')
+
+  await page.locator("html").evaluate((root) => root.setAttribute("data-color-scheme", "light"))
+  await expect(composer).toHaveCSS("background-color", "rgb(255, 255, 255)")
+
+  await page.locator("html").evaluate((root) => root.setAttribute("data-color-scheme", "dark"))
+  await expect(composer).toHaveCSS("background-color", "rgb(36, 36, 36)")
+})
+
 for (const draft of ["empty-draft", "multiline-draft", "mixed-attachments"]) {
   story(`select all stays inside the composer with ${draft}`, async ({ mount, page }) => {
     const component = await mount(`opencode-composer-flow--${draft}`)

packages/app/e2e/regression/mobile-status-drawer.spec.ts

@@ -10,7 +10,7 @@ test("status drawer dismisses and reopens after button, backdrop, Escape, and dr
     .locator('[data-slot="session-mobile-view-navigation"]')
     .getByRole("button", { name: "More options", exact: true })
   const drawer = page.getByRole("dialog", { name: "Status", exact: true })
-  const overlay = page.locator('[data-slot="mobile-status-overlay"]')
+  const overlay = page.locator('[data-slot="mobile-drawer-overlay"]')
 
   for (const dismissal of ["button", "backdrop", "escape", "drag", "button"] as const) {
     await more.click()
@@ -21,7 +21,7 @@ test("status drawer dismisses and reopens after button, backdrop, Escape, and dr
     if (dismissal === "backdrop") await overlay.click({ position: { x: 10, y: 10 } })
     if (dismissal === "escape") await page.keyboard.press("Escape")
     if (dismissal === "drag") {
-      const handle = drawer.locator('[data-slot="mobile-status-drag-handle"]')
+      const handle = drawer.locator('[data-slot="mobile-drawer-handle"]')
       const bounds = await handle.boundingBox()
       expect(bounds).not.toBeNull()
       await page.mouse.move(bounds!.x + bounds!.width / 2, bounds!.y + bounds!.height / 2)

packages/app/e2e/regression/project-extensions.spec.ts

@@ -64,7 +64,7 @@ test("project Extensions stays inside settings while plugins load", async ({ pag
           location: project ? { directory: project } : {},
           data: (project ? ["shared-plugin", "project-plugin"] : ["shared-plugin"]).map((id) => ({
             id,
-            source: { type: "package", package: id },
+            source: { type: "package", target: id },
             state: { status: "active" },
             features: { server: true },
           })),

packages/app/e2e/regression/settings-loading.spec.ts

@@ -85,7 +85,7 @@ test("extensions opens without waiting for MCPs or plugins", async ({ page }) =>
         data: [
           {
             id: "demo-plugin",
-            source: { type: "package", package: "demo-plugin" },
+            source: { type: "package", target: "demo-plugin" },
             state: { status: "active" },
             features: { server: true },
           },

packages/app/manifest.json

@@ -9,13 +9,13 @@
       "src": "/web-app-manifest-192x192.png",
       "sizes": "192x192",
       "type": "image/png",
-      "purpose": "any"
+      "purpose": "maskable"
     },
     {
       "src": "/web-app-manifest-512x512.png",
       "sizes": "512x512",
       "type": "image/png",
-      "purpose": "any"
+      "purpose": "maskable"
     }
   ],
   "theme_color": "#080808",

packages/app/src/composer/editor/editor.css

@@ -1,3 +1,7 @@
 [data-component="composer-editor"]:empty::before {
   content: "\200B";
 }
+
+[data-color-scheme="dark"] [data-component="composer"][data-dock-border-underlay="true"] {
+  background: var(--v2-background-bg-layer-01);
+}

packages/app/src/composer/editor/editor.tsx

@@ -114,10 +114,8 @@ export function ComposerEditor(props: ComposerEditorProps) {
       <form
         data-component="composer"
         data-dock-border-underlay={props.borderUnderlay ? "true" : undefined}
-        class="group/composer relative min-h-[96px] w-full overflow-clip rounded-xl"
+        class="group/composer relative min-h-[96px] w-full overflow-clip rounded-xl bg-v2-background-bg-base"
         classList={{
-          "bg-v2-background-bg-layer-01": props.borderUnderlay,
-          "bg-v2-background-bg-base": !props.borderUnderlay,
           "shadow-[var(--v2-elevation-raised)]": !props.borderUnderlay,
           "border border-v2-icon-icon-info border-dashed": state.drag === "active",
         }}

packages/app/src/providers/catalog/plugin.test.ts

@@ -8,7 +8,7 @@ describe("pluginLabels", () => {
       { id: "opencode.internal", source: { type: "builtin" }, state: { status: "active" }, features: { server: true } },
       {
         id: "package-plugin",
-        source: { type: "package", package: "example" },
+        source: { type: "package", target: "example" },
         state: { status: "active" },
         features: { server: true },
       },

packages/app/src/providers/catalog/plugin.ts

@@ -2,7 +2,7 @@ import type { PluginInfo } from "@opencode-ai/client"
 
 export function pluginLabel(plugin: PluginInfo) {
   if (plugin.id) return plugin.id
-  if (plugin.source.type === "package") return plugin.source.package
+  if (plugin.source.type === "package") return plugin.source.target
   if (plugin.source.type === "local") return plugin.source.path
   return plugin.source.type
 }

packages/app/src/shell/mobile-drawer.css

@@ -0,0 +1,90 @@
+[data-slot="mobile-drawer-overlay"] {
+  position: fixed;
+  inset: 0;
+  z-index: 50;
+  background: var(--v2-overlay-simple-overlay-scrim);
+  animation: mobile-drawer-backdrop-in 240ms ease-out;
+}
+
+[data-slot="mobile-drawer-overlay"]:is([data-closing], [data-closed]) {
+  animation: mobile-drawer-backdrop-out 200ms ease-in forwards;
+}
+
+[data-slot="mobile-drawer-content"] {
+  box-sizing: border-box;
+  position: fixed;
+  inset-inline: 0;
+  bottom: 0;
+  z-index: 51;
+  display: flex;
+  flex-direction: column;
+  max-height: min(75dvh, calc(100dvh - env(safe-area-inset-top, 0px) - 16px));
+  padding: 0 12px max(12px, env(safe-area-inset-bottom, 0px));
+  padding-left: max(12px, env(safe-area-inset-left, 0px));
+  padding-right: max(12px, env(safe-area-inset-right, 0px));
+  border-radius: 16px 16px 0 0;
+  background: var(--v2-background-bg-deep);
+  color: var(--v2-text-text-base);
+  box-shadow: var(--v2-elevation-overlay);
+  outline: none;
+  app-region: no-drag;
+}
+
+[data-slot="mobile-drawer-content"][data-transitioning] {
+  transition: transform 240ms cubic-bezier(0.2, 0.8, 0.2, 1);
+}
+
+[data-slot="mobile-drawer-content"][data-closing] {
+  transition-duration: 200ms;
+}
+
+[data-slot="mobile-drawer-content"][data-closed] {
+  visibility: hidden;
+  pointer-events: none;
+}
+
+[data-slot="mobile-drawer-handle"] {
+  display: flex;
+  height: 28px;
+  flex-shrink: 0;
+  align-items: center;
+  justify-content: center;
+  touch-action: none;
+}
+
+[data-slot="mobile-drawer-handle"] span {
+  width: 32px;
+  height: 4px;
+  border-radius: 999px;
+  background: var(--v2-border-border-strong);
+}
+
+@keyframes mobile-drawer-backdrop-in {
+  from {
+    opacity: 0;
+  }
+  to {
+    opacity: 1;
+  }
+}
+
+@keyframes mobile-drawer-backdrop-out {
+  from {
+    opacity: 1;
+  }
+  to {
+    opacity: 0;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  [data-slot="mobile-drawer-content"][data-transitioning],
+  [data-slot="mobile-drawer-content"][data-closing] {
+    transition: none;
+  }
+
+  [data-slot="mobile-drawer-overlay"],
+  [data-slot="mobile-drawer-overlay"]:is([data-closing], [data-closed]) {
+    animation: none;
+  }
+}

packages/app/src/shell/mobile-drawer.tsx

@@ -0,0 +1,47 @@
+import Drawer from "@corvu/drawer"
+import type { ParentProps } from "solid-js"
+import { useLanguage } from "@/runtime/i18n/language"
+import "./mobile-drawer.css"
+
+export function MobileDrawer(
+  props: ParentProps<{
+    open: boolean
+    onOpenChange: (open: boolean) => void
+    onContentPresentChange?: (present: boolean) => void
+    returnFocus?: () => HTMLElement | undefined
+    closeOnOutsideFocus?: boolean
+  }>,
+) {
+  return (
+    <Drawer
+      open={props.open}
+      onOpenChange={props.onOpenChange}
+      onContentPresentChange={props.onContentPresentChange}
+      side="bottom"
+      finalFocusEl={props.returnFocus?.()}
+      closeOnOutsideFocus={props.closeOnOutsideFocus}
+    >
+      {props.children}
+    </Drawer>
+  )
+}
+
+export const MobileDrawerTrigger = Drawer.Trigger
+
+export function MobileDrawerContent(props: ParentProps) {
+  const language = useLanguage()
+  return (
+    <Drawer.Portal forceMount>
+      <Drawer.Overlay data-slot="mobile-drawer-overlay" />
+      <Drawer.Content forceMount data-slot="mobile-drawer-content" dir={language.direction()}>
+        <div data-slot="mobile-drawer-handle" aria-hidden="true">
+          <span />
+        </div>
+        {props.children}
+      </Drawer.Content>
+    </Drawer.Portal>
+  )
+}
+
+export const MobileDrawerLabel = Drawer.Label
+export const MobileDrawerClose = Drawer.Close

packages/app/src/shell/mobile-panel-drawer.css

@@ -0,0 +1,34 @@
+[data-slot="mobile-panel"] {
+  display: flex;
+  min-height: 0;
+  flex-direction: column;
+}
+
+[data-slot="mobile-panel-header"] {
+  display: flex;
+  flex-shrink: 0;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  padding-inline-start: 8px;
+  padding-block-end: 8px;
+}
+
+[data-slot="mobile-panel-header"] h2 {
+  margin: 0;
+  font-size: 14px;
+  font-weight: 530;
+  line-height: var(--line-height-base);
+}
+
+[data-slot="mobile-panel-close"][data-component="button-v2"] {
+  height: 44px;
+  flex-shrink: 0;
+}
+
+[data-slot="mobile-panel-content"] {
+  min-height: 0;
+  overflow-y: auto;
+  overscroll-behavior: contain;
+  touch-action: pan-y;
+}

packages/app/src/shell/mobile-panel-drawer.tsx

@@ -1,7 +1,8 @@
-import Drawer from "@corvu/drawer"
 import type { ParentProps } from "solid-js"
+import { Button } from "@opencode-ai/ui/button"
 import { useLanguage } from "@/runtime/i18n/language"
-import "./status/status-drawer.css"
+import { MobileDrawer, MobileDrawerClose, MobileDrawerContent, MobileDrawerLabel } from "./mobile-drawer"
+import "./mobile-panel-drawer.css"
 
 export function MobilePanelDrawer(
   props: ParentProps<{
@@ -13,32 +14,29 @@ export function MobilePanelDrawer(
 ) {
   const language = useLanguage()
   return (
-    <Drawer
+    <MobileDrawer
       open={props.open}
       onOpenChange={props.onOpenChange}
-      side="bottom"
-      finalFocusEl={props.returnFocus?.()}
+      returnFocus={props.returnFocus}
       // Menu focus handoff must not dismiss the drawer during its opening transition.
       closeOnOutsideFocus={false}
     >
-      {/* Preserve Corvu's content and dismissal lifecycle across reopenings. */}
-      <Drawer.Portal forceMount>
-        <Drawer.Overlay data-slot="mobile-status-overlay" />
-        <Drawer.Content forceMount data-slot="mobile-status-drawer" dir={language.direction()}>
-          <div data-slot="mobile-status-drag-handle" aria-hidden="true">
-            <span />
-          </div>
-          <div data-slot="mobile-status-header" data-corvu-no-drag>
-            <Drawer.Label>{props.title}</Drawer.Label>
-            <Drawer.Close data-slot="mobile-status-close" aria-label={language.t("common.close")}>
+      <MobileDrawerContent>
+        <div data-slot="mobile-panel" data-corvu-no-drag>
+          <div data-slot="mobile-panel-header">
+            <MobileDrawerLabel>{props.title}</MobileDrawerLabel>
+            <MobileDrawerClose
+              as={Button}
+              variant="ghost"
+              data-slot="mobile-panel-close"
+              aria-label={language.t("common.close")}
+            >
               {language.t("common.close")}
-            </Drawer.Close>
+            </MobileDrawerClose>
           </div>
-          <div data-slot="mobile-status-content" data-corvu-no-drag>
-            {props.children}
-          </div>
-        </Drawer.Content>
-      </Drawer.Portal>
-    </Drawer>
+          <div data-slot="mobile-panel-content">{props.children}</div>
+        </div>
+      </MobileDrawerContent>
+    </MobileDrawer>
   )
 }

packages/app/src/shell/status/status-drawer.css

@@ -1,109 +1,3 @@
-[data-slot="mobile-status-overlay"] {
-  position: fixed;
-  inset: 0;
-  z-index: 50;
-  background: var(--v2-overlay-simple-overlay-scrim);
-  animation: mobile-status-backdrop-in 240ms ease-out;
-}
-
-[data-slot="mobile-status-overlay"]:is([data-closing], [data-closed]) {
-  animation: mobile-status-backdrop-out 200ms ease-in forwards;
-}
-
-[data-slot="mobile-status-drawer"] {
-  box-sizing: border-box;
-  position: fixed;
-  inset-inline: 0;
-  bottom: 0;
-  z-index: 51;
-  display: flex;
-  flex-direction: column;
-  max-height: min(75dvh, calc(100dvh - env(safe-area-inset-top, 0px) - 16px));
-  padding: 0 12px max(12px, env(safe-area-inset-bottom, 0px));
-  padding-left: max(12px, env(safe-area-inset-left, 0px));
-  padding-right: max(12px, env(safe-area-inset-right, 0px));
-  border-radius: 16px 16px 0 0;
-  background: var(--v2-background-bg-deep);
-  color: var(--v2-text-text-base);
-  box-shadow: var(--v2-elevation-overlay);
-  outline: none;
-  app-region: no-drag;
-}
-
-[data-slot="mobile-status-drawer"][data-transitioning] {
-  transition: transform 240ms cubic-bezier(0.2, 0.8, 0.2, 1);
-}
-
-[data-slot="mobile-status-drawer"][data-closing] {
-  transition-duration: 200ms;
-}
-
-[data-slot="mobile-status-drawer"][data-closed] {
-  visibility: hidden;
-  pointer-events: none;
-}
-
-[data-slot="mobile-status-drag-handle"] {
-  display: flex;
-  height: 28px;
-  flex-shrink: 0;
-  align-items: center;
-  justify-content: center;
-  touch-action: none;
-}
-
-[data-slot="mobile-status-drag-handle"] span {
-  width: 32px;
-  height: 4px;
-  border-radius: 999px;
-  background: var(--v2-border-border-strong);
-}
-
-[data-slot="mobile-status-header"] {
-  display: flex;
-  flex-shrink: 0;
-  align-items: center;
-  justify-content: space-between;
-  gap: 12px;
-  padding-inline-start: 8px;
-  padding-block-end: 8px;
-}
-
-[data-slot="mobile-status-header"] h2 {
-  margin: 0;
-  font-size: 14px;
-  font-weight: 530;
-  line-height: var(--line-height-base);
-}
-
-[data-slot="mobile-status-close"] {
-  min-height: 44px;
-  flex-shrink: 0;
-  padding-inline: 12px;
-  border-radius: 6px;
-  color: var(--v2-text-text-base);
-  font-size: 13px;
-  line-height: var(--line-height-compact);
-}
-
-@media (hover: hover) {
-  [data-slot="mobile-status-close"]:hover {
-    background: var(--v2-overlay-simple-overlay-hover);
-  }
-}
-
-[data-slot="mobile-status-close"]:focus-visible {
-  outline: 2px solid var(--v2-border-border-focus);
-  outline-offset: -2px;
-}
-
-[data-slot="mobile-status-content"] {
-  min-height: 0;
-  overflow-y: auto;
-  overscroll-behavior: contain;
-  touch-action: pan-y;
-}
-
 [data-slot="mobile-status-loading"] {
   display: flex;
   min-height: 56px;
@@ -113,33 +7,3 @@
   font-size: 13px;
   line-height: var(--line-height-base);
 }
-
-@keyframes mobile-status-backdrop-in {
-  from {
-    opacity: 0;
-  }
-  to {
-    opacity: 1;
-  }
-}
-
-@keyframes mobile-status-backdrop-out {
-  from {
-    opacity: 1;
-  }
-  to {
-    opacity: 0;
-  }
-}
-
-@media (prefers-reduced-motion: reduce) {
-  [data-slot="mobile-status-drawer"][data-transitioning],
-  [data-slot="mobile-status-drawer"][data-closing] {
-    transition: none;
-  }
-
-  [data-slot="mobile-status-overlay"],
-  [data-slot="mobile-status-overlay"]:is([data-closing], [data-closed]) {
-    animation: none;
-  }
-}

packages/app/src/shell/status/status-drawer.tsx

@@ -1,6 +1,7 @@
 import { lazy, Suspense } from "solid-js"
 import { useLanguage } from "@/runtime/i18n/language"
 import { MobilePanelDrawer } from "../mobile-panel-drawer"
+import "./status-drawer.css"
 
 const Body = lazy(async () => {
   const { StatusPopoverBody } = await import("./body")

packages/app/src/shell/titlebar/titlebar.css

@@ -14,63 +14,13 @@
     var(--v2-background-bg-layer-02);
 }
 
-[data-slot="mobile-tabs-overlay"] {
-  position: fixed;
-  inset: 0;
-  z-index: 50;
-  background: var(--v2-overlay-simple-overlay-scrim);
-  animation: mobile-tabs-backdrop-in 240ms ease-out;
-}
-
-[data-slot="mobile-tabs-overlay"]:is([data-closing], [data-closed]) {
-  animation: mobile-tabs-backdrop-out 200ms ease-in forwards;
-}
-
 /* Keep the strip mounted for tab shortcuts and session metadata while collapsed. */
 [data-slot="mobile-tabs-drawer"] {
-  box-sizing: border-box;
-  position: fixed;
-  inset-inline: 0;
-  bottom: 0;
-  z-index: 51;
   display: flex;
+  min-height: 0;
   flex-direction: column;
   gap: 8px;
-  max-height: min(75dvh, calc(100dvh - env(safe-area-inset-top, 0px) - 16px));
-  padding: 0 12px max(12px, env(safe-area-inset-bottom, 0px));
-  border-radius: 16px 16px 0 0;
-  background: var(--v2-background-bg-deep);
-  box-shadow: var(--v2-elevation-overlay);
-  outline: none;
-}
-
-[data-slot="mobile-tabs-drawer"][data-transitioning] {
-  transition: transform 240ms cubic-bezier(0.2, 0.8, 0.2, 1);
-}
-
-[data-slot="mobile-tabs-drawer"][data-closing] {
-  transition-duration: 200ms;
-}
-
-[data-slot="mobile-tabs-drawer"][data-closed] {
-  visibility: hidden;
-  pointer-events: none;
-}
-
-[data-slot="mobile-tabs-drag-handle"] {
-  display: flex;
-  height: 28px;
-  flex-shrink: 0;
-  align-items: center;
-  justify-content: center;
-  touch-action: none;
-}
-
-[data-slot="mobile-tabs-drag-handle"] span {
-  width: 32px;
-  height: 4px;
-  border-radius: 999px;
-  background: var(--v2-border-border-strong);
+  margin-block-start: 8px;
 }
 
 [data-slot="mobile-tabs-drawer-list"] {
@@ -79,36 +29,6 @@
   flex-direction: column;
 }
 
-@keyframes mobile-tabs-backdrop-in {
-  from {
-    opacity: 0;
-  }
-  to {
-    opacity: 1;
-  }
-}
-
-@keyframes mobile-tabs-backdrop-out {
-  from {
-    opacity: 1;
-  }
-  to {
-    opacity: 0;
-  }
-}
-
-@media (prefers-reduced-motion: reduce) {
-  [data-slot="mobile-tabs-drawer"][data-transitioning],
-  [data-slot="mobile-tabs-drawer"][data-closing] {
-    transition: none;
-  }
-
-  [data-slot="mobile-tabs-overlay"],
-  [data-slot="mobile-tabs-overlay"]:is([data-closing], [data-closed]) {
-    animation: none;
-  }
-}
-
 [data-slot="mobile-tabs-drawer"] [data-slot="vertical-tabs"] {
   display: flex;
   flex-direction: column;

packages/app/src/shell/titlebar/titlebar.tsx

@@ -25,7 +25,7 @@ import type { ComposerState } from "@/composer/persistence"
 import "./titlebar.css"
 import { newTabTooltipKeybind } from "@/shell/commands/tooltip-keybind"
 import { TitlebarRightMount } from "@/shell/titlebar/right-slot"
-import Drawer from "@corvu/drawer"
+import { MobileDrawer, MobileDrawerContent, MobileDrawerLabel, MobileDrawerTrigger } from "@/shell/mobile-drawer"
 import { sessionLabel } from "@/session/title"
 import { SessionTabAvatar } from "@/shell/layout/session-tab-avatar"
 import { projectForSession } from "@/shell/layout/helpers"
@@ -415,7 +415,7 @@ export function Titlebar(props: {
                 <Show
                   when={!mobile()}
                   fallback={
-                    <Drawer
+                    <MobileDrawer
                       open={mobileTabs.open}
                       onOpenChange={(open) => setMobileTabs("open", open)}
                       onContentPresentChange={(present) => {
@@ -423,11 +423,9 @@ export function Titlebar(props: {
                         setMobileTabs("settings", false)
                         openSettings()
                       }}
-                      side="bottom"
                     >
-                      <Drawer.Trigger
+                      <MobileDrawerTrigger
                         data-slot="mobile-tabs-trigger"
-                        aria-expanded={mobileTabs.open}
                         class="flex h-7 min-w-0 flex-1 items-center gap-2 rounded-[6px] px-2 text-[13px] leading-4 text-v2-text-text-base focus-visible:outline-none [app-region:no-drag]"
                         aria-label={language.t("titlebar.tabs")}
                       >
@@ -467,15 +465,11 @@ export function Titlebar(props: {
                           {currentTitle()}
                         </span>
                         <span class="shrink-0 text-v2-text-text-muted">{tabsStore.length}</span>
-                      </Drawer.Trigger>
-                      <Drawer.Portal forceMount>
-                        <Drawer.Overlay data-slot="mobile-tabs-overlay" />
-                        <Drawer.Content forceMount data-slot="mobile-tabs-drawer" dir={language.direction()}>
-                          <Drawer.Label class="sr-only">{language.t("titlebar.tabs")}</Drawer.Label>
-                          <div data-slot="mobile-tabs-drag-handle" aria-hidden="true">
-                            <span />
-                          </div>
-                          <div data-slot="mobile-tabs-drawer-list" data-corvu-no-drag>
+                      </MobileDrawerTrigger>
+                      <MobileDrawerContent>
+                        <MobileDrawerLabel class="sr-only">{language.t("titlebar.tabs")}</MobileDrawerLabel>
+                        <div data-slot="mobile-tabs-drawer" data-corvu-no-drag>
+                          <div data-slot="mobile-tabs-drawer-list">
                             <TitlebarTabStrip
                               orientation="vertical"
                               tabs={tabsStore}
@@ -493,7 +487,6 @@ export function Titlebar(props: {
                           </div>
                           <button
                             type="button"
-                            data-corvu-no-drag
                             data-action="mobile-tabs-new-session"
                             class="flex h-7 w-full shrink-0 items-center gap-2 rounded-[6px] px-2 text-[13px] leading-4 text-v2-text-text-base hover:bg-v2-background-bg-layer-02 focus-visible:outline-none focus-visible:bg-v2-background-bg-layer-02"
                             onClick={() => {
@@ -504,10 +497,7 @@ export function Titlebar(props: {
                             <Icon name="plus" />
                             {language.t("command.session.new")}
                           </button>
-                          <div
-                            class="flex shrink-0 flex-col gap-1 border-t border-v2-border-border-muted pt-2"
-                            data-corvu-no-drag
-                          >
+                          <div class="flex shrink-0 flex-col gap-1 border-t border-v2-border-border-muted pt-2">
                             <button
                               type="button"
                               data-action="mobile-tabs-home"
@@ -546,9 +536,9 @@ export function Titlebar(props: {
                               </button>
                             </div>
                           </div>
-                        </Drawer.Content>
-                      </Drawer.Portal>
-                    </Drawer>
+                        </div>
+                      </MobileDrawerContent>
+                    </MobileDrawer>
                   }
                 >
                   <Show

packages/app/vite.icons.test.ts

@@ -59,6 +59,7 @@ test.each(["dev", "beta", "prod"])("serves %s app icons", async (channel) => {
 async function check(channel: string, read: (path: string) => Promise<Uint8Array>) {
   const html = new TextDecoder().decode(await read("/index.html"))
   const actual: typeof manifest = JSON.parse(new TextDecoder().decode(await read("/site.webmanifest")))
+  expect(actual.icons.every((icon) => icon.purpose === "maskable")).toBe(true)
   expect(actual).toEqual({
     ...manifest,
     icons: manifest.icons.map((icon) => ({ ...icon, src: `/icons/${channel}${icon.src}` })),

packages/cli/src/commands/commands.ts

@@ -1,6 +1,7 @@
 import { Argument, Flag, GlobalFlag } from "effect/unstable/cli"
 import { Schema } from "effect"
 import { Spec } from "../framework/spec"
+import { Updater } from "../services/updater"
 
 export const PrintLogs = GlobalFlag.setting("print-logs")({
   flag: Flag.boolean("print-logs").pipe(
@@ -56,6 +57,20 @@ const Root = Spec.make(typeof OPENCODE_CLI_NAME === "string" ? OPENCODE_CLI_NAME
     prompt: Flag.string("prompt").pipe(Flag.withDescription("Prompt to use"), Flag.optional),
   },
   commands: [
+    Spec.make("upgrade", {
+      description: "Upgrade OpenCode to the latest or a specific version",
+      params: {
+        target: Argument.string("target").pipe(
+          Argument.withDescription("Version to upgrade to (with or without a leading v)"),
+          Argument.optional,
+        ),
+        method: Flag.choice("method", Updater.methods).pipe(
+          Flag.withAlias("m"),
+          Flag.withDescription("Installation method to use"),
+          Flag.optional,
+        ),
+      },
+    }),
     Spec.make("acp", { description: "Start an Agent Client Protocol server" }),
     Spec.make("api", {
       description: "Make a request to the running server",

packages/cli/src/commands/handlers/plugin/list.ts

@@ -54,7 +54,7 @@ export function format(
     plugin.state.status !== "active" || !plugin.features.tui
       ? []
       : plugin.source.type === "package"
-        ? [{ target: plugin.source.package, source: "advertised" as const }]
+        ? [{ target: plugin.source.target, source: "advertised" as const }]
         : plugin.source.type === "local"
           ? [{ target: path.dirname(plugin.source.path), source: "advertised" as const }]
           : [],
@@ -73,7 +73,7 @@ export function format(
 
 function name(plugin: PluginInfo) {
   if (plugin.id) return plugin.id
-  if (plugin.source.type === "package") return plugin.source.package
+  if (plugin.source.type === "package") return plugin.source.target
   if (plugin.source.type === "local") return plugin.source.path
   return plugin.source.type
 }

packages/cli/src/commands/handlers/upgrade.ts

@@ -0,0 +1,38 @@
+import { intro, log, outro, spinner } from "@clack/prompts"
+import { Effect, Option } from "effect"
+import { Commands } from "../commands"
+import { Runtime } from "../../framework/runtime"
+import { Updater } from "../../services/updater"
+import { handlePromptErrors } from "../../ui/prompt"
+import { OPENCODE_VERSION } from "../../version"
+
+export default Runtime.handler(
+  Commands.commands.upgrade,
+  Effect.fn("cli.upgrade")(function* (input) {
+    intro("Upgrade")
+    const updater = yield* Updater.Service
+    const method = Option.getOrUndefined(input.method) ?? (yield* updater.method())
+    if (!method)
+      return yield* Effect.fail(
+        new Error("Could not detect the installation method. Pass --method to choose how to upgrade OpenCode."),
+      )
+
+    log.info(`Using method: ${method}`)
+    const target = Option.getOrUndefined(input.target) ?? (yield* updater.latest())
+    const version = target.trim().replace(/^v/, "")
+    if (version === OPENCODE_VERSION) {
+      log.warn(`OpenCode upgrade skipped: ${version} is already installed`)
+      outro("Done")
+      return
+    }
+
+    log.info(`From ${OPENCODE_VERSION} → ${version}`)
+    const progress = spinner()
+    progress.start("Upgrading...")
+    yield* updater.upgrade(method, target).pipe(
+      Effect.tap(() => Effect.sync(() => progress.stop("Upgrade complete"))),
+      Effect.tapCause(() => Effect.sync(() => progress.stop("Upgrade failed", 1))),
+    )
+    outro("Done")
+  }, handlePromptErrors),
+)

packages/cli/src/index.ts

@@ -17,6 +17,7 @@ import { CpuProfile } from "./cpu-profile"
 
 const Handlers = Runtime.handlers(Commands, {
   $: () => import("./commands/handlers/default"),
+  upgrade: () => import("./commands/handlers/upgrade"),
   acp: () => import("./commands/handlers/acp"),
   api: () => import("./commands/handlers/api"),
   auth: {
@@ -98,12 +99,13 @@ Effect.gen(function* () {
   Effect.provide(Config.layer),
   Effect.provide(Updater.layer),
   Effect.provide(
-    LayerNode.compile(LayerNode.group([Global.node, AppProcess.node, Npm.node]), [
-      [
-        Global.node,
-        Global.layerWith(process.env.OPENCODE_CONFIG_DIR ? { config: process.env.OPENCODE_CONFIG_DIR } : {}),
+    LayerNode.compile(LayerNode.group([Global.node, AppProcess.node, Npm.node]), {
+      replacements: [
+        Global.node.replace(
+          Global.layerWith(process.env.OPENCODE_CONFIG_DIR ? { config: process.env.OPENCODE_CONFIG_DIR } : {}),
+        ),
       ],
-    ]),
+    }),
   ),
   Effect.provide(
     Observability.layer({

packages/cli/src/mini-host.ts

@@ -4,6 +4,7 @@ import fs from "node:fs"
 import { readFile } from "node:fs/promises"
 import path from "node:path"
 import { ReadStream } from "node:tty"
+import { OPENCODE_VERSION } from "./version"
 
 export const INTERACTIVE_INPUT_ERROR = "opencode mini requires a controlling terminal for input"
 
@@ -137,6 +138,7 @@ export function createMiniHost(input: {
     argv: process.argv.slice(2),
   }
   return {
+    version: OPENCODE_VERSION,
     terminal: { stdin: input.terminal.stdin },
     platform: process.platform,
     stdout: {

packages/cli/src/server-process.ts

@@ -30,12 +30,13 @@ export const run = Effect.fnUntraced(function* (options: Options) {
   return yield* processEffect(options).pipe(
     Effect.provide(Updater.layer),
     Effect.provide(
-      LayerNode.compile(LayerNode.group([Global.node, AppProcess.node]), [
-        [
-          Global.node,
-          Global.layerWith(process.env.OPENCODE_CONFIG_DIR ? { config: process.env.OPENCODE_CONFIG_DIR } : {}),
+      LayerNode.compile(LayerNode.group([Global.node, AppProcess.node]), {
+        replacements: [
+          Global.node.replace(
+            Global.layerWith(process.env.OPENCODE_CONFIG_DIR ? { config: process.env.OPENCODE_CONFIG_DIR } : {}),
+          ),
         ],
-      ]),
+      }),
     ),
     Effect.provide(NodeServices.layer),
   )

packages/cli/src/services/updater-action.ts

@@ -15,7 +15,7 @@ export function action(current: string, latest: string, policy: Policy): Action
   return policy === "notify" ? "notify" : "upgrade"
 }
 
-function parseReleaseVersion(input: string) {
+export function parseReleaseVersion(input: string) {
   if (input.length > 256) return
   const match = input.trim().match(versionPattern)
   if (!match) return

packages/cli/src/services/updater.ts

@@ -5,19 +5,21 @@ import { Context, Duration, Effect, FileSystem, Layer } from "effect"
 import { ChildProcess } from "effect/unstable/process"
 import { parse, type ParseError } from "jsonc-parser"
 import path from "node:path"
-import { action, type Policy } from "./updater-action"
+import { action, parseReleaseVersion, type Policy } from "./updater-action"
 
 declare const OPENCODE_CLI_NAME: string | undefined
 
-type Method = "npm" | "pnpm" | "bun" | "yarn" | "curl"
+export const methods = ["curl", "npm", "pnpm", "bun", "yarn"] as const
+export type Method = (typeof methods)[number]
 
 const packageName =
-  typeof OPENCODE_CLI_NAME === "string" && OPENCODE_CLI_NAME === "opencode2-node"
-    ? OPENCODE_CLI_NAME
-    : "@opencode-ai/cli"
+  typeof OPENCODE_CLI_NAME === "string" && OPENCODE_CLI_NAME === "opencode2-node" ? "opencode-node" : "@opencode-ai/cli"
 
 export interface Interface {
   readonly check: () => Effect.Effect<void>
+  readonly method: () => Effect.Effect<Method | undefined>
+  readonly latest: () => Effect.Effect<string, Error>
+  readonly upgrade: (method: Method, version: string) => Effect.Effect<void, Error>
 }
 
 export class Service extends Context.Service<Service, Interface>()("@opencode/cli/Updater") {}
@@ -110,7 +112,9 @@ export const layer = Layer.effect(
       return data.version
     })
 
-    const upgrade = Effect.fnUntraced(function* (method: Method, version: string) {
+    const upgrade = Effect.fnUntraced(function* (method: Method, input: string) {
+      if (!parseReleaseVersion(input)) return yield* Effect.fail(new Error(`Invalid version: ${input}`))
+      const version = input.trim().replace(/^v/, "")
       const target = `${packageName}@${version}`
       const commands: Record<Exclude<Method, "bun" | "curl">, string[]> = {
         npm: ["npm", "install", "--global", target],
@@ -138,7 +142,7 @@ export const layer = Layer.effect(
           }
           return yield* run(commands[method], "5 minutes")
         }),
-      )
+      ).pipe(Effect.mapError((cause) => new Error(`Failed to update with ${method}`, { cause })))
       if (result.code === 0) return
       return yield* Effect.fail(new Error(result.stderr.trim() || `Failed to update with ${method}`))
     })
@@ -173,7 +177,7 @@ export const layer = Layer.effect(
       Effect.catchCause((cause) => Effect.logWarning("automatic update failed", { cause })),
     )
 
-    return Service.of({ check })
+    return Service.of({ check, method, latest, upgrade })
   }),
 )
 

packages/cli/test/config.test.ts

@@ -486,7 +486,14 @@ test("updates a config draft while preserving JSONC comments", async () => {
       const service = yield* Config.Service
       return yield* service.update((draft) => {
         draft.prompt = { paste: "compact" }
-        draft.mini = { thinking: "hide", shell_output: "hide", turn_summary: "hide", splash: "hide", mono: true }
+        draft.mini = {
+          thinking: "hide",
+          shell_output: "hide",
+          turn_summary: "hide",
+          splash: "hide",
+          work_spinner: "block-low-comet",
+          mono: true,
+        }
       })
     }),
   )
@@ -494,7 +501,14 @@ test("updates a config draft while preserving JSONC comments", async () => {
   expect(config).toEqual({
     animations: true,
     prompt: { paste: "compact" },
-    mini: { thinking: "hide", shell_output: "hide", turn_summary: "hide", splash: "hide", mono: true },
+    mini: {
+      thinking: "hide",
+      shell_output: "hide",
+      turn_summary: "hide",
+      splash: "hide",
+      work_spinner: "block-low-comet",
+      mono: true,
+    },
   })
   expect(await Bun.file(path.join(directory.path, "cli.json")).text()).toContain("// Keep this comment")
 })

packages/cli/test/fixture/upgrade.ts

@@ -0,0 +1,36 @@
+import { NodeServices } from "@effect/platform-node"
+import { Effect } from "effect"
+import { Command } from "effect/unstable/cli"
+import { Commands } from "../../src/commands/commands"
+import upgrade from "../../src/commands/handlers/upgrade"
+import { Updater } from "../../src/services/updater"
+
+const record = (event: unknown) => console.log(`EVENT ${JSON.stringify(event)}`)
+
+await Effect.runPromise(
+  Command.runWith(Commands.commands.upgrade.spec.pipe(Command.withHandler(upgrade)), { version: "test" })(
+    process.argv.slice(2),
+  ).pipe(
+    Effect.provideService(Updater.Service, {
+      check: () => Effect.die("Manual upgrades must not run the automatic update check"),
+      method: () =>
+        Effect.sync(() => {
+          record("method")
+          return Updater.methods.find((method) => method === (process.env.UPGRADE_TEST_METHOD ?? "npm"))
+        }),
+      latest: () =>
+        Effect.suspend(() => {
+          record("latest")
+          return process.env.UPGRADE_TEST_LATEST_ERROR
+            ? Effect.fail(new Error("Update check failed"))
+            : Effect.succeed("0.0.0-beta-new")
+        }),
+      upgrade: (method, version) =>
+        Effect.suspend(() => {
+          record({ method, version })
+          return process.env.UPGRADE_TEST_INSTALL_ERROR ? Effect.fail(new Error("Permission denied")) : Effect.void
+        }),
+    }),
+    Effect.provide(NodeServices.layer),
+  ),
+)

packages/cli/test/mini-host.test.ts

@@ -9,6 +9,7 @@ import {
   type InteractiveStdin,
   usingInteractiveStdin,
 } from "../src/mini-host"
+import { OPENCODE_VERSION } from "../src/version"
 import { tmpdir } from "./fixture/tmpdir"
 
 const model = { providerID: "openai", modelID: "gpt-5" }
@@ -145,6 +146,7 @@ describe("Mini CLI host", () => {
     const input = host({ stdin: stream(true), cleanup() {} }, directory.path)
 
     expect(input.paths).toEqual({ home: directory.path })
+    expect(input.version).toBe(OPENCODE_VERSION)
     expect(input.platform).toBe(process.platform)
     expect(typeof input.files.readText).toBe("function")
     const file = path.join(directory.path, "attachment.txt")

packages/cli/test/plugin-list.test.ts

@@ -9,12 +9,12 @@ test("formats server and TUI plugins in sections without builtins", () => {
         { id: "opencode.agent", source: { type: "builtin" }, state: { status: "active" }, features: { server: true } },
         {
           id: "acme.dual",
-          source: { type: "package", package: "acme-plugin@1.0.0" },
+          source: { type: "package", target: "acme-plugin@1.0.0" },
           state: { status: "active" },
           features: { server: true, tui: true },
         },
         {
-          source: { type: "package", package: "broken-plugin" },
+          source: { type: "package", target: "broken-plugin" },
           state: { status: "failed", error: "broken" },
           features: { server: true },
         },

packages/cli/test/updater-install.test.ts

@@ -0,0 +1,227 @@
+import { NodeServices } from "@effect/platform-node"
+import { Global } from "@opencode-ai/util/global"
+import { AppProcess } from "@opencode-ai/util/process"
+import { expect, test } from "bun:test"
+import { Effect, FileSystem, Stream } from "effect"
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process"
+import { existsSync } from "node:fs"
+import path from "node:path"
+import { Updater } from "../src/services/updater"
+import { testEffect } from "../../core/test/lib/effect"
+
+const it = testEffect(NodeServices.layer)
+
+declare const OPENCODE_CLI_NAME: string | undefined
+
+function fixture(
+  respond: (command: ChildProcess.StandardCommand) => Partial<AppProcess.RunResult> & {
+    error?: AppProcess.AppProcessError
+  } = () => ({}),
+) {
+  return Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem
+    const spawner = yield* ChildProcessSpawner.ChildProcessSpawner
+    const root = yield* fs.makeTempDirectoryScoped({ prefix: "opencode-updater-" })
+    const global = Global.make({
+      home: path.join(root, "home"),
+      data: path.join(root, "data"),
+      cache: path.join(root, "cache"),
+      config: path.join(root, "config"),
+      state: path.join(root, "state"),
+      tmp: path.join(root, "tmp"),
+      bin: path.join(root, "bin"),
+      log: path.join(root, "log"),
+      repos: path.join(root, "repos"),
+    })
+    const commands: string[][] = []
+    const updater = yield* Updater.Service.pipe(
+      Effect.provide(Updater.layer),
+      Effect.provideService(Global.Service, global),
+      Effect.provideService(
+        AppProcess.Service,
+        AppProcess.Service.of({
+          ...spawner,
+          run: (command) =>
+            Effect.suspend(() => {
+              if (command._tag !== "StandardCommand") return Effect.die("Unexpected piped install command")
+              commands.push([command.command, ...command.args])
+              const result = respond(command)
+              if (result.error) return Effect.fail(result.error)
+              return Effect.succeed({
+                command: command.command,
+                exitCode: 0,
+                stdout: Buffer.alloc(0),
+                stderr: Buffer.alloc(0),
+                stdoutTruncated: false,
+                stderrTruncated: false,
+                ...result,
+              })
+            }),
+          runStream: () => Stream.die("Unexpected streaming install command"),
+        }),
+      ),
+    )
+    return { updater, commands, global, fs }
+  })
+}
+
+const installs = [
+  { method: "npm", command: ["npm", "install", "--global", "@opencode-ai/cli@2.3.4-beta.1"] },
+  {
+    method: "pnpm",
+    command: ["pnpm", "add", "--global", "--allow-build=@opencode-ai/cli", "@opencode-ai/cli@2.3.4-beta.1"],
+  },
+  { method: "yarn", command: ["yarn", "global", "add", "@opencode-ai/cli@2.3.4-beta.1"] },
+] as const
+
+installs.forEach(({ method, command }) => {
+  it.live(`${method} installs the explicit V2 package version without a leading v`, () =>
+    Effect.gen(function* () {
+      const test = yield* fixture()
+      yield* test.updater.upgrade(method, "v2.3.4-beta.1")
+      expect(test.commands).toEqual([[...command]])
+    }),
+  )
+})
+;[0, 1].forEach((exitCode) => {
+  it.live(`bun isolates and removes its install cache after exit ${exitCode}`, () =>
+    Effect.gen(function* () {
+      const test = yield* fixture((command) => {
+        expect(command.command).toBe("bun")
+        expect(existsSync(command.args[4])).toBe(true)
+        return { exitCode, stderr: Buffer.from("bun install failed") }
+      })
+      const result = yield* test.updater.upgrade("bun", "v2.3.4-beta.1").pipe(Effect.flip, Effect.option)
+      const cache = test.commands[0]?.[5]
+      expect(cache).toStartWith(path.join(test.global.cache, "update-"))
+      expect(test.commands).toEqual([
+        ["bun", "install", "--global", "--trust", "--cache-dir", cache, "@opencode-ai/cli@2.3.4-beta.1"],
+      ])
+      expect(yield* test.fs.readDirectory(test.global.cache)).toEqual([])
+      expect(result._tag).toBe(exitCode === 0 ? "None" : "Some")
+      if (result._tag === "Some") expect(result.value.message).toBe("bun install failed")
+    }),
+  )
+})
+;["success", "download", "install"].forEach((failure) => {
+  it.live(`curl uses the V2 installer and cleans its directory: ${failure}`, () =>
+    Effect.gen(function* () {
+      const test = yield* fixture((command) => {
+        const installer = command.command === "curl" ? command.args[2] : command.args[0]
+        expect(existsSync(path.dirname(installer))).toBe(true)
+        return {
+          exitCode: command.command === (failure === "download" ? "curl" : failure === "install" ? "bash" : "") ? 1 : 0,
+          stderr: Buffer.from(`${failure} failed`),
+        }
+      })
+      const result = yield* test.updater.upgrade("curl", "v2.3.4-beta.1").pipe(Effect.flip, Effect.option)
+      const installer = test.commands[0]?.[3]
+      expect(installer).toStartWith(path.join(test.global.cache, "update-"))
+      expect(test.commands).toEqual([
+        ["curl", "-fsSL", "-o", installer, "https://opencode.ai/v2/install"],
+        ...(failure === "download" ? [] : [["bash", installer, "--version", "2.3.4-beta.1", "--no-modify-path"]]),
+      ])
+      expect(yield* test.fs.readDirectory(test.global.cache)).toEqual([])
+      expect(result._tag).toBe(failure === "success" ? "None" : "Some")
+      if (result._tag === "Some") expect(result.value.message).toBe(`${failure} failed`)
+    }),
+  )
+})
+
+it.live("invalid version targets never execute a command or create a cache", () =>
+  Effect.gen(function* () {
+    const test = yield* fixture()
+    yield* Effect.forEach(Updater.methods, (method) =>
+      Effect.forEach(
+        ["", "latest", "2.3", "01.2.3", "vv2.3.4", "2.3.4; echo unsafe", "--global", "v2.3.4\n--force"],
+        (version) =>
+          Effect.gen(function* () {
+            const error = yield* test.updater.upgrade(method, version).pipe(Effect.flip)
+            expect(error.message).toBe(`Invalid version: ${version}`)
+          }),
+      ),
+    )
+    expect(test.commands).toEqual([])
+    expect(yield* test.fs.exists(test.global.cache)).toBe(false)
+  }),
+)
+
+it.live("install failures expose stderr and process errors do not report success", () =>
+  Effect.gen(function* () {
+    const failed = yield* fixture(() => ({ exitCode: 1, stderr: Buffer.from("  registry denied access\n") }))
+    const error = yield* failed.updater.upgrade("npm", "2.3.4").pipe(Effect.flip)
+    expect(error.message).toBe("registry denied access")
+    const missing = yield* fixture(() => ({ error: new AppProcess.AppProcessError({ command: "npm" }) }))
+    const unavailable = yield* missing.updater.upgrade("npm", "2.3.4").pipe(Effect.flip)
+    expect(unavailable.message).toBe("Failed to update with npm")
+    expect(failed.commands).toHaveLength(1)
+    expect(missing.commands).toHaveLength(1)
+  }),
+)
+;(["npm", "pnpm", "bun", "yarn", undefined] as const).forEach((method) => {
+  it.live(`method detection identifies ${method ?? "an unknown installation"} using the V2 package`, () =>
+    Effect.gen(function* () {
+      const test = yield* fixture((command) => ({
+        stdout: Buffer.from(command.command === method ? "@opencode-ai/cli@2.3.4" : "opencode-ai@1.0.0"),
+      }))
+      expect(yield* test.updater.method()).toBe(method)
+      expect(test.commands).toEqual([
+        ["npm", "list", "-g", "--depth=0", "@opencode-ai/cli"],
+        ["pnpm", "list", "-g", "--depth=0", "@opencode-ai/cli"],
+        ["bun", "pm", "ls", "-g"],
+        ["yarn", "global", "list"],
+      ])
+    }),
+  )
+})
+
+it.live("method detection tolerates unavailable package managers", () =>
+  Effect.gen(function* () {
+    const test = yield* fixture((command) =>
+      command.command === "yarn"
+        ? { stdout: Buffer.from("@opencode-ai/cli@2.3.4") }
+        : { error: new AppProcess.AppProcessError({ command: command.command }) },
+    )
+    expect(yield* test.updater.method()).toBe("yarn")
+    expect(test.commands).toHaveLength(4)
+  }),
+)
+
+test("Node distribution honors the compile-time CLI name", async () => {
+  const child = Bun.spawn(
+    [
+      process.execPath,
+      "test",
+      import.meta.path,
+      "--define",
+      'OPENCODE_CLI_NAME="opencode2-node"',
+      "--test-name-pattern",
+      "^Node distribution resolves the published npm package$",
+    ],
+    { cwd: path.join(import.meta.dir, ".."), stdout: "ignore", stderr: "pipe" },
+  )
+  const [code, stderr] = await Promise.all([child.exited, new Response(child.stderr).text()])
+  expect(code, stderr).toBe(0)
+  expect(stderr).toContain("1 pass")
+})
+
+if (typeof OPENCODE_CLI_NAME === "string" && OPENCODE_CLI_NAME === "opencode2-node") {
+  it.live("Node distribution resolves the published npm package", () =>
+    Effect.gen(function* () {
+      const test = yield* fixture((command) => ({
+        stdout: Buffer.from(command.command === "npm" ? "opencode-node@2.3.4" : ""),
+      }))
+      expect(yield* test.updater.method()).toBe("npm")
+      yield* test.updater.upgrade("npm", "v2.3.4")
+      yield* test.updater.upgrade("pnpm", "v2.3.4")
+      expect(test.commands).toEqual([
+        ["npm", "list", "-g", "--depth=0", "opencode-node"],
+        ["pnpm", "list", "-g", "--depth=0", "opencode-node"],
+        ["bun", "pm", "ls", "-g"],
+        ["yarn", "global", "list"],
+        ["npm", "install", "--global", "opencode-node@2.3.4"],
+        ["pnpm", "add", "--global", "--allow-build=opencode-node", "opencode-node@2.3.4"],
+      ])
+    }),
+  )
+}

packages/cli/test/upgrade.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, test } from "bun:test"
+import { mkdtemp, rm } from "node:fs/promises"
+import os from "node:os"
+import path from "node:path"
+
+describe("upgrade command", () => {
+  test("is registered in root help and documents its options", async () => {
+    const root = await cli(["--help"], {}, "../src/index.ts")
+    const help = await cli(["upgrade", "--help"], {}, "../src/index.ts")
+    expect(root.exitCode).toBe(0)
+    expect(root.stdout).toContain("upgrade")
+    expect(help.exitCode).toBe(0)
+    expect(help.stdout).toContain("[<target>]")
+    expect(help.stdout).toContain("--method")
+    expect(help.stdout).toContain("-m")
+  })
+
+  test("detects the installation method and resolves the latest version", async () => {
+    const result = await cli([])
+    expect(result.exitCode).toBe(0)
+    expect(result.events).toEqual(["method", "latest", { method: "npm", version: "0.0.0-beta-new" }])
+    expect(result.stdout).toContain("Upgrade complete")
+  })
+
+  test("accepts an explicit version and method without detection or a version lookup", async () => {
+    const result = await cli(["v0.0.0-beta-target", "--method", "pnpm"])
+    expect(result.exitCode).toBe(0)
+    expect(result.events).toEqual([{ method: "pnpm", version: "v0.0.0-beta-target" }])
+    expect(result.stdout).toContain("0.0.0-beta-old → 0.0.0-beta-target")
+  })
+
+  test("accepts the short method flag and an explicit major upgrade", async () => {
+    const result = await cli(["2.0.0", "-m", "bun"])
+    expect(result.exitCode).toBe(0)
+    expect(result.events).toEqual([{ method: "bun", version: "2.0.0" }])
+  })
+
+  test("skips the already installed version", async () => {
+    const result = await cli(["v0.0.0-beta-old"])
+    expect(result.exitCode).toBe(0)
+    expect(result.events).toEqual(["method"])
+    expect(result.stdout).toContain("already installed")
+  })
+
+  test("requires an explicit method when detection fails", async () => {
+    const result = await cli([], { UPGRADE_TEST_METHOD: "unknown" })
+    expect(result.exitCode).toBe(1)
+    expect(result.events).toEqual(["method"])
+    expect(result.stdout).toContain("Pass --method")
+  })
+
+  test("rejects unsupported methods before attempting an upgrade", async () => {
+    const result = await cli(["--method", "brew"])
+    expect(result.exitCode).not.toBe(0)
+    expect(result.events).toEqual([])
+  })
+
+  test("reports version lookup failures without installing", async () => {
+    const result = await cli([], { UPGRADE_TEST_LATEST_ERROR: "1" })
+    expect(result.exitCode).toBe(1)
+    expect(result.events).toEqual(["method", "latest"])
+    expect(result.stdout).toContain("Update check failed")
+  })
+
+  test("reports installation failures with a nonzero exit code", async () => {
+    const result = await cli([], { UPGRADE_TEST_INSTALL_ERROR: "1" })
+    expect(result.exitCode).toBe(1)
+    expect(result.stdout).toContain("Upgrade failed")
+    expect(result.stdout).toContain("Permission denied")
+    expect(result.stdout).not.toContain("Upgrade complete")
+  })
+})
+
+async function cli(args: string[], env: Record<string, string> = {}, entry = "fixture/upgrade.ts") {
+  const root = await mkdtemp(path.join(os.tmpdir(), "opencode-upgrade-"))
+  try {
+    const child = Bun.spawn(
+      [process.execPath, "--define", 'OPENCODE_VERSION="0.0.0-beta-old"', path.join(import.meta.dir, entry), ...args],
+      {
+        cwd: path.join(import.meta.dir, ".."),
+        env: {
+          ...process.env,
+          OPENCODE_TEST_HOME: root,
+          XDG_DATA_HOME: path.join(root, "data"),
+          XDG_CONFIG_HOME: path.join(root, "config"),
+          XDG_CACHE_HOME: path.join(root, "cache"),
+          XDG_STATE_HOME: path.join(root, "state"),
+          OPENCODE_DISABLE_AUTOUPDATE: "1",
+          ...env,
+        },
+        stdout: "pipe",
+        stderr: "pipe",
+      },
+    )
+    const [stdout, stderr, exitCode] = await Promise.all([
+      new Response(child.stdout).text(),
+      new Response(child.stderr).text(),
+      child.exited,
+    ])
+    const events = stdout
+      .split("\n")
+      .filter((line) => line.startsWith("EVENT "))
+      .map((line) => JSON.parse(line.slice(6)))
+    expect(await Bun.file(path.join(root, "state", "opencode", "service-local.json")).exists()).toBe(false)
+    return { stdout, stderr, exitCode, events }
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+}

packages/client/src/effect/api/api.ts

@@ -88,8 +88,16 @@ export type PluginListInput = {
 export type PluginListOutput = { readonly location: Location.Info; readonly data: ReadonlyArray<Plugin.Info> }
 export type PluginListOperation<E = never> = (input?: PluginListInput) => Effect.Effect<PluginListOutput, E>
 
+export type PluginUpdateInput = {
+  readonly location?: { readonly directory?: string | undefined; readonly workspace?: string | undefined } | undefined
+  readonly target: string
+}
+export type PluginUpdateOutput = void
+export type PluginUpdateOperation<E = never> = (input: PluginUpdateInput) => Effect.Effect<PluginUpdateOutput, E>
+
 export interface PluginApi<E = never> {
   readonly list: PluginListOperation<E>
+  readonly update: PluginUpdateOperation<E>
 }
 
 export type SessionListInput = {

packages/client/src/effect/generated/client.ts

@@ -15,6 +15,8 @@ import type {
   AgentGetOutput,
   PluginListInput,
   PluginListOutput,
+  PluginUpdateInput,
+  PluginUpdateOutput,
   SessionListInput,
   SessionListOutput,
   SessionStatsInput,
@@ -322,7 +324,17 @@ const EndpointPluginList = (raw: RawClient["server.plugin"]) => (input?: PluginL
     raw["plugin.list"]({ query: { location: input?.["location"] } }).pipe(Effect.mapError(mapClientError)),
   )
 
-const adaptGroupPlugin = (raw: RawClient["server.plugin"]) => ({ list: EndpointPluginList(raw) })
+const EndpointPluginUpdate = (raw: RawClient["server.plugin"]) => (input: PluginUpdateInput) =>
+  preserveEffect<PluginUpdateOutput>()(
+    raw["plugin.update"]({ query: { location: input["location"] }, payload: { target: input["target"] } }).pipe(
+      Effect.mapError(mapClientError),
+    ),
+  )
+
+const adaptGroupPlugin = (raw: RawClient["server.plugin"]) => ({
+  list: EndpointPluginList(raw),
+  update: EndpointPluginUpdate(raw),
+})
 
 const EndpointSessionList = (raw: RawClient["server.session"]) => (input?: SessionListInput) =>
   preserveEffect<SessionListOutput>()(

packages/client/src/promise/generated/client.ts

@@ -9,6 +9,8 @@ import type {
   AgentGetOutput,
   PluginListInput,
   PluginListOutput,
+  PluginUpdateInput,
+  PluginUpdateOutput,
   SessionListInput,
   SessionListOutput,
   SessionStatsInput,
@@ -466,6 +468,19 @@ export function make(options: ClientOptions) {
           },
           requestOptions,
         ),
+      update: (input: PluginUpdateInput, requestOptions?: RequestOptions) =>
+        request<PluginUpdateOutput>(
+          {
+            method: "POST",
+            path: `/api/plugin/update`,
+            query: { location: input["location"] },
+            body: { target: input["target"] },
+            successStatus: 204,
+            declaredStatuses: [400, 503, 401],
+            empty: true,
+          },
+          requestOptions,
+        ),
     },
     session: {
       list: (input?: SessionListInput, requestOptions?: RequestOptions) =>

packages/client/src/promise/generated/types.ts

@@ -12,7 +12,7 @@ export type PermissionEffect = "allow" | "deny" | "ask"
 
 export type PluginSource =
   | { type: "builtin" }
-  | { type: "package"; package: string }
+  | { type: "package"; target: string; version?: string; outdated?: true }
   | { type: "local"; path: string }
   | { type: "sdk" }
 
@@ -2354,6 +2354,14 @@ export type AgentNotFoundError = {
 export const isAgentNotFoundError = (value: unknown): value is AgentNotFoundError =>
   typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "AgentNotFoundError"
 
+export type ServiceUnavailableError = {
+  readonly _tag: "ServiceUnavailableError"
+  readonly message: string
+  readonly service?: string | undefined
+}
+export const isServiceUnavailableError = (value: unknown): value is ServiceUnavailableError =>
+  typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "ServiceUnavailableError"
+
 export type InvalidCursorError = { readonly _tag: "InvalidCursorError"; readonly message: string }
 export const isInvalidCursorError = (value: unknown): value is InvalidCursorError =>
   typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "InvalidCursorError"
@@ -2415,14 +2423,6 @@ export type SkillNotFoundError = {
 export const isSkillNotFoundError = (value: unknown): value is SkillNotFoundError =>
   typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "SkillNotFoundError"
 
-export type ServiceUnavailableError = {
-  readonly _tag: "ServiceUnavailableError"
-  readonly message: string
-  readonly service?: string | undefined
-}
-export const isServiceUnavailableError = (value: unknown): value is ServiceUnavailableError =>
-  typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "ServiceUnavailableError"
-
 export type SessionBusyError = {
   readonly _tag: "SessionBusyError"
   readonly sessionID: string
@@ -2582,6 +2582,15 @@ export type PluginListOutput = {
   data: Array<PluginInfo>
 }
 
+export type PluginUpdateInput = {
+  readonly location?: {
+    readonly location?: { readonly directory?: string | undefined; readonly workspace?: string | undefined } | undefined
+  }["location"]
+  readonly target: { readonly target: string }["target"]
+}
+
+export type PluginUpdateOutput = void
+
 export type SessionListInput = {
   readonly workspace?: {
     readonly workspace?: string | undefined

packages/codemode/README.md

@@ -26,7 +26,7 @@ Unsupported syntax returns an `UnsupportedSyntax` diagnostic with a source locat
 ## Quick Start
 
 ```ts
-import { CodeMode, Tool } from "@opencode-ai/codemode"
+import { CodeMode, Namespace, Tool } from "@opencode-ai/codemode"
 import { Effect, Schema } from "effect"
 
 const lookupOrder = Tool.make({
@@ -60,9 +60,22 @@ only shape the model-visible signature. Without `output`, the signature uses `Pr
 
 Descriptions and schemas are model-visible contracts. Authorization belongs in `execute`.
 
-Dots in tool names create namespaces: `{ "issues.list": tool }` and `{ issues: { list: tool } }` both expose
-`tools.issues.list(...)`. Other characters use bracket notation, such as
-`tools.context7["resolve-library-id"](...)`.
+Nested records are the shorthand for ordinary namespaces. Use `Namespace.make` when a namespace needs a description:
+
+```ts
+const runtime = CodeMode.make({
+  tools: {
+    orders: Namespace.make({
+      description: "Purchases, fulfillment, and shipment tracking",
+      tools: { lookup: lookupOrder },
+    }),
+  },
+})
+```
+
+Namespace descriptions are optional and participate in search matching for every descendant tool. Names still come
+from record keys, so the wrapper does not repeat `orders`. Dots in keys create nested paths; other characters use
+bracket notation, such as `tools.context7["resolve-library-id"](...)`.
 
 ### `CodeMode.execute` and `CodeMode.make`
 
@@ -150,7 +163,7 @@ and `CodeMode.toolExpression(path)` supply the exact callable forms.
 
 The synchronous `search(...)` built-in is always available. It supports exact-path lookup, namespace-scoped search,
 empty-query browsing, and pagination, and returns callable paths with full signatures. Search counts toward
-`maxToolCalls`.
+`maxToolCalls`. Search also matches descriptions from enclosing `Namespace` values.
 
 ## Execution Limits
 

packages/codemode/src/index.ts

@@ -1,4 +1,5 @@
 export * as CodeMode from "./codemode.js"
+export * as Namespace from "./namespace.js"
 export * as Tool from "./tool.js"
 export * as OpenAPI from "./openapi/index.js"
 export { searchSignature, toolExpression } from "./codemode.js"

packages/codemode/src/interpreter/references.ts

@@ -1,5 +1,6 @@
 import {
   type AstNode,
+  AsyncIteratorSymbol,
   CodeModeFunction,
   CodeModeGenerator,
   CoercionFunction,
@@ -9,6 +10,7 @@ import {
   GeneratorMethodReference,
   InterpreterRuntimeError,
   IntrinsicReference,
+  IteratorSymbol,
   JsonMethodReference,
   PromiseCapabilityFunction,
   PromiseInstanceMethodReference,
@@ -42,13 +44,12 @@ export const isRuntimeReference = (value: unknown): boolean =>
   value instanceof SymbolNamespace ||
   isCodeModeValue(value)
 
-function* childValues(value: object): Generator<unknown> {
-  if (Array.isArray(value)) {
-    const length = value.length
-    for (let index = 0; index < length; index++) yield value[index]
-    return
+function* childValues(value: object): Generator {
+  for (const key of Reflect.ownKeys(value)) {
+    if (!Object.prototype.propertyIsEnumerable.call(value, key)) continue
+    if (typeof key === "symbol" && key !== AsyncIteratorSymbol && key !== IteratorSymbol) continue
+    yield Reflect.get(value, key)
   }
-  yield* Object.values(value)
 }
 
 export const containsRuntimeReference = (value: unknown): boolean => {
@@ -90,9 +91,14 @@ export const containsOpaqueReference = (value: unknown): boolean => {
 }
 
 // Reject cycles before mutation so later boundary walks remain safe.
-export const rejectCircularInsertion = (container: object, value: unknown, label: string, node: AstNode): void => {
+export const rejectCircularInsertion = (
+  container: object,
+  value: unknown,
+  label: string,
+  node: AstNode,
+  seen = new Set<object>(),
+): void => {
   const pending: Array<Iterator<unknown>> = [[value].values()]
-  const seen = new Set<object>()
   while (pending.length > 0) {
     const next = pending.at(-1)!.next()
     if (next.done) {
@@ -104,7 +110,7 @@ export const rejectCircularInsertion = (container: object, value: unknown, label
       throw new InterpreterRuntimeError(`${label} contains a circular value.`, node, "InvalidDataValue")
     if (current === null || typeof current !== "object" || isRuntimeReference(current) || seen.has(current)) continue
     seen.add(current)
-    pending.push(Array.isArray(current) ? current[Symbol.iterator]() : childValues(current))
+    pending.push(childValues(current))
   }
 }
 

packages/codemode/src/namespace.ts

@@ -0,0 +1,24 @@
+import type { Tools } from "./tools.js"
+
+/** A tool namespace with optional model-visible metadata. */
+export type Namespace<R = never> = {
+  readonly _tag: "CodeModeNamespace"
+  readonly description?: string
+  readonly tools: Tools<R>
+}
+
+/** Options for declaring one CodeMode namespace. */
+export type Options<R = never> = {
+  readonly description?: string
+  readonly tools: Tools<R>
+}
+
+export const isNamespace = <R = never>(value: Namespace<R> | Tools<R>): value is Namespace<R> =>
+  Object.hasOwn(value, "_tag") && value._tag === "CodeModeNamespace"
+
+/** Declares a namespace when descriptions or other namespace metadata are needed. */
+export const make = <R = never>(options: Options<R>): Namespace<R> => ({
+  _tag: "CodeModeNamespace",
+  ...(options.description === undefined ? {} : { description: options.description }),
+  tools: options.tools,
+})

packages/codemode/src/openapi/index.ts

@@ -53,7 +53,6 @@ export const fromSpec = (options: Options): Result => {
     if (!isRecord(pathValue)) continue
     for (const [method, operationValue] of Object.entries(pathValue)) {
       if (!methods.has(method) || !isRecord(operationValue)) continue
-      const segments = operationPath(method, path, operationValue, used, namespaces)
       const operation: Operation = {
         operationId: nonEmptyString(operationValue.operationId),
         method: method.toUpperCase(),
@@ -99,6 +98,7 @@ export const fromSpec = (options: Options): Result => {
         auth: options.auth,
         headers: options.headers ?? {},
       }
+      const segments = operationPath(method, path, operationValue, used, namespaces)
       used.add(segments.join("."))
       for (const index of segments.slice(0, -1).keys()) namespaces.add(segments.slice(0, index + 1).join("."))
       setTool(

packages/codemode/src/openapi/spec.ts

@@ -461,9 +461,7 @@ export const operationInput = (
   const fields = [...parameters.value, ...requestBody.value.fields]
 
   const conflicts = new Set(
-    [...Map.groupBy(fields, (field) => field.name)]
-      .filter(([, matches]) => new Set(matches.map((field) => field.location)).size > 1)
-      .map(([name]) => name),
+    [...Map.groupBy(fields, (field) => field.name)].filter(([, matches]) => matches.length > 1).map(([name]) => name),
   )
   const used = new Set<string>()
   return {

packages/codemode/src/stdlib/object.ts

@@ -1,12 +1,6 @@
 import { Effect } from "effect"
-import {
-  type AstNode,
-  AsyncIteratorSymbol,
-  InterpreterRuntimeError,
-  IteratorSymbol,
-  IteratorSymbols,
-} from "../interpreter/model.js"
-import { containsOpaqueReference } from "../interpreter/references.js"
+import { type AstNode, AsyncIteratorSymbol, InterpreterRuntimeError, IteratorSymbol } from "../interpreter/model.js"
+import { containsOpaqueReference, rejectCircularInsertion } from "../interpreter/references.js"
 import { isBlockedMember } from "../tool-runtime.js"
 import { isCodeModeValue, CodeModePromise } from "../values.js"
 import { boundedData, coerceToString } from "./value.js"
@@ -37,10 +31,6 @@ export const invokeObjectMethod = (name: string, args: Array<unknown>, node: Ast
     }
     return input as Record<string, unknown>
   }
-  const guardedSet = (out: Record<string, unknown>, key: string, item: unknown): void => {
-    if (isBlockedMember(key)) throw new InterpreterRuntimeError(`Property '${key}' is not available.`, node)
-    out[key] = item
-  }
   switch (name) {
     case "keys":
       return Object.keys(requireObject())
@@ -64,14 +54,29 @@ export const invokeObjectMethod = (name: string, args: Array<unknown>, node: Ast
         throw new InterpreterRuntimeError("Object.assign expects a data object target.", node)
       }
       const out = target as Record<string, unknown>
+      const seen = new Set<object>()
+      const guardedSet = (key: PropertyKey, item: unknown): void => {
+        if (typeof key === "string" && isBlockedMember(key))
+          throw new InterpreterRuntimeError(`Property '${key}' is not available.`, node)
+        rejectCircularInsertion(out, item, "Object.assign result", node, seen)
+        if (!Reflect.set(out, key, item))
+          throw new InterpreterRuntimeError(`Object.assign could not assign property '${String(key)}'.`, node).as(
+            "TypeError",
+          )
+      }
       for (const source of args.slice(1)) {
         if (source === null || source === undefined || isCodeModeValue(source)) continue
         if (typeof source !== "object" || Array.isArray(source)) {
           throw new InterpreterRuntimeError("Object.assign expects data objects.", node)
         }
-        for (const [key, item] of Object.entries(source)) guardedSet(out, key, item)
-        for (const symbol of IteratorSymbols) {
-          if (Object.hasOwn(source, symbol)) Reflect.set(out, symbol, Reflect.get(source, symbol))
+        for (const key of Reflect.ownKeys(source)) {
+          if (typeof key === "string") {
+            if (Object.prototype.propertyIsEnumerable.call(source, key)) guardedSet(key, Reflect.get(source, key))
+            continue
+          }
+          if (key !== AsyncIteratorSymbol && key !== IteratorSymbol) continue
+          if (!Object.prototype.propertyIsEnumerable.call(source, key)) continue
+          guardedSet(key, Reflect.get(source, key))
         }
       }
       return out

packages/codemode/src/tool-runtime.ts

@@ -8,6 +8,7 @@ import {
   inputTypeScript,
   outputTypeScript,
 } from "./tool-schema.js"
+import { isNamespace, type Namespace } from "./namespace.js"
 import { isTool, type Tool } from "./tool.js"
 import type { Tools } from "./tools.js"
 import {
@@ -277,6 +278,7 @@ export const copyOut = (value: unknown, mode: CopyOutMode): unknown => {
 // Dots in tool names are namespace separators; the last tool for a canonical path wins.
 type ToolNode<R> = {
   tool?: Tool<R>
+  namespace?: Namespace<R>
   readonly children: Map<string, ToolNode<R>>
 }
 
@@ -292,7 +294,10 @@ const toolTrie = <R>(tools: Tools<R>): ToolNode<R> => {
         current = child
       }
       if (isTool<R>(value)) current.tool = value
-      else insert(current, value)
+      else if (isNamespace<R>(value)) {
+        current.namespace = value
+        insert(current, value.tools)
+      } else insert(current, value)
     }
   }
   insert(root, tools)
@@ -302,29 +307,33 @@ const toolTrie = <R>(tools: Tools<R>): ToolNode<R> => {
 const canonicalSegments = (path: ReadonlyArray<string>): ReadonlyArray<string> =>
   path.flatMap((segment) => segment.split("."))
 
+type VisibleTool<R> = {
+  readonly path: string
+  readonly tool: Tool<R>
+  readonly namespaces: ReadonlyArray<Namespace<R>>
+}
+
 const flattenTools = <R>(
   node: ToolNode<R>,
   path: ReadonlyArray<string> = [],
-): Array<{ path: string; tool: Tool<R> }> => [
-  ...(node.tool === undefined ? [] : [{ path: path.join("."), tool: node.tool }]),
-  ...Array.from(node.children, ([name, child]) => flattenTools(child, [...path, name])).flat(),
-]
+  namespaces: ReadonlyArray<Namespace<R>> = [],
+): Array<VisibleTool<R>> => {
+  const next = node.namespace === undefined ? namespaces : [...namespaces, node.namespace]
+  return [
+    ...(node.tool === undefined ? [] : [{ path: path.join("."), tool: node.tool, namespaces: next }]),
+    ...Array.from(node.children).flatMap(([name, child]) => flattenTools(child, [...path, name], next)),
+  ]
+}
 
-const describeTool = <R>(path: string, tool: Tool<R>): ToolDescription => ({
-  path,
-  description: tool.description,
-  signature: `${toolExpression(path)}(input: ${inputTypeScript(tool, true)}): Promise<${outputTypeScript(tool, true)}>`,
+const describeTool = <R>(visible: VisibleTool<R>): ToolDescription => ({
+  path: visible.path,
+  description: visible.tool.description,
+  signature: `${toolExpression(visible.path)}(input: ${inputTypeScript(visible.tool, true)}): Promise<${outputTypeScript(visible.tool, true)}>`,
 })
 
 // Discovery bytes are durable instructions, so order only after canonical-path collisions settle.
 const visibleTools = <R>(tools: Tools<R>) =>
-  flattenTools(toolTrie(tools))
-    .sort((left, right) => compareText(left.path, right.path))
-    .map(({ path, tool }) => ({
-      path,
-      tool,
-      description: describeTool(path, tool),
-    }))
+  flattenTools(toolTrie(tools)).sort((left, right) => compareText(left.path, right.path))
 
 export type DiscoveryPlan = {
   readonly catalog: ReadonlyArray<ToolDescription>
@@ -420,12 +429,13 @@ export const searchSignature = (() => {
   return `search(input: ${inputTypeScript(tool, true)}): ${outputTypeScript(tool, true)}`
 })()
 
-const toSearchEntry = <R>(path: string, tool: Tool<R>, description: ToolDescription): SearchEntry => ({
-  description,
+const toSearchEntry = <R>(visible: VisibleTool<R>): SearchEntry => ({
+  description: describeTool(visible),
   searchText: [
-    path,
-    tool.description,
-    ...inputProperties(tool).flatMap(({ name, description: property }) =>
+    visible.path,
+    visible.tool.description,
+    ...visible.namespaces.flatMap((namespace) => (namespace.description === undefined ? [] : [namespace.description])),
+    ...inputProperties(visible.tool).flatMap(({ name, description: property }) =>
       property === undefined ? [name] : [name, property],
     ),
   ]
@@ -433,14 +443,13 @@ const toSearchEntry = <R>(path: string, tool: Tool<R>, description: ToolDescript
     .toLowerCase(),
 })
 
-export const searchIndex = <R>(tools: Tools<R>): ReadonlyArray<SearchEntry> =>
-  visibleTools(tools).map(({ path, tool, description }) => toSearchEntry(path, tool, description))
+export const searchIndex = <R>(tools: Tools<R>): ReadonlyArray<SearchEntry> => visibleTools(tools).map(toSearchEntry)
 
 export const prepare = <R>(tools: Tools<R>): DiscoveryPlan => {
   const visible = visibleTools(tools)
   return {
-    catalog: visible.map(({ description }) => description),
-    searchIndex: visible.map(({ path, tool, description }) => toSearchEntry(path, tool, description)),
+    catalog: visible.map(describeTool),
+    searchIndex: visible.map(toSearchEntry),
   }
 }
 

packages/codemode/src/tool-schema.ts

@@ -63,8 +63,18 @@ const docTags = (schema: JsonSchema): Array<string> => {
     } catch {}
   }
   if (typeof schema.format === "string") tags.push(`@format ${schema.format}`)
+  if (schema.type === "integer") tags.push("@integer")
+  if (typeof schema.minimum === "number") tags.push(`@minimum ${schema.minimum}`)
+  if (typeof schema.maximum === "number") tags.push(`@maximum ${schema.maximum}`)
+  if (typeof schema.exclusiveMinimum === "number") tags.push(`@exclusiveMinimum ${schema.exclusiveMinimum}`)
+  if (typeof schema.exclusiveMaximum === "number") tags.push(`@exclusiveMaximum ${schema.exclusiveMaximum}`)
+  if (typeof schema.multipleOf === "number") tags.push(`@multipleOf ${schema.multipleOf}`)
+  if (typeof schema.minLength === "number") tags.push(`@minLength ${schema.minLength}`)
+  if (typeof schema.maxLength === "number") tags.push(`@maxLength ${schema.maxLength}`)
+  if (typeof schema.pattern === "string") tags.push(`@pattern ${schema.pattern}`)
   if (typeof schema.minItems === "number") tags.push(`@minItems ${schema.minItems}`)
   if (typeof schema.maxItems === "number") tags.push(`@maxItems ${schema.maxItems}`)
+  if (schema.uniqueItems === true) tags.push("@uniqueItems true")
   return tags
 }
 
@@ -127,8 +137,8 @@ const renderSchema = (
     ])
   }
   if (schema.allOf) {
-    const members = schema.allOf.map((item) => renderSchema(item, nested, depth + 1, seen))
     if (schema.allOf.some((item) => hasUnresolvedRef(item, nested.definitions))) return "unknown"
+    const members = schema.allOf.map((item) => renderSchema(item, nested, depth + 1, seen))
     return intersection([renderSchema({ ...schema, allOf: undefined }, nested, depth + 1, seen), ...members])
   }
   if (Array.isArray(schema.type)) {
@@ -180,7 +190,7 @@ export const toTypeScript = (schema: Schema.Top, decoded = false, pretty = false
 
 export const jsonSchemaToTypeScript = (schema: JsonSchema, pretty = false): string => {
   try {
-    return renderSchema(schema, { definitions: { ...(schema.definitions ?? {}), ...(schema.$defs ?? {}) }, pretty })
+    return renderSchema(schema, { definitions: {}, pretty })
   } catch {
     return "unknown"
   }

packages/codemode/src/tool.ts

@@ -1,4 +1,6 @@
 import { Effect, Schema } from "effect"
+import type { Namespace } from "./namespace.js"
+import type { Tools } from "./tools.js"
 
 /**
  * JSON Schema subset for model-visible signatures. CodeMode does not validate values against
@@ -19,8 +21,17 @@ export type JsonSchema = {
   readonly default?: unknown
   readonly format?: string
   readonly deprecated?: boolean
+  readonly minimum?: number
+  readonly maximum?: number
+  readonly exclusiveMinimum?: number
+  readonly exclusiveMaximum?: number
+  readonly multipleOf?: number
+  readonly minLength?: number
+  readonly maxLength?: number
+  readonly pattern?: string
   readonly minItems?: number
   readonly maxItems?: number
+  readonly uniqueItems?: boolean
   readonly $ref?: string
   readonly $defs?: Readonly<Record<string, JsonSchema>>
   readonly definitions?: Readonly<Record<string, JsonSchema>>
@@ -50,13 +61,8 @@ export type Options<I extends SchemaType, O extends SchemaType | undefined, R =
   readonly execute: (input: InputType<I>) => Effect.Effect<ResultType<O>, unknown, R>
 }
 
-// Object.hasOwn: an inherited _tag must not classify a namespace as a Tool.
-export const isTool = <R = never>(value: unknown): value is Tool<R> =>
-  typeof value === "object" &&
-  value !== null &&
-  "_tag" in value &&
-  Object.hasOwn(value, "_tag") &&
-  value._tag === "CodeModeTool"
+export const isTool = <R = never>(value: Tool<R> | Namespace<R> | Tools<R> | undefined): value is Tool<R> =>
+  value !== undefined && Object.hasOwn(value, "_tag") && value._tag === "CodeModeTool"
 
 /**
  * Declares one schema-described tool available to a CodeMode program through `tools.*`.

packages/codemode/src/tools.ts

@@ -1,5 +1,6 @@
+import type { Namespace } from "./namespace.js"
 import type { Tool } from "./tool.js"
 
 export type Tools<R = never> = {
-  readonly [name: string]: Tool<R> | Tools<R>
+  readonly [name: string]: Tool<R> | Namespace<R> | Tools<R>
 }

packages/codemode/test/openapi.test.ts

@@ -25,8 +25,12 @@ const happyPathSpec = async (): Promise<Document> => {
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   typeof value === "object" && value !== null && !Array.isArray(value)
 
-const toolAt = (tools: unknown, name: string) =>
-  name.split(".").reduce<unknown>((current, segment) => (isRecord(current) ? current[segment] : undefined), tools)
+const toolAt = (tools: OpenAPI.Tools, name: string) =>
+  name
+    .split(".")
+    .reduce<
+      Tool.Tool<HttpClient.HttpClient> | OpenAPI.Tools | undefined
+    >((current, segment) => (current !== undefined && !Tool.isTool(current) ? current[segment] : undefined), tools)
 
 const recordingClient = (respond: (request: HttpClientRequest.HttpClientRequest) => Response) => {
   const requests: Array<Recorded> = []
@@ -278,6 +282,30 @@ describe("OpenAPI.fromSpec", () => {
     expect(Tool.isTool(toolAt(result.tools, "group.operation.other"))).toBe(true)
   })
 
+  test("does not reserve names for unsupported operations between duplicate operation IDs", () => {
+    const operation = { operationId: "group.item", responses: { 200: { description: "Success" } } }
+    for (const unsupported of [false, true]) {
+      const result = OpenAPI.fromSpec({
+        baseUrl,
+        spec: {
+          openapi: "3.1.0",
+          paths: {
+            "/first": { get: operation },
+            ...(unsupported ? { "/unsupported": { get: { ...operation, "x-websocket": true } } } : {}),
+            "/last": { get: operation },
+          },
+        },
+      })
+
+      expect(Object.keys(result.tools)).toEqual(["group", "group_item_2"])
+      expect(toolAt(result.tools, "group.item")).toMatchObject({ _tag: "CodeModeTool", description: "GET /first" })
+      expect(toolAt(result.tools, "group_item_2")).toMatchObject({ _tag: "CodeModeTool", description: "GET /last" })
+      expect(result.skipped).toEqual(
+        unsupported ? [{ method: "GET", path: "/unsupported", reason: "WebSocket operations are not supported" }] : [],
+      )
+    }
+  })
+
   test("synthesizes flat operation IDs from methods and paths", () => {
     const response = { responses: { 200: { description: "Success" } } }
     const tools = OpenAPI.fromSpec({
@@ -315,7 +343,10 @@ describe("OpenAPI.fromSpec", () => {
               parameters: [{ name: "limit", in: "query", schema: { type: "string" } }],
               get: {
                 operationId: "test",
-                parameters: [{ name: "limit", in: "query", required: true, schema: { type: "number" } }],
+                parameters: [
+                  { name: "limit", in: "query", schema: { type: "boolean" } },
+                  { name: "limit", in: "query", required: true, schema: { type: "number" } },
+                ],
                 responses: { 200: { description: "Success" } },
               },
             },
@@ -948,7 +979,7 @@ describe("OpenAPI.fromSpec", () => {
     expect(spec.security).toStrictEqual([])
     expect(isRecord(components.securitySchemes) ? Object.keys(components.securitySchemes) : []).toStrictEqual([])
     const health = toolAt(result.tools, "v2.health.get")
-    const healthInput = isRecord(health) ? health.input : undefined
+    const healthInput = Tool.isTool(health) && isRecord(health.input) ? health.input : undefined
     expect(healthInput).toMatchObject({ type: "object", properties: {} })
     const input = isRecord(healthInput) ? healthInput : {}
     expect(Object.keys(isRecord(input.properties) ? input.properties : {})).toStrictEqual([])

packages/codemode/test/signature.test.ts

@@ -139,6 +139,81 @@ describe("pretty signature rendering", () => {
     expect(pretty).toBe(["{", "  size?: number,", "}"].join("\n"))
   })
 
+  test.each([
+    [{ type: "number", minimum: 0 }, "@minimum 0", "number"],
+    [{ type: "number", maximum: 0 }, "@maximum 0", "number"],
+    [{ type: "number", exclusiveMinimum: 0 }, "@exclusiveMinimum 0", "number"],
+    [{ type: "number", exclusiveMaximum: 0 }, "@exclusiveMaximum 0", "number"],
+    [{ type: "number", multipleOf: 0.25 }, "@multipleOf 0.25", "number"],
+    [{ type: "string", minLength: 0 }, "@minLength 0", "string"],
+    [{ type: "string", maxLength: 0 }, "@maxLength 0", "string"],
+    [{ type: "string", pattern: "^[a-z]+$" }, "@pattern ^[a-z]+$", "string"],
+    [{ type: "array", minItems: 0 }, "@minItems 0", "Array<unknown>"],
+    [{ type: "array", maxItems: 0 }, "@maxItems 0", "Array<unknown>"],
+    [{ type: "array", uniqueItems: true }, "@uniqueItems true", "Array<unknown>"],
+  ] as const)("renders constraint %j without changing the compact type", (value, tag, type) => {
+    const schema = { type: "object", properties: { value } }
+    expect(jsonSchemaToTypeScript(schema, true)).toBe(["{", `  /** ${tag} */`, `  value?: ${type},`, "}"].join("\n"))
+    expect(jsonSchemaToTypeScript(schema)).toBe(`{ value?: ${type} }`)
+  })
+
+  test("documents integer numbers without adding redundant types or requiring uniqueness when false", () => {
+    expect(
+      jsonSchemaToTypeScript(
+        {
+          type: "object",
+          properties: {
+            count: { type: "integer" },
+            amount: { type: "number" },
+            name: { type: "string" },
+            enabled: { type: "boolean" },
+            values: { type: "array", uniqueItems: false },
+            choice: { type: ["integer", "string"] },
+          },
+        },
+        true,
+      ),
+    ).toBe(
+      [
+        "{",
+        "  /** @integer */",
+        "  count?: number,",
+        "  amount?: number,",
+        "  name?: string,",
+        "  enabled?: boolean,",
+        "  values?: Array<unknown>,",
+        "  choice?: number | string,",
+        "}",
+      ].join("\n"),
+    )
+  })
+
+  test.each([false, null, ""])("preserves default %j alongside constraint tags", (value) => {
+    expect(jsonSchemaToTypeScript({ properties: { value: { default: value, minLength: 0 } } }, true)).toContain(
+      `   * @default ${JSON.stringify(value)}\n   * @minLength 0\n`,
+    )
+  })
+
+  test("escapes comment terminators in tag values", () => {
+    expect(
+      jsonSchemaToTypeScript(
+        { properties: { value: { type: "string", default: "*/", format: "*/", pattern: "^a*/b$" } } },
+        true,
+      ),
+    ).toBe(
+      [
+        "{",
+        "  /**",
+        '   * @default "* /"',
+        "   * @format * /",
+        "   * @pattern ^a* /b$",
+        "   */",
+        "  value?: string,",
+        "}",
+      ].join("\n"),
+    )
+  })
+
   test("neutralizes */ inside descriptions so nothing closes the comment early", () => {
     const pretty = jsonSchemaToTypeScript(
       { type: "object", properties: { note: { type: "string", description: "Ends */ early" } } },
@@ -216,6 +291,35 @@ describe("pretty signature rendering", () => {
   })
 })
 
+describe("JSON Schema definition scope", () => {
+  test.each(["definitions", "$defs"])("resolves root %s and lets $defs take precedence", (key) => {
+    const schema = { $ref: `#/${key}/Value`, [key]: { Value: { type: "string" } } }
+    expect(jsonSchemaToTypeScript(schema)).toBe("string")
+    expect(jsonSchemaToTypeScript(schema, true)).toBe("string")
+
+    const overridden = { ...schema, $defs: { Value: { type: "number" } } }
+    expect(jsonSchemaToTypeScript(overridden)).toBe("number")
+    expect(jsonSchemaToTypeScript(overridden, true)).toBe("number")
+  })
+
+  test.each(["definitions", "$defs"])("nested %s shadow inherited definitions without affecting siblings", (key) => {
+    const schema = {
+      type: "object",
+      definitions: { Inherited: { type: "string" } },
+      $defs: { Value: { type: "number" } },
+      properties: {
+        nested: { $ref: `#/${key}/Value`, [key]: { Value: { type: "boolean" } } },
+        inherited: { $ref: "#/definitions/Inherited" },
+        sibling: { $ref: "#/$defs/Value" },
+      },
+    }
+    expect(jsonSchemaToTypeScript(schema)).toBe("{ nested?: boolean; inherited?: string; sibling?: number }")
+    expect(jsonSchemaToTypeScript(schema, true)).toBe(
+      ["{", "  nested?: boolean,", "  inherited?: string,", "  sibling?: number,", "}"].join("\n"),
+    )
+  })
+})
+
 describe("non-identifier property names render as quoted keys", () => {
   // MCP-style schemas routinely carry property names that are not bare TS identifiers
   // (`foo-bar`, `@type`, dotted names); the rendered signature must quote them so the
@@ -315,33 +419,100 @@ describe("union schemas render every alternative", () => {
     expect(outputTypeScript(tool)).toBe("number | boolean")
   })
 
-  test("allOf renders intersections with parenthesized union members", () => {
+  test("allOf keeps siblings and parenthesized union members in order", () => {
     const schema = {
+      properties: { common: { type: "boolean" } },
       allOf: [{ type: "object", properties: { id: { type: "string" } } }, { type: ["string", "null"] }],
     } as const
-    expect(jsonSchemaToTypeScript(schema)).toBe("{ id?: string } & (string | null)")
+    expect(jsonSchemaToTypeScript(schema)).toBe("{ common?: boolean } & { id?: string } & (string | null)")
+    expect(jsonSchemaToTypeScript(schema, true)).toBe(
+      ["{", "    common?: boolean,", "  } & {", "    id?: string,", "  } & (string | null)"].join("\n"),
+    )
   })
 
-  test("allOf does not discard an unresolved constraint", () => {
-    expect(jsonSchemaToTypeScript({ allOf: [{ type: "string" }, { $ref: "https://example.com/external.json" }] })).toBe(
-      "unknown",
-    )
+  test.each([false, true])("allOf does not discard an unresolved constraint (pretty=%s)", (pretty) => {
+    for (const $ref of ["#/$defs/Missing", "#/definitions/Missing", "https://example.com/external.json"]) {
+      expect(jsonSchemaToTypeScript({ allOf: [{ type: "string" }, { $ref }] }, pretty)).toBe("unknown")
+      expect(jsonSchemaToTypeScript({ allOf: [{ type: "string" }, { allOf: [{ $ref }] }] }, pretty)).toBe("unknown")
+      expect(
+        jsonSchemaToTypeScript({ allOf: [{ properties: { nested: { $ref } } }, { type: "string" }] }, pretty),
+      ).toBe("unknown")
+    }
     expect(
-      jsonSchemaToTypeScript({
-        allOf: [{ type: "string" }, { allOf: [{ $ref: "https://example.com/external.json" }] }],
-      }),
-    ).toBe("unknown")
-    expect(
-      jsonSchemaToTypeScript({
-        type: "string",
-        allOf: [{ $ref: "#/$defs/Constraint" }],
-        $defs: { Constraint: { description: "TypeScript-neutral constraint" } },
-      }),
+      jsonSchemaToTypeScript(
+        {
+          type: "string",
+          allOf: [{ $ref: "#/$defs/Constraint" }],
+          $defs: { Constraint: { description: "TypeScript-neutral constraint" } },
+        },
+        pretty,
+      ),
     ).toBe("string")
   })
 })
 
 describe("JSDoc signatures in catalogs and search results", () => {
+  test.each([
+    {
+      source: "JSON Schema",
+      schema: {
+        type: "object",
+        properties: {
+          count: { type: "integer", minimum: 0, maximum: 10 },
+          name: { type: "string", minLength: 1, maxLength: 20, pattern: "^[a-z]+$" },
+          labels: { type: "array", items: { type: "string" }, minItems: 1, maxItems: 5 },
+        },
+        required: ["count", "name", "labels"],
+      },
+    },
+    {
+      source: "Effect",
+      schema: Schema.Struct({
+        count: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0), Schema.isLessThanOrEqualTo(10)),
+        name: Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(20), Schema.isPattern(/^[a-z]+$/)),
+        labels: Schema.Array(Schema.String).check(Schema.isMinLength(1), Schema.isMaxLength(5)),
+      }),
+    },
+  ])("$source constraints survive input/output catalog and search signatures", async ({ schema }) => {
+    const runtime = CodeMode.make({
+      tools: {
+        constrained: Tool.make({
+          description: "Constrained tool",
+          input: schema,
+          output: schema,
+          execute: () => Effect.succeed({ count: 1, name: "test", labels: ["test"] }),
+        }),
+      },
+    })
+    const type = [
+      "{",
+      "  /**",
+      "   * @integer",
+      "   * @minimum 0",
+      "   * @maximum 10",
+      "   */",
+      "  count: number,",
+      "  /**",
+      "   * @minLength 1",
+      "   * @maxLength 20",
+      "   * @pattern ^[a-z]+$",
+      "   */",
+      "  name: string,",
+      "  /**",
+      "   * @minItems 1",
+      "   * @maxItems 5",
+      "   */",
+      "  labels: Array<string>,",
+      "}",
+    ].join("\n")
+    const signature = `tools.constrained(input: ${type}): Promise<${type}>`
+    expect(runtime.catalog()[0]?.signature).toBe(signature)
+    const result = await Effect.runPromise(runtime.execute('return search({ query: "tools.constrained" })'))
+    expect(result.ok).toBe(true)
+    if (!result.ok) throw new Error("search failed")
+    expect(result.value).toMatchObject({ items: [{ signature }] })
+  })
+
   const runtime = CodeMode.make({ tools: { github: { list_issues: listIssues }, orders: { lookup: lookupOrder } } })
 
   const search = async (query: string) => {

packages/codemode/test/stdlib.test.ts

@@ -17,6 +17,8 @@
 import { describe, expect, test } from "bun:test"
 import { Effect, Schema } from "effect"
 import { CodeMode, Tool } from "../src/index.js"
+import { AsyncIteratorSymbol, IteratorSymbol } from "../src/interpreter/model.js"
+import { invokeObjectMethod } from "../src/stdlib/object.js"
 
 // Standard-library value types: Date, RegExp, Map, Set. Programs use them as ordinary JS;
 // intra-CodeMode checkpoints (Object.* helpers, spread, coercion inputs) preserve the live
@@ -824,6 +826,174 @@ describe("stdlib integration", () => {
     expect(await value(`try { Object.assign(null, { a: 1 }); return false } catch { return true }`)).toBe(true)
   })
 
+  test("Object.assign ignores non-enumerable supported symbols without reading them", () => {
+    const target = {}
+    const reads: Array<boolean> = []
+    const source = Object.defineProperty({}, IteratorSymbol, {
+      get() {
+        reads.push(true)
+        return target
+      },
+    })
+    expect(invokeObjectMethod("assign", [target, source], { type: "CallExpression" })).toBe(target)
+    expect(reads).toEqual([])
+    expect(Object.hasOwn(target, IteratorSymbol)).toBe(false)
+  })
+
+  test("Object.assign ignores nested non-enumerable supported symbols during cycle checks", () => {
+    const target = {}
+    const reads: Array<boolean> = []
+    const nested = Object.defineProperty({}, IteratorSymbol, {
+      get() {
+        reads.push(true)
+        return target
+      },
+    })
+    expect(invokeObjectMethod("assign", [target, { nested }], { type: "CallExpression" })).toBe(target)
+    expect(reads).toEqual([])
+    expect(target).toEqual({ nested })
+  })
+
+  test("Object.assign rejects cycles through supported symbols on nested arrays", () => {
+    const target = {}
+    const nested = Object.defineProperty([], IteratorSymbol, { enumerable: true, value: target })
+    expect(() => invokeObjectMethod("assign", [target, { nested }], { type: "CallExpression" })).toThrow(
+      "Object.assign result contains a circular value.",
+    )
+    expect(Object.hasOwn(target, "nested")).toBe(false)
+  })
+
+  test("Object.assign cycle checks traverse sparse keys lazily", () => {
+    const target = {}
+    const reads: Array<boolean> = []
+    const nested = Object.defineProperties([], {
+      4294967294: { enumerable: true, value: target },
+      later: {
+        enumerable: true,
+        get() {
+          reads.push(true)
+          return null
+        },
+      },
+    })
+    expect(() => invokeObjectMethod("assign", [target, { nested }], { type: "CallExpression" })).toThrow(
+      "Object.assign result contains a circular value.",
+    )
+    expect(reads).toEqual([])
+  })
+
+  test("Object.assign stops after a supported symbol write fails", () => {
+    const previous = () => ({ done: true })
+    const target = Object.defineProperty({}, IteratorSymbol, { value: previous })
+    const reads: Array<boolean> = []
+    const source = Object.defineProperties(
+      {},
+      {
+        [IteratorSymbol]: { enumerable: true, value: () => ({ done: false }) },
+        [AsyncIteratorSymbol]: {
+          enumerable: true,
+          get() {
+            reads.push(true)
+            return () => ({ done: true })
+          },
+        },
+      },
+    )
+    expect(() => invokeObjectMethod("assign", [target, source], { type: "CallExpression" })).toThrow(
+      "Object.assign could not assign property",
+    )
+    expect(Reflect.get(target, IteratorSymbol)).toBe(previous)
+    expect(reads).toEqual([])
+  })
+
+  test("Object.assign rejects direct and nested cycles", async () => {
+    expect(
+      await value(`
+        const target = { kept: true }
+        try { Object.assign(target, { self: target }) } catch { return target }
+        return null
+      `),
+    ).toEqual({ kept: true })
+    expect(
+      await value(`
+        const target = { kept: true }
+        const nested = { target }
+        try { Object.assign(target, { nested }) } catch { return target }
+        return null
+      `),
+    ).toEqual({ kept: true })
+    expect(
+      await value(`
+        const target = {}
+        const source = {}
+        source[Symbol.iterator] = target
+        try { Object.assign(target, source) } catch { return Object.hasOwn(target, Symbol.iterator) }
+        return true
+      `),
+    ).toBe(false)
+    expect(
+      await value(`
+        const target = {}
+        const nested = {}
+        nested[Symbol.iterator] = target
+        try { Object.assign(target, { nested }) } catch { return Object.hasOwn(target, "nested") }
+        return true
+      `),
+    ).toBe(false)
+  })
+
+  test("Object.assign preserves mutations before a circular field", async () => {
+    expect(
+      await value(`
+        const target = {}
+        try { Object.assign(target, { before: 1, cycle: { target }, after: 2 }) } catch { return target }
+        return null
+      `),
+    ).toEqual({ before: 1 })
+    expect(
+      await value(`
+        const target = {}
+        const marker = {}
+        const source = {}
+        source[Symbol.iterator] = marker
+        source[Symbol.asyncIterator] = target
+        try { Object.assign(target, source) } catch {
+          return [target[Symbol.iterator] === marker, Object.hasOwn(target, Symbol.asyncIterator)]
+        }
+        return null
+      `),
+    ).toEqual([true, false])
+  })
+
+  test("Object.assign preserves target identity and acyclic shared aliases", async () => {
+    expect(
+      await value(`
+        const shared = { count: 1 }
+        const target = {}
+        const result = Object.assign(target, { left: shared, right: shared })
+        result.left.count = 2
+        return [result === target, result.left === shared, result.left === result.right, shared.count]
+      `),
+    ).toEqual([true, true, true, 2])
+  })
+
+  test("Object.assign traverses shared aliases once", () => {
+    const reads: Array<boolean> = []
+    const shared = Object.defineProperty({}, "value", {
+      enumerable: true,
+      get() {
+        reads.push(true)
+        return 1
+      },
+    })
+    const target = {}
+    expect(invokeObjectMethod("assign", [target, { left: shared, right: shared }], { type: "CallExpression" })).toBe(
+      target,
+    )
+    expect(target).toEqual({ left: shared, right: shared })
+    expect(reads).toEqual([true])
+  })
+
   test("assignment resolves and reads its left side before evaluating the right side", async () => {
     expect(await value(`let x = 1; x += (x = 5); return x`)).toBe(6)
     expect(await value(`let i = 0; const values = [9]; values[i++] = i; return [values, i]`)).toEqual([[1], 1])

packages/codemode/test/tool-paths.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test"
 import { Effect, Schema } from "effect"
-import { CodeMode, Tool } from "../src/index.js"
+import { CodeMode, Namespace, Tool } from "../src/index.js"
 
 const echo = (description: string, result: string) =>
   Tool.make({
@@ -177,6 +177,48 @@ describe("blocked member names on tool paths", () => {
   })
 })
 
+describe("namespace metadata", () => {
+  const tools = {
+    api: Namespace.make({
+      description: "Manage the workspace",
+      tools: {
+        users: Namespace.make({
+          description: "Directory and account administration",
+          tools: { list: echo("List users", "users") },
+        }),
+        status: echo("Read service status", "ok"),
+      },
+    }),
+    plain: { read: echo("Read plain data", "plain") },
+  }
+  const runtime = CodeMode.make({ tools })
+
+  test("the wrapper does not add a segment to callable paths", async () => {
+    expect(runtime.catalog().map((tool) => tool.path)).toEqual(["api.status", "api.users.list", "plain.read"])
+    expect(await value(runtime, `return await tools.api.users.list({})`)).toBe("users")
+  })
+
+  test("search matches descriptions from every enclosing namespace", async () => {
+    const workspace = await value(runtime, `return search({ query: "workspace" })`)
+    expect((workspace as { items: Array<{ path: string }> }).items.map((item) => item.path)).toEqual([
+      "tools.api.status",
+      "tools.api.users.list",
+    ])
+
+    const directory = await value(runtime, `return search({ query: "account administration" })`)
+    expect((directory as { items: Array<{ path: string }> }).items.map((item) => item.path)).toEqual([
+      "tools.api.users.list",
+    ])
+  })
+
+  test("a namespace description is optional", async () => {
+    const optional = CodeMode.make({
+      tools: { api: Namespace.make({ tools: { read: echo("Read data", "read") } }) },
+    })
+    expect(await value(optional, `return await tools.api.read({})`)).toBe("read")
+  })
+})
+
 describe("empty segments", () => {
   test("tool names with empty segments are rejected at make", () => {
     for (const name of ["", "a..b", "trail.", ".lead"]) {

packages/core/src/codemode/catalog.ts

@@ -1,22 +1,29 @@
 export * as CodeModeCatalog from "./catalog.js"
 
+import type { Namespace } from "@opencode-ai/schema/tool"
 import { Schema } from "effect"
 
-export const Entry = Schema.Struct({
+export const Tool = Schema.Struct({
   path: Schema.String,
   description: Schema.String,
   signature: Schema.String,
   pinned: Schema.optionalKey(Schema.Boolean),
 })
-export type Entry = typeof Entry.Type
+export type Tool = typeof Tool.Type
+
+export type Inventory = {
+  readonly tools: ReadonlyArray<Tool>
+  readonly namespaces?: ReadonlyMap<string, Namespace>
+}
 
 const Listing = Schema.Struct({
   path: Schema.String,
   line: Schema.String,
 })
 
-const Namespace = Schema.Struct({
+const NamespaceSummary = Schema.Struct({
   name: Schema.String,
+  description: Schema.optionalKey(Schema.String),
   count: Schema.Number,
   entries: Schema.Array(Listing),
 })
@@ -24,24 +31,30 @@ const Namespace = Schema.Struct({
 export const Summary = Schema.Struct({
   total: Schema.Number,
   shown: Schema.Number,
-  namespaces: Schema.Array(Namespace),
+  namespaces: Schema.Array(NamespaceSummary),
 })
 export type Summary = typeof Summary.Type
 
+export type Options = {
+  readonly budget?: number
+}
+
 const DESCRIPTION_LIMIT = 120
 const CHARACTERS_PER_TOKEN = 4
 const INLINE_BUDGET = 2_000
 
-// Keep every namespace searchable, then select full listings one per namespace per round,
+// Keep every namespace visible, then select full listings one per namespace per round,
 // considering shorter listings first until the inline budget is exhausted.
-export function summarize(entries: ReadonlyArray<Entry>, budget = INLINE_BUDGET): Summary {
-  const namespaces = [...Map.groupBy(entries, (entry) => entry.path.split(".", 1)[0] ?? entry.path)]
+export function summarize(inventory: Inventory, options: Options = {}): Summary {
+  const budget = options.budget ?? INLINE_BUDGET
+  const namespaces = [...Map.groupBy(inventory.tools, (tool) => tool.path.split(".", 1)[0] ?? tool.path)]
     .sort(([left], [right]) => {
       if (left < right) return -1
       if (left > right) return 1
       return 0
     })
     .map(([name, namespaceEntries]) => {
+      const description = inventory.namespaces?.get(name)?.description
       const listings = namespaceEntries
         .map((entry) => {
           const firstLine = entry.description.split("\n", 1)[0]?.trim() ?? ""
@@ -64,6 +77,7 @@ export function summarize(entries: ReadonlyArray<Entry>, budget = INLINE_BUDGET)
       )
       return {
         name,
+        ...(description === undefined ? {} : { description }),
         listings,
         selectionOrder: ranked.filter((candidate) => !pinned.has(candidate.listing)),
         selectedListings: pinned,
@@ -72,11 +86,25 @@ export function summarize(entries: ReadonlyArray<Entry>, budget = INLINE_BUDGET)
     })
 
   const active = new Set(namespaces)
+  // TODO: Bound namespace discovery once large namespace inventories and descriptions can no longer stay inline.
   let remaining =
     budget -
+    namespaces.reduce(
+      (total, namespace) =>
+        total +
+        cost(
+          namespaceLine({
+            name: namespace.name,
+            ...(namespace.description === undefined ? {} : { description: namespace.description }),
+            count: namespace.listings.length,
+            entries: [],
+          }),
+        ),
+      0,
+    ) -
     namespaces
       .flatMap((namespace) => namespace.listings.filter((listing) => namespace.selectedListings.has(listing)))
-      .reduce((total, listing) => total + Math.round(listing.line.length / CHARACTERS_PER_TOKEN), 0)
+      .reduce((total, listing) => total + cost(listing.line), 0)
   while (active.size > 0) {
     for (const namespace of active) {
       const candidate = namespace.selectionOrder[namespace.selectionIndex]
@@ -93,19 +121,31 @@ export function summarize(entries: ReadonlyArray<Entry>, budget = INLINE_BUDGET)
 
   const namespaceSummaries = namespaces.map((namespace) => ({
     name: namespace.name,
+    ...(namespace.description === undefined ? {} : { description: namespace.description }),
     count: namespace.listings.length,
     entries: namespace.listings.filter((listing) => namespace.selectedListings.has(listing)),
   }))
   return {
-    total: entries.length,
+    total: inventory.tools.length,
     shown: namespaceSummaries.reduce((total, namespace) => total + namespace.entries.length, 0),
     namespaces: namespaceSummaries,
   }
 }
 
+export function namespaceLine(namespace: typeof NamespaceSummary.Type) {
+  const count = namespace.count === 1 ? "1 tool" : `${namespace.count} tools`
+  const label =
+    namespace.entries.length === namespace.count
+      ? count
+      : namespace.entries.length === 0
+        ? `${count}, none shown`
+        : `${count}, ${namespace.entries.length} shown`
+  return `- ${namespace.name} (${label})${namespace.description === undefined ? "" : ` // ${namespace.description}`}`
+}
+
 function rankListings(listings: ReadonlyArray<typeof Listing.Type>) {
   return listings
-    .map((listing) => ({ listing, cost: Math.round(listing.line.length / CHARACTERS_PER_TOKEN) }))
+    .map((listing) => ({ listing, cost: cost(listing.line) }))
     .toSorted((left, right) => {
       if (left.cost !== right.cost) return left.cost - right.cost
       if (left.listing.path < right.listing.path) return -1
@@ -113,3 +153,7 @@ function rankListings(listings: ReadonlyArray<typeof Listing.Type>) {
       return 0
     })
 }
+
+function cost(text: string) {
+  return Math.round(text.length / CHARACTERS_PER_TOKEN)
+}

packages/core/src/codemode/instructions.ts

@@ -23,14 +23,7 @@ export function render(catalog: CodeModeCatalog.Summary) {
     return "No Code Mode tools are currently available. Later Code Mode catalog updates may add or remove tools. Do not call `execute` unless there is at least one available Code Mode tool."
 
   const tools = catalog.namespaces.flatMap((namespace) => {
-    const count = namespace.count === 1 ? "1 tool" : `${namespace.count} tools`
-    const label =
-      namespace.entries.length === namespace.count
-        ? count
-        : namespace.entries.length === 0
-          ? `${count}, none shown`
-          : `${count}, ${namespace.entries.length} shown`
-    return [`- ${namespace.name} (${label})`, ...namespace.entries.map((entry) => entry.line)]
+    return [CodeModeCatalog.namespaceLine(namespace), ...namespace.entries.map((entry) => entry.line)]
   })
 
   return `${prompt(catalog.shown < catalog.total)}
@@ -47,6 +40,15 @@ ${render(current)}`
   const currentComplete = current.shown === current.total
   if (previousComplete !== currentComplete) return replacement
 
+  const descriptions = Instructions.diffByKey(
+    previous.namespaces.filter((namespace) => namespace.description !== undefined),
+    current.namespaces.filter((namespace) => namespace.description !== undefined),
+    (namespace) => namespace.name,
+    (before, after) => before.description !== after.description,
+  )
+  if (descriptions.added.length > 0 || descriptions.removed.length > 0 || descriptions.changed.length > 0)
+    return replacement
+
   const diff = Instructions.diffByKey(
     previous.namespaces.flatMap((namespace) => namespace.entries),
     current.namespaces.flatMap((namespace) => namespace.entries),
@@ -126,8 +128,8 @@ ${render(current)}`
 const key = Instructions.Key.make("core/codemode")
 const codec = Schema.toCodecJson(CodeModeCatalog.Summary)
 
-export const make = (entries?: ReadonlyArray<CodeModeCatalog.Entry>): Instructions.List => {
-  const catalog = entries === undefined ? Instructions.removed : CodeModeCatalog.summarize(entries)
+export const make = (inventory?: CodeModeCatalog.Inventory): Instructions.List => {
+  const catalog = inventory === undefined ? Instructions.removed : CodeModeCatalog.summarize(inventory)
   return Instructions.make({
     key,
     codec,

packages/core/src/codemode/tool.ts

@@ -1,9 +1,18 @@
 export * as CodeModeTool from "./tool.js"
 
-import { CodeMode, Tool, toolError } from "@opencode-ai/codemode"
-import type { Content, Context, Error, Info, Metadata, Result } from "@opencode-ai/schema/tool"
+import { CodeMode, Namespace, Tool, toolError } from "@opencode-ai/codemode"
+import type {
+  Content,
+  Context,
+  Error,
+  Info,
+  Metadata,
+  Namespace as ToolNamespace,
+  Result,
+} from "@opencode-ai/schema/tool"
 import { Effect, Ref, Schema, Semaphore } from "effect"
 import { definition, normalizedName } from "../tool/runtime.js"
+import { CodeModeCatalog } from "./catalog.js"
 
 const ExecuteFile = Schema.Struct({
   data: Schema.String,
@@ -31,6 +40,21 @@ type CollectedFiles = {
   readonly files: Array<typeof ExecuteFile.Type>
 }
 
+type ToolNode = {
+  tool?: Tool.Tool<never>
+  namespace?: ToolNamespace
+  readonly children: Map<string, ToolNode>
+}
+
+type Tools = {
+  [name: string]: Tool.Tool<never> | Namespace.Namespace<never> | Tools
+}
+
+export type Inventory = {
+  readonly tools: ReadonlyMap<string, Info>
+  readonly namespaces?: ReadonlyMap<string, ToolNamespace>
+}
+
 // Invariant model-facing guidance; the changing tool catalog is delivered through Instructions.
 const description = [
   "Run JavaScript in a confined Code Mode runtime to orchestrate tool calls and compose their results.",
@@ -42,7 +66,7 @@ const description = [
 ].join("\n")
 
 export const create = (
-  registrations: ReadonlyMap<string, Info>,
+  inventory: Inventory,
   executeTool: (name: string, tool: Info, input: unknown, context: Context) => Effect.Effect<Result, Error>,
 ) => {
   return {
@@ -61,7 +85,7 @@ export const create = (
             Ref.updateAndGet(calls, update).pipe(Effect.flatMap((toolCalls) => context.progress({ toolCalls }))),
           )
         const result = yield* runtime(
-          registrations,
+          inventory,
           (name, tool, input) =>
             Effect.gen(function* () {
               const index = yield* Ref.getAndUpdate(callIndex, (index) => index + 1)
@@ -132,36 +156,95 @@ export const create = (
   } satisfies Info
 }
 
-export const catalog = (registrations: ReadonlyMap<string, Info>) => {
+export const catalog = (inventory: Inventory) => {
   const pinned = new Set(
-    Array.from(registrations.values())
+    Array.from(inventory.tools.values())
       .filter((registration) => registration.options?.pinned === true)
       .map(qualifiedName),
   )
-  return runtime(registrations, () => Effect.fail(toolError("Execute context is unavailable")))
-    .catalog()
-    .map((entry) => ({ ...entry, pinned: pinned.has(entry.path) }))
+  return {
+    tools: runtime(inventory, () => Effect.fail(toolError("Execute context is unavailable")))
+      .catalog()
+      .map((tool) => ({ ...tool, pinned: pinned.has(tool.path) })),
+    ...(inventory.namespaces === undefined ? {} : { namespaces: inventory.namespaces }),
+  } satisfies CodeModeCatalog.Inventory
 }
 
 function runtime(
-  registrations: ReadonlyMap<string, Info>,
+  inventory: Inventory,
   executeTool: (name: string, tool: Info, input: unknown) => Effect.Effect<unknown, unknown>,
   hooks?: CodeMode.ToolCallHooks,
 ) {
-  const tools: Record<string, Tool.Tool<never>> = {}
-  for (const [name, registration] of registrations) {
+  // A path may carry namespace metadata, a callable tool, child tools, or all three.
+  const root: ToolNode = { children: new Map() }
+  for (const namespace of inventory.namespaces?.values() ?? []) getNode(root, namespace.name).namespace = namespace
+  for (const [name, registration] of inventory.tools) {
     const child = definition(registration)
-    const path = qualifiedName(registration)
-    tools[path] = Tool.make({
+    getNode(root, qualifiedName(registration)).tool = Tool.make({
       description: child.description,
       input: child.inputSchema,
       output: child.outputSchema ?? Schema.NullOr(Schema.String),
       execute: (input) => executeTool(name, registration, input),
     })
   }
+  const tools = renderTools(root)
   return CodeMode.make<typeof tools>({ tools, ...hooks })
 }
 
+function getNode(root: ToolNode, path: string) {
+  return path.split(".").reduce((parent, name) => {
+    const child: ToolNode = parent.children.get(name) ?? { children: new Map() }
+    parent.children.set(name, child)
+    return child
+  }, root)
+}
+
+function renderTools(root: ToolNode) {
+  const callables = new Map<string, Tool.Tool<never>>()
+  const tools = renderChildren(root, [], callables)
+  for (const [path, tool] of callables) tools[path] = tool
+  return tools
+}
+
+function renderChildren(node: ToolNode, path: ReadonlyArray<string>, callables: Map<string, Tool.Tool<never>>): Tools {
+  return Object.fromEntries(
+    Array.from(node.children).flatMap(([name, child]) => {
+      const next = [...path, name]
+      // A record cannot hold both a top-level tool and namespace under the same key.
+      if (path.length === 0 && child.tool !== undefined && (child.namespace !== undefined || child.children.size > 0)) {
+        const tools: Tools = {}
+        flattenTools(child, next, tools)
+        return Object.entries(tools)
+      }
+      return [[name, renderEntry(child, next, callables)]]
+    }),
+  )
+}
+
+function renderEntry(
+  node: ToolNode,
+  path: ReadonlyArray<string>,
+  callables: Map<string, Tool.Tool<never>>,
+): Tools[string] {
+  const tools = renderChildren(node, path, callables)
+  // CodeMode merges this dotted tool path with the nested namespace entry.
+  if (node.tool !== undefined && (node.namespace !== undefined || node.children.size > 0))
+    callables.set(path.join("."), node.tool)
+  if (node.namespace !== undefined)
+    return Namespace.make({
+      description: node.namespace.description,
+      tools,
+    })
+  if (node.tool === undefined) return tools
+  if (node.children.size === 0) return node.tool
+  return tools
+}
+
+function flattenTools(node: ToolNode, path: ReadonlyArray<string>, tools: Tools) {
+  if (node.tool !== undefined) tools[path.join(".")] = node.tool
+  for (const [name, child] of node.children) flattenTools(child, [...path, name], tools)
+}
+
 function qualifiedName(registration: Info) {
   const normalized = normalizedName(registration)
   if (registration.options?.namespace === undefined) return normalized

packages/core/src/effect/app-node-builder.ts

@@ -1,20 +1,11 @@
 import { buildLocationServiceMap } from "../location-services.js"
 import { LocationServiceMap } from "../location-service-map.js"
 import { LayerNode } from "@opencode-ai/util/effect/layer-node"
-import { makeGlobalNode } from "@opencode-ai/util/effect/app-node"
 
-export function build<A, E>(root: LayerNode.Node<A, E, any>, replacements: LayerNode.Replacements = []) {
-  // Only build the location service map if it's actually needed
-  if (!LayerNode.hasUnbound(root, LocationServiceMap.node) || hasReplacement(replacements, LocationServiceMap.node))
-    return LayerNode.compile(root, replacements)
-
-  const locationMap = buildLocationServiceMap(replacements)
-  const locationMapNode = makeGlobalNode({ service: LocationServiceMap.Service, layer: locationMap, deps: [] })
-  return LayerNode.compile(root, replacements.concat([[LocationServiceMap.node, locationMapNode]]))
-}
-
-function hasReplacement(replacements: LayerNode.Replacements, node: LayerNode.Node<unknown, unknown, any>) {
-  return replacements.some(([source]) => source.name === node.name)
+export function build<A, E>(root: LayerNode.Graph<A, E>, replacements: LayerNode.Replacements = []) {
+  return LayerNode.compile(root, {
+    replacements: [LocationServiceMap.node.replace(buildLocationServiceMap(replacements)), ...replacements],
+  })
 }
 
 export * as AppNodeBuilder from "./app-node-builder.js"

packages/core/src/instance.ts

@@ -55,6 +55,7 @@ import { ToolOutput } from "./tool-output.js"
 import { Vcs } from "./vcs.js"
 
 export * as Instance from "./instance.js"
+export { Service, byLocationNode, type Interface } from "./instance/service.js"
 
 const nodes = [
   Location.node,
@@ -110,9 +111,9 @@ const nodes = [
   Vcs.node,
   // Start repository watches only after boot-critical filesystem and Git work.
   LocationWatcher.node,
-] as const satisfies readonly Node.LocationNode<unknown, unknown>[]
+] as const satisfies readonly Node.LocationGraph<never, unknown>[]
 
-export const graph = LayerNode.group<typeof nodes>(nodes)
+export const graph = LayerNode.group(nodes)
 
 export type Services = LayerNode.Output<typeof graph>
 export type Error = LayerNode.Error<typeof graph>
@@ -141,29 +142,23 @@ export interface Options {
 // source still honors explicit plugin operations from wellknown and
 // host-injected config.
 const vanillaReplacements: LayerNode.Replacements = [
-  [Config.node, Config.configured({ project: false, global: false })],
-  [InstructionDiscovery.node, InstructionDiscovery.configured({ project: false, global: false })],
+  Config.node.replace(Config.configured({ project: false, global: false })),
+  InstructionDiscovery.node.replace(InstructionDiscovery.configured({ project: false, global: false })),
 ]
 
 // One instance is one compiled, fresh copy of the graph standing on a directory.
 export function layer(ref: Location.Ref, options: Options = {}) {
   const startedAt = performance.now()
   // Ordered: vanilla defaults, then caller replacements (which win over the
-  // defaults), then bound pairs (which win over everything).
-  const allReplacements: LayerNode.Replacements = [
+  // defaults), then instance bindings (which win over everything).
+  const replacements: LayerNode.Replacements = [
     ...(options.discovery === false ? vanillaReplacements : []),
     ...(options.replacements ?? []),
-    [Location.node, Location.boundNode(ref, { discovery: options.discovery })],
-    [InstancePlugins.node, InstancePlugins.bound(options.plugins ?? [])],
+    Location.node.replace(Location.boundNode(ref, { discovery: options.discovery })),
+    InstancePlugins.node.replace(InstancePlugins.bound(options.plugins ?? [])),
   ]
-  // Apply replacements during hoist, not afterward: replacements can
-  // introduce new tagged dependencies (Location.boundNode depends on
-  // Project), and the hoist walk is the only pass that can still slice
-  // those back out.
-  const location = LayerNode.hoist(graph, Node.tags.values.global, allReplacements)
 
-  return LayerNode.compile(location.node).pipe(
-    Layer.fresh,
+  return LayerNode.compile(graph, { replacements, shared: Node.tags.values.global }).pipe(
     Layer.tap(() =>
       Effect.logInfo("location services booted", {
         directory: ref.directory,
@@ -171,6 +166,5 @@ export function layer(ref: Location.Ref, options: Options = {}) {
         durationMs: Math.round(performance.now() - startedAt),
       }),
     ),
-    Layer.provide(LayerNode.compile(location.hoisted)),
   )
 }

packages/core/src/instance/service.ts

@@ -0,0 +1,42 @@
+export * as Instance from "./service.js"
+export type { Services } from "../instance.js"
+
+import { Context, Effect, Layer, Option, Scope } from "effect"
+import type { Session } from "@opencode-ai/schema/session"
+import { makeGlobalNode } from "@opencode-ai/util/effect/app-node"
+import type { Services } from "../instance.js"
+import { LocationServiceMap } from "../location-service-map.js"
+
+/** Selects Session capabilities; implementations own caching and lifetime. */
+export interface Interface {
+  readonly provide: (
+    session: Session.Info,
+  ) => <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, Services>>
+  /** Borrow a cached instance without initializing one when it is absent. */
+  readonly provideIfLoaded: (
+    session: Session.Info,
+  ) => <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<Option.Option<A>, E, Exclude<R, Services>>
+}
+
+export class Service extends Context.Service<Service, Interface>()("@opencode/Instance") {}
+
+const layer = Layer.effect(
+  Service,
+  Effect.gen(function* () {
+    const locations = yield* LocationServiceMap.Service
+    return Service.of({
+      provide: (session) => Effect.provide(locations.get(session.location)),
+      provideIfLoaded: (session) => (effect) =>
+        // Scope the borrowed reference without replacing the caller's Scope.
+        Effect.scopedWith((scope) =>
+          Effect.gen(function* () {
+            const context = yield* locations.contextEffectOption(session.location).pipe(Scope.provide(scope))
+            if (Option.isNone(context)) return Option.none()
+            return Option.some(yield* effect.pipe(Effect.provide(context.value)))
+          }),
+        ),
+    })
+  }),
+)
+
+export const byLocationNode = makeGlobalNode({ service: Service, layer, deps: [LocationServiceMap.node] })

packages/core/src/location-mutation.ts

@@ -7,7 +7,6 @@ import { FSUtil } from "@opencode-ai/util/fs-util"
 import { Global } from "@opencode-ai/util/global"
 import { Location } from "./location.js"
 import { Project } from "./project.js"
-import { ProjectMarkers } from "./project/markers.js"
 import { AbsolutePath } from "./schema.js"
 
 export const Kind = Schema.Literals(["file", "directory"])
@@ -81,7 +80,6 @@ const layer = Layer.effect(
   Effect.gen(function* () {
     const fs = yield* FSUtil.Service
     const location = yield* Location.Service
-    const markers = yield* ProjectMarkers.Service
 
     const resolve = Effect.fnUntraced(function* (input: ResolveInput) {
       const absolute = resolvePath(location.directory, input.path)
@@ -113,7 +111,7 @@ const layer = Layer.effect(
           resource: externalResource,
           save: slash(
             path.join(
-              (yield* Project.root(fs, AbsolutePath.make(externalDirectory), markers.targets())) ?? externalDirectory,
+              (yield* Project.root(fs, AbsolutePath.make(externalDirectory))) ?? externalDirectory,
               "*",
             ),
           ),
@@ -128,5 +126,5 @@ const layer = Layer.effect(
 export const node = makeLocationNode({
   service: Service,
   layer,
-  deps: [FSUtil.node, Location.node, ProjectMarkers.node],
+  deps: [FSUtil.node, Location.node],
 })

packages/core/src/location.ts

@@ -10,7 +10,6 @@ export { Info, Ref, response }
 
 export interface Interface extends Info {
   readonly vcs?: Project.Vcs
-  readonly vcsBackend?: string
 }
 
 export class Service extends Context.Service<Service, Interface>()("@opencode/Location") {}
@@ -28,7 +27,6 @@ const layer = (ref: Ref, options?: { readonly discovery?: boolean }) =>
         workspaceID: ref.workspaceID,
         project: { id: resolved.id, directory: resolved.directory, canonical: resolved.canonical },
         vcs: resolved.vcs,
-        vcsBackend: resolved.vcsBackend,
       })
     }),
   )

packages/core/src/model.ts

@@ -38,10 +38,10 @@ export function compatibility(input: unknown): Compatibility | undefined {
 }
 
 export function parse(input: string): { providerID: Provider.ID; modelID: ID } {
-  const [providerID, ...modelID] = input.split("/")
+  const index = input.indexOf("/")
   return {
-    providerID: Provider.ID.make(providerID),
-    modelID: ID.make(modelID.join("/")),
+    providerID: Provider.ID.make(index === -1 ? input : input.slice(0, index)),
+    modelID: ID.make(index === -1 ? "" : input.slice(index + 1)),
   }
 }
 

packages/core/src/persistent-pty/index.ts

@@ -112,7 +112,7 @@ export interface Interface {
 
 export class Service extends Context.Service<Service, Interface>()("@opencode/PersistentPty") {}
 
-export const configured = (options: Options = {}) =>
+const makeLayer = (options: Options = {}) =>
   Layer.effect(
     Service,
     Effect.gen(function* () {
@@ -361,8 +361,14 @@ export const configured = (options: Options = {}) =>
     }),
   )
 
-export const layer = configured()
-export const node = makeGlobalNode({ service: Service, layer, deps: [Bus.node, Global.node] })
+export const layer = makeLayer()
+export const configured = (options?: Options) =>
+  makeGlobalNode({
+    service: Service,
+    layer: options === undefined ? layer : makeLayer(options),
+    deps: [Bus.node, Global.node],
+  })
+export const node = configured()
 
 const request = (daemon: DaemonTransport, value: object, start = false) =>
   daemon.request(value, start).pipe(Effect.mapError(unavailable))

packages/core/src/plugin.ts

@@ -30,7 +30,7 @@ import { Permission } from "./permission.js"
 
 export interface Interface {
   readonly activate: (
-    plugins: readonly Versioned[],
+    plugins: readonly Generation[],
     failures?: readonly Failure[],
   ) => Effect.Effect<void>
   readonly list: () => Effect.Effect<Plugin.Info[]>
@@ -38,8 +38,8 @@ export interface Interface {
 
 type Failure = Plugin.Info & { readonly state: Extract<Plugin.State, { readonly status: "failed" }> }
 
-export type Versioned = PluginDefinition & {
-  readonly version: string
+export type Generation = PluginDefinition & {
+  readonly revision: string
   readonly source?: Plugin.Source
   readonly features?: Plugin.Features
 }
@@ -52,11 +52,11 @@ const layer = Layer.effect(
     const bus = yield* Bus.Service
     const kv = yield* KV.Service
     const scope = yield* Scope.make()
-    const active = new Map<Plugin.ID, { readonly plugin: Versioned; readonly scope: Scope.Closeable }>()
+    const active = new Map<Plugin.ID, { readonly plugin: Generation; readonly scope: Scope.Closeable }>()
     const lock = Semaphore.makeUnsafe(1)
     let inventory: Plugin.Info[] = []
     let host: Parameters<PluginDefinition["effect"]>[0]
-    const load = Effect.fnUntraced(function* (plugin: Versioned) {
+    const load = Effect.fnUntraced(function* (plugin: Generation) {
       const child = yield* Scope.fork(scope)
       const inherit = yield* State.inherit()
       const loaded = yield* Effect.suspend(() =>
@@ -83,7 +83,7 @@ const layer = Layer.effect(
     })
 
     const activate = Effect.fn("Plugin.activate")(function* (
-      plugins: readonly Versioned[],
+      plugins: readonly Generation[],
       failures: readonly Failure[] = [],
     ) {
       const definitions = plugins.map((plugin) => ({ ...plugin, id: Plugin.ID.make(plugin.id) }))
@@ -99,10 +99,14 @@ const layer = Layer.effect(
             active.size === definitions.length &&
             Array.from(active.values()).every((entry, index) => {
               const definition = definitions[index]
-              return entry.plugin.id === definition?.id && entry.plugin.version === definition.version
+              return entry.plugin.id === definition?.id && entry.plugin.revision === definition.revision
             })
           ) {
-            const nextInventory = [...Array.from(active.values(), (entry) => activeInfo(entry.plugin)), ...failures]
+            for (const definition of definitions) {
+              const entry = active.get(definition.id)
+              if (entry) active.set(definition.id, { ...entry, plugin: definition })
+            }
+            const nextInventory = [...definitions.map(activeInfo), ...failures]
             if (JSON.stringify(inventory) === JSON.stringify(nextInventory)) return
             inventory = nextInventory
             yield* bus.publish(Plugin.Event.Updated, {})
@@ -174,7 +178,7 @@ const layer = Layer.effect(
   }),
 )
 
-function activeInfo(plugin: Versioned): Plugin.Info {
+function activeInfo(plugin: Generation): Plugin.Info {
   return {
     id: Plugin.ID.make(plugin.id),
     source: plugin.source ?? { type: "builtin" },

packages/core/src/plugin/host.ts

@@ -80,7 +80,8 @@ export const make = Effect.fn("PluginHost.make")(function* (plugin: Interface, p
   const response = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
     effect.pipe(Effect.map((data) => ({ location: locationInfo(), data })))
 
-  return {
+  // Keep the instance graph's inferred types independent of Session handles.
+  const context: Plugin.Context = {
     app,
     location: locationInfo(),
     options: {},
@@ -206,7 +207,8 @@ export const make = Effect.fn("PluginHost.make")(function* (plugin: Interface, p
           .subscribe()
           .pipe(
             Stream.filter(
-              (event): event is EventManifest.ServerEvent | RpcEvent => EventManifest.isServer(event) || isRpcEvent(event),
+              (event): event is EventManifest.ServerEvent | RpcEvent =>
+                EventManifest.isServer(event) || isRpcEvent(event),
             ),
           ),
     },
@@ -449,7 +451,8 @@ export const make = Effect.fn("PluginHost.make")(function* (plugin: Interface, p
       wait: (input) => runtime.session.wait(input.sessionID),
       context: (input) => runtime.session.context(input.sessionID),
     },
-  } satisfies Plugin.Context
+  }
+  return context
 })
 
 export function storage(kv: KV.Interface, pluginID: string): Plugin.Context["storage"] {

packages/core/src/plugin/instance.ts

@@ -3,7 +3,7 @@ export * as InstancePlugins from "./instance.js"
 import type { Plugin } from "@opencode-ai/plugin/effect/plugin"
 import { Context, Layer } from "effect"
 import { makeLocationNode } from "@opencode-ai/util/effect/app-node"
-import type { Versioned } from "../plugin.js"
+import type { Generation } from "../plugin.js"
 
 /**
  * Holds the plugins one instance is born with. Unlike the host-global
@@ -13,16 +13,13 @@ import type { Versioned } from "../plugin.js"
  * for the instance's lifetime; runtime dynamism lives inside plugins through
  * the container transform/reload APIs.
  *
- * Limitations: `vcs` marker declarations in an instance list are not seen by
- * `ProjectMarkers` (it is global and runs during project resolution, before
- * the instance exists — unlike `SdkPlugins`, whose declarations it consumes
- * directly), and config plugin operations may disable instance plugins by id,
- * matching `SdkPlugins` behavior.
+ * Config plugin operations may disable instance plugins by id, matching
+ * `SdkPlugins` behavior.
  */
 export type List = readonly Plugin[]
 
 export interface Interface {
-  readonly all: () => readonly Versioned[]
+  readonly all: () => readonly Generation[]
 }
 
 export class Service extends Context.Service<Service, Interface>()("@opencode/InstancePlugins") {}
@@ -33,8 +30,8 @@ export const node = makeLocationNode({
   deps: [],
 })
 
-// The constant version is load-bearing: the plugin registry treats an
-// unchanged (id, version) pair as the same plugin across activations, which
+// The constant revision is load-bearing: the plugin registry treats an
+// unchanged (id, revision) pair as the same plugin across activations, which
 // is only correct because a bound list never changes after creation.
 // `source: "sdk"` means host-contributed; an instance list is the
 // per-instance form of the same channel.
@@ -44,7 +41,7 @@ export function bound(plugins: List) {
     throw new Error(`duplicate instance plugin ids: ${duplicates.map((plugin) => plugin.id).join(", ")}`)
   }
   const stamped = plugins.map(
-    (plugin): Versioned => ({ ...plugin, version: "instance", source: { type: "sdk" } }),
+    (plugin): Generation => ({ ...plugin, revision: "instance", source: { type: "sdk" } }),
   )
   return Layer.succeed(Service, Service.of({ all: () => stamped }))
 }

packages/core/src/plugin/internal.ts

@@ -26,7 +26,6 @@ import { ConfigShellPlugin } from "../config/plugin/shell.js"
 import { ConfigSnapshotPlugin } from "../config/plugin/snapshot.js"
 import { ConfigSkillPlugin } from "../config/plugin/skill.js"
 import { ConfigToolOutputPlugin } from "../config/plugin/tool-output.js"
-import { ConfigPluginSource } from "../config/plugin/source.js"
 import { ConfigWebSearchPlugin } from "../config/plugin/websearch.js"
 import { Bus } from "../bus.js"
 import { Environment } from "../environment/index.js"
@@ -97,7 +96,6 @@ const services = Effect.fn("PluginInternal.services")(function* () {
   const command = yield* Command.Service
   const config = yield* Config.Service
   const credential = yield* Credential.Service
-  const pluginSources = yield* ConfigPluginSource.Service
   const bus = yield* Bus.Service
   const environment = yield* Environment.Service
   const mutation = yield* FileMutation.Service
@@ -141,7 +139,6 @@ const services = Effect.fn("PluginInternal.services")(function* () {
     Context.make(Command.Service, command),
     Context.make(Config.Service, config),
     Context.make(Credential.Service, credential),
-    Context.make(ConfigPluginSource.Service, pluginSources),
     Context.make(Bus.Service, bus),
     Context.make(Environment.Service, environment),
     Context.make(FileMutation.Service, mutation),
@@ -192,7 +189,6 @@ export const requirements = LayerNode.group([
   Command.node,
   Config.node,
   Credential.node,
-  ConfigPluginSource.node,
   Bus.node,
   Environment.node,
   FileMutation.node,
@@ -287,7 +283,6 @@ export const list = Effect.fn("PluginInternal.list")(function* () {
     plugins.map(
       (plugin): Plugin => ({
         id: plugin.id,
-        vcs: plugin.vcs,
         effect: (host) => plugin.effect(host).pipe(Effect.provide(context)),
       }),
     )

packages/core/src/plugin/module.ts

@@ -8,23 +8,17 @@ import { readdir } from "node:fs/promises"
 import path from "path"
 import { pathToFileURL } from "url"
 import type { ConfigPluginSource } from "../config/plugin/source.js"
-import type { Versioned } from "../plugin.js"
+import type { Generation } from "../plugin.js"
 import { PluginPromise } from "./promise.js"
 
-const Discovery = Schema.Struct({
-  id: Schema.optional(Schema.String),
-  markers: Schema.Array(Schema.String),
-})
 const Definition = Schema.Struct({
   default: Schema.Union([
     Schema.Struct({
       id: Schema.String,
-      vcs: Schema.optional(Discovery),
       effect: Schema.declare<Plugin["effect"]>((input): input is Plugin["effect"] => typeof input === "function"),
     }),
     Schema.Struct({
       id: Schema.String,
-      vcs: Schema.optional(Discovery),
       setup: Schema.declare<Parameters<typeof PluginPromise.fromPromise>[0]["setup"]>(
         (input): input is Parameters<typeof PluginPromise.fromPromise>[0]["setup"] => typeof input === "function",
       ),
@@ -34,13 +28,17 @@ const Definition = Schema.Struct({
 
 export const load = Effect.fn("PluginModule.load")(function* (
   operation: Extract<ConfigPluginSource.Operation, { type: "add" }>,
+  options?: { readonly install?: boolean },
 ) {
   const npm = yield* Npm.Service
   const local = path.isAbsolute(operation.target)
-  const installed = local
-    ? { entrypoint: pathToFileURL(operation.target).href }
-    : yield* npm.add(operation.target, { subpaths: ["server", ""] })
+  const installed: Npm.EntryPoint = local
+    ? { directory: path.dirname(operation.target), entrypoint: pathToFileURL(operation.target).href }
+    : options?.install === false
+      ? yield* npm.resolve(operation.target, { subpaths: ["server", ""] })
+      : yield* npm.add(operation.target, { subpaths: ["server", ""] })
   const entrypoint = installed.entrypoint
+  if (!local && options?.install === false && !entrypoint) return { pending: true as const }
   if (!entrypoint) return yield* Effect.fail(new Error(`Plugin entrypoint not found: ${operation.target}`))
   // Bun currently ignores query parameters when caching file:// imports.
   const target = typeof Bun !== "undefined" ? operation.target.replaceAll("\\", "/") : entrypoint
@@ -63,13 +61,16 @@ export const load = Effect.fn("PluginModule.load")(function* (
   return {
     id: plugin.id,
     features,
-    vcs: plugin.vcs,
-    version: JSON.stringify(operation),
+    revision: JSON.stringify([operation, installed.revision]),
     source: path.isAbsolute(operation.target)
       ? { type: "local" as const, path: operation.target }
-      : { type: "package" as const, package: operation.target },
+      : {
+          type: "package" as const,
+          target: operation.target,
+          ...(installed.version ? { version: installed.version } : {}),
+        },
     effect: (host) => plugin.effect({ ...host, options: operation.options }),
-  } satisfies Versioned
+  } satisfies Generation
 })
 
 function localFeatures(entrypoint: string) {

packages/core/src/plugin/runtime.ts

@@ -62,7 +62,7 @@ const require = <A, E, R>(cell: Cell, f: (runtime: Interface) => Effect.Effect<A
 
 const defaultCell = makeCell()
 
-export const layerWithCell = (cell: Cell) =>
+export const layerWithCell = (cell: Cell): Layer.Layer<Service> =>
   Layer.succeed(
     Service,
     Service.of({

packages/core/src/plugin/sdk.ts

@@ -4,7 +4,7 @@ import type { Plugin } from "@opencode-ai/plugin/effect/plugin"
 import { Context, Effect, Layer } from "effect"
 import { makeGlobalNode } from "@opencode-ai/util/effect/app-node"
 import { Bus } from "../bus.js"
-import type { Versioned } from "../plugin.js"
+import type { Generation } from "../plugin.js"
 
 export const Updated = Bus.ephemeral({ type: "sdk.plugin.updated", schema: {} })
 
@@ -21,7 +21,7 @@ export const Updated = Bus.ephemeral({ type: "sdk.plugin.updated", schema: {} })
  */
 export interface Interface {
   readonly register: (plugin: Plugin) => Effect.Effect<void>
-  readonly all: () => readonly Versioned[]
+  readonly all: () => readonly Generation[]
 }
 
 export class Service extends Context.Service<Service, Interface>()("@opencode/SdkPlugins") {}
@@ -30,12 +30,12 @@ export const layer = Layer.effect(
   Service,
   Effect.gen(function* () {
     const bus = yield* Bus.Service
-    const plugins = new Map<string, Versioned>()
+    const plugins = new Map<string, Generation>()
     let revision = 0
     return Service.of({
       register: (plugin) =>
         Effect.sync(() => {
-          plugins.set(plugin.id, { ...plugin, version: String(++revision), source: { type: "sdk" } })
+          plugins.set(plugin.id, { ...plugin, revision: String(++revision), source: { type: "sdk" } })
         }).pipe(Effect.andThen(bus.publish(Updated, {})), Effect.asVoid),
       all: () => [...plugins.values()],
     })

packages/core/src/plugin/skill.ts

@@ -3,10 +3,11 @@
 export * as SkillPlugin from "./skill.js"
 
 import { define, type Context } from "@opencode-ai/plugin/effect/plugin"
+import { Document } from "@opencode-ai/schema/config"
 import { Effect } from "effect"
 import { AbsolutePath } from "../schema.js"
 import { Skill } from "../skill.js"
-import { ConfigPluginSource } from "../config/plugin/source.js"
+import { Config } from "../config.js"
 import os from "os"
 import opencodeContent from "./skill/opencode.md" with { type: "text" }
 import reportContent from "./skill/report.md" with { type: "text" }
@@ -68,9 +69,11 @@ const reportContentWithDiagnostics = Effect.fn("SkillPlugin.reportContentWithDia
 })
 
 const configuredPlugins = Effect.fn("SkillPlugin.configuredPlugins")(function* () {
-  const sources = yield* ConfigPluginSource.Service
-  return (yield* sources.operations())
-    .map((operation) => (operation.type === "remove" ? `-${operation.target}` : operation.target))
+  const config = yield* Config.Service
+  return (yield* config.entries())
+    .filter((entry): entry is Document => entry.type === "document")
+    .flatMap((entry) => entry.info.plugins ?? [])
+    .map((entry) => (typeof entry === "string" ? entry : entry.package))
     .toSorted()
 })
 

packages/core/src/plugin/skill/opencode.md

@@ -11,6 +11,9 @@ truth. Follow links from that page when the question needs more detail. Fetch
 <https://opencode.ai/v2/docs/> first when you need to discover the relevant
 documentation page.
 
+A machine-readable documentation index is available at
+<https://opencode.ai/v2/llms.txt>.
+
 ## Version policy
 
 Always answer for OpenCode V2 unless the user explicitly asks about V1,
@@ -152,6 +155,8 @@ before answering. Refer to this guide when the user wants to build a plugin. It
 covers hooks, transforms, tools, plugin context capabilities, and package
 entrypoints. Plugins can also extend the TUI; for those, fetch the
 [CLI plugin guide](https://opencode.ai/v2/docs/build/plugins/cli).
+For custom methods and events shared with other plugins or clients, fetch the
+[RPC guide](https://opencode.ai/v2/docs/build/plugins/rpc).
 
 ## [Service](https://opencode.ai/v2/docs/troubleshooting#check-the-background-service)
 
@@ -220,6 +225,16 @@ exposes typed Effects, Streams, and decoded OpenCode schema values. Its
 `Service` API can discover, start, stop, and authenticate with the local
 background service from a Node application.
 
+## [SDK](https://opencode.ai/v2/docs/build/sdk)
+
+For questions about embedding OpenCode directly in an application, fetch the
+full [SDK guide](https://opencode.ai/v2/docs/build/sdk) before answering. The SDK
+hosts OpenCode in the application without opening an HTTP listener.
+
+Use the [Effect SDK guide](https://opencode.ai/v2/docs/build/sdk/effect) for
+Effect applications. For Cloudflare Durable Objects, use the
+[Cloudflare SDK guide](https://opencode.ai/v2/docs/build/sdk/cloudflare).
+
 ## [Troubleshooting](https://opencode.ai/v2/docs/troubleshooting)
 
 OpenCode runs a client and a background server. Start by determining whether a

packages/core/src/plugin/supervisor-service.ts

@@ -7,7 +7,10 @@ import { Context, Effect } from "effect"
  * imports: the supervisor reaches PluginRuntime, which depends on Session.
  */
 export interface Interface {
-  /** Wait for the initial plugin generation and startup updates to settle. */
+  /**
+   * Wait for the plugin generation to settle. Use this rarely: blocking reads,
+   * UI startup, or other unrelated work on plugin boot should be avoided.
+   */
   readonly flush: Effect.Effect<void>
 }
 

packages/core/src/plugin/supervisor.ts

@@ -14,17 +14,20 @@ import { PluginInternal } from "./internal.js"
 import { PluginModule } from "./module.js"
 import { SdkPlugins } from "./sdk.js"
 import { Service } from "./supervisor-service.js"
+import { PluginUpdate } from "./update.js"
 
 const resolve = Effect.fn("PluginSupervisor.resolve")(function* (
-  pre: readonly Plugin.Versioned[],
-  post: readonly Plugin.Versioned[],
+  pre: readonly Plugin.Generation[],
+  post: readonly Plugin.Generation[],
   operations: readonly ConfigPluginSource.Operation[],
+  install: boolean,
 ) {
   const matches = (selector: string, target: string) =>
     selector === "*" || (selector.endsWith(".*") ? target.startsWith(selector.slice(0, -1)) : selector === target)
   const definitions = [...pre, ...post]
   const enabled = new Set(definitions.map((plugin) => plugin.id))
-  const packages = new Map<string, Plugin.Versioned>()
+  const packages = new Map<string, Plugin.Generation>()
+  const pending = new Set<string>()
   const failures = new Map<
     string,
     Plugin.Info & { readonly state: Extract<Plugin.State, { readonly status: "failed" }> }
@@ -51,13 +54,17 @@ const resolve = Effect.fn("PluginSupervisor.resolve")(function* (
       continue
     }
 
-    const plugin = yield* PluginModule.load(operation).pipe(
+    const plugin = yield* PluginModule.load(operation, { install }).pipe(
       Effect.catchCause((cause) =>
         Effect.logWarning("failed to load plugin", { target: operation.target, cause }).pipe(
           Effect.as({ error: Cause.pretty(cause) }),
         ),
       ),
     )
+    if ("pending" in plugin) {
+      pending.add(operation.target)
+      continue
+    }
     if ("error" in plugin) {
       failures.set(operation.target, {
         source: pluginSource(operation.target),
@@ -80,9 +87,7 @@ const resolve = Effect.fn("PluginSupervisor.resolve")(function* (
       ...post.filter((plugin) => enabled.has(plugin.id)),
     ],
     failures: [...failures.values()],
-    refreshes: [...packages.entries()].flatMap(([target, plugin]) =>
-      !path.isAbsolute(target) && enabled.has(plugin.id) ? [target] : [],
-    ),
+    pending: [...pending],
   }
 })
 
@@ -94,45 +99,74 @@ export const layer = Layer.effect(
     const instance = yield* InstancePlugins.Service
     const sources = yield* ConfigPluginSource.Service
     const bus = yield* Bus.Service
-    const npm = yield* Npm.Service
+    const updates = yield* PluginUpdate.Service
     const ready = yield* Latch.make()
+    let packages = new Set<string>()
+    let outdated = new Set<string>()
+    let generation = 0
     let observed = 0
 
     const activate = Effect.fn("PluginSupervisor.activate")(function* () {
+      const current = ++generation
       // Resolve OpenCode's internal plugins with their privileged Location services.
       const internal = yield* PluginInternal.list()
       // Combine internal plugins with host-contributed plugins in boot order.
       // Instance-bound plugins come last: later activation can override earlier
       // container writes, so the instance's explicit choices win over globals.
       const pre = [
-        ...internal.pre.map((plugin) => ({ ...plugin, version: "internal", source: { type: "builtin" as const } })),
+        ...internal.pre.map((plugin) => ({ ...plugin, revision: "internal", source: { type: "builtin" as const } })),
         ...sdk.all(),
         ...instance.all(),
       ]
       const post = internal.post.map((plugin) => ({
         ...plugin,
-        version: "internal",
+        revision: "internal",
         source: { type: "builtin" as const },
       }))
       const operations = yield* sources.operations()
-      // Apply config operations and load enabled package plugins into one ordered generation.
-      const resolved = yield* resolve(pre, post, operations)
-      // Replace the active generation in one scoped, batched activation.
-      yield* registry.activate(resolved.plugins, resolved.failures)
-      if (resolved.refreshes.length) {
-        yield* Effect.forEach(
-          resolved.refreshes,
-          (target) =>
-            npm
-              .add(target, { subpaths: ["server", ""], refresh: true })
-              .pipe(
-                Effect.catchCause((cause) => Effect.logWarning("failed to refresh package plugin", { target, cause })),
-              ),
-          { concurrency: "unbounded", discard: true },
-        ).pipe(Effect.forkDetach)
-      }
+      // Activate everything available locally before waiting on missing package installs.
+      const immediate = yield* resolve(pre, post, operations, false)
+      const source = (source: Plugin.Source) =>
+        source.type === "package" && outdated.has(source.target)
+          ? { ...source, outdated: true as const }
+          : source
+      const apply = (resolved: typeof immediate) =>
+        registry.activate(
+          resolved.plugins.map((plugin) => (plugin.source ? { ...plugin, source: source(plugin.source) } : plugin)),
+          resolved.failures.map((failure) => ({ ...failure, source: source(failure.source) })),
+        )
+      yield* apply(immediate)
+      const resolved = immediate.pending.length ? yield* resolve(pre, post, operations, true) : immediate
+      if (resolved !== immediate) yield* apply(resolved)
+      const loaded = new Set(
+        [...resolved.plugins, ...resolved.failures].flatMap((plugin) =>
+          plugin.source?.type === "package" ? [plugin.source.target] : [],
+        ),
+      )
+      packages = loaded
+      yield* Effect.forEach(
+        loaded,
+        (target) => updates.check(target).pipe(Effect.map((available) => [target, available] as const)),
+        { concurrency: "unbounded" },
+      ).pipe(
+        Effect.flatMap((checked) => {
+          if (current !== generation) return Effect.void
+          const next = new Set(checked.flatMap(([target, available]) => (available ? [target] : [])))
+          if (next.size === outdated.size && [...next].every((target) => outdated.has(target))) return Effect.void
+          outdated = next
+          return apply(resolved)
+        }),
+        Effect.forkScoped({ startImmediately: true }),
+      )
     })
-    const updates = Stream.merge(sources.changes(), bus.subscribe([Event.Updated, SdkPlugins.Updated])).pipe(
+    const reloads = Stream.merge(
+      Stream.merge(sources.changes(), bus.subscribe([Event.Updated, SdkPlugins.Updated])),
+      updates.changes().pipe(
+        Stream.filter((target) => packages.has(target)),
+        Stream.tap((target) => Effect.sync(() => outdated.delete(target))),
+        Stream.map(() => undefined),
+      ),
+    ).pipe(
       // Make accepted work visible to flush before coalescing the burst.
       Stream.mapEffect(() =>
         Effect.gen(function* () {
@@ -142,7 +176,7 @@ export const layer = Layer.effect(
         }),
       ),
     )
-    yield* Stream.concat(Stream.succeed(0), updates).pipe(
+    yield* Stream.concat(Stream.succeed(0), reloads).pipe(
       // Keep observing updates while activation runs, retaining only the latest generation request.
       Stream.buffer({ capacity: 1, strategy: "sliding" }),
       Stream.debounce("100 millis"),
@@ -154,6 +188,7 @@ export const layer = Layer.effect(
       ),
       Effect.forkScoped({ startImmediately: true }),
     )
+    yield* Effect.sleep("24 hours").pipe(Effect.andThen(activate()), Effect.forever, Effect.forkScoped)
     return Service.of({ flush: ready.await })
   }),
 )
@@ -163,6 +198,7 @@ const nodeDeps = [
   SdkPlugins.node,
   InstancePlugins.node,
   ConfigPluginSource.node,
+  PluginUpdate.node,
   Bus.node,
   Npm.node,
   PluginInternal.requirements,
@@ -170,7 +206,7 @@ const nodeDeps = [
 
 function pluginSource(target: string): Plugin.Source {
   if (path.isAbsolute(target)) return { type: "local", path: target }
-  return { type: "package", package: target }
+  return { type: "package", target }
 }
 
 export const node = makeLocationNode({ service: Service, layer, deps: nodeDeps })

packages/core/src/plugin/update.ts

@@ -0,0 +1,54 @@
+export * as PluginUpdate from "./update.js"
+
+import { Clock, Context, Effect, Layer, Option, PubSub, Stream } from "effect"
+import { Npm } from "@opencode-ai/util/npm"
+import { EffectFlock } from "@opencode-ai/util/effect-flock"
+import { makeGlobalNode } from "@opencode-ai/util/effect/app-node"
+import { KeyedMutex } from "../effect/keyed-mutex.js"
+
+const interval = 24 * 60 * 60 * 1_000
+
+export interface Interface {
+  readonly check: (target: string) => Effect.Effect<boolean>
+  readonly update: (target: string) => Effect.Effect<void, Npm.InstallFailedError | EffectFlock.LockError>
+  readonly changes: () => Stream.Stream<string>
+}
+
+export class Service extends Context.Service<Service, Interface>()("@opencode/PluginUpdate") {}
+
+const layer = Layer.effect(
+  Service,
+  Effect.gen(function* () {
+    const npm = yield* Npm.Service
+    const locks = KeyedMutex.makeUnsafe<string>()
+    const status = new Map<string, { readonly outdated: boolean; readonly checkedAt: number }>()
+    const changes = yield* PubSub.unbounded<string>()
+
+    return Service.of({
+      check: (target) =>
+        locks.withLock(target)(
+          Effect.gen(function* () {
+            const checkedAt = yield* Clock.currentTimeMillis
+            const current = status.get(target)
+            if (current && checkedAt - current.checkedAt < interval) return current.outdated
+            const outdated = yield* npm.check(target).pipe(
+              Effect.tapCause((cause) => Effect.logWarning("failed to check plugin update", { target, cause })),
+              Effect.option,
+            )
+            const value = Option.getOrElse(outdated, () => current?.outdated ?? false)
+            status.set(target, { outdated: value, checkedAt })
+            return value
+          }),
+        ),
+      update: (target) =>
+        npm.update(target).pipe(
+          Effect.tap(() => Effect.sync(() => status.delete(target))),
+          Effect.tap(() => PubSub.publish(changes, target)),
+          Effect.asVoid,
+        ),
+      changes: () => Stream.fromPubSub(changes),
+    })
+  }),
+)
+
+export const node = makeGlobalNode({ service: Service, layer, deps: [Npm.node] })

packages/core/src/plugin/vcs/git.ts

@@ -20,7 +20,6 @@ import type { Patch } from "../../vcs/patch.js"
 
 export const Plugin = define({
   id: "opencode.vcs.git",
-  vcs: { id: "git", markers: [".git"] },
   effect: Effect.fn("VcsGitPlugin")(function* (ctx) {
     const location = yield* Location.Service
     if (location.vcs?.type !== "git") return

packages/core/src/plugin/vcs/hg.ts

@@ -24,7 +24,6 @@ import {
 
 export const Plugin = define({
   id: "opencode.vcs.hg",
-  vcs: { id: "hg", markers: [".hg"] },
   effect: Effect.fn("VcsHgPlugin")(function* (ctx) {
     const location = yield* Location.Service
     if (location.vcs?.type !== "hg") return

packages/core/src/project.ts

@@ -13,7 +13,6 @@ import { Git } from "./git.js"
 import { AppProcess } from "@opencode-ai/util/process"
 import { makeGlobalNode } from "@opencode-ai/util/effect/app-node"
 import { Hash } from "@opencode-ai/util/hash"
-import { ProjectMarkers } from "./project/markers.js"
 import { ProjectSchema } from "./project/schema.js"
 import { ProjectTable, upsertProject } from "./project/sql.js"
 import { WorktreeTable } from "./worktree/sql.js"
@@ -44,7 +43,6 @@ export interface Resolved {
   // This checkout's main directory; the stored project canonical may be another clone.
   readonly canonical: AbsolutePath
   readonly vcs?: Vcs
-  readonly vcsBackend?: string
 }
 
 // Keep this filesystem-only; permission checks use it and should not execute VCS commands.
@@ -98,7 +96,6 @@ const layer = Layer.effect(
   Effect.gen(function* () {
     const fs = yield* FSUtil.Service
     const git = yield* Git.Service
-    const markers = yield* ProjectMarkers.Service
     const proc = yield* AppProcess.Service
     const bus = yield* Bus.Service
     const db = (yield* Database.Service).db
@@ -172,7 +169,7 @@ const layer = Layer.effect(
               if (candidate.id === item.projectID) return false
               if (!FSUtil.contains(directory, candidate.directory)) return false
               const found = yield* fs
-                .up({ targets: [...markers.targets()], start: candidate.directory, stop: directory, mode: "first" })
+                .up({ targets: [".git", ".hg"], start: candidate.directory, stop: directory, mode: "first" })
                 .pipe(Effect.orElseSucceed(() => []))
               if (!found[0]) return false
               return (yield* fs.resolve(path.dirname(found[0]))) === directory
@@ -318,10 +315,9 @@ const layer = Layer.effect(
 
     const resolve = Effect.fn("Project.resolve")(function* (
       input: AbsolutePath,
-      options?: { readonly discovery?: boolean },
+      _options?: { readonly discovery?: boolean },
     ) {
       const directory = AbsolutePath.make(yield* fs.resolve(input))
-      const marker = yield* markers.discover(directory, options)
       const native = yield* fs.up({ targets: [".git", ".hg"], start: directory, mode: "first" }).pipe(
         Effect.map((matches) => matches[0]),
         Effect.orElseSucceed(() => undefined),
@@ -330,7 +326,7 @@ const layer = Layer.effect(
         native && path.basename(native) === ".git"
           ? yield* git.repo.discover(AbsolutePath.make(path.dirname(native)))
           : undefined
-      if (repo && (!marker || FSUtil.contains(marker.directory, repo.worktree))) {
+      if (repo) {
         const previous = yield* cached(repo.commonDirectory)
         const id = (yield* remote(repo)) ?? previous ?? (yield* rootCommit(repo))
         const canonical =
@@ -346,27 +342,14 @@ const layer = Layer.effect(
           directory: repo.worktree,
           canonical,
           vcs: { type: "git" as const, store: repo.commonDirectory },
-          ...(marker?.directory === repo.worktree && marker.type !== "git" ? { vcsBackend: marker.type } : {}),
         })
       }
 
       const hg = native && path.basename(native) === ".hg" ? yield* hgDiscover(AbsolutePath.make(native)) : undefined
-      if (hg && (!marker || FSUtil.contains(marker.directory, hg.directory))) {
+      if (hg) {
         return yield* persist({
           ...hg,
           canonical: hg.directory,
-          ...(marker?.directory === hg.directory && marker.type !== "hg" ? { vcsBackend: marker.type } : {}),
-        })
-      }
-
-      if (marker) {
-        const previous = yield* cached(marker.marker)
-        return yield* persist({
-          previous,
-          id: previous ?? ID.make(Hash.fast(`vcs-repository:${marker.type}:${marker.marker}`)),
-          directory: marker.directory,
-          canonical: marker.directory,
-          vcs: { type: marker.type, store: marker.marker },
         })
       }
 
@@ -385,5 +368,5 @@ const layer = Layer.effect(
 export const node = makeGlobalNode({
   service: Service,
   layer: layer,
-  deps: [Bus.node, Database.node, FSUtil.node, Git.node, ProjectMarkers.node, AppProcess.node],
+  deps: [Bus.node, Database.node, FSUtil.node, Git.node, AppProcess.node],
 })

packages/core/src/project/markers.ts

@@ -1,191 +0,0 @@
-export * as ProjectMarkers from "./markers.js"
-
-import { FSUtil } from "@opencode-ai/util/fs-util"
-import { Global } from "@opencode-ai/util/global"
-import { Npm } from "@opencode-ai/util/npm"
-import { makeGlobalNode } from "@opencode-ai/util/effect/app-node"
-import { Context, Effect, Layer, Option } from "effect"
-import { parse, type ParseError } from "jsonc-parser"
-import path from "path"
-import { fileURLToPath } from "url"
-import type { ConfigPluginSource } from "../config/plugin/source.js"
-import type { Versioned } from "../plugin.js"
-import { PluginModule } from "../plugin/module.js"
-import { PluginSourceDirectory } from "../plugin/source-directory.js"
-import { SdkPlugins } from "../plugin/sdk.js"
-import { AbsolutePath } from "../schema.js"
-
-export interface Match {
-  readonly type: string
-  readonly directory: AbsolutePath
-  readonly marker: AbsolutePath
-}
-
-export interface Interface {
-  readonly discover: (
-    directory: AbsolutePath,
-    options?: { readonly discovery?: boolean },
-  ) => Effect.Effect<Match | undefined>
-  readonly targets: () => readonly string[]
-}
-
-export class Service extends Context.Service<Service, Interface>()("@opencode/ProjectMarkers") {}
-
-const layer = Layer.effect(
-  Service,
-  Effect.gen(function* () {
-    const fs = yield* FSUtil.Service
-    const global = yield* Global.Service
-    const npm = yield* Npm.Service
-    const sdk = yield* SdkPlugins.Service
-    const known = new Set([".git", ".hg"])
-    const loaded = new Map<string, Versioned | undefined>()
-
-    // The filesystem half of discovery: walk up for config, scan plugin
-    // directories, and read configured plugin operations. This is the part a
-    // no-discovery caller must skip — it imports plugin modules.
-    const scanOperations = Effect.fnUntraced(function* (directory: AbsolutePath) {
-      const found = yield* fs
-        .up({ targets: [".opencode", "opencode.json", "opencode.jsonc"], start: directory })
-        .pipe(Effect.orElseSucceed(() => []))
-      const roots = [global.config, ...found.filter((value) => path.basename(value) === ".opencode").toReversed()]
-      const files = [
-        ...["opencode.json", "opencode.jsonc"].map((name) => path.join(global.config, name)),
-        ...found.filter((value) => path.basename(value) !== ".opencode").toReversed(),
-        ...roots.slice(1).flatMap((root) => ["opencode.json", "opencode.jsonc"].map((name) => path.join(root, name))),
-      ]
-      const automatic = yield* Effect.forEach(roots, (root) => PluginSourceDirectory.discover(fs, root)).pipe(
-        Effect.map((entries) => entries.flat()),
-      )
-      const configured = yield* Effect.forEach([...new Set(files)], (file) => read(fs, file)).pipe(
-        Effect.map((entries) => entries.flat()),
-      )
-      return yield* Effect.forEach(
-        [
-          ...automatic.map((target): ConfigPluginSource.Operation => ({ type: "add", target, options: {} })),
-          ...configured,
-        ],
-        (operation) => {
-          if (operation.type === "remove" || !path.isAbsolute(operation.target)) return Effect.succeed(operation)
-          return fs.stat(operation.target).pipe(
-            Effect.map((info) => ({
-              ...operation,
-              mtime: Option.getOrElse(info.mtime, () => new Date(0)).getTime(),
-            })),
-            Effect.orElseSucceed(() => operation),
-          )
-        },
-      )
-    })
-
-    const discover = Effect.fn("ProjectMarkers.discover")(function* (
-      directory: AbsolutePath,
-      options?: { readonly discovery?: boolean },
-    ) {
-      // discovery: false skips the config scan and its plugin module loading;
-      // sdk-declared vcs markers are host-explicit, not ambient, so they stay.
-      const operations = options?.discovery === false ? [] : yield* scanOperations(directory)
-      const declarations = new Map<string, { readonly id: string; readonly markers: readonly string[] }>()
-
-      for (const plugin of sdk.all()) {
-        if (!plugin.vcs) continue
-        declarations.set(plugin.id, { id: plugin.vcs.id ?? plugin.id, markers: plugin.vcs.markers })
-      }
-
-      for (const operation of operations) {
-        if (operation.type === "remove") {
-          for (const id of declarations.keys()) {
-            if (
-              operation.target === "*" ||
-              (operation.target.endsWith(".*") ? id.startsWith(operation.target.slice(0, -1)) : operation.target === id)
-            ) {
-              declarations.delete(id)
-            }
-          }
-          continue
-        }
-        if (operation.target === "*" || operation.target.endsWith(".*") || operation.target.startsWith("opencode."))
-          continue
-        const key = JSON.stringify(operation)
-        const plugin = loaded.has(key)
-          ? loaded.get(key)
-          : yield* PluginModule.load(operation).pipe(
-              Effect.provideService(Npm.Service, npm),
-              Effect.catchCause((cause) =>
-                Effect.logDebug("failed to discover plugin repository markers", {
-                  target: operation.target,
-                  cause,
-                }).pipe(Effect.as(undefined)),
-              ),
-              Effect.tap((value) => Effect.sync(() => loaded.set(key, value))),
-            )
-        if (!plugin?.vcs) continue
-        declarations.set(plugin.id, { id: plugin.vcs.id ?? plugin.id, markers: plugin.vcs.markers })
-      }
-
-      const markers = new Map<string, string>()
-      for (const declaration of declarations.values()) {
-        if (!/^[a-z][a-z0-9._-]*$/.test(declaration.id)) continue
-        for (const marker of declaration.markers) {
-          if (!marker || marker === "." || marker === ".." || /[\\/]/.test(marker)) continue
-          known.add(marker)
-          markers.set(marker, declaration.id)
-        }
-      }
-      if (!markers.size) return undefined
-
-      const marker = yield* fs.up({ targets: [...markers.keys()], start: directory, mode: "first" }).pipe(
-        Effect.map((entries) => entries[0]),
-        Effect.orElseSucceed(() => undefined),
-      )
-      if (!marker) return undefined
-      const type = markers.get(path.basename(marker))
-      if (!type) return undefined
-      return {
-        type,
-        directory: AbsolutePath.make(path.dirname(marker)),
-        marker: AbsolutePath.make(marker),
-      } satisfies Match
-    })
-
-    return Service.of({ discover, targets: () => [...known] })
-  }),
-)
-
-function read(fs: FSUtil.Interface, file: string): Effect.Effect<ConfigPluginSource.Operation[]> {
-  return Effect.gen(function* () {
-    const source = yield* fs.readFileStringSafe(file).pipe(Effect.orElseSucceed(() => undefined))
-    if (!source) return []
-    const errors: ParseError[] = []
-    const document: unknown = parse(source, errors, { allowTrailingComma: true })
-    if (errors.length || typeof document !== "object" || document === null || !("plugins" in document)) return []
-    if (!Array.isArray(document.plugins)) return []
-    return document.plugins.flatMap<ConfigPluginSource.Operation>((entry) => {
-      if (typeof entry === "string" && entry.startsWith("-")) {
-        return [{ type: "remove", target: entry.slice(1) }]
-      }
-      if (
-        typeof entry !== "string" &&
-        (typeof entry !== "object" || entry === null || !("package" in entry) || typeof entry.package !== "string")
-      ) {
-        return []
-      }
-      const target = typeof entry === "string" ? entry : entry.package
-      const options =
-        typeof entry !== "string" && "options" in entry && typeof entry.options === "object" && entry.options !== null
-          ? Object.fromEntries(Object.entries(entry.options))
-          : {}
-      if (target.startsWith("file://")) return [{ type: "add", target: fileURLToPath(target), options }]
-      if (target.startsWith("./") || target.startsWith("../")) {
-        return [{ type: "add", target: path.resolve(path.dirname(file), target), options }]
-      }
-      return [{ type: "add", target, options }]
-    })
-  })
-}
-
-export const node = makeGlobalNode({
-  service: Service,
-  layer,
-  deps: [FSUtil.node, Global.node, Npm.node, SdkPlugins.node],
-})

packages/core/src/session.ts

@@ -1,7 +1,7 @@
 export * as Session from "./session.js"
 export * from "./session/schema.js"
 
-import { Cause, Effect, Layer, Schema, Context, RcMap, Stream } from "effect"
+import { Cause, Effect, Layer, Schema, Context, Stream } from "effect"
 import { ListAnchor } from "@opencode-ai/schema/session"
 import { and, desc, eq } from "drizzle-orm"
 import { Project } from "./project.js"
@@ -10,6 +10,7 @@ import { Location } from "./location.js"
 import { SessionMessage } from "./session/message.js"
 import { PromptInput } from "@opencode-ai/schema/prompt-input"
 import { Bus } from "./bus.js"
+import { Instance } from "./instance/service.js"
 import { Database } from "./database/database.js"
 import { SessionProjector } from "./session/projector.js"
 import { SessionMessageTable } from "./session/sql.js"
@@ -238,20 +239,16 @@ const layer = Layer.effect(
     const global = yield* Global.Service
     const execution = yield* SessionExecution.Service
     const store = yield* SessionStore.Service
+    const instances = yield* Instance.Service
     const locations = yield* LocationServiceMap.Service
     const fs = yield* FSUtil.Service
     const jobs = yield* Job.Service
     const environments = yield* SessionEnvironment.Service
-    const sessions = yield* Session.make((ref) => locations.get(ref))
+    const sessions = yield* Session.make()
     const admission = yield* SessionInbox.Service
     const closeTransport = Effect.fn("Session.closeTransport")(function* (session: SessionSchema.Info) {
-      const location = Location.Ref.make({
-        directory: session.location.directory,
-        workspaceID: session.location.workspaceID,
-      })
-      if (!(yield* RcMap.has(locations.rcMap, location))) return
       yield* SessionModelTransport.Service.use((transport) => transport.close(session.id)).pipe(
-        Effect.provide(locations.get(location)),
+        instances.provideIfLoaded(session),
       )
     })
     const isDurableSessionEvent = Schema.is(SessionEvent.Durable)
@@ -403,7 +400,7 @@ const layer = Layer.effect(
       prompt: (input) => sessions.forSession(input.sessionID).prompt(input),
       generate: Effect.fn("Session.generate")(function* (input) {
         const session = yield* result.get(input.sessionID)
-        const generate = yield* SessionGenerate.Service.pipe(Effect.provide(locations.get(session.location)))
+        const generate = yield* SessionGenerate.Service.pipe(instances.provide(session))
         return yield* generate.generate(input)
       }),
       command: Effect.fn("Session.command")(function* (input) {
@@ -412,7 +409,7 @@ const layer = Layer.effect(
           const plugins = yield* PluginSupervisor.Service
           yield* plugins.flush
           return yield* Command.Service
-        }).pipe(Effect.provide(locations.get(session.location)))
+        }).pipe(instances.provide(session))
         const delivery = input.delivery ?? "steer"
         yield* commands.execute({
           name: input.command,
@@ -468,7 +465,8 @@ const layer = Layer.effect(
           Effect.gen(function* () {
             const latest = yield* result.get(input.sessionID)
             const source = yield* fs.stat(latest.location.directory).pipe(Effect.orElseSucceed(() => undefined))
-            if (!source || source.type !== "Directory") {
+            // Active runners must hand off at a step boundary to retain their continuation.
+            if ((!source || source.type !== "Directory") && !(yield* execution.isActive(input.sessionID))) {
               const cancellations = (yield* SessionInbox.moveIDs(db, input.sessionID)).map(
                 (item) => [SessionEvent.InboxCancelled, { sessionID: input.sessionID, inboxID: item.id }] as const,
               )
@@ -534,6 +532,7 @@ export const node = makeGlobalNode({
     Project.node,
     SessionExecution.node,
     SessionStore.node,
+    Instance.byLocationNode,
     SessionInbox.node,
     LocationServiceMap.node,
     SessionProjector.node,

packages/core/src/session/execution.ts

@@ -4,7 +4,7 @@ import { Cause, Context, Effect, Exit, Layer } from "effect"
 import { Bus } from "../bus.js"
 import { Database } from "../database/database.js"
 import { Job } from "../job.js"
-import { LocationServiceMap } from "../location-service-map.js"
+import { Instance } from "../instance/service.js"
 import { makeGlobalNode } from "@opencode-ai/util/effect/app-node"
 import { SessionEvent } from "./event.js"
 import { SessionRunCoordinator } from "./run-coordinator.js"
@@ -35,7 +35,7 @@ export interface Interface {
   readonly awaitIdle: (sessionID: SessionSchema.ID) => Effect.Effect<void>
 }
 
-/** Routes execution from a Session ID to the runner owned by that Session's Location. */
+/** Routes execution from a Session ID to its selected instance's runner. */
 export class Service extends Context.Service<Service, Interface>()("@opencode/SessionExecution") {}
 
 type InterruptReason = "user" | "shutdown"
@@ -48,12 +48,12 @@ export function terminal(exit: Exit.Exit<void, SessionRunner.RunError>, reason?:
   return { type: "failed" as const, error: toSessionError(failure) }
 }
 
-/** Process-local execution: drains run in this process, routed through the Session's Location graph. */
+/** Process-local execution: drains run in this process using the selected instance. */
 export const layer = Layer.effect(
   Service,
   Effect.gen(function* () {
     const store = yield* SessionStore.Service
-    const locations = yield* LocationServiceMap.Service
+    const instances = yield* Instance.Service
     const bus = yield* Bus.Service
     const jobs = yield* Job.Service
     const db = (yield* Database.Service).db
@@ -90,7 +90,7 @@ export const layer = Layer.effect(
       const result = yield* SessionRunner.Service.use((runner) =>
         runner.drain({ sessionID, force, continuation, promotable }),
       ).pipe(
-        Effect.provide(locations.get(session.location)),
+        instances.provide(session),
         Effect.tapCause((cause) =>
           Cause.hasInterruptsOnly(cause)
             ? Effect.void
@@ -173,7 +173,7 @@ export const layer = Layer.effect(
 export const node = makeGlobalNode({
   service: Service,
   layer,
-  deps: [SessionStore.node, LocationServiceMap.node, Bus.node, Database.node, Job.node],
+  deps: [SessionStore.node, Instance.byLocationNode, Bus.node, Database.node, Job.node],
 })
 
 /** Low-level compatibility layer for callers that only need durable Session recording. */

packages/core/src/session/runner/llm.ts

@@ -96,7 +96,7 @@ const layer = Layer.effect(
                 step = 1
               }
               if (pending?.type === "move")
-                return DrainResult.Moved({ continuation: !entering && continuing ? { step } : undefined })
+                return DrainResult.Moved({ continuation: continuing ? { step } : undefined })
               if (pending?.type === "compaction") {
                 const session = yield* store.get(sessionID)
                 if (!session) return yield* Effect.die(new Error(`Session not found: ${sessionID}`))

packages/core/src/session/session.ts

@@ -1,11 +1,11 @@
 export * as Session from "./session.js"
 
-import { DateTime, Effect, Fiber, Layer, Schema, Scope } from "effect"
+import { DateTime, Effect, Fiber, Schema, Scope } from "effect"
 import type { Agent } from "@opencode-ai/schema/agent"
 import type { Model } from "@opencode-ai/schema/model"
 import { Event } from "@opencode-ai/schema/event"
 import { Bus } from "../bus.js"
-import { Location } from "../location.js"
+import { Instance } from "../instance/service.js"
 import { PluginSupervisor } from "../plugin/supervisor-service.js"
 import { Shell } from "../shell.js"
 import { ShellResult } from "../shell/result.js"
@@ -33,26 +33,19 @@ import { SessionRevert } from "./revert.js"
 import { SessionSchema } from "./schema.js"
 import { SessionStore } from "./store.js"
 
-export type Services =
-  | PluginSupervisor.Service
-  | Reference.Service
-  | SessionPrompt.Service
-  | SessionRevert.Service
-  | Shell.Service
-  | Skill.Service
-
 type PromptRequest = SessionPrompt.Input & {
   id?: SessionMessage.ID
   resume?: boolean
 }
 
 /**
- * Build once in the host Scope: `const sessions = yield* Session.make(servicesFor)`.
+ * Build once in the host Scope: `const sessions = yield* Session.make()`.
  * Use `sessions.forSession(id)` for handles that share host services and reload current state.
  */
-export const make = Effect.fn("Session.make")(function* (servicesFor: (ref: Location.Ref) => Layer.Layer<Services>) {
+export const make = Effect.fn("Session.make")(function* () {
   const bus = yield* Bus.Service
   const store = yield* SessionStore.Service
+  const instances = yield* Instance.Service
   const execution = yield* SessionExecution.Service
   const admission = yield* SessionInbox.Service
   const scope = yield* Scope.Scope
@@ -174,7 +167,7 @@ export const make = Effect.fn("Session.make")(function* (servicesFor: (ref: Loca
               const preparation = yield* SessionPrompt.Service
               const references = yield* Reference.Service
               return { item: yield* preparation.prepare({ sessionID, messageID, input }), references }
-            }).pipe(Effect.provide(servicesFor(session.location))),
+            }).pipe(instances.provide(session)),
           )
           // Commit a staged revert only after preparation succeeds, before admitting new work.
           if (session.revert) yield* SessionRevert.commit(bus, session)
@@ -205,7 +198,7 @@ export const make = Effect.fn("Session.make")(function* (servicesFor: (ref: Loca
         const plugins = yield* PluginSupervisor.Service
         yield* plugins.flush
         return yield* Shell.Service
-      }).pipe(Effect.provide(servicesFor(session.location)))
+      }).pipe(instances.provide(session))
       const started = yield* shell
         .create({
           command: input.command,
@@ -256,7 +249,7 @@ export const make = Effect.fn("Session.make")(function* (servicesFor: (ref: Loca
     input: { id?: SessionMessage.ID; skill: Skill.ID; resume?: boolean },
   ) {
     const session = yield* get(sessionID)
-    const skills = yield* Skill.Service.pipe(Effect.provide(servicesFor(session.location)))
+    const skills = yield* Skill.Service.pipe(instances.provide(session))
     const skill = yield* skills.get(input.skill)
     if (!skill) return yield* new SkillNotFoundError({ skill: input.skill })
     yield* bus.publish(
@@ -355,14 +348,12 @@ export const make = Effect.fn("Session.make")(function* (servicesFor: (ref: Loca
     if (yield* execution.isActive(sessionID)) return yield* new BusyError({ sessionID })
     return yield* SessionRevert.Service.use((revert) =>
       revert.stage({ session, messageID: input.messageID, files: input.files }),
-    ).pipe(Effect.provide(servicesFor(session.location)))
+    ).pipe(instances.provide(session))
   })
   const clear = Effect.fn("Session.revert.clear")(function* (sessionID: SessionSchema.ID) {
     const session = yield* get(sessionID)
     if (yield* execution.isActive(sessionID)) return yield* new BusyError({ sessionID })
-    yield* SessionRevert.Service.use((revert) => revert.clear(session)).pipe(
-      Effect.provide(servicesFor(session.location)),
-    )
+    yield* SessionRevert.Service.use((revert) => revert.clear(session)).pipe(instances.provide(session))
     return yield* execution.wake(sessionID)
   })
   const commit = Effect.fn("Session.revert.commit")(function* (sessionID: SessionSchema.ID) {

packages/core/src/tool.ts

@@ -1,6 +1,6 @@
 export * as Tool from "./tool.js"
 export { CallID, Content, Error, FileContent, TextContent } from "@opencode-ai/schema/tool"
-export type { Context, Metadata, Options, Result } from "@opencode-ai/schema/tool"
+export type { Context, Metadata, Namespace, Options, Result } from "@opencode-ai/schema/tool"
 
 import { ToolDefinition, type ToolCall } from "@opencode-ai/ai"
 import { Tool } from "@opencode-ai/schema/tool"
@@ -26,6 +26,7 @@ export class RegistrationError extends Schema.TaggedError<RegistrationError>()("
 export interface Draft {
   readonly list: () => readonly (Tool.Info & { readonly id: string })[]
   readonly get: (id: string) => (Tool.Info & { readonly id: string }) | undefined
+  readonly namespace: (namespace: Tool.Namespace) => void
   readonly add: (tool: Tool.Info) => void
   readonly update: (id: string, update: (tool: Types.Mutable<Tool.Info>) => void) => void
   readonly remove: (id: string) => void
@@ -33,7 +34,8 @@ export interface Draft {
 
 type Data = {
   tools: Map<string, Tool.Info & { readonly id: string }>
-  errors: { tool: Tool.Info; error: RegistrationError }[]
+  namespaces: Map<string, Tool.Namespace>
+  errors: { kind: "tool" | "namespace"; name: string; namespace?: string; error: RegistrationError }[]
 }
 
 export interface Interface extends State.Transformable<Draft> {
@@ -42,7 +44,7 @@ export interface Interface extends State.Transformable<Draft> {
 
 export interface Snapshot {
   readonly definitions: ReadonlyArray<ToolDefinition>
-  readonly codeModeCatalog?: ReadonlyArray<CodeModeCatalog.Entry>
+  readonly codeModeCatalog?: CodeModeCatalog.Inventory
   readonly execute: (input: {
     readonly sessionID: SessionSchema.ID
     readonly agent: Agent.ID
@@ -151,15 +153,24 @@ const layer = Layer.effect(
       name: "tool",
       initial: () => ({
         tools: new Map(),
+        namespaces: new Map(),
         errors: [],
       }),
       draft: (draft) => ({
         list: () => Array.from(draft.tools.values()),
         get: (id) => draft.tools.get(id),
+        namespace: (namespace) => {
+          const error = namespaceError(namespace.name)
+          if (error) {
+            draft.errors.push({ kind: "namespace", name: namespace.name, namespace: namespace.name, error })
+            return
+          }
+          draft.namespaces.set(namespace.name, { ...namespace })
+        },
         add: (tool) => {
           const error = registrationError(tool)
           if (error) {
-            draft.errors.push({ tool, error })
+            draft.errors.push({ kind: "tool", name: tool.name, namespace: tool.options?.namespace, error })
             return
           }
           const id = effectiveName(tool)
@@ -176,7 +187,7 @@ const layer = Layer.effect(
             tool.options = { ...tool.options, namespace: current.options?.namespace }
           const error = registrationError(tool)
           if (error) {
-            draft.errors.push({ tool, error })
+            draft.errors.push({ kind: "tool", name: tool.name, namespace: tool.options?.namespace, error })
             return
           }
           draft.tools.set(id, tool)
@@ -188,10 +199,10 @@ const layer = Layer.effect(
       finalize: () =>
         Effect.forEach(
           state.get().errors,
-          ({ tool, error }) =>
-            Effect.logError("Skipping invalid tool registration", {
-              name: tool.name,
-              namespace: tool.options?.namespace,
+          ({ kind, name, namespace, error }) =>
+            Effect.logError(`Skipping invalid ${kind} registration`, {
+              name,
+              namespace,
               error: error.message,
             }),
           { discard: true },
@@ -210,23 +221,25 @@ const layer = Layer.effect(
             active.set(name, tool)
           }
           const direct = new Map(Array.from(active).filter(([, tool]) => tool.options?.codemode === false))
-          const codemode = new Map(Array.from(active).filter(([, tool]) => tool.options?.codemode !== false))
-          const codemodeEnabled = !whollyDisabled("execute", rules)
-          const codemodeTool = codemodeEnabled
-            ? CodeModeTool.create(codemode, (name, tool, input, context) =>
+          const codeModeTools = new Map(Array.from(active).filter(([, tool]) => tool.options?.codemode !== false))
+          const namespaces = state.get().namespaces
+          const codeModeInventory = { tools: codeModeTools, namespaces }
+          const codeModeEnabled = !whollyDisabled("execute", rules)
+          const codeModeTool = codeModeEnabled
+            ? CodeModeTool.create(codeModeInventory, (name, tool, input, context) =>
                 beforeExecute(name, input, context).pipe(
                   Effect.flatMap((event) => executeTool(tool, name, event.input, context)),
                 ),
               )
             : undefined
-          const codeModeCatalog = codemodeEnabled ? CodeModeTool.catalog(codemode) : undefined
+          const codeModeCatalog = codeModeEnabled ? CodeModeTool.catalog(codeModeInventory) : undefined
           return {
             ...(codeModeCatalog === undefined ? {} : { codeModeCatalog }),
             definitions: [
               ...Array.from(direct)
                 .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
                 .map(([, tool]) => definition(tool)),
-              ...(codemodeTool ? [definition(codemodeTool)] : []),
+              ...(codeModeTool ? [definition(codeModeTool)] : []),
             ],
             execute: Effect.fnUntraced(function* (input: Parameters<Snapshot["execute"]>[0]) {
               const context: Tool.Context = {
@@ -239,11 +252,11 @@ const layer = Layer.effect(
               const event = yield* beforeExecute(input.call.name, input.call.input, context)
               const requested = input.definitions?.get(event.tool)
               // Preserve session context removal and alias resolution, now after the repair hook.
-              if (!requested && input.definitions && (direct.has(event.tool) || codemodeTool?.name === event.tool))
+              if (!requested && input.definitions && (direct.has(event.tool) || codeModeTool?.name === event.tool))
                 return yield* new Tool.Error({ message: `Tool is not available for this request: ${event.tool}` })
               const name = requested?.name ?? event.tool
-              if (name === "execute" && codemodeTool)
-                return yield* executeTool(codemodeTool, name, event.input, context)
+              if (name === "execute" && codeModeTool)
+                return yield* executeTool(codeModeTool, name, event.input, context)
               const tool = direct.get(name)
               if (tool) return yield* executeTool(tool, name, event.input, context)
               return yield* new Tool.Error({ message: `Unknown tool: ${name}` })
@@ -269,8 +282,10 @@ function schemaMakeError(error: unknown) {
 
 function registrationError(tool: Tool.Info) {
   const namespace = tool.options?.namespace
-  if (namespace !== undefined && !namespace.split(".").every((segment) => /^[A-Za-z0-9_-]{1,64}$/.test(segment)))
-    return new RegistrationError({ name: namespace, message: `Invalid tool namespace: ${JSON.stringify(namespace)}` })
+  if (namespace !== undefined) {
+    const error = namespaceError(namespace)
+    if (error) return error
+  }
   const name = normalizedName(tool)
   if (!/^[A-Za-z0-9_-]{1,64}$/.test(name)) return new RegistrationError({ name, message: `Invalid tool name: ${name}` })
   const id = effectiveName(tool)
@@ -284,6 +299,11 @@ function registrationError(tool: Tool.Info) {
   return Result.isFailure(result) ? result.failure : undefined
 }
 
+function namespaceError(name: string) {
+  if (name.split(".").every((segment) => /^[A-Za-z0-9_-]{1,64}$/.test(segment))) return
+  return new RegistrationError({ name, message: `Invalid tool namespace: ${JSON.stringify(name)}` })
+}
+
 export const node = makeLocationNode({
   service: Service,
   layer,

packages/core/src/tool/AGENTS.md

@@ -32,6 +32,8 @@ Leaves own resolution, permission, and side-effect ordering. Translate only expe
 
 Built-ins, plugins, and MCP install tools through `Tool.Service.transform`, adding complete tool objects to the draft. A tool may provide a namespace, which flattens direct model names to `<namespace>_<tool>`, and defaults into CodeMode (`codemode` defaults true; `codemode: false` keeps the tool on the provider's native tool list).
 
+Namespace descriptions are registered once through `draft.namespace(...)`. Tool options continue to reference the namespace by string name; an unregistered namespace remains valid and simply has no namespace description.
+
 The service uses shared `State` to replay synchronous transforms in registration order against a fresh draft. `Tool.Service.reload()` rebuilds from captured source data without changing registration precedence. Registrations are scoped and return a real, idempotent `dispose` Effect:
 
 - The latest valid active registration for the same effective name wins.

packages/core/src/vcs.ts

@@ -82,7 +82,7 @@ const layer = Layer.effect(
     })
     const selected = () => {
       const value = state.get()
-      const id = value.selection ?? location.vcsBackend ?? vcs?.type
+      const id = value.selection ?? vcs?.type
       return id ? value.providers.get(id) : undefined
     }
     const protect = <A>(provider: VcsDefinition, operation: string, effect: Effect.Effect<A, unknown>, fallback: A) =>

packages/core/test/agent.test.ts

@@ -22,8 +22,8 @@ const globalLayer = Layer.succeed(Global.Service, Global.Service.of(global))
 
 const it = testEffect(
   AppNodeBuilder.build(LayerNode.group([Agent.node, Bus.node, Location.node]), [
-    [Global.node, globalLayer],
-    [Location.node, locationLayer],
+    Global.node.replace(globalLayer),
+    Location.node.replace(locationLayer),
   ]) as unknown as Layer.Layer<unknown, never>,
 )
 

packages/core/test/bus-session-routing.test.ts

@@ -21,7 +21,7 @@ import { testEffect } from "./lib/effect"
 
 const it = testEffect(
   AppNodeBuilder.build(LayerNode.group([Database.node, Bus.node, SessionProjector.node]), [
-    [Bus.node, Bus.configured({ persist: true })],
+    Bus.node.replace(Bus.configured({ persist: true })),
   ]),
 )
 const a = Location.Ref.make({ directory: AbsolutePath.make("/a") })

packages/core/test/bus.test.ts

@@ -100,12 +100,14 @@ const tail = (bus: Bus.Interface, input: { aggregateID: string; after?: number }
 
 const it = testEffect(
   AppNodeBuilder.build(LayerNode.group([Database.node, Bus.node, Location.node]), [
-    [Location.node, locationLayer],
-    [Bus.node, Bus.configured({ persist: true })],
+    Location.node.replace(locationLayer),
+    Bus.node.replace(Bus.configured({ persist: true })),
   ]),
 )
 const itWithoutLocation = testEffect(
-  AppNodeBuilder.build(LayerNode.group([Database.node, Bus.node]), [[Bus.node, Bus.configured({ persist: true })]]),
+  AppNodeBuilder.build(LayerNode.group([Database.node, Bus.node]), [
+    Bus.node.replace(Bus.configured({ persist: true })),
+  ]),
 )
 const itWithoutPersistence = testEffect(AppNodeBuilder.build(LayerNode.group([Database.node, Bus.node])))
 
@@ -631,8 +633,7 @@ describe("Bus", () => {
       const continueRead = yield* Deferred.make<void>()
       let pause = true
       const eventLayer = AppNodeBuilder.build(LayerNode.group([Database.node, Bus.node]), [
-        [
-          Bus.node,
+        Bus.node.replace(
           Bus.configured({
             persist: true,
             beforeAggregateRead: () =>
@@ -640,7 +641,7 @@ describe("Bus", () => {
                 ? Deferred.succeed(readStarted, undefined).pipe(Effect.andThen(Deferred.await(continueRead)))
                 : Effect.void,
           }),
-        ],
+        ),
       ])
 
       yield* Effect.gen(function* () {
@@ -1318,7 +1319,7 @@ describe("Bus", () => {
   it.effect("log replays across configured read pages", () =>
     Effect.gen(function* () {
       const eventLayer = AppNodeBuilder.build(LayerNode.group([Database.node, Bus.node]), [
-        [Bus.node, Bus.configured({ persist: true, logReadPageSize: 2 })],
+        Bus.node.replace(Bus.configured({ persist: true, logReadPageSize: 2 })),
       ])
 
       yield* Effect.gen(function* () {
@@ -1351,8 +1352,7 @@ describe("Bus", () => {
       const releaseRead = yield* Deferred.make<void>()
       const firstRead = yield* Ref.make(true)
       const eventLayer = AppNodeBuilder.build(LayerNode.group([Database.node, Bus.node]), [
-        [
-          Bus.node,
+        Bus.node.replace(
           Bus.configured({
             persist: true,
             beforeAggregateRead: () =>
@@ -1363,7 +1363,7 @@ describe("Bus", () => {
                 }),
               ),
           }),
-        ],
+        ),
       ])
 
       yield* Effect.gen(function* () {