@effect-uai/core 0.3.0 → 0.5.0

package/dist/transcriber/Transcriber.mjs

@@ -0,0 +1,49 @@
+import { n as __exportAll } from "../chunk-uyGKjUfl.mjs";
+import { Context, Effect, Function, Stream } from "effect";
+//#region src/transcriber/Transcriber.ts
+var Transcriber_exports = /* @__PURE__ */ __exportAll({
+	SttStreaming: () => SttStreaming,
+	Transcriber: () => Transcriber,
+	streamTranscriptionFrom: () => streamTranscriptionFrom,
+	transcribe: () => transcribe
+});
+var Transcriber = class extends Context.Service()("@betalyra/effect-uai/Transcriber") {};
+/**
+* Capability marker — provided by provider layers whose
+* `streamTranscriptionFrom` is wired up at the wire level. Azure does
+* not ship it (streaming-STT is SDK-internal). Calling
+* `streamTranscriptionFrom` while only Azure's Layer is in scope fails
+* at `Effect.provide` with a type error, not at runtime.
+*
+* Phantom — the value is `void`; providers register with
+* `Layer.succeed(SttStreaming, undefined)`.
+*/
+var SttStreaming = class extends Context.Service()("@betalyra/effect-uai/capability/SttStreaming") {};
+/** One-shot transcription. */
+const transcribe = (request) => Effect.flatMap(Transcriber.asEffect(), (t) => t.transcribe(request));
+/**
+* Live transcription. Dual-arity: pipeable (data-last) and direct
+* (data-first). Requires `SttStreaming` in R — providers without
+* streaming support are a type error at provide time.
+*
+* @example
+* ```ts
+* // Pipeable — composes with other Stream operators
+* mic.frames.pipe(
+*   Transcriber.streamTranscriptionFrom(req),
+*   Stream.filter((e) => e._tag === "final"),
+* )
+*
+* // Direct
+* Transcriber.streamTranscriptionFrom(mic.frames, req)
+* ```
+*/
+const streamTranscriptionFrom = Function.dual(2, (audioIn, request) => Stream.unwrap(Effect.gen(function* () {
+	const t = yield* Transcriber.asEffect();
+	yield* SttStreaming.asEffect();
+	return t.streamTranscriptionFrom(audioIn, request);
+})));
+//#endregion
+export { SttStreaming, Transcriber, streamTranscriptionFrom, Transcriber_exports as t, transcribe };
+
+//# sourceMappingURL=Transcriber.mjs.map

package/dist/transcriber/Transcriber.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Transcriber.mjs","names":[],"sources":["../../src/transcriber/Transcriber.ts"],"sourcesContent":["import { Context, Effect, Function, Stream } from \"effect\"\nimport * as AiError from \"../domain/AiError.js\"\nimport type { AudioFormat, AudioSource } from \"../domain/Audio.js\"\nimport type { TranscriptEvent, TranscriptResult } from \"../domain/Transcript.js\"\n\n/**\n * Cross-provider sync transcription request. Provider-specific\n * extensions (Deepgram `keyterm[]`, ElevenLabs `diarize`, Google\n * `adaptation`, …) live on each provider's typed request which extends\n * this and narrows `model`.\n */\nexport type CommonTranscribeRequest = {\n  readonly audio: AudioSource\n  /** Model identifier. Each provider narrows to its typed literal union. */\n  readonly model: string\n  /** ISO-639-1 / BCP-47. Omit for autodetection (where supported). */\n  readonly language?: string\n  /**\n   * Vocab biasing. Single-string covers OpenAI/Whisper-style prompts;\n   * `terms[]` covers Deepgram `keyterm`, Google adaptation phrases, AWS\n   * `vocabularyName`. Providers ignore what they don't support.\n   */\n  readonly prompt?: string | { readonly terms: ReadonlyArray<string> }\n  readonly diarization?: boolean\n  readonly wordTimestamps?: boolean\n}\n\n/**\n * Streaming-transcription request. `inputFormat` declares what the\n * bytes in the input stream will look like — providers reject\n * mismatches at stream startup with `AiError.InvalidRequest`.\n */\nexport type CommonStreamTranscribeRequest = Omit<CommonTranscribeRequest, \"audio\"> & {\n  readonly inputFormat: AudioFormat\n  readonly interimResults?: boolean\n  readonly vadEvents?: boolean\n}\n\nexport type TranscriberService = {\n  /**\n   * One-shot transcription. Universal — AWS Transcribe (which has no\n   * native sync endpoint) emulates this by draining a streaming session\n   * internally.\n   */\n  readonly transcribe: (\n    request: CommonTranscribeRequest,\n  ) => Effect.Effect<TranscriptResult, AiError.AiError>\n  /**\n   * Live transcription as a Stream transformer. Consumes audio bytes\n   * from `audioIn`; emits `TranscriptEvent`s as they arrive. The\n   * underlying WS / gRPC connection is acquired on first pull and\n   * released when the output stream is finalized (success, failure, or\n   * interruption) via `Stream.scoped` — no explicit Scope handling at\n   * the call site.\n   *\n   * Gated by the `SttStreaming` capability marker on the top-level\n   * helper — providers without streaming-STT support don't ship the\n   * marker, so calls fail at `Effect.provide` with a type error.\n   */\n  readonly streamTranscriptionFrom: <E, R>(\n    audioIn: Stream.Stream<Uint8Array, E, R>,\n    request: CommonStreamTranscribeRequest,\n  ) => Stream.Stream<TranscriptEvent, AiError.AiError | E, R>\n}\n\nexport class Transcriber extends Context.Service<Transcriber, TranscriberService>()(\n  \"@betalyra/effect-uai/Transcriber\",\n) {}\n\n/**\n * Capability marker — provided by provider layers whose\n * `streamTranscriptionFrom` is wired up at the wire level. Azure does\n * not ship it (streaming-STT is SDK-internal). Calling\n * `streamTranscriptionFrom` while only Azure's Layer is in scope fails\n * at `Effect.provide` with a type error, not at runtime.\n *\n * Phantom — the value is `void`; providers register with\n * `Layer.succeed(SttStreaming, undefined)`.\n */\nexport class SttStreaming extends Context.Service<SttStreaming, void>()(\n  \"@betalyra/effect-uai/capability/SttStreaming\",\n) {}\n\n/** One-shot transcription. */\nexport const transcribe = (\n  request: CommonTranscribeRequest,\n): Effect.Effect<TranscriptResult, AiError.AiError, Transcriber> =>\n  Effect.flatMap(Transcriber.asEffect(), (t) => t.transcribe(request))\n\n/**\n * Live transcription. Dual-arity: pipeable (data-last) and direct\n * (data-first). Requires `SttStreaming` in R — providers without\n * streaming support are a type error at provide time.\n *\n * @example\n * ```ts\n * // Pipeable — composes with other Stream operators\n * mic.frames.pipe(\n *   Transcriber.streamTranscriptionFrom(req),\n *   Stream.filter((e) => e._tag === \"final\"),\n * )\n *\n * // Direct\n * Transcriber.streamTranscriptionFrom(mic.frames, req)\n * ```\n */\nexport const streamTranscriptionFrom: {\n  (\n    request: CommonStreamTranscribeRequest,\n  ): <E, R>(\n    audioIn: Stream.Stream<Uint8Array, E, R>,\n  ) => Stream.Stream<TranscriptEvent, AiError.AiError | E, R | Transcriber | SttStreaming>\n  <E, R>(\n    audioIn: Stream.Stream<Uint8Array, E, R>,\n    request: CommonStreamTranscribeRequest,\n  ): Stream.Stream<TranscriptEvent, AiError.AiError | E, R | Transcriber | SttStreaming>\n} = Function.dual(\n  2,\n  <E, R>(audioIn: Stream.Stream<Uint8Array, E, R>, request: CommonStreamTranscribeRequest) =>\n    Stream.unwrap(\n      Effect.gen(function* () {\n        const t = yield* Transcriber.asEffect()\n        yield* SttStreaming.asEffect()\n        return t.streamTranscriptionFrom(audioIn, request)\n      }),\n    ),\n)\n"],"mappings":";;;;;;;;;AAiEA,IAAa,cAAb,cAAiC,QAAQ,SAA0C,CACjF,mCACD,CAAC;;;;;;;;;;;AAYF,IAAa,eAAb,cAAkC,QAAQ,SAA6B,CACrE,+CACD,CAAC;;AAGF,MAAa,cACX,YAEA,OAAO,QAAQ,YAAY,UAAU,GAAG,MAAM,EAAE,WAAW,QAAQ,CAAC;;;;;;;;;;;;;;;;;;AAmBtE,MAAa,0BAUT,SAAS,KACX,IACO,SAA0C,YAC/C,OAAO,OACL,OAAO,IAAI,aAAa;CACtB,MAAM,IAAI,OAAO,YAAY,UAAU;AACvC,QAAO,aAAa,UAAU;AAC9B,QAAO,EAAE,wBAAwB,SAAS,QAAQ;EAClD,CACH,CACJ"}

package/dist/transcriber/Transcriber.test.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/transcriber/Transcriber.test.mjs

@@ -0,0 +1,130 @@
+import { streamTranscriptionFrom, transcribe } from "./Transcriber.mjs";
+import { i as it, n as globalExpect, r as describe, t as import_dist } from "../dist-DV5ISja1.mjs";
+import { layer, layerSyncOnly } from "../testing/MockTranscriber.mjs";
+import { Effect, Stream } from "effect";
+//#region src/transcriber/Transcriber.test.ts
+describe("Transcriber.transcribe", () => {
+	it("returns the scripted TranscriptResult", async () => {
+		const mock = layer({ transcripts: [{
+			text: "hello world",
+			durationSeconds: 1.23
+		}] });
+		const program = transcribe({
+			audio: {
+				_tag: "bytes",
+				bytes: new Uint8Array([0]),
+				mimeType: "audio/wav"
+			},
+			model: "mock-stt"
+		});
+		const result = await Effect.runPromise(program.pipe(Effect.provide(mock.layer)));
+		globalExpect(result.text).toBe("hello world");
+		globalExpect(result.durationSeconds).toBe(1.23);
+	});
+	it("records each transcribe call", async () => {
+		const mock = layer({ transcripts: [{ text: "a" }, { text: "b" }] });
+		const program = Effect.gen(function* () {
+			yield* transcribe({
+				audio: {
+					_tag: "bytes",
+					bytes: new Uint8Array([1]),
+					mimeType: "audio/wav"
+				},
+				model: "m1"
+			});
+			yield* transcribe({
+				audio: {
+					_tag: "bytes",
+					bytes: new Uint8Array([2]),
+					mimeType: "audio/wav"
+				},
+				model: "m2"
+			});
+			return yield* mock.recorder;
+		});
+		globalExpect((await Effect.runPromise(program.pipe(Effect.provide(mock.layer)))).transcribeCalls.map((c) => c.model)).toEqual(["m1", "m2"]);
+	});
+});
+describe("Transcriber capability marker (compile-time)", () => {
+	const sttReq = {
+		model: "mock-stt",
+		inputFormat: {
+			container: "raw",
+			encoding: "pcm_s16le",
+			sampleRate: 16e3
+		}
+	};
+	it("requires `SttStreaming` on the R channel of streamTranscriptionFrom", () => {
+		(0, import_dist.expectTypeOf)(Stream.fromIterable([new Uint8Array([0])]).pipe(streamTranscriptionFrom(sttReq))).toEqualTypeOf();
+	});
+	it("does NOT require `SttStreaming` for sync `transcribe`", () => {
+		(0, import_dist.expectTypeOf)(transcribe({
+			audio: {
+				_tag: "bytes",
+				bytes: new Uint8Array([0]),
+				mimeType: "audio/wav"
+			},
+			model: "m"
+		})).toEqualTypeOf();
+	});
+	it("a sync-only layer leaves `SttStreaming` unsatisfied in R", () => {
+		const syncOnly = layerSyncOnly({});
+		const events = Stream.fromIterable([new Uint8Array([0])]).pipe(streamTranscriptionFrom(sttReq));
+		(0, import_dist.expectTypeOf)(Stream.runDrain(events).pipe(Effect.provide(syncOnly.layer))).toEqualTypeOf();
+	});
+	it("a full layer (with marker) clears R to never", () => {
+		const fullMock = layer({ streams: [[]] });
+		const events = Stream.fromIterable([new Uint8Array([0])]).pipe(streamTranscriptionFrom(sttReq));
+		(0, import_dist.expectTypeOf)(Stream.runDrain(events).pipe(Effect.provide(fullMock.layer))).toEqualTypeOf();
+	});
+});
+describe("Transcriber.streamTranscriptionFrom", () => {
+	const sttReq = {
+		model: "mock-stt",
+		inputFormat: {
+			container: "raw",
+			encoding: "pcm_s16le",
+			sampleRate: 16e3
+		}
+	};
+	it("emits scripted events after draining the input audio stream", async () => {
+		const mock = layer({ streams: [[{
+			_tag: "partial",
+			text: "hello"
+		}, {
+			_tag: "final",
+			text: "hello world"
+		}]] });
+		const events = Stream.fromIterable([new Uint8Array([
+			0,
+			1,
+			2
+		]), new Uint8Array([
+			3,
+			4,
+			5
+		])]).pipe(streamTranscriptionFrom(sttReq));
+		globalExpect(await Effect.runPromise(Stream.runCollect(events).pipe(Effect.provide(mock.layer)))).toEqual([{
+			_tag: "partial",
+			text: "hello"
+		}, {
+			_tag: "final",
+			text: "hello world"
+		}]);
+	});
+	it("works data-first (direct call) as well as pipeable (data-last)", async () => {
+		const mock = layer({ streams: [[{
+			_tag: "final",
+			text: "x"
+		}]] });
+		const events = streamTranscriptionFrom(Stream.fromIterable([new Uint8Array([0])]), sttReq);
+		globalExpect(await Effect.runPromise(Stream.runCollect(events).pipe(Effect.provide(mock.layer)))).toEqual([{
+			_tag: "final",
+			text: "x"
+		}]);
+	});
+});
+//#endregion
+export {};
+
+//# sourceMappingURL=Transcriber.test.mjs.map

package/dist/transcriber/Transcriber.test.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Transcriber.test.mjs","names":["MockTranscriber.layer","Transcriber.transcribe","Transcriber.streamTranscriptionFrom","MockTranscriber.layerSyncOnly"],"sources":["../../src/transcriber/Transcriber.test.ts"],"sourcesContent":["import { Effect, Stream } from \"effect\"\nimport { describe, expect, expectTypeOf, it } from \"vitest\"\nimport type * as AiError from \"../domain/AiError.js\"\nimport type { TranscriptEvent, TranscriptResult } from \"../domain/Transcript.js\"\nimport * as MockTranscriber from \"../testing/MockTranscriber.js\"\nimport * as Transcriber from \"./Transcriber.js\"\n\ndescribe(\"Transcriber.transcribe\", () => {\n  it(\"returns the scripted TranscriptResult\", async () => {\n    const mock = MockTranscriber.layer({\n      transcripts: [{ text: \"hello world\", durationSeconds: 1.23 }],\n    })\n    const program = Transcriber.transcribe({\n      audio: { _tag: \"bytes\", bytes: new Uint8Array([0]), mimeType: \"audio/wav\" },\n      model: \"mock-stt\",\n    })\n    const result = await Effect.runPromise(program.pipe(Effect.provide(mock.layer)))\n    expect(result.text).toBe(\"hello world\")\n    expect(result.durationSeconds).toBe(1.23)\n  })\n\n  it(\"records each transcribe call\", async () => {\n    const mock = MockTranscriber.layer({\n      transcripts: [{ text: \"a\" }, { text: \"b\" }],\n    })\n    const program = Effect.gen(function* () {\n      yield* Transcriber.transcribe({\n        audio: { _tag: \"bytes\", bytes: new Uint8Array([1]), mimeType: \"audio/wav\" },\n        model: \"m1\",\n      })\n      yield* Transcriber.transcribe({\n        audio: { _tag: \"bytes\", bytes: new Uint8Array([2]), mimeType: \"audio/wav\" },\n        model: \"m2\",\n      })\n      return yield* mock.recorder\n    })\n    const rec = await Effect.runPromise(program.pipe(Effect.provide(mock.layer)))\n    expect(rec.transcribeCalls.map((c) => c.model)).toEqual([\"m1\", \"m2\"])\n  })\n})\n\ndescribe(\"Transcriber capability marker (compile-time)\", () => {\n  const sttReq: Transcriber.CommonStreamTranscribeRequest = {\n    model: \"mock-stt\",\n    inputFormat: { container: \"raw\", encoding: \"pcm_s16le\", sampleRate: 16000 },\n  }\n\n  it(\"requires `SttStreaming` on the R channel of streamTranscriptionFrom\", () => {\n    const audio: Stream.Stream<Uint8Array> = Stream.fromIterable([new Uint8Array([0])])\n    const events = audio.pipe(Transcriber.streamTranscriptionFrom(sttReq))\n    expectTypeOf(events).toEqualTypeOf<\n      Stream.Stream<\n        TranscriptEvent,\n        AiError.AiError,\n        Transcriber.Transcriber | Transcriber.SttStreaming\n      >\n    >()\n  })\n\n  it(\"does NOT require `SttStreaming` for sync `transcribe`\", () => {\n    const eff = Transcriber.transcribe({\n      audio: { _tag: \"bytes\", bytes: new Uint8Array([0]), mimeType: \"audio/wav\" },\n      model: \"m\",\n    })\n    expectTypeOf(eff).toEqualTypeOf<\n      Effect.Effect<TranscriptResult, AiError.AiError, Transcriber.Transcriber>\n    >()\n  })\n\n  it(\"a sync-only layer leaves `SttStreaming` unsatisfied in R\", () => {\n    const syncOnly = MockTranscriber.layerSyncOnly({})\n    const audio: Stream.Stream<Uint8Array> = Stream.fromIterable([new Uint8Array([0])])\n    const events = audio.pipe(Transcriber.streamTranscriptionFrom(sttReq))\n    const program = Stream.runDrain(events).pipe(Effect.provide(syncOnly.layer))\n    // `Transcriber` is provided by syncOnly.layer; `SttStreaming` is not.\n    expectTypeOf(program).toEqualTypeOf<\n      Effect.Effect<void, AiError.AiError, Transcriber.SttStreaming>\n    >()\n  })\n\n  it(\"a full layer (with marker) clears R to never\", () => {\n    const fullMock = MockTranscriber.layer({ streams: [[]] })\n    const audio: Stream.Stream<Uint8Array> = Stream.fromIterable([new Uint8Array([0])])\n    const events = audio.pipe(Transcriber.streamTranscriptionFrom(sttReq))\n    const program = Stream.runDrain(events).pipe(Effect.provide(fullMock.layer))\n    expectTypeOf(program).toEqualTypeOf<Effect.Effect<void, AiError.AiError, never>>()\n  })\n})\n\ndescribe(\"Transcriber.streamTranscriptionFrom\", () => {\n  const sttReq: Transcriber.CommonStreamTranscribeRequest = {\n    model: \"mock-stt\",\n    inputFormat: { container: \"raw\", encoding: \"pcm_s16le\", sampleRate: 16000 },\n  }\n\n  it(\"emits scripted events after draining the input audio stream\", async () => {\n    const mock = MockTranscriber.layer({\n      streams: [\n        [\n          { _tag: \"partial\", text: \"hello\" },\n          { _tag: \"final\", text: \"hello world\" },\n        ],\n      ],\n    })\n    const audio = Stream.fromIterable([new Uint8Array([0, 1, 2]), new Uint8Array([3, 4, 5])])\n    const events = audio.pipe(Transcriber.streamTranscriptionFrom(sttReq))\n    const collected = await Effect.runPromise(\n      Stream.runCollect(events).pipe(Effect.provide(mock.layer)),\n    )\n    expect(collected).toEqual([\n      { _tag: \"partial\", text: \"hello\" },\n      { _tag: \"final\", text: \"hello world\" },\n    ])\n  })\n\n  it(\"works data-first (direct call) as well as pipeable (data-last)\", async () => {\n    const mock = MockTranscriber.layer({\n      streams: [[{ _tag: \"final\", text: \"x\" }]],\n    })\n    const audio = Stream.fromIterable([new Uint8Array([0])])\n    const events = Transcriber.streamTranscriptionFrom(audio, sttReq)\n    const out = await Effect.runPromise(Stream.runCollect(events).pipe(Effect.provide(mock.layer)))\n    expect(out).toEqual([{ _tag: \"final\", text: \"x\" }])\n  })\n})\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effect-uai/core",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Low-level primitives (loop, conversation, items, tools, streaming codecs) for building AI agents with Effect.",
   "keywords": [
     "agents",
@@ -38,6 +38,10 @@
       "types": "./dist/domain/AiError.d.mts",
       "import": "./dist/domain/AiError.mjs"
     },
+    "./Audio": {
+      "types": "./dist/domain/Audio.d.mts",
+      "import": "./dist/domain/Audio.mjs"
+    },
     "./Image": {
       "types": "./dist/domain/Image.d.mts",
       "import": "./dist/domain/Image.mjs"
@@ -50,6 +54,14 @@
       "types": "./dist/domain/Media.d.mts",
       "import": "./dist/domain/Media.mjs"
     },
+    "./Music": {
+      "types": "./dist/domain/Music.d.mts",
+      "import": "./dist/domain/Music.mjs"
+    },
+    "./Transcript": {
+      "types": "./dist/domain/Transcript.d.mts",
+      "import": "./dist/domain/Transcript.mjs"
+    },
     "./Turn": {
       "types": "./dist/domain/Turn.d.mts",
       "import": "./dist/domain/Turn.mjs"
@@ -66,6 +78,18 @@
       "types": "./dist/language-model/LanguageModel.d.mts",
       "import": "./dist/language-model/LanguageModel.mjs"
     },
+    "./MusicGenerator": {
+      "types": "./dist/music-generator/MusicGenerator.d.mts",
+      "import": "./dist/music-generator/MusicGenerator.mjs"
+    },
+    "./SpeechSynthesizer": {
+      "types": "./dist/speech-synthesizer/SpeechSynthesizer.d.mts",
+      "import": "./dist/speech-synthesizer/SpeechSynthesizer.mjs"
+    },
+    "./Transcriber": {
+      "types": "./dist/transcriber/Transcriber.d.mts",
+      "import": "./dist/transcriber/Transcriber.mjs"
+    },
     "./Loop": {
       "types": "./dist/loop/Loop.d.mts",
       "import": "./dist/loop/Loop.mjs"
@@ -121,6 +145,18 @@
     "./testing/MockProvider": {
       "types": "./dist/testing/MockProvider.d.mts",
       "import": "./dist/testing/MockProvider.mjs"
+    },
+    "./testing/MockMusicGenerator": {
+      "types": "./dist/testing/MockMusicGenerator.d.mts",
+      "import": "./dist/testing/MockMusicGenerator.mjs"
+    },
+    "./testing/MockSpeechSynthesizer": {
+      "types": "./dist/testing/MockSpeechSynthesizer.d.mts",
+      "import": "./dist/testing/MockSpeechSynthesizer.mjs"
+    },
+    "./testing/MockTranscriber": {
+      "types": "./dist/testing/MockTranscriber.d.mts",
+      "import": "./dist/testing/MockTranscriber.mjs"
     }
   },
   "publishConfig": {

package/src/domain/AiError.ts

@@ -72,7 +72,7 @@ export class GenerationFailed extends Data.TaggedError("GenerationFailed")<{
 }> {}
 
 /**
- * The provider's delta stream ended without a terminal `turn_complete`.
+ * The provider's delta stream ended without a terminal `TurnComplete`.
  * Indicates a misbehaving provider or a connection that dropped mid-flight.
  * Non-terminal deltas seen so far have already been emitted downstream.
  */
@@ -80,6 +80,26 @@ export class IncompleteTurn extends Data.TaggedError("IncompleteTurn")<{
   raw?: unknown
 }> {}
 
+/**
+ * The provider does not implement the requested capability for this
+ * specific request. Distinct from `InvalidRequest` (the request shape is
+ * malformed) and `AuthFailed` (the request was rejected).
+ *
+ * Reserved for request-data-dependent gaps where the provider supports
+ * the method in general but not for these inputs — e.g. Google's
+ * `streamSynthesisFrom` works only for Chirp 3 HD voices; calling it
+ * with a Neural2 voice ID fails `Unsupported`.
+ *
+ * Blanket provider-level gaps (e.g. OpenAI has no incremental-text-in
+ * TTS at all) are gated at compile time via capability marker tags
+ * (`TtsIncrementalText`, `SttStreaming`) on the R channel instead.
+ */
+export class Unsupported extends Data.TaggedError("Unsupported")<{
+  provider: string
+  capability: string
+  reason?: string
+}> {}
+
 export type AiError =
   | RateLimited
   | Unavailable
@@ -91,3 +111,4 @@ export type AiError =
   | Cancelled
   | IncompleteTurn
   | GenerationFailed
+  | Unsupported

package/src/domain/Audio.ts

@@ -0,0 +1,88 @@
+import type { MediaBase64, MediaBytes, MediaUrl } from "./Media.js"
+
+/**
+ * MIME types we care about across STT input and TTS output. Container-
+ * level only — sample rate / encoding flavours live on `AudioFormat`.
+ *
+ * Per-provider request types narrow this further. The `(string & {})`
+ * tail keeps autocomplete on the literals while still accepting any
+ * string, so unusual formats work without an SDK update.
+ */
+export type AudioMimeType =
+  | "audio/mpeg"
+  | "audio/wav"
+  | "audio/x-wav"
+  | "audio/ogg"
+  | "audio/opus"
+  | "audio/flac"
+  | "audio/aac"
+  | "audio/mp4"
+  | "audio/webm"
+  | "audio/L16"
+  | "audio/pcm"
+  | "audio/mulaw"
+  | "audio/alaw"
+  // eslint-disable-next-line @typescript-eslint/ban-types
+  | (string & {})
+
+/**
+ * Audio at rest — instantiates `MediaSource` with the audio MIME union.
+ * Used for sync STT input.
+ *
+ * URL variant is best-effort: some providers (OpenAI, Cartesia, Azure
+ * short-audio) reject URL ingestion and the adapter must upload via the
+ * `bytes` or `base64` variant instead. Adapter layers reject unsupported
+ * shapes up front with `AiError.InvalidRequest`.
+ */
+export type AudioSource =
+  | MediaUrl<AudioMimeType>
+  | MediaBase64<AudioMimeType>
+  | MediaBytes<AudioMimeType>
+
+export const isAudioUrl = (s: AudioSource): s is MediaUrl<AudioMimeType> => s._tag === "url"
+export const isAudioBase64 = (s: AudioSource): s is MediaBase64<AudioMimeType> =>
+  s._tag === "base64"
+export const isAudioBytes = (s: AudioSource): s is MediaBytes<AudioMimeType> => s._tag === "bytes"
+
+/**
+ * Structural audio format. Used both as TTS output spec and as STT
+ * streaming-input declaration. Providers that use compound slugs
+ * (`mp3_44100_128`, `audio-16khz-128kbitrate-mono-mp3`,
+ * `aura-2-thalia-en`) are encoded at the adapter layer.
+ */
+export type AudioFormat = {
+  readonly container: "mp3" | "wav" | "ogg" | "opus" | "flac" | "aac" | "webm" | "raw"
+  readonly encoding:
+    | "pcm_s16le"
+    | "pcm_f32le"
+    | "pcm_mulaw"
+    | "pcm_alaw"
+    | "mp3"
+    | "opus"
+    | "vorbis"
+    | "flac"
+    | "aac"
+  readonly sampleRate: 8000 | 16000 | 22050 | 24000 | 32000 | 44100 | 48000
+  /** mp3 / opus only. */
+  readonly bitRate?: number
+  readonly channels?: 1 | 2
+}
+
+/**
+ * Streamed audio chunk. `bytes` carries the codec-encoded payload as
+ * declared on the stream's `AudioFormat`. No per-chunk timestamp here —
+ * providers that emit timing do so via `TranscriptEvent.words[]`.
+ */
+export type AudioChunk = {
+  readonly bytes: Uint8Array
+}
+
+/**
+ * Full audio result for sync TTS. Format mirrors the request; provider
+ * layers normalize.
+ */
+export type AudioBlob = {
+  readonly format: AudioFormat
+  readonly bytes: Uint8Array
+  readonly durationSeconds?: number
+}

package/src/domain/Items.ts

@@ -82,7 +82,7 @@ export type OutputText = typeof OutputText.Type
  * Model-emitted refusal. Distinct from `output_text`: the model declined
  * to answer rather than producing normal output. Pair with
  * `stop_reason: "refusal"` on the surrounding `Turn`. Streamed via the
- * `refusal_delta` `TurnEvent`.
+ * `RefusalDelta` `TurnEvent`.
  */
 export const Refusal = Schema.Struct({
   type: Schema.Literal("refusal"),

package/src/domain/Music.ts

@@ -0,0 +1,121 @@
+import type { AudioBlob, AudioFormat } from "./Audio.js"
+
+/**
+ * Prompt fragment with a relative weight. Native to Lyria RealTime
+ * (`{ text, weight }` pairs blended in the model). Single-prompt
+ * providers (Suno, Mureka, MiniMax) flatten to text at the adapter
+ * layer.
+ */
+export type WeightedPrompt = {
+  readonly text: string
+  /** Default `1.0`. Range typically `[0, 1]`; provider-dependent. */
+  readonly weight?: number
+}
+
+/**
+ * Cross-provider music-generation request. Provider-specific extras
+ * (Lyria `mode`, ElevenLabs `composition_plan`, Suno custom-mode `title`,
+ * MiniMax `lyrics_optimizer`) live on each provider's typed request
+ * which extends this and narrows `model`.
+ */
+export type CommonGenerateMusicRequest = {
+  /** Model identifier. Each provider narrows. */
+  readonly model: string
+  /** Single prompt string or weighted-prompt list (blended where supported). */
+  readonly prompts: string | ReadonlyArray<WeightedPrompt>
+  /**
+   * Lyrics text, optionally with section tags like `[Verse]` / `[Chorus]` /
+   * `[Bridge]` / `[Outro]`. Ignored for instrumental-only providers or
+   * when `instrumental: true`.
+   */
+  readonly lyrics?: string
+  /** Target duration in seconds. Provider may treat as a hint or hard limit. */
+  readonly durationSeconds?: number
+  /** Beats per minute (60–200 typical). */
+  readonly bpm?: number
+  /**
+   * Musical key/mode hint. Provider-specific vocabulary (e.g. Lyria
+   * RealTime uses enum values like `"C_MAJOR"`, `"A_MINOR"`).
+   */
+  readonly scale?: string
+  /** Skip vocals / lyrics. */
+  readonly instrumental?: boolean
+  /** Preferred output format. Provider may override. */
+  readonly outputFormat?: AudioFormat
+}
+
+/**
+ * Streamed-output request. Same shape as the sync request — the
+ * streaming variant only differs in how the response is delivered.
+ */
+export type CommonStreamGenerateMusicRequest = CommonGenerateMusicRequest
+
+/**
+ * Bidirectional-session input. The user pushes one of these per
+ * change: a new prompt blend, a config delta, or a playback control.
+ * Lyria RealTime is the only provider currently surfacing these.
+ */
+export type MusicSessionInput =
+  | { readonly _tag: "prompts"; readonly prompts: ReadonlyArray<WeightedPrompt> }
+  | {
+      readonly _tag: "config"
+      readonly config: {
+        readonly bpm?: number
+        readonly scale?: string
+        readonly density?: number
+        readonly brightness?: number
+        readonly guidance?: number
+        readonly temperature?: number
+        readonly topK?: number
+        readonly seed?: number
+        readonly muteBass?: boolean
+        readonly muteDrums?: boolean
+        readonly onlyBassAndDrums?: boolean
+      }
+    }
+  | { readonly _tag: "control"; readonly action: "play" | "pause" | "stop" | "reset_context" }
+
+export const promptsInput = (prompts: ReadonlyArray<WeightedPrompt>): MusicSessionInput => ({
+  _tag: "prompts",
+  prompts,
+})
+
+export const configInput = (
+  config: (MusicSessionInput & { _tag: "config" })["config"],
+): MusicSessionInput => ({ _tag: "config", config })
+
+export const controlInput = (
+  action: (MusicSessionInput & { _tag: "control" })["action"],
+): MusicSessionInput => ({ _tag: "control", action })
+
+/**
+ * Sync-generation result. Extends `AudioBlob` with provider-side
+ * metadata that's common across music providers:
+ *
+ * - `songId` — Suno task id, ElevenLabs `song_id`, etc. Used for
+ *   back-reference (re-download, stem export, follow-up edits).
+ * - `lyrics` — generated lyrics when the model returned them (Lyria
+ *   text part, Mureka, Suno).
+ * - `sections` — structured section markers (Lyria optional JSON
+ *   structure response).
+ * - `watermark` — presence marker (Lyria SynthID is always set).
+ */
+export type MusicResult = AudioBlob & {
+  readonly songId?: string
+  readonly lyrics?: string
+  readonly sections?: ReadonlyArray<{
+    readonly label: string
+    readonly startSeconds: number
+    readonly endSeconds: number
+  }>
+  readonly watermark?: { readonly kind: string }
+}
+
+export const isPromptsInput = (
+  i: MusicSessionInput,
+): i is MusicSessionInput & { _tag: "prompts" } => i._tag === "prompts"
+export const isConfigInput = (i: MusicSessionInput): i is MusicSessionInput & { _tag: "config" } =>
+  i._tag === "config"
+export const isControlInput = (
+  i: MusicSessionInput,
+): i is MusicSessionInput & { _tag: "control" } => i._tag === "control"

package/src/domain/Transcript.ts

@@ -0,0 +1,83 @@
+/**
+ * Per-word timing + metadata. `confidence` and `speakerId` are optional
+ * because providers vary widely in what they emit and when (some only on
+ * final, some only with diarization enabled, some not at all).
+ */
+export type WordTimestamp = {
+  readonly text: string
+  readonly startSeconds: number
+  readonly endSeconds: number
+  readonly confidence?: number
+  readonly speakerId?: string
+  readonly languageCode?: string
+}
+
+/**
+ * Sync STT result. `raw` preserves the provider-specific response for
+ * consumers that need fields the common shape doesn't expose
+ * (alternatives, segments, NBest, audio events, etc.).
+ */
+export type TranscriptResult = {
+  readonly text: string
+  readonly languageCode?: string
+  readonly durationSeconds?: number
+  readonly words?: ReadonlyArray<WordTimestamp>
+  readonly raw?: unknown
+}
+
+/**
+ * Streaming STT event union. Collapses every provider's vocabulary into
+ * a small set; provider-specific shapes survive on `metadata.raw`.
+ *
+ * - `partial`: interim hypothesis. `stability` is Google-only.
+ * - `final`: committed transcript for the current utterance / segment.
+ * - `speech-started` / `utterance-ended`: VAD-derived boundaries. Not
+ *   all providers emit them (OpenAI Realtime, Google with
+ *   `voice_activity_events`, Deepgram with `vad_events`, AssemblyAI).
+ * - `audio-event`: non-speech label (`(laughter)`, `(music)`) — ElevenLabs only.
+ * - `metadata`: opaque server-side bookkeeping (request_id, model info).
+ * - `error`: non-fatal provider error mid-stream. Fatal errors surface
+ *   on the `Stream`'s error channel as `AiError.AiError`.
+ */
+export type TranscriptEvent =
+  | {
+      readonly _tag: "partial"
+      readonly text: string
+      readonly words?: ReadonlyArray<WordTimestamp>
+      readonly stability?: number
+    }
+  | {
+      readonly _tag: "final"
+      readonly text: string
+      readonly words?: ReadonlyArray<WordTimestamp>
+      readonly languageCode?: string
+    }
+  | { readonly _tag: "speech-started"; readonly atSeconds: number }
+  | { readonly _tag: "utterance-ended"; readonly atSeconds: number }
+  | {
+      readonly _tag: "audio-event"
+      readonly label: string
+      readonly startSeconds: number
+      readonly endSeconds: number
+    }
+  | { readonly _tag: "metadata"; readonly raw: unknown }
+  | { readonly _tag: "error"; readonly code?: string; readonly message: string }
+
+export const isPartial = (e: TranscriptEvent): e is Extract<TranscriptEvent, { _tag: "partial" }> =>
+  e._tag === "partial"
+export const isFinal = (e: TranscriptEvent): e is Extract<TranscriptEvent, { _tag: "final" }> =>
+  e._tag === "final"
+export const isSpeechStarted = (
+  e: TranscriptEvent,
+): e is Extract<TranscriptEvent, { _tag: "speech-started" }> => e._tag === "speech-started"
+export const isUtteranceEnded = (
+  e: TranscriptEvent,
+): e is Extract<TranscriptEvent, { _tag: "utterance-ended" }> => e._tag === "utterance-ended"
+export const isAudioEvent = (
+  e: TranscriptEvent,
+): e is Extract<TranscriptEvent, { _tag: "audio-event" }> => e._tag === "audio-event"
+export const isMetadata = (
+  e: TranscriptEvent,
+): e is Extract<TranscriptEvent, { _tag: "metadata" }> => e._tag === "metadata"
+export const isError = (e: TranscriptEvent): e is Extract<TranscriptEvent, { _tag: "error" }> =>
+  e._tag === "error"