@effect-uai/mistral 0.8.0

package/src/codec.ts

@@ -0,0 +1,338 @@
+import { Array as Arr, Encoding, Match, Option, Schema } from "effect"
+import type {
+  ContentBlock,
+  HistoryItem,
+  InputImage,
+  StopReason,
+  Usage,
+} from "@effect-uai/core/Items"
+import type { StructuredFormat } from "@effect-uai/core/StructuredFormat"
+import type { ToolDescriptor } from "@effect-uai/core/Tool"
+import type { Turn } from "@effect-uai/core/Turn"
+import { TurnEvent } from "@effect-uai/core/Turn"
+
+// ---------------------------------------------------------------------------
+// History → Mistral chat `messages`
+//
+// Mistral speaks the OpenAI chat-completions dialect: a flat list of
+// `{ role, content, ... }` objects where an assistant turn's tool calls live
+// on the assistant message (`tool_calls`) and each tool result is its own
+// `{ role: "tool", tool_call_id, content }` message. Our history is a flatter
+// item list (assistant message, then separate `function_call` items), so we
+// fold consecutive `function_call`s onto the preceding assistant message.
+// ---------------------------------------------------------------------------
+
+type WireMessage = {
+  role: string
+  content: string | ReadonlyArray<Record<string, unknown>>
+  tool_calls?: ReadonlyArray<Record<string, unknown>>
+  tool_call_id?: string
+}
+
+/** A `data:` URI for inline image bytes; URLs pass through untouched. */
+const imageSourceToUrl = Match.type<InputImage["source"]>().pipe(
+  Match.tag("url", (s) => s.url),
+  Match.tag("base64", (s) => `data:${s.mimeType};base64,${s.base64}`),
+  Match.tag("bytes", (s) => `data:${s.mimeType};base64,${Encoding.encodeBase64(s.bytes)}`),
+  Match.exhaustive,
+)
+
+const blockToPart = Match.type<ContentBlock>().pipe(
+  Match.discriminatorsExhaustive("type")({
+    input_text: (b) => ({ type: "text", text: b.text }),
+    output_text: (b) => ({ type: "text", text: b.text }),
+    refusal: (b) => ({ type: "text", text: b.text }),
+    input_image: (b) => ({ type: "image_url", image_url: imageSourceToUrl(b.source) }),
+  }),
+)
+
+const isTextBlock = (b: ContentBlock): boolean =>
+  b.type === "input_text" || b.type === "output_text" || b.type === "refusal"
+
+const textOfBlock = (b: ContentBlock): string => (b.type === "input_image" ? "" : b.text)
+
+/**
+ * Collapse a message's content to a plain string when it is text-only
+ * (the common case Mistral prefers), otherwise emit the multimodal parts
+ * array.
+ */
+const encodeContent = (
+  content: ReadonlyArray<ContentBlock>,
+): string | ReadonlyArray<Record<string, unknown>> =>
+  Arr.every(content, isTextBlock) ? content.map(textOfBlock).join("") : content.map(blockToPart)
+
+const toolCallWire = (call_id: string, name: string, args: string): Record<string, unknown> => ({
+  id: call_id,
+  type: "function",
+  function: { name, arguments: args },
+})
+
+const appendToolCall = (
+  acc: ReadonlyArray<WireMessage>,
+  call_id: string,
+  name: string,
+  args: string,
+): ReadonlyArray<WireMessage> => {
+  const last = acc[acc.length - 1]
+  const wire = toolCallWire(call_id, name, args)
+  // Attach to the immediately-preceding assistant message (not a tool result),
+  // matching the OpenAI/Mistral shape where tool calls ride the assistant turn.
+  if (last !== undefined && last.role === "assistant" && last.tool_call_id === undefined) {
+    return [...acc.slice(0, -1), { ...last, tool_calls: [...(last.tool_calls ?? []), wire] }]
+  }
+  return [...acc, { role: "assistant", content: "", tool_calls: [wire] }]
+}
+
+const foldItem = (acc: ReadonlyArray<WireMessage>, item: HistoryItem): ReadonlyArray<WireMessage> =>
+  Match.value(item).pipe(
+    Match.discriminatorsExhaustive("type")({
+      message: (m) => [...acc, { role: m.role, content: encodeContent(m.content) }],
+      function_call: (f) => appendToolCall(acc, f.call_id, f.name, f.arguments),
+      function_call_output: (o) => [
+        ...acc,
+        { role: "tool", tool_call_id: o.call_id, content: o.output },
+      ],
+      // Reasoning items are not replayed to the chat-completions endpoint.
+      reasoning: () => acc,
+    }),
+  )
+
+/** Convert our `HistoryItem[]` history into Mistral chat `messages`. */
+export const itemsToMessages = (items: ReadonlyArray<HistoryItem>): ReadonlyArray<WireMessage> =>
+  Arr.reduce(items, [] as ReadonlyArray<WireMessage>, foldItem)
+
+// ---------------------------------------------------------------------------
+// tools / tool_choice / response_format
+// ---------------------------------------------------------------------------
+
+export const toolsWire = (
+  descriptors: ReadonlyArray<ToolDescriptor>,
+): Option.Option<ReadonlyArray<Record<string, unknown>>> =>
+  descriptors.length > 0
+    ? Option.some(
+        descriptors.map((t) => ({
+          type: "function",
+          function: {
+            name: t.name,
+            description: t.description,
+            parameters: t.inputSchema,
+            ...(t.strict !== undefined && { strict: t.strict }),
+          },
+        })),
+      )
+    : Option.none()
+
+type ToolChoice =
+  | "auto"
+  | "required"
+  | "none"
+  | { readonly type: "function"; readonly name: string }
+
+// Mistral uses "any" for forced tool use (OpenAI's "required").
+export const toolChoiceWire = (choice: ToolChoice): string | Record<string, unknown> =>
+  Match.value(choice).pipe(
+    Match.when("auto", () => "auto" as const),
+    Match.when("required", () => "any" as const),
+    Match.when("none", () => "none" as const),
+    Match.orElse((c) => ({ type: "function", function: { name: c.name } })),
+  )
+
+export const responseFormatWire = (
+  structured: StructuredFormat<unknown>,
+): Record<string, unknown> => ({
+  type: "json_schema",
+  json_schema: {
+    name: structured.name,
+    schema: structured.schema["~standard"].jsonSchema.input({ target: "draft-2020-12" }),
+    ...(structured.strict !== undefined && { strict: structured.strict }),
+  },
+})
+
+// ---------------------------------------------------------------------------
+// Streaming decode: chat.completion.chunk → TurnEvent
+// ---------------------------------------------------------------------------
+
+const WireFunction = Schema.Struct({
+  name: Schema.optional(Schema.NullOr(Schema.String)),
+  arguments: Schema.optional(Schema.NullOr(Schema.String)),
+})
+
+const WireToolCall = Schema.Struct({
+  index: Schema.optional(Schema.Number),
+  id: Schema.optional(Schema.NullOr(Schema.String)),
+  function: Schema.optional(WireFunction),
+})
+
+const WireDelta = Schema.Struct({
+  role: Schema.optional(Schema.NullOr(Schema.String)),
+  content: Schema.optional(Schema.NullOr(Schema.String)),
+  tool_calls: Schema.optional(Schema.NullOr(Schema.Array(WireToolCall))),
+})
+
+const WireChoice = Schema.Struct({
+  index: Schema.optional(Schema.Number),
+  delta: Schema.optional(WireDelta),
+  finish_reason: Schema.optional(Schema.NullOr(Schema.String)),
+})
+
+const WireUsage = Schema.Struct({
+  prompt_tokens: Schema.optional(Schema.Number),
+  completion_tokens: Schema.optional(Schema.Number),
+  total_tokens: Schema.optional(Schema.Number),
+})
+
+export const WireChunk = Schema.Struct({
+  choices: Schema.optional(Schema.Array(WireChoice)),
+  usage: Schema.optional(Schema.NullOr(WireUsage)),
+})
+export type WireChunk = typeof WireChunk.Type
+
+export const decodeChunk = Schema.decodeUnknownEffect(WireChunk)
+
+// ---------------------------------------------------------------------------
+// Accumulator
+// ---------------------------------------------------------------------------
+
+type ToolAcc = {
+  readonly call_id: string
+  readonly name: string
+  readonly arguments: string
+}
+
+export type Accumulator = {
+  readonly text: string
+  /** Tool calls keyed by their wire `index` (defaults to position when absent). */
+  readonly tools: ReadonlyMap<number, ToolAcc>
+  readonly order: ReadonlyArray<number>
+  readonly usage: Usage
+  readonly finishReason: Option.Option<string>
+}
+
+export const emptyAccumulator: Accumulator = {
+  text: "",
+  tools: new Map(),
+  order: [],
+  usage: {},
+  finishReason: Option.none(),
+}
+
+/** State threaded through the fold plus the events the step produced. */
+type Step = readonly [Accumulator, ReadonlyArray<TurnEvent>]
+
+const usageFrom = (wire: typeof WireUsage.Type): Usage => ({
+  ...(wire.prompt_tokens !== undefined && { input_tokens: wire.prompt_tokens }),
+  ...(wire.completion_tokens !== undefined && { output_tokens: wire.completion_tokens }),
+  ...(wire.total_tokens !== undefined && { total_tokens: wire.total_tokens }),
+})
+
+const reasonToStop = Match.type<string>().pipe(
+  Match.when("stop", () => "stop" as const),
+  Match.when("length", () => "max_tokens" as const),
+  Match.when("model_length", () => "max_tokens" as const),
+  Match.when("tool_calls", () => "tool_calls" as const),
+  Match.when("content_filter", () => "content_filter" as const),
+  Match.orElse(() => "stop" as const),
+)
+
+const stopReasonOf = (acc: Accumulator): StopReason =>
+  Option.match(acc.finishReason, {
+    onNone: () => (acc.tools.size > 0 ? "tool_calls" : "stop"),
+    onSome: reasonToStop,
+  })
+
+const withTool = (acc: Accumulator, index: number, tool: ToolAcc, isNew: boolean): Accumulator => ({
+  ...acc,
+  tools: new Map(acc.tools).set(index, tool),
+  order: isNew ? [...acc.order, index] : acc.order,
+})
+
+const applyContent = (acc: Accumulator, delta: typeof WireDelta.Type | undefined): Step => {
+  const content = delta?.content
+  return content !== undefined && content !== null && content.length > 0
+    ? [{ ...acc, text: acc.text + content }, [TurnEvent.TextDelta({ text: content })]]
+    : [acc, []]
+}
+
+const applyToolCall = (acc: Accumulator, tc: typeof WireToolCall.Type, position: number): Step => {
+  const index = tc.index ?? position
+  const argsDelta = tc.function?.arguments ?? ""
+  const existing = acc.tools.get(index)
+  if (existing === undefined) {
+    const call_id = tc.id ?? `call_${index}`
+    const name = tc.function?.name ?? ""
+    return [
+      withTool(acc, index, { call_id, name, arguments: argsDelta }, true),
+      [
+        TurnEvent.ToolCallStart({ call_id, name }),
+        ...(argsDelta.length > 0
+          ? [TurnEvent.ToolCallArgsDelta({ call_id, delta: argsDelta })]
+          : []),
+      ],
+    ]
+  }
+  return argsDelta.length > 0
+    ? [
+        withTool(acc, index, { ...existing, arguments: existing.arguments + argsDelta }, false),
+        [TurnEvent.ToolCallArgsDelta({ call_id: existing.call_id, delta: argsDelta })],
+      ]
+    : [acc, []]
+}
+
+const chain = (step: Step, next: (acc: Accumulator) => Step): Step => {
+  const [acc, events] = step
+  const [acc2, more] = next(acc)
+  return [acc2, [...events, ...more]]
+}
+
+const applyChoice = (step: Step, choice: typeof WireChoice.Type): Step => {
+  const withContent = chain(step, (acc) => applyContent(acc, choice.delta))
+  const withTools = Arr.reduce(choice.delta?.tool_calls ?? [], withContent, (s: Step, tc, i) =>
+    chain(s, (acc) => applyToolCall(acc, tc, i)),
+  )
+  const reason = choice.finish_reason
+  return reason !== undefined && reason !== null
+    ? [{ ...withTools[0], finishReason: Option.some(reason) }, withTools[1]]
+    : withTools
+}
+
+/**
+ * Fold one decoded chunk into the accumulator, returning the next state and
+ * the `TurnEvent`s the chunk produced. Mirrors Anthropic's `deltasFromEvent`,
+ * but over chat-completions deltas.
+ */
+export const applyChunk = (acc: Accumulator, chunk: WireChunk): Step => {
+  const afterChoices = Arr.reduce(chunk.choices ?? [], [acc, []] as Step, applyChoice)
+  const usage = chunk.usage
+  return usage !== undefined && usage !== null
+    ? chain(afterChoices, (a) => {
+        const u = usageFrom(usage)
+        return [{ ...a, usage: u }, [TurnEvent.UsageUpdate({ usage: u })]]
+      })
+    : afterChoices
+}
+
+/** Assemble the terminal `Turn` from the accumulated state. */
+export const accumulatorToTurn = (acc: Accumulator): Turn => {
+  const message: ReadonlyArray<HistoryItem> =
+    acc.text.length > 0
+      ? [{ type: "message", role: "assistant", content: [{ type: "output_text", text: acc.text }] }]
+      : []
+  const toolCalls: ReadonlyArray<HistoryItem> = acc.order.flatMap((index) => {
+    const t = acc.tools.get(index)
+    return t === undefined
+      ? []
+      : [
+          {
+            type: "function_call" as const,
+            call_id: t.call_id,
+            name: t.name,
+            arguments: t.arguments,
+          },
+        ]
+  })
+  return {
+    items: [...message, ...toolCalls],
+    usage: acc.usage,
+    stop_reason: stopReasonOf(acc),
+  }
+}

package/src/http.ts

@@ -0,0 +1,46 @@
+import { Match } from "effect"
+import * as AiError from "@effect-uai/core/AiError"
+
+/** Map an HTTP status from any Mistral endpoint to an `AiError` variant. */
+export const httpStatusError: (status: number, body: string) => AiError.AiError = (status, body) =>
+  Match.value(status).pipe(
+    Match.when(
+      429,
+      (): AiError.AiError => new AiError.RateLimited({ provider: "mistral", raw: body }),
+    ),
+    Match.whenOr(
+      408,
+      504,
+      (): AiError.AiError => new AiError.Timeout({ provider: "mistral", raw: body }),
+    ),
+    Match.when(
+      401,
+      (): AiError.AiError =>
+        new AiError.AuthFailed({ provider: "mistral", subtype: "auth", raw: body }),
+    ),
+    Match.when(
+      403,
+      (): AiError.AiError =>
+        new AiError.AuthFailed({ provider: "mistral", subtype: "permission", raw: body }),
+    ),
+    Match.when(
+      402,
+      (): AiError.AiError =>
+        new AiError.AuthFailed({ provider: "mistral", subtype: "billing", raw: body }),
+    ),
+    Match.when(
+      413,
+      (): AiError.AiError => new AiError.ContextLengthExceeded({ provider: "mistral", raw: body }),
+    ),
+    Match.when(
+      (n) => n >= 500,
+      (n): AiError.AiError =>
+        new AiError.Unavailable({ provider: "mistral", status: n, raw: body }),
+    ),
+    Match.orElse(
+      (): AiError.AiError => new AiError.InvalidRequest({ provider: "mistral", raw: body }),
+    ),
+  )
+
+export const transportFailure = (cause: unknown): AiError.AiError =>
+  new AiError.Unavailable({ provider: "mistral", raw: cause })

package/src/index.ts

@@ -0,0 +1,6 @@
+export * as Mistral from "./Mistral.js"
+export * as MistralTranscriber from "./MistralTranscriber.js"
+export * as MistralRealtimeTranscriber from "./MistralRealtimeTranscriber.js"
+export * as MistralSynthesizer from "./MistralSynthesizer.js"
+export * as codec from "./codec.js"
+export * from "./models.js"

package/src/models.ts

@@ -0,0 +1,47 @@
+/**
+ * Known Mistral model identifiers usable via the chat-completions API (as of
+ * mid-2026). The `(string & {})` tail keeps autocomplete on the literals while
+ * still accepting any string, so newly-released models work without an SDK
+ * update.
+ *
+ * Reference: https://docs.mistral.ai/getting-started/models/models_overview
+ *
+ * Prefer the `-latest` aliases for evergreen pins; the dated snapshots are
+ * available when you need a frozen version.
+ */
+export type MistralModel =
+  | "mistral-large-latest"
+  | "mistral-medium-latest"
+  | "mistral-small-latest"
+  | "magistral-medium-latest"
+  | "magistral-small-latest"
+  | "ministral-8b-latest"
+  | "ministral-3b-latest"
+  | "open-mistral-nemo"
+  | "codestral-latest"
+  // eslint-disable-next-line @typescript-eslint/ban-types
+  | (string & {})
+
+// ---------------------------------------------------------------------------
+// Voxtral audio models (Mistral's STT / TTS family)
+// Reference: https://docs.mistral.ai/studio-api/audio/overview
+// ---------------------------------------------------------------------------
+
+/** Batch / offline transcription models. */
+export type MistralTranscribeModel =
+  | "voxtral-mini-latest"
+  | "voxtral-mini-2507"
+  // eslint-disable-next-line @typescript-eslint/ban-types
+  | (string & {})
+
+/** Realtime (streaming) transcription models. */
+export type MistralRealtimeModel =
+  | "voxtral-mini-transcribe-realtime-2602"
+  // eslint-disable-next-line @typescript-eslint/ban-types
+  | (string & {})
+
+/** Text-to-speech models. */
+export type MistralTtsModel =
+  | "voxtral-mini-tts-2603"
+  // eslint-disable-next-line @typescript-eslint/ban-types
+  | (string & {})

package/src/realtimeStt.ts

@@ -0,0 +1,256 @@
+/**
+ * Voxtral Realtime STT over WebSocket.
+ *
+ * Protocol mirrors the `mistralai[realtime]` Python client:
+ *   - URL: `wss://api.mistral.ai/v1/audio/transcriptions/realtime?model=…`
+ *     (the model is a query param, not a session field).
+ *   - Auth: `Authorization: Bearer …` header on the upgrade. The browser
+ *     `WebSocket` API can't set headers, so this module uses the `ws` peer
+ *     dep; `ws` is only pulled in transitively via
+ *     `MistralRealtimeTranscriber` (the sync `MistralTranscriber` stays free
+ *     of it).
+ *   - Client → server (JSON): `session.update` (audio_format +
+ *     target_streaming_delay_ms), then `input_audio.append` with base64 PCM,
+ *     and `input_audio.end` when the mic stream stops.
+ *   - Server → client (JSON): `session.created` / `session.updated`,
+ *     `transcription.text.delta` (`{ text }`), `transcription.done`
+ *     (`{ text }`), `transcription.segment`, `transcription.language`,
+ *     and `error` (`{ error: { message, code } }`).
+ *
+ * Voxtral Realtime is a *continuous* transcriber: it streams text deltas and
+ * only emits one `transcription.done` at end-of-audio (no server-side
+ * utterance segmentation). To satisfy the `Transcriber` contract's `final`
+ * semantics for conversational use, this adapter synthesizes a `final` event
+ * when the deltas go quiet for `utteranceSilence`.
+ */
+import {
+  Cause,
+  Clock,
+  Duration,
+  Effect,
+  Encoding,
+  Match,
+  Queue,
+  Redacted,
+  Ref,
+  Schema,
+  Stream,
+} from "effect"
+import * as Socket from "effect/unstable/socket/Socket"
+import * as AiError from "@effect-uai/core/AiError"
+import type { AudioFormat } from "@effect-uai/core/Audio"
+import * as JSONL from "@effect-uai/core/JSONL"
+import type { TranscriptEvent } from "@effect-uai/core/Transcript"
+import type { CommonStreamTranscribeRequest } from "@effect-uai/core/Transcriber"
+import { WebSocket as WSWebSocket } from "ws"
+
+export type Config = {
+  readonly apiKey: Redacted.Redacted
+  readonly baseUrl?: string
+  /** Target latency knob (`target_streaming_delay_ms`); lower = faster, less accurate. */
+  readonly targetStreamingDelay?: Duration.Duration
+  /**
+   * Silence gap after which the accumulated deltas are committed as a synthetic
+   * `final`. Voxtral Realtime does no utterance segmentation, so this is how the
+   * adapter delimits turns. Default 700 ms.
+   */
+  readonly utteranceSilence?: Duration.Duration
+}
+
+const DEFAULT_SILENCE = Duration.millis(700)
+
+// ---------------------------------------------------------------------------
+// AudioFormat gate — Voxtral Realtime ingests pcm_s16le @ 16000 mono only.
+// ---------------------------------------------------------------------------
+
+const ensureInputFormat = (format: AudioFormat): Effect.Effect<void, AiError.AiError> =>
+  format.container === "raw" && format.encoding === "pcm_s16le" && format.sampleRate === 16000
+    ? Effect.void
+    : Effect.fail(
+        new AiError.Unsupported({
+          provider: "mistral",
+          capability: "inputFormat",
+          reason: `Voxtral Realtime accepts pcm_s16le @ 16000 mono only. Got ${JSON.stringify(format)}.`,
+        }),
+      )
+
+// ---------------------------------------------------------------------------
+// URL + client frame builders
+// ---------------------------------------------------------------------------
+
+const buildWsUrl = (cfg: Config, model: string) => {
+  const base = (cfg.baseUrl ?? "https://api.mistral.ai").replace(/^http/, "ws")
+  return `${base}/v1/audio/transcriptions/realtime?model=${encodeURIComponent(model)}`
+}
+
+const sessionUpdateFrame = (cfg: Config) =>
+  JSON.stringify({
+    type: "session.update",
+    session: {
+      audio_format: { encoding: "pcm_s16le", sample_rate: 16000 },
+      ...(cfg.targetStreamingDelay !== undefined && {
+        target_streaming_delay_ms: Duration.toMillis(cfg.targetStreamingDelay),
+      }),
+    },
+  })
+
+const audioAppendFrame = (bytes: Uint8Array) =>
+  JSON.stringify({ type: "input_audio.append", audio: Encoding.encodeBase64(bytes) })
+
+const audioEndFrame = JSON.stringify({ type: "input_audio.end" })
+
+// ---------------------------------------------------------------------------
+// Wire schemas (server → client)
+// ---------------------------------------------------------------------------
+
+const ServerEvent = Schema.Union([
+  Schema.Struct({ type: Schema.Literal("session.created") }),
+  Schema.Struct({ type: Schema.Literal("session.updated") }),
+  Schema.Struct({ type: Schema.Literal("transcription.language") }),
+  Schema.Struct({ type: Schema.Literal("transcription.segment") }),
+  Schema.Struct({ type: Schema.Literal("transcription.text.delta"), text: Schema.String }),
+  Schema.Struct({ type: Schema.Literal("transcription.done"), text: Schema.String }),
+  Schema.Struct({
+    type: Schema.Literal("error"),
+    error: Schema.Struct({
+      message: Schema.String,
+      code: Schema.optional(Schema.NullOr(Schema.Number)),
+    }),
+  }),
+])
+const decodeServerEvent = Schema.decodeUnknownEffect(ServerEvent)
+
+/** Mutable turn state shared by the message handler and the silence finalizer. */
+type TurnState = {
+  readonly text: Ref.Ref<string>
+  readonly lastActivityMs: Ref.Ref<number>
+}
+
+const emitFinal = (
+  queue: Queue.Queue<TranscriptEvent, Cause.Done>,
+  state: TurnState,
+  override?: string,
+): Effect.Effect<void> =>
+  Effect.gen(function* () {
+    const acc = yield* Ref.getAndSet(state.text, "")
+    const text = (override !== undefined && override.length > 0 ? override : acc).trim()
+    if (text.length > 0) yield* Queue.offer(queue, { _tag: "final", text })
+  })
+
+const handleServerMessage =
+  (queue: Queue.Queue<TranscriptEvent, Cause.Done>, state: TurnState) => (raw: string) =>
+    Effect.gen(function* () {
+      const json = yield* JSONL.parseSafe(raw)
+      if (json === undefined) return
+      const decoded = yield* decodeServerEvent(json).pipe(Effect.option)
+      if (decoded._tag === "None") return
+      yield* Match.value(decoded.value).pipe(
+        Match.when({ type: "transcription.text.delta" }, (m) =>
+          Effect.gen(function* () {
+            const now = yield* Clock.currentTimeMillis
+            const next = yield* Ref.updateAndGet(state.text, (t) => t + m.text)
+            yield* Ref.set(state.lastActivityMs, now)
+            // Cumulative partial so the UI shows the growing sentence.
+            yield* Queue.offer(queue, { _tag: "partial", text: next })
+          }),
+        ),
+        // End-of-audio: commit whatever's left as the final utterance.
+        Match.when({ type: "transcription.done" }, (m) => emitFinal(queue, state, m.text)),
+        Match.when({ type: "error" }, (m) =>
+          Queue.offer(queue, {
+            _tag: "error",
+            ...(m.error.code != null && { code: String(m.error.code) }),
+            message: m.error.message,
+          }),
+        ),
+        // session.created / .updated / language / segment: no user-visible event.
+        Match.orElse(() => Effect.void),
+      )
+    })
+
+// Background loop: commit a synthetic final once the deltas go quiet.
+const silenceFinalizer = (
+  queue: Queue.Queue<TranscriptEvent, Cause.Done>,
+  state: TurnState,
+  silence: Duration.Duration,
+): Effect.Effect<never> => {
+  const silenceMs = Duration.toMillis(silence)
+  return Effect.gen(function* () {
+    const now = yield* Clock.currentTimeMillis
+    const last = yield* Ref.get(state.lastActivityMs)
+    const acc = yield* Ref.get(state.text)
+    if (acc.trim().length > 0 && now - last >= silenceMs) yield* emitFinal(queue, state)
+    yield* Effect.sleep("150 millis")
+  }).pipe(Effect.forever)
+}
+
+// ---------------------------------------------------------------------------
+// Stream<Uint8Array> → Stream<TranscriptEvent>
+// ---------------------------------------------------------------------------
+
+// `@types/ws`'s WebSocket extends Node's EventEmitter while
+// `globalThis.WebSocket` extends EventTarget; the browser-style surface
+// Effect's Socket reads (`addEventListener` / `send` / `close`) is identical at
+// runtime, hence the single contained cast.
+const authedWsConstructor =
+  (cfg: Config): Socket.WebSocketConstructor["Service"] =>
+  (url) =>
+    new WSWebSocket(url, undefined, {
+      headers: { Authorization: `Bearer ${Redacted.value(cfg.apiKey)}` },
+    }) as unknown as globalThis.WebSocket
+
+export const streamTranscription =
+  (cfg: Config) =>
+  <E, R>(
+    audioIn: Stream.Stream<Uint8Array, E, R>,
+    request: CommonStreamTranscribeRequest,
+  ): Stream.Stream<TranscriptEvent, AiError.AiError | E, R> =>
+    Stream.unwrap(
+      Effect.gen(function* () {
+        yield* ensureInputFormat(request.inputFormat)
+        const socket = yield* Socket.makeWebSocket(buildWsUrl(cfg, request.model), {
+          // Effect's Socket treats all close codes as errors by default —
+          // whitelist standard clean-close codes (1000 / 1001 / 1005).
+          closeCodeIsError: (code) => code !== 1000 && code !== 1001 && code !== 1005,
+        }).pipe(Effect.provideService(Socket.WebSocketConstructor, authedWsConstructor(cfg)))
+        const queue = yield* Queue.bounded<TranscriptEvent, Cause.Done>(64)
+        const state: TurnState = {
+          text: yield* Ref.make(""),
+          lastActivityMs: yield* Ref.make(0),
+        }
+        const write = yield* socket.writer
+
+        // session.update first, then stream base64 PCM frames, then signal end.
+        // Fork-scoped so the Stream's downstream scope tears them down on
+        // disconnect / cancel.
+        yield* Effect.gen(function* () {
+          yield* write(sessionUpdateFrame(cfg))
+          yield* Stream.runForEach(audioIn, (bytes) => write(audioAppendFrame(bytes)))
+          yield* write(audioEndFrame)
+        }).pipe(
+          Effect.tapError((cause) =>
+            Effect.logWarning("[voxtral-realtime] audio send failed", { cause }),
+          ),
+          Effect.ignore,
+          Effect.forkScoped,
+        )
+
+        yield* silenceFinalizer(queue, state, cfg.utteranceSilence ?? DEFAULT_SILENCE).pipe(
+          Effect.forkScoped,
+        )
+
+        // `Queue.end` flushes pending events then ends the stream cleanly;
+        // `Queue.shutdown` would drop queued items and interrupt takes. A
+        // connection/read failure is logged (otherwise the stream would end
+        // silently with no transcripts).
+        yield* socket.runString(handleServerMessage(queue, state)).pipe(
+          Effect.tapError((cause) =>
+            Effect.logWarning("[voxtral-realtime] socket closed", { cause }),
+          ),
+          Effect.ensuring(Queue.end(queue)),
+          Effect.forkScoped,
+        )
+
+        return Stream.fromQueue(queue)
+      }),
+    )