@effect-uai/core 0.8.0 → 0.10.0

package/src/observability/Telemetry.test.ts

@@ -0,0 +1,123 @@
+import { describe, it } from "@effect/vitest"
+import { Array as Arr, Duration, Effect, Layer, Metric, Option, Ref, Stream } from "effect"
+import { type HttpBody, HttpClient, HttpClientResponse } from "effect/unstable/http"
+import { expect } from "vitest"
+import { type Measurement, makeEvent } from "./Metrics.js"
+import { layerOtlp, record } from "./Telemetry.js"
+
+const event = (measurements: ReadonlyArray<Measurement>) =>
+  makeEvent({ _tag: "Test", turnIndex: 0, measurements })
+
+// Each test gets a fresh registry so instruments do not leak across tests.
+const isolated = <A, E, R>(self: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
+  Effect.provideService(self, Metric.MetricRegistry, new Map())
+
+const findById = (snap: ReadonlyArray<Metric.Metric.Snapshot>, id: string) =>
+  Option.getOrThrow(Arr.findFirst(snap, (s) => s.id === id))
+
+describe("record", () => {
+  it.effect("accumulates a counter measurement across events", () =>
+    isolated(
+      Effect.gen(function* () {
+        const ev = event([{ name: "rec_counter", kind: "counter", value: 5 }])
+        yield* Stream.make(ev, ev).pipe(record(), Stream.runDrain)
+        const snap = yield* Metric.snapshot
+        const c = findById(snap, "rec_counter")
+        expect(c.type).toBe("Counter")
+        expect((c.state as { readonly count: number }).count).toBe(10)
+      }),
+    ),
+  )
+
+  it.effect("records a timer measurement as a histogram observation", () =>
+    isolated(
+      Effect.gen(function* () {
+        const ev = event([{ name: "rec_timer", kind: "timer", value: Duration.millis(100) }])
+        yield* Stream.make(ev).pipe(record(), Stream.runDrain)
+        const snap = yield* Metric.snapshot
+        const h = findById(snap, "rec_timer")
+        expect(h.type).toBe("Histogram")
+        expect((h.state as { readonly count: number }).count).toBe(1)
+      }),
+    ),
+  )
+
+  it.effect("applies base attributes to every recorded metric", () =>
+    isolated(
+      Effect.gen(function* () {
+        const ev = event([{ name: "rec_attr", kind: "counter", value: 1 }])
+        yield* Stream.make(ev).pipe(
+          record({ attributes: { model: "test-model" } }),
+          Stream.runDrain,
+        )
+        const snap = yield* Metric.snapshot
+        const c = findById(snap, "rec_attr")
+        expect(c.attributes).toMatchObject({ model: "test-model" })
+      }),
+    ),
+  )
+
+  it.effect("records a custom metric with a novel name, unchanged recorder", () =>
+    isolated(
+      Effect.gen(function* () {
+        // A user-defined event the recorder has never seen: still exported.
+        const custom = makeEvent({
+          _tag: "ToolLatency",
+          turnIndex: 0,
+          measurements: [{ name: "myapp_tool_latency_total", kind: "counter", value: 3 }],
+        })
+        yield* Stream.make(custom).pipe(record(), Stream.runDrain)
+        const snap = yield* Metric.snapshot
+        const c = findById(snap, "myapp_tool_latency_total")
+        expect((c.state as { readonly count: number }).count).toBe(3)
+      }),
+    ),
+  )
+
+  it.effect("passes non-metric elements through untouched", () =>
+    isolated(
+      Effect.gen(function* () {
+        const out = yield* Stream.make("a", "b", "c").pipe(record(), Stream.runCollect)
+        expect(out).toEqual(["a", "b", "c"])
+      }),
+    ),
+  )
+})
+
+const bodyToString = (body: HttpBody.HttpBody): string =>
+  body._tag === "Uint8Array" ? new TextDecoder().decode(body.body) : ""
+
+describe("layerOtlp", () => {
+  it.effect("exports recorded metrics over OTLP via a mock HttpClient", () =>
+    isolated(
+      Effect.gen(function* () {
+        const bodies = yield* Ref.make<ReadonlyArray<string>>([])
+        const mockClient = HttpClient.make((request) =>
+          Ref.update(bodies, (b) => [...b, bodyToString(request.body)]).pipe(
+            Effect.as(HttpClientResponse.fromWeb(request, new Response("{}", { status: 200 }))),
+          ),
+        )
+        const clientLayer = Layer.succeed(HttpClient.HttpClient, mockClient)
+        const ev = event([{ name: "otlp_export_counter", kind: "counter", value: 3 }])
+
+        // Provide the OTLP layer scoped to the recording program. The exporter
+        // flushes on scope close (interval is long, so we rely on the flush).
+        yield* Stream.make(ev).pipe(
+          record(),
+          Stream.runDrain,
+          Effect.provide(
+            layerOtlp({
+              url: "http://localhost:4318/v1/metrics",
+              resource: { serviceName: "test-service" },
+              exportInterval: "10 minutes",
+            }).pipe(Layer.provide(clientLayer)),
+          ),
+        )
+
+        const captured = yield* Ref.get(bodies)
+        expect(captured.length).toBeGreaterThanOrEqual(1)
+        expect(captured.join("\n")).toContain("otlp_export_counter")
+      }),
+    ),
+  )
+})

package/src/observability/Telemetry.ts

@@ -0,0 +1,96 @@
+import { Duration, Effect, Layer, Match, Metric, Stream } from "effect"
+import type { HttpClient } from "effect/unstable/http"
+import { OtlpMetrics, OtlpSerialization } from "effect/unstable/observability"
+import { isMetricEvent, type Measurement, type MetricEvent } from "./Metrics.js"
+
+// ---------------------------------------------------------------------------
+// The agnostic recorder
+// ---------------------------------------------------------------------------
+
+/**
+ * Histogram bucket boundaries used for every histogram measurement (the only
+ * built-in one is throughput). Custom histogram metrics share these; a metric
+ * that needs bespoke boundaries can update its own instrument directly instead
+ * of routing through `record`.
+ */
+const histogramBoundaries = Metric.exponentialBoundaries({ start: 1, factor: 2, count: 16 })
+
+/**
+ * Build the effect `Metric` instrument a measurement maps to. Dispatches on
+ * `kind`, never on the event `_tag`, so a new built-in or custom metric needs
+ * no change here. Instruments dedupe by name in the global registry, so a fresh
+ * instance per call accumulates onto the same series (no cache needed).
+ */
+const buildInstrument = (m: Measurement): Metric.Metric<any, any> =>
+  Match.value(m.kind).pipe(
+    Match.when("counter", () => Metric.counter(m.name, { incremental: true })),
+    Match.when("histogram", () => Metric.histogram(m.name, { boundaries: histogramBoundaries })),
+    Match.when("timer", () => Metric.timer(m.name)),
+    Match.when("gauge", () => Metric.gauge(m.name)),
+    Match.exhaustive,
+  )
+
+const mergeAttributes = (
+  base: Readonly<Record<string, string>> | undefined,
+  extra: Readonly<Record<string, string>> | undefined,
+): Readonly<Record<string, string>> | undefined =>
+  base === undefined ? extra : extra === undefined ? base : { ...base, ...extra }
+
+const recordEvent = (
+  ev: MetricEvent,
+  baseAttributes: Readonly<Record<string, string>> | undefined,
+): Effect.Effect<void> =>
+  Effect.forEach(
+    ev.measurements,
+    (m) => {
+      const attributes = mergeAttributes(baseAttributes, m.attributes)
+      const base = buildInstrument(m)
+      const instrument = attributes === undefined ? base : Metric.withAttributes(base, attributes)
+      return Metric.update(instrument, m.value)
+    },
+    { discard: true },
+  )
+
+export type RecordOptions = {
+  /** Attributes applied to every recorded metric, e.g. `{ model, provider }`. */
+  readonly attributes?: Readonly<Record<string, string>>
+}
+
+/**
+ * Record every measurement on every metric event into effect `Metric`
+ * instruments, then pass events through unchanged. Matches events structurally
+ * (`isMetricEvent`), so it records built-in and custom metrics alike, and
+ * dispatches on `measurement.kind`, never on the event tag. Sits mid-pipeline
+ * before the transport. Provide an OTLP (or Prometheus) layer to export the
+ * instruments it populates.
+ */
+export const record =
+  (options?: RecordOptions) =>
+  <A, E, R>(self: Stream.Stream<A, E, R>): Stream.Stream<A, E, R> =>
+    self.pipe(
+      Stream.tap((ev) => (isMetricEvent(ev) ? recordEvent(ev, options?.attributes) : Effect.void)),
+    )
+
+// ---------------------------------------------------------------------------
+// OTLP wiring
+// ---------------------------------------------------------------------------
+
+export type LayerOtlpOptions = {
+  readonly url: string
+  readonly resource?: {
+    readonly serviceName?: string
+    readonly serviceVersion?: string
+  }
+  readonly exportInterval?: Duration.Input
+}
+
+/**
+ * Convenience layer that exports recorded metrics over OTLP. Provides the JSON
+ * serializer and leaves `HttpClient` as a requirement, so the platform's client
+ * (FetchHttpClient, NodeHttpClient, ...) is provided at the edge. This keeps
+ * the library platform-independent.
+ */
+export const layerOtlp = (
+  options: LayerOtlpOptions,
+): Layer.Layer<never, never, HttpClient.HttpClient> =>
+  OtlpMetrics.layer(options).pipe(Layer.provide(OtlpSerialization.layerJson))

package/src/structured-format/StructuredFormat.ts

@@ -142,6 +142,10 @@ export const parseJson =
   (raw: string): Effect.Effect<A, JsonParseError | StructuredDecodeError> =>
     pipe(
       Effect.try({
+        // Validation runs through Standard Schema (Zod / Valibot / Effect), not
+        // Effect Schema, so its JSON codecs don't apply here; and JSON.parse is
+        // a separate step on purpose, to surface JsonParseError distinctly.
+        // @effect-diagnostics-next-line effect/preferSchemaOverJson:off
         try: () => JSON.parse(raw),
         catch: (cause) => new JsonParseError({ raw, cause }),
       }),

package/src/tool/Approval.test.ts

@@ -15,9 +15,15 @@ import { describe, expect, it } from "vitest"
 import * as Items from "../domain/Items.js"
 import { findUnansweredCalls, cancelAllPending, isReconciled } from "./HistoryCheck.js"
 import { type ToolResult, isFailure, isOk, toToolCallOutput } from "./ToolResult.js"
-import { type ApprovalMapEntry, type ApprovalDecision, fromMap, fromQueue } from "./Approval.js"
-import { fromEffectSchema, make as makeTool, streaming } from "./Tool.js"
-import { run } from "./Toolkit.js"
+import {
+  type ApprovalMapEntry,
+  type ApprovalDecision,
+  type Verdict,
+  fromMap,
+  fromQueue,
+} from "./Approval.js"
+import { fromEffectSchema, make as makeTool } from "./Tool.js"
+import { make as makeToolkit, run } from "./Toolkit.js"
 import { ToolEvent, isApprovalRequested, isProgress, isOutput } from "./ToolEvent.js"
 
 // ---------------------------------------------------------------------------
@@ -27,34 +33,35 @@ import { ToolEvent, isApprovalRequested, isProgress, isOutput } from "./ToolEven
 //   - delete_database : non-streaming, requires approval
 // ---------------------------------------------------------------------------
 
-const webSearch = streaming({
+const webSearch = makeTool({
   name: "web_search",
   description: "search",
   inputSchema: fromEffectSchema(Schema.Struct({ query: Schema.String })),
-  run: ({ query }) =>
-    Stream.fromIterable([
-      { url: "a", title: `${query} 1` },
-      { url: "b", title: `${query} 2` },
-      { url: "c", title: `${query} 3` },
-    ]),
-  finalize: (hits) => ({ count: hits.length }),
+  run: ({ query }, emit) =>
+    Effect.gen(function* () {
+      const hits = [
+        { url: "a", title: `${query} 1` },
+        { url: "b", title: `${query} 2` },
+        { url: "c", title: `${query} 3` },
+      ]
+      yield* Stream.runForEach(Stream.fromIterable(hits), emit)
+      return { count: hits.length }
+    }),
 })
 
-const bulkEmail = streaming({
+const bulkEmail = makeTool({
   name: "bulk_email",
   description: "send",
   inputSchema: fromEffectSchema(
     Schema.Struct({ recipients: Schema.Array(Schema.String), subject: Schema.String }),
   ),
-  run: ({ recipients }) =>
-    Stream.fromIterable(
-      recipients.map((_, i) => ({
-        type: "progress" as const,
-        sent: i + 1,
-        total: recipients.length,
-      })),
-    ),
-  finalize: (events) => ({ status: "sent" as const, delivered: events.length }),
+  run: ({ recipients }, emit) =>
+    Effect.gen(function* () {
+      yield* Effect.forEach(recipients, (_, i) =>
+        emit({ type: "progress" as const, sent: i + 1, total: recipients.length }),
+      )
+      return { status: "sent" as const, delivered: recipients.length }
+    }),
 })
 
 const deleteDatabase = makeTool({
@@ -64,7 +71,7 @@ const deleteDatabase = makeTool({
   run: ({ name }) => Effect.succeed({ status: "dropped", name }),
 })
 
-const allTools = [webSearch, bulkEmail, deleteDatabase]
+const allTools = makeToolkit(webSearch, bulkEmail, deleteDatabase)
 const SENSITIVE = new Set(["bulk_email", "delete_database"])
 const isSensitive = (call: Items.ToolCall) => SENSITIVE.has(call.name)
 
@@ -248,6 +255,50 @@ describe("fromQueue + run", () => {
       reason: "too risky",
     })
   })
+
+  it("router retires per round, so sequential rounds over one queue both resolve", async () => {
+    // A verdict-per-round over one shared queue and scope. The old
+    // never-terminating router would still be alive for round 1 and steal
+    // round 2's verdict (not in its map), hanging round 2.
+    const decisions = await Effect.runPromise(
+      Effect.scoped(
+        Effect.gen(function* () {
+          const verdicts = yield* Queue.unbounded<Verdict>()
+          const round = (id: string) => [fc(id, "delete_database", { name: "prod" })]
+
+          const r1 = yield* fromQueue(isSensitive, verdicts)(round("c1"))
+          yield* Queue.offer(verdicts, { call_id: "c1", decision: "approve" })
+          const d1 = Array.from(yield* Stream.runCollect(r1.decisions))
+
+          const r2 = yield* fromQueue(isSensitive, verdicts)(round("c2"))
+          yield* Queue.offer(verdicts, { call_id: "c2", decision: "deny", reason: "no" })
+          const d2 = Array.from(yield* Stream.runCollect(r2.decisions))
+
+          return { d1, d2 }
+        }),
+      ),
+    )
+    expect(decisions.d1[0]).toMatchObject({ _tag: "Approved" })
+    expect(decisions.d2[0]).toMatchObject({ _tag: "Rejected", result: { kind: "denied" } })
+  })
+
+  it("timeout resolves an unanswered gated call as cancelled", async () => {
+    const decisions = await Effect.runPromise(
+      Effect.scoped(
+        Effect.gen(function* () {
+          const verdicts = yield* Queue.unbounded<Verdict>()
+          const { decisions } = yield* fromQueue(isSensitive, verdicts, { timeout: "10 millis" })([
+            fc("c1", "delete_database", { name: "prod" }),
+          ])
+          return Array.from(yield* Stream.runCollect(decisions))
+        }),
+      ),
+    )
+    expect(decisions[0]).toMatchObject({
+      _tag: "Rejected",
+      result: { _tag: "Failure", kind: "cancelled" },
+    })
+  })
 })
 
 // ---------------------------------------------------------------------------
@@ -312,7 +363,7 @@ describe("toToolCallOutput", () => {
     expect(JSON.parse(out.output)).toEqual({ count: 3 })
   })
 
-  it("round-trips a Failure result with reason", () => {
+  it("renders a Failure with reason as a nested error object", () => {
     const r: ToolResult = {
       _tag: "Failure",
       call_id: "c2",
@@ -321,10 +372,10 @@ describe("toToolCallOutput", () => {
       reason: "spam concern",
     }
     const out = toToolCallOutput(r)
-    expect(JSON.parse(out.output)).toEqual({ kind: "denied", reason: "spam concern" })
+    expect(JSON.parse(out.output)).toEqual({ error: { kind: "denied", message: "spam concern" } })
   })
 
-  it("round-trips a Failure result without reason (omits the field)", () => {
+  it("renders a Failure without reason (omits message)", () => {
     const r: ToolResult = {
       _tag: "Failure",
       call_id: "c3",
@@ -332,7 +383,7 @@ describe("toToolCallOutput", () => {
       kind: "cancelled",
     }
     const out = toToolCallOutput(r)
-    expect(JSON.parse(out.output)).toEqual({ kind: "cancelled" })
+    expect(JSON.parse(out.output)).toEqual({ error: { kind: "cancelled" } })
   })
 })
 

package/src/tool/Approval.ts

@@ -5,7 +5,7 @@
  * results must be returned to the model. Tool execution stays explicit at
  * the recipe boundary via `Toolkit.run`.
  */
-import { Data, Deferred, Effect, Queue, Scope, Stream } from "effect"
+import { Data, Deferred, type Duration, Effect, Queue, Ref, Scope, Stream } from "effect"
 import type { ToolCall } from "../domain/Items.js"
 import { type ToolResult, cancelled, denied } from "./ToolResult.js"
 import { ToolEvent } from "./ToolEvent.js"
@@ -53,13 +53,30 @@ export type Verdict = {
   readonly reason?: string
 }
 
+export type FromQueueOptions = {
+  /**
+   * Resolve any still-pending gated call as `cancelled` once this elapses,
+   * so a lost or never-sent verdict cannot hang the decisions stream
+   * forever. Omit to wait indefinitely.
+   */
+  readonly timeout?: Duration.Input
+}
+
 /**
  * Queue-backed approval planner. Safe calls are returned immediately in
  * `approved`; gated calls emit `ApprovalRequested` events and later produce
  * one `ApprovalDecision` when their matching verdict arrives.
+ *
+ * The verdict queue is a single-consumer transport: run one approval round
+ * at a time (the router retires once every gated call of the round is
+ * resolved). For overlapping rounds, use one queue per round.
  */
 export const fromQueue =
-  (predicate: (call: ToolCall) => boolean, verdicts: Queue.Dequeue<Verdict>) =>
+  (
+    predicate: (call: ToolCall) => boolean,
+    verdicts: Queue.Dequeue<Verdict>,
+    options?: FromQueueOptions,
+  ) =>
   (
     calls: ReadonlyArray<ToolCall>,
   ): Effect.Effect<
@@ -76,37 +93,65 @@ export const fromQueue =
       const approved = calls.filter((call) => !predicate(call))
 
       const entries = yield* Effect.forEach(gated, (call) =>
-        Deferred.make<Verdict>().pipe(Effect.map((d) => [call.call_id, d] as const)),
+        Deferred.make<ApprovalDecision>().pipe(Effect.map((d) => [call.call_id, d] as const)),
       )
-      const deferreds: ReadonlyMap<string, Deferred.Deferred<Verdict>> = new Map(entries)
-
-      // Router is forked into the surrounding Scope so it lives as long
-      // as the consumer is pulling events. Recipes typically supply the
-      // scope by wrapping the events construction in `Stream.unwrap`.
-      yield* Effect.forkScoped(
-        Effect.forever(
-          Effect.gen(function* () {
-            const v = yield* Queue.take(verdicts)
-            const d = deferreds.get(v.call_id)
-            if (d !== undefined) yield* Deferred.succeed(d, v)
-          }),
+      const deferreds: ReadonlyMap<string, Deferred.Deferred<ApprovalDecision>> = new Map(entries)
+      const callById: ReadonlyMap<string, ToolCall> = new Map(gated.map((c) => [c.call_id, c]))
+      const outstanding = yield* Ref.make(gated.length)
+
+      // Complete a deferred once; decrement only on the winning transition so
+      // a late verdict for an already-resolved call is a no-op.
+      const resolve = (call: ToolCall, decision: ApprovalDecision) =>
+        Deferred.succeed(deferreds.get(call.call_id)!, decision).pipe(
+          Effect.flatMap((won) => (won ? Ref.update(outstanding, (n) => n - 1) : Effect.void)),
+        )
+
+      // Router retires once every gated call is resolved (by verdict or
+      // timeout), so sequential rounds over one queue do not accumulate
+      // racing routers. Recursive + suspended: stack-safe, no imperative loop.
+      const route: Effect.Effect<void> = Effect.suspend(() =>
+        Ref.get(outstanding).pipe(
+          Effect.flatMap((n) =>
+            n <= 0
+              ? Effect.void
+              : Queue.take(verdicts).pipe(
+                  Effect.flatMap((v) => {
+                    const call = callById.get(v.call_id)
+                    return (
+                      call === undefined
+                        ? Effect.void
+                        : resolve(
+                            call,
+                            v.decision === "approve"
+                              ? approve(call)
+                              : reject(denied(call, v.reason)),
+                          )
+                    ).pipe(Effect.andThen(route))
+                  }),
+                ),
+          ),
         ),
       )
 
-      const decisions = Stream.fromIterable(gated).pipe(
-        Stream.flatMap(
-          (call) => {
-            const d = deferreds.get(call.call_id)!
-            return Stream.fromEffect(
-              Deferred.await(d).pipe(
-                Effect.map((v) =>
-                  v.decision === "approve" ? approve(call) : reject(denied(call, v.reason)),
+      if (gated.length > 0) {
+        yield* Effect.forkScoped(route)
+        if (options?.timeout !== undefined) {
+          yield* Effect.forkScoped(
+            Effect.sleep(options.timeout).pipe(
+              Effect.andThen(
+                Effect.forEach(gated, (call) =>
+                  resolve(call, reject(cancelled(call, "approval timed out"))),
                 ),
               ),
-            )
-          },
-          { concurrency: "unbounded" },
-        ),
+            ),
+          )
+        }
+      }
+
+      const decisions = Stream.fromIterable(gated).pipe(
+        Stream.flatMap((call) => Stream.fromEffect(Deferred.await(deferreds.get(call.call_id)!)), {
+          concurrency: "unbounded",
+        }),
       )
 
       const approvalRequests = Stream.fromIterable<ToolEvent>(gated.map(approvalRequested))

package/src/tool/Tool.test.ts

@@ -1,6 +1,7 @@
 import type { StandardJSONSchemaV1, StandardSchemaV1 } from "@standard-schema/spec"
 import { Effect } from "effect"
 import { describe, expect, expectTypeOf, it } from "vitest"
+import type * as Items from "../domain/Items.js"
 import * as Tool from "./Tool.js"
 
 // ---------------------------------------------------------------------------
@@ -81,7 +82,7 @@ describe("Tool.fromStandardSchema", () => {
 
     // `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" }))
+    const result = await Effect.runPromise(sendEmail.run({ to: "x@y.z" }, () => Effect.void))
     expect(result).toBe("queued: x@y.z")
   })
 
@@ -99,7 +100,59 @@ describe("Tool.fromStandardSchema", () => {
       run: (input) => Effect.succeed(input),
     })
 
-    type InputOf<T> = T extends Tool.Tool<string, infer I, unknown, never> ? I : never
+    type InputOf<T> = T extends Tool.Tool<string, infer I, any, any, any> ? I : never
     expectTypeOf<InputOf<typeof tool>>().toEqualTypeOf<EmailRecipient>()
   })
 })
+
+describe("Tool.withRun", () => {
+  const sendEmail = Tool.make({
+    name: "send_email",
+    description: "Send an email to a single recipient.",
+    inputSchema: Tool.fromStandardSchema(emailRecipientSchema),
+    run: ({ to }) => Effect.succeed(`sent: ${to}`),
+  })
+
+  it("swaps run while keeping the model-facing descriptor identical", async () => {
+    const dryRun = Tool.withRun(sendEmail, ({ to }) => Effect.succeed(`dry-run: ${to}`))
+
+    // Definition (name/description/schema) is byte-identical -> same descriptor.
+    expect(Tool.toDescriptors([dryRun])).toEqual(Tool.toDescriptors([sendEmail]))
+    // input is typed from the original tool, no annotation needed.
+    const out = await Effect.runPromise(dryRun.run({ to: "x@y.z" }, () => Effect.void))
+    expect(out).toBe("dry-run: x@y.z")
+  })
+})
+
+describe("Tool.decodeArgs", () => {
+  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}`),
+  })
+
+  const callWith = (args: string): Items.ToolCall => ({
+    type: "function_call",
+    call_id: "call_1",
+    name: "send_email",
+    arguments: args,
+  })
+
+  it("decodes valid JSON arguments to the typed input", async () => {
+    const input = await Effect.runPromise(Tool.decodeArgs(sendEmail, callWith('{"to":"x@y.z"}')))
+    expect(input).toEqual({ to: "x@y.z" })
+    // The return type is the tool's Input, no annotation needed.
+    expectTypeOf(input).toEqualTypeOf<EmailRecipient>()
+  })
+
+  it("fails with ToolError when the arguments aren't valid JSON", async () => {
+    const exit = await Effect.runPromiseExit(Tool.decodeArgs(sendEmail, callWith("not json")))
+    expect(exit._tag).toBe("Failure")
+  })
+
+  it("fails with ToolError when the arguments don't satisfy the schema", async () => {
+    const exit = await Effect.runPromiseExit(Tool.decodeArgs(sendEmail, callWith('{"to":42}')))
+    expect(exit._tag).toBe("Failure")
+  })
+})