feat(ai): add streamed compaction triggers

packages/ai/README.md

@@ -247,6 +247,8 @@ 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.
 
+For `compact(request, { mechanism: "trigger" })`, script a `CompactionCheckpointResponse` instead. It carries `checkpoint`, `responseID`, and optional `usage`. Endpoint and trigger calls reject each other's fixtures; both share the same queue, gates, lazy recording, and fallback controls.
+
 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`.
@@ -259,7 +261,7 @@ This is different from prompt caching, server-side history storage, or truncatio
 
 ### 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.
+`LLMClient.compact(request)` (equivalently, `{ mechanism: "endpoint" }`) 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. This mechanism does not accept a WebSocket executor.
 
 Prefer this operation, where supported, when the application owns compaction policy and durable context updates.
 
@@ -279,6 +281,41 @@ Generation-only body overlays such as `stream` and `store` are not sent to the c
 
 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.
 
+### Streamed checkpoint compaction
+
+OpenAI Responses also exposes a separate, explicitly selected mechanism:
+
+```ts
+const result =
+  yield *
+  LLMClient.compact(request, {
+    mechanism: "trigger",
+    webSocket, // Optional: without it, the request uses HTTP/SSE.
+  })
+
+result.checkpoint // Successful encrypted CompactionPart.
+result.responseID
+result.usage
+```
+
+This appends a native `compaction_trigger` control item to the full input and sends a normal Responses request. It follows the [Codex V2 request shape](https://github.com/openai/codex/blob/728cb12/codex-rs/core/src/compact_remote_v2_attempt.rs), with tools and instructions retained, `stream: true`, `store: false`, and parallel tool calls enabled. It removes normal-answer text/output-format controls, forced tool choices, output-token/tool-call limits, and automatic `context_management`. Body overlays cannot replace `input` or supply `previous_response_id`/`conversation`; the complete canonical history is required for safe stateless replay. Session/cache identifiers, auth, headers, query parameters, service tier, and supported prompt-cache settings are preserved.
+
+Only a successful `response.completed` with a response ID and exactly one logical encrypted checkpoint succeeds. Repeated item events are correlated by ID/output slot, including ID-less checkpoints. Other output is ignored, not returned as assistant text or dispatched as tools. Failed, incomplete, malformed, and interrupted responses return errors rather than partial checkpoints.
+
+The result is **not a replacement window**. The caller selects retained history, combines it with `result.checkpoint`, and durably installs it before continuing. The operation does not choose a retention budget, prune messages, or modify the original request.
+
+The supplied WebSocket executor can reuse a compatible append baseline for the compaction request. On completion the protocol supplies no continuation checkpoint, clearing the old baseline so the next generation sends the newly installed window in full. Validation occurs before transport completion is acknowledged. There is no operation-level retry or fallback to `/responses/compact`; existing safe transport fallback may use SSE, with full history and no connection-local response ID.
+
+Trigger support is separate from endpoint support. Only the OpenAI Responses route advertises it; Azure, xAI, Chat, and compatible Responses routes do not inherit it. Untyped calls still fail before sending: missing route capabilities return `UnsupportedOperation`, while unknown mechanism names and invalid inputs return `InvalidRequest`. Dynamic callers must narrow for the selected mechanism:
+
+```ts
+if (LLMClient.canCompact(request, { mechanism: "trigger" })) {
+  const result = yield * LLMClient.compact(request, { mechanism: "trigger" })
+}
+```
+
+This capability describes protocol implementation, **not universal availability on OpenAI API deployments**. The host application owns subscription/deployment eligibility, OAuth, endpoint selection, and deployment-specific headers. Local protocol/socket tests do not establish live provider support.
+
 ### 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.

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

@@ -42,6 +42,7 @@ const canonical = (value: unknown): string => {
   if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`
   if (!ProviderShared.isRecord(value)) return ProviderShared.encodeJson(value)
   return `{${Object.keys(value)
+    .filter((key) => value[key] !== undefined)
     .sort()
     .map((key) => `${ProviderShared.encodeJson(key)}:${canonical(value[key])}`)
     .join(",")}}`
@@ -149,6 +150,12 @@ export const driver = (input: DriverInput): WebSocketChannelDriver => {
           if (rejection === "websocket_connection_limit_reached") return rejected(observation, "rotate-and-retry-full")
         }
         if (observation.type !== "completed") return observation
+        // A trigger installs a different context window. Clear the append baseline, retaining the socket.
+        if (
+          Array.isArray(request.input) &&
+          request.input.some((item) => ProviderShared.isRecord(item) && item.type === "compaction_trigger")
+        )
+          return observation
         const responseID = event.response?.id
         if (!responseID || responseID.trim().length === 0) return observation
         return {

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

@@ -920,7 +920,7 @@ const joinReasoningText = (parts: ReadonlyArray<string | undefined>) => {
   return parts.filter((part) => part !== undefined).join("\n\n")
 }
 
-const outputItemID = (state: ParserState, event: Event) =>
+const outputItemID = (state: Pick<ParserState, "outputItems">, 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>> = {
@@ -932,7 +932,11 @@ const ITEM_ID_PREFIX: Readonly<Record<string, string>> = {
 
 // 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 => ({
+const resolveItem = (
+  state: Pick<ParserState, "outputItems">,
+  item: StreamItem,
+  index: number | undefined,
+): OutputItem => ({
   ...item,
   id:
     item.id ??
@@ -942,7 +946,7 @@ const resolveItem = (state: ParserState, item: StreamItem, index: number | undef
 
 // 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 => ({
+export const normalize = (state: Pick<ParserState, "outputItems">, 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,

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

@@ -5,7 +5,7 @@ import { Auth } from "../route/auth.js"
 import { Endpoint } from "../route/endpoint.js"
 import { Protocol } from "../route/protocol.js"
 import { HttpTransport } from "../route/transport/index.js"
-import type { LLMRequest, JsonSchema, ToolDefinition } from "../schema/index.js"
+import { LLMRequest, mergeJsonRecords, type JsonSchema, type ToolDefinition } from "../schema/index.js"
 import { OpenResponses } from "./open-responses.js"
 import { JsonObject, optionalArray, optionalNull, ProviderShared } from "./shared.js"
 import { OpenAIImage } from "./utils/openai-image.js"
@@ -13,6 +13,7 @@ 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"
+import { ResponsesCheckpoint } from "./utils/responses-checkpoint.js"
 
 const ADAPTER = "openai-responses"
 const NAME = "OpenAI Responses"
@@ -103,6 +104,18 @@ const OpenAIResponsesBody = Schema.Struct({
 })
 export type OpenAIResponsesBody = Schema.Schema.Type<typeof OpenAIResponsesBody>
 
+/** Request control, never conversation content. */
+export const CompactionTrigger = Schema.Struct({ type: Schema.Literal("compaction_trigger") })
+const CheckpointBody = Schema.Struct({
+  ...OpenAIResponsesBody.fields,
+  input: Schema.Array(Schema.Union([OpenResponses.InputItem, OpenAIResponsesHostedToolItem, CompactionTrigger])),
+  store: Schema.Literal(false),
+  prompt_cache_retention: optionalNull(Schema.String),
+  prompt_cache_options: optionalNull(
+    Schema.Struct({ mode: Schema.optional(Schema.String), ttl: Schema.optional(Schema.String) }),
+  ),
+})
+
 const adapter = {
   id: ADAPTER,
   name: NAME,
@@ -162,6 +175,35 @@ const fromRequest = Effect.fn("OpenAIResponses.fromRequest")(function* (request:
   })
 })
 
+const checkpointBody = {
+  schema: CheckpointBody,
+  from: Effect.fn("OpenAIResponses.checkpointBody")(function* (request: LLMRequest) {
+    const native = yield* fromRequest(LLMRequest.update(request, { toolChoice: undefined }))
+    const overlay = request.http?.body
+    // Complete history is required for stateless replay and SSE recovery. Raw input overrides bypass that contract.
+    if (
+      overlay?.input !== undefined ||
+      overlay?.previous_response_id !== undefined ||
+      overlay?.conversation !== undefined
+    )
+      return yield* ProviderShared.invalidRequest(
+        "Trigger compaction requires complete canonical history, not an input or continuation override",
+      )
+    return yield* ProviderShared.validateWith(Schema.decodeUnknownEffect(CheckpointBody))({
+      ...mergeJsonRecords(native, overlay),
+      input: [...native.input, { type: "compaction_trigger" }],
+      stream: true,
+      store: false,
+      parallel_tool_calls: true,
+      tool_choice: undefined,
+      context_management: undefined,
+      text: undefined,
+      max_output_tokens: undefined,
+      max_tool_calls: undefined,
+    })
+  }),
+}
+
 const hostedToolResult = Effect.fn("OpenAIResponses.hostedToolResult")(function* (item: ResponsesHostedTools.Item) {
   const isError = item.error !== undefined && item.error !== null
   if (item.type === "image_generation_call" && item.result) {
@@ -239,7 +281,7 @@ export const transport = channelTransport({
 })
 
 export const route = Route.make({
-  compact: ResponsesCompaction.make(adapter),
+  compact: { endpoint: ResponsesCompaction.make(adapter), trigger: ResponsesCheckpoint.make(checkpointBody) },
   id: ADAPTER,
   provider: "openai",
   providerMetadataKey: "openai",

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

@@ -0,0 +1,123 @@
+import { Effect, Schema, Stream } from "effect"
+import { Route, type RouteBody, type TriggerCompactOperation } from "../../route/client.js"
+import { Protocol } from "../../route/protocol.js"
+import { CompactionCheckpointResponse, CompactionPart, HttpOptions, LLMEvent, LLMRequest } from "../../schema/index.js"
+import { OpenResponses } from "../open-responses.js"
+import { ProviderShared } from "../shared.js"
+
+interface State {
+  readonly parser: Pick<OpenResponses.ParserState, "id" | "provider" | "outputItems">
+  readonly checkpoints: Readonly<Record<string, CompactionPart>>
+  readonly responseID?: string
+}
+
+const onOutputItem = Effect.fn("ResponsesCheckpoint.onOutputItem")(function* (
+  state: State,
+  input: OpenResponses.Event,
+) {
+  const event = OpenResponses.normalize(state.parser, input)
+  const item = event.item
+  if (!item) return state
+  const parser =
+    event.output_index === undefined
+      ? state.parser
+      : { ...state.parser, outputItems: { ...state.parser.outputItems, [event.output_index]: item.id } }
+  if (event.type === "response.output_item.added" || item.type !== "compaction") return { ...state, parser }
+  if (
+    event.output_index !== undefined &&
+    Object.entries(state.parser.outputItems).some(
+      ([index, id]) => id === item.id && Number(index) !== event.output_index,
+    )
+  )
+    return yield* ProviderShared.eventError(parser.id, "Compaction checkpoint appeared in multiple output slots")
+  if (!item.encrypted_content)
+    return yield* ProviderShared.eventError(parser.id, "Compaction output is missing its encrypted content")
+  const previous = state.checkpoints[item.id]
+  if (previous && previous.encrypted !== item.encrypted_content)
+    return yield* ProviderShared.eventError(parser.id, "Compaction output changed after completion")
+  return {
+    ...state,
+    parser,
+    checkpoints: {
+      ...state.checkpoints,
+      [item.id]: CompactionPart.make({ provider: parser.provider, id: item.id, encrypted: item.encrypted_content }),
+    },
+  }
+})
+
+/** Collect a trigger response before acknowledging transport completion. No generation output escapes. */
+export const make = <Body>(body: RouteBody<Body>): TriggerCompactOperation =>
+  Effect.fn("ResponsesCheckpoint.execute")(function* (request, executor, options) {
+    const source = request.model.route
+    let result: CompactionCheckpointResponse | undefined
+    // Route registries erase the frame type. The codec validates that boundary before parsing.
+    const event: Schema.Codec<OpenResponses.Event, unknown> = OpenResponses.protocol.stream.event
+    const protocol = Protocol.make({
+      id: source.protocol,
+      body,
+      stream: {
+        event,
+        initial: (request: LLMRequest): State => ({
+          parser: { id: source.id, provider: request.model.provider, outputItems: {} },
+          checkpoints: {},
+        }),
+        terminal: OpenResponses.terminal,
+        step: Effect.fn("ResponsesCheckpoint.step")(function* (state: State, event: OpenResponses.Event) {
+          if (event.response?.id && state.responseID && event.response.id !== state.responseID)
+            return yield* ProviderShared.eventError(source.id, "Compaction response ID changed during execution")
+          if (event.type === "response.created") return [{ ...state, responseID: event.response?.id }, []] as const
+          if (event.type === "error" || event.type === "response.failed")
+            return yield* OpenResponses.providerFailure(event, "Compaction request failed")
+          if (event.type === "response.incomplete")
+            return yield* ProviderShared.eventError(source.id, "Compaction response was incomplete")
+          if (event.type === "response.output_item.added" || event.type === "response.output_item.done")
+            return [yield* onOutputItem(state, event), []] as const
+          if (event.type !== "response.completed") return [state, []] as const
+          const responseID = event.response?.id
+          if (!responseID?.trim())
+            return yield* ProviderShared.eventError(source.id, "Compaction response is missing its response ID")
+          if (event.response?.status !== undefined && event.response.status !== "completed")
+            return yield* ProviderShared.eventError(source.id, "Compaction response did not complete successfully")
+          let next = state
+          for (const [index, item] of (event.response?.output ?? []).entries()) {
+            next = yield* onOutputItem(next, { type: "response.output_item.done", output_index: index, item })
+          }
+          const checkpoints = Object.values(next.checkpoints)
+          const checkpoint = checkpoints[0]
+          if (checkpoints.length !== 1 || !checkpoint?.encrypted)
+            return yield* ProviderShared.eventError(
+              source.id,
+              "Compaction response must contain exactly one checkpoint",
+            )
+          result = new CompactionCheckpointResponse({
+            checkpoint: { ...checkpoint, encrypted: checkpoint.encrypted, text: undefined },
+            responseID,
+            usage: OpenResponses.mapUsage(event.response?.usage, OpenResponses.metadataKey(request.model)),
+          })
+          return [next, [LLMEvent.finish({ reason: { normalized: "stop" } })]] as const
+        }),
+      },
+    })
+    const route = Route.make({
+      id: source.id,
+      provider: source.provider,
+      providerMetadataKey: source.providerMetadataKey,
+      protocol,
+      endpoint: source.endpoint,
+      auth: source.auth,
+      transport: source.transport,
+    })
+    const native = yield* body
+      .from(request)
+      .pipe(Effect.flatMap(ProviderShared.validateWith(Schema.decodeUnknownEffect(body.schema))))
+    // The body builder already applied and validated overlays. Do not let transport reapply them.
+    const preparedRequest = LLMRequest.update(request, {
+      http: request.http === undefined ? undefined : new HttpOptions({ ...request.http, body: undefined }),
+    })
+    const prepared = yield* route.prepareTransport(native, preparedRequest, options)
+    yield* route.streamPrepared(prepared, preparedRequest, { http: executor }, options).pipe(Stream.runDrain)
+    if (!result) return yield* ProviderShared.eventError(source.id, "Compaction response ended without a checkpoint")
+    return result
+  })
+
+export * as ResponsesCheckpoint from "./responses-checkpoint.js"

packages/ai/src/provider-package.ts

@@ -1,5 +1,5 @@
 import type { LanguageModel, ProviderOptions } from "./schema/index.js"
-import type { CompactOperation } from "./route/client.js"
+import type { CompactionOperations } from "./route/client.js"
 
 export interface Settings extends Readonly<Record<string, unknown>> {
   readonly baseURL?: string
@@ -10,7 +10,7 @@ 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,
+  Compact extends CompactionOperations | undefined = CompactionOperations | undefined,
 > {
   readonly model: (modelID: string, settings: ProviderSettings) => LanguageModel<Options, Compact>
 }

packages/ai/src/providers/azure.ts

@@ -1,7 +1,7 @@
 import { Headers } from "effect/unstable/http"
 import { Auth } from "../route/auth.js"
 import { type AtLeastOne, type ProviderAuthOption } from "../route/auth-options.js"
-import type { Route, RouteDefaultsInput, CompactOperation } from "../route/client.js"
+import type { Route, RouteDefaultsInput, CompactionOperations } 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"
@@ -39,6 +39,7 @@ export type Settings = ProviderPackage.Settings &
 const resourceBaseURL = (resourceName: string) => `https://${resourceName.trim()}.openai.azure.com/openai`
 
 const responsesRoute = OpenAIResponses.route.with({
+  compact: { endpoint: OpenAIResponses.route.compact.endpoint },
   id: "azure-openai-responses",
   provider: id,
   auth: routeAuth,
@@ -102,7 +103,7 @@ const auth = (input: Config) => {
   )
 }
 
-const configuredRoute = <Body, Prepared, Compact extends CompactOperation | undefined>(
+const configuredRoute = <Body, Prepared, Compact extends CompactionOperations | undefined>(
   route: Route<Body, Prepared, Compact>,
   input: Config,
   modelID: string | ModelID,
@@ -168,7 +169,7 @@ const config = (settings: Settings): Config => {
 export const responsesModel: ProviderPackage.Definition<
   Settings,
   OpenAIProviderOptionsInput,
-  CompactOperation
+  typeof responsesRoute.compact
 >["model"] = (modelID, settings) => configure(config(settings)).responses(modelID)
 export const chatModel: ProviderPackage.Definition<Settings, OpenAIProviderOptionsInput>["model"] = (
   modelID,

packages/ai/src/providers/openai.ts

@@ -1,5 +1,5 @@
 import { AuthOptions, type ProviderAuthOption } from "../route/auth-options.js"
-import type { Route, RouteDefaultsInput, CompactOperation } from "../route/client.js"
+import type { Route, RouteDefaultsInput, CompactionOperations } 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,7 @@ const defaults = (input: Config) => {
   return rest
 }
 
-const configuredRoute = <Body, Prepared, Compact extends CompactOperation | undefined>(
+const configuredRoute = <Body, Prepared, Compact extends CompactionOperations | undefined>(
   route: Route<Body, Prepared, Compact>,
   input: Config,
 ) =>
@@ -132,10 +132,11 @@ const config = (settings: Settings): Config => {
   }
 }
 
-export const model: ProviderPackage.Definition<Settings, OpenAIProviderOptionsInput, CompactOperation>["model"] = (
-  modelID,
-  settings,
-) => {
+export const model: ProviderPackage.Definition<
+  Settings,
+  OpenAIProviderOptionsInput,
+  typeof OpenAIResponses.route.compact
+>["model"] = (modelID, settings) => {
   return configure(config(settings)).responses(modelID)
 }
 

packages/ai/src/providers/xai.ts

@@ -1,5 +1,5 @@
 import { AuthOptions, type ProviderAuthOption } from "../route/auth-options.js"
-import { Route, type RouteDefaultsInput, type CompactOperation } from "../route/client.js"
+import { Route, type RouteDefaultsInput } from "../route/client.js"
 import { Endpoint } from "../route/endpoint.js"
 import { HttpOptions, ProviderID, type ModelID } from "../schema/index.js"
 import * as OpenAICompatibleProfiles from "./openai-compatible-profile.js"
@@ -32,7 +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,
+  compact: { endpoint: XAIResponses.compact },
   id: "openai-responses",
   provider: id,
   providerMetadataKey: "xai",
@@ -103,10 +103,11 @@ export const configure = (input: LanguageModelOptions = {}) => {
 }
 
 export const provider = configure()
-export const model: ProviderPackage.Definition<Settings, XAIProviderOptionsInput, CompactOperation>["model"] = (
-  modelID,
-  settings,
-) =>
+export const model: ProviderPackage.Definition<
+  Settings,
+  XAIProviderOptionsInput,
+  typeof responsesRoute.compact
+>["model"] = (modelID, settings) =>
   configure({
     apiKey: settings.apiKey,
     baseURL: settings.baseURL,

packages/ai/src/route/client.ts

@@ -14,6 +14,7 @@ import type { ProtocolID, ProviderOptions } from "../schema/index.js"
 import {
   AIError,
   CompactionResponse,
+  CompactionCheckpointResponse,
   AIErrorReason,
   GenerationOptions,
   HttpOptions,
@@ -38,7 +39,7 @@ export interface RouteBody<Body> {
 export interface Route<
   Body,
   Prepared = unknown,
-  Compact extends CompactOperation | undefined = CompactOperation | undefined,
+  Compact extends CompactionOperations | undefined = CompactionOperations | undefined,
 > {
   readonly compact: Compact
   readonly id: string
@@ -53,7 +54,15 @@ export interface Route<
   readonly transport: Transport<Body, Prepared, unknown>
   readonly defaults: RouteDefaults
   readonly body: RouteBody<Body>
-  readonly with: (patch: RoutePatch<Body, Prepared>) => Route<Body, Prepared, Compact>
+  readonly with: {
+    <Next extends CompactionOperations | undefined>(
+      patch: RoutePatch<Body, Prepared> & { readonly compact: Next },
+    ): Route<Body, Prepared, Next>
+    (
+      patch: Omit<RoutePatch<Body, Prepared>, "compact"> & { readonly compact?: undefined },
+    ): Route<Body, Prepared, Compact>
+    (patch: RoutePatch<Body, Prepared>): Route<Body, Prepared>
+  }
   readonly model: <Options extends ProviderOptions = ProviderOptions>(
     input: RouteMappedLanguageModelInput,
   ) => LanguageModel<Options, Compact>
@@ -74,7 +83,7 @@ export interface Route<
 // Normal call sites use `OpenAIChat.route`; callers only need body types
 // when preparing a request with a protocol-specific type assertion.
 // oxlint-disable-next-line typescript-eslint/no-explicit-any
-export type AnyRoute<Compact extends CompactOperation | undefined = CompactOperation | undefined> = Route<
+export type AnyRoute<Compact extends CompactionOperations | undefined = CompactionOperations | undefined> = Route<
   any,
   any,
   Compact
@@ -101,6 +110,7 @@ export interface RouteDefaultsInput {
 }
 
 export interface RoutePatch<Body, Prepared> extends RouteDefaultsInput {
+  readonly compact?: CompactionOperations
   readonly id?: string
   readonly provider?: string | ProviderID
   readonly providerMetadataKey?: string
@@ -111,7 +121,7 @@ export interface RoutePatch<Body, Prepared> extends RouteDefaultsInput {
 
 type RouteMappedLanguageModelInput = RouteLanguageModelInput | RouteRoutedLanguageModelInput
 
-const makeRouteLanguageModel = <Options extends ProviderOptions, Compact extends CompactOperation | undefined>(
+const makeRouteLanguageModel = <Options extends ProviderOptions, Compact extends CompactionOperations | undefined>(
   route: AnyRoute<Compact>,
   mapped: RouteMappedLanguageModelInput,
 ) => {
@@ -162,10 +172,7 @@ export const httpOptions = (input: HttpOptionsInput | undefined) => {
 }
 
 export interface Interface {
-  readonly compact: (
-    request: CompactionRequest,
-    options?: Pick<StreamOptions, "http">,
-  ) => Effect.Effect<CompactionResponse, AIError>
+  readonly compact: CompactMethod
   readonly stream: StreamMethod
   readonly generate: GenerateMethod
 }
@@ -189,12 +196,64 @@ export type CompactOperation = (
   options?: Pick<StreamOptions, "http">,
 ) => Effect.Effect<CompactionResponse, AIError>
 
-export type CompactionRequest = LLMRequest & {
-  readonly model: LanguageModel<ProviderOptions, CompactOperation>
+export type TriggerCompactOperation = (
+  request: LLMRequest,
+  executor: RequestExecutor.Interface,
+  options: TriggerCompactOptions,
+) => Effect.Effect<CompactionCheckpointResponse, AIError>
+
+/** Protocol capabilities, not deployment/model eligibility. */
+export interface CompactionOperations {
+  readonly endpoint?: CompactOperation
+  readonly trigger?: TriggerCompactOperation
 }
 
-export const canCompact = (request: LLMRequest): request is CompactionRequest =>
-  request.model.route.compact !== undefined
+export interface EndpointCompactOptions extends Pick<StreamOptions, "http"> {
+  readonly mechanism?: "endpoint"
+  readonly webSocket?: never
+}
+
+export interface TriggerCompactOptions extends StreamOptions {
+  readonly mechanism: "trigger"
+}
+
+// Keep the required route shape explicit: the schema class's self type erases its model parameter in assignability.
+export type CompactionRequest = LLMRequest & {
+  readonly model: LanguageModel<ProviderOptions, { readonly endpoint: CompactOperation }>
+}
+export type CheckpointRequest = LLMRequest & {
+  readonly model: LanguageModel<ProviderOptions, { readonly trigger: TriggerCompactOperation }>
+}
+
+export interface CompactMethod<R = never> {
+  (request: CheckpointRequest, options: TriggerCompactOptions): Effect.Effect<CompactionCheckpointResponse, AIError, R>
+  (request: CompactionRequest, options?: EndpointCompactOptions): Effect.Effect<CompactionResponse, AIError, R>
+}
+
+export function canCompact(
+  request: LLMRequest,
+  options?: { readonly mechanism?: "endpoint" },
+): request is CompactionRequest
+export function canCompact(
+  request: LLMRequest,
+  options: { readonly mechanism: "trigger" },
+): request is CheckpointRequest
+export function canCompact(request: LLMRequest, options?: { readonly mechanism?: string }) {
+  if (options?.mechanism === "trigger") return request.model.route.compact?.trigger !== undefined
+  if (options?.mechanism !== undefined && options.mechanism !== "endpoint") return false
+  return request.model.route.compact?.endpoint !== undefined
+}
+
+const unsupportedCompaction = (request: LLMRequest, mechanism: string | undefined) => {
+  if (mechanism !== undefined && mechanism !== "endpoint" && mechanism !== "trigger")
+    return ProviderShared.invalidRequest(`Unknown compaction mechanism: ${mechanism}`)
+  return ProviderShared.unsupportedOperation({
+    operation: mechanism === "trigger" ? "compact.trigger" : "compact",
+    provider: request.model.provider,
+    route: request.model.route.id,
+    message: `${request.model.provider}/${request.model.route.id} does not support ${mechanism === "trigger" ? "trigger" : "explicit"} compaction`,
+  })
+}
 
 export class Service extends Context.Service<Service, Interface>()("@opencode/LLMClient") {}
 
@@ -216,7 +275,7 @@ const resolveRequestOptions = (request: LLMRequest) => {
 }
 
 export interface MakeInput<Body, Frame, Event, State> {
-  readonly compact?: CompactOperation
+  readonly compact?: CompactionOperations
   /** Route id used in diagnostics and prepared request metadata. */
   readonly id: string
   /** Provider identity for route-owned model construction. */
@@ -238,7 +297,7 @@ export interface MakeInput<Body, Frame, Event, State> {
 }
 
 export interface MakeTransportInput<Body, Prepared, Frame, Event, State> {
-  readonly compact?: CompactOperation
+  readonly compact?: CompactionOperations
   /** Route id used in diagnostics and prepared request metadata. */
   readonly id: string
   /** Provider identity for route-owned model construction. */
@@ -326,9 +385,10 @@ function makeFromTransport<Body, Prepared, Frame, Event, State>(
       defaults: routeInput.defaults ?? {},
       body: protocol.body,
       with: (patch: RoutePatch<Body, Prepared>) => {
-        const { id, provider, providerMetadataKey, auth, transport, endpoint, ...defaults } = patch
+        const { compact, id, provider, providerMetadataKey, auth, transport, endpoint, ...defaults } = patch
         return build({
           ...routeInput,
+          compact: "compact" in patch ? compact : routeInput.compact,
           id: id ?? routeInput.id,
           provider: provider ?? routeInput.provider,
           providerMetadataKey:
@@ -343,7 +403,7 @@ function makeFromTransport<Body, Prepared, Frame, Event, State>(
         })
       },
       model: <Options extends ProviderOptions = ProviderOptions>(input: RouteMappedLanguageModelInput) =>
-        makeRouteLanguageModel<Options, CompactOperation | undefined>(route, input),
+        makeRouteLanguageModel<Options, CompactionOperations | undefined>(route, input),
       prepareTransport: (body, request, options) =>
         routeInput.transport.prepare({
           body,
@@ -440,12 +500,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, Compact extends CompactionOperations>(
+  input: MakeTransportInput<Body, Prepared, Frame, Event, State> & { readonly compact: Compact },
+): Route<Body, Prepared, Compact>
+export function make<Body, Frame, Event, State, Compact extends CompactionOperations>(
+  input: MakeInput<Body, Frame, Event, State> & { readonly compact: Compact },
+): Route<Body, HttpTransport.HttpPrepared<Frame>, Compact>
 export function make<Body, Prepared, Frame, Event, State>(
   input: MakeTransportInput<Body, Prepared, Frame, Event, State>,
 ): Route<Body, Prepared>
@@ -557,14 +617,23 @@ export function generate(request: LLMRequest, options?: StreamOptions): Effect.E
   })
 }
 
-export const compact = (
+export function compact(
+  request: CheckpointRequest,
+  options: TriggerCompactOptions,
+): Effect.Effect<CompactionCheckpointResponse, AIError, Service>
+export function compact(
   request: CompactionRequest,
-  options?: Pick<StreamOptions, "http">,
-): Effect.Effect<CompactionResponse, AIError, Service> =>
-  Effect.gen(function* () {
+  options?: EndpointCompactOptions,
+): Effect.Effect<CompactionResponse, AIError, Service>
+export function compact(request: LLMRequest, options?: EndpointCompactOptions | TriggerCompactOptions) {
+  return Effect.gen(function* () {
     const client = yield* Service
-    return yield* client.compact(request, options)
+    if (options?.mechanism === "trigger" && canCompact(request, options)) return yield* client.compact(request, options)
+    if ((options?.mechanism === undefined || options.mechanism === "endpoint") && canCompact(request))
+      return yield* client.compact(request, options)
+    return yield* unsupportedCompaction(request, options?.mechanism)
   })
+}
 
 export const streamRequest = (request: LLMRequest, options?: StreamOptions) =>
   Stream.unwrap(
@@ -578,21 +647,27 @@ export const layer: Layer.Layer<Service, never, RequestExecutor.Service> = Layer
   Effect.gen(function* () {
     const executor = yield* RequestExecutor.Service
     const stream = streamRequestWith({ http: executor })
+    function compact(
+      request: CompactionRequest,
+      options?: EndpointCompactOptions,
+    ): Effect.Effect<CompactionResponse, AIError>
+    function compact(
+      request: CheckpointRequest,
+      options: TriggerCompactOptions,
+    ): Effect.Effect<CompactionCheckpointResponse, AIError>
+    function compact(request: LLMRequest, options?: EndpointCompactOptions | TriggerCompactOptions) {
+      return Effect.suspend((): Effect.Effect<CompactionResponse | CompactionCheckpointResponse, AIError> => {
+        if (options?.mechanism === "trigger" && canCompact(request, options))
+          return request.model.route.compact.trigger(prepareRequest(request), executor, options)
+        if ((options?.mechanism === undefined || options.mechanism === "endpoint") && canCompact(request))
+          return request.model.route.compact.endpoint(prepareRequest(request), executor, options)
+        return unsupportedCompaction(request, options?.mechanism)
+      })
+    }
     return Service.of({
       stream,
       generate: generateWith(stream),
-      compact: (request, options) =>
-        Effect.suspend(() => {
-          const operation = request.model.route.compact
-          if (!operation)
-            return ProviderShared.unsupportedOperation({
-              operation: "compact",
-              provider: request.model.provider,
-              route: request.model.route.id,
-              message: `${request.model.provider}/${request.model.route.id} does not support explicit compaction`,
-            })
-          return operation(prepareRequest(request), executor, options)
-        }),
+      compact,
     })
   }),
 )

packages/ai/src/route/index.ts

@@ -9,6 +9,12 @@ export type {
   Interface as LLMClientShape,
   Service as LLMClientService,
   StreamOptions,
+  CompactMethod,
+  CompactionOperations,
+  CompactionRequest,
+  CheckpointRequest,
+  EndpointCompactOptions,
+  TriggerCompactOptions,
 } from "./client.js"
 export * from "./executor.js"
 export { Auth } from "./auth.js"

packages/ai/src/schema/events.ts

@@ -97,6 +97,21 @@ export class CompactionResponse extends Schema.Class<CompactionResponse>("LLM.Co
   usage: Schema.optional(Usage),
 }) {}
 
+/** A checkpoint only; retained history and replacement-window construction belong to the caller. */
+export class CompactionCheckpointResponse extends Schema.Class<CompactionCheckpointResponse>(
+  "LLM.CompactionCheckpointResponse",
+)({
+  checkpoint: CompactionPart.pipe(
+    Schema.refine(
+      (part): part is CompactionPart & { readonly encrypted: string; readonly text?: never } =>
+        part.encrypted !== undefined && part.encrypted.length > 0,
+      { message: "A checkpoint response requires encrypted compaction content" },
+    ),
+  ),
+  responseID: Schema.String.check(Schema.isPattern(/\S/)),
+  usage: Schema.optional(Usage),
+}) {}
+
 export const StepStart = Schema.Struct({
   type: Schema.tag("step-start"),
   index: Schema.Number,

packages/ai/src/schema/options.ts

@@ -1,6 +1,6 @@
 import { Schema } from "effect"
 import { ModelID, ProviderID } from "./ids.js"
-import type { AnyRoute, CompactOperation } from "../route/client.js"
+import type { AnyRoute, CompactionOperations } from "../route/client.js"
 import { isRecord } from "../utils/record.js"
 
 export const JsonSchema = Schema.Record(Schema.String, Schema.Unknown)
@@ -175,7 +175,7 @@ export namespace LanguageModelCompatibility {
 
 export class LanguageModel<
   Options extends ProviderOptions = ProviderOptions,
-  Compact extends CompactOperation | undefined = CompactOperation | undefined,
+  Compact extends CompactionOperations | undefined = CompactionOperations | undefined,
 > {
   declare protected readonly _ProviderOptions: Options
   readonly id: ModelID
@@ -194,7 +194,7 @@ export class LanguageModel<
 
   static make<
     Options extends ProviderOptions = ProviderOptions,
-    Compact extends CompactOperation | undefined = CompactOperation | undefined,
+    Compact extends CompactionOperations | undefined = CompactionOperations | undefined,
   >(input: LanguageModel.Input<Compact>) {
     return new LanguageModel<Options, Compact>({
       id: ModelID.make(input.id),
@@ -206,7 +206,7 @@ export class LanguageModel<
     })
   }
 
-  static input<Options extends ProviderOptions, Compact extends CompactOperation | undefined>(
+  static input<Options extends ProviderOptions, Compact extends CompactionOperations | undefined>(
     model: LanguageModel<Options, Compact>,
   ): LanguageModel.ConstructorInput<Compact> {
     return {
@@ -218,11 +218,11 @@ export class LanguageModel<
     }
   }
 
-  static update<Options extends ProviderOptions, Compact extends CompactOperation | undefined>(
+  static update<Options extends ProviderOptions, Compact extends CompactionOperations | 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>(
+  static update<Options extends ProviderOptions, Compact extends CompactionOperations | undefined>(
     model: LanguageModel<Options, Compact>,
     patch: Partial<Omit<LanguageModel.Input, "route">> & { readonly route?: undefined },
   ): LanguageModel<Options, Compact>
@@ -241,7 +241,7 @@ export class LanguageModel<
 }
 
 export namespace LanguageModel {
-  export type ConstructorInput<Compact extends CompactOperation | undefined = CompactOperation | undefined> = {
+  export type ConstructorInput<Compact extends CompactionOperations | undefined = CompactionOperations | undefined> = {
     readonly id: ModelID
     readonly provider: ProviderID
     readonly route: AnyRoute<Compact>
@@ -249,7 +249,7 @@ export namespace LanguageModel {
     readonly compatibility?: LanguageModelCompatibility
   }
 
-  export type Input<Compact extends CompactOperation | undefined = CompactOperation | undefined> = Omit<
+  export type Input<Compact extends CompactionOperations | undefined = CompactionOperations | undefined> = Omit<
     ConstructorInput<Compact>,
     "id" | "provider" | "defaults" | "compatibility"
   > & {

packages/ai/src/testing.ts

@@ -1,10 +1,17 @@
 export * as TestLLM from "./testing.js"
 
-import { LLMClient } from "./route/client.js"
+import {
+  LLMClient,
+  type CompactionRequest,
+  type CheckpointRequest,
+  type EndpointCompactOptions,
+  type TriggerCompactOptions,
+} from "./route/client.js"
 import {
   LLMEvent,
   LLMResponse,
   CompactionResponse,
+  CompactionCheckpointResponse,
   type FinishReasonDetails,
   type AIError,
   type LLMRequest,
@@ -13,7 +20,11 @@ import {
 } from "./schema/index.js"
 import { Context, Deferred, Effect, Latch, Layer, Queue, Scope, Stream } from "effect"
 
-export type Response = readonly LLMEvent[] | Stream.Stream<LLMEvent, AIError> | CompactionResponse
+export type Response =
+  | readonly LLMEvent[]
+  | Stream.Stream<LLMEvent, AIError>
+  | CompactionResponse
+  | CompactionCheckpointResponse
 
 export type Gate = Readonly<{ started: Effect.Effect<void>; release: Effect.Effect<void> }>
 
@@ -132,21 +143,38 @@ const make = (options: LayerOptions) =>
       Stream.unwrap(
         take(request).pipe(
           Effect.map((response) => {
-            if (response instanceof CompactionResponse)
+            if (response instanceof CompactionResponse || response instanceof CompactionCheckpointResponse)
               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
+    function compact(
+      request: CompactionRequest,
+      options?: EndpointCompactOptions,
+    ): Effect.Effect<CompactionResponse, AIError>
+    function compact(
+      request: CheckpointRequest,
+      options: TriggerCompactOptions,
+    ): Effect.Effect<CompactionCheckpointResponse, AIError>
+    function compact(
+      request: LLMRequest,
+      options?: EndpointCompactOptions | TriggerCompactOptions,
+    ): Effect.Effect<CompactionResponse | CompactionCheckpointResponse, AIError> {
+      return take(request).pipe(
+        Effect.flatMap((response): Effect.Effect<CompactionResponse | CompactionCheckpointResponse> => {
+          if (options?.mechanism === "trigger")
+            return response instanceof CompactionCheckpointResponse
               ? Effect.succeed(response)
-              : Effect.die("TestLLM compaction requires a CompactionResponse"),
-          ),
-        ),
+              : Effect.die("TestLLM trigger compaction requires a CompactionCheckpointResponse")
+          return response instanceof CompactionResponse
+            ? Effect.succeed(response)
+            : Effect.die("TestLLM compaction requires a CompactionResponse")
+        }),
+      )
+    }
+    const test = Test.of({
+      compact,
       stream,
       generate: (request) =>
         stream(request).pipe(

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

@@ -0,0 +1,146 @@
+import { Effect } from "effect"
+import {
+  CompactionCheckpointResponse,
+  CompactionResponse,
+  LanguageModel,
+  LLM,
+  LLMClient,
+  LLMRequest,
+} from "../../src/index.js"
+import {
+  Anthropic,
+  Azure,
+  AmazonBedrock,
+  AmazonBedrockMantle,
+  OpenAI,
+  OpenAICompatibleResponses,
+  XAI,
+} from "../../src/providers.js"
+import type { WebSocketChannelExecutor } from "../../src/route.js"
+import type { RoutePatch } from "../../src/route/client.js"
+import type { OpenAIResponsesBody } from "../../src/protocols/openai-responses.js"
+import type { Prepared } from "../../src/protocols/open-responses-channel.js"
+
+declare const webSocket: WebSocketChannelExecutor
+const model = OpenAI.configure().responses("fixture")
+const request = LLM.request({ model, prompt: "hello" })
+LLMClient.compact(request).pipe(Effect.map((result) => result satisfies CompactionResponse))
+LLMClient.compact(request, { mechanism: "endpoint" }).pipe(Effect.map((result) => result satisfies CompactionResponse))
+LLMClient.compact(request, { mechanism: "trigger", webSocket }).pipe(
+  Effect.map((result) => {
+    result satisfies CompactionCheckpointResponse
+    result.checkpoint.encrypted satisfies string
+    result.responseID satisfies string
+    // @ts-expect-error A trigger does not return replacement history.
+    result.replacement
+  }),
+)
+// @ts-expect-error Endpoint compaction does not accept a WebSocket executor.
+LLMClient.compact(request, { mechanism: "endpoint", webSocket })
+// @ts-expect-error Omitting mechanism selects the HTTP endpoint.
+LLMClient.compact(request, { webSocket })
+// @ts-expect-error Unknown mechanisms do not have a permissive fallback overload.
+LLMClient.compact(request, { mechanism: "other" })
+
+for (const selected of [
+  model,
+  OpenAI.model("fixture", {}),
+  model.route.with({ headers: { fixture: "test" } }).model({ id: "fixture" }),
+  LanguageModel.make(LanguageModel.input(model)),
+  LanguageModel.update(model, { defaults: { generation: { maxTokens: 100 } } }),
+]) {
+  LLMClient.compact(LLM.request({ model: selected }), { mechanism: "trigger" })
+}
+LLMClient.compact(new LLMRequest(LLMRequest.input(request)), { mechanism: "trigger" })
+LLMClient.compact(LLMRequest.update(request, { messages: [] }), { mechanism: "trigger" })
+
+const azure = Azure.configure({ resourceName: "fixture" }).responses("fixture")
+const xai = XAI.configure().responses("fixture")
+LLMClient.compact(LLM.request({ model: azure }))
+LLMClient.compact(LLM.request({ model: xai }))
+// @ts-expect-error Azure must not inherit OpenAI's trigger operation.
+LLMClient.compact(LLM.request({ model: azure }), { mechanism: "trigger" })
+LLMClient.compact(LLM.request({ model: Azure.responsesModel("fixture", { resourceName: "fixture" }) }), {
+  // @ts-expect-error Azure's package entrypoint must preserve its narrower capability.
+  mechanism: "trigger",
+})
+// @ts-expect-error xAI endpoint support does not imply trigger support.
+LLMClient.compact(LLM.request({ model: xai }), { mechanism: "trigger" })
+// @ts-expect-error xAI's package entrypoint must preserve its narrower capability.
+LLMClient.compact(LLM.request({ model: XAI.model("fixture", {}) }), { mechanism: "trigger" })
+
+const unsupported = {
+  bedrock: LLM.request({ model: AmazonBedrock.configure().model("fixture") }),
+  mantle: LLM.request({ model: AmazonBedrockMantle.configure().responses("fixture") }),
+  anthropic: LLM.request({ model: Anthropic.configure().model("fixture") }),
+  openai: LLM.request({ model: OpenAI.configure().chat("fixture") }),
+  azure: LLM.request({ model: Azure.configure({ resourceName: "fixture" }).chat("fixture") }),
+  xai: LLM.request({ model: XAI.configure().chat("fixture") }),
+  compatible: LLM.request({
+    model: OpenAICompatibleResponses.configure({ baseURL: "https://example.com" }).model("fixture"),
+  }),
+}
+// @ts-expect-error Bedrock does not expose endpoint compaction.
+LLMClient.compact(unsupported.bedrock)
+// @ts-expect-error Bedrock does not expose trigger compaction.
+LLMClient.compact(unsupported.bedrock, { mechanism: "trigger" })
+// @ts-expect-error Mantle does not expose endpoint compaction.
+LLMClient.compact(unsupported.mantle)
+// @ts-expect-error Mantle must not inherit trigger support from OpenAI's protocol.
+LLMClient.compact(unsupported.mantle, { mechanism: "trigger" })
+// @ts-expect-error Anthropic does not expose endpoint compaction.
+LLMClient.compact(unsupported.anthropic)
+// @ts-expect-error Anthropic does not expose trigger compaction.
+LLMClient.compact(unsupported.anthropic, { mechanism: "trigger" })
+// @ts-expect-error OpenAI Chat does not expose endpoint compaction.
+LLMClient.compact(unsupported.openai)
+// @ts-expect-error OpenAI Chat does not expose trigger compaction.
+LLMClient.compact(unsupported.openai, { mechanism: "trigger" })
+// @ts-expect-error Azure Chat does not expose endpoint compaction.
+LLMClient.compact(unsupported.azure)
+// @ts-expect-error Azure Chat does not expose trigger compaction.
+LLMClient.compact(unsupported.azure, { mechanism: "trigger" })
+// @ts-expect-error xAI Chat does not expose endpoint compaction.
+LLMClient.compact(unsupported.xai)
+// @ts-expect-error xAI Chat does not expose trigger compaction.
+LLMClient.compact(unsupported.xai, { mechanism: "trigger" })
+// @ts-expect-error Generic protocol compatibility does not grant endpoint support.
+LLMClient.compact(unsupported.compatible)
+// @ts-expect-error Generic protocol compatibility does not grant trigger support.
+LLMClient.compact(unsupported.compatible, { mechanism: "trigger" })
+// @ts-expect-error Changing the model replaces its capability.
+LLMClient.compact(LLMRequest.update(request, { model: azure }), { mechanism: "trigger" })
+// @ts-expect-error Changing the route replaces its capability.
+LLMClient.compact(LLM.request({ model: LanguageModel.update(model, { route: azure.route }) }), { mechanism: "trigger" })
+LLMClient.compact(
+  LLM.request({
+    model: model.route.with({ compact: { endpoint: model.route.compact.endpoint } }).model({ id: "fixture" }),
+  }),
+  // @ts-expect-error Replacing route operations does not retain the old trigger capability.
+  { mechanism: "trigger" },
+)
+
+declare const dynamic: LLMRequest
+declare const patch: Partial<LLMRequest.Input>
+declare const routePatch: RoutePatch<OpenAIResponsesBody, Prepared>
+// @ts-expect-error A dynamic operation override cannot preserve trigger support.
+LLMClient.compact(LLM.request({ model: model.route.with(routePatch).model({ id: "fixture" }) }), {
+  mechanism: "trigger",
+})
+// @ts-expect-error Explicitly removing operations removes trigger support.
+LLMClient.compact(LLM.request({ model: model.route.with({ compact: undefined }).model({ id: "fixture" }) }), {
+  mechanism: "trigger",
+})
+// @ts-expect-error Dynamic models must be narrowed.
+LLMClient.compact(dynamic, { mechanism: "trigger" })
+if (LLMClient.canCompact(dynamic, { mechanism: "trigger" })) {
+  LLMClient.compact(dynamic, { mechanism: "trigger" })
+  LLMClient.Service.use((client) => client.compact(dynamic, { mechanism: "trigger" }))
+}
+if (LLMClient.canCompact(dynamic)) {
+  LLMClient.compact(dynamic)
+  // @ts-expect-error Endpoint narrowing does not grant trigger support.
+  LLMClient.compact(dynamic, { mechanism: "trigger" })
+}
+// @ts-expect-error A dynamic model override cannot preserve trigger support.
+LLMClient.compact(LLMRequest.update(request, patch), { mechanism: "trigger" })

packages/ai/test/provider/checkpoint.test.ts

@@ -0,0 +1,374 @@
+import { expect, test } from "bun:test"
+import { Effect, Schema, Stream } from "effect"
+import { CompactionCheckpointResponse, LLM, LLMClient, LLMRequest, LanguageModel, SystemPart } from "../../src/index.js"
+import { Anthropic, Azure, OpenAI, XAI } from "../../src/providers.js"
+import { Route } from "../../src/route/client.js"
+import { OpenAIResponses } from "../../src/protocols/openai-responses.js"
+import { testEffect } from "../lib/effect.js"
+import { dynamicResponse, fixedResponse, scriptedResponses, truncatedStream } from "../lib/http.js"
+import { sseEvents } from "../lib/sse.js"
+
+const checkpoint = { type: "compaction", id: "cmp_1", encrypted_content: "opaque" }
+const request = LLM.request({ model: OpenAI.configure({ apiKey: "fixture" }).responses("fixture"), prompt: "hello" })
+const trigger = { mechanism: "trigger" } as const
+
+testEffect(
+  dynamicResponse(({ request, text, respond }) =>
+    Effect.sync(() => {
+      expect(new URL(request.url).pathname).toBe("/v1/responses")
+      expect(new URL(request.url).searchParams.get("deployment")).toBe("fixture")
+      expect(new URL(request.url).searchParams.get("trace")).toBe("request")
+      expect(request.headers.authorization).toBe("Bearer fixture")
+      expect(request.headers["chatgpt-account-id"]).toBe("fixture-account")
+      expect(request.headers["x-codex-beta-features"]).toBe("remote_compaction_v2")
+      expect(request.headers["x-deployment"]).toBe("resolved")
+      const body = JSON.parse(text)
+      expect(body).toMatchObject({
+        model: "fixture",
+        stream: true,
+        store: false,
+        instructions: "system\noperator",
+        parallel_tool_calls: true,
+        prompt_cache_key: "session-key",
+        service_tier: "priority",
+        reasoning: { effort: "high", summary: "auto" },
+        prompt_cache_retention: "24h",
+        prompt_cache_options: { mode: "session", ttl: "1h" },
+        input: [{ role: "user", content: [{ type: "input_text", text: "hello" }] }, { type: "compaction_trigger" }],
+      })
+      expect(body.tools).toHaveLength(1)
+      expect(body.tools[0].name).toBe("lookup")
+      expect(body.tool_choice).toBeUndefined()
+      expect(body.context_management).toBeUndefined()
+      expect(body.text).toBeUndefined()
+      expect(body.max_output_tokens).toBeUndefined()
+      expect(body.previous_response_id).toBeUndefined()
+      return respond(
+        sseEvents({
+          type: "response.completed",
+          response: {
+            id: "resp_1",
+            output: [checkpoint],
+            usage: {
+              input_tokens: 100,
+              input_tokens_details: { cached_tokens: 40 },
+              output_tokens: 5,
+              total_tokens: 105,
+            },
+          },
+        }),
+        { headers: { "content-type": "text/event-stream" } },
+      )
+    }),
+  ),
+).effect("trigger uses normal request preparation, configured deployment, and supplied subscription headers", () =>
+  Effect.gen(function* () {
+    const calls: string[] = []
+    const route = Route.make({
+      id: "fixture-responses",
+      provider: "openai",
+      protocol: OpenAIResponses.protocol,
+      compact: OpenAIResponses.route.compact,
+      endpoint: OpenAIResponses.route.endpoint,
+      auth: request.model.route.auth,
+      transport: OpenAIResponses.transport,
+      headers: () => {
+        calls.push("headers")
+        return { "x-deployment": "resolved" }
+      },
+    }).with({ endpoint: { query: { deployment: "fixture" } } })
+    const input = LLM.request({
+      model: route.model({ id: "fixture" }),
+      system: [SystemPart.make("system"), SystemPart.make("operator")],
+      prompt: "hello",
+      promptCacheKey: "session-key",
+      tools: [{ name: "lookup", description: "Lookup", inputSchema: { type: "object", properties: {} } }],
+      toolChoice: { type: "tool", name: "lookup" },
+      generation: { maxTokens: 1 },
+      providerOptions: {
+        store: true,
+        reasoningEffort: "high",
+        reasoningSummary: "auto",
+        contextManagement: [{ type: "compaction" }],
+      },
+      http: {
+        headers: { "chatgpt-account-id": "fixture-account", "x-codex-beta-features": "remote_compaction_v2" },
+        query: { trace: "request" },
+        body: {
+          service_tier: "priority",
+          prompt_cache_retention: "24h",
+          prompt_cache_options: { mode: "session", ttl: "1h" },
+          store: true,
+          stream: false,
+          text: { format: { type: "json_object" } },
+          tool_choice: "required",
+        },
+      },
+    })
+    const original = LLMRequest.input(input)
+    const result = yield* LLMClient.compact(input, {
+      ...trigger,
+      http: (request, next) => {
+        calls.push("http")
+        return next(request)
+      },
+    })
+    expect(result).toBeInstanceOf(CompactionCheckpointResponse)
+    expect(result.checkpoint).toMatchObject({
+      type: "compaction",
+      provider: "openai",
+      id: "cmp_1",
+      encrypted: "opaque",
+    })
+    expect(result.responseID).toBe("resp_1")
+    expect(result.usage).toMatchObject({
+      inputTokens: 100,
+      outputTokens: 5,
+      totalTokens: 105,
+      cacheReadInputTokens: 40,
+    })
+    expect(LLMRequest.input(input)).toEqual(original)
+    expect(calls).toEqual(["headers", "http"])
+    const codec = Schema.fromJsonString(CompactionCheckpointResponse)
+    expect(Schema.decodeSync(codec)(Schema.encodeSync(codec)(result))).toEqual(result)
+    expect("replacement" in result).toBe(false)
+  }),
+)
+
+for (const id of ["cmp_1", undefined]) {
+  for (const added of [true, false]) {
+    const item = { type: "compaction", id, encrypted_content: "opaque" }
+    testEffect(
+      fixedResponse(
+        sseEvents(
+          { type: "response.created", response: { id: "resp_1" } },
+          ...(added ? [{ type: "response.output_item.added", output_index: 0, item: { type: "compaction", id } }] : []),
+          { type: "response.output_item.done", output_index: 0, item },
+          { type: "response.output_item.done", output_index: 0, item },
+          { type: "response.completed", response: { id: "resp_1", output: [item] } },
+        ),
+      ),
+    ).effect(`correlates repeated checkpoint events: id=${id}, added=${added}`, () =>
+      Effect.gen(function* () {
+        const result = yield* LLMClient.compact(request, trigger)
+        expect(result.checkpoint.encrypted).toBe("opaque")
+        expect(result.checkpoint.id).toBeString()
+      }),
+    )
+  }
+}
+
+testEffect(
+  fixedResponse(
+    sseEvents(
+      {
+        type: "response.output_item.done",
+        output_index: 0,
+        item: { type: "function_call", id: "fc_1", name: "unexpected", arguments: "not JSON" },
+      },
+      { type: "response.output_text.delta", delta: "do not expose this" },
+      {
+        type: "response.completed",
+        response: {
+          id: "resp_1",
+          output: [{ type: "function_call", id: "fc_1", name: "unexpected", arguments: "not JSON" }, checkpoint],
+        },
+      },
+    ),
+  ),
+).effect("ignores other output rather than generating an answer or dispatching tools", () =>
+  Effect.gen(function* () {
+    const result = yield* LLMClient.compact(request, trigger)
+    expect(result.checkpoint.encrypted).toBe("opaque")
+    expect("message" in result).toBe(false)
+  }),
+)
+
+for (const [name, events] of Object.entries({
+  missing: [{ type: "response.completed", response: { id: "resp_1", output: [] } }],
+  multiple: [
+    { type: "response.completed", response: { id: "resp_1", output: [checkpoint, { ...checkpoint, id: "cmp_2" }] } },
+  ],
+  duplicateSlots: [{ type: "response.completed", response: { id: "resp_1", output: [checkpoint, checkpoint] } }],
+  malformed: [
+    { type: "response.completed", response: { id: "resp_1", output: [{ type: "compaction", id: "cmp_1" }] } },
+  ],
+  empty: [
+    { type: "response.completed", response: { id: "resp_1", output: [{ ...checkpoint, encrypted_content: "" }] } },
+  ],
+  wrongType: [
+    { type: "response.completed", response: { id: "resp_1", output: [{ ...checkpoint, encrypted_content: 42 }] } },
+  ],
+  noResponseID: [{ type: "response.completed", response: { output: [checkpoint] } }],
+  changedID: [
+    { type: "response.created", response: { id: "resp_1" } },
+    { type: "response.completed", response: { id: "resp_2", output: [checkpoint] } },
+  ],
+  changedCheckpoint: [
+    { type: "response.output_item.done", item: checkpoint },
+    {
+      type: "response.completed",
+      response: { id: "resp_1", output: [{ ...checkpoint, encrypted_content: "changed" }] },
+    },
+  ],
+  incomplete: [
+    { type: "response.output_item.done", item: checkpoint },
+    { type: "response.incomplete", response: { id: "resp_1", incomplete_details: { reason: "max_output_tokens" } } },
+  ],
+  failed: [
+    { type: "response.output_item.done", item: checkpoint },
+    { type: "response.failed", response: { id: "resp_1", error: { code: "server_error", message: "failed" } } },
+  ],
+  wrongStatus: [{ type: "response.completed", response: { id: "resp_1", status: "incomplete", output: [checkpoint] } }],
+})) {
+  const wire = events.map((event) => ({ ...event, fixture_extra: "preserved" }))
+  testEffect(
+    fixedResponse(sseEvents(...wire), { headers: { "content-type": "text/event-stream", "x-fixture": "preserved" } }),
+  ).effect(`rejects ${name} checkpoint response and preserves original error context`, () =>
+    Effect.gen(function* () {
+      const error = yield* LLMClient.compact(request, trigger).pipe(Effect.flip)
+      expect(error.reason.body).toBe(JSON.stringify(wire.at(-1)))
+      expect(error.reason.http).toMatchObject({ status: 200, headers: { "x-fixture": "preserved" } })
+    }),
+  )
+}
+
+testEffect(fixedResponse(sseEvents({ type: "response.output_item.done", item: checkpoint }))).effect(
+  "rejects clean EOF without response.completed",
+  () =>
+    Effect.gen(function* () {
+      const error = yield* LLMClient.compact(request, trigger).pipe(Effect.flip)
+      expect(error.reason._tag).toBe("InvalidProviderOutput")
+    }),
+)
+testEffect(truncatedStream([sseEvents({ type: "response.output_item.done", item: checkpoint })])).effect(
+  "does not return a checkpoint from an interrupted stream",
+  () =>
+    Effect.gen(function* () {
+      const error = yield* LLMClient.compact(request, trigger).pipe(Effect.flip)
+      expect(error.reason._tag).toBe("Transport")
+    }),
+)
+
+for (const body of [{ input: [] }, { previous_response_id: "stale" }, { conversation: "stored" }]) {
+  testEffect(dynamicResponse(() => Effect.die("Must reject before sending"))).effect(
+    `rejects caller-supplied ${Object.keys(body)[0]} before sending trigger`,
+    () =>
+      Effect.gen(function* () {
+        const error = yield* LLMClient.compact(LLMRequest.update(request, { http: { body } }), trigger).pipe(
+          Effect.flip,
+        )
+        expect(error.reason._tag).toBe("InvalidRequest")
+      }),
+  )
+}
+
+test("trigger capability follows selected routes, independently of endpoint support", () => {
+  expect(LLMClient.canCompact(request, trigger)).toBe(true)
+  for (const model of [
+    Azure.configure({ resourceName: "fixture" }).responses("fixture"),
+    XAI.configure().responses("fixture"),
+  ]) {
+    expect(LLMClient.canCompact(LLM.request({ model }))).toBe(true)
+    expect(LLMClient.canCompact(LLM.request({ model }), trigger)).toBe(false)
+    expect(LLMClient.canCompact(LLMRequest.update(request, { model }), trigger)).toBe(false)
+    expect(
+      LLMClient.canCompact(
+        LLM.request({ model: LanguageModel.update(request.model, { route: model.route }) }),
+        trigger,
+      ),
+    ).toBe(false)
+  }
+})
+
+testEffect(dynamicResponse(() => Effect.die("Must reject before sending"))).effect(
+  "untyped unsupported mechanisms and routes fail locally in both client surfaces",
+  () =>
+    Effect.gen(function* () {
+      const client = yield* LLMClient.Service
+      for (const model of [
+        Anthropic.configure().model("fixture"),
+        Azure.configure({ resourceName: "fixture" }).responses("fixture"),
+      ]) {
+        const unsupported = LLM.request({ model })
+        // @ts-expect-error Exercise untyped consumers; runtime must still reject unsupported routes.
+        const error = yield* LLMClient.compact(unsupported, trigger).pipe(Effect.flip)
+        expect(error.reason._tag).toBe("UnsupportedOperation")
+        // @ts-expect-error The service has the same runtime guard.
+        const serviceError = yield* client.compact(unsupported, trigger).pipe(Effect.flip)
+        expect(serviceError.reason._tag).toBe("UnsupportedOperation")
+      }
+      // @ts-expect-error Exercise an unknown mechanism supplied by JavaScript.
+      const error = yield* LLMClient.compact(request, { mechanism: "other" }).pipe(Effect.flip)
+      expect(error.reason._tag).toBe("InvalidRequest")
+      // @ts-expect-error An empty string is not the default mechanism.
+      const empty = yield* client.compact(request, { mechanism: "" }).pipe(Effect.flip)
+      expect(empty.reason._tag).toBe("InvalidRequest")
+    }),
+)
+
+for (const valid of [true, false]) {
+  testEffect(fixedResponse("must not use HTTP")).effect(
+    `acknowledges channel completion only after validation: valid=${valid}`,
+    () =>
+      Effect.gen(function* () {
+        let completed = 0
+        const operation = LLMClient.compact(request, {
+          mechanism: "trigger",
+          webSocket: {
+            execute: () =>
+              Effect.succeed({
+                frames: Stream.make(
+                  JSON.stringify({
+                    type: "response.completed",
+                    response: { id: "resp_1", output: valid ? [checkpoint] : [] },
+                  }),
+                ),
+                complete: Effect.sync(() => {
+                  completed++
+                }),
+              }),
+          },
+        })
+        const result = yield* Effect.result(operation)
+        expect(result._tag).toBe(valid ? "Success" : "Failure")
+        expect(completed).toBe(valid ? 1 : 0)
+      }),
+  )
+}
+
+test("checkpoint result schema rejects failed or unencrypted representations", () => {
+  const decode = Schema.decodeUnknownSync(CompactionCheckpointResponse)
+  for (const checkpoint of [
+    { type: "compaction", provider: "anthropic", text: null },
+    { type: "compaction", provider: "anthropic", text: "summary" },
+    { type: "compaction", provider: "openai", encrypted: "" },
+  ])
+    expect(() => decode({ checkpoint, responseID: "resp_1" })).toThrow()
+  expect(() =>
+    decode({ checkpoint: { type: "compaction", provider: "openai", encrypted: "opaque" }, responseID: " " }),
+  ).toThrow()
+})
+
+testEffect(
+  scriptedResponses([
+    sseEvents(
+      { type: "response.created", response: { id: "resp_discarded" } },
+      { type: "response.output_item.done", item: { ...checkpoint, encrypted_content: "discarded" } },
+      { type: "response.incomplete", response: { id: "resp_discarded", usage: { input_tokens: 999 } } },
+    ),
+    sseEvents({
+      type: "response.completed",
+      response: { id: "resp_success", output: [checkpoint], usage: { input_tokens: 12 } },
+    }),
+  ]),
+).effect("an explicitly retried effect does not reuse failed-attempt checkpoint or metadata", () =>
+  Effect.gen(function* () {
+    const operation = LLMClient.compact(request, trigger)
+    yield* operation.pipe(Effect.flip)
+    const result = yield* operation
+    expect(result.checkpoint.encrypted).toBe("opaque")
+    expect(result.responseID).toBe("resp_success")
+    expect(result.usage?.inputTokens).toBe(12)
+  }),
+)

packages/ai/test/testing.test.ts

@@ -3,6 +3,7 @@ import {
   AIError,
   CompactionPart,
   CompactionResponse,
+  CompactionCheckpointResponse,
   LanguageModel,
   LLM,
   LLMClient,
@@ -79,6 +80,47 @@ describe("TestLLM legacy client", () => {
 })
 
 describe("TestLLM first-class client", () => {
+  it.effect("scripts trigger checkpoints lazily with gates, queue order, and fallbacks", () =>
+    Effect.gen(function* () {
+      const client = yield* TestLLM.Test
+      const request = LLM.request({ model: OpenAI.configure().responses("fixture"), prompt: "hello" })
+      const checkpoint = new CompactionCheckpointResponse({
+        checkpoint: { type: "compaction", provider: ProviderID.make("openai"), encrypted: "opaque" },
+        responseID: "resp_fixture",
+      })
+      const endpoint = new CompactionResponse({ replacement: [] })
+      yield* client.push(checkpoint, endpoint)
+      const operation = LLMClient.compact(request, { mechanism: "trigger" })
+      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(checkpoint)
+      expect(yield* client.compact(request)).toBe(endpoint)
+      yield* client.serve((observed) => {
+        expect(observed).toBe(request)
+        return checkpoint
+      })
+      expect(yield* LLMClient.compact(request, { mechanism: "trigger" })).toBe(checkpoint)
+      yield* client.always(checkpoint)
+      expect(yield* LLMClient.compact(request, { mechanism: "trigger" })).toBe(checkpoint)
+      yield* client.push(endpoint, checkpoint, checkpoint)
+      expect(yield* client.compact(request, { mechanism: "trigger" }).pipe(Effect.catchDefect(Effect.succeed))).toBe(
+        "TestLLM trigger compaction requires a CompactionCheckpointResponse",
+      )
+      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",
+      )
+      expect(yield* client.requests()).toHaveLength(7)
+    }),
+  )
+
   it.effect("rejects response fixtures for the wrong operation", () =>
     Effect.gen(function* () {
       const client = yield* TestLLM.Test

packages/ai/tsconfig.types.json

@@ -5,5 +5,5 @@
     "noEmit": true,
     "rootDir": "."
   },
-  "include": ["test/**/*.types.ts", "test/testing.test.ts"]
+  "include": ["test/**/*.types.ts", "test/testing.test.ts", "test/provider/checkpoint.test.ts"]
 }

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

@@ -0,0 +1,249 @@
+import { expect } from "bun:test"
+import { LLM, LLMRequest, Message } from "@opencode-ai/ai"
+import { LLMClient, RequestExecutor } from "@opencode-ai/ai/route"
+import { configure } from "@opencode-ai/ai/providers/openai"
+import { SessionModelTransport } from "../src/session/model-transport"
+import { WebSocketConstructor } from "../src/effect/websocket-constructor"
+import { Session } from "@opencode-ai/schema/session"
+import { Deferred, Effect, Fiber, Layer, Schema } from "effect"
+import { FetchHttpClient } from "effect/unstable/http"
+import { testEffect } from "./lib/effect"
+
+const runtime = Layer.mergeAll(
+  LLMClient.layer.pipe(Layer.provide(RequestExecutor.layer), Layer.provide(FetchHttpClient.layer)),
+  SessionModelTransport.layer.pipe(Layer.provide(WebSocketConstructor.layer)),
+)
+const it = testEffect(runtime)
+const sessionID = Session.ID.make("ses_checkpoint_transport")
+const checkpoint = { type: "compaction", encrypted_content: "opaque" }
+type Mode =
+  | "success"
+  | "missing"
+  | "multiple"
+  | "incomplete"
+  | "disconnect"
+  | "cancel"
+  | "rejected"
+  | "ambiguous"
+  | "fallback"
+
+const fixture = (mode: Mode) =>
+  Effect.gen(function* () {
+    const seen = yield* Deferred.make<void>()
+    const requests: Array<Record<string, unknown>> = []
+    const headers: Array<Record<string, string>> = []
+    const http: Array<Record<string, unknown>> = []
+    let opens = 0
+    let closes = 0
+    let socket: Bun.ServerWebSocket<undefined> | undefined
+    const server = yield* Effect.acquireRelease(
+      Effect.sync(() =>
+        Bun.serve({
+          hostname: "127.0.0.1",
+          port: 0,
+          async fetch(request, server) {
+            headers.push(Object.fromEntries(request.headers))
+            if (request.headers.get("upgrade") === "websocket") {
+              if (mode === "fallback" && opens > 0) return new Response("rejected upgrade", { status: 426 })
+              if (server.upgrade(request)) return
+              return new Response("upgrade required", { status: 426 })
+            }
+            http.push(Schema.decodeUnknownSync(Schema.Record(Schema.String, Schema.Unknown))(await request.json()))
+            return new Response(
+              `data: ${JSON.stringify({
+                type: "response.completed",
+                response: {
+                  id: "resp_http",
+                  output: [checkpoint],
+                  usage: { input_tokens: 70, output_tokens: 7 },
+                },
+              })}\n\n`,
+              { headers: { "content-type": "text/event-stream", "x-response": "http" } },
+            )
+          },
+          websocket: {
+            open(value) {
+              socket = value
+              opens++
+            },
+            close() {
+              closes++
+            },
+            message(socket, message) {
+              const body = JSON.parse(message.toString())
+              requests.push(body)
+              const id = `resp_${requests.length}`
+              const send = (event: unknown) => socket.send(JSON.stringify(event))
+              if (body.input.at(-1)?.type !== "compaction_trigger") {
+                const item = {
+                  type: "message",
+                  id: `msg_${requests.length}`,
+                  role: "assistant",
+                  content: [{ type: "output_text", text: "Hello" }],
+                }
+                send({ type: "response.created", response: { id } })
+                send({ type: "response.output_item.added", output_index: 0, item })
+                send({ type: "response.output_text.delta", item_id: item.id, delta: "Hello" })
+                send({ type: "response.output_item.done", output_index: 0, item })
+                send({ type: "response.completed", response: { id, output: [item] } })
+                return
+              }
+              if (mode === "ambiguous") {
+                socket.close()
+                return
+              }
+              if (mode === "rejected") {
+                send({ type: "error", error: { code: "previous_response_not_found", message: "missing baseline" } })
+                return
+              }
+              send({ type: "response.created", response: { id } })
+              if (mode !== "missing") send({ type: "response.output_item.done", output_index: 0, item: checkpoint })
+              Deferred.doneUnsafe(seen, Effect.void)
+              if (mode === "cancel") return
+              if (mode === "disconnect") {
+                socket.close()
+                return
+              }
+              send({
+                type: mode === "incomplete" ? "response.incomplete" : "response.completed",
+                response: {
+                  id,
+                  output:
+                    mode === "missing"
+                      ? []
+                      : mode === "multiple"
+                        ? [checkpoint, { ...checkpoint, encrypted_content: "second" }]
+                        : [checkpoint],
+                  usage: { input_tokens: 100, output_tokens: 10 },
+                },
+              })
+            },
+          },
+        }),
+      ),
+      (server) => Effect.promise(() => server.stop(true)),
+    )
+    return {
+      requests,
+      headers,
+      http,
+      seen,
+      opens: () => opens,
+      closes: () => closes,
+      disconnect: () => socket?.close(),
+      request: LLM.request({
+        model: configure({
+          apiKey: "fixture",
+          baseURL: server.url.toString(),
+          headers: { "chatgpt-account-id": "account", "x-codex-beta-features": "remote_compaction_v2" },
+          providerOptions: { parallelToolCalls: true },
+        }).responses("fixture"),
+        prompt: "First",
+        promptCacheKey: "session-key",
+      }),
+    }
+  })
+
+it.live("trigger reuses the append baseline and clears it before the next generation", () =>
+  Effect.gen(function* () {
+    const server = yield* fixture("success")
+    const transport = yield* SessionModelTransport.Service
+    const webSocket = transport.bind(sessionID)
+    const first = yield* LLMClient.generate(server.request, { webSocket })
+    const compacted = yield* LLMClient.compact(
+      LLMRequest.update(server.request, {
+        messages: [...server.request.messages, first.message],
+      }),
+      { mechanism: "trigger", webSocket },
+    )
+    expect(server.requests[1]).toMatchObject({
+      previous_response_id: "resp_1",
+      input: [{ type: "compaction_trigger" }],
+    })
+    expect(compacted.responseID).toBe("resp_2")
+    expect(compacted.usage).toMatchObject({ inputTokens: 100, outputTokens: 10 })
+    expect(compacted.checkpoint.encrypted).toBe("opaque")
+    const messages = [Message.assistant(compacted.checkpoint), Message.user("Continue")]
+    yield* LLMClient.generate(LLMRequest.update(server.request, { messages }), { webSocket })
+    expect(server.requests[2]?.previous_response_id).toBeUndefined()
+    expect(server.requests[2]?.input).toMatchObject([
+      { type: "compaction", encrypted_content: "opaque" },
+      { role: "user", content: [{ type: "input_text", text: "Continue" }] },
+    ])
+    expect(server.requests[1]?.stream).toBeUndefined()
+    expect(server.requests[1]?.store).toBe(false)
+    expect(server.headers[0]).toMatchObject({
+      authorization: "Bearer fixture",
+      "chatgpt-account-id": "account",
+      "x-codex-beta-features": "remote_compaction_v2",
+    })
+    expect(server.opens()).toBe(1)
+    expect(server.http).toHaveLength(0)
+  }),
+)
+
+for (const mode of ["missing", "multiple", "incomplete", "disconnect", "rejected", "ambiguous"] as const) {
+  it.live(`trigger ${mode} does not retry, fall back, or commit a continuation checkpoint`, () =>
+    Effect.gen(function* () {
+      const server = yield* fixture(mode)
+      const transport = yield* SessionModelTransport.Service
+      const webSocket = transport.bind(sessionID)
+      const first = yield* LLMClient.generate(server.request, { webSocket })
+      const input = LLMRequest.update(server.request, { messages: [...server.request.messages, first.message] })
+      const error = yield* LLMClient.compact(input, { mechanism: "trigger", webSocket }).pipe(Effect.flip)
+      expect(error.reason._tag).toBe(
+        ["disconnect", "ambiguous", "rejected"].includes(mode) ? "Transport" : "InvalidProviderOutput",
+      )
+      if (mode === "rejected") expect(error.reason).toMatchObject({ delivery: "rejected", recovery: "retry-full" })
+      if (mode === "ambiguous") expect(error.reason).toMatchObject({ delivery: "ambiguous" })
+      expect(server.requests).toHaveLength(2)
+      expect(server.http).toHaveLength(0)
+      yield* LLMClient.generate(input, { webSocket })
+      expect(server.requests[2]?.previous_response_id).toBeUndefined()
+      expect(server.requests[2]?.input).toHaveLength(2)
+    }),
+  )
+}
+
+it.live("cancelled trigger closes its connection without returning the partial checkpoint", () =>
+  Effect.gen(function* () {
+    const server = yield* fixture("cancel")
+    const transport = yield* SessionModelTransport.Service
+    const webSocket = transport.bind(sessionID)
+    const running = yield* LLMClient.compact(server.request, { mechanism: "trigger", webSocket }).pipe(
+      Effect.forkChild(),
+    )
+    yield* Deferred.await(server.seen)
+    yield* Fiber.interrupt(running)
+    yield* LLMClient.generate(server.request, { webSocket })
+    expect(server.requests).toHaveLength(2)
+    expect(server.opens()).toBe(2)
+    expect(server.requests[1]?.previous_response_id).toBeUndefined()
+    expect(server.http).toHaveLength(0)
+  }),
+)
+
+it.live("trigger recovers over SSE with complete input after the old socket closes and reconnect is rejected", () =>
+  Effect.gen(function* () {
+    const server = yield* fixture("fallback")
+    const transport = yield* SessionModelTransport.Service
+    const webSocket = transport.bind(sessionID)
+    const first = yield* LLMClient.generate(server.request, { webSocket })
+    server.disconnect()
+    // Let the real close event reach the connector before the next send.
+    yield* Effect.sleep("20 millis")
+    const result = yield* LLMClient.compact(
+      LLMRequest.update(server.request, {
+        messages: [...server.request.messages, first.message],
+      }),
+      { mechanism: "trigger", webSocket },
+    )
+    expect(result.responseID).toBe("resp_http")
+    expect(result.usage).toMatchObject({ inputTokens: 70, outputTokens: 7 })
+    expect(server.http).toHaveLength(1)
+    expect(server.http[0]?.previous_response_id).toBeUndefined()
+    expect(server.http[0]?.stream).toBe(true)
+    expect(server.http[0]?.input).toHaveLength(3)
+    expect(server.requests).toHaveLength(1)
+  }),
+)