@effect-uai/core 0.3.0 → 0.5.0

package/src/testing/MockTranscriber.ts

@@ -0,0 +1,137 @@
+import { Effect, Layer, Ref, Stream } from "effect"
+import * as AiError from "../domain/AiError.js"
+import type { TranscriptEvent, TranscriptResult } from "../domain/Transcript.js"
+import {
+  SttStreaming,
+  Transcriber,
+  type CommonStreamTranscribeRequest,
+  type CommonTranscribeRequest,
+  type TranscriberService,
+} from "../transcriber/Transcriber.js"
+
+/**
+ * Recorder of every call made to the mock.
+ */
+export type MockTranscriberRecorder = {
+  readonly transcribeCalls: ReadonlyArray<CommonTranscribeRequest>
+  readonly streamCalls: ReadonlyArray<CommonStreamTranscribeRequest>
+}
+
+export type MockTranscriberScript = {
+  /** One result per `transcribe` call, consumed in order. */
+  readonly transcripts?: ReadonlyArray<TranscriptResult>
+  /** One event-list per `streamTranscriptionFrom` call, consumed in order. */
+  readonly streams?: ReadonlyArray<ReadonlyArray<TranscriptEvent>>
+}
+
+const makeService = (
+  script: MockTranscriberScript,
+  record: {
+    readonly transcribe: (req: CommonTranscribeRequest) => Effect.Effect<void>
+    readonly stream: (req: CommonStreamTranscribeRequest) => Effect.Effect<void>
+  },
+) =>
+  Effect.gen(function* () {
+    const tCursor = yield* Ref.make(0)
+    const sCursor = yield* Ref.make(0)
+    const service: TranscriberService = {
+      transcribe: (request) =>
+        Effect.gen(function* () {
+          yield* record.transcribe(request)
+          const i = yield* Ref.getAndUpdate(tCursor, (n) => n + 1)
+          const scripted = script.transcripts ?? []
+          if (i >= scripted.length) {
+            return yield* new AiError.InvalidRequest({
+              provider: "mock",
+              raw: `MockTranscriber exhausted: ${scripted.length} transcripts scripted, but call ${i + 1} was made`,
+            })
+          }
+          return scripted[i]!
+        }),
+      streamTranscriptionFrom: <E, R>(
+        audioIn: Stream.Stream<Uint8Array, E, R>,
+        request: CommonStreamTranscribeRequest,
+      ): Stream.Stream<TranscriptEvent, AiError.AiError | E, R> =>
+        Stream.unwrap(
+          Effect.gen(function* () {
+            yield* record.stream(request)
+            const i = yield* Ref.getAndUpdate(sCursor, (n) => n + 1)
+            const scripted = script.streams ?? []
+            if (i >= scripted.length) {
+              const exhausted: Stream.Stream<TranscriptEvent, AiError.AiError | E, R> = Stream.fail(
+                new AiError.InvalidRequest({
+                  provider: "mock",
+                  raw: `MockTranscriber exhausted: ${scripted.length} streams scripted, but call ${i + 1} was made`,
+                }),
+              )
+              return exhausted
+            }
+            // Drain the input audio fully before emitting the scripted events,
+            // so consumers can assert on what bytes were pushed.
+            return Stream.drain(audioIn).pipe(Stream.concat(Stream.fromIterable(scripted[i]!)))
+          }),
+        ),
+    }
+    return service
+  })
+
+/**
+ * Returns a Layer that provides both the `Transcriber` service and the
+ * `SttStreaming` capability marker. Use when the code under test calls
+ * `streamTranscriptionFrom`.
+ */
+export const layer = (
+  script: MockTranscriberScript,
+): {
+  readonly layer: Layer.Layer<Transcriber | SttStreaming>
+  readonly recorder: Effect.Effect<MockTranscriberRecorder>
+} => {
+  const tCalls = Ref.makeUnsafe<ReadonlyArray<CommonTranscribeRequest>>([])
+  const sCalls = Ref.makeUnsafe<ReadonlyArray<CommonStreamTranscribeRequest>>([])
+  const transcriberLayer = Layer.effect(
+    Transcriber,
+    makeService(script, {
+      transcribe: (req) => Ref.update(tCalls, (xs) => [...xs, req]),
+      stream: (req) => Ref.update(sCalls, (xs) => [...xs, req]),
+    }),
+  )
+  const live = Layer.merge(transcriberLayer, Layer.succeed(SttStreaming, undefined))
+  return {
+    layer: live,
+    recorder: Effect.gen(function* () {
+      const transcribeCalls = yield* Ref.get(tCalls)
+      const streamCalls = yield* Ref.get(sCalls)
+      return { transcribeCalls, streamCalls }
+    }),
+  }
+}
+
+/**
+ * Variant that omits the `SttStreaming` marker — use to test that
+ * consumers calling `streamTranscriptionFrom` fail to compile against
+ * a non-streaming provider.
+ */
+export const layerSyncOnly = (
+  script: MockTranscriberScript,
+): {
+  readonly layer: Layer.Layer<Transcriber>
+  readonly recorder: Effect.Effect<MockTranscriberRecorder>
+} => {
+  const tCalls = Ref.makeUnsafe<ReadonlyArray<CommonTranscribeRequest>>([])
+  const sCalls = Ref.makeUnsafe<ReadonlyArray<CommonStreamTranscribeRequest>>([])
+  const live = Layer.effect(
+    Transcriber,
+    makeService(script, {
+      transcribe: (req) => Ref.update(tCalls, (xs) => [...xs, req]),
+      stream: (req) => Ref.update(sCalls, (xs) => [...xs, req]),
+    }),
+  )
+  return {
+    layer: live,
+    recorder: Effect.gen(function* () {
+      const transcribeCalls = yield* Ref.get(tCalls)
+      const streamCalls = yield* Ref.get(sCalls)
+      return { transcribeCalls, streamCalls }
+    }),
+  }
+}

package/src/tool/Resolvers.test.ts

@@ -22,8 +22,8 @@ import {
   fromVerdictQueue,
 } from "./Resolvers.js"
 import { fromEffectSchema, make as makeTool, streaming } from "./Tool.js"
-import { executeAll, outputEvent, outputEvents } from "./Toolkit.js"
-import { type ToolEvent, isApprovalRequested, isIntermediate, isOutput } from "./ToolEvent.js"
+import { executeAll } from "./Toolkit.js"
+import { ToolEvent, isApprovalRequested, isIntermediate, isOutput } from "./ToolEvent.js"
 
 // ---------------------------------------------------------------------------
 // Three demo tools covering the matrix:
@@ -91,15 +91,18 @@ const resultsFrom = (collected: ReadonlyArray<ToolEvent>): ReadonlyArray<ToolRes
 
 const byCallId = (results: ReadonlyArray<ToolResult>) => new Map(results.map((r) => [r.call_id, r]))
 
+const rejectedStream = (rejected: ReadonlyArray<ToolResult>) =>
+  Stream.fromIterable(rejected.map((result) => ToolEvent.Output({ result })))
+
 const eventsFromApprovalMap = (approvals: ReadonlyMap<string, ApprovalMapEntry>) => {
   const plan = fromApprovalMap(isSensitive, approvals)(calls)
-  return Stream.merge(executeAll(allTools, plan.approved), outputEvents(plan.rejected))
+  return Stream.merge(executeAll(allTools, plan.approved), rejectedStream(plan.rejected))
 }
 
 const eventsFromDecision = (decision: ToolCallDecision): Stream.Stream<ToolEvent> =>
   decision._tag === "Approved"
     ? executeAll(allTools, [decision.call])
-    : Stream.succeed(outputEvent(decision.result))
+    : Stream.succeed(ToolEvent.Output({ result: decision.result }))
 
 // ---------------------------------------------------------------------------
 // fromApprovalMap: HTTP-style scenarios
@@ -189,7 +192,7 @@ describe("executeAll: graceful degradation", () => {
             isSensitive,
             new Map([["c3", { decision: "approve" }]]),
           )(callsWithBogus)
-          return Stream.merge(executeAll(allTools, plan.approved), outputEvents(plan.rejected))
+          return Stream.merge(executeAll(allTools, plan.approved), rejectedStream(plan.rejected))
         })(),
       ),
     )

package/src/tool/Resolvers.ts

@@ -5,29 +5,27 @@
  * results must be returned to the model. Tool execution stays explicit at
  * the recipe boundary via `Toolkit.executeAll`.
  */
-import { Deferred, Effect, Queue, Scope, Stream } from "effect"
+import { Data, Deferred, Effect, Queue, Scope, Stream } from "effect"
 import type { FunctionCall } from "../domain/Items.js"
 import { type ToolResult, cancelled, denied } from "./Outcome.js"
-import type { ToolEvent } from "./ToolEvent.js"
+import { ToolEvent } from "./ToolEvent.js"
 
 export type ToolCallPlan = {
   readonly approved: ReadonlyArray<FunctionCall>
   readonly rejected: ReadonlyArray<ToolResult>
 }
 
-export type ToolCallDecision =
-  | { readonly _tag: "Approved"; readonly call: FunctionCall }
-  | { readonly _tag: "Rejected"; readonly result: ToolResult }
+export type ToolCallDecision = Data.TaggedEnum<{
+  Approved: { readonly call: FunctionCall }
+  Rejected: { readonly result: ToolResult }
+}>
 
-export const approve = (call: FunctionCall): ToolCallDecision => ({
-  _tag: "Approved",
-  call,
-})
+export const ToolCallDecision = Data.taggedEnum<ToolCallDecision>()
 
-export const reject = (result: ToolResult): ToolCallDecision => ({
-  _tag: "Rejected",
-  result,
-})
+export const approve = (call: FunctionCall): ToolCallDecision => ToolCallDecision.Approved({ call })
+
+export const reject = (result: ToolResult): ToolCallDecision =>
+  ToolCallDecision.Rejected({ result })
 
 export const splitToolCallDecisions = (decisions: ReadonlyArray<ToolCallDecision>): ToolCallPlan =>
   decisions.reduce<ToolCallPlan>(
@@ -38,12 +36,12 @@ export const splitToolCallDecisions = (decisions: ReadonlyArray<ToolCallDecision
     { approved: [], rejected: [] },
   )
 
-export const approvalRequested = (call: FunctionCall): ToolEvent => ({
-  _tag: "ApprovalRequested",
-  call_id: call.call_id,
-  tool: call.name,
-  arguments: call.arguments,
-})
+export const approvalRequested = (call: FunctionCall): ToolEvent =>
+  ToolEvent.ApprovalRequested({
+    call_id: call.call_id,
+    tool: call.name,
+    arguments: call.arguments,
+  })
 
 // ---------------------------------------------------------------------------
 // Verdict queue (WebSocket-style transport).

package/src/tool/Tool.test.ts

@@ -0,0 +1,105 @@
+import type { StandardJSONSchemaV1, StandardSchemaV1 } from "@standard-schema/spec"
+import { Effect } from "effect"
+import { describe, expect, expectTypeOf, it } from "vitest"
+import * as Tool from "./Tool.js"
+
+// ---------------------------------------------------------------------------
+// Minimal dual-standard schema for testing — no need to pull Zod / Valibot /
+// ArkType as devDeps. This is the smallest possible object satisfying both
+// `StandardSchemaV1` and `StandardJSONSchemaV1` per their published specs.
+// ---------------------------------------------------------------------------
+
+type EmailRecipient = { readonly to: string }
+
+const emailRecipientSchema: StandardSchemaV1<unknown, EmailRecipient> &
+  StandardJSONSchemaV1<unknown, EmailRecipient> = {
+  "~standard": {
+    version: 1,
+    vendor: "test-fixture",
+    validate: (value) => {
+      if (
+        typeof value === "object" &&
+        value !== null &&
+        "to" in value &&
+        typeof (value as { to: unknown }).to === "string"
+      ) {
+        return { value: value as EmailRecipient }
+      }
+      return { issues: [{ message: "expected { to: string }" }] }
+    },
+    jsonSchema: {
+      input: () => ({
+        type: "object",
+        properties: { to: { type: "string" } },
+        required: ["to"],
+      }),
+      output: () => ({
+        type: "object",
+        properties: { to: { type: "string" } },
+        required: ["to"],
+      }),
+    },
+  },
+}
+
+// A schema that satisfies StandardSchemaV1 only (no JSON Schema). Used to
+// verify the helper's compile-time guard.
+const standardOnly: StandardSchemaV1<unknown, EmailRecipient> = {
+  "~standard": {
+    version: 1,
+    vendor: "test-fixture",
+    validate: () => ({ value: { to: "" } }),
+  },
+}
+
+describe("Tool.fromStandardSchema", () => {
+  it("returns the schema (structurally) typed as ToolInputSchema<Output>", () => {
+    const adapted = Tool.fromStandardSchema(emailRecipientSchema)
+
+    // Same object — helper is a type-narrowing identity at runtime.
+    expect(adapted).toBe(emailRecipientSchema)
+
+    // Both interfaces accessible through the same `~standard` key.
+    const valid = adapted["~standard"].validate({ to: "hi@example.com" })
+    expect(valid).toEqual({ value: { to: "hi@example.com" } })
+
+    const json = adapted["~standard"].jsonSchema.input({ target: "draft-2020-12" })
+    expect(json).toEqual({
+      type: "object",
+      properties: { to: { type: "string" } },
+      required: ["to"],
+    })
+  })
+
+  it("composes with Tool.make so Input is inferred from the schema's Output", async () => {
+    const sendEmail = Tool.make({
+      name: "send_email",
+      description: "Send an email to a single recipient.",
+      inputSchema: Tool.fromStandardSchema(emailRecipientSchema),
+      run: ({ to }) => Effect.succeed(`queued: ${to}`),
+    })
+
+    // `run`'s parameter is typed as { to: string } via the schema's Output —
+    // this property access compiles without annotation.
+    const result = await Effect.runPromise(sendEmail.run({ to: "x@y.z" }))
+    expect(result).toBe("queued: x@y.z")
+  })
+
+  it("type: rejects schemas missing the Standard JSON Schema half at compile time", () => {
+    // @ts-expect-error — `standardOnly` lacks `jsonSchema`; helper's
+    // intersection constraint refuses it.
+    Tool.fromStandardSchema(standardOnly)
+  })
+
+  it("type: Output type flows through fromStandardSchema into Tool.make", () => {
+    const tool = Tool.make({
+      name: "send_email",
+      description: "send",
+      inputSchema: Tool.fromStandardSchema(emailRecipientSchema),
+      run: (input) => Effect.succeed(input),
+    })
+
+    type InputOf<T> = T extends Tool.Tool<string, infer I, unknown, never> ? I : never
+    expectTypeOf<InputOf<typeof tool>>().toEqualTypeOf<EmailRecipient>()
+  })
+})

package/src/tool/Tool.ts

@@ -36,6 +36,26 @@ export const fromEffectSchema = <S extends Schema.Codec<any, any, never, any>>(
   Schema.toStandardJSONSchemaV1(Schema.toStandardSchemaV1(schema)) as unknown as S &
     ToolInputSchema<S["Type"]>
 
+/**
+ * Use any schema library that implements both Standard Schema (validation)
+ * and Standard JSON Schema (JSON Schema generation) as a `Tool.inputSchema`.
+ * Covers Zod 4.2+, Valibot 1.2+, and ArkType 2.1.28+ in one helper.
+ *
+ * Effect Schema doesn't implement Standard JSON Schema natively — use
+ * `fromEffectSchema` for those.
+ *
+ * The intersection constraint catches missing interfaces at compile time:
+ * a Zod v3 schema (no Standard JSON Schema) produces a precise type error
+ * pointing at the missing interface rather than a runtime surprise. The
+ * helper itself is a thin type-narrowing identity — schemas that satisfy
+ * both standards already structurally satisfy `ToolInputSchema`; the
+ * helper makes the input type inference explicit at the call site.
+ */
+export const fromStandardSchema = <S extends StandardSchemaV1 & StandardJSONSchemaV1>(
+  schema: S,
+): S & ToolInputSchema<StandardSchemaV1.InferOutput<S>> =>
+  schema as S & ToolInputSchema<StandardSchemaV1.InferOutput<S>>
+
 export type Tool<Name extends string, Input, Output, R = never> = {
   readonly name: Name
   readonly description: string

package/src/tool/Toolkit.ts

@@ -1,4 +1,4 @@
-import { Array as Arr, Effect, Function, Ref, Stream } from "effect"
+import { Array as Arr, Effect, Function, Ref, Schema, Stream } from "effect"
 import * as Loop from "../loop/Loop.js"
 import type { FunctionCall } from "../domain/Items.js"
 import {
@@ -10,8 +10,8 @@ import {
   type Tool,
   type ToolDescriptor,
 } from "./Tool.js"
-import { type ToolResult, executionError, rejected } from "./Outcome.js"
-import type { ToolEvent } from "./ToolEvent.js"
+import { ToolResult, executionError, rejected } from "./Outcome.js"
+import { ToolEvent } from "./ToolEvent.js"
 import { isOutput } from "./ToolEvent.js"
 
 export type AnyTool = Tool<string, any, any, any>
@@ -52,7 +52,12 @@ export const toDescriptors = <Tools extends ReadonlyArray<AnyTool>>(
       target: "draft-2020-12",
     })
     return tool.strict !== undefined
-      ? { name: tool.name, description: tool.description, inputSchema, strict: tool.strict }
+      ? {
+          name: tool.name,
+          description: tool.description,
+          inputSchema,
+          strict: tool.strict,
+        }
       : { name: tool.name, description: tool.description, inputSchema }
   })
 
@@ -78,17 +83,12 @@ export const executeAll = <Tools extends ReadonlyArray<AnyKindTool<any>>>(
     }),
   )
 
-export const outputEvent = (result: ToolResult): ToolEvent => ({ _tag: "Output", result })
-
-export const outputEvents = (results: ReadonlyArray<ToolResult>): Stream.Stream<ToolEvent> =>
-  Stream.fromIterable(results.map(outputEvent))
-
-const valueResult = (call: FunctionCall, tool: string, value: unknown): ToolResult => ({
-  _tag: "Value",
-  call_id: call.call_id,
-  tool,
-  value,
-})
+const valueResult = (call: FunctionCall, tool: string, value: unknown): ToolResult =>
+  ToolResult.Value({
+    call_id: call.call_id,
+    tool,
+    value,
+  })
 
 const runOne = <R>(
   tools: ReadonlyArray<AnyKindTool<R>>,
@@ -98,25 +98,27 @@ const runOne = <R>(
   if (tool === undefined) {
     // Graceful: emit a synthetic Failure so OTHER calls in this turn
     // still execute. LLMs hallucinate tool names; MCP tools come and go.
-    return Stream.succeed<ToolEvent>({
-      _tag: "Output",
-      result: rejected(call, "unknown_tool", `No tool registered with name "${call.name}"`),
-    })
+    return Stream.succeed(
+      ToolEvent.Output({
+        result: rejected(call, "unknown_tool", `No tool registered with name "${call.name}"`),
+      }),
+    )
   }
   if (isStreamingTool(tool)) return runStreaming(tool, call)
   return runPlain(tool, call)
 }
 
+const parseJsonUnknown = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Unknown))
+
 const runPlain = <R>(
   tool: AnyPlainTool<R>,
   call: FunctionCall,
 ): Stream.Stream<ToolEvent, never, R> =>
   Stream.fromEffect(
     Effect.gen(function* () {
-      const parsed = yield* Effect.try({
-        try: () => JSON.parse(call.arguments) as unknown,
-        catch: () => "json_parse_error" as const,
-      })
+      const parsed = yield* parseJsonUnknown(call.arguments).pipe(
+        Effect.mapError(() => "json_parse_error" as const),
+      )
       const validated = yield* Effect.tryPromise({
         try: () => Promise.resolve(tool.inputSchema["~standard"].validate(parsed)),
         catch: () => "validation_threw" as const,
@@ -128,7 +130,7 @@ const runPlain = <R>(
       return valueResult(call, tool.name, output)
     }).pipe(
       Effect.catchCause(() => Effect.succeed(executionError(call, "Tool execution failed"))),
-      Effect.map((result) => ({ _tag: "Output", result }) satisfies ToolEvent),
+      Effect.map((result) => ToolEvent.Output({ result })),
     ),
   )
 
@@ -138,19 +140,19 @@ const runStreaming = <R>(
 ): Stream.Stream<ToolEvent, never, R> =>
   Stream.unwrap(
     Effect.gen(function* () {
-      const parsed = yield* Effect.try({
-        try: () => JSON.parse(call.arguments) as unknown,
-        catch: () => "json_parse_error" as const,
-      })
+      const parsed = yield* parseJsonUnknown(call.arguments).pipe(
+        Effect.mapError(() => "json_parse_error" as const),
+      )
       const validated = yield* Effect.tryPromise({
         try: () => Promise.resolve(tool.inputSchema["~standard"].validate(parsed)),
         catch: () => "validation_threw" as const,
       })
       if (validated.issues !== undefined) {
-        return Stream.succeed<ToolEvent>({
-          _tag: "Output",
-          result: executionError(call, "Tool input failed schema validation"),
-        })
+        return Stream.succeed<ToolEvent>(
+          ToolEvent.Output({
+            result: executionError(call, "Tool input failed schema validation"),
+          }),
+        )
       }
 
       // Real-time: tap each event into a Ref as it flows; emit one
@@ -159,24 +161,20 @@ const runStreaming = <R>(
       const ref = yield* Ref.make<Array<unknown>>([])
       const intermediates = tool.run(validated.value).pipe(
         Stream.tap((event) => Ref.update(ref, Arr.append(event))),
-        Stream.map(
-          (data) =>
-            ({
-              _tag: "Intermediate",
-              call_id: call.call_id,
-              tool: tool.name,
-              data,
-            }) satisfies ToolEvent,
+        Stream.map((data) =>
+          ToolEvent.Intermediate({
+            call_id: call.call_id,
+            tool: tool.name,
+            data,
+          }),
         ),
       )
       const output = Stream.fromEffect(
         Ref.get(ref).pipe(
-          Effect.map(
-            (events) =>
-              ({
-                _tag: "Output",
-                result: valueResult(call, tool.name, tool.finalize(events)),
-              }) satisfies ToolEvent,
+          Effect.map((events) =>
+            ToolEvent.Output({
+              result: valueResult(call, tool.name, tool.finalize(events)),
+            }),
           ),
         ),
       )
@@ -184,10 +182,11 @@ const runStreaming = <R>(
     }),
   ).pipe(
     Stream.catchCause(() =>
-      Stream.succeed<ToolEvent>({
-        _tag: "Output",
-        result: executionError(call, "Tool execution failed"),
-      }),
+      Stream.succeed(
+        ToolEvent.Output({
+          result: executionError(call, "Tool execution failed"),
+        }),
+      ),
     ),
   )
 

package/src/transcriber/Transcriber.test.ts

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