@effect-uai/core 0.8.0 → 0.9.0

package/src/tool/Tool.ts

@@ -1,5 +1,5 @@
 import type { StandardJSONSchemaV1, StandardSchemaV1 } from "@standard-schema/spec"
-import { Effect, Schema, Stream } from "effect"
+import { Effect, Schema } from "effect"
 import type { ToolCall, ToolCallOutput } from "../domain/Items.js"
 import { toolCallOutput } from "../domain/Items.js"
 
@@ -13,6 +13,30 @@ export class ToolError extends Schema.TaggedErrorClass<ToolError>("@betalyra/eff
   },
 ) {}
 
+/**
+ * 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.
+ */
+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.
+ */
+export class ToolValidationError extends Schema.TaggedErrorClass<ToolValidationError>(
+  "@betalyra/effect-uai/ToolValidationError",
+)("ToolValidationError", {
+  call_id: Schema.String,
+  tool: Schema.String,
+  issues: Schema.Array(ToolValidationIssue),
+}) {}
+
 /**
  * Schemas accepted on `Tool.inputSchema`. Must implement both Standard
  * Schema validation and JSON Schema conversion (for rendering tool
@@ -33,8 +57,7 @@ export type ToolInputSchema<Input = unknown> = StandardSchemaV1<unknown, Input>
 export const fromEffectSchema = <S extends Schema.Codec<any, any, never, any>>(
   schema: S,
 ): S & ToolInputSchema<S["Type"]> =>
-  Schema.toStandardJSONSchemaV1(Schema.toStandardSchemaV1(schema)) as unknown as S &
-    ToolInputSchema<S["Type"]>
+  Schema.toStandardJSONSchemaV1(Schema.toStandardSchemaV1(schema))
 
 /**
  * Use any schema library that implements both Standard Schema (validation)
@@ -56,11 +79,37 @@ export const fromStandardSchema = <S extends StandardSchemaV1 & StandardJSONSche
 ): S & ToolInputSchema<StandardSchemaV1.InferOutput<S>> =>
   schema as S & ToolInputSchema<StandardSchemaV1.InferOutput<S>>
 
-export type Tool<Name extends string, Input, Output, R = 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>
+
+/**
+ * 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, R = never> = {
+  readonly _tag: "LocalTool"
   readonly name: Name
   readonly description: string
   readonly inputSchema: ToolInputSchema<Input>
-  readonly run: (input: Input) => Effect.Effect<Output, unknown, R>
+  readonly run: (input: Input, emit: Emit<Event>) => Effect.Effect<Output, unknown, R>
+  /**
+   * 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
@@ -70,6 +119,67 @@ export type Tool<Name extends string, Input, Output, R = never> = {
   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.
+ */
+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 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`.
+ */
+export type SignalTool<Name extends string, Input> = {
+  readonly _tag: "SignalTool"
+  readonly name: Name
+  readonly description: string
+  readonly inputSchema: ToolInputSchema<Input>
+}
+
+/**
+ * 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.
+ */
+export type InteractionTool<Name extends string, Input> = {
+  readonly _tag: "InteractionTool"
+  readonly name: Name
+  readonly description: string
+  readonly inputSchema: ToolInputSchema<Input>
+}
+
+/** A local (executable) tool of any shape. Readability alias. */
+export type AnyLocalTool<R = any> = Tool<string, any, any, any, R>
+
+/** Any of the four model-visible tool kinds. */
+export type AnyTool<R = any> =
+  | Tool<string, any, any, any, R>
+  | ProviderTool<string, any, string, any>
+  | SignalTool<string, any>
+  | InteractionTool<string, any>
+
+/** A model-visible tool that carries a decodable input schema (every kind). */
+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, infer R> ? R : never
+
 /**
  * Provider-agnostic tool descriptor. Each provider maps `inputSchema`
  * to its own wire field (OpenAI → `parameters`, Anthropic →
@@ -82,69 +192,111 @@ export type ToolDescriptor = {
   readonly strict?: boolean
 }
 
-export const make = <Name extends string, Input, Output, R = never>(
-  spec: Tool<Name, Input, Output, R>,
-): Tool<Name, Input, Output, R> => spec
-
-// ---------------------------------------------------------------------------
-// Streaming tools
-//
-// `run` returns a `Stream<Event>` instead of an `Effect<Output>`. Events
-// flow through to the consumer as `ToolEvent.Progress`s in real time;
-// at end-of-stream `finalize(events)` reduces them to the model-facing
-// `Output`. Sub-agents, slow downloads with progress, recipe streamers.
-// ---------------------------------------------------------------------------
-
-export type StreamingTool<Name extends string, Input, Event, Output, R = never> = {
-  readonly _kind: "streaming"
-  readonly name: Name
-  readonly description: string
-  readonly inputSchema: ToolInputSchema<Input>
-  readonly run: (input: Input) => Stream.Stream<Event, unknown, R>
-  readonly finalize: (events: ReadonlyArray<Event>) => Output
-  readonly strict?: boolean
-}
+/** 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 streaming = <Name extends string, Input, Event, Output, R = never>(
-  spec: Omit<StreamingTool<Name, Input, Event, Output, R>, "_kind">,
-): StreamingTool<Name, Input, Event, Output, R> => ({ _kind: "streaming", ...spec })
+/**
+ * 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`.
+ */
+export const provider = <Name extends string, Input, Provider extends string, Config>(
+  spec: Omit<ProviderTool<Name, Input, Provider, Config>, "_tag">,
+): ProviderTool<Name, Input, Provider, Config> => ({ _tag: "ProviderTool", ...spec })
 
-export type AnyStreamingTool<R = any> = StreamingTool<string, any, any, any, R>
-export type AnyPlainTool<R = any> = Tool<string, any, any, R>
-export type AnyTool<R = any> = AnyStreamingTool<R> | AnyPlainTool<R>
+/**
+ * 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`.
+ */
+export const signal = <Name extends string, Input>(
+  spec: Omit<SignalTool<Name, Input>, "_tag">,
+): SignalTool<Name, Input> => ({ _tag: "SignalTool", ...spec })
+
+/**
+ * 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, Input>(
+  spec: Omit<InteractionTool<Name, Input>, "_tag">,
+): InteractionTool<Name, Input> => ({ _tag: "InteractionTool", ...spec })
 
-export const isStreamingTool = <R>(t: AnyTool<R>): t is AnyStreamingTool<R> =>
-  "_kind" in t && t._kind === "streaming"
+/**
+ * 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.
+ */
+export const withName = <N extends string, T extends AnyTool>(
+  tool: T,
+  name: N,
+): Omit<T, "name"> & { readonly name: N } => ({ ...tool, name })
 
 /**
- * Render any-kind tools (mixed plain and streaming) to provider-agnostic
- * descriptors. Accepts the union type so a single list can carry both
- * plain and streaming tools.
+ * 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.
  */
-export const toDescriptors = <R>(tools: ReadonlyArray<AnyTool<R>>): ReadonlyArray<ToolDescriptor> =>
+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 })
+
+/** Render tools to provider-agnostic descriptors. Every kind is model-visible. */
+export const toDescriptors = (tools: ReadonlyArray<AnyTool>): ReadonlyArray<ToolDescriptor> =>
   tools.map((tool) => {
     const inputSchema = tool.inputSchema["~standard"].jsonSchema.input({
       target: "draft-2020-12",
     })
-    return tool.strict !== undefined
-      ? { name: tool.name, description: tool.description, inputSchema, strict: tool.strict }
+    // `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.
+ */
+export const descriptorsOf = (
+  toolkit?: Readonly<Record<string, AnyTool>>,
+): 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 })
 
 /**
- * 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.
+ * 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.
  */
-export const execute = <Name extends string, Input, Output, R>(
-  tool: Tool<Name, Input, Output, R>,
+export const decodeArgs = <Input>(
+  tool: DecodableTool<Input>,
   call: ToolCall,
-): Effect.Effect<ToolCallOutput, ToolError, R> =>
+): 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"),
     })
@@ -153,16 +305,30 @@ export const execute = <Name extends string, Input, Output, R>(
       Promise.resolve(tool.inputSchema["~standard"].validate(parsed)),
     )
     if (result.issues !== undefined) {
-      return yield* new ToolError({
+      return yield* new ToolValidationError({
         call_id: call.call_id,
         tool: tool.name,
-        message: "Tool input failed schema validation",
-        cause: result.issues,
+        issues: result.issues,
       })
     }
-
-    const output = yield* tool
-      .run(result.value)
-      .pipe(Effect.mapError(toToolError(call, tool.name, "Tool execution failed")))
-    return toolCallOutput(call.call_id, JSON.stringify(output))
+    return result.value
   })
+
+/**
+ * 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, R>(
+  tool: Tool<Name, Input, Event, Output, R>,
+  call: ToolCall,
+): Effect.Effect<ToolCallOutput, 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))),
+  )

package/src/tool/ToolResult.ts

@@ -66,10 +66,31 @@ export const denied = (call: ToolCall, reason?: string): ToolResult =>
 export const cancelled = (call: ToolCall, reason?: string): ToolResult =>
   failed(call, "cancelled", reason)
 
-/** Tool's own execution failed (parse error, schema, runtime crash). */
+/** Tool's own execution failed (JSON parse error, runtime crash). */
 export const executionError = (call: ToolCall, reason: string): ToolResult =>
   failed(call, "execution_error", reason)
 
+/**
+ * The model called a tool that is visible to it but has no local executor — a
+ * provider-hosted, signal, or interaction tool routed through `Toolkit.run`.
+ * Distinct from `unknown_tool` (no such tool at all): the loop is expected to
+ * intercept these kinds before execution, so this kind flags a missing handler.
+ */
+export const nonLocalTool = (call: ToolCall, reason?: string): ToolResult =>
+  failed(
+    call,
+    "non_local_tool",
+    reason ?? `Tool "${call.name}" is visible to the model but has no local executor`,
+  )
+
+/**
+ * The model's `arguments` failed the tool's input schema. Distinct kind from
+ * `execution_error` so recipes can tell a contract violation apart from a
+ * runtime crash.
+ */
+export const validationError = (call: ToolCall, reason?: string): ToolResult =>
+  failed(call, "input_validation_error", reason ?? "Tool input failed schema validation")
+
 // ---------------------------------------------------------------------------
 // Wire conversion - the one place structured → string happens.
 // ---------------------------------------------------------------------------

package/src/tool/Toolkit.test.ts

@@ -1,4 +1,4 @@
-import { Context, Effect, Layer, Schema, Stream } from "effect"
+import { Context, Effect, Layer, pipe, Schema, Stream } from "effect"
 import { describe, expect, expectTypeOf, it } from "vitest"
 import type { ToolCall } from "../domain/Items.js"
 import { isOutput } from "./ToolEvent.js"
@@ -92,7 +92,7 @@ describe("Toolkit.run - tools with R requirements", () => {
   })
 
   it("propagates each tool's R into the resulting Stream's requirements", () => {
-    const stream = Toolkit.run([getWeather, getCoords], [])
+    const stream = Toolkit.run(Toolkit.make(getWeather, getCoords), [])
     expectTypeOf(stream).toEqualTypeOf<
       Stream.Stream<import("./ToolEvent.js").ToolEvent, never, WeatherApiKey | GeoApiKey>
     >()
@@ -104,10 +104,10 @@ describe("Toolkit.run - tools with R requirements", () => {
       Layer.succeed(GeoApiKey, { key: "geo-456" }),
     )
 
-    const program = Toolkit.run(
-      [getWeather, getCoords],
-      [call("get_weather", "c1"), call("get_coords", "c2")],
-    ).pipe(Stream.runCollect, Effect.provide(layer))
+    const program = Toolkit.run(Toolkit.make(getWeather, getCoords), [
+      call("get_weather", "c1"),
+      call("get_coords", "c2"),
+    ]).pipe(Stream.runCollect, Effect.provide(layer))
 
     const events = await Effect.runPromise(program)
     const outputs = Array.from(events).filter(isOutput)
@@ -125,6 +125,43 @@ describe("Toolkit.run - tools with R requirements", () => {
     })
   })
 
+  it("reports non-local kinds as non_local_tool while local calls in the same turn still run", async () => {
+    const escalate = Tool.signal({
+      name: "escalate",
+      description: "",
+      inputSchema: Tool.fromEffectSchema(Empty),
+    })
+    const localPlain = Tool.make({
+      name: "plain",
+      description: "",
+      inputSchema: Tool.fromEffectSchema(Empty),
+      run: () => Effect.succeed({ ok: true }),
+    })
+
+    const events = await Effect.runPromise(
+      Toolkit.run(Toolkit.make(localPlain, escalate), [
+        call("escalate", "s1"),
+        call("plain", "p1"),
+        call("ghost", "g1"),
+      ]).pipe(Stream.runCollect),
+    )
+    const byCall = new Map(
+      Array.from(events)
+        .filter(isOutput)
+        .map((e) => [e.result.call_id, e.result] as const),
+    )
+
+    // Signal tool: model-visible but no local executor.
+    const s = byCall.get("s1")
+    expect(s?._tag === "Failure" && s.kind).toBe("non_local_tool")
+    // Unknown tool stays distinct from non-local.
+    const g = byCall.get("g1")
+    expect(g?._tag === "Failure" && g.kind).toBe("unknown_tool")
+    // The local call still executed despite the non-local sibling.
+    const p = byCall.get("p1")
+    expect(p !== undefined && isOk(p) && p.value).toEqual({ ok: true })
+  })
+
   it("with no service-needing tools, R is never", () => {
     const plain = Tool.make({
       name: "plain",
@@ -132,9 +169,133 @@ describe("Toolkit.run - tools with R requirements", () => {
       inputSchema: Tool.fromEffectSchema(Empty),
       run: () => Effect.succeed(0),
     })
-    const stream = Toolkit.run([plain], [])
+    const stream = Toolkit.run(Toolkit.make(plain), [])
     expectTypeOf(stream).toEqualTypeOf<
       Stream.Stream<import("./ToolEvent.js").ToolEvent, never, never>
     >()
   })
 })
+
+describe("Toolkit.make / compose / namespace - uniqueness", () => {
+  const Empty = Schema.Struct({})
+  const tool = (name: string) =>
+    Tool.make({
+      name,
+      description: "",
+      inputSchema: Tool.fromEffectSchema(Empty),
+      run: () => Effect.succeed(0),
+    })
+
+  it("rejects a duplicate literal name at compile time", () => {
+    const a = tool("search")
+    const b = Tool.provider({
+      name: "search",
+      description: "",
+      inputSchema: Tool.fromEffectSchema(Empty),
+      provider: "demo",
+      config: {},
+    })
+    // @ts-expect-error Duplicate tool name: search
+    Toolkit.make(a, b)
+  })
+
+  it("fails compose with DuplicateToolName naming the colliding sources (dynamic)", async () => {
+    const github = Toolkit.fromArray([tool("search")])
+    const linear = Toolkit.fromArray([tool("search")])
+    const exit = await Effect.runPromiseExit(Toolkit.compose(github, linear))
+    expect(exit._tag).toBe("Failure")
+    if (exit._tag === "Failure") {
+      const json = JSON.stringify(exit.cause)
+      expect(json).toContain("DuplicateToolName")
+      expect(json).toContain("toolkit-0")
+      expect(json).toContain("toolkit-1")
+    }
+  })
+
+  it("namespaces names so generic names from two sources compose cleanly", async () => {
+    const github = Toolkit.namespace("github", Toolkit.fromArray([tool("search")]))
+    const linear = Toolkit.namespace("linear", Toolkit.fromArray([tool("search")]))
+    const composed = await Effect.runPromise(Toolkit.compose(github, linear))
+    expect(Object.keys(composed).sort()).toEqual(["github__search", "linear__search"])
+  })
+
+  it("preserves each tool's R through compose", () => {
+    const stream = Effect.gen(function* () {
+      const composed = yield* Toolkit.compose(Toolkit.make(tool("a")), Toolkit.make(tool("b")))
+      return Toolkit.run(composed, [])
+    })
+    // No service-needing tools here -> R stays never (compose didn't poison it).
+    expectTypeOf(stream).toEqualTypeOf<
+      Effect.Effect<
+        Stream.Stream<import("./ToolEvent.js").ToolEvent, never, never>,
+        Toolkit.DuplicateToolName
+      >
+    >()
+  })
+})
+
+describe("Toolkit.wrap - middleware", () => {
+  const Empty = Schema.Struct({})
+  type AuditShape = { readonly record: (name: string) => Effect.Effect<void> }
+  class Audit extends Context.Service<Audit, AuditShape>()("test/Audit") {}
+
+  const getWeather = Tool.make({
+    name: "get_weather",
+    description: "",
+    inputSchema: Tool.fromEffectSchema(Empty),
+    run: () => Effect.succeed({ tempC: 18 }),
+  })
+  const escalate = Tool.signal({
+    name: "escalate",
+    description: "",
+    inputSchema: Tool.fromEffectSchema(Empty),
+  })
+
+  // A middleware that needs the Audit service -> R2 = Audit.
+  const audited: Toolkit.Middleware<Audit> = (run, name) => (input, emit) =>
+    Effect.gen(function* () {
+      const a = yield* Audit
+      yield* a.record(name)
+      return yield* run(input, emit)
+    })
+
+  const call = (name: string, id: string): ToolCall => ({
+    type: "function_call",
+    call_id: id,
+    name,
+    arguments: "{}",
+  })
+
+  it("unions the middleware's R2 into the toolkit's requirements", () => {
+    const wrapped = Toolkit.wrap(Toolkit.make(getWeather), audited)
+    const stream = Toolkit.run(wrapped, [])
+    expectTypeOf(stream).toEqualTypeOf<
+      Stream.Stream<import("./ToolEvent.js").ToolEvent, never, Audit>
+    >()
+  })
+
+  it("runs the wrapped handler and leaves non-local kinds untouched", async () => {
+    const recorded: Array<string> = []
+    const wrapped = pipe(Toolkit.make(getWeather, escalate), Toolkit.wrap(audited))
+
+    const events = await Effect.runPromise(
+      Toolkit.run(wrapped, [call("get_weather", "w1"), call("escalate", "s1")]).pipe(
+        Stream.runCollect,
+        Effect.provideService(Audit, { record: (n) => Effect.sync(() => void recorded.push(n)) }),
+      ),
+    )
+    const byCall = new Map(
+      Array.from(events)
+        .filter(isOutput)
+        .map((e) => [e.result.call_id, e.result] as const),
+    )
+
+    // Local tool ran through the middleware (audit fired).
+    expect(recorded).toEqual(["get_weather"])
+    const w = byCall.get("w1")
+    expect(w !== undefined && isOk(w) && w.value).toEqual({ tempC: 18 })
+    // Signal kind is left alone by wrap -> still reported non-local.
+    const s = byCall.get("s1")
+    expect(s?._tag === "Failure" && s.kind).toBe("non_local_tool")
+  })
+})