@effect-uai/core 0.4.0 → 0.5.0

package/src/testing/MockProvider.ts

@@ -1,8 +1,8 @@
-import { Duration, Effect, Layer, Ref, Schedule, Stream } from "effect"
+import { Array as Arr, Duration, Effect, Layer, Match, Option, Ref, Schedule, Stream } from "effect"
 import * as AiError from "../domain/AiError.js"
-import type { Item } from "../domain/Items.js"
+import { type Item, isOutputText } from "../domain/Items.js"
 import { LanguageModel, type LanguageModelService } from "../language-model/LanguageModel.js"
-import type { Turn, TurnEvent } from "../domain/Turn.js"
+import { type Turn, TurnEvent } from "../domain/Turn.js"
 
 export type MockOptions = {
   /**
@@ -13,46 +13,48 @@ export type MockOptions = {
   readonly deltaInterval?: Duration.Input
 }
 
+export type Call = {
+  readonly history: ReadonlyArray<Item>
+  readonly turn: Turn
+}
+
 /**
  * A scripted mock provider. Pre-canned `Turn` outputs are returned in order,
  * one per call to `streamTurn`. Each scripted turn is split into synthetic
- * deltas (text → tool_call_start → tool_call_args_delta → ... → turn_complete)
+ * deltas (text → ToolCallStart → ToolCallArgsDelta → ... → TurnComplete)
  * so streaming consumers can see realistic delta shapes.
  */
 export type MockRecorder = {
-  readonly calls: ReadonlyArray<{
-    readonly history: ReadonlyArray<Item>
-    readonly turn: Turn
-  }>
+  readonly calls: ReadonlyArray<Call>
 }
 
-const turnToDeltas = (turn: Turn): ReadonlyArray<TurnEvent> => {
-  const deltas: TurnEvent[] = []
-  for (const item of turn.items) {
-    if (item.type === "message" && item.role === "assistant") {
-      for (const block of item.content) {
-        if (block.type === "output_text") {
-          deltas.push({ type: "text_delta", text: block.text })
-        }
-      }
-    } else if (item.type === "function_call") {
-      deltas.push({
-        type: "tool_call_start",
-        call_id: item.call_id,
-        name: item.name,
-      })
-      deltas.push({
-        type: "tool_call_args_delta",
-        call_id: item.call_id,
-        delta: item.arguments,
-      })
-    } else if (item.type === "reasoning" && item.summary !== undefined) {
-      deltas.push({ type: "reasoning_delta", text: item.summary, kind: "summary" })
-    }
-  }
-  deltas.push({ type: "turn_complete", turn })
-  return deltas
-}
+// ---------------------------------------------------------------------------
+// Pure projection: Turn → ReadonlyArray<TurnEvent>
+// ---------------------------------------------------------------------------
+
+const itemToDeltas: (item: Item) => ReadonlyArray<TurnEvent> = Match.type<Item>().pipe(
+  Match.discriminators("type")({
+    message: (m): ReadonlyArray<TurnEvent> =>
+      m.role === "assistant"
+        ? m.content.filter(isOutputText).map((b) => TurnEvent.TextDelta({ text: b.text }))
+        : [],
+    function_call: (fc) => [
+      TurnEvent.ToolCallStart({ call_id: fc.call_id, name: fc.name }),
+      TurnEvent.ToolCallArgsDelta({ call_id: fc.call_id, delta: fc.arguments }),
+    ],
+    function_call_output: () => [],
+    reasoning: (r) =>
+      r.summary !== undefined
+        ? [TurnEvent.ReasoningDelta({ text: r.summary, kind: "summary" as const })]
+        : [],
+  }),
+  Match.exhaustive,
+)
+
+const turnToDeltas = (turn: Turn): ReadonlyArray<TurnEvent> => [
+  ...turn.items.flatMap(itemToDeltas),
+  TurnEvent.TurnComplete({ turn }),
+]
 
 const pacedDeltas = (turn: Turn, options?: MockOptions): Stream.Stream<TurnEvent> => {
   const base = Stream.fromIterable(turnToDeltas(turn))
@@ -61,101 +63,120 @@ const pacedDeltas = (turn: Turn, options?: MockOptions): Stream.Stream<TurnEvent
     : base.pipe(Stream.schedule(Schedule.spaced(options.deltaInterval)))
 }
 
-const makeService = (
+// ---------------------------------------------------------------------------
+// Canonical service factory. One implementation; sync/Layer/recorder
+// variants below are just different ways to wire the cursor + record hook.
+// ---------------------------------------------------------------------------
+
+const exhausted = (n: number, attempt: number): AiError.AiError =>
+  new AiError.InvalidRequest({
+    provider: "mock",
+    raw: `MockProvider exhausted: ${n} turns scripted, but call ${attempt} was made`,
+  })
+
+const noRecord = (_: Call): Effect.Effect<void> => Effect.void
+
+const buildService = (
   scriptedTurns: ReadonlyArray<Turn>,
-  options?: MockOptions,
-  recordCall?: (history: ReadonlyArray<Item>, turn: Turn) => Effect.Effect<void>,
-) =>
-  Effect.gen(function* () {
-    const cursor = yield* Ref.make(0)
-    return LanguageModel.of({
-      streamTurn: (request) =>
-        Stream.unwrap(
-          Effect.gen(function* () {
-            const i = yield* Ref.getAndUpdate(cursor, (n) => n + 1)
-            if (i >= scriptedTurns.length) {
-              return Stream.fail(
-                new AiError.InvalidRequest({
-                  provider: "mock",
-                  raw: `MockProvider exhausted: ${scriptedTurns.length} turns scripted, but call ${i + 1} was made`,
-                }),
-              )
-            }
-            const turn = scriptedTurns[i]!
-            if (recordCall !== undefined) {
-              yield* recordCall(request.history, turn)
-            }
-            return pacedDeltas(turn, options)
-          }),
+  options: MockOptions | undefined,
+  cursor: Ref.Ref<number>,
+  record: (call: Call) => Effect.Effect<void>,
+): LanguageModelService => ({
+  streamTurn: (request) =>
+    Stream.unwrap(
+      Ref.getAndUpdate(cursor, (n) => n + 1).pipe(
+        Effect.flatMap(
+          (i): Effect.Effect<Stream.Stream<TurnEvent, AiError.AiError>> =>
+            Option.match(Arr.get(scriptedTurns, i), {
+              onNone: () => Effect.succeed(Stream.fail(exhausted(scriptedTurns.length, i + 1))),
+              onSome: (turn) =>
+                record({ history: request.history, turn }).pipe(
+                  Effect.as(pacedDeltas(turn, options)),
+                ),
+            }),
         ),
-    })
-  })
+      ),
+    ),
+})
+
+// ---------------------------------------------------------------------------
+// Recorder handle. Unsafe Ref is local: it backs both the `record` write
+// hook (called inside the service) and the `recorder` read effect (called
+// by the test). Both close over the same cell.
+// ---------------------------------------------------------------------------
+
+type RecorderHandle = {
+  readonly record: (call: Call) => Effect.Effect<void>
+  readonly recorder: Effect.Effect<MockRecorder>
+}
 
+const makeRecorderUnsafe = (): RecorderHandle => {
+  const ref = Ref.makeUnsafe<ReadonlyArray<Call>>([])
+  return {
+    record: (call) => Ref.update(ref, Arr.append(call)),
+    recorder: Ref.get(ref).pipe(Effect.map((calls): MockRecorder => ({ calls }))),
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Layer that registers a `MockProvider` against the `LanguageModel` tag.
+ * Calls beyond the scripted turn count fail with `InvalidRequest`.
+ */
 export const layer = (
   scriptedTurns: ReadonlyArray<Turn>,
   options?: MockOptions,
-): Layer.Layer<LanguageModel> => Layer.effect(LanguageModel, makeService(scriptedTurns, options))
+): Layer.Layer<LanguageModel> =>
+  Layer.effect(
+    LanguageModel,
+    Ref.make(0).pipe(
+      Effect.map((cursor) => buildService(scriptedTurns, options, cursor, noRecord)),
+    ),
+  )
 
 /**
- * Synchronous constructor that returns the `LanguageModelService` value
- * directly, plus a recorder. Use this when you want to swap models
- * mid-stream via `Effect.provideService` instead of providing one model
- * for the whole program via `Layer`.
+ * Like `layer`, but also exposes a recorder that captures every call
+ * (history + returned turn).
  */
-export const make = (
+export const layerWithRecorder = (
   scriptedTurns: ReadonlyArray<Turn>,
   options?: MockOptions,
 ): {
-  readonly service: LanguageModelService
+  readonly layer: Layer.Layer<LanguageModel>
   readonly recorder: Effect.Effect<MockRecorder>
 } => {
-  const cursor = Ref.makeUnsafe(0)
-  const callsRef = Ref.makeUnsafe<ReadonlyArray<{ history: ReadonlyArray<Item>; turn: Turn }>>([])
-  const service: LanguageModelService = {
-    streamTurn: (request) =>
-      Stream.unwrap(
-        Effect.gen(function* () {
-          const i = yield* Ref.getAndUpdate(cursor, (n) => n + 1)
-          if (i >= scriptedTurns.length) {
-            return Stream.fail(
-              new AiError.InvalidRequest({
-                provider: "mock",
-                raw: `MockProvider exhausted: ${scriptedTurns.length} turns scripted, but call ${i + 1} was made`,
-              }),
-            )
-          }
-          const turn = scriptedTurns[i]!
-          yield* Ref.update(callsRef, (xs) => [...xs, { history: request.history, turn }])
-          return pacedDeltas(turn, options)
-        }),
-      ),
-  }
+  const { record, recorder } = makeRecorderUnsafe()
   return {
-    service,
-    recorder: Ref.get(callsRef).pipe(Effect.map((calls) => ({ calls }))),
+    layer: Layer.effect(
+      LanguageModel,
+      Ref.make(0).pipe(
+        Effect.map((cursor) => buildService(scriptedTurns, options, cursor, record)),
+      ),
+    ),
+    recorder,
   }
 }
 
 /**
- * Same as `layer`, but also exposes a recorder that captures every call
- * (history + returned turn).
+ * Build the `LanguageModelService` value directly (no Layer), plus a
+ * recorder. Use this when you want to swap models mid-program via
+ * `Effect.provideService` instead of providing one model for the whole
+ * program via `Layer`.
  */
-export const layerWithRecorder = (
+export const make = (
   scriptedTurns: ReadonlyArray<Turn>,
   options?: MockOptions,
 ): {
-  readonly layer: Layer.Layer<LanguageModel>
+  readonly service: LanguageModelService
   readonly recorder: Effect.Effect<MockRecorder>
 } => {
-  const callsRef = Ref.makeUnsafe<ReadonlyArray<{ history: ReadonlyArray<Item>; turn: Turn }>>([])
-  const live = Layer.effect(
-    LanguageModel,
-    makeService(scriptedTurns, options, (history, turn) =>
-      Ref.update(callsRef, (xs) => [...xs, { history, turn }]),
-    ),
-  )
+  const cursor = Ref.makeUnsafe(0)
+  const { record, recorder } = makeRecorderUnsafe()
   return {
-    layer: live,
-    recorder: Ref.get(callsRef).pipe(Effect.map((calls) => ({ calls }))),
+    service: buildService(scriptedTurns, options, cursor, record),
+    recorder,
   }
 }

package/src/testing/MockSpeechSynthesizer.ts

@@ -43,12 +43,10 @@ const makeService = (
           const i = yield* Ref.getAndUpdate(bCursor, (n) => n + 1)
           const scripted = script.blobs ?? []
           if (i >= scripted.length) {
-            return yield* Effect.fail(
-              new AiError.InvalidRequest({
-                provider: "mock",
-                raw: `MockSpeechSynthesizer exhausted: ${scripted.length} blobs scripted, but call ${i + 1} was made`,
-              }),
-            )
+            return yield* new AiError.InvalidRequest({
+              provider: "mock",
+              raw: `MockSpeechSynthesizer exhausted: ${scripted.length} blobs scripted, but call ${i + 1} was made`,
+            })
           }
           return scripted[i]!
         }),

package/src/testing/MockTranscriber.ts

@@ -41,12 +41,10 @@ const makeService = (
           const i = yield* Ref.getAndUpdate(tCursor, (n) => n + 1)
           const scripted = script.transcripts ?? []
           if (i >= scripted.length) {
-            return yield* Effect.fail(
-              new AiError.InvalidRequest({
-                provider: "mock",
-                raw: `MockTranscriber exhausted: ${scripted.length} transcripts scripted, but call ${i + 1} was made`,
-              }),
-            )
+            return yield* new AiError.InvalidRequest({
+              provider: "mock",
+              raw: `MockTranscriber exhausted: ${scripted.length} transcripts scripted, but call ${i + 1} was made`,
+            })
           }
           return scripted[i]!
         }),

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