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

package/src/tool/ToolEvent.ts

@@ -1,46 +1,26 @@
 /**
- * The event type emitted while handling tool calls.
- *
- *   - ApprovalRequested : gated calls waiting for approval
- *   - Progress          : per-element passthrough from a streaming tool's run
- *   - Output            : terminal result (carries a structured ToolResult)
- *
- * Recipes thread `ToolEvent.Output.result` through `continueWithResults` and
- * apply `toToolCallOutput` when appending to history.
- *
- * Demux note: `Progress` carries `call_id` / `tool` at the top level, while
- * `Output` nests them inside `result` (the `ToolResult` already carries both).
- * A consumer grouping events by call reads `e.call_id` for `Progress` and
- * `e.result.call_id` for `Output`.
+ * What `Toolkit.run` emits, typed per tool: `tool` is the discriminant, so
+ * `e.tool === "search"` narrows `value` / `result` to that tool's types. Values
+ * are decoded (the tool's own types); `Toolkit.output` encodes them for history.
  */
-import { Data } from "effect"
-import type { ToolResult } from "./ToolResult.js"
+import type { Result } from "effect"
 
-export type ToolEvent = Data.TaggedEnum<{
-  ApprovalRequested: {
-    readonly call_id: string
-    readonly tool: string
-    readonly arguments: string
-  }
-  Progress: {
-    readonly call_id: string
-    readonly tool: string
-    readonly data: unknown
-  }
-  Output: {
-    readonly result: ToolResult
-  }
-}>
+/** An intermediate value of a `Stream` tool. */
+export type Partial<Name extends string = string, Output = unknown> = {
+  readonly _tag: "Partial"
+  readonly call_id: string
+  readonly tool: Name
+  readonly value: Output
+}
 
-/**
- * Namespace of constructors, type guards, and matchers for `ToolEvent`,
- * provided by `Data.taggedEnum`. Use `ToolEvent.Output({ result })` to build
- * an event, `ToolEvent.$is("Output")` for type narrowing,
- * `ToolEvent.$match({ ApprovalRequested, Progress, Output })` for
- * exhaustive pattern matching.
- */
-export const ToolEvent = Data.taggedEnum<ToolEvent>()
+/** The call ended: `Success` with its value, or `Failure` with a declared or core error. */
+export type Output<Name extends string = string, Out = unknown, E = unknown> = {
+  readonly _tag: "Output"
+  readonly call_id: string
+  readonly tool: Name
+  readonly result: Result.Result<Out, E>
+}
 
-export const isApprovalRequested = ToolEvent.$is("ApprovalRequested")
-export const isProgress = ToolEvent.$is("Progress")
-export const isOutput = ToolEvent.$is("Output")
+export type ToolEvent<Name extends string = string, Out = unknown, E = unknown> =
+  | Partial<Name, Out>
+  | Output<Name, Out, E>

package/src/tool/ToolOutput.test.ts

@@ -0,0 +1,132 @@
+import { describe, expect, it } from "@effect/vitest"
+import { Effect, Schema, SchemaTransformation } from "effect"
+import { imageBytes } from "../domain/Image.js"
+import * as Content from "./Content.js"
+import * as ToolOutput from "./ToolOutput.js"
+
+const call = { call_id: "c1" }
+const png = Content.image(imageBytes(new Uint8Array([1, 2, 3]), "image/png"))
+
+describe("ToolOutput.success", () => {
+  it.effect("splits only top-level media: text, JSON and arrays without media stay one part", () =>
+    Effect.gen(function* () {
+      const outputs = yield* Effect.forEach(["hello", { hits: [1, 2] }, [1, 2], png], (value) =>
+        ToolOutput.make(call, value),
+      )
+      expect(outputs.map((o) => o.output.map((p) => p.type))).toEqual([
+        ["input_text"],
+        ["input_json"],
+        ["input_json"],
+        ["input_image"],
+      ])
+    }),
+  )
+
+  it.effect("takes JSON from the schema's encoded side and media from the value", () =>
+    Effect.gen(function* () {
+      const Shot = Schema.Tuple([
+        Schema.Struct({ title: Schema.String, at: Schema.DateFromString }),
+        Content.Image,
+      ])
+      const value = [{ title: "Home", at: new Date("2026-01-01T00:00:00.000Z") }, png] as const
+
+      const out = yield* ToolOutput.success(call, Shot, value)
+      expect(out.output).toEqual([
+        { type: "input_json", value: { title: "Home", at: "2026-01-01T00:00:00.000Z" } },
+        { type: "input_image", source: png.source },
+      ])
+      expect(out.isError).toBeUndefined()
+
+      const back = yield* ToolOutput.encoded(out.output).pipe(
+        Effect.flatMap(Schema.decodeUnknownEffect(Shot)),
+      )
+      expect(back).toEqual(value)
+    }),
+  )
+
+  it.effect("keeps the JSON whole when the schema encodes a mixed array to another shape", () =>
+    Effect.gen(function* () {
+      const Encoded = Schema.Struct({
+        title: Schema.String,
+        shot: Schema.toEncoded(Content.Image),
+      })
+      const Reshaped = Encoded.pipe(
+        Schema.decodeTo(
+          Schema.Tuple([Schema.String, Content.Image]),
+          SchemaTransformation.transform({
+            decode: ({ title, shot }) => [title, shot] as const,
+            encode: ([title, shot]) => ({ title, shot }),
+          }),
+        ),
+      )
+      const out = yield* ToolOutput.success(call, Reshaped, ["Home", png] as const)
+      expect(out.output).toHaveLength(1)
+      expect(out.output[0]).toMatchObject({
+        type: "input_json",
+        value: { title: "Home", shot: { _tag: "Image" } },
+      })
+    }),
+  )
+})
+
+describe("ToolOutput.failure", () => {
+  it.effect("encodes the error as JSON and flags the output", () =>
+    Effect.gen(function* () {
+      const out = yield* ToolOutput.failure(
+        call,
+        ToolOutput.RunError,
+        new ToolOutput.UnknownTool({ message: "no tool named nope" }),
+      )
+      expect(out).toEqual({
+        type: "function_call_output",
+        call_id: "c1",
+        output: [
+          { type: "input_json", value: { _tag: "UnknownTool", message: "no tool named nope" } },
+        ],
+        isError: true,
+      })
+    }),
+  )
+})
+
+describe("ToolOutput.value", () => {
+  it.effect("reads parts back as the value that made them, media as classes", () =>
+    Effect.gen(function* () {
+      const value = [{ title: "Home" }, png, "caption"]
+      const out = yield* ToolOutput.make(call, value)
+      expect(out.output.map((p) => p.type)).toEqual(["input_json", "input_image", "input_text"])
+      const back = ToolOutput.value(out.output)
+      expect(back).toEqual(value)
+      expect(Array.isArray(back) && back[1]).toBeInstanceOf(Content.Image)
+    }),
+  )
+})
+
+describe("ToolOutput.ValueParts", () => {
+  const encode = Schema.encodeEffect(ToolOutput.ValueParts)
+  const decode = Schema.decodeUnknownEffect(ToolOutput.ValueParts)
+
+  it.effect("JSON shaped like an image stays JSON through the wire", () =>
+    Effect.gen(function* () {
+      const lookalike = { _tag: "Image", source: { _tag: "url", url: "https://x/cat.png" } }
+      const wire = yield* encode(lookalike)
+      expect(wire).toEqual([{ type: "input_json", value: lookalike }])
+      const back = yield* decode(JSON.parse(JSON.stringify(wire)))
+      expect(back).toEqual(lookalike)
+      expect(back).not.toBeInstanceOf(Content.Image)
+    }),
+  )
+
+  it.effect("media round-trips as a class, bytes as base64 on the wire", () =>
+    Effect.gen(function* () {
+      const value = [{ title: "Home" }, png, "caption"]
+      const wire = yield* encode(value)
+      expect(wire[1]).toEqual({
+        type: "input_image",
+        source: { _tag: "bytes", bytes: "AQID", mimeType: "image/png" },
+      })
+      const back = yield* decode(JSON.parse(JSON.stringify(wire)))
+      expect(back).toEqual(value)
+    }),
+  )
+})

package/src/tool/ToolOutput.ts

@@ -0,0 +1,198 @@
+/**
+ * Tool values to history parts, and back. One rule, top level only:
+ *   string → text · media → its part · array with media → one part per element ·
+ *   anything else → one JSON value.
+ * Every value goes through a schema (the tool's `outputSchema`, else `Content.Value`):
+ * the decoded side decides the shape and supplies media, the encoded side the JSON.
+ */
+import {
+  Array as Arr,
+  Effect,
+  Match,
+  Option,
+  Predicate,
+  Schema,
+  SchemaTransformation,
+} from "effect"
+import { FileSourceJson } from "../domain/File.js"
+import { ImageSourceJson } from "../domain/Image.js"
+import * as Items from "../domain/Items.js"
+import type { ToolCall, ToolCallOutput, ToolOutputContent } from "../domain/Items.js"
+import * as Content from "./Content.js"
+
+type CallId = Pick<ToolCall, "call_id">
+
+const toPart = Match.type<Content.Media>().pipe(
+  Match.tagsExhaustive({
+    Image: (m) => Items.image(m.source),
+    File: (m) => Items.file(m.source, m.filename),
+  }),
+)
+
+const fromPart = Match.type<ToolOutputContent>().pipe(
+  Match.discriminatorsExhaustive("type")({
+    input_text: (p) => p.text,
+    input_json: (p) => p.value,
+    input_image: (p) => Content.image(p.source),
+    input_file: (p) => Content.file(p.source, p.filename),
+  }),
+)
+
+const isMixed = (u: unknown): u is ReadonlyArray<unknown> =>
+  Array.isArray(u) && u.some(Content.isMedia)
+
+const zipMixed = (
+  decoded: ReadonlyArray<unknown>,
+  encoded: Schema.Json,
+): ReadonlyArray<ToolOutputContent> =>
+  Array.isArray(encoded) && encoded.length === decoded.length
+    ? Arr.zipWith(decoded, encoded, (d, e) =>
+        Match.value(d).pipe(
+          Match.when(Content.isMedia, toPart),
+          Match.orElse(() => (Predicate.isString(e) ? Items.text(e) : Items.json(e))),
+        ),
+      )
+    : [Items.json(encoded)] // the schema reshaped the array: keep its JSON whole
+
+/** `decoded` decides the shape and supplies media; `encoded` supplies the JSON. */
+export const parts = (decoded: unknown, encoded: Schema.Json): ReadonlyArray<ToolOutputContent> =>
+  Match.value(decoded).pipe(
+    Match.when(Predicate.isString, (text) => [Items.text(text)]),
+    Match.when(Content.isMedia, (media) => [toPart(media)]),
+    Match.when(isMixed, (values) => zipMixed(values, encoded)),
+    Match.orElse(() => [Items.json(encoded)]),
+  )
+
+/** A value, encoded by `schema`, as the call's output. */
+export const success = <A>(
+  call: CallId,
+  schema: Schema.Codec<A, Schema.Json>,
+  value: A,
+): Effect.Effect<ToolCallOutput, Schema.SchemaError> =>
+  Effect.map(Schema.encodeEffect(schema)(value), (encoded) => ({
+    type: "function_call_output",
+    call_id: call.call_id,
+    output: parts(value, encoded),
+  }))
+
+/** An error, encoded by `schema`, as the call's output, flagged `isError`. */
+export const failure = <E>(
+  call: CallId,
+  schema: Schema.Codec<E, Schema.Json>,
+  error: E,
+): Effect.Effect<ToolCallOutput, Schema.SchemaError> =>
+  Effect.map(Schema.encodeEffect(schema)(error), (encoded) => ({
+    type: "function_call_output",
+    call_id: call.call_id,
+    output: [Items.json(encoded)],
+    isError: true,
+  }))
+
+/** Any `Content.Value` as the call's output, for calls the app closes itself. */
+export const make = (call: CallId, value: Content.Value) => success(call, Content.Value, value)
+
+/** One value as itself, several (or none) as the array: how parts read back as a value. */
+export const single = <A>(values: ReadonlyArray<A>): A | ReadonlyArray<A> =>
+  Arr.isReadonlyArrayNonEmpty(values) && values.length === 1 ? Arr.headNonEmpty(values) : values
+
+/** A text or JSON part. */
+export const isTextual = (p: ToolOutputContent): p is Items.InputText | Items.InputJson =>
+  p.type === "input_text" || p.type === "input_json"
+
+/** A text part verbatim, a JSON part serialized. */
+export const partText = (p: Items.InputText | Items.InputJson): string =>
+  p.type === "input_text" ? p.text : JSON.stringify(p.value)
+
+/**
+ * The parts as one string joined by newlines, for wires (or wire paths) whose
+ * tool outputs carry text only. `None` when a part is media.
+ */
+export const text = (output: ReadonlyArray<ToolOutputContent>): Option.Option<string> =>
+  Arr.every(output, isTextual) ? Option.some(output.map(partText).join("\n")) : Option.none()
+
+/** Parts back to a `Content.Value`, read from the parts' own types. */
+export const value = (output: ReadonlyArray<ToolOutputContent>): Content.Value =>
+  single(output.map(fromPart))
+
+/** Parts back to the encoded form an `outputSchema` decodes (media re-encoded). */
+export const encoded = (
+  output: ReadonlyArray<ToolOutputContent>,
+): Effect.Effect<unknown, Schema.SchemaError> =>
+  Effect.forEach(output.map(fromPart), (v) =>
+    Content.isMedia(v) ? Schema.encodeEffect(Content.Media)(v) : Effect.succeed(v),
+  ).pipe(Effect.map(single))
+
+// --- a Content.Value as typed parts, for the wire to a UI -------------------------
+
+const isJson = Schema.is(Schema.Json)
+
+const elementPart = Match.type<Content.Media | Schema.Json>().pipe(
+  Match.when(Content.isMedia, toPart),
+  Match.when(Predicate.isString, Items.text),
+  Match.orElse(Items.json),
+)
+
+/** A `Content.Value` as history parts, by the same rule as `parts` (its JSON is itself). */
+export const valueParts = (v: Content.Value): ReadonlyArray<ToolOutputContent> =>
+  Match.value(v).pipe(
+    Match.when(Predicate.isString, (text) => [Items.text(text)]),
+    Match.when(Content.isMedia, (media) => [toPart(media)]),
+    Match.when(isMixed, (values) => values.map(elementPart)),
+    Match.when(isJson, (json) => [Items.json(json)]),
+    // Unreachable: a Content.Value is text, JSON, media or a mix of them.
+    Match.orElse(() => []),
+  )
+
+/** A history part with JSON sources (bytes as base64), as it travels to a UI. */
+export const PartJson = Schema.Union([
+  Items.InputText,
+  Items.InputJson,
+  Schema.Struct({ type: Schema.Literal("input_image"), source: ImageSourceJson }),
+  Schema.Struct({
+    type: Schema.Literal("input_file"),
+    source: FileSourceJson,
+    filename: Schema.optionalKey(Schema.String),
+  }),
+])
+
+/**
+ * A `Content.Value` on the wire to a UI: typed parts instead of its plain JSON,
+ * so JSON shaped like `{ _tag: "Image", source }` can't come back as an image.
+ */
+export const ValueParts = Schema.Array(PartJson).pipe(
+  Schema.decodeTo(
+    Schema.toType(Content.Value),
+    SchemaTransformation.transform({ decode: value, encode: valueParts }),
+  ),
+)
+
+// --- core's own failures -------------------------------------------------------
+
+/** The model's arguments are not JSON or fail `inputSchema`. */
+export class InputInvalid extends Schema.TaggedError<InputInvalid>(
+  "@betalyra/effect-uai/InputInvalid",
+)("InputInvalid", { message: Schema.String }) {}
+
+/** `run` returned a value its `outputSchema` rejects: a bug in the tool. */
+export class OutputInvalid extends Schema.TaggedError<OutputInvalid>(
+  "@betalyra/effect-uai/OutputInvalid",
+)("OutputInvalid", { message: Schema.String }) {}
+
+/** No local tool by that name (hallucinated, removed, or a declared or provider tool). */
+export class UnknownTool extends Schema.TaggedError<UnknownTool>(
+  "@betalyra/effect-uai/UnknownTool",
+)("UnknownTool", { message: Schema.String }) {}
+
+/** The call was left unanswered and closed before the next model call. */
+export class Cancelled extends Schema.TaggedError<Cancelled>("@betalyra/effect-uai/Cancelled")(
+  "Cancelled",
+  { message: Schema.String },
+) {}
+
+/** What `Toolkit.run` produces itself. */
+export type RunError = InputInvalid | OutputInvalid | UnknownTool
+export const RunError = Schema.Union([InputInvalid, OutputInvalid, UnknownTool])
+
+/** Every error core writes into history; what history and the UI always decode. */
+export type CoreError = RunError | Cancelled
+export const CoreError = Schema.Union([InputInvalid, OutputInvalid, UnknownTool, Cancelled])