@effect-uai/inworld 0.4.0

package/src/InworldTranscriber.ts

@@ -0,0 +1,225 @@
+/**
+ * Sync transcription via Inworld's REST endpoint.
+ *
+ * - `transcribe` → `POST /stt/v1/transcribe` with audio as base64 in
+ *   `audioData.content`. URL input is not accepted by Inworld — the
+ *   adapter rejects `_tag: "url"` audio sources with `InvalidRequest`.
+ *
+ * Streaming transcription lives at the `InworldRealtimeTranscriber`
+ * subpath, which adds the WS path and the `SttStreaming` capability marker.
+ */
+import { Context, Effect, Encoding, Layer, Match, Redacted, Schema, Stream } from "effect"
+import { HttpClient, HttpClientRequest } from "effect/unstable/http"
+import * as AiError from "@effect-uai/core/AiError"
+import type { AudioSource } from "@effect-uai/core/Audio"
+import type { TranscriptEvent, TranscriptResult, WordTimestamp } from "@effect-uai/core/Transcript"
+import {
+  type CommonStreamTranscribeRequest,
+  type CommonTranscribeRequest,
+  Transcriber,
+  type TranscriberService,
+} from "@effect-uai/core/Transcriber"
+import { authHeader, httpStatusError, transportFailure } from "./codec.js"
+import type { InworldSttModel } from "./models.js"
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+/**
+ * Inworld-typed transcribe request. `numberOfChannels` defaults to 1.
+ * `audioEncoding` is autodetected from the audio MIME by default; pass
+ * an explicit value to override (useful for raw PCM bytes).
+ */
+export type InworldTranscribeRequest = Omit<CommonTranscribeRequest, "model"> & {
+  readonly model: InworldSttModel
+  readonly audioEncoding?: "AUTO_DETECT" | "LINEAR16" | "MP3" | "OGG_OPUS" | "FLAC"
+  readonly sampleRateHertz?: number
+  readonly numberOfChannels?: number
+}
+
+export type InworldTranscriberService = {
+  readonly transcribe: (
+    r: InworldTranscribeRequest,
+  ) => Effect.Effect<TranscriptResult, AiError.AiError>
+  readonly streamTranscriptionFrom: TranscriberService["streamTranscriptionFrom"]
+}
+
+export class InworldTranscriber extends Context.Service<
+  InworldTranscriber,
+  InworldTranscriberService
+>()("@betalyra/effect-uai/providers/inworld/InworldTranscriber") {}
+
+export type Config = { readonly apiKey: Redacted.Redacted; readonly baseUrl?: string }
+
+// ---------------------------------------------------------------------------
+// AudioSource → base64. Inworld's sync endpoint takes inline base64 only.
+// ---------------------------------------------------------------------------
+
+const urlNotSupported: AiError.AiError = new AiError.InvalidRequest({
+  provider: "inworld",
+  param: "audio",
+  raw: 'Inworld accepts only inline base64. Fetch the URL yourself and pass `{ _tag: "bytes", bytes, mimeType }`.',
+})
+
+const audioToBase64: (audio: AudioSource) => Effect.Effect<string, AiError.AiError> =
+  Match.type<AudioSource>().pipe(
+    Match.tag("bytes", (a) => Effect.succeed(Encoding.encodeBase64(a.bytes))),
+    Match.tag("base64", (a) => Effect.succeed(a.base64)),
+    Match.tag("url", () => Effect.fail(urlNotSupported)),
+    Match.exhaustive,
+  )
+
+// ---------------------------------------------------------------------------
+// Request body
+// ---------------------------------------------------------------------------
+
+const promptToTerms = (
+  prompt: string | { readonly terms: ReadonlyArray<string> } | undefined,
+): ReadonlyArray<string> | undefined =>
+  prompt === undefined ? undefined : typeof prompt === "string" ? [prompt] : prompt.terms
+
+const buildBody = (request: InworldTranscribeRequest) =>
+  Effect.gen(function* () {
+    const content = yield* audioToBase64(request.audio)
+    const prompts = promptToTerms(request.prompt)
+    return {
+      transcribeConfig: {
+        modelId: request.model,
+        audioEncoding: request.audioEncoding ?? "AUTO_DETECT",
+        ...(request.sampleRateHertz !== undefined && {
+          sampleRateHertz: request.sampleRateHertz,
+        }),
+        numberOfChannels: request.numberOfChannels ?? 1,
+        ...(request.language !== undefined && { language: request.language }),
+        ...(prompts !== undefined && { prompts }),
+        ...(request.wordTimestamps === true && { includeWordTimestamps: true }),
+      },
+      audioData: { content },
+    }
+  })
+
+// ---------------------------------------------------------------------------
+// Wire schema
+// ---------------------------------------------------------------------------
+
+const WireWord = Schema.Struct({
+  word: Schema.String,
+  startTimeMs: Schema.optional(Schema.Number),
+  endTimeMs: Schema.optional(Schema.Number),
+  confidence: Schema.optional(Schema.Number),
+})
+
+const WireResponse = Schema.Struct({
+  transcription: Schema.Struct({
+    transcript: Schema.String,
+    isFinal: Schema.optional(Schema.Boolean),
+    wordTimestamps: Schema.optional(Schema.NullOr(Schema.Array(WireWord))),
+  }),
+})
+const decodeResponse = Schema.decodeUnknownEffect(WireResponse)
+
+const wireWordToCommon = (w: typeof WireWord.Type): WordTimestamp | undefined =>
+  w.startTimeMs === undefined || w.endTimeMs === undefined
+    ? undefined
+    : {
+        text: w.word,
+        startSeconds: w.startTimeMs / 1000,
+        endSeconds: w.endTimeMs / 1000,
+        ...(w.confidence !== undefined && { confidence: w.confidence }),
+      }
+
+// ---------------------------------------------------------------------------
+// HTTP plumbing
+// ---------------------------------------------------------------------------
+
+const baseUrl = (cfg: Config) => cfg.baseUrl ?? "https://api.inworld.ai"
+
+/** Exported for reuse by `InworldRealtimeTranscriber`. */
+export const transcribeImpl = (cfg: Config) => (request: InworldTranscribeRequest) =>
+  Effect.gen(function* () {
+    const client = yield* HttpClient.HttpClient
+    const body = yield* buildBody(request)
+    const httpRequest = HttpClientRequest.post(`${baseUrl(cfg)}/stt/v1/transcribe`).pipe(
+      HttpClientRequest.setHeader("Authorization", authHeader(cfg.apiKey)),
+      HttpClientRequest.bodyJsonUnsafe(body),
+    )
+    const response = yield* client.execute(httpRequest).pipe(Effect.mapError(transportFailure))
+    if (response.status >= 400) {
+      const text = yield* response.text.pipe(Effect.orElseSucceed(() => ""))
+      return yield* Effect.fail(httpStatusError(response.status, text))
+    }
+    const json = yield* response.json.pipe(Effect.mapError(transportFailure))
+    const wire = yield* decodeResponse(json).pipe(
+      Effect.mapError(
+        (cause) =>
+          new AiError.GenerationFailed({
+            provider: "inworld",
+            raw: { message: "STT response missing `transcription.transcript`", cause, json },
+          }),
+      ),
+    )
+    const words = wire.transcription.wordTimestamps
+      ?.map(wireWordToCommon)
+      .filter((w): w is WordTimestamp => w !== undefined)
+    return {
+      text: wire.transcription.transcript,
+      ...(words !== undefined && words.length > 0 && { words }),
+      raw: json,
+    } satisfies TranscriptResult
+  })
+
+// ---------------------------------------------------------------------------
+// streamTranscriptionFrom Unsupported on this Layer
+// ---------------------------------------------------------------------------
+
+const streamUnsupported = <E, R>(
+  _audioIn: Stream.Stream<Uint8Array, E, R>,
+  _request: CommonStreamTranscribeRequest,
+): Stream.Stream<TranscriptEvent, AiError.AiError | E, R> => {
+  const fail: Stream.Stream<TranscriptEvent, AiError.AiError | E, R> = Stream.fail(
+    new AiError.Unsupported({
+      provider: "inworld",
+      capability: "streamTranscriptionFrom",
+      reason:
+        "This Layer is sync-only. Import `@effect-uai/inworld/InworldRealtimeTranscriber` to use the WS streamTranscriptionFrom path.",
+    }),
+  )
+  return fail
+}
+
+// ---------------------------------------------------------------------------
+// Constructors
+// ---------------------------------------------------------------------------
+
+export const make = (
+  cfg: Config,
+): Effect.Effect<InworldTranscriberService, never, HttpClient.HttpClient> =>
+  Effect.map(HttpClient.HttpClient.asEffect(), (client) => ({
+    transcribe: (request) =>
+      transcribeImpl(cfg)(request).pipe(Effect.provideService(HttpClient.HttpClient, client)),
+    streamTranscriptionFrom: streamUnsupported,
+  }))
+
+/**
+ * Sync-only Layer. Registers `InworldTranscriber` + the generic
+ * `Transcriber`. Does **not** register `SttStreaming` — for live
+ * transcription use `@effect-uai/inworld/InworldRealtimeTranscriber`.
+ */
+export const layer = (
+  cfg: Config,
+): Layer.Layer<InworldTranscriber | Transcriber, never, HttpClient.HttpClient> =>
+  Layer.merge(
+    Layer.effect(InworldTranscriber, make(cfg)),
+    Layer.effect(
+      Transcriber,
+      Effect.map(
+        make(cfg),
+        (s): TranscriberService => ({
+          transcribe: (req: CommonTranscribeRequest) =>
+            s.transcribe(req as InworldTranscribeRequest),
+          streamTranscriptionFrom: s.streamTranscriptionFrom,
+        }),
+      ),
+    ),
+  )

package/src/codec.ts

@@ -0,0 +1,141 @@
+import { Effect, Encoding, Match, Redacted, Result } from "effect"
+import * as AiError from "@effect-uai/core/AiError"
+import type { AudioFormat } from "@effect-uai/core/Audio"
+import type { InworldAudioEncoding } from "./models.js"
+
+// ---------------------------------------------------------------------------
+// Auth — `Authorization: Basic $INWORLD_API_KEY`. The portal key is already
+// base64-encoded, so we inject it verbatim. Do NOT re-encode `key:secret`.
+// ---------------------------------------------------------------------------
+
+export const authHeader = (apiKey: Redacted.Redacted): string => `Basic ${Redacted.value(apiKey)}`
+
+// ---------------------------------------------------------------------------
+// AudioFormat → Inworld `audioConfig`
+// ---------------------------------------------------------------------------
+
+export type AudioConfig = {
+  readonly audioEncoding: InworldAudioEncoding
+  readonly sampleRateHertz?: number
+  readonly bitRate?: number
+  readonly speakingRate?: number
+}
+
+const unsupportedFormat = (format: AudioFormat): AiError.AiError =>
+  new AiError.Unsupported({
+    provider: "inworld",
+    capability: "outputFormat",
+    reason: `Cannot encode ${JSON.stringify(format)} as Inworld audioConfig. Supported: mp3, wav (LINEAR16), ogg+opus, flac, raw pcm_s16le/mulaw/alaw.`,
+  })
+
+/**
+ * Map our cross-provider `AudioFormat` to Inworld's `audioConfig.audioEncoding`.
+ *
+ * Inworld quirk: sync `LINEAR16` / `WAV` responses include a WAV header in
+ * the returned `audioContent`; streaming (NDJSON + WS) responses for the
+ * same encoding do NOT include the header. Callers consuming raw PCM via
+ * streaming should request `raw + pcm_s16le` (→ `PCM`) for predictable
+ * concatenation, and reserve `wav` for sync.
+ */
+export const audioEncodingFor: (
+  format: AudioFormat,
+) => Effect.Effect<InworldAudioEncoding, AiError.AiError> = (format) =>
+  Match.value(format).pipe(
+    Match.when({ container: "mp3" }, () => Effect.succeed<InworldAudioEncoding>("MP3")),
+    Match.when({ container: "wav" }, () => Effect.succeed<InworldAudioEncoding>("LINEAR16")),
+    Match.when({ container: "ogg", encoding: "opus" }, () =>
+      Effect.succeed<InworldAudioEncoding>("OGG_OPUS"),
+    ),
+    Match.when({ container: "flac" }, () => Effect.succeed<InworldAudioEncoding>("FLAC")),
+    Match.when({ container: "raw", encoding: "pcm_s16le" }, () =>
+      Effect.succeed<InworldAudioEncoding>("PCM"),
+    ),
+    Match.when({ container: "raw", encoding: "pcm_mulaw" }, () =>
+      Effect.succeed<InworldAudioEncoding>("MULAW"),
+    ),
+    Match.when({ container: "raw", encoding: "pcm_alaw" }, () =>
+      Effect.succeed<InworldAudioEncoding>("ALAW"),
+    ),
+    Match.orElse((f) => Effect.fail(unsupportedFormat(f))),
+  )
+
+export const audioConfigFor = (
+  format: AudioFormat,
+  speakingRate?: number,
+): Effect.Effect<AudioConfig, AiError.AiError> =>
+  Effect.map(audioEncodingFor(format), (audioEncoding) => ({
+    audioEncoding,
+    sampleRateHertz: format.sampleRate,
+    ...(format.bitRate !== undefined && { bitRate: format.bitRate }),
+    ...(speakingRate !== undefined && { speakingRate }),
+  }))
+
+/** Default Inworld output: 24 kHz mono mp3. Matches Inworld's docs default. */
+export const defaultFormat: AudioFormat = {
+  container: "mp3",
+  encoding: "mp3",
+  sampleRate: 24000,
+}
+
+// ---------------------------------------------------------------------------
+// base64 → bytes — decoding `audioContent` from sync, NDJSON, and WS responses
+// ---------------------------------------------------------------------------
+
+export const decodeAudioContent = (b64: string): Effect.Effect<Uint8Array, AiError.AiError> =>
+  Result.match(Encoding.decodeBase64(b64), {
+    onSuccess: Effect.succeed,
+    onFailure: (cause) =>
+      Effect.fail(
+        new AiError.GenerationFailed({
+          provider: "inworld",
+          raw: { message: "audioContent base64 decode failed", cause },
+        }),
+      ),
+  })
+
+// ---------------------------------------------------------------------------
+// HTTP status → AiError
+// ---------------------------------------------------------------------------
+
+export const httpStatusError: (status: number, body: string) => AiError.AiError = (status, body) =>
+  Match.value(status).pipe(
+    Match.when(
+      429,
+      (): AiError.AiError => new AiError.RateLimited({ provider: "inworld", raw: body }),
+    ),
+    Match.whenOr(
+      408,
+      504,
+      (): AiError.AiError => new AiError.Timeout({ provider: "inworld", raw: body }),
+    ),
+    Match.when(
+      401,
+      (): AiError.AiError =>
+        new AiError.AuthFailed({ provider: "inworld", subtype: "auth", raw: body }),
+    ),
+    Match.when(
+      403,
+      (): AiError.AiError =>
+        new AiError.AuthFailed({ provider: "inworld", subtype: "permission", raw: body }),
+    ),
+    Match.when(
+      402,
+      (): AiError.AiError =>
+        new AiError.AuthFailed({ provider: "inworld", subtype: "billing", raw: body }),
+    ),
+    Match.when(
+      413,
+      (): AiError.AiError => new AiError.ContextLengthExceeded({ provider: "inworld", raw: body }),
+    ),
+    Match.when(
+      (n) => n >= 500,
+      (n): AiError.AiError =>
+        new AiError.Unavailable({ provider: "inworld", status: n, raw: body }),
+    ),
+    Match.orElse(
+      (): AiError.AiError => new AiError.InvalidRequest({ provider: "inworld", raw: body }),
+    ),
+  )
+
+export const transportFailure = (cause: unknown): AiError.AiError =>
+  new AiError.Unavailable({ provider: "inworld", raw: cause })

package/src/index.ts

@@ -0,0 +1,6 @@
+export * as InworldSynthesizer from "./InworldSynthesizer.js"
+export * as InworldRealtimeSynthesizer from "./InworldRealtimeSynthesizer.js"
+export * as InworldTranscriber from "./InworldTranscriber.js"
+export * as InworldRealtimeTranscriber from "./InworldRealtimeTranscriber.js"
+export * as codec from "./codec.js"
+export * from "./models.js"

package/src/models.ts

@@ -0,0 +1,69 @@
+/**
+ * Inworld TTS models (current per [docs.inworld.ai/tts/tts](https://docs.inworld.ai/tts/tts)).
+ *
+ * - `inworld-tts-2` — flagship, 100+ languages, supports `deliveryMode` style
+ *   steering (`STABLE` / `BALANCED` / `CREATIVE`). ~200ms P50.
+ * - `inworld-tts-1.5-max` — 15 languages, ~200ms P50.
+ * - `inworld-tts-1.5-mini` — 15 languages, ~120ms P50, lowest latency.
+ *
+ * `inworld-tts-1` / `inworld-tts-1-max` are not in current docs — treat as
+ * superseded. The `(string & {})` tail keeps autocomplete on literals while
+ * accepting any string so newly-released models work without an SDK update.
+ */
+export type InworldTtsModel =
+  | "inworld-tts-2"
+  | "inworld-tts-1.5-max"
+  | "inworld-tts-1.5-mini"
+  // eslint-disable-next-line @typescript-eslint/ban-types
+  | (string & {})
+
+/**
+ * Inworld voice ID. Inworld voices are human-readable names ("Sarah",
+ * "Edward", …) but there's no public list-voices REST endpoint — voices
+ * are browsed via the Inworld Portal. Typing this as `string` rather than
+ * a hard-coded union avoids the union rotting between SDK releases.
+ */
+export type InworldVoiceId = string
+
+/**
+ * Inworld STT models. `inworld/inworld-stt-1` is the first-party model
+ * (marked Experimental in docs at time of writing). The rest are
+ * router-style passthroughs — Inworld proxies to the named provider
+ * behind their auth & billing.
+ *
+ * Streaming WS support varies: `inworld/inworld-stt-1` and AssemblyAI /
+ * Soniox variants support both sync + WS; Groq Whisper is sync-only.
+ */
+export type InworldSttModel =
+  | "inworld/inworld-stt-1"
+  | "groq/whisper-large-v3"
+  | "assemblyai/universal-streaming-english"
+  | "assemblyai/universal-streaming-multilingual"
+  | "assemblyai/u3-rt-pro"
+  | "assemblyai/whisper-rt"
+  | "soniox/stt-rt-v4"
+  // eslint-disable-next-line @typescript-eslint/ban-types
+  | (string & {})
+
+/**
+ * `deliveryMode` style steering — only honored by `inworld-tts-2`. Older
+ * models ignore the field silently.
+ */
+export type InworldDeliveryMode = "STABLE" | "BALANCED" | "CREATIVE"
+
+/**
+ * Inworld's `audioEncoding` enum (TTS audioConfig).
+ *
+ * Note: sync `LINEAR16` / `WAV` responses include a WAV header in the
+ * `audioContent` bytes. Streaming (NDJSON + WS) chunks do **not**. The
+ * codec layer surfaces this difference in `AudioFormat.container`.
+ */
+export type InworldAudioEncoding =
+  | "LINEAR16"
+  | "MP3"
+  | "OGG_OPUS"
+  | "ALAW"
+  | "MULAW"
+  | "FLAC"
+  | "PCM"
+  | "WAV"

package/src/realtimeStt.ts

@@ -0,0 +1,236 @@
+/**
+ * Inworld Realtime STT — `wss://api.inworld.ai/stt/v1/transcribe:streamBidirectional`.
+ *
+ * Auth: `Authorization: Basic <API_KEY>` on the WS upgrade header (matches
+ * Inworld's own JS sample). Setting headers needs the `ws` peer dep
+ * (Node/Bun); see `./wsAuth.ts`.
+ *
+ * Wire shape (per [inworld-ai/inworld-api-examples](https://github.com/inworld-ai/inworld-api-examples)):
+ *   client → server:
+ *     `{ "transcribeConfig": { modelId, audioEncoding, sampleRateHertz, language, ... } }`  (first frame)
+ *     `{ "audioChunk": { "content": "<base64 audio>" } }`                                  (×N)
+ *     `{ "closeStream": {} }`                                                              (end-of-input)
+ *   server → client:
+ *     `{ "result": { "transcription": { "transcript": "...", "isFinal": true|false } } }`
+ *     `{ "result": { "speechStarted": { "startTimeMs": ... } } }`
+ *     `{ "result": { "speechStopped": { "silenceDurationMs": ... } } }`
+ *
+ * Inworld's STT WS sends audio as base64 inside JSON (NOT binary frames),
+ * matching the rest of the Inworld API style.
+ */
+import { Cause, Effect, Encoding, Match, Queue, Redacted, 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, WordTimestamp } from "@effect-uai/core/Transcript"
+import type { CommonStreamTranscribeRequest } from "@effect-uai/core/Transcriber"
+import { authedWsConstructor } from "./wsAuth.js"
+
+export type Config = { readonly apiKey: Redacted.Redacted; readonly baseUrl?: string }
+
+// ---------------------------------------------------------------------------
+// AudioFormat → `audioEncoding` slug for Inworld STT
+// ---------------------------------------------------------------------------
+
+type WireEncoding = "LINEAR16" | "MP3" | "OGG_OPUS" | "FLAC"
+
+const unsupportedFormat = (format: AudioFormat) =>
+  new AiError.Unsupported({
+    provider: "inworld",
+    capability: "inputFormat",
+    reason: `Inworld realtime STT accepts pcm_s16le (LINEAR16), mp3, ogg/opus, or flac. Got ${JSON.stringify(format)}.`,
+  })
+
+const inputFormatToWire: (format: AudioFormat) => Effect.Effect<WireEncoding, AiError.AiError> =
+  Match.type<AudioFormat>().pipe(
+    Match.when({ container: "raw", encoding: "pcm_s16le" }, () =>
+      Effect.succeed<WireEncoding>("LINEAR16"),
+    ),
+    Match.when({ container: "wav", encoding: "pcm_s16le" }, () =>
+      Effect.succeed<WireEncoding>("LINEAR16"),
+    ),
+    Match.when({ container: "mp3" }, () => Effect.succeed<WireEncoding>("MP3")),
+    Match.when({ container: "ogg", encoding: "opus" }, () =>
+      Effect.succeed<WireEncoding>("OGG_OPUS"),
+    ),
+    Match.when({ container: "flac" }, () => Effect.succeed<WireEncoding>("FLAC")),
+    Match.orElse((f) => Effect.fail(unsupportedFormat(f))),
+  )
+
+// ---------------------------------------------------------------------------
+// URL + frame builders
+// ---------------------------------------------------------------------------
+
+const buildWsUrl = (cfg: Config) => {
+  const wsBase = (cfg.baseUrl ?? "https://api.inworld.ai").replace(/^http/, "ws")
+  return `${wsBase}/stt/v1/transcribe:streamBidirectional`
+}
+
+const promptToTerms = (
+  prompt: string | { readonly terms: ReadonlyArray<string> } | undefined,
+): ReadonlyArray<string> | undefined =>
+  prompt === undefined ? undefined : typeof prompt === "string" ? [prompt] : prompt.terms
+
+const configFrame = (encoding: WireEncoding, request: CommonStreamTranscribeRequest) => {
+  const prompts = promptToTerms(request.prompt)
+  return JSON.stringify({
+    transcribeConfig: {
+      modelId: request.model,
+      audioEncoding: encoding,
+      sampleRateHertz: request.inputFormat.sampleRate,
+      numberOfChannels: request.inputFormat.channels ?? 1,
+      // Inworld's sample includes `language` even though docs mark it optional.
+      // Default to en-US to match the sample's behavior; caller can override.
+      language: request.language ?? "en-US",
+      ...(prompts !== undefined && { prompts }),
+      ...(request.wordTimestamps === true && { includeWordTimestamps: true }),
+    },
+  })
+}
+
+const audioChunkFrame = (bytes: Uint8Array) =>
+  JSON.stringify({ audioChunk: { content: Encoding.encodeBase64(bytes) } })
+
+const endTurnFrame = JSON.stringify({ endTurn: {} })
+const closeStreamFrame = JSON.stringify({ closeStream: {} })
+
+// ---------------------------------------------------------------------------
+// Wire schemas (server → client)
+// ---------------------------------------------------------------------------
+
+const WireWord = Schema.Struct({
+  word: Schema.String,
+  startTimeMs: Schema.optional(Schema.Number),
+  endTimeMs: Schema.optional(Schema.Number),
+  confidence: Schema.optional(Schema.Number),
+})
+
+const ResultBody = Schema.Struct({
+  transcription: Schema.optional(
+    Schema.Struct({
+      transcript: Schema.String,
+      isFinal: Schema.optional(Schema.Boolean),
+      wordTimestamps: Schema.optional(Schema.NullOr(Schema.Array(WireWord))),
+    }),
+  ),
+  speechStarted: Schema.optional(
+    Schema.Struct({
+      startTimeMs: Schema.optional(Schema.Number),
+      confidence: Schema.optional(Schema.Number),
+    }),
+  ),
+  speechStopped: Schema.optional(
+    Schema.Struct({
+      silenceDurationMs: Schema.optional(Schema.Number),
+    }),
+  ),
+  status: Schema.optional(Schema.Unknown),
+})
+
+const ServerFrame = Schema.Struct({
+  result: Schema.optional(ResultBody),
+  error: Schema.optional(Schema.Unknown),
+})
+const decodeServerFrame = Schema.decodeUnknownEffect(ServerFrame)
+
+const wireWordToCommon = (w: typeof WireWord.Type): WordTimestamp | undefined =>
+  w.startTimeMs === undefined || w.endTimeMs === undefined
+    ? undefined
+    : {
+        text: w.word,
+        startSeconds: w.startTimeMs / 1000,
+        endSeconds: w.endTimeMs / 1000,
+        ...(w.confidence !== undefined && { confidence: w.confidence }),
+      }
+
+export const wireToEvent = (frame: typeof ServerFrame.Type): TranscriptEvent | undefined => {
+  if (frame.error !== undefined) {
+    return {
+      _tag: "error",
+      message: typeof frame.error === "string" ? frame.error : JSON.stringify(frame.error),
+    }
+  }
+  const result = frame.result
+  if (result === undefined) return undefined
+  if (result.transcription !== undefined) {
+    const t = result.transcription
+    const words = t.wordTimestamps
+      ?.map(wireWordToCommon)
+      .filter((w): w is WordTimestamp => w !== undefined)
+    return t.isFinal === true
+      ? {
+          _tag: "final",
+          text: t.transcript,
+          ...(words !== undefined && words.length > 0 && { words }),
+        }
+      : {
+          _tag: "partial",
+          text: t.transcript,
+          ...(words !== undefined && words.length > 0 && { words }),
+        }
+  }
+  if (result.speechStarted !== undefined) {
+    return {
+      _tag: "speech-started",
+      atSeconds: (result.speechStarted.startTimeMs ?? 0) / 1000,
+    }
+  }
+  if (result.speechStopped !== undefined) {
+    return { _tag: "utterance-ended", atSeconds: 0 }
+  }
+  return undefined
+}
+
+const handleServerMessage = (queue: Queue.Queue<TranscriptEvent, Cause.Done>) => (raw: string) =>
+  Effect.gen(function* () {
+    const json = yield* JSONL.parseSafe(raw)
+    if (json === undefined) return
+    const decoded = yield* decodeServerFrame(json).pipe(Effect.option)
+    if (decoded._tag === "None") return
+    const event = wireToEvent(decoded.value)
+    if (event !== undefined) yield* Queue.offer(queue, event)
+  })
+
+// ---------------------------------------------------------------------------
+// Stream<Uint8Array> → Stream<TranscriptEvent>
+// ---------------------------------------------------------------------------
+
+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* () {
+        const encoding = yield* inputFormatToWire(request.inputFormat)
+        const socket = yield* Socket.makeWebSocket(buildWsUrl(cfg), {
+          // 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.apiKey)))
+        const queue = yield* Queue.bounded<TranscriptEvent, Cause.Done>(64)
+        const write = yield* socket.writer
+
+        // Writer: config → drain audio → endTurn → closeStream. Inworld
+        // emits `result.transcription` partials in real-time via VAD;
+        // `endTurn` is sent on input-stream end to flush any tail audio
+        // into a final transcript, then `closeStream` for graceful close.
+        yield* Effect.gen(function* () {
+          yield* write(configFrame(encoding, request))
+          yield* Stream.runForEach(audioIn, (bytes) => write(audioChunkFrame(bytes)))
+          yield* write(endTurnFrame)
+          yield* write(closeStreamFrame)
+        }).pipe(Effect.ignore, Effect.forkScoped)
+
+        // `Queue.end` flushes pending events then fails the next take with
+        // `Done` — clean stream end. `Queue.shutdown` would CLEAR queued
+        // items and interrupt pending takes (wrong for graceful teardown).
+        yield* socket
+          .runString(handleServerMessage(queue))
+          .pipe(Effect.ensuring(Queue.end(queue)), Effect.forkScoped)
+
+        return Stream.fromQueue(queue)
+      }),
+    )