fix(core): attribute deferred skill plugin failures

Co-authored-by: Hona <10430890+Hona@users.noreply.github.com>

.github/workflows/publish.yml

@@ -47,7 +47,7 @@ jobs:
       - uses: ./.github/actions/setup-bun
 
       - name: Deploy update service
-        if: github.ref_name == 'v2' || github.ref_name == 'beta'
+        if: github.ref_name == 'v2'
         working-directory: packages/updates
         run: bun run deploy
         env:

bun.lock

@@ -575,6 +575,7 @@
         "@opencode-ai/client": "workspace:*",
         "@opencode-ai/protocol": "workspace:*",
         "@opencode-ai/schema": "workspace:*",
+        "@opencode-ai/util": "workspace:*",
         "@standard-schema/spec": "catalog:",
         "effect": "catalog:",
         "zod": "catalog:",
@@ -585,6 +586,7 @@
         "@opentui/solid": "catalog:",
         "@tsconfig/bun": "catalog:",
         "@tsconfig/node22": "catalog:",
+        "@types/bun": "catalog:",
         "@types/node": "catalog:",
         "@typescript/native-preview": "catalog:",
         "solid-js": "catalog:",
@@ -971,7 +973,6 @@
         "minimatch": "10.2.5",
         "npm-package-arg": "13.0.2",
         "pacote": "21.5.1",
-        "resolve.exports": "catalog:",
       },
       "devDependencies": {
         "@tsconfig/bun": "catalog:",
@@ -1123,7 +1124,6 @@
     "opentui-spinner": "0.0.7",
     "remeda": "2.26.0",
     "remend": "1.3.1",
-    "resolve.exports": "2.0.3",
     "semver": "7.7.4",
     "shiki": "4.4.3",
     "solid-js": "1.9.15",
@@ -5171,8 +5171,6 @@
 
     "resolve-pkg-maps": ["resolve-pkg-maps@1.0.0", "", {}, "sha512-seS2Tj26TBVOC2NIc2rOe2y2ZO7efxITtLZcGSOnHHNOQ7CkiUBfw0Iw2ck6xkIhPwLhKNLS8BO+hEpngQlqzw=="],
 
-    "resolve.exports": ["resolve.exports@2.0.3", "", {}, "sha512-OcXjMsGdhL4XnbShKpAcSqPMzQoYkYyhbEaeSko47MjRP9NfEQMhZkXL1DoFlt9LWQn4YttrdnV6X2OiyzBi+A=="],
-
     "responselike": ["responselike@2.0.1", "", { "dependencies": { "lowercase-keys": "^2.0.0" } }, "sha512-4gl03wn3hj1HP3yzgdI7d3lCkF95F21Pz4BPGvKHinyQzALR5CapwC8yIi0Rh58DEMQ/SguC03wFj2k0M/mHhw=="],
 
     "restructure": ["restructure@3.0.2", "", {}, "sha512-gSfoiOEA0VPE6Tukkrr7I0RBdE0s7H1eFCDBk05l1KIQT1UIKNc5JZy6jdyW6eYH3aR3g5b3PuL77rq0hvwtAw=="],

nix/hashes.json

@@ -1,8 +1,8 @@
 {
   "nodeModules": {
-    "x86_64-linux": "sha256-Vazzj75ji5YbLtX5X0q+IZvygGrfmEi3+PzJsAkaa3s=",
-    "aarch64-linux": "sha256-QFKzH7wlRcvYG4EHQgQ+++9zNQ+Mw5DVKembGiMjiCg=",
-    "aarch64-darwin": "sha256-WAYBBA2jLW95wM8Dgk77KsO3yS5efxQs9oBVAcdx8Gc=",
-    "x86_64-darwin": "sha256-c9P+VQvfdOu5ef6BnKXb3/IUo8pPFaYQv8B+ijofm1s="
+    "x86_64-linux": "sha256-j3Vtfd5sx+hHnV3qHBq7Ae96E08meNqTqtYN9kWmCqE=",
+    "aarch64-linux": "sha256-LCvHEYoDgvkXtFFs0u7XBEzyo8fGGX25N8iuLrHSu8I=",
+    "aarch64-darwin": "sha256-wBRx1e8x6toEHV1sFMDDs26+s8IHyPAqCg6TcBgsxxA=",
+    "x86_64-darwin": "sha256-ClVls/CTpT76W5SQ/cij2YFmBqv9FGLeVxQh8iStnEk="
   }
 }

package.json

@@ -27,7 +27,6 @@
     "upgrade-opentui": "bun run script/upgrade-opentui.ts",
     "postinstall": "bun run --cwd packages/core fix-node-pty",
     "prepare": "husky",
-    "reserve-packages": "bun script/reserve-package-names.ts",
     "random": "echo 'Random script'",
     "sso": "aws sso login --sso-session=opencode --no-browser",
     "test": "echo 'do not run tests from root' && exit 1"
@@ -93,7 +92,6 @@
       "@typescript/native-preview": "7.0.0-dev.20251207.1",
       "zod": "4.1.8",
       "remeda": "2.26.0",
-      "resolve.exports": "2.0.3",
       "sst": "4.13.1",
       "shiki": "4.4.3",
       "solid-list": "0.3.0",

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({
@@ -281,6 +304,11 @@ const OpenResponsesUsage = Schema.Struct({
 })
 type OpenResponsesUsage = Schema.Schema.Type<typeof OpenResponsesUsage>
 
+// The spec requires `id` on every output item, but some gateways drop it from
+// later item events (Bedrock Mantle renames it to `item_id` on
+// `output_item.done` and `response.completed.output`). Decode it as optional
+// and let `normalize` recover or mint it once before the parser runs.
+// https://www.openresponses.org/specification#extending-items
 export const StreamItem = Schema.StructWithRest(
   Schema.Struct({
     type: Schema.String,
@@ -293,6 +321,7 @@ export const StreamItem = Schema.StructWithRest(
   [Schema.Record(Schema.String, Schema.Unknown)],
 )
 export type StreamItem = Schema.Schema.Type<typeof StreamItem>
+export type OutputItem = StreamItem & { readonly id: string }
 
 // The Responses schema puts streaming error details at the top level and
 // response failures under `response.error`. WebSocket failures use an
@@ -372,6 +401,7 @@ export const Event = Schema.StructWithRest(
   [Schema.Record(Schema.String, Schema.Unknown)],
 )
 export type Event = Schema.Schema.Type<typeof Event>
+export type NormalizedEvent = Event & { readonly item?: OutputItem | null }
 
 export interface ProviderAdapter {
   readonly id: string
@@ -387,18 +417,19 @@ 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
   readonly tools: ToolStream.State<string>
-  // Call ids stay independent of item ids, which may be omitted or reused.
+  // Item ids are response-scoped identities. Keep completed ids tombstoned so
+  // reconnect replay cannot reopen fragments already emitted downstream.
   readonly completedTools: ReadonlySet<string>
   readonly hasFunctionCall: boolean
   readonly lifecycle: Lifecycle.State
   readonly outputItems: Readonly<Record<number, string>>
   readonly message: { readonly id: string; readonly phase: MessagePhase | null | undefined } | undefined
-  // Item ids are response-scoped identities. Keep completed ids tombstoned so
-  // reconnect replay cannot reopen fragments already emitted downstream.
   readonly completedMessages: ReadonlySet<string>
   readonly reasoningItems: Readonly<Record<string, ReasoningStreamItem>>
 }
@@ -491,6 +522,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 +535,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 +610,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 +626,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 +640,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 +654,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 +662,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 +747,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 +798,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 +812,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 +829,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 +845,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,13 +875,12 @@ 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,
 })
 
-const isReasoningItem = (item: StreamItem): item is StreamItem & { type: "reasoning"; id: string } =>
-  item.type === "reasoning" && typeof item.id === "string"
-
 export type StepResult = readonly [ParserState, ReadonlyArray<LLMEvent>]
 
 const NO_EVENTS: StepResult["1"] = []
@@ -862,9 +924,34 @@ const joinReasoningText = (parts: ReadonlyArray<string | undefined>) => {
   return parts.filter((part) => part !== undefined).join("\n\n")
 }
 
-export const outputItemID = (state: ParserState, event: Event) =>
+const outputItemID = (state: ParserState, event: Event) =>
   event.output_index === undefined ? event.item_id : (state.outputItems[event.output_index] ?? event.item_id)
 
+const ITEM_ID_PREFIX: Readonly<Record<string, string>> = {
+  message: "msg",
+  reasoning: "rs",
+  function_call: "fc",
+  compaction: "cmp",
+}
+
+// An item without an id adopts the id already open in its output slot,
+// otherwise it gets a locally minted one.
+const resolveItem = (state: ParserState, item: StreamItem, index: number | undefined): OutputItem => ({
+  ...item,
+  id:
+    item.id ??
+    (index === undefined ? undefined : state.outputItems[index]) ??
+    `${ITEM_ID_PREFIX[item.type] ?? "item"}_${crypto.randomUUID().replaceAll("-", "")}`,
+})
+
+// Registered output slots are authoritative for `item_id` routing, and items
+// are resolved here so everything downstream can rely on `item.id`.
+export const normalize = (state: ParserState, input: Event): NormalizedEvent => ({
+  ...input,
+  item_id: input.item_id === undefined ? undefined : outputItemID(state, input),
+  item: input.item ? resolveItem(state, input.item, input.output_index) : input.item,
+})
+
 const startReasoningSummaryPart = (state: ParserState, itemID: string, index: number): StepResult => {
   const item = state.reasoningItems[itemID]
   if (!item?.open || index === 0 || item.summaryParts[index] !== undefined) return [state, NO_EVENTS]
@@ -938,7 +1025,7 @@ export const onReasoningDone = (state: ParserState, event: Event, itemID: string
   return onReasoningDelta(state, { ...event, delta: event.text }, itemID)
 }
 
-const reasoningMetadata = (state: ParserState, item: StreamItem & { id: string }) =>
+const reasoningMetadata = (state: ParserState, item: OutputItem) =>
   providerMetadata(state, { itemId: item.id, reasoningEncryptedContent: item.encrypted_content ?? null })
 
 // Responses APIs normally stream reasoning items in this order:
@@ -951,18 +1038,18 @@ const reasoningMetadata = (state: ParserState, item: StreamItem & { id: string }
 // `onOutputItemAdded` seeds the per-item entry, while each later part start is
 // also an implicit boundary for the previous part. This keeps the common event
 // lifecycle ordered when a compatible provider omits or delays a part-done event.
-const onOutputItemAdded = (state: ParserState, event: Event): StepResult => {
+const onOutputItemAdded = (state: ParserState, event: NormalizedEvent): StepResult => {
   const item = event.item
-  if (item?.type === "message" && item.id !== undefined) {
-    const itemID = item.id
-    if (state.completedMessages.has(itemID)) return [state, NO_EVENTS]
+  if (!item) return [state, NO_EVENTS]
+  if (item.type === "message") {
+    if (state.completedMessages.has(item.id)) return [state, NO_EVENTS]
     const phase = messagePhase(item.phase)
     const completedMessages = new Set(state.completedMessages)
-    if (state.message !== undefined && state.message.id !== itemID) completedMessages.add(state.message.id)
+    if (state.message !== undefined && state.message.id !== item.id) completedMessages.add(state.message.id)
     // A new message closes earlier messages, including ones that never streamed.
     const events: LLMEvent[] = []
     const lifecycle = [...state.lifecycle.text]
-      .filter((id) => id !== itemID)
+      .filter((id) => id !== item.id)
       .reduce((lifecycle, id) => {
         completedMessages.add(id)
         const openPhase = state.message?.id === id ? state.message.phase : undefined
@@ -979,14 +1066,14 @@ const onOutputItemAdded = (state: ParserState, event: Event): StepResult => {
         lifecycle,
         completedMessages,
         message: {
-          id: itemID,
-          phase: phase === undefined && state.message?.id === itemID ? state.message.phase : phase,
+          id: item.id,
+          phase: phase === undefined && state.message?.id === item.id ? state.message.phase : phase,
         },
       },
       events,
     ]
   }
-  if (item && isReasoningItem(item)) {
+  if (item.type === "reasoning") {
     if (state.reasoningItems[item.id] !== undefined) return [state, NO_EVENTS]
     const events: LLMEvent[] = []
     return [
@@ -1006,18 +1093,16 @@ const onOutputItemAdded = (state: ParserState, event: Event): StepResult => {
       events,
     ]
   }
-  if (item?.type !== "function_call" || !item.call_id) return [state, NO_EVENTS]
-  const id = item.id ?? item.call_id
-  if (Object.values(state.tools).some((tool) => tool?.id === item.call_id) || state.completedTools.has(item.call_id))
-    return [state, NO_EVENTS]
-  const metadata = item.id !== undefined ? providerMetadata(state, { itemId: item.id }) : undefined
+  if (item.type !== "function_call" || !item.call_id) return [state, NO_EVENTS]
+  if (state.tools[item.id] !== undefined || state.completedTools.has(item.id)) return [state, NO_EVENTS]
+  const metadata = providerMetadata(state, { itemId: item.id })
   const events: LLMEvent[] = []
   const lifecycle = Lifecycle.stepStart(state.lifecycle, events)
   return [
     {
       ...state,
       lifecycle,
-      tools: ToolStream.start(state.tools, id, {
+      tools: ToolStream.start(state.tools, item.id, {
         id: item.call_id,
         name: item.name ?? "",
         input: item.arguments ?? "",
@@ -1089,11 +1174,30 @@ const onFunctionCallArgumentsDelta = Effect.fn("OpenResponses.onFunctionCallArgu
 
 const onOutputItemDone = Effect.fn("OpenResponses.onOutputItemDone")(function* (
   state: ParserState,
-  item: Event["item"],
+  item: NormalizedEvent["item"],
 ) {
   if (!item) return [state, NO_EVENTS] satisfies StepResult
 
-  if (item.type === "message" && item.id !== undefined) {
+  if (item.type === "compaction") {
+    if (typeof item.encrypted_content !== "string")
+      return yield* ProviderShared.eventError(state.id, "Compaction output is missing its 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") {
     if (state.completedMessages.has(item.id)) return [state, NO_EVENTS] satisfies StepResult
     const completedMessages = new Set(state.completedMessages)
     completedMessages.add(item.id)
@@ -1126,36 +1230,23 @@ const onOutputItemDone = Effect.fn("OpenResponses.onOutputItemDone")(function* (
 
   if (item.type === "function_call") {
     if (!item.call_id || !item.name) return [state, NO_EVENTS] satisfies StepResult
-    const callID = item.call_id
-    if (state.completedTools.has(callID)) return [state, NO_EVENTS] satisfies StepResult
-    const metadata = item.id !== undefined ? providerMetadata(state, { itemId: item.id }) : undefined
-    const fallback = item.id ?? callID
-    // Match the pending tool by call id so item events that disagree on
-    // whether `item.id` is present still resolve the same call.
-    const registered =
-      state.tools[fallback] !== undefined
-        ? fallback
-        : Object.keys(state.tools).find((key) => state.tools[key]?.id === callID)
-    const id = registered ?? fallback
-    const tools =
-      registered !== undefined
-        ? state.tools
-        : ToolStream.start(state.tools, id, {
-            id: callID,
-            name: item.name,
-            providerMetadata: metadata,
-          })
+    if (state.completedTools.has(item.id)) return [state, NO_EVENTS] satisfies StepResult
+    const metadata = providerMetadata(state, { itemId: item.id })
+    const registered = state.tools[item.id] !== undefined
+    const tools = registered
+      ? state.tools
+      : ToolStream.start(state.tools, item.id, { id: item.call_id, name: item.name, providerMetadata: metadata })
     const result =
       item.arguments === undefined
-        ? yield* ToolStream.finish(state.id, tools, id)
-        : yield* ToolStream.finishWithInput(state.id, tools, id, item.arguments)
+        ? yield* ToolStream.finish(state.id, tools, item.id)
+        : yield* ToolStream.finishWithInput(state.id, tools, item.id, item.arguments)
     const events: LLMEvent[] = []
     const finished = result.events ?? []
     // A done-only call never streamed a start event, so open its lifecycle here.
     const resultEvents =
-      registered !== undefined || finished.length === 0
+      registered || finished.length === 0
         ? finished
-        : [LLMEvent.toolInputStart({ id: callID, name: item.name, providerMetadata: metadata }), ...finished]
+        : [LLMEvent.toolInputStart({ id: item.call_id, name: item.name, providerMetadata: metadata }), ...finished]
     const lifecycle = resultEvents.length ? Lifecycle.stepStart(state.lifecycle, events) : state.lifecycle
     events.push(...resultEvents)
     return [
@@ -1166,13 +1257,13 @@ const onOutputItemDone = Effect.fn("OpenResponses.onOutputItemDone")(function* (
           resultEvents.some((event) => LLMEvent.is.toolCall(event) || LLMEvent.is.toolInputError(event)) ||
           state.hasFunctionCall,
         tools: result.tools,
-        completedTools: new Set([...state.completedTools, callID]),
+        completedTools: new Set([...state.completedTools, item.id]),
       },
       events,
     ] satisfies StepResult
   }
 
-  if (isReasoningItem(item)) {
+  if (item.type === "reasoning") {
     if (state.reasoningItems[item.id]?.open === false) return [state, NO_EVENTS] satisfies StepResult
     const metadata = reasoningMetadata(state, item)
     const summaryParts: ReadonlyArray<unknown> = Array.isArray(item.summary) ? item.summary : []
@@ -1256,30 +1347,35 @@ const onResponseFinish = Effect.fn("OpenResponses.onResponseFinish")(function* (
   let current = state
   const events: LLMEvent[] = []
   if (event.type === "response.completed") {
-    for (const item of event.response?.output ?? []) {
-      if (
-        item.type !== "function_call" ||
-        !item.call_id ||
-        !Object.values(current.tools).some((tool) => tool?.id === item.call_id)
-      )
-        continue
+    // An output item's array position is its output index.
+    for (const item of (event.response?.output ?? []).map((item, index) => resolveItem(state, item, index))) {
+      // Terminal recovery cannot insert a checkpoint before already-emitted content.
+      if (item.type === "compaction" && state.lifecycle.stepStarted && !state.completedCompactions.has(item.id))
+        return yield* ProviderShared.eventError(
+          state.id,
+          "Cannot recover a compaction checkpoint after output has been emitted",
+        )
+      const recoverable =
+        item.type === "compaction" || (item.type === "function_call" && current.tools[item.id] !== undefined)
+      if (!recoverable) 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 +1387,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.
@@ -1328,12 +1424,9 @@ export const providerFailure = (event: Event, fallback: string, body = ProviderS
   return new AIError({ reason })
 }
 
-export const step = (state: ParserState, input: Event) => {
-  // The OpenAPI requires string IDs but imposes no minLength; empty is not missing.
-  const event =
-    input.item_id !== undefined && outputItemID(state, input) !== input.item_id
-      ? { ...input, item_id: outputItemID(state, input) }
-      : input
+// Callers must pass events through `normalize` first. The OpenAPI requires
+// string IDs but imposes no minLength; empty is not missing.
+export const step = (state: ParserState, event: NormalizedEvent) => {
   if (event.type === "response.output_text.delta" || event.type === "response.output_text.done") {
     if (event.item_id === undefined) return ProviderShared.eventError(state.id, `${event.type} is missing item_id`)
     return Effect.succeed(
@@ -1373,20 +1466,16 @@ export const step = (state: ParserState, input: Event) => {
       ? Effect.succeed(onReasoningSummaryPartDone(state, event))
       : ProviderShared.eventError(state.id, `${event.type} is missing item_id`)
   if (event.type === "response.output_item.added") {
-    if (event.item?.type === "message" && event.item.id === undefined)
-      return ProviderShared.eventError(state.id, `${event.type} message is missing id`)
     if (
-      event.item &&
-      isReasoningItem(event.item) &&
+      event.item?.type === "reasoning" &&
       state.reasoningItems[event.item.id] === undefined &&
       state.lifecycle.reasoning.size > 0
     )
       return ProviderShared.eventError(state.id, `${event.type} started reasoning before the previous item ended`)
-    const id = event.item?.id ?? (event.item?.type === "function_call" ? event.item.call_id : undefined)
     return Effect.succeed(
       onOutputItemAdded(
-        event.output_index !== undefined && id !== undefined
-          ? { ...state, outputItems: { ...state.outputItems, [event.output_index]: id } }
+        event.output_index !== undefined && event.item
+          ? { ...state, outputItems: { ...state.outputItems, [event.output_index]: event.item.id } }
           : state,
         event,
       ),
@@ -1396,11 +1485,7 @@ export const step = (state: ParserState, input: Event) => {
     return event.item_id !== undefined
       ? onFunctionCallArgumentsDelta(state, event)
       : ProviderShared.eventError(state.id, `${event.type} is missing item_id`)
-  if (event.type === "response.output_item.done") {
-    if (event.item?.type === "message" && event.item.id === undefined)
-      return ProviderShared.eventError(state.id, `${event.type} message is missing id`)
-    return onOutputItemDone(state, event.item)
-  }
+  if (event.type === "response.output_item.done") return onOutputItemDone(state, event.item)
   if (event.type === "response.completed" || event.type === "response.incomplete") return onResponseFinish(state, event)
   if (event.type === "response.failed") return providerFailure(event, `${state.name} response failed`)
   if (event.type === "error")
@@ -1426,9 +1511,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>(),
@@ -1448,7 +1535,7 @@ export const protocol = Protocol.make({
   stream: {
     event: Protocol.jsonEvent(Event),
     initial,
-    step,
+    step: (state: ParserState, event: Event) => step(state, normalize(state, event)),
     terminal,
   },
 })

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),
   })
 })
 
@@ -184,12 +201,11 @@ const HOSTED_TOOLS = {
   },
 } as const satisfies ResponsesHostedTools.Definitions
 
-const step = (state: OpenResponses.ParserState, event: OpenResponses.Event) => {
+const step = (state: OpenResponses.ParserState, input: OpenResponses.Event) => {
+  const event = OpenResponses.normalize(state, input)
   if (event.type === "response.reasoning_text.delta")
     return event.item_id !== undefined
-      ? Effect.succeed(
-          OpenResponses.onReasoningDelta(state, event, OpenResponses.outputItemID(state, event) ?? event.item_id),
-        )
+      ? Effect.succeed(OpenResponses.onReasoningDelta(state, event, event.item_id))
       : ProviderShared.eventError(ADAPTER, `${event.type} is missing item_id`)
   if (event.type === "response.output_item.done" && event.item && ResponsesHostedTools.isItem(event.item, HOSTED_TOOLS))
     return ResponsesHostedTools.onDone(state, event.item, HOSTED_TOOLS)
@@ -223,6 +239,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/utils/responses-hosted-tools.ts

@@ -3,8 +3,7 @@ import { LLMEvent, type AIError, type ToolResultPart } from "../../schema/index.
 import { OpenResponses } from "../open-responses.js"
 import { Lifecycle } from "./lifecycle.js"
 
-export type Item = OpenResponses.StreamItem & {
-  readonly id: string
+export type Item = OpenResponses.OutputItem & {
   readonly status?: string
   readonly action?: unknown
   readonly queries?: unknown
@@ -27,8 +26,8 @@ export interface Definition {
 
 export type Definitions = Readonly<Record<string, Definition>>
 
-export const isItem = <Tools extends Definitions>(item: OpenResponses.StreamItem, tools: Tools): item is Item =>
-  item.type in tools && typeof item.id === "string" && item.id.length > 0
+export const isItem = <Tools extends Definitions>(item: OpenResponses.OutputItem, tools: Tools): item is Item =>
+  item.type in tools
 
 export const onDone: (
   state: OpenResponses.ParserState,

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))
 })
 
@@ -64,7 +69,8 @@ const HOSTED_TOOLS = {
 
 // Grok speaks the standard Responses reasoning dialect (`reasoning_summary_text.*`,
 // handled by the baseline); only its hosted tool vocabulary differs.
-const step = (state: OpenResponses.ParserState, event: OpenResponses.Event) => {
+const step = (state: OpenResponses.ParserState, input: OpenResponses.Event) => {
+  const event = OpenResponses.normalize(state, input)
   if (event.type === "response.output_item.done" && event.item && ResponsesHostedTools.isItem(event.item, HOSTED_TOOLS))
     return ResponsesHostedTools.onDone(state, event.item, HOSTED_TOOLS)
   return OpenResponses.step(state, event)
@@ -84,4 +90,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,139 @@
+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("mints an id for terminal checkpoints that omit one", () =>
+  Effect.gen(function* () {
+    const response = yield* LLMClient.generate(
+      LLM.request({ model: OpenAI.configure({ apiKey: "test" }).responses("fixture"), prompt: "hello" }),
+    )
+    const part = response.message.content[0]
+    expect(part?.type).toBe("compaction")
+    if (part?.type !== "compaction") return
+    expect(part.id).toMatch(/^cmp_[0-9a-f]{32}$/)
+    expect(part.encrypted).toBe("opaque")
+  }),
+)

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/provider/open-responses-lifecycle.test.ts

@@ -329,69 +329,126 @@ describe("Open Responses basic-item lifecycles", () => {
       ])
     }),
   )
-  ;[undefined, "fc_1"].forEach((id) => {
-    it.effect(`opens and closes a done-only tool ${id === undefined ? "without" : "with"} an item id`, () =>
-      Effect.gen(function* () {
-        const item = {
-          type: "function_call",
-          ...(id === undefined ? {} : { id }),
-          call_id: "call_1",
-          name: "lookup",
-          arguments: '{"query":"weather"}',
-        }
-        const events = yield* collect(
-          { type: "response.output_item.done", item },
-          { type: "response.output_item.done", item: { ...item, id: "fc_1" } },
-          { type: "response.output_item.added", item },
-          completed,
-        )
-        const providerMetadata = id === undefined ? undefined : { "openai-compatible": { itemId: id } }
-        expect(events.filter((event) => event.type.startsWith("tool-"))).toEqual([
-          { type: "tool-input-start", id: "call_1", name: "lookup", providerMetadata },
-          { type: "tool-input-end", id: "call_1", name: "lookup", providerMetadata },
-          { type: "tool-call", id: "call_1", name: "lookup", input: { query: "weather" }, providerMetadata },
-        ])
-        expect(events.filter(LLMEvent.is.finish)).toEqual([
-          {
-            type: "finish",
-            reason: { normalized: "tool-calls", raw: undefined },
-            providerMetadata: { "openai-compatible": { responseId: "resp_1", serviceTier: undefined } },
+  // Captured from Bedrock Mantle (openai.gpt-oss-120b): the terminal function_call
+  // items rename `id` to `item_id` and carry a stray `output_index`.
+  it.effect("recovers a terminal function_call id from its output slot", () =>
+    Effect.gen(function* () {
+      const terminal = {
+        type: "function_call",
+        item_id: "fc_828bee50dee1d029",
+        call_id: "call_bc1eb4b42e70ee53",
+        name: "get_weather",
+        arguments: '{\n  "city": "Paris"\n}',
+        output_index: 1,
+        status: "completed",
+      }
+      const events = yield* collect(
+        {
+          type: "response.output_item.added",
+          output_index: 0,
+          item: { type: "reasoning", id: "msg_879a68b589198b4c" },
+        },
+        { type: "response.output_item.done", output_index: 0, item: { type: "reasoning", id: "msg_879a68b589198b4c" } },
+        {
+          type: "response.output_item.added",
+          output_index: 1,
+          item: {
+            type: "function_call",
+            id: "fc_828bee50dee1d029",
+            call_id: "call_bc1eb4b42e70ee53",
+            name: "get_weather",
+            arguments: "",
+            status: "in_progress",
           },
-        ])
-      }),
-    )
+        },
+        {
+          type: "response.function_call_arguments.delta",
+          output_index: 1,
+          item_id: "fc_828bee50dee1d029",
+          delta: '{\n  "city": "Paris"\n}',
+        },
+        {
+          type: "response.function_call_arguments.done",
+          output_index: 1,
+          item_id: "fc_828bee50dee1d029",
+          arguments: '{\n  "city": "Paris"\n}',
+        },
+        { type: "response.output_item.done", output_index: 1, item: terminal },
+        {
+          type: "response.completed",
+          response: { id: "resp_1", output: [{ type: "reasoning", id: "msg_879a68b589198b4c" }, terminal] },
+        },
+      )
+      const providerMetadata = { "openai-compatible": { itemId: "fc_828bee50dee1d029" } }
+      expect(events.filter((event) => event.type.startsWith("tool-"))).toEqual([
+        { type: "tool-input-start", id: "call_bc1eb4b42e70ee53", name: "get_weather", providerMetadata },
+        {
+          type: "tool-input-delta",
+          id: "call_bc1eb4b42e70ee53",
+          name: "get_weather",
+          text: '{\n  "city": "Paris"\n}',
+          input: { city: "Paris" },
+        },
+        { type: "tool-input-end", id: "call_bc1eb4b42e70ee53", name: "get_weather", providerMetadata },
+        {
+          type: "tool-call",
+          id: "call_bc1eb4b42e70ee53",
+          name: "get_weather",
+          input: { city: "Paris" },
+          providerMetadata,
+        },
+      ])
+    }),
+  )
 
-    it.effect(`deduplicates a pending call whose item id is ${id === undefined ? "introduced" : "omitted"} later`, () =>
-      Effect.gen(function* () {
-        const item = { type: "function_call", call_id: "call_1", name: "lookup" }
-        const first = { ...item, ...(id === undefined ? {} : { id }) }
-        const duplicate = { ...item, ...(id === undefined ? { id: "fc_1" } : {}) }
-        const events = yield* collect(
-          { type: "response.output_item.added", item: first },
-          { type: "response.function_call_arguments.delta", item_id: id ?? "call_1", delta: '{"query":"weather"}' },
-          { type: "response.output_item.added", item: duplicate },
-          { type: "response.output_item.done", item: duplicate },
-          { type: "response.output_item.done", item: first },
-          { type: "response.output_item.added", item: duplicate },
-          completed,
-        )
-        // Identity metadata comes from the first admission, not the duplicate.
-        const providerMetadata = id === undefined ? undefined : { "openai-compatible": { itemId: id } }
-        expect(events.filter((event) => event.type.startsWith("tool-"))).toEqual([
-          { type: "tool-input-start", id: "call_1", name: "lookup", providerMetadata },
-          {
-            type: "tool-input-delta",
-            id: "call_1",
-            name: "lookup",
-            text: '{"query":"weather"}',
-            input: { query: "weather" },
-          },
-          { type: "tool-input-end", id: "call_1", name: "lookup", providerMetadata },
-          { type: "tool-call", id: "call_1", name: "lookup", input: { query: "weather" }, providerMetadata },
-        ])
-      }),
-    )
-  })
+  it.effect("mints an id for a done-only tool that never had one", () =>
+    Effect.gen(function* () {
+      const events = yield* collect(
+        {
+          type: "response.output_item.done",
+          output_index: 0,
+          item: { type: "function_call", call_id: "call_1", name: "lookup", arguments: '{"query":"weather"}' },
+        },
+        completed,
+      )
+      const call = events.find(LLMEvent.is.toolCall)
+      expect(call).toMatchObject({ id: "call_1", name: "lookup", input: { query: "weather" } })
+      expect(call?.providerMetadata?.["openai-compatible"]).toMatchObject({
+        itemId: expect.stringMatching(/^fc_[0-9a-f]{32}$/),
+      })
+    }),
+  )
+
+  it.effect("opens and closes a done-only tool once", () =>
+    Effect.gen(function* () {
+      const item = {
+        type: "function_call",
+        id: "fc_1",
+        call_id: "call_1",
+        name: "lookup",
+        arguments: '{"query":"weather"}',
+      }
+      const events = yield* collect(
+        { type: "response.output_item.done", item },
+        { type: "response.output_item.done", item },
+        { type: "response.output_item.added", item },
+        completed,
+      )
+      const providerMetadata = { "openai-compatible": { itemId: "fc_1" } }
+      expect(events.filter((event) => event.type.startsWith("tool-"))).toEqual([
+        { type: "tool-input-start", id: "call_1", name: "lookup", providerMetadata },
+        { type: "tool-input-end", id: "call_1", name: "lookup", providerMetadata },
+        { type: "tool-call", id: "call_1", name: "lookup", input: { query: "weather" }, providerMetadata },
+      ])
+      expect(events.filter(LLMEvent.is.finish)).toEqual([
+        {
+          type: "finish",
+          reason: { normalized: "tool-calls", raw: undefined },
+          providerMetadata: { "openai-compatible": { responseId: "resp_1", serviceTier: undefined } },
+        },
+      ])
+    }),
+  )
 
   it.effect("recovers pending calls without reconciling terminal reasoning", () =>
     Effect.gen(function* () {
@@ -436,21 +493,6 @@ describe("Open Responses basic-item lifecycles", () => {
     }),
   )
 
-  it.effect("preserves call identity and pending order when an item id is reused", () =>
-    Effect.gen(function* () {
-      const first = { type: "function_call", id: "fc_1", call_id: "call_1", name: "lookup", arguments: "{}" }
-      const events = yield* collect(
-        { type: "response.output_item.added", item: first },
-        { type: "response.output_item.added", item: { ...first, id: "fc_2", call_id: "call_2" } },
-        { type: "response.output_item.done", item: first },
-        { type: "response.output_item.added", item: { ...first, call_id: "call_3" } },
-        { type: "response.output_item.done", item: first },
-        completed,
-      )
-      expect(events.filter(LLMEvent.is.toolCall).map((event) => event.id)).toEqual(["call_1", "call_2", "call_3"])
-    }),
-  )
-
   it.effect("keeps text and reasoning identities separate even with empty item ids", () =>
     Effect.gen(function* () {
       const events = yield* collect(
@@ -500,14 +542,15 @@ describe("Open Responses basic-item lifecycles", () => {
         { type: "response.output_text.delta", item_id: "msg_1", delta: "Answer" },
         {
           type: "response.output_item.added",
-          item: { type: "function_call", call_id: "call_1", name: "lookup", arguments: "{}" },
+          item: { type: "function_call", id: "fc_1", call_id: "call_1", name: "lookup", arguments: "{}" },
         },
         completed,
       )
       // Generic terminal closure does not repeat the message's phase metadata.
+      const providerMetadata = { "openai-compatible": { itemId: "fc_1" } }
       expect(events.slice(4, -2)).toEqual([
-        { type: "tool-input-end", id: "call_1", name: "lookup" },
-        { type: "tool-call", id: "call_1", name: "lookup", input: {} },
+        { type: "tool-input-end", id: "call_1", name: "lookup", providerMetadata },
+        { type: "tool-call", id: "call_1", name: "lookup", input: {}, providerMetadata },
         { type: "text-end", id: "msg_1" },
       ])
     }),

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

@@ -586,23 +586,21 @@ describe("Open Responses-compatible route", () => {
       Effect.gen(function* () {
         yield* Effect.forEach(["response.output_item.added", "response.output_item.done"], (type) =>
           Effect.forEach(fixtures, (fixture) =>
-            Effect.forEach(
-              fixture.item.type === "message" ? [undefined, null, 0, false, {}, []] : [null, 0, false, {}, []],
-              (id) =>
-                Effect.gen(function* () {
-                  const error = yield* LLMClient.generate(request).pipe(
-                    Effect.provide(
-                      fixedResponse(
-                        sseEvents(
-                          { type, item: { ...fixture.item, id } },
-                          { type: "response.completed", response: { id: "resp_1" } },
-                        ),
+            Effect.forEach([null, 0, false, {}, []], (id) =>
+              Effect.gen(function* () {
+                const error = yield* LLMClient.generate(request).pipe(
+                  Effect.provide(
+                    fixedResponse(
+                      sseEvents(
+                        { type, item: { ...fixture.item, id } },
+                        { type: "response.completed", response: { id: "resp_1" } },
                       ),
                     ),
-                    Effect.flip,
-                  )
-                  expect(error.reason._tag).toBe("InvalidProviderOutput")
-                }),
+                  ),
+                  Effect.flip,
+                )
+                expect(error.reason._tag).toBe("InvalidProviderOutput")
+              }),
             ),
           ),
         )
@@ -610,43 +608,6 @@ describe("Open Responses-compatible route", () => {
     )
   })
 
-  it.effect("streams function calls without optional item ids through the shared baseline", () =>
-    Effect.gen(function* () {
-      const model = configure({
-        apiKey: "test-key",
-        baseURL: "https://responses.example.test/v1",
-        provider: "example",
-      }).model("example-model")
-      const item = { type: "function_call", call_id: "call_1", name: "lookup", arguments: "" }
-      const response = yield* LLMClient.generate(LLM.request({ model, prompt: "Look it up." })).pipe(
-        Effect.provide(
-          fixedResponse(
-            sseEvents(
-              { type: "response.output_item.added", output_index: 1, item },
-              {
-                type: "response.function_call_arguments.delta",
-                output_index: 1,
-                item_id: "opaque_item",
-                delta: '{"query":"shared"}',
-              },
-              {
-                type: "response.output_item.done",
-                output_index: 1,
-                item: { ...item, arguments: '{"query":"complete"}' },
-              },
-              { type: "response.completed", response: { id: "resp_1" } },
-            ),
-          ),
-        ),
-      )
-
-      expect(response.events.filter(LLMEvent.is.toolCall)).toEqual([
-        expect.objectContaining({ id: "call_1", name: "lookup", input: { query: "complete" } }),
-      ])
-      expect(response.events.find(LLMEvent.is.toolCall)?.providerMetadata).toBeUndefined()
-    }),
-  )
-
   it.effect("finalizes pending function calls from completed response output", () =>
     Effect.gen(function* () {
       const model = configure({

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

@@ -469,7 +469,7 @@ describe("OpenAI Responses route", () => {
     }),
   )
 
-  it.effect("continues an item-id-less tool call with only the new tool output", () =>
+  it.effect("continues a streamed tool call with only the new tool output", () =>
     Effect.gen(function* () {
       const firstRequest = {
         type: "response.create",
@@ -485,6 +485,7 @@ describe("OpenAI Responses route", () => {
           type: "response.output_item.done",
           item: {
             type: "function_call",
+            id: "fc_1",
             status: "completed",
             call_id: "call_1",
             name: "weather",
@@ -2129,47 +2130,6 @@ describe("OpenAI Responses route", () => {
     }),
   )
 
-  it.effect("routes item-id-less function arguments by output index and prefers item completion", () =>
-    Effect.gen(function* () {
-      const item = { type: "function_call", call_id: "call_1", name: "lookup", arguments: "" }
-      const response = yield* LLMClient.generate(request).pipe(
-        Effect.provide(
-          fixedResponse(
-            sseEvents(
-              { type: "response.output_item.added", output_index: 2, item },
-              {
-                type: "response.function_call_arguments.delta",
-                output_index: 2,
-                item_id: "opaque_delta",
-                delta: '{"query":"streamed"}',
-              },
-              {
-                type: "response.function_call_arguments.done",
-                output_index: 2,
-                item_id: "opaque_done",
-                arguments: '{"query":"arguments-done"}',
-              },
-              {
-                type: "response.output_item.done",
-                output_index: 2,
-                item: { ...item, arguments: '{"query":"output-item-done"}' },
-              },
-              { type: "response.completed", response: { id: "resp_1" } },
-            ),
-          ),
-        ),
-      )
-
-      expect(response.events.filter((event) => event.type === "tool-input-delta")).toMatchObject([
-        { id: "call_1", text: '{"query":"streamed"}' },
-      ])
-      expect(response.events.filter(LLMEvent.is.toolCall)).toEqual([
-        expect.objectContaining({ id: "call_1", name: "lookup", input: { query: "output-item-done" } }),
-      ])
-      expect(response.events.find(LLMEvent.is.toolCall)?.providerMetadata).toBeUndefined()
-    }),
-  )
-
   it.effect("routes reasoning summary events by output index", () =>
     Effect.gen(function* () {
       const response = yield* LLMClient.generate(request).pipe(
@@ -2389,7 +2349,7 @@ describe("OpenAI Responses route", () => {
                 {
                   type: "response.output_item.added",
                   output_index: 0,
-                  item: { type: "function_call", call_id: "call_1", name: "lookup", arguments: "" },
+                  item: { type: "function_call", id: "fc_1", call_id: "call_1", name: "lookup", arguments: "" },
                 },
                 event,
                 { type: "response.completed", response: { id: "resp_1" } },
@@ -2931,14 +2891,10 @@ describe("OpenAI Responses route", () => {
                   arguments: '{"query":"weather"}',
                 },
               },
-              // Duplicates that drop the item id still resolve the same call.
-              {
-                type: "response.output_item.done",
-                item: { type: "function_call", call_id: "call_1", name: "lookup", arguments: '{"query":"weather"}' },
-              },
+              // A completed item that is re-added stays closed.
               {
                 type: "response.output_item.added",
-                item: { type: "function_call", call_id: "call_1", name: "lookup", arguments: "" },
+                item: { type: "function_call", id: "fc_1", call_id: "call_1", name: "lookup", arguments: "" },
               },
               { type: "response.completed", response: { id: "resp_1" } },
             ),
@@ -3793,43 +3749,6 @@ describe("OpenAI Responses route", () => {
     }),
   )
 
-  it.effect("finalizes and replays a completed function call without an optional item id", () =>
-    Effect.gen(function* () {
-      const response = yield* LLMClient.generate(request).pipe(
-        Effect.provide(
-          fixedResponse(
-            sseEvents(
-              {
-                type: "response.output_item.done",
-                item: { type: "function_call", call_id: "call_1", name: "lookup", arguments: '{"query":"weather"}' },
-              },
-              { type: "response.completed", response: { id: "resp_1" } },
-            ),
-          ),
-        ),
-      )
-
-      expect(response.events.filter(LLMEvent.is.toolCall)).toEqual([
-        expect.objectContaining({ id: "call_1", name: "lookup", input: { query: "weather" } }),
-      ])
-      expect(response.events.find(LLMEvent.is.toolCall)?.providerMetadata).toBeUndefined()
-
-      const prepared = yield* compileRequest(
-        LLM.request({
-          model,
-          messages: [
-            response.message,
-            Message.tool({ id: "call_1", name: "lookup", resultType: "json", result: { forecast: "sunny" } }),
-          ],
-        }),
-      )
-      expect(prepared.body.input).toEqual([
-        { type: "function_call", call_id: "call_1", name: "lookup", arguments: '{"query":"weather"}' },
-        { type: "function_call_output", call_id: "call_1", output: '{"forecast":"sunny"}' },
-      ])
-    }),
-  )
-
   it.effect("emits only missing function arguments from the arguments done event", () =>
     Effect.gen(function* () {
       const body = sseEvents(
@@ -4017,7 +3936,7 @@ describe("OpenAI Responses route", () => {
     }),
   )
 
-  it.effect("uses completed response output when item completion and its terminal item id are missing", () =>
+  it.effect("uses completed response output when output item completion is missing", () =>
     Effect.gen(function* () {
       const body = sseEvents(
         {
@@ -4032,6 +3951,7 @@ describe("OpenAI Responses route", () => {
             output: [
               {
                 type: "function_call",
+                id: "fc_item_1",
                 call_id: "call_1",
                 name: "lookup",
                 arguments: '{"query":"weather"}',
@@ -4053,37 +3973,6 @@ describe("OpenAI Responses route", () => {
     }),
   )
 
-  it.effect("reconciles an item-id-less pending function call from completed response output", () =>
-    Effect.gen(function* () {
-      const item = { type: "function_call", call_id: "call_1", name: "lookup", arguments: "" }
-      const response = yield* LLMClient.generate(request).pipe(
-        Effect.provide(
-          fixedResponse(
-            sseEvents(
-              { type: "response.output_item.added", output_index: 0, item },
-              {
-                type: "response.function_call_arguments.delta",
-                output_index: 0,
-                item_id: "opaque_delta",
-                delta: '{"query":"partial',
-              },
-              {
-                type: "response.completed",
-                response: { id: "resp_1", output: [{ ...item, arguments: '{"query":"complete"}' }] },
-              },
-            ),
-          ),
-        ),
-      )
-
-      expect(response.events.filter(LLMEvent.is.toolCall)).toEqual([
-        expect.objectContaining({ id: "call_1", name: "lookup", input: { query: "complete" } }),
-      ])
-      expect(response.events.find(LLMEvent.is.toolCall)?.providerMetadata).toBeUndefined()
-      expect(response.events.filter(LLMEvent.is.toolInputEnd)).toHaveLength(1)
-    }),
-  )
-
   it.effect("lets completed response output override arguments done", () =>
     Effect.gen(function* () {
       const body = sseEvents(

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/app/e2e/regression/tab-navigate-mousedown.spec.ts

@@ -9,30 +9,42 @@ const sessionB = session("ses_tab_b", "Tab B session")
 const sessionC = session("ses_tab_c", "Tab C session")
 const unresolvedSessionID = "ses_tab_unresolved"
 
-test("new session tab hugs its content", async ({ page }) => {
+test("new session tab matches neighboring session widths", async ({ page }, testInfo) => {
   await mockServer(page)
   await page.addInitScript(
-    ({ server, sessionID, directory }) => {
+    ({ server, sessionA, sessionB, directory }) => {
       localStorage.setItem(
         "opencode.window.browser.dat:tabs",
         JSON.stringify([
-          { type: "session", server, sessionId: sessionID },
+          { type: "session", server, sessionId: sessionA },
           { type: "draft", server, directory, draftID: "draft_tab_width" },
+          { type: "session", server, sessionId: sessionB },
         ]),
       )
     },
-    { server, sessionID: sessionA.id, directory: sessionA.directory },
+    { server, sessionA: sessionA.id, sessionB: sessionB.id, directory: sessionA.directory },
   )
 
   const href = `/server/${base64Encode(server)}/session/${sessionA.id}`
   await page.goto(href)
 
-  const sessionTab = page.locator(`[data-titlebar-tab-slot]:has(a[href="${href}"])`)
-  const draftTab = page.locator('[data-titlebar-tab-slot]:has(a[href^="/new-session?draftId="])')
-  await expect(draftTab).toContainText("New session")
-  const width = (await draftTab.boundingBox())?.width ?? 0
-  expect(width).toBeGreaterThan(100)
-  expect(width).toBeLessThan((await sessionTab.boundingBox())?.width ?? 0)
+  const tabs = page.locator("[data-titlebar-tab-slot]")
+  await expect(tabs.locator("[data-titlebar-tab-title]")).toHaveText([sessionA.title, "New session", sessionB.title])
+  await testInfo.attach("new-session-between-tabs", {
+    body: await page.locator('[data-slot="titlebar-v2"]').screenshot(),
+    contentType: "image/png",
+  })
+  for (const width of [1280, 800]) {
+    await page.setViewportSize({ width, height: 720 })
+    await expect
+      .poll(() =>
+        tabs.evaluateAll((tabs) => {
+          const widths = tabs.map((tab) => tab.getBoundingClientRect().width)
+          return Math.max(...widths) - Math.min(...widths)
+        }),
+      )
+      .toBeLessThan(1)
+  }
 })
 
 test("pressing mouse down on a tab navigates before mouse up", async ({ page }) => {
@@ -280,9 +292,7 @@ test("appearance experimental settings control vertical tab details", async ({ p
   await page.reload()
   const href = `/server/${base64Encode(server)}/session/${sessionA.id}`
   await page.getByRole("button", { name: "Tabs", exact: true }).click()
-  await expect(page.locator('[data-slot="mobile-tabs-drawer"] [data-slot="tab-project"]')).toHaveText([
-    "tab-project",
-  ])
+  await expect(page.locator('[data-slot="mobile-tabs-drawer"] [data-slot="tab-project"]')).toHaveText(["tab-project"])
   await expect(
     page
       .locator('[data-slot="mobile-tabs-drawer"]')

packages/app/src/runtime/server/global-sync/utils.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test"
-import type { AgentListOutput, ModelListOutput, ProviderListOutput } from "@opencode-ai/client/promise"
-import { directoryKey, normalizeAgentList, normalizeProviderList } from "./utils"
+import type { AgentListOutput, ModelListOutput, Project, ProviderListOutput } from "@opencode-ai/client/promise"
+import { directoryKey, normalizeAgentList, normalizeProjectInfo, normalizeProviderList } from "./utils"
 
 describe("normalizeAgentList", () => {
   test("adapts current agents to the app agent shape", () => {
@@ -85,6 +85,15 @@ describe("normalizeProviderList", () => {
   })
 })
 
+describe("normalizeProjectInfo", () => {
+  test("keeps the project VCS backend", () => {
+    const project = { id: "prj", canonical: "/repo", time: { created: 1, updated: 1 }, sandboxes: [] }
+    expect(normalizeProjectInfo({ ...project, vcs: "git" } as Project).vcs).toBe("git")
+    expect(normalizeProjectInfo({ ...project, vcs: "hg" } as Project).vcs).toBe("hg")
+    expect(normalizeProjectInfo(project as Project).vcs).toBeUndefined()
+  })
+})
+
 describe("directoryKey", () => {
   test("normalizes slashes", () => {
     expect(String(directoryKey("C:\\Repos\\sst\\opencode"))).toBe("C:/Repos/sst/opencode")

packages/app/src/runtime/server/global-sync/utils.ts

@@ -135,6 +135,5 @@ export function normalizeProjectInfo(project: Project | CurrentProject): Project
     ...project,
     worktree,
     worktrees: "worktrees" in project ? project.worktrees : [{ directory: worktree }],
-    vcs: project.vcs === "git" ? "git" : undefined,
   }
 }

packages/app/src/runtime/server/sync.tsx

@@ -230,8 +230,6 @@ export function createServerSyncContextInner(serverSDK: ServerSDK, data: Data) {
     children.mark(key)
     if (event.type === "config.updated" || event.type === "agent.updated") queue.push(key)
     if (event.type === "worktree.updated") void bootstrap.refetch()
-    if (event.type === "reference.updated" && children.active(key))
-      void data.location.reference.sync({ directory: key }).catch(() => undefined)
   })
 
   onCleanup(unsub)

packages/app/src/session/review/model.ts

@@ -55,9 +55,9 @@ export function createSessionReview(input: {
   const options = createMemo<ChangeMode[]>(() => {
     const list: ChangeMode[] = []
     const project = input.session.project()
-    if (project?.vcs === "git") list.push("git")
+    if (project?.vcs) list.push("git")
     if (
-      project?.vcs === "git" &&
+      project?.vcs &&
       vcs()?.branch.current &&
       vcs()?.branch.default &&
       vcs()?.branch.current !== vcs()?.branch.default
@@ -94,7 +94,7 @@ export function createSessionReview(input: {
     const value = vcsMode()
     return {
       queryKey: [...vcsKey(), value] as const,
-      enabled: server.connection.status() === "connected" && wantsReview() && input.session.project()?.vcs === "git",
+      enabled: server.connection.status() === "connected" && wantsReview() && !!input.session.project()?.vcs,
       refetchOnMount: "always" as const,
       refetchOnWindowFocus: true,
       queryFn: value
@@ -110,7 +110,7 @@ export function createSessionReview(input: {
   })
   const detailsQuery = createQuery(() => ({
     queryKey: [server.scope, "session-details", input.session.workspace.directory()] as const,
-    enabled: state.detailsOpen && server.connection.status() === "connected" && input.session.project()?.vcs === "git",
+    enabled: state.detailsOpen && server.connection.status() === "connected" && !!input.session.project()?.vcs,
     queryFn: () =>
       server.api.vcs
         .diff({ location: { directory: input.session.workspace.directory() }, mode: "working" })
@@ -413,7 +413,7 @@ export function createSessionReview(input: {
       tab: () => state.mobileTab,
     },
     mode,
-    noGit: createMemo(() => !!input.session.project() && input.session.project()?.vcs !== "git"),
+    noGit: createMemo(() => !!input.session.project() && !input.session.project()?.vcs),
     open,
     openFile,
     options,

packages/app/src/session/screen.tsx

@@ -165,7 +165,7 @@ export function SessionScreen(props: { session: SessionModel }) {
                         baseBranch={
                           session.shared.data.location.vcs.info({ directory: project().worktree })?.branch.current
                         }
-                        diffs={project().vcs === "git" ? review.details.diffs() : []}
+                        diffs={project().vcs ? review.details.diffs() : []}
                         sessionID={session.identity.params.id ?? ""}
                         moveEligible={composer.workspaceMoveEligible()}
                         moveDismissed={store.mobileMoveDismissed}

packages/app/src/shell/titlebar/tab-nav.tsx

@@ -395,11 +395,8 @@ export function DraftTabItem(props: {
       data-active={props.active}
       data-dragging={props.dragging}
       data-state={props.active || props.pressed ? "pressed" : undefined}
-      class="group relative flex h-7 min-w-0 flex-row items-center gap-1.5 overflow-hidden rounded-[6px] px-1.5 whitespace-nowrap"
-      classList={{
-        invisible: props.hidden,
-        "w-full [container-type:inline-size]": props.orientation === "vertical",
-      }}
+      class="group relative flex h-7 w-full min-w-0 flex-row items-center gap-1.5 overflow-hidden rounded-[6px] px-1.5 [container-type:inline-size] whitespace-nowrap"
+      classList={{ invisible: props.hidden }}
       onMouseDown={(event) => {
         if (event.button !== MIDDLE_MOUSE_BUTTON) return
         event.preventDefault()
@@ -432,16 +429,14 @@ export function DraftTabItem(props: {
           if (props.suppressNavigation) return
           props.onNavigate()
         }}
-        class="flex h-full min-w-0 flex-row items-center gap-1.5 text-[13px] font-medium text-v2-text-text-faint group-data-[active='true']:text-v2-text-text-base [-webkit-user-drag:none]"
-        classList={{ "flex-1": props.orientation === "vertical", "flex-none pe-10": props.orientation !== "vertical" }}
+        class="flex h-full min-w-0 flex-1 flex-row items-center gap-1.5 text-[13px] font-medium text-v2-text-text-faint group-data-[active='true']:text-v2-text-text-base [-webkit-user-drag:none]"
       >
         <span class="flex size-4 shrink-0 items-center justify-center">
           <Icon name="edit" />
         </span>
         <span
           data-titlebar-tab-title
-          class="min-w-0 overflow-hidden text-clip whitespace-nowrap outline-none leading-4"
-          classList={{ "flex-1": props.orientation === "vertical", "flex-none": props.orientation !== "vertical" }}
+          class="min-w-0 flex-1 overflow-hidden text-clip whitespace-nowrap outline-none leading-4"
         >
           {props.title}
         </span>

packages/app/src/shell/titlebar/tab-strip.tsx

@@ -211,7 +211,7 @@ function DraftTabSlot(props: {
       data-orientation={props.orientation}
       class="relative flex"
       classList={{
-        "w-max min-w-7 max-w-56 shrink-0": props.orientation === "horizontal",
+        "w-56 min-w-7 max-w-56 flex-shrink": props.orientation === "horizontal",
         "w-full shrink-0": props.orientation === "vertical",
       }}
     >

packages/cli/script/build.ts

@@ -128,6 +128,9 @@ export default { path: file, version: ${JSON.stringify(opencodePty.version)}, sh
     external: ["node-gyp"],
     format: "esm",
     minify: true,
+    // Bun 1.4.0 cross-compiled bytecode can crash on Windows (oven-sh/bun#40270).
+    // Re-enable after both the builder and embedded runtime move to Bun 1.4.1.
+    bytecode: false,
     sourcemap: Script.channel === "dev" || Script.channel === "local" ? "inline" : "none",
     splitting: true,
     compile: {
@@ -145,6 +148,7 @@ export default { path: file, version: ${JSON.stringify(opencodePty.version)}, sh
       OPENCODE_VERSION: `'${Script.version}'`,
       OPENCODE_CLI_NAME: `'${binary}'`,
       OPENCODE_CHANNEL: `'${Script.channel}'`,
+      OPENCODE_ARTIFACT: `'cli'`,
       OPENCODE_LIBC: item.os === "linux" ? `'${item.abi ?? "glibc"}'` : "undefined",
       // FFF_LIBC selects the fff native lib variant: "musl" or "gnu".
       FFF_LIBC: item.os === "linux" ? `'${item.abi ?? "gnu"}'` : "undefined",

packages/cli/script/publish.ts

@@ -23,7 +23,13 @@ async function publish(dir: string, name: string, version: string) {
   }
 }
 
-async function publishDistribution(input: { root: string; name: string; binary: string; packagePrefix: string }) {
+async function publishDistribution(input: {
+  root: string
+  name: string
+  binary: string
+  packagePrefix: string
+  artifact: string
+}) {
   const binaries: Record<string, string> = {}
   for (const filepath of new Bun.Glob("*/package.json").scanSync({ cwd: input.root })) {
     const item = await Bun.file(`${input.root}/${filepath}`).json()
@@ -72,6 +78,13 @@ async function publishDistribution(input: { root: string; name: string; binary:
     ),
   )
   await publish(`${input.root}/${input.name}`, input.name, version)
+  await UpdateArtifact.publish({
+    channel: Script.channel,
+    name: input.artifact,
+    distribution: "npm",
+    version,
+    metadata: { package: input.name },
+  })
 }
 
 await publishDistribution({
@@ -79,6 +92,7 @@ await publishDistribution({
   name: pkg.name,
   binary: "opencode2",
   packagePrefix: "@opencode-ai/cli-",
+  artifact: "cli",
 })
 if (existsSync("./dist/node")) {
   await publishDistribution({
@@ -86,12 +100,6 @@ if (existsSync("./dist/node")) {
     name: "opencode-node",
     binary: "opencode2-node",
     packagePrefix: "@opencode-ai/cli-node-",
+    artifact: "cli-node",
   })
 }
-await UpdateArtifact.publish({
-  channel: Script.channel,
-  name: "cli",
-  distribution: "npm",
-  version: Script.version,
-  metadata: {},
-})

packages/cli/script/service-smoke.ts

@@ -93,7 +93,11 @@ try {
 }
 
 const output = await Promise.all(errors)
-await fs.rm(root, { recursive: true, force: true })
+// Windows can retain directory handles briefly after the service processes exit.
+await fs.rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 }).catch((cause: unknown) => {
+  console.error("Failed to remove service smoke-test directory", cause)
+  failure ??= cause
+})
 if (failure)
   throw new Error(output.filter(Boolean).join("\n") || "Compiled service lifecycle smoke test failed", {
     cause: failure,

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/src/commands/handlers/default.ts

@@ -47,7 +47,7 @@ export default Runtime.handler(Commands, (input) =>
       ),
     )
     const updater = yield* Updater.Service
-    yield* updater.check().pipe(Effect.forkScoped)
+    if (!server.service) yield* updater.check().pipe(Effect.forkScoped)
     preflight.loading()
     const config = yield* Config.Service
     const npm = yield* Npm.Service
@@ -83,13 +83,13 @@ export default Runtime.handler(Commands, (input) =>
         get: () => runPromise(config.get()),
         update: (update) => runPromise(config.update(update)),
       },
+      updater: service
+        ? {
+            apply: (version) => runPromise(updater.apply(version)),
+          }
+        : undefined,
       packages: {
-        resolve: (spec, install = true) =>
-          runPromise(
-            (install ? npm.add(spec, { subpaths: ["tui"] }) : npm.resolve(spec, { subpaths: ["tui"] })).pipe(
-              Effect.map((result) => result.entrypoint),
-            ),
-          ),
+        prepare: (spec, install = true) => runPromise(install ? npm.add(spec) : npm.resolve(spec)),
       },
       environment: requestedServer === undefined ? Env.session() : undefined,
       terminalHandoff: () => preflight.finish(),

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

@@ -5,6 +5,7 @@ import { Effect } from "effect"
 import { applyEdits, modify, parse, type ParseError } from "jsonc-parser"
 import { Global } from "@opencode-ai/util/global"
 import { Npm } from "@opencode-ai/util/npm"
+import { Host } from "@opencode-ai/plugin/host"
 import { Commands } from "../../commands"
 import { Runtime } from "../../../framework/runtime"
 import { resolveConfigPath } from "../mcp/add"
@@ -16,9 +17,9 @@ export default Runtime.handler(
     if (!(yield* Effect.promise(() => Npm.isInstallablePackage(input.package))))
       return yield* Effect.fail(new Error("Plugin target must be an npm registry package or Git package specifier"))
     const npm = yield* Npm.Service
-    const installed = yield* npm.add(input.package, { subpaths: ["server", ""] })
-    const tui = yield* npm.resolve(input.package, { subpaths: ["tui"] })
-    const target = configurationTarget(installed.entrypoint, tui.entrypoint)
+    const installed = yield* npm.add(input.package)
+    const entrypoints = Host.resolve(installed)
+    const target = configurationTarget(entrypoints.server, entrypoints.tui)
     if (!target)
       return yield* Effect.fail(new Error(`Plugin package has no server or TUI entrypoint: ${input.package}`))
 

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

@@ -62,7 +62,7 @@ export const inspect = Effect.fn("cli.plugin.inspect")(function* (selected?: str
     tuiTargets,
     (target) =>
       Effect.gen(function* () {
-        const installed = yield* npm.resolve(target, { subpaths: ["tui"] })
+        const installed = yield* npm.resolve(target)
         const outdated = yield* npm.check(target).pipe(Effect.exit)
         return {
           runtime: "TUI" as const,

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

@@ -9,8 +9,9 @@ import { ServiceConfig } from "../../../services/service-config"
 import { Config } from "../../../config"
 import { Global } from "@opencode-ai/util/global"
 import { Npm } from "@opencode-ai/util/npm"
+import { Host } from "@opencode-ai/plugin/host"
 import { fileURLToPath } from "node:url"
-import { discoverTuiPlugins, localPluginDirectories, localSource } from "@opencode-ai/tui/plugin/discovery"
+import { discoverPluginTargets, localPluginDirectories, localSource } from "@opencode-ai/tui/plugin/discovery"
 
 export default Runtime.handler(
   Commands.commands.plugin.commands.list,
@@ -22,27 +23,27 @@ export default Runtime.handler(
     const global = yield* Global.Service
     const info = yield* config.get()
     const discovered = yield* Effect.promise(() =>
-      localPluginDirectories(process.cwd(), global.config).then(discoverTuiPlugins),
+      localPluginDirectories(process.cwd(), global.config).then(discoverPluginTargets),
     )
     const npm = yield* Npm.Service
-    const configured = yield* Effect.forEach(info.plugins ?? [], (entry) =>
+    const configured = yield* Effect.forEach([...(info.plugins ?? []), ...discovered], (entry) =>
       Effect.gen(function* () {
         const target = typeof entry === "string" ? entry : entry.package
         if (target.startsWith("-") || target === "*" || target.endsWith(".*") || target.startsWith("opencode."))
           return []
         const local = localSource(target, path.dirname(config.path))
-        if (local) return [{ target: fileURLToPath(local), version: "local" }]
+        if (local) {
+          const directory = fileURLToPath(local)
+          const entrypoints = Host.resolve({ directory })
+          return entrypoints.tui ? [{ target: directory, version: "local" }] : []
+        }
         if (!(yield* Effect.promise(() => Npm.isInstallablePackage(target)))) return []
-        const installed = yield* npm.resolve(target, { subpaths: ["tui"] })
-        if (!installed.entrypoint) return []
+        const installed = yield* npm.resolve(target)
+        if (!Host.resolve(installed).tui) return []
         return [{ target, version: installed.version }]
       }),
     )
-    const output = format(
-      response.data,
-      [...configured.flat(), ...discovered.map((target) => ({ target, version: "local" }))],
-      input.builtin,
-    )
+    const output = format(response.data, configured.flat(), input.builtin)
     if (!output) {
       process.stdout.write("No plugins found" + EOL)
       return
@@ -81,9 +82,7 @@ export function format(
             ? plugin.source.target === item.target
             : plugin.source.type === "local" &&
               (plugin.source.path === item.target ||
-                (plugin.features.tui &&
-                  path.dirname(plugin.source.path) ===
-                    (item.version === "local" && path.extname(item.target) ? path.dirname(item.target) : item.target))),
+                (plugin.features.tui && path.dirname(plugin.source.path) === item.target)),
         ),
     )
     .filter((plugin, index, all) => all.findIndex((candidate) => candidate.target === plugin.target) === index)

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

@@ -26,7 +26,7 @@ export default Runtime.handler(
       (item) =>
         (item.runtime === "Server"
           ? Effect.promise(() => result.client.plugin.update({ location: result.location, targets: [item.target] }))
-          : npm.update(item.target, { subpaths: ["tui"] }).pipe(Effect.asVoid)
+          : npm.update(item.target).pipe(Effect.asVoid)
         ).pipe(
           Effect.exit,
           Effect.map((result) => ({ item, result })),

packages/cli/src/server-process.ts

@@ -7,7 +7,8 @@ import { Global } from "@opencode-ai/util/global"
 import { OPENCODE_CHANNEL, OPENCODE_VERSION } from "./version"
 import { AppProcess } from "@opencode-ai/util/process"
 import { randomBytes, randomUUID } from "node:crypto"
-import { Effect, Option, Redacted, Schedule, Schema } from "effect"
+import { spawn } from "node:child_process"
+import { Deferred, Effect, Option, Redacted, Schedule, Schema } from "effect"
 import { PersistentPty } from "@opencode-ai/schema/persistent-pty"
 import { HttpServer } from "effect/unstable/http"
 import { Env } from "./env"
@@ -53,7 +54,8 @@ const processEffect = Effect.fnUntraced(function* (options: Options) {
         )
   const global = yield* Global.Service
   if (options.mode === "service") yield* Effect.sync(() => process.chdir(global.home))
-  return yield* Effect.scoped(
+  const replacement = yield* Deferred.make<PersistentPty.Handoff | null>()
+  const next = yield* Effect.scoped(
     Effect.gen(function* () {
       const foreground = options.mode === "default"
       const serviceOptions = options.mode === "service" ? yield* ServiceConfig.options() : undefined
@@ -64,7 +66,7 @@ const processEffect = Effect.fnUntraced(function* (options: Options) {
         serviceOptions !== undefined && port !== undefined
           ? yield* Service.incumbent({ ...serviceOptions, url: serviceURL(hostname, port) })
           : undefined
-      if (incumbent !== undefined) return
+      if (incumbent !== undefined) return Option.none<PersistentPty.Handoff | null>()
       const { start } = yield* Effect.promise(() => import("@opencode-ai/server/process"))
       const environmentPassword = yield* Env.password
       // Keep the lease credential out of the environment inherited by tools.
@@ -161,19 +163,62 @@ const processEffect = Effect.fnUntraced(function* (options: Options) {
           )
         }),
       )
-      if (server === undefined) return
+      if (server === undefined) return Option.none<PersistentPty.Handoff | null>()
       const url = HttpServer.formatAddress(server.address)
       console.log(options.mode === "stdio" ? JSON.stringify({ url }) : `server listening on ${url}`)
       if (foreground && !environmentPassword) console.log(`server password ${password}`)
       const updater = yield* Updater.Service
-      yield* updater.check().pipe(Effect.schedule(Schedule.spaced("10 minutes")), Effect.forkScoped)
+      yield* updater
+        .monitor({
+          url,
+          password,
+          managed: options.mode === "service",
+          notify: server.updateAvailable,
+          restart: (handoff) => Deferred.succeed(replacement, handoff).pipe(Effect.asVoid),
+        })
+        .pipe(Effect.forkScoped)
       return yield* options.mode === "service"
-        ? server.shutdown
+        ? Effect.raceFirst(
+            server.shutdown.pipe(Effect.as(Option.none<PersistentPty.Handoff | null>())),
+            Deferred.await(replacement).pipe(Effect.map(Option.some)),
+          )
         : options.mode === "stdio"
-          ? waitForStdinClose()
+          ? waitForStdinClose().pipe(Effect.as(Option.none<PersistentPty.Handoff | null>()))
           : Effect.never
     }).pipe(Effect.annotateLogs({ role: "server" })),
   )
+  if (Option.isNone(next)) return
+  yield* spawnReplacement(next.value)
+})
+
+const spawnReplacement = Effect.fnUntraced(function* (handoff: PersistentPty.Handoff | null) {
+  const options = yield* ServiceConfig.options()
+  const [command, ...args] = options.command
+  if (!command) return yield* Effect.fail(new Error("Failed to resolve CLI command for restart"))
+  // We do not monitor the replacement after spawn. A managed TUI
+  // recovers with Service.ensure if startup fails; a future client
+  // restart signal could coordinate that recovery instead.
+  yield* Effect.tryPromise({
+    try: () =>
+      new Promise<void>((resolve, reject) => {
+        const child = spawn(command, args, {
+          detached: true,
+          stdio: "ignore",
+          windowsHide: true,
+          env: {
+            ...process.env,
+            ...options.env,
+            OPENCODE_PTY_HANDOFF: handoff ? JSON.stringify(handoff) : undefined,
+          },
+        })
+        child.once("spawn", () => {
+          child.unref()
+          resolve()
+        })
+        child.once("error", reject)
+      }),
+    catch: (cause) => new Error("Failed to start replacement server", { cause }),
+  })
 })
 
 const recognizeIncumbent = Effect.fnUntraced(function* (options: DiscoverOptions, hostname: string, port: number) {

packages/cli/src/services/server-connection.ts

@@ -56,7 +56,7 @@ function managedService(options: EnsureOptions) {
     reconnect: () => Service.ensure(reconnectOptions),
     restart: () =>
       Effect.gen(function* () {
-        yield* Service.stop(options)
+        yield* Service.stop({ file: options.file, pty: "handoff" })
         yield* Service.ensure(reconnectOptions)
       }),
   }

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

@@ -1,4 +1,4 @@
-export type Policy = boolean | "notify"
+export type Policy = "disable" | "notify" | "auto"
 export type Action = "none" | "notify" | "upgrade"
 
 const maximumComponent = "9007199254740991"
@@ -6,13 +6,14 @@ const versionPattern =
   /^v?([0-9]+)\.([0-9]+)\.([0-9]+)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/
 
 export function action(current: string, latest: string, policy: Policy): Action {
-  if (policy === false) return "none"
+  if (policy === "disable") return "none"
   const currentVersion = parseReleaseVersion(current)
   const latestVersion = parseReleaseVersion(latest)
   if (!currentVersion || !latestVersion || sameRelease(currentVersion, latestVersion)) return "none"
+  if (policy === "notify") return "notify"
   // Major upgrades are never installed automatically.
-  if (currentVersion.major !== latestVersion.major) return "none"
-  return policy === "notify" ? "notify" : "upgrade"
+  if (currentVersion.major !== latestVersion.major) return "notify"
+  return "upgrade"
 }
 
 export function parseReleaseVersion(input: string) {

packages/cli/src/services/updater.test.ts

@@ -3,46 +3,54 @@ import { action } from "./updater-action"
 import { decodePolicy } from "./updater"
 
 describe("updater", () => {
-  test("reads autoupdate from JSONC", () => {
-    expect(decodePolicy('{ // preference\n "autoupdate": "notify",\n}')).toBe("notify")
-    expect(decodePolicy('{ "autoupdate": false }')).toBe(false)
-    expect(decodePolicy('{ "autoupdate": "invalid" }')).toBeUndefined()
+  test("reads update policy from JSONC", () => {
+    expect(decodePolicy('{ // preference\n "update": "notify",\n}')).toBe("notify")
+    expect(decodePolicy('{ "update": "disable" }')).toBe("disable")
+    expect(decodePolicy('{ "update": "auto" }')).toBe("auto")
+    expect(decodePolicy('{ "update": "invalid" }')).toBeUndefined()
+  })
+
+  test("maps the v1 update policy", () => {
+    expect(decodePolicy('{ "autoupdate": false }')).toBe("disable")
+    expect(decodePolicy('{ "autoupdate": "notify" }')).toBe("notify")
+    expect(decodePolicy('{ "autoupdate": true }')).toBe("auto")
   })
 
   test("automatically updates patches and minors", () => {
-    expect(action("1.2.3", "1.2.4", true)).toBe("upgrade")
-    expect(action("1.2.3", "1.3.0", true)).toBe("upgrade")
+    expect(action("1.2.3", "1.2.4", "auto")).toBe("upgrade")
+    expect(action("1.2.3", "1.3.0", "auto")).toBe("upgrade")
   })
 
   test("reports patches and minors without automatically installing them", () => {
     expect(action("1.2.3", "1.2.4", "notify")).toBe("notify")
     expect(action("1.2.3", "1.3.0", "notify")).toBe("notify")
+    expect(action("1.2.3", "2.0.0", "notify")).toBe("notify")
     expect(action("1.2.3", "1.2.3", "notify")).toBe("none")
   })
 
-  test("skips when autoupdate is disabled", () => {
-    expect(action("1.2.3", "1.2.4", false)).toBe("none")
+  test("skips when updates are disabled", () => {
+    expect(action("1.2.3", "1.2.4", "disable")).toBe("none")
   })
 
-  test("never automatically updates majors", () => {
-    expect(action("1.2.3", "2.0.0", true)).toBe("none")
+  test("reports majors instead of automatically installing them", () => {
+    expect(action("1.2.3", "2.0.0", "auto")).toBe("notify")
   })
 
   test("reports up-to-date only when versions match", () => {
-    expect(action("1.2.3", "1.2.3", true)).toBe("none")
+    expect(action("1.2.3", "1.2.3", "auto")).toBe("none")
   })
 
   test("upgrades when latest is lower (rollback)", () => {
-    expect(action("1.2.4", "1.2.3", true)).toBe("upgrade")
+    expect(action("1.2.4", "1.2.3", "auto")).toBe("upgrade")
   })
 
   test("accepts strict release version variants", () => {
-    expect(action("v1.2.3", " 1.2.4\n", true)).toBe("upgrade")
-    expect(action("1.2.3-alpha.1", "1.2.3-alpha.2", true)).toBe("upgrade")
-    expect(action("0.0.0-dev-17403", "0.0.0-dev-17403.2", true)).toBe("upgrade")
-    expect(action("0.0.0-next-17403", "0.0.0-beta-17404", true)).toBe("upgrade")
-    expect(action("1.2.3+old", "1.2.3+new", true)).toBe("none")
-    expect(action("v1.2.3+old", "1.2.3", true)).toBe("none")
+    expect(action("v1.2.3", " 1.2.4\n", "auto")).toBe("upgrade")
+    expect(action("1.2.3-alpha.1", "1.2.3-alpha.2", "auto")).toBe("upgrade")
+    expect(action("0.0.0-dev-17403", "0.0.0-dev-17403.2", "auto")).toBe("upgrade")
+    expect(action("0.0.0-next-17403", "0.0.0-beta-17404", "auto")).toBe("upgrade")
+    expect(action("1.2.3+old", "1.2.3+new", "auto")).toBe("none")
+    expect(action("v1.2.3+old", "1.2.3", "auto")).toBe("none")
   })
 
   test("preserves strict validity", () => {
@@ -63,21 +71,21 @@ describe("updater", () => {
       "0.9007199254740992.0",
       "0.0.9007199254740992",
     ]
-    invalid.forEach((version) => expect(action("1.2.3", version, true), version).toBe("none"))
+    invalid.forEach((version) => expect(action("1.2.3", version, "auto"), version).toBe("none"))
   })
 
   test("handles numeric limits without losing precision", () => {
-    expect(action("9007199254740991.0.0", "9007199254740991.0.1", true)).toBe("upgrade")
-    expect(action("9007199254740990.0.0", "9007199254740991.0.0", true)).toBe("none")
+    expect(action("9007199254740991.0.0", "9007199254740991.0.1", "auto")).toBe("upgrade")
+    expect(action("9007199254740990.0.0", "9007199254740991.0.0", "auto")).toBe("notify")
   })
 
   test("preserves equality for oversized numeric prerelease identifiers", () => {
-    expect(action("1.0.0-9007199254740992", "1.0.0-9007199254740993", true)).toBe("none")
-    expect(action("1.0.0-9007199254740991", "1.0.0-9007199254740992", true)).toBe("upgrade")
+    expect(action("1.0.0-9007199254740992", "1.0.0-9007199254740993", "auto")).toBe("none")
+    expect(action("1.0.0-9007199254740991", "1.0.0-9007199254740992", "auto")).toBe("upgrade")
   })
 
   test("rejects versions longer than semver's limit before trimming", () => {
-    expect(action("1.2.3", `${" ".repeat(251)}1.2.3`, true)).toBe("none")
-    expect(action("1.2.3", `1.2.4+${"a".repeat(250)}`, true)).toBe("upgrade")
+    expect(action("1.2.3", `${" ".repeat(251)}1.2.3`, "auto")).toBe("none")
+    expect(action("1.2.3", `1.2.4+${"a".repeat(250)}`, "auto")).toBe("upgrade")
   })
 })

packages/cli/src/services/updater.ts

@@ -1,27 +1,156 @@
 import { Global } from "@opencode-ai/util/global"
 import { AppProcess } from "@opencode-ai/util/process"
-import { OPENCODE_CHANNEL, OPENCODE_LOCAL, OPENCODE_VERSION } from "../version"
-import { Context, Duration, Effect, FileSystem, Layer } from "effect"
+import { OpenCode } from "@opencode-ai/client"
+import { PersistentPty } from "@opencode-ai/schema/persistent-pty"
+import { OPENCODE_ARTIFACT, OPENCODE_CHANNEL, OPENCODE_LOCAL, OPENCODE_VERSION } from "../version"
+import { Context, Duration, Effect, FileSystem, Layer, Ref, Schedule, Semaphore, Stream } from "effect"
 import { ChildProcess } from "effect/unstable/process"
 import { parse, type ParseError } from "jsonc-parser"
 import path from "node:path"
-import { action, parseReleaseVersion, type Policy } from "./updater-action"
-
-declare const OPENCODE_CLI_NAME: string | undefined
+import { action, parseReleaseVersion, type Action, type Policy } from "./updater-action"
 
 export const methods = ["curl", "npm", "pnpm", "bun", "yarn"] as const
 export type Method = (typeof methods)[number]
 
-const packageName =
-  typeof OPENCODE_CLI_NAME === "string" && OPENCODE_CLI_NAME === "opencode2-node" ? "opencode-node" : "@opencode-ai/cli"
-
 export interface Interface {
   readonly check: () => Effect.Effect<void>
+  readonly monitor: (input: {
+    readonly url: string
+    readonly password: string
+    readonly managed: boolean
+    readonly notify: (version: string) => Effect.Effect<void>
+    readonly restart: (handoff: PersistentPty.Handoff | null) => Effect.Effect<void>
+  }) => Effect.Effect<void>
+  readonly apply: (version: string) => Effect.Effect<void, Error>
   readonly method: () => Effect.Effect<Method | undefined>
   readonly latest: () => Effect.Effect<string, Error>
   readonly upgrade: (method: Method, version: string) => Effect.Effect<void, Error>
 }
 
+export type Inspection =
+  | { readonly action: "none" }
+  | { readonly action: Exclude<Action, "none">; readonly version: string }
+
+type State =
+  | { readonly type: "current" }
+  | { readonly type: "available"; readonly version: string; readonly availableSince: number }
+  | { readonly type: "ready-to-restart"; readonly version: string }
+
+export interface MonitorInput {
+  readonly url: string
+  readonly password: string
+  readonly managed: boolean
+  readonly inspect: () => Effect.Effect<Inspection, Error>
+  readonly install: (version: string) => Effect.Effect<boolean, Error>
+  readonly restart: (handoff: PersistentPty.Handoff | null) => Effect.Effect<void>
+  readonly interval?: Duration.Input
+  readonly notificationThreshold?: Duration.Input
+  readonly notify: (version: string) => Effect.Effect<void>
+}
+
+export const monitorServer = Effect.fnUntraced(function* (input: MonitorInput) {
+  const state = yield* Ref.make<State>({ type: "current" })
+  const applyLock = yield* Semaphore.make(1)
+  const client = OpenCode.make({
+    baseUrl: input.url,
+    headers: { authorization: `Basic ${btoa(`opencode:${input.password}`)}` },
+  })
+
+  const applyIfIdle = () =>
+    applyLock.withPermit(
+      Effect.gen(function* () {
+        const pending = yield* Ref.get(state)
+        if (pending.type !== "available") return
+        const active = yield* Effect.tryPromise({
+          try: () => client.session.active(),
+          catch: (cause) => new Error("Failed to read active sessions", { cause }),
+        })
+        if (Object.keys(active).length > 0) return
+        const latest = yield* input.inspect()
+        if (latest.action !== "upgrade") {
+          yield* Ref.set(state, { type: "current" })
+          return
+        }
+        const installed = yield* input
+          .install(latest.version)
+          .pipe(
+            Effect.catch((error) =>
+              Effect.logWarning("automatic update failed", { cause: error }).pipe(Effect.as(false)),
+            ),
+          )
+        if (!installed) return
+        const handoff = input.managed
+          ? yield* Effect.tryPromise({
+              try: () => client.experimental.persistentPty.handoff(),
+              catch: (cause) => new Error("Failed to prepare persistent terminals for restart", { cause }),
+            })
+          : undefined
+        yield* Ref.set(state, { type: "ready-to-restart", version: latest.version })
+        if (handoff) yield* input.restart(handoff.handoff)
+      }),
+    )
+
+  const checkServer = Effect.gen(function* () {
+    const result = yield* input.inspect()
+    if (result.action === "notify") {
+      yield* input.notify(result.version)
+      return
+    }
+    if (result.action !== "upgrade") {
+      yield* Ref.update(
+        state,
+        (current): State => (current.type === "ready-to-restart" ? current : { type: "current" }),
+      )
+      return
+    }
+    yield* Ref.update(state, (current): State => {
+      if (current.type === "ready-to-restart" && current.version === result.version) return current
+      return {
+        type: "available",
+        version: result.version,
+        availableSince: current.type === "available" ? current.availableSince : Date.now(),
+      }
+    })
+    yield* applyIfIdle()
+    const pending = yield* Ref.get(state)
+    if (
+      pending.type === "available" &&
+      Date.now() - pending.availableSince >= Duration.toMillis(input.notificationThreshold ?? "3 days")
+    )
+      yield* input.notify(pending.version)
+  }).pipe(Effect.catch((cause) => Effect.logWarning("automatic update check failed", { cause })))
+
+  const subscribe = Effect.suspend(() =>
+    Stream.fromAsyncIterable(
+      client.event.subscribe(),
+      (cause) => new Error("Update event stream failed", { cause }),
+    ).pipe(
+      Stream.runForEach((event) => {
+        if (event.type === "server.connected") return applyIfIdle()
+        if (
+          event.type !== "session.execution.succeeded" &&
+          event.type !== "session.execution.failed" &&
+          event.type !== "session.execution.interrupted"
+        )
+          return Effect.void
+        return Effect.tryPromise({
+          try: () => client.session.wait({ sessionID: event.data.sessionID }),
+          catch: (cause) => new Error(`Failed to wait for Session ${event.data.sessionID}`, { cause }),
+        }).pipe(Effect.andThen(applyIfIdle()))
+      }),
+      Effect.catch((cause) => Effect.logWarning("update event stream disconnected", { cause })),
+    ),
+  ).pipe(Effect.repeat(Schedule.spaced("1 second")))
+
+  return yield* Effect.all(
+    [checkServer.pipe(Effect.repeat(Schedule.spaced(input.interval ?? "10 minutes"))), subscribe],
+    {
+      concurrency: "unbounded",
+      discard: true,
+    },
+  )
+})
+
 export class Service extends Context.Service<Service, Interface>()("@opencode/cli/Updater") {}
 
 export function decodePolicy(text: string): Policy | undefined {
@@ -29,157 +158,220 @@ export function decodePolicy(text: string): Policy | undefined {
   // the location-scoped server configuration graph.
   const errors: ParseError[] = []
   const input: unknown = parse(text, errors, { allowTrailingComma: true })
-  if (errors.length || typeof input !== "object" || input === null || !("autoupdate" in input)) return
-  const value = input.autoupdate
-  if (typeof value === "boolean" || value === "notify") return value
+  if (errors.length || typeof input !== "object" || input === null) return
+  if ("update" in input) {
+    const value = input.update
+    if (value === "disable" || value === "notify" || value === "auto") return value
+    return
+  }
+  if (!("autoupdate" in input)) return
+  if (input.autoupdate === false) return "disable"
+  if (input.autoupdate === "notify") return "notify"
+  if (input.autoupdate === true) return "auto"
 }
 
-export const layer = Layer.effect(
-  Service,
-  Effect.gen(function* () {
-    const fs = yield* FileSystem.FileSystem
-    const global = yield* Global.Service
-    const appProcess = yield* AppProcess.Service
-    const channel = OPENCODE_CHANNEL.replace(/[^a-zA-Z0-9._-]/g, "-")
+const make = Effect.gen(function* () {
+  const fs = yield* FileSystem.FileSystem
+  const global = yield* Global.Service
+  const appProcess = yield* AppProcess.Service
+  const channel = OPENCODE_CHANNEL.replace(/[^a-zA-Z0-9._-]/g, "-")
+  const installedPackage = yield* Effect.gen(function* () {
+    const executable = yield* fs.realPath(process.execPath)
+    const directory = path.dirname(path.dirname(executable))
+    const manifest: { name: string; bin?: Record<string, string> } = yield* fs
+      .readFileString(path.join(directory, "package.json"))
+      .pipe(Effect.flatMap((text) => Effect.try(() => JSON.parse(text))))
+    if (Object.values(manifest.bin ?? {}).some((bin) => path.resolve(directory, bin) === executable))
+      return manifest.name
+  }).pipe(Effect.orElseSucceed(() => undefined))
 
-    const readPolicy = Effect.fnUntraced(function* () {
-      const values = yield* Effect.forEach(["config.json", "opencode.json", "opencode.jsonc"], (name) =>
-        fs.readFileString(path.join(global.config, name)).pipe(
-          Effect.map(decodePolicy),
-          Effect.orElseSucceed(() => undefined),
-        ),
+  const readPolicy = Effect.fnUntraced(function* () {
+    const values = yield* Effect.forEach(["config.json", "opencode.json", "opencode.jsonc"], (name) =>
+      fs.readFileString(path.join(global.config, name)).pipe(
+        Effect.map(decodePolicy),
+        Effect.orElseSucceed(() => undefined),
+      ),
+    )
+    return values.findLast((value) => value !== undefined) ?? "auto"
+  })
+
+  const run = Effect.fnUntraced(function* (command: string[], timeout: Duration.Input = "10 seconds") {
+    return yield* appProcess
+      .run(ChildProcess.make(command[0], command.slice(1)), {
+        timeout,
+        maxOutputBytes: 100_000,
+        maxErrorBytes: 100_000,
+      })
+      .pipe(
+        Effect.map((result) => ({
+          code: result.exitCode,
+          stdout: result.stdout.toString("utf8"),
+          stderr: result.stderr.toString("utf8"),
+        })),
+        Effect.orElseSucceed(() => ({ code: 1, stdout: "", stderr: "" })),
       )
-      return values.findLast((value) => value !== undefined) ?? true
-    })
+  })
 
-    const run = Effect.fnUntraced(function* (command: string[], timeout: Duration.Input = "10 seconds") {
-      return yield* appProcess
-        .run(ChildProcess.make(command[0], command.slice(1)), {
-          timeout,
-          maxOutputBytes: 100_000,
-          maxErrorBytes: 100_000,
-        })
-        .pipe(
-          Effect.map((result) => ({
-            code: result.exitCode,
-            stdout: result.stdout.toString("utf8"),
-            stderr: result.stderr.toString("utf8"),
-          })),
-          Effect.orElseSucceed(() => ({ code: 1, stdout: "", stderr: "" })),
-        )
-    })
+  const method = Effect.fnUntraced(function* () {
+    const binary = path.join(
+      global.home,
+      ".opencode",
+      "bin",
+      process.platform === "win32" ? "opencode2.exe" : "opencode2",
+    )
+    if (path.resolve(process.execPath) === path.resolve(binary)) return "curl"
+    if (!installedPackage) return
 
-    const method = Effect.fnUntraced(function* () {
-      const binary = path.join(
-        global.home,
-        ".opencode",
-        "bin",
-        process.platform === "win32" ? "opencode2.exe" : "opencode2",
-      )
-      if (path.resolve(process.execPath) === path.resolve(binary)) return "curl"
+    const checks: ReadonlyArray<{ method: Method; command: string[] }> = [
+      { method: "npm", command: ["npm", "list", "-g", "--depth=0", installedPackage] },
+      { method: "pnpm", command: ["pnpm", "list", "-g", "--depth=0", installedPackage] },
+      { method: "bun", command: ["bun", "pm", "ls", "-g"] },
+      { method: "yarn", command: ["yarn", "global", "list"] },
+    ]
+    const results = yield* Effect.forEach(
+      checks,
+      (check) => run(check.command).pipe(Effect.map((result) => ({ check, result }))),
+      { concurrency: "unbounded" },
+    )
+    return results.find((result) => result.result.stdout.includes(installedPackage))?.check.method
+  })
 
-      const checks: ReadonlyArray<{ method: Method; command: string[] }> = [
-        { method: "npm", command: ["npm", "list", "-g", "--depth=0", packageName] },
-        { method: "pnpm", command: ["pnpm", "list", "-g", "--depth=0", packageName] },
-        { method: "bun", command: ["bun", "pm", "ls", "-g"] },
-        { method: "yarn", command: ["yarn", "global", "list"] },
-      ]
-      const results = yield* Effect.forEach(
-        checks,
-        (check) => run(check.command).pipe(Effect.map((result) => ({ check, result }))),
-        { concurrency: "unbounded" },
-      )
-      return results.find((result) => result.result.stdout.includes(packageName))?.check.method
-    })
-
-    const latest = Effect.fnUntraced(function* () {
-      const response = yield* Effect.tryPromise({
-        try: () =>
-          fetch(`https://update.opencode.ai/api/${encodeURIComponent(channel)}/cli/npm`, {
+  const release = Effect.fnUntraced(function* () {
+    const response = yield* Effect.tryPromise({
+      try: () =>
+        fetch(
+          `https://update.opencode.ai/api/${encodeURIComponent(channel)}/${encodeURIComponent(OPENCODE_ARTIFACT)}/npm`,
+          {
             headers: { "User-Agent": `opencode/${OPENCODE_VERSION}` },
             signal: AbortSignal.timeout(10_000),
-          }),
-        catch: (cause) => new Error("Failed to check for updates", { cause }),
-      })
-      if (!response.ok) return yield* Effect.fail(new Error(`Update check failed with status ${response.status}`))
-      const data = yield* Effect.tryPromise({
-        try: () => response.json(),
-        catch: (cause) => new Error("Failed to read update information", { cause }),
-      })
-      if (typeof data !== "object" || data === null || !("version" in data) || typeof data.version !== "string") {
-        return yield* Effect.fail(new Error("Update information did not include a version"))
-      }
-      return data.version
+          },
+        ),
+      catch: (cause) => new Error("Failed to check for updates", { cause }),
     })
-
-    const upgrade = Effect.fnUntraced(function* (method: Method, input: string) {
-      if (!parseReleaseVersion(input)) return yield* Effect.fail(new Error(`Invalid version: ${input}`))
-      const version = input.trim().replace(/^v/, "")
-      const target = `${packageName}@${version}`
-      const commands: Record<Exclude<Method, "bun" | "curl">, string[]> = {
-        npm: ["npm", "install", "--global", target],
-        pnpm: ["pnpm", "add", "--global", `--allow-build=${packageName}`, target],
-        yarn: ["yarn", "global", "add", target],
-      }
-      const result = yield* Effect.scoped(
-        Effect.gen(function* () {
-          if (method === "bun") {
-            // Bun does not prune old versions from its shared package cache.
-            yield* fs.makeDirectory(global.cache, { recursive: true })
-            const cache = yield* fs.makeTempDirectoryScoped({ directory: global.cache, prefix: "update-" })
-            return yield* run(["bun", "install", "--global", "--trust", "--cache-dir", cache, target], "5 minutes")
-          }
-          if (method === "curl") {
-            yield* fs.makeDirectory(global.cache, { recursive: true })
-            const directory = yield* fs.makeTempDirectoryScoped({ directory: global.cache, prefix: "update-" })
-            const installer = path.join(directory, "install")
-            const download = yield* run(
-              ["curl", "-fsSL", "-o", installer, "https://opencode.ai/v2/install"],
-              "5 minutes",
-            )
-            if (download.code !== 0) return download
-            return yield* run(["bash", installer, "--version", version, "--no-modify-path"], "5 minutes")
-          }
-          return yield* run(commands[method], "5 minutes")
-        }),
-      ).pipe(Effect.mapError((cause) => new Error(`Failed to update with ${method}`, { cause })))
-      if (result.code === 0) return
-      return yield* Effect.fail(new Error(result.stderr.trim() || `Failed to update with ${method}`))
+    if (!response.ok) return yield* Effect.fail(new Error(`Update check failed with status ${response.status}`))
+    const data: { version: string; metadata?: { package?: string } } = yield* Effect.tryPromise({
+      try: () => response.json(),
+      catch: (cause) => new Error("Failed to read update information", { cause }),
     })
+    if (!data.metadata?.package) return yield* Effect.fail(new Error("Update information did not include a package"))
+    return { package: data.metadata.package, version: data.version }
+  })
 
-    const check = Effect.fn("cli.updater.check")(
-      function* () {
-        if (OPENCODE_LOCAL || ["1", "true"].includes(process.env.OPENCODE_DISABLE_AUTOUPDATE?.toLowerCase() ?? ""))
-          return yield* Effect.logInfo("update check skipped", {
-            reason: OPENCODE_LOCAL ? "local-install" : "disabled",
-            version: OPENCODE_VERSION,
-            channel: OPENCODE_CHANNEL,
-          })
-        const policy = yield* readPolicy()
-        if (policy === false) return yield* Effect.logInfo("update check skipped", { reason: "policy-disabled" })
+  const latest = () => release().pipe(Effect.map((data) => data.version))
 
-        return yield* Effect.gen(function* () {
-          const version = yield* latest()
-          yield* Effect.logInfo("update check", {
-            current: OPENCODE_VERSION,
-            latest: version,
-          })
-          const next = action(OPENCODE_VERSION, version, policy)
-          if (next === "none") return yield* Effect.logInfo("update check done", { action: "up-to-date" })
-          if (next === "notify")
-            return yield* Effect.logInfo("OpenCode update available", { current: OPENCODE_VERSION, latest: version })
-          const detected = yield* method()
-          if (!detected) return yield* Effect.logWarning("automatic update skipped: installation method not found")
-          yield* upgrade(detected, version)
-          yield* Effect.logInfo("updated OpenCode", { from: OPENCODE_VERSION, to: version, method: detected })
-        })
-      },
-      Effect.catchCause((cause) => Effect.logWarning("automatic update failed", { cause })),
-    )
+  const upgrade = Effect.fnUntraced(function* (method: Method, input: string) {
+    if (!parseReleaseVersion(input)) return yield* Effect.fail(new Error(`Invalid version: ${input}`))
+    const version = input.trim().replace(/^v/, "")
+    const packageName = (yield* release()).package
+    const target = `${packageName}@${version}`
+    if (installedPackage && packageName !== installedPackage && (method === "pnpm" || method === "yarn")) {
+      return yield* Effect.fail(new Error(`Reinstall ${target} with ${method} to migrate from ${installedPackage}.`))
+    }
+    const commands: Record<Exclude<Method, "bun" | "curl">, string[]> = {
+      // Keep the old package: uninstalling it can unlink the replacement command.
+      npm: [
+        "npm",
+        "install",
+        "--global",
+        ...(installedPackage && packageName !== installedPackage ? ["--force"] : []),
+        target,
+      ],
+      pnpm: ["pnpm", "add", "--global", `--allow-build=${packageName}`, target],
+      yarn: ["yarn", "global", "add", target],
+    }
+    const result = yield* Effect.scoped(
+      Effect.gen(function* () {
+        if (method === "bun") {
+          // Bun does not prune old versions from its shared package cache.
+          yield* fs.makeDirectory(global.cache, { recursive: true })
+          const cache = yield* fs.makeTempDirectoryScoped({ directory: global.cache, prefix: "update-" })
+          return yield* run(["bun", "install", "--global", "--trust", "--cache-dir", cache, target], "5 minutes")
+        }
+        if (method === "curl") {
+          yield* fs.makeDirectory(global.cache, { recursive: true })
+          const directory = yield* fs.makeTempDirectoryScoped({ directory: global.cache, prefix: "update-" })
+          const installer = path.join(directory, "install")
+          const download = yield* run(["curl", "-fsSL", "-o", installer, "https://opencode.ai/v2/install"], "5 minutes")
+          if (download.code !== 0) return download
+          return yield* run(["bash", installer, "--version", version, "--no-modify-path"], "5 minutes")
+        }
+        return yield* run(commands[method], "5 minutes")
+      }),
+    ).pipe(Effect.mapError((cause) => new Error(`Failed to update with ${method}`, { cause })))
+    if (result.code === 0) return
+    return yield* Effect.fail(new Error(result.stderr.trim() || `Failed to update with ${method}`))
+  })
 
-    return Service.of({ check, method, latest, upgrade })
-  }),
-)
+  const inspect = Effect.fnUntraced(function* (): Effect.fn.Return<Inspection, Error> {
+    if (OPENCODE_LOCAL || ["1", "true"].includes(process.env.OPENCODE_DISABLE_AUTOUPDATE?.toLowerCase() ?? "")) {
+      yield* Effect.logInfo("update check skipped", {
+        reason: OPENCODE_LOCAL ? "local-install" : "disabled",
+        version: OPENCODE_VERSION,
+        channel: OPENCODE_CHANNEL,
+      })
+      return { action: "none" }
+    }
+    const policy = yield* readPolicy()
+    if (policy === "disable") {
+      yield* Effect.logInfo("update check skipped", { reason: "policy-disabled" })
+      return { action: "none" }
+    }
+
+    const version = yield* latest()
+    yield* Effect.logInfo("update check", {
+      current: OPENCODE_VERSION,
+      latest: version,
+    })
+    const next = action(OPENCODE_VERSION, version, policy)
+    if (next === "none") {
+      yield* Effect.logInfo("update check done", { action: "up-to-date" })
+      return { action: "none" }
+    }
+    if (next === "notify") {
+      yield* Effect.logInfo("OpenCode update available", { current: OPENCODE_VERSION, latest: version })
+      return { action: next, version }
+    }
+    return { action: next, version }
+  })
+
+  const install = Effect.fnUntraced(function* (version: string) {
+    const detected = yield* method()
+    if (!detected) {
+      yield* Effect.logWarning("automatic update skipped: installation method not found")
+      return false
+    }
+    yield* upgrade(detected, version)
+    yield* Effect.logInfo("updated OpenCode", { from: OPENCODE_VERSION, to: version, method: detected })
+    return true
+  })
+
+  const apply = Effect.fn("cli.updater.apply")(function* (version: string) {
+    if (!(yield* install(version))) return yield* Effect.fail(new Error("Installation method not found"))
+  })
+
+  const check = Effect.fn("cli.updater.check")(
+    function* () {
+      const result = yield* inspect()
+      if (result.action !== "upgrade") return
+      yield* install(result.version)
+    },
+    Effect.catchCause((cause) => Effect.logWarning("automatic update failed", { cause })),
+  )
+
+  const monitor = Effect.fn("cli.updater.monitor")(function* (input: {
+    readonly url: string
+    readonly password: string
+    readonly managed: boolean
+    readonly notify: (version: string) => Effect.Effect<void>
+    readonly restart: (handoff: PersistentPty.Handoff | null) => Effect.Effect<void>
+  }) {
+    return yield* monitorServer({ ...input, inspect, install })
+  })
+
+  return Service.of({ check, monitor, apply, method, latest, upgrade })
+})
+
+export const layer = Layer.effect(Service, make)
 
 export * as Updater from "./updater"
 export { action, type Action, type Policy } from "./updater-action"

packages/cli/src/version.ts

@@ -1,8 +1,10 @@
 declare const OPENCODE_VERSION: string
 declare const OPENCODE_CHANNEL: string
+declare const OPENCODE_ARTIFACT: string
 
 const version = typeof OPENCODE_VERSION === "string" ? OPENCODE_VERSION : "local"
 const channel = typeof OPENCODE_CHANNEL === "string" ? OPENCODE_CHANNEL : "local"
+const artifact = typeof OPENCODE_ARTIFACT === "string" ? OPENCODE_ARTIFACT : "cli"
 
-export { version as OPENCODE_VERSION, channel as OPENCODE_CHANNEL }
+export { version as OPENCODE_VERSION, channel as OPENCODE_CHANNEL, artifact as OPENCODE_ARTIFACT }
 export const OPENCODE_LOCAL = channel === "local"

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/cli/test/acp/subprocess.ts

@@ -179,7 +179,7 @@ function verifierConfig(llmUrl: string, skills?: string) {
     limit: { context: 100_000, output: 10_000 },
   }
   return {
-    autoupdate: false,
+    update: "disable",
     model: "test/test-model",
     ...(skills ? { skills: [skills] } : {}),
     providers: {

packages/cli/test/fixture/upgrade.ts

@@ -13,6 +13,8 @@ await Effect.runPromise(
   ).pipe(
     Effect.provideService(Updater.Service, {
       check: () => Effect.die("Manual upgrades must not run the automatic update check"),
+      monitor: () => Effect.die("Manual upgrades must not monitor automatic updates"),
+      apply: () => Effect.die("Manual upgrades must not apply automatic updates"),
       method: () =>
         Effect.sync(() => {
           record("method")

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

@@ -1,7 +1,7 @@
 import { NodeServices } from "@effect/platform-node"
 import { Global } from "@opencode-ai/util/global"
 import { AppProcess } from "@opencode-ai/util/process"
-import { expect, test } from "bun:test"
+import { expect, spyOn, test } from "bun:test"
 import { Effect, FileSystem, Stream } from "effect"
 import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process"
 import { existsSync } from "node:fs"
@@ -17,11 +17,29 @@ function fixture(
   respond: (command: ChildProcess.StandardCommand) => Partial<AppProcess.RunResult> & {
     error?: AppProcess.AppProcessError
   } = () => ({}),
+  name = "@opencode-ai/cli",
 ) {
   return Effect.gen(function* () {
     const fs = yield* FileSystem.FileSystem
     const spawner = yield* ChildProcessSpawner.ChildProcessSpawner
     const root = yield* fs.makeTempDirectoryScoped({ prefix: "opencode-updater-" })
+    const executable = path.join(root, "package", "bin", "opencode")
+    yield* fs.makeDirectory(path.dirname(executable), { recursive: true })
+    yield* fs.writeFileString(
+      path.join(root, "package", "package.json"),
+      JSON.stringify({ name, bin: { opencode: "bin/opencode" } }),
+    )
+    // The updater uses global fetch; scope this replacement to each install test.
+    yield* Effect.acquireRelease(
+      Effect.sync(() =>
+        spyOn(globalThis, "fetch").mockImplementation(
+          Object.assign(async () => Response.json({ version: "2.3.4", metadata: { package: name } }), {
+            preconnect: fetch.preconnect,
+          }),
+        ),
+      ),
+      (request) => Effect.sync(() => request.mockRestore()),
+    )
     const global = Global.make({
       home: path.join(root, "home"),
       data: path.join(root, "data"),
@@ -37,6 +55,10 @@ function fixture(
     const updater = yield* Updater.Service.pipe(
       Effect.provide(Updater.layer),
       Effect.provideService(Global.Service, global),
+      Effect.provideService(FileSystem.FileSystem, {
+        ...fs,
+        realPath: (input) => (input === process.execPath ? Effect.succeed(executable) : fs.realPath(input)),
+      }),
       Effect.provideService(
         AppProcess.Service,
         AppProcess.Service.of({
@@ -214,9 +236,12 @@ test("Node distribution honors the compile-time CLI name", async () => {
 if (typeof OPENCODE_CLI_NAME === "string" && OPENCODE_CLI_NAME === "opencode2-node") {
   it.live("Node distribution resolves the published npm package", () =>
     Effect.gen(function* () {
-      const test = yield* fixture((command) => ({
-        stdout: Buffer.from(command.command === "npm" ? "opencode-node@2.3.4" : ""),
-      }))
+      const test = yield* fixture(
+        (command) => ({
+          stdout: Buffer.from(command.command === "npm" ? "opencode-node@2.3.4" : ""),
+        }),
+        "opencode-node",
+      )
       expect(yield* test.updater.method()).toBe("npm")
       yield* test.updater.upgrade("npm", "v2.3.4")
       yield* test.updater.upgrade("pnpm", "v2.3.4")

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

@@ -0,0 +1,107 @@
+import { expect } from "bun:test"
+import { Deferred, Effect, Layer, Option } from "effect"
+import { testEffect } from "../../core/test/lib/effect"
+import { Updater } from "../src/services/updater"
+
+const it = testEffect(Layer.empty)
+
+it.live("installs and restarts after the final Session settles", () =>
+  Effect.gen(function* () {
+    const fixture = yield* Effect.acquireRelease(Effect.sync(makeServer), (server) => Effect.sync(() => server.stop()))
+    const installed = yield* Deferred.make<string>()
+    const restarted = yield* Deferred.make<void>()
+    yield* Updater.monitorServer({
+      url: fixture.url,
+      password: "test",
+      managed: true,
+      inspect: () => Effect.succeed({ action: "upgrade", version: "1.1.0" }),
+      install: (version) => Deferred.succeed(installed, version).pipe(Effect.as(true)),
+      restart: () => Deferred.succeed(restarted, undefined).pipe(Effect.asVoid),
+      notify: () => Effect.void,
+    }).pipe(Effect.forkScoped)
+    yield* wait(fixture.activeRead, () => "Updater did not check active Sessions")
+    yield* wait(fixture.eventOpened, () => "Updater did not open the server event stream")
+    expect(Option.isNone(yield* Deferred.poll(installed))).toBe(true)
+
+    fixture.settle()
+    yield* wait(fixture.waited, () => "Updater did not receive the settlement event")
+    expect(
+      yield* Effect.raceFirst(
+        Deferred.await(installed),
+        Effect.sleep("1 second").pipe(Effect.andThen(Effect.fail(new Error("Updater did not install the update")))),
+      ),
+    ).toBe("1.1.0")
+    yield* Effect.raceFirst(
+      Deferred.await(restarted),
+      Effect.sleep("1 second").pipe(Effect.andThen(Effect.fail(new Error("Updater did not restart the server")))),
+    )
+  }),
+)
+
+const wait = (promise: Promise<unknown>, message: () => string) =>
+  Effect.tryPromise(() => Promise.race([promise, Bun.sleep(1_000).then(() => Promise.reject(new Error(message())))]))
+
+function makeServer() {
+  const encoder = new TextEncoder()
+  const activeRead = Promise.withResolvers<void>()
+  const eventOpened = Promise.withResolvers<void>()
+  const waited = Promise.withResolvers<void>()
+  let active = true
+  let events: ReadableStreamDefaultController<Uint8Array> | undefined
+  const server = Bun.serve({
+    hostname: "127.0.0.1",
+    port: 0,
+    fetch(request) {
+      const url = new URL(request.url)
+      if (url.pathname === "/api/session/active") {
+        activeRead.resolve()
+        return Response.json({ data: active ? { ses_test: { type: "running" } } : {} })
+      }
+      if (url.pathname === "/api/session/ses_test/wait" && request.method === "POST") {
+        waited.resolve()
+        return new Response(null, { status: 204 })
+      }
+      if (url.pathname === "/api/experimental/persistent-pty/handoff" && request.method === "POST") {
+        return Response.json({ handoff: null })
+      }
+      if (url.pathname === "/api/event") {
+        return new Response(
+          new ReadableStream<Uint8Array>({
+            start(controller) {
+              events = controller
+              eventOpened.resolve()
+            },
+          }),
+          { headers: { "content-type": "text/event-stream" } },
+        )
+      }
+      return new Response("Not found", { status: 404 })
+    },
+  })
+
+  return {
+    url: server.url.origin,
+    activeRead: activeRead.promise,
+    eventOpened: eventOpened.promise,
+    waited: waited.promise,
+    settle() {
+      active = false
+      events?.enqueue(
+        encoder.encode(
+          `data: ${JSON.stringify({
+            id: "evt_settled",
+            created: Date.now(),
+            type: "session.execution.succeeded",
+            durable: { aggregateID: "ses_test", seq: 0, version: 1 },
+            data: { sessionID: "ses_test" },
+          })}\n\n`,
+        ),
+      )
+      events?.close()
+      events = undefined
+    },
+    stop() {
+      server.stop(true)
+    },
+  }
+}

packages/cli/vite.node.config.ts

@@ -268,6 +268,7 @@ export function mainConfig(input: NodeBuildInput): UserConfig {
       OPENCODE_VERSION: JSON.stringify(input.version),
       OPENCODE_CLI_NAME: JSON.stringify("opencode2-node"),
       OPENCODE_CHANNEL: JSON.stringify(input.channel),
+      OPENCODE_ARTIFACT: JSON.stringify("cli-node"),
       OPENCODE_LIBC: input.target.platform === "linux" ? JSON.stringify("glibc") : "undefined",
       FFF_LIBC: input.target.platform === "linux" ? JSON.stringify("gnu") : "undefined",
       "process.env.WS_NO_BUFFER_UTIL": JSON.stringify("1"),

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>(
           {
@@ -1620,7 +1634,7 @@ export function make(options: ClientOptions) {
             path: `/api/skill`,
             query: { location: input?.["location"] },
             successStatus: 200,
-            declaredStatuses: [400, 401],
+            declaredStatuses: [400, 401, 500],
             empty: false,
           },
           requestOptions,

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

@@ -985,15 +985,6 @@ export type ReferenceUpdated = {
   data: {}
 }
 
-export type PluginAdded = {
-  id: string
-  created: number
-  metadata?: { [x: string]: any }
-  type: "plugin.added"
-  location?: LocationRef
-  data: { id: string }
-}
-
 export type PluginUpdated = {
   id: string
   created: number
@@ -1892,7 +1883,7 @@ export type ConfigEntry =
         shell?: string
         model?: string | { providerID: string; model: string; variant?: string }
         default_agent?: string
-        autoupdate?: boolean | "notify"
+        update?: "disable" | "notify" | "auto"
         share?: "manual" | "auto" | "disabled"
         enterprise?: { url?: string }
         username?: string
@@ -2299,7 +2290,6 @@ export type V2Event =
   | ReferenceUpdated
   | PermissionAsked
   | PermissionReplied
-  | PluginAdded
   | PluginUpdated
   | ProjectUpdated
   | WorktreeUpdated
@@ -2498,6 +2488,15 @@ export type PermissionNotFoundError = {
 export const isPermissionNotFoundError = (value: unknown): value is PermissionNotFoundError =>
   typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "PermissionNotFoundError"
 
+export type PluginCallbackError = {
+  readonly _tag: "PluginCallbackError"
+  readonly pluginID: string
+  readonly operation: "skill.transform"
+  readonly message: string
+}
+export const isPluginCallbackError = (value: unknown): value is PluginCallbackError =>
+  typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "PluginCallbackError"
+
 export type RpcError = {
   readonly _tag: "RpcError"
   readonly type: string
@@ -2585,6 +2584,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/client/src/solid/data.ts

@@ -83,10 +83,8 @@ type LocationData = {
   agent?: AgentInfo[]
   command?: CommandInfo[]
   integration?: IntegrationInfo[]
-  mcp?: {
-    server?: McpServer[]
-    resource?: McpResource[]
-  }
+  mcpServer?: McpServer[]
+  mcpResource?: McpResource[]
   model?: ModelInfo[]
   provider?: ProviderInfo[]
   reference?: ReferenceInfo[]
@@ -109,7 +107,6 @@ type Store = {
     messageCursor: Record<string, string | undefined>
     messageLoading: Record<string, boolean>
     pending: Record<string, SessionInboxInfo[]>
-    input: Record<string, string[]>
     permission: Record<string, PermissionRequest[]>
     // Pending forms keyed by owner: a session ID or the temporary "global" elicitation sentinel.
     form: Record<string, FormWithLocation[]>
@@ -125,8 +122,8 @@ export function locationKey(location: LocationRef) {
   return JSON.stringify([location.directory, location.workspaceID])
 }
 
-function locationQuery(ref?: LocationRef) {
-  return ref ? { directory: ref.directory, workspace: ref.workspaceID } : undefined
+function locationQuery(ref: LocationRef) {
+  return { directory: ref.directory, workspace: ref.workspaceID }
 }
 
 function formRequestOptions(sessionID: string, ref?: LocationRef) {
@@ -200,7 +197,6 @@ export function createData(config: CreateDataInput) {
       messageCursor: {},
       messageLoading: {},
       pending: {},
-      input: {},
       permission: {},
       form: {},
     },
@@ -233,13 +229,6 @@ export function createData(config: CreateDataInput) {
         sessionID,
         (store.session.pending[sessionID] ?? []).filter((item) => item.id !== inboxID),
       )
-    if (store.session.input[sessionID]?.includes(inboxID))
-      setStore(
-        "session",
-        "input",
-        sessionID,
-        (store.session.input[sessionID] ?? []).filter((id) => id !== inboxID),
-      )
   }
 
   function removePermission(sessionID: string, requestID: string) {
@@ -337,8 +326,8 @@ export function createData(config: CreateDataInput) {
     return request
   }
 
-  // Upsert an admitted inbox item into pending, input, and (for user and
-  // synthetic items) the visible transcript. Used by the inbox.enqueued
+  // Upsert an admitted inbox item into pending and (for user and synthetic
+  // items) the visible transcript. Used by the inbox.enqueued
   // handler and by optimistic admission; the upsert is what reconciles
   // the durable echo with an optimistic placeholder — the durable payload and
   // times replace the client's guess.
@@ -353,8 +342,6 @@ export function createData(config: CreateDataInput) {
         at < 0 ? [...pending, item] : pending.map((entry, index) => (index === at ? item : entry)),
       )
       if (item.type === "compaction") return
-      const input = store.session.input[item.sessionID] ?? []
-      if (!input.includes(item.id)) setStore("session", "input", item.sessionID, [...input, item.id])
       materializeInboxMessage(item)
     })
   }
@@ -403,15 +390,44 @@ export function createData(config: CreateDataInput) {
       index.set(item.id, messages.length)
       messages.push(item)
     },
+    insert(sessionID: string, item: SessionMessageInfo) {
+      message.update(sessionID, (draft, index) => message.append(draft, index, item))
+    },
+    // Streaming events target one assistant message and, within it, the latest part of a kind.
+    // A missing target means the row was never loaded or was evicted; the event is dropped.
+    editAssistant(sessionID: string, messageID: string, fn: (assistant: SessionMessageAssistant) => void) {
+      message.update(sessionID, (draft, index) => {
+        const position = index.get(messageID)
+        const item = position === undefined ? undefined : draft[position]
+        if (item?.type === "assistant") fn(item)
+      })
+    },
+    editTool(sessionID: string, messageID: string, toolID: string, fn: (tool: SessionMessageAssistantTool) => void) {
+      message.editAssistant(sessionID, messageID, (assistant) => {
+        const tool = assistant.content.findLast(
+          (item): item is SessionMessageAssistantTool => item.type === "tool" && item.id === toolID,
+        )
+        if (tool) fn(tool)
+      })
+    },
+    editText(sessionID: string, messageID: string, fn: (text: SessionMessageAssistantText) => void) {
+      message.editAssistant(sessionID, messageID, (assistant) => {
+        const text = assistant.content.findLast((item): item is SessionMessageAssistantText => item.type === "text")
+        if (text) fn(text)
+      })
+    },
+    editReasoning(sessionID: string, messageID: string, fn: (reasoning: SessionMessageAssistantReasoning) => void) {
+      message.editAssistant(sessionID, messageID, (assistant) => {
+        const reasoning = assistant.content.findLast(
+          (item): item is SessionMessageAssistantReasoning => item.type === "reasoning" && !item.time?.completed,
+        )
+        if (reasoning) fn(reasoning)
+      })
+    },
     activeAssistant(messages: SessionMessageInfo[]) {
       const item = messages.findLast((item) => item.type === "assistant" && !item.time.completed)
       return item?.type === "assistant" ? item : undefined
     },
-    assistant(messages: SessionMessageInfo[], index: Map<string, number>, messageID: string) {
-      const position = index.get(messageID)
-      const item = position === undefined ? undefined : messages[position]
-      return item?.type === "assistant" ? item : undefined
-    },
     shell(messages: SessionMessageInfo[], shellID: string) {
       const item = messages.findLast((item) => item.type === "shell" && item.shellID === shellID)
       return item?.type === "shell" ? item : undefined
@@ -420,19 +436,6 @@ export function createData(config: CreateDataInput) {
       const item = messages.findLast((item) => item.type === "compaction" && item.status === "running")
       return item?.type === "compaction" ? item : undefined
     },
-    latestTool(assistant: SessionMessageAssistant | undefined, id?: string) {
-      return assistant?.content.findLast(
-        (item): item is SessionMessageAssistantTool => item.type === "tool" && (id === undefined || item.id === id),
-      )
-    },
-    latestText(assistant: SessionMessageAssistant | undefined) {
-      return assistant?.content.findLast((item): item is SessionMessageAssistantText => item.type === "text")
-    },
-    latestReasoning(assistant: SessionMessageAssistant | undefined) {
-      return assistant?.content.findLast(
-        (item): item is SessionMessageAssistantReasoning => item.type === "reasoning" && !item.time?.completed,
-      )
-    },
     reindex(messages: SessionMessageInfo[], index: Map<string, number>, start: number) {
       for (let position = start; position < messages.length; position++) {
         const item = messages[position]
@@ -510,12 +513,8 @@ export function createData(config: CreateDataInput) {
         delete draft.messageCursor[sessionID]
         delete draft.messageLoading[sessionID]
         delete draft.pending[sessionID]
-        delete draft.input[sessionID]
         if (messages.length) draft.message[sessionID] = messages
-        if (pending.length) {
-          draft.pending[sessionID] = pending
-          draft.input[sessionID] = pending.filter((item) => item.type !== "compaction").map((item) => item.id)
-        }
+        if (pending.length) draft.pending[sessionID] = pending
       }),
     )
   }
@@ -539,7 +538,6 @@ export function createData(config: CreateDataInput) {
         delete draft.messageCursor[sessionID]
         delete draft.messageLoading[sessionID]
         delete draft.pending[sessionID]
-        delete draft.input[sessionID]
         delete draft.permission[sessionID]
         delete draft.form[sessionID]
         for (const [rootID, family] of Object.entries(draft.family)) {
@@ -611,14 +609,12 @@ export function createData(config: CreateDataInput) {
         const previous = store.session.info[event.data.sessionID]?.agent
         if (store.session.info[event.data.sessionID])
           setStore("session", "info", event.data.sessionID, "agent", event.data.agent)
-        message.update(event.data.sessionID, (draft, index) => {
-          message.append(draft, index, {
-            id: messageIDFromEvent(event.id),
-            type: "agent-switched",
-            agent: event.data.agent,
-            previous,
-            time: { created: event.created },
-          })
+        message.insert(event.data.sessionID, {
+          id: messageIDFromEvent(event.id),
+          type: "agent-switched",
+          agent: event.data.agent,
+          previous,
+          time: { created: event.created },
         })
         return
       }
@@ -626,13 +622,11 @@ export function createData(config: CreateDataInput) {
         if (store.session.info[event.data.sessionID])
           setStore("session", "info", event.data.sessionID, "model", event.data.model)
         if (!store.session.message[event.data.sessionID]) return
-        message.update(event.data.sessionID, (draft, index) => {
-          message.append(draft, index, {
-            id: messageIDFromEvent(event.id),
-            type: "model-switched",
-            model: event.data.model,
-            time: { created: event.created },
-          })
+        message.insert(event.data.sessionID, {
+          id: messageIDFromEvent(event.id),
+          type: "model-switched",
+          model: event.data.model,
+          time: { created: event.created },
         })
         void api()
           .session.message({ sessionID: event.data.sessionID, messageID: messageIDFromEvent(event.id) })
@@ -667,16 +661,14 @@ export function createData(config: CreateDataInput) {
           setStore("session", "info", event.data.sessionID, "location", event.data.location)
           if (event.data.projectID) setStore("session", "info", event.data.sessionID, "projectID", event.data.projectID)
           setStore("session", "info", event.data.sessionID, "subpath", event.data.subpath)
-          message.update(event.data.sessionID, (draft, index) => {
-            message.append(draft, index, {
-              id: messageIDFromEvent(event.id),
-              type: "location-switched",
-              location: event.data.location,
-              projectID: event.data.projectID,
-              subpath: event.data.subpath,
-              previous,
-              time: { created: event.created },
-            })
+          message.insert(event.data.sessionID, {
+            id: messageIDFromEvent(event.id),
+            type: "location-switched",
+            location: event.data.location,
+            projectID: event.data.projectID,
+            subpath: event.data.subpath,
+            previous,
+            time: { created: event.created },
           })
         }
         return
@@ -706,7 +698,7 @@ export function createData(config: CreateDataInput) {
         return
       }
       case "session.inbox.delivered": {
-        const admitted = store.session.input[event.data.sessionID]?.includes(event.data.inboxID) ?? false
+        const admitted = result.session.input.has(event.data.sessionID, event.data.inboxID)
         removePending(event.data.sessionID, event.data.inboxID)
         message.update(event.data.sessionID, (draft, index) => {
           const position = index.get(event.data.inboxID)
@@ -750,42 +742,36 @@ export function createData(config: CreateDataInput) {
         // and produce no transcript message.
         const updateText = event.data.text
         if (updateText === undefined) return
-        message.update(event.data.sessionID, (draft, index) => {
-          message.append(draft, index, {
-            id: messageIDFromEvent(event.id),
-            type: "system",
-            text: updateText,
-            description: `Instructions updated: ${Object.keys(event.data.delta).join(", ")}`,
-            metadata: event.metadata,
-            time: { created: event.created },
-          })
+        message.insert(event.data.sessionID, {
+          id: messageIDFromEvent(event.id),
+          type: "system",
+          text: updateText,
+          description: `Instructions updated: ${Object.keys(event.data.delta).join(", ")}`,
+          metadata: event.metadata,
+          time: { created: event.created },
         })
         return
       case "session.synthetic":
-        message.update(event.data.sessionID, (draft, index) => {
-          message.append(draft, index, {
-            id: messageIDFromEvent(event.id),
-            type: "synthetic",
-            text: event.data.text,
-            description: event.data.description,
-            metadata: event.data.metadata,
-            time: { created: event.created },
-          })
+        message.insert(event.data.sessionID, {
+          id: messageIDFromEvent(event.id),
+          type: "synthetic",
+          text: event.data.text,
+          description: event.data.description,
+          metadata: event.data.metadata,
+          time: { created: event.created },
         })
         return
       case "session.shell.started":
-        message.update(event.data.sessionID, (draft, index) => {
-          message.append(draft, index, {
-            id: messageIDFromEvent(event.id),
-            type: "shell",
-            shellID: event.data.shell.id,
-            command: event.data.shell.command,
-            status: event.data.shell.status,
-            exit: event.data.shell.exit,
-            metadata:
-              event.data.shell.metadata.background === true ? { ...event.metadata, background: true } : event.metadata,
-            time: { created: event.created },
-          })
+        message.insert(event.data.sessionID, {
+          id: messageIDFromEvent(event.id),
+          type: "shell",
+          shellID: event.data.shell.id,
+          command: event.data.shell.command,
+          status: event.data.shell.status,
+          exit: event.data.shell.exit,
+          metadata:
+            event.data.shell.metadata.background === true ? { ...event.metadata, background: true } : event.metadata,
+          time: { created: event.created },
         })
         return
       case "session.shell.ended":
@@ -800,9 +786,8 @@ export function createData(config: CreateDataInput) {
         return
       case "session.message.content.updated": {
         if (store.session.message[event.data.sessionID])
-          message.update(event.data.sessionID, (draft, index) => {
-            const assistant = message.assistant(draft, index, event.data.messageID)
-            if (assistant) assistant.content = [...event.data.content]
+          message.editAssistant(event.data.sessionID, event.data.messageID, (assistant) => {
+            assistant.content = [...event.data.content]
           })
         if (!sync.pending(`session.message:${event.data.sessionID}`)) return
         result.session.message.invalidate(event.data.sessionID)
@@ -844,65 +829,54 @@ export function createData(config: CreateDataInput) {
         })
         return
       case "session.step.streamed":
-        message.update(event.data.sessionID, (draft, index) => {
-          const currentAssistant = message.assistant(draft, index, event.data.assistantMessageID)
-          if (currentAssistant) currentAssistant.time.streamed = event.created
+        message.editAssistant(event.data.sessionID, event.data.assistantMessageID, (assistant) => {
+          assistant.time.streamed = event.created
         })
         return
       case "session.step.ended": {
-        message.update(event.data.sessionID, (draft, index) => {
-          const currentAssistant = message.assistant(draft, index, event.data.assistantMessageID)
-          if (!currentAssistant) return
-          currentAssistant.time.completed = event.created
-          currentAssistant.finish = event.data.finish
-          currentAssistant.rawFinish = event.data.rawFinish
-          currentAssistant.providerState = event.data.providerState
-          currentAssistant.cost = event.data.cost
-          currentAssistant.tokens = event.data.tokens
-          if (event.data.snapshot)
-            currentAssistant.snapshot = { ...currentAssistant.snapshot, end: event.data.snapshot }
+        message.editAssistant(event.data.sessionID, event.data.assistantMessageID, (assistant) => {
+          assistant.time.completed = event.created
+          assistant.finish = event.data.finish
+          assistant.rawFinish = event.data.rawFinish
+          assistant.providerState = event.data.providerState
+          assistant.cost = event.data.cost
+          assistant.tokens = event.data.tokens
+          if (event.data.snapshot) assistant.snapshot = { ...assistant.snapshot, end: event.data.snapshot }
         })
         return
       }
       case "session.step.failed":
-        message.update(event.data.sessionID, (draft, index) => {
-          const currentAssistant = message.assistant(draft, index, event.data.assistantMessageID)
-          if (!currentAssistant) return
-          currentAssistant.time.completed = event.created
-          currentAssistant.finish = event.data.finish ?? "error"
-          currentAssistant.rawFinish = event.data.rawFinish
-          currentAssistant.providerState = event.data.providerState
-          currentAssistant.error = event.data.error
-          currentAssistant.retry = undefined
+        message.editAssistant(event.data.sessionID, event.data.assistantMessageID, (assistant) => {
+          assistant.time.completed = event.created
+          assistant.finish = event.data.finish ?? "error"
+          assistant.rawFinish = event.data.rawFinish
+          assistant.providerState = event.data.providerState
+          assistant.error = event.data.error
+          assistant.retry = undefined
           if (event.data.cost !== undefined && event.data.tokens !== undefined) {
-            currentAssistant.cost = event.data.cost
-            currentAssistant.tokens = event.data.tokens
+            assistant.cost = event.data.cost
+            assistant.tokens = event.data.tokens
           }
         })
         return
       case "session.text.started":
-        message.update(event.data.sessionID, (draft, index) => {
-          message.assistant(draft, index, event.data.assistantMessageID)?.content.push({
-            type: "text",
-            text: "",
-          })
+        message.editAssistant(event.data.sessionID, event.data.assistantMessageID, (assistant) => {
+          assistant.content.push({ type: "text", text: "" })
         })
         return
       case "session.text.delta":
-        message.update(event.data.sessionID, (draft, index) => {
-          const match = message.latestText(message.assistant(draft, index, event.data.assistantMessageID))
-          if (match) match.text += event.data.delta
+        message.editText(event.data.sessionID, event.data.assistantMessageID, (text) => {
+          text.text += event.data.delta
         })
         return
       case "session.text.ended":
-        message.update(event.data.sessionID, (draft, index) => {
-          const match = message.latestText(message.assistant(draft, index, event.data.assistantMessageID))
-          if (match) match.text = event.data.text
+        message.editText(event.data.sessionID, event.data.assistantMessageID, (text) => {
+          text.text = event.data.text
         })
         return
       case "session.tool.input.started":
-        message.update(event.data.sessionID, (draft, index) => {
-          message.assistant(draft, index, event.data.assistantMessageID)?.content.push({
+        message.editAssistant(event.data.sessionID, event.data.assistantMessageID, (assistant) => {
+          assistant.content.push({
             type: "tool",
             id: event.data.id,
             name: event.data.name,
@@ -912,86 +886,60 @@ export function createData(config: CreateDataInput) {
         })
         return
       case "session.tool.input.delta":
-        message.update(event.data.sessionID, (draft, index) => {
-          const match = message.latestTool(
-            message.assistant(draft, index, event.data.assistantMessageID),
-            event.data.id,
-          )
-          if (match?.state.status === "streaming") match.state.input += event.data.delta
+        message.editTool(event.data.sessionID, event.data.assistantMessageID, event.data.id, (tool) => {
+          if (tool.state.status === "streaming") tool.state.input += event.data.delta
         })
         return
       case "session.tool.input.ended":
-        message.update(event.data.sessionID, (draft, index) => {
-          const match = message.latestTool(
-            message.assistant(draft, index, event.data.assistantMessageID),
-            event.data.id,
-          )
-          if (match?.state.status === "streaming") match.state.input = event.data.text
+        message.editTool(event.data.sessionID, event.data.assistantMessageID, event.data.id, (tool) => {
+          if (tool.state.status === "streaming") tool.state.input = event.data.text
         })
         return
       case "session.tool.called":
-        message.update(event.data.sessionID, (draft, index) => {
-          const match = message.latestTool(
-            message.assistant(draft, index, event.data.assistantMessageID),
-            event.data.id,
-          )
-          if (!match) return
-          match.time.ran = event.created
-          match.executed = event.data.executed
-          match.providerState = event.data.state
-          match.state = { status: "running", input: event.data.input, metadata: {} }
+        message.editTool(event.data.sessionID, event.data.assistantMessageID, event.data.id, (tool) => {
+          tool.time.ran = event.created
+          tool.executed = event.data.executed
+          tool.providerState = event.data.state
+          tool.state = { status: "running", input: event.data.input, metadata: {} }
         })
         return
       case "session.tool.progress":
-        message.update(event.data.sessionID, (draft, index) => {
-          const match = message.latestTool(
-            message.assistant(draft, index, event.data.assistantMessageID),
-            event.data.id,
-          )
-          if (match?.state.status !== "running") return
-          match.state.metadata = event.data.metadata
+        message.editTool(event.data.sessionID, event.data.assistantMessageID, event.data.id, (tool) => {
+          if (tool.state.status === "running") tool.state.metadata = event.data.metadata
         })
         return
       case "session.tool.success":
-        message.update(event.data.sessionID, (draft, index) => {
-          const match = message.latestTool(
-            message.assistant(draft, index, event.data.assistantMessageID),
-            event.data.id,
-          )
-          if (match?.state.status !== "running") return
-          match.state = {
+        message.editTool(event.data.sessionID, event.data.assistantMessageID, event.data.id, (tool) => {
+          if (tool.state.status !== "running") return
+          tool.state = {
             status: "completed",
-            input: match.state.input,
+            input: tool.state.input,
             metadata: event.data.metadata,
             content: [...event.data.content],
           }
-          match.executed = event.data.executed || match.executed === true
-          match.providerResultState = event.data.resultState
-          match.time.completed = event.created
+          tool.executed = event.data.executed || tool.executed === true
+          tool.providerResultState = event.data.resultState
+          tool.time.completed = event.created
         })
         return
       case "session.tool.failed":
-        message.update(event.data.sessionID, (draft, index) => {
-          const match = message.latestTool(
-            message.assistant(draft, index, event.data.assistantMessageID),
-            event.data.id,
-          )
-          if (!match || (match.state.status !== "streaming" && match.state.status !== "running")) return
-          match.state = {
+        message.editTool(event.data.sessionID, event.data.assistantMessageID, event.data.id, (tool) => {
+          if (tool.state.status !== "streaming" && tool.state.status !== "running") return
+          tool.state = {
             status: "error",
             error: event.data.error,
-            input: typeof match.state.input === "string" ? {} : match.state.input,
+            input: typeof tool.state.input === "string" ? {} : tool.state.input,
             metadata: event.data.metadata,
             content: event.data.content,
           }
-          match.executed = event.data.executed || match.executed === true
-          match.providerResultState = event.data.resultState
-          match.time.completed = event.created
+          tool.executed = event.data.executed || tool.executed === true
+          tool.providerResultState = event.data.resultState
+          tool.time.completed = event.created
         })
         return
       case "session.reasoning.started":
-        message.update(event.data.sessionID, (draft, index) => {
-          message.assistant(draft, index, event.data.assistantMessageID)?.content.push({
+        message.editAssistant(event.data.sessionID, event.data.assistantMessageID, (assistant) => {
+          assistant.content.push({
             type: "reasoning",
             text: "",
             state: event.data.state,
@@ -1000,30 +948,20 @@ export function createData(config: CreateDataInput) {
         })
         return
       case "session.reasoning.delta":
-        message.update(event.data.sessionID, (draft, index) => {
-          const match = message.latestReasoning(message.assistant(draft, index, event.data.assistantMessageID))
-          if (match) match.text += event.data.delta
+        message.editReasoning(event.data.sessionID, event.data.assistantMessageID, (reasoning) => {
+          reasoning.text += event.data.delta
         })
         return
       case "session.reasoning.ended":
-        message.update(event.data.sessionID, (draft, index) => {
-          const match = message.latestReasoning(message.assistant(draft, index, event.data.assistantMessageID))
-          if (match) {
-            match.text = event.data.text
-            match.time = { created: match.time?.created ?? event.created, completed: event.created }
-            if (event.data.state !== undefined) match.state = event.data.state
-          }
+        message.editReasoning(event.data.sessionID, event.data.assistantMessageID, (reasoning) => {
+          reasoning.text = event.data.text
+          reasoning.time = { created: reasoning.time?.created ?? event.created, completed: event.created }
+          if (event.data.state !== undefined) reasoning.state = event.data.state
         })
         return
       case "session.retry.scheduled":
-        message.update(event.data.sessionID, (draft, index) => {
-          const currentAssistant = message.assistant(draft, index, event.data.assistantMessageID)
-          if (!currentAssistant) return
-          currentAssistant.retry = {
-            attempt: event.data.attempt,
-            at: event.data.at,
-            error: event.data.error,
-          }
+        message.editAssistant(event.data.sessionID, event.data.assistantMessageID, (assistant) => {
+          assistant.retry = { attempt: event.data.attempt, at: event.data.at, error: event.data.error }
         })
         return
       case "session.execution.started":
@@ -1031,16 +969,14 @@ export function createData(config: CreateDataInput) {
         return
       case "session.compaction.started":
         if (event.data.inputID) removePending(event.data.sessionID, event.data.inputID)
-        message.update(event.data.sessionID, (draft, index) => {
-          message.append(draft, index, {
-            id: event.data.inputID ?? messageIDFromEvent(event.id),
-            type: "compaction",
-            status: "running",
-            reason: event.data.reason,
-            summary: "",
-            recent: event.data.recent ?? "",
-            time: { created: event.created },
-          })
+        message.insert(event.data.sessionID, {
+          id: event.data.inputID ?? messageIDFromEvent(event.id),
+          type: "compaction",
+          status: "running",
+          reason: event.data.reason,
+          summary: "",
+          recent: event.data.recent ?? "",
+          time: { created: event.created },
         })
         if (event.data.inputID) compacting.get(event.data.sessionID)?.observed.add(event.data.inputID)
         return
@@ -1075,11 +1011,12 @@ export function createData(config: CreateDataInput) {
         if (store.session.info[event.data.sessionID]) {
           setStore("session", "info", event.data.sessionID, "revert", undefined)
         }
+        // The projector also deletes inbox items enqueued at or after the boundary without a cancel event.
         setStore(
           "session",
-          "input",
+          "pending",
           event.data.sessionID,
-          (store.session.input[event.data.sessionID] ?? []).filter((id) => id < event.data.to),
+          (store.session.pending[event.data.sessionID] ?? []).filter((item) => item.id < event.data.to),
         )
         message.update(event.data.sessionID, (draft, index) => {
           const position = draft.findIndex((item) => item.id >= event.data.to)
@@ -1243,8 +1180,8 @@ export function createData(config: CreateDataInput) {
         }))
         break
       case "reference.updated":
-        result.location.reference.invalidate()
-        void result.location.reference.sync()
+        result.location.reference.invalidate(location)
+        void result.location.reference.sync(location)
         break
       case "integration.updated":
         result.location.integration.invalidate(location)
@@ -1273,6 +1210,41 @@ export function createData(config: CreateDataInput) {
     }
   }
 
+  // A cached per-location catalog. `sync` loads once per invalidation, keyed by the
+  // effective location, and publishes under the server's canonical location; `alias`
+  // also publishes under the requested key when the two differ.
+  function locationResource<Field extends keyof LocationData>(
+    field: Field,
+    load: (location: ReturnType<typeof locationQuery>) => Promise<{ location: LocationRef; data: LocationData[Field] }>,
+    options?: { alias?: boolean },
+  ) {
+    const publish = (key: string, value: LocationData[Field]) => setStore("location", key, { [field]: value })
+    return {
+      list: (ref?: LocationRef) => store.location[locationKey(ref ?? defaultLocation())]?.[field],
+      sync: (ref?: LocationRef) => {
+        const location = ref ?? defaultLocation()
+        const id = locationKey(location)
+        return sync.run(`location.${field}:${id}`, async () => {
+          const response = await load(locationQuery(location))
+          const key = locationKey(response.location)
+          publish(key, response.data)
+          if (options?.alias && key !== id) publish(id, response.data)
+        })
+      },
+      invalidate: (ref?: LocationRef) => sync.invalidate(`location.${field}:${locationKey(ref ?? defaultLocation())}`),
+    }
+  }
+
+  const vcs = locationResource("vcs", (location) => api().vcs.get({ location }))
+  const shells = locationResource("shell", async (location) => {
+    const response = await api().shell.list({ location })
+    const ref = { directory: response.location.directory, workspaceID: response.location.workspaceID }
+    return {
+      location: response.location,
+      data: Object.fromEntries(response.data.map((info) => [info.id, { ...info, location: ref }])),
+    }
+  })
+
   const result = {
     on: config.event.on,
     listen: config.event.listen,
@@ -1321,12 +1293,17 @@ export function createData(config: CreateDataInput) {
       status(sessionID: string) {
         return store.session.active[sessionID] ?? "idle"
       },
+      // Inputs are the pending user and synthetic items; compactions are control items.
       input: {
         list(sessionID: string) {
-          return store.session.input[sessionID] ?? []
+          return (store.session.pending[sessionID] ?? []).flatMap((item) =>
+            item.type === "compaction" ? [] : [item.id],
+          )
         },
         has(sessionID: string, inboxID: string) {
-          return store.session.input[sessionID]?.includes(inboxID) ?? false
+          return (
+            store.session.pending[sessionID]?.some((item) => item.id === inboxID && item.type !== "compaction") ?? false
+          )
         },
       },
       pending: {
@@ -1350,12 +1327,6 @@ export function createData(config: CreateDataInput) {
             const merged = inflight.length === 0 ? pending : [...pending, ...inflight]
             batch(() => {
               setStore("session", "pending", sessionID, reconcile(merged))
-              setStore(
-                "session",
-                "input",
-                sessionID,
-                reconcile(merged.filter((item) => item.type !== "compaction").map((item) => item.id)),
-              )
               merged.forEach(materializeInboxMessage)
             })
           })
@@ -1740,7 +1711,7 @@ export function createData(config: CreateDataInput) {
     },
     shell: {
       list(location?: LocationRef) {
-        return Object.values(store.location[locationKey(location ?? defaultLocation())]?.shell ?? {})
+        return Object.values(shells.list(location) ?? {})
       },
       listBySession(sessionID: string) {
         return Object.values(store.location)
@@ -1752,31 +1723,8 @@ export function createData(config: CreateDataInput) {
           .map((data) => data.shell?.[id])
           .find((shell) => shell !== undefined)
       },
-      sync(ref?: LocationRef) {
-        const id = locationKey(ref ?? defaultLocation())
-        return sync.run(`location.shell:${id}`, async () => {
-          const response = await api().shell.list({ location: locationQuery(ref ?? defaultLocation()) })
-          const key = locationKey(response.location)
-          setStore("location", key, {
-            ...store.location[key],
-            shell: Object.fromEntries(
-              response.data.map((info) => [
-                info.id,
-                {
-                  ...info,
-                  location: {
-                    directory: response.location.directory,
-                    workspaceID: response.location.workspaceID,
-                  },
-                },
-              ]),
-            ),
-          })
-        })
-      },
-      invalidate(ref?: LocationRef) {
-        sync.invalidate(`location.shell:${locationKey(ref ?? defaultLocation())}`)
-      },
+      sync: shells.sync,
+      invalidate: shells.invalidate,
     },
     location: {
       info(ref?: LocationRef) {
@@ -1831,162 +1779,20 @@ export function createData(config: CreateDataInput) {
         result.shell.invalidate(location)
         result.session.form.invalidate("global", location)
       },
-      vcs: {
-        info(location?: LocationRef) {
-          return store.location[locationKey(location ?? defaultLocation())]?.vcs
-        },
-        sync(ref?: LocationRef) {
-          const location = ref ?? defaultLocation()
-          return sync.run(`location.vcs:${locationKey(location)}`, async () => {
-            const response = await api().vcs.get({ location: locationQuery(location) })
-            const key = locationKey(response.location)
-            setStore("location", key, { ...store.location[key], vcs: response.data })
-          })
-        },
-        invalidate(ref?: LocationRef) {
-          sync.invalidate(`location.vcs:${locationKey(ref ?? defaultLocation())}`)
-        },
-      },
-      agent: {
-        list(location?: LocationRef) {
-          return store.location[locationKey(location ?? defaultLocation())]?.agent
-        },
-        sync(ref?: LocationRef) {
-          const id = locationKey(ref ?? defaultLocation())
-          return sync.run(`location.agent:${id}`, async () => {
-            const response = await api().agent.list({ location: locationQuery(ref ?? defaultLocation()) })
-            const key = locationKey(response.location)
-            setStore("location", key, { ...store.location[key], agent: response.data })
-          })
-        },
-        invalidate(ref?: LocationRef) {
-          sync.invalidate(`location.agent:${locationKey(ref ?? defaultLocation())}`)
-        },
-      },
-      command: {
-        list(location?: LocationRef) {
-          return store.location[locationKey(location ?? defaultLocation())]?.command
-        },
-        sync(ref?: LocationRef) {
-          const id = locationKey(ref ?? defaultLocation())
-          return sync.run(`location.command:${id}`, async () => {
-            const response = await api().command.list({ location: locationQuery(ref ?? defaultLocation()) })
-            const key = locationKey(response.location)
-            setStore("location", key, { ...store.location[key], command: response.data })
-          })
-        },
-        invalidate(ref?: LocationRef) {
-          sync.invalidate(`location.command:${locationKey(ref ?? defaultLocation())}`)
-        },
-      },
-      integration: {
-        list(location?: LocationRef) {
-          return store.location[locationKey(location ?? defaultLocation())]?.integration
-        },
-        sync(ref?: LocationRef) {
-          const id = locationKey(ref ?? defaultLocation())
-          return sync.run(`location.integration:${id}`, async () => {
-            const response = await api().integration.list({ location: locationQuery(ref ?? defaultLocation()) })
-            const key = locationKey(response.location)
-            setStore("location", key, { ...store.location[key], integration: response.data })
-          })
-        },
-        invalidate(ref?: LocationRef) {
-          sync.invalidate(`location.integration:${locationKey(ref ?? defaultLocation())}`)
-        },
-      },
+      vcs: { info: vcs.list, sync: vcs.sync, invalidate: vcs.invalidate },
+      agent: locationResource("agent", (location) => api().agent.list({ location })),
+      command: locationResource("command", (location) => api().command.list({ location })),
+      integration: locationResource("integration", (location) => api().integration.list({ location })),
       mcp: {
-        server: {
-          list(location?: LocationRef) {
-            return store.location[locationKey(location ?? defaultLocation())]?.mcp?.server
-          },
-          sync(ref?: LocationRef) {
-            const id = locationKey(ref ?? defaultLocation())
-            return sync.run(`location.mcp.server:${id}`, async () => {
-              const response = await api().mcp.list({ location: locationQuery(ref ?? defaultLocation()) })
-              const key = locationKey(response.location)
-              setStore("location", key, {
-                ...store.location[key],
-                mcp: { ...store.location[key]?.mcp, server: response.data },
-              })
-            })
-          },
-          invalidate(ref?: LocationRef) {
-            sync.invalidate(`location.mcp.server:${locationKey(ref ?? defaultLocation())}`)
-          },
-        },
-        resource: {
-          list(location?: LocationRef) {
-            return store.location[locationKey(location ?? defaultLocation())]?.mcp?.resource
-          },
-          sync(ref?: LocationRef) {
-            const id = locationKey(ref ?? defaultLocation())
-            return sync.run(`location.mcp.resource:${id}`, async () => {
-              const response = await api().mcp.resource.catalog({
-                location: locationQuery(ref ?? defaultLocation()),
-              })
-              const key = locationKey(response.location)
-              setStore("location", key, {
-                ...store.location[key],
-                mcp: { ...store.location[key]?.mcp, resource: response.data.resources },
-              })
-            })
-          },
-          invalidate(ref?: LocationRef) {
-            sync.invalidate(`location.mcp.resource:${locationKey(ref ?? defaultLocation())}`)
-          },
-        },
-      },
-      model: {
-        list(location?: LocationRef) {
-          return store.location[locationKey(location ?? defaultLocation())]?.model
-        },
-        sync(ref?: LocationRef) {
-          const id = locationKey(ref ?? defaultLocation())
-          return sync.run(`location.model:${id}`, async () => {
-            const response = await api().model.list({ location: locationQuery(ref ?? defaultLocation()) })
-            const key = locationKey(response.location)
-            setStore("location", key, { ...store.location[key], model: response.data })
-            if (key !== id) setStore("location", id, { ...store.location[id], model: response.data })
-          })
-        },
-        invalidate(ref?: LocationRef) {
-          sync.invalidate(`location.model:${locationKey(ref ?? defaultLocation())}`)
-        },
-      },
-      provider: {
-        list(location?: LocationRef) {
-          return store.location[locationKey(location ?? defaultLocation())]?.provider
-        },
-        sync(ref?: LocationRef) {
-          const id = locationKey(ref ?? defaultLocation())
-          return sync.run(`location.provider:${id}`, async () => {
-            const response = await api().provider.list({ location: locationQuery(ref ?? defaultLocation()) })
-            const key = locationKey(response.location)
-            setStore("location", key, { ...store.location[key], provider: response.data })
-            if (key !== id) setStore("location", id, { ...store.location[id], provider: response.data })
-          })
-        },
-        invalidate(ref?: LocationRef) {
-          sync.invalidate(`location.provider:${locationKey(ref ?? defaultLocation())}`)
-        },
-      },
-      reference: {
-        list(location?: LocationRef) {
-          return store.location[locationKey(location ?? defaultLocation())]?.reference
-        },
-        sync(ref?: LocationRef) {
-          const id = locationKey(ref ?? defaultLocation())
-          return sync.run(`location.reference:${id}`, async () => {
-            const response = await api().reference.list({ location: locationQuery(ref ?? defaultLocation()) })
-            const key = locationKey(response.location)
-            setStore("location", key, { ...store.location[key], reference: response.data })
-          })
-        },
-        invalidate(ref?: LocationRef) {
-          sync.invalidate(`location.reference:${locationKey(ref ?? defaultLocation())}`)
-        },
+        server: locationResource("mcpServer", (location) => api().mcp.list({ location })),
+        resource: locationResource("mcpResource", async (location) => {
+          const response = await api().mcp.resource.catalog({ location })
+          return { location: response.location, data: response.data.resources }
+        }),
       },
+      model: locationResource("model", (location) => api().model.list({ location }), { alias: true }),
+      provider: locationResource("provider", (location) => api().provider.list({ location }), { alias: true }),
+      reference: locationResource("reference", (location) => api().reference.list({ location })),
       websearch: {
         list(location?: LocationRef) {
           return store.location[locationKey(location ?? defaultLocation())]?.websearch
@@ -2001,22 +1807,7 @@ export function createData(config: CreateDataInput) {
           })
         },
       },
-      skill: {
-        list(location?: LocationRef) {
-          return store.location[locationKey(location ?? defaultLocation())]?.skill
-        },
-        sync(ref?: LocationRef) {
-          const id = locationKey(ref ?? defaultLocation())
-          return sync.run(`location.skill:${id}`, async () => {
-            const response = await api().skill.list({ location: locationQuery(ref ?? defaultLocation()) })
-            const key = locationKey(response.location)
-            setStore("location", key, { ...store.location[key], skill: response.data })
-          })
-        },
-        invalidate(ref?: LocationRef) {
-          sync.invalidate(`location.skill:${locationKey(ref ?? defaultLocation())}`)
-        },
-      },
+      skill: locationResource("skill", (location) => api().skill.list({ location })),
     },
   }
 

packages/client/test/effect.test.ts

@@ -15,6 +15,23 @@ import {
 
 const synced = { type: "log.synced" as const, aggregateID: "ses_test", seq: Event.Seq.make(1) }
 
+test("skill.list decodes a declared plugin callback failure", async () => {
+  const failure = {
+    _tag: "PluginCallbackError",
+    pluginID: "broken-skills",
+    operation: "skill.transform",
+    message: 'Plugin "broken-skills" failed during skill.transform. Check server logs for details.',
+  }
+  const httpClient = HttpClient.make((request) =>
+    Effect.succeed(HttpClientResponse.fromWeb(request, Response.json(failure, { status: 500 }))),
+  )
+  const error = await Effect.gen(function* () {
+    const client = yield* OpenCode.make({ baseUrl: "http://localhost:3000" })
+    return yield* client.skill.list().pipe(Effect.flip)
+  }).pipe(Effect.provideService(HttpClient.HttpClient, httpClient), Effect.runPromise)
+  expect(error).toMatchObject(failure)
+})
+
 test("health.get decodes the readiness response", async () => {
   const httpClient = HttpClient.make((request) =>
     Effect.succeed(HttpClientResponse.fromWeb(request, Response.json({ healthy: true, version: "old", pid: 123 }))),

packages/client/test/promise.test.ts

@@ -1,5 +1,20 @@
 import { expect, test } from "bun:test"
-import { isSessionNotFoundError, isUnauthorizedError, OpenCode } from "../src/promise/index"
+import { isPluginCallbackError, isSessionNotFoundError, isUnauthorizedError, OpenCode } from "../src/promise/index"
+
+test("skill.list preserves a declared plugin callback failure", async () => {
+  const failure = {
+    _tag: "PluginCallbackError",
+    pluginID: "broken-skills",
+    operation: "skill.transform",
+    message: 'Plugin "broken-skills" failed during skill.transform. Check server logs for details.',
+  }
+  const client = OpenCode.make({
+    baseUrl: "http://localhost:3000",
+    fetch: async () => Response.json(failure, { status: 500 }),
+  })
+  await expect(client.skill.list()).rejects.toEqual(failure)
+  expect(isPluginCallbackError(failure)).toBe(true)
+})
 
 test("exposes every standard HTTP API group", () => {
   const client = OpenCode.make({ baseUrl: "http://localhost:3000" })

packages/client/test/solid-data.test.ts

@@ -409,6 +409,66 @@ test("refreshes global credential events across every loaded location and worksp
   }
 })
 
+test("refreshes references for the location an update names", async () => {
+  const listeners = new Set<Parameters<CreateDataInput["event"]["listen"]>[0]>()
+  const requests: URL[] = []
+  const api = OpenCode.make({
+    baseUrl: "http://opencode.local",
+    fetch: async (input, init) => {
+      const request = input instanceof Request ? input : new Request(input, init)
+      const url = new URL(request.url)
+      requests.push(url)
+      const directory = url.searchParams.get("location[directory]") ?? "/project"
+      return Response.json({
+        location: {
+          directory,
+          workspaceID: url.searchParams.get("location[workspace]") ?? undefined,
+          project: { id: "project", directory, canonical: directory },
+        },
+        data: [],
+      })
+    },
+  })
+  const setup = createRoot((dispose) => ({
+    data: createData({
+      api: () => api,
+      directory: "/project",
+      event: {
+        on: () => () => {},
+        listen(handler) {
+          listeners.add(handler)
+          return () => listeners.delete(handler)
+        },
+      },
+      connection: { status: () => "connected" },
+    }),
+    dispose,
+  }))
+  const other = { directory: "/other", workspaceID: "workspace-other" }
+
+  try {
+    await Promise.all([setup.data.location.reference.sync(), setup.data.location.reference.sync(other)])
+    requests.length = 0
+
+    const updated: OpenCodeEvent = {
+      id: "evt_reference.updated",
+      created: 1,
+      type: "reference.updated",
+      location: other,
+      data: {},
+    }
+    listeners.forEach((listener) => listener({ name: updated.type, details: updated }))
+    await wait(() => requests.length === 1)
+    expect([
+      requests[0]!.pathname,
+      requests[0]!.searchParams.get("location[directory]"),
+      requests[0]!.searchParams.get("location[workspace]"),
+    ]).toEqual(["/api/reference", "/other", "workspace-other"])
+  } finally {
+    setup.dispose()
+  }
+})
+
 test("reports optimistic sessions as creating until the request settles", async () => {
   const release = Promise.withResolvers<void>()
   const api = OpenCode.make({

packages/codemode/test/fixtures/opencode-v2-openapi.json

@@ -20378,44 +20378,6 @@
         "required": ["id", "created", "type", "data"],
         "additionalProperties": false
       },
-      "plugin.added": {
-        "type": "object",
-        "properties": {
-          "id": {
-            "type": "string",
-            "allOf": [
-              {
-                "pattern": "^evt_"
-              }
-            ]
-          },
-          "created": {
-            "type": "number"
-          },
-          "metadata": {
-            "type": "object"
-          },
-          "type": {
-            "type": "string",
-            "enum": ["plugin.added"]
-          },
-          "location": {
-            "$ref": "#/components/schemas/Location.Ref"
-          },
-          "data": {
-            "type": "object",
-            "properties": {
-              "id": {
-                "type": "string"
-              }
-            },
-            "required": ["id"],
-            "additionalProperties": false
-          }
-        },
-        "required": ["id", "created", "type", "data"],
-        "additionalProperties": false
-      },
       "plugin.updated": {
         "type": "object",
         "properties": {
@@ -23123,9 +23085,6 @@
           {
             "$ref": "#/components/schemas/permission.v2.replied"
           },
-          {
-            "$ref": "#/components/schemas/plugin.added"
-          },
           {
             "$ref": "#/components/schemas/plugin.updated"
           },

packages/core/package.json

@@ -20,6 +20,7 @@
     "migration": "bun run script/migration.ts",
     "fix-node-pty": "bun run script/fix-node-pty.ts",
     "benchmark:location": "bun run script/benchmark-location.ts",
+    "benchmark:location-memory": "bun run script/benchmark-location-memory.ts",
     "build": "bun run script/build.ts",
     "update-models-snapshot": "bun run script/update-models-snapshot.ts",
     "test": "bun run script/test.ts",

packages/core/script/benchmark-location-memory.ts

@@ -0,0 +1,210 @@
+// Measures the heap retained by Location service graphs and by the models.dev
+// catalog plugin. Everything runs against a temporary global directory with a
+// temporary home, an in-memory database, no filesystem watchers, and no network,
+// so it never touches a live server, database, or user configuration.
+//
+//   bun run script/benchmark-location-memory.ts [--locations 6] [--plugins 8] [--json out.json]
+//
+// "retained" numbers are heapUsed after two forced GCs; "peak" numbers are the
+// highest heapUsed sampled without forcing GC and are reported separately.
+import fs from "fs/promises"
+import os from "os"
+import path from "path"
+import { heapStats } from "bun:jsc"
+import { Effect, Layer, Logger, Scope } from "effect"
+import { Global } from "@opencode-ai/util/global"
+import { LayerNode } from "@opencode-ai/util/effect/layer-node"
+import { AppNodeBuilder } from "../src/effect/app-node-builder"
+import { Bus } from "../src/bus"
+import { Catalog } from "../src/catalog"
+import { Database } from "../src/database/database"
+import { Integration } from "../src/integration"
+import { Location } from "../src/location"
+import { LocationServiceMap } from "../src/location-service-map"
+import { ModelsDev } from "../src/models-dev"
+import { Plugin } from "../src/plugin"
+import { ModelsDevPlugin } from "../src/plugin/models-dev"
+import { AbsolutePath } from "../src/schema"
+import { Watcher } from "../src/filesystem/watcher"
+import { location } from "../test/fixture/location"
+import { catalogHost, host, integrationHost } from "../test/plugin/host"
+
+const args = process.argv.slice(2)
+const flag = (name: string, fallback: number) => {
+  const index = args.indexOf(`--${name}`)
+  if (index === -1) return fallback
+  const value = Number(args[index + 1])
+  if (!Number.isInteger(value) || value < 1) {
+    console.error(`--${name} must be a positive integer`)
+    process.exit(1)
+  }
+  return value
+}
+const locationCount = flag("locations", 6)
+const pluginCount = flag("plugins", 8)
+const jsonIndex = args.indexOf("--json")
+const jsonPath = jsonIndex === -1 ? undefined : args[jsonIndex + 1]
+
+type Sample = { heapUsed: number; rss: number; objects: number }
+
+const sample = (): Sample => {
+  Bun.gc(true)
+  Bun.gc(true)
+  const usage = process.memoryUsage()
+  return { heapUsed: usage.heapUsed, rss: usage.rss, objects: heapStats().objectCount }
+}
+
+const mib = (bytes: number) => (bytes / 1024 / 1024).toFixed(2).padStart(8)
+
+const median = (values: ReadonlyArray<number>) => {
+  const sorted = values.toSorted((a, b) => a - b)
+  const middle = Math.floor(sorted.length / 2)
+  const upper = sorted[middle] ?? 0
+  return sorted.length % 2 === 0 ? ((sorted[middle - 1] ?? 0) + upper) / 2 : upper
+}
+
+const root = await fs.realpath(await fs.mkdtemp(path.join(os.tmpdir(), "opencode-location-memory-")))
+const globalLayer = Global.layerWith({
+  home: path.join(root, "home"),
+  data: path.join(root, "data"),
+  cache: path.join(root, "cache"),
+  config: path.join(root, "config"),
+  state: path.join(root, "state"),
+  tmp: path.join(root, "tmp"),
+  bin: path.join(root, "cache", "bin"),
+  log: path.join(root, "data", "log"),
+  repos: path.join(root, "data", "repos"),
+})
+const replacements = [
+  Global.node.replace(globalLayer),
+  ModelsDev.node.replace(ModelsDev.configured({ fetch: false })),
+  Watcher.node.replace(Watcher.configured({ enabled: false })),
+]
+
+// One full Location graph per directory, retained for the rest of the run, the
+// way a long-running server retains every directory a client has touched.
+const locationsProgram = Effect.gen(function* () {
+  const locations = yield* LocationServiceMap.Service
+  const scope = yield* Scope.Scope
+  const before = sample()
+  const deltas: number[] = []
+  const rss: number[] = []
+  let previous = before
+  for (let index = 0; index < locationCount; index++) {
+    const directory = path.join(root, "projects", `location-${index}`)
+    yield* Effect.promise(() => fs.mkdir(directory, { recursive: true }))
+    const context = yield* locations
+      .contextEffect(Location.Ref.make({ directory: AbsolutePath.make(directory) }))
+      .pipe(Scope.provide(scope))
+    const plugins = yield* Plugin.Service.pipe(Effect.provideContext(context))
+    yield* plugins.awaitActivation
+    const current = sample()
+    deltas.push(current.heapUsed - previous.heapUsed)
+    rss.push(current.rss)
+    previous = current
+  }
+  const catalog = yield* Catalog.Service.pipe(
+    Effect.provideContext(
+      yield* locations
+        .contextEffect(Location.Ref.make({ directory: AbsolutePath.make(path.join(root, "projects", `location-0`)) }))
+        .pipe(Scope.provide(scope)),
+    ),
+  )
+  const models = yield* catalog.model.all()
+  const providers = yield* catalog.provider.all()
+  return {
+    before,
+    after: previous,
+    deltas,
+    rss,
+    catalog: { providers: providers.length, models: models.length },
+  }
+}).pipe(Effect.scoped)
+
+// The models.dev plugin alone, against a real Catalog and Integration state per
+// instance, isolates the catalog-copy contribution from the rest of the graph.
+const pluginProgram = Effect.gen(function* () {
+  const modelsDev = yield* ModelsDev.Service
+  const snapshot = yield* modelsDev.get()
+  const scope = yield* Scope.Scope
+  const before = sample()
+  const deltas: number[] = []
+  let previous = before
+  for (let index = 0; index < pluginCount; index++) {
+    const directory = AbsolutePath.make(path.join(root, "plugins", `instance-${index}`))
+    const locationLayer = Layer.succeed(
+      Location.Service,
+      Location.Service.of(location(Location.Ref.make({ directory }))),
+    )
+    const context = yield* Layer.build(
+      AppNodeBuilder.build(LayerNode.group([Catalog.node, Integration.node, Bus.node]), [
+        Location.node.replace(locationLayer),
+        ...replacements,
+      ]),
+    ).pipe(Scope.provide(scope))
+    const catalog = yield* Catalog.Service.pipe(Effect.provideContext(context))
+    const integration = yield* Integration.Service.pipe(Effect.provideContext(context))
+    yield* ModelsDevPlugin.effect(
+      host({ catalog: catalogHost(catalog), integration: integrationHost(integration) }),
+    ).pipe(Effect.provideService(ModelsDev.Service, modelsDev), Effect.provideContext(context), Scope.provide(scope))
+    yield* catalog.model.all()
+    yield* integration.list()
+    const current = sample()
+    deltas.push(current.heapUsed - previous.heapUsed)
+    previous = current
+  }
+  return {
+    before,
+    after: previous,
+    deltas,
+    snapshot: {
+      providers: snapshot.length,
+      models: snapshot.reduce((total, provider) => total + provider.models.length, 0),
+    },
+  }
+}).pipe(Effect.scoped)
+
+const program = Effect.gen(function* () {
+  const plugin = yield* pluginProgram.pipe(
+    Effect.provide(AppNodeBuilder.build(LayerNode.group([Database.node, Bus.node, ModelsDev.node]), replacements)),
+  )
+  const locations = yield* locationsProgram.pipe(
+    Effect.provide(
+      AppNodeBuilder.build(LayerNode.group([Database.node, Bus.node, LocationServiceMap.node]), replacements),
+    ),
+  )
+  return { plugin, locations }
+}).pipe(Effect.provide(Logger.layer([])))
+
+const result = await Effect.runPromise(program)
+await fs.rm(root, { recursive: true, force: true }).catch(() => undefined)
+
+console.log(
+  `models.dev snapshot: ${result.plugin.snapshot.providers} providers, ${result.plugin.snapshot.models} models`,
+)
+console.log(`ModelsDevPlugin instances: ${pluginCount}`)
+console.log(`  retained heap per instance (MiB): ${result.plugin.deltas.map((delta) => mib(delta).trim()).join(", ")}`)
+console.log(`  median per instance: ${mib(median(result.plugin.deltas))} MiB`)
+console.log(
+  `Location graphs: ${locationCount} (catalog ${result.locations.catalog.providers} providers, ${result.locations.catalog.models} models each)`,
+)
+console.log(
+  `  retained heap per location (MiB): ${result.locations.deltas.map((delta) => mib(delta).trim()).join(", ")}`,
+)
+console.log(`  median per location: ${mib(median(result.locations.deltas))} MiB`)
+console.log(
+  `  heapUsed before ${mib(result.locations.before.heapUsed)} MiB -> after ${mib(result.locations.after.heapUsed)} MiB`,
+)
+console.log(`  rss before ${mib(result.locations.before.rss)} MiB -> after ${mib(result.locations.after.rss)} MiB`)
+
+if (jsonPath) {
+  await fs.mkdir(path.dirname(jsonPath), { recursive: true })
+  await fs.writeFile(
+    jsonPath,
+    JSON.stringify(
+      { revision: process.env.OPENCODE_BENCH_REVISION, bun: Bun.version, locationCount, pluginCount, ...result },
+      null,
+      2,
+    ),
+  )
+}

packages/core/src/agent.ts

@@ -34,7 +34,7 @@ type Data = {
   default?: ID
 }
 
-export type Draft = {
+export type Editor = {
   list: () => readonly Info[]
   get: (id: ID) => Info | undefined
   default: (id: ID | undefined) => void
@@ -42,7 +42,7 @@ export type Draft = {
   remove: (id: ID) => void
 }
 
-export interface Interface extends State.Transformable<Draft> {
+export interface Interface extends State.Transformable<Editor> {
   readonly get: (id: ID) => Effect.Effect<Info | undefined>
   readonly resolve: (id?: ID | string) => Effect.Effect<Info | undefined>
   readonly select: (id?: ID | string) => Effect.Effect<Selection>
@@ -62,32 +62,32 @@ const layer = Layer.effect(
       { action: "external_directory", resource: path.join(global.tmp, "*"), effect: "allow" },
       { action: "external_directory", resource: path.join(global.config, "*"), effect: "allow" },
     ]
-    const state = State.create<Data, Draft>({
+    const state = State.create<Data, Editor>({
       name: "agent",
       initial: () => ({ agents: new Map() }),
-      draft: (draft) => ({
-        list: () => Array.fromIterable(draft.agents.values()) as Info[],
-        get: (id) => draft.agents.get(id),
+      editor: (editor) => ({
+        list: () => Array.fromIterable(editor.agents.values()) as Info[],
+        get: (id) => editor.agents.get(id),
         default: (id) => {
-          draft.default = id
+          editor.default = id
         },
         update: (id, fn) => {
           const defaults = Info.default(id)
           const current =
-            draft.agents.get(id) ??
+            editor.agents.get(id) ??
             ({
               ...defaults,
               permissions: [...defaults.permissions, ...permissions],
             } as Types.DeepMutable<Info>)
-          if (!draft.agents.has(id)) draft.agents.set(id, current)
+          if (!editor.agents.has(id)) editor.agents.set(id, current)
           fn(current)
           current.id = id
         },
         remove: (id) => {
-          draft.agents.delete(id)
+          editor.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

@@ -23,7 +23,7 @@ type Data = {
   defaultModel?: DefaultModel
 }
 
-export type Draft = {
+export type Editor = {
   provider: {
     list: () => readonly ProviderRecord[]
     get: (providerID: Provider.ID) => ProviderRecord | undefined
@@ -41,7 +41,7 @@ export type Draft = {
   }
 }
 
-export interface Interface extends State.Transformable<Draft> {
+export interface Interface extends State.Transformable<Editor> {
   readonly provider: {
     readonly get: (providerID: Provider.ID) => Effect.Effect<Provider.Info | undefined>
     readonly all: () => Effect.Effect<Provider.Info[]>
@@ -82,39 +82,40 @@ const layer = Layer.effect(
       } satisfies Model.Info
     }
 
-    const state = State.create<Data, Draft>({
+    const state = State.create<Data, Editor>({
       name: "catalog",
       initial: () => ({ providers: new Map() }),
-      draft: (draft) => {
-        const result: Draft = {
+      editor: (editor) => {
+        const result: Editor = {
           provider: {
-            list: () => Array.fromIterable(draft.providers.values()) as ProviderRecord[],
-            get: (providerID) => draft.providers.get(providerID),
+            list: () => Array.fromIterable(editor.providers.values()) as ProviderRecord[],
+            get: (providerID) => editor.providers.get(providerID),
             update: (providerID, fn) => {
-              let current = draft.providers.get(providerID)
+              let current = editor.providers.get(providerID)
               if (!current) {
                 current = {
                   provider: Provider.Info.empty(providerID) as Provider.MutableInfo,
                   models: new Map<Model.ID, Model.MutableInfo>(),
                 }
-                draft.providers.set(providerID, current)
+                editor.providers.set(providerID, current)
               }
               fn(current.provider)
+              current.provider.id = providerID
             },
             remove: (providerID) => {
-              draft.providers.delete(providerID)
+              editor.providers.delete(providerID)
             },
           },
           model: {
-            get: (providerID, modelID) => draft.providers.get(providerID)?.models.get(modelID),
+            get: (providerID, modelID) => editor.providers.get(providerID)?.models.get(modelID),
             update: (providerID, modelID, fn) => {
-              let record = draft.providers.get(providerID)
+              let record = editor.providers.get(providerID)
               if (!record) {
                 record = {
                   provider: Provider.Info.empty(providerID) as Provider.MutableInfo,
                   models: new Map<Model.ID, Model.MutableInfo>(),
                 }
-                draft.providers.set(providerID, record)
+                editor.providers.set(providerID, record)
               }
               const model = record.models.get(modelID) ?? (Model.Info.default(providerID, modelID) as Model.MutableInfo)
               if (!record.models.has(modelID)) record.models.set(modelID, model)
@@ -123,21 +124,19 @@ const layer = Layer.effect(
               model.providerID = providerID
             },
             remove: (providerID, modelID) => {
-              draft.providers.get(providerID)?.models.delete(modelID)
+              editor.providers.get(providerID)?.models.delete(modelID)
             },
             default: {
-              get: () => draft.defaultModel,
+              get: () => editor.defaultModel,
               set: (providerID, modelID) => {
-                draft.defaultModel = { providerID, modelID }
+                editor.defaultModel = { providerID, modelID }
               },
             },
           },
         }
         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

@@ -25,7 +25,7 @@ export interface Definition {
   readonly execute: (input: Invocation) => Effect.Effect<void, unknown>
 }
 
-export type Draft = {
+export type Editor = {
   add: (definition: Definition) => void
 }
 
@@ -39,7 +39,7 @@ export class ExecutionError extends Schema.TaggedError<ExecutionError>()("Comman
   message: Schema.String,
 }) {}
 
-export interface Interface extends State.Transformable<Draft> {
+export interface Interface extends State.Transformable<Editor> {
   readonly get: (name: string) => Effect.Effect<Info | undefined>
   readonly list: () => Effect.Effect<Info[]>
   readonly execute: (input: {
@@ -54,13 +54,13 @@ export const layer = Layer.effect(
   Service,
   Effect.gen(function* () {
     const bus = yield* Bus.Service
-    const state = State.create<Map<string, Definition>, Draft>({
+    const state = State.create<Map<string, Definition>, Editor>({
       name: "command",
       initial: () => new Map(),
-      draft: (draft) => ({
-        add: (definition) => draft.set(definition.name, definition),
+      editor: (editor) => ({
+        add: (definition) => editor.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/config.ts

@@ -188,7 +188,15 @@ export const layer = (options?: Options) =>
         const globalDirectory = AbsolutePath.make(global.config)
         const globalAgentsDirectory = AbsolutePath.make(path.join(global.home, ".agents"))
         const globalClaudeDirectory = AbsolutePath.make(path.join(global.home, ".claude"))
-        const locationIsGlobal = path.resolve(location.directory) === path.resolve(global.config)
+        // Global roots and the walk are compared by canonical path: the same
+        // directory reached under two spellings (a symlinked checkout, macOS
+        // /var vs /private/var, OPENCODE_CONFIG_DIR inside the project) must
+        // classify identically or it enters discovery twice.
+        const globalRoots = yield* Effect.forEach(
+          [globalDirectory, globalClaudeDirectory, globalAgentsDirectory],
+          (item) => fs.resolve(item),
+        )
+        const locationIsGlobal = (yield* fs.resolve(location.directory)) === globalRoots[0]
         const discovered =
           locationIsGlobal || options?.project === false
             ? []
@@ -197,22 +205,30 @@ export const layer = (options?: Options) =>
                   targets: [".opencode", ".claude", ".agents", ...names.toReversed()],
                   start: location.directory,
                 })
-                .pipe(Effect.orDie)
+                .pipe(
+                  Effect.flatMap((items) =>
+                    Effect.forEach(items, (item) =>
+                      fs.resolve(item).pipe(Effect.map((resolved) => ({ item, resolved }))),
+                    ),
+                  ),
+                  Effect.orDie,
+                )
 
         const globalEnabled = options?.global !== false
         // A walked path that resolves into a global root is global config
         // however the walk reached it (home above the project, or a location
         // beneath the global config dir), so global: false excludes it
-        // uniformly — classified once here, not per consumer below.
-        const globalRoots = [globalDirectory, globalClaudeDirectory, globalAgentsDirectory].map((item) =>
-          path.resolve(item),
-        )
-        const visible = globalEnabled
-          ? discovered
-          : discovered.filter((item) => {
-              const resolved = path.resolve(item)
-              return !globalRoots.some((root) => resolved === root || resolved.startsWith(root + path.sep))
-            })
+        // uniformly — classified once here, not per consumer below. With
+        // global enabled, the roots themselves and the global config files are
+        // already loaded below, so the walk must not add them a second time.
+        const globalFiles = yield* Effect.forEach(names, (name) => fs.resolve(path.join(globalDirectory, name)))
+        const visible = discovered
+          .filter(({ resolved }) =>
+            globalEnabled
+              ? !globalRoots.includes(resolved) && !globalFiles.includes(resolved)
+              : !globalRoots.some((root) => resolved === root || resolved.startsWith(root + path.sep)),
+          )
+          .map(({ item }) => item)
         // We load certain files from a few other folders in the ecosystem
         const claude = [
           ...new Set([

packages/core/src/config/normalize.ts

@@ -24,6 +24,7 @@ import { ConfigMCPV1 } from "../v1/config/mcp.js"
 import { ConfigPermissionV1 } from "../v1/config/permission.js"
 import { ConfigPluginV1 } from "../v1/config/plugin.js"
 import { ConfigProviderV1 } from "../v1/config/provider.js"
+import { ConfigV1 } from "../v1/config/config.js"
 import { ConfigMigrateV1 } from "../v1/config/migrate.js"
 import { PositiveInt } from "../schema.js"
 
@@ -69,6 +70,9 @@ export function normalize(input: unknown): Result {
   const legacySnapshots = own(input, "snapshot")
     ? decodeEncoded(Schema.Boolean, input.snapshot, ["snapshot"], diagnostics)
     : undefined
+  const legacyUpdate = own(input, "autoupdate")
+    ? decodeValue(ConfigV1.Info.fields.autoupdate, input.autoupdate, ["autoupdate"], diagnostics)
+    : undefined
   const legacyShare = own(input, "autoshare")
     ? decodeValue(Schema.Boolean, input.autoshare, ["autoshare"], diagnostics) === true
       ? "auto"
@@ -82,6 +86,7 @@ export function normalize(input: unknown): Result {
     if (migrated !== undefined) encoded.media = canonical(ConfigMedia.Info, migrated)
   }
   if (legacySnapshots !== undefined) encoded.snapshots = legacySnapshots
+  if (legacyUpdate !== undefined) encoded.update = ConfigMigrateV1.migrate({ autoupdate: legacyUpdate }).update
   if (legacyShare !== undefined) encoded.share = legacyShare
 
   const legacyReferences = decodeMap(input.reference, ConfigReference.Entry, ["reference"], diagnostics, decodeEncoded)
@@ -191,7 +196,7 @@ export function normalize(input: unknown): Result {
     shell: Info.fields.shell,
     model: Info.fields.model,
     default_agent: Info.fields.default_agent,
-    autoupdate: Info.fields.autoupdate,
+    update: Info.fields.update,
     share: Info.fields.share,
     enterprise: Info.fields.enterprise,
     username: Info.fields.username,

packages/core/src/config/plugin/agent.ts

@@ -4,7 +4,7 @@ import { define } from "@opencode-ai/plugin/effect/plugin"
 import { Document, Info, type Entry } from "@opencode-ai/schema/config"
 import { ConfigAgent } from "@opencode-ai/schema/config/agent"
 import path from "path"
-import { Effect, Option, Schema, Stream } from "effect"
+import { Effect, Option, PubSub, Schema, Stream } from "effect"
 import { Agent } from "../../agent.js"
 import { Config } from "../../config.js"
 import { ConfigMarkdown } from "../markdown.js"
@@ -59,42 +59,51 @@ export const Plugin = define({
       Effect.tap((documents) => Effect.sync(() => (loaded.documents = documents))),
       Effect.andThen(ctx.agent.reload()),
     )
-    // One merged trigger stream serializes reloads and shares one debounce
-    // window; subscribing before the initial scan means updates racing the
-    // scan still trigger a rebuild.
-    const sourceChanges = config
-      .changes()
-      .pipe(
-        Stream.filterEffect((update) => Effect.map(config.entries(), (entries) => isAgentSource(entries, update.path))),
-      )
-    const configUpdates = ctx.event.subscribe().pipe(Stream.filter((event) => event.type === "config.updated"))
-    yield* Stream.merge(sourceChanges, configUpdates).pipe(
+    // One trigger feed serializes reloads and shares one debounce window;
+    // subscribing before the initial scan means updates racing the scan still
+    // trigger a rebuild. Each source is subscribed eagerly on its own fiber
+    // (Stream.merge and Stream.debounce both open upstream a fiber hop later)
+    // so no update slips through while the debounce starts its pull.
+    const changes = yield* PubSub.sliding<void>(1)
+    const notify = () => PubSub.publish(changes, undefined)
+    yield* config.changes().pipe(
+      Stream.filterEffect((update) => Effect.map(config.entries(), (entries) => isAgentSource(entries, update.path))),
+      Stream.runForEach(notify),
+      Effect.forkScoped({ startImmediately: true }),
+    )
+    yield* ctx.event.subscribe().pipe(
+      Stream.filter((event) => event.type === "config.updated"),
+      Stream.runForEach(notify),
+      Effect.forkScoped({ startImmediately: true }),
+    )
+    const updates = yield* PubSub.subscribe(changes)
+    yield* Stream.fromSubscription(updates).pipe(
       Stream.debounce("100 millis"),
       Stream.runForEach(() => reload),
       Effect.forkScoped({ startImmediately: true }),
     )
     loaded.documents = yield* load()
-    yield* ctx.agent.transform((draft) => {
+    yield* ctx.agent.transform((editor) => {
       const permissions = expandPermissions(
         loaded.documents.flatMap((document) => document.info.permissions ?? []),
         global.home,
       )
       const configuredDefault = Config.latest(loaded.documents, "default_agent")
-      if (configuredDefault !== undefined) draft.default(Agent.ID.make(configuredDefault))
-      for (const current of draft.list()) {
-        draft.update(current.id, (agent) => agent.permissions.push(...permissions))
+      if (configuredDefault !== undefined) editor.default(Agent.ID.make(configuredDefault))
+      for (const current of editor.list()) {
+        editor.update(current.id, (agent) => agent.permissions.push(...permissions))
       }
 
       for (const document of loaded.documents) {
         for (const [id, item] of Object.entries(document.info.agents ?? {})) {
           const agentID = Agent.ID.make(id)
           if (item.disabled) {
-            draft.remove(agentID)
+            editor.remove(agentID)
             continue
           }
 
-          const exists = draft.get(agentID) !== undefined
-          draft.update(agentID, (agent) => {
+          const exists = editor.get(agentID) !== undefined
+          editor.update(agentID, (agent) => {
             if (!exists) agent.permissions.push(...permissions)
             if (item.model !== undefined)
               agent.model = {

packages/core/src/config/plugin/command.ts

@@ -8,7 +8,7 @@ import { Model } from "@opencode-ai/schema/model"
 import { Provider } from "@opencode-ai/schema/provider"
 import { AppProcess } from "@opencode-ai/util/process"
 import path from "path"
-import { Effect, Option, Schema, Stream } from "effect"
+import { Effect, Option, PubSub, Schema, Stream } from "effect"
 import { ChildProcess } from "effect/unstable/process"
 import { Config } from "../../config.js"
 import { Location } from "../../location.js"
@@ -40,27 +40,34 @@ export const Plugin = define({
       Effect.tap((documents) => Effect.sync(() => (loaded.documents = documents))),
       Effect.andThen(ctx.command.reload()),
     )
-    // One merged trigger stream serializes reloads and shares one debounce
-    // window; subscribing before the initial scan means updates racing the
-    // scan still trigger a rebuild.
-    const sourceChanges = config
-      .changes()
-      .pipe(
-        Stream.filterEffect((update) =>
-          Effect.map(config.entries(), (entries) => isCommandSource(entries, update.path)),
-        ),
-      )
-    const configUpdates = ctx.event.subscribe().pipe(Stream.filter((event) => event.type === "config.updated"))
-    yield* Stream.merge(sourceChanges, configUpdates).pipe(
+    // One trigger feed serializes reloads and shares one debounce window;
+    // subscribing before the initial scan means updates racing the scan still
+    // trigger a rebuild. Each source is subscribed eagerly on its own fiber
+    // (Stream.merge and Stream.debounce both open upstream a fiber hop later)
+    // so no update slips through while the debounce starts its pull.
+    const changes = yield* PubSub.sliding<void>(1)
+    const notify = () => PubSub.publish(changes, undefined)
+    yield* config.changes().pipe(
+      Stream.filterEffect((update) => Effect.map(config.entries(), (entries) => isCommandSource(entries, update.path))),
+      Stream.runForEach(notify),
+      Effect.forkScoped({ startImmediately: true }),
+    )
+    yield* ctx.event.subscribe().pipe(
+      Stream.filter((event) => event.type === "config.updated"),
+      Stream.runForEach(notify),
+      Effect.forkScoped({ startImmediately: true }),
+    )
+    const updates = yield* PubSub.subscribe(changes)
+    yield* Stream.fromSubscription(updates).pipe(
       Stream.debounce("100 millis"),
       Stream.runForEach(() => reload),
       Effect.forkScoped({ startImmediately: true }),
     )
     loaded.documents = yield* load()
-    yield* ctx.command.transform((draft) => {
+    yield* ctx.command.transform((editor) => {
       for (const document of loaded.documents) {
         for (const [name, command] of Object.entries(document.commands ?? {})) {
-          draft.add({
+          editor.add({
             name,
             description: command.description,
             execute: (input) =>

packages/core/src/config/plugin/compaction.ts

@@ -12,10 +12,10 @@ export const Plugin = define({
     const config = yield* Config.Service
     const compaction = yield* SessionCompaction.Service
     const loaded = yield* ConfigEntryObserver.observe(config, ctx.event, compaction.reload())
-    yield* compaction.transform((draft) => {
+    yield* compaction.transform((editor) => {
       for (const entry of loaded.entries) {
         if (entry.type !== "document" || !entry.info.compaction) continue
-        draft.configure({
+        editor.configure({
           ...(entry.info.compaction.auto === undefined ? {} : { auto: entry.info.compaction.auto }),
           ...(entry.info.compaction.buffer === undefined ? {} : { buffer: entry.info.compaction.buffer }),
           ...(entry.info.compaction.keep?.tokens === undefined ? {} : { tokens: entry.info.compaction.keep.tokens }),

packages/core/src/config/plugin/formatter.ts

@@ -24,7 +24,7 @@ export const Plugin = define({
     const processes = yield* AppProcess.Service
     const loaded = yield* ConfigEntryObserver.observe(config, ctx.event, formatter.reload())
 
-    yield* formatter.transform((draft) => {
+    yield* formatter.transform((editor) => {
       const configured = Config.latest(loaded.entries, "formatter")
       if (!configured) return
       const builtIns = make({
@@ -35,12 +35,12 @@ export const Plugin = define({
         processes,
         bin: global.bin,
       })
-      builtIns.forEach(draft.set)
+      builtIns.forEach(editor.set)
       if (configured === true) return
 
       for (const [name, entry] of Object.entries(configured)) {
         if (entry.disabled) {
-          draft.remove(name)
+          editor.remove(name)
           continue
         }
         const builtIn = builtIns.find((formatter) => formatter.name === name)
@@ -51,7 +51,7 @@ export const Plugin = define({
           enabled:
             builtIn && !entry.command ? builtIn.enabled : Effect.succeed(entry.command ? [...entry.command] : false),
         }
-        draft.set(current)
+        editor.set(current)
       }
     })
   }),

packages/core/src/config/plugin/image.ts

@@ -12,12 +12,12 @@ export const Plugin = define({
     const config = yield* Config.Service
     const image = yield* Image.Service
     const loaded = yield* ConfigEntryObserver.observe(config, ctx.event, image.reload())
-    yield* image.transform((draft) => {
+    yield* image.transform((editor) => {
       for (const entry of loaded.entries) {
         if (entry.type !== "document") continue
         const configured = entry.info.media?.image
         if (!configured) continue
-        draft.configure({
+        editor.configure({
           ...(configured.auto_resize === undefined ? {} : { autoResize: configured.auto_resize }),
           ...(configured.max_width === undefined ? {} : { maxWidth: configured.max_width }),
           ...(configured.max_height === undefined ? {} : { maxHeight: configured.max_height }),

packages/core/src/config/plugin/instruction.ts

@@ -103,22 +103,26 @@ export const Plugin = define({
         (effect, ..._args: [file?: string]) => lock.withPermit(effect),
       )
 
-      yield* Stream.fromPubSub(changes).pipe(
+      // Editor saves arrive as bursts of watcher events; settle before rescanning once. Subscribe
+      // before debouncing so no update slips through while the debounce starts its pull.
+      const updates = yield* PubSub.subscribe(changes)
+      yield* Stream.fromSubscription(updates).pipe(
+        Stream.debounce("100 millis"),
         Stream.runForEach((file) => refresh(file).pipe(Effect.andThen(discovery.reload()))),
         Effect.forkScoped({ startImmediately: true }),
       )
       yield* refresh()
-      yield* discovery.transform((draft) => {
+      yield* discovery.transform((editor) => {
         if (loaded.current.type === "unavailable") {
-          draft.unavailable()
+          editor.unavailable()
           return
         }
-        for (const file of loaded.current.files) draft.add(file)
+        for (const file of loaded.current.files) editor.add(file)
       })
     }).pipe(
       Effect.catchCause((cause) =>
         Effect.logWarning("failed to activate instruction source", { cause }).pipe(
-          Effect.andThen(discovery.transform((draft) => draft.unavailable())),
+          Effect.andThen(discovery.transform((editor) => editor.unavailable())),
           Effect.asVoid,
         ),
       ),

packages/core/src/config/plugin/location-watcher.ts

@@ -12,10 +12,10 @@ export const Plugin = define({
     const config = yield* Config.Service
     const policy = yield* LocationWatcherPolicy.Service
     const loaded = yield* ConfigEntryObserver.observe(config, ctx.event, policy.reload())
-    yield* policy.transform((draft) => {
+    yield* policy.transform((editor) => {
       for (const entry of loaded.entries) {
         if (entry.type !== "document" || !entry.info.watcher?.ignore) continue
-        draft.add(entry.info.watcher.ignore)
+        editor.add(entry.info.watcher.ignore)
       }
     })
   }),

packages/core/src/config/plugin/mcp.ts

@@ -36,7 +36,7 @@ export const register = Effect.fn("ConfigMCPPlugin.register")(function* (
 
   // Subscribe before the initial load so updates racing it trigger a rebuild.
   loaded.entries = yield* config.entries()
-  yield* mcp.transform((draft) => {
+  yield* mcp.transform((editor) => {
     const documents = loaded.entries.filter((entry): entry is Document => entry.type === "document")
     // Global timeout defaults merge in config order; each server can override them.
     const timeout = Object.assign(
@@ -50,8 +50,8 @@ export const register = Effect.fn("ConfigMCPPlugin.register")(function* (
       }
     }
     for (const [name, server] of servers) {
-      if (draft.get(name)) continue
-      draft.set(name, { ...server, timeout: { ...timeout, ...server.timeout } })
+      if (editor.get(name)) continue
+      editor.set(name, { ...server, timeout: { ...timeout, ...server.timeout } })
     }
   })
 })

packages/core/src/config/plugin/reference.ts

@@ -19,14 +19,14 @@ export const Plugin = define({
     const location = yield* Location.Service
     const global = yield* Global.Service
     const loaded = yield* ConfigEntryObserver.observe(config, ctx.event, ctx.reference.reload())
-    yield* ctx.reference.transform((draft) => {
+    yield* ctx.reference.transform((editor) => {
       for (const doc of loaded.entries.filter((entry): entry is Document => entry.type === "document")) {
         const directory = doc.path ? path.dirname(doc.path) : location.directory
         for (const [name, entry] of Object.entries(doc.info.references ?? {})) {
           if (!validAlias(name)) continue
           const description = typeof entry === "string" ? undefined : entry.description
           const hidden = typeof entry === "string" ? undefined : entry.hidden
-          draft.add(
+          editor.add(
             name,
             local(entry)
               ? Reference.LocalSource.make({

packages/core/src/config/plugin/shell.ts

@@ -12,9 +12,9 @@ export const Plugin = define({
     const config = yield* Config.Service
     const shell = yield* ShellSelect.Service
     const loaded = yield* ConfigEntryObserver.observe(config, ctx.event, shell.reload())
-    yield* shell.transform((draft) => {
+    yield* shell.transform((editor) => {
       const configured = Config.latest(loaded.entries, "shell")
-      if (configured) draft.configure(configured)
+      if (configured) editor.configure(configured)
     })
   }),
 })

packages/core/src/config/plugin/skill.ts

@@ -171,13 +171,17 @@ export const Plugin = define({
       (effect, ..._args: [file?: string]) => lock.withPermit(effect),
     )
 
-    yield* Stream.fromPubSub(changes).pipe(
+    // Editor saves arrive as bursts of watcher events; settle before rescanning once. Subscribe
+    // before debouncing so no update slips through while the debounce starts its pull.
+    const updates = yield* PubSub.subscribe(changes)
+    yield* Stream.fromSubscription(updates).pipe(
+      Stream.debounce("100 millis"),
       Stream.runForEach((file) => refresh(file).pipe(Effect.andThen(ctx.skill.reload()))),
       Effect.forkScoped({ startImmediately: true }),
     )
     yield* refresh()
-    yield* ctx.skill.transform((draft) => {
-      for (const skill of loaded.skills) draft.add(skill)
+    yield* ctx.skill.transform((editor) => {
+      for (const skill of loaded.skills) editor.add(skill)
     })
     yield* ctx.event.subscribe().pipe(
       Stream.filter((event) => event.type === "config.updated"),

packages/core/src/config/plugin/snapshot.ts

@@ -12,10 +12,10 @@ export const Plugin = define({
     const config = yield* Config.Service
     const snapshot = yield* Snapshot.Service
     const loaded = yield* ConfigEntryObserver.observe(config, ctx.event, snapshot.reload())
-    yield* snapshot.transform((draft) => {
+    yield* snapshot.transform((editor) => {
       const configured = Config.latest(loaded.entries, "snapshots")
       if (configured === undefined) return
-      draft.configure(configured)
+      editor.configure(configured)
     })
   }),
 })

packages/core/src/config/plugin/source.ts

@@ -3,10 +3,11 @@ export * as ConfigPluginSource from "./source.js"
 import { Directory, Document, type Entry } from "@opencode-ai/schema/config"
 import { ConfigPlugin } from "@opencode-ai/schema/config/plugin"
 import { FSUtil } from "@opencode-ai/util/fs-util"
+import { Host } from "@opencode-ai/plugin/host"
 import { makeLocationNode } from "@opencode-ai/util/effect/app-node"
 import { Context, Effect, Layer, Option, PubSub, Scope, Stream } from "effect"
 import path from "path"
-import { fileURLToPath } from "url"
+import { fileURLToPath, pathToFileURL } from "url"
 import { Config } from "../../config.js"
 import { Watcher } from "../../filesystem/watcher.js"
 import { Location } from "../../location.js"
@@ -41,8 +42,8 @@ export const layer = Layer.effect(
     const configuredChanges = yield* PubSub.unbounded<void>()
     const watched = new Set<string>()
 
-    // Configured local plugin entrypoints can live outside config roots, where the
-    // config change feed cannot see them; watch those entrypoints directly.
+    // Configured local plugins can live outside config roots, where the
+    // config change feed cannot see them; watch those targets directly.
     // Watches start on first sighting and are never torn down individually:
     // a stale watch after a config edit costs one deduped fs handle and a
     // no-op activation, and every watch dies with this layer's scope.
@@ -56,7 +57,10 @@ export const layer = Layer.effect(
         // The config change feed already covers {plugin,plugins} directories.
         if (isPluginSource(entries, operation.target)) continue
         watched.add(operation.target)
-        const updates = yield* watcher.subscribe({ path: operation.target, type: "file" })
+        const updates = yield* watcher.subscribe({
+          path: operation.target,
+          type: (yield* fs.isDir(operation.target)) ? "directory" : "file",
+        })
         yield* updates.pipe(
           Stream.runForEach(() => PubSub.publish(configuredChanges, undefined)),
           Effect.catchCause((cause) =>
@@ -148,24 +152,40 @@ const scan = Effect.fn("ConfigPluginSource.scan")(function* (
         yield* Effect.logWarning("configured plugin path must be a directory", { target: operation.target })
         return Option.none<Operation>()
       }
-      if (!(yield* fs.isDir(operation.target))) return Option.some<Operation>(operation)
-      const entrypoint = yield* PluginSourceDirectory.entrypoint(fs, operation.target)
-      if (Option.isSome(entrypoint)) return Option.some<Operation>({ ...operation, target: entrypoint.value })
-      yield* Effect.logWarning("configured plugin directory has no index entrypoint", { target: operation.target })
-      return Option.none<Operation>()
+      return Option.some<Operation>(operation)
     }),
   ).pipe(Effect.map((operations) => operations.flatMap(Option.toArray)))
   // Explicit config is applied last so it can remove auto-discovered packages.
-  return yield* Effect.forEach([...discovered, ...resolved], (operation) => {
-    if (operation.type === "remove" || !path.isAbsolute(operation.target)) return Effect.succeed(operation)
-    return fs.stat(operation.target).pipe(
-      Effect.map((info) => ({
-        ...operation,
-        mtime: Option.getOrElse(info.mtime, () => new Date(0)).getTime(),
-      })),
-      Effect.orElseSucceed(() => operation),
-    )
-  })
+  return yield* Effect.forEach([...discovered, ...resolved], (operation) =>
+    Effect.gen(function* () {
+      if (operation.type === "remove" || !path.isAbsolute(operation.target)) return [operation]
+      if (!(yield* fs.existsSafe(operation.target))) return [operation]
+      const directory = yield* fs.isDir(operation.target)
+      const entrypoints: Host.Entrypoints = directory
+        ? yield* Effect.sync(() => Host.resolve({ directory: operation.target }))
+        : { server: pathToFileURL(operation.target).href }
+      if (!entrypoints.server) return []
+      if (directory) {
+        const root = yield* fs.resolve(operation.target)
+        const server = yield* fs.resolve(fileURLToPath(entrypoints.server))
+        if (!FSUtil.contains(root, server)) return []
+      }
+      const times = yield* Effect.forEach(
+        [
+          ...Object.values(entrypoints)
+            .filter((entry) => entry !== undefined)
+            .map((entry) => fileURLToPath(entry)),
+          path.join(directory ? operation.target : path.dirname(operation.target), "package.json"),
+        ],
+        (entry) =>
+          fs.stat(entry).pipe(
+            Effect.map((info) => Option.getOrElse(info.mtime, () => new Date(0)).getTime()),
+            Effect.orElseSucceed(() => 0),
+          ),
+      )
+      return [{ ...operation, mtime: Math.max(...times) }]
+    }),
+  ).pipe(Effect.map((operations) => operations.flat()))
 })
 
 function isPluginSource(entries: readonly Entry[], file: string) {

packages/core/src/config/plugin/tool-output.ts

@@ -12,10 +12,10 @@ export const Plugin = define({
     const config = yield* Config.Service
     const output = yield* ToolOutput.Service
     const loaded = yield* ConfigEntryObserver.observe(config, ctx.event, output.reload())
-    yield* output.transform((draft) => {
+    yield* output.transform((editor) => {
       const configured = Config.latest(loaded.entries, "tool_output")
       if (!configured) return
-      draft.configure({
+      editor.configure({
         ...(configured.max_lines === undefined ? {} : { maxLines: configured.max_lines }),
         ...(configured.max_bytes === undefined ? {} : { maxBytes: configured.max_bytes }),
       })

packages/core/src/database/database.ts

@@ -2,7 +2,7 @@ export * as Database from "./database.js"
 
 import { EffectDrizzleSqlite } from "./drizzle.js"
 import { sqliteLayer, supportsForeignKeyToggle, supportsTuningPragmas } from "#sqlite"
-import { Context, Effect, Layer, Schema } from "effect"
+import { Context, Effect, Layer, Schema, Semaphore } from "effect"
 import type { SqlClient } from "effect/unstable/sql"
 import { Global } from "@opencode-ai/util/global"
 import { isAbsolute, join } from "path"
@@ -23,30 +23,52 @@ export type Options = typeof Options.Type
 
 export class Service extends Context.Service<Service, Interface>()("@opencode/storage/Database") {}
 
-const databaseLayer = Layer.effect(
-  Service,
-  Effect.gen(function* () {
-    const db = yield* makeDatabase
+// The bootstrap lock is scoped to the database being built, never to this
+// module: on workerd every Durable Object in an isolate shares module state, and
+// releasing a shared semaphore resumes the waiting object's fiber inside the
+// releasing object's I/O context, where its first storage call is rejected as
+// cross-object I/O.
+const databaseLayer = (lock: Effect.Effect<Semaphore.Semaphore>) =>
+  Layer.effect(
+    Service,
+    Effect.gen(function* () {
+      const db = yield* makeDatabase
 
-    if (supportsTuningPragmas) {
-      yield* db.run("PRAGMA journal_mode = WAL")
-      yield* db.run("PRAGMA synchronous = NORMAL")
-      yield* db.run("PRAGMA busy_timeout = 5000")
-      yield* db.run("PRAGMA cache_size = -64000")
-      yield* db.run("PRAGMA wal_checkpoint(PASSIVE)")
-    }
-    // Durable Object SQLite always enforces foreign keys and rejects the pragma.
-    if (supportsForeignKeyToggle) yield* db.run("PRAGMA foreign_keys = ON")
-    yield* DatabaseMigration.apply(db)
+      if (supportsTuningPragmas) {
+        yield* db.run("PRAGMA journal_mode = WAL")
+        yield* db.run("PRAGMA synchronous = NORMAL")
+        yield* db.run("PRAGMA busy_timeout = 5000")
+        yield* db.run("PRAGMA cache_size = -64000")
+        yield* db.run("PRAGMA wal_checkpoint(PASSIVE)")
+      }
+      // Durable Object SQLite always enforces foreign keys and rejects the pragma.
+      if (supportsForeignKeyToggle) yield* db.run("PRAGMA foreign_keys = ON")
+      const semaphore = yield* lock
+      yield* semaphore.withPermit(DatabaseMigration.apply(db))
 
-    return { db }
-  }).pipe(Effect.orDie),
-)
+      return { db }
+    }).pipe(Effect.orDie),
+  )
+
+// Two instances over one file bootstrap the same schema, so file databases
+// share a lock per path. Each in-memory database is its own connection.
+const locks = new Map<string, Semaphore.Semaphore>()
+
+function lockFor(filename: string) {
+  const existing = locks.get(filename)
+  if (existing) return existing
+  const lock = Semaphore.makeUnsafe(1)
+  locks.set(filename, lock)
+  return lock
+}
 
 export function layer(options: Options = { path: ":memory:" }) {
   return Layer.unwrap(
     Effect.gen(function* () {
-      const provide = (filename: string) => layerFromClient.pipe(Layer.provide(sqliteLayer({ filename })))
+      const provide = (filename: string) =>
+        databaseLayer(filename === ":memory:" ? Semaphore.make(1) : Effect.succeed(lockFor(filename))).pipe(
+          Layer.provide(sqliteLayer({ filename })),
+        )
       const filename = options.path ?? ":memory:"
       if (filename === ":memory:" || isAbsolute(filename)) return provide(filename)
       const global = yield* Global.Service
@@ -58,8 +80,11 @@ export function layer(options: Options = { path: ":memory:" }) {
 // The database service over an injected SqlClient, for runtimes that receive
 // database storage instead of opening a filesystem path. Any client provided
 // here still goes through the pragma guards and migrations; Global is required
-// because migrations may read it (the v1 import).
-export const layerFromClient: Layer.Layer<Service, never, SqlClient.SqlClient | Global.Service> = databaseLayer
+// because migrations may read it (the v1 import). The lock is created per build
+// because every Durable Object builds this layer over its own storage.
+export const layerFromClient: Layer.Layer<Service, never, SqlClient.SqlClient | Global.Service> = databaseLayer(
+  Semaphore.make(1),
+)
 
 export function configured(options?: Options) {
   return makeGlobalNode({ service: Service, layer: layer(options), deps: [Global.node] })