@effect-uai/core 0.9.0 → 0.10.0

package/src/tool/Tool.ts

@@ -1,7 +1,8 @@
 import type { StandardJSONSchemaV1, StandardSchemaV1 } from "@standard-schema/spec"
-import { Effect, Schema } from "effect"
+import { Effect, Match, Schema } from "effect"
 import type { ToolCall, ToolCallOutput } from "../domain/Items.js"
 import { toolCallOutput } from "../domain/Items.js"
+import { serializeValue } from "./ToolResult.js"
 
 export class ToolError extends Schema.TaggedErrorClass<ToolError>("@betalyra/effect-uai/ToolError")(
   "ToolError",
@@ -37,6 +38,35 @@ export class ToolValidationError extends Schema.TaggedErrorClass<ToolValidationE
   issues: Schema.Array(ToolValidationIssue),
 }) {}
 
+/**
+ * The deliberate "speak to the model" failure sentinel. A tool's `run` that
+ * fails with a `ToolFailed` (or a bare `string`, its sugar) is absorbed by
+ * `Toolkit.run` into a `ToolResult.Failure` the model reads and adapts to,
+ * instead of ending the run. Every other error type propagates typed on the
+ * executor's stream. `kind` overrides the synthesized `Failure.kind`
+ * (default `"tool_failed"`) so a tool can hand the model a distinguishable
+ * category (`"not_found"`, `"rate_limited"`) without a new result variant.
+ */
+export class ToolFailed extends Schema.TaggedErrorClass<ToolFailed>(
+  "@betalyra/effect-uai/ToolFailed",
+)("ToolFailed", {
+  message: Schema.String,
+  kind: Schema.optional(Schema.String),
+}) {}
+
+/**
+ * Fail a tool's `run` with a model-visible message (optionally a `kind`).
+ * `yield* Tool.fail("page not found", { kind: "not_found" })` inside a
+ * `run`'s `Effect.gen`; the executor absorbs it as `ToolResult.Failure`.
+ */
+export const fail = (
+  message: string,
+  options?: { readonly kind?: string },
+): Effect.Effect<never, ToolFailed> =>
+  Effect.fail(
+    new ToolFailed({ message, ...(options?.kind !== undefined ? { kind: options.kind } : {}) }),
+  )
+
 /**
  * Schemas accepted on `Tool.inputSchema`. Must implement both Standard
  * Schema validation and JSON Schema conversion (for rendering tool
@@ -79,6 +109,25 @@ export const fromStandardSchema = <S extends StandardSchemaV1 & StandardJSONSche
 ): S & ToolInputSchema<StandardSchemaV1.InferOutput<S>> =>
   schema as S & ToolInputSchema<StandardSchemaV1.InferOutput<S>>
 
+/**
+ * Input schema for a tool that takes no arguments. Renders a clean
+ * `{ type: "object", properties: {} }`; validation accepts anything and
+ * yields `{}`. Use it instead of `fromEffectSchema(Schema.Struct({}))`,
+ * which renders a degenerate `anyOf` (object-or-array) that strict
+ * providers like Gemini reject.
+ */
+export const noInput: ToolInputSchema<Record<string, never>> = {
+  "~standard": {
+    version: 1,
+    vendor: "effect-uai",
+    validate: () => ({ value: {} }),
+    jsonSchema: {
+      input: () => ({ type: "object", properties: {} }),
+      output: () => ({ type: "object", properties: {} }),
+    },
+  },
+}
+
 /**
  * Emit one intermediate `Event` from inside a tool's `run`. Backed by the
  * executor's per-call queue, so it returns an `Effect` (backpressure) and
@@ -98,12 +147,12 @@ export type Emit<Event> = (event: Event) => Effect.Effect<void>
  * no local executor — see their constructors below. `Tool` keeps its name (and
  * the `Tool.make` constructor) because the local kind is by far the common one.
  */
-export type Tool<Name extends string, Input, Event, Output, R = never> = {
+export type Tool<Name extends string, Input, Event, Output, E = unknown, R = never> = {
   readonly _tag: "LocalTool"
   readonly name: Name
   readonly description: string
   readonly inputSchema: ToolInputSchema<Input>
-  readonly run: (input: Input, emit: Emit<Event>) => Effect.Effect<Output, unknown, R>
+  readonly run: (input: Input, emit: Emit<Event>) => Effect.Effect<Output, E, R>
   /**
    * Bound on this tool's emit queue. Unbounded when omitted. Per-tool because
    * backpressure depends on how a given tool emits, unlike `concurrency`
@@ -162,11 +211,11 @@ export type InteractionTool<Name extends string, Input> = {
 }
 
 /** A local (executable) tool of any shape. Readability alias. */
-export type AnyLocalTool<R = any> = Tool<string, any, any, any, R>
+export type AnyLocalTool<E = any, R = any> = Tool<string, any, any, any, E, R>
 
 /** Any of the four model-visible tool kinds. */
-export type AnyTool<R = any> =
-  | Tool<string, any, any, any, R>
+export type AnyTool<E = any, R = any> =
+  | Tool<string, any, any, any, E, R>
   | ProviderTool<string, any, string, any>
   | SignalTool<string, any>
   | InteractionTool<string, any>
@@ -178,7 +227,10 @@ export type DecodableTool<Input> = {
 }
 
 /** Extract the `R` of a local tool; non-local kinds contribute `never`. */
-export type ToolR<T> = T extends Tool<string, any, any, any, infer R> ? R : never
+export type ToolR<T> = T extends Tool<string, any, any, any, any, infer R> ? R : never
+
+/** Extract the `E` of a local tool; non-local kinds contribute `never`. */
+export type ToolE<T> = T extends Tool<string, any, any, any, infer E, any> ? E : never
 
 /**
  * Provider-agnostic tool descriptor. Each provider maps `inputSchema`
@@ -193,9 +245,9 @@ export type ToolDescriptor = {
 }
 
 /** A model-visible tool with a local `Effect` executor. */
-export const make = <Name extends string, Input, Event, Output, R = never>(
-  spec: Omit<Tool<Name, Input, Event, Output, R>, "_tag">,
-): Tool<Name, Input, Event, Output, R> => ({ _tag: "LocalTool", ...spec })
+export const make = <Name extends string, Input, Event, Output, E = never, R = never>(
+  spec: Omit<Tool<Name, Input, Event, Output, E, R>, "_tag">,
+): Tool<Name, Input, Event, Output, E, R> => ({ _tag: "LocalTool", ...spec })
 
 /**
  * A provider-hosted tool (native web search, code execution, RAG grounding).
@@ -245,10 +297,20 @@ export const withName = <N extends string, T extends AnyTool>(
  * Descriptors stay identical to production, so a mocked toolkit can't drift
  * from the contract the model sees.
  */
-export const withRun = <Name extends string, Input, Event, Output, R, Output2, R2 = never>(
-  tool: Tool<Name, Input, Event, Output, R>,
-  run: (input: Input, emit: Emit<Event>) => Effect.Effect<Output2, unknown, R2>,
-): Tool<Name, Input, Event, Output2, R2> => ({ ...tool, run })
+export const withRun = <
+  Name extends string,
+  Input,
+  Event,
+  Output,
+  E,
+  R,
+  Output2,
+  E2 = never,
+  R2 = never,
+>(
+  tool: Tool<Name, Input, Event, Output, E, R>,
+  run: (input: Input, emit: Emit<Event>) => Effect.Effect<Output2, E2, R2>,
+): Tool<Name, Input, Event, Output2, E2, R2> => ({ ...tool, run })
 
 /** Render tools to provider-agnostic descriptors. Every kind is model-visible. */
 export const toDescriptors = (tools: ReadonlyArray<AnyTool>): ReadonlyArray<ToolDescriptor> =>
@@ -275,8 +337,51 @@ export const descriptorsOf = (
 ): ReadonlyArray<ToolDescriptor> =>
   toolkit === undefined ? [] : toDescriptors(Object.values(toolkit))
 
-const toToolError = (call: ToolCall, toolName: string, message: string) => (cause: unknown) =>
-  new ToolError({ call_id: call.call_id, tool: toolName, message, cause })
+/**
+ * Outcome of decoding a call's `arguments` against a tool's `inputSchema`,
+ * as data so both the typed (`decodeArgs`) and result-synthesizing
+ * (`Toolkit.run`) callers can translate it their own way.
+ */
+export type DecodeResult<Input> =
+  | { readonly _tag: "ok"; readonly input: Input }
+  | { readonly _tag: "parseError" }
+  | { readonly _tag: "invalid"; readonly issues: ReadonlyArray<StandardSchemaV1.Issue> }
+
+const VALIDATION_THREW: ReadonlyArray<StandardSchemaV1.Issue> = [
+  { message: "input schema validation threw" },
+]
+
+/**
+ * Parse and validate a call's `arguments`. Empty arguments normalize to
+ * `{}` (some models emit `""` for zero-arg tools); a throwing validator is
+ * captured, not propagated. Never fails.
+ */
+export const decodeCallInput = <Input>(
+  tool: DecodableTool<Input>,
+  call: ToolCall,
+): Effect.Effect<DecodeResult<Input>> => {
+  const raw = call.arguments.trim() === "" ? "{}" : call.arguments
+  return Effect.try({
+    // @effect-diagnostics-next-line effect/preferSchemaOverJson:off
+    try: () => JSON.parse(raw) as unknown,
+    catch: (): DecodeResult<Input> => ({ _tag: "parseError" }),
+  }).pipe(
+    Effect.flatMap((parsed) =>
+      Effect.tryPromise({
+        try: () => Promise.resolve(tool.inputSchema["~standard"].validate(parsed)),
+        catch: (): DecodeResult<Input> => ({ _tag: "invalid", issues: VALIDATION_THREW }),
+      }).pipe(
+        Effect.map(
+          (result): DecodeResult<Input> =>
+            result.issues !== undefined
+              ? { _tag: "invalid", issues: result.issues }
+              : { _tag: "ok", input: result.value },
+        ),
+      ),
+    ),
+    Effect.catch((captured: DecodeResult<Input>) => Effect.succeed(captured)),
+  )
+}
 
 /**
  * Decode and validate a function_call's JSON `arguments` against the tool's
@@ -291,28 +396,26 @@ export const decodeArgs = <Input>(
   tool: DecodableTool<Input>,
   call: ToolCall,
 ): Effect.Effect<Input, ToolError | ToolValidationError> =>
-  Effect.gen(function* () {
-    const parsed = yield* Effect.try({
-      // inputSchema validates through Standard Schema, not Effect Schema, so its
-      // JSON codecs don't apply; the parse is separate to keep ToolError (bad
-      // JSON) distinct from ToolValidationError (bad shape).
-      // @effect-diagnostics-next-line effect/preferSchemaOverJson:off
-      try: () => JSON.parse(call.arguments) as unknown,
-      catch: toToolError(call, tool.name, "Failed to parse JSON arguments"),
-    })
-
-    const result = yield* Effect.promise(() =>
-      Promise.resolve(tool.inputSchema["~standard"].validate(parsed)),
-    )
-    if (result.issues !== undefined) {
-      return yield* new ToolValidationError({
-        call_id: call.call_id,
-        tool: tool.name,
-        issues: result.issues,
-      })
-    }
-    return result.value
-  })
+  decodeCallInput(tool, call).pipe(
+    Effect.flatMap(
+      Match.type<DecodeResult<Input>>().pipe(
+        Match.tag("ok", ({ input }) => Effect.succeed(input)),
+        Match.tag("parseError", () =>
+          Effect.fail(
+            new ToolError({
+              call_id: call.call_id,
+              tool: tool.name,
+              message: "Failed to parse JSON arguments",
+            }),
+          ),
+        ),
+        Match.tag("invalid", ({ issues }) =>
+          Effect.fail(new ToolValidationError({ call_id: call.call_id, tool: tool.name, issues })),
+        ),
+        Match.exhaustive,
+      ),
+    ),
+  )
 
 /**
  * Decode and validate the JSON arguments of a function_call against the
@@ -320,15 +423,11 @@ export const decodeArgs = <Input>(
  * function_call_output item. Single-shot: intermediate events emitted by
  * `run` are discarded (use `Toolkit.run` to stream them).
  */
-export const execute = <Name extends string, Input, Event, Output, R>(
-  tool: Tool<Name, Input, Event, Output, R>,
+export const execute = <Name extends string, Input, Event, Output, E, R>(
+  tool: Tool<Name, Input, Event, Output, E, R>,
   call: ToolCall,
-): Effect.Effect<ToolCallOutput, ToolError | ToolValidationError, R> =>
+): Effect.Effect<ToolCallOutput, E | ToolError | ToolValidationError, R> =>
   decodeArgs(tool, call).pipe(
-    Effect.flatMap((input) =>
-      tool
-        .run(input, () => Effect.void)
-        .pipe(Effect.mapError(toToolError(call, tool.name, "Tool execution failed"))),
-    ),
-    Effect.map((output) => toolCallOutput(call.call_id, JSON.stringify(output))),
+    Effect.flatMap((input) => tool.run(input, () => Effect.void)),
+    Effect.map((output) => toolCallOutput(call.call_id, serializeValue(output))),
   )

package/src/tool/ToolEvent.ts

@@ -7,6 +7,11 @@
  *
  * 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`.
  */
 import { Data } from "effect"
 import type { ToolResult } from "./ToolResult.js"

package/src/tool/ToolResult.ts

@@ -95,14 +95,20 @@ export const validationError = (call: ToolCall, reason?: string): ToolResult =>
 // Wire conversion - the one place structured → string happens.
 // ---------------------------------------------------------------------------
 
+/**
+ * Serialize a success value for the wire. A `string` passes through raw
+ * (models read plain text best; JSON.stringify would quote and escape it);
+ * `undefined` becomes `"null"`; anything else is JSON.
+ */
+export const serializeValue = (value: unknown): string =>
+  typeof value === "string" ? value : JSON.stringify(value ?? null)
+
+/** The one failure shape the model sees: `{"error":{"kind","message"}}`. */
+const failureBody = (kind: string, message?: string): string =>
+  JSON.stringify({ error: message !== undefined ? { kind, message } : { kind } })
+
 export const toToolCallOutput = (r: ToolResult): ToolCallOutput =>
   ToolResult.$match(r, {
-    Ok: (v) => toolCallOutput(v.call_id, JSON.stringify(v.value)),
-    Failure: (f) =>
-      toolCallOutput(
-        f.call_id,
-        JSON.stringify(
-          f.reason !== undefined ? { kind: f.kind, reason: f.reason } : { kind: f.kind },
-        ),
-      ),
+    Ok: (v) => toolCallOutput(v.call_id, serializeValue(v.value)),
+    Failure: (f) => toolCallOutput(f.call_id, failureBody(f.kind, f.reason)),
   })

package/src/tool/Toolkit.test.ts

@@ -1,11 +1,29 @@
 import { Context, Effect, Layer, pipe, Schema, Stream } from "effect"
 import { describe, expect, expectTypeOf, it } from "vitest"
+import * as AiError from "../domain/AiError.js"
 import type { ToolCall } from "../domain/Items.js"
-import { isOutput } from "./ToolEvent.js"
-import { isOk } from "./ToolResult.js"
+import { type ToolEvent, isOutput, isProgress } from "./ToolEvent.js"
+import { isFailure, isOk, toToolCallOutput } from "./ToolResult.js"
 import * as Tool from "./Tool.js"
 import * as Toolkit from "./Toolkit.js"
 
+const Empty = Schema.Struct({})
+const toolCall = (name: string, id: string, args = "{}"): ToolCall => ({
+  type: "function_call",
+  call_id: id,
+  name,
+  arguments: args,
+})
+const runToArray = <T extends Toolkit.Toolkit>(
+  toolkit: T,
+  calls: ReadonlyArray<ToolCall>,
+  options?: Toolkit.ExecuteOptions,
+) =>
+  Toolkit.run(toolkit, calls, options).pipe(
+    Stream.runCollect,
+    Effect.map((events): ReadonlyArray<ToolEvent> => Array.from(events)),
+  )
+
 describe("Tool.toDescriptors", () => {
   const GetWeatherInput = Schema.Struct({ city: Schema.String })
 
@@ -299,3 +317,154 @@ describe("Toolkit.wrap - middleware", () => {
     expect(s?._tag === "Failure" && s.kind).toBe("non_local_tool")
   })
 })
+
+describe("Toolkit.run - executor outcomes", () => {
+  const plain = <N extends string>(name: N, out: unknown) =>
+    Tool.make({
+      name,
+      description: "",
+      inputSchema: Tool.fromEffectSchema(Empty),
+      run: () => Effect.succeed(out),
+    })
+
+  it("absorbs a bare string failure as a tool_failed result", async () => {
+    const t = Tool.make({
+      name: "t",
+      description: "",
+      inputSchema: Tool.fromEffectSchema(Empty),
+      run: () => Effect.fail("nope"),
+    })
+    const events = await Effect.runPromise(runToArray(Toolkit.make(t), [toolCall("t", "1")]))
+    const result = events.filter(isOutput)[0]?.result
+    expect(result).toMatchObject({ _tag: "Failure", kind: "tool_failed", reason: "nope" })
+  })
+
+  it("absorbs Tool.fail with a custom kind", async () => {
+    const t = Tool.make({
+      name: "t",
+      description: "",
+      inputSchema: Tool.fromEffectSchema(Empty),
+      run: () => Tool.fail("missing", { kind: "not_found" }),
+    })
+    const events = await Effect.runPromise(runToArray(Toolkit.make(t), [toolCall("t", "1")]))
+    const result = events.filter(isOutput)[0]?.result
+    expect(result).toMatchObject({ _tag: "Failure", kind: "not_found", reason: "missing" })
+  })
+
+  it("propagates a typed non-sentinel failure on the stream", async () => {
+    const t = Tool.make({
+      name: "t",
+      description: "",
+      inputSchema: Tool.fromEffectSchema(Empty),
+      run: () => Effect.fail(new AiError.RateLimited({ provider: "x", raw: null })),
+    })
+    const exit = await Effect.runPromiseExit(runToArray(Toolkit.make(t), [toolCall("t", "1")]))
+    expect(exit._tag).toBe("Failure")
+  })
+
+  it("dies on a defect instead of masking it as a result", async () => {
+    const t = Tool.make({
+      name: "t",
+      description: "",
+      inputSchema: Tool.fromEffectSchema(Empty),
+      run: () => Effect.die(new Error("boom")),
+    })
+    const exit = await Effect.runPromiseExit(runToArray(Toolkit.make(t), [toolCall("t", "1")]))
+    expect(exit._tag).toBe("Failure")
+  })
+
+  it("streams progress events strictly before the terminal output", async () => {
+    const t = Tool.make({
+      name: "t",
+      description: "",
+      inputSchema: Tool.fromEffectSchema(Empty),
+      run: (_input, emit) =>
+        emit("a").pipe(Effect.andThen(emit("b")), Effect.andThen(Effect.succeed("done"))),
+    })
+    const events = await Effect.runPromise(runToArray(Toolkit.make(t), [toolCall("t", "1")]))
+    expect(events.map((e) => e._tag)).toEqual(["Progress", "Progress", "Output"])
+    expect(events.filter(isProgress).map((p) => p.data)).toEqual(["a", "b"])
+  })
+
+  it("reports input validation failures as a result carrying the issue detail", async () => {
+    const t = Tool.make({
+      name: "t",
+      description: "",
+      inputSchema: Tool.fromEffectSchema(Schema.Struct({ x: Schema.Number })),
+      run: () => Effect.succeed(1),
+    })
+    const events = await Effect.runPromise(
+      runToArray(Toolkit.make(t), [toolCall("t", "1", '{"x":"nope"}')]),
+    )
+    const result = events.filter(isOutput)[0]?.result
+    expect(result).toMatchObject({ _tag: "Failure", kind: "input_validation_error" })
+    expect(result !== undefined && isFailure(result) && result.reason).toBeTruthy()
+  })
+
+  it("normalizes empty arguments to {} for a zero-arg tool", async () => {
+    const events = await Effect.runPromise(
+      runToArray(Toolkit.make(plain("t", "ok")), [toolCall("t", "1", "")]),
+    )
+    const result = events.filter(isOutput)[0]?.result
+    expect(result).toMatchObject({ _tag: "Ok", value: "ok" })
+  })
+
+  it("reports unparseable arguments as input_validation_error", async () => {
+    const events = await Effect.runPromise(
+      runToArray(Toolkit.make(plain("t", "ok")), [toolCall("t", "1", "not json")]),
+    )
+    const result = events.filter(isOutput)[0]?.result
+    expect(result).toMatchObject({ _tag: "Failure", kind: "input_validation_error" })
+  })
+
+  it("a call named constructor is unknown_tool, not non_local_tool", async () => {
+    const events = await Effect.runPromise(
+      runToArray(Toolkit.make(plain("t", "ok")), [toolCall("constructor", "1")]),
+    )
+    const result = events.filter(isOutput)[0]?.result
+    expect(result).toMatchObject({ _tag: "Failure", kind: "unknown_tool" })
+  })
+
+  it('serializes an undefined output as "null" on the wire', async () => {
+    const t = Tool.make({
+      name: "t",
+      description: "",
+      inputSchema: Tool.fromEffectSchema(Empty),
+      run: () => Effect.void,
+    })
+    const events = await Effect.runPromise(runToArray(Toolkit.make(t), [toolCall("t", "1")]))
+    const result = events.filter(isOutput)[0]?.result
+    expect(result !== undefined && toToolCallOutput(result).output).toBe("null")
+  })
+
+  it("preserves call order with concurrency 1", async () => {
+    const kit = Toolkit.make(plain("a", "A"), plain("b", "B"))
+    const events = await Effect.runPromise(
+      runToArray(kit, [toolCall("a", "a1"), toolCall("b", "b1")], { concurrency: 1 }),
+    )
+    expect(events.filter(isOutput).map((e) => e.result.call_id)).toEqual(["a1", "b1"])
+  })
+
+  it("type: run of a describeFailures toolkit has no stream error", () => {
+    const t = Tool.make({
+      name: "t",
+      description: "",
+      inputSchema: Tool.fromEffectSchema(Empty),
+      run: () => Effect.fail(new AiError.RateLimited({ provider: "x", raw: null })),
+    })
+    const kit = Toolkit.describeFailures(Toolkit.make(t), AiError.describe)
+    const stream = Toolkit.run(kit, [])
+    expectTypeOf(stream).toEqualTypeOf<Stream.Stream<ToolEvent, never, never>>()
+  })
+
+  it("type: run of a typed toolkit propagates the tool's E", () => {
+    const t = Tool.make({
+      name: "t",
+      description: "",
+      inputSchema: Tool.fromEffectSchema(Empty),
+      run: () => Effect.fail(new AiError.RateLimited({ provider: "x", raw: null })),
+    })
+    const stream = Toolkit.run(Toolkit.make(t), [])
+    expectTypeOf(stream).toEqualTypeOf<Stream.Stream<ToolEvent, AiError.RateLimited, never>>()
+  })
+})