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

package/src/tool/Tool.ts

@@ -1,8 +1,6 @@
 import type { StandardJSONSchemaV1, StandardSchemaV1 } from "@standard-schema/spec"
-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"
+import { Effect, Function, Match, Schema, Stream } from "effect"
+import type { ToolCall } from "../domain/Items.js"
 
 export class ToolError extends Schema.TaggedError<ToolError>("@betalyra/effect-uai/ToolError")(
   "ToolError",
@@ -16,20 +14,14 @@ export class ToolError extends Schema.TaggedError<ToolError>("@betalyra/effect-u
 
 /**
  * One Standard Schema validation issue, carried on `ToolValidationError`.
- * Mirrors `StandardSchemaV1.Issue`; `path` is left as `unknown` elements
- * because Standard Schema path segments may be symbols or `{ key }` objects.
+ * `path` elements stay `unknown`: Standard Schema segments may be symbols or `{ key }`.
  */
 const ToolValidationIssue = Schema.Struct({
   message: Schema.String,
   path: Schema.optional(Schema.Array(Schema.Unknown)),
 })
 
-/**
- * The model's `arguments` for a call failed the tool's `inputSchema`. Distinct
- * from `ToolError` (malformed JSON, runtime crash) so callers can tell a
- * contract violation apart from a parse or execution failure, and so the
- * structured `issues` survive instead of being flattened into a message string.
- */
+/** A call's `arguments` failed the tool's `inputSchema` (from `decodeArgs`). */
 export class ToolValidationError extends Schema.TaggedError<ToolValidationError>(
   "@betalyra/effect-uai/ToolValidationError",
 )("ToolValidationError", {
@@ -39,71 +31,43 @@ export class ToolValidationError extends Schema.TaggedError<ToolValidationError>
 }) {}
 
 /**
- * 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.
+ * A ready-made model-visible error for one-off messages. It reaches the model
+ * only when listed in the tool's `failureSchema` (or via `Toolkit.describeFailures`).
  */
 export class ToolFailed extends Schema.TaggedError<ToolFailed>("@betalyra/effect-uai/ToolFailed")(
   "ToolFailed",
-  {
-    message: Schema.String,
-    kind: Schema.optional(Schema.String),
-  },
+  { message: 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 } : {}) }),
-  )
+/** `yield* Tool.fail("page not found")` inside a `run`. */
+export const fail = (message: string): Effect.Effect<never, ToolFailed> =>
+  Effect.fail(new ToolFailed({ message }))
+
+// ---------------------------------------------------------------------------
+// Input schemas
+// ---------------------------------------------------------------------------
 
 /**
- * Schemas accepted on `Tool.inputSchema`. Must implement both Standard
- * Schema validation and JSON Schema conversion (for rendering tool
- * descriptors to provider request bodies).
- *
- * Any Standard-Schema-compliant library that exposes both interfaces
- * works directly: Zod 4+, Valibot, ArkType, Effect Schema (after
- * `fromEffectSchema`), etc.
+ * Standard Schema with JSON Schema conversion (Zod 4+, Valibot, ArkType, or an
+ * Effect Schema via `fromEffectSchema`). Validates the model's arguments and
+ * renders the provider descriptor.
  */
 export type ToolInputSchema<Input = unknown> = StandardSchemaV1<unknown, Input> &
   StandardJSONSchemaV1<unknown, Input>
 
-/**
- * Convenience wrapper for Effect Schema users - adds both the
- * `validate` and `jsonSchema` extensions to a plain Effect Schema so it
- * can be used as a `Tool.inputSchema`.
- */
+/** What `inputSchema` accepts: an Effect Schema directly, or a `ToolInputSchema`. */
+export type InputSchema<Input> = Schema.Codec<Input, any, never, any> | ToolInputSchema<Input>
+
+/** Adds the Standard Schema and Standard JSON Schema interfaces to an Effect Schema. */
 export const fromEffectSchema = <S extends Schema.Codec<any, any, never, any>>(
   schema: S,
 ): S & ToolInputSchema<S["Type"]> =>
   Schema.toStandardJSONSchemaV1(Schema.toStandardSchemaV1(schema))
 
 /**
- * Use any schema library that implements both Standard Schema (validation)
- * and Standard JSON Schema (JSON Schema generation) as a `Tool.inputSchema`.
- * Covers Zod 4.2+, Valibot 1.2+, and ArkType 2.1.28+ in one helper.
- *
- * Effect Schema doesn't implement Standard JSON Schema natively — use
- * `fromEffectSchema` for those.
- *
- * The intersection constraint catches missing interfaces at compile time:
- * a Zod v3 schema (no Standard JSON Schema) produces a precise type error
- * pointing at the missing interface rather than a runtime surprise. The
- * helper itself is a thin type-narrowing identity — schemas that satisfy
- * both standards already structurally satisfy `ToolInputSchema`; the
- * helper makes the input type inference explicit at the call site.
+ * Types a schema that implements both Standard Schema and Standard JSON Schema
+ * (Zod 4.2+, Valibot 1.2+, ArkType 2.1.28+). A schema missing either half is a
+ * compile error here rather than a runtime surprise.
  */
 export const fromStandardSchema = <S extends StandardSchemaV1 & StandardJSONSchemaV1>(
   schema: S,
@@ -111,11 +75,8 @@ export const fromStandardSchema = <S extends StandardSchemaV1 & StandardJSONSche
   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.
+ * Input for a tool without arguments: renders `{ type: "object", properties: {} }`
+ * (an empty `Schema.Struct` renders an `anyOf` that strict providers reject).
  */
 export const noInput: ToolInputSchema<Record<string, never>> = {
   "~standard": {
@@ -129,287 +90,250 @@ export const noInput: ToolInputSchema<Record<string, never>> = {
   },
 }
 
-/**
- * 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
- * composes with `Stream.runForEach(emit)`.
- */
-export type Emit<Event> = (event: Event) => Effect.Effect<void>
+const resolveInputSchema = <Input>(schema: InputSchema<Input>): ToolInputSchema<Input> =>
+  Schema.isSchema(schema) ? fromEffectSchema(schema) : schema
 
-/**
- * A model-visible tool with a local `Effect` executor. `run` computes the
- * model-facing `Output`; emitting progress is a side channel via `emit`. A
- * plain tool never calls `emit` (its `Event` is irrelevant); a streaming tool
- * emits intermediate `Event`s that flow to the consumer as
- * `ToolEvent.Progress` in real time.
- *
- * This is one of four tool *kinds*, discriminated by `_tag`. The other three
- * (`ProviderTool`, `SignalTool`, `InteractionTool`) are model-visible but have
- * 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, E = unknown, R = never> = {
-  readonly _tag: "LocalTool"
+// ---------------------------------------------------------------------------
+// Tool kinds
+// ---------------------------------------------------------------------------
+
+/** One result (`Effect`) or partial results whose last element is the result (`Stream`). */
+export type Run<Input, Output, E, R> = (
+  input: Input,
+) => Effect.Effect<Output, E, R> | Stream.Stream<Output, E, R>
+
+/** Whether `run` returned a `Stream` (values as partials) rather than an `Effect` (one value). */
+export const isStreamed = <A, E, R>(
+  out: Effect.Effect<A, E, R> | Stream.Stream<A, E, R>,
+): out is Stream.Stream<A, E, R> => Stream.isStream(out)
+
+/** An `Effect` is a one-element stream. */
+export const toStream = <A, E, R>(
+  out: Effect.Effect<A, E, R> | Stream.Stream<A, E, R>,
+): Stream.Stream<A, E, R> => (Effect.isEffect(out) ? Stream.fromEffect(out) : out)
+
+type Described<Name extends string, Input, Output, Failure> = {
   readonly name: Name
   readonly description: string
   readonly inputSchema: ToolInputSchema<Input>
-  readonly run: (input: Input, emit: Emit<Event>) => Effect.Effect<Output, E, R>
+  /** Checks every value and encodes it for history and the UI. A rejected value is `OutputInvalid`. */
+  readonly outputSchema?: Schema.Codec<Output, any>
   /**
-   * Bound on this tool's emit queue. Unbounded when omitted. Per-tool because
-   * backpressure depends on how a given tool emits, unlike `concurrency`
-   * (cross-tool, on `Toolkit.run`'s options).
-   */
-  readonly emitBufferSize?: number
-  /**
-   * Whether the provider should render this tool with its strict-mode
-   * flag (OpenAI's `strict: true`, etc). Default: true. The framework
-   * never rewrites the schema; if the rendered JSON Schema isn't
-   * compatible, the provider returns an error.
+   * Every error a call may end with that the model sees: errors `run` raises and
+   * errors the app closes calls with (`ToolDecision.Denied`, see `Toolkit.close`).
    */
+  readonly failureSchema?: Schema.Codec<Failure, any>
+  /** Render with the provider's strict-mode flag. Default: true. */
   readonly strict?: boolean
 }
 
 /**
- * A provider-hosted tool: visible to the model and executed by the *provider*
- * (native web search, code execution, RAG grounding), never by this process.
- * It has no local `run`; `provider`/`config` tell the provider adapter how to
- * render it. Passing it to `Toolkit.run` yields a `non_local_tool` result.
+ * A model-visible tool that `Toolkit.run` executes: errors matching
+ * `failureSchema` reach the model, any other error fails the stream.
  */
-export type ProviderTool<Name extends string, Input, Provider extends string, Config> = {
-  readonly _tag: "ProviderTool"
-  readonly name: Name
-  readonly description: string
-  readonly inputSchema: ToolInputSchema<Input>
-  readonly provider: Provider
-  readonly config: Config
-  readonly strict?: boolean
+export type Tool<
+  Name extends string,
+  Input,
+  Output,
+  Failure = never,
+  E = never,
+  R = never,
+> = Described<Name, Input, Output, Failure> & {
+  readonly _tag: "LocalTool"
+  readonly run: Run<Input, Output, E, R>
 }
 
 /**
- * A typed request for the agent loop to change control flow (escalate, pause,
- * schedule, hand off). Model-visible and decodable (`decodeArgs`) but never
- * locally executed — the loop intercepts the call in `onTurnComplete` and acts
- * on it, so there is no fake `run`. `Toolkit.run` reports it as `non_local_tool`.
+ * A model-visible tool without `run`: the app handles its calls. A signal to
+ * the loop (`escalate`), or a call answered elsewhere (`ask_user`, typed by
+ * `outputSchema`). `Tool.withRun` turns it into a `Tool`.
  */
-export type SignalTool<Name extends string, Input> = {
-  readonly _tag: "SignalTool"
-  readonly name: Name
-  readonly description: string
-  readonly inputSchema: ToolInputSchema<Input>
+export type Declared<Name extends string, Input, Output = never, Failure = never> = Described<
+  Name,
+  Input,
+  Output,
+  Failure
+> & {
+  readonly _tag: "DeclaredTool"
 }
 
 /**
- * A typed request for an external actor (user, channel, frontend) to respond
- * before the loop resumes. Like `SignalTool` it is decode-only, but its
- * lifecycle differs: the loop usually stops/pauses and resumes later by
- * appending a `function_call_output` once the actor replies.
+ * A provider-hosted tool (native web search, code execution, grounding), executed
+ * by the provider. `provider` / `config` drive the adapter's rendering.
  */
-export type InteractionTool<Name extends string, Input> = {
-  readonly _tag: "InteractionTool"
+export type ProviderTool<Name extends string, Input, Provider extends string, Config> = {
+  readonly _tag: "ProviderTool"
   readonly name: Name
   readonly description: string
   readonly inputSchema: ToolInputSchema<Input>
+  readonly provider: Provider
+  readonly config: Config
+  readonly strict?: boolean
 }
 
-/** A local (executable) tool of any shape. Readability alias. */
 export type AnyLocalTool<E = any, R = any> = Tool<string, any, any, any, E, R>
 
-/** Any of the four model-visible tool kinds. */
+export type AnyDeclared = Declared<string, any, any, any>
+
+/** A tool with schemas the app sees: `Tool` or `Declared`. */
+export type AnyDescribed = AnyLocalTool | AnyDeclared
+
 export type AnyTool<E = any, R = any> =
-  | Tool<string, any, any, any, E, R>
+  | AnyLocalTool<E, R>
+  | AnyDeclared
   | ProviderTool<string, any, string, any>
-  | SignalTool<string, any>
-  | InteractionTool<string, any>
 
-/** A model-visible tool that carries a decodable input schema (every kind). */
+/** Any tool kind with a decodable input schema. */
 export type DecodableTool<Input> = {
   readonly name: string
   readonly inputSchema: ToolInputSchema<Input>
 }
 
-/** Extract the `R` of a local tool; non-local kinds contribute `never`. */
-export type ToolR<T> = T extends Tool<string, any, any, any, any, infer R> ? R : never
+type DescribedTag = { readonly _tag: "LocalTool" | "DeclaredTool" }
 
-/** Extract the `E` of a local tool; non-local kinds contribute `never`. */
+export type ToolOutput<T> = T extends DescribedTag & Described<string, any, infer O, any>
+  ? O
+  : never
+export type ToolFailure<T> = T extends DescribedTag & Described<string, any, any, infer F>
+  ? F
+  : never
 export type ToolE<T> = T extends Tool<string, any, any, any, infer E, any> ? E : never
+export type ToolR<T> = T extends Tool<string, any, any, any, any, infer R> ? R : never
 
-/**
- * Provider-agnostic tool descriptor. Each provider maps `inputSchema`
- * to its own wire field (OpenAI → `parameters`, Anthropic →
- * `input_schema`). Built from a `Tool` by `Tool.toDescriptors`.
- */
-export type ToolDescriptor = {
-  readonly name: string
+/** The errors a tool did not declare: these fail `Toolkit.run`'s stream. */
+export type ToolUnhandled<T> =
+  T extends Tool<string, any, any, infer F, infer E, any> ? Exclude<E, F> : never
+
+type Spec<Name extends string, Input, Failure, FailureEncoded> = {
+  readonly name: Name
   readonly description: string
-  readonly inputSchema: Record<string, unknown>
+  readonly inputSchema: InputSchema<Input>
+  readonly failureSchema?: Schema.Codec<Failure, FailureEncoded>
   readonly strict?: boolean
 }
 
-const resolveInputSchema = (
-  schema: ToolInputSchema<any> | Schema.Codec<any, any, never, any>,
-): ToolInputSchema<any> =>
-  Schema.isSchema(schema)
-    ? fromEffectSchema(schema as Schema.Codec<any, any, never, any>)
-    : (schema as ToolInputSchema<any>)
-
-/** A model-visible tool with a local `Effect` executor. */
-export const make: {
-  <
-    Name extends string,
-    S extends Schema.Codec<any, any, never, any>,
-    Event,
-    Output,
-    E = never,
-    R = never,
-  >(
-    spec: Omit<Tool<Name, S["Type"], Event, Output, E, R>, "_tag" | "inputSchema"> & {
-      readonly inputSchema: S
-    },
-  ): Tool<Name, S["Type"], Event, Output, E, R>
-  <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>
-} = (
-  spec: Omit<AnyLocalTool, "_tag" | "inputSchema"> & {
-    readonly inputSchema: ToolInputSchema<any> | Schema.Codec<any, any, never, any>
-  },
-): AnyLocalTool => ({
-  _tag: "LocalTool",
-  ...spec,
-  inputSchema: resolveInputSchema(spec.inputSchema),
-})
-
 /**
- * A provider-hosted tool (native web search, code execution, RAG grounding).
- * No local executor — `provider`/`config` drive the provider adapter's
- * rendering. The model sees it; `Toolkit.run` reports it as `non_local_tool`.
+ * A tool `Toolkit.run` executes. `outputSchema` says what `run` returns and its
+ * encoded side must be JSON. `Content.Value` is the explicit "anything": text,
+ * JSON or media.
  */
-export const provider: {
-  <
-    Name extends string,
-    S extends Schema.Codec<any, any, never, any>,
-    Provider extends string,
-    Config,
-  >(
-    spec: Omit<ProviderTool<Name, S["Type"], Provider, Config>, "_tag" | "inputSchema"> & {
-      readonly inputSchema: S
-    },
-  ): ProviderTool<Name, S["Type"], Provider, Config>
-  <Name extends string, Input, Provider extends string, Config>(
-    spec: Omit<ProviderTool<Name, Input, Provider, Config>, "_tag">,
-  ): ProviderTool<Name, Input, Provider, Config>
-} = (
-  spec: Omit<ProviderTool<string, any, string, any>, "_tag" | "inputSchema"> & {
-    readonly inputSchema: ToolInputSchema<any> | Schema.Codec<any, any, never, any>
+export const make = <
+  const Name extends string,
+  Input,
+  Output,
+  Encoded extends Schema.Json,
+  Failure = never,
+  FailureEncoded extends Schema.Json = never,
+  E = never,
+  R = never,
+>(
+  spec: Spec<Name, Input, Failure, FailureEncoded> & {
+    readonly outputSchema: Schema.Codec<Output, Encoded>
+    readonly run: Run<Input, Output, E, R>
   },
-): ProviderTool<string, any, string, any> => ({
-  _tag: "ProviderTool",
+): Tool<Name, Input, Output, Failure, E, R> => ({
   ...spec,
+  _tag: "LocalTool",
   inputSchema: resolveInputSchema(spec.inputSchema),
 })
 
 /**
- * A typed control-flow signal to the agent loop (escalate, pause, schedule,
- * hand off). Decode-only: the loop interprets the call rather than executing a
- * handler, so there is no `run`.
+ * A tool without `run`: the app handles its calls. A signal to the loop (no
+ * `outputSchema`), or a call answered elsewhere (typed by `outputSchema`).
  */
-export const signal: {
-  <Name extends string, S extends Schema.Codec<any, any, never, any>>(
-    spec: Omit<SignalTool<Name, S["Type"]>, "_tag" | "inputSchema"> & {
-      readonly inputSchema: S
-    },
-  ): SignalTool<Name, S["Type"]>
-  <Name extends string, Input>(spec: Omit<SignalTool<Name, Input>, "_tag">): SignalTool<Name, Input>
-} = (
-  spec: Omit<SignalTool<string, any>, "_tag" | "inputSchema"> & {
-    readonly inputSchema: ToolInputSchema<any> | Schema.Codec<any, any, never, any>
+export const declare = <
+  const Name extends string,
+  Input,
+  Output = never,
+  Encoded extends Schema.Json = never,
+  Failure = never,
+  FailureEncoded extends Schema.Json = never,
+>(
+  spec: Spec<Name, Input, Failure, FailureEncoded> & {
+    readonly outputSchema?: Schema.Codec<Output, Encoded>
   },
-): SignalTool<string, any> => ({
-  _tag: "SignalTool",
+): Declared<Name, Input, Output, Failure> => ({
   ...spec,
+  _tag: "DeclaredTool",
   inputSchema: resolveInputSchema(spec.inputSchema),
 })
 
-/**
- * A typed request for an external actor to respond before the loop resumes
- * (frontend, Telegram, CLI prompt). Decode-only; the loop stops/pauses and
- * resumes by appending the actor's `function_call_output`.
- */
-export const interaction: {
-  <Name extends string, S extends Schema.Codec<any, any, never, any>>(
-    spec: Omit<InteractionTool<Name, S["Type"]>, "_tag" | "inputSchema"> & {
-      readonly inputSchema: S
-    },
-  ): InteractionTool<Name, S["Type"]>
-  <Name extends string, Input>(
-    spec: Omit<InteractionTool<Name, Input>, "_tag">,
-  ): InteractionTool<Name, Input>
-} = (
-  spec: Omit<InteractionTool<string, any>, "_tag" | "inputSchema"> & {
-    readonly inputSchema: ToolInputSchema<any> | Schema.Codec<any, any, never, any>
+/** A provider-hosted tool. */
+export const provider = <const Name extends string, Input, Provider extends string, Config>(
+  spec: Omit<ProviderTool<Name, Input, Provider, Config>, "_tag" | "inputSchema"> & {
+    readonly inputSchema: InputSchema<Input>
   },
-): InteractionTool<string, any> => ({
-  _tag: "InteractionTool",
+): ProviderTool<Name, Input, Provider, Config> => ({
+  _tag: "ProviderTool",
   ...spec,
   inputSchema: resolveInputSchema(spec.inputSchema),
 })
 
-/**
- * Return a copy of a tool under a new `name`. Useful for resolving a name
- * clash before combining tools into one `Toolkit`. Literal-preserving, so the
- * renamed tool keys the toolkit record under the new name statically.
- */
+/** A copy of a tool under a new `name`, e.g. to resolve a clash before `Toolkit.compose`. */
 export const withName = <N extends string, T extends AnyTool>(
   tool: T,
   name: N,
 ): Omit<T, "name"> & { readonly name: N } => ({ ...tool, name })
 
 /**
- * Replace a local tool's `run`, keeping its model-facing definition (name,
- * description, schema, `_tag`) identical. The new `run`'s `input` is typed from
- * the original tool, so override/mock need no annotation:
- *
- *   const safe = { ...toolkit, send_email: Tool.withRun(toolkit.send_email,
- *     ({ to }) => Effect.succeed({ status: "dry-run", to })) }
- *
- * Descriptors stay identical to production, so a mocked toolkit can't drift
- * from the contract the model sees.
+ * Give a tool a `run`, keeping everything else (name, description, schemas):
+ * implement a declared tool (a spec shared with the browser), or mock a tool.
+ * The new `run` returns the same output type.
  */
-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 })
+export const withRun = <Name extends string, Input, Output, Failure, E2 = never, R2 = never>(
+  tool: Tool<Name, Input, Output, Failure, any, any> | Declared<Name, Input, Output, Failure>,
+  run: Run<Input, Output, E2, R2>,
+): Tool<Name, Input, Output, Failure, E2, R2> => ({ ...tool, _tag: "LocalTool", run })
+
+/** The same kind of tool, with more failures. */
+export type WithFailures<T, F2> =
+  T extends Tool<infer N, infer I, infer O, infer F, infer E, infer R>
+    ? Tool<N, I, O, F | F2, E, R>
+    : T extends Declared<infer N, infer I, infer O, infer F>
+      ? Declared<N, I, O, F | F2>
+      : never
+
+/**
+ * Add errors a call of this tool may end with, e.g. the app's `ToolDecision.Denied`
+ * for a tool that needs approval. Its `run` need not raise them; the app closes
+ * calls with them (`Toolkit.close`).
+ */
+export const withFailures: {
+  <F2, F2Encoded extends Schema.Json>(
+    failures: Schema.Codec<F2, F2Encoded>,
+  ): <T extends AnyDescribed>(tool: T) => WithFailures<T, F2>
+  <T extends AnyDescribed, F2, F2Encoded extends Schema.Json>(
+    tool: T,
+    failures: Schema.Codec<F2, F2Encoded>,
+  ): WithFailures<T, F2>
+} = Function.dual(2, (tool: AnyDescribed, failures: Schema.Codec<unknown, any>): AnyDescribed => ({
+  ...tool,
+  failureSchema:
+    tool.failureSchema === undefined ? failures : Schema.Union([tool.failureSchema, failures]),
+}))
+
+// ---------------------------------------------------------------------------
+// Descriptors
+// ---------------------------------------------------------------------------
+
+/** Provider-agnostic descriptor; each provider maps `inputSchema` to its own field. */
+export type ToolDescriptor = {
+  readonly name: string
+  readonly description: string
+  readonly inputSchema: Record<string, unknown>
+  readonly strict?: boolean
+}
 
-/** True for provider-hosted tools — the kind a provider renders natively. */
 export const isProviderTool = (tool: AnyTool): tool is ProviderTool<string, any, string, any> =>
   tool._tag === "ProviderTool"
 
-/**
- * The `ProviderTool`s in a toolkit, for a provider adapter to render as its
- * native hosted-tool entries (web search, code execution, grounding). The other
- * kinds render as function declarations via `descriptorsOf`.
- */
+/** The provider-hosted tools in a toolkit, for an adapter to render natively. */
 export const providerToolsOf = (
   toolkit?: Readonly<Record<string, AnyTool>>,
 ): ReadonlyArray<ProviderTool<string, any, string, any>> =>
   toolkit === undefined ? [] : Object.values(toolkit).filter(isProviderTool)
 
-/**
- * Render tools to provider-agnostic descriptors. `ProviderTool`s are excluded:
- * they are provider-hosted and must never leak into the function-declaration
- * list — each adapter renders them natively via `providerToolsOf`. Every other
- * kind is model-visible as a declaration.
- */
+/** Function descriptors for every tool except provider-hosted ones. */
 export const toDescriptors = (tools: ReadonlyArray<AnyTool>): ReadonlyArray<ToolDescriptor> =>
   tools
     .filter((tool) => !isProviderTool(tool))
@@ -417,30 +341,22 @@ export const toDescriptors = (tools: ReadonlyArray<AnyTool>): ReadonlyArray<Tool
       const inputSchema = tool.inputSchema["~standard"].jsonSchema.input({
         target: "draft-2020-12",
       })
-      // `strict` only exists on local/provider kinds; signals/interactions omit it.
       const strict = "strict" in tool ? tool.strict : undefined
       return strict !== undefined
         ? { name: tool.name, description: tool.description, inputSchema, strict }
         : { name: tool.name, description: tool.description, inputSchema }
     })
 
-/**
- * Render a `Toolkit` (a name-indexed record of tools) to descriptors, treating
- * an absent toolkit as no tools. The normalization point the `LanguageModel`
- * boundary uses so a request can carry the toolkit itself instead of a
- * pre-rendered descriptor array. Lives here (not on `Toolkit`) to keep providers
- * free of a dependency on the toolkit module — it only needs the tool values.
- */
+/** `toDescriptors` over a toolkit record; an absent toolkit has none. */
 export const descriptorsOf = (
   toolkit?: Readonly<Record<string, AnyTool>>,
 ): ReadonlyArray<ToolDescriptor> =>
   toolkit === undefined ? [] : toDescriptors(Object.values(toolkit))
 
-/**
- * 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.
- */
+// ---------------------------------------------------------------------------
+// Decoding arguments
+// ---------------------------------------------------------------------------
+
 export type DecodeResult<Input> =
   | { readonly _tag: "ok"; readonly input: Input }
   | { readonly _tag: "parseError" }
@@ -451,9 +367,8 @@ const VALIDATION_THREW: ReadonlyArray<StandardSchemaV1.Issue> = [
 ]
 
 /**
- * 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.
+ * Parse and validate a call's `arguments`, as data. Empty arguments read as `{}`
+ * (some models send `""` for tools without arguments). Never fails.
  */
 export const decodeCallInput = <Input>(
   tool: DecodableTool<Input>,
@@ -461,7 +376,7 @@ export const decodeCallInput = <Input>(
 ): Effect.Effect<DecodeResult<Input>> => {
   const raw = call.arguments.trim() === "" ? "{}" : call.arguments
   return Effect.try({
-    // @effect-diagnostics-next-line effect/preferSchemaOverJson:off
+    // @effect-diagnostics-next-linepreferSchemaOverJson:off
     try: () => JSON.parse(raw) as unknown,
     catch: (): DecodeResult<Input> => ({ _tag: "parseError" }),
   }).pipe(
@@ -482,13 +397,8 @@ export const decodeCallInput = <Input>(
 }
 
 /**
- * Decode and validate a function_call's JSON `arguments` against the tool's
- * own `inputSchema`, yielding the typed input. The decode-only half of
- * `execute` - reach for it when you intercept a call to translate it into a
- * control-flow decision rather than running the tool's `run`.
- *
- * Malformed JSON fails with `ToolError`; a parsed body that violates
- * `inputSchema` fails with `ToolValidationError` carrying the issues.
+ * A call's typed input, e.g. for a tool without `run` the loop handles itself.
+ * Bad JSON fails with `ToolError`, a schema violation with `ToolValidationError`.
  */
 export const decodeArgs = <Input>(
   tool: DecodableTool<Input>,
@@ -514,18 +424,3 @@ export const decodeArgs = <Input>(
       ),
     ),
   )
-
-/**
- * Decode and validate the JSON arguments of a function_call against the
- * tool's input schema, run the tool, and serialize the output into a
- * 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, E, R>(
-  tool: Tool<Name, Input, Event, Output, E, R>,
-  call: ToolCall,
-): Effect.Effect<ToolCallOutput, E | ToolError | ToolValidationError, R> =>
-  decodeArgs(tool, call).pipe(
-    Effect.flatMap((input) => tool.run(input, () => Effect.void)),
-    Effect.map((output) => toolCallOutput(call.call_id, serializeValue(output))),
-  )