@effect-uai/core 0.9.0 → 0.11.0

package/src/streaming/SSE.ts

@@ -1,8 +1,9 @@
 import { Stream } from "effect"
+import { Sse } from "effect/unstable/encoding"
 
 /**
  * One Server-Sent Event. Fields per the WHATWG spec:
- * - `event`: optional event name (default "message" on the wire)
+ * - `event`: optional event name (absent for the default "message")
  * - `data`: payload, with multiple `data:` lines joined by `\n`
  * - `id`: optional last-event id
  */
@@ -12,98 +13,44 @@ export type Event = {
   readonly id?: string
 }
 
-// ---------------------------------------------------------------------------
-// Generic stream helpers (kept module-local for now; promote to a shared
-// Stream module once a third caller appears).
-// ---------------------------------------------------------------------------
+const toEvent = (wire: Sse.Event): Event => ({
+  data: wire.data,
+  ...(wire.event !== "message" && { event: wire.event }),
+  ...(wire.id !== undefined && { id: wire.id }),
+})
 
-/** Decode `Uint8Array` chunks as UTF-8, handling multi-byte boundaries. */
-const decodeText = <E, R>(self: Stream.Stream<Uint8Array, E, R>): Stream.Stream<string, E, R> =>
-  self.pipe(
-    Stream.mapAccum(
-      (): TextDecoder => new TextDecoder("utf-8"),
-      (decoder, chunk: Uint8Array) => [decoder, [decoder.decode(chunk, { stream: true })]] as const,
-      {
-        onHalt: (decoder: TextDecoder) => {
-          const tail = decoder.decode()
-          return tail.length > 0 ? [tail] : []
-        },
-      },
-    ),
-  )
-
-/** Split a text stream on a separator, buffering across chunk boundaries. */
-const splitOn =
-  (separator: string) =>
-  <E, R>(self: Stream.Stream<string, E, R>): Stream.Stream<string, E, R> =>
-    self.pipe(
-      Stream.mapAccum(
-        (): string => "",
-        (buffer, chunk: string) => {
-          const parts = (buffer + chunk).split(separator)
-          const tail = parts[parts.length - 1] ?? ""
-          return [tail, parts.slice(0, -1)] as const
-        },
-        { onHalt: (tail: string) => (tail.length > 0 ? [tail] : []) },
-      ),
-    )
-
-// ---------------------------------------------------------------------------
-// Parser
-// ---------------------------------------------------------------------------
-
-const parseField = (line: string): readonly [string, string] => {
-  const colon = line.indexOf(":")
-  if (colon < 0) return [line, ""]
-  const value = line.slice(colon + 1)
-  return [line.slice(0, colon), value.startsWith(" ") ? value.slice(1) : value]
+type ParserState = {
+  readonly parser: Sse.Parser
+  readonly out: Array<Event>
 }
 
-const parseBlock = (block: string): Event | null => {
-  const lines = block.split("\n").filter((l) => l.length > 0 && !l.startsWith(":"))
-  if (lines.length === 0) return null
-
-  const fields = lines.map(parseField)
-  const dataLines = fields.filter(([f]) => f === "data").map(([, v]) => v)
-  const event = fields.find(([f]) => f === "event")?.[1]
-  const id = fields.find(([f]) => f === "id")?.[1]
-
-  const out: { event?: string; data: string; id?: string } = {
-    data: dataLines.join("\n"),
-  }
-  if (event !== undefined) out.event = event
-  if (id !== undefined) out.id = id
-  return out as Event
+const makeParserState = (): ParserState => {
+  const out: Array<Event> = []
+  const parser = Sse.makeParser((event) => {
+    // `retry:` reconnection hints have no representation in `Event`
+    if (event._tag === "Event") out.push(toEvent(event))
+  })
+  return { parser, out }
 }
 
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-
 /**
  * Decode a `Stream<Uint8Array>` (e.g. an HTTP response body) into a
- * `Stream<SSE.Event>`. Handles partial UTF-8 sequences, CRLF/LF line
- * endings, and events split across chunk boundaries.
+ * `Stream<SSE.Event>`, using the spec parser from `effect/unstable/encoding`.
+ * An event is dispatched only once its terminating blank line arrives, so a
+ * partial event at stream end (clean or failed) is discarded per the spec
+ * rather than surfaced as a truncated frame.
  */
 export const fromBytes = <E, R>(
   self: Stream.Stream<Uint8Array, E, R>,
 ): Stream.Stream<Event, E, R> =>
   self.pipe(
-    decodeText,
-    Stream.map((s) => s.replace(/\r/g, "")), // SSE allows CRLF; normalize to LF
-    splitOn("\n\n"),
-    Stream.map(parseBlock),
-    Stream.filter((ev): ev is Event => ev !== null),
+    Stream.decodeText,
+    Stream.mapAccum(makeParserState, (state, text: string) => {
+      state.parser.feed(text)
+      return [state, state.out.splice(0)] as const
+    }),
   )
 
-const eventToString = (ev: Event): string => {
-  const parts: string[] = []
-  if (ev.event !== undefined) parts.push(`event: ${ev.event}`)
-  if (ev.id !== undefined) parts.push(`id: ${ev.id}`)
-  for (const line of ev.data.split("\n")) parts.push(`data: ${line}`)
-  return parts.join("\n") + "\n\n"
-}
-
 const encoder = new TextEncoder()
 
 /**
@@ -111,4 +58,13 @@ const encoder = new TextEncoder()
  * HTTP response with `Content-Type: text/event-stream`.
  */
 export const toBytes = <E, R>(self: Stream.Stream<Event, E, R>): Stream.Stream<Uint8Array, E, R> =>
-  Stream.map(self, (ev) => encoder.encode(eventToString(ev)))
+  Stream.map(self, (ev) =>
+    encoder.encode(
+      Sse.encoder.write({
+        _tag: "Event",
+        event: ev.event ?? "message",
+        id: ev.id,
+        data: ev.data,
+      }),
+    ),
+  )

package/src/tool/Approval.test.ts

@@ -15,7 +15,13 @@ import { describe, expect, it } from "vitest"
 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 {
+  type ApprovalMapEntry,
+  type ApprovalDecision,
+  type Verdict,
+  fromMap,
+  fromQueue,
+} from "./Approval.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"
@@ -249,6 +255,50 @@ describe("fromQueue + run", () => {
       reason: "too risky",
     })
   })
+
+  it("router retires per round, so sequential rounds over one queue both resolve", async () => {
+    // A verdict-per-round over one shared queue and scope. The old
+    // never-terminating router would still be alive for round 1 and steal
+    // round 2's verdict (not in its map), hanging round 2.
+    const decisions = await Effect.runPromise(
+      Effect.scoped(
+        Effect.gen(function* () {
+          const verdicts = yield* Queue.unbounded<Verdict>()
+          const round = (id: string) => [fc(id, "delete_database", { name: "prod" })]
+
+          const r1 = yield* fromQueue(isSensitive, verdicts)(round("c1"))
+          yield* Queue.offer(verdicts, { call_id: "c1", decision: "approve" })
+          const d1 = Array.from(yield* Stream.runCollect(r1.decisions))
+
+          const r2 = yield* fromQueue(isSensitive, verdicts)(round("c2"))
+          yield* Queue.offer(verdicts, { call_id: "c2", decision: "deny", reason: "no" })
+          const d2 = Array.from(yield* Stream.runCollect(r2.decisions))
+
+          return { d1, d2 }
+        }),
+      ),
+    )
+    expect(decisions.d1[0]).toMatchObject({ _tag: "Approved" })
+    expect(decisions.d2[0]).toMatchObject({ _tag: "Rejected", result: { kind: "denied" } })
+  })
+
+  it("timeout resolves an unanswered gated call as cancelled", async () => {
+    const decisions = await Effect.runPromise(
+      Effect.scoped(
+        Effect.gen(function* () {
+          const verdicts = yield* Queue.unbounded<Verdict>()
+          const { decisions } = yield* fromQueue(isSensitive, verdicts, { timeout: "10 millis" })([
+            fc("c1", "delete_database", { name: "prod" }),
+          ])
+          return Array.from(yield* Stream.runCollect(decisions))
+        }),
+      ),
+    )
+    expect(decisions[0]).toMatchObject({
+      _tag: "Rejected",
+      result: { _tag: "Failure", kind: "cancelled" },
+    })
+  })
 })
 
 // ---------------------------------------------------------------------------
@@ -313,7 +363,7 @@ describe("toToolCallOutput", () => {
     expect(JSON.parse(out.output)).toEqual({ count: 3 })
   })
 
-  it("round-trips a Failure result with reason", () => {
+  it("renders a Failure with reason as a nested error object", () => {
     const r: ToolResult = {
       _tag: "Failure",
       call_id: "c2",
@@ -322,10 +372,10 @@ describe("toToolCallOutput", () => {
       reason: "spam concern",
     }
     const out = toToolCallOutput(r)
-    expect(JSON.parse(out.output)).toEqual({ kind: "denied", reason: "spam concern" })
+    expect(JSON.parse(out.output)).toEqual({ error: { kind: "denied", message: "spam concern" } })
   })
 
-  it("round-trips a Failure result without reason (omits the field)", () => {
+  it("renders a Failure without reason (omits message)", () => {
     const r: ToolResult = {
       _tag: "Failure",
       call_id: "c3",
@@ -333,7 +383,7 @@ describe("toToolCallOutput", () => {
       kind: "cancelled",
     }
     const out = toToolCallOutput(r)
-    expect(JSON.parse(out.output)).toEqual({ kind: "cancelled" })
+    expect(JSON.parse(out.output)).toEqual({ error: { kind: "cancelled" } })
   })
 })
 

package/src/tool/Approval.ts

@@ -5,7 +5,7 @@
  * results must be returned to the model. Tool execution stays explicit at
  * the recipe boundary via `Toolkit.run`.
  */
-import { Data, Deferred, Effect, Queue, Scope, Stream } from "effect"
+import { Data, Deferred, type Duration, Effect, Queue, Ref, Scope, Stream } from "effect"
 import type { ToolCall } from "../domain/Items.js"
 import { type ToolResult, cancelled, denied } from "./ToolResult.js"
 import { ToolEvent } from "./ToolEvent.js"
@@ -53,13 +53,30 @@ export type Verdict = {
   readonly reason?: string
 }
 
+export type FromQueueOptions = {
+  /**
+   * Resolve any still-pending gated call as `cancelled` once this elapses,
+   * so a lost or never-sent verdict cannot hang the decisions stream
+   * forever. Omit to wait indefinitely.
+   */
+  readonly timeout?: Duration.Input
+}
+
 /**
  * Queue-backed approval planner. Safe calls are returned immediately in
  * `approved`; gated calls emit `ApprovalRequested` events and later produce
  * one `ApprovalDecision` when their matching verdict arrives.
+ *
+ * The verdict queue is a single-consumer transport: run one approval round
+ * at a time (the router retires once every gated call of the round is
+ * resolved). For overlapping rounds, use one queue per round.
  */
 export const fromQueue =
-  (predicate: (call: ToolCall) => boolean, verdicts: Queue.Dequeue<Verdict>) =>
+  (
+    predicate: (call: ToolCall) => boolean,
+    verdicts: Queue.Dequeue<Verdict>,
+    options?: FromQueueOptions,
+  ) =>
   (
     calls: ReadonlyArray<ToolCall>,
   ): Effect.Effect<
@@ -76,37 +93,65 @@ export const fromQueue =
       const approved = calls.filter((call) => !predicate(call))
 
       const entries = yield* Effect.forEach(gated, (call) =>
-        Deferred.make<Verdict>().pipe(Effect.map((d) => [call.call_id, d] as const)),
+        Deferred.make<ApprovalDecision>().pipe(Effect.map((d) => [call.call_id, d] as const)),
       )
-      const deferreds: ReadonlyMap<string, Deferred.Deferred<Verdict>> = new Map(entries)
-
-      // Router is forked into the surrounding Scope so it lives as long
-      // as the consumer is pulling events. Recipes typically supply the
-      // scope by wrapping the events construction in `Stream.unwrap`.
-      yield* Effect.forkScoped(
-        Effect.forever(
-          Effect.gen(function* () {
-            const v = yield* Queue.take(verdicts)
-            const d = deferreds.get(v.call_id)
-            if (d !== undefined) yield* Deferred.succeed(d, v)
-          }),
+      const deferreds: ReadonlyMap<string, Deferred.Deferred<ApprovalDecision>> = new Map(entries)
+      const callById: ReadonlyMap<string, ToolCall> = new Map(gated.map((c) => [c.call_id, c]))
+      const outstanding = yield* Ref.make(gated.length)
+
+      // Complete a deferred once; decrement only on the winning transition so
+      // a late verdict for an already-resolved call is a no-op.
+      const resolve = (call: ToolCall, decision: ApprovalDecision) =>
+        Deferred.succeed(deferreds.get(call.call_id)!, decision).pipe(
+          Effect.flatMap((won) => (won ? Ref.update(outstanding, (n) => n - 1) : Effect.void)),
+        )
+
+      // Router retires once every gated call is resolved (by verdict or
+      // timeout), so sequential rounds over one queue do not accumulate
+      // racing routers. Recursive + suspended: stack-safe, no imperative loop.
+      const route: Effect.Effect<void> = Effect.suspend(() =>
+        Ref.get(outstanding).pipe(
+          Effect.flatMap((n) =>
+            n <= 0
+              ? Effect.void
+              : Queue.take(verdicts).pipe(
+                  Effect.flatMap((v) => {
+                    const call = callById.get(v.call_id)
+                    return (
+                      call === undefined
+                        ? Effect.void
+                        : resolve(
+                            call,
+                            v.decision === "approve"
+                              ? approve(call)
+                              : reject(denied(call, v.reason)),
+                          )
+                    ).pipe(Effect.andThen(route))
+                  }),
+                ),
+          ),
         ),
       )
 
-      const decisions = Stream.fromIterable(gated).pipe(
-        Stream.flatMap(
-          (call) => {
-            const d = deferreds.get(call.call_id)!
-            return Stream.fromEffect(
-              Deferred.await(d).pipe(
-                Effect.map((v) =>
-                  v.decision === "approve" ? approve(call) : reject(denied(call, v.reason)),
+      if (gated.length > 0) {
+        yield* Effect.forkScoped(route)
+        if (options?.timeout !== undefined) {
+          yield* Effect.forkScoped(
+            Effect.sleep(options.timeout).pipe(
+              Effect.andThen(
+                Effect.forEach(gated, (call) =>
+                  resolve(call, reject(cancelled(call, "approval timed out"))),
                 ),
               ),
-            )
-          },
-          { concurrency: "unbounded" },
-        ),
+            ),
+          )
+        }
+      }
+
+      const decisions = Stream.fromIterable(gated).pipe(
+        Stream.flatMap((call) => Stream.fromEffect(Deferred.await(deferreds.get(call.call_id)!)), {
+          concurrency: "unbounded",
+        }),
       )
 
       const approvalRequests = Stream.fromIterable<ToolEvent>(gated.map(approvalRequested))

package/src/tool/Tool.test.ts

@@ -1,5 +1,5 @@
 import type { StandardJSONSchemaV1, StandardSchemaV1 } from "@standard-schema/spec"
-import { Effect } from "effect"
+import { Context, Effect, Schema } from "effect"
 import { describe, expect, expectTypeOf, it } from "vitest"
 import type * as Items from "../domain/Items.js"
 import * as Tool from "./Tool.js"
@@ -156,3 +156,153 @@ describe("Tool.decodeArgs", () => {
     expect(exit._tag).toBe("Failure")
   })
 })
+
+describe("Effect Schema inputSchema", () => {
+  const Recipient = Schema.Struct({ to: Schema.String })
+
+  const sendEmail = Tool.make({
+    name: "send_email",
+    description: "Send an email to a single recipient.",
+    inputSchema: Recipient,
+    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("runs with the input inferred from the schema's Type", async () => {
+    const result = await Effect.runPromise(sendEmail.run({ to: "x@y.z" }, () => Effect.void))
+    expect(result).toBe("queued: x@y.z")
+  })
+
+  it("type: Input is the schema's Type", () => {
+    type InputOf<T> = T extends Tool.Tool<string, infer I, any, any, any> ? I : never
+    expectTypeOf<InputOf<typeof sendEmail>>().toEqualTypeOf<{ readonly to: string }>()
+  })
+
+  it("type: E and R are inferred from run through the Effect Schema overload", () => {
+    class Mailer extends Context.Service<
+      Mailer,
+      { readonly send: (to: string) => Effect.Effect<string> }
+    >()("test/Mailer") {}
+
+    const tool = Tool.make({
+      name: "send_email",
+      description: "send",
+      inputSchema: Recipient,
+      run: ({ to }) =>
+        Effect.gen(function* () {
+          const mailer = yield* Mailer
+          if (to === "") return yield* Effect.fail("empty" as const)
+          return yield* mailer.send(to)
+        }),
+    })
+
+    expectTypeOf<Tool.ToolE<typeof tool>>().toEqualTypeOf<"empty">()
+    expectTypeOf<Tool.ToolR<typeof tool>>().toEqualTypeOf<Mailer>()
+  })
+
+  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" })
+    expectTypeOf(input).toEqualTypeOf<{ readonly to: string }>()
+  })
+
+  it("fails with ToolValidationError 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")
+  })
+
+  it("renders a JSON Schema descriptor from the wrapped schema", () => {
+    const [descriptor] = Tool.toDescriptors([sendEmail])
+    expect(descriptor?.name).toBe("send_email")
+    expect(descriptor?.inputSchema).toMatchObject({
+      type: "object",
+      properties: { to: { type: "string" } },
+      required: ["to"],
+    })
+  })
+
+  it("accepts an already-wrapped fromEffectSchema value unchanged", async () => {
+    const wrapped = Tool.make({
+      name: "send_email",
+      description: "Send an email to a single recipient.",
+      inputSchema: Tool.fromEffectSchema(Recipient),
+      run: ({ to }) => Effect.succeed(`queued: ${to}`),
+    })
+    expect(Tool.toDescriptors([wrapped])).toEqual(Tool.toDescriptors([sendEmail]))
+    const input = await Effect.runPromise(Tool.decodeArgs(wrapped, callWith('{"to":"x@y.z"}')))
+    expectTypeOf(input).toEqualTypeOf<{ readonly to: string }>()
+  })
+
+  it("signal: decode-only kinds accept an Effect Schema directly", async () => {
+    const escalate = Tool.signal({
+      name: "escalate",
+      description: "Escalate to a human.",
+      inputSchema: Schema.Struct({ reason: Schema.String }),
+    })
+    const input = await Effect.runPromise(
+      Tool.decodeArgs(escalate, {
+        type: "function_call",
+        call_id: "call_2",
+        name: "escalate",
+        arguments: '{"reason":"stuck"}',
+      }),
+    )
+    expect(input).toEqual({ reason: "stuck" })
+    expectTypeOf(input).toEqualTypeOf<{ readonly reason: string }>()
+  })
+})
+
+describe("provider-hosted tools", () => {
+  const localTool = Tool.make({
+    name: "send_email",
+    description: "Send an email.",
+    inputSchema: Tool.fromEffectSchema(Schema.Struct({ to: Schema.String })),
+    run: ({ to }) => Effect.succeed(`sent: ${to}`),
+  })
+  const signalTool = Tool.signal({
+    name: "escalate",
+    description: "Escalate to a human.",
+    inputSchema: Schema.Struct({ reason: Schema.String }),
+  })
+  const hostedTool = Tool.provider({
+    name: "web_search",
+    description: "Search the web.",
+    inputSchema: Tool.noInput,
+    provider: "gemini",
+    config: { kind: "google_search" },
+  })
+  const toolkit = { send_email: localTool, escalate: signalTool, web_search: hostedTool }
+
+  it("descriptorsOf excludes provider-hosted tools", () => {
+    const descriptors = Tool.descriptorsOf(toolkit)
+    expect(descriptors.map((d) => d.name)).toEqual(["send_email", "escalate"])
+  })
+
+  it("toDescriptors drops a ProviderTool from a mixed array", () => {
+    expect(Tool.toDescriptors([localTool, hostedTool]).map((d) => d.name)).toEqual(["send_email"])
+  })
+
+  it("providerToolsOf returns only the provider-hosted tools", () => {
+    const provider = Tool.providerToolsOf(toolkit)
+    expect(provider).toHaveLength(1)
+    expect(provider[0]?.name).toBe("web_search")
+    expect(provider[0]?.provider).toBe("gemini")
+    expect(provider[0]?.config).toEqual({ kind: "google_search" })
+  })
+
+  it("providerToolsOf on an absent toolkit is empty", () => {
+    expect(Tool.providerToolsOf(undefined)).toEqual([])
+  })
+
+  it("isProviderTool narrows the tool kind", () => {
+    expect(Tool.isProviderTool(hostedTool)).toBe(true)
+    expect(Tool.isProviderTool(localTool)).toBe(false)
+    expect(Tool.isProviderTool(signalTool)).toBe(false)
+  })
+})