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

package/src/Run.ts

@@ -0,0 +1,166 @@
+/**
+ * Server-side stream operators for runs. Each does one thing; a run pipes
+ * the ones it needs:
+ *
+ *   agent(history).pipe(
+ *     Projection.toRunEvents({ contract }),
+ *     Run.coalesce("30 millis"),
+ *     Stream.catchCause((cause) => Stream.succeed(Run.failed(cause))),
+ *     Run.stopWhen(Deferred.await(stop)), // durable runs
+ *     Run.start({ runId, inputs }),
+ *     Run.complete,
+ *     Run.sequence(streamId),
+ *   )
+ *
+ * In this order they keep the protocol's rule: `run-started` first, exactly
+ * one terminal last. Direct mode needs no stop: when the client goes away,
+ * the server interrupts the stream (Effect's `HttpServer`, or
+ * `HttpRouter.toWebHandler` behind a framework's route).
+ */
+import { Array as Arr, Cause, Effect, Predicate, Schema, Stream } from "effect"
+import type * as Duration from "effect/Duration"
+import {
+  type Envelope,
+  type InputId,
+  isTerminal,
+  PROTOCOL_VERSION,
+  RunId,
+  type RunEvent,
+  type StreamId,
+} from "./RunEvent.js"
+
+// ---------------------------------------------------------------------------
+// A run's frame: start, stop, failure, completion
+// ---------------------------------------------------------------------------
+
+export type StartOptions = {
+  readonly runId: RunId
+  /** Client input ids the run answers. */
+  readonly inputs?: ReadonlyArray<InputId>
+  /** Role label when a stream carries several kinds of run. */
+  readonly name?: string
+}
+
+/** Prepend `run-started`. */
+export const start =
+  (options: StartOptions) =>
+  <E, R>(self: Stream.Stream<RunEvent, E, R>): Stream.Stream<RunEvent, E, R> => {
+    const started: RunEvent = {
+      type: "run-started",
+      runId: options.runId,
+      inputs: options.inputs ?? [],
+      protocol: PROTOCOL_VERSION,
+      ...(options.name !== undefined ? { name: options.name } : {}),
+    }
+    return Stream.make(started).pipe(Stream.concat(self))
+  }
+
+/** End the run at its first terminal; append `run-completed` if it ends without one. */
+export const complete = <E, R>(
+  self: Stream.Stream<RunEvent, E, R>,
+): Stream.Stream<RunEvent, E, R> =>
+  self.pipe(
+    Stream.takeUntil(isTerminal),
+    Stream.mapAccum(
+      () => false,
+      (ended, event): readonly [boolean, ReadonlyArray<RunEvent>] => [
+        ended || isTerminal(event),
+        [event],
+      ],
+      { onHalt: (ended): ReadonlyArray<RunEvent> => (ended ? [] : [{ type: "run-completed" }]) },
+    ),
+  )
+
+/** End the run with `run-stopped` when `signal` completes (e.g. a stop `Deferred`). */
+export const stopWhen =
+  (signal: Effect.Effect<void>) =>
+  <E, R>(self: Stream.Stream<RunEvent, E, R>): Stream.Stream<RunEvent, E, R> =>
+    self.pipe(
+      Stream.merge(Stream.fromEffect(Effect.as(signal, { type: "run-stopped" } as const)), {
+        haltStrategy: "left",
+      }),
+      Stream.takeUntil((event) => event.type === "run-stopped"),
+    )
+
+/** A `run-failed` for a failed stream: `reason` is the error's `_tag`, else `"internal"`. */
+export const failed = (cause: Cause.Cause<unknown>): RunEvent => {
+  const error = Cause.squash(cause)
+  const reason =
+    Predicate.hasProperty(error, "_tag") && Predicate.isString(error._tag) ? error._tag : "internal"
+  return { type: "run-failed", reason }
+}
+
+// ---------------------------------------------------------------------------
+// sequence
+// ---------------------------------------------------------------------------
+
+export const SequenceState = Schema.Struct({
+  seq: Schema.Int,
+  /** Id of the run currently open on this stream. */
+  runId: Schema.optionalKey(RunId),
+})
+export type SequenceState = typeof SequenceState.Type
+
+const sequenceStep =
+  (streamId: StreamId) =>
+  (s: SequenceState, event: RunEvent): readonly [SequenceState, ReadonlyArray<Envelope>] => {
+    const runId = event.type === "run-started" ? event.runId : s.runId
+    const seq = s.seq + 1
+    const envelope: Envelope =
+      runId === undefined ? { streamId, seq, event } : { streamId, seq, runId, event }
+    const next: SequenceState = runId === undefined || isTerminal(event) ? { seq } : { seq, runId }
+    return [next, [envelope]]
+  }
+
+/**
+ * Wrap events in envelopes with a per-stream `seq` (starting after `from`,
+ * default 0) and the current run's id, taken from the last `run-started`.
+ */
+export const sequence =
+  (streamId: StreamId, options?: { readonly from?: number }) =>
+  <E, R>(self: Stream.Stream<RunEvent, E, R>): Stream.Stream<Envelope, E, R> =>
+    self.pipe(
+      Stream.mapAccum((): SequenceState => ({ seq: options?.from ?? 0 }), sequenceStep(streamId)),
+    )
+
+// ---------------------------------------------------------------------------
+// coalesce
+// ---------------------------------------------------------------------------
+
+const merge = (a: RunEvent, b: RunEvent): RunEvent | undefined => {
+  if (a.type === "text-delta" && b.type === "text-delta") return { ...a, text: a.text + b.text }
+  if (a.type === "refusal-delta" && b.type === "refusal-delta")
+    return { ...a, text: a.text + b.text }
+  if (a.type === "reasoning-delta" && b.type === "reasoning-delta" && a.kind === b.kind) {
+    return { ...a, text: a.text + b.text }
+  }
+  if (
+    a.type === "tool-call-args-delta" &&
+    b.type === "tool-call-args-delta" &&
+    a.callId === b.callId
+  ) {
+    return { ...a, delta: a.delta + b.delta }
+  }
+  return undefined
+}
+
+const mergeAdjacent = (group: ReadonlyArray<RunEvent>): ReadonlyArray<RunEvent> =>
+  Arr.reduce(group, Arr.empty<RunEvent>(), (acc: ReadonlyArray<RunEvent>, event) => {
+    const last = acc.at(-1)
+    const merged = last === undefined ? undefined : merge(last, event)
+    return merged === undefined ? [...acc, event] : [...acc.slice(0, -1), merged]
+  })
+
+/**
+ * Merge consecutive text, reasoning and tool-argument deltas that arrive
+ * within `window`; every other event passes through unchanged and in order.
+ * Bounds frames on the wire and rows in a durable log; adds up to `window`
+ * latency.
+ */
+export const coalesce =
+  (window: Duration.Input) =>
+  <E, R>(self: Stream.Stream<RunEvent, E, R>): Stream.Stream<RunEvent, E, R> =>
+    self.pipe(
+      Stream.groupedWithin(1024, window),
+      Stream.flatMap((group) => Stream.fromIterable(mergeAdjacent(group))),
+    )

package/src/RunEvent.test.ts

@@ -0,0 +1,84 @@
+import { describe, it } from "@effect/vitest"
+import { Effect, Exit, Schema } from "effect"
+import { expect } from "vitest"
+import * as RunEvent from "./RunEvent.js"
+
+const Wire = Schema.fromJsonString(RunEvent.EnvelopeJson)
+const encode = Schema.encodeEffect(Wire)
+const decode = Schema.decodeUnknownEffect(Wire)
+
+const r1 = RunEvent.RunId.make("r1")
+
+const envelope = (seq: number, event: RunEvent.RunEvent): RunEvent.Envelope => ({
+  streamId: RunEvent.StreamId.make("st_1"),
+  seq,
+  runId: r1,
+  event,
+})
+
+describe("RunEvent wire codec", () => {
+  it.effect.each([
+    {
+      label: "run-started",
+      frame: envelope(1, {
+        type: "run-started",
+        runId: r1,
+        inputs: [RunEvent.InputId.make("in_1")],
+        protocol: 2,
+      }),
+    },
+    {
+      label: "tool-call-ready",
+      frame: envelope(2, {
+        type: "tool-call-ready",
+        callId: "c1",
+        name: "get_weather",
+        input: { city: "Lisbon" },
+      }),
+    },
+    {
+      label: "image bytes",
+      frame: envelope(3, {
+        type: "image",
+        image: { _tag: "bytes", bytes: new Uint8Array([137, 80, 78, 71]), mimeType: "image/png" },
+      }),
+    },
+    {
+      label: "object-delta patch",
+      frame: envelope(4, {
+        type: "object-delta",
+        id: "o1",
+        patch: [{ op: "add", path: "/items/-", value: "eggs" }],
+      }),
+    },
+    {
+      label: "run-completed",
+      frame: envelope(5, { type: "run-completed", metadata: { usage: { input_tokens: 10 } } }),
+    },
+  ])("round-trips $label through JSON", ({ frame }) =>
+    encode(frame).pipe(
+      Effect.flatMap(decode),
+      Effect.map((decoded) => expect(decoded).toEqual(frame)),
+    ),
+  )
+
+  it.effect.each([
+    { label: "an unknown event type", frame: { streamId: "s", seq: 1, event: { type: "nope" } } },
+    {
+      label: "another protocol version",
+      frame: {
+        streamId: "s",
+        seq: 1,
+        event: { type: "run-started", runId: "r1", inputs: [], protocol: 1 },
+      },
+    },
+    {
+      label: "a seq below 1",
+      frame: { streamId: "s", seq: 0, event: { type: "text-delta", text: "hi" } },
+    },
+  ])("rejects $label", ({ frame }) =>
+    Effect.exit(decode(JSON.stringify(frame))).pipe(
+      Effect.map((exit) => expect(Exit.isFailure(exit)).toBe(true)),
+    ),
+  )
+})

package/src/RunEvent.ts

@@ -0,0 +1,374 @@
+/**
+ * The `@effect-uai/ui` wire protocol (v1): what a server streams to a client
+ * about agent runs. Every frame is an `Envelope`; `seq` is per stream,
+ * starts at 1 and never repeats, so clients dedupe and resume by it.
+ *
+ * A run starts with `run-started` and ends with exactly one terminal
+ * (`run-completed`, `run-interrupted`, `run-failed`, `run-stopped`). Field
+ * names are camelCase; the event discriminator is `type`.
+ */
+import * as Img from "@effect-uai/core/Image"
+import * as Items from "@effect-uai/core/Items"
+import { Schema } from "effect"
+
+export const PROTOCOL_VERSION = 2
+
+// ---------------------------------------------------------------------------
+// Ids: branded so a stream, run and input id can't be swapped. Wire decoding
+// brands them; build one by hand with `StreamId.make("st_1")`.
+// ---------------------------------------------------------------------------
+
+export const StreamId = Schema.String.pipe(Schema.brand("StreamId"))
+export type StreamId = typeof StreamId.Type
+
+export const RunId = Schema.String.pipe(Schema.brand("RunId"))
+export type RunId = typeof RunId.Type
+
+/** Client-generated id of one input. */
+export const InputId = Schema.String.pipe(Schema.brand("InputId"))
+export type InputId = typeof InputId.Type
+
+const event = <const T extends string, const F extends Schema.Struct.Fields>(type: T, fields: F) =>
+  Schema.Struct({ type: Schema.Literal(type), ...fields })
+
+// ---------------------------------------------------------------------------
+// Run lifecycle
+// ---------------------------------------------------------------------------
+
+export const RunStarted = event("run-started", {
+  runId: RunId,
+  /** Role of the run when a stream carries several, e.g. "assistant", "reviewer". */
+  name: Schema.optional(Schema.String),
+  /** Client input ids this run consumed, for optimistic-UI reconciliation. */
+  inputs: Schema.Array(InputId),
+  protocol: Schema.Literal(PROTOCOL_VERSION),
+})
+
+/** A pause point the client must answer (today: a tool call awaiting approval). */
+export const Interrupt = Schema.Struct({
+  callId: Schema.String,
+  reason: Schema.Literal("approval"),
+  name: Schema.String,
+  input: Schema.Json,
+})
+
+export const RunCompleted = event("run-completed", { metadata: Schema.optional(Schema.Json) })
+export const RunInterrupted = event("run-interrupted", { interrupts: Schema.Array(Interrupt) })
+/** `reason` is a short code (an error's `_tag`); whether to offer a retry is the client's call. */
+export const RunFailed = event("run-failed", {
+  reason: Schema.String,
+  message: Schema.optional(Schema.String),
+})
+export const RunStopped = event("run-stopped", {})
+
+// ---------------------------------------------------------------------------
+// Steps (one per model turn) and content
+// ---------------------------------------------------------------------------
+
+export const StepStarted = event("step-started", {})
+export const StepFinished = event("step-finished", { usage: Schema.optional(Items.Usage) })
+/** Discard the current step's partial output (mid-stream fallback or retry). */
+export const StepReset = event("step-reset", {})
+
+export const TextDelta = event("text-delta", { text: Schema.String })
+/** The model declined to answer; distinct from text (core's `refusal` block). */
+export const RefusalDelta = event("refusal-delta", { text: Schema.String })
+export const ReasoningStarted = event("reasoning-started", {})
+export const ReasoningDelta = event("reasoning-delta", {
+  text: Schema.String,
+  kind: Schema.Literals(["trace", "summary"]),
+})
+export const Citation = event("citation", { annotation: Items.Annotation })
+export const Image = event("image", {
+  image: Img.ImageSource,
+  /** Set only on a preview frame; absent means final. */
+  partialIndex: Schema.optional(Schema.Number),
+})
+
+// ---------------------------------------------------------------------------
+// Structured objects
+// ---------------------------------------------------------------------------
+
+const JsonPatchOperation = Schema.Union([
+  Schema.Struct({ op: Schema.Literal("add"), path: Schema.String, value: Schema.Json }),
+  Schema.Struct({ op: Schema.Literal("remove"), path: Schema.String }),
+  Schema.Struct({ op: Schema.Literal("replace"), path: Schema.String, value: Schema.Json }),
+])
+
+export const ObjectStarted = event("object-started", {
+  id: Schema.String,
+  /** Which schema or list the object belongs to. */
+  name: Schema.optional(Schema.String),
+})
+/** Either a JSON Patch against the previous partial value, or a snapshot `value`. */
+export const ObjectDelta = event("object-delta", {
+  id: Schema.String,
+  patch: Schema.optional(Schema.Array(JsonPatchOperation)),
+  value: Schema.optional(Schema.Json),
+})
+export const ObjectDone = event("object-done", {
+  id: Schema.String,
+  /** The object's name again, so a client can decode `value` without state. */
+  name: Schema.optional(Schema.String),
+  value: Schema.Json,
+})
+export const ObjectFailed = event("object-failed", {
+  id: Schema.String,
+  issues: Schema.Array(
+    Schema.Struct({
+      path: Schema.Array(Schema.Union([Schema.String, Schema.Number])),
+      message: Schema.String,
+    }),
+  ),
+})
+
+// ---------------------------------------------------------------------------
+// Tools
+// ---------------------------------------------------------------------------
+
+export const ToolCallStarted = event("tool-call-started", {
+  callId: Schema.String,
+  name: Schema.String,
+})
+export const ToolCallArgsDelta = event("tool-call-args-delta", {
+  callId: Schema.String,
+  delta: Schema.String,
+})
+export const ToolCallReady = event("tool-call-ready", {
+  callId: Schema.String,
+  name: Schema.String,
+  input: Schema.Json,
+})
+/** The run is waiting in-process for a decision on this call (it keeps running). */
+export const ToolApprovalRequested = event("tool-approval-requested", {
+  callId: Schema.String,
+  name: Schema.String,
+  input: Schema.Json,
+})
+/** An intermediate value of a streaming tool, encoded like its output. */
+export const ToolPartial = event("tool-partial", {
+  callId: Schema.String,
+  name: Schema.String,
+  value: Schema.Json,
+})
+
+/** How a call ended: its output, or an error (the tool's, core's, or the app's). */
+export const outcome = <V extends Schema.Top, E extends Schema.Top>(value: V, error: E) =>
+  Schema.Union([
+    Schema.TaggedStruct("Success", { value }),
+    Schema.TaggedStruct("Failure", { error }),
+  ])
+
+/** An outcome as sent: value and error are JSON. */
+export const Outcome = outcome(Schema.Json, Schema.Json)
+
+export type Outcome<V = Json, E = Json> =
+  | { readonly _tag: "Success"; readonly value: V }
+  | { readonly _tag: "Failure"; readonly error: E }
+
+/**
+ * Every call ends with one `tool-result`: calls that ran, and calls the app
+ * closed itself (denied, cancelled, answered by the user).
+ */
+export const ToolResult = event("tool-result", {
+  callId: Schema.String,
+  /** The tool's name, so a client can decode `result` without state. */
+  name: Schema.String,
+  result: Outcome,
+})
+
+// ---------------------------------------------------------------------------
+// Usage and app payloads
+// ---------------------------------------------------------------------------
+
+export const Usage = event("usage", { usage: Items.Usage })
+/** Persisted app payload; a repeated `id` replaces the earlier one in place. */
+export const Data = event("data", {
+  name: Schema.String,
+  value: Schema.Json,
+  id: Schema.optional(Schema.String),
+})
+/** Transient app payload (metrics, status); latest value wins, never stored in a message. */
+export const Live = event("live", { name: Schema.String, value: Schema.Json })
+
+/**
+ * Stream-scoped: the server accepted an input (queued or about to run). Lets a
+ * reloaded client show inputs that wait for their run. `input` is the app's
+ * encoded input (e.g. `Input.InputJson`); its run's `run-started` lists its id.
+ */
+export const InputAccepted = event("input-accepted", { input: Schema.Json })
+
+// ---------------------------------------------------------------------------
+// Unions and envelope
+// ---------------------------------------------------------------------------
+
+/** Events whose payloads a contract types (see `UiContract`). */
+export const payloadEvents = [
+  RunCompleted,
+  RunInterrupted,
+  ObjectDone,
+  ToolCallReady,
+  ToolApprovalRequested,
+  ToolPartial,
+  ToolResult,
+  Data,
+  Live,
+] as const
+
+/** Events a contract leaves as they are. */
+export const plainEvents = [
+  RunStarted,
+  RunFailed,
+  RunStopped,
+  StepStarted,
+  StepFinished,
+  StepReset,
+  TextDelta,
+  RefusalDelta,
+  ReasoningStarted,
+  ReasoningDelta,
+  Citation,
+  Image,
+  ObjectStarted,
+  ObjectDelta,
+  ObjectFailed,
+  ToolCallStarted,
+  ToolCallArgsDelta,
+  Usage,
+  InputAccepted,
+] as const
+
+/** The protocol as sent: payloads are JSON. A contract decodes them (`UiContract`). */
+export const RunEvent = Schema.Union([...plainEvents, ...payloadEvents])
+
+export const envelopeFields = {
+  streamId: StreamId,
+  seq: Schema.Int.check(Schema.isGreaterThanOrEqualTo(1)),
+  /** Set on run-scoped events; absent on stream-scoped ones. */
+  runId: Schema.optional(RunId),
+}
+
+export const Envelope = Schema.Struct({ ...envelopeFields, event: RunEvent })
+
+/** JSON codec for the wire: `Uint8Array` image bytes and other non-JSON values encode safely. */
+export const EnvelopeJson = Schema.toCodecJson(Envelope)
+
+// ---------------------------------------------------------------------------
+// Payload types: what a contract types. `P` defaults to `Untyped` (JSON as sent).
+// ---------------------------------------------------------------------------
+
+export type Json = Schema.Json
+
+export type ToolPayload = {
+  readonly name: string
+  readonly input: unknown
+  readonly output: unknown
+  /** Every error a call of this tool can end with. */
+  readonly failure: unknown
+}
+export type NamedPayload = { readonly name: string; readonly value: unknown }
+
+/** Typed payloads: each field is a union with one member per name. */
+export type Payloads = {
+  readonly tool: ToolPayload
+  readonly object: NamedPayload
+  readonly data: NamedPayload
+  readonly live: NamedPayload
+  readonly metadata: unknown
+}
+
+/** No contract: any name, payloads as sent. */
+export type Untyped = {
+  readonly tool: {
+    readonly name: string
+    readonly input: Json
+    readonly output: Json
+    readonly failure: Json
+  }
+  readonly object: { readonly name: string; readonly value: Json }
+  readonly data: { readonly name: string; readonly value: Json }
+  readonly live: { readonly name: string; readonly value: Json }
+  readonly metadata: Json
+}
+
+type Plain = (typeof plainEvents)[number]["Type"]
+
+// Distributes over the tool union, so narrowing by `name` types `value` and `result`.
+type ToolEvents<T> = T extends ToolPayload
+  ?
+      | {
+          readonly type: "tool-partial"
+          readonly callId: string
+          readonly name: T["name"]
+          readonly value: T["output"]
+        }
+      | {
+          readonly type: "tool-result"
+          readonly callId: string
+          readonly name: T["name"]
+          readonly result: Outcome<T["output"], T["failure"]>
+        }
+  : never
+
+export type Interrupt<P extends Payloads = Untyped> = {
+  readonly callId: string
+  readonly reason: "approval"
+  readonly name: P["tool"]["name"]
+  readonly input: P["tool"]["input"]
+}
+
+type Typed<P extends Payloads> =
+  | { readonly type: "run-completed"; readonly metadata?: P["metadata"] | undefined }
+  | { readonly type: "run-interrupted"; readonly interrupts: ReadonlyArray<Interrupt<P>> }
+  | {
+      readonly type: "object-done"
+      readonly id: string
+      readonly name?: P["object"]["name"] | undefined
+      readonly value: P["object"]["value"]
+    }
+  | {
+      readonly type: "tool-call-ready"
+      readonly callId: string
+      readonly name: P["tool"]["name"]
+      readonly input: P["tool"]["input"]
+    }
+  | {
+      readonly type: "tool-approval-requested"
+      readonly callId: string
+      readonly name: P["tool"]["name"]
+      readonly input: P["tool"]["input"]
+    }
+  | ToolEvents<P["tool"]>
+  | {
+      readonly type: "data"
+      readonly name: P["data"]["name"]
+      readonly value: P["data"]["value"]
+      readonly id?: string | undefined
+    }
+  | { readonly type: "live"; readonly name: P["live"]["name"]; readonly value: P["live"]["value"] }
+
+/** One event; with a contract's `P`, its payloads are decoded. */
+export type RunEvent<P extends Payloads = Untyped> = Plain | Typed<P>
+
+export type Envelope<P extends Payloads = Untyped> = {
+  readonly streamId: StreamId
+  readonly seq: number
+  readonly runId?: RunId | undefined
+  readonly event: RunEvent<P>
+}
+
+export type Terminal<P extends Payloads = Untyped> = Extract<
+  RunEvent<P>,
+  { readonly type: "run-completed" | "run-interrupted" | "run-failed" | "run-stopped" }
+>
+
+const terminalTypes: ReadonlySet<string> = new Set([
+  "run-completed",
+  "run-interrupted",
+  "run-failed",
+  "run-stopped",
+])
+
+export const isTerminal = <P extends Payloads = Untyped>(
+  event: RunEvent<P>,
+): event is Terminal<P> => terminalTypes.has(event.type)