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

package/src/SseEncoding.test.ts

@@ -0,0 +1,46 @@
+import { describe, it } from "@effect/vitest"
+import { Effect, Option, Stream } from "effect"
+import { expect } from "vitest"
+import { type Envelope, RunId, StreamId } from "./RunEvent.js"
+import * as SseEncoding from "./SseEncoding.js"
+
+describe("SseEncoding", () => {
+  const envelopes: ReadonlyArray<Envelope> = [
+    {
+      streamId: StreamId.make("s"),
+      seq: 1,
+      runId: RunId.make("r1"),
+      event: { type: "text-delta", text: "two\nlines" },
+    },
+    {
+      streamId: StreamId.make("s"),
+      seq: 2,
+      event: {
+        type: "image",
+        image: { _tag: "bytes", bytes: new Uint8Array([1, 2]), mimeType: "image/png" },
+      },
+    },
+  ]
+
+  it.effect("frames id = seq, event = type, and round-trips non-JSON values", () =>
+    Effect.gen(function* () {
+      const bytes = yield* Stream.fromIterable(envelopes).pipe(
+        SseEncoding.encode,
+        Stream.runCollect,
+      )
+      const text = new TextDecoder().decode(Buffer.concat(bytes))
+      expect(text).toContain("id: 1\nevent: text-delta\n")
+      const decoded = yield* Stream.fromIterable(bytes).pipe(SseEncoding.decode, Stream.runCollect)
+      expect(decoded).toEqual(envelopes)
+    }),
+  )
+
+  it.each([
+    { label: "web Headers", headers: new Headers({ "last-event-id": "9" }), seq: Option.some(9) },
+    { label: "Effect record headers", headers: { "last-event-id": "7" }, seq: Option.some(7) },
+    { label: "no header", headers: new Headers(), seq: Option.none() },
+    { label: "a non-integer value", headers: { "last-event-id": "abc" }, seq: Option.none() },
+  ])("lastEventId reads $label", ({ headers, seq }) => {
+    expect(SseEncoding.lastEventId(headers)).toEqual(seq)
+  })
+})

package/src/SseEncoding.ts

@@ -0,0 +1,77 @@
+/**
+ * SSE framing for envelopes, on Effect's `effect/encoding/Sse`. A frame
+ * carries `id: <seq>` (so a browser's auto-reconnect sends `Last-Event-ID`),
+ * `event: <type>` and the envelope's JSON in `data`. `EnvelopeEvent` is that
+ * mapping as a Schema; `encode` / `decode` run it with Effect's SSE
+ * encoder and parser.
+ * For NDJSON use `effect/encoding/Ndjson` with `RunEvent.EnvelopeJson`.
+ */
+import { Effect, Option, Schema, SchemaTransformation, Stream } from "effect"
+import { Sse } from "effect/encoding"
+import { Envelope, EnvelopeJson } from "./RunEvent.js"
+
+/** An envelope as an SSE event: `id` = seq, `event` = type, `data` = the envelope as JSON. */
+export const EnvelopeEvent = Schema.Struct({
+  id: Schema.optional(Schema.String),
+  event: Schema.String,
+  data: Schema.fromJsonString(EnvelopeJson),
+}).pipe(
+  Schema.decodeTo(
+    Schema.toType(Envelope),
+    SchemaTransformation.transform({
+      decode: (event) => event.data,
+      encode: (envelope) => ({
+        id: String(envelope.seq),
+        event: envelope.event.type,
+        data: envelope,
+      }),
+    }),
+  ),
+)
+
+const encodeEvent = Schema.encodeEffect(EnvelopeEvent)
+
+/** Envelopes → an SSE response body. */
+export const encode = <E, R>(
+  self: Stream.Stream<Envelope, E, R>,
+): Stream.Stream<Uint8Array, E | Schema.SchemaError, R> =>
+  self.pipe(
+    Stream.mapEffect((envelope) =>
+      encodeEvent(envelope).pipe(
+        Effect.map((event) => Sse.encoder.write({ _tag: "Event", id: event.id, ...event })),
+      ),
+    ),
+    Stream.encodeText,
+  )
+
+/** An SSE response body → envelopes. A `retry:` hint from the server fails with `Sse.Retry`. */
+export const decode = <E, R>(
+  self: Stream.Stream<Uint8Array, E, R>,
+): Stream.Stream<Envelope, E | Sse.Retry | Sse.SseError | Schema.SchemaError, R> =>
+  self.pipe(Stream.decodeText, Stream.pipeThroughChannelOrFail(Sse.decodeSchema(EnvelopeEvent)))
+
+/**
+ * Headers an SSE response needs. Behind nginx-style proxies, also send
+ * `x-accel-buffering: no` so frames are not buffered.
+ */
+export const responseHeaders: Readonly<Record<string, string>> = {
+  "content-type": "text/event-stream",
+  "cache-control": "no-cache",
+}
+
+const parseSeq = Schema.decodeUnknownOption(Schema.FiniteFromString.check(Schema.isInt()))
+
+/**
+ * The `seq` a reconnecting SSE client last received, from the standard
+ * `Last-Event-ID` header (a browser's EventSource sends it on every
+ * auto-reconnect). Accepts web `Headers` or Effect's record headers.
+ *
+ * Prefer it over any position the app carries in the URL: EventSource keeps
+ * reconnecting to its original URL, so a URL position goes stale.
+ */
+export const lastEventId = (
+  headers: Headers | { readonly [key: string]: string | undefined },
+): Option.Option<number> =>
+  Option.fromNullishOr(
+    headers instanceof Headers ? headers.get("last-event-id") : headers["last-event-id"],
+  ).pipe(Option.flatMap(parseSeq))

package/src/Thread.test.ts

@@ -0,0 +1,304 @@
+import * as ToolDecision from "@effect-uai/core/ToolDecision"
+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 Turn from "@effect-uai/core/Turn"
+import { describe, it } from "@effect/vitest"
+import { Effect, Option, pipe, Schema, Stream } from "effect"
+import { expect } from "vitest"
+import * as Input from "./Input.js"
+import * as Projection from "./Projection.js"
+import * as Run from "./Run.js"
+import { type Envelope, InputId, RunId, type RunEvent, StreamId } from "./RunEvent.js"
+import * as RunView from "./RunView.js"
+import * as SseEncoding from "./SseEncoding.js"
+import * as Thread from "./Thread.js"
+import * as UiContract from "./UiContract.js"
+
+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, temperatureC: Schema.Number }),
+  run: ({ city }) => Effect.succeed({ city, temperatureC: 19.4 }),
+})
+const toolkit = Toolkit.make(getWeather)
+const usage = { input_tokens: 5, output_tokens: 5 }
+
+type State = { readonly history: ReadonlyArray<Items.HistoryItem> }
+
+// Server side: a real tool loop, projected, bracketed, sequenced, framed as SSE bytes.
+const serve = (inputId: InputId) => {
+  const { service } = MockProvider.make([
+    {
+      stop_reason: "tool_calls",
+      usage,
+      items: [
+        {
+          type: "function_call",
+          call_id: "c1",
+          name: "get_weather",
+          arguments: `{"city":"Lisbon"}`,
+        },
+      ],
+    },
+    {
+      stop_reason: "stop",
+      usage,
+      items: [
+        { type: "message", role: "assistant", content: [{ type: "output_text", text: "19°C." }] },
+      ],
+    },
+  ])
+  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).pipe(Toolkit.next(toolkit, state, turn))
+          }),
+        ),
+      ),
+    ),
+    Projection.toRunEvents({ contract: UiContract.make({ tools: [getWeather] }) }),
+    Stream.catchCause((cause) => Stream.succeed(Run.failed(cause))),
+    Run.start({ runId: RunId.make("r1"), inputs: [inputId] }),
+    Run.complete,
+    Run.sequence(StreamId.make("st_1")),
+    SseEncoding.encode,
+  )
+}
+
+const receive = (bytes: Stream.Stream<Uint8Array, Schema.SchemaError>) =>
+  bytes.pipe(SseEncoding.decode, Stream.runCollect)
+
+describe("Thread over the wire", () => {
+  it.effect("folds a served tool run into a settled assistant message", () =>
+    Effect.gen(function* () {
+      const input = { ...Input.submit("Weather in Lisbon?"), id: InputId.make("in_1") }
+      const envelopes = yield* receive(serve(input.id))
+      const thread = envelopes.reduce(Thread.step, Thread.submitted(Thread.initial, input))
+
+      expect(thread.active).toBeNull()
+      expect(thread.messages.map((m) => m.role)).toEqual(["user", "assistant"])
+      const assistant = thread.messages[1]
+      expect(assistant?.role === "assistant" && assistant.value.status).toBe("completed")
+      expect(assistant?.role === "assistant" && assistant.value.usage).toEqual({
+        input_tokens: 10,
+        output_tokens: 10,
+      })
+      expect(assistant?.role === "assistant" && assistant.value.blocks).toMatchObject([
+        {
+          type: "tool",
+          id: "c1",
+          name: "get_weather",
+          status: "done",
+          input: { city: "Lisbon" },
+          outcome: { _tag: "Success", value: { city: "Lisbon", temperatureC: 19.4 } },
+        },
+        { type: "output_text", text: "19°C." },
+      ])
+    }),
+  )
+
+  it.effect("is unchanged when a reconnect replays frames it already applied", () =>
+    Effect.gen(function* () {
+      const input = { ...Input.submit("Weather in Lisbon?"), id: InputId.make("in_1") }
+      const envelopes = yield* receive(serve(input.id))
+      const start = Thread.submitted(Thread.initial, input)
+      const once = envelopes.reduce(Thread.step, start)
+      // Drop after frame 4, reconnect, receive everything again from the start.
+      const replayed = [...envelopes.slice(0, 4), ...envelopes].reduce(Thread.step, start)
+      expect(replayed).toEqual(once)
+    }),
+  )
+})
+
+describe("Thread across streams", () => {
+  // One stream per run: each run's seq starts at 1 again.
+  const run = (stream: string, text: string): ReadonlyArray<Envelope> =>
+    (
+      [
+        {
+          type: "run-started",
+          runId: RunId.make(stream),
+          inputs: [],
+          protocol: 2,
+        },
+        { type: "text-delta", text },
+        { type: "run-completed" },
+      ] satisfies ReadonlyArray<RunEvent>
+    ).map((event, i) => ({
+      streamId: StreamId.make(stream),
+      seq: i + 1,
+      runId: RunId.make(stream),
+      event,
+    }))
+
+  it("keeps input sent during a run pending until its own run starts", () => {
+    const s = StreamId.make("chat")
+    const frame = (seq: number, runId: string, event: RunEvent): Envelope => ({
+      streamId: s,
+      seq,
+      runId: RunId.make(runId),
+      event,
+    })
+    const first = { ...Input.submit("first"), id: InputId.make("in_1") }
+    const second = { ...Input.submit("second"), id: InputId.make("in_2") }
+    const started = (runId: string, input: InputId): RunEvent => ({
+      type: "run-started",
+      runId: RunId.make(runId),
+      inputs: [input],
+      protocol: 2,
+    })
+
+    const streaming = [
+      frame(1, "r1", started("r1", first.id)),
+      frame(2, "r1", { type: "text-delta", text: "a" }),
+    ].reduce(Thread.step, Thread.submitted(Thread.initial, first))
+    const queued = Thread.submitted(streaming, second)
+    expect(queued.pending.map((m) => m.id)).toEqual([second.id])
+
+    const done = [
+      frame(3, "r1", { type: "run-completed" }),
+      frame(4, "r2", started("r2", second.id)),
+      frame(5, "r2", { type: "text-delta", text: "b" }),
+      frame(6, "r2", { type: "run-completed" }),
+    ].reduce(Thread.step, queued)
+    expect(done.pending).toEqual([])
+    expect(
+      done.messages.map((m) => (m.role === "user" ? Input.text(m.value) : RunView.text(m.value))),
+    ).toEqual(["first", "a", "second", "b"])
+  })
+
+  it("a custom fold rebuilds the conversation from the stream alone (reload): echoes become entries", () => {
+    // Entries as plain text instead of the preset's messages / RunView.
+    const text = Thread.make({
+      toUser: (input: Input.Submit) => Option.some(Input.text(input)),
+      settle: RunView.text,
+      decodeInput: Schema.decodeUnknownOption(Input.SubmitJson),
+    })
+    const s = StreamId.make("chat")
+    const r = RunId.make("r1")
+    const echo = Schema.encodeSync(Input.SubmitJson)({
+      ...Input.submit("hi"),
+      id: InputId.make("in_1"),
+    })
+    const frames: ReadonlyArray<Envelope> = [
+      { streamId: s, seq: 1, event: { type: "input-accepted", input: echo } },
+      {
+        streamId: s,
+        seq: 2,
+        runId: r,
+        event: {
+          type: "run-started",
+          runId: r,
+          inputs: [InputId.make("in_1")],
+          protocol: 2,
+        },
+      },
+      { streamId: s, seq: 3, runId: r, event: { type: "text-delta", text: "Hello" } },
+      { streamId: s, seq: 4, runId: r, event: { type: "run-completed" } },
+    ]
+
+    const afterEcho = text.step(text.initial, frames[0]!)
+    expect(afterEcho.pending.map((m) => m.value)).toEqual(["hi"])
+
+    const done = frames.reduce(text.step, text.initial)
+    expect(done.pending).toEqual([])
+    expect(done.messages.map((m) => [m.role, m.value])).toEqual([
+      ["user", "hi"],
+      ["assistant", "Hello"],
+    ])
+  })
+
+  it("does not mistake a later run on a new stream for a replay", () => {
+    const thread = [...run("a", "first"), ...run("b", "second")].reduce(Thread.step, Thread.initial)
+    expect(
+      thread.messages.map((m) => (m.role === "assistant" ? RunView.text(m.value) : "")),
+    ).toEqual(["first", "second"])
+  })
+})
+
+describe("Thread approvals", () => {
+  const s = StreamId.make("chat")
+  const frame = (seq: number, runId: string, event: RunEvent): Envelope => ({
+    streamId: s,
+    seq,
+    runId: RunId.make(runId),
+    event,
+  })
+  const ask = { ...Input.submit("Book a table for 8"), id: InputId.make("in_1") }
+  const call = { callId: "call_1", name: "book_table", input: { time: "20:00" } }
+
+  // The first run asks for approval and ends interrupted.
+  const interrupted = [
+    frame(1, "r1", { type: "run-started", runId: RunId.make("r1"), inputs: [ask.id], protocol: 2 }),
+    frame(2, "r1", { type: "tool-call-ready", ...call }),
+    frame(3, "r1", { type: "run-interrupted", interrupts: [{ ...call, reason: "approval" }] }),
+  ].reduce(Thread.step, Thread.submitted(Thread.initial, ask))
+
+  // The answer runs the call (or not) in the next run.
+  const answer = (approved: boolean, result: RunEvent) => {
+    const decision = approved ? ToolDecision.Default.Approve() : ToolDecision.Default.Deny()
+    const resolve = {
+      ...Input.resolve([{ callId: "call_1", decision }]),
+      id: InputId.make("in_2"),
+    }
+    return [
+      frame(4, "r2", {
+        type: "run-started",
+        runId: RunId.make("r2"),
+        inputs: [resolve.id],
+        protocol: 2,
+      }),
+      frame(5, "r2", result),
+      frame(6, "r2", { type: "text-delta", text: approved ? "Booked." : "Not booked." }),
+      frame(7, "r2", { type: "run-completed" }),
+    ].reduce(Thread.step, Thread.submitted(interrupted, resolve))
+  }
+
+  const blocksOf = (thread: Thread.Thread, index: number) => {
+    const m = thread.messages[index]
+    return m?.role === "assistant" ? m.value.blocks : []
+  }
+
+  it("an approved call's result updates the card it was asked from", () => {
+    const thread = answer(true, {
+      type: "tool-result",
+      callId: "call_1",
+      name: "book_table",
+      result: { _tag: "Success", value: { booked: true } },
+    })
+    expect(blocksOf(thread, 1)).toMatchObject([
+      {
+        type: "tool",
+        id: "call_1",
+        status: "done",
+        outcome: { _tag: "Success", value: { booked: true } },
+      },
+    ])
+    expect(blocksOf(thread, 2)).toEqual([{ type: "output_text", id: "b0", text: "Booked." }])
+  })
+
+  it("a denied call fails on the same card, with the server's error", () => {
+    const error = { _tag: "Denied", message: "not tonight" }
+    const thread = answer(false, {
+      type: "tool-result",
+      callId: "call_1",
+      name: "book_table",
+      result: { _tag: "Failure", error },
+    })
+    expect(blocksOf(thread, 1)).toMatchObject([
+      { type: "tool", id: "call_1", status: "failed", outcome: { _tag: "Failure", error } },
+    ])
+    expect(blocksOf(thread, 2)).toEqual([{ type: "output_text", id: "b0", text: "Not booked." }])
+  })
+})