@effect-uai/core 0.9.0 → 0.10.0

package/src/tool/Toolkit.ts

@@ -1,3 +1,4 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec"
 import {
   Array as Arr,
   Cause,
@@ -10,7 +11,6 @@ import {
   Queue,
   Record,
   Ref,
-  Schema,
   Stream,
 } from "effect"
 import * as Loop from "../loop/Loop.js"
@@ -19,18 +19,21 @@ import { appendToHistory, type Turn } from "../domain/Turn.js"
 import {
   type AnyLocalTool,
   type AnyTool,
+  type DecodeResult,
+  decodeCallInput,
   type Emit,
   type InteractionTool,
   type ProviderTool,
   type SignalTool,
   type Tool,
   type ToolDescriptor,
+  type ToolE,
+  ToolFailed,
   type ToolR,
   toDescriptors,
 } from "./Tool.js"
 import {
   ToolResult,
-  executionError,
   failed,
   nonLocalTool,
   toToolCallOutput,
@@ -93,6 +96,15 @@ export const descriptors = (toolkit: Toolkit): ReadonlyArray<ToolDescriptor> =>
  */
 export type ToolkitR<T extends Toolkit> = ToolMap extends T ? never : ToolR<T[keyof T]>
 
+/**
+ * Union of every tool's `E` error type in a toolkit. `Toolkit.run` reports
+ * `Exclude<ToolkitE<T>, string | ToolFailed>` on its stream: the sentinel
+ * failures are absorbed into results, everything else propagates typed. The
+ * same `ToolMap extends T` guard as `ToolkitR` keeps a wide toolkit at
+ * `never` rather than `any`.
+ */
+export type ToolkitE<T extends Toolkit> = ToolMap extends T ? never : ToolE<T[keyof T]>
+
 // ---------------------------------------------------------------------------
 // Uniqueness & composition. `make` rejects duplicate literal names at compile
 // time; `compose` rejects cross-source collisions — at compile time when the
@@ -257,45 +269,99 @@ export const compose = <const Kits extends ReadonlyArray<Toolkit>>(
 // widening every tool's type.
 // ---------------------------------------------------------------------------
 
-type Handler<Input, Event, Output, R> = (
+type Handler<Input, Event, Output, E, R> = (
   input: Input,
   emit: Emit<Event>,
-) => Effect.Effect<Output, unknown, R>
+) => Effect.Effect<Output, E, R>
 
-export type Middleware<R2 = never> = <Input, Event, Output, R>(
-  run: Handler<Input, Event, Output, R>,
+/**
+ * A `run` transform, tracking an added requirement `R2` and optional added
+ * error `E2`. The tool's own `E` is preserved; `describeFailures` is the
+ * combinator that *replaces* it (mapping every error to `string`).
+ */
+export type Middleware<R2 = never, E2 = never> = <Input, Event, Output, E, R>(
+  run: Handler<Input, Event, Output, E, R>,
   name: string,
-) => Handler<Input, Event, Output, R | R2>
+) => Handler<Input, Event, Output, E | E2, R | R2>
 
-type WrapTool<T extends AnyTool, R2> =
-  T extends Tool<infer N, infer I, infer Ev, infer O, infer R> ? Tool<N, I, Ev, O, R | R2> : T
+type WrapTool<T extends AnyTool, R2, E2> =
+  T extends Tool<infer N, infer I, infer Ev, infer O, infer E, infer R>
+    ? Tool<N, I, Ev, O, E | E2, R | R2>
+    : T
 
-type WrapToolkit<T extends ToolMap, R2> = {
-  readonly [K in keyof T]: T[K] extends AnyTool ? WrapTool<T[K], R2> : T[K]
+type WrapToolkit<T extends ToolMap, R2, E2> = {
+  readonly [K in keyof T]: T[K] extends AnyTool ? WrapTool<T[K], R2, E2> : T[K]
 }
 
 /**
  * Wrap every local tool's `run` with a middleware, preserving each tool's
  * `Input`/`Output` and unioning the middleware's requirement `R2` into the
  * toolkit's `ToolkitR`. Non-local kinds pass through unchanged. Stack with
- * `pipe`:
+ * `pipe` - inner-first, so the last `wrap` applied is the outermost and runs
+ * first:
  *
  *   const observed = pipe(toolkit, Toolkit.wrap(logging), Toolkit.wrap(authz))
- *   Toolkit.run(observed, calls) // R = ToolkitR<typeof toolkit> | <authz R>
+ *   Toolkit.run(observed, calls) // authz runs, then logging, then the tool
  *
- * A middleware that `Effect.fail`s surfaces as a `ToolResult.Failure` from the
- * executor like any run failure; use the `Approval` flow for a distinct
- * "denied" verdict.
+ * A middleware that fails with `string` / `ToolFailed` is absorbed by the
+ * executor into a `ToolResult.Failure`; any other error propagates typed. Use
+ * `describeFailures` for the total "everything to the model" case, or the
+ * `Approval` flow for a distinct "denied" verdict.
  */
 export const wrap: {
-  <R2>(middleware: Middleware<R2>): <T extends Toolkit>(toolkit: T) => WrapToolkit<T, R2>
-  <T extends Toolkit, R2>(toolkit: T, middleware: Middleware<R2>): WrapToolkit<T, R2>
+  <R2, E2>(
+    middleware: Middleware<R2, E2>,
+  ): <T extends Toolkit>(toolkit: T) => WrapToolkit<T, R2, E2>
+  <T extends Toolkit, R2, E2>(toolkit: T, middleware: Middleware<R2, E2>): WrapToolkit<T, R2, E2>
 } = Function.dual(
   2,
-  <T extends Toolkit, R2>(toolkit: T, middleware: Middleware<R2>): WrapToolkit<T, R2> =>
+  <T extends Toolkit, R2, E2>(toolkit: T, middleware: Middleware<R2, E2>): WrapToolkit<T, R2, E2> =>
     Record.map(toolkit, (tool) =>
       tool._tag === "LocalTool" ? { ...tool, run: middleware(tool.run, tool.name) } : tool,
-    ) as WrapToolkit<T, R2>,
+    ) as WrapToolkit<T, R2, E2>,
+)
+
+// ---------------------------------------------------------------------------
+// describeFailures: map every local tool's error to a model-visible string,
+// opting its failures into recovery. Group tools by recovery policy, wrap
+// each group, then compose.
+// ---------------------------------------------------------------------------
+
+type DescribeTool<T extends AnyTool> =
+  T extends Tool<infer N, infer I, infer Ev, infer O, any, infer R>
+    ? Tool<N, I, Ev, O, string, R>
+    : T
+
+type DescribeToolkit<T extends ToolMap> = {
+  readonly [K in keyof T]: T[K] extends AnyTool ? DescribeTool<T[K]> : T[K]
+}
+
+/**
+ * Map every local tool's error to a `string`, so `Toolkit.run` absorbs those
+ * failures into `ToolResult.Failure` the model reads and adapts to. Pairs
+ * with the domain `describe` helpers (`AiError.describe`,
+ * `BrowserError.describe`). Non-local kinds pass through.
+ *
+ *   const kit = yield* Toolkit.compose(
+ *     Toolkit.describeFailures(searchKit, AiError.describe),
+ *     browserToolkit(session), // failures stay typed
+ *   )
+ */
+export const describeFailures: {
+  <E>(describe: (e: E) => string): <T extends Toolkit>(toolkit: T) => DescribeToolkit<T>
+  <T extends Toolkit>(toolkit: T, describe: (e: ToolkitE<T>) => string): DescribeToolkit<T>
+} = Function.dual(
+  2,
+  <T extends Toolkit>(toolkit: T, describe: (e: any) => string): DescribeToolkit<T> =>
+    Record.map(toolkit, (tool) =>
+      tool._tag === "LocalTool"
+        ? {
+            ...tool,
+            run: (input: unknown, emit: Emit<unknown>) =>
+              (tool as AnyLocalTool).run(input, emit).pipe(Effect.mapError(describe)),
+          }
+        : tool,
+    ) as DescribeToolkit<T>,
 )
 
 // ---------------------------------------------------------------------------
@@ -307,17 +373,26 @@ export type ExecuteOptions = {
   readonly concurrency?: number | "unbounded"
 }
 
-/** Execute every provided call. Approval/rejection policy belongs upstream. */
+/**
+ * Execute every provided call. Approval/rejection policy belongs upstream.
+ *
+ * String and `ToolFailed` failures are absorbed into `ToolResult.Failure`
+ * (the model reads and adapts to them); every other tool error propagates
+ * typed on the stream, so `Exclude<ToolkitE<T>, string | ToolFailed>` is
+ * what a caller catches or lets end the run. If one call in a concurrent
+ * batch fails the stream, siblings may go unanswered: a loop that catches
+ * and continues must reconcile history first (`HistoryCheck.cancelAllPending`).
+ */
 export const run = <T extends Toolkit>(
   toolkit: T,
   calls: ReadonlyArray<ToolCall>,
   options?: ExecuteOptions,
-): Stream.Stream<ToolEvent, never, ToolkitR<T>> =>
+): Stream.Stream<ToolEvent, Exclude<ToolkitE<T>, string | ToolFailed>, ToolkitR<T>> =>
   Stream.fromIterable(calls).pipe(
     Stream.flatMap((call) => runOne(toolkit, call), {
       concurrency: options?.concurrency ?? "unbounded",
     }),
-  ) as Stream.Stream<ToolEvent, never, ToolkitR<T>>
+  ) as Stream.Stream<ToolEvent, Exclude<ToolkitE<T>, string | ToolFailed>, ToolkitR<T>>
 
 const okResult = (call: ToolCall, tool: string, value: unknown): ToolResult =>
   ToolResult.Ok({ call_id: call.call_id, tool, value })
@@ -325,8 +400,11 @@ const okResult = (call: ToolCall, tool: string, value: unknown): ToolResult =>
 const outputEvent = (result: ToolResult): Stream.Stream<ToolEvent, never, any> =>
   Stream.succeed(ToolEvent.Output({ result }))
 
-const runOne = (toolkit: ToolMap, call: ToolCall): Stream.Stream<ToolEvent, never, any> =>
-  Match.value(toolkit[call.name]).pipe(
+const runOne = (toolkit: ToolMap, call: ToolCall): Stream.Stream<ToolEvent, unknown, any> => {
+  // Own-property lookup: a hallucinated call named `constructor` / `toString`
+  // must not resolve to a prototype method.
+  const tool = Object.hasOwn(toolkit, call.name) ? toolkit[call.name] : undefined
+  return Match.value(tool).pipe(
     // No such tool. Graceful: emit a synthetic Failure so OTHER calls in this
     // turn still execute. LLMs hallucinate tool names; MCP tools come and go.
     Match.when(Match.undefined, () =>
@@ -338,23 +416,46 @@ const runOne = (toolkit: ToolMap, call: ToolCall): Stream.Stream<ToolEvent, neve
     // execution; reaching here means it didn't, so report it rather than crash.
     Match.orElse(() => outputEvent(nonLocalTool(call))),
   )
+}
 
-const parseJsonUnknown = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Unknown))
+const describeIssues = (issues: ReadonlyArray<StandardSchemaV1.Issue>): string =>
+  issues
+    .map((issue) => {
+      const path = (issue.path ?? [])
+        .map((seg) => (typeof seg === "object" && seg !== null ? String(seg.key) : String(seg)))
+        .join(".")
+      return path === "" ? issue.message : `${path}: ${issue.message}`
+    })
+    .join("; ")
+    .slice(0, 500)
+
+// A decode failure is the model's contract violation: report it as a result
+// (never a stream failure) so the model can correct its next call.
+const runTool = (tool: AnyLocalTool, call: ToolCall): Stream.Stream<ToolEvent, unknown, any> =>
+  Stream.unwrap(
+    decodeCallInput(tool, call).pipe(
+      Effect.map(
+        Match.type<DecodeResult<unknown>>().pipe(
+          Match.tag("parseError", () =>
+            outputEvent(validationError(call, "arguments are not valid JSON")),
+          ),
+          Match.tag("invalid", ({ issues }) =>
+            outputEvent(validationError(call, describeIssues(issues))),
+          ),
+          Match.tag("ok", ({ input }) => runValidated(tool, call, input)),
+          Match.exhaustive,
+        ),
+      ),
+    ),
+  )
 
-const runTool = (tool: AnyLocalTool, call: ToolCall): Stream.Stream<ToolEvent, never, any> =>
+const runValidated = (
+  tool: AnyLocalTool,
+  call: ToolCall,
+  input: unknown,
+): Stream.Stream<ToolEvent, unknown, any> =>
   Stream.unwrap(
     Effect.gen(function* () {
-      const parsed = yield* parseJsonUnknown(call.arguments).pipe(
-        Effect.mapError(() => "json_parse_error" as const),
-      )
-      const validated = yield* Effect.tryPromise({
-        try: () => Promise.resolve(tool.inputSchema["~standard"].validate(parsed)),
-        catch: () => "validation_threw" as const,
-      })
-      if (validated.issues !== undefined) {
-        return Stream.succeed<ToolEvent>(ToolEvent.Output({ result: validationError(call) }))
-      }
-
       // Per-call queue: `emit` offers events as `run` produces them; the
       // progress stream drains them in real time; `Queue.end` (in the
       // `ensuring`) flushes pending events then signals a clean end, which
@@ -363,7 +464,7 @@ const runTool = (tool: AnyLocalTool, call: ToolCall): Stream.Stream<ToolEvent, n
       const queue = yield* Queue.make<unknown, Cause.Done>({ capacity: tool.emitBufferSize })
       const emit = (event: unknown) => Effect.asVoid(Queue.offer(queue, event))
       const fiber = yield* tool
-        .run(validated.value, emit)
+        .run(input, emit)
         .pipe(Effect.ensuring(Queue.end(queue)), Effect.forkScoped)
 
       const progress = Stream.fromQueue(queue).pipe(
@@ -371,24 +472,38 @@ const runTool = (tool: AnyLocalTool, call: ToolCall): Stream.Stream<ToolEvent, n
       )
       const output = Stream.fromEffect(
         Fiber.join(fiber).pipe(
-          Effect.map((value) => ToolEvent.Output({ result: okResult(call, tool.name, value) })),
-          Effect.catchCause(() =>
-            Effect.succeed(
-              ToolEvent.Output({ result: executionError(call, "Tool execution failed") }),
-            ),
-          ),
+          Effect.matchCauseEffect({
+            onSuccess: (value: unknown) =>
+              Effect.succeed(ToolEvent.Output({ result: okResult(call, tool.name, value) })),
+            onFailure: (cause: Cause.Cause<unknown>) => routeCause(call, cause),
+          }),
         ),
       )
       return progress.pipe(Stream.concat(output))
     }),
-  ).pipe(
-    // Backstop for the input-parsing failures (`json_parse_error`,
-    // `validation_threw`) and any defect before the run fiber is forked.
-    Stream.catchCause(() =>
-      Stream.succeed(ToolEvent.Output({ result: executionError(call, "Tool execution failed") })),
-    ),
   )
 
+// A clean single string / ToolFailed failure is absorbed as a model-visible
+// result; interruption, defects, and typed non-sentinel errors propagate.
+const routeCause = (
+  call: ToolCall,
+  cause: Cause.Cause<unknown>,
+): Effect.Effect<ToolEvent, unknown> => {
+  const only = cause.reasons.length === 1 ? cause.reasons[0] : undefined
+  if (only !== undefined && Cause.isFailReason(only)) {
+    const error = only.error
+    if (typeof error === "string") {
+      return Effect.succeed(ToolEvent.Output({ result: failed(call, "tool_failed", error) }))
+    }
+    if (error instanceof ToolFailed) {
+      return Effect.succeed(
+        ToolEvent.Output({ result: failed(call, error.kind ?? "tool_failed", error.message) }),
+      )
+    }
+  }
+  return Effect.failCause(cause)
+}
+
 // ---------------------------------------------------------------------------
 // `continueWithResults` - bridge from a `Stream<ToolEvent>` to the loop's
 // emit shape. Drains the stream to the consumer in real-time, taps every
@@ -455,19 +570,17 @@ export const collectResults = <E, R>(
 export const continueWithResults: {
   <S>(
     build: (results: ReadonlyArray<ToolResult>) => S,
-  ): <R>(
-    stream: Stream.Stream<ToolEvent, never, R>,
-  ) => Stream.Stream<Loop.Step<ToolEvent, S>, never, R>
-  <S, R>(
-    stream: Stream.Stream<ToolEvent, never, R>,
+  ): <E, R>(stream: Stream.Stream<ToolEvent, E, R>) => Stream.Stream<Loop.Step<ToolEvent, S>, E, R>
+  <S, E, R>(
+    stream: Stream.Stream<ToolEvent, E, R>,
     build: (results: ReadonlyArray<ToolResult>) => S,
-  ): Stream.Stream<Loop.Step<ToolEvent, S>, never, R>
+  ): Stream.Stream<Loop.Step<ToolEvent, S>, E, R>
 } = Function.dual(
   2,
-  <S, R>(
-    stream: Stream.Stream<ToolEvent, never, R>,
+  <S, E, R>(
+    stream: Stream.Stream<ToolEvent, E, R>,
     build: (results: ReadonlyArray<ToolResult>) => S,
-  ): Stream.Stream<Loop.Step<ToolEvent, S>, never, R> =>
+  ): Stream.Stream<Loop.Step<ToolEvent, S>, E, R> =>
     Stream.unwrap(
       Effect.gen(function* () {
         const ref = yield* Ref.make<ReadonlyArray<ToolResult>>([])

package/src/web-read/WebRead.ts

@@ -0,0 +1,70 @@
+import { Context, type Duration, Effect } from "effect"
+import type * as AiError from "../domain/AiError.js"
+
+// ---------------------------------------------------------------------------
+// Format
+// ---------------------------------------------------------------------------
+
+/** Representation to return for a page. `markdown` is the default. */
+export type ReadFormat = "markdown" | "html"
+
+// ---------------------------------------------------------------------------
+// Request
+// ---------------------------------------------------------------------------
+
+/**
+ * Cross-provider read request: one URL in, clean content out. Provider-specific
+ * knobs live on the provider-typed request.
+ */
+export type CommonReadRequest = {
+  /** The page to read. */
+  readonly url: string
+  /** Output representation. Defaults to `markdown`. See {@link ReadFormat}. */
+  readonly format?: ReadFormat
+  /** Upper bound on time spent fetching the page. */
+  readonly timeout?: Duration.Duration
+}
+
+// ---------------------------------------------------------------------------
+// Response
+// ---------------------------------------------------------------------------
+
+/** One normalized read result. */
+export type ReadResponse = {
+  /** The URL that was read. */
+  readonly url: string
+  /** Extracted content in the requested {@link ReadFormat}. */
+  readonly content: string
+  /** Page title, when reported. */
+  readonly title?: string
+  /** Links discovered on the page, when returned. */
+  readonly links?: ReadonlyArray<string>
+  /** The provider-native response. */
+  readonly raw: unknown
+}
+
+// ---------------------------------------------------------------------------
+// Service + helper
+// ---------------------------------------------------------------------------
+
+/**
+ * The portable read surface: one operation, `read`. Every implementor can
+ * answer, so this capability needs no marker tags.
+ */
+export type WebReadService = {
+  readonly read: (request: CommonReadRequest) => Effect.Effect<ReadResponse, AiError.AiError>
+}
+
+/**
+ * Generic read service tag. Yield this for provider-portable code; yield a
+ * provider tag for provider-specific knobs. A provider `layer` registers both.
+ */
+export class WebRead extends Context.Service<WebRead, WebReadService>()(
+  "@betalyra/effect-uai/WebRead",
+) {}
+
+/** Read one URL against whichever provider Layer is in scope. */
+export const read = (
+  request: CommonReadRequest,
+): Effect.Effect<ReadResponse, AiError.AiError, WebRead> =>
+  Effect.flatMap(WebRead.asEffect(), (s) => s.read(request))

package/src/web-read/WebReadTool.ts

@@ -0,0 +1,96 @@
+import { Effect, Schema } from "effect"
+import type * as AiError from "../domain/AiError.js"
+import * as Tool from "../tool/Tool.js"
+import { read, type ReadFormat, type ReadResponse, WebRead } from "./WebRead.js"
+
+/**
+ * Model-facing argument schema. Deliberately narrow: the URL is the only
+ * thing that is genuinely the model's call. Output format and the content
+ * cost ceiling are app policy, pinned on the constructor instead, so they
+ * are guaranteed rather than left to the model to remember each call.
+ */
+const WebReadToolArgs = Schema.Struct({
+  url: Schema.String.annotate({
+    description: "Absolute URL of the page to read.",
+  }),
+})
+
+export type WebReadToolArgs = typeof WebReadToolArgs.Type
+
+/** `title / url` header plus the extracted content - what a model reads best. */
+const defaultRender = (response: ReadResponse, maxChars: number): string => {
+  const header = response.title === undefined ? response.url : `${response.title}\n${response.url}`
+  const body =
+    response.content.length > maxChars
+      ? `${response.content.slice(0, maxChars)}\n[content truncated at ${maxChars} characters]`
+      : response.content
+  return `${header}\n\n${body}`
+}
+
+export type WebReadToolOptions = {
+  /** Tool name the model sees. Default `"web_read"`. */
+  readonly name?: string
+  /**
+   * App-fixed representation for every read - a policy choice, not a model
+   * knob. Default `"markdown"` (what models read best).
+   */
+  readonly format?: ReadFormat
+  /**
+   * App-fixed ceiling on rendered content characters per call - a context
+   * cost guard, not exposed to the model. Default `20000`.
+   */
+  readonly maxChars?: number
+  /**
+   * Override how a read response is rendered into the model-facing string.
+   * Default: `title / url` header plus the content, truncated at `maxChars`.
+   */
+  readonly render?: (response: ReadResponse) => string
+}
+
+/**
+ * The canonical web-read tool. Its `R` is just `WebRead`, so providing any
+ * read-provider Layer satisfies it and the model-facing contract (name,
+ * description, schema) is identical no matter which backend answers - swap
+ * `FirecrawlRead.layer` for `JinaRead.layer` and the tool the model sees
+ * does not change. Drops straight into a `Toolkit` next to `webSearchTool`
+ * (search finds the URLs, read fetches the ones worth reading in full).
+ *
+ * `Output` is the rendered page; failures stay typed on the `AiError`
+ * channel. To let the model recover from a failed read, wrap the toolkit in
+ * `Toolkit.describeFailures(AiError.describe)`.
+ *
+ * This is a simple default implementation for quick use. For more elaborate
+ * cases (a different output contract, more model-facing knobs), build your
+ * own tool with `Tool.make` over the same `read` helper.
+ */
+export const webReadTool = (
+  options?: WebReadToolOptions,
+): Tool.Tool<string, WebReadToolArgs, never, string, AiError.AiError, WebRead> => {
+  const name = options?.name ?? "web_read"
+  const format = options?.format ?? "markdown"
+  const maxChars = options?.maxChars ?? 20_000
+  const render = options?.render ?? ((response: ReadResponse) => defaultRender(response, maxChars))
+  return Tool.make({
+    name,
+    description:
+      "Read a web page and return its content as clean text. Use it to read a promising URL in full (e.g. one found via search).",
+    inputSchema: Tool.fromEffectSchema(WebReadToolArgs),
+    // The call is wrapped in a tracing span so agent traces show the tool
+    // invocation (url, format, content length) nested under the model turn.
+    // `withSpan` is a no-op until a Tracer is installed, so this is free by
+    // default and adds nothing to the requirements.
+    run: (args) =>
+      read({ url: args.url, format }).pipe(
+        Effect.tap((r) => Effect.annotateCurrentSpan("web_read.content_chars", r.content.length)),
+        Effect.map(render),
+        Effect.withSpan(name, {
+          kind: "client",
+          attributes: {
+            "web_read.url": args.url,
+            "web_read.format": format,
+            "web_read.max_chars": maxChars,
+          },
+        }),
+      ),
+  })
+}

package/src/web-search/WebSearchTool.ts

@@ -1,4 +1,5 @@
 import { Effect, Schema } from "effect"
+import type * as AiError from "../domain/AiError.js"
 import * as Tool from "../tool/Tool.js"
 import { search, SearchRecency, type SearchResult, WebSearch } from "./WebSearch.js"
 
@@ -59,14 +60,19 @@ export type WebSearchToolOptions = {
  * `LanguageModel` tool-calling loop.
  *
  * The model controls only `query` and `recency`; domain scoping and the
- * result cap are app policy, fixed here on the constructor. `Output` is
- * rendered text, not raw `SearchResult[]`: the model reads the list, while
- * the app still gets the structured results through the normal tool-result
- * channel. Pass `render` to change the format.
+ * result cap are app policy, fixed here on the constructor. `Output` is the
+ * rendered text (the model reads a numbered list better than raw
+ * `SearchResult[]`; pass `render` to change the format); failures stay typed
+ * on the `AiError` channel. To let the model recover from a failed search,
+ * wrap the toolkit in `Toolkit.describeFailures(AiError.describe)`.
+ *
+ * This is a simple default implementation for quick use. For more elaborate
+ * cases (a different output contract, more model-facing knobs), build your
+ * own tool with `Tool.make` over the same `search` helper.
  */
 export const webSearchTool = (
   options?: WebSearchToolOptions,
-): Tool.Tool<string, WebSearchToolArgs, never, string, WebSearch> => {
+): Tool.Tool<string, WebSearchToolArgs, never, string, AiError.AiError, WebSearch> => {
   const name = options?.name ?? "web_search"
   const render = options?.render ?? defaultRender
   const maxResults = options?.maxResults ?? 5

package/dist/Tool-0XUIT2A2.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"Tool-0XUIT2A2.d.mts","names":[],"sources":["../src/tool/Tool.ts"],"mappings":"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"}

package/dist/ToolEvent-DYrAUJGs.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"ToolEvent-DYrAUJGs.d.mts","names":[],"sources":["../src/tool/ToolEvent.ts"],"mappings":";;;;;;;;KAaY,SAAA,GAAY,IAAA,CAAK,UAAA;EAC3B,iBAAA;IAAA,SACW,OAAA;IAAA,SACA,IAAA;IAAA,SACA,SAAA;EAAA;EAEX,QAAA;IAAA,SACW,OAAA;IAAA,SACA,IAAA;IAAA,SACA,IAAA;EAAA;EAEX,MAAA;IAAA,SACW,MAAA,EAAQ,UAAA;EAAA;AAAA;;;;;AAWrB;;;cAAa,SAAA;EAAA;;;;;;;;;;;;;;qBAXQ,UAAA;EAAA;EAAA;;;;;;;;;;;;;;;;qBAAA,UAAA;EAAA;IAAA;;;;;;;;;;;;;;;;;;yBAAA,UAAA;MAAA;IAAA;;;;;;;;;;;;uBAAA,UAAA;IAAA;;;;;;;;;;;;;;;;yBAAA,UAAA;MAAA;IAAA;;;;;;;;;;;;uBAAA,UAAA;IAAA;;;cAaR,mBAAA,GAAmB,CAAA,cAAA,CAAA;EAAA;;;;;cACnB,UAAA,GAAU,CAAA,cAAA,CAAA;EAAA;;;;;cACV,QAAA,GAAQ,CAAA,cAAA,CAAA;EAAA;mBAfA,UAAA;AAAA"}

package/dist/ToolResult-BZd-cEWW.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"ToolResult-BZd-cEWW.d.mts","names":[],"sources":["../src/tool/ToolResult.ts"],"mappings":";;;;;;;;KAqBY,UAAA,GAAa,IAAA,CAAK,UAAA;EAC5B,EAAA;IAAA,SACW,OAAA;IAAA,SACA,IAAA;IAAA,SACA,KAAA;EAAA;EAEX,OAAA;IAAA,SACW,OAAA;IAAA,SACA,IAAA;IAAA,SACA,IAAA;IAAA,SACA,MAAA;EAAA;AAAA;;;;;;;;AAYb;cAAa,UAAA;EAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAEA,IAAA,GAAI,CAAA,cAAA,CAAA;EAAA;;;;;cACJ,SAAA,GAAS,CAAA,cAAA,CAAA;EAAA;;;;;;cAMT,MAAA,GAAU,IAAA,EAAM,QAAA,EAAU,IAAA,UAAc,MAAA,cAAkB,UAAA;;cAS1D,MAAA,GAAU,IAAA,EAAM,QAAA,EAAU,MAAA,cAAkB,UAAA;;cAI5C,SAAA,GAAa,IAAA,EAAM,QAAA,EAAU,MAAA,cAAkB,UAAA;;cAI/C,cAAA,GAAkB,IAAA,EAAM,QAAA,EAAU,MAAA,aAAiB,UAAA;;;;;;;cASnD,YAAA,GAAgB,IAAA,EAAM,QAAA,EAAU,MAAA,cAAkB,UAAA;;;;;;cAYlD,eAAA,GAAmB,IAAA,EAAM,QAAA,EAAU,MAAA,cAAkB,UAAA;AAAA,cAOrD,gBAAA,GAAoB,CAAA,EAAG,UAAA,KAAa,cAAA"}

package/dist/Toolkit-BKC8b8Xo.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"Toolkit-BKC8b8Xo.d.mts","names":[],"sources":["../src/tool/Toolkit.ts"],"mappings":";;;;;;;;;;;;;KAkDY,OAAA,GAAU,MAAA,SAAe,OAAA;AAAA,KAEzB,OAAA,eAAsB,OAAA,GAAU,OAAA,IAAW,KAAA;AAAA,cAgB1C,IAAA,uBAA4B,aAAA,CAAc,OAAA,MAClD,KAAA,EAAO,WAAA,CAAY,KAAA,MACrB,OAAA,SAAgB,KAAA,YAAiB,CAAA,WAAY,CAAA;;;;;;;cAQnC,SAAA,GAAa,KAAA,EAAO,aAAA,CAAc,OAAA,MAAW,OAAA;;cAG7C,WAAA,GAAe,OAAA,EAAS,OAAA,KAAU,aAAA,CAAc,cAAA;;;;;;;;;;KAYjD,QAAA,WAAmB,OAAA,IAAW,OAAA,SAAgB,CAAA,WAAY,KAAA,CAAM,CAAA,OAAQ,CAAA;AAAA,KAY/E,aAAA,eACW,aAAA,CAAc,OAAA,kCAE1B,KAAA,sCACiB,OAAA,wBACG,aAAA,CAAc,OAAA,KAElC,IAAA,iBAAqB,IAAA,GACnB,IAAA,WACA,aAAA,CAAc,IAAA,EAAM,IAAA,GAAO,IAAA;AAAA,KAG5B,kBAAA;EAAA,SACM,OAAA,0BAAiC,IAAA;AAAA;AAAA,KAGhC,gBAAA,eAA+B,aAAA,CAAc,OAAA,MACvD,aAAA,CAAc,KAAA,+BAGZ,kBAAA,CAAmB,aAAA,CAAc,KAAA;;KAGzB,WAAA,eAA0B,aAAA,CAAc,OAAA,KAAY,KAAA,GAAQ,gBAAA,CAAiB,KAAA;AAAA,KAIpF,mBAAA,cACU,aAAA,CAAc,OAAA,kCAEzB,IAAA,sCAA0C,OAAA,wBAA+B,aAAA,CAAc,OAAA,0BAClE,IAAA,GACnB,mBAAA,CAAoB,IAAA,EAAM,IAAA,IAC1B,OAAA,OAAc,IAAA,WAAe,IAAA,kBAC3B,mBAAA,CAAoB,IAAA,EAAM,IAAA,UAAc,IAAA,cACxC,OAAA,OAAc,IAAA,WAAe,IAAA;AAAA,KAGhC,uBAAA,cAAqC,aAAA,CAAc,OAAA,MACtD,mBAAA,CAAoB,IAAA,+BAGlB,kBAAA,CAAmB,mBAAA,CAAoB,IAAA;AAAA,KAEtC,mBAAA,OAA0B,CAAA,oBAAqB,CAAA,EAAG,CAAA,6BACrD,CAAA,sBAEE,CAAA;AAAA,KAGC,QAAA,cAAsB,aAAA,CAAc,OAAA,KACvC,mBAAA,CAAoB,IAAA,6BAAiC,CAAA,SAAU,OAAA,GAAU,CAAA,GAAI,OAAA,IAAW,OAAA;AAAA,cAAO,sBAAA;;;;AAxFjG;;;;;cAkGa,iBAAA,SAA0B,sBAAA;EAAA,SAC5B,IAAA;EAAA,SACA,OAAA,EAAS,aAAA;AAAA;AAAA,KAKf,UAAA,kDAA4D,MAAA,KAAW,IAAA;AAAA,KAEvE,UAAA,kCAA4C,OAAA,IAC/C,CAAA,SAAU,IAAA,iDACN,IAAA,CAAK,UAAA,CAAW,MAAA,EAAQ,CAAA,GAAI,CAAA,EAAG,EAAA,EAAI,CAAA,EAAG,CAAA,IACtC,CAAA,SAAU,YAAA,uCACR,YAAA,CAAa,UAAA,CAAW,MAAA,EAAQ,CAAA,GAAI,CAAA,EAAG,CAAA,EAAG,CAAA,IAC1C,CAAA,SAAU,UAAA,qBACR,UAAA,CAAW,UAAA,CAAW,MAAA,EAAQ,CAAA,GAAI,CAAA,IAClC,CAAA,SAAU,eAAA,qBACR,eAAA,CAAgB,UAAA,CAAW,MAAA,EAAQ,CAAA,GAAI,CAAA,IACvC,CAAA;AAAA,KAEP,UAAA,kCAA4C,OAAA,2BAC1B,CAAA,aAAc,UAAA,CAAW,MAAA,EAAQ,CAAA,IAAK,CAAA,CAAE,CAAA,UAAW,OAAA,GACpE,UAAA,CAAW,MAAA,EAAQ,CAAA,CAAE,CAAA;;;;;;;cAUd,SAAA,gDAA0D,OAAA,EACrE,MAAA,EAAQ,MAAA,EACR,OAAA,EAAS,OAAA,CAAQ,CAAA,MAChB,OAAA,CAAQ,UAAA,CAAW,MAAA,EAAQ,CAAA;;cASjB,cAAA,oDAES,aAAA,CAAc,OAAA,GAElC,MAAA,EAAQ,MAAA,KACL,KAAA,EAAO,WAAA,CAAY,KAAA,MACrB,OAAA,CAAQ,UAAA,CAAW,MAAA,UAAgB,KAAA,YAAiB,CAAA,WAAY,CAAA;;;AA1InE;;;;;cAsJa,OAAA,sBAA8B,aAAA,CAAc,OAAA,MACpD,QAAA,EAAU,IAAA,GAAO,uBAAA,CAAwB,IAAA,MAC3C,MAAA,CAAO,MAAA,CAAO,OAAA,CAAQ,QAAA,CAAS,IAAA,IAAQ,iBAAA;AAAA,KA6BrC,OAAA,6BACH,KAAA,EAAO,KAAA,EACP,IAAA,EAAM,IAAA,CAAK,KAAA,MACR,MAAA,CAAO,MAAA,CAAO,MAAA,WAAiB,CAAA;AAAA,KAExB,UAAA,yCACV,GAAA,EAAK,OAAA,CAAQ,KAAA,EAAO,KAAA,EAAO,MAAA,EAAQ,CAAA,GACnC,IAAA,aACG,OAAA,CAAQ,KAAA,EAAO,KAAA,EAAO,MAAA,EAAQ,CAAA,GAAI,EAAA;AAAA,KAElC,QAAA,WAAmB,OAAA,QACtB,CAAA,SAAU,IAAA,iDAAqD,IAAA,CAAK,CAAA,EAAG,CAAA,EAAG,EAAA,EAAI,CAAA,EAAG,CAAA,GAAI,EAAA,IAAM,CAAA;AAAA,KAExF,WAAA,WAAsB,OAAA,+BACJ,CAAA,GAAI,CAAA,CAAE,CAAA,UAAW,OAAA,GAAU,QAAA,CAAS,CAAA,CAAE,CAAA,GAAI,EAAA,IAAM,CAAA,CAAE,CAAA;;;AAhMzE;;;;;;;;;;;cAgNa,IAAA;EAAA,KACN,UAAA,EAAY,UAAA,CAAW,EAAA,eAAiB,OAAA,EAAS,OAAA,EAAS,CAAA,KAAM,WAAA,CAAY,CAAA,EAAG,EAAA;EAAA,WACzE,OAAA,MAAa,OAAA,EAAS,CAAA,EAAG,UAAA,EAAY,UAAA,CAAW,EAAA,IAAM,WAAA,CAAY,CAAA,EAAG,EAAA;AAAA;AAAA,KActE,cAAA;EAAA,SACD,WAAA;AAAA;;cAIE,GAAA,aAAiB,OAAA,EAC5B,OAAA,EAAS,CAAA,EACT,KAAA,EAAO,aAAA,CAAc,QAAA,GACrB,OAAA,GAAU,cAAA,KACT,MAAA,CAAO,MAAA,CAAO,SAAA,SAAkB,QAAA,CAAS,CAAA;;;;;;;;;;;;;cAmG/B,iBAAA;EAAA,SACW,OAAA,EAAS,aAAA,CAAc,WAAA;AAAA,GAAgB,KAAA,EAAO,CAAA,EAAG,IAAA,EAAM,IAAA,MAC5E,OAAA,EAAS,aAAA,CAAc,UAAA,MAAc,CAAA;;;;;;;;;;;;cAc3B,cAAA,SACX,MAAA,EAAQ,MAAA,CAAO,MAAA,CAAO,SAAA,EAAW,CAAA,EAAG,CAAA,MACnC,MAAA,CAAO,MAAA,CAAO,aAAA,CAAc,UAAA,GAAa,CAAA,EAAG,CAAA;;;;;;;;;;;;;;;;;cAuBlC,mBAAA;EAAA,IAET,KAAA,GAAQ,OAAA,EAAS,aAAA,CAAc,UAAA,MAAgB,CAAA,OAE/C,MAAA,EAAQ,MAAA,CAAO,MAAA,CAAO,SAAA,SAAkB,CAAA,MACrC,MAAA,CAAO,MAAA,CAAO,IAAA,CAAU,SAAA,EAAW,CAAA,UAAW,CAAA;EAAA,OAEjD,MAAA,EAAQ,MAAA,CAAO,MAAA,CAAO,SAAA,SAAkB,CAAA,GACxC,KAAA,GAAQ,OAAA,EAAS,aAAA,CAAc,UAAA,MAAgB,CAAA,GAC9C,MAAA,CAAO,MAAA,CAAO,IAAA,CAAU,SAAA,EAAW,CAAA,UAAW,CAAA;AAAA"}