@effect-uai/ui 0.0.0-stage → 0.19.0-dev-20261109183959

package/src/Input.ts

@@ -0,0 +1,165 @@
+/**
+ * What a client sends to start or continue a run. The library only needs an
+ * `id` on an input (generated on the client, so optimistic UI can match it
+ * to `run-started { inputs }`); this module is a preset, and an app with a
+ * different shape passes its own schema.
+ *
+ * A `submit` carries user `messages` (core message items: the server appends
+ * them to its history as they are) and, with `make(DataSchema)`, typed `data` the server
+ * interprets (template id, model choice). Decode request bodies with the
+ * `*Json` codecs: they carry image bytes over JSON.
+ *
+ * Constructors build drafts without randomness; the id is assigned where an
+ * input is sent (`Atoms.submit`, or `withId`).
+ */
+import * as ToolDecision from "@effect-uai/core/ToolDecision"
+import * as Items from "@effect-uai/core/Items"
+import { Effect, Schema } from "effect"
+import { SecureRandom } from "effect/crypto"
+import { InputId } from "./RunEvent.js"
+
+/** A user message: core's `message` item with role `user` and input blocks only. */
+export const UserMessage = Schema.Struct({
+  type: Schema.Literal("message"),
+  role: Schema.Literal("user"),
+  content: Schema.Array(Schema.Union([Items.InputText, Items.InputImage])),
+})
+export type UserMessage = typeof UserMessage.Type
+export type Content = UserMessage["content"][number]
+
+/** The answer to one waiting call, with a decision of the app's `ToolDecision.make`. */
+export const answer = <D extends Schema.Top>(decision: D) =>
+  Schema.Struct({ callId: Schema.String, decision })
+
+/** The default answer: `ToolDecision.Default` (approve, or deny with an optional reason). */
+export const Decision = answer(ToolDecision.Default.schema)
+export type Decision = typeof Decision.Type
+
+const submitFields = {
+  id: InputId,
+  kind: Schema.Literal("submit"),
+  messages: Schema.Array(UserMessage),
+}
+
+const resolveFields = <D extends Schema.Top>(decision: D) => ({
+  id: InputId,
+  kind: Schema.Literal("resolve"),
+  decisions: Schema.Array(answer(decision)),
+})
+
+export const Submit = Schema.Struct(submitFields)
+export type Submit = typeof Submit.Type
+
+export const Resolve = Schema.Struct(resolveFields(ToolDecision.Default.schema))
+export type Resolve = typeof Resolve.Type
+
+export const Input = Schema.Union([Submit, Resolve])
+export type Input = typeof Input.Type
+
+export const SubmitJson = Schema.toCodecJson(Submit)
+export const InputJson = Schema.toCodecJson(Input)
+
+/**
+ * The preset with typed app `data` (required on `submit`, optional on
+ * `resolve`) and, optionally, the app's decisions (`ToolDecision.make(...).schema`).
+ */
+export function make<D extends Schema.Top>(data: D): Preset<D, typeof ToolDecision.Default.schema>
+export function make<D extends Schema.Top, A extends Schema.Top>(
+  data: D,
+  decisions: A,
+): Preset<D, A>
+export function make(data: Schema.Top, decisions: Schema.Top = ToolDecision.Default.schema) {
+  return preset(data, decisions)
+}
+
+type Preset<D extends Schema.Top, A extends Schema.Top> = ReturnType<typeof preset<D, A>>
+
+const preset = <D extends Schema.Top, A extends Schema.Top>(data: D, decisions: A) => {
+  const Submit = Schema.Struct({ ...submitFields, data })
+  const Resolve = Schema.Struct({ ...resolveFields(decisions), data: Schema.optionalKey(data) })
+  const Input = Schema.Union([Submit, Resolve])
+  return {
+    Submit,
+    Resolve,
+    Input,
+    SubmitJson: Schema.toCodecJson(Submit),
+    InputJson: Schema.toCodecJson(Input),
+  }
+}
+
+/** An input whose `id` is not assigned yet (per union member). */
+export type Draft<I> = I extends unknown ? Omit<I, "id"> & { readonly id?: InputId } : never
+
+/** A draft with its `id` assigned. */
+export type Identified<D> = D & { readonly id: InputId }
+
+/** What a transport receives for inputs of type `I`: the draft `submit` took, with its id. */
+export type Sent<I = Input> = Identified<Draft<I>>
+
+/** Assign a UUIDv7 id unless the draft already has one. */
+export const withId = <D extends { readonly id?: InputId }>(
+  draft: D,
+): Effect.Effect<Identified<D>, never, SecureRandom.SecureRandom> => {
+  const { id } = draft
+  return id !== undefined
+    ? Effect.succeed({ ...draft, id })
+    : SecureRandom.SecureRandom.use((random) => random.uuidV7()).pipe(
+        Effect.map((uuid) => ({ ...draft, id: InputId.make(uuid) })),
+      )
+}
+
+/** A user message: `text` first, then any attachments (images). */
+export const user = (text: string, attachments: ReadonlyArray<Content> = []): UserMessage => ({
+  type: "message",
+  role: "user",
+  content: [{ type: "input_text", text }, ...attachments],
+})
+
+type Id = { readonly id?: InputId }
+
+const toMessages = (messages: string | ReadonlyArray<UserMessage>): ReadonlyArray<UserMessage> =>
+  typeof messages === "string" ? [user(messages)] : messages
+
+export function submit(messages: string | ReadonlyArray<UserMessage>, options?: Id): Draft<Submit>
+export function submit<D>(
+  messages: string | ReadonlyArray<UserMessage>,
+  options: Id & { readonly data: D },
+): Draft<Submit> & { readonly data: D }
+export function submit(
+  messages: string | ReadonlyArray<UserMessage>,
+  options?: Id & { readonly data?: unknown },
+): Draft<Submit> & { readonly data?: unknown } {
+  return {
+    ...options,
+    kind: "submit",
+    messages: toMessages(messages),
+  }
+}
+
+/** A resolve draft; the decision type defaults to `ToolDecision.Default`'s. */
+export type ResolveDraft<A = Decision["decision"]> = {
+  readonly id?: InputId
+  readonly kind: "resolve"
+  readonly decisions: ReadonlyArray<ToolDecision.Answer<A>>
+}
+
+export function resolve<A = Decision["decision"]>(
+  decisions: ReadonlyArray<ToolDecision.Answer<A>>,
+  options?: Id,
+): ResolveDraft<A>
+export function resolve<A, D>(
+  decisions: ReadonlyArray<ToolDecision.Answer<A>>,
+  options: Id & { readonly data: D },
+): ResolveDraft<A> & { readonly data: D }
+export function resolve(
+  decisions: ReadonlyArray<ToolDecision.Answer<unknown>>,
+  options?: Id & { readonly data?: unknown },
+): ResolveDraft<unknown> & { readonly data?: unknown } {
+  return { ...options, kind: "resolve", decisions }
+}
+
+/** All text of the submit's messages, joined by blank lines. */
+export const text = (input: Pick<Submit, "messages">): string =>
+  input.messages
+    .flatMap((m) => m.content.flatMap((block) => (block.type === "input_text" ? [block.text] : [])))
+    .join("\n\n")

package/src/Projection.test.ts

@@ -0,0 +1,198 @@
+import type * as Items from "@effect-uai/core/Items"
+import { loop, onTurnComplete, stop } from "@effect-uai/core/Loop"
+import * as MockProvider from "@effect-uai/core/testing/MockProvider"
+import * as Tool from "@effect-uai/core/Tool"
+import * as Toolkit from "@effect-uai/core/Toolkit"
+import * as ToolOutput from "@effect-uai/core/ToolOutput"
+import * as Turn from "@effect-uai/core/Turn"
+import { describe, expect, it } from "@effect/vitest"
+import { Effect, pipe, Result, Schema, Stream } from "effect"
+import * as Projection from "./Projection.js"
+import type { RunEvent } from "./RunEvent.js"
+import * as UiContract from "./UiContract.js"
+
+class CityNotFound extends Schema.TaggedError<CityNotFound>()("CityNotFound", {
+  city: Schema.String,
+}) {}
+
+const getWeather = Tool.make({
+  name: "get_weather",
+  description: "Current weather for a city.",
+  inputSchema: Schema.Struct({ city: Schema.String }),
+  outputSchema: Schema.Struct({ city: Schema.String, observedAt: Schema.DateFromString }),
+  failureSchema: CityNotFound,
+  run: ({ city }) =>
+    city === "Atlantis"
+      ? Effect.fail(new CityNotFound({ city }))
+      : Effect.succeed({ city, observedAt: new Date("2026-01-01T12:00:00.000Z") }),
+})
+const search = Tool.make({
+  name: "search",
+  description: "Search.",
+  inputSchema: Tool.noInput,
+  outputSchema: Schema.Struct({ hits: Schema.Number }),
+  run: () => Stream.make({ hits: 1 }, { hits: 3 }),
+})
+const toolkit = Toolkit.make(getWeather, search)
+const contract = UiContract.make({ tools: [getWeather, search] })
+
+const usage = { input_tokens: 5, output_tokens: 5 }
+const callTurn = (calls: ReadonlyArray<readonly [string, string, string]>): Turn.Turn => ({
+  stop_reason: "tool_calls",
+  usage,
+  items: calls.map(([call_id, name, args]) => ({
+    type: "function_call",
+    call_id,
+    name,
+    arguments: args,
+  })),
+})
+const answerTurn: Turn.Turn = {
+  stop_reason: "stop",
+  usage,
+  items: [
+    { type: "reasoning", summary: "Weather tool says 19.4." },
+    { type: "message", role: "assistant", content: [{ type: "output_text", text: "Done." }] },
+  ],
+}
+
+type State = { readonly history: ReadonlyArray<Items.HistoryItem> }
+
+const runLoop = (turns: ReadonlyArray<Turn.Turn>) => {
+  const { service } = MockProvider.make(turns)
+  const initialState: State = { history: [] }
+  return pipe(
+    initialState,
+    loop((state: State) =>
+      service.streamTurn({ history: state.history, model: "mock", tools: toolkit }).pipe(
+        onTurnComplete((turn) =>
+          Effect.sync(() => {
+            const calls = Turn.getToolCalls(turn)
+            return calls.length === 0
+              ? stop()
+              : Toolkit.run(toolkit, calls, { concurrency: 1 }).pipe(
+                  Toolkit.next(toolkit, state, turn),
+                )
+          }),
+        ),
+      ),
+    ),
+    Projection.toRunEvents({ contract }),
+    Stream.runCollect,
+  )
+}
+
+describe("Projection.toRunEvents", () => {
+  it.effect("projects a tool loop: steps per turn, tool lifecycle, encoded outcomes", () =>
+    Effect.gen(function* () {
+      const events = yield* runLoop([
+        callTurn([
+          ["c1", "get_weather", `{"city":"Lisbon"}`],
+          ["c2", "get_weather", `{"city":"Atlantis"}`],
+        ]),
+        answerTurn,
+      ])
+      expect(events.filter((e) => e.type === "tool-result")).toEqual<ReadonlyArray<RunEvent>>([
+        {
+          type: "tool-result",
+          callId: "c1",
+          name: "get_weather",
+          result: {
+            _tag: "Success",
+            value: { city: "Lisbon", observedAt: "2026-01-01T12:00:00.000Z" },
+          },
+        },
+        {
+          type: "tool-result",
+          callId: "c2",
+          name: "get_weather",
+          result: { _tag: "Failure", error: { _tag: "CityNotFound", city: "Atlantis" } },
+        },
+      ])
+      expect(events.map((e) => e.type)).toEqual([
+        "step-started",
+        "tool-call-started",
+        "tool-call-started",
+        "tool-call-ready",
+        "tool-call-ready",
+        "step-finished",
+        "tool-result",
+        "tool-result",
+        "step-started",
+        "reasoning-started",
+        "text-delta",
+        "step-finished",
+      ])
+    }),
+  )
+
+  it.effect("projects a streaming tool's values as partials before its result", () =>
+    Effect.gen(function* () {
+      const events = yield* runLoop([callTurn([["s1", "search", "{}"]]), answerTurn])
+      expect(events.filter((e) => e.type === "tool-partial" || e.type === "tool-result")).toEqual<
+        ReadonlyArray<RunEvent>
+      >([
+        { type: "tool-partial", callId: "s1", name: "search", value: { hits: 1 } },
+        { type: "tool-partial", callId: "s1", name: "search", value: { hits: 3 } },
+        {
+          type: "tool-result",
+          callId: "s1",
+          name: "search",
+          result: { _tag: "Success", value: { hits: 3 } },
+        },
+      ])
+    }),
+  )
+
+  it.effect("projects a history item an app closed itself from its parts", () =>
+    Effect.gen(function* () {
+      const cancelled = yield* ToolOutput.failure(
+        { call_id: "c1" },
+        ToolOutput.CoreError,
+        new ToolOutput.Cancelled({ message: "user moved on" }),
+      )
+      const events = yield* Stream.fromIterable<Projection.Source>([
+        Turn.TurnEvent.TurnComplete({ turn: callTurn([["c1", "get_weather", "{}"]]) }),
+        cancelled,
+      ]).pipe(Projection.toRunEvents({ contract }), Stream.runCollect)
+      expect(events.at(-1)).toEqual<RunEvent>({
+        type: "tool-result",
+        callId: "c1",
+        name: "get_weather",
+        result: { _tag: "Failure", error: { _tag: "Cancelled", message: "user moved on" } },
+      })
+    }),
+  )
+
+  it.effect("fails the stream when a value doesn't fit its contract schema", () =>
+    Effect.gen(function* () {
+      const output: Projection.Source = {
+        _tag: "Output",
+        call_id: "c1",
+        tool: "search",
+        result: Result.succeed({ hits: "many" }),
+      }
+      const error = yield* Effect.flip(
+        Stream.make(output).pipe(Projection.toRunEvents({ contract }), Stream.runCollect),
+      )
+      expect(error._tag).toBe("SchemaError")
+    }),
+  )
+
+  it.effect("projects a refusal as refusal-delta, not as text", () =>
+    Stream.make(
+      Turn.TurnEvent.RefusalDelta({ text: "I can't help with that." }),
+      Turn.TurnEvent.TurnComplete({ turn: { stop_reason: "refusal", usage, items: [] } }),
+    ).pipe(
+      Projection.toRunEvents({ contract }),
+      Stream.runCollect,
+      Effect.map((events) =>
+        expect(events).toEqual<ReadonlyArray<RunEvent>>([
+          { type: "step-started" },
+          { type: "refusal-delta", text: "I can't help with that." },
+          { type: "step-finished", usage },
+        ]),
+      ),
+    ),
+  )
+})

package/src/Projection.ts

@@ -0,0 +1,142 @@
+/**
+ * Project an effect-uai loop onto `RunEvent`s. The projection is a fold pair
+ * (`initial`, `step`) because step boundaries need state; `toRunEvents` runs
+ * it over a stream. To add app events (metrics, domain data), map them
+ * yourself and delegate the rest to `step`.
+ *
+ * Never forwards `TurnComplete.turn` itself: it carries `providerData`
+ * (encrypted reasoning, item ids) that must not reach a browser.
+ */
+import type * as Items from "@effect-uai/core/Items"
+import type * as ToolEvent from "@effect-uai/core/ToolEvent"
+import * as Turn from "@effect-uai/core/Turn"
+import { Effect, Match, Option, Schema, Stream } from "effect"
+import type { Json, RunEvent } from "./RunEvent.js"
+import * as UiContract from "./UiContract.js"
+
+/** What an effect-uai loop emits: turn events, tool events, and plain tool outputs. */
+export type Source = Turn.TurnEvent | ToolEvent.ToolEvent | Items.ToolCallOutput
+
+export const Options = Schema.Struct({
+  /**
+   * `"signal"` (default): only `reasoning-started`. `"summary"`: also
+   * forward summary deltas. `"full"`: also forward raw reasoning traces.
+   */
+  reasoning: Schema.optionalKey(Schema.Literals(["signal", "summary", "full"])),
+  /** Forward raw tool-argument deltas (`tool-call-args-delta`). Default false. */
+  toolArgs: Schema.optionalKey(Schema.Boolean),
+})
+export type Options = typeof Options.Type
+
+/** `Options` plus the contract whose tool schemas encode tool values and errors. */
+export type Config = Options & {
+  readonly contract: Pick<UiContract.UiContract<any>, "toolEvent" | "toolOutput">
+}
+
+export const State = Schema.Struct({
+  inStep: Schema.Boolean,
+  reasoningShown: Schema.Boolean,
+  /** Tool names by call id, for outputs that arrive as plain `function_call_output` items. */
+  tools: Schema.Record(Schema.String, Schema.String),
+})
+export type State = typeof State.Type
+
+export const initial: State = { inStep: false, reasoningShown: false, tools: {} }
+
+type Step = readonly [State, ReadonlyArray<RunEvent>]
+
+// Tool arguments are a JSON string; hand the client the decoded value, falling
+// back to the raw string when it isn't JSON.
+const parseJson = Schema.decodeUnknownOption(Schema.fromJsonString(Schema.Json))
+const decodeJson = (raw: string): Json => Option.getOrElse(parseJson(raw), () => raw)
+
+// Content belongs to a step (one model turn); open one lazily on its first event.
+const inStep = (s: State, events: ReadonlyArray<RunEvent>): Step =>
+  s.inStep
+    ? [s, events]
+    : [{ ...s, inStep: true, reasoningShown: false }, [{ type: "step-started" }, ...events]]
+
+const reasoning =
+  (options: Options | undefined) =>
+  (s: State, e: Extract<Turn.TurnEvent, { _tag: "ReasoningDelta" }>): Step => {
+    const mode = options?.reasoning ?? "signal"
+    const forward = mode === "full" || (mode === "summary" && e.kind === "summary")
+    const [opened, prefix] = inStep(s, [])
+    const started: ReadonlyArray<RunEvent> = opened.reasoningShown
+      ? []
+      : [{ type: "reasoning-started" }]
+    const delta: ReadonlyArray<RunEvent> = forward
+      ? [{ type: "reasoning-delta", text: e.text, kind: e.kind }]
+      : []
+    return [{ ...opened, reasoningShown: true }, [...prefix, ...started, ...delta]]
+  }
+
+const turnComplete = (s: State, turn: Turn.Turn): Step => {
+  const calls = Turn.getToolCalls(turn)
+  const ready = calls.map((call): RunEvent => ({
+    type: "tool-call-ready",
+    callId: call.call_id,
+    name: call.name,
+    input: decodeJson(call.arguments),
+  }))
+  const [, events] = inStep(s, [...ready, { type: "step-finished", usage: turn.usage }])
+  const tools = { ...s.tools, ...Object.fromEntries(calls.map((c) => [c.call_id, c.name])) }
+  return [{ ...initial, tools }, events]
+}
+
+// A history item already holds the encoded value; the contract shapes it for the wire.
+const outputResult = (config: Config, s: State, o: Items.ToolCallOutput) =>
+  Effect.map(config.contract.toolOutput(o, s.tools[o.call_id] ?? ""), (event): Step => [s, [event]])
+
+/** Map one loop event onto zero or more `RunEvent`s; tool values are encoded by the contract. */
+export const step =
+  (config: Config) =>
+  (s: State, event: Source): Effect.Effect<Step, Schema.SchemaError> =>
+    Match.value(event).pipe(
+      Match.when({ type: "function_call_output" }, (o) => outputResult(config, s, o)),
+      Match.tags({
+        Partial: (e) => Effect.map(config.contract.toolEvent(e), (r): Step => [s, [r]]),
+        Output: (e) => Effect.map(config.contract.toolEvent(e), (r): Step => [s, [r]]),
+      }),
+      Match.orElse((e) => Effect.succeed(turnStep(config)(s, e))),
+    )
+
+const turnStep =
+  (options: Options) =>
+  (s: State, event: Turn.TurnEvent): Step =>
+    Match.value(event).pipe(
+      Match.tagsExhaustive({
+        TextDelta: (e) => inStep(s, [{ type: "text-delta", text: e.text }]),
+        RefusalDelta: (e) => inStep(s, [{ type: "refusal-delta", text: e.text }]),
+        ReasoningDelta: (e) => reasoning(options)(s, e),
+        ToolCallStart: (e) =>
+          inStep(s, [{ type: "tool-call-started", callId: e.call_id, name: e.name }]),
+        ToolCallArgsDelta: (e) =>
+          inStep(
+            s,
+            options?.toolArgs === true
+              ? [{ type: "tool-call-args-delta", callId: e.call_id, delta: e.delta }]
+              : [],
+          ),
+        CitationAdded: (e) => inStep(s, [{ type: "citation", annotation: e.annotation }]),
+        ImageOutput: (e) =>
+          inStep(s, [
+            e.partialIndex === undefined
+              ? { type: "image", image: e.image }
+              : { type: "image", image: e.image, partialIndex: e.partialIndex },
+          ]),
+        // Usage arrives on `step-finished`; search progress has no UI event yet.
+        UsageUpdate: (): Step => [s, []],
+        WebSearchCall: (): Step => [s, []],
+        TurnComplete: (e) => turnComplete(s, e.turn),
+      }),
+    )
+
+/**
+ * Stream operator: project a loop's events onto `RunEvent`s. A tool value the
+ * contract can't encode fails the stream: a contract violation, not data to show.
+ */
+export const toRunEvents =
+  (config: Config) =>
+  <E, R>(self: Stream.Stream<Source, E, R>): Stream.Stream<RunEvent, E | Schema.SchemaError, R> =>
+    self.pipe(Stream.mapAccumEffect(() => initial, step(config)))

package/src/Run.test.ts

@@ -0,0 +1,119 @@
+import * as AiError from "@effect-uai/core/AiError"
+import { describe, it } from "@effect/vitest"
+import { Deferred, Effect, Fiber, Stream } from "effect"
+import { expect } from "vitest"
+import * as Run from "./Run.js"
+import { InputId, RunId, type RunEvent, StreamId } from "./RunEvent.js"
+
+const r1 = RunId.make("r1")
+const text = (t: string): RunEvent => ({ type: "text-delta", text: t })
+const types = (events: ReadonlyArray<RunEvent>) => events.map((e) => e.type)
+
+describe("Run frame", () => {
+  const frame = <E>(body: Stream.Stream<RunEvent, E>) =>
+    body.pipe(
+      Stream.catchCause((cause) => Stream.succeed(Run.failed(cause))),
+      Run.start({ runId: r1, inputs: [InputId.make("in_1")] }),
+      Run.complete,
+    )
+
+  it.effect("brackets a successful body with run-started and run-completed", () =>
+    frame(Stream.make(text("hi"))).pipe(
+      Stream.runCollect,
+      Effect.map((events) => {
+        expect(types(events)).toEqual(["run-started", "text-delta", "run-completed"])
+        expect(events[0]).toMatchObject({ runId: "r1", inputs: ["in_1"] })
+      }),
+    ),
+  )
+
+  it.effect("turns a failure into run-failed with the error's tag", () =>
+    frame(
+      Stream.make(text("partial")).pipe(
+        Stream.concat(Stream.fail(new AiError.RateLimited({ provider: "x", raw: null }))),
+      ),
+    ).pipe(
+      Stream.runCollect,
+      Effect.map((events) => {
+        expect(types(events)).toEqual(["run-started", "text-delta", "run-failed"])
+        expect(events.at(-1)).toEqual({ type: "run-failed", reason: "RateLimited" })
+      }),
+    ),
+  )
+
+  it.effect("lets the body's own terminal win and end the run", () =>
+    frame(
+      Stream.fromIterable<RunEvent>([
+        text("needs approval"),
+        { type: "run-interrupted", interrupts: [] },
+        text("never sent"),
+      ]),
+    ).pipe(
+      Stream.runCollect,
+      Effect.map((events) =>
+        expect(types(events)).toEqual(["run-started", "text-delta", "run-interrupted"]),
+      ),
+    ),
+  )
+
+  it.effect("ends with run-stopped when the stop signal completes", () =>
+    Effect.gen(function* () {
+      const stop = yield* Deferred.make<void>()
+      const fiber = yield* Stream.make(text("streaming")).pipe(
+        Stream.concat(Stream.never),
+        Run.stopWhen(Deferred.await(stop)),
+        frame,
+        Stream.runCollect,
+        Effect.forkChild,
+      )
+      yield* Deferred.succeed(stop, undefined)
+      const events = yield* Fiber.join(fiber)
+      expect(types(events)).toEqual(["run-started", "text-delta", "run-stopped"])
+    }),
+  )
+})
+
+describe("Run.sequence", () => {
+  it.effect("numbers frames per stream and tags run-scoped ones with the open run", () =>
+    Stream.fromIterable<RunEvent>([
+      { type: "data", name: "before", value: 1 },
+      { type: "run-started", runId: r1, inputs: [], protocol: 2 },
+      text("hi"),
+      { type: "run-completed" },
+      { type: "live", name: "after", value: 2 },
+    ]).pipe(
+      Run.sequence(StreamId.make("st_1"), { from: 10 }),
+      Stream.runCollect,
+      Effect.map((frames) => {
+        expect(frames.map((f) => f.seq)).toEqual([11, 12, 13, 14, 15])
+        expect(frames.map((f) => f.runId)).toEqual([undefined, "r1", "r1", "r1", undefined])
+      }),
+    ),
+  )
+})
+
+describe("Run.coalesce", () => {
+  it.effect("merges adjacent deltas of the same kind and keeps everything else in order", () =>
+    Stream.fromIterable<RunEvent>([
+      text("Hel"),
+      text("lo"),
+      { type: "tool-call-args-delta", callId: "c1", delta: `{"a"` },
+      { type: "tool-call-args-delta", callId: "c1", delta: ":1}" },
+      { type: "tool-call-args-delta", callId: "c2", delta: "{}" },
+      { type: "step-finished" },
+      text("!"),
+    ]).pipe(
+      Run.coalesce("50 millis"),
+      Stream.runCollect,
+      Effect.map((events) =>
+        expect(events).toEqual<ReadonlyArray<RunEvent>>([
+          text("Hello"),
+          { type: "tool-call-args-delta", callId: "c1", delta: `{"a":1}` },
+          { type: "tool-call-args-delta", callId: "c2", delta: "{}" },
+          { type: "step-finished" },
+          text("!"),
+        ]),
+      ),
+    ),
+  )
+})