@effect-uai/core 0.18.0 → 0.19.0-dev-20261109183959

package/src/loop/Loop.ts

@@ -125,26 +125,27 @@ 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> =
+// The Effect and the stream it returns infer their errors separately.
+type TurnContinuation<S, A, E2, R2, E3, R3> =
   | Stream.Stream<Step<A, S>, E2, R2>
-  | Effect.Effect<Stream.Stream<Step<A, S>, E2, R2>, E2, R2>
+  | Effect.Effect<Stream.Stream<Step<A, S>, E2, R2>, E3, R3>
 
 export const onTurnComplete: {
-  <S, A, E2 = never, R2 = never>(
-    then: (turn: Turn) => TurnContinuation<S, A, E2, R2>,
+  <S, A, E2 = never, R2 = never, E3 = never, R3 = never>(
+    then: (turn: Turn) => TurnContinuation<S, A, E2, R2, E3, R3>,
   ): <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>(
+  ) => Stream.Stream<Step<TurnEvent | A, S>, E | E2 | E3 | IncompleteTurn, R | R2 | R3>
+  <S, A, E, R, E2 = never, R2 = never, E3 = never, R3 = never>(
     deltas: Stream.Stream<TurnEvent, E, R>,
-    then: (turn: Turn) => TurnContinuation<S, A, E2, R2>,
-  ): Stream.Stream<Step<TurnEvent | A, S>, E | E2 | IncompleteTurn, R | R2>
+    then: (turn: Turn) => TurnContinuation<S, A, E2, R2, E3, R3>,
+  ): Stream.Stream<Step<TurnEvent | A, S>, E | E2 | E3 | IncompleteTurn, R | R2 | R3>
 } = Function.dual(
   2,
-  <S, A, E, R, E2, R2>(
+  <S, A, E, R, E2, R2, E3, R3>(
     deltas: Stream.Stream<TurnEvent, E, R>,
-    then: (turn: Turn) => TurnContinuation<S, A, E2, R2>,
-  ): Stream.Stream<Step<TurnEvent | A, S>, E | E2 | IncompleteTurn, R | R2> =>
+    then: (turn: Turn) => TurnContinuation<S, A, E2, R2, E3, R3>,
+  ): Stream.Stream<Step<TurnEvent | A, S>, E | E2 | E3 | IncompleteTurn, R | R2 | R3> =>
     Stream.unwrap(
       Effect.gen(function* () {
         const turnRef = yield* Ref.make<Option.Option<Turn>>(Option.none())
@@ -217,6 +218,11 @@ type LoopBody<S, A, E, R> = (
   state: S,
 ) => Stream.Stream<Step<A, S>, E, R> | Effect.Effect<Stream.Stream<Step<A, S>, E, R>, E, R>
 
+// What callers pass: the Effect and its stream infer errors and requirements separately.
+type LoopBodyIn<S, A, E, R, E2, R2> = (
+  state: S,
+) => Stream.Stream<Step<A, S>, E, R> | Effect.Effect<Stream.Stream<Step<A, S>, E, R>, E2, R2>
+
 /**
  * Drive a state-threaded loop body. Each iteration runs `body(state)` to get
  * a `Stream<Step<A, S>>`; values flow downstream, `next(s)` continues with
@@ -227,8 +233,13 @@ type LoopBody<S, A, E, R> = (
  * (or `pipe(initial, loop(body))`) both work.
  */
 export const loop: {
-  <S, A, E, R>(body: LoopBody<S, A, E, R>): (initial: S) => Stream.Stream<A, E, R>
-  <S, A, E, R>(initial: S, body: LoopBody<S, A, E, R>): Stream.Stream<A, E, R>
+  <S, A, E, R, E2 = never, R2 = never>(
+    body: LoopBodyIn<S, A, E, R, E2, R2>,
+  ): (initial: S) => Stream.Stream<A, E | E2, R | R2>
+  <S, A, E, R, E2 = never, R2 = never>(
+    initial: S,
+    body: LoopBodyIn<S, A, E, R, E2, R2>,
+  ): Stream.Stream<A, E | E2, R | R2>
 } = Function.dual(2, <S, A, E, R>(initial: S, body: LoopBody<S, A, E, R>): Stream.Stream<A, E, R> =>
   Stream.scoped(
     Stream.fromPull(

package/src/streaming/Multipart.test.ts

@@ -0,0 +1,26 @@
+import { describe, it } from "@effect/vitest"
+import { Effect } from "effect"
+import { HttpClientRequest } from "effect/http"
+import { expect } from "vitest"
+import { bodyMultipart } from "./Multipart.js"
+
+describe("bodyMultipart", () => {
+  it.effect("sends the boundary the encoded parts are delimited by", () =>
+    Effect.gen(function* () {
+      const form = new FormData()
+      form.set("file", new Blob([new Uint8Array([1, 2, 3])], { type: "audio/ogg" }), "audio.ogg")
+      form.set("model", "whisper-1")
+
+      const request = HttpClientRequest.post("https://example.test/upload").pipe(
+        yield* bodyMultipart(form),
+      )
+      const contentType = request.headers["content-type"] ?? ""
+      const boundary = /boundary=(.+)$/.exec(contentType)?.[1]
+
+      expect(boundary).toBeDefined()
+      const body =
+        request.body._tag === "Uint8Array" ? new TextDecoder().decode(request.body.body) : ""
+      expect(body.startsWith(`--${boundary}\r\n`)).toBe(true)
+    }),
+  )
+})

package/src/streaming/Multipart.ts

@@ -21,9 +21,10 @@ export const bodyMultipart = (
 > =>
   Effect.gen(function* () {
     const encoded = new Response(form)
+    // Read before the body: once it is consumed, Bun answers `null` for this
+    // header (Node keeps it), which would drop the boundary and leave the
+    // server unable to parse the parts.
+    const contentType = encoded.headers.get("content-type") ?? "multipart/form-data"
     const buffer = yield* Effect.tryPromise(() => encoded.arrayBuffer())
-    return HttpClientRequest.bodyUint8Array(
-      new Uint8Array(buffer),
-      encoded.headers.get("content-type") ?? "multipart/form-data",
-    )
+    return HttpClientRequest.bodyUint8Array(new Uint8Array(buffer), contentType)
   })

package/src/tool/Content.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, expectTypeOf, it } from "@effect/vitest"
+import { Effect, Schema } from "effect"
+import { imageBytes } from "../domain/Image.js"
+import * as Content from "./Content.js"
+
+const bytes = new Uint8Array([137, 80, 78, 71])
+const encode = Schema.encodeUnknownEffect(Content.Value)
+const decode = Schema.decodeUnknownEffect(Content.Value)
+
+describe("Content.Value", () => {
+  it("encodes to JSON", () => {
+    expectTypeOf<typeof Content.Value.Encoded>().toExtend<Schema.Json>()
+  })
+
+  it.effect("round-trips image bytes through JSON as base64", () =>
+    Effect.gen(function* () {
+      const encoded = yield* encode(Content.image(imageBytes(bytes, "image/png")))
+      expect(encoded).toEqual({
+        _tag: "Image",
+        source: { _tag: "bytes", bytes: "iVBORw==", mimeType: "image/png" },
+      })
+
+      const decoded = yield* decode(JSON.parse(JSON.stringify(encoded)))
+      expect(decoded).toBeInstanceOf(Content.Image)
+      expect(decoded).toEqual(Content.image(imageBytes(bytes, "image/png")))
+    }),
+  )
+
+  it.effect("keeps plain objects plain and media as classes in a mixed array", () =>
+    Effect.gen(function* () {
+      const value = [
+        { title: "Home" },
+        Content.file({ _tag: "url", url: "https://x/a.pdf" }, "a.pdf"),
+      ]
+      const decoded = yield* decode(yield* encode(value))
+      expect(decoded).toEqual(value)
+      expect(Array.isArray(decoded) && decoded.map(Content.isMedia)).toEqual([false, true])
+    }),
+  )
+})

package/src/tool/Content.ts

@@ -0,0 +1,38 @@
+/**
+ * What a tool's `run` may return without an `outputSchema`. Plain values stay
+ * plain (a string is text, anything else JSON); only media is marked, by class,
+ * so it is told apart from JSON by `instanceof`, never by shape.
+ */
+import { Schema } from "effect"
+import { type FileSource, FileSourceJson } from "../domain/File.js"
+import { type ImageSource, ImageSourceJson } from "../domain/Image.js"
+
+export class Image extends Schema.TaggedClass<Image>()("Image", { source: ImageSourceJson }) {}
+
+export class File extends Schema.TaggedClass<File>()("File", {
+  source: FileSourceJson,
+  filename: Schema.optionalKey(Schema.String),
+}) {}
+
+export const Media = Schema.Union([Image, File])
+export type Media = typeof Media.Type
+
+export const image = (source: ImageSource): Image => new Image({ source })
+
+export const file = (source: FileSource, filename?: string): File =>
+  new File(filename === undefined ? { source } : { source, filename })
+
+export const isMedia = (u: unknown): u is Media => u instanceof Image || u instanceof File
+
+/**
+ * Text, JSON, one medium, or a top-level array mixing JSON and media. Encodes to
+ * JSON (bytes as base64), so it also serves as the UI codec for tools without
+ * an `outputSchema`.
+ */
+export const Value = Schema.Union([
+  Schema.String,
+  Media,
+  Schema.Array(Schema.Union([Media, Schema.Json])),
+  Schema.Json,
+])
+export type Value = typeof Value.Type

package/src/tool/HistoryCheck.ts

@@ -1,23 +1,20 @@
 /**
- * History-consistency primitives. Useful even WITHOUT HITL.
- *
- * Every provider rejects a new request if any prior `function_call` lacks
- * a matching `function_call_output`. Multi-turn flows that can be
- * interrupted, restarted, or branched (HITL, mid-stream abort, persisted
- * checkpoints, stateless HTTP servers) need to detect orphans and
- * synthesize closing outputs before submitting.
- *
- * Recipe author calls these at known transition points (right before the
- * next provider request). Not invoked from inside the loop.
+ * History consistency. Providers reject a request when a `function_call` has no
+ * matching `function_call_output`; flows that can be interrupted, restarted or
+ * branched (approvals, aborts, persisted checkpoints) close orphans with these
+ * before the next model call.
  */
-import { type ToolCall, type HistoryItem, isToolCall, isToolCallOutput } from "../domain/Items.js"
-import { type ToolResult, cancelled } from "./ToolResult.js"
+import { Effect, type Schema } from "effect"
+import {
+  type HistoryItem,
+  isToolCall,
+  isToolCallOutput,
+  type ToolCall,
+  type ToolCallOutput,
+} from "../domain/Items.js"
+import * as ToolOutput from "./ToolOutput.js"
 
-/**
- * Return every `function_call` in `history` that does not have a matching
- * `function_call_output` later in `history` (correlated by `call_id`).
- * Empty result = history is provider-submittable from this invariant.
- */
+/** Every `function_call` in `history` without a `function_call_output` (by `call_id`). */
 export const findUnansweredCalls = (
   history: ReadonlyArray<HistoryItem>,
 ): ReadonlyArray<ToolCall> => {
@@ -25,19 +22,17 @@ export const findUnansweredCalls = (
   return history.filter(isToolCall).filter((c) => !answered.has(c.call_id))
 }
 
-/** Cheap predicate: is this history submittable to a provider? */
 export const isReconciled = (history: ReadonlyArray<HistoryItem>): boolean =>
   findUnansweredCalls(history).length === 0
 
 /**
- * Synthesize cancellation results for every unanswered call. Caller maps
- * via `toToolCallOutput` and appends to history before submitting.
- *
- * Use when: a new user message arrives mid-approval; an approval timer
- * fires; a persisted checkpoint contains orphans (crash recovery); a
- * stateless HTTP server reconstructed history from a stale checkpoint.
+ * A `Cancelled` output for every unanswered call, to append before the next
+ * model call. For your own error, use `findUnansweredCalls` + `ToolOutput.failure`.
  */
 export const cancelAllPending = (
   history: ReadonlyArray<HistoryItem>,
-  reason?: string,
-): ReadonlyArray<ToolResult> => findUnansweredCalls(history).map((call) => cancelled(call, reason))
+  reason = "The call was cancelled before it ran.",
+): Effect.Effect<ReadonlyArray<ToolCallOutput>, Schema.SchemaError> =>
+  Effect.forEach(findUnansweredCalls(history), (call) =>
+    ToolOutput.failure(call, ToolOutput.Cancelled, new ToolOutput.Cancelled({ message: reason })),
+  )