refactor(core): share session message row codec

.changeset/directory-page-heading.md

@@ -1,5 +0,0 @@
----
-"@opencode/core": patch
----
-
-Correct directory page headings when the read offset is zero.

packages/ai/AGENTS.md

@@ -98,11 +98,11 @@ When a provider supports multiple physical transports, selection remains executi
 
 Media does not fit the SSE-frames-to-event-state-machine LLM route. `MediaRoute.inline(...)` / `queued(...)` / `stream(...)` (`src/route/media.ts`) compose a `MediaProtocol` kind with `Endpoint` and `Auth` and own the transport plumbing: `http` option merging, URL/query rendering, auth headers, JSON vs multipart encoding, and handing the response back to the protocol. `MediaProtocol.inline` (`src/route/media-protocol.ts`) is `body.from(request)` plus `response.decode(response, context)`; each protocol declares `const route = MediaProtocol.identity({ id, name, provider })` once and decodes through `route.decodeJson` / `route.text` / `route.decodeStarted` so decode failures retain the raw body and HTTP context, raising `route.unsupported(operation, message)` for requests it cannot lower, and passes `route` as the first argument to `MediaProtocol.inline` / `queued` / `stream`. `Generation` (`src/generation.ts`) is the provider-neutral handle for a queued generation over a `GenerationRoute` (`status`, `result`, `cancel`). Image protocol files follow the same section order as LLM protocols and declare unsupported common fields once through the protocol's `unsupported` list.
 
-`MediaProtocol.queued` is the submit-then-poll kind every video route uses: `start` (body + decode into `{ token, snapshot }`), `status`, `result`, and optional `cancel` (with `activeOnly` when the provider's cancel endpoint deletes finished work, as Runway's does: the route refreshes status first and skips terminal generations), each addressed by a route-owned `token` whose `Schema.Codec` makes it serializable. `MediaRoute.inline` and `MediaRoute.queued` compose the two kinds with `Endpoint` and `Auth`; the queued route decodes the token once at the boundary (`start` output or `resume` input) and closes over it in a token-free `GenerationRoute` (`status`/`result`/`cancel` are plain Effects), so `Generation` never sees the token's shape and only carries the encoded JSON for persistence. Polls reuse the route's auth and deployment headers plus the request's `http` overlay after `start`, and resolve relative paths against the route base URL (provider-issued absolute URLs such as fal's `status_url` pass through). `result` is always its own GET even when the provider returns output inside the status document, so `Generation.await` behaves the same after `start` and after `resume`. `PollContext.auth` carries only what `Auth` added or changed so protocols can hand download credentials to output assets as transient `Media.Asset.headers` (Veo) — never part of `source` or JSON. Status strings map through a per-protocol `STATUS` table via `MediaProtocol.status`; terminal generations without output fail through `output.ended` / `output.contentPolicy` with the provider document on `reason.body`. `GenerationAwaitOptions` (`AwaitOptions` in `src/generation.ts`, `{ poll?: Poll }`) is the one options type for `await`, `events`, `Video.generate`, and `Video.stream`.
+`MediaProtocol.queued` is the submit-then-poll kind every video route uses: `start` (body + decode into `{ token, snapshot }`), `status`, `result`, and optional `cancel` (with `activeOnly` when the provider's cancel endpoint deletes finished work, as Runway's does: the route refreshes status first and skips terminal generations), each addressed by a route-owned `token` whose `Schema.Codec` makes it serializable. `MediaRoute.inline` and `MediaRoute.queued` compose the two kinds with `Endpoint` and `Auth`; the queued route decodes the token once at the boundary (`start` output or `resume` input) and closes over it in a token-free `GenerationRoute` (`status`/`result`/`cancel` are plain Effects), so `Generation` never sees the token's shape and only carries the encoded JSON for persistence. Polls reuse the route's auth and deployment headers plus the request's `http` overlay after `start`, and resolve relative paths against the route base URL (provider-issued absolute URLs such as fal's `status_url` pass through). `result` is always its own GET even when the provider returns output inside the status document, so `Generation.await` behaves the same after `start` and after `resume`. `PollContext.auth` carries only what `Auth` added or changed so protocols can hand download credentials to output assets as transient `Media.Asset.headers` (Veo) — never part of `source` or JSON. Status strings map through a per-protocol `STATUS` table via `MediaProtocol.status`; terminal generations without output fail through `output.ended` / `output.contentPolicy` with the provider document on `reason.body`; a `failed` generation maps the provider's error code through a per-protocol `FAILURE` table via `MediaProtocol.failure` so rejected inputs are not reported as retryable `ProviderInternal`. `GenerationAwaitOptions` (`AwaitOptions` in `src/generation.ts`, `{ poll?: Poll }`) is the one options type for `await`, `events`, `Video.generate`, and `Video.stream`.
 
 `MediaProtocol.stream` is the incremental kind every speech route uses, with the same discipline as LLM protocols. `MediaRoute.stream` submits the caller's request as `MediaProtocol.Addressed<Request>` (`{ ...request, mode }`, `mode: "generate" | "stream"`), so one provider stays one protocol: `body.from`, the endpoint path, and `frames` read `request.mode` to pick the body, path, and framing. `frames(bytes, context)` returns frames — `Framing.sse`, `Framing.lines`, `Framing.document` (a single-document response shaped like a streamed record), or the raw `bytes` for chunked audio. `initial()` is fresh per-response parser state; `step` folds each frame into it and emits modality events; `finish(state, context)` runs once after the last frame with the request, body, and observed `http` (header-only usage lives there) and emits exactly one terminal event or fails with `route.incomplete()`. Keep parser state to real accumulators and derive anything the request or body determines in `finish`. `generate` runs the same stream and folds it with the modality's `collect`. Request-derived URL parameters go on the body's `query` (array values repeat the parameter), applied before route and caller `http.query`. Decode frames with `route.decodeFrame` and raise stream-time failures with `route.frameError` (the frame stays on `reason.body`); protocols never thread HTTP context, because the route fills `reason.http` on stream errors that lack it. Speech protocols share `protocols/utils/speech-stream.ts` for deltas, timestamps, voice ids, PCM and container descriptions, and the terminal asset.
 
-Every modality route is the inline | stream | queued union (transcription uses all three: OpenAI and Gemini stream, Deepgram is inline, AssemblyAI is queued), every client is `MediaClient.make(Service, { modality, responseEvents })` (`src/media-client.ts`), which dispatches on the route's `kind`, and every model composes through `composeRoute`. fal queue protocols come from `protocols/utils/fal-queue.ts`, bodies are `json`, `multipart`, or `binary` (a raw upload), and a queued protocol that must upload media before submitting implements `start.prepare` (`MediaProtocol.Prepare`; AssemblyAI `/v2/upload`).
+Every modality route is the inline | stream | queued union (transcription uses all three: OpenAI and Gemini stream, Deepgram and ElevenLabs are inline, AssemblyAI is queued), every client is `MediaClient.make(Service, { modality, responseEvents })` (`src/media-client.ts`), which dispatches on the route's `kind`, and every model composes through `composeRoute`. fal queue protocols come from `protocols/utils/fal-queue.ts`, bodies are `json`, `multipart`, or `binary` (a raw upload), and a queued protocol that must upload media before submitting implements `start.prepare` (`MediaProtocol.Prepare`; AssemblyAI `/v2/upload`).
 
 ### URL Construction
 

packages/ai/README.md

@@ -752,7 +752,10 @@ const events = Video.stream({ model: Runway.configure({ apiKey }).video("gen4.5"
 
 Status polls, result fetches, cancels, and asset downloads all run through the same request executor with the route's
 auth. `Generation.await` and `Generation.events` fail with a
-`Timeout` reason when `poll.timeout` (default 10 minutes) elapses. Failed,
+`Timeout` reason when `poll.timeout` (default 10 minutes) elapses. Status polls and result fetches retry transient
+failures (rate limits, provider 5xx, network errors) with backoff that honors `retry-after`, always within
+`poll.timeout`; submits and cancels never retry. Interrupting a wait (or aborting its `signal`) does not cancel the
+provider job, which keeps running and billing: call `cancel()` to stop it. Failed,
 cancelled, and expired generations fail typed with the provider's terminal document on `reason.body`; moderation
 outcomes (Veo `raiMediaFilteredReasons`, xAI `respect_moderation`, Runway `SAFETY.*` codes) surface as `notices` when
 a video is still returned and as a `ContentPolicy` reason when nothing is.
@@ -773,7 +776,9 @@ Provider notes:
 The promise client exposes the same surface: `ai.video.start(...)` resolves to a handle with `await`, `events`,
 `result`, `refresh`, `cancel`, and `token`; `ai.video.generate`, `ai.video.resume(model, token)`, and
 `ai.video.stream` mirror the Effect API. The handle's `status` and `progress` are a snapshot from when it was
-created; `refresh()` resolves to a new handle.
+created; `refresh()` resolves to a new handle. Every promise method and stream accepts `{ signal }`: like `fetch`,
+aborting rejects the Promise or throws from the `for await` loop with `signal.reason` (an `AbortError` `DOMException`
+unless `abort(reason)` passed one), while `break` stops a stream without throwing.
 
 ```ts
 import { ai } from "@opencode/ai/promise"
@@ -871,11 +876,12 @@ for await (const event of ai.speech.stream({ model, text: "Hello from OpenCode."
 ## Transcription
 
 Transcription (speech-to-text) is the one modality whose providers use every route kind: OpenAI and Gemini stream,
-Deepgram answers inline, and AssemblyAI is queued. `Transcription.generate` and `Transcription.stream` work on all of
-them; `Transcription.start` / `resume` return a `Generation` on queued routes and fail with `UnsupportedOperation`
-elsewhere. Models come from `.transcription(...)` selectors on the `OpenAI`, `Google`, `Deepgram`, and `AssemblyAI`
-facades. Common fields (`language`, `prompt`, `timestamps: "none" | "segment" | "word"`, `diarize`, `speakers`) lower
-natively or fail with a typed `AIError` before any network call; a route may return more than asked.
+Deepgram and ElevenLabs answer inline, and AssemblyAI is queued. `Transcription.generate` and `Transcription.stream`
+work on all of them; `Transcription.start` / `resume` return a `Generation` on queued routes and fail with
+`UnsupportedOperation` elsewhere. Models come from `.transcription(...)` selectors on the `OpenAI`, `Google`,
+`Deepgram`, `ElevenLabs`, and `AssemblyAI` facades. Common fields (`language`, `prompt`,
+`timestamps: "none" | "segment" | "word"`, `diarize`, `speakers`) lower natively or fail with a typed `AIError` before
+any network call; a route may return more than asked.
 
 ```ts
 import { Console, Effect, Stream } from "effect"
@@ -887,7 +893,7 @@ const openai = OpenAI.configure({ apiKey: process.env.OPENAI_API_KEY })
 const program = Effect.gen(function* () {
   const audio = yield* Media.file("./call.mp3")
 
-  // Speaker-labelled segments; labels are provider-native strings ("A", "0", "spk:0").
+  // Speaker-labelled segments; labels are provider-native strings ("A", "0", "spk:0", "speaker_0").
   const response = yield* Transcription.generate({
     model: Deepgram.configure({ apiKey }).transcription("nova-3"),
     audio,
@@ -897,7 +903,7 @@ const program = Effect.gen(function* () {
   response.text // "Hello from OpenCode."
   response.segments // [{ text, startSeconds, endSeconds, speaker: "0" }]
   response.words // [{ text, startSeconds, endSeconds, speaker, confidence }]
-  response.language // the provider's own value, lowercased ("en", "english", "en_us")
+  response.language // the provider's own value, lowercased ("en", "eng", "english", "en_us")
 
   // Text deltas as the model transcribes, then one finish carrying the whole transcript.
   yield* Transcription.stream({ model: openai.transcription("gpt-4o-mini-transcribe"), audio }).pipe(
@@ -921,7 +927,12 @@ Provider notes:
 - **OpenAI** takes inline audio only; `diarize` needs `gpt-4o-transcribe-diarize`, timestamps need `whisper-1`, and `whisper-1` does not stream.
 - **Gemini** needs a transcribe model (`gemini-3.5-transcribe`); `prompt` and `speakers` fail typed.
 - **Deepgram** detects the language unless `language` is set; vocabulary goes in `providerOptions.keyterm`.
-- **AssemblyAI** uploads inline audio before submitting and is the only route that accepts `speakers`.
+- **ElevenLabs** (`scribe_v2`) uploads inline audio as the multipart `file` and sends a URL as `source_url`. Words
+  always carry timestamps, and segments are speaker turns, so `diarize`, `timestamps: "segment"`, or `speakers` turns
+  on diarization. `speakers` is an upper bound (`num_speakers`); `prompt` fails typed (vocabulary goes in
+  `providerOptions.keyterms`), as do webhook delivery and per-channel output (`use_multi_channel` without
+  `multichannel_output_style: "combined"`).
+- **AssemblyAI** uploads inline audio before submitting and treats `speakers` as the exact speaker count.
 
 The promise client mirrors the Effect API:
 

packages/ai/docs/media-design.md

@@ -1,7 +1,6 @@
 # Media generation in `@opencode/ai` — public API direction
 
-Status: phases 1–4 implemented (through Image queued routes and partial images; ElevenLabs Scribe transcription
-pending); phase 5 proposal.
+Status: phases 1–4 implemented (through Image queued routes and partial images); phase 5 proposal.
 
 ## Goal
 
@@ -271,8 +270,8 @@ Deferred: `Speech.session(...)` — input-streaming TTS where text arrives incre
 #### Transcription (STT)
 
 Shipped as the second half of phase 3 (`src/transcription.ts`, `src/transcription-client.ts`, protocols
-`openai-transcription`, `google-transcription`, `deepgram-transcription`, `assemblyai-transcription`; new `AssemblyAI`
-facade).
+`openai-transcription`, `google-transcription`, `deepgram-transcription`, `elevenlabs-transcription`,
+`assemblyai-transcription`; new `AssemblyAI` facade).
 
 ```ts
 const request = Transcription.request({
@@ -281,7 +280,7 @@ const request = Transcription.request({
   language: "en",                                  // provider-native passthrough
   timestamps: "segment",                           // none | segment | word
   diarize: true,
-  speakers: 2,                                     // exact speaker count (AssemblyAI only)
+  speakers: 2,                                     // speaker count (AssemblyAI exact, ElevenLabs maximum)
   providerOptions: { known_speaker_names: ["agent"] },
 })
 
@@ -309,17 +308,23 @@ upload); `packages/ai/AGENTS.md` (Media Routes) describes both.
 Settled rules:
 
 - **Timestamps.** A granularity the selected route or model cannot produce fails as `UnsupportedOperation`
-  (`media.timestamps`), following Speech; a route that returns more than asked (Deepgram and AssemblyAI always return
-  words) is not stripped. Segments always carry start and end times: Gemini times each transcription part from its
+  (`media.timestamps`), following Speech; a route that returns more than asked (Deepgram, ElevenLabs, and AssemblyAI
+  always return words) is not stripped. Segments always carry start and end times: Gemini times each transcription part from its
   word offsets, so segment timestamps and diarization also request word offsets there.
 - **Diarization.** `diarize` means segments (and words, where the provider labels them) carry `speaker`. Labels are
-  provider-native strings — OpenAI `A` or a known speaker name, Deepgram `0`, Gemini `spk:0`, AssemblyAI `A` — with no
-  cross-provider speaker model. `speakers` is the exact number of speakers to label, which AssemblyAI (`speakers_expected`, the only route that
-  accepts it) treats as a constraint rather than a hint.
+  provider-native strings — OpenAI `A` or a known speaker name, Deepgram `0`, Gemini `spk:0`, AssemblyAI `A`,
+  ElevenLabs `speaker_0` — with no cross-provider speaker model. `speakers` is the number of speakers to label:
+  AssemblyAI (`speakers_expected`) treats it as an exact constraint rather than a hint, and ElevenLabs
+  (`num_speakers`) as the maximum. Both turn on diarization for it; the other routes reject it.
+- **Segments from words.** ElevenLabs returns only a token list (`word`, `spacing`, `audio_event`), so its segments
+  are speaker turns: consecutive words and spacing with one `speaker_id`, text joined from the provider's own spacing
+  tokens. `words` drops spacing and audio events. Segments therefore need diarization, which `timestamps: "segment"`
+  turns on, as AssemblyAI's utterances need speaker labels.
 - **Language** is passed through (`language`, OpenAI `gpt-transcribe` `languages[]`, Gemini `languageCodes`,
-  AssemblyAI `language_code`). `response.language` is the provider's own value, lowercased but not normalized: an
-  ISO code on most routes (AssemblyAI's detection returns `en`), `english` from whisper-1. Deepgram and AssemblyAI
-  assume English unless asked to detect, so a missing `language` enables their detection.
+  AssemblyAI and ElevenLabs `language_code`). `response.language` is the provider's own value, lowercased but not
+  normalized: an ISO code on most routes (AssemblyAI's detection returns `en`, ElevenLabs ISO 639-3 `eng`), `english`
+  from whisper-1. Deepgram and AssemblyAI assume English unless asked to detect, so a missing `language` enables their
+  detection.
 - **Gemini** requires a transcribe model; other model ids fail with `UnsupportedOperation` before the call, because
   general models ignore `audioTranscriptionConfig` and answer conversationally. Streamed chunks carry whole speaker
   turns (one part per turn), which join with a space.
@@ -332,11 +337,12 @@ Settled rules:
 | OpenAI | stream (`stream: true` in `stream` mode; `whisper-1` ignores `stream`, so it emits only `finish`) | multipart `file` (inline only) | `whisper-1` (`verbose_json`); diarize model: `segment` | `gpt-4o-transcribe-diarize` (`diarized_json`) | `speakers`; `prompt` on the diarize model | `tokens` or `seconds` |
 | Gemini | stream (`generateContent` / `streamGenerateContent`) | `inlineData` or Gemini Files `fileData` | `audioTranscriptionConfig.wordTimestamp` | `audioTranscriptionConfig.diarization` | `prompt`, `speakers` | `tokens` |
 | Deepgram | inline | raw body, or JSON `{ url }` | words always; `segment` → `utterances` | `diarize_model=latest` + `utterances` | `prompt`, `speakers` | `seconds` (`metadata.duration`) |
+| ElevenLabs | inline | multipart `file`, or `source_url` | words always; `segment` → `diarize` (speaker turns) | `diarize` | `prompt`; `webhook`, per-channel `use_multi_channel` | `seconds` (`audio_duration_secs`) |
 | AssemblyAI | queued (upload → submit → poll) | `/v2/upload` then `audio_url`, or a URL | words always; `segment` → `speaker_labels` | `speaker_labels` | — | `seconds` (`audio_duration`) |
 
 Deferred: `Transcription.session(...)` — realtime STT over WebSocket (Deepgram live, AssemblyAI streaming, ElevenLabs
 realtime, OpenAI realtime transcription) — is the same future scoped `session` shape as input-streaming TTS and ships
-with the realtime work in phase 5. ElevenLabs Scribe is not implemented yet.
+with the realtime work in phase 5.
 
 ### `Generation` — shared async execution
 
@@ -361,6 +367,10 @@ Poll = { interval?: Duration; timeout?: Duration }
 
 `Generation` is not video-specific. Image routes on BFL, fal, Replicate, and Stability `upscale()` are queued; `Image.start` exists for them. A route declares itself `inline` or `queued`; `generate` on a queued route is `start` then `await`.
 
+Status polls and result reads retry transient failures (rate limits, provider 5xx, and transport errors, classified by the same `isRetryable` the Session runner uses) inside `MediaRoute.queued`. Only the HTTP exchange retries, never the decoded document: a terminal `failed` generation also surfaces as `ProviderInternal` and must not be re-read. Gaps grow exponentially from 1s with jitter, up to 30s each, honoring a provider `retry-after` up to that cap, for at most 8 retries. `await`, `events`, and `Video.stream` cut retries off at `poll.timeout` and fail with `Timeout`, so retries never extend the caller's deadline; a direct `result()` or `resume` read is bounded by the retry cap alone. `start` and `cancel` never retry: a repeated submit can start and bill a second job. The policy is internal; there is no option for it.
+
+Interrupting `await`, `events`, or `Video.stream` (or aborting the promise API's `signal`) stops waiting only. The provider job keeps running and billing; call `cancel()` explicitly to stop it.
+
 ### Usage
 
 ```ts
@@ -402,7 +412,7 @@ for await (const event of ai.llm.stream(request)) { … }
 await ai.dispose()
 ```
 
-Streams become `AsyncIterable` via `Stream.toAsyncIterable`. `AIError` is thrown as-is. `AbortSignal` maps to interruption. Nothing in `src/*` except this entrypoint knows about promises.
+Streams become `AsyncIterable` via `Stream.toAsyncIterable`. `AIError` is thrown as-is. Aborting an `AbortSignal` interrupts the work and, like `fetch`, rejects the Promise or throws from the stream with `signal.reason` instead of ending the stream as if complete. Nothing in `src/*` except this entrypoint knows about promises.
 
 ### Providers
 
@@ -414,7 +424,7 @@ implemented):
 | `OpenAI` | responses (default), chat | Images API (stream) | *Sora skipped (decision 8)* | ✓ | ✓ | |
 | `Google` | Gemini | Gemini-native | Veo | Gemini TTS | `gemini-3.5-transcribe` | |
 | `XAI` | ✓ | ✓ | ✓ | | | |
-| `ElevenLabs` | | | | ✓ | *Scribe (pending)* | *soundEffect, music (phase 5)* |
+| `ElevenLabs` | | | | ✓ | Scribe | *soundEffect, music (phase 5)* |
 | `Cartesia` | | | | ✓ | | |
 | `Deepgram` | | | | Aura | ✓ | |
 | `Fal` | | ✓ (queued) | ✓ | | | |
@@ -467,7 +477,7 @@ Foundation + Image ship together as the reference implementation, serially. Vide
 
 1. **Foundation** — per-modality selectors, `Media`, `Generation`, `Poll`, `Usage` union, `MediaProtocol` kinds, `@opencode/ai/promise` with `llm` + `image`. Port the five existing image protocols onto it. Unify `MediaPart` and add the `media` LLM event (fixes Gemini image output being dropped).
 2. **Video** — ✅ Veo, xAI, fal, Runway shipped (`MediaProtocol.queued`, `Video.start/generate/resume/stream`, promise `ai.video`). Deferred: `Video.complete` (webhooks), Luma, Kling, MiniMax, Replicate.
-3. **Speech + Transcription** — ✅ Speech: OpenAI, Gemini TTS, ElevenLabs, Cartesia, Deepgram shipped (`MediaProtocol.stream`, `Speech.generate/stream`, promise `ai.speech`). ✅ Transcription: OpenAI, Gemini, Deepgram, AssemblyAI shipped across all three route kinds (`Transcription.generate/stream/start/resume`, promise `ai.transcription`). Pending: ElevenLabs Scribe. Deferred: `Speech.session` and `Transcription.session` (WebSocket streaming).
+3. **Speech + Transcription** — ✅ Speech: OpenAI, Gemini TTS, ElevenLabs, Cartesia, Deepgram shipped (`MediaProtocol.stream`, `Speech.generate/stream`, promise `ai.speech`). ✅ Transcription: OpenAI, Gemini, Deepgram, ElevenLabs Scribe, AssemblyAI shipped across all three route kinds (`Transcription.generate/stream/start/resume`, promise `ai.transcription`). Deferred: `Speech.session` and `Transcription.session` (WebSocket streaming).
 4. **Image queued routes and partials** — ✅ BFL, fal, Replicate, and Stability creative upscale queued; Stability generate inline; OpenAI `partial_images` streaming (`image-partial` restored). Imagen dropped: shut down on the Gemini API and discontinued on Vertex (2026-06-30). Deferred: Stability's synchronous edit and fast/conservative upscale endpoints.
 5. **Later** — ElevenLabs music/SFX, Lyria, `Speech.session` / `Transcription.session`, realtime.
 

packages/ai/src/generation.ts

@@ -102,7 +102,7 @@ export class Generation<Response> {
     return settled.pipe(
       // Non-completed terminal states also go through `result` so the route can surface its provider failure body.
       Effect.flatMap((generation) => generation.result()),
-      Effect.timeoutOrElse({ duration: timeout, orElse: () => this.timeoutError(timeout) }),
+      Effect.timeoutOrElse({ duration: timeout, orElse: () => timeoutError(this.id, timeout) }),
     )
   }
 
@@ -123,20 +123,7 @@ export class Generation<Response> {
       Clock.currentTimeMillis.pipe(
         Effect.map((start) => {
           const deadline = start + Duration.toMillis(timeout)
-          // Fail before polling once the deadline has passed: a fast status request could otherwise win the zero-budget
-          // race and schedule another zero-delay poll.
-          const refresh = Clock.currentTimeMillis.pipe(
-            Effect.flatMap((now) =>
-              now >= deadline
-                ? this.timeoutError(timeout)
-                : this.refresh().pipe(
-                    Effect.timeoutOrElse({
-                      duration: Duration.millis(deadline - now),
-                      orElse: () => this.timeoutError(timeout),
-                    }),
-                  ),
-            ),
-          )
+          const refresh = within(this.refresh(), this.id, timeout, deadline)
           const schedule = this.schedule(options?.poll).pipe(
             Schedule.modifyDelay((meta) =>
               Effect.succeed(Duration.min(meta.duration, Duration.millis(Math.max(0, deadline - meta.now)))),
@@ -157,15 +144,6 @@ export class Generation<Response> {
     return { type: "generation-progress", id: this.id, progress: this.progress }
   }
 
-  private timeoutError(timeout: Duration.Duration) {
-    return new AIError({
-      reason: new TimeoutError({
-        message: `Generation ${this.id} did not finish within ${Duration.format(timeout)}`,
-        timeoutMs: Duration.toMillis(timeout),
-      }),
-    })
-  }
-
   private poll(poll: Poll | undefined) {
     return this.refresh().pipe(
       Effect.repeat({ schedule: this.schedule(poll), until: (generation) => generation.terminal }),
@@ -177,12 +155,53 @@ export class Generation<Response> {
   }
 }
 
+/** `events` followed by the expanded result, with the result fetch bounded by the same `poll.timeout` deadline. */
 export const resultEvents = <Response, A>(
   generation: Generation<Response>,
   expand: (response: Response) => ReadonlyArray<A>,
   options?: AwaitOptions,
-): Stream.Stream<Observation | A, AIError> =>
-  generation.events(options).pipe(
-    Stream.filter((event): event is Observation => event.type !== "generation-finished"),
-    Stream.concat(Stream.fromIterableEffect(Effect.map(generation.result(), expand))),
+): Stream.Stream<Observation | A, AIError> => {
+  const timeout = Duration.fromInputUnsafe(options?.poll?.timeout ?? DEFAULT_POLL_TIMEOUT)
+  return Stream.unwrap(
+    Clock.currentTimeMillis.pipe(
+      Effect.map((start) =>
+        generation.events(options).pipe(
+          Stream.filter((event): event is Observation => event.type !== "generation-finished"),
+          Stream.concat(
+            Stream.fromIterableEffect(
+              within(generation.result(), generation.id, timeout, start + Duration.toMillis(timeout)).pipe(
+                Effect.map(expand),
+              ),
+            ),
+          ),
+        ),
+      ),
+    ),
   )
+}
+
+/**
+ * Run `effect` within the time left until `deadline`. Fails before starting once the deadline has passed: a fast
+ * request could otherwise win the zero-budget race and schedule another zero-delay poll.
+ */
+const within = <A>(effect: Effect.Effect<A, AIError>, id: string, timeout: Duration.Duration, deadline: number) =>
+  Clock.currentTimeMillis.pipe(
+    Effect.flatMap((now) =>
+      now >= deadline
+        ? Effect.fail(timeoutError(id, timeout))
+        : effect.pipe(
+            Effect.timeoutOrElse({
+              duration: Duration.millis(deadline - now),
+              orElse: () => Effect.fail(timeoutError(id, timeout)),
+            }),
+          ),
+    ),
+  )
+
+const timeoutError = (id: string, timeout: Duration.Duration) =>
+  new AIError({
+    reason: new TimeoutError({
+      message: `Generation ${id} did not finish within ${Duration.format(timeout)}`,
+      timeoutMs: Duration.toMillis(timeout),
+    }),
+  })

packages/ai/src/index.ts

@@ -4,7 +4,7 @@ export { ImageClient } from "./image-client.js"
 export { Auth } from "./route/auth.js"
 export { Provider } from "./provider.js"
 export { ProviderPackage } from "./provider-package.js"
-export { isContextOverflow, isContextOverflowFailure } from "./provider-error.js"
+export { isContextOverflow, isContextOverflowFailure, isRetryable } from "./provider-error.js"
 export type {
   RouteLanguageModelInput,
   RouteRoutedLanguageModelInput,

packages/ai/src/promise.ts

@@ -42,7 +42,7 @@ export type GenerationHandle<Response> = Snapshot & {
   /** Serializable JSON; pass it back to `resume` from another process. */
   readonly token: unknown
   readonly await: (options?: AwaitOptions & RunOptions) => Promise<Response>
-  /** Status observations until the first terminal one, polling like `await`; abort ends iteration without throwing. */
+  /** Status observations until the first terminal one, polling like `await`; abort throws `signal.reason`. */
   readonly events: (options?: AwaitOptions & RunOptions) => AsyncIterable<Event>
   /** The result without polling; fails when the generation has not completed. */
   readonly result: (options?: RunOptions) => Promise<Response>
@@ -50,15 +50,16 @@ export type GenerationHandle<Response> = Snapshot & {
   readonly cancel: (options?: RunOptions) => Promise<void>
 }
 
+// Fails with `signal.reason` so aborted calls reject and aborted streams throw like `fetch`: an `AbortError` by default.
 const abortEffect = (signal: AbortSignal | undefined) =>
   signal === undefined
     ? Effect.never
-    : Effect.callback<void>((resume) => {
+    : Effect.callback<never, unknown>((resume) => {
         if (signal.aborted) {
-          resume(Effect.void)
+          resume(Effect.fail(signal.reason))
           return
         }
-        const onAbort = () => resume(Effect.void)
+        const onAbort = () => resume(Effect.fail(signal.reason))
         signal.addEventListener("abort", onAbort, { once: true })
         return Effect.sync(() => signal.removeEventListener("abort", onAbort))
       })
@@ -68,14 +69,14 @@ export const make = (options: Options = {}) => {
 
   /** Run any package Effect (for example `LLMClient.compact(...)`) inside this runtime. */
   const run = <A, E>(effect: Effect.Effect<A, E, Services>, options?: RunOptions) =>
-    runtime.runPromise(effect, { signal: options?.signal })
+    runtime.runPromise(Effect.raceFirst(effect, abortEffect(options?.signal)))
 
   const iterate = <A, E>(stream: Stream.Stream<A, E, Services>, options?: RunOptions): AsyncIterable<A> =>
     Stream.toAsyncIterable(
       Stream.unwrap(
         runtime.contextEffect.pipe(
           Effect.map(
-            (context): Stream.Stream<A, E> =>
+            (context): Stream.Stream<A, unknown> =>
               stream.pipe(Stream.interruptWhen(abortEffect(options?.signal)), Stream.provideContext(context)),
           ),
         ),

packages/ai/src/protocols/deepgram-transcription.ts

@@ -6,6 +6,7 @@ import { mergeJsonRecords, type OpenString } from "../schema/index.js"
 import { TranscriptionModel, TranscriptionResponse, type TranscriptionRequestFor } from "../transcription.js"
 import { ProviderShared } from "./shared.js"
 import { MediaInput } from "./utils/media-input.js"
+import { SpeakerTurns } from "./utils/speaker-turns.js"
 
 const route = MediaProtocol.identity({ id: "deepgram-transcription", name: "Deepgram", provider: "deepgram" })
 export const DEFAULT_BASE_URL = "https://api.deepgram.com"
@@ -115,16 +116,6 @@ const speaker = (value: number | undefined) => (value === undefined ? undefined
 
 const wordText = (word: typeof Word.Type) => word.punctuated_word ?? word.word
 
-// Utterances split on pauses, not speakers: the v2 diarizer labels a whole utterance with one speaker even when its
-// words change speaker, so segments split each utterance at speaker changes.
-const speakerTurns = (words: ReadonlyArray<typeof Word.Type>) =>
-  words.reduce<Array<Array<typeof Word.Type>>>((turns, word) => {
-    const last = turns.at(-1)
-    if (last === undefined || last[0].speaker !== word.speaker) return [...turns, [word]]
-    last.push(word)
-    return turns
-  }, [])
-
 const decodeResponse = Effect.fn("DeepgramTranscription.decodeResponse")(function* (
   response: HttpClientResponse.HttpClientResponse,
 ) {
@@ -136,6 +127,8 @@ const decodeResponse = Effect.fn("DeepgramTranscription.decodeResponse")(functio
   const requestID = output.value.metadata?.request_id
   return new TranscriptionResponse({
     text: alternative.transcript,
+    // Utterances split on pauses, not speakers: the v2 diarizer labels a whole utterance with one speaker even when
+    // its words change speaker, so segments split each utterance at speaker changes.
     segments: output.value.results.utterances?.flatMap((utterance) =>
       utterance.words === undefined || utterance.words.length === 0
         ? [
@@ -146,7 +139,7 @@ const decodeResponse = Effect.fn("DeepgramTranscription.decodeResponse")(functio
               speaker: speaker(utterance.speaker),
             },
           ]
-        : speakerTurns(utterance.words).map((turn) => ({
+        : SpeakerTurns.group(utterance.words, (word) => word.speaker).map((turn) => ({
             text: turn.map(wordText).join(" "),
             startSeconds: turn[0].start,
             endSeconds: turn[turn.length - 1].end,

packages/ai/src/protocols/elevenlabs-transcription.ts

@@ -0,0 +1,211 @@
+import { Effect, Schema } from "effect"
+import type { HttpClientResponse } from "effect/unstable/http"
+import { MediaProtocol } from "../route/media-protocol.js"
+import { MediaRoute } from "../route/media.js"
+import { mergeJsonRecords, type OpenString } from "../schema/index.js"
+import { TranscriptionModel, TranscriptionResponse, type TranscriptionRequestFor } from "../transcription.js"
+import { mediaTypeExtension } from "../utils/media-type.js"
+import { ProviderShared, optionalNull } from "./shared.js"
+import { MediaInput } from "./utils/media-input.js"
+import { SpeakerTurns } from "./utils/speaker-turns.js"
+
+const route = MediaProtocol.identity({
+  id: "elevenlabs-transcription",
+  name: "ElevenLabs Transcription",
+  provider: "elevenlabs",
+})
+export const DEFAULT_BASE_URL = "https://api.elevenlabs.io"
+export const PATH = "/v1/speech-to-text"
+
+// ---------------------------------------------------------------------------
+// 1. Public model input
+// ---------------------------------------------------------------------------
+
+export type ElevenLabsTranscriptionOptions = {
+  readonly tag_audio_events?: boolean
+  readonly timestamps_granularity?: OpenString<"none" | "word" | "character">
+  readonly diarization_threshold?: number
+  readonly file_format?: OpenString<"pcm_s16le_16" | "other">
+  readonly temperature?: number
+  readonly seed?: number
+  readonly keyterms?: ReadonlyArray<string>
+  readonly no_verbatim?: boolean
+  readonly detect_speaker_roles?: boolean
+  readonly use_speaker_library?: boolean
+  readonly entity_detection?: string | ReadonlyArray<string>
+  readonly entity_redaction?: string | ReadonlyArray<string>
+  readonly entity_redaction_mode?: OpenString<"redacted" | "entity_type" | "enumerated_entity_type">
+} & Record<string, unknown>
+
+export type Request = TranscriptionRequestFor<ElevenLabsTranscriptionOptions>
+
+// ---------------------------------------------------------------------------
+// 2. Response schema
+// ---------------------------------------------------------------------------
+
+/** `type` is `word`, `spacing` (the whitespace between words), or `audio_event` (`(laughter)`). */
+const Token = Schema.Struct({
+  text: Schema.String,
+  type: Schema.String,
+  start: optionalNull(Schema.Number),
+  end: optionalNull(Schema.Number),
+  speaker_id: optionalNull(Schema.String),
+  logprob: optionalNull(Schema.Number),
+})
+type Token = Schema.Schema.Type<typeof Token>
+
+const Transcript = Schema.Struct({
+  language_code: optionalNull(Schema.String),
+  text: Schema.String,
+  words: optionalNull(Schema.Array(Token)),
+  transcription_id: optionalNull(Schema.String),
+  audio_duration_secs: optionalNull(Schema.Number),
+})
+
+// ---------------------------------------------------------------------------
+// 5. Request body construction
+// ---------------------------------------------------------------------------
+
+/** Speaker turns are the only segments ElevenLabs can produce, and `num_speakers` only applies to diarization. */
+const diarizes = (request: Request) =>
+  request.diarize === true || request.timestamps === "segment" || request.speakers !== undefined
+
+const RESERVED_FORM_FIELDS = new Set([
+  "file",
+  "cloud_storage_url",
+  "source_url",
+  "model_id",
+  "language_code",
+  "diarize",
+  "num_speakers",
+])
+
+const validate = (request: Request, overlay: Record<string, unknown>) => {
+  // Webhook requests return 202 with no transcript; the result arrives at a configured webhook instead.
+  if (overlay.webhook === true)
+    return Effect.fail(route.unsupported("transcription.webhook", `${route.name} does not deliver to webhooks`))
+  // Separate multichannel output replaces the transcript with one transcript per channel.
+  if (overlay.use_multi_channel === true && overlay.multichannel_output_style !== "combined")
+    return Effect.fail(
+      route.unsupported(
+        "transcription.multichannel",
+        `${route.name} returns a single transcript; set multichannel_output_style: "combined" to merge channels`,
+      ),
+    )
+  if (overlay.timestamps_granularity === "none" && (request.timestamps === "word" || diarizes(request)))
+    return Effect.fail(
+      route.unsupported(
+        "media.timestamps",
+        `${route.name} cannot return word timestamps or speaker turns with timestamps_granularity: "none"`,
+      ),
+    )
+  return Effect.void
+}
+
+const fromRequest = Effect.fn("ElevenLabsTranscription.fromRequest")(function* (request: Request) {
+  const overlay = mergeJsonRecords(request.providerOptions, request.http?.body) ?? {}
+  yield* validate(request, overlay)
+  const form = new FormData()
+  const url = ProviderShared.mediaUrl(request.audio)
+  if (url === undefined) {
+    const extension = mediaTypeExtension(request.audio.mediaType)
+    const audio = yield* MediaInput.inlineBytes(route.id, request.audio)
+    form.append(
+      "file",
+      MediaInput.blob(audio, request.audio.mediaType),
+      extension === undefined ? "audio" : `audio.${extension}`,
+    )
+  }
+  MediaInput.appendFields(
+    form,
+    {
+      model_id: request.model.id,
+      // `cloud_storage_url` is deprecated in favor of `source_url`, which accepts any hosted audio or video URL.
+      source_url: url,
+      language_code: request.language,
+      diarize: diarizes(request) ? true : undefined,
+      num_speakers: request.speakers,
+    },
+    { overlay, reserved: RESERVED_FORM_FIELDS, repeatArrays: "key" },
+  )
+  return MediaProtocol.multipart(form)
+})
+
+// ---------------------------------------------------------------------------
+// 6. Response decoding
+// ---------------------------------------------------------------------------
+
+const decodeTranscript = route.decodeJson(Transcript)
+
+type TimedWord = Token & { readonly start: number; readonly end: number }
+
+const isTimedWord = (token: Token): token is TimedWord =>
+  token.type === "word" && typeof token.start === "number" && typeof token.end === "number"
+
+/** Turn text keeps the provider's own spacing tokens, so languages written without spaces are not re-spaced. */
+const speakerTurns = (tokens: ReadonlyArray<Token>) =>
+  SpeakerTurns.group(
+    tokens.filter((token) => token.type === "word" || token.type === "spacing"),
+    (token) => token.speaker_id,
+  ).flatMap((turn) => {
+    const words = turn.filter(isTimedWord)
+    if (words.length === 0) return []
+    return [
+      {
+        text: turn
+          .map((token) => token.text)
+          .join("")
+          .trim(),
+        startSeconds: words[0].start,
+        endSeconds: words[words.length - 1].end,
+        speaker: turn[0].speaker_id ?? undefined,
+      },
+    ]
+  })
+
+const decodeResponse = Effect.fn("ElevenLabsTranscription.decodeResponse")(function* (
+  response: HttpClientResponse.HttpClientResponse,
+  context: MediaProtocol.DecodeContext<Request>,
+) {
+  const output = yield* decodeTranscript(response)
+  const transcript = output.value
+  const tokens = transcript.words ?? []
+  const duration = transcript.audio_duration_secs ?? undefined
+  const transcriptionID = transcript.transcription_id ?? undefined
+  return new TranscriptionResponse({
+    text: transcript.text,
+    segments: diarizes(context.request) ? speakerTurns(tokens) : undefined,
+    words: tokens.filter(isTimedWord).map((word) => ({
+      text: word.text,
+      startSeconds: word.start,
+      endSeconds: word.end,
+      speaker: word.speaker_id ?? undefined,
+      confidence: typeof word.logprob === "number" ? Math.exp(word.logprob) : undefined,
+    })),
+    language: transcript.language_code?.toLowerCase(),
+    durationSeconds: duration,
+    usage: duration === undefined ? undefined : { type: "seconds", seconds: duration },
+    providerMetadata: transcriptionID === undefined ? undefined : { elevenlabs: { transcriptionId: transcriptionID } },
+  })
+})
+
+// ---------------------------------------------------------------------------
+// 7. Protocol and route
+// ---------------------------------------------------------------------------
+
+export const protocol = MediaProtocol.inline<Request, TranscriptionResponse>(route, {
+  unsupported: ["prompt"],
+  body: { from: fromRequest },
+  response: { decode: decodeResponse },
+})
+
+export const model = (input: MediaRoute.ModelInput) =>
+  TranscriptionModel.fromRoute<ElevenLabsTranscriptionOptions>(
+    { protocol, baseURL: DEFAULT_BASE_URL, path: PATH },
+    input,
+  )
+
+export const ElevenLabsTranscription = {
+  protocol,
+  model,
+} as const

packages/ai/src/protocols/google-video.ts

@@ -36,7 +36,9 @@ const StartResponse = Schema.Struct({ name: Schema.String })
 
 const Operation = Schema.Struct({
   done: Schema.optional(Schema.Boolean),
-  error: Schema.optional(Schema.Struct({ message: Schema.optional(Schema.String) })),
+  error: Schema.optional(
+    Schema.Struct({ code: Schema.optional(Schema.Number), message: Schema.optional(Schema.String) }),
+  ),
   response: Schema.optional(
     Schema.Struct({
       generateVideoResponse: Schema.optional(
@@ -60,6 +62,16 @@ const Operation = Schema.Struct({
   metadata: Schema.optional(Schema.Unknown),
 })
 
+// Operation errors are `google.rpc.Status`; unlisted codes (INTERNAL, UNAVAILABLE, ...) are provider-side.
+const FAILURE = {
+  3: "InvalidRequest", // INVALID_ARGUMENT
+  7: "Authentication", // PERMISSION_DENIED
+  8: "RateLimit", // RESOURCE_EXHAUSTED
+  9: "InvalidRequest", // FAILED_PRECONDITION
+  11: "InvalidRequest", // OUT_OF_RANGE
+  16: "Authentication", // UNAUTHENTICATED
+} as const satisfies Record<number, MediaProtocol.Failure>
+
 // ---------------------------------------------------------------------------
 // 5. Request body construction
 // ---------------------------------------------------------------------------
@@ -154,6 +166,7 @@ const decodeResult = Effect.fn("GoogleVideo.decodeResult")(function* (
     return yield* output.ended(
       "failed",
       `${route.name} operation failed${operation.error?.message === undefined ? "" : `: ${operation.error.message}`}`,
+      MediaProtocol.failure(FAILURE, operation.error?.code),
     )
   const generated = operation.response?.generateVideoResponse
   // Downloads require the same API key as the poll; the asset carries it transiently and follows the redirect.

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

@@ -193,7 +193,7 @@ const fromRequest = Effect.fn("OpenAITranscription.fromRequest")(function* (requ
     {
       overlay: mergeJsonRecords(request.providerOptions, request.http?.body),
       reserved: RESERVED_FORM_FIELDS,
-      repeatArrays: true,
+      repeatArrays: "key[]",
     },
   )
   return MediaProtocol.multipart(form)

packages/ai/src/protocols/runway-video.ts

@@ -137,7 +137,12 @@ const decodeResult = Effect.fn("RunwayVideo.decodeResult")(function* (
     const message = `${route.name} task failed${code === undefined ? "" : ` (${code})`}${task.failure ? `: ${task.failure}` : ""}`
     // Runway failure codes are dotted paths; every moderation outcome carries a SAFETY segment.
     if (code !== undefined && /(^|\.)SAFETY(\.|$)/.test(code)) return yield* output.contentPolicy(message)
-    return yield* output.ended("failed", message)
+    // ASSET.INVALID rejects the caller's input media; Runway documents it as not retryable.
+    return yield* output.ended(
+      "failed",
+      message,
+      code !== undefined && /^ASSET\.INVALID(\.|$)/.test(code) ? "InvalidRequest" : "ProviderInternal",
+    )
   }
   if (status === "cancelled")
     return yield* output.ended("cancelled", `${route.name} task ${context.token.taskID} was cancelled`)

packages/ai/src/protocols/utils/media-input.ts

@@ -71,8 +71,9 @@ export const imageOutput = (
 }
 
 /**
- * Append multipart text fields: strings as-is, other values as JSON, or arrays as repeated `key[]` parts with
- * `repeatArrays`. `overlay` keys in `reserved` are dropped so `http.body` cannot replace route-owned fields.
+ * Append multipart text fields: strings as-is, other values as JSON, or scalar arrays as one part per item with
+ * `repeatArrays`, named `key[]` or `key`. `overlay` keys in `reserved` are dropped so `http.body` cannot replace
+ * route-owned fields.
  */
 export const appendFields = (
   form: FormData,
@@ -80,13 +81,13 @@ export const appendFields = (
   options: {
     readonly overlay?: Record<string, unknown>
     readonly reserved: ReadonlySet<string>
-    readonly repeatArrays?: true
+    readonly repeatArrays?: "key[]" | "key"
   },
 ) => {
   const overlay = Object.entries(options.overlay ?? {}).filter(([key]) => !options.reserved.has(key))
   Object.entries(mergeJsonRecords(fields, Object.fromEntries(overlay)) ?? {}).forEach(([key, value]) => {
-    if (Array.isArray(value) && options.repeatArrays)
-      return value.forEach((item) => form.append(`${key}[]`, String(item)))
+    if (Array.isArray(value) && value.every(isScalar) && options.repeatArrays !== undefined)
+      return value.forEach((item) => form.append(options.repeatArrays === "key[]" ? `${key}[]` : key, String(item)))
     form.append(key, typeof value === "string" ? value : encodeJson(value))
   })
 }

packages/ai/src/protocols/utils/speaker-turns.ts

@@ -0,0 +1,10 @@
+/** Split an ordered token list into runs of consecutive tokens with the same speaker. */
+export const group = <Item>(items: ReadonlyArray<Item>, speaker: (item: Item) => unknown) =>
+  items.reduce<Array<Array<Item>>>((turns, item) => {
+    const last = turns.at(-1)
+    if (last === undefined || speaker(last[0]) !== speaker(item)) return [...turns, [item]]
+    last.push(item)
+    return turns
+  }, [])
+
+export * as SpeakerTurns from "./speaker-turns.js"

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

@@ -65,6 +65,13 @@ const STATUS = {
   expired: "expired",
 } as const satisfies Record<string, Status>
 
+// Documented video error codes; `service_unavailable`, `internal_error`, and unknown codes are provider-side.
+const FAILURE = {
+  invalid_argument: "InvalidRequest",
+  failed_precondition: "InvalidRequest",
+  permission_denied: "Authentication",
+} as const satisfies Record<string, MediaProtocol.Failure>
+
 // ---------------------------------------------------------------------------
 // 5. Request body construction
 // ---------------------------------------------------------------------------
@@ -143,6 +150,7 @@ const decodeResult = Effect.fn("XAIVideo.decodeResult")(function* (
     return yield* output.ended(
       "failed",
       `${route.name} generation failed${code === undefined ? "" : ` (${code})`}${message === undefined ? "" : `: ${message}`}`,
+      MediaProtocol.failure(FAILURE, code),
     )
   }
   if (status !== "completed")

packages/ai/src/provider-error.ts

@@ -58,6 +58,47 @@ export const isContextOverflowFailure = (failure: unknown) =>
     ? failure.reason._tag === "InvalidRequest" && failure.reason.classification === "context-overflow"
     : Schema.is(ProviderErrorEvent)(failure) && failure.classification === "context-overflow"
 
+/**
+ * Whether a failed call may succeed when sent again: rate limits, provider-side failures, transport failures that did
+ * not deliver an accepted write, and unrecognized failures. Callers decide which calls are safe to repeat.
+ */
+export const isRetryable = (error: AIError) => {
+  const override = error.reason.http?.headers["x-should-retry"]
+  if (override === "true") return true
+  if (override === "false") return false
+  switch (error.reason._tag) {
+    case "RateLimit":
+    case "ProviderInternal":
+      return true
+    // A WebSocket acknowledgment marks delivery accepted before model output may exist.
+    // Read failures can still recover; the caller chooses retry versus continuation from durable output.
+    case "Transport":
+      return (
+        error.reason.delivery !== "rejected" &&
+        (error.reason.delivery !== "accepted" || error.reason.operation === "read")
+      )
+    case "InvalidProviderOutput":
+      return error.reason.classification === "incomplete-stream"
+    // Unrecognized failures retry: classification records affirmative
+    // deterministic evidence, and transient failures are exactly the ones
+    // that arrive in shapes no classifier anticipates.
+    case "UnknownProvider":
+      return true
+    case "Authentication":
+    case "QuotaExceeded":
+    case "ContentPolicy":
+    case "InvalidRequest":
+    case "UnsupportedOperation":
+    case "NoRoute":
+    case "Timeout":
+      return false
+    default: {
+      const exhaustive: never = error.reason
+      return exhaustive
+    }
+  }
+}
+
 const decodeJson = Schema.decodeUnknownOption(Schema.fromJsonString(Schema.Unknown))
 // OpenCode Zen reports account caps as typed 429/402 errors that are not throttles.
 const QUOTA_CODES = new Set([

packages/ai/src/providers/elevenlabs.ts

@@ -3,8 +3,10 @@ import type { ProviderAuthOption } from "../route/auth-options.js"
 import { MediaRoute } from "../route/media.js"
 import { type HttpOptions, ProviderID, type ModelID } from "../schema/index.js"
 import { ElevenLabsSpeech } from "../protocols/elevenlabs-speech.js"
+import { ElevenLabsTranscription } from "../protocols/elevenlabs-transcription.js"
 
 export type { ElevenLabsOutputFormat, ElevenLabsSpeechOptions } from "../protocols/elevenlabs-speech.js"
+export type { ElevenLabsTranscriptionOptions } from "../protocols/elevenlabs-transcription.js"
 
 export const id = ProviderID.make("elevenlabs")
 
@@ -24,12 +26,15 @@ const auth = (options: ProviderAuthOption<"optional">) => {
 export const configure = (input: Config = {}) => {
   const media = MediaRoute.deployment(input, auth(input))
   const speech = (modelID: string | ModelID) => ElevenLabsSpeech.model({ ...media, id: modelID })
+  const transcription = (modelID: string | ModelID) => ElevenLabsTranscription.model({ ...media, id: modelID })
   return {
     id,
     speech,
+    transcription,
     configure,
   }
 }
 
 export const provider = configure()
 export const speech = provider.speech
+export const transcription = provider.transcription

packages/ai/src/route/media-protocol.ts

@@ -5,12 +5,14 @@ import { Media } from "../media.js"
 import type { AuthInput } from "./auth.js"
 import {
   AIError,
+  AuthenticationError,
   ContentPolicyError,
   HttpContext,
   InvalidProviderOutputError,
   InvalidRequestError,
   ProviderID,
   ProviderInternalError,
+  RateLimitError,
   UnsupportedOperationError,
 } from "../schema/index.js"
 
@@ -188,6 +190,16 @@ export const stream = <Request, Event, Frame, State>(
 // Response helpers
 // ---------------------------------------------------------------------------
 
+/** Reasons a provider can report for a `failed` generation; anything it does not classify is `ProviderInternal`. */
+const FAILURES = {
+  InvalidRequest: InvalidRequestError,
+  Authentication: AuthenticationError,
+  RateLimit: RateLimitError,
+  ProviderInternal: ProviderInternalError,
+}
+
+export type Failure = keyof typeof FAILURES
+
 const context = (response: HttpClientResponse.HttpClientResponse) =>
   new HttpContext({ url: response.request.url, status: response.status, headers: response.headers })
 
@@ -199,9 +211,10 @@ export const identity = (input: { readonly id: string; readonly name: string; re
 
   /**
    * Read a text body while retaining the original payload and HTTP context on every downstream error. `invalid` is a
-   * malformed provider document; `ended` is a generation that reached a terminal status without output (`failed` is
-   * provider-side, `cancelled`/`expired` mean the result will never exist); `pending` is a `result()` read before the
-   * generation finished, which is caller misuse; `contentPolicy` is a moderated result.
+   * malformed provider document; `ended` is a generation that reached a terminal status without output (`failed`
+   * carries the provider's classification, defaulting to `ProviderInternal`; `cancelled`/`expired` mean the result
+   * will never exist); `pending` is a `result()` read before the generation finished, which is caller misuse;
+   * `contentPolicy` is a moderated result.
    */
   const text = Effect.fn("MediaProtocol.text")(function* (response: HttpClientResponse.HttpClientResponse) {
     const http = context(response)
@@ -223,11 +236,15 @@ export const identity = (input: { readonly id: string; readonly name: string; re
       http,
       invalid: (message: string, cause?: unknown) =>
         new AIError({ reason: new InvalidProviderOutputError({ route: input.id, message, body, http, cause }) }),
-      ended: (status: Exclude<Status, "queued" | "running" | "completed">, message: string) =>
+      ended: (
+        status: Exclude<Status, "queued" | "running" | "completed">,
+        message: string,
+        failure: Failure = "ProviderInternal",
+      ) =>
         new AIError({
           reason:
             status === "failed"
-              ? new ProviderInternalError({ message, body, http })
+              ? new FAILURES[failure]({ message, body, http })
               : new InvalidRequestError({ message, body, http }),
         }),
       pending: (id: string) =>
@@ -303,6 +320,10 @@ export const status = <Table extends Record<string, Status>>(
   return Effect.succeed(table[raw])
 }
 
+/** Map a provider error code through the protocol's table; missing or unmapped codes are `ProviderInternal`. */
+export const failure = (table: Readonly<Record<string, Failure>>, code: string | number | undefined): Failure =>
+  code !== undefined && Object.hasOwn(table, code) ? table[code] : "ProviderInternal"
+
 /** A `url` asset whose provider-declared retention window starts now. */
 export const expiringUrl = (url: string, retention: Duration.Duration, options?: Parameters<typeof Media.url>[1]) =>
   Clock.currentTimeMillis.pipe(

packages/ai/src/route/media.ts

@@ -1,4 +1,4 @@
-import { Effect, Schema, Stream } from "effect"
+import { Duration, Effect, Schedule, Schema, Stream } from "effect"
 import { Headers, HttpClientRequest, type HttpClientResponse } from "effect/unstable/http"
 import { Auth, type AuthInput } from "./auth.js"
 import { Endpoint } from "./endpoint.js"
@@ -7,6 +7,7 @@ import { RequestExecutor } from "./executor.js"
 import { MediaProtocol } from "./media-protocol.js"
 import { Generation, isTerminal } from "../generation.js"
 import type { Media } from "../media.js"
+import { isRetryable } from "../provider-error.js"
 import {
   AIError,
   AIErrorReason,
@@ -137,6 +138,32 @@ export const inline = <Request extends MediaRequest, Response>(
   }
 }
 
+const READ_RETRY_MAX_DELAY = Duration.seconds(30)
+
+/**
+ * Status and result reads retry transient failures; `start` and `cancel` never do. Gaps grow exponentially from 1s,
+ * jittered, up to 30s each, for at most 8 retries (about two minutes when every attempt fails), so a direct
+ * `Generation.result()` stays bounded; `await` and `events` also cut retries off at `poll.timeout`. A provider
+ * `retryAfterMs` raises the gap, still capped at 30s.
+ */
+const READ_RETRY = Schedule.max([
+  Schedule.min([Schedule.exponential("1 second"), Schedule.spaced(READ_RETRY_MAX_DELAY)]),
+  Schedule.recurs(8),
+]).pipe(
+  Schedule.jittered,
+  Schedule.setInputType<AIError>(),
+  Schedule.modifyDelay(({ input, duration }) =>
+    Effect.succeed(
+      Duration.min(
+        input.reason._tag === "RateLimit" || input.reason._tag === "ProviderInternal"
+          ? Duration.max(duration, Duration.millis(input.reason.retryAfterMs ?? 0))
+          : duration,
+        READ_RETRY_MAX_DELAY,
+      ),
+    ),
+  ),
+)
+
 /**
  * Compose a queued media protocol the same way, adding `start`/`resume` handles whose polls reuse the route's auth,
  * deployment headers, and (for `start`) the request's `http` overlay. The token is decoded once at the boundary and
@@ -154,6 +181,8 @@ export const queued = <Request extends MediaRequest, Response, Token>(
   const generationRoute = (token: Token, http: HttpOptions | undefined, execute: Execute) => {
     const materialize = (asset: Media.Asset) =>
       asset.materialize().pipe(Effect.provideService(RequestExecutorService, { execute }))
+    // Only the GET exchange retries: a decoded terminal failure (`output.ended`) can be a `ProviderInternal` too, and
+    // re-reading it would spin until the caller's deadline.
     const poll = <A>(operation: {
       readonly path: (token: Token) => string
       readonly decode: (
@@ -161,9 +190,10 @@ export const queued = <Request extends MediaRequest, Response, Token>(
         context: MediaProtocol.PollContext<Token>,
       ) => Effect.Effect<A, AIError>
     }) =>
-      transport
-        .call("GET", operation.path(token), http, execute)
-        .pipe(Effect.flatMap((sent) => operation.decode(sent.response, { token, auth: sent.auth, materialize })))
+      transport.call("GET", operation.path(token), http, execute).pipe(
+        Effect.retry({ schedule: READ_RETRY, while: isRetryable }),
+        Effect.flatMap((sent) => operation.decode(sent.response, { token, auth: sent.auth, materialize })),
+      )
     const status = poll(protocol.status)
     const cancel = protocol.cancel
     const send =

packages/ai/src/transcription.ts

@@ -103,7 +103,7 @@ export type TranscriptionRequestInput<Model extends TranscriptionModel = Transcr
 // Response and events
 // ---------------------------------------------------------------------------
 
-/** Speaker labels are provider-native (`A`, `0`, `spk:0`, or a known speaker name). */
+/** Speaker labels are provider-native (`A`, `0`, `spk:0`, `speaker_0`, or a known speaker name). */
 export const TranscriptionSegment = Schema.Struct({
   text: Schema.String,
   startSeconds: Schema.Number,

packages/ai/test/exports.test.ts

@@ -197,6 +197,11 @@ describe("public exports", () => {
     expect(Google.configure({ apiKey: "fixture" }).transcription("gemini-3.5-transcribe").route.kind).toBe("stream")
     expect(Deepgram.configure({ apiKey: "fixture" }).transcription("nova-3").route.kind).toBe("inline")
     expect(AssemblyAI.configure({ apiKey: "fixture" }).transcription("universal-3-5-pro").route.kind).toBe("queued")
+    expect(ElevenLabs.configure({ apiKey: "fixture" }).transcription("scribe_v2").route.id).toBe(
+      "elevenlabs-transcription",
+    )
+    expect(ElevenLabs.configure({ apiKey: "fixture" }).transcription("scribe_v2").route.kind).toBe("inline")
+    expect(ElevenLabs.provider.transcription).toBe(ElevenLabs.transcription)
   })
 
   test("protocol barrels expose supported low-level routes", () => {

packages/ai/test/fixtures/recordings/elevenlabs-transcription/groups-diarized-words-into-speaker-turns.json

@@ -0,0 +1,32 @@
+{
+  "version": 1,
+  "metadata": {
+    "tags": [
+      "prefix:elevenlabs-transcription",
+      "provider:elevenlabs",
+      "protocol:elevenlabs-transcription"
+    ],
+    "name": "elevenlabs-transcription/groups-diarized-words-into-speaker-turns",
+    "recordedAt": "2026-09-27T09:35:28.265Z"
+  },
+  "interactions": [
+    {
+      "transport": "http",
+      "request": {
+        "method": "POST",
+        "url": "https://api.elevenlabs.io/v1/speech-to-text",
+        "headers": {
+          "content-type": "multipart/form-data; boundary=----WebKitFormBoundary356bdc14864a477dbacbfcf60d1ecceb"
+        },
+        "body": "--BOUNDARY\r\nContent-Disposition: form-data; name=\"file\"; filename=\"audio.mp3\"\r\nContent-Type: audio/mpeg\r\n\r\n[audio]\r\n--BOUNDARY\r\nContent-Disposition: form-data; name=\"model_id\"\r\n\r\nscribe_v2\r\n--BOUNDARY\r\nContent-Disposition: form-data; name=\"diarize\"\r\n\r\ntrue\r\n--BOUNDARY--\r\n"
+      },
+      "response": {
+        "status": 200,
+        "headers": {
+          "content-type": "application/json"
+        },
+        "body": "{\"language_code\":\"eng\",\"language_probability\":0.9495430588722229,\"text\":\"Did the release ship? Yes, it shipped this morning\",\"words\":[{\"text\":\"Did\",\"start\":0.34,\"end\":0.44,\"type\":\"word\",\"speaker_id\":\"speaker_0\",\"logprob\":-1.7881377516459906e-6},{\"text\":\" \",\"start\":0.44,\"end\":0.48,\"type\":\"spacing\",\"speaker_id\":\"speaker_0\",\"logprob\":-1.1920928244535389e-7},{\"text\":\"the\",\"start\":0.48,\"end\":0.56,\"type\":\"word\",\"speaker_id\":\"speaker_0\",\"logprob\":-1.1920928244535389e-7},{\"text\":\" \",\"start\":0.56,\"end\":0.6,\"type\":\"spacing\",\"speaker_id\":\"speaker_0\",\"logprob\":-7.152531907195225e-6},{\"text\":\"release\",\"start\":0.6,\"end\":0.92,\"type\":\"word\",\"speaker_id\":\"speaker_0\",\"logprob\":-7.152531907195225e-6},{\"text\":\" \",\"start\":0.92,\"end\":0.94,\"type\":\"spacing\",\"speaker_id\":\"speaker_0\",\"logprob\":-8.344646857949556e-7},{\"text\":\"ship?\",\"start\":0.94,\"end\":1.26,\"type\":\"word\",\"speaker_id\":\"speaker_0\",\"logprob\":-7.414704032271402e-6},{\"text\":\" \",\"start\":1.26,\"end\":1.26,\"type\":\"spacing\",\"speaker_id\":\"speaker_0\",\"logprob\":-0.0009363081189803779},{\"text\":\"Yes,\",\"start\":1.68,\"end\":2.02,\"type\":\"word\",\"speaker_id\":\"speaker_1\",\"logprob\":-0.003542040009030245},{\"text\":\" \",\"start\":2.02,\"end\":2.48,\"type\":\"spacing\",\"speaker_id\":\"speaker_1\",\"logprob\":-3.933898824470816e-6},{\"text\":\"it\",\"start\":2.48,\"end\":2.62,\"type\":\"word\",\"speaker_id\":\"speaker_1\",\"logprob\":-3.933898824470816e-6},{\"text\":\" \",\"start\":2.62,\"end\":2.64,\"type\":\"spacing\",\"speaker_id\":\"speaker_1\",\"logprob\":-0.000013589766240329482},{\"text\":\"shipped\",\"start\":2.66,\"end\":2.9,\"type\":\"word\",\"speaker_id\":\"speaker_1\",\"logprob\":-0.000013589766240329482},{\"text\":\" \",\"start\":2.9,\"end\":2.94,\"type\":\"spacing\",\"speaker_id\":\"speaker_1\",\"logprob\":0.0},{\"text\":\"this\",\"start\":2.94,\"end\":3.12,\"type\":\"word\",\"speaker_id\":\"speaker_1\",\"logprob\":0.0},{\"text\":\" \",\"start\":3.12,\"end\":3.18,\"type\":\"spacing\",\"speaker_id\":\"speaker_1\",\"logprob\":-3.576278118089249e-7},{\"text\":\"morning\",\"start\":3.18,\"end\":3.5,\"type\":\"word\",\"speaker_id\":\"speaker_1\",\"logprob\":-3.576278118089249e-7}],\"transcription_id\":\"cs3I2282TH8hjw12brNg\",\"audio_duration_secs\":3.5526875}"
+      }
+    }
+  ]
+}

packages/ai/test/fixtures/recordings/elevenlabs-transcription/transcribes-audio-with-word-timestamps.json

@@ -0,0 +1,50 @@
+{
+  "version": 1,
+  "metadata": {
+    "tags": [
+      "prefix:elevenlabs-transcription",
+      "provider:elevenlabs",
+      "protocol:elevenlabs-transcription"
+    ],
+    "name": "elevenlabs-transcription/transcribes-audio-with-word-timestamps",
+    "recordedAt": "2026-09-27T09:35:27.686Z"
+  },
+  "interactions": [
+    {
+      "transport": "http",
+      "request": {
+        "method": "POST",
+        "url": "https://api.elevenlabs.io/v1/speech-to-text",
+        "headers": {
+          "content-type": "multipart/form-data; boundary=----WebKitFormBoundarye2be7b31e94441bbbeb35a9c890a9d74"
+        },
+        "body": "--BOUNDARY\r\nContent-Disposition: form-data; name=\"file\"; filename=\"audio.mp3\"\r\nContent-Type: audio/mpeg\r\n\r\n[audio]\r\n--BOUNDARY\r\nContent-Disposition: form-data; name=\"model_id\"\r\n\r\nscribe_v2\r\n--BOUNDARY--\r\n"
+      },
+      "response": {
+        "status": 200,
+        "headers": {
+          "content-type": "application/json"
+        },
+        "body": "{\"language_code\":\"eng\",\"language_probability\":0.6618340611457825,\"text\":\"Hello from OpenCode\",\"words\":[{\"text\":\"Hello\",\"start\":0.4,\"end\":0.66,\"type\":\"word\",\"logprob\":-0.000014781842764932662},{\"text\":\" \",\"start\":0.66,\"end\":0.74,\"type\":\"spacing\",\"logprob\":-3.814689989667386e-6},{\"text\":\"from\",\"start\":0.74,\"end\":0.84,\"type\":\"word\",\"logprob\":-3.814689989667386e-6},{\"text\":\" \",\"start\":0.84,\"end\":0.9,\"type\":\"spacing\",\"logprob\":-0.018268775194883347},{\"text\":\"OpenCode\",\"start\":0.9,\"end\":1.44,\"type\":\"word\",\"logprob\":-0.1251817401498556}],\"transcription_id\":\"D4VfnANM2ArCHTujIb9q\",\"audio_duration_secs\":1.54125}"
+      }
+    },
+    {
+      "transport": "http",
+      "request": {
+        "method": "POST",
+        "url": "https://api.elevenlabs.io/v1/speech-to-text",
+        "headers": {
+          "content-type": "multipart/form-data; boundary=----WebKitFormBoundaryfb80d0e44d9e44d299416ed546a04056"
+        },
+        "body": "--BOUNDARY\r\nContent-Disposition: form-data; name=\"file\"; filename=\"audio.mp3\"\r\nContent-Type: audio/mpeg\r\n\r\n[audio]\r\n--BOUNDARY\r\nContent-Disposition: form-data; name=\"model_id\"\r\n\r\nscribe_v2\r\n--BOUNDARY--\r\n"
+      },
+      "response": {
+        "status": 200,
+        "headers": {
+          "content-type": "application/json"
+        },
+        "body": "{\"language_code\":\"eng\",\"language_probability\":0.6618340611457825,\"text\":\"Hello from OpenCode\",\"words\":[{\"text\":\"Hello\",\"start\":0.4,\"end\":0.66,\"type\":\"word\",\"logprob\":-0.000023007127310847864},{\"text\":\" \",\"start\":0.66,\"end\":0.74,\"type\":\"spacing\",\"logprob\":-2.3841830625315197e-6},{\"text\":\"from\",\"start\":0.74,\"end\":0.84,\"type\":\"word\",\"logprob\":-2.3841830625315197e-6},{\"text\":\" \",\"start\":0.84,\"end\":0.9,\"type\":\"spacing\",\"logprob\":-0.008306833915412426},{\"text\":\"OpenCode\",\"start\":0.9,\"end\":1.44,\"type\":\"word\",\"logprob\":-0.1075385226868093}],\"transcription_id\":\"SkYplzfq1DW8Ae3bWnoy\",\"audio_duration_secs\":1.54125}"
+      }
+    }
+  ]
+}

packages/ai/test/image.test.ts

@@ -842,6 +842,30 @@ describe("Image", () => {
     ),
   )
 
+  const falDetail = { detail: [{ loc: ["body", "prompt"], msg: "Invalid input", type: "value_error" }] }
+  it.effect(
+    "fails a fal await whose COMPLETED status carries an error with the response_url body and HTTP context",
+    () =>
+      Effect.gen(function* () {
+        const generation = yield* Image.resume(Fal.configure({ apiKey: "test" }).image("fal-ai/flux/schnell"), falToken)
+        expect(generation.status).toBe("failed")
+        const error = yield* generation.await().pipe(Effect.flip)
+        expect(error.reason._tag).toBe("InvalidRequest")
+        expect(error.reason.body).toBe(JSON.stringify(falDetail))
+        expect(error.reason.http).toMatchObject({ url: falToken.responseURL, status: 422 })
+      }).pipe(
+        Effect.provide(
+          layer((input) =>
+            Effect.succeed(
+              input.request.url === falToken.statusURL
+                ? json(input, { status: "COMPLETED", error: "Invalid input", error_type: "ValidationError" })
+                : json(input, falDetail, { status: 422 }),
+            ),
+          ),
+        ),
+      ),
+  )
+
   const moderated = { id: "req_1", status: "Content Moderated" }
   const prediction = {
     id: "p_1",

packages/ai/test/promise.test.ts

@@ -22,7 +22,8 @@ const chatBody = sseEvents(
 /**
  * Executor layer that answers chat completions with SSE text, image generations with one base64 PNG, Runway video
  * tasks with a queued submission that succeeds on the second poll, speech with raw audio or SSE audio deltas, OpenAI
- * transcription with JSON or SSE text deltas, and AssemblyAI transcripts that complete on the first poll.
+ * transcription with JSON or SSE text deltas, AssemblyAI transcripts that complete on the first poll, and `slow.test`
+ * chat completions that send one text delta and never finish.
  */
 const executor = (seen: Array<string>) =>
   RequestExecutor.layer.pipe(
@@ -55,6 +56,18 @@ const executor = (seen: Array<string>) =>
               output: "https://replicate.test/a.webp",
               urls: { get: "https://replicate.test/p_1", cancel: "https://replicate.test/p_1/cancel" },
             })
+          if (web.url.startsWith("https://slow.test"))
+            return input.respond(
+              new ReadableStream({
+                start: (controller) =>
+                  controller.enqueue(
+                    new TextEncoder().encode(
+                      `data: ${JSON.stringify({ choices: [{ delta: { content: "Hello" } }] })}\n\n`,
+                    ),
+                  ),
+              }),
+              { headers: { "content-type": "text/event-stream" } },
+            )
           if (web.url.endsWith("/chat/completions"))
             return input.respond(chatBody, { headers: { "content-type": "text/event-stream" } })
           if (web.url.endsWith("/audio/speech"))
@@ -304,6 +317,77 @@ describe("AI promise client", () => {
     await ai.dispose()
   })
 
+  test("aborted calls reject and aborted streams throw with the signal's reason", async () => {
+    const ai = AI.make({ layer: executor([]) })
+    const slow = OpenAI.configure({ apiKey: "test", baseURL: "https://slow.test/v1" }).chat("gpt-4o-mini")
+    const aborted = new AbortController()
+    aborted.abort()
+    const reason = new Error("mine")
+
+    const rejected = await ai.run(Effect.never, { signal: aborted.signal }).catch((error: unknown) => error)
+    expect(rejected).toBe(aborted.signal.reason)
+    expect(rejected).toMatchObject({ name: "AbortError" })
+
+    const inFlight = new AbortController()
+    setTimeout(() => inFlight.abort(reason), 10)
+    expect(
+      await ai.llm
+        .generate({ model: slow, prompt: "Hello" }, { signal: inFlight.signal })
+        .catch((error: unknown) => error),
+    ).toBe(reason)
+
+    const preAborted = await Array.fromAsync(
+      ai.speech.stream({ model: openai.speech("gpt-4o-mini-tts"), text: "Hello" }, { signal: aborted.signal }),
+    ).catch((error: unknown) => error)
+    expect(preAborted).toBe(aborted.signal.reason)
+    expect(preAborted).toMatchObject({ name: "AbortError" })
+
+    const midStream = new AbortController()
+    const deltas: Array<string> = []
+    const midStreamFailure = await Array.fromAsync(
+      ai.llm.stream({ model: slow, prompt: "Hello" }, { signal: midStream.signal }),
+      (event) => {
+        if (!LLMEvent.is.textDelta(event)) return
+        deltas.push(event.text)
+        midStream.abort()
+      },
+    ).catch((error: unknown) => error)
+    expect(deltas).toEqual(["Hello"])
+    expect(midStreamFailure).toBe(midStream.signal.reason)
+    expect(midStreamFailure).toMatchObject({ name: "AbortError" })
+
+    const model = Runway.configure({ apiKey: "test", baseURL: "https://runway.test/v1" }).video("gen4.5")
+    const generation = await ai.video.start({ model, prompt: "A kite" })
+    const polling = new AbortController()
+    const events: Array<string> = []
+    const eventsFailure = await Array.fromAsync(
+      generation.events({ poll: { interval: 60_000 }, signal: polling.signal }),
+      (event) => {
+        events.push(event.type)
+        polling.abort(reason)
+      },
+    ).catch((error: unknown) => error)
+    expect(events).toEqual(["generation-progress"])
+    expect(eventsFailure).toBe(reason)
+
+    await ai.dispose()
+  })
+
+  test("breaking out of an abortable stream cleans up without throwing", async () => {
+    const ai = AI.make({ layer: executor([]) })
+    const slow = OpenAI.configure({ apiKey: "test", baseURL: "https://slow.test/v1" }).chat("gpt-4o-mini")
+    const controller = new AbortController()
+    const deltas: Array<string> = []
+    for await (const event of ai.llm.stream({ model: slow, prompt: "Hello" }, { signal: controller.signal })) {
+      if (!LLMEvent.is.textDelta(event)) continue
+      deltas.push(event.text)
+      break
+    }
+    controller.abort()
+    expect(deltas).toEqual(["Hello"])
+    await ai.dispose()
+  })
+
   test("the default client is created lazily and can be disposed", async () => {
     expect(typeof AI.ai.llm.generate).toBe("function")
     expect(typeof AI.ai.image.generate).toBe("function")

packages/ai/test/provider/elevenlabs-transcription.recorded.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect } from "bun:test"
+import { Effect, Stream } from "effect"
+import { Transcription } from "../../src/index.js"
+import { ElevenLabs } from "../../src/providers.js"
+import { recordedTests } from "../recorded-test.js"
+import { TRANSCRIPT, audio, audioRecording, dialog } from "./transcription-recording.js"
+
+const model = ElevenLabs.configure({ apiKey: process.env.ELEVENLABS_API_KEY ?? "fixture" }).transcription("scribe_v2")
+
+const recorded = recordedTests({
+  prefix: "elevenlabs-transcription",
+  provider: "elevenlabs",
+  protocol: "elevenlabs-transcription",
+  requires: ["ELEVENLABS_API_KEY"],
+  options: audioRecording,
+})
+
+describe("ElevenLabs Transcription recorded", () => {
+  recorded.effect("transcribes audio with word timestamps", () =>
+    Effect.gen(function* () {
+      const request = Transcription.request({ model, audio: yield* audio, timestamps: "word" })
+      const response = yield* Transcription.generate(request)
+
+      expect(response.text).toMatch(TRANSCRIPT)
+      expect(response.words?.map((word) => word.text)).toEqual(["Hello", "from", "OpenCode"])
+      expect(response.words?.every((word) => word.speaker === undefined && (word.confidence ?? 0) > 0)).toBe(true)
+      expect(response.segments).toBeUndefined()
+      expect(response.language).toBe("eng")
+      expect(response.durationSeconds).toBeGreaterThan(0)
+      expect(response.usage).toEqual({ type: "seconds", seconds: response.durationSeconds })
+      expect(response.providerMetadata?.elevenlabs?.transcriptionId).toEqual(expect.any(String))
+
+      const events = Array.from(yield* Stream.runCollect(Transcription.stream(request)))
+      expect(events.map((event) => event.type)).toEqual(["finish"])
+    }),
+  )
+
+  recorded.effect("groups diarized words into speaker turns", () =>
+    Effect.gen(function* () {
+      const response = yield* Transcription.generate({ model, audio: yield* dialog, diarize: true })
+
+      expect(response.segments?.map((segment) => segment.speaker)).toEqual(["speaker_0", "speaker_1"])
+      expect(response.segments?.[0].text).toMatch(/^Did the release ship\?$/)
+      expect(response.segments?.[1].text).toMatch(/^Yes, it shipped this morning\.?$/)
+      expect(response.segments?.map((segment) => segment.text).join(" ")).toBe(response.text)
+      expect(response.words?.some((word) => word.text.trim() === "")).toBe(false)
+      expect(new Set(response.words?.map((word) => word.speaker))).toEqual(new Set(["speaker_0", "speaker_1"]))
+    }),
+  )
+})

packages/ai/test/transcription.test.ts

@@ -2,10 +2,11 @@ import { describe, expect } from "bun:test"
 import { Effect, Fiber, Layer, Stream } from "effect"
 import * as TestClock from "effect/testing/TestClock"
 import { HttpClientRequest } from "effect/unstable/http"
-import { Media, Transcription, TranscriptionClient } from "../src/index.js"
-import { AssemblyAI, Deepgram, Google, OpenAI } from "../src/providers.js"
+import { Media, Transcription, TranscriptionClient, type TranscriptionEvent } from "../src/index.js"
+import { AssemblyAI, Deepgram, ElevenLabs, Google, OpenAI } from "../src/providers.js"
 import { it } from "./lib/effect.js"
 import { dynamicResponse, json, observe, type Call } from "./lib/http.js"
+import { sseEvents } from "./lib/sse.js"
 
 const layer = (handler: Parameters<typeof dynamicResponse>[0]) =>
   TranscriptionClient.layer.pipe(Layer.provideMerge(dynamicResponse(handler)))
@@ -16,9 +17,27 @@ const deepgram = Deepgram.configure({ apiKey: "test", baseURL: "https://deepgram
 const google = Google.configure({ apiKey: "test", baseURL: "https://google.test/v1beta" }).transcription(
   "gemini-3.5-transcribe",
 )
+/**
+ * Multipart fields of a recorded request, with repeated names collected in order. The boundary comes from the body:
+ * each conversion of a FormData request to a web request picks a fresh one, so the recorded headers may not match.
+ */
+const formFields = (call: Call) =>
+  Effect.promise(() =>
+    new Response(call.body, {
+      headers: { "content-type": `multipart/form-data; boundary=${call.body.slice(2, call.body.indexOf("\r\n"))}` },
+    }).formData(),
+  ).pipe(
+    Effect.map((form) =>
+      Object.fromEntries([...new Set(form.keys())].map((key) => [key, form.getAll(key).map((value) => String(value))])),
+    ),
+  )
+
 const assemblyai = AssemblyAI.configure({ apiKey: "aai-key", baseURL: "https://assemblyai.test" }).transcription(
   "universal-3-5-pro",
 )
+const elevenlabs = ElevenLabs.configure({ apiKey: "test", baseURL: "https://elevenlabs.test" }).transcription(
+  "scribe_v2",
+)
 
 describe("Transcription", () => {
   it.effect("rejects what a route cannot honor before sending anything", () =>
@@ -129,6 +148,198 @@ describe("Transcription", () => {
     }),
   )
 
+  it.effect("streams diarized segments and finishes with the accumulated segments", () =>
+    Effect.gen(function* () {
+      const calls: Array<Call> = []
+      const body = sseEvents(
+        { type: "transcript.text.segment", id: "seg_0", text: " Hello", start: 0.25, end: 0.7, speaker: "A" },
+        { type: "transcript.text.segment", id: "seg_1", text: " there.", start: 0.7, end: 1.25, speaker: "B" },
+        { type: "transcript.text.done", text: "Hello there.", usage: { type: "duration", seconds: 2 } },
+      )
+      const events = Array.from(
+        yield* Stream.runCollect(
+          Transcription.stream({ model: openai.transcription("gpt-4o-transcribe-diarize"), audio, diarize: true }),
+        ).pipe(
+          Effect.provide(
+            layer((input) =>
+              observe(calls, input).pipe(
+                Effect.as(input.respond(body, { headers: { "content-type": "text/event-stream" } })),
+              ),
+            ),
+          ),
+        ),
+      )
+
+      const form = yield* formFields(calls[0])
+      expect(form).toMatchObject({
+        model: ["gpt-4o-transcribe-diarize"],
+        response_format: ["diarized_json"],
+        chunking_strategy: ["auto"],
+        stream: ["true"],
+      })
+      const segments = [
+        { text: "Hello", startSeconds: 0.25, endSeconds: 0.7, speaker: "A" },
+        { text: "there.", startSeconds: 0.7, endSeconds: 1.25, speaker: "B" },
+      ]
+      expect(events).toEqual([
+        { type: "segment", segment: segments[0] },
+        { type: "segment", segment: segments[1] },
+        expect.objectContaining({
+          type: "finish",
+          text: "Hello there.",
+          segments,
+          usage: { type: "seconds", seconds: 2 },
+        }),
+      ])
+    }),
+  )
+
+  it.effect("requests whisper-1 segment timestamps as verbose_json", () =>
+    Effect.gen(function* () {
+      const calls: Array<Call> = []
+      const response = yield* Transcription.generate({
+        model: openai.transcription("whisper-1"),
+        audio,
+        timestamps: "segment",
+      }).pipe(
+        Effect.provide(
+          layer((input) =>
+            observe(calls, input).pipe(
+              Effect.as(
+                json(input, {
+                  text: "Hello there.",
+                  language: "English",
+                  duration: 1.25,
+                  segments: [
+                    { id: 0, text: " Hello", start: 0.25, end: 0.7 },
+                    { id: 1, text: " there.", start: 0.7, end: 1.25 },
+                  ],
+                  usage: { type: "duration", seconds: 2 },
+                }),
+              ),
+            ),
+          ),
+        ),
+      )
+
+      const form = yield* formFields(calls[0])
+      expect(form).toMatchObject({
+        model: ["whisper-1"],
+        response_format: ["verbose_json"],
+        "timestamp_granularities[]": ["segment"],
+      })
+      expect(form.stream).toBeUndefined()
+      expect(response).toMatchObject({
+        text: "Hello there.",
+        segments: [
+          { text: "Hello", startSeconds: 0.25, endSeconds: 0.7 },
+          { text: "there.", startSeconds: 0.7, endSeconds: 1.25 },
+        ],
+        language: "english",
+        durationSeconds: 1.25,
+        usage: { type: "seconds", seconds: 2 },
+      })
+    }),
+  )
+
+  it.effect("fails an OpenAI stream that ends without transcript.text.done as incomplete", () =>
+    Effect.gen(function* () {
+      const events: Array<TranscriptionEvent> = []
+      const error = yield* Transcription.stream({ model: openai.transcription("gpt-4o-mini-transcribe"), audio }).pipe(
+        Stream.runForEach((event) => Effect.sync(() => events.push(event))),
+        Effect.flip,
+        Effect.provide(
+          layer((input) =>
+            Effect.succeed(
+              input.respond(sseEvents({ type: "transcript.text.delta", delta: "Hel" }), {
+                headers: { "content-type": "text/event-stream" },
+              }),
+            ),
+          ),
+        ),
+      )
+
+      expect(events).toEqual([{ type: "text-delta", delta: "Hel" }])
+      expect(error.reason).toMatchObject({ _tag: "InvalidProviderOutput", classification: "incomplete-stream" })
+      expect(error.reason.http?.status).toBe(200)
+    }),
+  )
+
+  it.effect("sends a Deepgram URL source as a JSON body and repeats array query parameters", () =>
+    Effect.gen(function* () {
+      const calls: Array<Call> = []
+      const response = yield* Transcription.generate({
+        model: deepgram,
+        audio: Media.url("https://a.test/call.mp3", { mediaType: "audio/mpeg" }),
+        language: "en",
+        providerOptions: { keyterm: ["OpenCode", "Effect"] },
+      }).pipe(
+        Effect.provide(
+          layer((input) =>
+            observe(calls, input).pipe(
+              Effect.as(
+                json(input, {
+                  metadata: { request_id: "dg_1", duration: 2 },
+                  results: { channels: [{ alternatives: [{ transcript: "Hello there." }] }] },
+                }),
+              ),
+            ),
+          ),
+        ),
+      )
+
+      expect(calls).toHaveLength(1)
+      const url = new URL(calls[0].url)
+      expect(url.origin + url.pathname).toBe("https://deepgram.test/v1/listen")
+      expect([...url.searchParams]).toEqual([
+        ["model", "nova-3"],
+        ["smart_format", "true"],
+        ["language", "en"],
+        ["keyterm", "OpenCode"],
+        ["keyterm", "Effect"],
+      ])
+      expect(calls[0].headers.get("content-type")).toBe("application/json")
+      expect(JSON.parse(calls[0].body)).toEqual({ url: "https://a.test/call.mp3" })
+      expect(response).toMatchObject({
+        text: "Hello there.",
+        usage: { type: "seconds", seconds: 2 },
+        providerMetadata: { deepgram: { requestId: "dg_1" } },
+      })
+    }),
+  )
+
+  it.effect("transcribes an AssemblyAI URL source without uploading it first", () =>
+    Effect.gen(function* () {
+      const calls: Array<Call> = []
+      const response = yield* Transcription.generate({
+        model: assemblyai,
+        audio: Media.url("https://a.test/call.mp3", { mediaType: "audio/mpeg" }),
+      }).pipe(
+        Effect.provide(
+          layer((input) =>
+            Effect.gen(function* () {
+              const { call } = yield* observe(calls, input)
+              if (call.method === "POST") return json(input, { id: "tr_1", status: "queued" })
+              return json(input, { id: "tr_1", status: "completed", text: "Hello there.", audio_duration: 2 })
+            }),
+          ),
+        ),
+      )
+
+      expect(calls.map((call) => `${call.method} ${call.url}`)).toEqual([
+        "POST https://assemblyai.test/v2/transcript",
+        "GET https://assemblyai.test/v2/transcript/tr_1",
+        "GET https://assemblyai.test/v2/transcript/tr_1",
+      ])
+      expect(JSON.parse(calls[0].body)).toEqual({
+        audio_url: "https://a.test/call.mp3",
+        speech_models: ["universal-3-5-pro"],
+        language_detection: true,
+      })
+      expect(response).toMatchObject({ text: "Hello there.", usage: { type: "seconds", seconds: 2 } })
+    }),
+  )
+
   it.effect(
     "uploads inline audio to AssemblyAI, resumes polling from a persisted token, and surfaces failed transcripts",
     () =>
@@ -251,6 +462,115 @@ describe("Transcription", () => {
     }),
   )
 
+  it.effect("rejects ElevenLabs prompts, webhooks, per-channel transcripts, and untimed diarization", () =>
+    Effect.gen(function* () {
+      const errors = yield* Effect.all(
+        [
+          Transcription.generate({ model: elevenlabs, audio, prompt: "OpenCode" }),
+          Transcription.generate({ model: elevenlabs, audio, providerOptions: { webhook: true } }),
+          Transcription.generate({ model: elevenlabs, audio, http: { body: { use_multi_channel: true } } }),
+          Transcription.generate({
+            model: elevenlabs,
+            audio,
+            diarize: true,
+            providerOptions: { timestamps_granularity: "none" },
+          }),
+          Transcription.generate({
+            model: elevenlabs,
+            audio: Media.ref("file_1", { provider: "elevenlabs", mediaType: "audio/mpeg" }),
+          }),
+        ].map((effect) => Effect.flip(effect)),
+      )
+      expect(errors.map((error) => [error.reason._tag, "operation" in error.reason && error.reason.operation])).toEqual(
+        [
+          ["UnsupportedOperation", "media.prompt"],
+          ["UnsupportedOperation", "transcription.webhook"],
+          ["UnsupportedOperation", "transcription.multichannel"],
+          ["UnsupportedOperation", "media.timestamps"],
+          ["InvalidRequest", false],
+        ],
+      )
+    }).pipe(Effect.provide(layer(() => Effect.die("an unsupported request reached the network")))),
+  )
+
+  it.effect("sends ElevenLabs URL audio as source_url and groups diarized words into speaker turns", () =>
+    Effect.gen(function* () {
+      const calls: Array<Call> = []
+      const token = (text: string, type: string, start: number, end: number, speaker_id?: string) => ({
+        text,
+        type,
+        start,
+        end,
+        speaker_id,
+        logprob: 0,
+      })
+      const response = yield* Transcription.generate({
+        model: elevenlabs,
+        audio: Media.url("https://a.test/call.mp3"),
+        language: "en",
+        speakers: 2,
+        providerOptions: { keyterms: ["OpenCode", "Scribe"], tag_audio_events: true, diarize: false },
+      }).pipe(
+        Effect.provide(
+          layer((input) =>
+            observe(calls, input).pipe(
+              Effect.as(
+                json(input, {
+                  language_code: "ENG",
+                  text: "Ready? (laughs) Yes. Go",
+                  words: [
+                    token("Ready?", "word", 0, 0.5, "speaker_0"),
+                    token(" ", "spacing", 0.5, 0.6, "speaker_0"),
+                    token("(laughs)", "audio_event", 0.6, 1, "speaker_0"),
+                    token(" ", "spacing", 1, 1.1, "speaker_0"),
+                    token("Yes.", "word", 1.2, 1.5, "speaker_1"),
+                    token(" ", "spacing", 1.5, 1.6, "speaker_1"),
+                    token("Go", "word", 1.6, 1.9, "speaker_0"),
+                  ],
+                  transcription_id: "tr_1",
+                  audio_duration_secs: 2,
+                }),
+              ),
+            ),
+          ),
+        ),
+      )
+
+      // `observe` re-encodes the FormData with a new boundary, so read the boundary from the sent body.
+      const boundary = /^--(\S+)/.exec(calls[0].body)?.[1]
+      const form = yield* Effect.promise(() =>
+        new Response(calls[0].body, {
+          headers: { "content-type": `multipart/form-data; boundary=${boundary}` },
+        }).formData(),
+      )
+      expect(calls[0].url).toBe("https://elevenlabs.test/v1/speech-to-text")
+      expect(calls[0].headers.get("xi-api-key")).toBe("test")
+      expect(Array.from(form.entries())).toEqual([
+        ["model_id", "scribe_v2"],
+        ["source_url", "https://a.test/call.mp3"],
+        ["language_code", "en"],
+        ["diarize", "true"],
+        ["num_speakers", "2"],
+        ["keyterms", "OpenCode"],
+        ["keyterms", "Scribe"],
+        ["tag_audio_events", "true"],
+      ])
+      expect(response.segments).toEqual([
+        { text: "Ready?", startSeconds: 0, endSeconds: 0.5, speaker: "speaker_0" },
+        { text: "Yes.", startSeconds: 1.2, endSeconds: 1.5, speaker: "speaker_1" },
+        { text: "Go", startSeconds: 1.6, endSeconds: 1.9, speaker: "speaker_0" },
+      ])
+      expect(response.words?.map((word) => [word.text, word.speaker, word.confidence])).toEqual([
+        ["Ready?", "speaker_0", 1],
+        ["Yes.", "speaker_1", 1],
+        ["Go", "speaker_0", 1],
+      ])
+      expect(response.language).toBe("eng")
+      expect(response.usage).toEqual({ type: "seconds", seconds: 2 })
+      expect(response.providerMetadata).toEqual({ elevenlabs: { transcriptionId: "tr_1" } })
+    }),
+  )
+
   it.effect("rejects reading an AssemblyAI result before the transcript finishes", () =>
     Effect.gen(function* () {
       const generation = yield* Transcription.resume(assemblyai, { transcriptID: "tr_1" })

packages/ai/test/video.test.ts

@@ -1,9 +1,10 @@
 import { describe, expect } from "bun:test"
-import { Effect, Layer, Stream } from "effect"
-import { Media, Video, VideoClient, type GenerationEvent } from "../src/index.js"
+import { Effect, Fiber, Layer, Stream } from "effect"
+import * as TestClock from "effect/testing/TestClock"
+import { Media, Video, VideoClient, type GenerationEvent, type VideoEvent } from "../src/index.js"
 import { Fal, Google, Runway, XAI } from "../src/providers.js"
 import { it } from "./lib/effect.js"
-import { dynamicResponse, json, observe, settle, type Call } from "./lib/http.js"
+import { dynamicResponse, json, observe, settle, type Call, type HandlerInput } from "./lib/http.js"
 
 const layer = (handler: Parameters<typeof dynamicResponse>[0]) =>
   VideoClient.layer.pipe(Layer.provideMerge(dynamicResponse(handler)))
@@ -162,27 +163,39 @@ describe("Video / Google Veo", () => {
     ),
   )
 
-  it.effect("surfaces an operation error as a failed generation with the provider body", () =>
-    Effect.gen(function* () {
-      const failure = {
-        name: operation,
-        done: true,
-        error: { code: 3, message: "Prompt violates policy", status: "INVALID_ARGUMENT" },
-      }
-      const error = yield* Video.generate({ model, prompt: "nope" }).pipe(
-        Effect.flip,
-        Effect.provide(
-          layer((input) =>
-            Effect.succeed(input.request.method === "POST" ? json(input, { name: operation }) : json(input, failure)),
-          ),
-        ),
-      )
-      expect(error.reason._tag).toBe("ProviderInternal")
-      expect(error.message).toBe("Google Veo operation failed: Prompt violates policy")
-      expect(error.reason.body).toBe(JSON.stringify(failure))
-      expect(error.reason.http?.status).toBe(200)
-    }),
-  )
+  for (const terminal of [
+    { error: { code: 3, message: "Prompt violates policy", status: "INVALID_ARGUMENT" }, tag: "InvalidRequest" },
+    { error: { code: 9, message: "Unsupported resolution", status: "FAILED_PRECONDITION" }, tag: "InvalidRequest" },
+    { error: { code: 11, message: "Duration out of range", status: "OUT_OF_RANGE" }, tag: "InvalidRequest" },
+    { error: { code: 7, message: "Permission denied", status: "PERMISSION_DENIED" }, tag: "Authentication" },
+    { error: { code: 16, message: "Invalid credentials", status: "UNAUTHENTICATED" }, tag: "Authentication" },
+    { error: { code: 8, message: "Quota exceeded", status: "RESOURCE_EXHAUSTED" }, tag: "RateLimit" },
+    { error: { code: 13, message: "Internal error", status: "INTERNAL" }, tag: "ProviderInternal" },
+    { error: { code: 14, message: "Service unavailable", status: "UNAVAILABLE" }, tag: "ProviderInternal" },
+    { error: { message: "Something broke" }, tag: "ProviderInternal" },
+  ]) {
+    it.effect(
+      `surfaces ${terminal.error.status ?? "an uncoded"} operation error as ${terminal.tag} with the provider body`,
+      () =>
+        Effect.gen(function* () {
+          const failure = { name: operation, done: true, error: terminal.error }
+          const error = yield* Video.generate({ model, prompt: "nope" }).pipe(
+            Effect.flip,
+            Effect.provide(
+              layer((input) =>
+                Effect.succeed(
+                  input.request.method === "POST" ? json(input, { name: operation }) : json(input, failure),
+                ),
+              ),
+            ),
+          )
+          expect(error.reason._tag).toBe(terminal.tag)
+          expect(error.message).toBe(`Google Veo operation failed: ${terminal.error.message}`)
+          expect(error.reason.body).toBe(JSON.stringify(failure))
+          expect(error.reason.http?.status).toBe(200)
+        }),
+    )
+  }
 
   it.effect("reports fully filtered output as a content policy failure", () =>
     Effect.gen(function* () {
@@ -332,12 +345,37 @@ describe("Video / xAI", () => {
   for (const terminal of [
     {
       body: { status: "failed", error: { code: "invalid_argument", message: "Prompt cannot be empty." } },
-      tag: "ProviderInternal",
+      tag: "InvalidRequest",
       message: "xAI Video generation failed (invalid_argument): Prompt cannot be empty.",
     },
+    {
+      body: { status: "failed", error: { code: "failed_precondition", message: "Extension is not supported." } },
+      tag: "InvalidRequest",
+      message: "xAI Video generation failed (failed_precondition): Extension is not supported.",
+    },
+    {
+      body: { status: "failed", error: { code: "permission_denied", message: "Team lacks access." } },
+      tag: "Authentication",
+      message: "xAI Video generation failed (permission_denied): Team lacks access.",
+    },
+    {
+      body: { status: "failed", error: { code: "service_unavailable", message: "Overloaded." } },
+      tag: "ProviderInternal",
+      message: "xAI Video generation failed (service_unavailable): Overloaded.",
+    },
+    {
+      body: { status: "failed", error: { code: "internal_error", message: "Generation failed." } },
+      tag: "ProviderInternal",
+      message: "xAI Video generation failed (internal_error): Generation failed.",
+    },
+    {
+      body: { status: "failed", error: { code: "constructor", message: "Future code." } },
+      tag: "ProviderInternal",
+      message: "xAI Video generation failed (constructor): Future code.",
+    },
     { body: { status: "expired" }, tag: "InvalidRequest", message: "xAI Video request req_1 expired" },
   ]) {
-    it.effect(`surfaces ${terminal.body.status} generations with the provider body`, () =>
+    it.effect(`surfaces ${terminal.body.error?.code ?? terminal.body.status} generations with the provider body`, () =>
       Effect.gen(function* () {
         const error = yield* Video.generate({ model, prompt: "x" }).pipe(Effect.flip)
         expect(error.reason._tag).toBe(terminal.tag)
@@ -542,6 +580,45 @@ describe("Video / fal", () => {
     ),
   )
 
+  for (const failure of [
+    {
+      name: "a COMPLETED status carrying an error",
+      status: { status: "COMPLETED", error: "Invalid input", error_type: "ValidationError" },
+      result: { status: 422, body: { detail: [{ loc: ["body", "prompt"], msg: "Invalid input" }] } },
+      tag: "InvalidRequest",
+    },
+    {
+      name: "a failing response_url",
+      status: { status: "COMPLETED" },
+      result: { status: 500, body: { detail: "Internal error" } },
+      tag: "ProviderInternal",
+    },
+  ]) {
+    it.effect(`fails await for ${failure.name} with the response_url body and HTTP context`, () =>
+      Effect.gen(function* () {
+        // A transient 500 on the result fetch is retried first; the body and HTTP context survive the final failure.
+        const fiber = yield* Effect.forkChild(Video.generate({ model, prompt: "x" }).pipe(Effect.flip))
+        yield* TestClock.adjust("5 minutes")
+        const error = yield* Fiber.join(fiber)
+        expect(error.reason._tag).toBe(failure.tag)
+        expect(error.reason.body).toBe(JSON.stringify(failure.result.body))
+        expect(error.reason.http).toMatchObject({ url: urls.response, status: failure.result.status })
+      }).pipe(
+        Effect.provide(
+          layer((input) =>
+            Effect.succeed(
+              input.request.method === "POST"
+                ? json(input, submitted)
+                : input.request.url === urls.response
+                  ? json(input, failure.result.body, { status: failure.result.status })
+                  : json(input, failure.status),
+            ),
+          ),
+        ),
+      ),
+    )
+  }
+
   it.effect("rejects model-specific common fields and points at providerOptions", () =>
     Effect.gen(function* () {
       const errors = yield* Effect.forEach(
@@ -729,6 +806,11 @@ describe("Video / Runway", () => {
       tag: "ProviderInternal",
       message: "Runway task failed (INTERNAL.BAD_OUTPUT.CODE01): Something broke",
     },
+    {
+      body: { status: "FAILED", failure: "Unsupported dimensions", failureCode: "ASSET.INVALID" },
+      tag: "InvalidRequest",
+      message: "Runway task failed (ASSET.INVALID): Unsupported dimensions",
+    },
     { body: { status: "CANCELLED" }, tag: "InvalidRequest", message: "Runway task task_1 was cancelled" },
   ]) {
     it.effect(`surfaces ${terminal.body.failureCode ?? terminal.body.status} with the task body`, () =>
@@ -818,6 +900,39 @@ describe("Video / Runway", () => {
     }),
   )
 
+  it.effect("streams the observations of a failed task and then fails with the task body", () =>
+    Effect.gen(function* () {
+      const calls: Array<Call> = []
+      const events: Array<VideoEvent> = []
+      const failed = { status: "FAILED", failure: "Something broke", failureCode: "INTERNAL.BAD_OUTPUT.CODE01" }
+      const program = Video.stream({ model, prompt: "x" }, { poll: { interval: "1 second" } }).pipe(
+        Stream.runForEach((event) => Effect.sync(() => events.push(event))),
+        Effect.flip,
+      )
+      const error = yield* settle(program, 3).pipe(
+        Effect.provide(
+          layer((input) =>
+            Effect.gen(function* () {
+              const { call, nth } = yield* observe(calls, input)
+              if (call.method === "POST") return json(input, { id: "task_1" })
+              if (nth === 1) return json(input, { status: "PENDING" })
+              if (nth === 2) return json(input, { status: "RUNNING", progress: 0.5 })
+              return json(input, failed)
+            }),
+          ),
+        ),
+      )
+      expect(events).toEqual([
+        { type: "generation-queued", id: "task_1", position: undefined },
+        { type: "generation-progress", id: "task_1", progress: 0.5 },
+      ])
+      expect(error.reason._tag).toBe("ProviderInternal")
+      expect(error.message).toBe("Runway task failed (INTERNAL.BAD_OUTPUT.CODE01): Something broke")
+      expect(error.reason.body).toBe(JSON.stringify(failed))
+      expect(error.reason.http?.status).toBe(200)
+    }),
+  )
+
   it.effect("fails a stream with a Timeout reason once polling passes the poll deadline", () =>
     Effect.gen(function* () {
       const program = Video.stream(
@@ -839,6 +954,169 @@ describe("Video / Runway", () => {
   )
 })
 
+// ---------------------------------------------------------------------------
+// Transient read failures
+// ---------------------------------------------------------------------------
+
+describe("Video / transient read failures", () => {
+  const model = Runway.configure({ apiKey: "test", baseURL: "https://runway.test/v1" }).video("gen4.5")
+  const succeeded = { id: "task_1", status: "SUCCEEDED", output: ["https://runway.test/out.mp4"] }
+  const failure = (input: HandlerInput, status: number, headers?: Record<string, string>) =>
+    json(input, { error: `HTTP ${status}` }, { status, headers })
+  const methods = (calls: ReadonlyArray<Call>) => calls.map((call) => call.method)
+
+  it.effect("retries a 503 status poll and a 503 result read, then returns the result", () =>
+    Effect.gen(function* () {
+      const calls: Array<Call> = []
+      const response = yield* settle(
+        Video.generate({ model, prompt: "x" }, { poll: { interval: "1 second" } }),
+        5,
+      ).pipe(
+        Effect.provide(
+          layer((input) =>
+            Effect.gen(function* () {
+              const { call, nth } = yield* observe(calls, input)
+              if (call.method === "POST") return json(input, { id: "task_1" })
+              // 1: status fails, 2: status succeeds, 3: result fails, 4: result succeeds.
+              if (nth === 1 || nth === 3) return failure(input, 503)
+              return json(input, succeeded)
+            }),
+          ),
+        ),
+      )
+      expect(response.video.source).toMatchObject({ type: "url", url: "https://runway.test/out.mp4" })
+      expect(methods(calls)).toEqual(["POST", "GET", "GET", "GET", "GET"])
+    }),
+  )
+
+  it.effect("waits for a 429 retry-after before polling again", () =>
+    Effect.gen(function* () {
+      const calls: Array<Call> = []
+      const fiber = yield* Effect.forkChild(
+        Video.generate({ model, prompt: "x" }, { poll: { interval: "1 second" } }).pipe(
+          Effect.provide(
+            layer((input) =>
+              Effect.gen(function* () {
+                const { call, nth } = yield* observe(calls, input)
+                if (call.method === "POST") return json(input, { id: "task_1" })
+                if (nth === 1) return failure(input, 429, { "retry-after": "10" })
+                return json(input, succeeded)
+              }),
+            ),
+          ),
+        ),
+      )
+      yield* TestClock.adjust("9 seconds")
+      expect(methods(calls)).toEqual(["POST", "GET"])
+      yield* TestClock.adjust("1 second")
+      yield* Fiber.join(fiber)
+      expect(methods(calls)).toEqual(["POST", "GET", "GET", "GET"])
+    }),
+  )
+
+  it.effect("fails a 400 status poll without retrying", () =>
+    Effect.gen(function* () {
+      const calls: Array<Call> = []
+      const error = yield* Video.generate({ model, prompt: "x" }).pipe(
+        Effect.flip,
+        Effect.provide(
+          layer((input) =>
+            Effect.gen(function* () {
+              const { call } = yield* observe(calls, input)
+              return call.method === "POST" ? json(input, { id: "task_1" }) : failure(input, 400)
+            }),
+          ),
+        ),
+      )
+      expect(error.reason._tag).toBe("InvalidRequest")
+      expect(methods(calls)).toEqual(["POST", "GET"])
+    }),
+  )
+
+  it.effect("stops retrying at poll.timeout with a Timeout reason", () =>
+    Effect.gen(function* () {
+      const calls: Array<Call> = []
+      const error = yield* settle(
+        Video.generate({ model, prompt: "x" }, { poll: { interval: "1 second", timeout: "5 seconds" } }).pipe(
+          Effect.flip,
+        ),
+        6,
+      ).pipe(
+        Effect.provide(
+          layer((input) =>
+            Effect.gen(function* () {
+              const { call } = yield* observe(calls, input)
+              return call.method === "POST" ? json(input, { id: "task_1" }) : failure(input, 503)
+            }),
+          ),
+        ),
+      )
+      expect(error.reason._tag).toBe("Timeout")
+      expect(calls.filter((call) => call.method === "GET").length).toBeGreaterThan(1)
+    }),
+  )
+
+  it.effect("bounds a streamed result read's retries by poll.timeout", () =>
+    Effect.gen(function* () {
+      const calls: Array<Call> = []
+      const error = yield* settle(
+        Video.stream({ model, prompt: "x" }, { poll: { interval: "1 second", timeout: "5 seconds" } }).pipe(
+          Stream.runCollect,
+          Effect.flip,
+        ),
+        6,
+      ).pipe(
+        Effect.provide(
+          layer((input) =>
+            Effect.gen(function* () {
+              const { call, nth } = yield* observe(calls, input)
+              if (call.method === "POST") return json(input, { id: "task_1" })
+              return nth === 1 ? json(input, succeeded) : failure(input, 503)
+            }),
+          ),
+        ),
+      )
+      expect(error.reason._tag).toBe("Timeout")
+      expect(calls.filter((call) => call.method === "GET").length).toBeGreaterThan(2)
+    }),
+  )
+
+  it.effect("never retries a failed submit", () =>
+    Effect.gen(function* () {
+      const calls: Array<Call> = []
+      const error = yield* Video.generate({ model, prompt: "x" }).pipe(
+        Effect.flip,
+        Effect.provide(layer((input) => observe(calls, input).pipe(Effect.map(() => failure(input, 503))))),
+      )
+      expect(error.reason._tag).toBe("ProviderInternal")
+      expect(methods(calls)).toEqual(["POST"])
+    }),
+  )
+
+  it.effect("never retries a failed cancel", () =>
+    Effect.gen(function* () {
+      const calls: Array<Call> = []
+      const error = yield* Effect.gen(function* () {
+        const generation = yield* Video.start({ model, prompt: "x" })
+        return yield* generation.cancel().pipe(Effect.flip)
+      }).pipe(
+        Effect.provide(
+          layer((input) =>
+            Effect.gen(function* () {
+              const { call } = yield* observe(calls, input)
+              if (call.method === "POST") return json(input, { id: "task_1" })
+              if (call.method === "DELETE") return failure(input, 503)
+              return json(input, { id: "task_1", status: "RUNNING" })
+            }),
+          ),
+        ),
+      )
+      expect(error.reason._tag).toBe("ProviderInternal")
+      expect(methods(calls)).toEqual(["POST", "GET", "DELETE"])
+    }),
+  )
+})
+
 // ---------------------------------------------------------------------------
 // Shared queued behavior
 // ---------------------------------------------------------------------------
@@ -878,6 +1156,123 @@ describe("Video / queued result", () => {
     )
   }
 
+  const veoOperation = "models/veo-3.1/operations/op_1"
+  const falURLs = {
+    status: "https://queue.fal.test/fal-ai/veo3.1/requests/r1/status",
+    response: "https://queue.fal.test/fal-ai/veo3.1/requests/r1",
+    cancel: "https://queue.fal.test/fal-ai/veo3.1/requests/r1/cancel",
+  }
+  for (const queued of [
+    {
+      model: Google.configure({ apiKey: "test", baseURL: "https://google.test/v1beta" }).video("veo-3.1"),
+      submitted: { name: veoOperation },
+      token: { operation: veoOperation },
+      submitURL: "https://google.test/v1beta/models/veo-3.1:predictLongRunning",
+      statusURL: `https://google.test/v1beta/${veoOperation}`,
+      resultURL: `https://google.test/v1beta/${veoOperation}`,
+      running: { name: veoOperation, done: false },
+      done: {
+        name: veoOperation,
+        done: true,
+        response: { generateVideoResponse: { generatedSamples: [{ video: { uri: "https://google.test/out.mp4" } }] } },
+      },
+      result: undefined,
+      url: "https://google.test/out.mp4",
+    },
+    {
+      model: XAI.configure({ apiKey: "test", baseURL: "https://xai.test/v1" }).video("grok-imagine-video-1.5"),
+      submitted: { request_id: "req_1" },
+      token: { requestID: "req_1" },
+      submitURL: "https://xai.test/v1/videos/generations",
+      statusURL: "https://xai.test/v1/videos/req_1",
+      resultURL: "https://xai.test/v1/videos/req_1",
+      running: { status: "pending", progress: 40 },
+      done: { status: "done", video: { url: "https://vidgen.x.ai/out.mp4", respect_moderation: true } },
+      result: undefined,
+      url: "https://vidgen.x.ai/out.mp4",
+    },
+    {
+      model: Fal.configure({ apiKey: "test", baseURL: "https://queue.fal.test" }).video("fal-ai/veo3.1"),
+      submitted: {
+        request_id: "r1",
+        status_url: falURLs.status,
+        response_url: falURLs.response,
+        cancel_url: falURLs.cancel,
+      },
+      token: { requestID: "r1", statusURL: falURLs.status, responseURL: falURLs.response, cancelURL: falURLs.cancel },
+      submitURL: "https://queue.fal.test/fal-ai/veo3.1",
+      statusURL: falURLs.status,
+      resultURL: falURLs.response,
+      running: { status: "IN_PROGRESS" },
+      done: { status: "COMPLETED" },
+      result: { video: { url: "https://v3.fal.media/out.mp4" } },
+      url: "https://v3.fal.media/out.mp4",
+    },
+  ]) {
+    it.effect(`resumes a ${queued.model.provider} generation from a JSON round-tripped token`, () =>
+      Effect.gen(function* () {
+        const calls: Array<Call> = []
+        const response = yield* Effect.gen(function* () {
+          const started = yield* Video.start({ model: queued.model, prompt: "x" })
+          const resumed = yield* Video.resume(queued.model, JSON.parse(JSON.stringify(started.token)))
+          expect(resumed.status).toBe("running")
+          expect(resumed.token).toEqual(queued.token)
+          return yield* resumed.await()
+        }).pipe(
+          Effect.provide(
+            layer((input) =>
+              Effect.gen(function* () {
+                const { call, nth } = yield* observe(calls, input)
+                if (call.method === "POST") return json(input, queued.submitted)
+                if (call.url === queued.resultURL && queued.result !== undefined) return json(input, queued.result)
+                return json(input, nth === 1 ? queued.running : queued.done)
+              }),
+            ),
+          ),
+        )
+        expect(response.video.source).toEqual(expect.objectContaining({ type: "url", url: queued.url }))
+        expect(calls.map((call) => `${call.method} ${call.url}`)).toEqual([
+          `POST ${queued.submitURL}`,
+          `GET ${queued.statusURL}`,
+          `GET ${queued.statusURL}`,
+          `GET ${queued.resultURL}`,
+        ])
+      }),
+    )
+  }
+
+  for (const queued of [
+    {
+      model: Google.configure({ apiKey: "test", baseURL: "https://google.test/v1beta" }).video("veo-3.1"),
+      submitted: { name: veoOperation },
+    },
+    {
+      model: XAI.configure({ apiKey: "test", baseURL: "https://xai.test/v1" }).video("grok-imagine-video-1.5"),
+      submitted: { request_id: "req_1" },
+    },
+  ]) {
+    it.effect(`cancels a ${queued.model.provider} generation without sending a request`, () =>
+      Effect.gen(function* () {
+        const calls: Array<Call> = []
+        yield* Effect.gen(function* () {
+          const generation = yield* Video.start({ model: queued.model, prompt: "x" })
+          yield* generation.cancel()
+        }).pipe(
+          Effect.provide(
+            layer((input) =>
+              Effect.gen(function* () {
+                const { call } = yield* observe(calls, input)
+                if (call.method !== "POST") return yield* Effect.die(`cancel sent ${call.method} ${call.url}`)
+                return json(input, queued.submitted)
+              }),
+            ),
+          ),
+        )
+        expect(calls.map((call) => call.method)).toEqual(["POST"])
+      }),
+    )
+  }
+
   it.effect("rejects a status that only matches an inherited property", () =>
     Effect.gen(function* () {
       const error = yield* Video.resume(

packages/core/package.json

@@ -66,12 +66,6 @@
       "node": "./src/shell/parser-wasm.node.ts",
       "default": "./src/shell/parser-wasm.bun.ts"
     },
-    "#process-lock-ffi": {
-      "workerd": "./src/util/process-lock-ffi.workerd.ts",
-      "bun": "./src/util/process-lock-ffi.bun.ts",
-      "node": "./src/util/process-lock-ffi.node.ts",
-      "default": "./src/util/process-lock-ffi.bun.ts"
-    },
     "#v1-migration": {
       "types": "./src/database/v1-migration.bun.ts",
       "bun": "./src/database/v1-migration.bun.ts",

packages/core/script/build.ts

@@ -26,7 +26,6 @@ const result = await Bun.build({
     "#fff",
     "#photon-wasm",
     "#shell-parser-wasm",
-    "#process-lock-ffi",
     "#v1-migration",
   ],
   splitting: true,

packages/core/src/file-access.ts

@@ -30,12 +30,6 @@ export interface ExternalDirectoryAuthorization {
   readonly save: string
 }
 
-export const externalDirectoryPermission = (input: ExternalDirectoryAuthorization) => ({
-  action: input.action,
-  resources: [input.resource],
-  save: [input.save],
-})
-
 export interface Target {
   readonly absolute: AbsolutePath
   /** Location-relative for internal paths, absolute for external paths. */

packages/core/src/file.ts

@@ -1,6 +0,0 @@
-export * as File from "./file.js"
-
-import { FileDiff } from "@opencode/schema/file-diff"
-
-export const Diff = FileDiff.Info
-export type Diff = typeof Diff.Type

packages/core/src/git.ts

@@ -7,7 +7,7 @@ import { AbsolutePath, RelativePath } from "./schema.js"
 import { FSUtil } from "@opencode/util/fs-util"
 import { AppProcess } from "@opencode/util/process"
 import { makeGlobalNode } from "@opencode/util/effect/app-node"
-import { File } from "./file.js"
+import { FileDiff } from "@opencode/schema/file-diff"
 import { KeyedMutex } from "./effect/keyed-mutex.js"
 import { VcsPatch } from "./vcs/patch.js"
 import { gitExecutable } from "./util/git-executable.js"
@@ -152,7 +152,7 @@ export interface Interface {
       to: TreeID
       context?: number
       paths?: readonly RelativePath[]
-    }) => Effect.Effect<readonly File.Diff[], OperationError>
+    }) => Effect.Effect<readonly FileDiff.Info[], OperationError>
     readonly restore: (input: {
       repository: Repository
       files: ReadonlyMap<RelativePath, TreeID>
@@ -571,7 +571,7 @@ const layer = Layer.effect(
           additions: stat?.additions ?? 0,
           deletions: stat?.deletions ?? 0,
           patch: stat?.binary ? "" : (patches.get(entry.file) ?? VcsPatch.emptyPatch(entry.file)),
-        } satisfies File.Diff
+        } satisfies FileDiff.Info
       })
     })
 

packages/core/src/instance.ts

@@ -152,7 +152,7 @@ export function layer(ref: Location.Ref, options: Options = {}): Layer.Layer<Ser
   const replacements: LayerNode.Replacements = [
     ...(options.discovery === false ? vanillaReplacements : []),
     ...(options.replacements ?? []),
-    Location.node.replace(Location.boundNode(ref, { discovery: options.discovery })),
+    Location.node.replace(Location.boundNode(ref)),
     InstancePlugins.node.replace(InstancePlugins.bound(options.plugins ?? [])),
   ]
 

packages/core/src/location-mutation.ts

@@ -1,3 +0,0 @@
-/** @deprecated Use FileAccess for path resolution and authorization. */
-export { FileAccess as LocationMutation } from "./file-access.js"
-export * from "./file-access.js"

packages/core/src/location-services.ts

@@ -8,7 +8,6 @@ import { LocationServiceMap } from "./location-service-map.js"
 export { LocationServiceMap } from "./location-service-map.js"
 
 export type LocationServices = Instance.Services
-export type LocationError = Instance.Error
 
 export function buildLocationServiceMap(
   replacements: LayerNode.Replacements = [],

packages/core/src/location.ts

@@ -16,12 +16,12 @@ export class Service extends Context.Service<Service, Interface>()("@opencode/Lo
 
 export const node = LayerNode.unbound(Service, tags.values.location)
 
-const layer = (ref: Ref, options?: { readonly discovery?: boolean }) =>
+const layer = (ref: Ref) =>
   Layer.effect(
     Service,
     Effect.gen(function* () {
       const project = yield* Project.Service
-      const resolved = yield* project.resolve(ref.directory, options)
+      const resolved = yield* project.resolve(ref.directory)
       return Service.of({
         directory: ref.directory,
         workspaceID: ref.workspaceID,
@@ -31,9 +31,9 @@ const layer = (ref: Ref, options?: { readonly discovery?: boolean }) =>
     }),
   )
 
-export const boundNode = (ref: Ref, options?: { readonly discovery?: boolean }) =>
+export const boundNode = (ref: Ref) =>
   makeLocationNode({
     service: Service,
-    layer: layer(ref, options),
+    layer: layer(ref),
     deps: [Project.node],
   })

packages/core/src/mcp/index.ts

@@ -45,8 +45,6 @@ export const ResourceTemplate = Mcp.ResourceTemplate
 export type ResourceTemplate = Mcp.ResourceTemplate
 export const ResourceCatalog = Mcp.ResourceCatalog
 export type ResourceCatalog = Mcp.ResourceCatalog
-export const ResourceContentPart = Mcp.ResourceContentPart
-export type ResourceContentPart = Mcp.ResourceContentPart
 export const ResourceContent = Mcp.ResourceContent
 export type ResourceContent = Mcp.ResourceContent
 

packages/core/src/permission.ts

@@ -156,8 +156,7 @@ const layer = Layer.effect(
     })
 
     const configured = Effect.fnUntraced(function* (sessionID: SessionSchema.ID, agentID?: Agent.ID) {
-      const session = yield* sessions.get(sessionID)
-      if (!session) return yield* new SessionErrors.NotFoundError({ sessionID })
+      const session = yield* sessions.require(sessionID)
       const agent = yield* agents.resolve(agentID ?? session.agent)
       return merge(agent?.permissions ?? missingAgentPermissions, session.permissions ?? [])
     })

packages/core/src/project.ts

@@ -65,7 +65,7 @@ export interface Interface {
   /** Records Project activity for recency ordering, at most once per minute per Project. */
   readonly activate: (projectID: ID) => Effect.Effect<void>
   /** Resolves and persists the owning Project. */
-  readonly resolve: (input: AbsolutePath, options?: { readonly discovery?: boolean }) => Effect.Effect<Resolved>
+  readonly resolve: (input: AbsolutePath) => Effect.Effect<Resolved>
 }
 
 export class Service extends Context.Service<Service, Interface>()("@opencode/Project") {}
@@ -334,10 +334,7 @@ const layer = Layer.effect(
       }
     })
 
-    const resolve = Effect.fn("Project.resolve")(function* (
-      input: AbsolutePath,
-      _options?: { readonly discovery?: boolean },
-    ) {
+    const resolve = Effect.fn("Project.resolve")(function* (input: AbsolutePath) {
       const directory = AbsolutePath.make(yield* fs.resolve(input))
       const native = yield* fs.up({ targets: [".git", ".hg"], start: directory, mode: "first" }).pipe(
         Effect.map((matches) => matches[0]),

packages/core/src/pty.ts

@@ -6,7 +6,6 @@ import { Context, Effect, Layer, Schema, Types } from "effect"
 import { Pty } from "@opencode/schema/pty"
 import { Bus } from "./bus.js"
 import { Location } from "./location.js"
-import { PtyID } from "./pty/schema.js"
 import { ShellSelect } from "./shell/select.js"
 import { lazy } from "./util/lazy.js"
 
@@ -35,6 +34,9 @@ type Active = {
   listeners: Disp[]
 }
 
+export const ID = Pty.ID
+export type ID = Pty.ID
+
 export const Info = Pty.Info
 export type Info = Types.DeepMutable<typeof Info.Type>
 
@@ -69,21 +71,21 @@ export type Attachment = {
 }
 
 export class NotFoundError extends Schema.TaggedError<NotFoundError>()("Pty.NotFoundError", {
-  ptyID: PtyID,
+  ptyID: ID,
 }) {}
 
 export class ExitedError extends Schema.TaggedError<ExitedError>()("Pty.ExitedError", {
-  ptyID: PtyID,
+  ptyID: ID,
 }) {}
 
 export interface Interface {
   readonly list: () => Effect.Effect<Info[]>
-  readonly get: (id: PtyID) => Effect.Effect<Info, NotFoundError>
+  readonly get: (id: ID) => Effect.Effect<Info, NotFoundError>
   readonly create: (input: CreateInput) => Effect.Effect<Info>
-  readonly update: (id: PtyID, input: UpdateInput) => Effect.Effect<Info, NotFoundError>
-  readonly remove: (id: PtyID) => Effect.Effect<void, NotFoundError>
-  readonly write: (id: PtyID, data: string) => Effect.Effect<void, NotFoundError>
-  readonly attach: (id: PtyID, input: AttachInput) => Effect.Effect<Attachment, NotFoundError | ExitedError>
+  readonly update: (id: ID, input: UpdateInput) => Effect.Effect<Info, NotFoundError>
+  readonly remove: (id: ID) => Effect.Effect<void, NotFoundError>
+  readonly write: (id: ID, data: string) => Effect.Effect<void, NotFoundError>
+  readonly attach: (id: ID, input: AttachInput) => Effect.Effect<Attachment, NotFoundError | ExitedError>
 }
 
 export class Service extends Context.Service<Service, Interface>()("@opencode/Pty") {}
@@ -96,8 +98,8 @@ const layer = Layer.effect(
     const shell = yield* ShellSelect.Service
     const context = yield* Effect.context()
     const runFork = Effect.runForkWith(context)
-    const sessions = new Map<PtyID, Active>()
-    const exitOrder: PtyID[] = []
+    const sessions = new Map<ID, Active>()
+    const exitOrder: ID[] = []
 
     function notifyEnd(session: Active, event: { exitCode?: number }) {
       for (const subscriber of session.subscribers.values()) {
@@ -131,13 +133,13 @@ const layer = Layer.effect(
       }),
     )
 
-    const requireSession = Effect.fn("Pty.requireSession")(function* (id: PtyID) {
+    const requireSession = Effect.fn("Pty.requireSession")(function* (id: ID) {
       const session = sessions.get(id)
       if (!session) return yield* new NotFoundError({ ptyID: id })
       return session
     })
 
-    const removeSession = Effect.fnUntraced(function* (id: PtyID) {
+    const removeSession = Effect.fnUntraced(function* (id: ID) {
       const session = sessions.get(id)
       if (!session) return
       sessions.delete(id)
@@ -148,7 +150,7 @@ const layer = Layer.effect(
       yield* bus.publish(Pty.Event.Deleted, { id: session.info.id })
     })
 
-    const remove = Effect.fn("Pty.remove")(function* (id: PtyID) {
+    const remove = Effect.fn("Pty.remove")(function* (id: ID) {
       yield* requireSession(id)
       yield* removeSession(id)
     })
@@ -157,12 +159,12 @@ const layer = Layer.effect(
       return Array.from(sessions.values()).map((session) => session.info)
     })
 
-    const get = Effect.fn("Pty.get")(function* (id: PtyID) {
+    const get = Effect.fn("Pty.get")(function* (id: ID) {
       return (yield* requireSession(id)).info
     })
 
     const create = Effect.fn("Pty.create")(function* (input: CreateInput) {
-      const id = PtyID.ascending()
+      const id = ID.ascending()
       const command = input.command || (yield* shell.resolve({ priority: "config" }))
       const args = ShellSelect.login(command) ? [...(input.args ?? []), "-l"] : [...(input.args ?? [])]
       const cwd = input.cwd || location.directory
@@ -242,7 +244,7 @@ const layer = Layer.effect(
       return info
     })
 
-    const update = Effect.fn("Pty.update")(function* (id: PtyID, input: UpdateInput) {
+    const update = Effect.fn("Pty.update")(function* (id: ID, input: UpdateInput) {
       const session = yield* requireSession(id)
       if (input.title) session.info.title = input.title
       if (input.size && session.info.status === "running") session.process.resize(input.size.cols, input.size.rows)
@@ -250,12 +252,12 @@ const layer = Layer.effect(
       return session.info
     })
 
-    const write = Effect.fn("Pty.write")(function* (id: PtyID, data: string) {
+    const write = Effect.fn("Pty.write")(function* (id: ID, data: string) {
       const session = yield* requireSession(id)
       if (session.info.status === "running") session.process.write(data)
     })
 
-    const attach = Effect.fn("Pty.attach")(function* (id: PtyID, input: AttachInput) {
+    const attach = Effect.fn("Pty.attach")(function* (id: ID, input: AttachInput) {
       const session = yield* requireSession(id)
       if (session.info.status !== "running") return yield* new ExitedError({ ptyID: id })
       yield* Effect.logInfo("client attached to session", { id, directory: location.directory })

packages/core/src/pty/schema.ts

@@ -1 +0,0 @@
-export { ID as PtyID } from "@opencode/schema/pty"

packages/core/src/pty/ticket.ts

@@ -2,7 +2,7 @@ export * as PtyTicket from "./ticket.js"
 
 import type { Workspace } from "@opencode/schema/workspace"
 import { PtyTicket } from "@opencode/schema/pty-ticket"
-import { PtyID } from "./schema.js"
+import type { Pty } from "@opencode/schema/pty"
 import { Cache, Context, Duration, Effect, Layer } from "effect"
 import { makeGlobalNode } from "@opencode/util/effect/app-node"
 
@@ -12,7 +12,7 @@ const CAPACITY = 10_000
 export const ConnectToken = PtyTicket.ConnectToken
 
 export type Scope = {
-  readonly ptyID: PtyID
+  readonly ptyID: Pty.ID
   readonly directory?: string
   readonly workspaceID?: Workspace.ID
 }

packages/core/src/session/error.ts

@@ -50,15 +50,6 @@ export class StepFailedError extends Schema.TaggedError<StepFailedError>()("Sess
   }
 }
 
-export class UserInterruptedError extends Schema.TaggedError<UserInterruptedError>()(
-  "Session.UserInterruptedError",
-  {},
-) {
-  override get message() {
-    return "Session interrupted by user"
-  }
-}
-
 export class PromptConflictError extends Schema.TaggedError<PromptConflictError>()("Session.PromptConflictError", {
   sessionID: SessionSchema.ID,
   messageID: SessionMessage.ID,

packages/core/src/session/execution.ts

@@ -12,7 +12,6 @@ import { SessionRunner } from "./runner/index.js"
 import { SessionSchema } from "./schema.js"
 import { SessionStore } from "./store.js"
 import { toSessionError } from "./to-session-error.js"
-import { UserInterruptedError } from "./error.js"
 import { SessionInbox } from "./inbox.js"
 
 export interface Interface {
@@ -51,9 +50,7 @@ type InterruptReason = "user" | "shutdown" | "inactivity"
 export function terminal(exit: Exit.Exit<void, SessionRunner.RunError>, reason?: InterruptReason) {
   if (Exit.isSuccess(exit)) return { type: "succeeded" as const }
   if (Cause.hasInterrupts(exit.cause)) return { type: "interrupted" as const, reason: reason ?? "shutdown" }
-  const failure = Cause.squash(exit.cause)
-  if (failure instanceof UserInterruptedError) return { type: "interrupted" as const, reason: "user" as const }
-  return { type: "failed" as const, error: toSessionError(failure) }
+  return { type: "failed" as const, error: toSessionError(Cause.squash(exit.cause)) }
 }
 
 /** Process-local execution: drains run in this process using the selected instance. */

packages/core/src/session/history.ts

@@ -1,8 +1,9 @@
 import { and, asc, desc, eq, gte, or, sql } from "drizzle-orm"
-import { Effect, Schema } from "effect"
+import { Effect } from "effect"
 import { Database } from "../database/database.js"
 import { MessageDecodeError } from "./error.js"
 import { SessionMessage } from "./message.js"
+import { SessionMessageRow } from "./message-row.js"
 import { SessionSchema } from "./schema.js"
 import { Instructions } from "../instructions/index.js"
 import { InstructionState } from "./instruction-state.js"
@@ -11,7 +12,6 @@ import { SessionMessageTable } from "./sql.js"
 
 type DatabaseService = Database.Interface["db"]
 
-const decode = Schema.decodeUnknownEffect(SessionMessage.Info)
 
 /**
  * Which completed compactions bound a history read. Local summaries always do. Native
@@ -60,7 +60,7 @@ export const latestCompaction = Effect.fnUntraced(function* (
 })
 
 export const decodeMessageRow = (row: typeof SessionMessageTable.$inferSelect) =>
-  decode({ ...row.data, id: row.id, type: row.type }).pipe(
+  SessionMessageRow.decodeEffect(row).pipe(
     Effect.tap((message) =>
       SessionProviderContext.isCheckpoint(message)
         ? SessionProviderContext.validate(message.providerContext)

packages/core/src/session/inbox.ts

@@ -21,6 +21,7 @@ import { Bus } from "../bus.js"
 import { KeyedMutex } from "../effect/keyed-mutex.js"
 import { SessionEvent } from "./event.js"
 import { SessionMessage } from "./message.js"
+import { SessionMessageRow } from "./message-row.js"
 import { SessionSchema } from "./schema.js"
 import { SessionInboxTable, SessionMessageTable } from "./sql.js"
 
@@ -55,7 +56,6 @@ const decodeCompaction = Schema.decodeUnknownSync(CompactionPayload)
 const encodeCompaction = Schema.encodeSync(CompactionPayload)
 const decodeMove = Schema.decodeUnknownSync(MovePayload)
 const encodeMove = Schema.encodeSync(MovePayload)
-const decodeMessage = Schema.decodeUnknownSync(SessionMessage.Info)
 const inboxLocks = KeyedMutex.makeUnsafe<SessionSchema.ID>()
 type PendingRef = { readonly id: SessionMessage.ID; readonly sessionID: SessionSchema.ID }
 
@@ -125,7 +125,7 @@ const promotedFromMessage = Effect.fn("SessionInbox.promotedFromMessage")(functi
   if (row === undefined) return undefined
   if (row.session_id !== sessionID || (row.type !== "user" && row.type !== "synthetic"))
     return yield* new LifecycleConflict({ id })
-  const message = decodeMessage({ ...row.data, id: row.id, type: row.type })
+  const message = SessionMessageRow.decode(row)
   const base = { id, sessionID, time: { created: message.time.created }, delivery }
   if (message.type === "user")
     return User.make({

packages/core/src/session/message-row.ts

@@ -0,0 +1,25 @@
+export * as SessionMessageRow from "./message-row.js"
+
+import { Schema } from "effect"
+import { SessionMessage } from "./message.js"
+import type { SessionMessageTable } from "./sql.js"
+
+type Row = Pick<typeof SessionMessageTable.$inferSelect, "id" | "type" | "data">
+
+const decodeSync = Schema.decodeUnknownSync(SessionMessage.Info)
+const decodeUnknown = Schema.decodeUnknownEffect(SessionMessage.Info)
+const encodeSync = Schema.encodeSync(SessionMessage.Info)
+
+const fields = (row: Row) => ({ ...row.data, id: row.id, type: row.type })
+
+/** Decodes a stored message row, throwing when the stored data is invalid. */
+export const decode = (row: Row) => decodeSync(fields(row))
+
+export const decodeEffect = (row: Row) => decodeUnknown(fields(row))
+
+/** Splits a message into its row identity, type, and JSON data columns. */
+export const encode = (message: SessionMessage.Info) => {
+  const encoded = encodeSync(message)
+  const { id, type, ...data } = encoded
+  return { id: SessionMessage.ID.make(id), type, data }
+}

packages/core/src/session/move.ts

@@ -65,11 +65,7 @@ const layer = Layer.effect(
     const database = yield* Database.Service
     const bus = yield* Bus.Service
 
-    const get = Effect.fn("SessionMove.get")(function* (sessionID: Session.ID) {
-      const session = yield* store.get(sessionID)
-      if (!session) return yield* new NotFoundError({ sessionID })
-      return session
-    })
+    const get = store.require
 
     const resolveDestination = Effect.fn("SessionMove.resolveDestination")(function* (
       session: Session.Info,

packages/core/src/session/projector.ts

@@ -10,6 +10,7 @@ import { Agent } from "@opencode/schema/agent"
 import { Model } from "@opencode/schema/model"
 import { SessionEvent } from "./event.js"
 import { SessionMessage } from "./message.js"
+import { SessionMessageRow } from "./message-row.js"
 import { SessionMessageUpdater } from "./message-updater.js"
 import { SessionInbox } from "./inbox.js"
 import { Workspace } from "@opencode/schema/workspace"
@@ -31,9 +32,6 @@ type MessageEvent = Exclude<
   typeof SessionEvent.Forked.Type | typeof SessionEvent.Deleted.Type
 >
 
-const decodeMessage = Schema.decodeUnknownSync(SessionMessage.Info)
-const encodeMessage = Schema.encodeSync(SessionMessage.Info)
-
 export class SessionAlreadyProjected extends Error {}
 
 type Usage = {
@@ -227,17 +225,14 @@ const projectFork = Effect.fn("SessionProjector.projectFork")(function* (
 
 function run(db: DatabaseService, event: MessageEvent) {
   return Effect.gen(function* () {
-    const decodeRow = (row: typeof SessionMessageTable.$inferSelect) =>
-      decodeMessage({ ...row.data, id: row.id, type: row.type })
     const updateMessage = (message: SessionMessage.Info) => {
-      const encoded = encodeMessage(message)
-      const { id, type, ...data } = encoded
+      const row = SessionMessageRow.encode(message)
       return db
         .update(SessionMessageTable)
-        .set({ type, time_created: DateTime.toEpochMillis(message.time.created), data })
+        .set({ type: row.type, time_created: DateTime.toEpochMillis(message.time.created), data: row.data })
         .where(
           and(
-            eq(SessionMessageTable.id, SessionMessage.ID.make(id)),
+            eq(SessionMessageTable.id, row.id),
             eq(SessionMessageTable.session_id, event.data.sessionID),
           ),
         )
@@ -309,7 +304,7 @@ function run(db: DatabaseService, event: MessageEvent) {
             .get()
             .pipe(Effect.orDie)
           if (!row) return
-          const message = decodeRow(row)
+          const message = SessionMessageRow.decode(row)
           return message.type === "assistant" && !message.time.completed ? message : undefined
         })
       },
@@ -328,7 +323,7 @@ function run(db: DatabaseService, event: MessageEvent) {
             .get()
             .pipe(Effect.orDie)
           if (!row) return
-          const message = decodeRow(row)
+          const message = SessionMessageRow.decode(row)
           return message.type === "assistant" ? message : undefined
         })
       },
@@ -349,7 +344,7 @@ function run(db: DatabaseService, event: MessageEvent) {
             .get()
             .pipe(Effect.orDie)
           if (!row) return
-          const message = decodeRow(row)
+          const message = SessionMessageRow.decode(row)
           return message.type === "shell" ? message : undefined
         })
       },
@@ -370,7 +365,7 @@ function run(db: DatabaseService, event: MessageEvent) {
             .get()
             .pipe(Effect.orDie)
           if (!row) return
-          const message = decodeRow(row)
+          const message = SessionMessageRow.decode(row)
           return message.type === "compaction" ? message : undefined
         })
       },
@@ -384,17 +379,16 @@ function run(db: DatabaseService, event: MessageEvent) {
 }
 
 function insertMessage(db: DatabaseService, event: SessionEvent.DurableEvent, message: SessionMessage.Info) {
-  const encoded = encodeMessage(message)
-  const { id, type, ...data } = encoded
+  const row = SessionMessageRow.encode(message)
   return db
     .insert(SessionMessageTable)
     .values({
-      id: SessionMessage.ID.make(id),
+      id: row.id,
       session_id: event.data.sessionID,
-      type,
+      type: row.type,
       seq: event.durable.seq,
       time_created: DateTime.toEpochMillis(message.time.created),
-      data,
+      data: row.data,
     })
     .run()
     .pipe(Effect.orDie)

packages/core/src/session/revert.ts

@@ -1,7 +1,7 @@
 export * as SessionRevert from "./revert.js"
 
 import { and, asc, eq, gt } from "drizzle-orm"
-import { Effect, Schema } from "effect"
+import { Effect } from "effect"
 import { Database } from "../database/database.js"
 import { Bus } from "../bus.js"
 import { Instance } from "../instance/service.js"
@@ -10,6 +10,7 @@ import { Snapshot } from "../snapshot.js"
 import { SessionEvent } from "./event.js"
 import { MessageNotFoundError } from "./error.js"
 import { SessionMessage } from "./message.js"
+import { SessionMessageRow } from "./message-row.js"
 import { SessionSchema } from "./schema.js"
 import { SessionMessageTable } from "./sql.js"
 
@@ -104,10 +105,9 @@ const plan = Effect.fn("SessionRevert.plan")(function* (db: Database.Interface["
     .orderBy(asc(SessionMessageTable.seq))
     .all()
     .pipe(Effect.orDie)
-  const decode = Schema.decodeUnknownEffect(SessionMessage.Info)
   const files = new Map<RelativePath, Snapshot.ID>()
   for (const row of rows) {
-    const message = yield* decode({ ...row.data, id: row.id, type: row.type }).pipe(Effect.orDie)
+    const message = yield* SessionMessageRow.decodeEffect(row).pipe(Effect.orDie)
     if (message.type !== "assistant" || !message.snapshot?.start) continue
     for (const file of message.snapshot.files ?? [])
       if (!files.has(file)) files.set(file, Snapshot.ID.make(message.snapshot.start))

packages/core/src/session/runner/index.ts

@@ -4,7 +4,7 @@ import type { AIError } from "@opencode/ai"
 import { Context, Data, Effect } from "effect"
 import { SessionSchema } from "../schema.js"
 import type { Promotable } from "../inbox.js"
-import type { AgentNotFoundError, MessageDecodeError, StepFailedError, UserInterruptedError } from "../error.js"
+import type { AgentNotFoundError, MessageDecodeError, StepFailedError } from "../error.js"
 import { SessionRunnerModel } from "./model.js"
 import type { Instructions } from "../../instructions/index.js"
 
@@ -14,7 +14,6 @@ export type RunError =
   | MessageDecodeError
   | AgentNotFoundError
   | StepFailedError
-  | UserInterruptedError
   | Instructions.InitializationBlocked
 
 export type Continuation = { readonly step: number }

packages/core/src/session/runner/model.ts

@@ -29,19 +29,6 @@ export class ModelUnavailableError extends Schema.TaggedError<ModelUnavailableEr
     return `Model unavailable: ${this.providerID}/${this.modelID}`
   }
 }
-export const VariantUnavailableError = ModelResolver.VariantUnavailableError
-export type VariantUnavailableError = ModelResolver.VariantUnavailableError
-export const UnsupportedPackageError = ModelResolver.UnsupportedPackageError
-export type UnsupportedPackageError = ModelResolver.UnsupportedPackageError
-export const ModelConfigurationError = ModelResolver.ModelConfigurationError
-export type ModelConfigurationError = ModelResolver.ModelConfigurationError
-export const ModelInitializationError = ModelResolver.ModelInitializationError
-export type ModelInitializationError = ModelResolver.ModelInitializationError
-export const UnresolvedProviderVariablesError = ModelResolver.UnresolvedProviderVariablesError
-export type UnresolvedProviderVariablesError = ModelResolver.UnresolvedProviderVariablesError
-export const UnsupportedCompactionError = ModelResolver.UnsupportedCompactionError
-export type UnsupportedCompactionError = ModelResolver.UnsupportedCompactionError
-
 export type Error = ModelNotSelectedError | ModelUnavailableError | ModelResolver.Error
 export type Resolved = ModelResolver.Resolved
 

packages/core/src/session/runner/retry.ts

@@ -1,6 +1,6 @@
 export * as SessionRunnerRetry from "./retry.js"
 
-import { AIError, isContextOverflowFailure } from "@opencode/ai"
+import { AIError, isRetryable } from "@opencode/ai"
 import { Agent } from "@opencode/schema/agent"
 import { Model } from "@opencode/schema/model"
 import { SessionError } from "@opencode/schema/session-error"
@@ -10,7 +10,8 @@ import type { PluginHooks } from "../../plugin/hooks.js"
 import { SessionEvent } from "../event.js"
 import { SessionMessage } from "../message.js"
 import { SessionSchema } from "../schema.js"
-import { toSessionError } from "../to-session-error.js"
+
+export { isRetryable }
 
 interface Input {
   readonly cause: AIError
@@ -27,43 +28,6 @@ export interface Decision {
   readonly delay: number
 }
 
-export function isRetryable(error: AIError) {
-  const override = error.reason.http?.headers["x-should-retry"]
-  if (override === "true") return true
-  if (override === "false") return false
-  switch (error.reason._tag) {
-    case "RateLimit":
-    case "ProviderInternal":
-      return true
-    // A WebSocket acknowledgment marks delivery accepted before model output may exist.
-    // Read failures can still recover; the Step chooses retry versus continuation from durable output.
-    case "Transport":
-      return (
-        error.reason.delivery !== "rejected" &&
-        (error.reason.delivery !== "accepted" || error.reason.operation === "read")
-      )
-    case "InvalidProviderOutput":
-      return error.reason.classification === "incomplete-stream"
-    // Unrecognized failures retry: classification records affirmative
-    // deterministic evidence, and transient failures are exactly the ones
-    // that arrive in shapes no classifier anticipates.
-    case "UnknownProvider":
-      return true
-    case "Authentication":
-    case "QuotaExceeded":
-    case "ContentPolicy":
-    case "InvalidRequest":
-    case "UnsupportedOperation":
-    case "NoRoute":
-    case "Timeout":
-      return false
-    default: {
-      const exhaustive: never = error.reason
-      return exhaustive
-    }
-  }
-}
-
 /** Bound provider-requested delays so a hostile or buggy retry-after cannot stall a session for hours. */
 const RETRY_AFTER_MAX = Duration.toMillis("15 minutes")
 
@@ -119,24 +83,6 @@ export const policy = (sessionID: SessionSchema.ID) =>
       })
   })
 
-/**
- * Retries one auxiliary request's transient failures under a shared `policy` allowance, letting the
- * session retry hook adjust each decision. Context overflow is never transient: callers recover it.
- */
-export const transient =
-  (decide: Effect.Success<ReturnType<typeof policy>>, input: Pick<Input, "agent" | "model" | "hook">) =>
-  <A, R>(effect: Effect.Effect<A, AIError, R>) =>
-    Effect.retry(effect, {
-      while: (cause) =>
-        Effect.gen(function* () {
-          if (isContextOverflowFailure(cause)) return false
-          const decision = yield* decide({ ...input, cause, error: toSessionError(cause), retry: isRetryable(cause) })
-          if (!decision.retry) return false
-          yield* Effect.sleep(decision.delay)
-          return true
-        }),
-    })
-
 export const make = (bus: Bus.Interface, sessionID: SessionSchema.ID) =>
   Effect.gen(function* () {
     const decide = yield* policy(sessionID)

packages/core/src/session/session.ts

@@ -16,7 +16,6 @@ import {
   CompactionConflictError,
   InboxConflictError,
   MessageNotFoundError,
-  NotFoundError,
   PromptConflictError,
   SyntheticConflictError,
 } from "./error.js"
@@ -50,11 +49,7 @@ export const make = Effect.fn("Session.make")(function* () {
   const fs = yield* FSUtil.Service
   const scope = yield* Scope.Scope
 
-  const get = Effect.fn("Session.get")(function* (sessionID: SessionSchema.ID) {
-    const session = yield* store.get(sessionID)
-    if (!session) return yield* new NotFoundError({ sessionID })
-    return session
-  })
+  const get = store.require
   const message = Effect.fn("Session.message")(function* (sessionID: SessionSchema.ID, messageID: SessionMessage.ID) {
     const stored = yield* store.message(messageID)
     return stored?.sessionID === sessionID ? stored.message : undefined

packages/core/src/session/store.ts

@@ -8,7 +8,7 @@ import { AbsolutePath, PositiveInt, RelativePath } from "@opencode/schema/schema
 import { Database } from "../database/database.js"
 import { makeGlobalNode } from "@opencode/util/effect/app-node"
 import { SessionHistory } from "./history.js"
-import { MessageDecodeError } from "./error.js"
+import { MessageDecodeError, NotFoundError } from "./error.js"
 import { SessionMessage } from "./message.js"
 import { Session } from "@opencode/schema/session"
 import { SessionMessageTable, SessionTable } from "./sql.js"
@@ -52,6 +52,7 @@ export type MessagesInput = {
 
 export interface Interface {
   readonly get: (sessionID: Session.ID) => Effect.Effect<Session.Info | undefined>
+  readonly require: (sessionID: Session.ID) => Effect.Effect<Session.Info, NotFoundError>
   readonly list: (input?: ListInput) => Effect.Effect<Session.Info[]>
   readonly messages: (input: MessagesInput) => Effect.Effect<SessionMessage.Info[], MessageDecodeError>
   readonly context: (sessionID: Session.ID) => Effect.Effect<SessionMessage.Info[], MessageDecodeError>
@@ -91,10 +92,17 @@ const layer = Layer.effect(
   Effect.gen(function* () {
     const { db } = yield* Database.Service
 
+    const get = Effect.fnUntraced(function* (sessionID: Session.ID) {
+      const row = yield* db.select().from(SessionTable).where(eq(SessionTable.id, sessionID)).get().pipe(Effect.orDie)
+      return row ? fromRow(row) : undefined
+    })
+
     return Service.of({
-      get: Effect.fnUntraced(function* (sessionID) {
-        const row = yield* db.select().from(SessionTable).where(eq(SessionTable.id, sessionID)).get().pipe(Effect.orDie)
-        return row ? fromRow(row) : undefined
+      get,
+      require: Effect.fn("SessionStore.require")(function* (sessionID) {
+        const session = yield* get(sessionID)
+        if (!session) return yield* new NotFoundError({ sessionID })
+        return session
       }),
       list: Effect.fn("SessionStore.list")(function* (input = {}) {
         const direction = input.anchor?.direction ?? "next"

packages/core/src/session/to-session-error.ts

@@ -3,7 +3,8 @@ import { Tool } from "@opencode/schema/tool"
 import { SessionError } from "@opencode/schema/session-error"
 import { Permission } from "../permission.js"
 import { Integration } from "../integration.js"
-import { AgentNotFoundError, StepFailedError, UserInterruptedError } from "./error.js"
+import { AgentNotFoundError, StepFailedError } from "./error.js"
+import { ModelResolver } from "../model-resolver.js"
 import { SessionRunnerModel } from "./runner/model.js"
 
 export function toSessionError(cause: unknown): SessionError.Error {
@@ -48,18 +49,17 @@ export function toSessionError(cause: unknown): SessionError.Error {
     return unwrapped.message === "" ? { ...unwrapped, type: "tool.execution", message: cause.message } : unwrapped
   }
   if (cause instanceof StepFailedError) return cause.error
-  if (cause instanceof SessionRunnerModel.UnsupportedCompactionError)
+  if (cause instanceof ModelResolver.UnsupportedCompactionError)
     return { type: "provider.unsupported-operation", message: cause.message }
   if (cause instanceof AgentNotFoundError) return { type: "unknown", message: cause.message }
-  if (cause instanceof UserInterruptedError) return { type: "aborted", message: cause.message }
   if (
     cause instanceof SessionRunnerModel.ModelNotSelectedError ||
     cause instanceof SessionRunnerModel.ModelUnavailableError ||
-    cause instanceof SessionRunnerModel.VariantUnavailableError ||
-    cause instanceof SessionRunnerModel.UnsupportedPackageError ||
-    cause instanceof SessionRunnerModel.ModelConfigurationError ||
-    cause instanceof SessionRunnerModel.ModelInitializationError ||
-    cause instanceof SessionRunnerModel.UnresolvedProviderVariablesError
+    cause instanceof ModelResolver.VariantUnavailableError ||
+    cause instanceof ModelResolver.UnsupportedPackageError ||
+    cause instanceof ModelResolver.ModelConfigurationError ||
+    cause instanceof ModelResolver.ModelInitializationError ||
+    cause instanceof ModelResolver.UnresolvedProviderVariablesError
   )
     return { type: "provider.no-route", message: cause.message }
   if (cause instanceof Integration.AuthorizationError) return { type: "provider.auth", message: cause.message }

packages/core/src/session/transfer.ts

@@ -19,6 +19,7 @@ import { Session } from "../session.js"
 import { Slug } from "../util/slug.js"
 import { SessionEvent } from "./event.js"
 import { SessionMessage } from "./message.js"
+import { SessionMessageRow } from "./message-row.js"
 import { SessionProjector } from "./projector.js"
 import { SessionMessageTable, SessionTable } from "./sql.js"
 
@@ -51,7 +52,6 @@ const layer = Layer.effect(
     const { db } = yield* Database.Service
     const projects = yield* Project.Service
     const sessions = yield* Session.Service
-    const encodeMessage = Schema.encodeSync(SessionMessage.Info)
 
     return Service.of({
       export: Effect.fn("SessionTransfer.export")(function* (input) {
@@ -75,15 +75,14 @@ const layer = Layer.effect(
         yield* upsertProject(db, project).pipe(Effect.orDie)
         const importedAt = yield* Clock.currentTimeMillis
         const messages = input.data.messages.filter(isSettled).map((message, index) => {
-          const encoded = encodeMessage(message)
-          const { id: _, type, ...data } = encoded
+          const row = SessionMessageRow.encode(message)
           return {
-            id: message.id,
+            id: row.id,
             session_id: sessionID,
-            type,
+            type: row.type,
             seq: index + 1,
             time_created: DateTime.toEpochMillis(message.time.created),
-            data,
+            data: row.data,
           }
         })
         yield* bus

packages/core/src/snapshot.ts

@@ -3,7 +3,7 @@ export * as Snapshot from "./snapshot.js"
 import { makeLocationNode } from "@opencode/util/effect/app-node"
 import path from "path"
 import { Context, Effect, Fiber, Layer, Schema, Scope } from "effect"
-import { File } from "./file.js"
+import { FileDiff } from "@opencode/schema/file-diff"
 import { FSUtil } from "@opencode/util/fs-util"
 import { Git } from "./git.js"
 import { Global } from "@opencode/util/global"
@@ -58,7 +58,7 @@ export interface Interface extends State.Transformable<Editor> {
    * Generate structured per-file diffs between two captured trees. `context`
    * controls unchanged lines around each unified diff hunk.
    */
-  readonly diff: (input: DiffInput) => Effect.Effect<readonly File.Diff[], Error>
+  readonly diff: (input: DiffInput) => Effect.Effect<readonly FileDiff.Info[], Error>
 
   /**
    * Restore selected project-relative paths from their associated trees. A path

packages/core/src/util/array.ts

@@ -1,10 +0,0 @@
-export function findLast<T>(
-  items: readonly T[],
-  predicate: (item: T, index: number, items: readonly T[]) => boolean,
-): T | undefined {
-  for (let i = items.length - 1; i >= 0; i -= 1) {
-    const item = items[i]
-    if (predicate(item, i, items)) return item
-  }
-  return undefined
-}

packages/core/src/util/process-lock-ffi.bun.ts

@@ -1,50 +0,0 @@
-import { dlopen, read, type Pointer } from "bun:ffi"
-import { existsSync } from "node:fs"
-
-export type LockResult =
-  | { readonly acquired: true }
-  | { readonly acquired: false; readonly held: true }
-  | { readonly acquired: false; readonly held: false; readonly code: number }
-
-const LOCK_EX = 2
-const LOCK_NB = 4
-const DARWIN_EWOULDBLOCK = 35
-const LINUX_EWOULDBLOCK = 11
-
-export function lockDarwin(fd: number): LockResult {
-  const library = dlopen("/usr/lib/libSystem.B.dylib", {
-    flock: { args: ["i32", "i32"], returns: "i32" },
-    __error: { args: [], returns: "ptr" },
-  })
-  try {
-    const result = library.symbols.flock(fd, LOCK_EX | LOCK_NB)
-    const code = result === 0 ? 0 : errorCode(library.symbols.__error())
-    if (result === 0) return { acquired: true }
-    if (code === DARWIN_EWOULDBLOCK) return { acquired: false, held: true }
-    return { acquired: false, held: false, code }
-  } finally {
-    library.close()
-  }
-}
-
-export function lockLinux(fd: number): LockResult {
-  const musl = `/lib/libc.musl-${process.arch === "arm64" ? "aarch64" : "x86_64"}.so.1`
-  const library = dlopen(existsSync(musl) ? musl : "libc.so.6", {
-    flock: { args: ["i32", "i32"], returns: "i32" },
-    __errno_location: { args: [], returns: "ptr" },
-  })
-  try {
-    const result = library.symbols.flock(fd, LOCK_EX | LOCK_NB)
-    const code = result === 0 ? 0 : errorCode(library.symbols.__errno_location())
-    if (result === 0) return { acquired: true }
-    if (code === LINUX_EWOULDBLOCK) return { acquired: false, held: true }
-    return { acquired: false, held: false, code }
-  } finally {
-    library.close()
-  }
-}
-
-function errorCode(pointer: Pointer | bigint | null) {
-  if (pointer === null) throw new Error("Failed to read process lock error code")
-  return read.i32(pointer, 0)
-}

packages/core/src/util/process-lock-ffi.node.ts

@@ -1,43 +0,0 @@
-import { dlopen, getInt32 } from "node:ffi"
-
-export type LockResult =
-  | { readonly acquired: true }
-  | { readonly acquired: false; readonly held: true }
-  | { readonly acquired: false; readonly held: false; readonly code: number }
-
-const LOCK_EX = 2
-const LOCK_NB = 4
-const DARWIN_EWOULDBLOCK = 35
-const LINUX_EWOULDBLOCK = 11
-
-export function lockDarwin(fd: number): LockResult {
-  const library = dlopen("/usr/lib/libSystem.B.dylib", {
-    flock: { arguments: ["int32", "int32"], return: "int32" },
-    __error: { arguments: [], return: "pointer" },
-  })
-  try {
-    const result = library.functions.flock(fd, LOCK_EX | LOCK_NB)
-    const code = result === 0 ? 0 : getInt32(library.functions.__error(), 0)
-    if (result === 0) return { acquired: true }
-    if (code === DARWIN_EWOULDBLOCK) return { acquired: false, held: true }
-    return { acquired: false, held: false, code }
-  } finally {
-    library.lib.close()
-  }
-}
-
-export function lockLinux(fd: number): LockResult {
-  const library = dlopen("libc.so.6", {
-    flock: { arguments: ["int32", "int32"], return: "int32" },
-    __errno_location: { arguments: [], return: "pointer" },
-  })
-  try {
-    const result = library.functions.flock(fd, LOCK_EX | LOCK_NB)
-    const code = result === 0 ? 0 : getInt32(library.functions.__errno_location(), 0)
-    if (result === 0) return { acquired: true }
-    if (code === LINUX_EWOULDBLOCK) return { acquired: false, held: true }
-    return { acquired: false, held: false, code }
-  } finally {
-    library.lib.close()
-  }
-}

packages/core/src/util/process-lock-ffi.workerd.ts

@@ -1,14 +0,0 @@
-export type LockResult =
-  | { readonly acquired: true }
-  | { readonly acquired: false; readonly held: true }
-  | { readonly acquired: false; readonly held: false; readonly code: number }
-
-// workerd has no FFI and no cross-process file locking; a Durable Object is
-// already single-threaded per instance, so nothing on this runtime should
-// reach these.
-const unavailable = (_fd: number): LockResult => {
-  throw new Error("Process locks are unavailable on the workerd runtime")
-}
-
-export const lockDarwin = unavailable
-export const lockLinux = unavailable

packages/core/src/util/process-lock.ts

@@ -1,131 +0,0 @@
-import { lockDarwin, lockLinux, type LockResult } from "#process-lock-ffi"
-import { closeSync, mkdirSync, openSync } from "node:fs"
-import { connect, createServer, type Server, type Socket } from "node:net"
-import path from "node:path"
-import { Effect, Schema } from "effect"
-import { Hash } from "@opencode/util/hash"
-
-export namespace ProcessLock {
-  export class HeldError extends Schema.TaggedError<HeldError>()("ProcessLockHeldError", {
-    file: Schema.String,
-  }) {
-    override get message() {
-      return `Process lock is already held: ${this.file}`
-    }
-  }
-
-  export class SystemError extends Schema.TaggedError<SystemError>()("ProcessLockSystemError", {
-    file: Schema.String,
-    operation: Schema.Literals(["open", "acquire"]),
-    code: Schema.String,
-  }) {
-    override get message() {
-      return `Process lock ${this.operation} failed for ${this.file}: ${this.code}`
-    }
-  }
-
-  export type LockError = HeldError | SystemError
-
-  const acquirePosix = Effect.fnUntraced(function* (file: string) {
-    const fd = yield* Effect.try({
-      try: () => {
-        mkdirSync(path.dirname(file), { recursive: true })
-        return openSync(file, "a+", 0o600)
-      },
-      catch: (cause) =>
-        new SystemError({
-          file,
-          operation: "open",
-          code: cause instanceof Error ? cause.message : String(cause),
-        }),
-    })
-    const result = yield* Effect.try({
-      try: () => lock(fd),
-      catch: (cause) =>
-        new SystemError({
-          file,
-          operation: "acquire",
-          code: cause instanceof Error ? cause.message : String(cause),
-        }),
-    }).pipe(
-      Effect.tapError(() =>
-        Effect.sync(() => {
-          closeSync(fd)
-        }),
-      ),
-    )
-    if (result.acquired) return fd
-    closeSync(fd)
-    return yield* result.held
-      ? new HeldError({ file })
-      : new SystemError({ file, operation: "acquire", code: String(result.code) })
-  })
-
-  export const acquire = Effect.fn("ProcessLock.acquire")(function* (file: string) {
-    if (process.platform === "win32") {
-      yield* Effect.acquireRelease(acquireWindows(file), closeWindows)
-      return
-    }
-    yield* Effect.acquireRelease(acquirePosix(file), (fd) =>
-      Effect.sync(() => {
-        closeSync(fd)
-      }),
-    )
-  })
-}
-
-function lock(fd: number): LockResult {
-  if (process.platform === "darwin") return lockDarwin(fd)
-  if (process.platform === "linux") return lockLinux(fd)
-  throw new Error(`Unsupported process lock platform: ${process.platform}`)
-}
-
-function acquireWindows(file: string) {
-  return Effect.callback<Server, ProcessLock.LockError>((resume) => {
-    const server = createServer()
-    let probe: Socket | undefined
-    const pipe = `\\\\.\\pipe\\opencode-process-lock-${Hash.sha256(path.resolve(file).toLowerCase())}`
-    const onError = (cause: NodeJS.ErrnoException) => {
-      server.off("listening", onListening)
-      probe = connect(pipe)
-      const onProbeError = () => {
-        probe?.off("connect", onConnect)
-        resume(
-          Effect.fail(
-            new ProcessLock.SystemError({
-              file,
-              operation: "acquire",
-              code: cause.code ?? cause.message,
-            }),
-          ),
-        )
-      }
-      const onConnect = () => {
-        probe?.off("error", onProbeError)
-        probe?.destroy()
-        resume(Effect.fail(new ProcessLock.HeldError({ file })))
-      }
-      probe.once("connect", onConnect)
-      probe.once("error", onProbeError)
-    }
-    const onListening = () => {
-      server.off("error", onError)
-      resume(Effect.succeed(server))
-    }
-    server.once("error", onError)
-    server.once("listening", onListening)
-    server.on("connection", (socket) => socket.destroy())
-    server.listen(pipe)
-    return Effect.sync(() => {
-      probe?.destroy()
-      server.close()
-    })
-  })
-}
-
-function closeWindows(server: Server) {
-  return Effect.callback<void>((resume) => {
-    if (!server.listening) return resume(Effect.void)
-    server.close((error) => resume(error ? Effect.die(error) : Effect.void))
-  })
-}

packages/core/test/fixture/process-lock-worker.ts

@@ -1,17 +0,0 @@
-import { ProcessLock } from "@opencode/core/util/process-lock"
-import { Effect, Schema } from "effect"
-import fs from "node:fs/promises"
-
-const input = Schema.decodeUnknownSync(
-  Schema.fromJsonString(Schema.Struct({ file: Schema.String, ready: Schema.String })),
-)(process.argv[2])
-
-await Effect.runPromise(
-  Effect.scoped(
-    Effect.gen(function* () {
-      yield* ProcessLock.acquire(input.file)
-      yield* Effect.promise(() => fs.writeFile(input.ready, String(process.pid)))
-      return yield* Effect.never
-    }),
-  ),
-)

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

@@ -5,13 +5,12 @@ import { LayerNode } from "@opencode/util/effect/layer-node"
 import { Bus } from "@opencode/core/bus"
 import { Location } from "@opencode/core/location"
 import { Pty } from "@opencode/core/pty"
-import { PtyID } from "@opencode/core/pty/schema"
 import { AbsolutePath } from "@opencode/core/schema"
 import { ShellSelect } from "@opencode/core/shell/select"
 import { location } from "../fixture/location"
 import { testEffect } from "../lib/effect"
 
-type PtyEvent = { type: "created" | "exited" | "deleted"; id: PtyID }
+type PtyEvent = { type: "created" | "exited" | "deleted"; id: Pty.ID }
 
 const locationLayer = Layer.succeed(
   Location.Service,
@@ -46,7 +45,7 @@ const createPty = Effect.fn("PtySessionTest.createPty")(function* (command: stri
   )
 })
 
-const waitForEvents = (events: Queue.Queue<PtyEvent>, id: PtyID, count: number) =>
+const waitForEvents = (events: Queue.Queue<PtyEvent>, id: Pty.ID, count: number) =>
   Effect.gen(function* () {
     const picked: Array<PtyEvent["type"]> = []
     while (picked.length < count) {
@@ -61,7 +60,7 @@ const waitForEvents = (events: Queue.Queue<PtyEvent>, id: PtyID, count: number)
     }),
   )
 
-const attachCollecting = Effect.fn("PtySessionTest.attachCollecting")(function* (id: PtyID, cursor?: number) {
+const attachCollecting = Effect.fn("PtySessionTest.attachCollecting")(function* (id: Pty.ID, cursor?: number) {
   const pty = yield* Pty.Service
   const output = yield* Queue.unbounded<string>()
   const ended = yield* Deferred.make<{ exitCode?: number }>()
@@ -90,7 +89,7 @@ describe("pty", () => {
   it.live("returns typed not found errors for missing sessions", () =>
     Effect.gen(function* () {
       const pty = yield* Pty.Service
-      const id = PtyID.make("pty_missing")
+      const id = Pty.ID.make("pty_missing")
 
       for (const result of [
         yield* pty.get(id).pipe(Effect.asVoid, Effect.exit),

packages/core/test/pty/ticket.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect } from "bun:test"
 import { Effect, Layer } from "effect"
 import { LayerNode } from "@opencode/util/effect/layer-node"
-import { PtyID } from "@opencode/core/pty/schema"
+import { Pty } from "@opencode/core/pty"
 import { PtyTicket } from "@opencode/core/pty/ticket"
 import { Workspace } from "@opencode/core/workspace"
 import { testEffect } from "../lib/effect"
@@ -17,7 +17,7 @@ describe("PTY websocket tickets", () => {
   it.live("consumes tickets once", () =>
     Effect.gen(function* () {
       const tickets = yield* PtyTicket.Service
-      const scope = { ptyID: PtyID.ascending(), directory: "/tmp/a" }
+      const scope = { ptyID: Pty.ID.ascending(), directory: "/tmp/a" }
       const issued = yield* tickets.issue(scope)
 
       expect(yield* tickets.consume({ ...scope, ticket: issued.ticket })).toBe(true)
@@ -28,7 +28,7 @@ describe("PTY websocket tickets", () => {
   it.live("rejects tickets scoped to a different request", () =>
     Effect.gen(function* () {
       const tickets = yield* PtyTicket.Service
-      const ptyID = PtyID.ascending()
+      const ptyID = Pty.ID.ascending()
       const issued = yield* tickets.issue({ ptyID, directory: "/tmp/a" })
 
       expect(yield* tickets.consume({ ptyID, directory: "/tmp/b", ticket: issued.ticket })).toBe(false)
@@ -39,7 +39,7 @@ describe("PTY websocket tickets", () => {
   itExpiring.live("rejects tickets after the TTL elapses", () =>
     Effect.gen(function* () {
       const tickets = yield* PtyTicket.Service
-      const ptyID = PtyID.ascending()
+      const ptyID = Pty.ID.ascending()
       const issued = yield* tickets.issue({ ptyID })
 
       yield* Effect.promise(() => new Promise((resolve) => setTimeout(resolve, 25)))
@@ -51,7 +51,7 @@ describe("PTY websocket tickets", () => {
   it.live("rejects tickets scoped to a different workspace", () =>
     Effect.gen(function* () {
       const tickets = yield* PtyTicket.Service
-      const ptyID = PtyID.ascending()
+      const ptyID = Pty.ID.ascending()
       const workspaceID = Workspace.ID.ascending()
       const issued = yield* tickets.issue({ ptyID, workspaceID })
 

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

@@ -15,7 +15,6 @@ import { AbsolutePath } from "@opencode/core/schema"
 import { Session } from "@opencode/core/session"
 import { SessionExecution } from "@opencode/core/session/execution"
 import { SessionRestart } from "@opencode/core/session/execution/restart"
-import { UserInterruptedError } from "@opencode/core/session/error"
 import { SessionEvent } from "@opencode/core/session/event"
 import { SessionInbox } from "@opencode/core/session/inbox"
 import { SessionMessage } from "@opencode/core/session/message"
@@ -50,10 +49,6 @@ describe("SessionExecution lifecycle", () => {
     const interrupted = Effect.runSyncExit(Effect.interrupt)
     expect(SessionExecution.terminal(interrupted)).toEqual({ type: "interrupted", reason: "shutdown" })
     expect(SessionExecution.terminal(interrupted, "user")).toEqual({ type: "interrupted", reason: "user" })
-    expect(SessionExecution.terminal(Exit.fail(new UserInterruptedError()))).toEqual({
-      type: "interrupted",
-      reason: "user",
-    })
   })
 
   it.effect("the sweep only lists claimed top-level Sessions", () =>

packages/core/test/util/process-lock.test.ts

@@ -1,71 +0,0 @@
-import { expect } from "bun:test"
-import { ProcessLock } from "@opencode/core/util/process-lock"
-import { Effect } from "effect"
-import fs from "node:fs/promises"
-import os from "node:os"
-import path from "node:path"
-import { it } from "../lib/effect"
-
-const worker = path.join(import.meta.dir, "../fixture/process-lock-worker.ts")
-
-it.live(
-  "releases ownership when the scope closes",
-  Effect.gen(function* () {
-    const root = yield* temp("opencode-process-lock-")
-    const file = path.join(root, "service.lock")
-    yield* Effect.scoped(ProcessLock.acquire(file))
-    yield* Effect.scoped(ProcessLock.acquire(file))
-  }),
-)
-
-it.live(
-  "releases ownership when the process dies",
-  Effect.gen(function* () {
-    const root = yield* temp("opencode-process-lock-death-")
-    const file = path.join(root, "service.lock")
-    const ready = path.join(root, "ready")
-    const child = yield* Effect.acquireRelease(
-      Effect.sync(() =>
-        Bun.spawn([process.execPath, worker, JSON.stringify({ file, ready })], {
-          stdout: "ignore",
-          stderr: "pipe",
-        }),
-      ),
-      (child) =>
-        Effect.promise(async () => {
-          kill(child)
-          await child.exited
-        }),
-    )
-    yield* Effect.promise(async () => {
-      for (let attempt = 0; attempt < 100 && !(await Bun.file(ready).exists()); attempt++) await Bun.sleep(20)
-    })
-    expect(yield* Effect.promise(() => Bun.file(ready).exists())).toBe(true)
-
-    const error = yield* Effect.scoped(ProcessLock.acquire(file)).pipe(Effect.flip)
-    expect(error._tag).toBe("ProcessLockHeldError")
-
-    if (process.platform !== "win32") {
-      process.kill(child.pid, "SIGSTOP")
-      const paused = yield* Effect.scoped(ProcessLock.acquire(file)).pipe(Effect.flip)
-      expect(paused._tag).toBe("ProcessLockHeldError")
-      process.kill(child.pid, "SIGCONT")
-    }
-
-    kill(child)
-    yield* Effect.promise(() => child.exited)
-    yield* Effect.scoped(ProcessLock.acquire(file))
-  }),
-)
-
-function temp(prefix: string) {
-  return Effect.acquireRelease(
-    Effect.promise(() => fs.mkdtemp(path.join(os.tmpdir(), prefix))),
-    (root) => Effect.promise(() => fs.rm(root, { recursive: true, force: true })),
-  )
-}
-
-function kill(child: Bun.Subprocess) {
-  if (process.platform === "win32") return child.kill()
-  return child.kill("SIGKILL")
-}

packages/server/src/workerd.ts

@@ -23,8 +23,8 @@ import type { ServerOptions } from "./options"
  *
  * - Database runs on the injected `DurableObjectStorage` SQLite.
  * - Watcher and fff are disabled through their existing option flags; pty, fff,
- *   shell-parser, photon, and process-lock native modules resolve to inert
- *   stubs under the `workerd` bundle condition.
+ *   shell-parser, and photon native modules resolve to inert stubs under the
+ *   `workerd` bundle condition.
  * - Bare locations use a typed no-execution-plane process spawner; FileSystem,
  *   FileSystemSearch, and Pty fail with a clear defect until a remote sandbox
  *   backs them; Snapshot and Vcs degrade to no-op results.

packages/tui/src/config/index.tsx

@@ -54,6 +54,9 @@ export const Plugin = Schema.Union([
   }),
 ])
 
+export const DiffSource = Schema.Union([Vcs.Mode, Schema.Literal("turn")])
+export type DiffSource = Schema.Schema.Type<typeof DiffSource>
+
 export const Cursor = Schema.Struct({
   style: Schema.optional(Schema.Literals(["block", "underline", "line", "default"])).annotate({
     description: "Cursor shape. Use 'default' to preserve the terminal setting",
@@ -108,8 +111,9 @@ export const Info = Schema.Struct({
   ).annotate({ description: "System notification and sound settings" }),
   diffs: Schema.optional(
     Schema.Struct({
-      source: Schema.optional(Vcs.Mode).annotate({
-        description: "Initial diff source; defaults to 'branch' (branch and uncommitted changes)",
+      source: Schema.optional(DiffSource).annotate({
+        description:
+          "Initial diff source; defaults to 'branch' (branch and uncommitted changes). 'turn' shows the session's last turn and falls back to 'branch' outside a session",
       }),
       wrap: Schema.optional(Schema.Literals(["word", "none"])).annotate({
         description: "Line wrapping behavior in diff output",

packages/tui/src/feature-plugins/prompt/btw.tsx

@@ -130,8 +130,8 @@ export function Answer(props: {
         <text attributes={TextAttributes.BOLD} fg={theme.text.base} flexShrink={0}>
           /btw
         </text>
-        <text fg={theme.text.muted} wrapMode="word" flexGrow={1}>
-          {props.question}
+        <text fg={theme.text.muted} wrapMode="none" flexGrow={1} truncate>
+          {props.question.replace(/\s+/g, " ")}
         </text>
         <text fg={theme.text.muted} flexShrink={0} onMouseUp={() => dialog.clear()}>
           esc

packages/tui/src/feature-plugins/system/diff-viewer.tsx

@@ -21,7 +21,7 @@ import { EmptyBorder } from "../../ui/border"
 import { FilePath } from "../../ui/file-path"
 import { getScrollAcceleration } from "../../util/scroll"
 import { createDebouncedSignal } from "../../util/signal"
-import { useConfig } from "../../config"
+import { type DiffSource, useConfig } from "../../config"
 import { locationKey } from "../../context/data"
 import { useThemes } from "../../context/theme"
 import { PatchDiff, type PatchDiffRef } from "../../component/patch-diff"
@@ -44,7 +44,7 @@ const FILE_TREE_MIN_WIDTH = 30
 const FILE_TREE_MAX_WIDTH = 40
 const FILE_HEADER_HEIGHT = 2
 const VCS_DIFF_CONTEXT_LINES = 12
-type DiffMode = Vcs.Mode
+type DiffMode = DiffSource
 type DiffView = "split" | "unified"
 type SelectedHunk = { readonly fileIndex: number; readonly hunkIndex: number; readonly scrollTop: number }
 type FileMenuState = { readonly fileIndex: number; readonly x: number; readonly y: number }
@@ -70,11 +70,16 @@ function storedView(value: unknown): DiffView | undefined {
   if (value === "split" || value === "unified") return value
 }
 
-function diffSourceLabel(mode: DiffMode) {
-  if (mode === "branch") return "All"
-  if (mode === "committed") return "Committed"
-  return "Uncommitted"
-}
+const DIFF_SOURCES = {
+  branch: { label: "All", description: "Branch + local changes" },
+  committed: { label: "Committed", description: "Branch commits only" },
+  working: { label: "Uncommitted", description: "Local changes only" },
+  turn: { label: "Last turn", description: "Latest session turn" },
+} satisfies Record<DiffMode, { label: string; description: string }>
+
+const VCS_SOURCES = ["branch", "committed", "working"] as const
+
+const needsBase = (mode: DiffMode) => mode === "branch" || mode === "committed"
 
 function DiffViewer(props: { context: Plugin.Context }) {
   const dimensions = useTerminalDimensions()
@@ -93,12 +98,15 @@ function DiffViewer(props: { context: Plugin.Context }) {
         }
       | undefined
   }
-  const [mode, setMode] = createSignal(params()?.mode ?? memory.source ?? config.data.diffs?.source ?? "branch")
+  const sessionID = () => params()?.sessionID
+  const sources = (): readonly DiffMode[] => (sessionID() ? [...VCS_SOURCES, "turn"] : VCS_SOURCES)
+  const initialMode = params()?.mode ?? memory.source ?? config.data.diffs?.source ?? "branch"
+  const [mode, setMode] = createSignal(sources().includes(initialMode) ? initialMode : "branch")
   const location = createMemo(
     () => {
-      const sessionID = params()?.sessionID
-      return sessionID
-        ? (props.context.data.session.get(sessionID)?.location ?? props.context.data.location.default())
+      const id = sessionID()
+      return id
+        ? (props.context.data.session.get(id)?.location ?? props.context.data.location.default())
         : props.context.data.location.default()
     },
     undefined,
@@ -121,19 +129,32 @@ function DiffViewer(props: { context: Plugin.Context }) {
     bases.set(key, pending)
     return pending
   }
-  const diffInput = createMemo(() => ({
-    mode: mode(),
-    location: location(),
-    key: baseKey(),
-    selected: mode() === "working" ? undefined : selectedBase(),
-  }))
-  const [diff] = createResource(diffInput, async (input) => {
-    const base =
-      input.mode === "working"
-        ? undefined
-        : input.selected
-          ? { name: input.selected, ref: input.selected }
-          : (await loadBase(input.location, input.key)).data
+  const diffInput = createMemo(() => {
+    const current = mode()
+    const id = sessionID()
+    if (current === "turn" && id) return { mode: current, sessionID: id }
+    const vcs = current === "turn" ? "branch" : current
+    return {
+      mode: vcs,
+      location: location(),
+      key: baseKey(),
+      selected: needsBase(vcs) ? selectedBase() : undefined,
+    }
+  })
+  const [diff, { refetch }] = createResource(diffInput, async (input) => {
+    if (input.mode === "turn") {
+      return {
+        base: null,
+        files: normalizeDiffs(
+          await props.context.client.session.diff({ sessionID: input.sessionID, context: VCS_DIFF_CONTEXT_LINES }),
+        ),
+      }
+    }
+    const base = !needsBase(input.mode)
+      ? undefined
+      : input.selected
+        ? { name: input.selected, ref: input.selected }
+        : (await loadBase(input.location, input.key)).data
     if (input !== diffInput() || (input.mode === "committed" && !base)) {
       return { base: null, files: [] }
     }
@@ -145,12 +166,21 @@ function DiffViewer(props: { context: Plugin.Context }) {
     })
     return { base, files: normalizeDiffs(result.data ?? []) }
   })
+  // Each completed turn replaces the last one.
+  createEffect((previous) => {
+    if (mode() !== "turn") return undefined
+    const id = sessionID()
+    const status = id ? props.context.data.session.status(id) : undefined
+    if (previous === "running" && status === "idle") void refetch()
+    return status
+  })
   const sourceBase = () => {
     const ref = selectedBase()
     return ref ? { name: ref, ref } : reportedBases().get(baseKey())
   }
   const result = () => (diff.error || diff.loading ? undefined : diff())
   const sourceDetail = () => {
+    if (mode() === "turn") return diff.error ? "Diff unavailable" : undefined
     if (mode() === "working") return "vs HEAD"
     if (diff.error) return "Base or diff unavailable"
     if (!result()) return "Resolving diff…"
@@ -167,6 +197,7 @@ function DiffViewer(props: { context: Plugin.Context }) {
         loading={diff.loading}
         error={diff.error}
         mode={mode()}
+        sources={sources()}
         sourceDetail={sourceDetail()}
         sourceBase={sourceBase()}
         unavailable={mode() === "committed" && !!result() && !result()?.base}
@@ -261,6 +292,7 @@ export function DiffViewerContent(props: {
   loading?: boolean
   error?: unknown
   mode: DiffMode
+  sources: readonly DiffMode[]
   sourceDetail?: string
   sourceBase?: Pick<Vcs.Base, "name" | "ref"> | null
   unavailable?: boolean
@@ -702,20 +734,6 @@ export function DiffViewerContent(props: {
   ]
 
   const openSwitchDiffDialog = () => {
-    const options = [
-      {
-        value: "branch" as const,
-        description: "Branch + local changes",
-      },
-      {
-        value: "committed" as const,
-        description: "Branch commits only",
-      },
-      {
-        value: "working" as const,
-        description: "Local changes only",
-      },
-    ]
     dialog.show(() => (
       <DialogSelect<DiffMode | "base">
         title="Diff source"
@@ -723,13 +741,14 @@ export function DiffViewerContent(props: {
         renderFilter={false}
         current={mode()}
         options={[
-          ...options.map((option) => ({
-            ...option,
-            title: diffSourceLabel(option.value),
-            titleView: diffSourceLabel(option.value).padEnd(11),
+          ...props.sources.map((source) => ({
+            value: source,
+            title: DIFF_SOURCES[source].label,
+            titleView: DIFF_SOURCES[source].label.padEnd(11),
+            description: DIFF_SOURCES[source].description,
             onSelect() {
               dialog.clear()
-              props.onSwitchSource(option.value)
+              props.onSwitchSource(source)
             },
           })),
           ...(props.onChooseBase
@@ -811,7 +830,7 @@ export function DiffViewerContent(props: {
               flexShrink={0}
               wrapMode="none"
             >
-              {diffSourceLabel(mode())}
+              {DIFF_SOURCES[mode()].label}
             </text>
             <Show when={props.sourceDetail}>
               <text fg={theme.text.muted} selectable={false} flexGrow={1} minWidth={0} wrapMode="none" truncate>
@@ -834,7 +853,7 @@ export function DiffViewerContent(props: {
           <Match when={!props.loading && props.error}>
             <box flexGrow={1} padding={2}>
               <text fg={theme.text.feedback.error.base}>
-                {!props.sourceBase && mode() !== "working"
+                {!props.sourceBase && needsBase(mode())
                   ? "Could not load diff. Choose a base branch from Diff source, or select Uncommitted."
                   : "Could not load diff. Reopen the diff viewer to try again."}
               </text>
@@ -868,7 +887,7 @@ export function DiffViewerContent(props: {
                   expandedNodes={expandedFileNodes()}
                   onRowClick={clickFileTreeRow}
                   onFileContextMenu={openFileMenu}
-                  source={diffSourceLabel(mode())}
+                  source={DIFF_SOURCES[mode()].label}
                   sourceDetail={props.sourceDetail}
                   onSwitchSource={openSwitchDiffDialog}
                   footer={<HelpShortcut />}

packages/tui/test/cli/tui/diff-viewer.test.tsx

@@ -209,6 +209,80 @@ test("explicit route source overrides the configured default", async () => {
   }
 })
 
+test("the turn source diffs the session's last turn without resolving a base", async () => {
+  const viewer = await renderDiffViewer(hunkDiff, { height: 30, kittyKeyboard: true })
+  try {
+    await chooseSource(viewer, 3)
+    await viewer.app.waitForFrame((frame) => frame.includes("Last turn") && frame.includes("const first"))
+    expect(viewer.app.captureCharFrame()).not.toContain("Base not reported")
+    expect(viewer.turnDiffRequests).toHaveLength(1)
+    expect(viewer.turnDiffRequests[0].searchParams.get("context")).toBe("12")
+    expect(viewer.turnDiffRequests[0].searchParams.has("from")).toBe(false)
+    expect(viewer.diffRequests).toHaveLength(1)
+    expect(viewer.baseRequests).toHaveLength(1)
+    await chooseSource(viewer, 2)
+    await viewer.app.waitForFrame((frame) => frame.includes("Uncommitted · vs HEAD") && frame.includes("const first"))
+    expect(viewer.vcsDiffInput()).toEqual({ location: session.location, mode: "working", context: "12" })
+  } finally {
+    viewer.app.renderer.destroy()
+  }
+})
+
+test("the turn source refreshes only when the session finishes a turn", async () => {
+  const viewer = await renderDiffViewer(hunkDiff, { source: "turn" })
+  try {
+    expect(viewer.turnDiffRequests).toHaveLength(1)
+    viewer.setSessionStatus("running")
+    await viewer.app.flush()
+    expect(viewer.turnDiffRequests).toHaveLength(1)
+    viewer.setSessionStatus("idle")
+    await viewer.app.waitFor(() => viewer.turnDiffRequests.length === 2)
+    await viewer.app.waitForFrame((frame) => frame.includes("const first"))
+    expect(viewer.diffRequests).toHaveLength(0)
+  } finally {
+    viewer.app.renderer.destroy()
+  }
+})
+
+test("an empty or failing turn diff uses the viewer's empty and error states", async () => {
+  const empty = await renderDiffViewer([], { source: "turn" })
+  try {
+    await empty.app.waitForFrame((frame) => frame.includes("No changes to show"))
+    expect(empty.baseRequests).toHaveLength(0)
+    expect(empty.diffRequests).toHaveLength(0)
+    expect(empty.turnDiffRequests).toHaveLength(1)
+  } finally {
+    empty.app.renderer.destroy()
+  }
+  const failing = await renderDiffViewer([], { source: "turn", fail: true })
+  try {
+    await failing.app.waitForFrame((frame) => frame.includes("Could not load diff. Reopen the diff viewer"))
+    expect(failing.app.captureCharFrame()).toContain("Last turn · Diff unavailable")
+    expect(failing.app.captureCharFrame()).not.toContain("Choose a base branch")
+  } finally {
+    failing.app.renderer.destroy()
+  }
+})
+
+test("the turn source is unavailable outside a session and falls back to the branch scope", async () => {
+  const viewer = await renderDiffViewer(hunkDiff, { source: "turn", height: 30, initialRoute: { type: "home" } })
+  try {
+    expect(viewer.vcsDiffInput()).toEqual({
+      location: { directory: "/repo/default" },
+      mode: "branch",
+      base: "refs/heads/v2",
+      context: "12",
+    })
+    expect(viewer.turnDiffRequests).toHaveLength(0)
+    viewer.app.mockInput.pressKey("d")
+    await viewer.app.waitForFrame((frame) => frame.includes("Diff source"))
+    expect(viewer.app.captureCharFrame()).not.toContain("Last turn")
+    expect(viewer.app.captureCharFrame()).toMatch(/Base\s+v2/)
+  } finally {
+    viewer.app.renderer.destroy()
+  }
+})
+
 test.each([50, 80, 160])(
   "keeps scope, base, and review count on one row with a selectable base at %i columns",
   async (width) => {
@@ -240,9 +314,11 @@ test.each([50, 80, 160])(
       expect(rows[first]).toMatch(/All\s+Branch \+ local changes/)
       expect(rows[first + 1]).toMatch(/Committed\s+Branch commits only/)
       expect(rows[first + 2]).toMatch(/Uncommitted\s+Local changes only/)
-      expect(rows[first + 3]).toMatch(/Base\s+release/)
+      expect(rows[first + 3]).toMatch(/Last turn\s+Latest session turn/)
+      expect(rows[first + 4]).toMatch(/Base\s+release/)
       expect(rows[first + 1].indexOf("Branch commits only")).toBe(rows[first].indexOf("Branch + local changes"))
       expect(rows[first + 2].indexOf("Local changes only")).toBe(rows[first].indexOf("Branch + local changes"))
+      expect(rows[first + 3].indexOf("Latest session turn")).toBe(rows[first].indexOf("Branch + local changes"))
       viewer.app.mockInput.pressEscape()
       await viewer.app.waitForFrame((frame) => !frame.includes("Diff source"))
       viewer.commands.get("diff.mark_reviewed")!.run()
@@ -292,7 +368,7 @@ test.each([50, 80, 100, 160])(
 )
 
 test("opening the source chooser from initial Uncommitted does not resolve a branch base", async () => {
-  const viewer = await renderDiffViewer(hunkDiff, { source: "working" })
+  const viewer = await renderDiffViewer(hunkDiff, { source: "working", height: 30 })
   try {
     viewer.app.mockInput.pressKey("d")
     await viewer.app.waitForFrame((frame) => frame.includes("Diff source"))
@@ -313,7 +389,7 @@ test.each(["branch", "committed", "working"] as const)(
       viewer.commands.get("diff.mark_reviewed")!.run()
       await viewer.app.flush()
       expect(viewer.app.captureCharFrame()).toContain("1/1")
-      await chooseSource(viewer, 3)
+      await chooseSource(viewer, 4)
       await viewer.app.waitForFrame((frame) => frame.includes("Base branch") && frame.includes("origin/release"))
       expect(viewer.app.captureCharFrame()).toMatch(/●\s+v2/)
       expect(viewer.branchesRequests[0].searchParams.get("location[directory]")).toBe("/repo/session")
@@ -347,7 +423,7 @@ test.each(["branch", "committed", "working"] as const)(
       expect(viewer.app.captureCharFrame()).toContain("0/1")
       expect(viewer.diffRequests).toHaveLength(source === "working" ? 2 : 3)
       if (source !== "working") expect(viewer.vcsDiffInput()).toMatchObject({ base: "origin/release" })
-      await chooseSource(viewer, 3)
+      await chooseSource(viewer, 4)
       await viewer.app.waitForFrame((frame) => /●\s+origin\/release/.test(frame))
       expect(viewer.baseRequests).toHaveLength(1)
     } finally {
@@ -371,7 +447,7 @@ test.each(["branch", "committed"] as const)("an ambiguous base never requests a
     expect(viewer.app.captureCharFrame()).toContain("Choose a base branch")
     expect(viewer.app.captureCharFrame()).not.toContain("No changes to show")
     expect(viewer.diffRequests).toHaveLength(0)
-    await chooseSource(viewer, 3)
+    await chooseSource(viewer, 4)
     await viewer.app.waitForFrame((frame) => frame.includes("Base branch") && frame.includes("origin/release"))
     viewer.app.mockInput.pressKey("HOME")
     viewer.app.mockInput.pressArrow("down")
@@ -388,7 +464,7 @@ test.each(["branch", "committed"] as const)("an ambiguous base never requests a
 test("base and scope choices survive reopening but not a new TUI instance", async () => {
   const viewer = await renderDiffViewer(hunkDiff, { source: "working", height: 30, kittyKeyboard: true })
   try {
-    await chooseSource(viewer, 3)
+    await chooseSource(viewer, 4)
     await viewer.app.waitForFrame((frame) => frame.includes("origin/release"))
     viewer.app.mockInput.pressArrow("down")
     viewer.app.mockInput.pressEnter()
@@ -421,7 +497,7 @@ test("base and scope choices survive reopening but not a new TUI instance", asyn
 test("base choices are isolated by branch within the same location", async () => {
   const viewer = await renderDiffViewer(hunkDiff, { height: 30, kittyKeyboard: true })
   try {
-    await chooseSource(viewer, 3)
+    await chooseSource(viewer, 4)
     await viewer.app.waitForFrame((frame) => frame.includes("origin/release"))
     viewer.app.mockInput.pressArrow("down")
     viewer.app.mockInput.pressEnter()
@@ -449,13 +525,13 @@ test("an invalid comparison reports an error and allows another base choice", as
         : json({ location: session.location, data: hunkDiff }),
   })
   try {
-    await chooseSource(viewer, 3)
+    await chooseSource(viewer, 4)
     await viewer.app.waitForFrame((frame) => frame.includes("origin/release"))
     viewer.app.mockInput.pressArrow("down")
     viewer.app.mockInput.pressEnter()
     await viewer.app.waitForFrame((frame) => frame.includes("Base or diff unavailable"))
     expect(viewer.app.captureCharFrame()).not.toContain("No changes to show")
-    await chooseSource(viewer, 3)
+    await chooseSource(viewer, 4)
     await viewer.app.waitForFrame((frame) => frame.includes("origin/release"))
     viewer.app.mockInput.pressKey("HOME")
     viewer.app.mockInput.pressEnter()
@@ -474,7 +550,7 @@ test("base search failures are visible without changing the diff", async () => {
     branchesResponse: async () => json({ message: "branches unavailable" }, { status: 503 }),
   })
   try {
-    await chooseSource(viewer, 3)
+    await chooseSource(viewer, 4)
     await viewer.app.waitForFrame((frame) => frame.includes("Could not load branches"))
     expect(viewer.app.captureCharFrame()).toContain("All · vs v2")
     expect(viewer.mutationRequests).toHaveLength(0)
@@ -493,7 +569,7 @@ test("a late base lookup cannot overwrite an in-memory base choice", async () =>
     baseResponse: () => pending.promise,
   })
   try {
-    await chooseSource(viewer, 3)
+    await chooseSource(viewer, 4)
     await viewer.app.waitForFrame((frame) => frame.includes("origin/release"))
     viewer.app.mockInput.pressArrow("down")
     viewer.app.mockInput.pressEnter()
@@ -522,7 +598,7 @@ test("dismissing the base picker leaves the comparison unchanged", async () => {
     kittyKeyboard: true,
   })
   try {
-    await chooseSource(viewer, 3)
+    await chooseSource(viewer, 4)
     await viewer.app.waitForFrame((frame) => frame.includes("origin/release"))
     viewer.app.mockInput.pressArrow("down")
     viewer.app.mockInput.pressEscape()
@@ -540,7 +616,7 @@ test("dismissing the base picker leaves the comparison unchanged", async () => {
 test("the base picker remembers its captured location without refreshing a moved session", async () => {
   const viewer = await renderDiffViewer(hunkDiff, { height: 30, kittyKeyboard: true })
   try {
-    await chooseSource(viewer, 3)
+    await chooseSource(viewer, 4)
     await viewer.app.waitForFrame((frame) => frame.includes("origin/release"))
     viewer.setSessionLocation({ directory: "/repo/moved" })
     await viewer.app.flush()
@@ -1800,7 +1876,7 @@ async function renderDiffViewer(
     onSessionTab?: () => void
     keybinds?: TuiKeybind.KeybindOverrides
     kittyKeyboard?: boolean
-    source?: "branch" | "committed" | "working"
+    source?: "branch" | "committed" | "working" | "turn"
     base?: typeof baseFixture | null
     open?: boolean
     pending?: boolean
@@ -1814,6 +1890,7 @@ async function renderDiffViewer(
   const [current, setCurrent] = createSignal<Route>(options.initialRoute ?? startRoute)
   const [sessionLocation, setSessionLocation] = createSignal(session.location)
   const [branch, setBranch] = createSignal("feature")
+  const [sessionStatus, setSessionStatus] = createSignal<"idle" | "running">("idle")
   const state = options.state ?? path.join(temporary.path, crypto.randomUUID())
   let renderDiff: Page["render"] | undefined
   let renderCommands: SlotClaim<"app">["render"] | undefined
@@ -1826,6 +1903,7 @@ async function renderDiffViewer(
   const writes: Info[] = []
   const baseRequests: URL[] = []
   const diffRequests: URL[] = []
+  const turnDiffRequests: URL[] = []
   const branchesRequests: URL[] = []
   const mutationRequests: URL[] = []
   const config = createTuiResolvedConfig(stored.info)
@@ -1858,6 +1936,11 @@ async function renderDiffViewer(
             ),
           })
     }
+    if (url.pathname === "/api/session/session-1/diff") {
+      turnDiffRequests.push(url)
+      if (options.fail) return json({ message: "boom" }, { status: 500 })
+      return json({ data: vcsDiff })
+    }
     if (url.pathname !== "/api/vcs/diff") return
     diffRequests.push(url)
     vcsDiffInput = {
@@ -1896,7 +1979,7 @@ async function renderDiffViewer(
         storage: useStorage(),
         client: createApi(transport.fetch),
         data: {
-          session: { get: () => ({ ...session, location: sessionLocation() }) },
+          session: { get: () => ({ ...session, location: sessionLocation() }), status: sessionStatus },
           location: {
             default: () => ({ directory: "/repo/default" }),
             vcs: { info: () => ({ branch: { current: branch() } }) },
@@ -2003,9 +2086,11 @@ async function renderDiffViewer(
     imageReadInput: () => imageReadInput,
     baseRequests,
     diffRequests,
+    turnDiffRequests,
     branchesRequests,
     mutationRequests,
     setSessionLocation,
+    setSessionStatus,
     setBranch,
     state,
     writes,

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

@@ -9,8 +9,8 @@ import { CommandMap, Definitions } from "../src/config/v1/keybind"
 
 const decodeInfo = Schema.decodeUnknownSync(Info)
 
-test("validates the three explicit diff source defaults", () => {
-  for (const source of ["branch", "committed", "working"] as const) {
+test("validates the explicit diff source defaults", () => {
+  for (const source of ["branch", "committed", "working", "turn"] as const) {
     expect(decodeInfo({ diffs: { source } })).toEqual({ diffs: { source } })
   }
   expect(decodeInfo({ diffs: {} })).toEqual({ diffs: {} })

services/www/src/docs/content/cli/config.mdx

@@ -194,18 +194,19 @@ Configure the initial diff scope and presentation:
 
 <div class="docs-table-scroll" role="region" aria-label="Diff settings" tabIndex={0}>
 
-| Setting        | Values                              | Description                                                   |
-| -------------- | ----------------------------------- | ------------------------------------------------------------- |
-| `diffs.source` | `branch`, `committed`, or `working` | Sets the initial review scope.                                |
-| `diffs.wrap`   | `word` or `none`                    | Wraps long lines at words or leaves them unwrapped.           |
-| `diffs.tree`   | boolean                             | Shows the diff file tree.                                     |
-| `diffs.single` | boolean                             | Shows only the selected file patch.                           |
-| `diffs.view`   | `auto`, `split`, or `unified`       | Sets the layout. `auto` chooses from the available width.     |
+| Setting        | Values                                      | Description                                               |
+| -------------- | ------------------------------------------- | --------------------------------------------------------- |
+| `diffs.source` | `branch`, `committed`, `working`, or `turn` | Sets the initial review scope.                            |
+| `diffs.wrap`   | `word` or `none`                            | Wraps long lines at words or leaves them unwrapped.       |
+| `diffs.tree`   | boolean                                     | Shows the diff file tree.                                 |
+| `diffs.single` | boolean                                     | Shows only the selected file patch.                       |
+| `diffs.view`   | `auto`, `split`, or `unified`               | Sets the layout. `auto` chooses from the available width. |
 
 </div>
 
 `branch` shows **All** branch and local changes, `committed` shows branch commits only, and `working` shows staged,
-unstaged, and untracked changes.
+unstaged, and untracked changes. `turn` shows **Last turn**, the files the session changed in its latest turn; it
+refreshes when the session finishes a turn and falls back to `branch` when `/diff` is not opened from a session.
 
 In `/diff`, press `d` to change the scope or choose a comparison branch from **Base**. These in-view choices last until
 the TUI exits and do not change `cli.json`.

services/www/src/docs/content/cli/keybinds.mdx

@@ -117,7 +117,7 @@ The `app.clear` command works only in [`opencode mini`](/cli). Press `ctrl+l` to
 
 ## Diff Viewer
 
-Press `d` (`diff.switch_source`) to choose **All**, **Committed**, or **Uncommitted**, or select **Base** to change the comparison branch. Choices are remembered until the TUI exits. Set the initial scope with [`diffs.source` in `cli.json`](/cli/config#diffs).
+Press `d` (`diff.switch_source`) to choose **All**, **Committed**, **Uncommitted**, or **Last turn** (inside a session), or select **Base** to change the comparison branch. Choices are remembered until the TUI exits. Set the initial scope with [`diffs.source` in `cli.json`](/cli/config#diffs).
 
 Scrolling, paging, and start/end shortcuts always control the diff. There is no keyboard focus switch: click files to open them, click folders to expand or collapse them, and use the mouse wheel to scroll the file tree.