fix(core): expose inline media source paths

packages/ai/README.md

@@ -241,14 +241,115 @@ 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.
 
-Responses remain canonical event arrays or arbitrary `Stream<LLMEvent, AIError>` values. The client consumes
+Generation 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`. Its `replacement` contains the next context window, including retained user messages. The client returns that result and usage directly, 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 explicit compaction calls in OpenAI/Azure/xAI Responses. Model and deployment support still depends on the provider. Bedrock compaction is deferred to a separate follow-up.
+
+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.
+
+### Explicit compaction
+
+`LLMClient.compact(request)` is the caller-controlled operation for OpenAI, Azure, and xAI Responses. It performs exactly one HTTP call to `/responses/compact`, using the selected route's endpoint, credentials, query, and HTTP middleware. It returns a `CompactionResponse` with `replacement: Message[]` and optional `usage`, not a normal generation response.
+
+Prefer this operation, where supported, when the application owns compaction policy and durable context updates.
+
+```ts
+const result = yield * LLMClient.compact(request)
+const next = LLMRequest.update(request, {
+  messages: result.replacement,
+})
+const response = yield * LLMClient.generate(next)
+```
+
+`replacement` replaces the complete input window. 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.
+
+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.
+
+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. Anthropic does not expose this operation in this package; its in-band compaction remains available below. Compatible routes do not inherit an explicit compact endpoint simply because they use a Responses protocol.
+
+### Advanced: in-band compaction
+
+`providerOptions.contextManagement` lets the provider decide when to compact during an ordinary `generate` or `stream` call. This is an advanced option for callers that own persistence and recovery: persist the complete assistant message, including its checkpoint, before continuing. Enabling the option does not provide durable checkpoint storage, interruption recovery, or model-switch policy. Keep the prior context until a successful checkpoint has been persisted.
+
+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"`. It occurs only if the threshold triggers compaction: `pauseAfterCompaction` does not mean "compact now". 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`.
+
+### 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, WebSocket recovery, 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), [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/protocols/anthropic-messages.ts

@@ -6,8 +6,12 @@ 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,
@@ -15,7 +19,6 @@ import {
   type FinishReasonDetails,
   type FinishReason,
   type JsonSchema,
-  type LLMRequest,
   type MediaPart,
   type ProviderMetadata,
   type ToolCallPart,
@@ -61,6 +64,8 @@ export type ThinkingInput =
     ))
 
 export interface OptionsInput {
+  /** Advanced in-band compaction. The caller owns checkpoint persistence and recovery. */
+  readonly contextManagement?: ContextManagement
   readonly [key: string]: unknown
   readonly thinking?: ThinkingInput
   readonly effort?: string
@@ -89,6 +94,23 @@ 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
 // =============================================================================
@@ -236,7 +258,12 @@ 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,
@@ -312,6 +339,18 @@ 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),
@@ -335,7 +374,7 @@ const AnthropicBodyFields = {
 export const AnthropicMessagesBody = Schema.Struct(AnthropicBodyFields)
 export type AnthropicMessagesBody = Schema.Schema.Type<typeof AnthropicMessagesBody>
 
-const AnthropicUsage = Schema.StructWithRest(
+const AnthropicIterationUsage = Schema.StructWithRest(
   Schema.Struct({
     input_tokens: optionalNull(Schema.Number),
     output_tokens: Schema.optional(Schema.Number),
@@ -354,6 +393,13 @@ const AnthropicUsage = 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({
@@ -377,6 +423,7 @@ 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),
@@ -406,6 +453,8 @@ 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>>
@@ -848,6 +897,12 @@ 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) })
@@ -1003,6 +1058,9 @@ 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 →
@@ -1037,7 +1095,7 @@ const fromRequest = Effect.fn("AnthropicMessages.fromRequest")(function* (reques
     )
   }
   const options = yield* resolveOptions(request)
-  return {
+  const body = {
     model: request.model.id,
     system,
     messages,
@@ -1058,6 +1116,18 @@ 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,
+      })),
+    },
+  }
 })
 
 // =============================================================================
@@ -1079,18 +1149,31 @@ 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 nonCached = usage.input_tokens ?? undefined
-  const cacheRead = usage.cache_read_input_tokens ?? undefined
-  const cacheWrite = usage.cache_creation_input_tokens ?? 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 inputTokens = ProviderShared.sumTokens(nonCached, cacheRead, cacheWrite)
+  const outputTokens = ProviderShared.sumTokens(...iterations.map((item) => item.output_tokens))
   return new Usage({
     inputTokens,
-    outputTokens: usage.output_tokens,
+    outputTokens,
+    contextTokens:
+      last?.type === "message"
+        ? ProviderShared.sumTokens(
+            last.input_tokens ?? undefined,
+            last.cache_read_input_tokens ?? undefined,
+            last.cache_creation_input_tokens ?? undefined,
+          )
+        : undefined,
     nonCachedInputTokens: nonCached,
     cacheReadInputTokens: cacheRead,
     cacheWriteInputTokens: cacheWrite,
-    reasoningTokens: usage.output_tokens_details?.thinking_tokens,
-    totalTokens: ProviderShared.totalTokens(inputTokens, usage.output_tokens, undefined),
+    reasoningTokens: ProviderShared.sumTokens(...iterations.map((item) => item.output_tokens_details?.thinking_tokens)),
+    totalTokens: ProviderShared.totalTokens(inputTokens, outputTokens, undefined),
     providerMetadata: { [providerMetadataKey]: usage },
   })
 }
@@ -1112,6 +1195,7 @@ const mergeUsage = (left: Usage | undefined, right: Usage | undefined, providerM
   return new Usage({
     inputTokens,
     outputTokens,
+    contextTokens: right.contextTokens ?? left.contextTokens,
     nonCachedInputTokens,
     cacheReadInputTokens,
     cacheWriteInputTokens,
@@ -1170,7 +1254,6 @@ 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]
@@ -1265,7 +1348,16 @@ const onContentBlockDelta = Effect.fn("AnthropicMessages.onContentBlockDelta")(f
 ) {
   const delta = event.delta
 
-  if (delta?.type === "text_delta" && delta.text) {
+  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 (!state.lifecycle.text.has(`text-${event.index ?? 0}`)) return [state, NO_EVENTS] satisfies StepResult
     const events: LLMEvent[] = []
     return [
@@ -1274,7 +1366,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 [
@@ -1286,7 +1378,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 [
@@ -1298,7 +1390,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(
@@ -1323,6 +1415,18 @@ 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 ?? []
@@ -1374,6 +1478,8 @@ 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
@@ -1418,16 +1524,21 @@ const onError = (event: AnthropicEvent) => {
   )
 }
 
-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 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 invalidStreamEvent = (event: AnthropicEvent) =>
   Effect.fail(
@@ -1456,7 +1567,16 @@ 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 (!isKnownStreamBlockType(event.content_block.type)) return Effect.succeed<StepResult>([state, NO_EVENTS])
+    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])
     const decoded = decodeAnthropicStreamBlock(event.content_block)
     if (Option.isNone(decoded)) return invalidStreamEvent(event)
     const block = decoded.value
@@ -1470,7 +1590,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" && !isKnownStreamDeltaType(event.delta.type))
+    if (typeof event.delta.type === "string" && !STREAM_DELTA_TYPES.has(event.delta.type))
       return Effect.succeed<StepResult>([state, NO_EVENTS])
     const decoded = decodeAnthropicStreamDelta(event.delta)
     if (Option.isNone(decoded)) return invalidStreamEvent(event)
@@ -1504,6 +1624,8 @@ 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: {},
@@ -1513,6 +1635,37 @@ 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",
@@ -1522,7 +1675,7 @@ export const route = Route.make({
     baseURL: DEFAULT_BASE_URL,
   }),
   auth: Auth.none,
-  framing,
+  transport: transport<AnthropicMessagesBody>(),
   headers: () => ({ "anthropic-version": "2023-06-01" }),
 })
 

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

@@ -32,17 +32,19 @@ export const PATH = "/responses"
 // =============================================================================
 // Request Body Schema
 // =============================================================================
-const OpenResponsesInputText = Schema.Struct({
+export const OpenResponsesInputText = Schema.Struct({
   type: Schema.tag("input_text"),
   text: Schema.String,
 })
-const OpenResponsesInputImage = Schema.Struct({
+export const OpenResponsesInputImage = Schema.Struct({
   type: Schema.tag("input_image"),
   image_url: Schema.String,
+  detail: Schema.optional(Schema.String),
 })
-const OpenResponsesInputFile = Schema.Struct({
+export 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),
 })
@@ -54,7 +56,7 @@ const MediaInput = Schema.Union([OpenResponsesInputImage, OpenResponsesInputFile
 export type MediaInput = Schema.Schema.Type<typeof MediaInput>
 const OpenResponsesInputContent = Schema.Union([OpenResponsesInputText, MediaInput])
 
-const OpenResponsesOutputText = Schema.Struct({
+export const OpenResponsesOutputText = Schema.Struct({
   type: Schema.tag("output_text"),
   text: Schema.String,
 })
@@ -62,6 +64,13 @@ 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
@@ -72,7 +81,7 @@ const OpenResponsesReasoningSummaryText = Schema.Struct({
   text: Schema.String,
 })
 
-const OpenResponsesReasoningItem = Schema.Struct({
+export const OpenResponsesReasoningItem = Schema.Struct({
   type: Schema.tag("reasoning"),
   id: Schema.optionalKey(Schema.String),
   summary: Schema.Array(OpenResponsesReasoningSummaryText),
@@ -149,16 +158,30 @@ 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) }),
+  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({
     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({
@@ -267,7 +290,7 @@ const OpenResponsesBody = Schema.Struct({
 })
 export type OpenResponsesBody = Schema.Schema.Type<typeof OpenResponsesBody>
 
-const OpenResponsesUsage = Schema.Struct({
+export const OpenResponsesUsage = Schema.Struct({
   input_tokens: Schema.optional(Schema.Number),
   input_tokens_details: optionalNull(
     Schema.Struct({
@@ -387,6 +410,8 @@ export interface ProviderAdapter {
 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
@@ -491,6 +516,9 @@ const lowerMedia = Effect.fn("OpenResponses.lowerMedia")(function* (
   const media = ProviderShared.normalizeMedia(part)
   const providerMedia = adapter.lowerMedia?.({ part, media, request })
   if (providerMedia) return providerMedia
+  const detail = yield* ProviderShared.validateWith(Schema.decodeUnknownEffect(OpenResponsesInputImage.fields.detail))(
+    part.providerMetadata?.[metadataKey(request.model)]?.detail,
+  )
   const url =
     typeof part.data === "string" && (part.data.startsWith("https://") || part.data.startsWith("http://"))
       ? part.data
@@ -501,10 +529,15 @@ 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 }
+  return {
+    type: "input_image" as const,
+    image_url: url ?? media.dataUrl,
+    detail,
+  }
 })
 
 const lowerUserContent = Effect.fnUntraced(function* (
@@ -571,9 +604,12 @@ const lowerMessages = Effect.fn("OpenResponses.lowerMessages")(function* (
   adapter: ProviderAdapter,
 ) {
   const input: LoweredInputItem[] = []
-  const providerMetadataKey = request.model.route.providerMetadataKey ?? "openresponses"
+  const providerMetadataKey = metadataKey(request.model)
 
   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",
@@ -584,7 +620,8 @@ const lowerMessages = Effect.fn("OpenResponses.lowerMessages")(function* (
 
     if (message.role === "user") {
       const content = yield* Effect.forEach(message.content, (part) => lowerUserContent(part, request, adapter))
-      if (content.length > 0) input.push({ role: "user", content })
+      if (content.length > 0)
+        input.push({ role: "user", content, type: metadata?.type, id: metadata?.itemId, status: metadata?.status })
       continue
     }
 
@@ -597,9 +634,10 @@ const lowerMessages = Effect.fn("OpenResponses.lowerMessages")(function* (
         const groups = content.reduce<
           Array<{ id: string | undefined; phase: MessagePhase | null | undefined; parts: TextPart[] }>
         >((groups, part) => {
-          const metadata = part.providerMetadata?.[providerMetadataKey]
-          const id = itemID(part.providerMetadata, providerMetadataKey)
-          const phase = ProviderShared.isRecord(metadata) ? messagePhase(metadata.phase) : undefined
+          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 group = groups.at(-1)
           if (group && group.id === id && group.phase === phase) group.parts.push(part)
           else groups.push({ id, phase, parts: [part] })
@@ -610,6 +648,7 @@ const lowerMessages = Effect.fn("OpenResponses.lowerMessages")(function* (
             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 }),
           })),
@@ -617,6 +656,15 @@ const lowerMessages = Effect.fn("OpenResponses.lowerMessages")(function* (
         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
@@ -693,13 +741,30 @@ const lowerMessages = Effect.fn("OpenResponses.lowerMessages")(function* (
   return input
 })
 
-const lowerOptions = (request: LLMRequest) => {
-  const options = OpenResponsesOptions.resolve(request)
+export const lowerConversation = Effect.fn("OpenResponses.lowerConversation")(function* (
+  request: LLMRequest,
+  adapter: ProviderAdapter,
+) {
   const instructions = ProviderShared.joinText(request.system)
+  return {
+    model: request.model.id,
+    input: yield* lowerMessages(request, adapter),
+    ...(instructions ? { instructions } : {}),
+  }
+})
+
+export const lowerGeneration = (request: LLMRequest) => {
+  const options = OpenResponsesOptions.resolve(request)
+  const generation = request.generation
   const cacheKey = ProviderShared.promptCacheKey(request)
   const parallelToolCalls = resolveParallelToolCalls(request)
   return {
-    ...(instructions ? { instructions } : {}),
+    stream: true as const,
+    max_output_tokens: generation?.maxTokens,
+    temperature: generation?.temperature,
+    top_p: generation?.topP,
+    presence_penalty: generation?.presencePenalty,
+    frequency_penalty: generation?.frequencyPenalty,
     ...(options.store !== undefined ? { store: options.store } : {}),
     ...(options.metadata ? { metadata: options.metadata } : {}),
     ...(options.safetyIdentifier ? { safety_identifier: options.safetyIdentifier } : {}),
@@ -727,7 +792,7 @@ export const resolveParallelToolCalls = (request: LLMRequest) => {
   return disabled === undefined ? undefined : !disabled
 }
 
-const allowedToolChoice = (request: LLMRequest) => {
+export const allowedToolChoice = (request: LLMRequest) => {
   const allowed = OpenResponsesOptions.resolve(request).allowedTools
   if (!allowed) return undefined
   return {
@@ -741,11 +806,10 @@ export const fromRequestWithAdapter = Effect.fn("OpenResponses.fromRequestWithAd
   request: LLMRequest,
   adapter: ProviderAdapter,
 ) {
-  const generation = request.generation
   const toolSchemaCompatibility = request.model.compatibility?.toolSchema
   return {
-    model: request.model.id,
-    input: yield* lowerMessages(request, adapter),
+    ...(yield* lowerConversation(request, adapter)),
+    ...lowerGeneration(request),
     tools:
       request.tools.length === 0
         ? undefined
@@ -759,13 +823,6 @@ export const fromRequestWithAdapter = Effect.fn("OpenResponses.fromRequestWithAd
     tool_choice:
       allowedToolChoice(request) ??
       (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),
   }
 })
 
@@ -782,7 +839,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.
-const mapUsage = (usage: OpenResponsesUsage | null | undefined, providerMetadataKey: string) => {
+export 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
@@ -812,6 +869,8 @@ 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,
 })
@@ -1093,6 +1152,25 @@ 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) {
     if (state.completedMessages.has(item.id)) return [state, NO_EVENTS] satisfies StepResult
     const completedMessages = new Set(state.completedMessages)
@@ -1257,29 +1335,38 @@ 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" ||
-        !item.call_id ||
-        !Object.values(current.tools).some((tool) => tool?.id === item.call_id)
+        item.type === "function_call" &&
+        (!item.call_id || !Object.values(current.tools).some((tool) => tool?.id === item.call_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, hasFunctionCall),
+      normalized: mapFinishReason(event, current.hasFunctionCall),
       raw: event.response?.incomplete_details?.reason,
     },
     usage: mapUsage(event.response?.usage, current.providerMetadataKey),
@@ -1291,7 +1378,7 @@ const onResponseFinish = Effect.fn("OpenResponses.onResponseFinish")(function* (
           })
         : undefined,
   })
-  return [{ ...current, lifecycle, hasFunctionCall, tools: pending.tools }, events] satisfies StepResult
+  return [{ ...current, lifecycle }, events] satisfies StepResult
 })
 
 // Build the prettiest summary available from whatever the provider supplied.
@@ -1426,9 +1513,11 @@ export const step = (state: ParserState, input: Event) => {
  * implementations compose this baseline with their own tools and event variants.
  */
 export const initial = (request: LLMRequest, adapter: ProviderAdapter = BASE_ADAPTER): ParserState => ({
+  provider: request.model.provider,
+  completedCompactions: new Set<string>(),
   id: adapter.id,
   name: adapter.name,
-  providerMetadataKey: request.model.route.providerMetadataKey ?? "openresponses",
+  providerMetadataKey: metadataKey(request.model),
   hasFunctionCall: false,
   tools: ToolStream.empty<string>(),
   completedTools: new Set<string>(),

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

@@ -5,13 +5,14 @@ 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 { LLMRequest, type JsonSchema, type ToolDefinition } from "../schema/index.js"
+import type { LLMRequest, JsonSchema, 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"
@@ -20,6 +21,14 @@ 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"])),
@@ -78,6 +87,14 @@ 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({
@@ -125,15 +142,14 @@ const lowerToolChoice = (toolChoice: NonNullable<LLMRequest["toolChoice"]>, tool
 const decodeBody = ProviderShared.validateWith(Schema.decodeUnknownEffect(OpenAIResponsesBody))
 
 const fromRequest = Effect.fn("OpenAIResponses.fromRequest")(function* (request: LLMRequest) {
-  const body = yield* OpenResponses.fromRequestWithAdapter(
-    LLMRequest.update(request, { tools: [], toolChoice: undefined }),
-    adapter,
-  )
+  const management = yield* ProviderShared.validateWith(
+    Schema.decodeUnknownEffect(Schema.UndefinedOr(ContextManagement)),
+  )(request.providerOptions?.contextManagement)
   const toolSchemaCompatibility = request.model.compatibility?.toolSchema
-  const parallelToolCalls = OpenResponses.resolveParallelToolCalls(request)
   return yield* decodeBody({
-    ...body,
-    ...(parallelToolCalls === undefined ? {} : { parallel_tool_calls: parallelToolCalls }),
+    ...(yield* OpenResponses.lowerConversation(request, adapter)),
+    ...OpenResponses.lowerGeneration(request),
+    context_management: management?.map((edit) => ({ type: edit.type, compact_threshold: edit.compactThreshold })),
     tools:
       request.tools.length === 0
         ? undefined
@@ -141,7 +157,8 @@ const fromRequest = Effect.fn("OpenAIResponses.fromRequest")(function* (request:
             lowerTool(tool, ToolSchemaProjection.modelCompatibility(tool.inputSchema, toolSchemaCompatibility)),
           ),
     tool_choice:
-      body.tool_choice ?? (request.toolChoice ? yield* lowerToolChoice(request.toolChoice, request.tools) : undefined),
+      OpenResponses.allowedToolChoice(request) ??
+      (request.toolChoice ? yield* lowerToolChoice(request.toolChoice, request.tools) : undefined),
   })
 })
 
@@ -223,6 +240,7 @@ export const transport = channelTransport({
 })
 
 export const route = Route.make({
+  compact: ResponsesCompaction.make(adapter),
   id: ADAPTER,
   provider: "openai",
   providerMetadataKey: "openai",

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

@@ -0,0 +1,174 @@
+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 = (adapter: OpenResponses.ProviderAdapter): CompactOperation =>
+  Effect.fn("ResponsesCompaction.execute")(function* (request, executor, options) {
+    const route = request.model.route
+    const native = yield* OpenResponses.lowerConversation(request, adapter)
+    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({
+      replacement: 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,6 +4,7 @@ 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"
@@ -44,6 +45,10 @@ const adapter = {
 
 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.fromRequestWithAdapter(request, adapter))
 })
 
@@ -84,4 +89,6 @@ export const protocol = Protocol.make({
   },
 })
 
+export const compact = ResponsesCompaction.make(adapter)
+
 export * as XAIResponses from "./xai-responses.js"

packages/ai/src/provider-package.ts

@@ -1,4 +1,5 @@
 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
@@ -9,8 +10,9 @@ 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>
+  readonly model: (modelID: string, settings: ProviderSettings) => LanguageModel<Options, Compact>
 }
 
 export * as ProviderPackage from "./provider-package.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 as RouteDef, RouteDefaultsInput } from "../route/client.js"
+import type { Route, RouteDefaultsInput, CompactOperation } 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,7 +102,11 @@ const auth = (input: Config) => {
   )
 }
 
-const configuredRoute = <Body, Prepared>(route: RouteDef<Body, Prepared>, input: Config, modelID: string | ModelID) =>
+const configuredRoute = <Body, Prepared, Compact extends CompactOperation | undefined>(
+  route: Route<Body, Prepared, Compact>,
+  input: Config,
+  modelID: string | ModelID,
+) =>
   route.with({
     auth: auth(input),
     endpoint: endpoint(input, modelID),
@@ -161,10 +165,11 @@ const config = (settings: Settings): Config => {
   throw new Error("Azure requires resourceName or baseURL")
 }
 
-export const responsesModel: ProviderPackage.Definition<Settings, OpenAIProviderOptionsInput>["model"] = (
-  modelID,
-  settings,
-) => configure(config(settings)).responses(modelID)
+export const responsesModel: ProviderPackage.Definition<
+  Settings,
+  OpenAIProviderOptionsInput,
+  CompactOperation
+>["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,7 +57,9 @@ const route = Route.make({
   }),
   endpoint: Endpoint.path(({ request }) => `/${request.model.id}:streamRawPredict`),
   auth: Auth.none,
-  framing: AnthropicMessages.framing,
+  transport: AnthropicMessages.transport<
+    Omit<AnthropicMessages.AnthropicMessagesBody, "model"> & { readonly anthropic_version: typeof VERSION }
+  >(),
   headers: () => ({ "anthropic-version": HEADER_VERSION }),
 })
 

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

@@ -1,10 +1,13 @@
 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"> & {
+  /** Advanced in-band compaction. The caller owns checkpoint persistence and recovery. */
+  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 } from "../route/client.js"
+import type { Route, RouteDefaultsInput, CompactOperation } 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,7 +73,10 @@ const defaults = (input: Config) => {
   return rest
 }
 
-const configuredRoute = <Body, Prepared>(route: Route<Body, Prepared>, input: Config) =>
+const configuredRoute = <Body, Prepared, Compact extends CompactOperation | undefined>(
+  route: Route<Body, Prepared, Compact>,
+  input: Config,
+) =>
   route.with({
     auth: auth(input),
     endpoint: { baseURL: input.baseURL, query: input.queryParams },
@@ -129,7 +132,10 @@ const config = (settings: Settings): Config => {
   }
 }
 
-export const model: ProviderPackage.Definition<Settings, OpenAIProviderOptionsInput>["model"] = (modelID, settings) => {
+export const model: ProviderPackage.Definition<Settings, OpenAIProviderOptionsInput, CompactOperation>["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 } from "../route/client.js"
+import { Route, type RouteDefaultsInput, type CompactOperation } 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
+export type XAIProviderOptionsInput = OpenAIOptionsInput & { readonly contextManagement?: never }
 
 export type LanguageModelOptions = Omit<RouteDefaultsInput, "providerOptions"> &
   ProviderAuthOption<"optional"> & {
@@ -32,6 +32,7 @@ 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",
@@ -102,7 +103,10 @@ export const configure = (input: LanguageModelOptions = {}) => {
 }
 
 export const provider = configure()
-export const model: ProviderPackage.Definition<Settings, XAIProviderOptionsInput>["model"] = (modelID, settings) =>
+export const model: ProviderPackage.Definition<Settings, XAIProviderOptionsInput, CompactOperation>["model"] = (
+  modelID,
+  settings,
+) =>
   configure({
     apiKey: settings.apiKey,
     baseURL: settings.baseURL,

packages/ai/src/route/client.ts

@@ -13,6 +13,7 @@ import * as ProviderShared from "../protocols/shared.js"
 import type { ProtocolID, ProviderOptions } from "../schema/index.js"
 import {
   AIError,
+  CompactionResponse,
   AIErrorReason,
   GenerationOptions,
   HttpOptions,
@@ -34,7 +35,12 @@ export interface RouteBody<Body> {
   readonly from: (request: LLMRequest) => Effect.Effect<Body, AIError>
 }
 
-export interface Route<Body, Prepared = unknown> {
+export interface Route<
+  Body,
+  Prepared = unknown,
+  Compact extends CompactOperation | undefined = CompactOperation | undefined,
+> {
+  readonly compact: Compact
   readonly id: string
   readonly provider?: ProviderID
   /** ProviderMetadata namespace emitted and consumed by this route. */
@@ -42,13 +48,15 @@ export interface Route<Body, Prepared = unknown> {
   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>
+  readonly with: (patch: RoutePatch<Body, Prepared>) => Route<Body, Prepared, Compact>
   readonly model: <Options extends ProviderOptions = ProviderOptions>(
     input: RouteMappedLanguageModelInput,
-  ) => LanguageModel<Options>
+  ) => LanguageModel<Options, Compact>
   readonly prepareTransport: (
     body: Body,
     request: LLMRequest,
@@ -66,7 +74,11 @@ export interface Route<Body, Prepared = unknown> {
 // 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 = Route<any, any>
+export type AnyRoute<Compact extends CompactOperation | undefined = CompactOperation | undefined> = Route<
+  any,
+  any,
+  Compact
+>
 
 export type HttpOptionsInput = HttpOptions.Input
 
@@ -99,15 +111,15 @@ export interface RoutePatch<Body, Prepared> extends RouteDefaultsInput {
 
 type RouteMappedLanguageModelInput = RouteLanguageModelInput | RouteRoutedLanguageModelInput
 
-const makeRouteLanguageModel = <Options extends ProviderOptions = ProviderOptions>(
-  route: AnyRoute,
+const makeRouteLanguageModel = <Options extends ProviderOptions, Compact extends CompactOperation | undefined>(
+  route: AnyRoute<Compact>,
   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>({
+  return LanguageModel.make<Options, Compact>({
     ...mapped,
     provider,
     route,
@@ -150,6 +162,10 @@ 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
 }
@@ -167,6 +183,19 @@ 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 & {
+  readonly model: 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) => {
@@ -187,6 +216,7 @@ 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. */
@@ -208,6 +238,7 @@ 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. */
@@ -283,12 +314,14 @@ 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,
@@ -310,7 +343,7 @@ function makeFromTransport<Body, Prepared, Frame, Event, State>(
         })
       },
       model: <Options extends ProviderOptions = ProviderOptions>(input: RouteMappedLanguageModelInput) =>
-        makeRouteLanguageModel<Options>(route, input),
+        makeRouteLanguageModel<Options, CompactOperation | undefined>(route, input),
       prepareTransport: (body, request, options) =>
         routeInput.transport.prepare({
           body,
@@ -318,7 +351,6 @@ 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,
         }),
@@ -408,6 +440,12 @@ 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>
@@ -435,6 +473,7 @@ 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,
@@ -447,11 +486,19 @@ export function make<Body, Prepared, Frame, Event, State>(
   })
 }
 
-const compile = Effect.fn("LLM.compile")(function* (request: LLMRequest, options?: StreamOptions) {
+const prepareRequest = (request: LLMRequest) => {
   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
@@ -510,6 +557,15 @@ 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* () {
@@ -520,16 +576,29 @@ export const streamRequest = (request: LLMRequest, options?: StreamOptions) =>
 export const layer: Layer.Layer<Service, never, RequestExecutor.Service> = Layer.effect(
   Service,
   Effect.gen(function* () {
-    const stream = streamRequestWith({
-      http: yield* RequestExecutor.Service,
+    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)
+        }),
     })
-    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,6 +3,7 @@ import { LLM } from "@opencode-ai/schema/llm"
 import { ContentBlockID, ToolCallID } from "./ids.js"
 import {
   Message,
+  CompactionPart,
   ProviderMetadata,
   ToolCallPart,
   ToolOutput,
@@ -62,6 +63,8 @@ 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),
@@ -72,7 +75,7 @@ export class Usage extends Schema.Class<Usage>("AI.Usage")({
   providerMetadata: Schema.optional(ProviderMetadata),
 }) {
   /**
-   * Visible output tokens — `outputTokens` minus `reasoningTokens`, clamped
+   * Non-reasoning output tokens (including compaction summaries) — `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.
@@ -88,6 +91,12 @@ export class Usage extends Schema.Class<Usage>("AI.Usage")({
 
 export type UsageInput = Usage | ConstructorParameters<typeof Usage>[0]
 
+/** A replacement context window, not an assistant message to append to prior history. */
+export class CompactionResponse extends Schema.Class<CompactionResponse>("LLM.CompactionResponse")({
+  replacement: Schema.Array(Message),
+  usage: Schema.optional(Usage),
+}) {}
+
 export const StepStart = Schema.Struct({
   type: Schema.tag("step-start"),
   index: Schema.Number,
@@ -241,6 +250,7 @@ export const ProviderErrorEvent = Schema.Struct({
 export type ProviderErrorEvent = Schema.Schema.Type<typeof ProviderErrorEvent>
 
 const llmEventTagged = Schema.Union([
+  CompactionPart,
   StepStart,
   TextStart,
   TextDelta,
@@ -274,6 +284,7 @@ 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) }),
@@ -311,6 +322,7 @@ 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"],
@@ -333,10 +345,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 = <Delta extends { id: string; text: string }, End extends { id: string; text?: string }>(
+const joinFragments = (
   events: ReadonlyArray<LLMEvent>,
-  isDelta: (event: LLMEvent) => event is Extract<LLMEvent, Delta>,
-  isEnd: (event: LLMEvent) => event is Extract<LLMEvent, End>,
+  isDelta: (event: LLMEvent) => event is LLMEvent & { id: string; text: string },
+  isEnd: (event: LLMEvent) => event is LLMEvent & { id: string; text?: string },
 ) => {
   const order: string[] = []
   const parts = new Map<string, string>()
@@ -563,6 +575,8 @@ 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,8 +7,10 @@ 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>
@@ -52,6 +54,7 @@ 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>
 
@@ -185,9 +188,40 @@ export const ReasoningPart = Schema.Struct({
 }).annotate({ identifier: "LLM.Content.Reasoning" })
 export type ReasoningPart = Schema.Schema.Type<typeof ReasoningPart>
 
-export const ContentPart = Schema.Union([TextPart, MediaPart, ToolCallPart, ToolResultPart, ReasoningPart]).pipe(
-  Schema.toTaggedUnion("type"),
-)
+/** 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 type ContentPart = Schema.Schema.Type<typeof ContentPart>
 
 export class Message extends Schema.Class<Message>("LLM.Message")({
@@ -195,6 +229,7 @@ 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)),
 }) {}
 
@@ -272,7 +307,7 @@ export namespace ToolChoice {
   }
 }
 
-export class LLMRequest extends Schema.Class<LLMRequest>("LLM.Request")({
+const requestSchema = Schema.Struct({
   id: Schema.optional(Schema.String),
   model: LanguageModelSchema,
   system: Schema.Array(SystemPart),
@@ -286,12 +321,26 @@ export class LLMRequest extends Schema.Class<LLMRequest>("LLM.Request")({
   // 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 = ConstructorParameters<typeof LLMRequest>[0]
+  export type Input<Model extends LanguageModel = LanguageModel> = Omit<typeof requestSchema.Type, "model"> & {
+    readonly model: Model
+  }
 
-  export const input = (request: LLMRequest): Input => ({
+  export const input = <Model extends LanguageModel>(request: LLMRequest<Model>): Input<Model> => ({
     id: request.id,
     model: request.model,
     system: request.system,
@@ -306,7 +355,16 @@ export namespace LLMRequest {
     metadata: request.metadata,
   })
 
-  export const update = (request: LLMRequest, patch: Partial<Input>) => {
+  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>) {
     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 } from "../route/client.js"
+import type { AnyRoute, CompactOperation } from "../route/client.js"
 import { isRecord } from "../utils/record.js"
 
 export const JsonSchema = Schema.Record(Schema.String, Schema.Unknown)
@@ -173,15 +173,18 @@ export namespace LanguageModelCompatibility {
     input instanceof LanguageModelCompatibility ? input : new LanguageModelCompatibility(input)
 }
 
-export class LanguageModel<Options extends ProviderOptions = ProviderOptions> {
+export class LanguageModel<
+  Options extends ProviderOptions = ProviderOptions,
+  Compact extends CompactOperation | undefined = CompactOperation | undefined,
+> {
   declare protected readonly _ProviderOptions: Options
   readonly id: ModelID
   readonly provider: ProviderID
-  readonly route: AnyRoute
+  readonly route: AnyRoute<Compact>
   readonly defaults?: LanguageModelDefaults
   readonly compatibility?: LanguageModelCompatibility
 
-  constructor(input: LanguageModel.ConstructorInput) {
+  constructor(input: LanguageModel.ConstructorInput<Compact>) {
     this.id = input.id
     this.provider = input.provider
     this.route = input.route
@@ -189,8 +192,11 @@ export class LanguageModel<Options extends ProviderOptions = ProviderOptions> {
     this.compatibility = input.compatibility
   }
 
-  static make<Options extends ProviderOptions = ProviderOptions>(input: LanguageModel.Input) {
-    return new LanguageModel<Options>({
+  static make<
+    Options extends ProviderOptions = ProviderOptions,
+    Compact extends CompactOperation | undefined = CompactOperation | undefined,
+  >(input: LanguageModel.Input<Compact>) {
+    return new LanguageModel<Options, Compact>({
       id: ModelID.make(input.id),
       provider: ProviderID.make(input.provider),
       route: input.route,
@@ -200,7 +206,9 @@ export class LanguageModel<Options extends ProviderOptions = ProviderOptions> {
     })
   }
 
-  static input<Options extends ProviderOptions>(model: LanguageModel<Options>): LanguageModel.ConstructorInput {
+  static input<Options extends ProviderOptions, Compact extends CompactOperation | undefined>(
+    model: LanguageModel<Options, Compact>,
+  ): LanguageModel.ConstructorInput<Compact> {
     return {
       id: model.id,
       provider: model.provider,
@@ -210,25 +218,41 @@ export class LanguageModel<Options extends ProviderOptions = ProviderOptions> {
     }
   }
 
+  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 = {
+  export type ConstructorInput<Compact extends CompactOperation | undefined = CompactOperation | undefined> = {
     readonly id: ModelID
     readonly provider: ProviderID
-    readonly route: AnyRoute
+    readonly route: AnyRoute<Compact>
     readonly defaults?: LanguageModelDefaults
     readonly compatibility?: LanguageModelCompatibility
   }
 
-  export type Input = Omit<ConstructorInput, "id" | "provider" | "defaults" | "compatibility"> & {
+  export type Input<Compact extends CompactOperation | undefined = CompactOperation | undefined> = Omit<
+    ConstructorInput<Compact>,
+    "id" | "provider" | "defaults" | "compatibility"
+  > & {
     readonly id: string | ModelID
     readonly provider: string | ProviderID
     readonly defaults?: LanguageModelDefaults.Input

packages/ai/src/testing.ts

@@ -4,6 +4,7 @@ import { LLMClient } from "./route/client.js"
 import {
   LLMEvent,
   LLMResponse,
+  CompactionResponse,
   type FinishReasonDetails,
   type AIError,
   type LLMRequest,
@@ -12,7 +13,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>
+export type Response = readonly LLMEvent[] | Stream.Stream<LLMEvent, AIError> | CompactionResponse
 
 export type Gate = Readonly<{ started: Effect.Effect<void>; release: Effect.Effect<void> }>
 
@@ -99,8 +100,6 @@ 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[] = []
@@ -113,26 +112,41 @@ const make = (options: LayerOptions) =>
         requests.length >= count ? Effect.void : Deferred.await(started).pipe(Effect.andThen(wait(count))),
       )
 
-    const stream: ClientInterface["stream"] = (request) =>
-      Stream.suspend(() => {
+    const take = (request: LLMRequest) =>
+      Effect.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 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)),
-          )
+          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))
         } 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,6 +56,7 @@ function normalizeToolMessage(message: Message, pending: Map<string, ToolCallPar
     role: message.role,
     content,
     metadata: message.metadata,
+    providerMetadata: message.providerMetadata,
     native: message.native,
   })
 }

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

@@ -0,0 +1,97 @@
+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.replacement, 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

@@ -0,0 +1,77 @@
+import { expect, test } from "bun:test"
+import { Schema } from "effect"
+import { CompactionPart, CompactionResponse, 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("explicit compaction serializes a replacement window without a messages alias", () => {
+  const response = new CompactionResponse({
+    replacement: [
+      Message.user("retained input"),
+      Message.assistant(CompactionPart.make({ provider: ProviderID.make("openai"), encrypted: "checkpoint" })),
+    ],
+  })
+  const codec = Schema.fromJsonString(CompactionResponse)
+  const decoded = Schema.decodeSync(codec)(Schema.encodeSync(codec)(response))
+  expect(decoded.replacement).toEqual(response.replacement)
+  expect("messages" in decoded).toBe(false)
+})
+
+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

@@ -0,0 +1,133 @@
+import { Effect } from "effect"
+import {
+  CompactionPart,
+  LanguageModel,
+  LLM,
+  LLMClient,
+  LLMEvent,
+  LLMRequest,
+  Message,
+  ProviderID,
+} from "../../src/index.js"
+import { OpenAI, Azure, XAI, Anthropic, 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") }),
+  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 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.replacement satisfies ReadonlyArray<Message>
+    // @ts-expect-error The replacement window is named explicitly; the old field is not an alias.
+    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" }],
+  },
+})
+const anthropic = Anthropic.configure().model("claude-opus-4-6")
+LLM.request({
+  model: anthropic,
+  providerOptions: {
+    contextManagement: {
+      edits: [{ type: "compact_20260112", pauseAfterCompaction: true, instructions: "Summarize without using tools" }],
+    },
+  },
+})
+LLM.request({
+  model: anthropic,
+  providerOptions: {
+    // @ts-expect-error A pause setting is boolean.
+    contextManagement: { edits: [{ type: "compact_20260112", pauseAfterCompaction: "yes" }] },
+  },
+})

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

@@ -0,0 +1,170 @@
+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/compaction-websocket.test.ts

@@ -0,0 +1,50 @@
+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

@@ -0,0 +1,91 @@
+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.replacement,
+              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

@@ -0,0 +1,136 @@
+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

@@ -0,0 +1,30 @@
+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/explicit-compaction.test.ts

@@ -0,0 +1,447 @@
+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, OpenAICompatibleResponses } 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.replacement[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.replacement.map((message) => message.role)).toEqual([
+        "user",
+        "assistant",
+        "assistant",
+        "assistant",
+        "user",
+        "assistant",
+      ])
+      expect(compacted.replacement[1]?.content).toEqual([
+        { type: "text", text: "First" },
+        { type: "text", text: "Second" },
+      ])
+      expect(compacted.replacement[2]?.content.map((part) => part.type)).toEqual(["reasoning", "reasoning"])
+      expect(compacted.replacement[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.replacement))
+      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.replacement))
+      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.replacement.map((message) => message.role)).toEqual(["user", "assistant"])
+      expect(compacted.replacement[0]?.content).toEqual([{ type: "text", text: "retained" }])
+      expect(compacted.replacement[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.replacement))
+      yield* LLMClient.generate(LLMRequest.update(request, { messages: [...messages, Message.user("continue")] }))
+    }),
+  )
+}
+
+for (const model of [
+  Anthropic.configure({ apiKey: "test" }).model("claude-opus-4-6"),
+  OpenAICompatibleResponses.configure({ apiKey: "test", baseURL: "https://compatible.example/v1" }).model("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

@@ -0,0 +1,60 @@
+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/testing.test.ts

@@ -1,5 +1,18 @@
 import { describe, expect } from "bun:test"
-import { AIError, LanguageModel, LLM, LLMClient, LLMEvent, LLMRequest, RateLimitError } from "../src/index.js"
+import {
+  AIError,
+  CompactionPart,
+  CompactionResponse,
+  LanguageModel,
+  LLM,
+  LLMClient,
+  LLMEvent,
+  LLMRequest,
+  Message,
+  ProviderID,
+  RateLimitError,
+} from "../src/index.js"
+import { OpenAI } from "../src/providers.js"
 import { OpenAIChat } from "../src/protocols/openai-chat.js"
 import { TestLLM } from "../src/testing.js"
 import { Effect, Fiber, Latch, Stream } from "effect"
@@ -66,6 +79,54 @@ 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({ replacement: [] }))
+      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({
+        replacement: [
+          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.replacement })
+      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/cli/src/acp/service.ts

@@ -400,7 +400,8 @@ function turnStart(messageID: string, slash: PreparedPrompt["slash"], skill: Ski
 
 async function loadCatalog(client: OpenCodeClient, cwd: string): Promise<Catalog> {
   const location = { directory: cwd }
-  // Location plugins initialize asynchronously, so the first ACP request may observe an empty catalog.
+  await client.plugin.awaitActivation({ location })
+  // Some providers discover models in the background after activation has settled.
   const deadline = Date.now() + 5_000
   let missing = "No models are available"
   while (Date.now() < deadline) {

packages/cli/test/acp/service-directory.test.ts

@@ -1,9 +1,50 @@
 import { describe, expect, test } from "bun:test"
 import type { McpServer, SessionConfigOption } from "@agentclientprotocol/sdk"
-import { makeACPFixture, makeSession, secondModel } from "./service-fixture"
+import { makeACPFixture, makeSession, secondModel, testModel } from "./service-fixture"
 import { flattenSelectOptions, requireSelectOption } from "./subprocess"
 
 describe("acp service directory behavior", () => {
+  test("does not cache an available model before plugin activation settles", async () => {
+    const requested = Promise.withResolvers<void>()
+    const release = Promise.withResolvers<void>()
+    let ready = false
+    await using fixture = makeACPFixture({
+      fetch(request) {
+        requested.resolve()
+        if (request.path === "/api/plugin/await-activation") {
+          return release.promise.then(() => {
+            ready = true
+            return new Response(null, { status: 204 })
+          })
+        }
+        if (!ready && request.path === "/api/model") {
+          return Response.json({ data: [{ ...testModel, providerID: "ambient" }] })
+        }
+        if (!ready && request.path === "/api/model/default") {
+          return Response.json({ data: { ...testModel, providerID: "ambient" } })
+        }
+        if (request.path === "/api/session" && request.method === "POST") {
+          return Response.json({ data: { ...makeSession("ses_ready"), model: undefined } })
+        }
+        return undefined
+      },
+    })
+    const pending = fixture.service.newSession({ cwd: "/workspace", mcpServers: [] })
+    try {
+      await requested.promise
+      expect(fixture.requests.map((request) => request.path)).toEqual(["/api/plugin/await-activation"])
+      expect(fixture.requests[0]?.query["location[directory]"]).toBe("/workspace")
+      release.resolve()
+      expect(currentValue(await pending, "model")).toBe("test/test-model")
+      expect(
+        fixture.requests.find((request) => request.path === "/api/session" && request.method === "POST")?.body,
+      ).toMatchObject({ model: { providerID: "test", id: "test-model" } })
+    } finally {
+      release.resolve()
+      await pending.catch(() => {})
+    }
+  })
+
   test("creates sessions from a catalog shared by concurrent callers in the same cwd", async () => {
     let created = 0
     await using fixture = makeACPFixture({
@@ -27,7 +68,14 @@ describe("acp service directory behavior", () => {
     expect(currentValue(first[0], "model")).toBe("test/test-model")
     expect(currentValue(first[0], "mode")).toBe("build")
     expect(
-      ["/api/model", "/api/model/default", "/api/agent", "/api/command", "/api/skill"].map((path) =>
+      [
+        "/api/plugin/await-activation",
+        "/api/model",
+        "/api/model/default",
+        "/api/agent",
+        "/api/command",
+        "/api/skill",
+      ].map((path) =>
         fixture.requests
           .filter((request) => request.path === path)
           .map((request) => request.query["location[directory]"]),
@@ -38,6 +86,7 @@ describe("acp service directory behavior", () => {
       ["/workspace", "/other"],
       ["/workspace", "/other"],
       ["/workspace", "/other"],
+      ["/workspace", "/other"],
     ])
     expect(
       fixture.requests

packages/cli/test/acp/service-fixture.ts

@@ -152,6 +152,7 @@ export function makeACPFixture(options: FixtureOptions = {}) {
 
       const directory = request.query["location[directory]"] ?? "/workspace"
       const location = { directory, project: { id: "global", directory } }
+      if (request.path === "/api/plugin/await-activation") return new Response(null, { status: 204 })
       if (request.path === "/api/event") {
         let controller: ReadableStreamDefaultController<Uint8Array> | undefined
         return new Response(

packages/cli/test/acp/service.test.ts

@@ -18,6 +18,7 @@ describe("acp service", () => {
           body: request.method === "GET" ? undefined : await request.json().catch(() => undefined),
         })
         const location = { directory: "/workspace", project: { id: "global", directory: "/workspace" } }
+        if (url.pathname === "/api/plugin/await-activation") return new Response(null, { status: 204 })
         if (url.pathname === "/api/model") return Response.json({ location, data: [model] })
         if (url.pathname === "/api/model/default") return Response.json({ location, data: model })
         if (url.pathname === "/api/agent") return Response.json({ location, data: [agent] })

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

@@ -88,6 +88,14 @@ export type PluginListInput = {
 export type PluginListOutput = { readonly location: Location.Info; readonly data: ReadonlyArray<Plugin.Info> }
 export type PluginListOperation<E = never> = (input?: PluginListInput) => Effect.Effect<PluginListOutput, E>
 
+export type PluginAwaitActivationInput = {
+  readonly location?: { readonly directory?: string | undefined; readonly workspace?: string | undefined } | undefined
+}
+export type PluginAwaitActivationOutput = void
+export type PluginAwaitActivationOperation<E = never> = (
+  input?: PluginAwaitActivationInput,
+) => Effect.Effect<PluginAwaitActivationOutput, E>
+
 export type PluginCheckInput = {
   readonly location?: { readonly directory?: string | undefined; readonly workspace?: string | undefined } | undefined
   readonly target?: string | undefined
@@ -104,6 +112,7 @@ export type PluginUpdateOperation<E = never> = (input: PluginUpdateInput) => Eff
 
 export interface PluginApi<E = never> {
   readonly list: PluginListOperation<E>
+  readonly awaitActivation: PluginAwaitActivationOperation<E>
   readonly check: PluginCheckOperation<E>
   readonly update: PluginUpdateOperation<E>
 }

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

@@ -15,6 +15,8 @@ import type {
   AgentGetOutput,
   PluginListInput,
   PluginListOutput,
+  PluginAwaitActivationInput,
+  PluginAwaitActivationOutput,
   PluginCheckInput,
   PluginCheckOutput,
   PluginUpdateInput,
@@ -326,6 +328,11 @@ const EndpointPluginList = (raw: RawClient["server.plugin"]) => (input?: PluginL
     raw["plugin.list"]({ query: { location: input?.["location"] } }).pipe(Effect.mapError(mapClientError)),
   )
 
+const EndpointPluginAwaitActivation = (raw: RawClient["server.plugin"]) => (input?: PluginAwaitActivationInput) =>
+  preserveEffect<PluginAwaitActivationOutput>()(
+    raw["plugin.awaitActivation"]({ query: { location: input?.["location"] } }).pipe(Effect.mapError(mapClientError)),
+  )
+
 const EndpointPluginCheck = (raw: RawClient["server.plugin"]) => (input?: PluginCheckInput) =>
   preserveEffect<PluginCheckOutput>()(
     raw["plugin.check"]({ query: { location: input?.["location"] }, payload: { target: input?.["target"] } }).pipe(
@@ -342,6 +349,7 @@ const EndpointPluginUpdate = (raw: RawClient["server.plugin"]) => (input: Plugin
 
 const adaptGroupPlugin = (raw: RawClient["server.plugin"]) => ({
   list: EndpointPluginList(raw),
+  awaitActivation: EndpointPluginAwaitActivation(raw),
   check: EndpointPluginCheck(raw),
   update: EndpointPluginUpdate(raw),
 })

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

@@ -9,6 +9,8 @@ import type {
   AgentGetOutput,
   PluginListInput,
   PluginListOutput,
+  PluginAwaitActivationInput,
+  PluginAwaitActivationOutput,
   PluginCheckInput,
   PluginCheckOutput,
   PluginUpdateInput,
@@ -470,6 +472,18 @@ export function make(options: ClientOptions) {
           },
           requestOptions,
         ),
+      awaitActivation: (input?: PluginAwaitActivationInput, requestOptions?: RequestOptions) =>
+        request<PluginAwaitActivationOutput>(
+          {
+            method: "POST",
+            path: `/api/plugin/await-activation`,
+            query: { location: input?.["location"] },
+            successStatus: 204,
+            declaredStatuses: [400, 401],
+            empty: true,
+          },
+          requestOptions,
+        ),
       check: (input?: PluginCheckInput, requestOptions?: RequestOptions) =>
         request<PluginCheckOutput>(
           {

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

@@ -2585,6 +2585,14 @@ export type PluginListOutput = {
   data: Array<PluginInfo>
 }
 
+export type PluginAwaitActivationInput = {
+  readonly location?: {
+    readonly location?: { readonly directory?: string | undefined; readonly workspace?: string | undefined } | undefined
+  }["location"]
+}
+
+export type PluginAwaitActivationOutput = void
+
 export type PluginCheckInput = {
   readonly location?: {
     readonly location?: { readonly directory?: string | undefined; readonly workspace?: string | undefined } | undefined

packages/core/src/agent.ts

@@ -87,7 +87,7 @@ const layer = Layer.effect(
           draft.agents.delete(id)
         },
       }),
-      finalize: () => bus.publish(Agent.Event.Updated, {}).pipe(Effect.asVoid),
+      notify: bus.publish(Agent.Event.Updated, {}).pipe(Effect.asVoid),
     })
     const selectable = (agent: Info | undefined) =>
       agent && agent.mode !== "subagent" && !agent.hidden ? agent : undefined

packages/core/src/aisdk.ts

@@ -306,6 +306,7 @@ function modelFromLanguage(info: Info, language: LanguageModelV3) {
   const providerID = info.canonical ?? info.providerID
   const optionKey = providerOptionKey(packageName, providerID)
   const route: AnyRoute = {
+    compact: undefined,
     id: `ai-sdk:${packageName}`,
     provider: ProviderID.make(providerID),
     providerMetadataKey: optionKey,
@@ -330,7 +331,12 @@ function modelFromLanguage(info: Info, language: LanguageModelV3) {
     },
     body: {
       schema: Schema.Unknown,
-      from: (request) => Effect.succeed(callOptions(request, packageName, info.modelID ?? info.id, optionKey)),
+      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),
+        }),
     },
     with: () => route,
     model: (input) =>
@@ -515,6 +521,8 @@ 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/catalog.ts

@@ -135,9 +135,7 @@ const layer = Layer.effect(
         }
         return result
       },
-      finalize: Effect.fn("Catalog.finalize")(function* () {
-        yield* bus.publish(Catalog.Event.Updated, {})
-      }),
+      notify: bus.publish(Catalog.Event.Updated, {}).pipe(Effect.asVoid, Effect.withSpan("Catalog.notify")),
     })
     const result: Interface = {
       transform: state.transform,

packages/core/src/command.ts

@@ -60,7 +60,7 @@ export const layer = Layer.effect(
       draft: (draft) => ({
         add: (definition) => draft.set(definition.name, definition),
       }),
-      finalize: () => bus.publish(Command.Event.Updated, {}).pipe(Effect.asVoid),
+      notify: bus.publish(Command.Event.Updated, {}).pipe(Effect.asVoid),
     })
     const info = (definition: Definition) =>
       Info.make({

packages/core/src/filesystem/location-watcher-policy.ts

@@ -25,7 +25,6 @@ export class Service extends Context.Service<Service, Interface>()("@opencode/Lo
 const layer = Layer.effect(
   Service,
   Effect.gen(function* () {
-    let current: readonly string[] = []
     const listeners = new Set<(ignore: readonly string[]) => Effect.Effect<void>>()
     const state = State.create<Data, Draft>({
       name: "location-watcher-policy",
@@ -34,11 +33,10 @@ const layer = Layer.effect(
         add: (ignore) => draft.ignore.push(...ignore),
         list: () => draft.ignore,
       }),
-      finalize: (draft) =>
-        Effect.sync(() => {
-          current = [...draft.list()]
-        }).pipe(Effect.andThen(Effect.forEach(listeners, (listener) => listener(current), { discard: true }))),
+      notify: Effect.forEach(listeners, (listener) => listener(current()), { discard: true }),
     })
+    // Annotated to break the inference cycle through notify: notify reads current, current reads state.
+    const current = (): readonly string[] => state.get().ignore
     const observe = Effect.fn("LocationWatcherPolicy.observe")(function* (
       listener: (ignore: readonly string[]) => Effect.Effect<void>,
     ) {
@@ -56,7 +54,7 @@ const layer = Layer.effect(
     return Service.of({
       transform: state.transform,
       reload: state.reload,
-      current: () => current,
+      current,
       observe,
     })
   }),

packages/core/src/instruction-discovery.ts

@@ -74,7 +74,7 @@ export const layer = (options?: Options) =>
             draft.available = false
           },
         }),
-        finalize: () => bus.publish(Event.Updated, {}).pipe(Effect.asVoid),
+        notify: bus.publish(Event.Updated, {}).pipe(Effect.asVoid),
       })
 
       const source = (value: ReadonlyArray<File> | Instructions.Unavailable | Instructions.Removed) =>

packages/core/src/integration.ts

@@ -328,7 +328,7 @@ const layer = Layer.effect(
           },
         },
       }),
-      finalize: () => bus.publish(Integration.Event.Updated, {}).pipe(Effect.asVoid),
+      notify: bus.publish(Integration.Event.Updated, {}).pipe(Effect.asVoid),
     })
 
     const createCredential = Effect.fnUntraced(function* (input: Parameters<Credential.Interface["create"]>[0]) {
@@ -400,21 +400,17 @@ const layer = Layer.effect(
       }
 
       yield* Effect.gen(function* () {
-        const implementation = state
-          .get()
-          .integrations.get(attempt.integrationID)
-          ?.implementations.get(attempt.methodID)
-        const persistence = yield* Effect.sync(() => attempt.label ?? implementation?.label?.(exit.value)).pipe(
-          Effect.flatMap((label) =>
-            createCredential({
-              integrationID: attempt.integrationID,
-              label,
-              value: exit.value,
-            }),
-          ),
-          Effect.asVoid,
-          Effect.exit,
-        )
+        const persistence = yield* Effect.suspend(() => {
+          const implementation = state
+            .get()
+            .integrations.get(attempt.integrationID)
+            ?.implementations.get(attempt.methodID)
+          return createCredential({
+            integrationID: attempt.integrationID,
+            label: attempt.label ?? implementation?.label?.(exit.value),
+            value: exit.value,
+          })
+        }).pipe(Effect.asVoid, Effect.exit)
         const settledAt = yield* Clock.currentTimeMillis
         const terminal: TerminalAttempt = Exit.isSuccess(persistence)
           ? {
@@ -432,7 +428,7 @@ const layer = Layer.effect(
             }
         // Persisting attempts cannot be cancelled, expired, or claimed again.
         yield* SynchronizedRef.update(attempts, (current) => new Map(current).set(attemptID, terminal))
-        if (Exit.isFailure(persistence)) yield* Effect.failCause(persistence.cause)
+        yield* persistence
       }).pipe(Effect.ensuring(close(attempt.scope)))
     }, Effect.uninterruptible)
 

packages/core/src/mcp/index.ts

@@ -6,7 +6,7 @@ import { ephemeral } from "@opencode-ai/schema/event"
 import type { Session } from "@opencode-ai/schema/session"
 import { createHash } from "node:crypto"
 import { isDeepStrictEqual } from "node:util"
-import { Cause, Context, Effect, Exit, FiberSet, Latch, Layer, Schema, Scope, Stream, Types } from "effect"
+import { Cause, Context, Effect, Exit, FiberSet, Latch, Layer, Schema, Scope, Semaphore, Stream, Types } from "effect"
 import { makeLocationNode } from "@opencode-ai/util/effect/app-node"
 import { Credential } from "../credential.js"
 import { Bus } from "../bus.js"
@@ -615,8 +615,9 @@ export const layer = (options?: Options) =>
 
       let applied: Map<ServerName, Mcp.ServerConfig> | undefined
       const overrides = new Map<ServerName, Mcp.ServerConfig | false>()
-      const reconcile = Effect.fnUntraced(function* (next: Draft) {
-        const servers = new Map(next.list())
+      const reconcileLock = Semaphore.makeUnsafe(1)
+      const reconcile = Effect.fnUntraced(function* () {
+        const servers = state.get().servers
         if (!applied && entries.size === 0) {
           for (const [name, server] of servers) {
             entries.set(name, {
@@ -677,7 +678,7 @@ export const layer = (options?: Options) =>
           Stream.runForEach((event) => Effect.sync(() => fork(reconnect(event.data.integrationID)))),
         ),
       )
-      const state = State.create<Data, Draft>({
+      const state: State.Interface<Data, Draft> = State.create<Data, Draft>({
         name: "mcp",
         initial: () => ({
           servers: new Map(
@@ -702,7 +703,7 @@ export const layer = (options?: Options) =>
           },
           remove: (server) => draft.servers.delete(ServerName.make(server)),
         }),
-        finalize: reconcile,
+        notify: State.reconcile(root, fork, () => reconcileLock.withPermit(reconcile())),
       })
 
       // Suspend so each await sees current entries; a bare Map iterator is exhausted after one run.

packages/core/src/model-resolver.ts

@@ -3,8 +3,7 @@ export * as ModelResolver from "./model-resolver.js"
 import { makeLocationNode } from "@opencode-ai/util/effect/app-node"
 import { LanguageModel } from "@opencode-ai/ai"
 import { Auth } from "@opencode-ai/ai/route"
-import { Context, Effect, Layer, Schema } from "effect"
-import { produce } from "immer"
+import { Context, Effect, Layer, Schema, Struct } from "effect"
 import { AISDK } from "./aisdk.js"
 import { AISDKNative } from "./aisdk-native.js"
 import { Catalog } from "./catalog.js"
@@ -79,6 +78,8 @@ export interface Interface {
 
 export class Service extends Context.Service<Service, Interface>()("@opencode/ModelResolver") {}
 
+// Catalog models are shared with the retained registry value and stay editable by later transforms, so
+// resolution copies with spreads: immer's produce would deep-freeze the unchanged subtrees it shares with its input.
 export const withVariant = (
   model: Info,
   variantID: VariantID | undefined,
@@ -95,11 +96,12 @@ export const withVariant = (
     )
   return Effect.succeed(
     variant
-      ? produce(model, (draft) => {
-          draft.settings = Provider.mergeOverlay(draft.settings, variant.settings)
-          draft.headers = Provider.mergeHeaders(draft.headers, variant.headers)
-          draft.body = Provider.mergeOverlay(draft.body, variant.body)
-        })
+      ? {
+          ...model,
+          settings: Provider.mergeOverlay(model.settings, variant.settings),
+          headers: Provider.mergeHeaders(model.headers, variant.headers),
+          body: Provider.mergeOverlay(model.body, variant.body),
+        }
       : model,
   )
 }
@@ -147,10 +149,7 @@ const resolveCatalogModel = Effect.fn("ModelResolver.resolveCatalogModel")(funct
         ...configuration,
       }) ?? {},
     )
-    const runtime = produce(resolved, (draft) => {
-      draft.settings = settings
-    })
-    return yield* loadAISDK(runtime).pipe(Effect.mapError(() => unsupported(resolved)))
+    return yield* loadAISDK({ ...resolved, settings }).pipe(Effect.mapError(() => unsupported(resolved)))
   }
   if (!native) return yield* unsupported(resolved)
 
@@ -160,7 +159,7 @@ const resolveCatalogModel = Effect.fn("ModelResolver.resolveCatalogModel")(funct
     Effect.mapError(() => unsupported(resolved)),
   )
   const settings = {
-    ...(credential ? withoutNativeAuthSettings(mapped) : mapped),
+    ...(credential ? Struct.omit(mapped, ["accessToken", "apiKey", "authToken"]) : mapped),
     ...(resolved.canonical === undefined ? {} : { provider: resolved.canonical }),
     ...nativeCredentialSettings(specifier, credential),
     headers: Provider.mergeHeaders(mapping?.headers, resolved.headers),
@@ -182,11 +181,13 @@ const resolveCatalogModel = Effect.fn("ModelResolver.resolveCatalogModel")(funct
 
 function prepareRuntimeModel(model: Info, credential: Credential.Value | undefined) {
   if (model.settings?.apiKey !== "" && (credential?.type !== "key" || credential.metadata === undefined)) return model
-  return produce(model, (draft) => {
-    if (draft.settings?.apiKey === "") delete draft.settings.apiKey
-    if (credential?.type === "key" && credential.metadata !== undefined)
-      draft.body = Provider.mergeOverlay(draft.body, credential.metadata)
-  })
+  return {
+    ...model,
+    ...(model.settings?.apiKey === "" ? { settings: Struct.omit(model.settings, ["apiKey"]) } : {}),
+    ...(credential?.type === "key" && credential.metadata !== undefined
+      ? { body: Provider.mergeOverlay(model.body, credential.metadata) }
+      : {}),
+  }
 }
 
 function validateProviderVariables(
@@ -243,11 +244,6 @@ const nativeCredentialSettings = (specifier: string, credential: Credential.Valu
   return { apiKey: credential.access }
 }
 
-const withoutNativeAuthSettings = (settings: Record<string, unknown>) => {
-  const { accessToken: _accessToken, apiKey: _apiKey, authToken: _authToken, ...rest } = settings
-  return rest
-}
-
 const unsupported = (model: Info) =>
   new UnsupportedPackageError({
     providerID: model.providerID,

packages/core/src/plugin.ts

@@ -169,7 +169,7 @@ const layer = Layer.effect(
       lock.withPermit(
         Effect.gen(function* () {
           active.clear()
-          yield* State.batch(Scope.close(scope, exit), { flush: false })
+          yield* State.shutdown(Scope.close(scope, exit))
         }),
       )
     yield* Effect.addFinalizer(close)

packages/core/src/plugin/system-prompt.ts

@@ -54,7 +54,7 @@ function make(
           const prompt = getPrompt(`${model?.modelID ?? event.model.id} ${model?.family ?? ""}`.toLowerCase())
           if (!prompt) return
           if (options.operation === "append") {
-            event.system.push(SystemPart.make(prompt))
+            event.system.splice(1, 0, SystemPart.make(prompt))
             return
           }
           event.system[0] = { ...system, text: prompt }

packages/core/src/reference.ts

@@ -1,7 +1,7 @@
 export * as Reference from "./reference.js"
 
 import { makeLocationNode } from "@opencode-ai/util/effect/app-node"
-import { Context, Effect, Layer, Scope, Types } from "effect"
+import { Context, Effect, Layer, Scope } from "effect"
 import { Reference } from "@opencode-ai/schema/reference"
 import { Global } from "@opencode-ai/util/global"
 import { Bus } from "./bus.js"
@@ -25,7 +25,7 @@ export const Info = Reference.Info
 export type Info = Reference.Info
 
 type Data = {
-  sources: Map<string, Types.DeepMutable<Source>>
+  sources: Map<string, Source>
 }
 
 type Draft = {
@@ -47,10 +47,34 @@ const layer = Layer.effect(
     const bus = yield* Bus.Service
     const cache = yield* RepositoryCache.Service
     const scope = yield* Scope.Scope
-    const materialized = new Map<string, Info>()
+    const list = (): Info[] =>
+      Array.from(state.get().sources).flatMap(([name, source]) => {
+        const info = {
+          name,
+          source,
+          ...(source.description === undefined ? {} : { description: source.description }),
+          ...(source.hidden === undefined ? {} : { hidden: source.hidden }),
+        }
+        if (source.type === "local") return [Info.make({ ...info, path: source.path })]
+        const repository = Repository.parse(source.repository)
+        if (!repository || !Repository.isRemote(repository)) return []
+        if (source.branch) {
+          try {
+            Repository.validateBranch(source.branch)
+          } catch {
+            return []
+          }
+        }
+        return [
+          Info.make({
+            ...info,
+            path: AbsolutePath.make(Repository.cachePath(global.repos, repository, source.branch)),
+          }),
+        ]
+      })
     const refresh = Effect.fn("Reference.refresh")(function* () {
       yield* Effect.forEach(
-        Array.from(materialized.values()),
+        list(),
         (reference) =>
           Effect.gen(function* () {
             if (reference.source.type !== "git") return
@@ -71,44 +95,14 @@ const layer = Layer.effect(
       name: "reference",
       initial: () => ({ sources: new Map() }),
       draft: (draft) => ({
-        add: (name, source) => draft.sources.set(name, source as Types.DeepMutable<Source>),
+        add: (name, source) => draft.sources.set(name, source),
         remove: (name) => draft.sources.delete(name),
-        list: () => Array.from(draft.sources.entries()) as [string, Source][],
+        list: () => Array.from(draft.sources),
+      }),
+      notify: Effect.gen(function* () {
+        yield* refresh().pipe(Effect.forkIn(scope))
+        yield* bus.publish(Reference.Event.Updated, {})
       }),
-      finalize: (draft) =>
-        Effect.gen(function* () {
-          materialized.clear()
-          for (const [name, source] of draft.list()) {
-            const info = {
-              name,
-              source,
-              ...(source.description === undefined ? {} : { description: source.description }),
-              ...(source.hidden === undefined ? {} : { hidden: source.hidden }),
-            }
-            if (source.type === "local") {
-              materialized.set(name, Info.make({ ...info, path: source.path }))
-              continue
-            }
-            const repository = Repository.parse(source.repository)
-            if (!repository || !Repository.isRemote(repository)) continue
-            if (source.branch) {
-              try {
-                Repository.validateBranch(source.branch)
-              } catch {
-                continue
-              }
-            }
-            materialized.set(
-              name,
-              Info.make({
-                ...info,
-                path: AbsolutePath.make(Repository.cachePath(global.repos, repository, source.branch)),
-              }),
-            )
-          }
-          yield* refresh().pipe(Effect.forkIn(scope))
-          yield* bus.publish(Reference.Event.Updated, {})
-        }),
     })
 
     // Check independently of session activity; the shared cache throttles Git work daily.
@@ -118,7 +112,7 @@ const layer = Layer.effect(
       transform: state.transform,
       reload: state.reload,
       list: Effect.fn("Reference.list")(function* () {
-        return Array.from(materialized.values())
+        return list()
       }),
     })
   }),

packages/core/src/session/compaction.ts

@@ -173,6 +173,8 @@ const estimateMedia = (mime: string) => {
 }
 
 const estimatePart = (part: ContentPart): number => {
+  // Encrypted checkpoints have no locally measurable token size.
+  if (part.type === "compaction") return Token.estimate(part.text ?? "")
   if (part.type === "text" || part.type === "reasoning") return Token.estimate(part.text)
   if (part.type === "media") return estimateMedia(part.mediaType)
   if (part.type === "tool-call") return Token.estimate(part.name + (JSON.stringify(part.input) ?? ""))

packages/core/src/session/runner/to-llm-message.ts

@@ -2,6 +2,7 @@ import { Message, ToolCallPart, ToolResultPart, type ContentPart, type ProviderM
 import type { Model } from "@opencode-ai/schema/model"
 import { Option, Schema } from "effect"
 import { fileURLToPath } from "url"
+import path from "path"
 import { SessionMessage } from "../message.js"
 import type { FileAttachment } from "@opencode-ai/schema/prompt"
 
@@ -16,7 +17,10 @@ const media = (file: FileAttachment): ContentPart => ({
 })
 
 const attachmentLocation = (file: FileAttachment) => {
-  if (file.source.type !== "uri") return undefined
+  if (file.source.type === "inline") {
+    if (!file.name) return undefined
+    return path.posix.isAbsolute(file.name) || path.win32.isAbsolute(file.name) ? file.name : undefined
+  }
   const url = URL.parse(file.source.uri)
   if (url?.protocol !== "file:") return undefined
   try {

packages/core/src/skill.ts

@@ -109,7 +109,7 @@ const layer = Layer.effect(
           draft.skills.delete(ID.make(id))
         },
       }),
-      finalize: () => bus.publish(Skill.Event.Updated, {}).pipe(Effect.asVoid),
+      notify: bus.publish(Skill.Event.Updated, {}).pipe(Effect.asVoid),
     })
 
     return Service.of({

packages/core/src/state.ts

@@ -1,9 +1,9 @@
 export * as State from "./state.js"
 
-import { Clock, Context, Deferred, Effect, Scope, Semaphore } from "effect"
+import { Cause, Clock, Context, Deferred, Effect, Exit, Fiber, Scope } from "effect"
 
 /**
- * A replayable transform applied to a draft during reload.
+ * A synchronous, replayable edit to the current domain state.
  *
  * Domain drafts expose readable and writable state while preserving concise
  * plugin/config code. Transforms synchronously rebuild derived state.
@@ -16,13 +16,14 @@ export interface Registration {
 }
 
 /**
- * Registers and applies a scoped transform. Closing the owning Scope removes
- * the transform and reloads the materialized state.
+ * Registers a scoped transform. Reads rebuild by applying every registered transform in order.
+ * Closing the owning Scope removes the transform and invalidates the current value.
  */
 export type Transform<DraftApi> = (
   transform: TransformCallback<DraftApi>,
 ) => Effect.Effect<Registration, never, Scope.Scope>
 
+/** Invalidates the current value after captured inputs change and coalesces notifications. */
 export type Reload = () => Effect.Effect<void>
 
 export interface Transformable<DraftApi> {
@@ -32,8 +33,8 @@ export interface Transformable<DraftApi> {
 
 type Batch = {
   active: boolean
-  readonly flush: boolean
-  readonly reloads: Set<Reload>
+  readonly shutdown: boolean
+  readonly notifications: Set<Effect.Effect<void>>
 }
 
 const CurrentBatch = Context.Reference<Batch | undefined>("@opencode/State/CurrentBatch", {
@@ -41,16 +42,49 @@ const CurrentBatch = Context.Reference<Batch | undefined>("@opencode/State/Curre
 })
 const reloadDebounce = 500
 
-/** flush: false is terminal teardown: states whose transforms are removed stop rebuilding, including pending reloads. */
-export function batch<A, E, R>(effect: Effect.Effect<A, E, R>, options: { readonly flush?: boolean } = {}) {
+/** Coalesces notifications until the effect completes. Reads inside stay fresh; nothing is rolled back. */
+export function batch<A, E, R>(effect: Effect.Effect<A, E, R>) {
+  return run(effect, false)
+}
+
+/**
+ * Runs the effect as shutdown: States changed inside it close permanently and never notify again,
+ * including debounced reloads already waiting.
+ */
+export function shutdown<A, E, R>(effect: Effect.Effect<A, E, R>) {
+  return run(effect, true)
+}
+
+function run<A, E, R>(effect: Effect.Effect<A, E, R>, shutdown: boolean) {
+  return Effect.uninterruptibleMask((restore) =>
+    Effect.gen(function* () {
+      const current = yield* CurrentBatch
+      if (current?.active && !shutdown) return yield* restore(effect)
+      const batch: Batch = { active: true, shutdown, notifications: new Set() }
+      const exit = yield* restore(effect.pipe(Effect.provideService(CurrentBatch, batch))).pipe(Effect.exit)
+      batch.active = false
+      // A shutdown batch never collects notifications: changed() closes the State instead.
+      const notifications = yield* Effect.forEach(batch.notifications, (notify) => restore(notify).pipe(Effect.exit))
+      // Aggregate ordinary failures across domains, while allowing cancellation to stop observer work.
+      yield* Exit.asVoidAll([exit, ...notifications])
+      return yield* exit
+    }),
+  )
+}
+
+/**
+ * A `notify` that runs resource reconciliation in the owning layer's FiberSet and awaits it, so work
+ * queued behind the layer's locks is interrupted with the layer. That interruption is not a failure.
+ */
+export function reconcile(
+  root: Scope.Scope,
+  fork: (effect: Effect.Effect<void>) => Fiber.Fiber<void>,
+  work: () => Effect.Effect<void>,
+): Effect.Effect<void> {
   return Effect.gen(function* () {
-    const current = yield* CurrentBatch
-    if (current?.active && options.flush !== false) return yield* effect
-    const batch: Batch = { active: true, flush: options.flush !== false, reloads: new Set() }
-    const exit = yield* effect.pipe(Effect.provideService(CurrentBatch, batch), Effect.exit)
-    batch.active = false
-    if (batch.flush) yield* Effect.forEach(batch.reloads, (reload) => reload(), { discard: true })
-    return yield* exit
+    const exit = yield* Fiber.await(fork(work()))
+    if (Exit.isFailure(exit) && root.state._tag === "Closed" && Cause.hasInterruptsOnly(exit.cause)) return
+    yield* exit
   })
 }
 
@@ -61,128 +95,112 @@ export const inherit = Effect.fnUntraced(function* () {
 
 export interface Options<State, DraftApi> {
   readonly name?: string
-  /** Creates the base value for initial state and every scoped-transform reload. */
+  /** Creates the empty base value for every rebuild. */
   readonly initial: () => State
   /** Wraps mutable state in a domain-specific draft API. */
   readonly draft: MakeDraft<State, DraftApi>
   /**
-   * Runs after the rebuilt state becomes visible. Update events published here
-   * act as read barriers: subscribers refetching on the event observe the
-   * committed state.
+   * Observes current state outside the read path. Batched changes notify at
+   * batch completion; reloads debounce notifications. Resource reconciliation
+   * owns its execution scope and coordination.
    */
-  readonly finalize?: (draft: DraftApi) => Effect.Effect<void>
+  readonly notify?: Effect.Effect<void>
 }
 
 export interface Interface<State, DraftApi> extends Transformable<DraftApi> {
+  /**
+   * Rebuilds synchronously when transforms changed since the last read. Each rebuild produces a new
+   * value and never touches earlier ones, so callers may retain what they read.
+   */
   readonly get: () => State
 }
 
 export function create<State, DraftApi>(options: Options<State, DraftApi>): Interface<State, DraftApi> {
   let state = options.initial()
-  let transforms: { run: TransformCallback<DraftApi> }[] = []
-  let generation = 0
+  const transforms: { run: TransformCallback<DraftApi> }[] = []
+  let dirty = false
   let requestedAt = 0
-  let running = false
   let closed = false
-  let waiters: { generation: number; done: Deferred.Deferred<void> }[] = []
-  const semaphore = Semaphore.makeUnsafe(1)
+  let pending: Deferred.Deferred<void> | undefined
 
-  const commit = Effect.fn("State.commit")(function* (next: State) {
-    state = next
-    if (options.finalize) yield* options.finalize(options.draft(next))
-  })
-
-  const materialize = Effect.fnUntraced(function* () {
-    if (closed) return
+  const get = () => {
+    if (closed || !dirty) return state
     const next = options.initial()
-    const api = options.draft(next)
-    for (const transform of transforms) {
-      yield* Effect.sync(() => {
-        transform.run(api)
-      })
-    }
-    yield* commit(next)
-  })
+    const draft = options.draft(next)
+    for (const transform of transforms) transform.run(draft)
+    // Only a complete fold becomes visible; a throwing callback leaves the previous value and stays dirty.
+    state = next
+    dirty = false
+    return state
+  }
 
-  const materializeReload = () => semaphore.withPermit(materialize())
-
-  const rebuild = (): Effect.Effect<void> =>
-    Effect.gen(function* () {
-      const clock = yield* Clock.Clock
-      const remaining = requestedAt + reloadDebounce - clock.currentTimeMillisUnsafe()
-      if (remaining > 0) yield* Effect.sleep(remaining)
-      if (clock.currentTimeMillisUnsafe() < requestedAt + reloadDebounce) return yield* rebuild()
-
-      const target = generation
-      const exit = yield* materializeReload().pipe(Effect.exit)
-      const completed = waiters.filter((waiter) => waiter.generation <= target)
-      waiters = waiters.filter((waiter) => waiter.generation > target)
-      yield* Effect.forEach(completed, (waiter) => Deferred.done(waiter.done, exit), {
-        concurrency: "unbounded",
-        discard: true,
-      })
-      if (generation > target) return yield* rebuild()
-      running = false
-    })
-
-  const reload = Effect.fnUntraced(function* () {
+  // One stable value per State, so a batch's notification Set holds it at most once.
+  const notify: Effect.Effect<void> = Effect.gen(function* () {
     if (closed) return
-    const done = Deferred.makeUnsafe<void>()
-    const clock = yield* Clock.Clock
-    generation++
-    requestedAt = clock.currentTimeMillisUnsafe()
-    waiters.push({ generation, done })
-    if (!running) {
-      running = true
-      yield* rebuild().pipe(Effect.forkDetach)
-    }
-    yield* Deferred.await(done)
-  })
+    get()
+    if (options.notify) yield* options.notify
+  }).pipe(Effect.withSpan("State.notify"))
+
+  const changed = (debounce: boolean) =>
+    Effect.uninterruptibleMask((restore) =>
+      Effect.gen(function* () {
+        if (closed) return
+        dirty = true
+        const batch = yield* CurrentBatch
+        if (batch?.active) {
+          if (batch.shutdown) {
+            closed = true
+            return
+          }
+          batch.notifications.add(notify)
+          return
+        }
+        if (!debounce) {
+          yield* restore(notify)
+          return
+        }
+
+        const clock = yield* Clock.Clock
+        requestedAt = clock.currentTimeMillisUnsafe()
+        if (pending) return yield* restore(Deferred.await(pending))
+        const done = Deferred.makeUnsafe<void>()
+        pending = done
+        yield* Effect.gen(function* () {
+          do {
+            const remaining = requestedAt + reloadDebounce - clock.currentTimeMillisUnsafe()
+            if (remaining > 0) yield* Effect.sleep(remaining)
+          } while (clock.currentTimeMillisUnsafe() < requestedAt + reloadDebounce)
+          // Observers can request and await another reload without joining their own notification.
+          pending = undefined
+          yield* notify.pipe(Deferred.into(done))
+        }).pipe(Effect.forkDetach)
+        yield* restore(Deferred.await(done))
+      }),
+    )
 
   return {
-    get: () => state,
+    get,
     transform: Effect.fn("State.transform")(function* (update) {
       yield* Effect.annotateCurrentSpan("state", options.name ?? "anonymous")
       const scope = yield* Scope.Scope
       return yield* Effect.uninterruptible(
         Effect.gen(function* () {
           const transform = { run: update }
-          let active = true
           const dispose = Effect.uninterruptible(
-            semaphore.withPermit(
-              Effect.suspend(() => {
-                if (!active) return Effect.void
-                active = false
-                transforms = transforms.filter((item) => item !== transform)
-                return Effect.gen(function* () {
-                  const batch = yield* CurrentBatch
-                  if (batch?.active) {
-                    // Detached debounced reloads must also stay quiet after teardown.
-                    if (!batch.flush) {
-                      closed = true
-                      return
-                    }
-                    batch.reloads.add(materializeReload)
-                    return
-                  }
-                  yield* materialize()
-                })
-              }),
-            ),
-          )
-          yield* semaphore.withPermit(
-            Effect.sync(() => {
-              transforms = [...transforms, transform]
+            Effect.suspend(() => {
+              const index = transforms.indexOf(transform)
+              if (index < 0) return Effect.void
+              transforms.splice(index, 1)
+              return changed(false)
             }),
           )
+          transforms.push(transform)
           yield* Scope.addFinalizer(scope, dispose)
-          const batch = yield* CurrentBatch
-          if (batch?.active) batch.reloads.add(materializeReload)
-          else yield* materializeReload()
+          yield* changed(false)
           return { dispose }
         }),
       )
     }),
-    reload,
+    reload: () => changed(true),
   }
 }

packages/core/src/tool.ts

@@ -196,7 +196,8 @@ const layer = Layer.effect(
           draft.tools.delete(id)
         },
       }),
-      finalize: () =>
+      // Read errors when the notification runs, not when the State is created.
+      notify: Effect.suspend(() =>
         Effect.forEach(
           state.get().errors,
           ({ kind, name, namespace, error }) =>
@@ -207,6 +208,7 @@ const layer = Layer.effect(
             }),
           { discard: true },
         ),
+      ),
     })
 
     return Service.of({

packages/core/src/vcs.ts

@@ -1,7 +1,7 @@
 export * as Vcs from "./vcs.js"
 
 import path from "path"
-import { Cause, Context, Effect, Layer, Schema, Stream } from "effect"
+import { Cause, Context, Effect, FiberSet, Layer, Schema, Semaphore, Stream } from "effect"
 import type { VcsDefinition, VcsDraft } from "@opencode-ai/plugin/effect/vcs"
 import { FileDiff } from "@opencode-ai/schema/file-diff"
 import { FileSystem } from "@opencode-ai/schema/filesystem"
@@ -55,8 +55,11 @@ const layer = Layer.effect(
     const fs = yield* FSUtil.Service
     const location = yield* Location.Service
     const bus = yield* Bus.Service
+    const root = yield* Effect.scope
+    const fork = yield* FiberSet.makeRuntime<never, void, never>()
     const vcs = location.vcs
     const current: { info: Info } = { info: { branch: {} } }
+    const refreshLock = Semaphore.makeUnsafe(1)
     const scope = {
       directory: location.directory,
       worktree: location.project.directory,
@@ -78,7 +81,7 @@ const layer = Layer.effect(
           set: (selection) => (draft.selection = selection),
         },
       }),
-      finalize: () => refresh(),
+      notify: State.reconcile(root, fork, () => refresh()),
     })
     const selected = () => {
       const value = state.get()
@@ -117,13 +120,23 @@ const layer = Layer.effect(
         }),
       )
     const refresh = Effect.fn("Vcs.refresh")(function* () {
-      const provider = selected()
-      const next: Info = provider
-        ? yield* protect(provider, "info", provider.info(scope).pipe(Effect.flatMap(decodeInfo)), { branch: {} })
-        : { branch: {} }
-      const changed = current.info.branch.current !== next.branch.current
-      current.info = next
-      if (changed) yield* bus.publish(VcsEvent.BranchUpdated, { branch: next.branch.current })
+      const changed = yield* Effect.gen(function* () {
+        const provider = selected()
+        const next: Info = provider
+          ? yield* protect(provider, "info", provider.info(scope).pipe(Effect.flatMap(decodeInfo)), { branch: {} })
+          : { branch: {} }
+        const changed = current.info.branch.current !== next.branch.current
+        current.info = next
+        return changed
+      }).pipe(Semaphore.withPermit(refreshLock))
+      if (!changed) return
+      // Legacy listeners can publish nested updates before streams and SSE receive
+      // this event. Re-announce the latest branch if publication was overtaken.
+      while (true) {
+        const branch = current.info.branch.current
+        yield* bus.publish(VcsEvent.BranchUpdated, { branch })
+        if (branch === current.info.branch.current) return
+      }
     })
 
     if (vcs) {
@@ -135,7 +148,13 @@ const layer = Layer.effect(
       yield* bus.subscribe(FileSystem.Event.Changed).pipe(
         Stream.filter((event) => isBranchMetadata(event.data.file)),
         Stream.runForEach((event) =>
-          refresh().pipe(Effect.withSpan("Vcs.refreshBranch", { attributes: { file: event.data.file } })),
+          refresh().pipe(
+            Effect.catchCauseIf(
+              (cause) => !Cause.hasInterrupts(cause),
+              (cause) => Effect.logWarning("vcs refresh failed", { file: event.data.file, cause }),
+            ),
+            Effect.withSpan("Vcs.refreshBranch", { attributes: { file: event.data.file } }),
+          ),
         ),
         Effect.forkScoped({ startImmediately: true }),
       )

packages/core/src/websearch.ts

@@ -88,7 +88,7 @@ const layer = Layer.effect(
           set: (selection) => (draft.selection = selection),
         },
       }),
-      finalize: () => bus.publish(WebSearch.Event.Updated, {}).pipe(Effect.asVoid),
+      notify: bus.publish(WebSearch.Event.Updated, {}).pipe(Effect.asVoid),
     })
 
     const requireProvider = (providers: Map<ID, ProviderImplementation>, providerID: ID) => {

packages/core/test/aisdk.test.ts

@@ -10,6 +10,8 @@ import { Provider } from "@opencode-ai/core/provider"
 import {
   LLM,
   AIError,
+  CompactionPart,
+  ProviderID,
   HttpContext,
   LLMEvent,
   Message,
@@ -68,6 +70,31 @@ const client = LLMClient.layer.pipe(
   ),
 )
 
+it.effect("rejects native provider compaction rather than silently dropping replay state", () =>
+  Effect.gen(function* () {
+    const aisdk = yield* AISDK.Service
+    yield* aisdk.hook.sdk((event) => {
+      event.sdk = { languageModel: () => streamModel([]) }
+    })
+    const resolved = yield* aisdk.model(model("@ai-sdk/openai"))
+    const error = yield* compileRequest(
+      LLM.request({
+        model: resolved,
+        messages: [
+          Message.assistant(
+            CompactionPart.make({
+              provider: ProviderID.make("test-provider"),
+              encrypted: "opaque",
+            }),
+          ),
+        ],
+      }),
+    ).pipe(Effect.flip)
+    expect(error.reason._tag).toBe("InvalidRequest")
+    expect(error.message).toContain("cannot replay")
+  }),
+)
+
 it.effect("keys language models by package and flattened overlays", () =>
   Effect.gen(function* () {
     const aisdk = yield* AISDK.Service

packages/core/test/catalog.test.ts

@@ -1,4 +1,6 @@
 import { describe, expect } from "bun:test"
+import { LanguageModel } from "@opencode-ai/ai"
+import { OpenAIChat } from "@opencode-ai/ai/protocols"
 import { Effect, Fiber, Layer, Stream } from "effect"
 import { TestClock } from "effect/testing"
 import { Catalog } from "@opencode-ai/core/catalog"
@@ -9,6 +11,7 @@ import { LayerNode } from "@opencode-ai/util/effect/layer-node"
 import { Bus } from "@opencode-ai/core/bus"
 import { Location } from "@opencode-ai/core/location"
 import { Model } from "@opencode-ai/core/model"
+import { ModelResolver } from "@opencode-ai/core/model-resolver"
 import { Provider } from "@opencode-ai/core/provider"
 import { AbsolutePath } from "@opencode-ai/core/schema"
 import { location } from "./fixture/location"
@@ -30,6 +33,52 @@ const catalogLayer = AppNodeBuilder.build(
 const it = testEffect(catalogLayer)
 
 describe("Catalog", () => {
+  ;["variant", "empty-key", "metadata", "aisdk"].forEach((path) =>
+    it.effect(`keeps nested catalog values editable after ${path} model resolution`, () =>
+      Effect.gen(function* () {
+        const catalog = yield* Catalog.Service
+        const providerID = Provider.ID.make("resolve-fixture")
+        const modelID = Model.ID.make("fixture-model")
+        yield* catalog.transform((draft) =>
+          draft.model.update(providerID, modelID, (model) => {
+            model.package = path === "aisdk" ? Provider.aisdk("@ai-sdk/fixture") : "@opencode-ai/ai/providers/openai"
+            model.settings = {
+              apiKey: path === "empty-key" ? "" : "fixture-key",
+              baseURL: "https://fixture.example/v1",
+            }
+            model.variants = [{ id: Model.VariantID.make("high"), body: { reasoning: { effort: "high" } } }]
+          }),
+        )
+        const selected = required(yield* catalog.model.get(providerID, modelID))
+        if (path === "variant") yield* ModelResolver.withVariant(selected, Model.VariantID.make("high"))
+        if (path !== "variant")
+          yield* ModelResolver.fromCatalogModel(
+            selected,
+            path === "metadata"
+              ? Credential.Key.make({ type: "key", key: "fixture-key", metadata: { tenant: "fixture" } })
+              : undefined,
+            {
+              loadAISDK: () =>
+                Effect.succeed(LanguageModel.make({ id: modelID, provider: providerID, route: OpenAIChat.route })),
+            },
+          )
+
+        yield* catalog.transform((draft) =>
+          draft.model.update(providerID, modelID, (model) => {
+            model.limit.context = 100_000
+            model.capabilities.tools = false
+            model.variants.push({ id: Model.VariantID.make("other") })
+          }),
+        )
+        expect(required(yield* catalog.model.get(providerID, modelID))).toMatchObject({
+          limit: { context: 100_000 },
+          capabilities: { tools: false },
+          variants: [{ id: "high" }, { id: "other" }],
+        })
+      }),
+    ),
+  )
+
   it.effect("publishes an updated event after catalog changes", () =>
     Effect.gen(function* () {
       const catalog = yield* Catalog.Service

packages/core/test/filesystem/location-watcher-policy.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect } from "bun:test"
+import { Effect, Scope } from "effect"
+import { AppNodeBuilder } from "@opencode-ai/core/effect/app-node-builder"
+import { LocationWatcherPolicy } from "@opencode-ai/core/filesystem/location-watcher-policy"
+import { State } from "@opencode-ai/core/state"
+import { testEffect } from "../lib/effect"
+
+const it = testEffect(AppNodeBuilder.build(LocationWatcherPolicy.node))
+
+describe("LocationWatcherPolicy", () => {
+  it.effect("reads batched registrations and disposals before notifying observers", () =>
+    Effect.gen(function* () {
+      const policy = yield* LocationWatcherPolicy.Service
+      const observed: string[][] = []
+      yield* policy.observe((ignore) =>
+        Effect.sync(() => {
+          expect(policy.current()).toEqual(ignore)
+          observed.push([...ignore])
+        }),
+      )
+
+      yield* State.batch(
+        Effect.gen(function* () {
+          yield* policy.transform((draft) => draft.add(["node_modules"]))
+          expect(policy.current()).toEqual(["node_modules"])
+          const overlay = yield* policy.transform((draft) => draft.add([".git"]))
+          expect(policy.current()).toEqual(["node_modules", ".git"])
+          expect(observed).toEqual([])
+
+          yield* overlay.dispose
+          expect(policy.current()).toEqual(["node_modules"])
+          expect(observed).toEqual([])
+        }),
+      )
+
+      expect(observed).toEqual([["node_modules"]])
+    }),
+  )
+
+  it.effect("passes the latest policy to later observers after a reentrant registration", () =>
+    Effect.gen(function* () {
+      const policy = yield* LocationWatcherPolicy.Service
+      const scope = yield* Scope.Scope
+      const observed: string[][] = []
+      let reentered = false
+      yield* policy.observe(() =>
+        Effect.gen(function* () {
+          if (reentered) return
+          reentered = true
+          yield* policy.transform((draft) => draft.add([".git"])).pipe(Scope.provide(scope))
+          expect(policy.current()).toEqual(["node_modules", ".git"])
+        }),
+      )
+      yield* policy.observe((ignore) =>
+        Effect.sync(() => {
+          expect(policy.current()).toEqual(ignore)
+          observed.push([...ignore])
+        }),
+      )
+
+      yield* policy.transform((draft) => draft.add(["node_modules"]))
+
+      expect(policy.current()).toEqual(["node_modules", ".git"])
+      expect(observed).toEqual([
+        ["node_modules", ".git"],
+        ["node_modules", ".git"],
+      ])
+    }),
+  )
+})

packages/core/test/integration.test.ts

@@ -7,6 +7,7 @@ import { makeGlobalNode } from "@opencode-ai/util/effect/app-node"
 import { LayerNode } from "@opencode-ai/util/effect/layer-node"
 import { Bus } from "@opencode-ai/core/bus"
 import { Integration } from "@opencode-ai/core/integration"
+import { State } from "@opencode-ai/core/state"
 import { testEffect } from "./lib/effect"
 
 const it = testEffect(AppNodeBuilder.build(LayerNode.group([Integration.node, Credential.node, Bus.node])))
@@ -429,6 +430,62 @@ describe("Integration", () => {
     }),
   )
 
+  it.effect("fails and closes OAuth attempts when a pending transform throws during persistence", () =>
+    Effect.gen(function* () {
+      const integrations = yield* Integration.Service
+      const credentials = yield* Credential.Service
+      const integrationID = Integration.ID.make("replay-fixture")
+      const methodID = Integration.MethodID.make("code")
+      let closed = false
+      yield* integrations.transform((editor) =>
+        editor.method.update({
+          integrationID,
+          method: { id: methodID, type: "oauth", label: "Fixture" },
+          authorize: () =>
+            Effect.addFinalizer(() => Effect.sync(() => (closed = true))).pipe(
+              Effect.as({
+                mode: "code" as const,
+                url: "https://example.com/authorize",
+                instructions: "Enter the fixture code",
+                callback: () =>
+                  Effect.succeed(
+                    Credential.OAuth.make({
+                      type: "oauth",
+                      methodID,
+                      access: "fixture-access",
+                      refresh: "fixture-refresh",
+                      expires: 1,
+                    }),
+                  ),
+              }),
+            ),
+        }),
+      )
+      const attempt = yield* integrations.oauth.connect({ integrationID, methodID })
+
+      yield* State.batch(
+        Effect.gen(function* () {
+          const failure = new Error("integration transform failed")
+          yield* integrations.transform(() => {
+            throw failure
+          })
+          const exit = yield* integrations.oauth
+            .complete({ integrationID, attemptID: attempt.attemptID, code: "fixture-code" })
+            .pipe(Effect.exit)
+
+          expect(Exit.isFailure(exit) && Cause.squash(exit.cause)).toBe(failure)
+          expect(yield* integrations.oauth.status({ integrationID, attemptID: attempt.attemptID })).toEqual({
+            status: "failed",
+            message: failure.message,
+            time: attempt.time,
+          })
+          expect(closed).toBe(true)
+          expect(yield* credentials.list(integrationID)).toEqual([])
+        }).pipe(Effect.scoped),
+      )
+    }),
+  )
+
   it.effect("expires abandoned OAuth attempts", () =>
     Effect.gen(function* () {
       const integrations = yield* Integration.Service

packages/core/test/mcp.test.ts

@@ -34,9 +34,24 @@ import { McpStdio } from "@opencode-ai/core/mcp/stdio"
 import { Permission } from "@opencode-ai/core/permission"
 import { AbsolutePath } from "@opencode-ai/core/schema"
 import { Session } from "@opencode-ai/core/session"
+import { State } from "@opencode-ai/core/state"
 import { McpTool } from "@opencode-ai/core/tool/mcp"
 import { Tool } from "@opencode-ai/core/tool"
-import { Deferred, Effect, Exit, Fiber, Layer, PubSub, Ref, Schedule, Schema, Sink, Stream } from "effect"
+import {
+  Context,
+  Deferred,
+  Effect,
+  Exit,
+  Fiber,
+  Layer,
+  PubSub,
+  Ref,
+  Schedule,
+  Schema,
+  Scope,
+  Sink,
+  Stream,
+} from "effect"
 import { TestClock } from "effect/testing"
 import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process"
 import { ExitCode, makeHandle, ProcessId } from "effect/unstable/process/ChildProcessSpawner"
@@ -69,7 +84,7 @@ function resourceServer(
     listChanged?: boolean
     emptyElicitation?: boolean
     urlElicitation?: boolean
-    respond?: (request: Request) => Response | undefined
+    respond?: (request: Request) => Response | undefined | Promise<Response | undefined>
   } = {},
 ) {
   return Effect.acquireRelease(
@@ -178,7 +193,7 @@ function resourceServer(
           if (typeof body === "object" && body !== null && "method" in body && body.method === "initialize") {
             state.initializations += 1
           }
-          return input.respond?.(request) ?? transport.handleRequest(request)
+          return (await input.respond?.(request)) ?? transport.handleRequest(request)
         },
       })
       return {
@@ -1331,6 +1346,9 @@ testEffect(resourceMcpLayer(new ConfigMCP.Local({ type: "local", command: ["unus
           )
           expect(yield* service.tools()).toHaveLength(2)
 
+          yield* service.transform((draft) => draft.update("dynamic", (server) => (server.codemode = false)))
+          expect((yield* service.tools()).map((tool) => tool.codemode)).toEqual([false, false])
+
           const settings = { disabled: true }
           yield* service.transform((draft) => {
             draft.update("dynamic", (server) => {
@@ -1415,7 +1433,7 @@ test("isolates nested configured MCP mutations and reconciles them", async () =>
         expect(published.filter((type) => type === McpEvent.StatusChanged.type)).toHaveLength(1)
         yield* service.transform((draft) =>
           draft.update("resources", (server) => {
-            if (server.type === "remote") server.headers = { Authorization: "transformed" }
+            if (server.type === "remote" && server.headers) server.headers.Authorization = "transformed"
           }),
         )
 
@@ -1426,6 +1444,41 @@ test("isolates nested configured MCP mutations and reconciles them", async () =>
   )
 })
 
+testEffect(Layer.empty).live("batches MCP transforms without connecting intermediate configurations", () =>
+  Effect.gen(function* () {
+    const server = yield* resourceServer()
+    yield* Effect.gen(function* () {
+      const service = yield* Mcp.Service
+      const registrations = yield* State.batch(
+        Effect.gen(function* () {
+          const added = yield* service.transform((draft) =>
+            draft.set("dynamic", {
+              type: "remote",
+              url: server.url,
+              oauth: false,
+            }),
+          )
+          expect((yield* service.servers()).some((server) => server.name === "dynamic")).toBe(false)
+          const disabled = yield* service.transform((draft) =>
+            draft.update("dynamic", (config) => (config.disabled = true)),
+          )
+          return [added, disabled]
+        }),
+      )
+
+      expect((yield* service.servers()).find((server) => server.name === "dynamic")?.status).toEqual({
+        status: "disabled",
+      })
+      expect(yield* service.tools()).toEqual([])
+      yield* State.batch(Effect.forEach(registrations, (registration) => registration.dispose))
+      expect((yield* service.servers()).some((server) => server.name === "dynamic")).toBe(false)
+      expect(server.state.initializations).toBe(0)
+    }).pipe(
+      Effect.provide(resourceMcpLayer(new ConfigMCP.Local({ type: "local", command: ["unused"], disabled: true }))),
+    )
+  }),
+)
+
 test("reconciles only changed MCP server config", async () => {
   await Effect.runPromise(
     Effect.scoped(
@@ -1516,6 +1569,130 @@ test("reconciles only changed MCP server config", async () => {
   )
 })
 
+testEffect(Layer.empty).live("keeps MCP config snapshots stable during an in-flight replacement", () =>
+  Effect.gen(function* () {
+    const started = yield* Deferred.make<void>()
+    const release = yield* Deferred.make<void>()
+    const accepted = yield* Deferred.make<void>()
+    const server = yield* resourceServer({
+      respond: (request) =>
+        request.method !== "POST"
+          ? undefined
+          : Effect.runPromise(
+              Deferred.succeed(started, undefined).pipe(Effect.andThen(Deferred.await(release)), Effect.as(undefined)),
+            ),
+    })
+
+    yield* Effect.gen(function* () {
+      const service = yield* Mcp.Service
+      const replacing = yield* service
+        .transform((draft) => draft.update("resources", (config) => (config.disabled = false)))
+        .pipe(Effect.forkScoped({ startImmediately: true }))
+      yield* Deferred.await(started)
+
+      const restoring = yield* State.batch(
+        Effect.gen(function* () {
+          yield* service.transform((draft) => draft.update("resources", (config) => (config.disabled = true)))
+          yield* Deferred.succeed(accepted, undefined)
+        }),
+      ).pipe(Effect.forkScoped({ startImmediately: true }))
+      yield* Deferred.await(accepted)
+      expect((yield* service.servers())[0]?.status).toEqual({ status: "pending" })
+
+      yield* Deferred.succeed(release, undefined)
+      yield* Fiber.join(replacing)
+      yield* Fiber.join(restoring)
+      expect((yield* service.servers())[0]?.status).toEqual({ status: "disabled" })
+      expect(yield* service.tools()).toEqual([])
+      expect(server.state.initializations).toBe(1)
+    }).pipe(
+      Effect.ensuring(Deferred.succeed(release, undefined)),
+      Effect.provide(
+        resourceMcpLayer(new ConfigMCP.Remote({ type: "remote", url: server.url, oauth: false, disabled: true })),
+      ),
+    )
+  }),
+)
+
+const shutdownIt = testEffect(
+  AppNodeBuilder.build(
+    LayerNode.group([Bus.node, Integration.node, Credential.node, Form.node, Environment.node, Location.node]),
+    [
+      Location.node.replace(
+        Layer.succeed(
+          Location.Service,
+          Location.Service.of(location({ directory: AbsolutePath.make(import.meta.dir) })),
+        ),
+      ),
+      Environment.node.replace(hostEnvironmentLayer),
+    ],
+  ),
+)
+shutdownIt.effect("discards in-flight and queued MCP notifications after its layer closes", () =>
+  Effect.gen(function* () {
+    const bus = yield* Bus.Service
+    const entered = yield* Deferred.make<void>()
+    const release = yield* Deferred.make<void>()
+    const root = yield* Scope.make()
+    yield* Effect.addFinalizer(() =>
+      Deferred.succeed(release, undefined).pipe(
+        Effect.andThen(State.shutdown(Scope.close(root, Exit.void))),
+        Effect.andThen(TestClock.adjust("500 millis")),
+      ),
+    )
+    const context = yield* Layer.buildWithScope(Mcp.layer(), root)
+    const service = Context.get(context, Mcp.Service)
+    const observed: string[] = []
+    let block = false
+    yield* Effect.acquireRelease(
+      bus.listen((event) =>
+        Effect.gen(function* () {
+          if (event.type !== McpEvent.StatusChanged.type) return
+          observed.push(Schema.decodeUnknownSync(McpEvent.StatusChanged.data)(event.data).server)
+          if (!block) return
+          block = false
+          yield* Deferred.succeed(entered, undefined)
+          yield* Deferred.await(release)
+        }),
+      ),
+      (unsubscribe) => unsubscribe,
+    )
+    const source = { url: "https://example.com/initial", added: false }
+    yield* service
+      .transform((draft) => {
+        draft.set("fixture", { type: "remote", url: source.url, oauth: false, disabled: true })
+        if (source.added) draft.set("queued", { type: "local", command: ["unused"], disabled: true })
+      })
+      .pipe(Scope.provide(root))
+
+    block = true
+    source.url = "https://example.com/first"
+    source.added = true
+    const first = yield* service.reload().pipe(Effect.forkChild({ startImmediately: true }))
+    yield* TestClock.adjust("500 millis")
+    yield* Deferred.await(entered)
+    source.url = "https://example.com/second"
+    const second = yield* service.reload().pipe(Effect.forkChild({ startImmediately: true }))
+    yield* TestClock.adjust("500 millis")
+
+    const shutdown = yield* State.shutdown(Scope.close(root, Exit.void)).pipe(
+      Effect.forkChild({ startImmediately: true }),
+    )
+    yield* TestClock.adjust("1 millis")
+    expect(shutdown.pollUnsafe()).toBeDefined()
+    expect(first.pollUnsafe()).toBeDefined()
+    expect(second.pollUnsafe()).toBeDefined()
+    expect(yield* Deferred.isDone(release)).toBe(false)
+    yield* Fiber.join(shutdown)
+    observed.length = 0
+    yield* Deferred.succeed(release, undefined)
+    yield* Fiber.join(first)
+    yield* Fiber.join(second)
+    expect(observed).toEqual([])
+    expect((yield* service.servers()).map((server) => server.name)).toEqual([Mcp.ServerName.make("fixture")])
+  }),
+)
+
 test("serializes concurrent MCP lifecycle operations", async () => {
   await Effect.runPromise(
     Effect.scoped(

packages/core/test/plugin.test.ts

@@ -1,7 +1,10 @@
 import { expect } from "bun:test"
 import path from "path"
-import { Effect } from "effect"
+import { Clock, Effect } from "effect"
+import { TestClock } from "effect/testing"
 import { Command } from "@opencode-ai/core/command"
+import { Credential } from "@opencode-ai/core/credential"
+import { Integration } from "@opencode-ai/core/integration"
 import { Plugin } from "@opencode-ai/core/plugin"
 import { PluginModule } from "@opencode-ai/core/plugin/module"
 import { Session } from "@opencode-ai/schema/session"
@@ -119,3 +122,68 @@ it.effect("reloading a plugin replaces its command implementation", () =>
     expect(output).toEqual(["before", "after"])
   }),
 )
+
+it.effect("refreshes expired OAuth credentials through the context during activation", () =>
+  Effect.gen(function* () {
+    const plugins = yield* Plugin.Service
+    const credentials = yield* Credential.Service
+    const integrations = yield* Integration.Service
+    const clock = yield* Clock.Clock
+    const integrationID = Integration.ID.make("refresh-fixture")
+    const methodID = Integration.MethodID.make("oauth")
+    const expired = Credential.OAuth.make({
+      type: "oauth",
+      methodID,
+      access: "expired-access",
+      refresh: "fixture-refresh",
+      expires: (yield* Clock.currentTimeMillis) + 60_000,
+    })
+    const stored = yield* credentials.create({ integrationID, label: "Fixture", value: expired })
+    yield* TestClock.adjust("2 minutes")
+    const refreshed = Credential.OAuth.make({
+      ...expired,
+      access: "fresh-access",
+      refresh: "rotated-refresh",
+      expires: (yield* Clock.currentTimeMillis) + 3_600_000,
+    })
+    const refreshes: Credential.OAuth[] = []
+    const resolved: Array<Credential.Value | undefined> = []
+
+    yield* plugins.activate([
+      {
+        id: "oauth-refresh",
+        revision: "1",
+        effect: (ctx) =>
+          Effect.gen(function* () {
+            yield* ctx.integration.transform((draft) =>
+              draft.method.update({
+                integrationID,
+                method: { id: methodID, type: "oauth", label: "Fixture" },
+                authorize: () => Effect.die("unexpected authorization"),
+                refresh: (value) =>
+                  Effect.sync(() => {
+                    refreshes.push(value)
+                    return refreshed
+                  }),
+              }),
+            )
+            // The method registered above must be readable before the activation batch ends.
+            const connection = yield* ctx.integration.connection.active(integrationID)
+            if (!connection) return yield* Effect.die("fixture connection not found")
+            resolved.push(yield* ctx.integration.connection.resolve(connection).pipe(Effect.orDie))
+          }).pipe(
+            // Plugin activation isolates ambient services, including the test clock.
+            Effect.provideService(Clock.Clock, clock),
+          ),
+      },
+    ])
+
+    expect(yield* plugins.list()).toMatchObject([{ id: "oauth-refresh", state: { status: "active" } }])
+    expect(resolved).toEqual([refreshed])
+    expect((yield* credentials.get(stored.id))?.value).toEqual(refreshed)
+    expect(yield* integrations.connection.resolve({ type: "credential", id: stored.id, label: stored.label })).toEqual(
+      refreshed,
+    )
+    expect(refreshes).toEqual([expired])
+  }),
+)

packages/core/test/project.test.ts

@@ -431,38 +431,6 @@ describe("Project.resolve", () => {
     }),
   )
 
-  const itHg = Bun.which("hg") ? it : { live: it.live.skip }
-
-  itHg.live("detects mercurial repositories from nested directories", () =>
-    Effect.gen(function* () {
-      const tmp = yield* Effect.acquireRelease(
-        Effect.promise(() => tmpdir()),
-        (tmp) => Effect.promise(() => tmp[Symbol.asyncDispose]()),
-      )
-      yield* Effect.promise(async () => {
-        await $`hg init`.cwd(tmp.path).quiet()
-        await Bun.write(path.join(tmp.path, "file.txt"), "one\n")
-        await $`hg addremove -q`
-          .cwd(tmp.path)
-          .env({ ...process.env, HGPLAIN: "1" })
-          .quiet()
-        await $`hg commit -q -m initial -u test`
-          .cwd(tmp.path)
-          .env({ ...process.env, HGPLAIN: "1" })
-          .quiet()
-        await fs.mkdir(path.join(tmp.path, "a", "b"), { recursive: true })
-      })
-      const project = yield* Project.Service
-
-      const result = yield* project.resolve(abs(path.join(tmp.path, "a", "b")))
-
-      expect(result.vcs?.type).toBe("hg")
-      expect(result.directory).toBe(abs(tmp.path))
-      expect(result.id).not.toBe(Project.ID.make("global"))
-      expect(result.previous).toBeUndefined()
-    }),
-  )
-
   it.live("prefers git when both git and mercurial metadata exist", () =>
     Effect.gen(function* () {
       const tmp = yield* Effect.acquireRelease(

packages/core/test/reference.test.ts

@@ -1,7 +1,10 @@
 import { describe, expect } from "bun:test"
-import { Effect, Exit, Layer, Scope } from "effect"
+import { Deferred, Effect, Exit, Layer, Scope } from "effect"
 import { AppNodeBuilder } from "@opencode-ai/core/effect/app-node-builder"
+import { Bus } from "@opencode-ai/core/bus"
 import { AbsolutePath } from "@opencode-ai/core/schema"
+import { State } from "@opencode-ai/core/state"
+import { LayerNode } from "@opencode-ai/util/effect/layer-node"
 import { Global } from "@opencode-ai/util/global"
 import { Reference } from "@opencode-ai/core/reference"
 import { Repository } from "@opencode-ai/core/repository"
@@ -11,9 +14,140 @@ import { it } from "./lib/effect"
 const cache = Layer.mock(RepositoryCache.Service, {
   ensure: () => Effect.die("unexpected Git materialization"),
 })
-const referenceLayer = AppNodeBuilder.build(Reference.node, [RepositoryCache.node.replace(cache)])
+const referenceLayer = AppNodeBuilder.build(LayerNode.group([Reference.node, Bus.node]), [
+  RepositoryCache.node.replace(cache),
+])
 
 describe("Reference", () => {
+  it.effect("reads batched references before cache work and update events", () => {
+    const operations: RepositoryCache.EnsureInput[] = []
+    const started = Deferred.makeUnsafe<void>()
+    const release = Deferred.makeUnsafe<void>()
+    const cache = Layer.succeed(RepositoryCache.Service, {
+      ensure: (input) =>
+        Effect.gen(function* () {
+          operations.push(input)
+          yield* Deferred.succeed(started, undefined)
+          yield* Deferred.await(release)
+          return {
+            repository: input.reference.label,
+            host: input.reference.host,
+            remote: input.reference.remote,
+            localPath: Repository.cachePath(Global.Path.repos, input.reference, input.branch),
+            status: "cached",
+          } satisfies RepositoryCache.Result
+        }),
+    })
+    const referenceLayer = AppNodeBuilder.build(LayerNode.group([Reference.node, Bus.node]), [
+      RepositoryCache.node.replace(cache),
+    ])
+
+    return Effect.gen(function* () {
+      const references = yield* Reference.Service
+      const bus = yield* Bus.Service
+      const observed: string[][] = []
+      yield* Effect.acquireRelease(
+        bus.listen((event) =>
+          event.type === Reference.Event.Updated.type
+            ? references.list().pipe(
+                Effect.map((infos) => {
+                  observed.push(infos.map((info) => info.name))
+                }),
+              )
+            : Effect.void,
+        ),
+        (unsubscribe) => unsubscribe,
+      )
+
+      yield* State.batch(
+        Effect.gen(function* () {
+          yield* references.transform((draft) =>
+            draft.add("docs", Reference.LocalSource.make({ type: "local", path: AbsolutePath.make("/docs") })),
+          )
+          expect((yield* references.list()).map((info) => info.name)).toEqual(["docs"])
+
+          yield* references.transform((draft) => {
+            draft.add(
+              "sdk",
+              Reference.GitSource.make({
+                type: "git",
+                repository: "owner/repo",
+                branch: "feature/docs",
+                description: "SDK documentation",
+                hidden: true,
+              }),
+            )
+            draft.add("invalid", Reference.GitSource.make({ type: "git", repository: "invalid" }))
+            draft.add(
+              "invalid-branch",
+              Reference.GitSource.make({ type: "git", repository: "owner/repo", branch: "../escape" }),
+            )
+            draft.add("file", Reference.GitSource.make({ type: "git", repository: "file:///docs" }))
+          })
+          const infos = yield* references.list()
+          expect(infos.map((info) => info.name)).toEqual(["docs", "sdk"])
+          expect(infos[1]).toMatchObject({
+            path: Repository.cachePath(Global.Path.repos, Repository.parseRemote("owner/repo"), "feature/docs"),
+            description: "SDK documentation",
+            hidden: true,
+          })
+          yield* Effect.yieldNow
+          expect(operations).toEqual([])
+          expect(observed).toEqual([])
+        }),
+      )
+
+      expect(observed).toEqual([["docs", "sdk"]])
+      yield* Deferred.await(started)
+      expect(operations).toEqual([
+        { reference: Repository.parseRemote("owner/repo"), branch: "feature/docs", refresh: "daily" },
+      ])
+      expect((yield* references.list()).map((info) => info.name)).toEqual(["docs", "sdk"])
+      yield* Effect.yieldNow
+      expect(operations).toHaveLength(1)
+      expect(observed).toHaveLength(1)
+      yield* Deferred.succeed(release, undefined)
+    }).pipe(Effect.scoped, Effect.provide(referenceLayer))
+  })
+
+  it.effect("lets update listeners replace references and refetch current info", () =>
+    Effect.gen(function* () {
+      const references = yield* Reference.Service
+      const bus = yield* Bus.Service
+      const scope = yield* Scope.Scope
+      const observed: string[][] = []
+      let reentered = false
+      const first = yield* bus.listen((event) =>
+        Effect.gen(function* () {
+          if (event.type !== Reference.Event.Updated.type || reentered) return
+          reentered = true
+          yield* references
+            .transform((draft) =>
+              draft.add("docs", Reference.LocalSource.make({ type: "local", path: AbsolutePath.make("/new") })),
+            )
+            .pipe(Scope.provide(scope))
+        }),
+      )
+      const second = yield* bus.listen((event) =>
+        event.type === Reference.Event.Updated.type
+          ? references.list().pipe(
+              Effect.map((infos) => {
+                observed.push(infos.map((info) => info.path))
+              }),
+            )
+          : Effect.void,
+      )
+      yield* Effect.addFinalizer(() => first.pipe(Effect.andThen(second)))
+
+      yield* references.transform((draft) =>
+        draft.add("docs", Reference.LocalSource.make({ type: "local", path: AbsolutePath.make("/old") })),
+      )
+
+      expect((yield* references.list()).map((info) => info.path)).toEqual([AbsolutePath.make("/new")])
+      expect(observed).toEqual([["/new"], ["/new"]])
+    }).pipe(Effect.scoped, Effect.provide(referenceLayer)),
+  )
+
   it.effect("registers normalized sources for the owning scope", () =>
     Effect.gen(function* () {
       const references = yield* Reference.Service

packages/core/test/session-compaction-transport.test.ts

@@ -0,0 +1,133 @@
+import { expect } from "bun:test"
+import { LLM, LLMClient, LLMRequest, Message } from "@opencode-ai/ai"
+import { OpenAI } from "@opencode-ai/ai/providers"
+import { RequestExecutor, WebSocketTransport } from "@opencode-ai/ai/route"
+import { SessionModelTransport } from "@opencode-ai/core/session/model-transport"
+import { WebSocketConstructor } from "@opencode-ai/core/effect/websocket-constructor"
+import { Session } from "@opencode-ai/schema/session"
+import { Effect, Latch, Layer, Schema } from "effect"
+import { FetchHttpClient } from "effect/unstable/http"
+import { Socket } from "effect/unstable/socket"
+import { testEffect } from "./lib/effect"
+
+const decodeBody = Schema.decodeSync(Schema.fromJsonString(Schema.Record(Schema.String, Schema.Unknown)))
+
+for (const recovery of ["reconnect", "http-fallback", "ambiguous-send"] as const) {
+  testEffect(WebSocketConstructor.layer).live(
+    `compaction survives ${recovery} without stale response IDs`,
+    () =>
+      Effect.gen(function* () {
+        const constructor = yield* Socket.WebSocketConstructor
+        const closed = yield* Latch.make()
+        const sockets: Bun.ServerWebSocket<{ id: number }>[] = []
+        const websocket: Array<{ connection: number; body: Record<string, unknown> }> = []
+        const http: Record<string, unknown>[] = []
+        const state = { rejectUpgrade: false }
+        const checkpoint = { type: "compaction", id: "cmp_1", encrypted_content: "opaque-context" }
+        const server = yield* Effect.acquireRelease(
+          Effect.sync(() =>
+            Bun.serve<{ id: number }>({
+              hostname: "127.0.0.1",
+              port: 0,
+              async fetch(request, server) {
+                if (request.headers.get("upgrade")?.toLowerCase() === "websocket") {
+                  if (!state.rejectUpgrade && server.upgrade(request, { data: { id: sockets.length } }))
+                    return undefined
+                  return new Response("Upgrade rejected", { status: 503 })
+                }
+                http.push(decodeBody(await request.text()))
+                return new Response(
+                  `data: ${JSON.stringify({ type: "response.completed", response: { id: "resp_http", output: [] } })}\n\n`,
+                  {
+                    headers: { "content-type": "text/event-stream" },
+                  },
+                )
+              },
+              websocket: {
+                open(socket) {
+                  sockets.push(socket)
+                },
+                message(socket, data) {
+                  websocket.push({ connection: socket.data.id, body: decodeBody(String(data)) })
+                  if (recovery === "ambiguous-send" && websocket.length === 3) {
+                    socket.close(1011, "fixture failure after receipt")
+                    return
+                  }
+                  const id = `resp_${websocket.length}`
+                  const output = websocket.length === 1 ? [checkpoint] : []
+                  socket.send(JSON.stringify({ type: "response.created", response: { id } }))
+                  if (output.length)
+                    socket.send(JSON.stringify({ type: "response.output_item.done", item: checkpoint }))
+                  socket.send(JSON.stringify({ type: "response.completed", response: { id, output } }))
+                },
+              },
+            }),
+          ),
+          (server) =>
+            Effect.sync(() => {
+              // Bun 1.3 closes the sockets but can leave the stop promise unresolved after upgrades.
+              void server.stop(true)
+            }),
+        )
+        const transport = SessionModelTransport.makeLayer({
+          open: (input) =>
+            WebSocketTransport.open(input).pipe(
+              Effect.provideService(Socket.WebSocketConstructor, constructor),
+              Effect.map((connection) => ({
+                ...connection,
+                close: connection.close.pipe(Effect.andThen(closed.open)),
+              })),
+            ),
+        })
+        const client = LLMClient.layer.pipe(Layer.provide(RequestExecutor.layer), Layer.provide(FetchHttpClient.layer))
+        yield* Effect.gen(function* () {
+          const channels = yield* SessionModelTransport.Service
+          const options = { webSocket: channels.bind(Session.ID.make(`ses_compaction_${recovery}`)) }
+          const first = LLM.request({
+            model: OpenAI.configure({ apiKey: "fixture", baseURL: server.url.toString() }).responses("fixture"),
+            prompt: "first",
+            providerOptions: { contextManagement: [{ type: "compaction", compactThreshold: 100000 }] },
+          })
+          const compacted = yield* LLMClient.generate(first, options)
+          const second = LLMRequest.update(first, {
+            messages: [...first.messages, compacted.message, Message.user("second")],
+          })
+          yield* LLMClient.generate(second, options)
+          expect(sockets).toHaveLength(1)
+          expect(websocket[1]?.body).toMatchObject({
+            store: false,
+            previous_response_id: "resp_1",
+            input: [{ role: "user", content: [{ type: "input_text", text: "second" }] }],
+          })
+          const third = LLMRequest.update(second, { messages: [...second.messages, Message.user("third")] })
+          if (recovery === "ambiguous-send") {
+            const error = yield* LLMClient.generate(third, options).pipe(Effect.flip)
+            expect(error.reason).toMatchObject({ _tag: "Transport", delivery: "ambiguous" })
+            expect(http).toHaveLength(0)
+            expect(websocket).toHaveLength(3)
+            state.rejectUpgrade = true
+          } else {
+            state.rejectUpgrade = recovery === "http-fallback"
+            sockets[0]?.close(1011, "fixture idle disconnect")
+          }
+          // The transport signals this only after discarding the failed physical connection.
+          yield* closed.await
+          yield* LLMClient.generate(third, options)
+          const body = recovery === "reconnect" ? websocket.at(-1)?.body : http[0]
+          expect(body).not.toHaveProperty("previous_response_id")
+          expect(body).toMatchObject({
+            store: false,
+            input: [
+              { role: "user", content: [{ type: "input_text", text: "first" }] },
+              checkpoint,
+              { role: "user", content: [{ type: "input_text", text: "second" }] },
+              { role: "user", content: [{ type: "input_text", text: "third" }] },
+            ],
+          })
+          expect(http).toHaveLength(recovery === "reconnect" ? 0 : 1)
+          expect(sockets).toHaveLength(recovery === "reconnect" ? 2 : 1)
+        }).pipe(Effect.provide(Layer.merge(transport, client)))
+      }),
+    10000,
+  )
+}

packages/core/test/session-runner-message.test.ts

@@ -491,6 +491,29 @@ Recent work
     ])
   })
 
+  test("exposes desktop media source paths retained on inline attachments", () => {
+    const data = Base64.make("AAECAw==")
+    const location = "/Users/vogel/Downloads/preview.gif"
+    const messages = toLLMMessages(
+      [
+        SessionMessage.User.make({
+          id: id("user-inline-image-path"),
+          type: "user",
+          text: "Add this GIF to the page",
+          files: [FileAttachment.make({ data, mime: "image/gif", source: { type: "inline" }, name: location })],
+          time: { created },
+        }),
+      ],
+      model,
+    )
+
+    expect(messages[0]?.content).toEqual([
+      { type: "text", text: "Add this GIF to the page" },
+      { type: "text", text: `Attached file: ${location}` },
+      { type: "media", mediaType: "image/gif", data, filename: location },
+    ])
+  })
+
   test("falls back to attachment names for invalid local source paths", () => {
     const data = Base64.make("AAECAw==")
     const messages = toLLMMessages(

packages/core/test/session-runner.test.ts

@@ -1590,8 +1590,8 @@ describe("SessionRunnerLLM", () => {
 
     expect(s.requests.at(-1)?.system.map((part) => part.text)).toEqual([
       defaultSystem,
-      "Initial context",
       expect.stringContaining("# Delegation"),
+      "Initial context",
     ])
   })
 
@@ -1611,8 +1611,8 @@ describe("SessionRunnerLLM", () => {
 
     expect(s.requests.at(-1)?.system.map((part) => part.text)).toEqual([
       defaultSystem,
-      "Initial context",
       expect.stringContaining("# Delegation"),
+      "Initial context",
     ])
   })
 

packages/core/test/state-replay.test.ts

@@ -0,0 +1,207 @@
+import { describe, expect, test } from "bun:test"
+import { State } from "@opencode-ai/core/state"
+import { Effect } from "effect"
+import { FastCheck } from "effect/testing"
+
+type Operation = { multiply: number; add: number }
+type Value = { value: number; order: number[] }
+
+const operation = FastCheck.record({
+  multiply: FastCheck.constantFrom(-3, -2, 2, 3),
+  add: FastCheck.integer({ min: -9, max: 9 }),
+})
+const source = FastCheck.integer({ min: -100, max: 100 })
+const target = FastCheck.integer({ min: 0, max: 1 })
+const command = FastCheck.oneof(
+  {
+    weight: 4,
+    arbitrary: FastCheck.record({ type: FastCheck.constant("append"), target, callback: FastCheck.nat(5) }),
+  },
+  { weight: 3, arbitrary: FastCheck.record({ type: FastCheck.constant("read"), target }) },
+  {
+    weight: 2,
+    arbitrary: FastCheck.record({ type: FastCheck.constant("dispose"), target, registration: FastCheck.nat(100) }),
+  },
+  { weight: 2, arbitrary: FastCheck.record({ type: FastCheck.constant("reload"), target, source }) },
+)
+
+// Affine transforms do not generally commute; the modulus keeps long traces exact.
+function apply(value: number, operation: Operation) {
+  return (value * operation.multiply + operation.add) % 10_007
+}
+
+const parameters = { numRuns: 300 }
+
+describe("State replay properties", () => {
+  test("matches a full fold across reads, registrations, removals and batched reloads", () =>
+    FastCheck.assert(
+      FastCheck.property(
+        FastCheck.tuple(source, source),
+        FastCheck.array(operation, { minLength: 1, maxLength: 6 }),
+        FastCheck.array(FastCheck.array(command, { maxLength: 48 }), { minLength: 1, maxLength: 8 }),
+        (initial, operations, batches) =>
+          Effect.gen(function* () {
+            const sources = [...initial]
+            const notifications = [0, 0]
+            let calls = 0
+            const states = sources.map((_, index) =>
+              State.create({
+                initial: (): Value => ({ value: sources[index], order: [] }),
+                draft: (draft) => draft,
+                notify: Effect.sync(() => void notifications[index]++),
+              }),
+            )
+            const callbacks = operations.map((operation, index) => (draft: Value) => {
+              calls++
+              draft.value = apply(draft.value, operation)
+              draft.order.push(index)
+            })
+            const registrations: { handle: State.Registration; callback: number; active: boolean }[][] = [[], []]
+            const expected = (index: number): Value => {
+              const order = registrations[index].filter((entry) => entry.active).map((entry) => entry.callback)
+              return {
+                value: order.reduce((value, callback) => apply(value, operations[callback]), sources[index]),
+                order,
+              }
+            }
+
+            yield* Effect.forEach(
+              batches,
+              (commands) =>
+                Effect.gen(function* () {
+                  const before = [...notifications]
+                  const dirty = new Set<number>()
+                  yield* State.batch(
+                    Effect.gen(function* () {
+                      yield* Effect.forEach(
+                        commands,
+                        (command) =>
+                          Effect.gen(function* () {
+                            const state = states[command.target]
+                            switch (command.type) {
+                              case "append": {
+                                const callback = command.callback % callbacks.length
+                                const handle = yield* state.transform(callbacks[callback])
+                                registrations[command.target].push({ handle, callback, active: true })
+                                dirty.add(command.target)
+                                return
+                              }
+                              case "read":
+                                expect(state.get()).toEqual(expected(command.target))
+                                return
+                              case "dispose": {
+                                const entries = registrations[command.target]
+                                if (!entries.length) return
+                                const entry = entries[command.registration % entries.length]
+                                yield* entry.handle.dispose
+                                if (!entry.active) return
+                                entry.active = false
+                                dirty.add(command.target)
+                                return
+                              }
+                              case "reload":
+                                sources[command.target] = command.source
+                                yield* state.reload()
+                                dirty.add(command.target)
+                            }
+                          }),
+                        { discard: true },
+                      )
+                      expect(notifications).toEqual(before)
+                    }),
+                  )
+                  expect(notifications).toEqual(before.map((count, index) => count + Number(dirty.has(index))))
+                  const flushed = calls
+                  states.forEach((state, index) => expect(state.get()).toEqual(expected(index)))
+                  expect(calls).toBe(flushed)
+                }),
+              { discard: true },
+            )
+          }).pipe(Effect.scoped, Effect.runSync),
+      ),
+      parameters,
+    ))
+
+  test("rebuilds all active callbacks once per change, reads for free otherwise, and never touches retained values", () =>
+    FastCheck.assert(
+      FastCheck.property(
+        FastCheck.array(
+          FastCheck.record({
+            append: FastCheck.array(operation, { minLength: 1, maxLength: 8 }),
+            reads: FastCheck.integer({ min: 1, max: 5 }),
+          }),
+          { minLength: 1, maxLength: 8 },
+        ),
+        FastCheck.nat(100),
+        (chunks, removal) =>
+          Effect.gen(function* () {
+            let calls = 0
+            const state = State.create({
+              initial: () => ({ value: 1, order: new Array<number>() }),
+              draft: (draft) => draft,
+            })
+            const registrations: State.Registration[] = []
+            const retained: { value: Value; snapshot: Value }[] = []
+            let settled = 0
+            const remember = () => {
+              const value = state.get()
+              retained.push({ value, snapshot: { value: value.value, order: [...value.order] } })
+            }
+            yield* State.batch(
+              Effect.gen(function* () {
+                yield* Effect.forEach(
+                  chunks,
+                  (chunk) =>
+                    Effect.gen(function* () {
+                      const before = calls
+                      const added = yield* Effect.forEach(chunk.append, (operation) =>
+                        state.transform((draft) => {
+                          calls++
+                          draft.value = apply(draft.value, operation)
+                          draft.order.push(draft.order.length)
+                        }),
+                      )
+                      registrations.push(...added)
+                      expect(calls).toBe(before)
+                      // The first read after a change replays every active callback; later reads do nothing.
+                      state.get()
+                      expect(calls).toBe(before + registrations.length)
+                      Array.from({ length: chunk.reads }).forEach(() => {
+                        const again = state.get()
+                        expect(again).toBe(state.get())
+                      })
+                      expect(calls).toBe(before + registrations.length)
+                      remember()
+                    }),
+                  { discard: true },
+                )
+
+                const removed = registrations[removal % registrations.length]
+                yield* removed.dispose
+                const before = calls
+                state.get()
+                expect(calls).toBe(before + registrations.length - 1)
+                remember()
+
+                const replayed = calls
+                yield* removed.dispose
+                state.get()
+                expect(calls).toBe(replayed)
+
+                yield* state.reload()
+                yield* state.reload()
+                expect(calls).toBe(replayed)
+                settled = replayed
+              }),
+            )
+            // Batch end notifies, and the two reloads left the value dirty: one more full rebuild.
+            expect(calls).toBe(settled + registrations.length - 1)
+            state.get()
+            expect(calls).toBe(settled + registrations.length - 1)
+            retained.forEach((entry) => expect(entry.value).toEqual(entry.snapshot))
+            expect(new Set(retained.map((entry) => entry.value)).size).toBe(retained.length)
+          }).pipe(Effect.scoped, Effect.runSync),
+      ),
+      parameters,
+    ))
+})

packages/core/test/state.test.ts

@@ -1,10 +1,8 @@
 import { describe, expect } from "bun:test"
 import { State } from "@opencode-ai/core/state"
-import { Deferred, Effect, Exit, Fiber, Layer, Scope } from "effect"
+import { Cause, Deferred, Effect, Exit, Fiber, Scope } from "effect"
 import { TestClock } from "effect/testing"
-import { testEffect } from "./lib/effect"
-
-const it = testEffect(Layer.empty)
+import { it } from "./lib/effect"
 
 describe("State", () => {
   it.effect("commits a transform atomically when its updater is interrupted", () =>
@@ -15,8 +13,9 @@ describe("State", () => {
       const state = State.create({
         initial: () => ({ values: [] as string[] }),
         draft: (draft) => ({ add: (value: string) => draft.values.push(value) }),
-        finalize: () =>
-          block ? Deferred.succeed(rebuilding, undefined).pipe(Effect.andThen(Deferred.await(release))) : Effect.void,
+        notify: block
+          ? Deferred.succeed(rebuilding, undefined).pipe(Effect.andThen(Deferred.await(release)))
+          : Effect.void,
       })
       const scope = yield* Scope.make()
       const fiber = yield* state
@@ -36,20 +35,20 @@ describe("State", () => {
     }),
   )
 
-  it.effect("commits rebuilt state before finalize runs", () =>
+  it.effect("makes current state visible before notifying", () =>
     Effect.gen(function* () {
       const observed: string[][] = []
       const state: State.Interface<{ values: string[] }, { add: (item: string) => void }> = State.create({
         initial: () => ({ values: [] as string[] }),
         draft: (draft) => ({ add: (item: string) => draft.values.push(item) }),
-        finalize: () => Effect.sync(() => observed.push([...state.get().values])),
+        notify: Effect.sync(() => observed.push([...state.get().values])),
       })
 
       yield* state.transform((draft) => {
         draft.add("value")
       })
 
-      // Update events publish from finalize, so consumers reading on the event
+      // Update events publish from notify, so consumers reading on the event
       // must observe the rebuilt state, not the previous one.
       expect(observed).toEqual([["value"]])
     }),
@@ -98,18 +97,18 @@ describe("State", () => {
     }),
   )
 
-  it.effect("batches automatic rebuilds", () =>
+  it.effect("batches notifications across domains", () =>
     Effect.gen(function* () {
       let finalized = 0
       const first = State.create({
         initial: () => ({ values: [] as string[] }),
         draft: (draft) => ({ add: (item: string) => draft.values.push(item) }),
-        finalize: () => Effect.sync(() => finalized++),
+        notify: Effect.sync(() => finalized++),
       })
       const second = State.create({
         initial: () => ({ values: [] as string[] }),
         draft: (draft) => ({ add: (item: string) => draft.values.push(item) }),
-        finalize: () => Effect.sync(() => finalized++),
+        notify: Effect.sync(() => finalized++),
       })
 
       yield* State.batch(
@@ -140,7 +139,7 @@ describe("State", () => {
       const state = State.create({
         initial: () => ({ values: [] as string[] }),
         draft: (draft) => ({ add: (item: string) => draft.values.push(item) }),
-        finalize: () => Effect.sync(() => finalized++),
+        notify: Effect.sync(() => finalized++),
       })
       const scope = yield* Scope.make()
       yield* Scope.addFinalizer(
@@ -152,7 +151,7 @@ describe("State", () => {
 
       const pending = yield* state.reload().pipe(Effect.forkChild({ startImmediately: true }))
       yield* TestClock.adjust("250 millis")
-      yield* State.batch(Scope.close(scope, Exit.void), { flush: false })
+      yield* State.shutdown(Scope.close(scope, Exit.void))
       expect(disposed).toBe(1)
       expect(finalized).toBe(1)
 
@@ -170,12 +169,12 @@ describe("State", () => {
       const closing = State.create({
         initial: () => ({}),
         draft: (draft) => draft,
-        finalize: () => Effect.sync(() => finalized.push("closing")),
+        notify: Effect.sync(() => finalized.push("closing")),
       })
       const live = State.create({
         initial: () => ({}),
         draft: (draft) => draft,
-        finalize: () => Effect.sync(() => finalized.push("live")),
+        notify: Effect.sync(() => finalized.push("live")),
       })
       const scope = yield* Scope.make()
       yield* closing.transform(() => {}).pipe(Scope.provide(scope))
@@ -184,7 +183,7 @@ describe("State", () => {
       yield* State.batch(
         Effect.gen(function* () {
           yield* live.transform(() => {})
-          yield* State.batch(Scope.close(scope, Exit.void), { flush: false })
+          yield* State.shutdown(Scope.close(scope, Exit.void))
         }),
       )
       expect(finalized).toEqual(["live"])
@@ -197,7 +196,7 @@ describe("State", () => {
       const state = State.create({
         initial: () => ({ values: [] as string[] }),
         draft: (draft) => ({ add: (item: string) => draft.values.push(item) }),
-        finalize: () => Effect.sync(() => finalized++),
+        notify: Effect.sync(() => finalized++),
       })
       yield* state.transform((draft) => {
         draft.add("value")
@@ -217,3 +216,496 @@ describe("State", () => {
     }),
   )
 })
+
+describe("State rebuild", () => {
+  it.effect("leaves a retained value untouched when later registrations rebuild", () =>
+    Effect.gen(function* () {
+      const state = State.create({
+        initial: () => ({ values: new Array<string>(), tags: new Map<string, number>() }),
+        draft: (data) => data,
+      })
+      yield* State.batch(
+        Effect.gen(function* () {
+          yield* state.transform((draft) => {
+            draft.values.push("first")
+            draft.tags.set("first", 1)
+          })
+          const retained = state.get()
+          expect(state.get()).toBe(retained)
+          yield* state.transform((draft) => {
+            draft.values.push("second")
+            draft.tags.set("second", 2)
+          })
+          const current = state.get()
+          expect(current).not.toBe(retained)
+          expect(current.values).toEqual(["first", "second"])
+          expect(Array.from(current.tags.keys())).toEqual(["first", "second"])
+          expect(retained.values).toEqual(["first"])
+          expect(Array.from(retained.tags.keys())).toEqual(["first"])
+        }),
+      )
+    }),
+  )
+
+  it.effect("recreates the draft with every rebuild", () =>
+    Effect.gen(function* () {
+      let drafts = 0
+      const state = State.create({
+        initial: () => ({ values: new Array<number>() }),
+        draft: (data) => {
+          drafts++
+          let sequence = 0
+          return { add: () => data.values.push(++sequence) }
+        },
+      })
+      yield* State.batch(
+        Effect.gen(function* () {
+          yield* state.transform((draft) => draft.add())
+          expect(state.get().values).toEqual([1])
+          expect(drafts).toBe(1)
+          yield* state.transform((draft) => draft.add())
+          expect(state.get().values).toEqual([1, 2])
+          expect(drafts).toBe(2)
+          yield* state.reload()
+          expect(state.get().values).toEqual([1, 2])
+          expect(drafts).toBe(3)
+        }),
+      )
+    }),
+  )
+
+  it.effect("rebuilds lazily on read and notifies even without a final read", () =>
+    Effect.gen(function* () {
+      const calls: string[] = []
+      const notifications: string[][] = []
+      const state: State.Interface<{ values: string[] }, { values: string[] }> = State.create({
+        initial: () => ({ values: new Array<string>() }),
+        draft: (data) => data,
+        notify: Effect.sync(() => notifications.push([...state.get().values])),
+      })
+      expect(state.get().values).toEqual([])
+      yield* State.batch(Effect.void)
+      expect(notifications).toEqual([])
+
+      yield* State.batch(
+        Effect.gen(function* () {
+          yield* state.transform((draft) => {
+            calls.push("first")
+            draft.values.push("first")
+          })
+          yield* state.transform((draft) => {
+            calls.push("second")
+            draft.values.push("second")
+          })
+          expect(calls).toEqual([])
+          const view = state.get()
+          expect(view.values).toEqual(["first", "second"])
+          expect(state.get()).toBe(view)
+          expect(calls).toEqual(["first", "second"])
+          yield* state.transform((draft) => {
+            calls.push("third")
+            draft.values.push("third")
+          })
+          expect(calls).toEqual(["first", "second"])
+          expect(state.get()).not.toBe(view)
+          expect(state.get().values).toEqual(["first", "second", "third"])
+          expect(view.values).toEqual(["first", "second"])
+          expect(calls).toEqual(["first", "second", "first", "second", "third"])
+          yield* state.transform((draft) => {
+            calls.push("fourth")
+            draft.values.push("fourth")
+          })
+          expect(notifications).toEqual([])
+        }),
+      )
+      expect(calls.slice(5)).toEqual(["first", "second", "third", "fourth"])
+      expect(notifications).toEqual([["first", "second", "third", "fourth"]])
+    }),
+  )
+
+  it.effect("replays every callback after each change outside a batch", () =>
+    Effect.gen(function* () {
+      const calls: number[] = []
+      const state = State.create({ initial: () => ({ value: 2 }), draft: (data) => data })
+      yield* state.transform((draft) => {
+        calls.push(1)
+        draft.value += 3
+      })
+      yield* state.transform((draft) => {
+        calls.push(2)
+        draft.value *= 4
+      })
+      // Each registration outside a batch notifies immediately, and notification materializes.
+      expect(calls).toEqual([1, 1, 2])
+      expect(state.get().value).toBe(20)
+      expect(calls).toEqual([1, 1, 2])
+      yield* state.transform((draft) => {
+        calls.push(3)
+        draft.value -= 1
+      })
+      expect(state.get().value).toBe(19)
+      expect(calls).toEqual([1, 1, 2, 1, 2, 3])
+    }),
+  )
+  ;[0, 1, 2].forEach((removed) =>
+    it.effect(`rebuilds noncommutative edits after removing position ${removed}`, () =>
+      Effect.gen(function* () {
+        const calls: number[] = []
+        const state = State.create({ initial: () => ({ value: 5 }), draft: (data) => data })
+        const registrations = yield* State.batch(
+          Effect.all([
+            state.transform((draft) => {
+              calls.push(0)
+              draft.value += 1
+            }),
+            state.transform((draft) => {
+              calls.push(1)
+              draft.value *= 3
+            }),
+            state.transform((draft) => {
+              calls.push(2)
+              draft.value -= 4
+            }),
+          ]),
+        )
+        expect(state.get().value).toBe(14)
+        const registration = registrations[removed]
+        if (!registration) throw new Error("missing registration")
+        calls.length = 0
+        yield* registration.dispose
+        expect(state.get().value).toBe([11, 2, 18][removed])
+        expect(calls).toEqual([0, 1, 2].filter((index) => index !== removed))
+        calls.length = 0
+        yield* registration.dispose
+        expect(calls).toEqual([])
+      }),
+    ),
+  )
+
+  it.effect("keeps equal callback registrations independently disposable", () =>
+    Effect.gen(function* () {
+      const state = State.create({ initial: () => ({ value: 0 }), draft: (data) => data })
+      const callback = (draft: { value: number }) => draft.value++
+      const first = yield* state.transform(callback)
+      const second = yield* state.transform(callback)
+      expect(state.get().value).toBe(2)
+      yield* first.dispose
+      expect(state.get().value).toBe(1)
+      yield* first.dispose
+      expect(state.get().value).toBe(1)
+      yield* second.dispose
+      expect(state.get().value).toBe(0)
+    }),
+  )
+
+  it.effect("does not evaluate a pending callback removed before the first read", () =>
+    Effect.gen(function* () {
+      let calls = 0
+      const state = State.create({ initial: () => ({ value: 0 }), draft: (data) => data })
+      yield* State.batch(
+        Effect.gen(function* () {
+          const registration = yield* state.transform(() => calls++)
+          yield* registration.dispose
+          expect(state.get().value).toBe(0)
+        }),
+      )
+      expect(calls).toBe(0)
+    }),
+  )
+
+  it.effect("invalidates on reload and reads new inputs before notification", () =>
+    Effect.gen(function* () {
+      let source = 1
+      let calls = 0
+      let notifications = 0
+      const state = State.create({
+        initial: () => ({ value: 0 }),
+        draft: (data) => data,
+        notify: Effect.sync(() => notifications++),
+      })
+      yield* state.transform((draft) => {
+        calls++
+        draft.value += source
+      })
+      notifications = 0
+      source = 2
+      const reload = yield* state.reload().pipe(Effect.forkChild({ startImmediately: true }))
+      expect(state.get().value).toBe(2)
+      expect(calls).toBe(2)
+      expect(notifications).toBe(0)
+      yield* TestClock.adjust("500 millis")
+      yield* Fiber.join(reload)
+      expect(calls).toBe(2)
+      expect(notifications).toBe(1)
+
+      yield* State.batch(
+        Effect.gen(function* () {
+          source = 3
+          yield* state.reload()
+          expect(state.get().value).toBe(3)
+          yield* state.transform((draft) => (draft.value *= 10))
+          expect(state.get().value).toBe(30)
+          expect(calls).toBe(4)
+          expect(notifications).toBe(1)
+        }),
+      )
+      expect(notifications).toBe(2)
+    }),
+  )
+
+  it.effect("resamples a changing initial value even when there are no transforms", () =>
+    Effect.gen(function* () {
+      let source = 1
+      const state = State.create({ initial: () => ({ value: source }), draft: (data) => data })
+      expect(state.get().value).toBe(1)
+      // A captured input changed but nothing invalidated the value, so reads stay cached.
+      source = 2
+      expect(state.get().value).toBe(1)
+      yield* State.batch(
+        Effect.gen(function* () {
+          yield* state.reload()
+          expect(state.get().value).toBe(2)
+        }),
+      )
+    }),
+  )
+
+  it.effect("keeps the previous value when a rebuild throws and retries on the next read", () =>
+    Effect.gen(function* () {
+      let fail = true
+      let initializations = 0
+      const state = State.create({
+        initial: () => {
+          initializations++
+          return { values: new Array<string>() }
+        },
+        draft: (data) => data,
+      })
+      yield* state.transform((draft) => draft.values.push("first"))
+      const before = state.get()
+      expect(initializations).toBe(2)
+      yield* State.batch(
+        Effect.gen(function* () {
+          yield* state.transform((draft) => {
+            draft.values.push("second")
+            if (fail) throw new Error("failed edit")
+          })
+          expect(() => state.get()).toThrow("failed edit")
+          expect(initializations).toBe(3)
+          expect(() => state.get()).toThrow("failed edit")
+          expect(initializations).toBe(4)
+          // The partially edited container is discarded; the last complete value is untouched.
+          expect(before.values).toEqual(["first"])
+          fail = false
+          expect(state.get().values).toEqual(["first", "second"])
+          expect(initializations).toBe(5)
+          yield* state.transform((draft) => draft.values.push("third"))
+          expect(state.get().values).toEqual(["first", "second", "third"])
+          expect(initializations).toBe(6)
+        }),
+      )
+    }),
+  )
+
+  it.effect("recovers by disposing a failing callback without keeping its partial edits", () =>
+    Effect.gen(function* () {
+      const state = State.create({ initial: () => ({ value: 2 }), draft: (data) => data })
+      yield* state.transform((draft) => (draft.value *= 3))
+      yield* State.batch(
+        Effect.gen(function* () {
+          const failing = yield* state.transform((draft) => {
+            draft.value += 100
+            throw new Error("bad callback")
+          })
+          expect(() => state.get()).toThrow("bad callback")
+          yield* failing.dispose
+          expect(state.get().value).toBe(6)
+          yield* state.transform((draft) => (draft.value += 1))
+          expect(state.get().value).toBe(7)
+        }),
+      )
+    }),
+  )
+})
+
+describe("State notification boundaries", () => {
+  ;["body", "observer"].forEach((phase) =>
+    it.effect(
+      `cancels remaining observers when interrupted during the ${phase}, without rolling back registrations`,
+      () =>
+        Effect.gen(function* () {
+          const entered = yield* Deferred.make<void>()
+          const observed: string[] = []
+          let block = true
+          const first = State.create({
+            initial: () => ({ value: 0 }),
+            draft: (data) => data,
+            notify: Effect.gen(function* () {
+              observed.push("first")
+              if (phase !== "observer" || !block) return
+              yield* Deferred.succeed(entered, undefined)
+              yield* Effect.never
+            }),
+          })
+          const second = State.create({
+            initial: () => ({ value: 0 }),
+            draft: (data) => data,
+            notify: Effect.sync(() => observed.push("second")),
+          })
+          const writer = yield* State.batch(
+            Effect.gen(function* () {
+              yield* first.transform((draft) => draft.value++)
+              yield* second.transform((draft) => draft.value++)
+              if (phase !== "body") return
+              yield* Deferred.succeed(entered, undefined)
+              yield* Effect.never
+            }),
+          ).pipe(Effect.forkChild({ startImmediately: true }))
+          yield* Deferred.await(entered)
+          yield* Fiber.interrupt(writer)
+          block = false
+          expect(Exit.hasInterrupts(yield* Fiber.await(writer))).toBe(true)
+          expect([first.get().value, second.get().value]).toEqual([1, 1])
+          expect(observed).toEqual(phase === "body" ? [] : ["first"])
+        }),
+    ),
+  )
+
+  it.effect("shares nested live batches and does not retain an escaped batch", () =>
+    Effect.gen(function* () {
+      let notifications = 0
+      const state = State.create({
+        initial: () => ({ value: 0 }),
+        draft: (data) => data,
+        notify: Effect.sync(() => notifications++),
+      })
+      const inherit = yield* State.batch(
+        Effect.gen(function* () {
+          yield* state.transform((draft) => draft.value++)
+          yield* State.batch(state.transform((draft) => draft.value++))
+          expect(state.get().value).toBe(2)
+          expect(notifications).toBe(0)
+          return yield* State.inherit()
+        }),
+      )
+      expect(notifications).toBe(1)
+      yield* inherit(state.transform((draft) => draft.value++))
+      expect(state.get().value).toBe(3)
+      expect(notifications).toBe(2)
+    }),
+  )
+
+  it.effect("lets observers read other pending domains and register more edits", () =>
+    Effect.gen(function* () {
+      const scope = yield* Scope.Scope
+      const observed: number[] = []
+      let added = false
+      const other = State.create({ initial: () => ({ value: 0 }), draft: (data) => data })
+      const state: State.Interface<object, object> = State.create({
+        initial: () => ({}),
+        draft: (data) => data,
+        notify: Effect.gen(function* () {
+          observed.push(other.get().value)
+          if (added) return
+          added = true
+          yield* state.transform(() => {}).pipe(Scope.provide(scope))
+        }),
+      })
+      yield* State.batch(
+        Effect.gen(function* () {
+          yield* state.transform(() => {})
+          yield* other.transform((draft) => (draft.value = 42))
+        }),
+      )
+      expect(observed).toEqual([42, 42])
+    }),
+  )
+
+  it.effect("allows a debounced observer to await another reload", () =>
+    Effect.gen(function* () {
+      let source = 1
+      let reloadAgain = false
+      const observed: number[] = []
+      const state: State.Interface<{ value: number }, { value: number }> = State.create({
+        initial: () => ({ value: 0 }),
+        draft: (data) => data,
+        notify: Effect.gen(function* () {
+          observed.push(state.get().value)
+          if (!reloadAgain) return
+          reloadAgain = false
+          source = 3
+          yield* state.reload()
+        }),
+      })
+      yield* state.transform((draft) => (draft.value = source))
+      source = 2
+      reloadAgain = true
+      const reload = yield* state.reload().pipe(Effect.forkChild({ startImmediately: true }))
+      yield* TestClock.adjust("1 second")
+      yield* Fiber.join(reload)
+      expect(observed).toEqual([1, 2, 3])
+    }),
+  )
+
+  it.effect("attempts every domain notification and preserves both batch and observer failures", () =>
+    Effect.gen(function* () {
+      const observed: string[] = []
+      let fail = true
+      const first = State.create({
+        initial: () => ({}),
+        draft: (data) => data,
+        notify: Effect.suspend(() => (fail ? Effect.die("observer failed") : Effect.void)),
+      })
+      const second = State.create({
+        initial: () => ({}),
+        draft: (data) => data,
+        notify: Effect.sync(() => observed.push("second")),
+      })
+      const exit = yield* State.batch(
+        Effect.gen(function* () {
+          yield* first.transform(() => {})
+          yield* second.transform(() => {})
+          return yield* Effect.fail("body failed")
+        }),
+      ).pipe(Effect.exit)
+      fail = false
+      expect(observed).toEqual(["second"])
+      expect(Exit.isFailure(exit)).toBe(true)
+      if (Exit.isFailure(exit)) {
+        expect(Cause.pretty(exit.cause)).toContain("observer failed")
+        expect(Cause.pretty(exit.cause)).toContain("body failed")
+      }
+    }),
+  )
+
+  it.effect("keeps cancelled reload callers independent and shares notification results", () =>
+    Effect.gen(function* () {
+      let fail = false
+      let notifications = 0
+      const state = State.create({
+        initial: () => ({}),
+        draft: (data) => data,
+        notify: Effect.sync(() => {
+          notifications++
+          if (fail) throw new Error("notification failed")
+        }),
+      })
+      yield* state.transform(() => {})
+      notifications = 0
+      fail = true
+      const cancelled = yield* state.reload().pipe(Effect.forkChild({ startImmediately: true }))
+      const first = yield* state.reload().pipe(Effect.forkChild({ startImmediately: true }))
+      const second = yield* state.reload().pipe(Effect.forkChild({ startImmediately: true }))
+      yield* Fiber.interrupt(cancelled)
+      yield* TestClock.adjust("500 millis")
+      const exits = yield* Fiber.awaitAll([first, second])
+      fail = false
+      expect(exits.every(Exit.isFailure)).toBe(true)
+      expect(notifications).toBe(1)
+      const recovered = yield* state.reload().pipe(Effect.forkChild({ startImmediately: true }))
+      yield* TestClock.adjust("500 millis")
+      yield* Fiber.join(recovered)
+      expect(notifications).toBe(2)
+    }),
+  )
+})

packages/core/test/tool-registry.test.ts

@@ -242,6 +242,7 @@ describe("Tool", () => {
           draft.add({ ...constant("overlay"), name: "echo", options: { codemode: false } })
         })
         .pipe(Scope.provide(scope))
+      // Each registration outside a batch notifies immediately, and every rebuild replays all transforms.
       expect(runs).toEqual(["base", "base", "overlay"])
       expect((yield* executeTool(service, call("echo"))).output).toEqual({ text: "overlay" })
 
@@ -254,7 +255,7 @@ describe("Tool", () => {
     }),
   )
 
-  it.effect("batches tool publication and suppresses terminal teardown replay", () =>
+  it.effect("reads pending tools inside a batch and suppresses terminal teardown replay", () =>
     Effect.gen(function* () {
       const service = yield* Tool.Service
       const runs: string[] = []
@@ -270,13 +271,14 @@ describe("Tool", () => {
             draft.add({ ...constant("overlay"), name: "echo", options: { codemode: false } })
           })
           expect(runs).toEqual([])
-          expect((yield* service.snapshot()).definitions.map((tool) => tool.name)).toEqual(["execute"])
+          expect((yield* service.snapshot()).definitions.map((tool) => tool.name)).toEqual(["echo", "execute"])
+          expect(runs).toEqual(["base", "overlay"])
         }).pipe(Scope.provide(scope)),
       )
 
       expect(runs).toEqual(["base", "overlay"])
       expect((yield* executeTool(service, call("echo"))).output).toEqual({ text: "overlay" })
-      yield* State.batch(Scope.close(scope, Exit.void), { flush: false })
+      yield* State.shutdown(Scope.close(scope, Exit.void))
       expect(runs).toEqual(["base", "overlay"])
     }),
   )
@@ -506,6 +508,41 @@ describe("Tool", () => {
     }),
   )
 
+  it.effect("retains namespace descriptions in executable snapshots after appended transforms", () =>
+    Effect.gen(function* () {
+      const service = yield* Tool.Service
+      yield* service.transform((draft) => {
+        draft.namespace({ name: "acme", description: "Archival operations" })
+        draft.add({ ...make(), options: { namespace: "acme" } })
+      })
+      const advertised = yield* service.snapshot()
+
+      yield* service.transform((draft) => {
+        draft.namespace({ name: "acme", description: "Billing operations" })
+      })
+      const current = yield* service.snapshot()
+      expect(advertised.codeModeCatalog?.tools).toMatchObject([{ name: "acme", description: "Archival operations" }])
+      expect(current.codeModeCatalog?.tools).toMatchObject([{ name: "acme", description: "Billing operations" }])
+
+      const search = (snapshot: Tool.Snapshot, query: string) =>
+        snapshot.execute({
+          ...call("execute"),
+          call: {
+            type: "tool-call",
+            id: `namespace-${query}`,
+            name: "execute",
+            input: {
+              code: `return search({ query: ${JSON.stringify(query)} }).items.map(item => item.path).join(",")`,
+            },
+          },
+        })
+      expect((yield* search(advertised, "archival")).output).toMatchObject({ output: "tools.acme.echo" })
+      expect((yield* search(advertised, "billing")).output).toMatchObject({ output: "" })
+      expect((yield* search(current, "archival")).output).toMatchObject({ output: "" })
+      expect((yield* search(current, "billing")).output).toMatchObject({ output: "tools.acme.echo" })
+    }),
+  )
+
   it.effect("preserves a top-level tool that also has child tools", () =>
     Effect.gen(function* () {
       const service = yield* Tool.Service

packages/core/test/vcs.test.ts

@@ -2,7 +2,8 @@ import { $ } from "bun"
 import { describe, expect } from "bun:test"
 import fs from "fs/promises"
 import path from "path"
-import { Cause, Effect, Exit, Fiber, Layer, Stream } from "effect"
+import { Cause, Context, Deferred, Effect, Exit, Fiber, Layer, Option, Schema, Scope, Stream } from "effect"
+import { TestClock } from "effect/testing"
 import { LayerNode } from "@opencode-ai/util/effect/layer-node"
 import { AppProcess } from "@opencode-ai/util/process"
 import { FSUtil } from "@opencode-ai/util/fs-util"
@@ -10,6 +11,7 @@ import { Git } from "@opencode-ai/core/git"
 import { Bus } from "@opencode-ai/core/bus"
 import { Location } from "@opencode-ai/core/location"
 import { AbsolutePath } from "@opencode-ai/core/schema"
+import { State } from "@opencode-ai/core/state"
 import { Vcs } from "@opencode-ai/core/vcs"
 import { VcsGitPlugin } from "@opencode-ai/core/plugin/vcs/git"
 import type { VcsDefinition, VcsDiffInput } from "@opencode-ai/plugin/effect/vcs"
@@ -17,9 +19,15 @@ import { FileSystem } from "@opencode-ai/schema/filesystem"
 import { VcsEvent } from "@opencode-ai/schema/vcs-event"
 import { location } from "./fixture/location"
 import { tmpdir } from "./fixture/tmpdir"
-import { it } from "./lib/effect"
+import { it, testEffect } from "./lib/effect"
 import { host } from "./plugin/host"
 
+const Done = Bus.ephemeral({ type: "test.vcs.done", schema: {} })
+const here = Location.node.replace(
+  Layer.succeed(Location.Service, Location.Service.of(location({ directory: AbsolutePath.make(import.meta.dir) }))),
+)
+const synthetic = testEffect(LayerNode.compile(LayerNode.group([Vcs.node, Bus.node]), { replacements: [here] }))
+
 const provide = (directory: string, input: { git?: boolean; worktree?: string } = {}) =>
   Effect.provide(
     LayerNode.compile(LayerNode.group([Vcs.node, Bus.node, Location.node, AppProcess.node, FSUtil.node, Git.node]), {
@@ -146,6 +154,44 @@ describe("Vcs", () => {
     ),
   )
 
+  synthetic.effect("reads batched providers without refreshing intermediate selections", () =>
+    Effect.gen(function* () {
+      const vcs = yield* Vcs.Service
+      const reads: string[] = []
+      yield* State.batch(
+        Effect.gen(function* () {
+          yield* vcs.transform((draft) => {
+            draft.add(
+              provider({
+                info: () =>
+                  Effect.sync(() => {
+                    reads.push("intermediate")
+                    return { branch: { current: "intermediate" } }
+                  }),
+              }),
+            )
+            draft.default.set("custom")
+          })
+          expect((yield* vcs.status())[0]?.file).toBe("file.txt")
+          expect(yield* vcs.info()).toEqual({ branch: {} })
+          yield* vcs.transform((draft) =>
+            draft.add(
+              provider({
+                info: () =>
+                  Effect.sync(() => {
+                    reads.push("final")
+                    return { branch: { current: "final" } }
+                  }),
+              }),
+            ),
+          )
+        }),
+      )
+      expect(reads).toEqual(["final"])
+      expect(yield* vcs.info()).toEqual({ branch: { current: "final" } })
+    }),
+  )
+
   it.live("passes location scope and bounded diff options to providers", () =>
     withTmp((directory) =>
       Effect.gen(function* () {
@@ -210,8 +256,16 @@ describe("Vcs", () => {
     withTmp((directory) =>
       Effect.gen(function* () {
         const vcs = yield* Vcs.Service
+        let interrupt = false
         yield* vcs.transform((draft) => {
-          draft.add(provider({ status: () => Effect.never, diff: () => Effect.never, base: () => Effect.never }))
+          draft.add(
+            provider({
+              info: () => (interrupt ? Effect.interrupt : Effect.succeed({ branch: { current: "feature" } })),
+              status: () => Effect.never,
+              diff: () => Effect.never,
+              base: () => Effect.never,
+            }),
+          )
           draft.default.set("custom")
         })
 
@@ -227,10 +281,239 @@ describe("Vcs", () => {
         yield* Fiber.interrupt(base)
         const cancelled = yield* Fiber.await(base)
         expect(Exit.isFailure(cancelled) && Cause.hasInterrupts(cancelled.cause)).toBeTrue()
+
+        interrupt = true
+        const refreshed = yield* vcs.reload().pipe(Effect.exit)
+        expect(Exit.isFailure(refreshed) && Cause.hasInterruptsOnly(refreshed.cause)).toBeTrue()
       }).pipe(provide(directory)),
     ),
   )
 
+  it.effect("stops in-flight and queued VCS reloads when its layer closes", () =>
+    Effect.gen(function* () {
+      const bus = yield* Bus.Service
+      const entered = yield* Deferred.make<void>()
+      const release = yield* Deferred.make<void>()
+      const root = yield* Scope.make()
+      yield* Effect.addFinalizer(() =>
+        Deferred.succeed(release, undefined).pipe(
+          Effect.andThen(State.shutdown(Scope.close(root, Exit.void))),
+          Effect.andThen(TestClock.adjust("500 millis")),
+        ),
+      )
+      const context = yield* Layer.buildWithScope(
+        LayerNode.compile(Vcs.node, { replacements: [Bus.node.replace(Layer.succeed(Bus.Service, bus)), here] }),
+        root,
+      )
+      const vcs = Context.get(context, Vcs.Service)
+      const reads: string[] = []
+      const observed: (string | undefined)[] = []
+      yield* Effect.acquireRelease(
+        bus.listen((event) =>
+          Effect.sync(() => {
+            if (event.type !== VcsEvent.BranchUpdated.type) return
+            observed.push(Schema.decodeUnknownSync(VcsEvent.BranchUpdated.data)(event.data).branch)
+          }),
+        ),
+        (unsubscribe) => unsubscribe,
+      )
+      let branch = "initial"
+      let block = false
+      yield* vcs
+        .transform((draft) => {
+          draft.add(
+            provider({
+              info: () =>
+                Effect.gen(function* () {
+                  const value = branch
+                  reads.push(value)
+                  if (block) {
+                    block = false
+                    yield* Deferred.succeed(entered, undefined)
+                    yield* Deferred.await(release)
+                  }
+                  return { branch: { current: value } }
+                }),
+            }),
+          )
+          draft.default.set("custom")
+        })
+        .pipe(Scope.provide(root))
+      observed.length = 0
+
+      block = true
+      const first = yield* vcs.reload().pipe(Effect.forkChild({ startImmediately: true }))
+      yield* TestClock.adjust("500 millis")
+      yield* Deferred.await(entered)
+      branch = "late"
+      const second = yield* vcs.reload().pipe(Effect.forkChild({ startImmediately: true }))
+      yield* TestClock.adjust("500 millis")
+      expect(reads).toEqual(["initial", "initial"])
+      expect(first.pollUnsafe()).toBeUndefined()
+      expect(second.pollUnsafe()).toBeUndefined()
+      const snapshot = yield* vcs.info()
+
+      const shutdown = yield* State.shutdown(Scope.close(root, Exit.void)).pipe(
+        Effect.forkChild({ startImmediately: true }),
+      )
+      yield* TestClock.adjust("1 millis")
+      expect(shutdown.pollUnsafe()).toBeDefined()
+      expect(first.pollUnsafe()).toBeDefined()
+      expect(second.pollUnsafe()).toBeDefined()
+      expect(yield* Deferred.isDone(release)).toBe(false)
+      yield* Fiber.join(shutdown)
+      yield* Deferred.succeed(release, undefined)
+      yield* Fiber.join(first)
+      yield* Fiber.join(second)
+      expect(reads).toEqual(["initial", "initial"])
+      expect(observed).toEqual([])
+      expect(yield* vcs.info()).toBe(snapshot)
+    }).pipe(Effect.provide(LayerNode.compile(Bus.node))),
+  )
+
+  it.live("keeps watching HEAD changes after a transform replay failure", () =>
+    withGit((directory) =>
+      Effect.gen(function* () {
+        const vcs = yield* Vcs.Service
+        const bus = yield* Bus.Service
+        const replayed = yield* Deferred.make<void>()
+        const faulty = yield* Scope.make()
+        yield* Effect.addFinalizer(() => Scope.close(faulty, Exit.void))
+        let branch = "initial"
+        yield* vcs.transform((draft) =>
+          draft.add(provider({ id: "git", info: () => Effect.sync(() => ({ branch: { current: branch } })) })),
+        )
+        const failure = new Error("fixture replay failed")
+        let replays = 0
+        const failed = yield* vcs
+          .transform(() => {
+            if (++replays === 2) Deferred.doneUnsafe(replayed, Exit.void)
+            throw failure
+          })
+          .pipe(Scope.provide(faulty), Effect.exit)
+        expect(Exit.isFailure(failed) && Cause.squash(failed.cause)).toBe(failure)
+
+        yield* bus.publish(FileSystem.Event.Changed, { file: path.join(directory, ".git", "HEAD"), event: "change" })
+        yield* Deferred.await(replayed).pipe(Effect.timeout("1 second"))
+        yield* Effect.yieldNow
+        const status = yield* vcs.status().pipe(Effect.exit)
+        expect(Exit.isFailure(status) && Cause.squash(status.cause)).toBe(failure)
+        expect((yield* vcs.info()).branch.current).toBe("initial")
+
+        branch = "recovered"
+        yield* Scope.close(faulty, Exit.void)
+        expect((yield* vcs.info()).branch.current).toBe("recovered")
+        const updated = yield* bus
+          .subscribe(VcsEvent.BranchUpdated)
+          .pipe(Stream.runHead, Effect.timeout("1 second"), Effect.forkScoped({ startImmediately: true }))
+        branch = "after-recovery"
+        yield* bus.publish(FileSystem.Event.Changed, { file: path.join(directory, ".git", "HEAD"), event: "change" })
+        expect(Option.getOrUndefined(yield* Fiber.join(updated))).toMatchObject({ data: { branch: "after-recovery" } })
+        expect((yield* vcs.info()).branch.current).toBe("after-recovery")
+      }),
+    ),
+  )
+
+  it.live("serializes filesystem and config refreshes while reading the latest desired provider", () =>
+    withGit((directory) =>
+      Effect.gen(function* () {
+        const vcs = yield* Vcs.Service
+        const bus = yield* Bus.Service
+        const started = yield* Deferred.make<void>()
+        const release = yield* Deferred.make<void>()
+        const accepted = yield* Deferred.make<void>()
+        const reads: string[] = []
+        yield* vcs.transform((draft) =>
+          draft.add(
+            provider({
+              id: "git",
+              info: () =>
+                Effect.gen(function* () {
+                  reads.push(reads.length === 0 ? "initial" : "filesystem")
+                  if (reads.length === 1) return { branch: { current: "initial" } }
+                  yield* Deferred.succeed(started, undefined)
+                  yield* Deferred.await(release)
+                  return { branch: { current: "filesystem" } }
+                }),
+            }),
+          ),
+        )
+        const updates = yield* bus
+          .subscribe(VcsEvent.BranchUpdated)
+          .pipe(Stream.take(2), Stream.runLast, Effect.forkScoped({ startImmediately: true }))
+
+        yield* Effect.gen(function* () {
+          yield* bus.publish(FileSystem.Event.Changed, { file: path.join(directory, ".git", "HEAD"), event: "change" })
+          yield* Deferred.await(started)
+          const configured = yield* State.batch(
+            Effect.gen(function* () {
+              yield* vcs.transform((draft) =>
+                draft.add(
+                  provider({
+                    id: "git",
+                    info: () =>
+                      Effect.sync(() => {
+                        reads.push("config")
+                        return { branch: { current: "config" } }
+                      }),
+                    status: () => Effect.succeed([{ file: "config.txt", additions: 1, deletions: 0, status: "added" }]),
+                  }),
+                ),
+              )
+              expect((yield* vcs.status())[0]?.file).toBe("config.txt")
+              expect(yield* vcs.info()).toEqual({ branch: { current: "initial" } })
+              yield* Deferred.succeed(accepted, undefined)
+            }),
+          ).pipe(Effect.forkScoped({ startImmediately: true }))
+          yield* Deferred.await(accepted)
+          expect(reads).toEqual(["initial", "filesystem"])
+
+          yield* Deferred.succeed(release, undefined)
+          yield* Fiber.join(configured)
+          expect(Option.getOrUndefined(yield* Fiber.join(updates))?.data.branch).toBe("config")
+          expect(yield* vcs.info()).toEqual({ branch: { current: "config" } })
+          expect(reads).toEqual(["initial", "filesystem", "config"])
+        }).pipe(Effect.ensuring(Deferred.succeed(release, undefined)))
+      }),
+    ),
+  )
+
+  synthetic.effect("keeps branch streams current when listeners change the selected provider", () =>
+    Effect.gen(function* () {
+      const vcs = yield* Vcs.Service
+      const bus = yield* Bus.Service
+      const scope = yield* Effect.scope
+      const updates = yield* bus.subscribe([VcsEvent.BranchUpdated, Done]).pipe(
+        Stream.takeUntil((event) => event.type === Done.type),
+        Stream.runCollect,
+        Effect.forkScoped({ startImmediately: true }),
+      )
+      const unsubscribe = yield* bus.listen((event) => {
+        if (
+          event.type !== VcsEvent.BranchUpdated.type ||
+          Schema.decodeUnknownSync(VcsEvent.BranchUpdated.data)(event.data).branch !== "feature"
+        )
+          return Effect.void
+        return vcs
+          .transform((draft) =>
+            draft.add(provider({ info: () => Effect.succeed({ branch: { current: "listener" } }) })),
+          )
+          .pipe(Scope.provide(scope), Effect.asVoid)
+      })
+      yield* Effect.gen(function* () {
+        yield* vcs.transform((draft) => {
+          draft.add(provider())
+          draft.default.set("custom")
+        })
+        yield* bus.publish(Done, {})
+        const events = (yield* Fiber.join(updates)).filter((event) => event.type === VcsEvent.BranchUpdated.type)
+        expect(yield* vcs.info()).toEqual({ branch: { current: "listener" } })
+        expect(events.length).toBeGreaterThanOrEqual(2)
+        expect(events.at(-1)?.data.branch).toBe((yield* vcs.info()).branch.current)
+      }).pipe(Effect.ensuring(unsubscribe))
+    }),
+  )
+
   it.live("lists local branches by recent activity", () =>
     withGit((directory) =>
       Effect.gen(function* () {

packages/plugin/src/effect/README.md

@@ -45,7 +45,7 @@ yield *
   })
 ```
 
-OpenCode rebuilds the domain when a transform is registered or disposed. A rebuild starts from fresh domain state and runs every active transform in registration order.
+Registry reads rebuild synchronously when registrations changed, applying every transform in registration order to a fresh value; unchanged registries return the previous value. Values read earlier are never mutated. Notifications and resource reconciliation run separately from that materialization.
 
 Available transform hooks are namespaced by domain:
 

packages/protocol/openapi.json

@@ -486,6 +486,82 @@
         "summary": "List plugins"
       }
     },
+    "/api/plugin/await-activation": {
+      "post": {
+        "tags": ["plugin"],
+        "operationId": "v2.plugin.awaitActivation",
+        "parameters": [
+          {
+            "name": "location",
+            "in": "query",
+            "schema": {
+              "anyOf": [
+                {
+                  "type": "object",
+                  "properties": {
+                    "directory": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ]
+                    },
+                    "workspace": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ]
+                    }
+                  },
+                  "additionalProperties": false
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "required": false,
+            "style": "deepObject",
+            "explode": true
+          }
+        ],
+        "security": [],
+        "responses": {
+          "204": {
+            "description": "<No Content>"
+          },
+          "400": {
+            "description": "InvalidRequestError",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/InvalidRequestErrorEncoded"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "UnauthorizedError",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/UnauthorizedErrorEncoded"
+                }
+              }
+            }
+          }
+        },
+        "description": "Wait for configured plugin activation at a Location to settle, including missing-package installs. Completion does not imply every plugin succeeded or background resource discovery finished. Cancelling this wait does not cancel activation.",
+        "summary": "Wait for plugin activation"
+      }
+    },
     "/api/plugin/check": {
       "post": {
         "tags": ["plugin"],

packages/protocol/src/groups/plugin.ts

@@ -20,6 +20,21 @@ export const PluginGroup = HttpApiGroup.make("server.plugin")
         }),
       ),
   )
+  .add(
+    HttpApiEndpoint.post("plugin.awaitActivation", "/api/plugin/await-activation", {
+      query: LocationQuery,
+      success: HttpApiSchema.NoContent,
+    })
+      .annotateMerge(locationQueryOpenApi)
+      .annotateMerge(
+        OpenApi.annotations({
+          identifier: "v2.plugin.awaitActivation",
+          summary: "Wait for plugin activation",
+          description:
+            "Wait for configured plugin activation at a Location to settle, including missing-package installs. Completion does not imply every plugin succeeded or background resource discovery finished. Cancelling this wait does not cancel activation.",
+        }),
+      ),
+  )
   .add(
     HttpApiEndpoint.post("plugin.check", "/api/plugin/check", {
       query: LocationQuery,

packages/server/src/handlers/plugin.ts

@@ -13,6 +13,7 @@ export const PluginHandler = HttpApiBuilder.group(Api, "server.plugin", (handler
         return yield* response(Plugin.Service.use((plugin) => plugin.list()))
       }),
     )
+    .handle("plugin.awaitActivation", () => Plugin.Service.use((plugin) => plugin.awaitActivation))
     .handle("plugin.check", (ctx) =>
       Effect.gen(function* () {
         const plugins = yield* Plugin.Service

packages/server/test/plugin-activation.test.ts

@@ -0,0 +1,192 @@
+import { expect } from "bun:test"
+import { mkdir } from "node:fs/promises"
+import path from "node:path"
+import { SdkPlugins } from "@opencode-ai/core/plugin/sdk"
+import { Plugin } from "@opencode-ai/plugin/effect"
+import { Context, Deferred, Effect, Fiber, Layer } from "effect"
+import { HttpEffect, HttpRouter, HttpServer } from "effect/unstable/http"
+import { tmpdirScoped } from "../../core/test/fixture/tmpdir"
+import { it } from "../../core/test/lib/effect"
+import { createRoutes } from "../src/routes"
+
+const fixture = Effect.fn(function* (plugin: Plugin.Plugin) {
+  const tmp = yield* tmpdirScoped("opencode-plugin-activation-")
+  const first = path.join(tmp.path, "first")
+  const second = path.join(tmp.path, "second")
+  const config = path.join(tmp.path, "config")
+  yield* Effect.promise(() => Promise.all([first, second, config].map((directory) => mkdir(directory))))
+  const context = yield* Layer.build(
+    createRoutes({
+      password: "secret",
+      database: { path: ":memory:" },
+      models: { fetch: false },
+      fs: { filewatcher: false },
+      config: {
+        directory: config,
+        project: false,
+        content: JSON.stringify({
+          providers: {
+            acme: {
+              models: {
+                reasoner: { name: "Configured Reasoner", limit: { context: 96_000, output: 8_000 } },
+              },
+            },
+          },
+        }),
+      },
+    }).pipe(Layer.provide(HttpServer.layerServices)),
+  )
+  const sdk = Context.get(context, SdkPlugins.Service)
+  yield* sdk.register(plugin)
+  const handler = Context.get(context, HttpRouter.HttpRouter).asHttpEffect().pipe(HttpEffect.toWebHandlerWith(context))
+  return {
+    first,
+    second,
+    request: (method: "GET" | "POST", route: string, directory = first, signal?: AbortSignal) =>
+      Effect.promise((interruption) => {
+        const url = new URL(route, "http://opencode.local")
+        url.searchParams.set("location[directory]", directory)
+        return handler(
+          new Request(url, {
+            method,
+            headers: { authorization: `Basic ${btoa("opencode:secret")}` },
+            signal: signal ?? interruption,
+          }),
+        )
+      }),
+  }
+})
+
+it.live(
+  "awaits activation only for the requested location without blocking model or plugin snapshots",
+  () =>
+    Effect.gen(function* () {
+      const started = yield* Deferred.make<void>()
+      const release = yield* Deferred.make<void>()
+      const server = yield* fixture(
+        Plugin.define({
+          id: "slow-plugin",
+          effect: (ctx) =>
+            Effect.gen(function* () {
+              if (path.basename(ctx.location.directory) !== "first") return
+              yield* Deferred.succeed(started, undefined)
+              yield* Deferred.await(release)
+            }),
+        }),
+      )
+      const pending = yield* server.request("POST", "/api/plugin/await-activation").pipe(Effect.forkScoped)
+      yield* Deferred.await(started)
+      expect(pending.pollUnsafe()).toBeUndefined()
+
+      const models = yield* server.request("GET", "/api/model")
+      expect(models.status).toBe(200)
+      expect(yield* Effect.promise(() => models.json())).toMatchObject({
+        location: { directory: server.first },
+        data: expect.not.arrayContaining([expect.objectContaining({ providerID: "acme", id: "reasoner" })]),
+      })
+      const plugins = yield* server.request("GET", "/api/plugin")
+      expect(plugins.status).toBe(200)
+      expect(yield* Effect.promise(() => plugins.json())).toMatchObject({ location: { directory: server.first } })
+
+      const second = yield* server.request("POST", "/api/plugin/await-activation", server.second)
+      expect(second.status).toBe(204)
+      expect(pending.pollUnsafe()).toBeUndefined()
+
+      yield* Deferred.succeed(release, undefined)
+      const response = yield* Fiber.join(pending)
+      expect(response.status).toBe(204)
+      expect(yield* Effect.promise(() => response.text())).toBe("")
+      const configured = yield* server.request("GET", "/api/model")
+      expect(configured.status).toBe(200)
+      expect(yield* Effect.promise(() => configured.json())).toMatchObject({
+        location: { directory: server.first },
+        data: expect.arrayContaining([
+          expect.objectContaining({
+            providerID: "acme",
+            id: "reasoner",
+            name: "Configured Reasoner",
+            limit: { context: 96_000, output: 8_000 },
+          }),
+        ]),
+      })
+      const active = yield* server.request("GET", "/api/plugin")
+      expect(active.status).toBe(200)
+      expect(yield* Effect.promise(() => active.json())).toMatchObject({
+        data: expect.arrayContaining([
+          expect.objectContaining({ id: "slow-plugin", source: { type: "sdk" }, state: { status: "active" } }),
+        ]),
+      })
+    }).pipe(Effect.timeout("10 seconds")),
+  15_000,
+)
+
+it.live(
+  "aborting an activation wait does not cancel plugin setup",
+  () =>
+    Effect.gen(function* () {
+      const started = yield* Deferred.make<void>()
+      const release = yield* Deferred.make<void>()
+      const completed = yield* Deferred.make<void>()
+      const interrupted = yield* Deferred.make<void>()
+      const server = yield* fixture(
+        Plugin.define({
+          id: "slow-plugin",
+          effect: () =>
+            Effect.gen(function* () {
+              yield* Deferred.succeed(started, undefined)
+              yield* Deferred.await(release)
+              yield* Deferred.succeed(completed, undefined)
+            }).pipe(Effect.onInterrupt(() => Deferred.succeed(interrupted, undefined))),
+        }),
+      )
+      const controller = new AbortController()
+      yield* Effect.addFinalizer(() => Effect.sync(() => controller.abort()))
+      const pending = yield* server
+        .request("POST", "/api/plugin/await-activation", server.first, controller.signal)
+        .pipe(Effect.forkScoped)
+      yield* Deferred.await(started)
+      controller.abort()
+      // HttpEffect resolves a cancelled Web request with 499 rather than rejecting its Promise.
+      expect((yield* Fiber.join(pending)).status).toBe(499)
+      expect(yield* Deferred.isDone(interrupted)).toBe(false)
+      expect(yield* Deferred.isDone(completed)).toBe(false)
+
+      yield* Deferred.succeed(release, undefined)
+      expect((yield* server.request("POST", "/api/plugin/await-activation")).status).toBe(204)
+      expect(yield* Deferred.isDone(completed)).toBe(true)
+      expect(yield* Deferred.isDone(interrupted)).toBe(false)
+      const plugins = yield* server.request("GET", "/api/plugin")
+      expect(plugins.status).toBe(200)
+      expect(yield* Effect.promise(() => plugins.json())).toMatchObject({
+        data: expect.arrayContaining([expect.objectContaining({ id: "slow-plugin", state: { status: "active" } })]),
+      })
+    }).pipe(Effect.timeout("10 seconds")),
+  15_000,
+)
+
+it.live(
+  "settles activation when plugin setup fails and exposes the failure in the inventory",
+  () =>
+    Effect.gen(function* () {
+      const server = yield* fixture(
+        Plugin.define({
+          id: "failing-plugin",
+          effect: () => Effect.die(new Error("fixture setup failed")),
+        }),
+      )
+      expect((yield* server.request("POST", "/api/plugin/await-activation")).status).toBe(204)
+      const plugins = yield* server.request("GET", "/api/plugin")
+      expect(plugins.status).toBe(200)
+      expect(yield* Effect.promise(() => plugins.json())).toMatchObject({
+        location: { directory: server.first },
+        data: expect.arrayContaining([
+          expect.objectContaining({
+            id: "failing-plugin",
+            source: { type: "sdk" },
+            state: { status: "failed", error: expect.stringContaining("fixture setup failed") },
+          }),
+        ]),
+      })
+    }).pipe(Effect.timeout("10 seconds")),
+  15_000,
+)

packages/server/test/provider.test.ts

@@ -1,74 +1,106 @@
-import fs from "node:fs/promises"
-import path from "node:path"
 import { expect } from "bun:test"
-import { Effect, Schedule } from "effect"
-import { tmpdir } from "../../core/test/fixture/tmpdir"
+import { SdkPlugins } from "@opencode-ai/core/plugin/sdk"
+import { Plugin } from "@opencode-ai/plugin/effect"
+import { Context, Deferred, Effect, Fiber, Layer } from "effect"
+import { HttpEffect, HttpRouter, HttpServer } from "effect/unstable/http"
+import { tmpdirScoped } from "../../core/test/fixture/tmpdir"
 import { it } from "../../core/test/lib/effect"
-import { startServer } from "./fixture/server"
+import { createRoutes } from "../src/routes"
 
 it.live(
-  "lists providers without blocking on plugin initialization",
+  "lists and gets providers without blocking on plugin initialization",
   () =>
     Effect.gen(function* () {
-      const fixture = yield* configuredProvider("opencode-provider-list-endpoint-")
-      const url = new URL("/api/provider", fixture.server.base)
-      url.searchParams.set("location[directory]", fixture.path)
-      yield* Effect.promise(async () => {
-        const response = await fetch(url, { headers: fixture.server.headers })
-        if (response.status !== 200) return false
-        const body: unknown = await response.json()
-        return isRecord(body) && Array.isArray(body["data"])
-          ? body["data"].some((provider) => isRecord(provider) && provider["id"] === "custom")
-          : false
-      }).pipe(
-        Effect.filterOrFail((found) => found),
-        Effect.retry(Schedule.spaced("10 millis")),
-        Effect.timeout("2 seconds"),
-      )
-    }),
-  15_000,
-)
-
-it.live(
-  "gets providers without blocking on plugin initialization",
-  () =>
-    Effect.gen(function* () {
-      const fixture = yield* configuredProvider("opencode-provider-get-endpoint-")
-      const url = new URL("/api/provider/custom", fixture.server.base)
-      url.searchParams.set("location[directory]", fixture.path)
-      const body: unknown = yield* Effect.tryPromise({
-        try: async () => {
-          const response = await fetch(url, { headers: fixture.server.headers })
-          if (response.status !== 200) throw new Error(`Provider not ready: ${response.status}`)
-          return response.json()
-        },
-        catch: (cause) => cause,
-      }).pipe(Effect.retry(Schedule.spaced("10 millis")), Effect.timeout("2 seconds"))
-      if (!isRecord(body) || !isRecord(body["data"])) throw new Error("Expected a provider response")
-      expect(body["data"]["id"]).toBe("custom")
-    }),
-  15_000,
-)
-
-const configuredProvider = Effect.fnUntraced(function* (prefix: string) {
-  const tmp = yield* Effect.acquireDisposable(Effect.promise(() => tmpdir(prefix)))
-  yield* Effect.promise(() =>
-    fs.writeFile(
-      path.join(tmp.path, "opencode.json"),
-      JSON.stringify({
-        providers: {
-          custom: {
-            package: "@opencode-ai/ai/providers/openai-compatible",
-            settings: { apiKey: "secret" },
-            models: { chat: {} },
+      const tmp = yield* tmpdirScoped("opencode-provider-endpoints-")
+      const started = yield* Deferred.make<void>()
+      const release = yield* Deferred.make<void>()
+      const context = yield* Layer.build(
+        createRoutes({
+          password: "secret",
+          database: { path: ":memory:" },
+          models: { fetch: false },
+          fs: { filewatcher: false },
+          config: {
+            directory: tmp.path,
+            project: false,
+            content: JSON.stringify({
+              providers: {
+                custom: {
+                  name: "Configured Custom Provider",
+                  package: "@opencode-ai/ai/providers/openai-compatible",
+                  settings: { apiKey: "secret" },
+                  models: { chat: {} },
+                },
+              },
+            }),
           },
-        },
-      }),
-    ),
-  )
-  return { server: yield* startServer(tmp.path), path: tmp.path }
-})
+        }).pipe(Layer.provide(HttpServer.layerServices)),
+      )
+      const sdk = Context.get(context, SdkPlugins.Service)
+      yield* sdk.register(
+        Plugin.define({
+          id: "slow-plugin",
+          effect: () =>
+            Effect.gen(function* () {
+              yield* Deferred.succeed(started, undefined)
+              yield* Deferred.await(release)
+            }),
+        }),
+      )
+      const handler = Context.get(context, HttpRouter.HttpRouter)
+        .asHttpEffect()
+        .pipe(HttpEffect.toWebHandlerWith(context))
+      const request = (method: "GET" | "POST", route: string) =>
+        Effect.promise((signal) => {
+          const url = new URL(route, "http://opencode.local")
+          url.searchParams.set("location[directory]", tmp.path)
+          return handler(
+            new Request(url, {
+              method,
+              headers: { authorization: `Basic ${btoa("opencode:secret")}` },
+              signal,
+            }),
+          )
+        })
+      const pending = yield* request("POST", "/api/plugin/await-activation").pipe(Effect.forkScoped)
+      yield* Deferred.await(started)
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value)
-}
+      // Config providers activate after SDK plugins; reads must return the current snapshot without waiting.
+      const list = yield* request("GET", "/api/provider").pipe(Effect.timeout("2 seconds"))
+      expect(list.status).toBe(200)
+      expect(yield* Effect.promise(() => list.json())).toMatchObject({
+        location: { directory: tmp.path },
+        data: expect.not.arrayContaining([expect.objectContaining({ id: "custom" })]),
+      })
+      const get = yield* request("GET", "/api/provider/custom").pipe(Effect.timeout("2 seconds"))
+      expect(get.status).toBe(404)
+      expect(yield* Effect.promise(() => get.json())).toMatchObject({
+        _tag: "ProviderNotFoundError",
+        providerID: "custom",
+      })
+      expect(pending.pollUnsafe()).toBeUndefined()
+
+      yield* Deferred.succeed(release, undefined)
+      expect((yield* Fiber.join(pending)).status).toBe(204)
+      const provider = {
+        id: "custom",
+        name: "Configured Custom Provider",
+        activation: "enabled",
+        package: "@opencode-ai/ai/providers/openai-compatible",
+        settings: { apiKey: "secret" },
+      }
+      const configuredList = yield* request("GET", "/api/provider").pipe(Effect.timeout("2 seconds"))
+      expect(configuredList.status).toBe(200)
+      expect(yield* Effect.promise(() => configuredList.json())).toMatchObject({
+        location: { directory: tmp.path },
+        data: expect.arrayContaining([expect.objectContaining(provider)]),
+      })
+      const configuredGet = yield* request("GET", "/api/provider/custom").pipe(Effect.timeout("2 seconds"))
+      expect(configuredGet.status).toBe(200)
+      expect(yield* Effect.promise(() => configuredGet.json())).toMatchObject({
+        location: { directory: tmp.path },
+        data: provider,
+      })
+    }),
+  15_000,
+)

packages/tui/src/component/dialog-config.tsx

@@ -55,7 +55,7 @@ export const settings: Setting[] = [
     title: "Terminal",
     category: "Session",
     path: ["session", "terminal"],
-    default: false,
+    default: process.platform !== "win32",
     values: [false, true],
     labels: ["off", "on"],
     keywords: ["pty", "shell", "terminal pane"],

packages/tui/src/config/index.tsx

@@ -265,12 +265,6 @@ export type Resolved = Omit<Info, "attention" | "cursor" | "keybinds" | "leader"
 
 export function resolve(input: Info, options: { terminalSuspend: boolean }): Resolved {
   const keybinds: TuiKeybind.KeybindOverrides = { ...input.keybinds }
-  if (input.session?.terminal) {
-    if (input.keybinds?.["terminal.toggle"] === undefined && input.keybinds?.["theme.switch"] === undefined) {
-      keybinds["terminal.toggle"] = "<leader>t"
-      keybinds["theme.switch"] = "none"
-    }
-  }
   if (!options.terminalSuspend) {
     keybinds["terminal.suspend"] = "none"
     if (keybinds["input.undo"] === undefined) {
@@ -305,6 +299,8 @@ export function resolve(input: Info, options: { terminalSuspend: boolean }): Res
     session: {
       ...input.session,
       new_location: input.session?.new_location ?? "launch",
+      // Persistent terminal panes need the opencode-pty daemon, which does not ship Windows binaries.
+      terminal: input.session?.terminal ?? process.platform !== "win32",
       tps: input.session?.tps ?? true,
     },
     tabs: {

packages/tui/src/config/keybind.ts

@@ -88,14 +88,14 @@ export const Definitions = {
   "diff.help": keybind("?,shift+?,shift+/", "Show more diff viewer shortcuts"),
 
   "prompt.editor": keybind("<leader>e", "Open external editor"),
-  "theme.switch": keybind("<leader>t", "List available themes"),
+  "theme.switch": keybind("none", "List available themes"),
   "theme.switch_mode": keybind("none", "Switch between light and dark theme mode"),
   "theme.mode.lock": keybind("none", "Lock or unlock theme mode"),
   "session.sidebar.toggle": keybind("<leader>b", "Toggle sidebar"),
   "pane.focus.left": keybind("<leader>left", "Focus session pane"),
   "pane.focus.right": keybind("<leader>right", "Focus terminal pane"),
   "terminal.select": keybind("<leader>down", "Select terminal"),
-  "terminal.toggle": keybind("none", "Toggle terminal pane"),
+  "terminal.toggle": keybind("<leader>t", "Toggle terminal pane"),
   "terminal.close": keybind("<leader>up", "Close terminal pane"),
   "session.toggle.scrollbar": keybind("none", "Toggle session scrollbar"),
   "opencode.status": keybind("<leader>s", "View status"),

packages/tui/test/cli/tui/composer-keymap.test.tsx

@@ -93,7 +93,7 @@ async function renderComposer(
   const app = await testRender(
     () => (
       <TestTuiContexts directory={directory}>
-        <ConfigProvider config={createTuiResolvedConfig({ keybinds })}>
+        <ConfigProvider config={createTuiResolvedConfig({ keybinds, session: { terminal: false } })}>
           <Keymap.Provider>
             <ClientProvider api={createApi(calls.fetch)}>
               <DataProvider directory={process.cwd()}>

packages/tui/test/cli/tui/data.test.tsx

@@ -41,7 +41,7 @@ function emitEvent(events: ReturnType<typeof createEventStream>, event: OpenCode
   events.emit({ ...event, location: { directory } })
 }
 
-const config = createTuiResolvedConfig()
+const config = createTuiResolvedConfig({ session: { terminal: false } })
 
 function DataProvider(props: ParentProps) {
   return (

packages/tui/test/config-v2.test.tsx

@@ -106,29 +106,6 @@ test("validates terminal copy behavior", () => {
   expect(setting?.default).toBe(process.platform === "win32" ? "manual" : "select")
 })
 
-test("keeps persistent terminals disabled until explicitly enabled", () => {
-  const disabled = resolve({}, { terminalSuspend: true })
-  expect(disabled.session.terminal ?? false).toBe(false)
-  expect(disabled.keybinds.get("theme.switch")).toMatchObject([{ key: "<leader>t" }])
-  expect(disabled.keybinds.get("terminal.toggle")).toEqual([])
-  expect(settings.find((setting) => setting.path.join(".") === "session.terminal")?.default).toBe(false)
-  expect(settings.filter((setting) => setting.category === "Terminal").map((setting) => setting.title)).toEqual([
-    "Window title",
-    "Copy behavior",
-  ])
-
-  const enabled = resolve({ session: { terminal: true } }, { terminalSuspend: true })
-  expect(enabled.keybinds.get("terminal.toggle")).toMatchObject([{ key: "<leader>t" }])
-  expect(enabled.keybinds.get("theme.switch")).toEqual([])
-
-  const customized = resolve(
-    { session: { terminal: true }, keybinds: { "theme.switch": "<leader>t", "terminal.toggle": "<leader>p" } },
-    { terminalSuspend: true },
-  )
-  expect(customized.keybinds.get("theme.switch")).toMatchObject([{ key: "<leader>t" }])
-  expect(customized.keybinds.get("terminal.toggle")).toMatchObject([{ key: "<leader>p" }])
-})
-
 test("uses command IDs as keybind keys", () => {
   const config = resolve({ keybinds: { "session.list": "ctrl+l" } }, { terminalSuspend: true })
 

packages/tui/test/fixture/tui-client.ts

@@ -145,6 +145,7 @@ export function createFetch(override?: FetchHandler, events?: ReturnType<typeof
     if (url.pathname === "/api/form/request")
       return json({ location: { directory, project: { id: "proj_test", directory: worktree } }, data: [] })
     if (/^\/api\/session\/[^/]+\/form$/.test(url.pathname)) return json({ data: [] })
+    if (/^\/api\/experimental\/session\/[^/]+\/terminal$/.test(url.pathname)) return json({ data: [] })
     if (
       ["/api/agent", "/api/model", "/api/provider", "/api/integration", "/api/command", "/api/skill"].includes(
         url.pathname,

packages/www/openapi.json

@@ -486,6 +486,82 @@
         "summary": "List plugins"
       }
     },
+    "/api/plugin/await-activation": {
+      "post": {
+        "tags": ["plugin"],
+        "operationId": "v2.plugin.awaitActivation",
+        "parameters": [
+          {
+            "name": "location",
+            "in": "query",
+            "schema": {
+              "anyOf": [
+                {
+                  "type": "object",
+                  "properties": {
+                    "directory": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ]
+                    },
+                    "workspace": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ]
+                    }
+                  },
+                  "additionalProperties": false
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "required": false,
+            "style": "deepObject",
+            "explode": true
+          }
+        ],
+        "security": [],
+        "responses": {
+          "204": {
+            "description": "<No Content>"
+          },
+          "400": {
+            "description": "InvalidRequestError",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/InvalidRequestErrorEncoded"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "UnauthorizedError",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/UnauthorizedErrorEncoded"
+                }
+              }
+            }
+          }
+        },
+        "description": "Wait for configured plugin activation at a Location to settle, including missing-package installs. Completion does not imply every plugin succeeded or background resource discovery finished. Cancelling this wait does not cancel activation.",
+        "summary": "Wait for plugin activation"
+      }
+    },
     "/api/plugin/check": {
       "post": {
         "tags": ["plugin"],

packages/www/public/openapi.json

@@ -486,6 +486,82 @@
         "summary": "List plugins"
       }
     },
+    "/api/plugin/await-activation": {
+      "post": {
+        "tags": ["plugin"],
+        "operationId": "v2.plugin.awaitActivation",
+        "parameters": [
+          {
+            "name": "location",
+            "in": "query",
+            "schema": {
+              "anyOf": [
+                {
+                  "type": "object",
+                  "properties": {
+                    "directory": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ]
+                    },
+                    "workspace": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ]
+                    }
+                  },
+                  "additionalProperties": false
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "required": false,
+            "style": "deepObject",
+            "explode": true
+          }
+        ],
+        "security": [],
+        "responses": {
+          "204": {
+            "description": "<No Content>"
+          },
+          "400": {
+            "description": "InvalidRequestError",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/InvalidRequestErrorEncoded"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "UnauthorizedError",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/UnauthorizedErrorEncoded"
+                }
+              }
+            }
+          }
+        },
+        "description": "Wait for configured plugin activation at a Location to settle, including missing-package installs. Completion does not imply every plugin succeeded or background resource discovery finished. Cancelling this wait does not cancel activation.",
+        "summary": "Wait for plugin activation"
+      }
+    },
     "/api/plugin/check": {
       "post": {
         "tags": ["plugin"],

packages/www/src/docs/content/build/plugins/index.mdx

@@ -117,8 +117,11 @@ export default Plugin.define({
 
 ## Transforms
 
-Transforms are a central pattern in the plugin API and modify how OpenCode works. Plugins register
-transforms and each builds on the changes made before it.
+Transforms are synchronous edits to OpenCode's domain state, and each builds on earlier registrations.
+Registry reads such as `ctx.catalog.model.list()` reflect every registration so far, including during plugin setup;
+startup batching only coalesces update notifications and never delays what a read returns. Resource status APIs still
+report the state of running resources: a registered definition does not mean its connection or other resource work has
+completed.
 
 Say we have a plugin that adds one model to the catalog.
 
@@ -134,10 +137,16 @@ export default Plugin.define({
         model.cost = [{ input: 2, output: 12, cache: { read: 0.2, write: 2 } }]
       })
     })
+
+    const models = await ctx.catalog.model.list() // Includes the model registered above.
   },
 })
 ```
 
+Any registration, removal, or `reload()` marks the registry changed; the next read rebuilds it by replaying every
+active transform in registration order onto a fresh value. Keep transforms cheap and repeatable. A value you have
+already read is never modified by later rebuilds.
+
 A later plugin can enforce a maximum output price across every model, including models added by earlier plugins.
 
 ```ts title="plugins/model-budget/index.ts"
@@ -159,8 +168,8 @@ export default Plugin.define({
 })
 ```
 
-Now say the first plugin dynamically fetches can fetch its model list from a
-dynamic source. It can call `reload` when that list changes.
+Captured inputs are not watched automatically. Load external data before the synchronous callback, then call
+`reload()` after those inputs change.
 
 ```ts title="plugins/models/index.ts"
 import { Plugin } from "@opencode-ai/plugin"
@@ -793,9 +802,8 @@ interface StorageScanResult {
 
 ### Tools
 
-Register, update, and remove tools with a transform. The callback is synchronous, including in Promise plugins; load external
-data before registering or reloading. OpenCode replays active transforms in registration order on a fresh draft.
-For the same effective tool name, a later valid registration overrides an earlier one.
+Register, update, and remove tools with a synchronous transform, including in Promise plugins. Load external data
+before registering or reloading. A later valid registration overrides the same effective tool name.
 
 ```ts
 const registration = await ctx.tool.transform((draft) => {
@@ -854,9 +862,10 @@ definition it overrode. Disposal is idempotent, and unloading the plugin also di
 await registration.dispose()
 ```
 
-Each model request captures a tool snapshot. Reload and disposal affect future snapshots, not the definitions or
-executors already captured by an existing request. Executors that close over mutable plugin data still observe
-that data; capture a value inside the transform when it must remain tied to that definition.
+Each model request captures a stable, executable tool snapshot. Later transforms, reloads, and disposal affect future
+snapshots, not the definitions, Code Mode namespace descriptions, or executors already captured. Executors that close
+over mutable plugin data still observe that data; capture a value inside the transform when it must remain tied to
+that definition.
 
 #### Reference