@effect-uai/core 0.7.0 → 0.9.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

@@ -16,8 +16,8 @@ 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 { 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 +27,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 +65,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)
 

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")
+  })
+})