@effect-uai/core 0.8.0 → 0.10.0

package/src/browser/BrowserTool.ts

@@ -0,0 +1,161 @@
+import { Effect, Schema } from "effect"
+import * as Tool from "../tool/Tool.js"
+import * as Toolkit from "../tool/Toolkit.js"
+import type { BrowserSession } from "./Browser.js"
+
+// ---------------------------------------------------------------------------
+// Model-facing argument schemas. Annotated so the descriptions reach the
+// model through the rendered JSON Schema (JSDoc does not).
+// ---------------------------------------------------------------------------
+
+const GotoArgs = Schema.Struct({
+  url: Schema.String.annotate({ description: "Absolute URL to navigate to." }),
+})
+
+const ClickArgs = Schema.Struct({
+  ref: Schema.String.annotate({
+    description: "A CSS selector, or an element @ref if a page-reading tool provides one.",
+  }),
+})
+
+const FillArgs = Schema.Struct({
+  ref: Schema.String.annotate({
+    description: "A CSS selector (or element @ref) of the input to fill.",
+  }),
+  text: Schema.String.annotate({ description: "The text to put in the input." }),
+})
+
+const PressArgs = Schema.Struct({
+  key: Schema.String.annotate({
+    description: 'Key to press, e.g. "Enter" to submit the focused input, "Tab", "Escape".',
+  }),
+})
+
+const ScrollArgs = Schema.Struct({
+  direction: Schema.Literals(["up", "down"]).annotate({
+    description: "Scroll the viewport up or down.",
+  }),
+})
+
+// ---------------------------------------------------------------------------
+// Uniform action outcome: the model always learns where the action left it.
+// ---------------------------------------------------------------------------
+
+const currentUrl = (session: BrowserSession): Effect.Effect<string> =>
+  session.evaluate("location.href").pipe(
+    Effect.flatMap(Schema.decodeUnknownEffect(Schema.String)),
+    Effect.orElseSucceed(() => "(unknown)"),
+  )
+
+const okAt = (session: BrowserSession): Effect.Effect<string> =>
+  Effect.map(currentUrl(session), (url) => `ok (now at ${url})`)
+
+// ---------------------------------------------------------------------------
+// The canonical browser action tools, each closed over a live `BrowserSession`
+// and failing with the full `BrowserError`. `Output` is a compact outcome
+// (`ok (now at <url>)`), not a page dump - a page-reading tool is the recipe's
+// to define, so history does not accumulate a full page per action.
+//
+// A failed action (stale ref, dead control, timeout) fails typed on the error
+// channel. Whether the model gets to recover from it is the loop's decision:
+// wrap the toolkit in `Toolkit.describeFailures(BrowserError.describe)` to
+// surface failures to the model, or map selectively to keep session/infra
+// errors (e.g. `BrowserSessionExpired`) fatal.
+//
+// Browser actions are order-dependent (fill, then press Enter): run a turn's
+// calls with `{ concurrency: 1 }`.
+// ---------------------------------------------------------------------------
+
+export const gotoTool = (session: BrowserSession) =>
+  Tool.make({
+    name: "browser_goto",
+    description: "Navigate the browser to an absolute URL.",
+    inputSchema: Tool.fromEffectSchema(GotoArgs),
+    run: (args) =>
+      Effect.andThen(session.goto(args.url), okAt(session)).pipe(
+        Effect.withSpan("browser_goto", {
+          kind: "client",
+          attributes: { "browser.url": args.url },
+        }),
+      ),
+  })
+
+export const clickTool = (session: BrowserSession) =>
+  Tool.make({
+    name: "browser_click",
+    description: "Click the element named by ref. A click may navigate to a new page.",
+    inputSchema: Tool.fromEffectSchema(ClickArgs),
+    run: (args) =>
+      Effect.andThen(session.click(args.ref), okAt(session)).pipe(
+        Effect.withSpan("browser_click", {
+          kind: "client",
+          attributes: { "browser.ref": args.ref },
+        }),
+      ),
+  })
+
+export const fillTool = (session: BrowserSession) =>
+  Tool.make({
+    name: "browser_fill",
+    description:
+      "Put text into the input named by ref. Filling alone does not submit; press Enter to submit the input.",
+    inputSchema: Tool.fromEffectSchema(FillArgs),
+    run: (args) =>
+      Effect.andThen(session.fill(args.ref, args.text), okAt(session)).pipe(
+        Effect.withSpan("browser_fill", {
+          kind: "client",
+          attributes: { "browser.ref": args.ref },
+        }),
+      ),
+  })
+
+export const pressTool = (session: BrowserSession) =>
+  Tool.make({
+    name: "browser_press",
+    description: "Press a keyboard key against the focused element.",
+    inputSchema: Tool.fromEffectSchema(PressArgs),
+    run: (args) =>
+      Effect.andThen(session.press(args.key), okAt(session)).pipe(
+        Effect.withSpan("browser_press", {
+          kind: "client",
+          attributes: { "browser.key": args.key },
+        }),
+      ),
+  })
+
+export const scrollTool = (session: BrowserSession) =>
+  Tool.make({
+    name: "browser_scroll",
+    description:
+      "Scroll the viewport. Only useful to bring an element into view - a page-reading tool's text is already scroll-independent.",
+    inputSchema: Tool.fromEffectSchema(ScrollArgs),
+    run: (args) =>
+      Effect.andThen(session.scroll({ direction: args.direction }), okAt(session)).pipe(
+        Effect.withSpan("browser_scroll", {
+          kind: "client",
+          attributes: { "browser.direction": args.direction },
+        }),
+      ),
+  })
+
+/**
+ * The canonical browser action verbs bundled as a `Toolkit`, closed over a
+ * live `BrowserSession`. Compose it with a recipe-local page-reading tool and
+ * whatever finish/signal tools the agent needs:
+ *
+ *   const toolkit = yield* Toolkit.compose(
+ *     browserToolkit(session),
+ *     Toolkit.make(readPageTool(session), finishTool),
+ *   )
+ *
+ * For an à-la-carte subset, use the individual `gotoTool` / `clickTool` / …
+ * constructors directly. Run a turn's calls with `{ concurrency: 1 }`.
+ */
+export const browserToolkit = (session: BrowserSession) =>
+  Toolkit.make(
+    gotoTool(session),
+    clickTool(session),
+    fillTool(session),
+    pressTool(session),
+    scrollTool(session),
+  )

package/src/domain/AiError.ts

@@ -1,4 +1,4 @@
-import { Data, Duration } from "effect"
+import { Data, Duration, Match } from "effect"
 
 export type Scope = "rpm" | "tpm" | "rpd" | "tpd"
 
@@ -112,3 +112,29 @@ export type AiError =
   | IncompleteTurn
   | GenerationFailed
   | Unsupported
+
+const withReason = (base: string, reason: string | undefined): string =>
+  reason === undefined ? base : `${base}: ${reason}`
+
+/**
+ * Short human-readable description of an error, for logs and model-facing
+ * failure messages. Prose, not a contract; branch on `_tag` instead.
+ */
+export const describe: (e: AiError) => string = Match.type<AiError>().pipe(
+  Match.discriminatorsExhaustive("_tag")({
+    RateLimited: (e) => `rate limited by ${e.provider}; try again later`,
+    Unavailable: (e) => `${e.provider} is temporarily unavailable`,
+    Timeout: (e) => `the ${e.provider} request timed out`,
+    ContentFiltered: (e) => withReason(`blocked by ${e.provider}'s content filter`, e.reason),
+    ContextLengthExceeded: (e) => `the request exceeded ${e.provider}'s context limit`,
+    InvalidRequest: (e) =>
+      e.param === undefined
+        ? `${e.provider} rejected the request`
+        : `${e.provider} rejected the request (param: ${e.param})`,
+    AuthFailed: (e) => `authentication against ${e.provider} failed (${e.subtype})`,
+    Cancelled: (e) => `the ${e.provider} request was cancelled`,
+    IncompleteTurn: () => "the provider stream ended without completing",
+    GenerationFailed: (e) => e.message ?? `${e.provider} failed mid-generation`,
+    Unsupported: (e) => withReason(`${e.provider} does not support ${e.capability}`, e.reason),
+  }),
+)

package/src/embedding-model/EmbeddingModel.test.ts

@@ -81,10 +81,14 @@ describe("embed / embedMany free exports preserve E in their return type", () =>
     // of the cross-provider request set. Requesting them on the generic
     // helper is a compile error; they're reachable only via the typed
     // `JinaEmbedding` tag.
+    // These calls exist only to assert the encoding is a compile error; they
+    // are intentionally never run, so the floating-effect check is off here.
+    // @effect-diagnostics effect/floatingEffect:off
     // @ts-expect-error "multivector" is not an EmbedEncoding
     embedMany({ inputs: ["x"], model: "m", encoding: "multivector" })
     // @ts-expect-error "sparse" is not an EmbedEncoding
     embed({ input: "x", model: "m", encoding: "sparse" })
+    // @effect-diagnostics effect/floatingEffect:error
   })
 
   it("when the request is widened to CommonEmbedRequest, the response is the open union", () => {

package/src/index.ts

@@ -1,5 +1,8 @@
 export * as AiError from "./domain/AiError.js"
 export * as Audio from "./domain/Audio.js"
+export * as Browser from "./browser/Browser.js"
+export * as BrowserError from "./browser/BrowserError.js"
+export * as BrowserTool from "./browser/BrowserTool.js"
 export * as Capabilities from "./capabilities/Capabilities.js"
 export * as Image from "./domain/Image.js"
 export * as Items from "./domain/Items.js"
@@ -18,6 +21,8 @@ export * as SandboxImage from "./sandbox/SandboxImage.js"
 export * as SandboxNetwork from "./sandbox/SandboxNetwork.js"
 export * as SpeechSynthesizer from "./speech-synthesizer/SpeechSynthesizer.js"
 export * as Transcriber from "./transcriber/Transcriber.js"
+export * as WebRead from "./web-read/WebRead.js"
+export * as WebReadTool from "./web-read/WebReadTool.js"
 export * as WebSearch from "./web-search/WebSearch.js"
 export * as WebSearchTool from "./web-search/WebSearchTool.js"
 export * as Vector from "./math/Vector.js"
@@ -34,3 +39,4 @@ export * as Lines from "./streaming/Lines.js"
 export * as SSE from "./streaming/SSE.js"
 export * as StructuredFormat from "./structured-format/StructuredFormat.js"
 export * as Metrics from "./observability/Metrics.js"
+export * as Telemetry from "./observability/Telemetry.js"

package/src/language-model/LanguageModel.ts

@@ -2,7 +2,7 @@ import { Array as Arr, Context, Effect, Option, Stream } from "effect"
 import * as AiError from "../domain/AiError.js"
 import type { HistoryItem } from "../domain/Items.js"
 import type * as StructuredFormat from "../structured-format/StructuredFormat.js"
-import type { ToolDescriptor } from "../tool/Tool.js"
+import type { Toolkit } from "../tool/Toolkit.js"
 import { isTurnComplete, type Turn, type TurnEvent } from "../domain/Turn.js"
 
 /**
@@ -18,7 +18,12 @@ export type CommonRequest = {
    * so code that yields a typed provider tag gets autocompletion.
    */
   readonly model: string
-  readonly tools?: ReadonlyArray<ToolDescriptor>
+  /**
+   * The model-visible tools for this request, as a `Toolkit`. The provider
+   * renders it to wire descriptors (`Tool.descriptorsOf`); omit it for a turn
+   * with no tools.
+   */
+  readonly tools?: Toolkit
   readonly toolChoice?:
     | "auto"
     | "required"

package/src/loop/Loop.test.ts

@@ -179,6 +179,28 @@ describe("Loop.loop", () => {
     expect(b.length).toBe(3)
   })
 
+  it("onTurnComplete: handler may return a step stream directly (not just Effect<Stream>)", async () => {
+    // The handler can skip the Effect wrapper when no effect is needed -
+    // bare stop() / next(s), mirroring loop's body.
+    const turnComplete: TurnEvent = TurnEvent.TurnComplete({
+      turn: { items: [], usage: { input_tokens: 0, output_tokens: 0 }, stop_reason: "stop" },
+    })
+    const deltas: Stream.Stream<TurnEvent> = Stream.fromIterable([
+      TurnEvent.TextDelta({ text: "hi" }),
+      turnComplete,
+    ])
+
+    const plain = deltas.pipe(onTurnComplete(() => stop()))
+    const effectful = deltas.pipe(onTurnComplete(() => Effect.sync(() => stop())))
+
+    const a = await Effect.runPromise(Stream.runCollect(plain))
+    const b = await Effect.runPromise(Stream.runCollect(effectful))
+
+    // Two value(delta) wraps + one stop sentinel; both return forms behave identically.
+    expect(a.length).toBe(3)
+    expect(b.length).toBe(3)
+  })
+
   it("is stack-safe and linear-time across many iterations", async () => {
     // 100k iterations far exceeds V8's typical stack depth (~10–15k frames).
     const N = 100_000

package/src/loop/Loop.ts

@@ -67,6 +67,16 @@ interface StepDef extends Data.TaggedEnum.WithGenerics<2> {
 
 const Step = Data.taggedEnum<StepDef>()
 
+/**
+ * Bare step constructors, so a loop body can emit `Value(...)`, `Next(...)`,
+ * `Stop()`, `StopWith(...)` directly inside a `Stream.make(...)` without the
+ * `Step.` prefix. (The `Step` object itself can't be exported under that name
+ * because it collides with the exported `Step` type.) For the common cases
+ * prefer the `value` / `next` / `stop` helpers, which also handle the
+ * single-element-stream wrapping for `next` / `stop`.
+ */
+export const { Value, Next, Stop, StopWith } = Step
+
 /** Wrap a value so it flows through the loop to downstream consumers. */
 export const value = <A>(a: A): Step<A, never> => Step.Value({ value: a })
 
@@ -103,6 +113,11 @@ export const stop = <S = never>(state?: S): Stream.Stream<Step<never, S>> =>
  * Pre-pipe transforms (`Stream.tap` / `Stream.map` / `Stream.filter`) on
  * the raw delta stream cover anything an `emit`-style callback would do.
  *
+ * `then` may return the step stream directly, or an `Effect` that produces
+ * it (for branches that need to read a `Ref`, decode tool args, log, etc.).
+ * Mirrors `loop`'s body: return a bare `stop()` / `next(s)` where no effect
+ * is needed, lift to `Effect` only where one is.
+ *
  * If the upstream ends without a `TurnComplete`, the resulting stream
  * fails with `AiError.IncompleteTurn`. Catch it via `Stream.catchTag` if
  * you want to recover.
@@ -110,21 +125,25 @@ export const stop = <S = never>(state?: S): Stream.Stream<Step<never, S>> =>
  * Dual: data-first `onTurnComplete(deltas, then)` and data-last
  * `deltas.pipe(onTurnComplete(then))` both work.
  */
+type TurnContinuation<S, A, E2, R2> =
+  | Stream.Stream<Step<A, S>, E2, R2>
+  | Effect.Effect<Stream.Stream<Step<A, S>, E2, R2>, E2, R2>
+
 export const onTurnComplete: {
   <S, A, E2 = never, R2 = never>(
-    then: (turn: Turn) => Effect.Effect<Stream.Stream<Step<A, S>, E2, R2>, E2, R2>,
+    then: (turn: Turn) => TurnContinuation<S, A, E2, R2>,
   ): <E, R>(
     deltas: Stream.Stream<TurnEvent, E, R>,
   ) => Stream.Stream<Step<TurnEvent | A, S>, E | E2 | IncompleteTurn, R | R2>
   <S, A, E, R, E2 = never, R2 = never>(
     deltas: Stream.Stream<TurnEvent, E, R>,
-    then: (turn: Turn) => Effect.Effect<Stream.Stream<Step<A, S>, E2, R2>, E2, R2>,
+    then: (turn: Turn) => TurnContinuation<S, A, E2, R2>,
   ): Stream.Stream<Step<TurnEvent | A, S>, E | E2 | IncompleteTurn, R | R2>
 } = Function.dual(
   2,
   <S, A, E, R, E2, R2>(
     deltas: Stream.Stream<TurnEvent, E, R>,
-    then: (turn: Turn) => Effect.Effect<Stream.Stream<Step<A, S>, E2, R2>, E2, R2>,
+    then: (turn: Turn) => TurnContinuation<S, A, E2, R2>,
   ): Stream.Stream<Step<TurnEvent | A, S>, E | E2 | IncompleteTurn, R | R2> =>
     Stream.unwrap(
       Effect.gen(function* () {
@@ -141,7 +160,8 @@ export const onTurnComplete: {
           Effect.gen(function* () {
             const opt = yield* Ref.get(turnRef)
             if (Option.isNone(opt)) return yield* new IncompleteTurn({})
-            return yield* then(opt.value)
+            const result = then(opt.value)
+            return Effect.isEffect(result) ? yield* result : result
           }),
         )
 
@@ -287,6 +307,9 @@ export const loop: {
             }
           })
 
+          // `Stream.fromPull` expects the generator to RETURN the pull effect,
+          // not run it; `return yield* pull` would execute a pull and break it.
+          // @effect-diagnostics-next-line effect/returnEffectInGen:off
           return pull
         }),
       ),

package/src/observability/Metrics.test.ts

@@ -0,0 +1,266 @@
+import { describe, it } from "@effect/vitest"
+import { Array as Arr, Duration, Effect, Fiber, Option, Stream } from "effect"
+import * as TestClock from "effect/testing/TestClock"
+import { expect } from "vitest"
+import type { Usage } from "../domain/Items.js"
+import { TurnEvent } from "../domain/Turn.js"
+import {
+  type MetricEvent,
+  type Throughput,
+  type TimeToCompletion,
+  type TimeToFirstToken,
+  type TokenTotals,
+  computeThroughputTick,
+  isMetricEvent,
+  makeEvent,
+  metricEvents,
+  throughput,
+  timeToCompletion,
+  timeToFirstToken,
+  tokenTotals,
+} from "./Metrics.js"
+
+const turnComplete = (usage: Usage): TurnEvent =>
+  TurnEvent.TurnComplete({ turn: { items: [], usage, stop_reason: "stop" } })
+
+const text = (s: string): TurnEvent => TurnEvent.TextDelta({ text: s })
+
+const samples = (events: ReadonlyArray<unknown>): ReadonlyArray<MetricEvent> =>
+  events.filter(isMetricEvent)
+
+const head = <A>(xs: ReadonlyArray<A>): A => Option.getOrThrow(Arr.head(xs))
+
+const tagged = <T extends MetricEvent["_tag"]>(
+  events: ReadonlyArray<unknown>,
+  tag: T,
+): ReadonlyArray<Extract<MetricEvent, { readonly _tag: T }>> =>
+  samples(events).filter((e): e is Extract<MetricEvent, { readonly _tag: T }> => e._tag === tag)
+
+// A stream that emits each event after the given delay since the previous one.
+const timed = <A>(steps: ReadonlyArray<readonly [Duration.Input, A]>): Stream.Stream<A> =>
+  Stream.fromIterable(steps).pipe(
+    Stream.mapEffect(([delay, ev]) => Effect.as(Effect.sleep(delay), ev)),
+  )
+
+// Collect a metered stream while advancing the test clock by each step, so
+// every per-event clock read lands at a known virtual time.
+const runTimed = <A>(
+  metered: Stream.Stream<A>,
+  steps: ReadonlyArray<Duration.Input>,
+): Effect.Effect<ReadonlyArray<A>> =>
+  Effect.gen(function* () {
+    const fiber = yield* Effect.forkChild(Stream.runCollect(metered))
+    yield* Effect.forEach(steps, (step) => TestClock.adjust(step), { discard: true })
+    return yield* Fiber.join(fiber)
+  })
+
+describe("tokenTotals", () => {
+  it.effect("turn level: a single TurnComplete reports that generation's usage", () =>
+    Effect.gen(function* () {
+      const stream = Stream.make(
+        text("hi"),
+        turnComplete({ input_tokens: 100, output_tokens: 20, total_tokens: 120 }),
+      )
+      const out = yield* Stream.runCollect(stream.pipe(tokenTotals))
+      const totals = tagged(out, "TokenTotals") as ReadonlyArray<TokenTotals>
+      expect(totals).toHaveLength(1)
+      expect(head(totals).turnIndex).toBe(0)
+      expect(head(totals).usage.output_tokens).toBe(20)
+      expect(head(totals).cumulative.output_tokens).toBe(20)
+    }),
+  )
+
+  it.effect("loop level: cumulative sums across every turn, usage stays per-turn", () =>
+    Effect.gen(function* () {
+      const stream = Stream.make(
+        text("a"),
+        turnComplete({ input_tokens: 1000, output_tokens: 120 }),
+        turnComplete({ input_tokens: 1300, output_tokens: 410 }),
+      )
+      const out = yield* Stream.runCollect(stream.pipe(tokenTotals))
+      const totals = tagged(out, "TokenTotals") as ReadonlyArray<TokenTotals>
+      expect(totals.map((t) => t.turnIndex)).toEqual([0, 1])
+      expect(totals.map((t) => t.usage.output_tokens)).toEqual([120, 410])
+      expect(totals.map((t) => t.cumulative.input_tokens)).toEqual([1000, 2300])
+      expect(totals.map((t) => t.cumulative.output_tokens)).toEqual([120, 530])
+    }),
+  )
+
+  it.effect("emits an incremental output_tokens counter measurement per turn", () =>
+    Effect.gen(function* () {
+      const stream = Stream.make(turnComplete({ output_tokens: 7 }))
+      const out = yield* Stream.runCollect(stream.pipe(tokenTotals))
+      const m = head(samples(out)).measurements.find((m) => m.name === "effect_uai_output_tokens")
+      expect(m).toEqual({ name: "effect_uai_output_tokens", kind: "counter", value: 7 })
+    }),
+  )
+})
+
+describe("timeToFirstToken", () => {
+  it.effect("fires on the first content delta, measured from request (stream init)", () =>
+    Effect.gen(function* () {
+      const stream = timed<TurnEvent>([
+        ["300 millis", text("hello")],
+        ["700 millis", turnComplete({})],
+      ]).pipe(timeToFirstToken())
+      const out = yield* runTimed(stream, ["300 millis", "700 millis"])
+      const ttft = tagged(out, "TimeToFirstToken") as ReadonlyArray<TimeToFirstToken>
+      expect(ttft).toHaveLength(1)
+      expect(Duration.toMillis(head(ttft).elapsed)).toBe(300)
+      expect(head(ttft).kind).toBe("text")
+    }),
+  )
+
+  it.effect("reports kind reasoning when reasoning arrives first", () =>
+    Effect.gen(function* () {
+      const stream = timed<TurnEvent>([
+        ["120 millis", TurnEvent.ReasoningDelta({ text: "...", kind: "trace" })],
+        ["80 millis", text("answer")],
+        ["50 millis", turnComplete({})],
+      ]).pipe(timeToFirstToken())
+      const out = yield* runTimed(stream, ["120 millis", "80 millis", "50 millis"])
+      const ttft = tagged(out, "TimeToFirstToken") as ReadonlyArray<TimeToFirstToken>
+      expect(ttft).toHaveLength(1)
+      expect(head(ttft).kind).toBe("reasoning")
+      expect(Duration.toMillis(head(ttft).elapsed)).toBe(120)
+    }),
+  )
+
+  it.effect("loop level: one TTFT per turn, turnIndex increments", () =>
+    Effect.gen(function* () {
+      const stream = timed<TurnEvent>([
+        ["200 millis", text("a")],
+        ["100 millis", turnComplete({})],
+        ["300 millis", text("b")],
+        ["100 millis", turnComplete({})],
+      ]).pipe(timeToFirstToken())
+      const out = yield* runTimed(stream, ["200 millis", "100 millis", "300 millis", "100 millis"])
+      const ttft = tagged(out, "TimeToFirstToken") as ReadonlyArray<TimeToFirstToken>
+      expect(ttft.map((t) => t.turnIndex)).toEqual([0, 1])
+      // turn 0 from init; turn 1 from the previous TurnComplete (loop-scope approximation)
+      expect(ttft.map((t) => Duration.toMillis(t.elapsed))).toEqual([200, 300])
+    }),
+  )
+})
+
+describe("timeToCompletion", () => {
+  it.effect("reports duration (request->complete) and generation (first token->complete)", () =>
+    Effect.gen(function* () {
+      const stream = timed<TurnEvent>([
+        ["300 millis", text("hi")],
+        ["700 millis", turnComplete({})],
+      ]).pipe(timeToCompletion)
+      const out = yield* runTimed(stream, ["300 millis", "700 millis"])
+      const done = tagged(out, "TimeToCompletion") as ReadonlyArray<TimeToCompletion>
+      expect(done).toHaveLength(1)
+      expect(Duration.toMillis(head(done).duration)).toBe(1000)
+      expect(Duration.toMillis(head(done).generation)).toBe(700)
+    }),
+  )
+})
+
+describe("computeThroughputTick", () => {
+  const base = {
+    units: 0,
+    lastUnits: 0,
+    lastMillis: 0,
+    firstMillis: Option.none<number>(),
+    smoothed: Option.none<number>(),
+    turnIndex: 0,
+  }
+
+  it("returns None before the first token", () => {
+    expect(Option.isNone(computeThroughputTick(base, 500, "windowed", undefined))).toBe(true)
+  })
+
+  it("windowed: rate is units in the last interval over that interval", () => {
+    const state = {
+      ...base,
+      units: 30,
+      lastUnits: 10,
+      lastMillis: 500,
+      firstMillis: Option.some(100),
+    }
+    const r = computeThroughputTick(state, 1000, "windowed", undefined)
+    // (30 - 10) units over (1000 - 500) ms = 40/s
+    expect(Option.getOrThrow(r).rate).toBe(40)
+  })
+
+  it("cumulative: rate is total units over time since first token", () => {
+    const state = {
+      ...base,
+      units: 30,
+      lastUnits: 10,
+      lastMillis: 500,
+      firstMillis: Option.some(100),
+    }
+    const r = computeThroughputTick(state, 1000, "cumulative", undefined)
+    // 30 units over (1000 - 100) ms ~= 33.33/s
+    expect(Option.getOrThrow(r).rate).toBeCloseTo(33.333, 2)
+  })
+
+  it("smooth: blends the instantaneous rate with the carried average", () => {
+    const state = {
+      ...base,
+      units: 20,
+      lastUnits: 0,
+      lastMillis: 0,
+      firstMillis: Option.some(0),
+      smoothed: Option.some(100),
+    }
+    // windowed instant = 20 units / 1000 ms = 20/s; smoothed = 0.5*20 + 0.5*100 = 60
+    const r = computeThroughputTick(state, 1000, "windowed", 0.5)
+    expect(Option.getOrThrow(r).rate).toBe(60)
+  })
+})
+
+describe("throughput (metronome)", () => {
+  it.effect("emits a live char rate on the tick, over the elapsed window", () =>
+    Effect.gen(function* () {
+      // 10 chars land at t=0; the source then stays open so the metronome can
+      // tick. take(1) ends the stream on the first sample, so termination does
+      // not depend on the source closing.
+      const source = Stream.make(text("aaaaa"), text("aaaaa")).pipe(
+        Stream.concat(timed<TurnEvent>([["10 seconds", turnComplete({})]])),
+      )
+      const stream = source.pipe(
+        throughput({ every: "1 second", unit: "char" }),
+        metricEvents,
+        Stream.take(1),
+      )
+      const out = yield* runTimed(stream, ["1 second"])
+      const rates = out.filter((e): e is Throughput => e._tag === "Throughput")
+      expect(rates).toHaveLength(1)
+      expect(head(rates).unit).toBe("char")
+      expect(head(rates).turnIndex).toBe(0)
+      // exact rate math is pinned by the computeThroughputTick tests; here we
+      // only assert the metronome wired a positive char rate onto the tick.
+      expect(head(rates).ratePerSecond).toBeGreaterThan(0)
+    }),
+  )
+})
+
+describe("custom events and helpers", () => {
+  it("makeEvent stamps the brand so isMetricEvent and the recorder see it", () => {
+    const ev = makeEvent({
+      _tag: "ToolLatency",
+      turnIndex: 0,
+      measurements: [{ name: "myapp_tool_latency", kind: "timer", value: Duration.millis(42) }],
+    })
+    expect(isMetricEvent(ev)).toBe(true)
+    expect(isMetricEvent(text("x"))).toBe(false)
+    expect(isMetricEvent(turnComplete({}))).toBe(false)
+  })
+
+  it.effect("metricEvents projects a mixed stream onto just the samples", () =>
+    Effect.gen(function* () {
+      const stream = Stream.make(text("hi"), turnComplete({ output_tokens: 3 })).pipe(
+        tokenTotals,
+        metricEvents,
+      )
+      const out = yield* Stream.runCollect(stream)
+      expect(out.every(isMetricEvent)).toBe(true)
+      expect(out.map((e) => e._tag)).toEqual(["TokenTotals"])
+    }),
+  )
+})