@effect-uai/core 0.9.0 → 0.11.0

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 })
 
@@ -234,6 +252,66 @@ describe("Toolkit.make / compose / namespace - uniqueness", () => {
   })
 })
 
+describe("Toolkit.namespace - typed toolkits", () => {
+  const Query = Schema.Struct({ q: Schema.String })
+  type GeoShape = { readonly lookup: (q: string) => Effect.Effect<string> }
+  class Geo extends Context.Service<Geo, GeoShape>()("test/Geo") {}
+
+  const search = Tool.make({
+    name: "search",
+    description: "",
+    inputSchema: Tool.fromEffectSchema(Query),
+    run: ({ q }) =>
+      Effect.gen(function* () {
+        const geo = yield* Geo
+        if (q === "") return yield* Effect.fail("empty_query" as const)
+        return yield* geo.lookup(q)
+      }),
+  })
+
+  const kit = Toolkit.namespace("geo", Toolkit.make(search))
+
+  it("type: prefixes the name literal of a service-requiring tool", () => {
+    expectTypeOf(kit.geo__search.name).toEqualTypeOf<"geo__search">()
+  })
+
+  it("type: preserves E and R through namespace", () => {
+    expectTypeOf<Toolkit.ToolkitE<typeof kit>>().toEqualTypeOf<"empty_query">()
+    expectTypeOf<Toolkit.ToolkitR<typeof kit>>().toEqualTypeOf<Geo>()
+  })
+
+  it("type: preserves E and R through makeNamespaced", () => {
+    const namespaced = Toolkit.makeNamespaced("geo", search)
+    expectTypeOf(namespaced.geo__search.name).toEqualTypeOf<"geo__search">()
+    expectTypeOf<Toolkit.ToolkitE<typeof namespaced>>().toEqualTypeOf<"empty_query">()
+    expectTypeOf<Toolkit.ToolkitR<typeof namespaced>>().toEqualTypeOf<Geo>()
+  })
+
+  it("type: Toolkit.run surfaces the namespaced tool's R (string E is absorbed)", () => {
+    const stream = Toolkit.run(kit, [])
+    expectTypeOf(stream).toEqualTypeOf<
+      Stream.Stream<import("./ToolEvent.js").ToolEvent, never, Geo>
+    >()
+  })
+
+  it("runtime: renames the tool and executes it under the prefixed name", async () => {
+    const call: ToolCall = {
+      type: "function_call",
+      call_id: "call_1",
+      name: "geo__search",
+      arguments: '{"q":"lisbon"}',
+    }
+    const events = await Effect.runPromise(
+      Stream.runCollect(Toolkit.run(kit, [call])).pipe(
+        Effect.provide(Layer.succeed(Geo, { lookup: (q) => Effect.succeed(`geo:${q}`) })),
+      ),
+    )
+    const outputs = events.filter(isOutput).map((e) => e.result)
+    expect(outputs).toHaveLength(1)
+    expect(outputs[0]).toMatchObject({ _tag: "Ok", tool: "geo__search", value: "geo:lisbon" })
+  })
+})
+
 describe("Toolkit.wrap - middleware", () => {
   const Empty = Schema.Struct({})
   type AuditShape = { readonly record: (name: string) => Effect.Effect<void> }
@@ -299,3 +377,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>>()
+  })
+})

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
@@ -174,8 +186,8 @@ export class DuplicateToolName extends Data.TaggedError("DuplicateToolName")<{
 type PrefixName<Prefix extends string, Name extends string> = `${Prefix}__${Name}`
 
 type PrefixTool<Prefix extends string, T extends AnyTool> =
-  T extends Tool<infer N, infer I, infer Ev, infer O, infer R>
-    ? Tool<PrefixName<Prefix, N>, I, Ev, O, R>
+  T extends Tool<infer N, infer I, infer Ev, infer O, infer E, infer R>
+    ? Tool<PrefixName<Prefix, N>, I, Ev, O, E, R>
     : T extends ProviderTool<infer N, infer I, infer P, infer C>
       ? ProviderTool<PrefixName<Prefix, N>, I, P, C>
       : T extends SignalTool<infer N, infer I>
@@ -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/transcriber/Transcriber.ts

@@ -88,7 +88,7 @@ export class SttStreaming extends Context.Service<SttStreaming, void>()(
 export const transcribe = (
   request: CommonTranscribeRequest,
 ): Effect.Effect<TranscriptResult, AiError.AiError, Transcriber> =>
-  Effect.flatMap(Transcriber.asEffect(), (t) => t.transcribe(request))
+  Effect.flatMap(Transcriber, (t) => t.transcribe(request))
 
 /**
  * Live transcription. Dual-arity: pipeable (data-last) and direct
@@ -122,8 +122,8 @@ export const streamTranscriptionFrom: {
   <E, R>(audioIn: Stream.Stream<Uint8Array, E, R>, request: CommonStreamTranscribeRequest) =>
     Stream.unwrap(
       Effect.gen(function* () {
-        const t = yield* Transcriber.asEffect()
-        yield* SttStreaming.asEffect()
+        const t = yield* Transcriber
+        yield* SttStreaming
         return t.streamTranscriptionFrom(audioIn, request)
       }),
     ),