@opencode-ai/ai 0.0.0-dev-18562 → 0.0.0-dev-18564

package/README.md

@@ -214,22 +214,40 @@ the requests sent by code under test:
 import { Effect } from "effect"
 import { TestLLM } from "@opencode-ai/ai/testing"
 
-const testLLM = TestLLM.layer({
-  fallback: TestLLM.text("Hello from the test model", "text-1"),
-})
-
-// TestLLM.clientLayer provides LLMClient.Service and consumes TestLLM.Service.
 const programWithTestClient = Effect.gen(function* () {
+  const test = yield* TestLLM.Test
+  yield* test.push(TestLLM.text("Hello from the test model", "text-1"))
   const result = yield* program
-  const test = yield* TestLLM.Service
-  console.log(test.requests)
+  console.log(yield* test.requests())
   return result
-}).pipe(Effect.provide(TestLLM.clientLayer), Effect.provide(testLLM))
+}).pipe(Effect.provide(TestLLM.testLayer()))
 ```
 
-`TestLLM.push(...)` scripts one-shot responses, `TestLLM.always(...)` changes the fallback, and
-`TestLLM.wait(...)` lets concurrent tests wait until a request has arrived. Every received canonical request is
-available on the yielded `TestLLM.Service`.
+`testLayer()` provides the same object under `LLMClient.Service` and `TestLLM.Test`. Production consumes the
+normal client; tests use the additional controls. Each layer build has fresh state.
+
+- `test.push(...)` queues one-shot responses in execution order. Each argument is one response.
+- `test.always(response)` installs a repeatable fallback. The layer's `fallback` option sets its initial value.
+- `test.serve(request => response)` installs a request-dependent fallback. `always` and `serve` replace each
+  other without changing queued replies; queued replies take precedence.
+- `test.requests()` returns an array snapshot. `transformRequest` changes only the recorded observation;
+  `serve` receives the original canonical request.
+- `test.wait(count)` waits for request arrivals, not output or completion, and supports concurrent waiters.
+- `test.gate()` returns a scoped gate with countable `started` notifications and a `release` Effect. Release
+  unblocks all requests captured by that gate; closing its scope also releases it. Effect-aware test runners
+  already provide Scope.
+
+Constructing `stream()` or `generate()` does not record a request, invoke a responder, or consume a script.
+Each execution does. An exhausted queue without a fallback defects immediately rather than waiting for a
+future reply.
+
+Responses remain canonical event arrays or arbitrary `Stream<LLMEvent, AIError>` values. The client consumes
+supplied streams directly, preserving failure identity, finalizers, incomplete output, and post-finish tails;
+it does not repair or truncate them.
+
+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`.
 
 ## Caching
 

package/dist/testing.d.ts

@@ -1,5 +1,5 @@
 export * as TestLLM from "./testing.js";
-import { type Interface as LLMClientShape } from "./route/client.js";
+import { LLMClient } from "./route/client.js";
 import { LLMEvent, type FinishReasonDetails, type AIError, type LLMRequest, type ProviderMetadata, type UsageInput } from "./schema/index.js";
 import { Context, Effect, Layer, Scope, Stream } from "effect";
 export type Response = readonly LLMEvent[] | Stream.Stream<LLMEvent, AIError>;
@@ -7,13 +7,31 @@ export type Gate = Readonly<{
     started: Effect.Effect<void>;
     release: Effect.Effect<void>;
 }>;
+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>;
+}
+declare const Test_base: Context.ServiceClass<Test, "@opencode/ai/TestLLM/Test", TestInterface>;
+export declare class Test extends Test_base {
+}
+/** @deprecated Use TestInterface through Test and testLayer. */
 export interface Interface {
     readonly requests: LLMRequest[];
     readonly push: (...responses: readonly Response[]) => Effect.Effect<void>;
     readonly always: (response: Response) => Effect.Effect<void>;
     readonly wait: (count: number) => Effect.Effect<void>;
     readonly gate: Effect.Effect<Gate, never, Scope.Scope>;
-    readonly client: LLMClientShape;
+    readonly client: ClientInterface;
 }
 export interface LayerOptions {
     readonly transformRequest?: (request: LLMRequest) => LLMRequest;
@@ -21,6 +39,7 @@ export interface LayerOptions {
     readonly fallback?: Response;
 }
 declare const Service_base: Context.ServiceClass<Service, "@opencode/ai/TestLLM", Interface>;
+/** @deprecated Use Test and testLayer for normal client methods and test controls. */
 export declare class Service extends Service_base {
 }
 export declare const complete: (options: {
@@ -1507,7 +1526,11 @@ export declare const hangAfter: (...events: readonly LLMEvent[]) => Stream.Strea
     } | undefined;
     readonly classification?: "context-overflow" | "payload-too-large" | undefined;
 }, never, never>;
+/** Provides one shared implementation under the normal client and test-control tags. */
+export declare const testLayer: (options?: LayerOptions) => Layer.Layer<import("./route/client.js").Service | Test, never, never>;
+/** @deprecated Use testLayer; retained for published callers of the legacy control interface. */
 export declare const layer: (options?: LayerOptions) => Layer.Layer<Service, never, never>;
+/** @deprecated testLayer provides LLMClient.Service directly. */
 export declare const clientLayer: Layer.Layer<import("./route/client.js").Service, never, Service>;
 export declare const push: (...responses: readonly Response[]) => Effect.Effect<void, never, Service>;
 export declare const always: (response: Response) => Effect.Effect<void, never, Service>;

package/dist/testing.js

@@ -2,6 +2,9 @@ export * as TestLLM from "./testing.js";
 import { LLMClient } from "./route/client.js";
 import { LLMEvent, LLMResponse, } from "./schema/index.js";
 import { Context, Deferred, Effect, Latch, Layer, Queue, Scope, Stream } from "effect";
+export class Test extends Context.Service()("@opencode/ai/TestLLM/Test") {
+}
+/** @deprecated Use Test and testLayer for normal client methods and test controls. */
 export class Service extends Context.Service()("@opencode/ai/TestLLM") {
 }
 export const complete = (options, ...events) => [
@@ -28,28 +31,33 @@ export const tool = (id, name, input) => toolCalls(LLMEvent.toolCall({ id, name,
 export const failAfter = (error, ...events) => Stream.fromIterable(events).pipe(Stream.concat(Stream.fail(error)));
 export const hangAfter = (...events) => Stream.concat(Stream.fromIterable(events), Stream.never);
 const toStream = (response) => (Stream.isStream(response) ? response : Stream.fromIterable(response));
-export const layer = (options = {}) => Layer.effect(Service, Effect.gen(function* () {
+const make = (options) => Effect.sync(() => {
     const requests = [];
     const responses = [];
     let started = Deferred.makeUnsafe();
     let fallback = options.fallback;
     let activeGate;
     const wait = (count) => Effect.suspend(() => requests.length >= count ? Effect.void : Deferred.await(started).pipe(Effect.andThen(wait(count))));
-    const stream = ((request) => {
-        requests.push(options.transformRequest?.(request) ?? request);
+    const stream = (request) => Stream.suspend(() => {
+        const count = requests.push(options.transformRequest?.(request) ?? request);
         const waiting = started;
         started = Deferred.makeUnsafe();
-        Deferred.doneUnsafe(waiting, Effect.void);
-        const response = responses.shift() ?? fallback;
-        if (!response)
-            return Stream.die(new Error(`TestLLM has no response for request ${requests.length}`));
-        const streamed = toStream(response);
         const gate = activeGate;
-        if (!gate)
-            return streamed;
-        return Stream.unwrap(Queue.offer(gate.started, undefined).pipe(Effect.andThen(gate.release.await), Effect.as(streamed)));
+        try {
+            const response = responses.shift() ?? (typeof fallback === "function" ? fallback(request) : fallback);
+            if (!response)
+                return Stream.die(new Error(`TestLLM has no response for request ${count}`));
+            const streamed = toStream(response);
+            if (!gate)
+                return streamed;
+            return Stream.unwrap(Queue.offer(gate.started, undefined).pipe(Effect.andThen(gate.release.await), Effect.as(streamed)));
+        }
+        finally {
+            // Waiters can resume synchronously; assign the reply and gate before notifying them.
+            Deferred.doneUnsafe(waiting, Effect.void);
+        }
     });
-    const client = LLMClient.Service.of({
+    const test = Test.of({
         stream,
         generate: (request) => stream(request).pipe(Stream.runFold(LLMResponse.empty, LLMResponse.reduce), Effect.flatMap((state) => {
             const response = LLMResponse.complete(state);
@@ -57,17 +65,18 @@ export const layer = (options = {}) => Layer.effect(Service, Effect.gen(function
                 return Effect.succeed(response);
             return Effect.die("TestLLM response ended without a terminal finish event");
         })),
-    });
-    return Service.of({
-        requests,
+        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* () {
+        gate: () => Effect.gen(function* () {
             const gate = {
                 started: yield* Effect.acquireRelease(Queue.unbounded(), Queue.shutdown),
                 release: yield* Latch.make(),
@@ -83,9 +92,21 @@ export const layer = (options = {}) => Layer.effect(Service, Effect.gen(function
                 release,
             };
         }),
-        client,
     });
-}));
+    return { test, requests };
+});
+/** Provides one shared implementation under the normal client and test-control tags. */
+export const testLayer = (options = {}) => Layer.effectContext(Effect.map(make(options), (implementation) => Context.make(LLMClient.Service, implementation.test).pipe(Context.add(Test, implementation.test))));
+/** @deprecated Use testLayer; retained for published callers of the legacy control interface. */
+export const layer = (options = {}) => Layer.effect(Service, Effect.map(make(options), (implementation) => Service.of({
+    requests: implementation.requests,
+    push: implementation.test.push,
+    always: implementation.test.always,
+    wait: implementation.test.wait,
+    gate: implementation.test.gate(),
+    client: implementation.test,
+})));
+/** @deprecated testLayer provides LLMClient.Service directly. */
 export const clientLayer = Layer.effect(LLMClient.Service, Effect.map(Service, (service) => service.client));
 export const push = (...responses) => Service.use((service) => service.push(...responses));
 export const always = (response) => Service.use((service) => service.always(response));

package/package.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
-  "version": "0.0.0-dev-18562",
+  "version": "0.0.0-dev-18564",
   "name": "@opencode-ai/ai",
   "type": "module",
   "license": "MIT",
@@ -30,7 +30,7 @@
   "devDependencies": {
     "@clack/prompts": "1.0.0-alpha.1",
     "@effect/platform-node": "4.0.0-rc.112",
-    "@opencode-ai/http-recorder": "0.0.0-dev-18562",
+    "@opencode-ai/http-recorder": "0.0.0-dev-18564",
     "@tsconfig/bun": "1.0.9",
     "@types/bun": "1.3.13",
     "@typescript/native-preview": "7.0.0-dev.20251207.1",
@@ -39,7 +39,7 @@
   "dependencies": {
     "@smithy/eventstream-codec": "4.2.14",
     "@smithy/util-utf8": "4.2.2",
-    "@opencode-ai/schema": "0.0.0-dev-18562",
+    "@opencode-ai/schema": "0.0.0-dev-18564",
     "aws4fetch": "1.0.20",
     "effect": "4.0.0-rc.112",
     "google-auth-library": "10.5.0"