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

package/src/embedding-model/EmbeddingModel.test.ts

@@ -83,12 +83,12 @@ describe("embed / embedMany free exports preserve E in their return type", () =>
     // `JinaEmbedding` tag.
     // These calls exist only to assert the encoding is a compile error; they
     // are intentionally never run, so the floating-effect check is off here.
-    // @effect-diagnostics effect/floatingEffect:off
+    // @effect-diagnostics floatingEffect:off
     // @ts-expect-error "multivector" is not an EmbedEncoding
     embedMany({ inputs: ["x"], model: "m", encoding: "multivector" })
     // @ts-expect-error "sparse" is not an EmbedEncoding
     embed({ input: "x", model: "m", encoding: "sparse" })
-    // @effect-diagnostics effect/floatingEffect:error
+    // @effect-diagnostics floatingEffect:error
   })
 
   it("when the request is widened to CommonEmbedRequest, the response is the open union", () => {

package/src/index.ts

@@ -46,11 +46,12 @@ export * as Settle from "./streaming/Settle.js"
 export * as WebSocketSession from "./streaming/WebSocketSession.js"
 export * as Loop from "./loop/Loop.js"
 export * as Retry from "./retry/Retry.js"
+export * as Content from "./tool/Content.js"
 export * as Tool from "./tool/Tool.js"
 export * as Toolkit from "./tool/Toolkit.js"
-export * as ToolResult from "./tool/ToolResult.js"
 export * as ToolEvent from "./tool/ToolEvent.js"
-export * as Approval from "./tool/Approval.js"
+export * as ToolOutput from "./tool/ToolOutput.js"
+export * as ToolDecision from "./tool/ToolDecision.js"
 export * as HistoryCheck from "./tool/HistoryCheck.js"
 export * as JSONL from "./streaming/JSONL.js"
 export * as Lines from "./streaming/Lines.js"

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(
@@ -307,7 +318,7 @@ export const loop: {
 
         // `Stream.fromPull` expects the generator to RETURN the pull effect,
         // not run it; `return yield* pull` would execute a pull and break it.
-        // @effect-diagnostics-next-line effect/returnEffectInGen:off
+        // @effect-diagnostics-next-line returnEffectInGen:off
         return pull
       }),
     ),

package/src/observability/Telemetry.test.ts

@@ -1,6 +1,6 @@
 import { describe, it } from "@effect/vitest"
 import { Array as Arr, Duration, Effect, Layer, Metric, Option, Ref, Stream } from "effect"
-import { type HttpBody, HttpClient, HttpClientResponse } from "effect/unstable/http"
+import { type HttpBody, HttpClient, HttpClientResponse } from "effect/http"
 import { expect } from "vitest"
 import { type Measurement, makeEvent } from "./Metrics.js"
 import { layerOtlp, record } from "./Telemetry.js"

package/src/observability/Telemetry.ts

@@ -1,6 +1,6 @@
 import { Duration, Effect, Layer, Match, Metric, Stream } from "effect"
-import type { HttpClient } from "effect/unstable/http"
-import { OtlpMetrics, OtlpSerialization } from "effect/unstable/observability"
+import type { HttpClient } from "effect/http"
+import { OtlpMetrics, OtlpSerialization } from "effect/observability"
 import { isMetricEvent, type Measurement, type MetricEvent } from "./Metrics.js"
 
 // ---------------------------------------------------------------------------

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

@@ -1,5 +1,5 @@
 import { Effect } from "effect"
-import { HttpClientRequest } from "effect/unstable/http"
+import { HttpClientRequest } from "effect/http"
 
 /**
  * Multipart body for an `HttpClientRequest`, encoded to bytes.
@@ -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/streaming/SSE.ts

@@ -1,5 +1,5 @@
 import { Stream } from "effect"
-import { Sse } from "effect/unstable/encoding"
+import { Sse } from "effect/encoding"
 
 /**
  * One Server-Sent Event. Fields per the WHATWG spec:
@@ -35,7 +35,7 @@ const makeParserState = (): ParserState => {
 
 /**
  * Decode a `Stream<Uint8Array>` (e.g. an HTTP response body) into a
- * `Stream<SSE.Event>`, using the spec parser from `effect/unstable/encoding`.
+ * `Stream<SSE.Event>`, using the spec parser from `effect/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.

package/src/streaming/WebSocketSession.test.ts

@@ -1,8 +1,10 @@
 import { describe, it } from "@effect/vitest"
-import * as Socket from "effect/unstable/socket/Socket"
+import { Effect, Exit, Pull, Queue, Schema } from "effect"
+import * as Socket from "effect/socket/Socket"
 import { expect } from "vitest"
 import * as AiError from "../domain/AiError.js"
-import { toAiError } from "./WebSocketSession.js"
+import * as FakeWebSocket from "../testing/FakeWebSocket.js"
+import { open, toAiError } from "./WebSocketSession.js"
 
 const KEY = "AIzaSyEXAMPLEKEY"
 const URL = `wss://generativelanguage.googleapis.com/ws/BidiGenerateContent?key=${KEY}`
@@ -50,3 +52,53 @@ describe("WebSocketSession errors", () => {
     expect(ended._tag).toBe("Unavailable")
   })
 })
+
+const Frame = Schema.Struct({ n: Schema.Number })
+
+const session = (server: FakeWebSocket.FakeWebSocketServer) =>
+  open({ url: "wss://example.test", provider: "test", schema: Frame }).pipe(
+    Effect.provide(server.layer),
+  )
+
+describe("WebSocketSession lifetime", () => {
+  it.live("writes a reply to a frame before the next one arrives", () =>
+    Effect.gen(function* () {
+      const server = yield* FakeWebSocket.make({ greeting: [{ n: 1 }] })
+      const { send, frames } = yield* session(server)
+
+      const first = yield* Queue.take(frames)
+      yield* send(JSON.stringify({ n: first.n + 1 }))
+      yield* Effect.sleep("5 millis")
+
+      expect(yield* server.sent).toEqual([{ n: 2 }])
+    }).pipe(Effect.scoped),
+  )
+
+  it.live("ends the frames on a clean close, and refuses a send after it", () =>
+    Effect.gen(function* () {
+      const server = yield* FakeWebSocket.make({ greeting: [{ n: 1 }] })
+      const { send, frames } = yield* session(server)
+
+      yield* Queue.take(frames)
+      yield* server.close(1000)
+      const end = yield* Effect.exit(Queue.take(frames))
+      const late = yield* Effect.exit(send(JSON.stringify({ n: 2 })))
+
+      expect(Exit.isFailure(end) && Pull.isDoneCause(end.cause)).toBe(true)
+      expect(Exit.isFailure(late) && JSON.stringify(late)).toContain("Unavailable")
+    }).pipe(Effect.scoped),
+  )
+
+  it.live("fails the frames on a dirty close", () =>
+    Effect.gen(function* () {
+      const server = yield* FakeWebSocket.make({ greeting: [{ n: 1 }] })
+      const { frames } = yield* session(server)
+
+      yield* Queue.take(frames)
+      yield* server.close(1011)
+      const end = yield* Effect.exit(Queue.take(frames))
+
+      expect(JSON.stringify(end)).toContain("Unavailable")
+    }).pipe(Effect.scoped),
+  )
+})

package/src/streaming/WebSocketSession.ts

@@ -14,10 +14,12 @@ import {
   Option,
   Predicate,
   Queue,
+  Ref,
   Schema,
   type Scope,
+  Stream,
 } from "effect"
-import * as Socket from "effect/unstable/socket/Socket"
+import * as Socket from "effect/socket/Socket"
 import * as AiError from "../domain/AiError.js"
 import * as JSONL from "./JSONL.js"
 
@@ -85,6 +87,13 @@ export const toAiError =
     )
   }
 
+/** Normal closure, going away, and no status code. */
+const cleanCloseCodes: ReadonlySet<number> = new Set([1000, 1001, 1005])
+
+/** Effect's `Socket` fails on every close, clean or not. */
+export const isCleanClose = (error: Socket.SocketError): boolean =>
+  error.reason._tag === "SocketCloseError" && cleanCloseCodes.has(error.reason.code)
+
 /**
  * Connect for the lifetime of the surrounding `Scope`. The reader runs in a
  * forked fiber; a dirty close reaches the consumer as a failed queue rather
@@ -97,12 +106,14 @@ export const open = <A, I>(
     const asAiError = toAiError(options.provider)
     const decode = Schema.decodeUnknownEffect(options.schema)
     const socket = yield* Socket.makeWebSocket(options.url, {
-      // Effect's Socket treats every close code as an error by default.
-      closeCodeIsError: (code) => code !== 1000 && code !== 1001 && code !== 1005,
       ...(options.openTimeout !== undefined && { openTimeout: options.openTimeout }),
     })
     const frames = yield* Queue.bounded<A, AiError.AiError | Cause.Done>(options.capacity ?? 64)
-    const write = yield* socket.writer
+    const { write } = yield* socket.writer
+    // The writer waits for the next connection rather than failing, so a send
+    // after the reader ends has to be refused here.
+    const ended = yield* Ref.make(false)
+    const closed = new AiError.Unavailable({ provider: options.provider, raw: "socket closed" })
 
     const onFrame = (raw: string) =>
       Effect.gen(function* () {
@@ -116,8 +127,13 @@ export const open = <A, I>(
         yield* Queue.offer(frames, decoded.value)
       })
 
-    yield* socket.runString(onFrame).pipe(
+    yield* Stream.fromPull(Socket.readerString(socket)).pipe(
+      Stream.scoped,
+      Stream.catchIf(isCleanClose, () => Stream.empty),
+      Stream.runForEach(onFrame),
       Effect.mapError(asAiError),
+      // Set before `frames` ends, so a send after the last frame already fails.
+      Effect.ensuring(Ref.set(ended, true)),
       // `Queue.end` on a clean close so the consumer drains what is queued;
       // a failure must not arrive looking like the end of the conversation.
       Effect.matchCauseEffect({
@@ -128,5 +144,10 @@ export const open = <A, I>(
       Effect.forkScoped,
     )
 
-    return { send: (frame: string) => write(frame).pipe(Effect.mapError(asAiError)), frames }
+    const send = (frame: string): Effect.Effect<void, AiError.AiError> =>
+      Effect.flatMap(Ref.get(ended), (isEnded) =>
+        isEnded ? Effect.fail(closed) : Effect.mapError(write(frame), asAiError),
+      )
+
+    return { send, frames }
   })

package/src/structured-format/StructuredFormat.ts

@@ -145,7 +145,7 @@ export const parseJson =
         // Validation runs through Standard Schema (Zod / Valibot / Effect), not
         // Effect Schema, so its JSON codecs don't apply here; and JSON.parse is
         // a separate step on purpose, to surface JsonParseError distinctly.
-        // @effect-diagnostics-next-line effect/preferSchemaOverJson:off
+        // @effect-diagnostics-next-linepreferSchemaOverJson:off
         try: () => JSON.parse(raw),
         catch: (cause) => new JsonParseError({ raw, cause }),
       }),

package/src/testing/FakeWebSocket.ts

@@ -10,12 +10,16 @@
  * shim registers, since `Socket.makeWebSocket` drives it with plain callbacks.
  * The shim is a plain object, so nothing here touches a platform global.
  */
-import { Effect, Layer, Queue, Ref, type Scope, Stream } from "effect"
-import * as Socket from "effect/unstable/socket/Socket"
+import { Deferred, Effect, Layer, Queue, type Scope, Stream, SubscriptionRef } from "effect"
+import * as Socket from "effect/socket/Socket"
 
 export type FakeWebSocketServer = {
   /** Every frame the client has sent, JSON-parsed, oldest first. */
   readonly sent: Effect.Effect<ReadonlyArray<unknown>>
+  /** Wait until the client has sent at least `count` frames. */
+  readonly awaitSent: (count: number) => Effect.Effect<void>
+  /** Wait until the client has subscribed and the greeting has landed. */
+  readonly greeted: Effect.Effect<void>
   /** Deliver one frame to the client. */
   readonly push: (frame: unknown) => Effect.Effect<void>
   /** Close the socket. 1000, 1001 and 1005 are the clean codes. */
@@ -46,7 +50,8 @@ export const make = (
 ): Effect.Effect<FakeWebSocketServer, never, Scope.Scope> =>
   Effect.gen(function* () {
     const inbound = yield* Queue.unbounded<unknown>()
-    const sent = yield* Ref.make<ReadonlyArray<unknown>>([])
+    const sent = yield* SubscriptionRef.make<ReadonlyArray<unknown>>([])
+    const greeted = yield* Deferred.make<void>()
 
     const wiring = {
       listeners: {} as Record<string, ReadonlyArray<Listener>>,
@@ -73,7 +78,7 @@ export const make = (
     yield* Stream.fromQueue(inbound).pipe(
       Stream.runForEach((frame) =>
         Effect.gen(function* () {
-          yield* Ref.update(sent, (frames) => [...frames, frame])
+          yield* SubscriptionRef.update(sent, (frames) => [...frames, frame])
           const answer = yield* options?.reply?.(frame) ?? Effect.succeed([])
           yield* deliver(answer)
         }),
@@ -93,7 +98,10 @@ export const make = (
         // The greeting waits for a subscriber before it lands.
         if (type === "message" && !wiring.greeted) {
           wiring.greeted = true
-          soon(() => deliverSync(options?.greeting ?? []))
+          soon(() => {
+            deliverSync(options?.greeting ?? [])
+            Deferred.doneUnsafe(greeted, Effect.void)
+          })
         }
       },
       removeEventListener: (type: string, fn: Listener): void => {
@@ -111,7 +119,14 @@ export const make = (
       socket as unknown as globalThis.WebSocket
 
     return {
-      sent: Ref.get(sent),
+      sent: SubscriptionRef.get(sent),
+      awaitSent: (count) =>
+        SubscriptionRef.changes(sent).pipe(
+          Stream.filter((frames) => frames.length >= count),
+          Stream.take(1),
+          Stream.runDrain,
+        ),
+      greeted: Deferred.await(greeted),
       push: (frame) => deliver([frame]),
       close: (code = 1000) => Effect.sync(() => shutdown(code)),
       connect,

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 })),
+  )