feat(ai): add test clients for image, video, speech, transcription and decisions (#59992)

Author: rekram1-node

packages/ai/README.md

@@ -1167,7 +1167,7 @@ Everything below is exported from `@opencode/ai/effect` unless noted.
 - **`Transcription.request` / `generate` / `stream` / `start` / `resume`** — speech-to-text over inline, streaming, and queued routes; `TranscriptionClient` is its Effect service and layer.
 - **`Decision.request` / `Decision.generate`** — typed predicate, choice, and score questions over text, JSON, and media input; `DecisionClient` is its Effect service and layer.
 - **`AIClient.layer` / `AIClient.layerWith(executor)`** — every modality client plus the request executor in one layer.
-- **`@opencode/ai`** (Promise root) — `AI.make({ layer? })` and a default `ai` client exposing `llm`, `image`, `video`, `speech`, `transcription`, and `decision` as Promise / `AsyncIterable` APIs, `run(effect)` for any package Effect, plus `file`, `write`, `bytes`, `base64`, and `materialize` for assets.
+- **`@opencode/ai`** (Promise root) — `AI.make({ layer?, clients? })` and a default `ai` client exposing `llm`, `image`, `video`, `speech`, `transcription`, and `decision` as Promise / `AsyncIterable` APIs, `run(effect)` for any package Effect, plus `file`, `write`, `bytes`, `base64`, and `materialize` for assets.
 - **`@opencode/ai/experimental`** — APIs that may still change: `Extraction` (typed values read out of text) and `Realtime` (`Realtime.connect` starts an OpenAI, xAI, or Gemini voice session and returns a WebRTC answer SDP or a short-lived WebSocket URL and token).
 
 ## Testing
@@ -1214,6 +1214,10 @@ For explicit compaction, script a `CompactionResponse` through `push`, `always`,
 
 For `compact(request, { mechanism: "trigger" })`, script a `CompactionCheckpointResponse` instead. It carries `checkpoint`, `responseID`, and optional `usage`. Endpoint and trigger calls reject each other's fixtures; both share the same queue, gates, lazy recording, and fallback controls.
 
+`TestImage`, `TestVideo`, `TestSpeech`, `TestTranscription`, and `TestDecision` follow the same pattern: `testLayer()` provides the modality's client and `Test`, with the same `push`, `always`, `serve`, `requests`, `wait`, and `gate` controls. Script an `ImageResponse` (or the modality's response) or an `AIError`. `stream` expands the response into its events, and `start` returns an already finished generation that `resume` accepts by token. Decision responses are returned as scripted, without checking the answers against the questions.
+
+The Promise client accepts the same layers as `AI.make({ clients: TestImage.testLayer() })`; `ai.run(TestImage.Test.use(...))` reaches the controls.
+
 The published legacy `Service`, `layer`, `clientLayer`, and module-level controls remain available as adapters
 over the same implementation, including the legacy live `requests` array. New tests should use `Test` and
 `testLayer`.

packages/ai/src/index.ts

@@ -30,9 +30,11 @@ import { Video, type VideoModel, type VideoRequest, type VideoRequestInput } fro
  * transcription and decision clients over a request executor; every method runs the corresponding Effect API and rethrows
  * `AIError` unchanged. `file` and `write` load `node:fs/promises` on first use, so importing this module does not.
  */
-export interface Options {
+export interface Options<R = never> {
   /** Executor layer; defaults to `RequestExecutor.fetchLayer`. Inject a recorder or `RequestExecutor.middleware(fn)` here. */
   readonly layer?: Layer.Layer<RequestExecutor.Service>
+  /** Replaces default clients, for example with `TestImage.testLayer()`; its other services are available to `run`. */
+  readonly clients?: Layer.Layer<R>
 }
 
 export interface RunOptions {
@@ -71,14 +73,20 @@ const abortEffect = (signal: AbortSignal | undefined) =>
         return Effect.sync(() => signal.removeEventListener("abort", onAbort))
       })
 
-export const make = (options: Options = {}) => {
-  const runtime = ManagedRuntime.make(AIClient.layerWith(options.layer ?? RequestExecutor.fetchLayer))
+export const make = <R = never>(options: Options<R> = {}) => {
+  const runtime = ManagedRuntime.make(
+    Layer.merge(
+      AIClient.layerWith(options.layer ?? RequestExecutor.fetchLayer),
+      // `R` is only inferred from `clients`, so it is `never` whenever `clients` is omitted.
+      (options.clients ?? Layer.empty) as Layer.Layer<R>,
+    ),
+  )
 
   /** Run any package Effect (for example `LLMClient.compact(...)`) inside this runtime. */
-  const run = <A, E>(effect: Effect.Effect<A, E, Services>, options?: RunOptions) =>
+  const run = <A, E>(effect: Effect.Effect<A, E, Services | R>, options?: RunOptions) =>
     runtime.runPromise(Effect.raceFirst(effect, abortEffect(options?.signal)))
 
-  const iterate = <A, E>(stream: Stream.Stream<A, E, Services>, options?: RunOptions): AsyncIterable<A> =>
+  const iterate = <A, E>(stream: Stream.Stream<A, E, Services | R>, options?: RunOptions): AsyncIterable<A> =>
     Stream.toAsyncIterable(
       Stream.unwrap(
         runtime.contextEffect.pipe(
@@ -234,7 +242,7 @@ export const make = (options: Options = {}) => {
   }
 }
 
-export type Client = ReturnType<typeof make>
+export type Client<R = never> = ReturnType<typeof make<R>>
 
 const fileError = (message: string, cause: unknown) =>
   new AIError({ reason: new InvalidRequestError({ message, cause }) })

packages/ai/src/media-client.ts

@@ -26,6 +26,7 @@ export const make = <Self, Req extends RoutedRequest<Req, Event, Response>, Even
     readonly responseEvents: (response: Response) => ReadonlyArray<Event>
   },
 ) => ({
+  responseEvents: input.responseEvents,
   layer: Layer.effect(
     service,
     Effect.gen(function* () {

packages/ai/src/testing.ts

@@ -1,5 +1,10 @@
 export * as TestLLM from "./testing.js"
 export { compileRequest } from "./route/client.js"
+export { TestDecision } from "./testing/decision.js"
+export { TestImage } from "./testing/image.js"
+export { TestSpeech } from "./testing/speech.js"
+export { TestTranscription } from "./testing/transcription.js"
+export { TestVideo } from "./testing/video.js"
 
 import {
   LLMClient,
@@ -19,40 +24,26 @@ import {
   type ProviderMetadata,
   type UsageInput,
 } from "./schema/index.js"
-import { Context, Deferred, Effect, Latch, Layer, Queue, Scope, Stream } from "effect"
+import { Context, Effect, Layer, Stream } from "effect"
+import { TestScript } from "./testing/script.js"
 
 export type Response =
   | readonly LLMEvent[]
   | Stream.Stream<LLMEvent, AIError>
   | CompactionResponse
   | CompactionCheckpointResponse
 
-export type Gate = Readonly<{ started: Effect.Effect<void>; release: Effect.Effect<void> }>
+export type Gate = TestScript.Gate
 
 type ClientInterface = Context.Service.Shape<typeof LLMClient.Service>
 
 export type Responder = (request: LLMRequest) => Response
 
-export interface TestInterface extends ClientInterface {
-  /** Returns a snapshot of requests observed at execution time. */
-  readonly requests: () => Effect.Effect<readonly LLMRequest[]>
-  readonly push: (...responses: readonly Response[]) => Effect.Effect<void>
-  /** Replaces the fallback without changing queued responses. */
-  readonly always: (response: Response) => Effect.Effect<void>
-  /** Answers requests after the one-shot queue is exhausted; receives the original request. */
-  readonly serve: (responder: Responder) => Effect.Effect<void>
-  /** Waits for request arrivals, not output or completion. */
-  readonly wait: (count: number) => Effect.Effect<void>
-  readonly gate: () => Effect.Effect<Gate, never, Scope.Scope>
-}
+export interface TestInterface extends ClientInterface, TestScript.Controls<LLMRequest, Response> {}
 
 export class Test extends Context.Service<Test, TestInterface>()("@opencode/ai/TestLLM/Test") {}
 
-export interface LayerOptions {
-  readonly transformRequest?: (request: LLMRequest) => LLMRequest
-  /** Used after the one-shot response queue is exhausted. Omit to defect on unexpected requests. */
-  readonly fallback?: Response
-}
+export type LayerOptions = TestScript.Options<LLMRequest, Response>
 
 export const complete = (
   options: {
@@ -101,35 +92,10 @@ export const hangAfter = (...events: readonly LLMEvent[]) => Stream.concat(Strea
 
 const make = (options: LayerOptions) =>
   Effect.sync(() => {
-    const requests: LLMRequest[] = []
-    const responses: Response[] = []
-    let started = Deferred.makeUnsafe<void>()
-    let fallback: Response | Responder | undefined = options.fallback
-    let activeGate: { readonly started: Queue.Queue<void>; readonly release: Latch.Latch } | undefined
-    const wait = (count: number): Effect.Effect<void> =>
-      Effect.suspend(() =>
-        requests.length >= count ? Effect.void : Deferred.await(started).pipe(Effect.andThen(wait(count))),
-      )
-
-    const take = (request: LLMRequest) =>
-      Effect.suspend(() => {
-        const count = requests.push(options.transformRequest?.(request) ?? request)
-        const waiting = started
-        started = Deferred.makeUnsafe()
-        const gate = activeGate
-        try {
-          const response = responses.shift() ?? (typeof fallback === "function" ? fallback(request) : fallback)
-          if (!response) return Effect.die(new Error(`TestLLM has no response for request ${count}`))
-          if (!gate) return Effect.succeed(response)
-          return Queue.offer(gate.started, undefined).pipe(Effect.andThen(gate.release.await), Effect.as(response))
-        } finally {
-          // Waiters can resume synchronously; assign the reply and gate before notifying them.
-          Deferred.doneUnsafe(waiting, Effect.void)
-        }
-      })
+    const script = TestScript.make<LLMRequest, Response>("TestLLM", options)
     const stream: ClientInterface["stream"] = (request) =>
       Stream.unwrap(
-        take(request).pipe(
+        script.take(request).pipe(
           Effect.map((response) => {
             if (response instanceof CompactionResponse || response instanceof CompactionCheckpointResponse)
               return Stream.die("TestLLM generation requires an event response")
@@ -149,7 +115,7 @@ const make = (options: LayerOptions) =>
       request: LLMRequest,
       options?: EndpointCompactOptions | TriggerCompactOptions,
     ): Effect.Effect<CompactionResponse | CompactionCheckpointResponse, AIError> {
-      return take(request).pipe(
+      return script.take(request).pipe(
         Effect.flatMap((response): Effect.Effect<CompactionResponse | CompactionCheckpointResponse> => {
           if (options?.mechanism === "trigger")
             return response instanceof CompactionCheckpointResponse
@@ -162,6 +128,7 @@ const make = (options: LayerOptions) =>
       )
     }
     return Test.of({
+      ...script.controls,
       compact,
       stream,
       generate: (request) =>
@@ -173,36 +140,6 @@ const make = (options: LayerOptions) =>
             return Effect.die("TestLLM response ended without a terminal finish event")
           }),
         ),
-      requests: () => Effect.sync(() => [...requests]),
-      push: (...input) =>
-        Effect.sync(() => {
-          responses.push(...input)
-        }),
-      always: (response) =>
-        Effect.sync(() => {
-          fallback = response
-        }),
-      serve: (responder) =>
-        Effect.sync(() => {
-          fallback = responder
-        }),
-      wait,
-      gate: () =>
-        Effect.gen(function* () {
-          const gate = {
-            started: yield* Effect.acquireRelease(Queue.unbounded<void>(), Queue.shutdown),
-            release: yield* Latch.make(),
-          }
-          activeGate = gate
-          const release = Effect.sync(() => {
-            if (activeGate === gate) activeGate = undefined
-          }).pipe(Effect.andThen(gate.release.open), Effect.asVoid)
-          yield* Effect.addFinalizer(() => release)
-          return {
-            started: Queue.take(gate.started),
-            release,
-          }
-        }),
     })
   })
 

packages/ai/src/testing/decision.ts

@@ -0,0 +1,38 @@
+import { Context, Effect, Layer } from "effect"
+import { DecisionClient, type Interface } from "../decision-client.js"
+import type { DecisionRequestFor, DecisionResponse, DecisionResponseFor } from "../decision.js"
+import { AIError } from "../schema/index.js"
+import { TestScript } from "./script.js"
+
+/** Returned as scripted, without checking its answers against the request's questions. */
+export type Response = DecisionResponse | AIError
+
+export interface TestInterface extends Interface, TestScript.Controls<DecisionRequestFor, Response> {}
+
+export class Test extends Context.Service<Test, TestInterface>()("@opencode/ai/TestDecision/Test") {}
+
+export type LayerOptions = TestScript.Options<DecisionRequestFor, Response>
+
+/** Provides one shared implementation under `DecisionClient.Service` and `TestDecision.Test`. */
+export const testLayer = (options: LayerOptions = {}) =>
+  Layer.effectContext(
+    Effect.sync(() => {
+      const script = TestScript.make("TestDecision", options)
+      const client = Test.of({
+        ...script.controls,
+        generate: (request) =>
+          script
+            .take(request)
+            .pipe(
+              Effect.flatMap((response) =>
+                response instanceof AIError
+                  ? Effect.fail(response)
+                  : Effect.succeed(response as DecisionResponseFor<typeof request.questions>),
+              ),
+            ),
+      })
+      return Context.make(DecisionClient.Service, client).pipe(Context.add(Test, client))
+    }),
+  )
+
+export * as TestDecision from "./decision.js"

packages/ai/src/testing/image.ts

@@ -0,0 +1,23 @@
+import { Context } from "effect"
+import { ImageClient } from "../image-client.js"
+import type { ImageEvent, ImageRequestFor, ImageResponse } from "../image.js"
+import { TestMedia } from "./media.js"
+import type { TestScript } from "./script.js"
+
+export type Response = TestMedia.Response<ImageResponse>
+
+export interface TestInterface extends TestMedia.TestInterface<ImageRequestFor, ImageEvent, ImageResponse> {}
+
+export class Test extends Context.Service<Test, TestInterface>()("@opencode/ai/TestImage/Test") {}
+
+export type LayerOptions = TestScript.Options<ImageRequestFor, Response>
+
+/** Provides one shared implementation under `ImageClient.Service` and `TestImage.Test`. */
+export const testLayer = (options: LayerOptions = {}) =>
+  TestMedia.testLayer(ImageClient.Service, Test, {
+    name: "TestImage",
+    responseEvents: ImageClient.responseEvents,
+    options,
+  })
+
+export * as TestImage from "./image.js"

packages/ai/src/testing/media.ts

@@ -0,0 +1,60 @@
+import { Context, Effect, Layer, Stream } from "effect"
+import { Generation } from "../generation.js"
+import type { MediaClient } from "../media-client.js"
+import { AIError } from "../schema/index.js"
+import { TestScript } from "./script.js"
+
+/** A scripted reply: the response every operation returns, or the error it fails with. */
+export type Response<Value> = Value | AIError
+
+export interface TestInterface<Req extends MediaClient.RoutedRequest<Req, Event, Value>, Event, Value>
+  extends MediaClient.Interface<Req, Event, Value>,
+    TestScript.Controls<Req, Response<Value>> {}
+
+/**
+ * Builds one media test client. `stream` expands the response like an inline route, and `start` returns an already
+ * finished generation whose token `resume` accepts.
+ */
+export const testLayer = <Self, Test, Req extends MediaClient.RoutedRequest<Req, Event, Value>, Event, Value>(
+  service: Context.Service<Self, MediaClient.Interface<Req, Event, Value>>,
+  test: Context.Service<Test, TestInterface<Req, Event, Value>>,
+  input: {
+    readonly name: string
+    readonly responseEvents: (response: Value) => ReadonlyArray<Event>
+    readonly options: TestScript.Options<Req, Response<Value>>
+  },
+) =>
+  Layer.effectContext(
+    Effect.sync(() => {
+      const script = TestScript.make(input.name, input.options)
+      const generations = new Map<string, Response<Value>>()
+      const result = (response: Response<Value>) =>
+        response instanceof AIError ? Effect.fail(response) : Effect.succeed(response)
+      const completed = (id: string, response: Response<Value>) => {
+        const snapshot = { id, status: response instanceof AIError ? "failed" : "completed" } as const
+        return new Generation({ status: Effect.succeed(snapshot), result: result(response) }, id, snapshot)
+      }
+      const generate = (request: Req) => script.take(request).pipe(Effect.flatMap(result))
+      const client = test.of({
+        ...script.controls,
+        generate,
+        stream: (request) => Stream.fromIterableEffect(Effect.map(generate(request), input.responseEvents)),
+        start: (request) =>
+          script.take(request).pipe(
+            Effect.map((response) => {
+              const id = `${input.name}-${generations.size + 1}`
+              generations.set(id, response)
+              return completed(id, response)
+            }),
+          ),
+        resume: (_model, token) => {
+          const response = typeof token === "string" ? generations.get(token) : undefined
+          if (response === undefined) return Effect.die(new Error(`${input.name} has no generation ${String(token)}`))
+          return Effect.succeed(completed(String(token), response))
+        },
+      })
+      return Context.make(service, client).pipe(Context.add(test, client))
+    }),
+  )
+
+export * as TestMedia from "./media.js"