feat(ai): add streamed compaction triggers

Co-authored-by: thdxr <826656+thdxr@users.noreply.github.com>

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

@@ -423,14 +423,10 @@ export interface ParserState {
   readonly name: string
   readonly providerMetadataKey: string
   readonly tools: ToolStream.State<string>
-  // 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
-  readonly completedMessages: ReadonlySet<string>
   readonly reasoningItems: Readonly<Record<string, ReasoningStreamItem>>
 }
 
@@ -924,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>> = {
@@ -936,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 ??
@@ -946,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,
@@ -1042,16 +1042,12 @@ const onOutputItemAdded = (state: ParserState, event: NormalizedEvent): StepResu
   const item = event.item
   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 !== 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 !== item.id)
       .reduce((lifecycle, id) => {
-        completedMessages.add(id)
         const openPhase = state.message?.id === id ? state.message.phase : undefined
         return Lifecycle.textEnd(
           lifecycle,
@@ -1064,7 +1060,6 @@ const onOutputItemAdded = (state: ParserState, event: NormalizedEvent): StepResu
       {
         ...state,
         lifecycle,
-        completedMessages,
         message: {
           id: item.id,
           phase: phase === undefined && state.message?.id === item.id ? state.message.phase : phase,
@@ -1094,7 +1089,7 @@ const onOutputItemAdded = (state: ParserState, event: NormalizedEvent): StepResu
     ]
   }
   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]
+  if (state.tools[item.id] !== undefined) return [state, NO_EVENTS]
   const metadata = providerMetadata(state, { itemId: item.id })
   const events: LLMEvent[] = []
   const lifecycle = Lifecycle.stepStart(state.lifecycle, events)
@@ -1198,14 +1193,9 @@ const onOutputItemDone = Effect.fn("OpenResponses.onOutputItemDone")(function* (
   }
 
   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)
-    if (state.message !== undefined && state.message.id !== item.id)
-      return [{ ...state, completedMessages }, NO_EVENTS] satisfies StepResult
-    const message = state.message
+    const active = state.message?.id === item.id
     const itemPhase = messagePhase(item.phase)
-    const phase = itemPhase === undefined ? message?.phase : itemPhase
+    const phase = itemPhase === undefined && active ? state.message?.phase : itemPhase
     const parts: ReadonlyArray<unknown> = Array.isArray(item.content) ? item.content : []
     const content: string[] = []
     for (const part of parts) {
@@ -1221,8 +1211,7 @@ const onOutputItemDone = Effect.fn("OpenResponses.onOutputItemDone")(function* (
       {
         ...state,
         lifecycle: Lifecycle.textEnd(lifecycle, events, item.id, metadata, text),
-        completedMessages,
-        message: undefined,
+        message: active ? undefined : state.message,
       },
       events,
     ] satisfies StepResult
@@ -1230,7 +1219,6 @@ const onOutputItemDone = Effect.fn("OpenResponses.onOutputItemDone")(function* (
 
   if (item.type === "function_call") {
     if (!item.call_id || !item.name) return [state, NO_EVENTS] satisfies StepResult
-    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
@@ -1257,7 +1245,6 @@ 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, item.id]),
       },
       events,
     ] satisfies StepResult
@@ -1518,11 +1505,9 @@ export const initial = (request: LLMRequest, adapter: ProviderAdapter = BASE_ADA
   providerMetadataKey: metadataKey(request.model),
   hasFunctionCall: false,
   tools: ToolStream.empty<string>(),
-  completedTools: new Set<string>(),
   lifecycle: Lifecycle.initial(),
   outputItems: {},
   message: undefined,
-  completedMessages: new Set<string>(),
   reasoningItems: {},
 })
 

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

@@ -5,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/shared.ts

@@ -6,11 +6,13 @@ import { Headers, HttpClientRequest, HttpClientResponse } from "effect/unstable/
 import {
   InvalidProviderOutputError,
   InvalidRequestError,
+  UnsupportedOperationError,
   AIError,
   HttpContext,
   type ContentPart,
   type LLMRequest,
   type MediaPart,
+  type ProviderID,
   type TextPart,
   type ToolResultPart,
 } from "../schema/index.js"
@@ -254,6 +256,29 @@ export const invalidRequest = (message: string, cause?: unknown) =>
     reason: new InvalidRequestError({ message, cause }),
   })
 
+/**
+ * Canonical constructor for operations the selected route does not implement.
+ * Prefer this over `invalidRequest` when the failure is a missing route
+ * capability rather than a malformed caller input, so consumers can branch on
+ * `reason._tag` plus `reason.operation` instead of matching message text.
+ */
+export const unsupportedOperation = (input: {
+  readonly operation: string
+  readonly message: string
+  readonly provider?: ProviderID
+  readonly route?: string
+  readonly cause?: unknown
+}) =>
+  new AIError({
+    reason: new UnsupportedOperationError({
+      operation: input.operation,
+      message: input.message,
+      provider: input.provider,
+      route: input.route,
+      cause: input.cause,
+    }),
+  })
+
 export const imageResponse = Effect.fn("ProviderShared.imageResponse")(function* (
   route: string,
   name: string,

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/protocols/xai-responses.ts

@@ -46,9 +46,12 @@ 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* ProviderShared.unsupportedOperation({
+      operation: "in-band-compaction",
+      provider: request.model.provider,
+      route: request.model.route.id,
+      message: "xAI requires explicit compaction through LLMClient.compact; automatic context management is not supported",
+    })
   return yield* decodeBody(yield* OpenResponses.fromRequestWithAdapter(request, adapter))
 })
 

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,18 +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.invalidRequest(
-              `${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/errors.ts

@@ -35,6 +35,21 @@ export class InvalidRequestError extends Schema.TaggedError<InvalidRequestError>
   },
 ) {}
 
+/**
+ * A caller-requested operation the selected route does not implement, such as
+ * explicit compaction on a route without a compact endpoint. Detected locally
+ * before any network I/O, so unlike transport or provider-output failures it
+ * never carries HTTP context from a provider round-trip.
+ */
+export class UnsupportedOperationError extends Schema.TaggedError<UnsupportedOperationError>(
+  "AI.Error.UnsupportedOperation",
+)("UnsupportedOperation", {
+  ...ReasonFields,
+  operation: Schema.String,
+  provider: Schema.optional(ProviderID),
+  route: Schema.optional(RouteID),
+}) {}
+
 export class NoRouteError extends Schema.TaggedError<NoRouteError>("AI.Error.NoRoute")("NoRoute", {
   ...ReasonFields,
   route: RouteID,
@@ -107,6 +122,7 @@ export class UnknownProviderError extends Schema.TaggedError<UnknownProviderErro
 
 export const AIErrorReason = Schema.Union([
   InvalidRequestError,
+  UnsupportedOperationError,
   NoRouteError,
   AuthenticationError,
   RateLimitError,

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

@@ -1,8 +1,10 @@
 import { expect, test } from "bun:test"
-import { Schema } from "effect"
+import { Effect, 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"
+import { testEffect } from "./lib/effect.js"
+import { fixedResponse } from "./lib/http.js"
 
 test("runtime capability checks follow model and route updates", () => {
   const supported = OpenAI.configure({ apiKey: "test" }).responses("fixture")
@@ -75,3 +77,25 @@ test("tagged content and event guards accept both checkpoint representations", (
     expect(Schema.decodeSync(codec)(Schema.encodeSync(codec)(message))).toEqual(message)
   }
 })
+
+testEffect(fixedResponse("")).effect(
+  "explicit compaction on a route without a compact endpoint fails with UnsupportedOperation",
+  () =>
+    Effect.gen(function* () {
+      const request = LLM.request({
+        model: Anthropic.configure({ apiKey: "test" }).model("fixture"),
+        prompt: "hello",
+      })
+      expect(LLMClient.canCompact(request)).toBe(false)
+      const error = yield* LLMClient.compact(
+        request as unknown as Parameters<typeof LLMClient.compact>[0],
+      ).pipe(Effect.flip)
+      expect(error.reason._tag).toBe("UnsupportedOperation")
+      expect(error.message).toContain("does not support explicit compaction")
+      if (error.reason._tag === "UnsupportedOperation") {
+        expect(error.reason.operation).toBe("compact")
+        expect(error.reason.provider).toBe("anthropic")
+        expect(error.reason.route).toBe("anthropic-messages")
+      }
+    }),
+)

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

@@ -130,16 +130,22 @@ for (const model of [
           }),
         ],
       })
-      for (const candidate of [
-        LLMRequest.update(request, {
-          tools: [
-            { name: "unsupported", description: "Generation only", inputSchema: {}, native: { unsupported: {} } },
-          ],
-        }),
-        LLMRequest.update(request, { providerOptions: { contextManagement: "invalid-generation-option" } }),
-      ]) {
+      for (const [candidate, tag] of [
+        [
+          LLMRequest.update(request, {
+            tools: [
+              { name: "unsupported", description: "Generation only", inputSchema: {}, native: { unsupported: {} } },
+            ],
+          }),
+          "InvalidRequest",
+        ],
+        [
+          LLMRequest.update(request, { providerOptions: { contextManagement: "invalid-generation-option" } }),
+          model.provider === "xai" ? "UnsupportedOperation" : "InvalidRequest",
+        ],
+      ] as const) {
         const error = yield* LLMClient.generate(candidate).pipe(Effect.flip)
-        expect(error.reason._tag).toBe("InvalidRequest")
+        expect(error.reason._tag).toBe(tag)
         const response = yield* LLMClient.compact(candidate)
         expect(response.replacement[0]?.content[0]?.type).toBe("compaction")
       }
@@ -361,8 +367,9 @@ testEffect(fixedResponse("must not execute")).effect("xAI rejects automatic comp
       { providerOptions: { contextManagement: [{ type: "compaction" }] } },
     )
     const error = yield* LLMClient.generate(request).pipe(Effect.flip)
-    expect(error.reason._tag).toBe("InvalidRequest")
+    expect(error.reason._tag).toBe("UnsupportedOperation")
     expect(error.message).toContain("LLMClient.compact")
+    if (error.reason._tag === "UnsupportedOperation") expect(error.reason.operation).toBe("in-band-compaction")
   }),
 )
 
@@ -428,7 +435,9 @@ for (const model of [
       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")
+        expect(error.reason._tag).toBe("UnsupportedOperation")
+        expect(error.message).toContain("does not support explicit compaction")
+        if (error.reason._tag === "UnsupportedOperation") expect(error.reason.operation).toBe("compact")
       }),
   )
 }

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

@@ -82,32 +82,6 @@ describe("Open Responses completed item text", () => {
       expect(response.events.filter(LLMEvent.is.textStart)).toEqual([])
     }),
   )
-
-  it.effect("assembles a done-only message once across replayed item events", () =>
-    Effect.gen(function* () {
-      const item = {
-        type: "message",
-        id: "msg_1",
-        content: [{ type: "output_text", text: "Recovered" }],
-      }
-      const response = yield* generate(
-        { type: "response.output_text.delta", item_id: "msg_1", delta: "Ignored after resume" },
-        { type: "response.output_item.done", item },
-        { type: "response.output_item.added", item },
-        { type: "response.output_item.done", item },
-        completed,
-      )
-      expect(response.text).toBe("Recovered")
-      expect(response.message.content).toEqual([
-        {
-          type: "text",
-          text: "Recovered",
-          providerMetadata: { "openai-compatible": { itemId: "msg_1" } },
-        },
-      ])
-      expect(response.events.filter(LLMEvent.is.textEnd)).toHaveLength(1)
-    }),
-  )
 })
 
 describe("Open Responses completed item reasoning", () => {

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

@@ -217,7 +217,7 @@ describe("Open Responses basic-item lifecycles", () => {
     }),
   )
 
-  it.effect("preserves non-empty done-only message content without replaying duplicates", () =>
+  it.effect("preserves non-empty done-only message content", () =>
     Effect.gen(function* () {
       const text = {
         type: "message",
@@ -230,17 +230,11 @@ describe("Open Responses basic-item lifecycles", () => {
         content: [{ type: "refusal", refusal: "Done-only refusal." }],
       }
       const events = yield* collect(
-        { type: "response.output_item.done", item: text },
         { type: "response.output_item.done", item: text },
         {
           type: "response.output_item.done",
           item: { type: "message", id: "msg_empty", content: [{ type: "output_text", text: "" }] },
         },
-        {
-          type: "response.output_item.done",
-          item: { type: "message", id: "msg_empty", content: [{ type: "output_text", text: "Late" }] },
-        },
-        { type: "response.output_item.done", item: refusal },
         { type: "response.output_item.done", item: refusal },
         completed,
       )
@@ -272,63 +266,6 @@ describe("Open Responses basic-item lifecycles", () => {
     }),
   )
 
-  it.effect("treats a repeated message lifecycle as replay", () =>
-    Effect.gen(function* () {
-      const events = yield* collect(
-        { type: "response.output_item.added", item: { type: "message", id: "msg_1", phase: "commentary" } },
-        { type: "response.output_text.delta", item_id: "msg_1", delta: "First" },
-        { type: "response.output_item.done", item: { type: "message", id: "msg_1" } },
-        { type: "response.output_item.added", item: { type: "message", id: "msg_1" } },
-        { type: "response.output_text.delta", item_id: "msg_1", delta: "Second" },
-        { type: "response.output_item.done", item: { type: "message", id: "msg_1" } },
-        completed,
-      )
-      expect(events.filter(LLMEvent.is.textEnd)).toEqual([
-        {
-          type: "text-end",
-          id: "msg_1",
-          providerMetadata: { "openai-compatible": { itemId: "msg_1", phase: "commentary" } },
-        },
-      ])
-      expect(events.filter(LLMEvent.is.textDelta).map((event) => event.text)).toEqual(["First"])
-    }),
-  )
-
-  it.effect("ignores a stale done-only message while another message is active", () =>
-    Effect.gen(function* () {
-      const events = yield* collect(
-        { type: "response.output_item.added", item: { type: "message", id: "msg_1", phase: "commentary" } },
-        { type: "response.output_text.delta", item_id: "msg_1", delta: "Draft" },
-        {
-          type: "response.output_item.done",
-          item: { type: "message", id: "msg_2", content: [{ type: "output_text", text: "Recovered" }] },
-        },
-        {
-          type: "response.output_item.done",
-          item: { type: "message", id: "msg_1", content: [{ type: "output_text", text: "Final" }] },
-        },
-        {
-          type: "response.output_item.done",
-          item: { type: "message", id: "msg_2", content: [{ type: "output_text", text: "Late" }] },
-        },
-        completed,
-      )
-      expect(events.filter((event) => event.type.startsWith("text-"))).toEqual([
-        {
-          type: "text-start",
-          id: "msg_1",
-          providerMetadata: { "openai-compatible": { itemId: "msg_1", phase: "commentary" } },
-        },
-        { type: "text-delta", id: "msg_1", text: "Draft" },
-        {
-          type: "text-end",
-          id: "msg_1",
-          text: "Final",
-          providerMetadata: { "openai-compatible": { itemId: "msg_1", phase: "commentary" } },
-        },
-      ])
-    }),
-  )
   // 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", () =>
@@ -419,7 +356,7 @@ describe("Open Responses basic-item lifecycles", () => {
     }),
   )
 
-  it.effect("opens and closes a done-only tool once", () =>
+  it.effect("opens and closes a done-only tool", () =>
     Effect.gen(function* () {
       const item = {
         type: "function_call",
@@ -428,12 +365,7 @@ describe("Open Responses basic-item lifecycles", () => {
         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 events = yield* collect({ type: "response.output_item.done", 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 },

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

@@ -2850,7 +2850,7 @@ describe("OpenAI Responses route", () => {
     }),
   )
 
-  it.effect("ignores duplicate item boundary events", () =>
+  it.effect("ignores duplicate item start events", () =>
     Effect.gen(function* () {
       const response = yield* LLMClient.generate(request).pipe(
         Effect.provide(
@@ -2881,21 +2881,6 @@ describe("OpenAI Responses route", () => {
                   arguments: '{"query":"weather"}',
                 },
               },
-              {
-                type: "response.output_item.done",
-                item: {
-                  type: "function_call",
-                  id: "fc_1",
-                  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", id: "fc_1", call_id: "call_1", name: "lookup", arguments: "" },
-              },
               { type: "response.completed", response: { id: "resp_1" } },
             ),
           ),

packages/ai/test/schema.test.ts

@@ -24,6 +24,7 @@ import {
   ToolResultValue,
   TransportError,
   UnknownProviderError,
+  UnsupportedOperationError,
   Usage,
 } from "../src/schema/index.js"
 import { ProviderShared } from "../src/protocols/shared.js"
@@ -276,6 +277,12 @@ test("AI errors serialize diagnostics only on their typed reason", () => {
 test("AI error reasons are tagged Errors with required messages", () => {
   const reasons = [
     new InvalidRequestError({ message: "Invalid request" }),
+    new UnsupportedOperationError({
+      message: "Unsupported operation",
+      operation: "compact",
+      provider: model.provider,
+      route: "fake-route",
+    }),
     new NoRouteError({
       message: "No route",
       route: RouteID.make("missing"),
@@ -293,6 +300,7 @@ test("AI error reasons are tagged Errors with required messages", () => {
   ]
   expect(reasons.map((reason) => reason._tag)).toEqual([
     "InvalidRequest",
+    "UnsupportedOperation",
     "NoRoute",
     "Authentication",
     "RateLimit",

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/app/e2e/regression/workspace-accent.spec.ts

@@ -78,9 +78,13 @@ for (const theme of ["light", "dark"] as const) {
         await expectToken(
           message,
           "background-color",
-          scenario.accent ? "--v2-background-bg-accent" : "--v2-state-bg-info",
+          scenario.accent ? "--v2-background-bg-accent" : theme === "light" ? "--v2-blue-100" : "--v2-blue-1200",
+        )
+        await expectToken(
+          message,
+          "color",
+          scenario.accent ? "--v2-text-text-contrast" : theme === "light" ? "--v2-blue-700" : "--v2-blue-300",
         )
-        await expectToken(message, "color", scenario.accent ? "--v2-text-text-contrast" : "--v2-text-text-accent")
       })
     }
 

packages/app/src/composer/composer.tsx

@@ -26,7 +26,8 @@ export function Composer(props: { class?: string; model: ComposerModel; borderUn
         modelControlsVisible={!props.model.model.loading}
         attachKeybind={command.keybindParts("file.attach")}
         attachShortcut={command.keybind("file.attach")}
-        alternateKeybind={[formatKeybind("mod", language.t), formatKeybind("enter", language.t)]}
+        alternateKeybind={[formatKeybind("mod", language.t), "↵"]}
+        exitShellKeybind={[formatKeybind("esc", language.t)]}
         modelControl={
           <ComposerModelControl
             loading={props.model.model.loading}

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

@@ -6,3 +6,7 @@
 [data-color-scheme="dark"] [data-component="new-session"] [data-component="composer"] {
   background: var(--v2-background-bg-layer-01);
 }
+
+[data-color-scheme="dark"] [data-component="composer-suggestions"] [data-active] {
+  background: var(--v2-alpha-light-10);
+}

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

@@ -47,6 +47,7 @@ export type ComposerEditorProps = {
   attachKeybind?: string[]
   attachShortcut?: string
   alternateKeybind?: string[]
+  exitShellKeybind?: string[]
 }
 
 export function ComposerEditor(props: ComposerEditorProps) {
@@ -281,6 +282,24 @@ export function ComposerEditor(props: ComposerEditorProps) {
               keybind={props.alternateKeybind ?? ["Mod", "Enter"]}
             />
           </Show>
+          <Show when={state.mode === "shell"}>
+            <Button
+              data-action="composer-exit-shell"
+              type="button"
+              variant="ghost-faint"
+              size="small"
+              class="me-3 gap-1.5 px-1.5"
+              onClick={() => {
+                props.controller.dispatch({ type: "mode.normal" })
+                props.controller.restoreFocus()
+              }}
+            >
+              {i18n.t("ui.promptInput.exitShell")}
+              <span class="hidden sm:block">
+                <Keybind keys={props.exitShellKeybind ?? ["ESC"]} variant="neutral" />
+              </span>
+            </Button>
+          </Show>
           <ComposerEditorSubmitButton
             mode={state.mode}
             stopping={view.submit.stopping()}
@@ -673,6 +692,7 @@ export function ComposerEditorPopover(props: {
 }) {
   return (
     <div
+      data-component="composer-suggestions"
       class="absolute inset-x-0 -top-2 z-40 flex max-h-80 -translate-y-full flex-col overflow-auto rounded-xl bg-v2-background-bg-base p-2 shadow-[var(--v2-elevation-raised)] no-scrollbar"
       onMouseDown={(event) => event.preventDefault()}
     >
@@ -701,6 +721,7 @@ export function ComposerEditorPopover(props: {
             <button
               type="button"
               data-suggestion-id={item.id}
+              data-active={props.activeID === item.id ? "" : undefined}
               class="flex w-full items-center gap-2 rounded-md px-2 py-1 text-start hover:bg-v2-overlay-simple-overlay-hover"
               classList={{ "bg-v2-overlay-simple-overlay-hover": props.activeID === item.id }}
               onPointerMove={() => props.onActiveChange(item)}
@@ -749,9 +770,9 @@ function ComposerEditorAlternateDelivery(props: { controller: ComposerEditorMode
             ref={setButton}
             data-action="composer-alternate-delivery"
             type="button"
-            variant="ghost-muted"
+            variant="ghost-faint"
             size="small"
-            class="me-3 gap-1.5 px-1.5 text-v2-text-text-muted ![font-weight:530] duration-150 motion-reduce:animate-none"
+            class="me-3 gap-1.5 px-1.5 ![font-weight:530] duration-150 motion-reduce:animate-none"
             classList={{
               "animate-in fade-in": presence.animate() && presence.show(),
               "animate-out fade-out fill-mode-forwards": presence.animate() && !presence.show(),

packages/app/src/home/model.ts

@@ -3,7 +3,8 @@ import { type HomeProjectSelection, useLayout } from "@/shell/state/layout"
 import { ServerConnection, useServers } from "@/runtime/server/registry"
 import { useTabs } from "@/shell/tabs/tabs"
 import { toggleHomeProjectSelection } from "@/shell/layout/helpers"
-import { createEffect, createMemo } from "solid-js"
+import { createEffect, createMemo, startTransition } from "solid-js"
+import type { SessionInfo } from "@opencode-ai/client/promise"
 
 export function createHomeController() {
   const layout = useLayout()
@@ -45,6 +46,18 @@ export function createHomeController() {
     void tabs.newDraft({ server: ServerConnection.key(conn), directory })
   }
 
+  function openProjectSession(conn: ServerConnection.Any, directory: string, session: SessionInfo) {
+    const ctx = global.ensureServerCtx(conn)
+    void ctx.data.session.message.sync(session.id).catch(() => undefined)
+    void startTransition(() => {
+      const tab = tabs.addSessionTab({ server: ServerConnection.key(conn), sessionId: session.id })
+      tabs.select(tab)
+      ctx.data.session.remember(session)
+      ctx.projects.open(directory)
+      ctx.projects.touch(directory)
+    })
+  }
+
   return {
     selection: {
       value: selection,
@@ -105,6 +118,7 @@ export function createHomeController() {
         openProjectNewSession(conn, project.worktree)
       },
       openProjectNewSession,
+      openProjectSession,
     },
   }
 }

packages/app/src/home/projects/controller.tsx

@@ -14,6 +14,7 @@ import { Schema } from "effect"
 import { Persistence } from "@/runtime/persistence/schema"
 import type { HomeController } from "../model"
 import { useGlobal } from "@/runtime/server/runtime"
+import { SessionTransfer } from "@opencode-ai/schema/session-transfer"
 
 export const HomeServersSchema = Schema.Struct({
   collapsed: Persistence.record(Persistence.fallback(Schema.Boolean, () => false)),
@@ -79,6 +80,35 @@ export function createHomeProjectsController(home: HomeController) {
       select: home.project.select,
       add: home.project.add,
       openNewSession: home.project.openProjectNewSession,
+      canImportSession: !!platform.openAttachmentPickerDialog,
+      importSession: (conn: ServerConnection.Any, project: LocalProject) => {
+        if (!platform.openAttachmentPickerDialog) return
+        void platform
+          .openAttachmentPickerDialog(
+            {
+              title: language.t("command.session.import"),
+              accept: ["application/json"],
+              extensions: ["json"],
+            },
+            async (file) => {
+              const data = await Schema.decodeUnknownPromise(Schema.fromJsonString(SessionTransfer.Data))(
+                await file.text(),
+              )
+              const api = home.server.context(conn).sdk.api.session
+              const imported = await api.import({
+                ...Schema.encodeSync(SessionTransfer.Data)(data),
+                location: { directory: project.worktree },
+              } as Parameters<typeof api.import>[0])
+              home.project.openProjectSession(conn, project.worktree, imported)
+            },
+          )
+          .catch((cause: unknown) => {
+            showToast({
+              title: language.t("common.requestFailed"),
+              description: errorMessage(cause, language.t("common.requestFailed")),
+            })
+          })
+      },
       edit: (conn: ServerConnection.Any, project: LocalProject) => {
         void import("@/settings/workspaces/project-dialog").then(({ DialogEditProject }) => {
           void dialog.show(() => <DialogEditProject server={conn} project={project} />)

packages/app/src/home/projects/region.tsx

@@ -37,6 +37,8 @@ export function HomeProjects(props: {
       onSelectProject={props.projects.project.select}
       onAddProjects={props.projects.project.add}
       onOpenProjectNewSession={props.projects.project.openNewSession}
+      canImportSession={props.projects.project.canImportSession}
+      onImportSession={props.projects.project.importSession}
       onEditProject={props.projects.project.edit}
       onRevealProject={props.projects.project.reveal}
       onClearNotifications={props.projects.project.clearNotifications}

packages/app/src/home/projects/view.tsx

@@ -57,6 +57,8 @@ export type HomeProjectsViewProps = {
   onSelectProject: (server: ServerConnection.Any, directory: string) => void
   onAddProjects: (server: ServerConnection.Any, directories: string[]) => void
   onOpenProjectNewSession: (server: ServerConnection.Any, directory: string) => void
+  canImportSession: boolean
+  onImportSession: (server: ServerConnection.Any, project: LocalProject) => void
   onEditProject: (server: ServerConnection.Any, project: LocalProject) => void
   onRevealProject: (server: ServerConnection.Any, project: LocalProject) => void
   onClearNotifications: (server: ServerConnection.Any, project: LocalProject) => void
@@ -670,6 +672,11 @@ function HomeProjectRow(
               <Menu.Item onSelect={() => props.onOpenProjectNewSession(props.server, props.project.worktree)}>
                 {props.language.t("command.session.new")}
               </Menu.Item>
+              <Show when={props.canImportSession}>
+                <Menu.Item onSelect={() => props.onImportSession(props.server, props.project)}>
+                  {props.language.t("command.session.import")}
+                </Menu.Item>
+              </Show>
               <Menu.Item onSelect={() => props.onEditProject(props.server, props.project)}>
                 {props.language.t("dialog.project.edit.title")}
               </Menu.Item>

packages/app/src/home/sessions/controller.tsx

@@ -21,7 +21,8 @@ import { errorMessage } from "@/shell/layout/helpers"
 import { useSessionTabAvatarState } from "@/shell/layout/project-avatar-state"
 import { removedSessionIDs } from "@/session/session-domain"
 import { pathKey } from "@/workspaces/path-key"
-import { downloadSessionExport, fetchSessionExport, sessionExportFilename } from "@/session/commands/export"
+import { fetchSessionExport, saveSessionExport, sessionExportFilename } from "@/session/commands/export"
+import { usePlatform } from "@/runtime/platform/platform"
 import { sessionLabel, sessionTitle } from "@/session/title"
 import { showToast } from "@/shell/notifications/toast"
 import { archiveHomeSession } from "./archive"
@@ -45,6 +46,7 @@ export function createHomeSessionsController(home: HomeController) {
   const command = useCommand()
   const dialog = useDialog()
   const language = useLanguage()
+  const platform = usePlatform()
   const queryClient = useQueryClient()
   const projectDirectories = createMemo(() => {
     const selected = home.selection.value().directory
@@ -172,7 +174,7 @@ export function createHomeSessionsController(home: HomeController) {
     try {
       const data = await fetchSessionExport({ sessionID: session.id, api: ctx.sdk.api })
       const filename = sessionExportFilename(data.info)
-      downloadSessionExport(filename, data)
+      if (!(await saveSessionExport(filename, data, platform))) return
       showToast({
         variant: "success",
         icon: "circle-check",

packages/app/src/runtime/i18n/am.ts

@@ -133,6 +133,7 @@ export const dict = {
   "command.language.cycle": "ሳይክል ቋንቋ",
   "command.language.set": "ቋንቋን ተጠቀም፡ {{language}}",
   "command.session.new": "አዲስ ክፍለ ጊዜ",
+  "command.session.import": "ክፍለ ጊዜ ማስመጣት",
   "command.file.open": "ክፍት ፋይል",
   "command.tab.close": "ትርፉን ዝጋ",
   "command.tab.reopenClosed": "የተዘጋውን ትር እንደገና ክፈት",

packages/app/src/runtime/i18n/ar.ts

@@ -139,6 +139,7 @@ export const dict = {
   "command.language.cycle": "تغيير اللغة",
   "command.language.set": "استخدام اللغة: {{language}}",
   "command.session.new": "جلسة جديدة",
+  "command.session.import": "استيراد جلسة",
   "command.file.open": "فتح ملف",
   "command.tab.close": "إغلاق علامة التبويب",
   "command.tab.reopenClosed": "إعادة فتح علامة التبويب المغلقة",

packages/app/src/runtime/i18n/az.ts

@@ -135,6 +135,7 @@ export const dict = {
   "command.language.cycle": "Dili dəyiş",
   "command.language.set": "Dildən istifadə et: {{language}}",
   "command.session.new": "Yeni sessiya",
+  "command.session.import": "Sessiyanı idxal et",
   "command.file.open": "Faylı aç",
   "command.tab.close": "Tabı bağla",
   "command.tab.reopenClosed": "Bağlanmış tabı yenidən aç",

packages/app/src/runtime/i18n/bg.ts

@@ -135,6 +135,7 @@ export const dict = {
   "command.language.cycle": "Цикличен език",
   "command.language.set": "Използвайте език: {{language}}",
   "command.session.new": "Нова сесия",
+  "command.session.import": "Импортиране на сесия",
   "command.file.open": "Отворете файла",
   "command.tab.close": "Затваряне на раздела",
   "command.tab.reopenClosed": "Повторно отваряне на затворен раздел",

packages/app/src/runtime/i18n/bn.ts

@@ -134,6 +134,7 @@ export const dict: Record<string, string> = {
   "command.language.cycle": "সাইকেল ভাষা",
   "command.language.set": "ভাষা ব্যবহার করুন: {{language}}",
   "command.session.new": "নতুন সেশন",
+  "command.session.import": "সেশন আমদানি করুন",
   "command.file.open": "ফাইল খুলুন",
   "command.tab.close": "ট্যাব বন্ধ করুন",
   "command.tab.reopenClosed": "বন্ধ ট্যাব আবার খুলুন",

packages/app/src/runtime/i18n/br.ts

@@ -141,6 +141,7 @@ export const dict = {
   "command.language.cycle": "Alternar idioma",
   "command.language.set": "Usar idioma: {{language}}",
   "command.session.new": "Nova sessão",
+  "command.session.import": "Importar sessão",
   "command.file.open": "Abrir arquivo",
   "command.tab.close": "Fechar aba",
   "command.tab.reopenClosed": "Reabrir aba fechada",

packages/app/src/runtime/i18n/bs.ts

@@ -147,6 +147,7 @@ export const dict = {
   "command.language.set": "Koristi jezik: {{language}}",
 
   "command.session.new": "Nova sesija",
+  "command.session.import": "Uvezi sesiju",
   "command.file.open": "Otvori datoteku",
   "command.tab.close": "Zatvori karticu",
   "command.tab.reopenClosed": "Ponovo otvori zatvorenu karticu",

packages/app/src/runtime/i18n/ca.ts

@@ -135,6 +135,7 @@ export const dict = {
   "command.language.cycle": "Llenguatge de cicle",
   "command.language.set": "Utilitza l'idioma: {{language}}",
   "command.session.new": "Nova sessió",
+  "command.session.import": "Importa la sessió",
   "command.file.open": "Obre el fitxer",
   "command.tab.close": "Tanca la pestanya",
   "command.tab.reopenClosed": "Torneu a obrir la pestanya tancada",

packages/app/src/runtime/i18n/cs.ts

@@ -133,6 +133,7 @@ export const dict = {
   "command.language.cycle": "Jazyk cyklu",
   "command.language.set": "Použít jazyk: {{language}}",
   "command.session.new": "Nová relace",
+  "command.session.import": "Importovat relaci",
   "command.file.open": "Otevřít soubor",
   "command.tab.close": "Zavřít kartu",
   "command.tab.reopenClosed": "Znovu otevřete zavřenou kartu",

packages/app/src/runtime/i18n/da.ts

@@ -46,6 +46,7 @@ export const dict = {
   "command.language.set": "Brug sprog: {{language}}",
 
   "command.session.new": "Ny session",
+  "command.session.import": "Importer session",
   "command.file.open": "Åbn fil",
   "command.tab.close": "Luk fane",
   "command.tab.reopenClosed": "Åbn lukket fane igen",

packages/app/src/runtime/i18n/de.ts

@@ -44,6 +44,7 @@ export const dict = {
   "command.language.cycle": "Sprache wechseln",
   "command.language.set": "Sprache verwenden: {{language}}",
   "command.session.new": "Neue Sitzung",
+  "command.session.import": "Sitzung importieren",
   "command.file.open": "Datei öffnen",
   "command.tab.close": "Tab schließen",
   "command.tab.reopenClosed": "Geschlossenen Tab wieder öffnen",

packages/app/src/runtime/i18n/dv.ts

@@ -136,6 +136,7 @@ export const dict = {
   "command.language.cycle": "ސައިކަލް ބަސް",
   "command.language.set": "ބަސް ބޭނުންކުރުން: {{language}}",
   "command.session.new": "އާ ޖަލްސާއެއް",
+  "command.session.import": "ޖަލްސާ އިމްޕޯޓް ކުރައްވާ",
   "command.file.open": "ފައިލް ހުޅުވާލާށެވެ",
   "command.tab.close": "ޓެބް ބަންދުކުރުން",
   "command.tab.reopenClosed": "ބަންދުކޮށްފައިވާ ޓެބް އަލުން ހުޅުވާލާށެވެ",

packages/app/src/runtime/i18n/dz.ts

@@ -136,6 +136,7 @@ export const dict: Record<string, string> = {
   "command.language.cycle": "འཁོར་བའི་སྐད་ཡིག།",
   "command.language.set": "སྐད་ཡིག་ལག་ལེན་འཐབ།: {{language}}",
   "command.session.new": "ལཱ་ཡུན་གསརཔ།",
+  "command.session.import": "ལཱ་ཡུན་ནང་འདྲེན།",
   "command.file.open": "ཡིག་སྣོད་ཁ་ཕྱེ།",
   "command.tab.close": "མཆོང་ལྡེ་ཁ་བསྡམས།",
   "command.tab.reopenClosed": "ཁ་བསྡམས་ཡོད་པའི་མཆོང་ལྡེ་ལོག་ཁ་ཕྱེ།",

packages/app/src/runtime/i18n/el.ts

@@ -134,6 +134,7 @@ export const dict = {
   "command.language.cycle": "Γλώσσα κύκλου",
   "command.language.set": "Γλώσσα χρήσης: {{language}}",
   "command.session.new": "Νέα συνεδρία",
+  "command.session.import": "Εισαγωγή συνεδρίας",
   "command.file.open": "Άνοιγμα αρχείου",
   "command.tab.close": "Κλείσιμο καρτέλας",
   "command.tab.reopenClosed": "Άνοιγμα ξανά κλειστής καρτέλας",

packages/app/src/runtime/i18n/en.ts

@@ -100,6 +100,7 @@ export const dict = {
   "command.session.fork.description": "Create a new session from a previous message",
   "command.session.export": "Export session",
   "command.session.export.description": "Export the full session transcript as JSON",
+  "command.session.import": "Import session",
   "command.session.copyID": "Copy Session ID",
 
   "palette.search.placeholder": "Search files, commands, and sessions",
@@ -675,11 +676,14 @@ export const dict = {
   "session.error.incompatible.description":
     "{{server}} is running OpenCode {{version}}, which isn't compatible with this app. Upgrade the server to OpenCode V2 to continue.",
   "session.background.moveTasks": "Move {{tasks}} to background",
+  "session.background.moveRunning": "Move running work to background",
   "session.background.inBackground": "Running {{tasks}} in background",
   "session.background.moveInline": "Press {{keybind}} to move running work to the background",
   "session.background.running": "Running work in background",
   "session.background.runningCount.one": "{{count}} item running in background",
   "session.background.runningCount.other": "{{count}} items running in background",
+  "session.background.tasksRunning.one": "{{count}} background task running",
+  "session.background.tasksRunning.other": "{{count}} background tasks running",
   "session.background.combine": "{{first}} and {{second}}",
   "session.background.shell.one": "{{count}} shell",
   "session.background.shell.other": "{{count}} shells",

packages/app/src/runtime/i18n/es.ts

@@ -147,6 +147,7 @@ export const dict = {
   "command.language.set": "Usar idioma: {{language}}",
 
   "command.session.new": "Nueva sesión",
+  "command.session.import": "Importar sesión",
   "command.file.open": "Abrir archivo",
   "command.tab.close": "Cerrar pestaña",
   "command.tab.reopenClosed": "Reabrir pestaña cerrada",

packages/app/src/runtime/i18n/et.ts

@@ -133,6 +133,7 @@ export const dict = {
   "command.language.cycle": "Tsükli keel",
   "command.language.set": "Kasuta keelt: {{language}}",
   "command.session.new": "Uus seanss",
+  "command.session.import": "Impordi seanss",
   "command.file.open": "Ava fail",
   "command.tab.close": "Sule vahekaart",
   "command.tab.reopenClosed": "Ava suletud vaheleht uuesti",

packages/app/src/runtime/i18n/fa.ts

@@ -134,6 +134,7 @@ export const dict = {
   "command.language.cycle": "زبان چرخه",
   "command.language.set": "استفاده از زبان: {{language}}",
   "command.session.new": "جلسه جدید",
+  "command.session.import": "وارد کردن جلسه",
   "command.file.open": "باز کردن فایل",
   "command.tab.close": "بستن برگه",
   "command.tab.reopenClosed": "برگه بسته را دوباره باز کنید",

packages/app/src/runtime/i18n/fi.ts

@@ -40,6 +40,7 @@ export const dict = {
   "command.language.cycle": "Vaihda kieltä",
   "command.language.set": "Käytä kieltä: {{language}}",
   "command.session.new": "Uusi istunto",
+  "command.session.import": "Tuo istunto",
   "command.file.open": "Avaa tiedosto",
   "command.tab.close": "Sulje välilehti",
   "command.tab.reopenClosed": "Avaa suljettu välilehti uudelleen",

packages/app/src/runtime/i18n/fo.ts

@@ -133,6 +133,7 @@ export const dict = {
   "command.language.cycle": "Súkklumál",
   "command.language.set": "Brúka mál: {{language}}",
   "command.session.new": "Nýggj setan",
+  "command.session.import": "Innflyt setan",
   "command.file.open": "Opna fíluna",
   "command.tab.close": "Lat flipan aftur",
   "command.tab.reopenClosed": "Opna aftur stongdan flipan",

packages/app/src/runtime/i18n/fr.ts

@@ -141,6 +141,7 @@ export const dict = {
   "command.language.cycle": "Changer de langue",
   "command.language.set": "Utiliser la langue : {{language}}",
   "command.session.new": "Nouvelle session",
+  "command.session.import": "Importer une session",
   "command.file.open": "Ouvrir un fichier",
   "command.tab.close": "Fermer l'onglet",
   "command.tab.reopenClosed": "Rouvrir l'onglet fermé",

packages/app/src/runtime/i18n/he.ts

@@ -134,6 +134,7 @@ export const dict = {
   "command.language.cycle": "מעבר לשפה הבאה",
   "command.language.set": "השתמש בשפה: {{language}}",
   "command.session.new": "הפעלה חדשה",
+  "command.session.import": "ייבוא הפעלה",
   "command.file.open": "פתח את הקובץ",
   "command.tab.close": "סגור כרטיסייה",
   "command.tab.reopenClosed": "פתח מחדש את הכרטיסייה הסגורה",

packages/app/src/runtime/i18n/hi.ts

@@ -140,6 +140,7 @@ export const dict = {
   "command.language.cycle": "भाषा बदलें",
   "command.language.set": "भाषा का प्रयोग करें: {{language}}",
   "command.session.new": "नया सेशन",
+  "command.session.import": "सेशन आयात करें",
   "command.file.open": "फ़ाइल खोलें",
   "command.tab.close": "टैब बंद करें",
   "command.tab.reopenClosed": "बंद टैब पुनः खोलें",

packages/app/src/runtime/i18n/hr.ts

@@ -137,6 +137,7 @@ export const dict = {
   "command.language.cycle": "Promijeni jezik",
   "command.language.set": "Koristite jezik: {{language}}",
   "command.session.new": "Nova sesija",
+  "command.session.import": "Uvezi sesiju",
   "command.file.open": "Otvori datoteku",
   "command.tab.close": "Zatvori karticu",
   "command.tab.reopenClosed": "Ponovno otvori zatvorenu karticu",

packages/app/src/runtime/i18n/hu.ts

@@ -137,6 +137,7 @@ export const dict = {
   "command.language.cycle": "Nyelv váltása",
   "command.language.set": "Nyelv használata: {{language}}",
   "command.session.new": "Új munkamenet",
+  "command.session.import": "Munkamenet importálása",
   "command.file.open": "Nyissa meg a fájlt",
   "command.tab.close": "Lap bezárása",
   "command.tab.reopenClosed": "Nyissa meg újra a bezárt lapot",

packages/app/src/runtime/i18n/hy.ts

@@ -135,6 +135,7 @@ export const dict = {
   "command.language.cycle": "Ցիկլի լեզու",
   "command.language.set": "Օգտագործել լեզուն՝ {{language}}",
   "command.session.new": "Նոր նիստ",
+  "command.session.import": "Ներմուծել նիստը",
   "command.file.open": "Բացել ֆայլ",
   "command.tab.close": "Փակել ներդիրը",
   "command.tab.reopenClosed": "Վերաբացել փակ ներդիրը",

packages/app/src/runtime/i18n/id.ts

@@ -147,6 +147,7 @@ export const dict = {
   "command.language.set": "Gunakan bahasa: {{language}}",
 
   "command.session.new": "Sesi baru",
+  "command.session.import": "Impor sesi",
   "command.file.open": "Buka berkas",
   "command.tab.close": "Tutup tab",
   "command.tab.reopenClosed": "Buka kembali tab yang ditutup",

packages/app/src/runtime/i18n/is.ts

@@ -137,6 +137,7 @@ export const dict = {
   "command.language.cycle": "Skipta um tungumál",
   "command.language.set": "Notaðu tungumál: {{language}}",
   "command.session.new": "Ný seta",
+  "command.session.import": "Flytja inn setu",
   "command.file.open": "Opna skrá",
   "command.tab.close": "Loka flipa",
   "command.tab.reopenClosed": "Opnaðu aftur lokaðan flipa",

packages/app/src/runtime/i18n/it.ts

@@ -41,6 +41,7 @@ export const dict = {
   "command.language.cycle": "Cambia lingua",
   "command.language.set": "Usa la lingua: {{language}}",
   "command.session.new": "Nuova sessione",
+  "command.session.import": "Importa sessione",
   "command.file.open": "Apri file",
   "command.tab.close": "Chiudi scheda",
   "command.tab.reopenClosed": "Riapri la scheda chiusa",

packages/app/src/runtime/i18n/ja.ts

@@ -139,6 +139,7 @@ export const dict = {
   "command.language.cycle": "言語の切り替え",
   "command.language.set": "言語を使用: {{language}}",
   "command.session.new": "新しいセッション",
+  "command.session.import": "セッションをインポート",
   "command.file.open": "ファイルを開く",
   "command.tab.close": "タブを閉じる",
   "command.tab.reopenClosed": "閉じたタブを再度開く",

packages/app/src/runtime/i18n/ka.ts

@@ -133,6 +133,7 @@ export const dict = {
   "command.language.cycle": "ციკლის ენა",
   "command.language.set": "გამოიყენე ენა: {{language}}",
   "command.session.new": "ახალი სესია",
+  "command.session.import": "სესიის იმპორტი",
   "command.file.open": "გახსენით ფაილი",
   "command.tab.close": "ჩანართის დახურვა",
   "command.tab.reopenClosed": "დახურული ჩანართის ხელახლა გახსნა",

packages/app/src/runtime/i18n/km.ts

@@ -133,6 +133,7 @@ export const dict = {
   "command.language.cycle": "ភាសាវដ្ត",
   "command.language.set": "ប្រើភាសា៖ {{language}}",
   "command.session.new": "សម័យថ្មី។",
+  "command.session.import": "នាំចូលសម័យ",
   "command.file.open": "បើកឯកសារ",
   "command.tab.close": "បិទផ្ទាំង",
   "command.tab.reopenClosed": "បើកផ្ទាំងបិទឡើងវិញ",

packages/app/src/runtime/i18n/ko.ts

@@ -37,6 +37,7 @@ export const dict = {
   "command.language.cycle": "언어 순환",
   "command.language.set": "언어 사용: {{language}}",
   "command.session.new": "새 세션",
+  "command.session.import": "세션 가져오기",
   "command.file.open": "파일 열기",
   "command.tab.close": "탭 닫기",
   "command.context.addSelection": "선택 영역을 컨텍스트에 추가",

packages/app/src/runtime/i18n/lo.ts

@@ -133,6 +133,7 @@ export const dict = {
   "command.language.cycle": "ພາສາຮອບວຽນ",
   "command.language.set": "ໃຊ້ພາສາ: {{language}}",
   "command.session.new": "ເຊດຊັນໃໝ່",
+  "command.session.import": "ນຳເຂົ້າເຊດຊັນ",
   "command.file.open": "ເປີດໄຟລ໌",
   "command.tab.close": "ປິດແຖບ",
   "command.tab.reopenClosed": "ເປີດແຖບປິດຄືນໃໝ່",

packages/app/src/runtime/i18n/lt.ts

@@ -137,6 +137,7 @@ export const dict = {
   "command.language.cycle": "Perjungti kalbą",
   "command.language.set": "Naudokite kalbą: {{language}}",
   "command.session.new": "Naujas seansas",
+  "command.session.import": "Importuoti seansą",
   "command.file.open": "Atidaryti failą",
   "command.tab.close": "Uždaryti skirtuką",
   "command.tab.reopenClosed": "Iš naujo atidaryti uždarytą skirtuką",

packages/app/src/runtime/i18n/lv.ts

@@ -133,6 +133,7 @@ export const dict = {
   "command.language.cycle": "Mainīt valodu",
   "command.language.set": "Izmantot valodu: {{language}}",
   "command.session.new": "Jauna sesija",
+  "command.session.import": "Importēt sesiju",
   "command.file.open": "Atvērt failu",
   "command.tab.close": "Aizvērt cilni",
   "command.tab.reopenClosed": "Atvērt aizvērtu cilni",

packages/app/src/runtime/i18n/mk.ts

@@ -134,6 +134,7 @@ export const dict = {
   "command.language.cycle": "Јазик на циклус",
   "command.language.set": "Користете јазик: {{language}}",
   "command.session.new": "Нова сесија",
+  "command.session.import": "Увези сесија",
   "command.file.open": "Отворете ја датотеката",
   "command.tab.close": "Затвори ја картичката",
   "command.tab.reopenClosed": "Повторно отворете го затворениот таб",

packages/app/src/runtime/i18n/mn.ts

@@ -135,6 +135,7 @@ export const dict = {
   "command.language.cycle": "Циклийн хэл",
   "command.language.set": "Хэл ашиглах: {{language}}",
   "command.session.new": "Шинэ сесс",
+  "command.session.import": "Сесс импортлох",
   "command.file.open": "Файлыг нээх",
   "command.tab.close": "Табыг хаах",
   "command.tab.reopenClosed": "Хаагдсан табыг дахин нээнэ үү",

packages/app/src/runtime/i18n/ms.ts

@@ -133,6 +133,7 @@ export const dict = {
   "command.language.cycle": "Tukar bahasa",
   "command.language.set": "Guna bahasa: {{language}}",
   "command.session.new": "Sesi baharu",
+  "command.session.import": "Import sesi",
   "command.file.open": "Buka fail",
   "command.tab.close": "Tutup tab",
   "command.tab.reopenClosed": "Buka semula tab tertutup",

packages/app/src/runtime/i18n/my.ts

@@ -135,6 +135,7 @@ export const dict = {
   "command.language.cycle": "စက်ဝိုင်းဘာသာစကား",
   "command.language.set": "ဘာသာစကားကို အသုံးပြုပါ- {{language}}",
   "command.session.new": "စက်ရှင်အသစ်",
+  "command.session.import": "စက်ရှင် တင်သွင်းရန်",
   "command.file.open": "ဖိုင်ကိုဖွင့်ပါ။",
   "command.tab.close": "တဘ်ကို ပိတ်ပါ။",
   "command.tab.reopenClosed": "ပိတ်ထားသော တက်ဘ်ကို ပြန်ဖွင့်ပါ။",

packages/app/src/runtime/i18n/ne.ts

@@ -134,6 +134,7 @@ export const dict: Record<string, string> = {
   "command.language.cycle": "साइकल भाषा",
   "command.language.set": "भाषा प्रयोग गर्नुहोस्: {{language}}",
   "command.session.new": "नयाँ सत्र",
+  "command.session.import": "सत्र आयात गर्नुहोस्",
   "command.file.open": "फाइल खोल्नुहोस्",
   "command.tab.close": "ट्याब बन्द गर्नुहोस्",
   "command.tab.reopenClosed": "बन्द ट्याब पुन: खोल्नुहोस्",

packages/app/src/runtime/i18n/nl.ts

@@ -133,6 +133,7 @@ export const dict = {
   "command.language.cycle": "Volgende taal",
   "command.language.set": "Gebruik taal: {{language}}",
   "command.session.new": "Nieuwe sessie",
+  "command.session.import": "Sessie importeren",
   "command.file.open": "Bestand openen",
   "command.tab.close": "Tabblad sluiten",
   "command.tab.reopenClosed": "Gesloten tabblad opnieuw openen",

packages/app/src/runtime/i18n/no.ts

@@ -146,6 +146,7 @@ export const dict = {
   "command.language.set": "Bruk språk: {{language}}",
 
   "command.session.new": "Ny sesjon",
+  "command.session.import": "Importer sesjon",
   "command.file.open": "Åpne fil",
   "command.tab.close": "Lukk fane",
   "command.context.addSelection": "Legg til markering i kontekst",

packages/app/src/runtime/i18n/pa.ts

@@ -139,6 +139,7 @@ export const dict = {
   "command.language.cycle": "اگلی بولی ورتو",
   "command.language.set": "بولی ورتو: {{language}}",
   "command.session.new": "نواں سیشن",
+  "command.session.import": "سیشن درآمد کرو",
   "command.file.open": "فائل کھولو",
   "command.tab.close": "ٹیب بند کرو",
   "command.tab.reopenClosed": "بند ٹیب دوبارہ کھولو",

packages/app/src/runtime/i18n/pl.ts

@@ -140,6 +140,7 @@ export const dict = {
   "command.language.cycle": "Przełącz język",
   "command.language.set": "Użyj języka: {{language}}",
   "command.session.new": "Nowa sesja",
+  "command.session.import": "Importuj sesję",
   "command.file.open": "Otwórz plik",
   "command.tab.close": "Zamknij kartę",
   "command.tab.reopenClosed": "Otwórz ponownie zamkniętą kartę",

packages/app/src/runtime/i18n/ro.ts

@@ -133,6 +133,7 @@ export const dict = {
   "command.language.cycle": "Schimbă limba",
   "command.language.set": "Folosește limba: {{language}}",
   "command.session.new": "Sesiune nouă",
+  "command.session.import": "Importă sesiunea",
   "command.file.open": "Deschide fișier",
   "command.tab.close": "Închide fila",
   "command.tab.reopenClosed": "Redeschide fila închisă",

packages/app/src/runtime/i18n/ru.ts

@@ -146,6 +146,7 @@ export const dict = {
   "command.language.set": "Использовать язык: {{language}}",
 
   "command.session.new": "Новая сессия",
+  "command.session.import": "Импортировать сессию",
   "command.file.open": "Открыть файл",
   "command.tab.close": "Закрыть вкладку",
   "command.tab.reopenClosed": "Повторно открыть закрытую вкладку",

packages/app/src/runtime/i18n/si.ts

@@ -133,6 +133,7 @@ export const dict: Record<string, string> = {
   "command.language.cycle": "චක්‍ර භාෂාව",
   "command.language.set": "භාෂාව භාවිතා කරන්න: {{language}}",
   "command.session.new": "නව සැසිය",
+  "command.session.import": "සැසිය ආනයනය කරන්න",
   "command.file.open": "ගොනුව විවෘත කරන්න",
   "command.tab.close": "ටැබ් එක වසන්න",
   "command.tab.reopenClosed": "වසා දැමූ ටැබය නැවත විවෘත කරන්න",

packages/app/src/runtime/i18n/sk.ts

@@ -133,6 +133,7 @@ export const dict = {
   "command.language.cycle": "Prepnúť jazyk",
   "command.language.set": "Použiť jazyk: {{language}}",
   "command.session.new": "Nová relácia",
+  "command.session.import": "Importovať reláciu",
   "command.file.open": "Otvoriť súbor",
   "command.tab.close": "Zavrieť kartu",
   "command.tab.reopenClosed": "Obnoviť zatvorenú kartu",

packages/app/src/runtime/i18n/sl.ts

@@ -133,6 +133,7 @@ export const dict = {
   "command.language.cycle": "Jezik cikla",
   "command.language.set": "Uporabi jezik: {{language}}",
   "command.session.new": "Nova seja",
+  "command.session.import": "Uvozi sejo",
   "command.file.open": "Odpri datoteko",
   "command.tab.close": "Zapri zavihek",
   "command.tab.reopenClosed": "Ponovno odpri zaprt zavihek",

packages/app/src/runtime/i18n/sq.ts

@@ -134,6 +134,7 @@ export const dict = {
   "command.language.cycle": "Gjuha e ciklit",
   "command.language.set": "Përdorni gjuhën: {{language}}",
   "command.session.new": "Sesion i ri",
+  "command.session.import": "Importo sesionin",
   "command.file.open": "Hap skedarin",
   "command.tab.close": "Mbyll skedën",
   "command.tab.reopenClosed": "Rihap skedën e mbyllur",

packages/app/src/runtime/i18n/sr.ts

@@ -134,6 +134,7 @@ export const dict = {
   "command.language.cycle": "језик циклуса",
   "command.language.set": "Користи језик: {{language}}",
   "command.session.new": "Нова сесија",
+  "command.session.import": "Увези сесију",
   "command.file.open": "Отворите датотеку",
   "command.tab.close": "Затвори картицу",
   "command.tab.reopenClosed": "Поново отворите затворену картицу",

packages/app/src/runtime/i18n/sv.ts

@@ -134,6 +134,7 @@ export const dict = {
   "command.language.cycle": "Växla språk",
   "command.language.set": "Använd språk: {{language}}",
   "command.session.new": "Ny session",
+  "command.session.import": "Importera session",
   "command.file.open": "Öppna filen",
   "command.tab.close": "Stäng fliken",
   "command.tab.reopenClosed": "Öppna stängd flik igen",

packages/app/src/runtime/i18n/tg.ts

@@ -134,6 +134,7 @@ export const dict = {
   "command.language.cycle": "Забони даврӣ",
   "command.language.set": "Истифодаи забон: {{language}}",
   "command.session.new": "Сеанси нав",
+  "command.session.import": "Воридоти сеанс",
   "command.file.open": "Файлро кушоед",
   "command.tab.close": "Варақаро пӯшед",
   "command.tab.reopenClosed": "Варақаи пӯшидаро аз нав кушоед",

packages/app/src/runtime/i18n/th.ts

@@ -145,6 +145,7 @@ export const dict = {
   "command.language.set": "ใช้ภาษา: {{language}}",
 
   "command.session.new": "เซสชันใหม่",
+  "command.session.import": "นำเข้าเซสชัน",
   "command.file.open": "เปิดไฟล์",
   "command.tab.close": "ปิดแท็บ",
   "command.tab.reopenClosed": "เปิดแท็บที่ปิดไปอีกครั้ง",

packages/app/src/runtime/i18n/tk.ts

@@ -134,6 +134,7 @@ export const dict = {
   "command.language.cycle": "Sikl dili",
   "command.language.set": "Dil ulanyň: {{language}}",
   "command.session.new": "Täze sessiýa",
+  "command.session.import": "Sessiýany import et",
   "command.file.open": "Faýl açyň",
   "command.tab.close": "Salgy ýapyň",
   "command.tab.reopenClosed": "Closedapyk goýmany açyň",

packages/app/src/runtime/i18n/tr.ts

@@ -151,6 +151,7 @@ export const dict = {
   "command.language.set": "Dil kullan: {{language}}",
 
   "command.session.new": "Yeni oturum",
+  "command.session.import": "Oturumu içe aktar",
   "command.file.open": "Dosya aç",
   "command.tab.close": "Sekmeyi kapat",
   "command.tab.reopenClosed": "Kapatılan sekmeyi yeniden aç",

packages/app/src/runtime/i18n/uk.ts

@@ -147,6 +147,7 @@ export const dict = {
   "command.language.set": "Використати мову: {{language}}",
 
   "command.session.new": "Нова сесія",
+  "command.session.import": "Імпортувати сесію",
   "command.file.open": "Відкрити файл",
   "command.tab.close": "Закрити вкладку",
   "command.tab.reopenClosed": "Повторно відкрити закриту вкладку",

packages/app/src/runtime/i18n/ur.ts

@@ -141,6 +141,7 @@ export const dict = {
   "command.language.cycle": "اگلی زبان منتخب کریں",
   "command.language.set": "زبان استعمال کریں: {{language}}",
   "command.session.new": "نیا سیشن",
+  "command.session.import": "سیشن درآمد کریں",
   "command.file.open": "فائل کھولیں۔",
   "command.tab.close": "ٹیب بند کریں۔",
   "command.tab.reopenClosed": "بند ٹیب کو دوبارہ کھولیں۔",

packages/app/src/runtime/i18n/uz.ts

@@ -135,6 +135,7 @@ export const dict = {
   "command.language.cycle": "Keyingi til",
   "command.language.set": "Tildan foydalaning: {{language}}",
   "command.session.new": "Yangi sessiya",
+  "command.session.import": "Sessiyani import qilish",
   "command.file.open": "Faylni ochish",
   "command.tab.close": "Tabni yoping",
   "command.tab.reopenClosed": "Yopiq tabni qayta oching",

packages/app/src/runtime/i18n/vi.ts

@@ -140,6 +140,7 @@ export const dict = {
   "command.language.cycle": "Chuyển ngôn ngữ",
   "command.language.set": "Sử dụng ngôn ngữ: {{language}}",
   "command.session.new": "Phiên mới",
+  "command.session.import": "Nhập phiên",
   "command.file.open": "Mở tệp",
   "command.tab.close": "Đóng tab",
   "command.tab.reopenClosed": "Mở lại tab đã đóng",

packages/app/src/runtime/i18n/zh.ts

@@ -154,6 +154,7 @@ export const dict = {
   "command.language.set": "使用语言：{{language}}",
 
   "command.session.new": "新建会话",
+  "command.session.import": "导入会话",
 
   "command.file.open": "打开文件",
 

packages/app/src/runtime/i18n/zht.ts

@@ -149,6 +149,7 @@ export const dict = {
   "command.language.set": "使用語言: {{language}}",
 
   "command.session.new": "新增工作階段",
+  "command.session.import": "匯入工作階段",
   "command.file.open": "開啟檔案",
   "command.tab.close": "關閉分頁",
   "command.tab.reopenClosed": "重新開啟已關閉的分頁",

packages/app/src/runtime/platform/platform.tsx

@@ -59,8 +59,8 @@ type PlatformBase = {
   /** Resolve the native source path for a desktop File. */
   getPathForFile?(file: File): string
 
-  /** Open a native save file picker dialog (desktop only) */
-  saveFilePickerDialog?(opts?: SaveFilePickerOptions): Promise<string | null>
+  /** Open a native save file dialog and write content to the selected path (desktop only) */
+  saveFile?(opts: SaveFilePickerOptions, content: string): Promise<boolean>
 
   /** Storage mechanism, defaults to localStorage */
   storage?: (name?: string) => SyncStorage | AsyncStorage