refactor(browser): colocate the public API plugin

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

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/README.md

@@ -241,121 +241,14 @@ Constructing `stream()` or `generate()` does not record a request, invoke a resp
 Each execution does. An exhausted queue without a fallback defects immediately rather than waiting for a
 future reply.
 
-Generation responses remain canonical event arrays or arbitrary `Stream<LLMEvent, AIError>` values. The client consumes
+Responses remain canonical event arrays or arbitrary `Stream<LLMEvent, AIError>` values. The client consumes
 supplied streams directly, preserving failure identity, finalizers, incomplete output, and post-finish tails;
 it does not repair or truncate them.
 
-For explicit compaction, script a `CompactionResponse` through `push`, `always`, or `serve`. The client returns that replacement window directly, including retained user messages and usage, with the same lazy request recording and gates. Generation and compaction reject fixtures for the wrong operation instead of converting between response shapes.
-
 The published legacy `Service`, `layer`, `clientLayer`, and module-level controls remain available as adapters
 over the same implementation, including the legacy live `requests` array. New tests should use `Test` and
 `testLayer`.
 
-## Provider compaction
-
-Compaction is opt-in. The package supports automatic compaction in OpenAI/Azure Responses and Anthropic Messages (including Claude on Vertex and Bedrock Messages), and explicit compaction calls in OpenAI/Azure/xAI Responses. Model and deployment support still depends on the provider.
-
-This is different from prompt caching, server-side history storage, or truncation. Compaction returns provider-owned context that must be replayed to continue the conversation.
-
-### Automatic compaction
-
-Inside an `Effect.gen`, enable OpenAI compaction with typed provider options:
-
-```ts
-import { LLM, LLMClient, LLMRequest, Message } from "@opencode-ai/ai"
-import { OpenAI } from "@opencode-ai/ai/providers"
-
-const request = LLM.request({
-  model: OpenAI.configure({ apiKey }).responses("gpt-5.3-codex"),
-  messages,
-  providerOptions: {
-    contextManagement: [{ type: "compaction", compactThreshold: 200_000 }],
-  },
-})
-const response = yield * LLMClient.generate(request)
-const next = LLMRequest.update(request, {
-  messages: [...request.messages, response.message, Message.user("Continue")],
-})
-```
-
-`store: false` remains the default. Keep the entire `response.message`, not just `response.text`. Compaction events become ordered `CompactionPart`s alongside text and reasoning. The conversation contains everything needed to continue; there is no separate replay object or hidden provider transcript.
-
-A compaction part has `provider` and exactly one representation: `encrypted` for Responses, or `text` for Anthropic. Responses also preserves the optional checkpoint `id`. These fields survive message serialization without becoming visible assistant text. Sending a checkpoint to another provider or an incompatible API fails rather than silently losing context.
-
-```ts
-import { CompactionPart, ProviderID } from "@opencode-ai/ai"
-
-CompactionPart.make({ provider: ProviderID.make("openai"), id: "cmp_123", encrypted: "..." })
-CompactionPart.make({ provider: ProviderID.make("anthropic"), text: "Summary of the conversation..." })
-```
-
-For Anthropic, use:
-
-```ts
-providerOptions: {
-  contextManagement: {
-    edits: [{
-      type: "compact_20260112",
-      trigger: { type: "input_tokens", value: 150_000 },
-      pauseAfterCompaction: true,
-      instructions: "Summarize the task and decisions. Do not call tools while summarizing.",
-    }],
-  },
-}
-```
-
-- The trigger is optional (provider default: 150,000 tokens), with a minimum of 50,000.
-- Custom instructions replace Anthropic's default summarization instructions.
-- The route adds `compact-2026-01-12` to existing beta headers, including when replaying a checkpoint without enabling new compactions.
-- A pause is exposed as `response.finishReason.raw === "compaction"`. The caller explicitly issues the next request; the package never automatically resumes.
-- Anthropic can return a compaction block with `content: null` when summarization fails. This becomes a compaction part with `text: null`, which is **not** a successful replacement for prior history. The package never prunes history automatically.
-- `Usage` totals include all reported Anthropic `usage.iterations`, including compaction. `contextTokens` separately reports the final message iteration's inclusive input size, when available. A compaction-only pause does not report a post-compaction context size. Raw iteration usage remains in `providerMetadata`.
-
-Bedrock's Converse API does not support this feature. Select the native Claude Messages route explicitly; the default `.model(...)` remains Converse:
-
-```ts
-import { AmazonBedrock } from "@opencode-ai/ai/providers"
-
-const model = AmazonBedrock.configure({ region: "us-east-1", credentials }).messages("us.anthropic.claude-opus-4-6-v1")
-```
-
-The corresponding package entrypoint is `@opencode-ai/ai/providers/amazon-bedrock/messages`. It uses InvokeModelWithResponseStream, AWS event-stream framing, bearer or SigV4 auth, and `anthropic_beta` in the request body.
-
-### Explicit compaction
-
-`LLMClient.compact(request)` performs exactly one HTTP call to `/responses/compact`, using the selected route's endpoint, credentials, query, and HTTP middleware. It returns a `CompactionResponse` containing replacement `messages` and usage, not a normal generation response.
-
-The selected model carries explicit-compaction capability through request construction and updates. Calls using unsupported routes fail type checking. When the model is selected dynamically, narrow the request with `LLMClient.canCompact(request)` before calling `LLMClient.compact`; a model or route switch does not inherit the old capability. Runtime validation still rejects unsupported calls from untyped consumers. Capability describes the route's API, not whether every model or custom deployment supports the operation.
-
-```ts
-const compacted = yield * LLMClient.compact(request)
-const next = LLMRequest.update(request, {
-  messages: [...compacted.messages, Message.user("Continue")],
-})
-const response = yield * LLMClient.generate(next)
-```
-
-Replace the prior window with `compacted.messages`. Do not append it to the original transcript or extract only the encrypted item: the provider may retain additional messages in its output. Retained user and assistant messages remain ordinary messages with typed text, media, or reasoning parts, in their original order. Provider-specific message IDs, status, and phase use `providerMetadata`, not a raw output array hidden in an assistant message. Unsupported returned item types fail explicitly. Generation-only body overlays such as `stream` and `store` are not sent to the compact endpoint.
-
-Supported compact controls such as service tier and prompt-cache settings preserve request defaults and HTTP-overlay precedence. Retained image and file detail settings survive serialization and replay.
-
-The input must still fit the model's context window. Explicit compaction is not an overflow-recovery operation. xAI supports this explicit path, not the automatic OpenAI option. Unsupported routes, including Bedrock Mantle, do not inherit an explicit compact endpoint simply because they use a Responses protocol.
-
-### Ownership and verification
-
-The AI package transports options and typed conversation parts. It does not schedule compaction, persist Session checkpoints, select history, switch providers, or replace Core's existing local compaction policy. Native compaction is not enabled for OpenCode Sessions by this feature; Session integration must persist these parts before enabling it. The AI SDK bridge rejects native compaction parts rather than dropping them. Provider-executed tool APIs and persistence changes are a separate follow-up.
-
-Tests cover serialized round trips, real local HTTP plus a tool loop, AWS binary frames and signing, provider errors, malformed blocks, and usage accounting. Live provider tests are gated by `RECORD=true` and the relevant API keys:
-
-```sh
-# Run from packages/ai. Only records the selected new cassette group.
-RECORD=true RECORDED_PREFIX=openai-compaction bun test test/provider/compaction.recorded.test.ts
-RECORD=true RECORDED_PREFIX=xai-compaction bun test test/provider/compaction.recorded.test.ts
-RECORD=true RECORDED_PREFIX=anthropic-compaction bun test test/provider/compaction.recorded.test.ts
-```
-
-Provider references: [OpenAI](https://developers.openai.com/api/docs/guides/compaction), [Azure](https://learn.microsoft.com/en-us/azure/foundry/openai/how-to/responses#server-side-compaction), [Anthropic](https://platform.claude.com/docs/en/build-with-claude/compaction), [Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/claude-messages-compaction.html), [xAI](https://docs.x.ai/developers/advanced-api-usage/context-compaction).
-
 ## Caching
 
 Prompt caching is **on by default**. Every `LLMRequest` resolves to `cache: "auto"` unless the caller opts out with `cache: "none"`. Each protocol translates `CacheHint`s to its wire format (`cache_control` on Anthropic, `cachePoint` on Bedrock; OpenAI and Gemini do implicit caching server-side and don't need inline markers — auto is a no-op there).

packages/ai/src/cache-policy.ts

@@ -40,7 +40,6 @@ const RESPECTS_INLINE_HINTS = new Set([
   "anthropic-messages",
   "google-vertex-messages",
   "bedrock-converse",
-  "bedrock-messages",
   "openrouter",
 ])
 

packages/ai/src/protocols/anthropic-messages.ts

@@ -6,12 +6,8 @@ import { Auth } from "../route/auth.js"
 import { Endpoint } from "../route/endpoint.js"
 import { Framing } from "../route/framing.js"
 import { Protocol } from "../route/protocol.js"
-import { Headers } from "effect/unstable/http"
-import { HttpTransport } from "../route/transport/index.js"
 import {
   AIError,
-  HttpOptions,
-  LLMRequest,
   LLMEvent,
   mergeJsonRecords,
   Usage,
@@ -19,6 +15,7 @@ import {
   type FinishReasonDetails,
   type FinishReason,
   type JsonSchema,
+  type LLMRequest,
   type MediaPart,
   type ProviderMetadata,
   type ToolCallPart,
@@ -64,7 +61,6 @@ export type ThinkingInput =
     ))
 
 export interface OptionsInput {
-  readonly contextManagement?: ContextManagement
   readonly [key: string]: unknown
   readonly thinking?: ThinkingInput
   readonly effort?: string
@@ -93,23 +89,6 @@ export interface OptionsInput {
 
 export type ProviderOptionsInput = OptionsInput
 
-export const ContextManagement = Schema.Struct({
-  edits: Schema.Array(
-    Schema.Struct({
-      type: Schema.Literal("compact_20260112"),
-      trigger: Schema.optional(
-        Schema.Struct({
-          type: Schema.Literal("input_tokens"),
-          value: Schema.Int.check(Schema.isGreaterThanOrEqualTo(50000)),
-        }),
-      ),
-      pauseAfterCompaction: Schema.optional(Schema.Boolean),
-      instructions: Schema.optional(Schema.String),
-    }),
-  ),
-})
-export type ContextManagement = typeof ContextManagement.Type
-
 // =============================================================================
 // Request Body Schema
 // =============================================================================
@@ -257,12 +236,7 @@ const AnthropicUserBlock = Schema.Union([
   AnthropicToolResultBlock,
 ])
 type AnthropicUserBlock = Schema.Schema.Type<typeof AnthropicUserBlock>
-const AnthropicCompactionBlock = Schema.Struct({
-  type: Schema.Literal("compaction"),
-  content: Schema.NullOr(Schema.String),
-})
 const AnthropicAssistantBlock = Schema.Union([
-  AnthropicCompactionBlock,
   AnthropicTextBlock,
   AnthropicThinkingBlock,
   AnthropicRedactedThinkingBlock,
@@ -338,18 +312,6 @@ const AnthropicContainer = Schema.Union([
 ])
 
 const AnthropicBodyFields = {
-  context_management: Schema.optional(
-    Schema.Struct({
-      edits: Schema.Array(
-        Schema.Struct({
-          type: Schema.Literal("compact_20260112"),
-          trigger: ContextManagement.fields.edits.value.fields.trigger,
-          pause_after_compaction: Schema.optional(Schema.Boolean),
-          instructions: Schema.optional(Schema.String),
-        }),
-      ),
-    }),
-  ),
   model: Schema.String,
   system: optionalArray(AnthropicTextBlock),
   messages: Schema.Array(AnthropicMessage),
@@ -373,7 +335,7 @@ const AnthropicBodyFields = {
 export const AnthropicMessagesBody = Schema.Struct(AnthropicBodyFields)
 export type AnthropicMessagesBody = Schema.Schema.Type<typeof AnthropicMessagesBody>
 
-const AnthropicIterationUsage = Schema.StructWithRest(
+const AnthropicUsage = Schema.StructWithRest(
   Schema.Struct({
     input_tokens: optionalNull(Schema.Number),
     output_tokens: Schema.optional(Schema.Number),
@@ -392,13 +354,6 @@ const AnthropicIterationUsage = Schema.StructWithRest(
   }),
   [Schema.Record(Schema.String, Schema.Unknown)],
 )
-const AnthropicUsage = Schema.StructWithRest(
-  Schema.Struct({
-    ...AnthropicIterationUsage.schema.fields,
-    iterations: Schema.optional(Schema.Array(AnthropicIterationUsage)),
-  }),
-  [JsonObject],
-)
 type AnthropicUsage = Schema.Schema.Type<typeof AnthropicUsage>
 
 const AnthropicStreamBlock = Schema.Struct({
@@ -422,7 +377,6 @@ type AnthropicStreamBlock = Schema.Schema.Type<typeof AnthropicStreamBlock>
 const decodeAnthropicStreamBlock = Schema.decodeUnknownOption(AnthropicStreamBlock)
 
 const AnthropicStreamDelta = Schema.Struct({
-  content: optionalNull(Schema.String),
   type: Schema.optional(Schema.String),
   text: Schema.optional(Schema.String),
   thinking: Schema.optional(Schema.String),
@@ -452,8 +406,6 @@ const AnthropicEvent = Schema.Struct({
 type AnthropicEvent = Schema.Schema.Type<typeof AnthropicEvent>
 
 interface ParserState {
-  readonly provider: LLMRequest["model"]["provider"]
-  readonly compactions: Readonly<Record<number, string | null>>
   readonly providerMetadataKey: string
   readonly tools: ToolStream.State<number>
   readonly reasoningSignatures: Readonly<Record<number, string>>
@@ -896,12 +848,6 @@ const lowerMessages = Effect.fn("AnthropicMessages.lowerMessages")(function* (
     if (message.role === "assistant") {
       const content: AnthropicAssistantBlock[] = []
       for (const part of message.content) {
-        if (part.type === "compaction") {
-          if (part.provider !== request.model.provider || part.text === undefined)
-            return yield* invalid("Compaction state must be replayed to its originating provider and API")
-          content.push({ type: "compaction", content: part.text })
-          continue
-        }
         if (part.type === "text") {
           if (part.text.trim().length === 0) continue
           content.push({ type: "text", text: part.text, cache_control: cacheControl(breakpoints, part.cache) })
@@ -1057,9 +1003,6 @@ const resolveThinking = Effect.fn("AnthropicMessages.resolveThinking")(function*
 })
 
 const fromRequest = Effect.fn("AnthropicMessages.fromRequest")(function* (request: LLMRequest) {
-  const management = yield* ProviderShared.validateWith(
-    Schema.decodeUnknownEffect(Schema.UndefinedOr(ContextManagement)),
-  )(request.providerOptions?.contextManagement)
   const generation = request.generation
   const toolSchemaCompatibility = request.model.compatibility?.toolSchema
   // Allocate the 4-breakpoint budget in invalidation order: tools → system →
@@ -1094,7 +1037,7 @@ const fromRequest = Effect.fn("AnthropicMessages.fromRequest")(function* (reques
     )
   }
   const options = yield* resolveOptions(request)
-  const body = {
+  return {
     model: request.model.id,
     system,
     messages,
@@ -1115,18 +1058,6 @@ const fromRequest = Effect.fn("AnthropicMessages.fromRequest")(function* (reques
     metadata: options.metadata,
     service_tier: options.service_tier,
   }
-  if (!management) return body
-  return {
-    ...body,
-    context_management: {
-      edits: management.edits.map((edit) => ({
-        type: edit.type,
-        trigger: edit.trigger,
-        pause_after_compaction: edit.pauseAfterCompaction,
-        instructions: edit.instructions,
-      })),
-    },
-  }
 })
 
 // =============================================================================
@@ -1148,31 +1079,18 @@ const mapFinishReason = (reason: string | null | undefined): FinishReason => {
 // expose that subset through `output_tokens_details.thinking_tokens`.
 const mapUsage = (usage: AnthropicUsage | undefined, providerMetadataKey: string): Usage | undefined => {
   if (!usage) return undefined
-  const iterations = usage.iterations?.length ? usage.iterations : [usage]
-  const last = usage.iterations?.at(-1)
-  const nonCached = ProviderShared.sumTokens(...iterations.map((item) => item.input_tokens ?? undefined))
-  const cacheRead = ProviderShared.sumTokens(...iterations.map((item) => item.cache_read_input_tokens ?? undefined))
-  const cacheWrite = ProviderShared.sumTokens(
-    ...iterations.map((item) => item.cache_creation_input_tokens ?? undefined),
-  )
+  const nonCached = usage.input_tokens ?? undefined
+  const cacheRead = usage.cache_read_input_tokens ?? undefined
+  const cacheWrite = usage.cache_creation_input_tokens ?? undefined
   const inputTokens = ProviderShared.sumTokens(nonCached, cacheRead, cacheWrite)
-  const outputTokens = ProviderShared.sumTokens(...iterations.map((item) => item.output_tokens))
   return new Usage({
     inputTokens,
-    outputTokens,
-    contextTokens:
-      last?.type === "message"
-        ? ProviderShared.sumTokens(
-            last.input_tokens ?? undefined,
-            last.cache_read_input_tokens ?? undefined,
-            last.cache_creation_input_tokens ?? undefined,
-          )
-        : undefined,
+    outputTokens: usage.output_tokens,
     nonCachedInputTokens: nonCached,
     cacheReadInputTokens: cacheRead,
     cacheWriteInputTokens: cacheWrite,
-    reasoningTokens: ProviderShared.sumTokens(...iterations.map((item) => item.output_tokens_details?.thinking_tokens)),
-    totalTokens: ProviderShared.totalTokens(inputTokens, outputTokens, undefined),
+    reasoningTokens: usage.output_tokens_details?.thinking_tokens,
+    totalTokens: ProviderShared.totalTokens(inputTokens, usage.output_tokens, undefined),
     providerMetadata: { [providerMetadataKey]: usage },
   })
 }
@@ -1194,7 +1112,6 @@ const mergeUsage = (left: Usage | undefined, right: Usage | undefined, providerM
   return new Usage({
     inputTokens,
     outputTokens,
-    contextTokens: right.contextTokens ?? left.contextTokens,
     nonCachedInputTokens,
     cacheReadInputTokens,
     cacheWriteInputTokens,
@@ -1253,6 +1170,7 @@ const onContentBlockStart = (
   event: AnthropicEvent & { readonly content_block: AnthropicStreamBlock },
 ): StepResult => {
   const block = event.content_block
+  if (!block) return [state, NO_EVENTS]
 
   if (block.type === "tool_use" || block.type === "server_tool_use") {
     if (event.index === undefined || !block.id) return [state, NO_EVENTS]
@@ -1347,16 +1265,7 @@ const onContentBlockDelta = Effect.fn("AnthropicMessages.onContentBlockDelta")(f
 ) {
   const delta = event.delta
 
-  if (delta.type === "compaction_delta") {
-    if (event.index === undefined || !(event.index in state.compactions) || delta.content === undefined)
-      return yield* ProviderShared.eventError(ADAPTER, "Compaction delta is missing its block or content")
-    return [
-      { ...state, compactions: { ...state.compactions, [event.index]: delta.content } },
-      NO_EVENTS,
-    ] satisfies StepResult
-  }
-
-  if (delta.type === "text_delta" && delta.text) {
+  if (delta?.type === "text_delta" && delta.text) {
     if (!state.lifecycle.text.has(`text-${event.index ?? 0}`)) return [state, NO_EVENTS] satisfies StepResult
     const events: LLMEvent[] = []
     return [
@@ -1365,7 +1274,7 @@ const onContentBlockDelta = Effect.fn("AnthropicMessages.onContentBlockDelta")(f
     ] satisfies StepResult
   }
 
-  if (delta.type === "thinking_delta" && delta.thinking) {
+  if (delta?.type === "thinking_delta" && delta.thinking) {
     if (!state.lifecycle.reasoning.has(`reasoning-${event.index ?? 0}`)) return [state, NO_EVENTS] satisfies StepResult
     const events: LLMEvent[] = []
     return [
@@ -1377,7 +1286,7 @@ const onContentBlockDelta = Effect.fn("AnthropicMessages.onContentBlockDelta")(f
     ] satisfies StepResult
   }
 
-  if (delta.type === "signature_delta" && delta.signature) {
+  if (delta?.type === "signature_delta" && delta.signature) {
     const index = event.index ?? 0
     if (!state.lifecycle.reasoning.has(`reasoning-${index}`)) return [state, NO_EVENTS] satisfies StepResult
     return [
@@ -1389,7 +1298,7 @@ const onContentBlockDelta = Effect.fn("AnthropicMessages.onContentBlockDelta")(f
     ] satisfies StepResult
   }
 
-  if (delta.type === "input_json_delta" && event.index !== undefined) {
+  if (delta?.type === "input_json_delta" && event.index !== undefined) {
     if (!delta.partial_json) return [state, NO_EVENTS] satisfies StepResult
     if (!state.tools[event.index]) return [state, NO_EVENTS] satisfies StepResult
     const result = ToolStream.appendExisting(
@@ -1414,18 +1323,6 @@ const onContentBlockStop = Effect.fn("AnthropicMessages.onContentBlockStop")(fun
   event: AnthropicEvent,
 ) {
   if (event.index === undefined) return [state, NO_EVENTS] satisfies StepResult
-  if (event.index in state.compactions) {
-    const { [event.index]: content, ...compactions } = state.compactions
-    const events: LLMEvent[] = []
-    const lifecycle = Lifecycle.stepStart(state.lifecycle, events)
-    events.push(
-      LLMEvent.compaction({
-        provider: state.provider,
-        text: content,
-      }),
-    )
-    return [{ ...state, compactions, lifecycle }, events] satisfies StepResult
-  }
   const result = yield* ToolStream.finish(ADAPTER, state.tools, event.index)
   const events: LLMEvent[] = []
   const resultEvents = result.events ?? []
@@ -1477,8 +1374,6 @@ const onMessageDelta = (
 }
 
 const onMessageStop = Effect.fn("AnthropicMessages.onMessageStop")(function* (state: ParserState) {
-  if (Object.keys(state.compactions).length)
-    return yield* ProviderShared.eventError(ADAPTER, "Response ended with an incomplete compaction block")
   const result = yield* ToolStream.finishAll(ADAPTER, state.tools)
   const events: LLMEvent[] = []
   const lifecycle = result.events.length ? Lifecycle.stepStart(state.lifecycle, events) : state.lifecycle
@@ -1523,21 +1418,16 @@ const onError = (event: AnthropicEvent) => {
   )
 }
 
-const STREAM_BLOCK_TYPES = new Set([
-  "compaction",
-  "text",
-  "thinking",
-  "redacted_thinking",
-  "tool_use",
-  "server_tool_use",
-])
-const STREAM_DELTA_TYPES = new Set([
-  "compaction_delta",
-  "text_delta",
-  "thinking_delta",
-  "signature_delta",
-  "input_json_delta",
-])
+const isKnownStreamBlockType = (type: string) =>
+  type === "text" ||
+  type === "thinking" ||
+  type === "redacted_thinking" ||
+  type === "tool_use" ||
+  type === "server_tool_use" ||
+  isServerToolResultType(type)
+
+const isKnownStreamDeltaType = (type: string) =>
+  type === "text_delta" || type === "thinking_delta" || type === "signature_delta" || type === "input_json_delta"
 
 const invalidStreamEvent = (event: AnthropicEvent) =>
   Effect.fail(
@@ -1566,16 +1456,7 @@ const step = (state: ParserState, event: AnthropicEvent) => {
   if (event.type === "content_block_start") {
     if (!ProviderShared.isRecord(event.content_block) || typeof event.content_block.type !== "string")
       return invalidStreamEvent(event)
-    if (event.content_block.type === "compaction") {
-      const decoded = Schema.decodeUnknownOption(AnthropicCompactionBlock)(event.content_block)
-      if (event.index === undefined || Option.isNone(decoded)) return invalidStreamEvent(event)
-      return Effect.succeed<StepResult>([
-        { ...state, compactions: { ...state.compactions, [event.index]: decoded.value.content } },
-        NO_EVENTS,
-      ])
-    }
-    if (!STREAM_BLOCK_TYPES.has(event.content_block.type) && !isServerToolResultType(event.content_block.type))
-      return Effect.succeed<StepResult>([state, NO_EVENTS])
+    if (!isKnownStreamBlockType(event.content_block.type)) return Effect.succeed<StepResult>([state, NO_EVENTS])
     const decoded = decodeAnthropicStreamBlock(event.content_block)
     if (Option.isNone(decoded)) return invalidStreamEvent(event)
     const block = decoded.value
@@ -1589,7 +1470,7 @@ const step = (state: ParserState, event: AnthropicEvent) => {
   }
   if (event.type === "content_block_delta") {
     if (!ProviderShared.isRecord(event.delta)) return invalidStreamEvent(event)
-    if (typeof event.delta.type === "string" && !STREAM_DELTA_TYPES.has(event.delta.type))
+    if (typeof event.delta.type === "string" && !isKnownStreamDeltaType(event.delta.type))
       return Effect.succeed<StepResult>([state, NO_EVENTS])
     const decoded = decodeAnthropicStreamDelta(event.delta)
     if (Option.isNone(decoded)) return invalidStreamEvent(event)
@@ -1623,8 +1504,6 @@ export const protocol = Protocol.make({
   stream: {
     event: Protocol.jsonEvent(AnthropicEvent),
     initial: (request) => ({
-      provider: request.model.provider,
-      compactions: {},
       providerMetadataKey: request.model.route.providerMetadataKey ?? String(request.model.provider),
       tools: ToolStream.empty<number>(),
       reasoningSignatures: {},
@@ -1634,37 +1513,6 @@ export const protocol = Protocol.make({
   },
 })
 
-export const transport = <Body extends Pick<AnthropicMessagesBody, "messages" | "context_management">>() => {
-  const http = HttpTransport.httpJson<Body, string>({ framing })
-  return {
-    ...http,
-    prepare: (input: Parameters<typeof http.prepare>[0]) => {
-      if (
-        !input.body.context_management?.edits.length &&
-        !input.body.messages.some((message) => message.content.some((block) => block.type === "compaction"))
-      )
-        return http.prepare(input)
-      const headers = Headers.fromInput(input.request.http?.headers)
-      const betas = new Set(
-        (headers["anthropic-beta"] ?? "")
-          .split(",")
-          .map((item) => item.trim())
-          .filter(Boolean),
-      )
-      betas.add("compact-2026-01-12")
-      return http.prepare({
-        ...input,
-        request: LLMRequest.update(input.request, {
-          http: new HttpOptions({
-            ...input.request.http,
-            headers: { ...headers, "anthropic-beta": [...betas].join(",") },
-          }),
-        }),
-      })
-    },
-  }
-}
-
 export const route = Route.make({
   id: ADAPTER,
   provider: "anthropic",
@@ -1674,7 +1522,7 @@ export const route = Route.make({
     baseURL: DEFAULT_BASE_URL,
   }),
   auth: Auth.none,
-  transport: transport<AnthropicMessagesBody>(),
+  framing,
   headers: () => ({ "anthropic-version": "2023-06-01" }),
 })
 

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/bedrock-messages.ts

@@ -1,121 +0,0 @@
-import { Effect, Encoding, Schema, Struct } from "effect"
-import { Headers } from "effect/unstable/http"
-import { AIError } from "../schema/index.js"
-import { Route } from "../route/client.js"
-import { Endpoint } from "../route/endpoint.js"
-import { Protocol } from "../route/protocol.js"
-import { classifyProviderFailure } from "../provider-error.js"
-import { AnthropicMessages } from "./anthropic-messages.js"
-import { BedrockEventStream } from "./bedrock-event-stream.js"
-import { BedrockAuth } from "./utils/bedrock-auth.js"
-import { JsonObject, ProviderShared } from "./shared.js"
-
-const ID = "bedrock-messages"
-const VERSION = "bedrock-2023-05-31"
-const Body = Schema.Struct({
-  ...Struct.omit(AnthropicMessages.AnthropicMessagesBody.fields, ["model", "stream"]),
-  anthropic_version: Schema.Literal(VERSION),
-  anthropic_beta: Schema.optional(Schema.Array(Schema.String)),
-}).check(
-  Schema.makeFilter(
-    (body) =>
-      body.messages.flatMap((message) => message.content.map(mediaIssue)).find((issue) => issue !== undefined) ?? true,
-  ),
-)
-const Event = Schema.Struct({
-  chunk: Schema.optional(Schema.Struct({ bytes: Schema.String })),
-  exception: Schema.optional(
-    Schema.Struct({
-      type: Schema.String,
-      details: Schema.StructWithRest(
-        Schema.Struct({ message: Schema.optional(Schema.String), originalMessage: Schema.optional(Schema.String) }),
-        [JsonObject],
-      ),
-    }),
-  ),
-})
-
-export const protocol = Protocol.make({
-  id: ID,
-  body: {
-    schema: Body,
-    from: Effect.fn("BedrockMessages.fromRequest")(function* (request) {
-      const body = yield* AnthropicMessages.protocol.body.from(request)
-      const headers = Headers.fromInput(request.http?.headers)
-      const betas = new Set(
-        (headers["anthropic-beta"] ?? "")
-          .split(",")
-          .map((value) => value.trim())
-          .filter(Boolean),
-      )
-      if (
-        body.context_management?.edits.length ||
-        body.messages.some((message) => message.content.some((block) => block.type === "compaction"))
-      )
-        betas.add("compact-2026-01-12")
-      return {
-        ...Struct.omit(body, ["model", "stream"]),
-        anthropic_version: VERSION,
-        anthropic_beta: betas.size ? [...betas] : undefined,
-      } satisfies typeof Body.Type
-    }),
-  },
-  stream: {
-    event: Event,
-    initial: AnthropicMessages.protocol.stream.initial,
-    step: Effect.fn("BedrockMessages.step")(function* (state, event) {
-      if (event.exception)
-        return yield* new AIError({
-          reason: classifyProviderFailure({
-            message: event.exception.details.message ?? event.exception.details.originalMessage ?? event.exception.type,
-            rawBody: ProviderShared.encodeJson(event),
-          }),
-        })
-      if (!event.chunk) return yield* ProviderShared.eventError(ID, "Bedrock Messages event is missing its chunk")
-      const text = yield* Effect.fromResult(Encoding.decodeBase64String(event.chunk.bytes)).pipe(
-        Effect.mapError((cause) =>
-          ProviderShared.eventError(ID, "Invalid Bedrock Messages chunk encoding", undefined, cause),
-        ),
-      )
-      const decoded = yield* Schema.decodeUnknownEffect(AnthropicMessages.protocol.stream.event)(text).pipe(
-        Effect.mapError((cause) => ProviderShared.eventError(ID, "Invalid Bedrock Messages event", undefined, cause)),
-      )
-      return yield* AnthropicMessages.protocol.stream.step(state, decoded)
-    }),
-  },
-})
-
-function mediaIssue(
-  block: AnthropicMessages.AnthropicMessagesBody["messages"][number]["content"][number],
-): string | undefined {
-  if (block.type === "tool_result")
-    return typeof block.content === "string"
-      ? undefined
-      : block.content.map(mediaIssue).find((issue) => issue !== undefined)
-  if (block.type !== "image" && block.type !== "document") return undefined
-  if (block.source.type === "url" || block.source.type === "file")
-    return "Bedrock Messages does not support URL or file-ID media sources"
-  if (
-    block.type === "image" &&
-    !["image/jpeg", "image/png", "image/webp", "image/gif"].includes(block.source.media_type)
-  )
-    return "Bedrock Messages requires a JPEG, PNG, WebP, or GIF image"
-  if (block.source.type === "base64" && Encoding.decodeBase64(block.source.data)._tag === "Failure")
-    return "Bedrock Messages media data must be valid base64"
-  return undefined
-}
-
-export const route = Route.make({
-  id: ID,
-  provider: "amazon-bedrock",
-  providerMetadataKey: "anthropic",
-  protocol,
-  endpoint: Endpoint.path(
-    ({ request }) => `/model/${encodeURIComponent(request.model.id)}/invoke-with-response-stream`,
-    { baseURL: "https://bedrock-runtime.us-east-1.amazonaws.com" },
-  ),
-  auth: BedrockAuth.auth,
-  framing: BedrockEventStream.framing(ID),
-})
-
-export * as BedrockMessages from "./bedrock-messages.js"

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/index.ts

@@ -1,6 +1,5 @@
 export * as AnthropicMessages from "./anthropic-messages.js"
 export * as BedrockConverse from "./bedrock-converse.js"
-export { BedrockMessages } from "./bedrock-messages.js"
 export * as Gemini from "./gemini.js"
 export * as MistralChat from "./mistral-chat.js"
 export * as OpenAIChat from "./openai-chat.js"

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

@@ -32,19 +32,17 @@ export const PATH = "/responses"
 // =============================================================================
 // Request Body Schema
 // =============================================================================
-export const OpenResponsesInputText = Schema.Struct({
+const OpenResponsesInputText = Schema.Struct({
   type: Schema.tag("input_text"),
   text: Schema.String,
 })
-export const OpenResponsesInputImage = Schema.Struct({
+const OpenResponsesInputImage = Schema.Struct({
   type: Schema.tag("input_image"),
   image_url: Schema.String,
-  detail: Schema.optional(Schema.String),
 })
-export const OpenResponsesInputFile = Schema.Struct({
+const OpenResponsesInputFile = Schema.Struct({
   type: Schema.tag("input_file"),
   filename: Schema.String,
-  detail: Schema.optional(Schema.String),
   file_data: Schema.optional(Schema.String),
   file_url: Schema.optional(Schema.String),
 })
@@ -56,7 +54,7 @@ const MediaInput = Schema.Union([OpenResponsesInputImage, OpenResponsesInputFile
 export type MediaInput = Schema.Schema.Type<typeof MediaInput>
 const OpenResponsesInputContent = Schema.Union([OpenResponsesInputText, MediaInput])
 
-export const OpenResponsesOutputText = Schema.Struct({
+const OpenResponsesOutputText = Schema.Struct({
   type: Schema.tag("output_text"),
   text: Schema.String,
 })
@@ -64,13 +62,6 @@ export const OpenResponsesOutputText = Schema.Struct({
 export const MessagePhase = Schema.NullOr(Schema.Literals(["commentary", "final_answer"]))
 type MessagePhase = Schema.Schema.Type<typeof MessagePhase>
 
-export const MessageMetadata = Schema.Struct({
-  itemId: Schema.optional(Schema.String),
-  type: Schema.optional(Schema.Literal("message")),
-  status: Schema.optional(Schema.String),
-  phase: Schema.optional(MessagePhase),
-})
-
 const messagePhase = (value: unknown): MessagePhase | undefined => {
   if (value === null || value === "commentary" || value === "final_answer") return value
   return undefined
@@ -81,7 +72,7 @@ const OpenResponsesReasoningSummaryText = Schema.Struct({
   text: Schema.String,
 })
 
-export const OpenResponsesReasoningItem = Schema.Struct({
+const OpenResponsesReasoningItem = Schema.Struct({
   type: Schema.tag("reasoning"),
   id: Schema.optionalKey(Schema.String),
   summary: Schema.Array(OpenResponsesReasoningSummaryText),
@@ -158,30 +149,16 @@ const OpenResponsesFunctionCallOutput = Schema.Union([
   Schema.Array(OpenResponsesFunctionCallOutputContent),
 ])
 
-export const CompactionItem = Schema.Struct({
-  type: Schema.Literal("compaction"),
-  id: optionalNull(Schema.String),
-  encrypted_content: Schema.String,
-})
-
 export const InputItem = Schema.Union([
-  CompactionItem,
   Schema.Struct({ role: Schema.tag("system"), content: Schema.String }),
   Schema.Struct({ role: Schema.tag("developer"), content: Schema.String }),
-  Schema.Struct({
-    role: Schema.tag("user"),
-    content: Schema.Array(OpenResponsesInputContent),
-    type: Schema.optional(Schema.Literal("message")),
-    id: Schema.optional(Schema.String),
-    status: Schema.optional(Schema.String),
-  }),
+  Schema.Struct({ role: Schema.tag("user"), content: Schema.Array(OpenResponsesInputContent) }),
   Schema.Struct({
     type: Schema.tag("message"),
     id: Schema.optionalKey(Schema.String),
     role: Schema.tag("assistant"),
     content: Schema.Array(OpenResponsesOutputText),
     phase: Schema.optionalKey(MessagePhase),
-    status: Schema.optional(Schema.String),
   }),
   OpenResponsesReasoningItem,
   Schema.Struct({
@@ -199,14 +176,14 @@ 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
   | {
       readonly type: "message"
       readonly id?: string
@@ -290,7 +267,7 @@ const OpenResponsesBody = Schema.Struct({
 })
 export type OpenResponsesBody = Schema.Schema.Type<typeof OpenResponsesBody>
 
-export const OpenResponsesUsage = Schema.Struct({
+const OpenResponsesUsage = Schema.Struct({
   input_tokens: Schema.optional(Schema.Number),
   input_tokens_details: optionalNull(
     Schema.Struct({
@@ -396,7 +373,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: {
@@ -404,14 +381,12 @@ export interface Extension {
     readonly media: ProviderShared.NormalizedMedia
     readonly request: LLMRequest
   }) => MediaInput | undefined
-  readonly lowerHostedToolItem?: (item: unknown) => ExtendedHostedToolItem | undefined
+  readonly restoreHostedToolItem?: (item: unknown) => HostedToolReplayItem | undefined
 }
 
-const BASE: Extension = { id: ADAPTER, name: NAME }
+const BASE_ADAPTER: ProviderAdapter = { id: ADAPTER, name: NAME }
 
 export interface ParserState {
-  readonly provider: LLMRequest["model"]["provider"]
-  readonly completedCompactions: ReadonlySet<string>
   readonly id: string
   readonly name: string
   readonly providerMetadataKey: string
@@ -422,6 +397,9 @@ 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>>
 }
 
@@ -507,15 +485,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 detail = yield* ProviderShared.validateWith(Schema.decodeUnknownEffect(OpenResponsesInputImage.fields.detail))(
-    part.providerMetadata?.[metadataKey(request.model)]?.detail,
-  )
+  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
@@ -526,31 +501,26 @@ const lowerMedia = Effect.fn("OpenResponses.lowerMedia")(function* (
     return {
       type: "input_file" as const,
       filename: part.filename ?? (media.mime === "application/pdf" ? "document.pdf" : "file"),
-      detail,
       ...(url ? { file_url: url } : { file_data: media.dataUrl }),
     }
   }
-  return {
-    type: "input_image" as const,
-    image_url: url ?? media.dataUrl,
-    detail,
-  }
+  return { type: "input_image" as const, image_url: url ?? media.dataUrl }
 })
 
 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
 })
 
@@ -559,13 +529,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",
   )
 })
@@ -573,49 +543,48 @@ 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 = metadataKey(request.model)
+  const providerMetadataKey = request.model.route.providerMetadataKey ?? "openresponses"
 
   for (const message of request.messages) {
-    const metadata = yield* ProviderShared.validateWith(
-      Schema.decodeUnknownEffect(Schema.UndefinedOr(MessageMetadata)),
-    )(message.providerMetadata?.[providerMetadataKey])
     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))
-      if (content.length > 0)
-        input.push({ role: "user", content, type: metadata?.type, id: metadata?.itemId, status: metadata?.status })
+      const content = yield* Effect.forEach(message.content, (part) => lowerUserContent(part, request, adapter))
+      if (content.length > 0) input.push({ role: "user", content })
       continue
     }
 
@@ -628,10 +597,9 @@ const lowerMessages = Effect.fn("OpenResponses.lowerMessages")(function* (reques
         const groups = content.reduce<
           Array<{ id: string | undefined; phase: MessagePhase | null | undefined; parts: TextPart[] }>
         >((groups, part) => {
-          const partMetadata = part.providerMetadata?.[providerMetadataKey]
-          const id = itemID(part.providerMetadata, providerMetadataKey) ?? metadata?.itemId
-          const partPhase = messagePhase(partMetadata?.phase)
-          const phase = partPhase === undefined ? metadata?.phase : partPhase
+          const metadata = part.providerMetadata?.[providerMetadataKey]
+          const id = itemID(part.providerMetadata, providerMetadataKey)
+          const phase = ProviderShared.isRecord(metadata) ? messagePhase(metadata.phase) : undefined
           const group = groups.at(-1)
           if (group && group.id === id && group.phase === phase) group.parts.push(part)
           else groups.push({ id, phase, parts: [part] })
@@ -642,7 +610,6 @@ const lowerMessages = Effect.fn("OpenResponses.lowerMessages")(function* (reques
             type: "message" as const,
             ...(group.id === undefined ? {} : { id: group.id }),
             role: "assistant" as const,
-            status: metadata?.status,
             content: group.parts.map((part) => ({ type: "output_text" as const, text: part.text })),
             ...(group.phase === undefined ? {} : { phase: group.phase }),
           })),
@@ -650,15 +617,6 @@ const lowerMessages = Effect.fn("OpenResponses.lowerMessages")(function* (reques
         content.splice(0, content.length)
       }
       for (const part of message.content) {
-        if (part.type === "compaction") {
-          flushText()
-          if (part.provider !== request.model.provider || part.encrypted === undefined)
-            return yield* ProviderShared.invalidRequest(
-              "Compaction state must be replayed to its originating provider and API",
-            )
-          input.push({ type: "compaction", id: part.id, encrypted_content: part.encrypted })
-          continue
-        }
         if (part.type === "text") {
           content.push(part)
           continue
@@ -692,7 +650,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)
@@ -706,13 +664,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",
@@ -725,11 +681,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),
       })
     }
   }
@@ -737,30 +693,13 @@ const lowerMessages = Effect.fn("OpenResponses.lowerMessages")(function* (reques
   return input
 })
 
-export const lowerConversation = Effect.fn("OpenResponses.lowerConversation")(function* (
-  request: LLMRequest,
-  extension: Extension,
-) {
-  const instructions = ProviderShared.joinText(request.system)
-  return {
-    model: request.model.id,
-    input: yield* lowerMessages(request, extension),
-    ...(instructions ? { instructions } : {}),
-  }
-})
-
-export const lowerGeneration = (request: LLMRequest) => {
+const lowerOptions = (request: LLMRequest) => {
   const options = OpenResponsesOptions.resolve(request)
-  const generation = request.generation
+  const instructions = ProviderShared.joinText(request.system)
   const cacheKey = ProviderShared.promptCacheKey(request)
   const parallelToolCalls = resolveParallelToolCalls(request)
   return {
-    stream: true as const,
-    max_output_tokens: generation?.maxTokens,
-    temperature: generation?.temperature,
-    top_p: generation?.topP,
-    presence_penalty: generation?.presencePenalty,
-    frequency_penalty: generation?.frequencyPenalty,
+    ...(instructions ? { instructions } : {}),
     ...(options.store !== undefined ? { store: options.store } : {}),
     ...(options.metadata ? { metadata: options.metadata } : {}),
     ...(options.safetyIdentifier ? { safety_identifier: options.safetyIdentifier } : {}),
@@ -788,7 +727,7 @@ export const resolveParallelToolCalls = (request: LLMRequest) => {
   return disabled === undefined ? undefined : !disabled
 }
 
-export const allowedToolChoice = (request: LLMRequest) => {
+const allowedToolChoice = (request: LLMRequest) => {
   const allowed = OpenResponsesOptions.resolve(request).allowedTools
   if (!allowed) return undefined
   return {
@@ -798,34 +737,42 @@ export 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 {
-    ...(yield* lowerConversation(request, extension)),
-    ...lowerGeneration(request),
+    model: request.model.id,
+    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,
+    top_p: generation?.topP,
+    presence_penalty: generation?.presencePenalty,
+    frequency_penalty: generation?.frequencyPenalty,
+    ...lowerOptions(request),
   }
 })
 
 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))
 })
 
 // =============================================================================
@@ -835,7 +782,7 @@ export const fromRequest = Effect.fn("OpenResponses.fromRequest")(function* (req
 // cached-read and cache-write subsets, and `output_tokens` (inclusive total)
 // with a `reasoning_tokens` subset. Pass the totals through and derive the
 // non-cached breakdown.
-export const mapUsage = (usage: OpenResponsesUsage | null | undefined, providerMetadataKey: string) => {
+const mapUsage = (usage: OpenResponsesUsage | null | undefined, providerMetadataKey: string) => {
   if (!usage) return undefined
   const cached = usage.input_tokens_details?.cached_tokens
   const cacheWrite = usage.input_tokens_details?.cache_write_tokens
@@ -865,8 +812,6 @@ const mapFinishReason = (event: Event, hasFunctionCall: boolean): FinishReason =
   return hasFunctionCall ? "tool-calls" : "unknown"
 }
 
-export const metadataKey = (model: LLMRequest["model"]) => model.route.providerMetadataKey ?? "openresponses"
-
 export const providerMetadata = (state: ParserState, metadata: Record<string, unknown>): ProviderMetadata => ({
   [state.providerMetadataKey]: metadata,
 })
@@ -1010,12 +955,16 @@ 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,
@@ -1028,6 +977,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,
@@ -1143,27 +1093,13 @@ const onOutputItemDone = Effect.fn("OpenResponses.onOutputItemDone")(function* (
 ) {
   if (!item) return [state, NO_EVENTS] satisfies StepResult
 
-  if (item.type === "compaction") {
-    if (!item.id || typeof item.encrypted_content !== "string")
-      return yield* ProviderShared.eventError(state.id, "Compaction output is missing its id or encrypted content")
-    if (state.completedCompactions.has(item.id)) return [state, NO_EVENTS] satisfies StepResult
-    const events: LLMEvent[] = []
-    const lifecycle = Lifecycle.stepStart(state.lifecycle, events)
-    events.push(
-      LLMEvent.compaction({
-        provider: state.provider,
-        id: item.id,
-        encrypted: item.encrypted_content,
-      }),
-    )
-    return [
-      { ...state, lifecycle, completedCompactions: new Set([...state.completedCompactions, item.id]) },
-      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 : []
@@ -1176,13 +1112,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
@@ -1321,34 +1257,26 @@ const onResponseFinish = Effect.fn("OpenResponses.onResponseFinish")(function* (
   const events: LLMEvent[] = []
   if (event.type === "response.completed") {
     for (const item of event.response?.output ?? []) {
-      if (item.type !== "compaction" && item.type !== "function_call") continue
-      if (item.type === "compaction") {
-        // Terminal recovery cannot insert a checkpoint before already-emitted content.
-        if (state.lifecycle.stepStarted && !state.completedCompactions.has(item.id ?? ""))
-          return yield* ProviderShared.eventError(
-            state.id,
-            "Cannot recover a compaction checkpoint after output has been emitted",
-          )
-      }
-      if (item.type === "function_call" && !current.tools[item.id ?? item.call_id ?? ""]) continue
+      const id = item.id ?? (item.type === "function_call" ? item.call_id : undefined)
+      if (id === undefined) continue
+      if (item.type !== "function_call" || !current.tools[id]) continue
       const [next, emitted] = yield* onOutputItemDone(current, item)
       current = next
       events.push(...emitted)
     }
-    // Some compatible providers omit output_item.done even after completing the response.
-    const pending = yield* ToolStream.finishAll(current.id, current.tools)
-    current = {
-      ...current,
-      tools: pending.tools,
-      hasFunctionCall:
-        current.hasFunctionCall ||
-        pending.events.some((event) => LLMEvent.is.toolCall(event) || LLMEvent.is.toolInputError(event)),
-    }
-    events.push(...pending.events)
   }
+  // Some compatible providers omit output_item.done even after completing the response.
+  const pending =
+    event.type === "response.completed"
+      ? yield* ToolStream.finishAll(current.id, current.tools)
+      : { tools: current.tools, events: NO_EVENTS }
+  events.push(...pending.events)
+  const hasFunctionCall =
+    pending.events.some((event) => LLMEvent.is.toolCall(event) || LLMEvent.is.toolInputError(event)) ||
+    current.hasFunctionCall
   const lifecycle = Lifecycle.finish(current.lifecycle, events, {
     reason: {
-      normalized: mapFinishReason(event, current.hasFunctionCall),
+      normalized: mapFinishReason(event, hasFunctionCall),
       raw: event.response?.incomplete_details?.reason,
     },
     usage: mapUsage(event.response?.usage, current.providerMetadataKey),
@@ -1360,7 +1288,7 @@ const onResponseFinish = Effect.fn("OpenResponses.onResponseFinish")(function* (
           })
         : undefined,
   })
-  return [{ ...current, lifecycle }, events] satisfies StepResult
+  return [{ ...current, lifecycle, hasFunctionCall, tools: pending.tools }, events] satisfies StepResult
 })
 
 // Build the prettiest summary available from whatever the provider supplied.
@@ -1494,18 +1422,17 @@ 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 => ({
-  provider: request.model.provider,
-  completedCompactions: new Set<string>(),
-  id: extension.id,
-  name: extension.name,
-  providerMetadataKey: metadataKey(request.model),
+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>(),
   completedTools: new Set<string>(),
   lifecycle: Lifecycle.initial(),
   outputItems: {},
   message: undefined,
+  completedMessages: new Set<string>(),
   reasoningItems: {},
 })
 

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

@@ -5,14 +5,13 @@ import { Auth } from "../route/auth.js"
 import { Endpoint } from "../route/endpoint.js"
 import { Protocol } from "../route/protocol.js"
 import { HttpTransport } from "../route/transport/index.js"
-import type { LLMRequest, JsonSchema, ToolDefinition } from "../schema/index.js"
+import { LLMRequest, type JsonSchema, type ToolDefinition } from "../schema/index.js"
 import { OpenResponses } from "./open-responses.js"
 import { JsonObject, optionalArray, optionalNull, ProviderShared } from "./shared.js"
 import { OpenAIImage } from "./utils/openai-image.js"
 import { ResponsesHostedTools } from "./utils/responses-hosted-tools.js"
 import { ToolSchemaProjection } from "./utils/tool-schema.js"
 import { OpenResponsesChannel } from "./open-responses-channel.js"
-import { ResponsesCompaction } from "./utils/responses-compaction.js"
 
 const ADAPTER = "openai-responses"
 const NAME = "OpenAI Responses"
@@ -21,14 +20,6 @@ const WEBSOCKET_ROTATE_AFTER_MS = 55 * 60 * 1000
 export const DEFAULT_BASE_URL = "https://api.openai.com/v1"
 export const PATH = OpenResponses.PATH
 
-export const ContextManagement = Schema.Array(
-  Schema.Struct({
-    type: Schema.Literal("compaction"),
-    compactThreshold: Schema.optional(Schema.Int.check(Schema.isGreaterThan(0))),
-  }),
-)
-export type ContextManagement = typeof ContextManagement.Type
-
 const OpenAIResponsesImageGenerationTool = Schema.Struct({
   type: Schema.tag("image_generation"),
   action: Schema.optional(Schema.Literals(["auto", "generate", "edit"])),
@@ -87,14 +78,6 @@ const OpenAIResponsesCoreFields = {
   input: Schema.Array(Schema.Union([OpenResponses.InputItem, OpenAIResponsesHostedToolItem])),
   tools: optionalArray(OpenAIResponsesTools),
   tool_choice: Schema.optional(OpenAIResponsesToolChoice),
-  context_management: Schema.optional(
-    Schema.Array(
-      Schema.Struct({
-        type: Schema.Literal("compaction"),
-        compact_threshold: Schema.optional(Schema.Int.check(Schema.isGreaterThan(0))),
-      }),
-    ),
-  ),
 }
 
 const OpenAIResponsesBody = Schema.Struct({
@@ -103,11 +86,11 @@ const OpenAIResponsesBody = Schema.Struct({
 })
 export type OpenAIResponsesBody = Schema.Schema.Type<typeof OpenAIResponsesBody>
 
-const extension = {
+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),
+} satisfies OpenResponses.ProviderAdapter
 
 const nativeImageToolInput = (tool: ToolDefinition) => {
   const native = tool.native?.openai
@@ -142,14 +125,15 @@ const lowerToolChoice = (toolChoice: NonNullable<LLMRequest["toolChoice"]>, tool
 const decodeBody = ProviderShared.validateWith(Schema.decodeUnknownEffect(OpenAIResponsesBody))
 
 const fromRequest = Effect.fn("OpenAIResponses.fromRequest")(function* (request: LLMRequest) {
-  const management = yield* ProviderShared.validateWith(
-    Schema.decodeUnknownEffect(Schema.UndefinedOr(ContextManagement)),
-  )(request.providerOptions?.contextManagement)
+  const body = yield* OpenResponses.fromRequestWithAdapter(
+    LLMRequest.update(request, { tools: [], toolChoice: undefined }),
+    adapter,
+  )
   const toolSchemaCompatibility = request.model.compatibility?.toolSchema
+  const parallelToolCalls = OpenResponses.resolveParallelToolCalls(request)
   return yield* decodeBody({
-    ...(yield* OpenResponses.lowerConversation(request, extension)),
-    ...OpenResponses.lowerGeneration(request),
-    context_management: management?.map((edit) => ({ type: edit.type, compact_threshold: edit.compactThreshold })),
+    ...body,
+    ...(parallelToolCalls === undefined ? {} : { parallel_tool_calls: parallelToolCalls }),
     tools:
       request.tools.length === 0
         ? undefined
@@ -157,8 +141,7 @@ const fromRequest = Effect.fn("OpenAIResponses.fromRequest")(function* (request:
             lowerTool(tool, ToolSchemaProjection.modelCompatibility(tool.inputSchema, toolSchemaCompatibility)),
           ),
     tool_choice:
-      OpenResponses.allowedToolChoice(request) ??
-      (request.toolChoice ? yield* lowerToolChoice(request.toolChoice, request.tools) : undefined),
+      body.tool_choice ?? (request.toolChoice ? yield* lowerToolChoice(request.toolChoice, request.tools) : undefined),
   })
 })
 
@@ -221,7 +204,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,
   },
@@ -240,7 +223,6 @@ export const transport = channelTransport({
 })
 
 export const route = Route.make({
-  compact: ResponsesCompaction.make(extension),
   id: ADAPTER,
   provider: "openai",
   providerMetadataKey: "openai",

packages/ai/src/protocols/utils/responses-compaction.ts

@@ -1,174 +0,0 @@
-import { Effect, Schema, Stream } from "effect"
-import {
-  AIError,
-  InvalidProviderOutputError,
-  CompactionPart,
-  CompactionResponse,
-  HttpOptions,
-  LLMRequest,
-  Message,
-  type ContentPart,
-  mergeJsonRecords,
-} from "../../schema/index.js"
-import type { CompactOperation } from "../../route/client.js"
-import { Endpoint } from "../../route/endpoint.js"
-import { RequestExecutor } from "../../route/executor.js"
-import { HttpTransport } from "../../route/transport/index.js"
-import { OpenResponses } from "../open-responses.js"
-import { JsonObject, optionalNull, ProviderShared } from "../shared.js"
-
-const Body = Schema.Struct({
-  model: Schema.String,
-  input: Schema.Array(Schema.Unknown),
-  instructions: optionalNull(Schema.String),
-  previous_response_id: optionalNull(Schema.String),
-  service_tier: optionalNull(Schema.String),
-  prompt_cache_key: optionalNull(Schema.String),
-  prompt_cache_retention: optionalNull(Schema.String),
-  prompt_cache_options: optionalNull(
-    Schema.Struct({ mode: Schema.optional(Schema.String), ttl: Schema.optional(Schema.String) }),
-  ),
-})
-
-const Text = Schema.Union([OpenResponses.OpenResponsesInputText, OpenResponses.OpenResponsesOutputText])
-const File = Schema.Union([
-  Schema.Struct({
-    ...OpenResponses.OpenResponsesInputFile.fields,
-    file_url: Schema.String,
-    file_data: Schema.optional(Schema.Never),
-  }),
-  Schema.Struct({
-    ...OpenResponses.OpenResponsesInputFile.fields,
-    file_data: Schema.String,
-    file_url: Schema.optional(Schema.Never),
-  }),
-])
-const MessageFields = {
-  type: Schema.Literal("message"),
-  id: Schema.optional(Schema.String),
-  status: Schema.optional(Schema.String),
-  phase: Schema.optional(OpenResponses.MessagePhase),
-}
-const Response = Schema.Struct({
-  object: Schema.Literal("response.compaction"),
-  output: Schema.Array(
-    Schema.Union([
-      OpenResponses.CompactionItem,
-      OpenResponses.OpenResponsesReasoningItem,
-      Schema.Struct({
-        ...MessageFields,
-        role: Schema.Literal("user"),
-        content: Schema.Array(Schema.Union([Text, OpenResponses.OpenResponsesInputImage, File])).check(
-          Schema.isMinLength(1),
-        ),
-      }),
-      Schema.Struct({
-        ...MessageFields,
-        role: Schema.Literal("assistant"),
-        content: Schema.Array(Text).check(Schema.isMinLength(1)),
-      }),
-    ]),
-  ),
-  usage: Schema.optional(Schema.StructWithRest(OpenResponses.OpenResponsesUsage, [JsonObject])),
-})
-
-export const make = (extension: OpenResponses.Extension): CompactOperation =>
-  Effect.fn("ResponsesCompaction.execute")(function* (request, executor, options) {
-    const route = request.model.route
-    const native = yield* OpenResponses.lowerConversation(request, extension)
-    const body = yield* ProviderShared.validateWith(Schema.decodeUnknownEffect(Body))(
-      mergeJsonRecords(
-        {
-          ...native,
-          service_tier: request.providerOptions?.serviceTier,
-          prompt_cache_key: ProviderShared.promptCacheKey(request),
-        },
-        request.http?.body,
-      ),
-    )
-    const url = Endpoint.render(route.endpoint, { request, body: native })
-    url.pathname = `${url.pathname.replace(/\/$/, "")}/compact`
-    const parts = yield* HttpTransport.jsonRequestParts({
-      request: LLMRequest.update(request, {
-        http: request.http === undefined ? undefined : new HttpOptions({ ...request.http, body: undefined }),
-      }),
-      body,
-      endpoint: Endpoint.path(url.toString()),
-      auth: route.auth,
-      encodeBody: Schema.encodeSync(Schema.fromJsonString(Body)),
-    })
-    const response = yield* executor.execute(
-      ProviderShared.jsonPost({ url: parts.url, body: parts.bodyText, headers: parts.headers }),
-      options?.http,
-    )
-    const text = yield* RequestExecutor.responseStream(response).pipe(
-      Stream.decodeText(),
-      Stream.runFold(
-        () => "",
-        (text, chunk) => text + chunk,
-      ),
-    )
-    const invalid = (message: string, cause?: unknown) =>
-      new AIError({
-        reason: new InvalidProviderOutputError({
-          route: route.id,
-          message,
-          body: text,
-          cause,
-          http: RequestExecutor.responseHttp(response),
-        }),
-      })
-    const result = yield* Schema.decodeUnknownEffect(Schema.fromJsonString(Response))(text).pipe(
-      Effect.mapError((cause) => invalid("Invalid compaction response", cause)),
-    )
-    if (!result.output.some((item) => item.type === "compaction"))
-      return yield* invalid("Compaction response did not contain a checkpoint")
-    return new CompactionResponse({
-      messages: result.output.map((item) => toMessage(item, request.model)),
-      usage: OpenResponses.mapUsage(result.usage, OpenResponses.metadataKey(request.model)),
-    })
-  })
-
-function toMessage(item: (typeof Response.Type.output)[number], model: LLMRequest["model"]): Message {
-  if (item.type === "compaction")
-    return Message.assistant(
-      CompactionPart.make({ provider: model.provider, id: item.id ?? undefined, encrypted: item.encrypted_content }),
-    )
-
-  const key = OpenResponses.metadataKey(model)
-  if (item.type === "reasoning") {
-    const summary = item.summary.length ? item.summary : [{ text: "" }]
-    return Message.assistant(
-      summary.map((part) => ({
-        type: "reasoning" as const,
-        text: part.text,
-        providerMetadata: { [key]: { itemId: item.id, reasoningEncryptedContent: item.encrypted_content } },
-      })),
-    )
-  }
-
-  return Message.make({
-    role: item.role,
-    providerMetadata: { [key]: { itemId: item.id, type: item.type, status: item.status, phase: item.phase } },
-    content: item.content.map((part): ContentPart => {
-      if (part.type === "input_text" || part.type === "output_text") return { type: "text", text: part.text }
-      if (part.type === "input_image")
-        return {
-          type: "media",
-          data: part.image_url,
-          mediaType: /^data:([^;,]+)/.exec(part.image_url)?.[1] ?? "image/*",
-          providerMetadata: part.detail === undefined ? undefined : { [key]: { detail: part.detail } },
-        }
-      const data = part.file_url === undefined ? part.file_data : part.file_url
-      return {
-        type: "media",
-        data,
-        filename: part.filename,
-        mediaType: /^data:([^;,]+)/.exec(data)?.[1] ?? "application/octet-stream",
-        providerMetadata: part.detail === undefined ? undefined : { [key]: { detail: part.detail } },
-      }
-    }),
-  })
-}
-
-export * as ResponsesCompaction from "./responses-compaction.js"

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

@@ -4,7 +4,6 @@ import type { LLMRequest } from "../schema/index.js"
 import { OpenResponses } from "./open-responses.js"
 import { JsonObject, optionalNull, ProviderShared } from "./shared.js"
 import { ResponsesHostedTools } from "./utils/responses-hosted-tools.js"
-import { ResponsesCompaction } from "./utils/responses-compaction.js"
 
 const ADAPTER = "xai-responses"
 const NAME = "xAI Responses"
@@ -37,19 +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) {
-  if (request.providerOptions?.contextManagement !== undefined)
-    return yield* ProviderShared.invalidRequest(
-      "xAI requires explicit compaction through LLMClient.compact; automatic context management is not supported",
-    )
-  return yield* decodeBody(yield* OpenResponses.fromRequestWithExtension(request, extension))
+  return yield* decodeBody(yield* OpenResponses.fromRequestWithAdapter(request, adapter))
 })
 
 const HOSTED_TOOLS = {
@@ -83,12 +78,10 @@ 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,
   },
 })
 
-export const compact = ResponsesCompaction.make(extension)
-
 export * as XAIResponses from "./xai-responses.js"

packages/ai/src/provider-package.ts

@@ -1,5 +1,4 @@
 import type { LanguageModel, ProviderOptions } from "./schema/index.js"
-import type { CompactOperation } from "./route/client.js"
 
 export interface Settings extends Readonly<Record<string, unknown>> {
   readonly baseURL?: string
@@ -10,9 +9,8 @@ export interface Settings extends Readonly<Record<string, unknown>> {
 export interface Definition<
   ProviderSettings extends Settings = Settings,
   Options extends ProviderOptions = ProviderOptions,
-  Compact extends CompactOperation | undefined = CompactOperation | undefined,
 > {
-  readonly model: (modelID: string, settings: ProviderSettings) => LanguageModel<Options, Compact>
+  readonly model: (modelID: string, settings: ProviderSettings) => LanguageModel<Options>
 }
 
 export * as ProviderPackage from "./provider-package.js"

packages/ai/src/providers/amazon-bedrock.ts

@@ -1,11 +1,9 @@
-import type { Route, RouteDefaultsInput } from "../route/client.js"
+import type { RouteDefaultsInput } from "../route/client.js"
 import { Auth } from "../route/auth.js"
 import type { ProviderPackage } from "../provider-package.js"
 import { ProviderID, type ModelID } from "../schema/index.js"
 import * as BedrockConverse from "../protocols/bedrock-converse.js"
 import type { BedrockCredentials } from "../protocols/bedrock-converse.js"
-import { BedrockMessages } from "../protocols/bedrock-messages.js"
-import type { AnthropicMessages } from "../protocols/anthropic-messages.js"
 
 export const id = ProviderID.make("amazon-bedrock")
 
@@ -27,40 +25,38 @@ export interface Settings extends ProviderPackage.Settings {
   readonly region?: string
   readonly topP?: number
 }
-export const routes = [BedrockConverse.route, BedrockMessages.route]
+export const routes = [BedrockConverse.route]
 
 const bedrockBaseURL = (region: string) => `https://bedrock-runtime.${region}.amazonaws.com`
 
-const configuredRoute = <Body, Prepared>(route: Route<Body, Prepared>, input: Config) => {
+const configuredRoute = (input: Config) => {
   const { apiKey, credentials, region, baseURL, ...rest } = input
   const resolvedRegion = region ?? credentials?.region ?? "us-east-1"
-  return route.with({
+  return BedrockConverse.route.with({
     ...rest,
     provider: id,
-    providerMetadataKey: route.providerMetadataKey,
+    providerMetadataKey: "bedrock",
     endpoint: { baseURL: baseURL ?? bedrockBaseURL(resolvedRegion) },
     auth: apiKey === undefined ? BedrockConverse.sigV4Auth(credentials) : Auth.bearer(apiKey),
   })
 }
 
 export const configure = (input: Config = {}) => {
-  const route = configuredRoute(BedrockConverse.route, input)
-  const messages = configuredRoute(BedrockMessages.route, input)
+  const route = configuredRoute(input)
   return {
     id,
     model: (modelID: string | ModelID) => route.model({ id: modelID }),
-    messages: (modelID: string | ModelID) => messages.model<AnthropicMessages.ProviderOptionsInput>({ id: modelID }),
     configure,
   }
 }
 
 export const provider = configure()
-const config = (settings: Settings): Config => {
+export const model: ProviderPackage.Definition<Settings>["model"] = (modelID, settings) => {
   if (settings.auth === "bearer" && settings.apiKey === undefined)
     throw new Error("Amazon Bedrock bearer auth requires apiKey")
   if (settings.auth === "sigv4" && settings.apiKey !== undefined)
     throw new Error("Amazon Bedrock SigV4 auth does not accept apiKey")
-  return {
+  return configure({
     apiKey: settings.auth === "sigv4" ? undefined : settings.apiKey,
     baseURL: settings.baseURL,
     credentials: settings.credentials,
@@ -68,13 +64,5 @@ const config = (settings: Settings): Config => {
     headers: settings.headers === undefined ? undefined : { ...settings.headers },
     http: settings.body === undefined ? undefined : { body: { ...settings.body } },
     region: settings.region,
-  }
+  }).model(modelID)
 }
-
-export const model: ProviderPackage.Definition<Settings>["model"] = (modelID, settings) =>
-  configure(config(settings)).model(modelID)
-export const messagesModel: ProviderPackage.Definition<
-  Settings & { readonly providerOptions?: AnthropicMessages.ProviderOptionsInput },
-  AnthropicMessages.ProviderOptionsInput
->["model"] = (modelID, settings) =>
-  configure({ ...config(settings), providerOptions: settings.providerOptions }).messages(modelID)

packages/ai/src/providers/amazon-bedrock/messages.ts

@@ -1 +0,0 @@
-export { messagesModel as model } from "../amazon-bedrock.js"

packages/ai/src/providers/azure.ts

@@ -1,7 +1,7 @@
 import { Headers } from "effect/unstable/http"
 import { Auth } from "../route/auth.js"
 import { type AtLeastOne, type ProviderAuthOption } from "../route/auth-options.js"
-import type { Route, RouteDefaultsInput, CompactOperation } from "../route/client.js"
+import type { Route as RouteDef, RouteDefaultsInput } from "../route/client.js"
 import type { ProviderPackage } from "../provider-package.js"
 import { ProviderID, type ModelID } from "../schema/index.js"
 import * as OpenAIChat from "../protocols/openai-chat.js"
@@ -102,11 +102,7 @@ const auth = (input: Config) => {
   )
 }
 
-const configuredRoute = <Body, Prepared, Compact extends CompactOperation | undefined>(
-  route: Route<Body, Prepared, Compact>,
-  input: Config,
-  modelID: string | ModelID,
-) =>
+const configuredRoute = <Body, Prepared>(route: RouteDef<Body, Prepared>, input: Config, modelID: string | ModelID) =>
   route.with({
     auth: auth(input),
     endpoint: endpoint(input, modelID),
@@ -165,11 +161,10 @@ const config = (settings: Settings): Config => {
   throw new Error("Azure requires resourceName or baseURL")
 }
 
-export const responsesModel: ProviderPackage.Definition<
-  Settings,
-  OpenAIProviderOptionsInput,
-  CompactOperation
->["model"] = (modelID, settings) => configure(config(settings)).responses(modelID)
+export const responsesModel: ProviderPackage.Definition<Settings, OpenAIProviderOptionsInput>["model"] = (
+  modelID,
+  settings,
+) => configure(config(settings)).responses(modelID)
 export const chatModel: ProviderPackage.Definition<Settings, OpenAIProviderOptionsInput>["model"] = (
   modelID,
   settings,

packages/ai/src/providers/google-vertex-messages.ts

@@ -57,9 +57,7 @@ const route = Route.make({
   }),
   endpoint: Endpoint.path(({ request }) => `/${request.model.id}:streamRawPredict`),
   auth: Auth.none,
-  transport: AnthropicMessages.transport<
-    Omit<AnthropicMessages.AnthropicMessagesBody, "model"> & { readonly anthropic_version: typeof VERSION }
-  >(),
+  framing: AnthropicMessages.framing,
   headers: () => ({ "anthropic-version": HEADER_VERSION }),
 })
 

packages/ai/src/providers/openai-options.ts

@@ -1,12 +1,10 @@
 import { mergeProviderOptions, type ProviderOptions } from "../schema/index.js"
 import type { OpenAIServiceTier } from "../protocols/utils/openai-options.js"
 import type { Options } from "../protocols/utils/open-responses-options.js"
-import type { ContextManagement } from "../protocols/openai-responses.js"
 
 export type { OpenAIResponseIncludable, OpenAIServiceTier } from "../protocols/utils/openai-options.js"
 
 export type OpenAIOptionsInput = Omit<Options, "serviceTier"> & {
-  readonly contextManagement?: ContextManagement
   readonly serviceTier?: OpenAIServiceTier
   readonly [key: string]: unknown
 }

packages/ai/src/providers/openai.ts

@@ -1,5 +1,5 @@
 import { AuthOptions, type ProviderAuthOption } from "../route/auth-options.js"
-import type { Route, RouteDefaultsInput, CompactOperation } from "../route/client.js"
+import type { Route, RouteDefaultsInput } from "../route/client.js"
 import type { ProviderPackage } from "../provider-package.js"
 import { HttpOptions, ProviderID, ToolDefinition, mergeHttpOptions, type ModelID } from "../schema/index.js"
 import * as OpenAIChat from "../protocols/openai-chat.js"
@@ -73,10 +73,7 @@ const defaults = (input: Config) => {
   return rest
 }
 
-const configuredRoute = <Body, Prepared, Compact extends CompactOperation | undefined>(
-  route: Route<Body, Prepared, Compact>,
-  input: Config,
-) =>
+const configuredRoute = <Body, Prepared>(route: Route<Body, Prepared>, input: Config) =>
   route.with({
     auth: auth(input),
     endpoint: { baseURL: input.baseURL, query: input.queryParams },
@@ -132,10 +129,7 @@ const config = (settings: Settings): Config => {
   }
 }
 
-export const model: ProviderPackage.Definition<Settings, OpenAIProviderOptionsInput, CompactOperation>["model"] = (
-  modelID,
-  settings,
-) => {
+export const model: ProviderPackage.Definition<Settings, OpenAIProviderOptionsInput>["model"] = (modelID, settings) => {
   return configure(config(settings)).responses(modelID)
 }
 

packages/ai/src/providers/xai.ts

@@ -1,5 +1,5 @@
 import { AuthOptions, type ProviderAuthOption } from "../route/auth-options.js"
-import { Route, type RouteDefaultsInput, type CompactOperation } from "../route/client.js"
+import { Route, type RouteDefaultsInput } from "../route/client.js"
 import { Endpoint } from "../route/endpoint.js"
 import { HttpOptions, ProviderID, type ModelID } from "../schema/index.js"
 import * as OpenAICompatibleProfiles from "./openai-compatible-profile.js"
@@ -13,7 +13,7 @@ import type { ProviderPackage } from "../provider-package.js"
 
 export const id = ProviderID.make("xai")
 
-export type XAIProviderOptionsInput = OpenAIOptionsInput & { readonly contextManagement?: never }
+export type XAIProviderOptionsInput = OpenAIOptionsInput
 
 export type LanguageModelOptions = Omit<RouteDefaultsInput, "providerOptions"> &
   ProviderAuthOption<"optional"> & {
@@ -32,7 +32,6 @@ export type { XAIImageOptions } from "../protocols/xai-images.js"
 const RESPONSES_WEBSOCKET_ROTATE_AFTER_MS = 24 * 60 * 1000
 
 const responsesRoute = Route.make({
-  compact: XAIResponses.compact,
   id: "openai-responses",
   provider: id,
   providerMetadataKey: "xai",
@@ -103,10 +102,7 @@ export const configure = (input: LanguageModelOptions = {}) => {
 }
 
 export const provider = configure()
-export const model: ProviderPackage.Definition<Settings, XAIProviderOptionsInput, CompactOperation>["model"] = (
-  modelID,
-  settings,
-) =>
+export const model: ProviderPackage.Definition<Settings, XAIProviderOptionsInput>["model"] = (modelID, settings) =>
   configure({
     apiKey: settings.apiKey,
     baseURL: settings.baseURL,

packages/ai/src/route/client.ts

@@ -13,7 +13,6 @@ import * as ProviderShared from "../protocols/shared.js"
 import type { ProtocolID, ProviderOptions } from "../schema/index.js"
 import {
   AIError,
-  CompactionResponse,
   AIErrorReason,
   GenerationOptions,
   HttpOptions,
@@ -35,12 +34,7 @@ export interface RouteBody<Body> {
   readonly from: (request: LLMRequest) => Effect.Effect<Body, AIError>
 }
 
-export interface Route<
-  Body,
-  Prepared = unknown,
-  Compact extends CompactOperation | undefined = CompactOperation | undefined,
-> {
-  readonly compact: Compact
+export interface Route<Body, Prepared = unknown> {
   readonly id: string
   readonly provider?: ProviderID
   /** ProviderMetadata namespace emitted and consumed by this route. */
@@ -48,15 +42,13 @@ export interface Route<
   readonly protocol: ProtocolID
   readonly endpoint: Endpoint.Definition<Body>
   readonly auth: Auth.Definition
-  /** Deployment headers resolved once for every operation, before transport authentication. */
-  readonly headers?: (input: { readonly request: LLMRequest }) => Record<string, string>
   readonly transport: Transport<Body, Prepared, unknown>
   readonly defaults: RouteDefaults
   readonly body: RouteBody<Body>
-  readonly with: (patch: RoutePatch<Body, Prepared>) => Route<Body, Prepared, Compact>
+  readonly with: (patch: RoutePatch<Body, Prepared>) => Route<Body, Prepared>
   readonly model: <Options extends ProviderOptions = ProviderOptions>(
     input: RouteMappedLanguageModelInput,
-  ) => LanguageModel<Options, Compact>
+  ) => LanguageModel<Options>
   readonly prepareTransport: (
     body: Body,
     request: LLMRequest,
@@ -74,11 +66,7 @@ export interface Route<
 // Normal call sites use `OpenAIChat.route`; callers only need body types
 // when preparing a request with a protocol-specific type assertion.
 // oxlint-disable-next-line typescript-eslint/no-explicit-any
-export type AnyRoute<Compact extends CompactOperation | undefined = CompactOperation | undefined> = Route<
-  any,
-  any,
-  Compact
->
+export type AnyRoute = Route<any, any>
 
 export type HttpOptionsInput = HttpOptions.Input
 
@@ -111,15 +99,15 @@ export interface RoutePatch<Body, Prepared> extends RouteDefaultsInput {
 
 type RouteMappedLanguageModelInput = RouteLanguageModelInput | RouteRoutedLanguageModelInput
 
-const makeRouteLanguageModel = <Options extends ProviderOptions, Compact extends CompactOperation | undefined>(
-  route: AnyRoute<Compact>,
+const makeRouteLanguageModel = <Options extends ProviderOptions = ProviderOptions>(
+  route: AnyRoute,
   mapped: RouteMappedLanguageModelInput,
 ) => {
   const provider = route.provider ?? ("provider" in mapped ? mapped.provider : undefined)
   if (!provider) throw new Error(`Route.model(${route.id}) requires a provider`)
   if (!endpointBaseURL(route.endpoint))
     throw new Error(`Route.model(${route.id}) requires an endpoint baseURL — configure it on the route first`)
-  return LanguageModel.make<Options, Compact>({
+  return LanguageModel.make<Options>({
     ...mapped,
     provider,
     route,
@@ -162,10 +150,6 @@ export const httpOptions = (input: HttpOptionsInput | undefined) => {
 }
 
 export interface Interface {
-  readonly compact: (
-    request: CompactionRequest,
-    options?: Pick<StreamOptions, "http">,
-  ) => Effect.Effect<CompactionResponse, AIError>
   readonly stream: StreamMethod
   readonly generate: GenerateMethod
 }
@@ -183,17 +167,6 @@ export interface GenerateMethod {
   (request: LLMRequest, options?: StreamOptions): Effect.Effect<LLMResponse, AIError>
 }
 
-export type CompactOperation = (
-  request: LLMRequest,
-  executor: RequestExecutor.Interface,
-  options?: Pick<StreamOptions, "http">,
-) => Effect.Effect<CompactionResponse, AIError>
-
-export type CompactionRequest = LLMRequest<LanguageModel<ProviderOptions, CompactOperation>>
-
-export const canCompact = (request: LLMRequest): request is CompactionRequest =>
-  request.model.route.compact !== undefined
-
 export class Service extends Context.Service<Service, Interface>()("@opencode/LLMClient") {}
 
 const resolveRequestOptions = (request: LLMRequest) => {
@@ -214,7 +187,6 @@ const resolveRequestOptions = (request: LLMRequest) => {
 }
 
 export interface MakeInput<Body, Frame, Event, State> {
-  readonly compact?: CompactOperation
   /** Route id used in diagnostics and prepared request metadata. */
   readonly id: string
   /** Provider identity for route-owned model construction. */
@@ -236,7 +208,6 @@ export interface MakeInput<Body, Frame, Event, State> {
 }
 
 export interface MakeTransportInput<Body, Prepared, Frame, Event, State> {
-  readonly compact?: CompactOperation
   /** Route id used in diagnostics and prepared request metadata. */
   readonly id: string
   /** Provider identity for route-owned model construction. */
@@ -312,14 +283,12 @@ function makeFromTransport<Body, Prepared, Frame, Event, State>(
 
   const build = (routeInput: BuiltRouteInput): Route<Body, Prepared> => {
     const route: Route<Body, Prepared> = {
-      compact: routeInput.compact,
       id: routeInput.id,
       provider: routeInput.provider === undefined ? undefined : ProviderID.make(routeInput.provider),
       providerMetadataKey: routeInput.providerMetadataKey,
       protocol: protocol.id,
       endpoint: routeInput.endpoint,
       auth: routeInput.auth ?? Auth.none,
-      headers: routeInput.headers,
       transport: routeInput.transport,
       defaults: routeInput.defaults ?? {},
       body: protocol.body,
@@ -341,7 +310,7 @@ function makeFromTransport<Body, Prepared, Frame, Event, State>(
         })
       },
       model: <Options extends ProviderOptions = ProviderOptions>(input: RouteMappedLanguageModelInput) =>
-        makeRouteLanguageModel<Options, CompactOperation | undefined>(route, input),
+        makeRouteLanguageModel<Options>(route, input),
       prepareTransport: (body, request, options) =>
         routeInput.transport.prepare({
           body,
@@ -349,6 +318,7 @@ function makeFromTransport<Body, Prepared, Frame, Event, State>(
           endpoint: routeInput.endpoint,
           auth: routeInput.auth ?? Auth.none,
           encodeBody,
+          headers: routeInput.headers,
           middleware: options?.http,
           webSocket: options?.webSocket,
         }),
@@ -438,12 +408,6 @@ function makeFromTransport<Body, Prepared, Frame, Event, State>(
   return build({ ...input, defaults: mergeRouteDefaults(undefined, input.defaults ?? {}) })
 }
 
-export function make<Body, Prepared, Frame, Event, State>(
-  input: MakeTransportInput<Body, Prepared, Frame, Event, State> & { readonly compact: CompactOperation },
-): Route<Body, Prepared, CompactOperation>
-export function make<Body, Frame, Event, State>(
-  input: MakeInput<Body, Frame, Event, State> & { readonly compact: CompactOperation },
-): Route<Body, HttpTransport.HttpPrepared<Frame>, CompactOperation>
 export function make<Body, Prepared, Frame, Event, State>(
   input: MakeTransportInput<Body, Prepared, Frame, Event, State>,
 ): Route<Body, Prepared>
@@ -471,7 +435,6 @@ export function make<Body, Prepared, Frame, Event, State>(
   if ("transport" in input) return makeFromTransport(input)
   const protocol = input.protocol
   return makeFromTransport({
-    compact: input.compact,
     id: input.id,
     provider: input.provider,
     providerMetadataKey: input.providerMetadataKey,
@@ -484,19 +447,11 @@ export function make<Body, Prepared, Frame, Event, State>(
   })
 }
 
-const prepareRequest = (request: LLMRequest) => {
+const compile = Effect.fn("LLM.compile")(function* (request: LLMRequest, options?: StreamOptions) {
   const original = applyCachePolicy(resolveRequestOptions(request))
   const sanitized = LLMRequest.update(original, sanitizeSurrogates({ ...LLMRequest.input(original), model: undefined }))
   const tools = [...new Map(sanitized.tools.map((tool) => [tool.name, tool])).values()]
   const resolved = tools.length === sanitized.tools.length ? sanitized : LLMRequest.update(sanitized, { tools })
-  const headers = resolved.model.route.headers?.({ request: resolved })
-  return headers === undefined
-    ? resolved
-    : LLMRequest.update(resolved, { http: mergeHttpOptions(new HttpOptions({ headers }), resolved.http) })
-}
-
-const compile = Effect.fn("LLM.compile")(function* (request: LLMRequest, options?: StreamOptions) {
-  const resolved = prepareRequest(request)
   const route = resolved.model.route
 
   const body = yield* route.body
@@ -555,15 +510,6 @@ export function generate(request: LLMRequest, options?: StreamOptions): Effect.E
   })
 }
 
-export const compact = (
-  request: CompactionRequest,
-  options?: Pick<StreamOptions, "http">,
-): Effect.Effect<CompactionResponse, AIError, Service> =>
-  Effect.gen(function* () {
-    const client = yield* Service
-    return yield* client.compact(request, options)
-  })
-
 export const streamRequest = (request: LLMRequest, options?: StreamOptions) =>
   Stream.unwrap(
     Effect.gen(function* () {
@@ -574,29 +520,16 @@ export const streamRequest = (request: LLMRequest, options?: StreamOptions) =>
 export const layer: Layer.Layer<Service, never, RequestExecutor.Service> = Layer.effect(
   Service,
   Effect.gen(function* () {
-    const executor = yield* RequestExecutor.Service
-    const stream = streamRequestWith({ http: executor })
-    return Service.of({
-      stream,
-      generate: generateWith(stream),
-      compact: (request, options) =>
-        Effect.suspend(() => {
-          const operation = request.model.route.compact
-          if (!operation)
-            return ProviderShared.invalidRequest(
-              `${request.model.provider}/${request.model.route.id} does not support explicit compaction`,
-            )
-          return operation(prepareRequest(request), executor, options)
-        }),
+    const stream = streamRequestWith({
+      http: yield* RequestExecutor.Service,
     })
+    return Service.of({ stream, generate: generateWith(stream) })
   }),
 )
 
 export const Route = { make } as const
 
 export const LLMClient = {
-  canCompact,
-  compact,
   Service,
   layer,
   stream,

packages/ai/src/schema/events.ts

@@ -3,7 +3,6 @@ import { LLM } from "@opencode-ai/schema/llm"
 import { ContentBlockID, ToolCallID } from "./ids.js"
 import {
   Message,
-  CompactionPart,
   ProviderMetadata,
   ToolCallPart,
   ToolOutput,
@@ -63,8 +62,6 @@ export { ProviderMetadata } from "./messages.js"
  * Matches the same escape-hatch field on `LLMEvent`.
  */
 export class Usage extends Schema.Class<Usage>("AI.Usage")({
-  /** Effective input size of the final message iteration, when reported; not billed totals. */
-  contextTokens: Schema.optional(Schema.Number),
   inputTokens: Schema.optional(Schema.Number),
   outputTokens: Schema.optional(Schema.Number),
   nonCachedInputTokens: Schema.optional(Schema.Number),
@@ -75,7 +72,7 @@ export class Usage extends Schema.Class<Usage>("AI.Usage")({
   providerMetadata: Schema.optional(ProviderMetadata),
 }) {
   /**
-   * Non-reasoning output tokens (including compaction summaries) — `outputTokens` minus `reasoningTokens`, clamped
+   * Visible output tokens — `outputTokens` minus `reasoningTokens`, clamped
    * to zero. The one place subtraction happens in this contract; the clamp
    * means a provider reporting `reasoningTokens > outputTokens` produces a
    * harmless zero rather than a negative that crashes downstream schemas.
@@ -91,12 +88,6 @@ export class Usage extends Schema.Class<Usage>("AI.Usage")({
 
 export type UsageInput = Usage | ConstructorParameters<typeof Usage>[0]
 
-/** A replacement context window. Replace prior history with these messages. */
-export class CompactionResponse extends Schema.Class<CompactionResponse>("LLM.CompactionResponse")({
-  messages: Schema.Array(Message),
-  usage: Schema.optional(Usage),
-}) {}
-
 export const StepStart = Schema.Struct({
   type: Schema.tag("step-start"),
   index: Schema.Number,
@@ -250,7 +241,6 @@ export const ProviderErrorEvent = Schema.Struct({
 export type ProviderErrorEvent = Schema.Schema.Type<typeof ProviderErrorEvent>
 
 const llmEventTagged = Schema.Union([
-  CompactionPart,
   StepStart,
   TextStart,
   TextDelta,
@@ -284,7 +274,6 @@ const toolCallID = (value: ToolCallID | string) => ToolCallID.make(value)
  * `events.filter(LLMEvent.guards["tool-call"])`.
  */
 export const LLMEvent = Object.assign(llmEventTagged, {
-  compaction: CompactionPart.make,
   stepStart: StepStart.make,
   textStart: (input: WithID<TextStart, ContentBlockID>) => TextStart.make({ ...input, id: contentBlockID(input.id) }),
   textDelta: (input: WithID<TextDelta, ContentBlockID>) => TextDelta.make({ ...input, id: contentBlockID(input.id) }),
@@ -322,7 +311,6 @@ export const LLMEvent = Object.assign(llmEventTagged, {
     }),
   providerError: ProviderErrorEvent.make,
   is: {
-    compaction: llmEventTagged.guards.compaction,
     stepStart: llmEventTagged.guards["step-start"],
     textStart: llmEventTagged.guards["text-start"],
     textDelta: llmEventTagged.guards["text-delta"],
@@ -345,10 +333,10 @@ export const LLMEvent = Object.assign(llmEventTagged, {
 export type LLMEvent = Schema.Schema.Type<typeof llmEventTagged>
 
 /** Joins deltas per fragment, letting an authoritative end value replace that fragment's accumulated deltas. */
-const joinFragments = (
+const joinFragments = <Delta extends { id: string; text: string }, End extends { id: string; text?: string }>(
   events: ReadonlyArray<LLMEvent>,
-  isDelta: (event: LLMEvent) => event is LLMEvent & { id: string; text: string },
-  isEnd: (event: LLMEvent) => event is LLMEvent & { id: string; text?: string },
+  isDelta: (event: LLMEvent) => event is Extract<LLMEvent, Delta>,
+  isEnd: (event: LLMEvent) => event is Extract<LLMEvent, End>,
 ) => {
   const order: string[] = []
   const parts = new Map<string, string>()
@@ -575,8 +563,6 @@ const reduceToolCall = (state: ResponseState, event: ToolCall): ResponseState =>
 const reduceResponseState = (state: ResponseState, event: LLMEvent): ResponseState => {
   const next = appendEvent(state, event)
   switch (event.type) {
-    case "compaction":
-      return appendContent(next, event)
     case "text-start":
       return ensureText(next, event.id, event.providerMetadata)
     case "text-delta":

packages/ai/src/schema/messages.ts

@@ -7,10 +7,8 @@ import {
   HttpOptions,
   JsonSchema,
   LanguageModelSchema,
-  type LanguageModel,
   ProviderOptions,
 } from "./options.js"
-import { ProviderID } from "./ids.js"
 
 export const MessageRole = Schema.Literals(["system", "user", "assistant", "tool"])
 export type MessageRole = Schema.Schema.Type<typeof MessageRole>
@@ -54,7 +52,6 @@ export const MediaPart = Schema.Struct({
   filename: Schema.optional(Schema.String),
   cache: Schema.optional(CacheHint),
   metadata: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
-  providerMetadata: Schema.optional(ProviderMetadata),
 }).annotate({ identifier: "LLM.Content.Media" })
 export type MediaPart = Schema.Schema.Type<typeof MediaPart>
 
@@ -188,40 +185,9 @@ export const ReasoningPart = Schema.Struct({
 }).annotate({ identifier: "LLM.Content.Reasoning" })
 export type ReasoningPart = Schema.Schema.Type<typeof ReasoningPart>
 
-/** A provider-generated context checkpoint, distinct from visible assistant text. */
-type CompactionContent =
-  | { readonly encrypted: string; readonly text?: never }
-  | { readonly text: string | null; readonly encrypted?: never }
-
-const compactionPartSchema = Schema.Struct({
-  type: Schema.Literal("compaction"),
-  provider: ProviderID,
-  id: Schema.optional(Schema.String),
-  encrypted: Schema.optional(Schema.String),
-  /** Null means the provider failed to produce a summary; prior history must be retained. */
-  text: Schema.optional(Schema.NullOr(Schema.String)),
-})
-  .pipe(
-    Schema.refine(
-      (part): part is typeof part & CompactionContent => (part.encrypted !== undefined) !== (part.text !== undefined),
-      { message: "Compaction requires either encrypted content or a summary" },
-    ),
-  )
-  .annotate({ identifier: "LLM.Content.Compaction" })
-export type CompactionPart = typeof compactionPartSchema.Type
-export const CompactionPart = Object.assign(compactionPartSchema, {
-  make: (input: Omit<CompactionPart, "type" | "encrypted" | "text"> & CompactionContent): CompactionPart =>
-    Schema.decodeUnknownSync(compactionPartSchema)({ type: "compaction", ...input }),
-})
-
-export const ContentPart = Schema.Union([
-  TextPart,
-  MediaPart,
-  ToolCallPart,
-  ToolResultPart,
-  ReasoningPart,
-  CompactionPart,
-]).pipe(Schema.toTaggedUnion("type"))
+export const ContentPart = Schema.Union([TextPart, MediaPart, ToolCallPart, ToolResultPart, ReasoningPart]).pipe(
+  Schema.toTaggedUnion("type"),
+)
 export type ContentPart = Schema.Schema.Type<typeof ContentPart>
 
 export class Message extends Schema.Class<Message>("LLM.Message")({
@@ -229,7 +195,6 @@ export class Message extends Schema.Class<Message>("LLM.Message")({
   role: MessageRole,
   content: Schema.Array(ContentPart),
   metadata: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
-  providerMetadata: Schema.optional(ProviderMetadata),
   native: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
 }) {}
 
@@ -307,7 +272,7 @@ export namespace ToolChoice {
   }
 }
 
-const requestSchema = Schema.Struct({
+export class LLMRequest extends Schema.Class<LLMRequest>("LLM.Request")({
   id: Schema.optional(Schema.String),
   model: LanguageModelSchema,
   system: Schema.Array(SystemPart),
@@ -321,26 +286,12 @@ const requestSchema = Schema.Struct({
   // Stable cache affinity for protocols that support provider-managed prompt caching.
   promptCacheKey: Schema.optional(Schema.String),
   metadata: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
-})
-
-export class LLMRequest<Model extends LanguageModel = LanguageModel> extends Schema.Class<LLMRequest>("LLM.Request")(
-  requestSchema.fields,
-) {
-  declare readonly model: Model
-
-  // Preserve model inference instead of inheriting the schema's erased constructor signature.
-  // oxlint-disable-next-line no-useless-constructor
-  constructor(input: LLMRequest.Input<Model>) {
-    super(input)
-  }
-}
+}) {}
 
 export namespace LLMRequest {
-  export type Input<Model extends LanguageModel = LanguageModel> = Omit<typeof requestSchema.Type, "model"> & {
-    readonly model: Model
-  }
+  export type Input = ConstructorParameters<typeof LLMRequest>[0]
 
-  export const input = <Model extends LanguageModel>(request: LLMRequest<Model>): Input<Model> => ({
+  export const input = (request: LLMRequest): Input => ({
     id: request.id,
     model: request.model,
     system: request.system,
@@ -355,16 +306,7 @@ export namespace LLMRequest {
     metadata: request.metadata,
   })
 
-  export function update<Model extends LanguageModel>(
-    request: LLMRequest,
-    patch: Partial<Input<Model>> & { readonly model: Model },
-  ): LLMRequest<Model>
-  export function update<Model extends LanguageModel>(
-    request: LLMRequest<Model>,
-    patch: Partial<Omit<Input, "model">> & { readonly model?: undefined },
-  ): LLMRequest<Model>
-  export function update(request: LLMRequest, patch: Partial<Input>): LLMRequest
-  export function update(request: LLMRequest, patch: Partial<Input>) {
+  export const update = (request: LLMRequest, patch: Partial<Input>) => {
     if (Object.keys(patch).length === 0) return request
     return new LLMRequest({
       ...input(request),

packages/ai/src/schema/options.ts

@@ -1,6 +1,6 @@
 import { Schema } from "effect"
 import { ModelID, ProviderID } from "./ids.js"
-import type { AnyRoute, CompactOperation } from "../route/client.js"
+import type { AnyRoute } from "../route/client.js"
 import { isRecord } from "../utils/record.js"
 
 export const JsonSchema = Schema.Record(Schema.String, Schema.Unknown)
@@ -173,18 +173,15 @@ export namespace LanguageModelCompatibility {
     input instanceof LanguageModelCompatibility ? input : new LanguageModelCompatibility(input)
 }
 
-export class LanguageModel<
-  Options extends ProviderOptions = ProviderOptions,
-  Compact extends CompactOperation | undefined = CompactOperation | undefined,
-> {
+export class LanguageModel<Options extends ProviderOptions = ProviderOptions> {
   declare protected readonly _ProviderOptions: Options
   readonly id: ModelID
   readonly provider: ProviderID
-  readonly route: AnyRoute<Compact>
+  readonly route: AnyRoute
   readonly defaults?: LanguageModelDefaults
   readonly compatibility?: LanguageModelCompatibility
 
-  constructor(input: LanguageModel.ConstructorInput<Compact>) {
+  constructor(input: LanguageModel.ConstructorInput) {
     this.id = input.id
     this.provider = input.provider
     this.route = input.route
@@ -192,11 +189,8 @@ export class LanguageModel<
     this.compatibility = input.compatibility
   }
 
-  static make<
-    Options extends ProviderOptions = ProviderOptions,
-    Compact extends CompactOperation | undefined = CompactOperation | undefined,
-  >(input: LanguageModel.Input<Compact>) {
-    return new LanguageModel<Options, Compact>({
+  static make<Options extends ProviderOptions = ProviderOptions>(input: LanguageModel.Input) {
+    return new LanguageModel<Options>({
       id: ModelID.make(input.id),
       provider: ProviderID.make(input.provider),
       route: input.route,
@@ -206,9 +200,7 @@ export class LanguageModel<
     })
   }
 
-  static input<Options extends ProviderOptions, Compact extends CompactOperation | undefined>(
-    model: LanguageModel<Options, Compact>,
-  ): LanguageModel.ConstructorInput<Compact> {
+  static input<Options extends ProviderOptions>(model: LanguageModel<Options>): LanguageModel.ConstructorInput {
     return {
       id: model.id,
       provider: model.provider,
@@ -218,41 +210,25 @@ export class LanguageModel<
     }
   }
 
-  static update<Options extends ProviderOptions, Compact extends CompactOperation | undefined>(
-    model: LanguageModel<Options>,
-    patch: Partial<LanguageModel.Input<Compact>> & { readonly route: AnyRoute<Compact> },
-  ): LanguageModel<Options, Compact>
-  static update<Options extends ProviderOptions, Compact extends CompactOperation | undefined>(
-    model: LanguageModel<Options, Compact>,
-    patch: Partial<Omit<LanguageModel.Input, "route">> & { readonly route?: undefined },
-  ): LanguageModel<Options, Compact>
-  static update<Options extends ProviderOptions>(
-    model: LanguageModel<Options>,
-    patch: Partial<LanguageModel.Input>,
-  ): LanguageModel<Options>
   static update<Options extends ProviderOptions>(model: LanguageModel<Options>, patch: Partial<LanguageModel.Input>) {
     if (Object.keys(patch).length === 0) return model
     return LanguageModel.make<Options>({
       ...LanguageModel.input(model),
       ...patch,
-      route: patch.route ?? model.route,
     })
   }
 }
 
 export namespace LanguageModel {
-  export type ConstructorInput<Compact extends CompactOperation | undefined = CompactOperation | undefined> = {
+  export type ConstructorInput = {
     readonly id: ModelID
     readonly provider: ProviderID
-    readonly route: AnyRoute<Compact>
+    readonly route: AnyRoute
     readonly defaults?: LanguageModelDefaults
     readonly compatibility?: LanguageModelCompatibility
   }
 
-  export type Input<Compact extends CompactOperation | undefined = CompactOperation | undefined> = Omit<
-    ConstructorInput<Compact>,
-    "id" | "provider" | "defaults" | "compatibility"
-  > & {
+  export type Input = Omit<ConstructorInput, "id" | "provider" | "defaults" | "compatibility"> & {
     readonly id: string | ModelID
     readonly provider: string | ProviderID
     readonly defaults?: LanguageModelDefaults.Input

packages/ai/src/testing.ts

@@ -4,7 +4,6 @@ import { LLMClient } from "./route/client.js"
 import {
   LLMEvent,
   LLMResponse,
-  CompactionResponse,
   type FinishReasonDetails,
   type AIError,
   type LLMRequest,
@@ -13,7 +12,7 @@ import {
 } from "./schema/index.js"
 import { Context, Deferred, Effect, Latch, Layer, Queue, Scope, Stream } from "effect"
 
-export type Response = readonly LLMEvent[] | Stream.Stream<LLMEvent, AIError> | CompactionResponse
+export type Response = readonly LLMEvent[] | Stream.Stream<LLMEvent, AIError>
 
 export type Gate = Readonly<{ started: Effect.Effect<void>; release: Effect.Effect<void> }>
 
@@ -100,6 +99,8 @@ export const failAfter = (error: AIError, ...events: readonly LLMEvent[]) =>
 
 export const hangAfter = (...events: readonly LLMEvent[]) => Stream.concat(Stream.fromIterable(events), Stream.never)
 
+const toStream = (response: Response) => (Stream.isStream(response) ? response : Stream.fromIterable(response))
+
 const make = (options: LayerOptions) =>
   Effect.sync(() => {
     const requests: LLMRequest[] = []
@@ -112,41 +113,26 @@ const make = (options: LayerOptions) =>
         requests.length >= count ? Effect.void : Deferred.await(started).pipe(Effect.andThen(wait(count))),
       )
 
-    const take = (request: LLMRequest) =>
-      Effect.suspend(() => {
+    const stream: ClientInterface["stream"] = (request) =>
+      Stream.suspend(() => {
         const count = requests.push(options.transformRequest?.(request) ?? request)
         const waiting = started
         started = Deferred.makeUnsafe()
         const gate = activeGate
         try {
           const response = responses.shift() ?? (typeof fallback === "function" ? fallback(request) : fallback)
-          if (!response) return Effect.die(new Error(`TestLLM has no response for request ${count}`))
-          if (!gate) return Effect.succeed(response)
-          return Queue.offer(gate.started, undefined).pipe(Effect.andThen(gate.release.await), Effect.as(response))
+          if (!response) return Stream.die(new Error(`TestLLM has no response for request ${count}`))
+          const streamed = toStream(response)
+          if (!gate) return streamed
+          return Stream.unwrap(
+            Queue.offer(gate.started, undefined).pipe(Effect.andThen(gate.release.await), Effect.as(streamed)),
+          )
         } finally {
           // Waiters can resume synchronously; assign the reply and gate before notifying them.
           Deferred.doneUnsafe(waiting, Effect.void)
         }
       })
-    const stream: ClientInterface["stream"] = (request) =>
-      Stream.unwrap(
-        take(request).pipe(
-          Effect.map((response) => {
-            if (response instanceof CompactionResponse)
-              return Stream.die("TestLLM generation requires an event response")
-            return Stream.isStream(response) ? response : Stream.fromIterable(response)
-          }),
-        ),
-      )
     const test = Test.of({
-      compact: (request) =>
-        take(request).pipe(
-          Effect.flatMap((response) =>
-            response instanceof CompactionResponse
-              ? Effect.succeed(response)
-              : Effect.die("TestLLM compaction requires a CompactionResponse"),
-          ),
-        ),
       stream,
       generate: (request) =>
         stream(request).pipe(

packages/ai/src/tool-history.ts

@@ -56,7 +56,6 @@ function normalizeToolMessage(message: Message, pending: Map<string, ToolCallPar
     role: message.role,
     content,
     metadata: message.metadata,
-    providerMetadata: message.providerMetadata,
     native: message.native,
   })
 }

packages/ai/test/cache-policy.test.ts

@@ -126,38 +126,6 @@ describe("applyCachePolicy", () => {
     }),
   )
 
-  for (const fixture of [
-    { name: "default", cache: undefined, control: { type: "ephemeral" } },
-    { name: "auto", cache: "auto", control: { type: "ephemeral" } },
-    {
-      name: "explicit one-hour",
-      cache: { tools: true, system: true, messages: { tail: 1 }, ttlSeconds: 3600 },
-      control: { type: "ephemeral", ttl: "1h" },
-    },
-    { name: "disabled", cache: "none", control: undefined },
-  ] as const) {
-    it.effect(`Bedrock Messages respects ${fixture.name} caching`, () =>
-      Effect.gen(function* () {
-        const prepared = yield* compileRequest(
-          LLM.request({
-            model: AmazonBedrock.configure({ apiKey: "test" }).messages("anthropic.claude-opus-4-6-v1"),
-            system: "Stable instructions",
-            tools: [
-              { name: "lookup", description: "Look up a value", inputSchema: { type: "object", properties: {} } },
-            ],
-            prompt: "hello",
-            cache: fixture.cache,
-          }),
-        )
-        expect(prepared.body).toMatchObject({
-          tools: [{ name: "lookup", cache_control: fixture.control }],
-          system: [{ type: "text", text: "Stable instructions", cache_control: fixture.control }],
-          messages: [{ role: "user", content: [{ type: "text", text: "hello", cache_control: fixture.control }] }],
-        })
-      }),
-    )
-  }
-
   it.effect("'auto' is a no-op on Gemini (out-of-band caching protocol)", () =>
     Effect.gen(function* () {
       const prepared = yield* compileRequest(

packages/ai/test/compaction-http.test.ts

@@ -1,97 +0,0 @@
-import { expect } from "bun:test"
-import { Effect } from "effect"
-import { FetchHttpClient } from "effect/unstable/http"
-import { LLM, LLMRequest, Message } from "../src/index.js"
-import { LLMClient } from "../src/route/client.js"
-import { OpenAI } from "../src/providers.js"
-import { testEffect } from "./lib/effect.js"
-import { runtimeLayer } from "./lib/http.js"
-import { sseEvents } from "./lib/sse.js"
-
-testEffect(runtimeLayer(FetchHttpClient.layer)).live("compaction and a tool loop work end to end over HTTP", () =>
-  Effect.gen(function* () {
-    const checkpoint = { type: "compaction", id: "cmp_local", encrypted_content: "opaque-local-state" }
-    const calls: string[] = []
-    const server = yield* Effect.acquireRelease(
-      Effect.sync(() =>
-        Bun.serve({
-          hostname: "127.0.0.1",
-          port: 0,
-          async fetch(request) {
-            const path = new URL(request.url).pathname
-            calls.push(path)
-            const body = await request.json()
-            expect(request.headers.get("authorization")).toBe("Bearer fixture")
-            if (path === "/v1/responses/compact") {
-              expect(body.stream).toBeUndefined()
-              return Response.json({
-                object: "response.compaction",
-                output: [checkpoint],
-                usage: { input_tokens: 100, output_tokens: 10, total_tokens: 110 },
-              })
-            }
-            expect(body.input[0]).toEqual(checkpoint)
-            expect(body.stream).toBe(true)
-            if (calls.length === 2)
-              return new Response(
-                sseEvents(
-                  {
-                    type: "response.output_item.done",
-                    item: { type: "function_call", id: "fc_1", call_id: "call_1", name: "lookup", arguments: "{}" },
-                  },
-                  { type: "response.completed", response: { id: "resp_1" } },
-                ),
-                { headers: { "content-type": "text/event-stream" } },
-              )
-            expect(body.input.at(-2)).toMatchObject({ type: "function_call", call_id: "call_1" })
-            expect(body.input.at(-1)).toEqual({ type: "function_call_output", call_id: "call_1", output: "42" })
-            const output = sseEvents(
-              { type: "response.output_item.added", item: { type: "message", id: "msg_1" } },
-              { type: "response.output_text.delta", item_id: "msg_1", delta: "The answer is 42." },
-              {
-                type: "response.output_item.done",
-                item: { type: "message", id: "msg_1", content: [{ type: "output_text", text: "The answer is 42." }] },
-              },
-              { type: "response.completed", response: { id: "resp_2" } },
-            )
-            return new Response(
-              new ReadableStream({
-                start(controller) {
-                  controller.enqueue(new TextEncoder().encode(output.slice(0, 37)))
-                  controller.enqueue(new TextEncoder().encode(output.slice(37)))
-                  controller.close()
-                },
-              }),
-              { headers: { "content-type": "text/event-stream" } },
-            )
-          },
-        }),
-      ),
-      (server) => Effect.sync(() => server.stop(true)),
-    )
-    const model = OpenAI.configure({ apiKey: "fixture", baseURL: `http://127.0.0.1:${server.port}/v1` }).responses(
-      "fixture",
-    )
-    const request = LLM.request({
-      model,
-      prompt: "original",
-      tools: [{ name: "lookup", description: "Lookup a number", inputSchema: { type: "object", properties: {} } }],
-    })
-    const compacted = yield* LLMClient.compact(request)
-    const messages = [...compacted.messages, Message.user("Look up the answer")]
-    const first = yield* LLMClient.generate(LLMRequest.update(request, { messages }))
-    expect(first.toolCalls).toHaveLength(1)
-    const call = first.toolCalls[0]!
-    const last = yield* LLMClient.generate(
-      LLMRequest.update(request, {
-        messages: [
-          ...messages,
-          first.message,
-          Message.tool({ id: call.id, name: call.name, result: "42", resultType: "text" }),
-        ],
-      }),
-    )
-    expect(last.text).toBe("The answer is 42.")
-    expect(calls).toEqual(["/v1/responses/compact", "/v1/responses", "/v1/responses"])
-  }),
-)

packages/ai/test/compaction.test.ts

@@ -1,64 +0,0 @@
-import { expect, test } from "bun:test"
-import { Schema } from "effect"
-import { CompactionPart, LLMEvent, LLMResponse, Message, ProviderID } from "../src/schema/index.js"
-import { LLM, LLMClient, LLMRequest, LanguageModel } from "../src/index.js"
-import { OpenAI, Anthropic } from "../src/providers.js"
-
-test("runtime capability checks follow model and route updates", () => {
-  const supported = OpenAI.configure({ apiKey: "test" }).responses("fixture")
-  const unsupported = Anthropic.configure({ apiKey: "test" }).model("fixture")
-  const request = LLM.request({ model: supported, prompt: "hello" })
-  expect(LLMClient.canCompact(request)).toBe(true)
-  expect(LLMClient.canCompact(LLMRequest.update(request, { messages: [] }))).toBe(true)
-  expect(LLMClient.canCompact(LLMRequest.update(request, { model: unsupported }))).toBe(false)
-  expect(
-    LLMClient.canCompact(LLM.request({ model: LanguageModel.update(supported, { route: unsupported.route }) })),
-  ).toBe(false)
-  expect(LLMClient.canCompact(LLM.request({ model: LanguageModel.update(supported, { route: undefined }) }))).toBe(true)
-})
-
-test("compaction survives event assembly and message serialization without becoming text", () => {
-  const part = CompactionPart.make({
-    provider: ProviderID.make("openai"),
-    id: "cmp_1",
-    encrypted: "opaque",
-  })
-  const response = LLMResponse.fromEvents([
-    LLMEvent.textStart({ id: "before" }),
-    LLMEvent.textDelta({ id: "before", text: "Before" }),
-    LLMEvent.textEnd({ id: "before" }),
-    part,
-    LLMEvent.textStart({ id: "after" }),
-    LLMEvent.textDelta({ id: "after", text: "After" }),
-    LLMEvent.textEnd({ id: "after" }),
-    LLMEvent.finish({ reason: { normalized: "stop" } }),
-  ])!
-  expect(response.message.content.map((part) => part.type)).toEqual(["text", "compaction", "text"])
-  expect(response.text).toBe("BeforeAfter")
-  expect(response.reasoning).toBe("")
-  expect(response.events.filter(LLMEvent.is.compaction)).toEqual([part])
-  const codec = Schema.fromJsonString(Message)
-  expect(Schema.decodeSync(codec)(Schema.encodeSync(codec)(response.message))).toEqual(response.message)
-})
-
-test("compaction requires exactly one typed representation", () => {
-  const provider = ProviderID.make("anthropic")
-  expect(CompactionPart.make({ provider, text: null })).toEqual({ type: "compaction", provider, text: null })
-  const decode = Schema.decodeUnknownSync(CompactionPart)
-  expect(() => decode({ type: "compaction", provider })).toThrow()
-  expect(() => decode({ type: "compaction", provider, text: "summary", encrypted: "opaque" })).toThrow()
-})
-
-test("tagged content and event guards accept both checkpoint representations", () => {
-  for (const part of [
-    CompactionPart.make({ provider: ProviderID.make("openai"), encrypted: "opaque" }),
-    CompactionPart.make({ provider: ProviderID.make("anthropic"), text: "summary" }),
-    CompactionPart.make({ provider: ProviderID.make("anthropic"), text: null }),
-  ]) {
-    expect(LLMEvent.is.compaction(part)).toBe(true)
-    expect(LLMEvent.guards.compaction(part)).toBe(true)
-    const codec = Schema.fromJsonString(Message)
-    const message = Message.assistant(part)
-    expect(Schema.decodeSync(codec)(Schema.encodeSync(codec)(message))).toEqual(message)
-  }
-})

packages/ai/test/provider-options/compaction.types.ts

@@ -1,154 +0,0 @@
-import { Effect } from "effect"
-import {
-  CompactionPart,
-  LanguageModel,
-  LLM,
-  LLMClient,
-  LLMEvent,
-  LLMRequest,
-  Message,
-  ProviderID,
-} from "../../src/index.js"
-import {
-  OpenAI,
-  Azure,
-  XAI,
-  Anthropic,
-  AmazonBedrock,
-  AmazonBedrockMantle,
-  OpenAICompatibleResponses,
-} from "../../src/providers.js"
-
-const openai = OpenAI.configure({
-  apiKey: "test",
-  providerOptions: { contextManagement: [{ type: "compaction", compactThreshold: 100000 }] },
-}).responses("gpt-5.3-codex")
-LLMClient.compact(LLM.request({ model: openai, prompt: "hello" }))
-
-for (const model of [
-  OpenAI.configure().responses("fixture"),
-  Azure.configure({ resourceName: "test" }).responses("fixture"),
-  XAI.configure().responses("fixture"),
-  OpenAI.model("fixture", {}),
-  Azure.responsesModel("fixture", { resourceName: "test" }),
-  XAI.model("fixture", {}),
-  openai.route.with({ headers: { "x-test": "test" } }).model({ id: "fixture" }),
-  LanguageModel.update(openai, { defaults: { generation: { maxTokens: 100 } } }),
-  LanguageModel.make(LanguageModel.input(openai)),
-]) {
-  LLMClient.compact(LLM.request({ model, prompt: "hello" }))
-}
-
-const unsupported = {
-  anthropic: LLM.request({ model: Anthropic.configure().model("fixture") }),
-  openaiChat: LLM.request({ model: OpenAI.configure().chat("fixture") }),
-  azureChat: LLM.request({ model: Azure.configure({ resourceName: "test" }).chat("fixture") }),
-  xaiChat: LLM.request({ model: XAI.configure().chat("fixture") }),
-  converse: LLM.request({ model: AmazonBedrock.configure().model("fixture") }),
-  bedrockMessages: LLM.request({ model: AmazonBedrock.configure().messages("fixture") }),
-  mantle: LLM.request({ model: AmazonBedrockMantle.configure().responses("fixture") }),
-  compatible: LLM.request({
-    model: OpenAICompatibleResponses.configure({ baseURL: "https://example.com" }).model("fixture"),
-  }),
-}
-// @ts-expect-error Anthropic has no standalone compact endpoint.
-LLMClient.compact(unsupported.anthropic)
-// @ts-expect-error Chat does not expose Responses compaction.
-LLMClient.compact(unsupported.openaiChat)
-// @ts-expect-error Azure Chat does not expose Responses compaction.
-LLMClient.compact(unsupported.azureChat)
-// @ts-expect-error xAI Chat does not expose Responses compaction.
-LLMClient.compact(unsupported.xaiChat)
-// @ts-expect-error Converse has no standalone compact endpoint.
-LLMClient.compact(unsupported.converse)
-// @ts-expect-error Bedrock Messages has no standalone compact endpoint.
-LLMClient.compact(unsupported.bedrockMessages)
-// @ts-expect-error Mantle does not inherit the OpenAI compact endpoint.
-LLMClient.compact(unsupported.mantle)
-// @ts-expect-error Protocol compatibility does not guarantee endpoint support.
-LLMClient.compact(unsupported.compatible)
-LLMClient.Service.use((client) => {
-  // @ts-expect-error The service enforces the same capability as the convenience function.
-  return client.compact(unsupported.anthropic)
-})
-
-const request = LLM.request({ model: openai, prompt: "hello" })
-LLMClient.compact(LLMRequest.update(request, { messages: [Message.user("continue")] }))
-LLMClient.compact(new LLMRequest(LLMRequest.input(request)))
-const switched = LLMRequest.update(request, { model: Anthropic.configure().model("fixture") })
-// @ts-expect-error Switching models replaces, rather than inherits, the capability.
-LLMClient.compact(switched)
-LLMClient.compact(LLMRequest.update(switched, { model: openai }))
-LLMClient.compact(
-  // @ts-expect-error Replacing the route also replaces compaction capability.
-  LLM.request({ model: LanguageModel.update(openai, { route: Anthropic.configure().model("fixture").route }) }),
-)
-
-declare const dynamicModel: LanguageModel
-declare const dynamicPatch: Partial<LLMRequest.Input>
-const dynamicRequest = LLM.request({ model: dynamicModel, prompt: "hello" })
-// @ts-expect-error A dynamically selected model must be narrowed first.
-LLMClient.compact(dynamicRequest)
-if (LLMClient.canCompact(dynamicRequest)) LLMClient.compact(dynamicRequest)
-// @ts-expect-error An optional model override cannot retain the old capability statically.
-LLMClient.compact(LLMRequest.update(request, dynamicPatch))
-
-const checkpoint = CompactionPart.make({ provider: ProviderID.make("openai"), id: "cmp_1", encrypted: "opaque" })
-const provider = ProviderID.make("anthropic")
-CompactionPart.make({ provider, text: "summary" })
-CompactionPart.make({ provider, text: null })
-// @ts-expect-error A checkpoint must have a representation.
-CompactionPart.make({ provider })
-// @ts-expect-error Encrypted and summary representations are mutually exclusive.
-CompactionPart.make({ provider, encrypted: "opaque", text: "summary" })
-// @ts-expect-error A failed summary cannot also carry encrypted content.
-LLMEvent.compaction({ provider, encrypted: "opaque", text: null })
-// @ts-expect-error The canonical message type also enforces the invariant.
-Message.assistant({ type: "compaction", provider })
-if (checkpoint.encrypted !== undefined) {
-  checkpoint.encrypted satisfies string
-  checkpoint.text satisfies undefined
-}
-if (checkpoint.text !== undefined) {
-  checkpoint.text satisfies string | null
-  checkpoint.encrypted satisfies undefined
-}
-checkpoint.encrypted
-// @ts-expect-error Compaction parts do not contain a generic provider payload.
-checkpoint.value
-LLMClient.compact(LLM.request({ model: openai, prompt: "hello" })).pipe(
-  Effect.map((result) => {
-    result.messages
-    // @ts-expect-error Compaction returns replacement history, not a synthetic assistant message.
-    result.message
-  }),
-)
-LLM.request({
-  model: openai,
-  providerOptions: {
-    // @ts-expect-error A token threshold is numeric.
-    contextManagement: [{ type: "compaction", compactThreshold: "100000" }],
-  },
-})
-for (const model of [
-  Anthropic.configure().model("claude-opus-4-6"),
-  AmazonBedrock.configure().messages("anthropic.claude-opus-4-6-v1"),
-]) {
-  LLM.request({
-    model,
-    providerOptions: {
-      contextManagement: {
-        edits: [
-          { type: "compact_20260112", pauseAfterCompaction: true, instructions: "Summarize without using tools" },
-        ],
-      },
-    },
-  })
-  LLM.request({
-    model,
-    providerOptions: {
-      // @ts-expect-error A pause setting is boolean.
-      contextManagement: { edits: [{ type: "compact_20260112", pauseAfterCompaction: "yes" }] },
-    },
-  })
-}

packages/ai/test/provider/anthropic-compaction.test.ts

@@ -1,170 +0,0 @@
-import { expect } from "bun:test"
-import { Effect, Schema } from "effect"
-import { LLM, LLMRequest, Message } from "../../src/index.js"
-import { LLMClient } from "../../src/route/client.js"
-import { Anthropic, GoogleVertexMessages } from "../../src/providers/index.js"
-import { testEffect } from "../lib/effect.js"
-import { dynamicResponse, fixedResponse } from "../lib/http.js"
-import { sseEvents } from "../lib/sse.js"
-
-for (const fixture of [
-  {
-    name: "empty iterations fall back to top-level usage",
-    usage: { input_tokens: 2, output_tokens: 3, cache_read_input_tokens: null, iterations: [] },
-    expected: { inputTokens: 2, outputTokens: 3, totalTokens: 5, contextTokens: undefined },
-  },
-  {
-    name: "compaction-only usage has no post-compaction context size",
-    usage: {
-      input_tokens: 0,
-      output_tokens: 0,
-      iterations: [{ type: "compaction", input_tokens: 7, cache_read_input_tokens: 3, output_tokens: 2 }],
-    },
-    expected: { inputTokens: 10, outputTokens: 2, totalTokens: 12, contextTokens: undefined },
-  },
-  {
-    name: "partially reported iterations preserve known totals",
-    usage: {
-      iterations: [
-        { type: "compaction", input_tokens: 7, cache_creation_input_tokens: 2 },
-        { type: "message", output_tokens: 3 },
-      ],
-    },
-    expected: { inputTokens: 9, outputTokens: 3, totalTokens: 12, contextTokens: undefined },
-  },
-  {
-    name: "missing counters remain unknown rather than zero",
-    usage: { iterations: [{ type: "message" }] },
-    expected: { inputTokens: undefined, outputTokens: undefined, totalTokens: undefined, contextTokens: undefined },
-  },
-]) {
-  testEffect(
-    fixedResponse(
-      sseEvents(
-        { type: "message_start", message: { usage: fixture.usage } },
-        { type: "message_delta", delta: { stop_reason: "end_turn" } },
-        { type: "message_stop" },
-      ),
-    ),
-  ).effect(fixture.name, () =>
-    Effect.gen(function* () {
-      const result = yield* LLMClient.generate(
-        LLM.request({
-          model: Anthropic.configure({ apiKey: "test" }).model("claude-opus-4-6"),
-          prompt: "hello",
-        }),
-      )
-      expect(result.usage).toMatchObject(fixture.expected)
-    }),
-  )
-}
-
-for (const model of [
-  Anthropic.configure({ apiKey: "test" }).model("claude-opus-4-6"),
-  GoogleVertexMessages.configure({ accessToken: "test", project: "test" }).model("claude-opus-4-6"),
-]) {
-  for (const summary of ["Summary of the conversation", null]) {
-    const block = { type: "compaction", content: summary }
-    testEffect(
-      dynamicResponse(({ request, text, respond }) =>
-        Effect.sync(() => {
-          const body = JSON.parse(text)
-          expect(request.headers["anthropic-beta"]).toBe("existing-beta,compact-2026-01-12")
-          if (body.messages.length === 1) {
-            expect(body.context_management.edits).toEqual([
-              {
-                type: "compact_20260112",
-                trigger: { type: "input_tokens", value: 50000 },
-                pause_after_compaction: true,
-              },
-            ])
-          }
-          if (body.messages.length > 1) {
-            expect(body.messages[1].content).toEqual([block])
-            expect(body.context_management).toBeUndefined()
-          }
-          return respond(
-            sseEvents(
-              { type: "message_start", message: { usage: { input_tokens: 50000, output_tokens: 0 } } },
-              { type: "content_block_start", index: 0, content_block: { type: "compaction", content: null } },
-              { type: "content_block_delta", index: 0, delta: { type: "compaction_delta", content: summary } },
-              { type: "content_block_stop", index: 0 },
-              {
-                type: "message_delta",
-                delta: { stop_reason: "compaction" },
-                usage: {
-                  input_tokens: 1000,
-                  output_tokens: 5,
-                  iterations: [
-                    { type: "compaction", input_tokens: 50000, output_tokens: 1000, cache_read_input_tokens: 10 },
-                    { type: "message", input_tokens: 1000, output_tokens: 5 },
-                  ],
-                },
-              },
-              { type: "message_stop" },
-            ),
-            { headers: { "content-type": "text/event-stream" } },
-          )
-        }),
-      ),
-    ).effect(
-      `${model.provider} replays ${summary === null ? "failed" : "successful"} compaction with billing and context usage`,
-      () =>
-        Effect.gen(function* () {
-          const request = LLM.request({
-            model,
-            prompt: "hello",
-            http: { headers: { "anthropic-beta": "existing-beta" } },
-            providerOptions: {
-              contextManagement: {
-                edits: [
-                  {
-                    type: "compact_20260112",
-                    trigger: { type: "input_tokens", value: 50000 },
-                    pauseAfterCompaction: true,
-                  },
-                ],
-              },
-            },
-          })
-          const first = yield* LLMClient.generate(request)
-          expect(first.finishReason.raw).toBe("compaction")
-          expect(first.message.content).toEqual([{ type: "compaction", provider: model.provider, text: summary }])
-          expect(first.text).toBe("")
-          expect(first.usage?.inputTokens).toBe(51010)
-          expect(first.usage?.outputTokens).toBe(1005)
-          expect(first.usage?.totalTokens).toBe(52015)
-          expect(first.usage?.contextTokens).toBe(1000)
-          const codec = Schema.fromJsonString(Message)
-          const message = Schema.decodeSync(codec)(Schema.encodeSync(codec)(first.message))
-          yield* LLMClient.generate(
-            LLMRequest.update(request, {
-              providerOptions: {},
-              messages: [...request.messages, message, Message.user("continue")],
-            }),
-          )
-        }),
-    )
-  }
-}
-
-for (const events of [
-  [{ type: "content_block_start", index: 0, content_block: { type: "compaction", content: 42 } }],
-  [{ type: "content_block_delta", index: 0, delta: { type: "compaction_delta", content: "no start" } }],
-  [
-    { type: "content_block_start", index: 0, content_block: { type: "compaction", content: null } },
-    { type: "message_stop" },
-  ],
-]) {
-  testEffect(fixedResponse(sseEvents(...events))).effect(
-    `rejects malformed compaction lifecycle: ${JSON.stringify(events)}`,
-    () =>
-      Effect.gen(function* () {
-        const error = yield* LLMClient.generate(
-          LLM.request({ model: Anthropic.configure({ apiKey: "test" }).model("claude-opus-4-6"), prompt: "hello" }),
-        ).pipe(Effect.flip)
-        expect(error.reason._tag).toBe("InvalidProviderOutput")
-        expect(error.reason.http?.status).toBe(200)
-      }),
-  )
-}

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

@@ -1,69 +0,0 @@
-import { EventStreamCodec } from "@smithy/eventstream-codec"
-import { fromUtf8, toUtf8 } from "@smithy/util-utf8"
-import { expect } from "bun:test"
-import { Effect } from "effect"
-import { LLM, LLMRequest, Message } from "../../src/index.js"
-import { LLMClient } from "../../src/route/client.js"
-import { AmazonBedrock } from "../../src/providers/index.js"
-import { testEffect } from "../lib/effect.js"
-import { dynamicResponse } from "../lib/http.js"
-
-const codec = new EventStreamCodec(toUtf8, fromUtf8)
-const frame = (event: object) =>
-  codec.encode({
-    headers: { ":message-type": { type: "string", value: "event" }, ":event-type": { type: "string", value: "chunk" } },
-    body: new TextEncoder().encode(JSON.stringify({ bytes: Buffer.from(JSON.stringify(event)).toString("base64") })),
-  })
-const response = Buffer.concat(
-  [
-    { type: "message_start", message: { usage: { input_tokens: 60000 } } },
-    { type: "content_block_start", index: 0, content_block: { type: "compaction", content: null } },
-    { type: "content_block_delta", index: 0, delta: { type: "compaction_delta", content: "Summary" } },
-    { type: "content_block_stop", index: 0 },
-    { type: "content_block_start", index: 1, content_block: { type: "text", text: "" } },
-    { type: "content_block_delta", index: 1, delta: { type: "text_delta", text: "Hello" } },
-    { type: "content_block_stop", index: 1 },
-    { type: "message_delta", delta: { stop_reason: "end_turn" }, usage: { output_tokens: 10 } },
-    { type: "message_stop" },
-  ].map(frame),
-)
-
-for (const auth of [
-  { apiKey: "test" },
-  { credentials: { accessKeyId: "test", secretAccessKey: "test", region: "us-west-2" } },
-]) {
-  testEffect(
-    dynamicResponse(({ request, text, respond }) =>
-      Effect.sync(() => {
-        expect(request.url).toBe(
-          "https://bedrock-runtime.us-west-2.amazonaws.com/model/anthropic.claude-opus-4-6-v1%3A0/invoke-with-response-stream",
-        )
-        expect(request.headers.authorization).toStartWith(auth.apiKey ? "Bearer test" : "AWS4-HMAC-SHA256")
-        const body = JSON.parse(text)
-        expect(body.model).toBeUndefined()
-        expect(body.stream).toBeUndefined()
-        expect(body.anthropic_version).toBe("bedrock-2023-05-31")
-        expect(body.anthropic_beta).toEqual(["compact-2026-01-12"])
-        expect(body.context_management.edits).toEqual([{ type: "compact_20260112" }])
-        if (body.messages.length > 1)
-          expect(body.messages[1].content[0]).toEqual({ type: "compaction", content: "Summary" })
-        return respond(response, { headers: { "content-type": "application/vnd.amazon.eventstream" } })
-      }),
-    ),
-  ).effect(`Bedrock Messages compaction round trip with ${auth.apiKey ? "bearer" : "SigV4"} authentication`, () =>
-    Effect.gen(function* () {
-      const model = AmazonBedrock.configure({ ...auth, region: "us-west-2" }).messages("anthropic.claude-opus-4-6-v1:0")
-      const request = LLM.request({
-        model,
-        prompt: "hello",
-        providerOptions: { contextManagement: { edits: [{ type: "compact_20260112" }] } },
-      })
-      const first = yield* LLMClient.generate(request)
-      expect(first.text).toBe("Hello")
-      expect(first.message.content.map((part) => part.type)).toEqual(["compaction", "text"])
-      yield* LLMClient.generate(
-        LLMRequest.update(request, { messages: [...request.messages, first.message, Message.user("continue")] }),
-      )
-    }),
-  )
-}

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/bedrock-messages-basic.test.ts

@@ -1,166 +0,0 @@
-import { EventStreamCodec } from "@smithy/eventstream-codec"
-import { fromUtf8, toUtf8 } from "@smithy/util-utf8"
-import { expect } from "bun:test"
-import { Effect } from "effect"
-import { LLM, LLMRequest, Message } from "../../src/index.js"
-import { LLMClient, compileRequest } from "../../src/route/client.js"
-import { AmazonBedrock } from "../../src/providers/index.js"
-import { it, testEffect } from "../lib/effect.js"
-import { dynamicResponse, fixedResponse } from "../lib/http.js"
-
-const codec = new EventStreamCodec(toUtf8, fromUtf8)
-const response = Buffer.concat(
-  [
-    { type: "message_start", message: { usage: { input_tokens: 10 } } },
-    { type: "content_block_start", index: 0, content_block: { type: "text", text: "" } },
-    { type: "content_block_delta", index: 0, delta: { type: "text_delta", text: "Hello" } },
-    { type: "content_block_stop", index: 0 },
-    { type: "message_delta", delta: { stop_reason: "end_turn" }, usage: { output_tokens: 2 } },
-    { type: "message_stop" },
-  ].map((event) =>
-    codec.encode({
-      headers: {
-        ":message-type": { type: "string", value: "event" },
-        ":event-type": { type: "string", value: "chunk" },
-      },
-      body: new TextEncoder().encode(JSON.stringify({ bytes: Buffer.from(JSON.stringify(event)).toString("base64") })),
-    }),
-  ),
-)
-
-for (const auth of [
-  { apiKey: "test" },
-  { credentials: { accessKeyId: "test", secretAccessKey: "test", region: "us-west-2" } },
-]) {
-  testEffect(
-    dynamicResponse(({ request, text, respond }) =>
-      Effect.sync(() => {
-        expect(request.url).toBe(
-          "https://bedrock-runtime.us-west-2.amazonaws.com/model/anthropic.claude-opus-4-6-v1%3A0/invoke-with-response-stream",
-        )
-        expect(request.headers.authorization).toStartWith(auth.apiKey ? "Bearer test" : "AWS4-HMAC-SHA256")
-        const body = JSON.parse(text)
-        expect(body.model).toBeUndefined()
-        expect(body.stream).toBeUndefined()
-        expect(body.anthropic_version).toBe("bedrock-2023-05-31")
-        expect(body.anthropic_beta).toEqual(["existing-beta"])
-        if (body.messages.length > 1) expect(body.messages[1].content).toEqual([{ type: "text", text: "Hello" }])
-        return respond(response, { headers: { "content-type": "application/vnd.amazon.eventstream" } })
-      }),
-    ),
-  ).effect(`Bedrock Messages text round trip with ${auth.apiKey ? "bearer" : "SigV4"} authentication`, () =>
-    Effect.gen(function* () {
-      const provider = AmazonBedrock.configure({ ...auth, region: "us-west-2" })
-      expect(provider.model("fixture").route.id).toBe("bedrock-converse")
-      const request = LLM.request({
-        model: provider.messages("anthropic.claude-opus-4-6-v1:0"),
-        prompt: "hello",
-        http: { headers: { "anthropic-beta": "existing-beta, existing-beta" } },
-      })
-      const first = yield* LLMClient.generate(request)
-      expect(first.text).toBe("Hello")
-      expect(first.usage?.totalTokens).toBe(12)
-      yield* LLMClient.generate(
-        LLMRequest.update(request, {
-          messages: [...request.messages, first.message, Message.user("continue")],
-        }),
-      )
-    }),
-  )
-}
-
-testEffect(
-  fixedResponse(
-    codec.encode({
-      headers: {
-        ":message-type": { type: "string", value: "exception" },
-        ":exception-type": { type: "string", value: "throttlingException" },
-      },
-      body: new TextEncoder().encode(JSON.stringify({ message: "Too many requests", trace: "keep-original" })),
-    }),
-  ),
-).effect("Bedrock Messages retains the original exception frame", () =>
-  Effect.gen(function* () {
-    const error = yield* LLMClient.generate(
-      LLM.request({
-        model: AmazonBedrock.configure({ apiKey: "test" }).messages("claude"),
-        prompt: "hello",
-      }),
-    ).pipe(Effect.flip)
-    expect(error.reason.body).toContain("keep-original")
-    expect(error.reason.http?.status).toBe(200)
-  }),
-)
-
-for (const mediaType of ["image/png", "application/pdf"]) {
-  for (const data of ["https://example.com/media", "invalid base64!"]) {
-    for (const role of ["user", "tool"] as const) {
-      it.effect(`rejects ${role} ${mediaType} with ${data}`, () =>
-        Effect.gen(function* () {
-          const error = yield* compileRequest(
-            LLM.request({
-              model: AmazonBedrock.configure({ apiKey: "test" }).messages("claude"),
-              messages:
-                role === "user"
-                  ? [Message.user({ type: "media", mediaType, data })]
-                  : [
-                      Message.tool({
-                        id: "call_1",
-                        name: "read",
-                        result: { type: "content", value: [{ type: "file", mime: mediaType, uri: data }] },
-                      }),
-                    ],
-            }),
-          ).pipe(Effect.flip)
-          expect(error.reason._tag).toBe("InvalidRequest")
-          expect(error.message).toContain("Bedrock Messages")
-        }),
-      )
-    }
-  }
-}
-
-it.effect("accepts inline image and document sources", () =>
-  Effect.gen(function* () {
-    const prepared = yield* compileRequest(
-      LLM.request({
-        model: AmazonBedrock.configure({ apiKey: "test" }).messages("claude"),
-        messages: [
-          Message.user([
-            { type: "media", mediaType: "image/png", data: "data:image/png;base64,AQID" },
-            { type: "media", mediaType: "application/pdf", data: "data:application/pdf;base64,AQID" },
-          ]),
-        ],
-      }),
-    )
-    expect(prepared.body.messages[0].content.map((block: { source: { type: string } }) => block.source.type)).toEqual([
-      "base64",
-      "base64",
-    ])
-  }),
-)
-
-it.effect("rejects Anthropic file IDs", () =>
-  Effect.gen(function* () {
-    const error = yield* compileRequest(
-      LLM.request({
-        model: AmazonBedrock.configure({ apiKey: "test" }).messages("claude"),
-        messages: [Message.user({ type: "media", mediaType: "image/png", data: "", metadata: { file_id: "file_1" } })],
-      }),
-    ).pipe(Effect.flip)
-    expect(error.message).toContain("file-ID")
-  }),
-)
-
-it.effect("rejects unsupported image formats", () =>
-  Effect.gen(function* () {
-    const error = yield* compileRequest(
-      LLM.request({
-        model: AmazonBedrock.configure({ apiKey: "test" }).messages("claude"),
-        messages: [Message.user({ type: "media", mediaType: "image/svg+xml", data: "AQID" })],
-      }),
-    ).pipe(Effect.flip)
-    expect(error.reason._tag).toBe("InvalidRequest")
-    expect(error.message).toContain("JPEG, PNG, WebP, or GIF")
-  }),
-)

packages/ai/test/provider/compaction-websocket.test.ts

@@ -1,50 +0,0 @@
-import { expect } from "bun:test"
-import { Effect, Stream } from "effect"
-import { LLM, LLMRequest, Message } from "../../src/index.js"
-import { LLMClient, WebSocketTransport } from "../../src/route.js"
-import { OpenAI } from "../../src/providers.js"
-import { testEffect } from "../lib/effect.js"
-import { fixedResponse } from "../lib/http.js"
-
-testEffect(fixedResponse("unexpected HTTP fallback")).effect(
-  "WebSocket responses preserve compaction options and replay state",
-  () =>
-    Effect.gen(function* () {
-      const checkpoint = { type: "compaction", id: "cmp_ws", encrypted_content: "opaque" }
-      const sent: unknown[] = []
-      const webSocket = WebSocketTransport.makeDirect({
-        open: () =>
-          Effect.succeed({
-            sendText: (message) =>
-              Effect.sync(() => {
-                const body = JSON.parse(message)
-                expect(body.context_management).toEqual([{ type: "compaction", compact_threshold: 100000 }])
-                expect(body.stream).toBeUndefined()
-                if (sent.length) expect(body.input[1]).toEqual(checkpoint)
-                sent.push(body)
-              }),
-            messages: Stream.fromIterable(
-              [
-                { type: "response.created", response: { id: "resp_ws" } },
-                { type: "response.output_item.done", item: checkpoint },
-                { type: "response.completed", response: { id: "resp_ws", output: [checkpoint] } },
-              ].map((event) => JSON.stringify(event)),
-            ),
-            close: Effect.void,
-          }),
-      })
-      const request = LLM.request({
-        model: OpenAI.configure({ apiKey: "test" }).responses("gpt-5.3-codex"),
-        prompt: "hello",
-        providerOptions: { contextManagement: [{ type: "compaction", compactThreshold: 100000 }] },
-      })
-      const first = yield* LLMClient.generate(request, { webSocket })
-      expect(first.message.content).toHaveLength(1)
-      expect(first.message.content[0]?.type).toBe("compaction")
-      yield* LLMClient.generate(
-        LLMRequest.update(request, { messages: [...request.messages, first.message, Message.user("continue")] }),
-        { webSocket },
-      )
-      expect(sent).toHaveLength(2)
-    }),
-)

packages/ai/test/provider/compaction.recorded.test.ts

@@ -1,91 +0,0 @@
-import { expect } from "bun:test"
-import { Effect } from "effect"
-import { LLM, LLMRequest, Message } from "../../src/index.js"
-import { LLMClient } from "../../src/route/client.js"
-import { OpenAI, XAI, Anthropic } from "../../src/providers.js"
-import { recordedTests } from "../recorded-test.js"
-
-const history = [
-  Message.user("Remember the project codename COPPER-ORBIT-42."),
-  Message.assistant(
-    "The project codename is COPPER-ORBIT-42. " + "We reviewed the implementation and tests. ".repeat(1000),
-  ),
-]
-
-for (const provider of [
-  {
-    id: "openai",
-    key: "OPENAI_API_KEY",
-    model: OpenAI.configure({ apiKey: process.env.OPENAI_API_KEY ?? "fixture" }).responses("gpt-5.3-codex"),
-  },
-  {
-    id: "xai",
-    key: "XAI_API_KEY",
-    model: XAI.configure({ apiKey: process.env.XAI_API_KEY ?? "fixture" }).responses("grok-4.6"),
-  },
-]) {
-  recordedTests({ prefix: `${provider.id}-compaction`, provider: provider.id, requires: [provider.key] }).effect(
-    "compacts and continues with the provider checkpoint",
-    () =>
-      Effect.gen(function* () {
-        const request = LLM.request({ model: provider.model, messages: history, generation: { maxTokens: 1024 } })
-        const compacted = yield* LLMClient.compact(request)
-        const result = yield* LLMClient.generate(
-          LLMRequest.update(request, {
-            messages: [
-              ...compacted.messages,
-              Message.user("What is the project codename? Reply only with the codename."),
-            ],
-          }),
-        )
-        expect(result.text).toContain("COPPER-ORBIT-42")
-      }),
-    120000,
-  )
-}
-
-recordedTests({
-  prefix: "anthropic-compaction",
-  provider: "anthropic",
-  requires: ["ANTHROPIC_API_KEY"],
-  options: { redact: { allowRequestHeaders: ["anthropic-version", "anthropic-beta"] } },
-}).effect(
-  "automatically compacts and continues after a pause",
-  () =>
-    Effect.gen(function* () {
-      const model = Anthropic.configure({ apiKey: process.env.ANTHROPIC_API_KEY ?? "fixture" }).model(
-        "claude-sonnet-4-6",
-      )
-      const request = LLM.request({
-        model,
-        messages: [
-          Message.user(
-            "Remember the project codename COPPER-ORBIT-42. " +
-              "The implementation and tests were reviewed. ".repeat(10000),
-          ),
-        ],
-        generation: { maxTokens: 4096 },
-        providerOptions: {
-          contextManagement: {
-            edits: [
-              { type: "compact_20260112", trigger: { type: "input_tokens", value: 50000 }, pauseAfterCompaction: true },
-            ],
-          },
-        },
-      })
-      const first = yield* LLMClient.generate(request)
-      expect(first.finishReason.raw).toBe("compaction")
-      expect(first.message.content.some((part) => part.type === "compaction")).toBe(true)
-      const result = yield* LLMClient.generate(
-        LLMRequest.update(request, {
-          messages: [
-            ...request.messages,
-            first.message,
-            Message.user("What is the project codename? Reply only with the codename."),
-          ],
-        }),
-      )
-      expect(result.text).toContain("COPPER-ORBIT-42")
-    }),
-  120000,
-)

packages/ai/test/provider/compaction.test.ts

@@ -1,136 +0,0 @@
-import { expect } from "bun:test"
-import { Effect, Schema } from "effect"
-import { LLM, LLMRequest, Message } from "../../src/index.js"
-import { LLMClient } from "../../src/route/client.js"
-import { OpenAI, Azure, XAI } from "../../src/providers/index.js"
-import { testEffect } from "../lib/effect.js"
-import { dynamicResponse, fixedResponse } from "../lib/http.js"
-import { sseEvents } from "../lib/sse.js"
-
-const checkpoint = { type: "compaction", id: "cmp_1", encrypted_content: "opaque" }
-const response = sseEvents(
-  { type: "response.output_item.done", item: checkpoint },
-  {
-    type: "response.completed",
-    response: { id: "resp_1", output: [checkpoint], usage: { input_tokens: 10, output_tokens: 2, total_tokens: 12 } },
-  },
-)
-
-for (const model of [
-  OpenAI.configure({ apiKey: "test" }).responses("gpt-5.3-codex"),
-  Azure.configure({ apiKey: "test", resourceName: "test" }).responses("deployment"),
-]) {
-  testEffect(
-    dynamicResponse(({ text, respond }) =>
-      Effect.sync(() => {
-        const body = JSON.parse(text)
-        expect(body.context_management).toEqual([{ type: "compaction", compact_threshold: 100000 }])
-        expect(body.store).toBe(false)
-        if (body.input.length > 1) expect(body.input[1]).toEqual(checkpoint)
-        return respond(response, { headers: { "content-type": "text/event-stream" } })
-      }),
-    ),
-  ).effect(`${model.provider} compaction survives generation, serialization, and a second request`, () =>
-    Effect.gen(function* () {
-      const request = LLM.request({
-        model,
-        prompt: "hello",
-        providerOptions: { contextManagement: [{ type: "compaction", compactThreshold: 100000 }] },
-      })
-      const first = yield* LLMClient.generate(request)
-      expect(first.message.content).toHaveLength(1)
-      expect(first.message.content[0]?.type).toBe("compaction")
-      expect(first.text).toBe("")
-      const codec = Schema.fromJsonString(Message)
-      const message = Schema.decodeSync(codec)(Schema.encodeSync(codec)(first.message))
-      yield* LLMClient.generate(
-        LLMRequest.update(request, { messages: [...request.messages, message, Message.user("continue")] }),
-      )
-      const rejected = yield* LLMClient.generate(
-        LLMRequest.update(request, {
-          model: XAI.configure({ apiKey: "test" }).responses("grok-4.6"),
-          providerOptions: {},
-          messages: [message],
-        }),
-      ).pipe(Effect.flip)
-      expect(rejected.reason._tag).toBe("InvalidRequest")
-    }),
-  )
-}
-
-testEffect(fixedResponse(sseEvents({ type: "response.completed", response: { output: [checkpoint] } }))).effect(
-  "recovers compaction from the terminal output when item completion is absent",
-  () =>
-    Effect.gen(function* () {
-      const result = yield* LLMClient.generate(
-        LLM.request({ model: OpenAI.configure({ apiKey: "test" }).responses("gpt-5.3-codex"), prompt: "hello" }),
-      )
-      expect(result.message.content).toHaveLength(1)
-      expect(result.message.content[0]?.type).toBe("compaction")
-    }),
-)
-
-testEffect(
-  fixedResponse(sseEvents({ type: "response.output_item.done", item: { type: "compaction", id: "cmp_bad" } })),
-).effect("rejects incomplete compaction payloads without publishing a checkpoint", () =>
-  Effect.gen(function* () {
-    const error = yield* LLMClient.generate(
-      LLM.request({ model: OpenAI.configure({ apiKey: "test" }).responses("gpt-5.3-codex"), prompt: "hello" }),
-    ).pipe(Effect.flip)
-    expect(error.reason._tag).toBe("InvalidProviderOutput")
-    expect(error.reason.body).toContain("cmp_bad")
-  }),
-)
-
-const textItem = {
-  type: "message",
-  id: "msg_after",
-  role: "assistant",
-  content: [{ type: "output_text", text: "After checkpoint" }],
-}
-
-for (const completed of [false, true]) {
-  testEffect(
-    fixedResponse(
-      sseEvents(
-        { type: "response.output_item.added", output_index: 0, item: { type: "compaction", id: checkpoint.id } },
-        ...(completed ? [{ type: "response.output_item.done", output_index: 0, item: checkpoint }] : []),
-        { type: "response.output_item.added", output_index: 1, item: textItem },
-        { type: "response.output_text.delta", output_index: 1, item_id: textItem.id, delta: "After checkpoint" },
-        { type: "response.output_item.done", output_index: 1, item: textItem },
-        { type: "response.completed", response: { id: "resp_1", output: [checkpoint, textItem] } },
-      ),
-    ),
-  ).effect(completed ? "keeps streamed checkpoints before later text" : "rejects order-unsafe terminal recovery", () =>
-    Effect.gen(function* () {
-      const request = LLM.request({ model: OpenAI.configure({ apiKey: "test" }).responses("fixture"), prompt: "hello" })
-      if (completed) {
-        const response = yield* LLMClient.generate(request)
-        expect(response.message.content.map((part) => part.type)).toEqual(["compaction", "text"])
-        return
-      }
-      const error = yield* LLMClient.generate(request).pipe(Effect.flip)
-      expect(error.reason._tag).toBe("InvalidProviderOutput")
-      expect(error.message).toContain("Cannot recover a compaction checkpoint")
-      expect(error.reason.body).toContain("response.completed")
-      expect(error.reason.http?.status).toBe(200)
-    }),
-  )
-}
-
-testEffect(
-  fixedResponse(
-    sseEvents({
-      type: "response.completed",
-      response: { output: [{ type: "compaction", encrypted_content: "opaque" }] },
-    }),
-  ),
-).effect("rejects terminal checkpoints missing an id", () =>
-  Effect.gen(function* () {
-    const error = yield* LLMClient.generate(
-      LLM.request({ model: OpenAI.configure({ apiKey: "test" }).responses("fixture"), prompt: "hello" }),
-    ).pipe(Effect.flip)
-    expect(error.reason._tag).toBe("InvalidProviderOutput")
-    expect(error.message).toContain("missing its id")
-  }),
-)

packages/ai/test/provider/conversation-lowering.test.ts

@@ -1,30 +0,0 @@
-import { expect } from "bun:test"
-import { Effect } from "effect"
-import { LLM, Message } from "../../src/index.js"
-import { OpenAI } from "../../src/providers.js"
-import { OpenResponses } from "../../src/protocols/open-responses.js"
-import { it } from "../lib/effect.js"
-
-it.effect("conversation lowering excludes generation settings and tool definitions", () =>
-  Effect.gen(function* () {
-    const body = yield* OpenResponses.lowerConversation(
-      LLM.request({
-        model: OpenAI.configure({ apiKey: "test" }).responses("fixture"),
-        system: "Keep the context",
-        messages: [Message.user("hello"), Message.assistant("hi")],
-        generation: { maxTokens: 100, temperature: 0.5 },
-        providerOptions: { store: false },
-        tools: [{ name: "unsupported", description: "Generation only", inputSchema: {}, native: { unsupported: {} } }],
-      }),
-      { id: "open-responses", name: "Open Responses" },
-    )
-    expect(body).toEqual({
-      model: "fixture",
-      instructions: "Keep the context",
-      input: [
-        { role: "user", content: [{ type: "input_text", text: "hello" }] },
-        { type: "message", role: "assistant", content: [{ type: "output_text", text: "hi" }] },
-      ],
-    })
-  }),
-)

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/explicit-compaction.test.ts

@@ -1,447 +0,0 @@
-import { expect } from "bun:test"
-import { Effect, Schema } from "effect"
-import { LLM, LLMRequest, Message } from "../../src/index.js"
-import { LLMClient, Route } from "../../src/route/client.js"
-import { Auth } from "../../src/route/auth.js"
-import { Endpoint } from "../../src/route/endpoint.js"
-import { OpenAIResponses } from "../../src/protocols/openai-responses.js"
-import { OpenAI, Azure, XAI, Anthropic, AmazonBedrockMantle } from "../../src/providers/index.js"
-import { testEffect } from "../lib/effect.js"
-import { dynamicResponse, fixedResponse } from "../lib/http.js"
-import { sseEvents } from "../lib/sse.js"
-
-const checkpoint = { type: "compaction", id: "cmp_1", encrypted_content: "opaque" }
-const retained = {
-  type: "message",
-  role: "user",
-  id: "msg_1",
-  status: "completed",
-  content: [{ type: "input_text", text: "retained" }],
-}
-const output = [retained, checkpoint]
-
-testEffect(
-  dynamicResponse(({ request, text, respond }) =>
-    Effect.sync(() => {
-      expect(request.headers["x-deployment"]).toBe("fixture")
-      expect(request.headers["x-override"]).toBe("request")
-      expect(request.headers["x-default"]).toBe("configured")
-      expect(request.headers.authorization).toBe("Bearer test")
-      expect(new URL(request.url).searchParams.get("api-version")).toBe("fixture")
-      expect(new URL(request.url).searchParams.get("trace")).toBe("request")
-      if (new URL(request.url).pathname.endsWith("/compact")) {
-        expect(JSON.parse(text)).toEqual({
-          model: "overlaid",
-          input: [{ role: "user", content: [{ type: "input_text", text: "hello" }] }],
-          instructions: "request instructions",
-          previous_response_id: "resp_previous",
-        })
-        return respond(JSON.stringify({ object: "response.compaction", output }))
-      }
-      return respond(sseEvents({ type: "response.completed", response: { id: "resp_1" } }))
-    }),
-  ),
-).effect("generation and compaction share deployment headers, defaults, auth, query, and middleware", () =>
-  Effect.gen(function* () {
-    const headers: string[] = []
-    const middleware: string[] = []
-    const route = Route.make({
-      id: "compaction-headers",
-      provider: "openai",
-      protocol: OpenAIResponses.protocol,
-      compact: OpenAIResponses.route.compact,
-      transport: OpenAIResponses.httpTransport,
-      endpoint: Endpoint.path(({ body }) => `/${body.model}/responses`, {
-        baseURL: "https://example.com",
-        query: { "api-version": "fixture" },
-      }),
-      auth: Auth.bearer("test"),
-      headers: ({ request }) => {
-        expect(request.providerOptions?.store).toBe(false)
-        headers.push(String(request.model.id))
-        return { "x-deployment": "fixture", "x-override": "route" }
-      },
-      defaults: {
-        headers: { "x-default": "configured", "x-override": "configured" },
-        providerOptions: { store: false },
-        http: { body: { instructions: "default instructions" } },
-      },
-    })
-    const request = LLM.request({
-      model: route.model({ id: "fixture" }),
-      prompt: "hello",
-      system: "system instructions",
-      http: {
-        headers: { "x-override": "request" },
-        query: { trace: "request" },
-        body: {
-          model: "overlaid",
-          instructions: "request instructions",
-          previous_response_id: "resp_previous",
-          store: false,
-          stream: true,
-        },
-      },
-    })
-    const options: Parameters<typeof LLMClient.compact>[1] = {
-      http: (request, next) => {
-        middleware.push(new URL(request.url).pathname)
-        return next(request)
-      },
-    }
-    yield* LLMClient.generate(request, options)
-    yield* LLMClient.compact(request, options)
-    expect(headers).toEqual(["fixture", "fixture"])
-    expect(middleware).toEqual(["/fixture/responses", "/fixture/responses/compact"])
-  }),
-)
-
-for (const model of [
-  OpenAI.configure({ apiKey: "test" }).responses("fixture"),
-  Azure.configure({ apiKey: "test", resourceName: "test" }).responses("fixture"),
-  XAI.configure({ apiKey: "test" }).responses("fixture"),
-]) {
-  const item = {
-    type: model.provider === "xai" ? "x_search_call" : "computer_call",
-    id: "hosted_1",
-    status: "completed",
-  }
-  testEffect(
-    dynamicResponse(({ request, text, respond }) =>
-      Effect.sync(() => {
-        expect(new URL(request.url).pathname).toEndWith("/responses/compact")
-        expect(JSON.parse(text)).toEqual({ model: "fixture", input: [item], instructions: "Keep the context" })
-        return respond(JSON.stringify({ object: "response.compaction", output: [checkpoint] }))
-      }),
-    ),
-  ).effect(`${model.provider} compacts provider-specific history without lowering generation settings`, () =>
-    Effect.gen(function* () {
-      const request = LLM.request({
-        model,
-        system: "Keep the context",
-        messages: [
-          Message.assistant({
-            type: "tool-result",
-            id: item.id,
-            name: item.type,
-            result: { type: "json", value: item },
-            providerExecuted: true,
-            providerMetadata: { [model.route.providerMetadataKey ?? model.provider]: { itemId: item.id } },
-          }),
-        ],
-      })
-      for (const candidate of [
-        LLMRequest.update(request, {
-          tools: [
-            { name: "unsupported", description: "Generation only", inputSchema: {}, native: { unsupported: {} } },
-          ],
-        }),
-        LLMRequest.update(request, { providerOptions: { contextManagement: "invalid-generation-option" } }),
-      ]) {
-        const error = yield* LLMClient.generate(candidate).pipe(Effect.flip)
-        expect(error.reason._tag).toBe("InvalidRequest")
-        const response = yield* LLMClient.compact(candidate)
-        expect(response.messages[0]?.content[0]?.type).toBe("compaction")
-      }
-    }),
-  )
-}
-
-const retainedItems = [
-  retained,
-  {
-    type: "message",
-    id: "msg_assistant",
-    role: "assistant",
-    status: "completed",
-    phase: "commentary",
-    content: [
-      { type: "output_text", text: "First" },
-      { type: "output_text", text: "Second" },
-    ],
-  },
-  {
-    type: "reasoning",
-    id: "rs_1",
-    summary: [
-      { type: "summary_text", text: "Thinking" },
-      { type: "summary_text", text: "More thinking" },
-    ],
-    encrypted_content: "reasoning-state",
-  },
-  { type: "reasoning", id: "rs_2", summary: [], encrypted_content: "hidden-reasoning" },
-  {
-    type: "message",
-    id: "msg_media",
-    role: "user",
-    content: [
-      { type: "input_image", image_url: "https://example.com/image.png" },
-      { type: "input_file", filename: "report.pdf", file_data: "data:application/pdf;base64,cGRm", detail: "high" },
-      { type: "input_file", filename: "other.pdf", file_url: "https://example.com/report.pdf", detail: "low" },
-    ],
-  },
-  checkpoint,
-]
-
-for (const model of [
-  OpenAI.configure({ apiKey: "test" }).responses("gpt-5.3-codex"),
-  ...[undefined, "custom"].map((providerMetadataKey) =>
-    Route.make({
-      id: providerMetadataKey ?? "default-metadata",
-      provider: "openai",
-      providerMetadataKey,
-      protocol: OpenAIResponses.protocol,
-      compact: OpenAIResponses.route.compact,
-      endpoint: OpenAIResponses.route.endpoint,
-      transport: OpenAIResponses.httpTransport,
-    }).model({ id: "fixture" }),
-  ),
-]) {
-  testEffect(
-    dynamicResponse(({ request, text, respond }) =>
-      Effect.sync(() => {
-        if (new URL(request.url).pathname.endsWith("/compact"))
-          return respond(JSON.stringify({ object: "response.compaction", output: retainedItems }))
-        expect(JSON.parse(text).input).toEqual(retainedItems)
-        return respond(sseEvents({ type: "response.completed", response: { id: "resp_1" } }), {
-          headers: { "content-type": "text/event-stream" },
-        })
-      }),
-    ),
-  ).effect(`${model.route.id} retains messages, reasoning, and media through typed conversation parts`, () =>
-    Effect.gen(function* () {
-      const request = LLM.request({
-        model,
-        prompt: "hello",
-      })
-      const compacted = yield* LLMClient.compact(request)
-      expect(compacted.messages.map((message) => message.role)).toEqual([
-        "user",
-        "assistant",
-        "assistant",
-        "assistant",
-        "user",
-        "assistant",
-      ])
-      expect(compacted.messages[1]?.content).toEqual([
-        { type: "text", text: "First" },
-        { type: "text", text: "Second" },
-      ])
-      expect(compacted.messages[2]?.content.map((part) => part.type)).toEqual(["reasoning", "reasoning"])
-      expect(compacted.messages[4]?.content.map((part) => part.type)).toEqual(["media", "media", "media"])
-      const codec = Schema.fromJsonString(Schema.Array(Message))
-      const messages = Schema.decodeSync(codec)(Schema.encodeSync(codec)(compacted.messages))
-      yield* LLMClient.generate(LLMRequest.update(request, { messages }))
-    }),
-  )
-}
-
-for (const overlay of [undefined, { service_tier: "priority", prompt_cache_key: "overridden" }]) {
-  testEffect(
-    dynamicResponse(({ text, respond }) =>
-      Effect.sync(() => {
-        expect(JSON.parse(text)).toEqual({
-          model: "fixture",
-          input: [{ role: "user", content: [{ type: "input_text", text: "hello" }] }],
-          service_tier: overlay?.service_tier ?? "flex",
-          prompt_cache_key: overlay?.prompt_cache_key ?? "affinity",
-          prompt_cache_retention: "24h",
-          prompt_cache_options: { mode: "explicit", ttl: "30m" },
-        })
-        return respond(JSON.stringify({ object: "response.compaction", output: [checkpoint] }))
-      }),
-    ),
-  ).effect(`compact preserves supported request controls${overlay ? " with HTTP overrides" : ""}`, () =>
-    LLMClient.compact(
-      LLM.request({
-        model: OpenAI.configure({ apiKey: "test" }).responses("fixture"),
-        prompt: "hello",
-        promptCacheKey: "affinity",
-        providerOptions: { serviceTier: "flex" },
-        generation: { maxTokens: 100 },
-        http: {
-          body: {
-            stream: true,
-            store: false,
-            prompt_cache_retention: "24h",
-            prompt_cache_options: { mode: "explicit", ttl: "30m" },
-            ...overlay,
-          },
-        },
-      }),
-    ),
-  )
-}
-
-for (const item of [
-  { type: "unknown_provider_item", data: "do not hide in a compaction part" },
-  {
-    type: "message",
-    role: "user",
-    content: [{ type: "input_image", image_url: "https://example.com/image.png", detail: 42 }],
-  },
-  { type: "message", role: "user", content: [] },
-  {
-    type: "message",
-    role: "assistant",
-    content: [{ type: "input_image", image_url: "https://example.com/image.png" }],
-  },
-  { type: "message", role: "user", content: [{ type: "input_file", filename: "missing.pdf" }] },
-  {
-    type: "message",
-    role: "user",
-    content: [{ type: "input_file", filename: "bad.pdf", file_url: "https://example.com/report.pdf", detail: 42 }],
-  },
-  {
-    type: "message",
-    role: "user",
-    content: [
-      {
-        type: "input_file",
-        filename: "both.pdf",
-        file_url: "https://example.com/report.pdf",
-        file_data: "data:application/pdf;base64,cGRm",
-      },
-    ],
-  },
-]) {
-  testEffect(fixedResponse(JSON.stringify({ object: "response.compaction", output: [item, checkpoint] }))).effect(
-    `rejects unsupported compact output: ${JSON.stringify(item)}`,
-    () =>
-      Effect.gen(function* () {
-        const error = yield* LLMClient.compact(
-          LLM.request({ model: OpenAI.configure({ apiKey: "test" }).responses("gpt-5.3-codex"), prompt: "hello" }),
-        ).pipe(Effect.flip)
-        expect(error.reason._tag).toBe("InvalidProviderOutput")
-        expect(error.reason.body).toContain(JSON.stringify(item))
-        expect(error.reason.http?.status).toBe(200)
-      }),
-  )
-}
-
-for (const model of [
-  OpenAI.configure({ apiKey: "test" }).responses("fixture"),
-  Azure.configure({ apiKey: "test", resourceName: "test" }).responses("fixture"),
-  XAI.configure({ apiKey: "test" }).responses("fixture"),
-]) {
-  const images = [undefined, "low", "high", "auto"].map((detail) => ({
-    type: "input_image",
-    image_url: "https://example.com/image.png",
-    ...(detail === undefined ? {} : { detail }),
-  }))
-  testEffect(
-    dynamicResponse(({ request, text, respond }) =>
-      Effect.sync(() => {
-        if (new URL(request.url).pathname.endsWith("/compact"))
-          return respond(
-            JSON.stringify({
-              object: "response.compaction",
-              output: [{ type: "message", role: "user", content: images }, checkpoint],
-            }),
-          )
-        expect(JSON.parse(text).input[0].content).toEqual(images)
-        return respond(sseEvents({ type: "response.completed", response: { id: "resp_1" } }))
-      }),
-    ),
-  ).effect(`${model.provider} preserves retained image detail through serialization and replay`, () =>
-    Effect.gen(function* () {
-      const request = LLM.request({ model, prompt: "hello" })
-      const compacted = yield* LLMClient.compact(request)
-      const codec = Schema.fromJsonString(Schema.Array(Message))
-      const messages = Schema.decodeSync(codec)(Schema.encodeSync(codec)(compacted.messages))
-      yield* LLMClient.generate(LLMRequest.update(request, { messages }))
-    }),
-  )
-}
-
-testEffect(fixedResponse("must not execute")).effect("xAI rejects automatic compaction options", () =>
-  Effect.gen(function* () {
-    const request = LLMRequest.update(
-      LLM.request({ model: XAI.configure({ apiKey: "test" }).responses("grok-4.6"), prompt: "hello" }),
-      { providerOptions: { contextManagement: [{ type: "compaction" }] } },
-    )
-    const error = yield* LLMClient.generate(request).pipe(Effect.flip)
-    expect(error.reason._tag).toBe("InvalidRequest")
-    expect(error.message).toContain("LLMClient.compact")
-  }),
-)
-
-for (const model of [
-  OpenAI.configure({ apiKey: "test" }).responses("gpt-5.3-codex"),
-  Azure.configure({ apiKey: "test", resourceName: "test" }).responses("deployment"),
-  XAI.configure({ apiKey: "test" }).responses("grok-4.6"),
-]) {
-  testEffect(
-    dynamicResponse(({ request, text, respond }) =>
-      Effect.sync(() => {
-        const body = JSON.parse(text)
-        expect(request.method).toBe("POST")
-        expect(request.headers[model.provider === "azure" ? "api-key" : "authorization"]).toBe(
-          model.provider === "azure" ? "test" : "Bearer test",
-        )
-        if (new URL(request.url).pathname.endsWith("/responses/compact")) {
-          expect(body).toEqual({
-            model: model.id,
-            input: [{ role: "user", content: [{ type: "input_text", text: "original" }] }],
-            instructions: "system",
-          })
-          return respond(
-            JSON.stringify({
-              object: "response.compaction",
-              output,
-              usage: { input_tokens: 1000, output_tokens: 10, total_tokens: 1010 },
-            }),
-            { headers: { "content-type": "application/json" } },
-          )
-        }
-        expect(new URL(request.url).pathname.endsWith("/responses")).toBe(true)
-        expect(body.input).toEqual([...output, { role: "user", content: [{ type: "input_text", text: "continue" }] }])
-        return respond(sseEvents({ type: "response.completed", response: { id: "resp_1", output: [] } }), {
-          headers: { "content-type": "text/event-stream" },
-        })
-      }),
-    ),
-  ).effect(`${model.provider} explicitly compacts and replays the entire canonical window`, () =>
-    Effect.gen(function* () {
-      const request = LLM.request({ model, prompt: "original", system: "system", http: { body: { store: false } } })
-      const compacted = yield* LLMClient.compact(request)
-      expect(compacted.usage?.totalTokens).toBe(1010)
-      expect(compacted.messages.map((message) => message.role)).toEqual(["user", "assistant"])
-      expect(compacted.messages[0]?.content).toEqual([{ type: "text", text: "retained" }])
-      expect(compacted.messages[1]?.content).toEqual([
-        { type: "compaction", provider: model.provider, id: "cmp_1", encrypted: "opaque" },
-      ])
-      const codec = Schema.fromJsonString(Schema.Array(Message))
-      const messages = Schema.decodeSync(codec)(Schema.encodeSync(codec)(compacted.messages))
-      yield* LLMClient.generate(LLMRequest.update(request, { messages: [...messages, Message.user("continue")] }))
-    }),
-  )
-}
-
-for (const model of [
-  Anthropic.configure({ apiKey: "test" }).model("claude-opus-4-6"),
-  AmazonBedrockMantle.configure({ apiKey: "test" }).responses("model"),
-]) {
-  testEffect(fixedResponse("must not execute")).effect(
-    `${model.route.id} does not inherit an unsupported compact endpoint`,
-    () =>
-      Effect.gen(function* () {
-        // @ts-expect-error Untyped callers must still receive the runtime capability error.
-        const error = yield* LLMClient.compact(LLM.request({ model, prompt: "hello" })).pipe(Effect.flip)
-        expect(error.reason._tag).toBe("InvalidRequest")
-      }),
-  )
-}
-
-testEffect(
-  fixedResponse(JSON.stringify({ object: "response.compaction", output: [retained], debug: "original payload" })),
-).effect("invalid explicit compaction preserves the original response and HTTP context", () =>
-  Effect.gen(function* () {
-    const error = yield* LLMClient.compact(
-      LLM.request({ model: OpenAI.configure({ apiKey: "test" }).responses("gpt-5.3-codex"), prompt: "hello" }),
-    ).pipe(Effect.flip)
-    expect(error.reason._tag).toBe("InvalidProviderOutput")
-    expect(error.reason.body).toContain("original payload")
-    expect(error.reason.http?.status).toBe(200)
-  }),
-)

packages/ai/test/provider/image-detail.test.ts

@@ -1,60 +0,0 @@
-import { expect } from "bun:test"
-import { Effect, Schema } from "effect"
-import { LLM, Message } from "../../src/index.js"
-import { OpenAI, Azure, XAI } from "../../src/providers.js"
-import { compileRequest } from "../../src/route/client.js"
-import { it } from "../lib/effect.js"
-
-for (const model of [
-  OpenAI.configure({ apiKey: "test" }).responses("fixture"),
-  Azure.configure({ apiKey: "test", resourceName: "test" }).responses("fixture"),
-  XAI.configure({ apiKey: "test" }).responses("fixture"),
-]) {
-  it.effect(`${model.provider} preserves image detail through message serialization and lowering`, () =>
-    Effect.gen(function* () {
-      const details = [undefined, "low", "high", "auto"]
-      const message = Message.user(
-        details.map((detail) => ({
-          type: "media",
-          mediaType: "image/png",
-          data: "https://example.com/image.png",
-          providerMetadata:
-            detail === undefined ? undefined : { [model.route.providerMetadataKey ?? model.provider]: { detail } },
-        })),
-      )
-      const codec = Schema.fromJsonString(Message)
-      const prepared = yield* compileRequest(
-        LLM.request({
-          model,
-          messages: [Schema.decodeSync(codec)(Schema.encodeSync(codec)(message))],
-        }),
-      )
-      expect(prepared.body.input[0].content).toEqual(
-        details.map((detail) => ({
-          type: "input_image",
-          image_url: "https://example.com/image.png",
-          detail,
-        })),
-      )
-    }),
-  )
-}
-
-it.effect("rejects malformed image detail instead of silently discarding it", () =>
-  Effect.gen(function* () {
-    const error = yield* compileRequest(
-      LLM.request({
-        model: OpenAI.configure({ apiKey: "test" }).responses("fixture"),
-        messages: [
-          Message.user({
-            type: "media",
-            mediaType: "image/png",
-            data: "https://example.com/image.png",
-            providerMetadata: { openai: { detail: 42 } },
-          }),
-        ],
-      }),
-    ).pipe(Effect.flip)
-    expect(error.reason._tag).toBe("InvalidRequest")
-  }),
-)

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", () => {

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

@@ -216,7 +216,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 +289,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) => {

packages/ai/test/testing.test.ts

@@ -1,18 +1,5 @@
 import { describe, expect } from "bun:test"
-import {
-  AIError,
-  CompactionPart,
-  CompactionResponse,
-  LanguageModel,
-  LLM,
-  LLMClient,
-  LLMEvent,
-  LLMRequest,
-  Message,
-  ProviderID,
-  RateLimitError,
-} from "../src/index.js"
-import { OpenAI } from "../src/providers.js"
+import { AIError, LanguageModel, LLM, LLMClient, LLMEvent, LLMRequest, RateLimitError } from "../src/index.js"
 import { OpenAIChat } from "../src/protocols/openai-chat.js"
 import { TestLLM } from "../src/testing.js"
 import { Effect, Fiber, Latch, Stream } from "effect"
@@ -79,54 +66,6 @@ describe("TestLLM legacy client", () => {
 })
 
 describe("TestLLM first-class client", () => {
-  it.effect("rejects response fixtures for the wrong operation", () =>
-    Effect.gen(function* () {
-      const client = yield* TestLLM.Test
-      const request = LLM.request({ model: OpenAI.configure({ apiKey: "test" }).responses("fixture"), prompt: "hello" })
-      yield* client.push(TestLLM.stop(), new CompactionResponse({ messages: [] }))
-      expect(yield* client.compact(request).pipe(Effect.catchDefect(Effect.succeed))).toBe(
-        "TestLLM compaction requires a CompactionResponse",
-      )
-      expect(yield* client.generate(request).pipe(Effect.catchDefect(Effect.succeed))).toBe(
-        "TestLLM generation requires an event response",
-      )
-    }),
-  )
-
-  it.effect("scripts replacement windows with the same lazy recording, gates, and fallback controls", () =>
-    Effect.gen(function* () {
-      const client = yield* TestLLM.Test
-      const request = LLM.request({ model: OpenAI.configure({ apiKey: "test" }).responses("fixture"), prompt: "hello" })
-      const compacted = new CompactionResponse({
-        messages: [
-          Message.user("retained input"),
-          Message.assistant(CompactionPart.make({ provider: ProviderID.make("openai"), encrypted: "checkpoint" })),
-          Message.user("retained tail"),
-        ],
-      })
-      yield* client.push(compacted, TestLLM.text("continued", "answer"))
-      const operation = LLMClient.compact(request)
-      expect(yield* client.requests()).toEqual([])
-      const gate = yield* client.gate()
-      const fiber = yield* operation.pipe(Effect.forkChild({ startImmediately: true }))
-      yield* gate.started
-      yield* client.wait(1)
-      expect(fiber.pollUnsafe()).toBeUndefined()
-      yield* gate.release
-      expect(yield* Fiber.join(fiber)).toBe(compacted)
-      const next = LLMRequest.update(request, { messages: compacted.messages })
-      expect((yield* LLMClient.generate(next)).text).toBe("continued")
-      yield* client.serve((observed) => {
-        expect(observed).toBe(next)
-        return compacted
-      })
-      expect(yield* LLMClient.compact(next)).toBe(compacted)
-      yield* client.always(compacted)
-      expect(yield* LLMClient.compact(next)).toBe(compacted)
-      expect(yield* client.requests()).toEqual([request, next, next, next])
-    }),
-  )
-
   it.effect("provides the same object under normal and test tags with snapshot observations", () =>
     Effect.gen(function* () {
       const llm = yield* TestLLM.Test

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/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/entry.tsx

@@ -6,6 +6,7 @@ import { AppBaseProviders, AppInterface } from "@/app"
 import { loadInitialLocale } from "@/runtime/i18n/language"
 import { PlatformProvider } from "@/runtime/platform/platform"
 import { createWebPlatform } from "@/runtime/platform/web"
+import { isStandalone, PwaRoutePersistence, restorePwaRoute } from "@/runtime/platform/pwa"
 import en from "@/runtime/i18n/en"
 import zh from "@/runtime/i18n/zh"
 import { authFromToken } from "@/runtime/server/api"
@@ -71,6 +72,8 @@ if (root instanceof HTMLElement && root.dataset.opencodeMounted === undefined) {
   void loadInitialLocale().then((locale) => {
     const auth = authFromToken(new URLSearchParams(location.search).get("auth_token"))
     clearAuthToken()
+    const standalone = isStandalone()
+    if (standalone) restorePwaRoute()
     const server: ServerConnection.Http = {
       type: "http",
       authToken: !!auth,
@@ -87,7 +90,9 @@ if (root instanceof HTMLElement && root.dataset.opencodeMounted === undefined) {
               defaultServer={ServerConnection.Key.make(web.defaultServerUrl)}
               canonicalLocalServer={ServerConnection.key(server)}
               servers={[server]}
-            />
+            >
+              {standalone && <PwaRoutePersistence />}
+            </AppInterface>
           </AppBaseProviders>
         </PlatformProvider>
       ),

packages/app/src/runtime/platform/pwa.ts

@@ -0,0 +1,43 @@
+import { useLocation } from "@solidjs/router"
+import { createEffect } from "solid-js"
+
+const LAST_ROUTE_KEY = "opencode.pwa.last-route"
+
+export function isStandalone() {
+  return (
+    window.matchMedia("(display-mode: standalone)").matches ||
+    ("standalone" in navigator && navigator.standalone === true)
+  )
+}
+
+export function restorePwaRoute() {
+  if (location.pathname !== "/" || location.search || location.hash) return
+  try {
+    const value = localStorage.getItem(LAST_ROUTE_KEY)
+    if (!value) return
+    const url = new URL(value, location.origin)
+    if (url.origin !== location.origin || url.searchParams.has("auth_token")) return
+    if (
+      url.pathname !== "/" &&
+      url.pathname !== "/new-session" &&
+      !/^\/server\/[^/]+\/session\/[^/]+$/.test(url.pathname)
+    )
+      return
+    history.replaceState(history.state, "", url.pathname + url.search + url.hash)
+  } catch {
+    // Storage may be unavailable; keep the launch URL in that case.
+  }
+}
+
+export function PwaRoutePersistence() {
+  const location = useLocation()
+  createEffect(() => {
+    const value = location.pathname + location.search + location.hash
+    try {
+      localStorage.setItem(LAST_ROUTE_KEY, value)
+    } catch {
+      // Navigation must still work when storage is unavailable or full.
+    }
+  })
+  return null
+}

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/test-browser/pwa-route.test.ts

@@ -0,0 +1,79 @@
+import { afterEach, beforeEach, expect, test } from "bun:test"
+import { MemoryRouter, createMemoryHistory } from "@solidjs/router"
+import { createComponent, render } from "solid-js/web"
+import { isStandalone, PwaRoutePersistence, restorePwaRoute } from "../src/runtime/platform/pwa"
+
+const key = "opencode.pwa.last-route"
+const originalUrl = window.location.href
+
+beforeEach(() => {
+  window.location.href = "http://localhost/"
+})
+
+afterEach(() => {
+  localStorage.removeItem(key)
+  window.location.href = originalUrl
+})
+
+test("normal browser windows are not standalone", () => {
+  expect(isStandalone()).toBe(false)
+})
+
+test("restores the last PWA route including query and hash without adding history", () => {
+  window.history.replaceState({ retained: true }, "", "http://localhost/")
+  const length = window.history.length
+  localStorage.setItem(key, "/server/local/session/session-1?view=files#file")
+
+  restorePwaRoute()
+
+  expect(window.location.pathname + window.location.search + window.location.hash).toBe(
+    "/server/local/session/session-1?view=files#file",
+  )
+  expect(window.history.length).toBe(length)
+  expect(window.history.state).toEqual({ retained: true })
+})
+
+test("preserves explicit launch routes, queries, and hashes", () => {
+  localStorage.setItem(key, "/server/local/session/saved")
+  for (const route of ["/server/local/session/linked", "/new-session?draftId=123", "/?launch=1", "/#launch"]) {
+    window.history.replaceState(null, "", `http://localhost${route}`)
+    restorePwaRoute()
+    expect(window.location.pathname + window.location.search + window.location.hash).toBe(route)
+  }
+})
+
+test("ignores missing, invalid, external, and auth-bearing saved routes", () => {
+  window.history.replaceState(null, "", "http://localhost/")
+  restorePwaRoute()
+  expect(window.location.pathname).toBe("/")
+
+  for (const value of [
+    "/removed-route",
+    "https://example.com/new-session",
+    "//example.com/new-session",
+    "http://[",
+    "/new-session?auth_token=secret",
+  ]) {
+    localStorage.setItem(key, value)
+    restorePwaRoute()
+    expect(window.location.href).toBe("http://localhost/")
+  }
+})
+
+test("persists router navigation including returning home", async () => {
+  const host = document.createElement("div")
+  const history = createMemoryHistory()
+  history.set({ value: "/new-session?draftId=123", replace: true, scroll: false })
+  const dispose = render(() => createComponent(MemoryRouter, { history, root: PwaRoutePersistence }), host)
+  try {
+    expect(localStorage.getItem(key)).toBe("/new-session?draftId=123")
+    history.set({ value: "/server/local/session/next#file", scroll: false })
+    await new Promise((resolve) => setTimeout(resolve, 0))
+    expect(localStorage.getItem(key)).toBe("/server/local/session/next#file")
+    history.set({ value: "/", scroll: false })
+    await new Promise((resolve) => setTimeout(resolve, 0))
+    expect(localStorage.getItem(key)).toBe("/")
+  } finally {
+    dispose()
+  }
+})

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/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/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/promise/api.ts

@@ -3,6 +3,7 @@ import type { OpenCode } from "./client.js"
 type Client = ReturnType<typeof OpenCode.make>
 
 export type { RpcApi, RpcCallOptions, RpcClient, RpcEventPayload } from "./rpc.js"
+export type { PermissionCreateInput } from "./generated/types.js"
 
 export type AgentApi = Client["agent"]
 export type CommandApi = Client["command"]

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/aisdk.ts

@@ -303,7 +303,6 @@ function modelFromLanguage(info: Info, language: LanguageModelV3) {
   const projected = mapBodyToProviderOptions(info, packageName)
   const optionKey = providerOptionKey(packageName, info.providerID)
   const route: AnyRoute = {
-    compact: undefined,
     id: `ai-sdk:${packageName}`,
     provider: ProviderID.make(info.providerID),
     providerMetadataKey: optionKey,
@@ -328,12 +327,7 @@ function modelFromLanguage(info: Info, language: LanguageModelV3) {
     },
     body: {
       schema: Schema.Unknown,
-      from: (request) =>
-        Effect.try({
-          try: () => callOptions(request, packageName, info.modelID ?? info.id, optionKey),
-          catch: (cause) =>
-            cause instanceof AIError ? cause : ProviderShared.invalidRequest("Invalid AI SDK request", cause),
-        }),
+      from: (request) => Effect.succeed(callOptions(request, packageName, info.modelID ?? info.id, optionKey)),
     },
     with: () => route,
     model: (input) =>
@@ -518,8 +512,6 @@ function userPart(part: ContentPart): UserContent {
 
 function assistantPart(part: ContentPart): AssistantContent {
   switch (part.type) {
-    case "compaction":
-      throw ProviderShared.invalidRequest("AI SDK routes cannot replay native provider compaction state")
     case "text":
       return [{ type: "text", text: part.text, providerOptions: metadataProviderOptions(part.providerMetadata) }]
     case "media":

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/formatter.ts

@@ -54,9 +54,8 @@ const layer = Layer.effect(
     })
 
     const file = Effect.fn("Formatter.file")(function* (filepath: string) {
-      const matching = state
-        .get()
-        .formatters.filter((formatter) => formatter.extensions.includes(path.extname(filepath)))
+      const extension = path.extname(filepath)
+      const matching = state.get().formatters.filter((formatter) => formatter.extensions.includes(extension))
 
       for (const formatter of matching) {
         const enabled = yield* command(formatter)

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/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/browser/README.md

@@ -0,0 +1,33 @@
+# Experimental Browser Plugin
+
+The server-side browser tool lives alongside the other built-in plugins. Its
+implementation uses only the public plugin API, public schemas, and Effect. The
+shared RPC contract is `@opencode-ai/schema/browser`; desktop clients do not import Core.
+
+Disable it through normal plugin configuration:
+
+```jsonc
+{
+  "plugins": ["-opencode.browser"],
+}
+```
+
+The desktop implementation connects with `client.rpc(Browser.Definition)` at the
+session's location. Subscribe to server events before calling `attach`; wait for
+`server.connected`, then the matching `attached` control event. The `attach` call
+stays pending for the attachment lifetime. Abort it when its event stream ends or
+the desktop owner closes. Completing the attachment also ends that event consumer.
+
+- `attach` holds one browser attachment per session until cancellation, plugin
+  unload, session deletion, or session movement.
+- `state` reports the current page, or `null` when no page is open.
+- `result` completes a command with its request ID and outcome.
+- `control` events carry attachment confirmation, commands, and cancellation.
+
+Control events use OpenCode's existing authenticated, server-wide event feed.
+Consumers filter by `connectionID`; this identifier is correlation, not private
+event delivery. State and results use RPC calls rather than broadcast events.
+
+The plugin requests normal agent permissions before acting on a URL. Browser
+content is untrusted. Pages use the desktop's network, with no server-side tunnel.
+The desktop owns Chromium, page isolation, and native controls.