@effect-uai/core 0.8.0 → 0.10.0

package/dist/tool/Toolkit.d.mts

@@ -1,73 +1,2 @@
-import { o as HistoryItem, v as ToolCall } from "../Items-7ljaVxH_.mjs";
-import { Turn } from "../domain/Turn.mjs";
-import { a as Tool, i as StreamingTool, r as AnyTool } from "../Tool-BKiieFXk.mjs";
-import { Step } from "../loop/Loop.mjs";
-import { ToolResult } from "./ToolResult.mjs";
-import { ToolEvent } from "./ToolEvent.mjs";
-import { Effect, Stream } from "effect";
-
-//#region src/tool/Toolkit.d.ts
-declare namespace Toolkit_d_exports {
-  export { ExecuteOptions, ToolKindR, appendToolResults, collectResults, continueWithResults, run };
-}
-/**
- * Union of every tool's `R` requirements in a mixed plain + streaming array.
- * Used by `run` to surface the services tools need at the recipe level, so
- * the loop's stream type carries them through to `Effect.provide`.
- */
-type ToolKindR<Tools extends ReadonlyArray<AnyTool<any>>> = Tools[number] extends StreamingTool<any, any, any, any, infer R> ? R : Tools[number] extends Tool<any, any, any, infer R> ? R : never;
-type ExecuteOptions = {
-  readonly concurrency?: number | "unbounded";
-};
-/** Execute every provided call. Approval/rejection policy belongs upstream. */
-declare const run: <Tools extends ReadonlyArray<AnyTool<any>>>(tools: Tools, calls: ReadonlyArray<ToolCall>, options?: ExecuteOptions) => Stream.Stream<ToolEvent, never, ToolKindR<Tools>>;
-/**
- * Append a completed turn plus tool results to a state's history, converting
- * the results to wire-format `ToolCallOutput`s. Curried so it slots directly
- * into `continueWithResults`:
- *
- *   Toolkit.run(tools, calls).pipe(
- *     Toolkit.continueWithResults(Toolkit.appendToolResults(state, turn)),
- *   )
- *
- * Equivalent to `appendToHistory(state, turn, results.map(toToolCallOutput))`
- * — the helper just hides the wire-conversion step.
- */
-declare const appendToolResults: <S extends {
-  readonly history: ReadonlyArray<HistoryItem>;
-}>(state: S, turn: Turn) => (results: ReadonlyArray<ToolResult>) => S;
-/**
- * Drain a `Stream<ToolEvent>` and return the accumulated `ToolResult`s
- * from every `Output` event. One-shot — the type is `Effect<results>`,
- * not a one-element stream — so it composes naturally with `Effect.map`
- * to build state.
- *
- * Counterpart to `continueWithResults`: `continueWithResults` bundles
- * drain + emit Next into one bridge; this one is the right arm of a
- * broadcast/fork-and-merge for callers that want to vary the left arm
- * (e.g., filter/tap ToolEvents before forwarding).
- */
-declare const collectResults: <E, R>(stream: Stream.Stream<ToolEvent, E, R>) => Effect.Effect<ReadonlyArray<ToolResult>, E, R>;
-/**
- * Bridge from a `Stream<ToolEvent>` to the loop's emit shape. Forwards
- * every ToolEvent downstream as a `Loop.value` and at end-of-stream emits
- * one `Loop.next(build(results))` carrying the accumulated `ToolResult`s
- * from terminal `Output` events.
- *
- * Conceptually a broadcast fork (one arm passes events through, the other
- * drains them into a state). Implemented as a single-pass Ref tap + concat
- * for zero buffering — the broadcast version is observationally equivalent
- * but holds events in a PubSub until both arms drain. The public primitives
- * (`Loop.value`, `collectResults`, `Loop.next`) compose the same pattern
- * when you need to vary an arm.
- *
- * Dual: data-first `continueWithResults(stream, build)` and data-last
- * `stream.pipe(continueWithResults(build))` both work.
- */
-declare const continueWithResults: {
-  <S>(build: (results: ReadonlyArray<ToolResult>) => S): <R>(stream: Stream.Stream<ToolEvent, never, R>) => Stream.Stream<Step<ToolEvent, S>, never, R>;
-  <S, R>(stream: Stream.Stream<ToolEvent, never, R>, build: (results: ReadonlyArray<ToolResult>) => S): Stream.Stream<Step<ToolEvent, S>, never, R>;
-};
-//#endregion
-export { ExecuteOptions, ToolKindR, appendToolResults, collectResults, continueWithResults, run, Toolkit_d_exports as t };
-//# sourceMappingURL=Toolkit.d.mts.map
+import { S as wrap, _ as fromArray, a as ToolMap, b as namespace, c as ToolkitR, d as appendToolResults, f as collectResults, g as descriptors, h as describeFailures, i as NoDuplicateNames, m as continueWithResults, n as ExecuteOptions, o as Toolkit, p as compose, r as Middleware, s as ToolkitE, t as DuplicateToolName, u as UniqueTools, v as make, x as run, y as makeNamespaced } from "../Toolkit-Dr9l_hNy.mjs";
+export { DuplicateToolName, ExecuteOptions, Middleware, NoDuplicateNames, ToolMap, Toolkit, ToolkitE, ToolkitR, UniqueTools, appendToolResults, collectResults, compose, continueWithResults, describeFailures, descriptors, fromArray, make, makeNamespaced, namespace, run, wrap };

package/dist/tool/Toolkit.mjs

@@ -1,63 +1,181 @@
 import { n as __exportAll } from "../chunk-uyGKjUfl.mjs";
+import { ToolResult, failed, nonLocalTool, toToolCallOutput, validationError } from "./ToolResult.mjs";
+import { ToolFailed, decodeCallInput, toDescriptors } from "./Tool.mjs";
 import { appendToHistory } from "../domain/Turn.mjs";
-import { isStreamingTool } from "./Tool.mjs";
 import { next, value } from "../loop/Loop.mjs";
-import { ToolResult, executionError, failed, toToolCallOutput } from "./ToolResult.mjs";
 import { ToolEvent, isOutput } from "./ToolEvent.mjs";
-import { Array, Effect, Function, Ref, Schema, Stream } from "effect";
+import { Array, Cause, Data, Effect, Fiber, Function, Match, Option, Queue, Record, Ref, Stream } from "effect";
 //#region src/tool/Toolkit.ts
 var Toolkit_exports = /* @__PURE__ */ __exportAll({
+	DuplicateToolName: () => DuplicateToolName,
 	appendToolResults: () => appendToolResults,
 	collectResults: () => collectResults,
+	compose: () => compose,
 	continueWithResults: () => continueWithResults,
-	run: () => run
+	describeFailures: () => describeFailures,
+	descriptors: () => descriptors,
+	fromArray: () => fromArray,
+	make: () => make,
+	makeNamespaced: () => makeNamespaced,
+	namespace: () => namespace,
+	run: () => run,
+	wrap: () => wrap
 });
-/** Execute every provided call. Approval/rejection policy belongs upstream. */
-const run = (tools, calls, options) => Stream.fromIterable(calls).pipe(Stream.flatMap((call) => runOne(tools, call), { concurrency: options?.concurrency ?? "unbounded" }));
+const indexByName = (tools) => Object.fromEntries(tools.map((tool) => [tool.name, tool]));
+/**
+* Index literal tools by their `name`. Duplicate names are a compile error
+* (`UniqueTools`). Names are not otherwise checked: a malformed name is a
+* developer typo in a literal that the provider rejects clearly on first use,
+* and there is no single cross-provider name rule to enforce here anyway.
+*/
+const buildStatic = (tools) => indexByName(tools);
+const make = (...tools) => buildStatic(tools);
+/**
+* Build a toolkit from a dynamically-sourced array (MCP server, plugin). Names
+* are not validated (MCP legitimately uses dots / >64 chars — sanitize at the
+* provider adapter); same-named tools resolve last-wins. Cross-source clashes
+* are caught by `compose`.
+*/
+const fromArray = (tools) => indexByName(tools);
+/** Render the provider-facing descriptors for a toolkit on demand. */
+const descriptors = (toolkit) => toDescriptors(Object.values(toolkit));
+/**
+* Two composed toolkits resolved to the same final name. Carries the colliding
+* `sources` (the positions of the clashing toolkits) so the error says *which*
+* inputs collided. Raised at runtime by `compose` for dynamic sources; static
+* collisions are caught earlier at compile time.
+*/
+var DuplicateToolName = class extends Data.TaggedError("DuplicateToolName") {};
+/**
+* Prefix every tool name with `<namespace>__`, returning a new toolkit. Use it
+* to keep generic names (`search`) from two sources distinct before `compose`.
+* If two namespaces collide at the `__` separator, the duplicate final name
+* surfaces from `compose` as a `DuplicateToolName`.
+*/
+const namespace = (prefix, toolkit) => {
+	return indexByName(Array.map(Record.values(toolkit), (tool) => ({
+		...tool,
+		name: `${prefix}__${tool.name}`
+	})));
+};
+/** `namespace(prefix, make(...tools))` in one step, for static namespaced tools. */
+const makeNamespaced = (prefix, ...tools) => namespace(prefix, buildStatic(tools));
+/**
+* Combine independently-built toolkits into one. This is where names from
+* separate sources can collide, so it is the one effectful constructor: a
+* duplicate final name fails with `DuplicateToolName` (naming the colliding
+* input positions) instead of silently overwriting or 400-ing later at the
+* provider. Statically-known collisions are additionally a compile error.
+*/
+const compose = (...toolkits) => Effect.gen(function* () {
+	const kits = toolkits;
+	const labelled = Array.flatMap(kits, (kit, i) => Array.map(Record.keys(kit), (name) => ({
+		name,
+		source: `toolkit-${i}`
+	})));
+	const collision = Array.findFirst(Record.toEntries(Array.groupBy(labelled, (entry) => entry.name)), ([, group]) => group.length > 1);
+	if (Option.isSome(collision)) {
+		const [name, group] = collision.value;
+		return yield* new DuplicateToolName({
+			name,
+			sources: Array.map(group, (e) => e.source)
+		});
+	}
+	return Array.reduce(kits, {}, (acc, kit) => ({
+		...acc,
+		...kit
+	}));
+});
+/**
+* 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` - 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) // authz runs, then logging, then the tool
+*
+* 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.
+*/
+const wrap = Function.dual(2, (toolkit, middleware) => Record.map(toolkit, (tool) => tool._tag === "LocalTool" ? {
+	...tool,
+	run: middleware(tool.run, tool.name)
+} : tool));
+/**
+* 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
+*   )
+*/
+const describeFailures = Function.dual(2, (toolkit, describe) => Record.map(toolkit, (tool) => tool._tag === "LocalTool" ? {
+	...tool,
+	run: (input, emit) => tool.run(input, emit).pipe(Effect.mapError(describe))
+} : tool));
+/**
+* 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`).
+*/
+const run = (toolkit, calls, options) => Stream.fromIterable(calls).pipe(Stream.flatMap((call) => runOne(toolkit, call), { concurrency: options?.concurrency ?? "unbounded" }));
 const okResult = (call, tool, value) => ToolResult.Ok({
 	call_id: call.call_id,
 	tool,
 	value
 });
-const runOne = (tools, call) => {
-	const tool = tools.find((t) => t.name === call.name);
-	if (tool === void 0) return Stream.succeed(ToolEvent.Output({ result: failed(call, "unknown_tool", `No tool registered with name "${call.name}"`) }));
-	if (isStreamingTool(tool)) return runStreaming(tool, call);
-	return runPlain(tool, call);
+const outputEvent = (result) => Stream.succeed(ToolEvent.Output({ result }));
+const runOne = (toolkit, call) => {
+	const tool = Object.hasOwn(toolkit, call.name) ? toolkit[call.name] : void 0;
+	return Match.value(tool).pipe(Match.when(Match.undefined, () => outputEvent(failed(call, "unknown_tool", `No tool registered with name "${call.name}"`))), Match.tag("LocalTool", (local) => runTool(local, call)), Match.orElse(() => outputEvent(nonLocalTool(call))));
 };
-const parseJsonUnknown = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Unknown));
-const runPlain = (tool, call) => Stream.fromEffect(Effect.gen(function* () {
-	const parsed = yield* parseJsonUnknown(call.arguments).pipe(Effect.mapError(() => "json_parse_error"));
-	const validated = yield* Effect.tryPromise({
-		try: () => Promise.resolve(tool.inputSchema["~standard"].validate(parsed)),
-		catch: () => "validation_threw"
-	});
-	if (validated.issues !== void 0) return executionError(call, "Tool input failed schema validation");
-	const output = yield* tool.run(validated.value);
-	return okResult(call, tool.name, output);
-}).pipe(Effect.catchCause(() => Effect.succeed(executionError(call, "Tool execution failed"))), Effect.map((result) => ToolEvent.Output({ result }))));
-const runStreaming = (tool, call) => Stream.unwrap(Effect.gen(function* () {
-	const parsed = yield* parseJsonUnknown(call.arguments).pipe(Effect.mapError(() => "json_parse_error"));
-	const validated = yield* Effect.tryPromise({
-		try: () => Promise.resolve(tool.inputSchema["~standard"].validate(parsed)),
-		catch: () => "validation_threw"
-	});
-	if (validated.issues !== void 0) return Stream.succeed(ToolEvent.Output({ result: executionError(call, "Tool input failed schema validation") }));
-	const ref = yield* Ref.make([]);
-	const progress = tool.run(validated.value).pipe(Stream.tap((event) => Ref.update(ref, Array.append(event))), Stream.map((data) => ToolEvent.Progress({
+const describeIssues = (issues) => 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);
+const runTool = (tool, call) => Stream.unwrap(decodeCallInput(tool, call).pipe(Effect.map(Match.type().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 runValidated = (tool, call, input) => Stream.unwrap(Effect.gen(function* () {
+	const queue = yield* Queue.make({ capacity: tool.emitBufferSize });
+	const emit = (event) => Effect.asVoid(Queue.offer(queue, event));
+	const fiber = yield* tool.run(input, emit).pipe(Effect.ensuring(Queue.end(queue)), Effect.forkScoped);
+	const progress = Stream.fromQueue(queue).pipe(Stream.map((data) => ToolEvent.Progress({
 		call_id: call.call_id,
 		tool: tool.name,
 		data
 	})));
-	const output = Stream.fromEffect(Ref.get(ref).pipe(Effect.map((events) => ToolEvent.Output({ result: okResult(call, tool.name, tool.finalize(events)) }))));
+	const output = Stream.fromEffect(Fiber.join(fiber).pipe(Effect.matchCauseEffect({
+		onSuccess: (value) => Effect.succeed(ToolEvent.Output({ result: okResult(call, tool.name, value) })),
+		onFailure: (cause) => routeCause(call, cause)
+	})));
 	return progress.pipe(Stream.concat(output));
-})).pipe(Stream.catchCause(() => Stream.succeed(ToolEvent.Output({ result: executionError(call, "Tool execution failed") }))));
+}));
+const routeCause = (call, cause) => {
+	const only = cause.reasons.length === 1 ? cause.reasons[0] : void 0;
+	if (only !== void 0 && 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);
+};
 /**
 * Append a completed turn plus tool results to a state's history, converting
 * the results to wire-format `ToolCallOutput`s. Curried so it slots directly
 * into `continueWithResults`:
 *
-*   Toolkit.run(tools, calls).pipe(
+*   Toolkit.run(toolkit, calls).pipe(
 *     Toolkit.continueWithResults(Toolkit.appendToolResults(state, turn)),
 *   )
 *
@@ -100,6 +218,6 @@ const continueWithResults = Function.dual(2, (stream, build) => Stream.unwrap(Ef
 	return tapped.pipe(Stream.concat(continuation));
 })));
 //#endregion
-export { appendToolResults, collectResults, continueWithResults, run, Toolkit_exports as t };
+export { DuplicateToolName, appendToolResults, collectResults, compose, continueWithResults, describeFailures, descriptors, fromArray, make, makeNamespaced, namespace, run, Toolkit_exports as t, wrap };
 
 //# sourceMappingURL=Toolkit.mjs.map

package/dist/tool/Toolkit.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"Toolkit.mjs","names":["Arr","Loop.value","Loop.next"],"sources":["../../src/tool/Toolkit.ts"],"sourcesContent":["import { Array as Arr, Effect, Function, Ref, Schema, Stream } from \"effect\"\nimport * as Loop from \"../loop/Loop.js\"\nimport type { ToolCall, HistoryItem } from \"../domain/Items.js\"\nimport { appendToHistory, type Turn } from \"../domain/Turn.js\"\nimport {\n  type AnyTool,\n  type AnyPlainTool,\n  type AnyStreamingTool,\n  isStreamingTool,\n  type StreamingTool,\n  type Tool,\n} from \"./Tool.js\"\nimport { ToolResult, executionError, failed, toToolCallOutput } from \"./ToolResult.js\"\nimport { ToolEvent } from \"./ToolEvent.js\"\nimport { isOutput } from \"./ToolEvent.js\"\n\n/**\n * Union of every tool's `R` requirements in a mixed plain + streaming array.\n * Used by `run` to surface the services tools need at the recipe level, so\n * the loop's stream type carries them through to `Effect.provide`.\n */\nexport type ToolKindR<Tools extends ReadonlyArray<AnyTool<any>>> =\n  Tools[number] extends StreamingTool<any, any, any, any, infer R>\n    ? R\n    : Tools[number] extends Tool<any, any, any, infer R>\n      ? R\n      : never\n\n// ---------------------------------------------------------------------------\n// Tool executor. Streams `ToolEvent`s in real time and dispatches streaming\n// and plain tools uniformly. Policy stays outside this module: callers pass\n// only the calls they have already decided should run.\n// ---------------------------------------------------------------------------\n\nexport type ExecuteOptions = {\n  readonly concurrency?: number | \"unbounded\"\n}\n\n/** Execute every provided call. Approval/rejection policy belongs upstream. */\nexport const run = <Tools extends ReadonlyArray<AnyTool<any>>>(\n  tools: Tools,\n  calls: ReadonlyArray<ToolCall>,\n  options?: ExecuteOptions,\n): Stream.Stream<ToolEvent, never, ToolKindR<Tools>> =>\n  Stream.fromIterable(calls).pipe(\n    Stream.flatMap((call) => runOne(tools, call), {\n      concurrency: options?.concurrency ?? \"unbounded\",\n    }),\n  )\n\nconst okResult = (call: ToolCall, tool: string, value: unknown): ToolResult =>\n  ToolResult.Ok({\n    call_id: call.call_id,\n    tool,\n    value,\n  })\n\nconst runOne = <R>(\n  tools: ReadonlyArray<AnyTool<R>>,\n  call: ToolCall,\n): Stream.Stream<ToolEvent, never, R> => {\n  const tool = tools.find((t) => t.name === call.name)\n  if (tool === undefined) {\n    // Graceful: emit a synthetic Failure so OTHER calls in this turn\n    // still execute. LLMs hallucinate tool names; MCP tools come and go.\n    return Stream.succeed(\n      ToolEvent.Output({\n        result: failed(call, \"unknown_tool\", `No tool registered with name \"${call.name}\"`),\n      }),\n    )\n  }\n  if (isStreamingTool(tool)) return runStreaming(tool, call)\n  return runPlain(tool, call)\n}\n\nconst parseJsonUnknown = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Unknown))\n\nconst runPlain = <R>(tool: AnyPlainTool<R>, call: ToolCall): Stream.Stream<ToolEvent, never, R> =>\n  Stream.fromEffect(\n    Effect.gen(function* () {\n      const parsed = yield* parseJsonUnknown(call.arguments).pipe(\n        Effect.mapError(() => \"json_parse_error\" as const),\n      )\n      const validated = yield* Effect.tryPromise({\n        try: () => Promise.resolve(tool.inputSchema[\"~standard\"].validate(parsed)),\n        catch: () => \"validation_threw\" as const,\n      })\n      if (validated.issues !== undefined) {\n        return executionError(call, \"Tool input failed schema validation\")\n      }\n      const output = yield* tool.run(validated.value)\n      return okResult(call, tool.name, output)\n    }).pipe(\n      Effect.catchCause(() => Effect.succeed(executionError(call, \"Tool execution failed\"))),\n      Effect.map((result) => ToolEvent.Output({ result })),\n    ),\n  )\n\nconst runStreaming = <R>(\n  tool: AnyStreamingTool<R>,\n  call: ToolCall,\n): Stream.Stream<ToolEvent, never, R> =>\n  Stream.unwrap(\n    Effect.gen(function* () {\n      const parsed = yield* parseJsonUnknown(call.arguments).pipe(\n        Effect.mapError(() => \"json_parse_error\" as const),\n      )\n      const validated = yield* Effect.tryPromise({\n        try: () => Promise.resolve(tool.inputSchema[\"~standard\"].validate(parsed)),\n        catch: () => \"validation_threw\" as const,\n      })\n      if (validated.issues !== undefined) {\n        return Stream.succeed<ToolEvent>(\n          ToolEvent.Output({\n            result: executionError(call, \"Tool input failed schema validation\"),\n          }),\n        )\n      }\n\n      // Real-time: tap each event into a Ref as it flows; emit one\n      // Progress per event; then concat one synthetic Output element\n      // built from the accumulated Ref via `finalize`.\n      const ref = yield* Ref.make<Array<unknown>>([])\n      const progress = tool.run(validated.value).pipe(\n        Stream.tap((event) => Ref.update(ref, Arr.append(event))),\n        Stream.map((data) =>\n          ToolEvent.Progress({\n            call_id: call.call_id,\n            tool: tool.name,\n            data,\n          }),\n        ),\n      )\n      const output = Stream.fromEffect(\n        Ref.get(ref).pipe(\n          Effect.map((events) =>\n            ToolEvent.Output({\n              result: okResult(call, tool.name, tool.finalize(events)),\n            }),\n          ),\n        ),\n      )\n      return progress.pipe(Stream.concat(output))\n    }),\n  ).pipe(\n    Stream.catchCause(() =>\n      Stream.succeed(\n        ToolEvent.Output({\n          result: executionError(call, \"Tool execution failed\"),\n        }),\n      ),\n    ),\n  )\n\n// ---------------------------------------------------------------------------\n// `continueWithResults` - bridge from a `Stream<ToolEvent>` to the loop's\n// emit shape. Drains the stream to the consumer in real-time, taps every\n// `Output` into an internal Ref, and at end-of-stream emits\n// `Loop.next(build(results))`. Recipe never sees the Ref.\n//\n// Dual: data-first `continueWithResults(stream, build)` and data-last\n// `stream.pipe(continueWithResults(build))` both work.\n// ---------------------------------------------------------------------------\n\n/**\n * Append a completed turn plus tool results to a state's history, converting\n * the results to wire-format `ToolCallOutput`s. Curried so it slots directly\n * into `continueWithResults`:\n *\n *   Toolkit.run(tools, calls).pipe(\n *     Toolkit.continueWithResults(Toolkit.appendToolResults(state, turn)),\n *   )\n *\n * Equivalent to `appendToHistory(state, turn, results.map(toToolCallOutput))`\n * — the helper just hides the wire-conversion step.\n */\nexport const appendToolResults =\n  <S extends { readonly history: ReadonlyArray<HistoryItem> }>(state: S, turn: Turn) =>\n  (results: ReadonlyArray<ToolResult>): S =>\n    appendToHistory(state, turn, results.map(toToolCallOutput))\n\n/**\n * Drain a `Stream<ToolEvent>` and return the accumulated `ToolResult`s\n * from every `Output` event. One-shot — the type is `Effect<results>`,\n * not a one-element stream — so it composes naturally with `Effect.map`\n * to build state.\n *\n * Counterpart to `continueWithResults`: `continueWithResults` bundles\n * drain + emit Next into one bridge; this one is the right arm of a\n * broadcast/fork-and-merge for callers that want to vary the left arm\n * (e.g., filter/tap ToolEvents before forwarding).\n */\nexport const collectResults = <E, R>(\n  stream: Stream.Stream<ToolEvent, E, R>,\n): Effect.Effect<ReadonlyArray<ToolResult>, E, R> =>\n  stream.pipe(\n    Stream.filter(isOutput),\n    Stream.map((e) => e.result),\n    Stream.runCollect,\n  )\n\n/**\n * Bridge from a `Stream<ToolEvent>` to the loop's emit shape. Forwards\n * every ToolEvent downstream as a `Loop.value` and at end-of-stream emits\n * one `Loop.next(build(results))` carrying the accumulated `ToolResult`s\n * from terminal `Output` events.\n *\n * Conceptually a broadcast fork (one arm passes events through, the other\n * drains them into a state). Implemented as a single-pass Ref tap + concat\n * for zero buffering — the broadcast version is observationally equivalent\n * but holds events in a PubSub until both arms drain. The public primitives\n * (`Loop.value`, `collectResults`, `Loop.next`) compose the same pattern\n * when you need to vary an arm.\n *\n * Dual: data-first `continueWithResults(stream, build)` and data-last\n * `stream.pipe(continueWithResults(build))` both work.\n */\nexport const continueWithResults: {\n  <S>(\n    build: (results: ReadonlyArray<ToolResult>) => S,\n  ): <R>(\n    stream: Stream.Stream<ToolEvent, never, R>,\n  ) => Stream.Stream<Loop.Step<ToolEvent, S>, never, R>\n  <S, R>(\n    stream: Stream.Stream<ToolEvent, never, R>,\n    build: (results: ReadonlyArray<ToolResult>) => S,\n  ): Stream.Stream<Loop.Step<ToolEvent, S>, never, R>\n} = Function.dual(\n  2,\n  <S, R>(\n    stream: Stream.Stream<ToolEvent, never, R>,\n    build: (results: ReadonlyArray<ToolResult>) => S,\n  ): Stream.Stream<Loop.Step<ToolEvent, S>, never, R> =>\n    Stream.unwrap(\n      Effect.gen(function* () {\n        const ref = yield* Ref.make<ReadonlyArray<ToolResult>>([])\n        const tapped = stream.pipe(\n          Stream.tap((e) =>\n            isOutput(e) ? Ref.update(ref, (acc) => Arr.append(acc, e.result)) : Effect.void,\n          ),\n          Stream.map(Loop.value),\n        )\n        const continuation = Stream.unwrap(\n          Ref.get(ref).pipe(Effect.map((acc) => Loop.next(build(acc)))),\n        )\n        return tapped.pipe(Stream.concat(continuation))\n      }),\n    ),\n)\n"],"mappings":"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"}
+{"version":3,"file":"Toolkit.mjs","names":["Arr","Loop.value","Loop.next"],"sources":["../../src/tool/Toolkit.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\"\nimport {\n  Array as Arr,\n  Cause,\n  Data,\n  Effect,\n  Fiber,\n  Function,\n  Match,\n  Option,\n  Queue,\n  Record,\n  Ref,\n  Stream,\n} from \"effect\"\nimport * as Loop from \"../loop/Loop.js\"\nimport type { HistoryItem, ToolCall } from \"../domain/Items.js\"\nimport { appendToHistory, type Turn } from \"../domain/Turn.js\"\nimport {\n  type AnyLocalTool,\n  type AnyTool,\n  type DecodeResult,\n  decodeCallInput,\n  type Emit,\n  type InteractionTool,\n  type ProviderTool,\n  type SignalTool,\n  type Tool,\n  type ToolDescriptor,\n  type ToolE,\n  ToolFailed,\n  type ToolR,\n  toDescriptors,\n} from \"./Tool.js\"\nimport {\n  ToolResult,\n  failed,\n  nonLocalTool,\n  toToolCallOutput,\n  validationError,\n} from \"./ToolResult.js\"\nimport { ToolEvent } from \"./ToolEvent.js\"\nimport { isOutput } from \"./ToolEvent.js\"\n\n// ---------------------------------------------------------------------------\n// Toolkit: a name-indexed record of tools — \"what the model sees\". The record\n// gives O(1) dispatch and within-toolkit name-uniqueness for free; descriptors\n// are derived, not stored. Build a static one with `make` (compile-time\n// duplicate-name check), a dynamic one with `fromArray` (trusted single source,\n// last-wins), and combine independent ones with `compose` (the application\n// boundary where cross-source names can clash).\n// ---------------------------------------------------------------------------\n\nexport type ToolMap = Record<string, AnyTool>\n\nexport type Toolkit<Tools extends ToolMap = ToolMap> = Tools\n\nconst indexByName = (tools: ReadonlyArray<AnyTool>): ToolMap =>\n  Object.fromEntries(tools.map((tool) => [tool.name, tool]))\n\n/**\n * Index literal tools by their `name`. Duplicate names are a compile error\n * (`UniqueTools`). Names are not otherwise checked: a malformed name is a\n * developer typo in a literal that the provider rejects clearly on first use,\n * and there is no single cross-provider name rule to enforce here anyway.\n */\nconst buildStatic = <Tools extends ReadonlyArray<AnyTool>>(\n  tools: Tools,\n): Toolkit<{ [T in Tools[number] as T[\"name\"]]: T }> =>\n  indexByName(tools) as Toolkit<{ [T in Tools[number] as T[\"name\"]]: T }>\n\nexport const make = <const Tools extends ReadonlyArray<AnyTool>>(\n  ...tools: UniqueTools<Tools>\n): Toolkit<{ [T in Tools[number] as T[\"name\"]]: T }> => buildStatic(tools as unknown as Tools)\n\n/**\n * Build a toolkit from a dynamically-sourced array (MCP server, plugin). Names\n * are not validated (MCP legitimately uses dots / >64 chars — sanitize at the\n * provider adapter); same-named tools resolve last-wins. Cross-source clashes\n * are caught by `compose`.\n */\nexport const fromArray = (tools: ReadonlyArray<AnyTool>): Toolkit => indexByName(tools)\n\n/** Render the provider-facing descriptors for a toolkit on demand. */\nexport const descriptors = (toolkit: Toolkit): ReadonlyArray<ToolDescriptor> =>\n  toDescriptors(Object.values(toolkit))\n\n/**\n * Union of every tool's `R` requirements in a toolkit. Surfaced by `run` so the\n * loop's stream type carries the services tools need through to `Effect.provide`.\n *\n * The `ToolMap extends T` guard yields `never` for the wide `Toolkit` type (a\n * toolkit passed through an untyped boundary, where the requirements aren't\n * statically known) instead of `any`, which would otherwise poison the\n * resulting stream's `R`. Concrete toolkits from `make` keep their precise R.\n */\nexport type ToolkitR<T extends Toolkit> = ToolMap extends T ? never : ToolR<T[keyof T]>\n\n/**\n * Union of every tool's `E` error type in a toolkit. `Toolkit.run` reports\n * `Exclude<ToolkitE<T>, string | ToolFailed>` on its stream: the sentinel\n * failures are absorbed into results, everything else propagates typed. The\n * same `ToolMap extends T` guard as `ToolkitR` keeps a wide toolkit at\n * `never` rather than `any`.\n */\nexport type ToolkitE<T extends Toolkit> = ToolMap extends T ? never : ToolE<T[keyof T]>\n\n// ---------------------------------------------------------------------------\n// Uniqueness & composition. `make` rejects duplicate literal names at compile\n// time; `compose` rejects cross-source collisions — at compile time when the\n// names are statically known, and at runtime (`DuplicateToolName`) for dynamic\n// sources whose keys are only `string`. No silent last-wins overwrite, no late\n// provider 400.\n// ---------------------------------------------------------------------------\n\n// --- compile-time duplicate detection --------------------------------------\n\ntype DuplicateName<\n  Tools extends ReadonlyArray<AnyTool>,\n  Seen extends string = never,\n> = Tools extends readonly [\n  infer Head extends AnyTool,\n  ...infer Tail extends ReadonlyArray<AnyTool>,\n]\n  ? Head[\"name\"] extends Seen\n    ? Head[\"name\"]\n    : DuplicateName<Tail, Seen | Head[\"name\"]>\n  : never\n\ntype DuplicateNameError<Name extends string> = {\n  readonly __error: `Duplicate tool name: ${Name}`\n}\n\nexport type NoDuplicateNames<Tools extends ReadonlyArray<AnyTool>> = [\n  DuplicateName<Tools>,\n] extends [never]\n  ? unknown\n  : DuplicateNameError<DuplicateName<Tools>>\n\n/** `Tools` constrained so a repeated literal name is a compile error in `make`. */\nexport type UniqueTools<Tools extends ReadonlyArray<AnyTool>> = Tools & NoDuplicateNames<Tools>\n\n// Cross-toolkit literal-key collision, skipping wide (`string`-keyed, dynamic)\n// toolkits so the compile-time check never false-positives on `fromArray`.\ntype ComposeDuplicateKey<\n  Kits extends ReadonlyArray<Toolkit>,\n  Seen extends string = never,\n> = Kits extends readonly [infer Head extends Toolkit, ...infer Tail extends ReadonlyArray<Toolkit>]\n  ? string extends keyof Head\n    ? ComposeDuplicateKey<Tail, Seen>\n    : Extract<keyof Head & string, Seen> extends never\n      ? ComposeDuplicateKey<Tail, Seen | (keyof Head & string)>\n      : Extract<keyof Head & string, Seen>\n  : never\n\ntype NoDuplicateComposedKeys<Kits extends ReadonlyArray<Toolkit>> = [\n  ComposeDuplicateKey<Kits>,\n] extends [never]\n  ? unknown\n  : DuplicateNameError<ComposeDuplicateKey<Kits>>\n\ntype UnionToIntersection<U> = (U extends unknown ? (x: U) => void : never) extends (\n  x: infer I,\n) => void\n  ? I\n  : never\n\ntype Composed<Kits extends ReadonlyArray<Toolkit>> =\n  UnionToIntersection<Kits[number]> extends infer M ? (M extends ToolMap ? M : ToolMap) : ToolMap\n\n// --- uniqueness error ------------------------------------------------------\n\n/**\n * Two composed toolkits resolved to the same final name. Carries the colliding\n * `sources` (the positions of the clashing toolkits) so the error says *which*\n * inputs collided. Raised at runtime by `compose` for dynamic sources; static\n * collisions are caught earlier at compile time.\n */\nexport class DuplicateToolName extends Data.TaggedError(\"DuplicateToolName\")<{\n  readonly name: string\n  readonly sources: ReadonlyArray<string>\n}> {}\n\n// --- namespacing -----------------------------------------------------------\n\ntype PrefixName<Prefix extends string, Name extends string> = `${Prefix}__${Name}`\n\ntype PrefixTool<Prefix extends string, T extends AnyTool> =\n  T extends Tool<infer N, infer I, infer Ev, infer O, infer R>\n    ? Tool<PrefixName<Prefix, N>, I, Ev, O, R>\n    : T extends ProviderTool<infer N, infer I, infer P, infer C>\n      ? ProviderTool<PrefixName<Prefix, N>, I, P, C>\n      : T extends SignalTool<infer N, infer I>\n        ? SignalTool<PrefixName<Prefix, N>, I>\n        : T extends InteractionTool<infer N, infer I>\n          ? InteractionTool<PrefixName<Prefix, N>, I>\n          : T\n\ntype Namespaced<Prefix extends string, T extends ToolMap> = {\n  readonly [K in keyof T & string as PrefixName<Prefix, K>]: T[K] extends AnyTool\n    ? PrefixTool<Prefix, T[K]>\n    : never\n}\n\n/**\n * Prefix every tool name with `<namespace>__`, returning a new toolkit. Use it\n * to keep generic names (`search`) from two sources distinct before `compose`.\n * If two namespaces collide at the `__` separator, the duplicate final name\n * surfaces from `compose` as a `DuplicateToolName`.\n */\nexport const namespace = <const Prefix extends string, const T extends ToolMap>(\n  prefix: Prefix,\n  toolkit: Toolkit<T>,\n): Toolkit<Namespaced<Prefix, T>> => {\n  const renamed = Arr.map(Record.values(toolkit), (tool) => ({\n    ...tool,\n    name: `${prefix}__${tool.name}`,\n  }))\n  return indexByName(renamed) as Toolkit<Namespaced<Prefix, T>>\n}\n\n/** `namespace(prefix, make(...tools))` in one step, for static namespaced tools. */\nexport const makeNamespaced = <\n  const Prefix extends string,\n  const Tools extends ReadonlyArray<AnyTool>,\n>(\n  prefix: Prefix,\n  ...tools: UniqueTools<Tools>\n): Toolkit<Namespaced<Prefix, { [T in Tools[number] as T[\"name\"]]: T }>> =>\n  namespace(prefix, buildStatic(tools as unknown as Tools))\n\n// --- composition (the application boundary) --------------------------------\n\n/**\n * Combine independently-built toolkits into one. This is where names from\n * separate sources can collide, so it is the one effectful constructor: a\n * duplicate final name fails with `DuplicateToolName` (naming the colliding\n * input positions) instead of silently overwriting or 400-ing later at the\n * provider. Statically-known collisions are additionally a compile error.\n */\nexport const compose = <const Kits extends ReadonlyArray<Toolkit>>(\n  ...toolkits: Kits & NoDuplicateComposedKeys<Kits>\n): Effect.Effect<Toolkit<Composed<Kits>>, DuplicateToolName> =>\n  Effect.gen(function* () {\n    const kits = toolkits as unknown as ReadonlyArray<Toolkit>\n    const labelled = Arr.flatMap(kits, (kit, i) =>\n      Arr.map(Record.keys(kit), (name) => ({ name, source: `toolkit-${i}` })),\n    )\n    const collision = Arr.findFirst(\n      Record.toEntries(Arr.groupBy(labelled, (entry) => entry.name)),\n      ([, group]) => group.length > 1,\n    )\n    if (Option.isSome(collision)) {\n      const [name, group] = collision.value\n      return yield* new DuplicateToolName({ name, sources: Arr.map(group, (e) => e.source) })\n    }\n    return Arr.reduce(kits, {} as ToolMap, (acc, kit) => ({ ...acc, ...kit })) as Toolkit<\n      Composed<Kits>\n    >\n  })\n\n// ---------------------------------------------------------------------------\n// Middleware: a `Toolkit -> Toolkit` transform applied up front, then the\n// wrapped toolkit is run. A middleware transforms one local tool's `run` given\n// its name (logging, retry, auth, metrics); `wrap` lifts it over the whole\n// toolkit, leaving provider/signal/interaction kinds untouched. The one reason\n// this is a combinator rather than native `Record.map`: it tracks the\n// middleware's added requirement `R2`, unioning it into `ToolkitR` instead of\n// widening every tool's type.\n// ---------------------------------------------------------------------------\n\ntype Handler<Input, Event, Output, E, R> = (\n  input: Input,\n  emit: Emit<Event>,\n) => Effect.Effect<Output, E, R>\n\n/**\n * A `run` transform, tracking an added requirement `R2` and optional added\n * error `E2`. The tool's own `E` is preserved; `describeFailures` is the\n * combinator that *replaces* it (mapping every error to `string`).\n */\nexport type Middleware<R2 = never, E2 = never> = <Input, Event, Output, E, R>(\n  run: Handler<Input, Event, Output, E, R>,\n  name: string,\n) => Handler<Input, Event, Output, E | E2, R | R2>\n\ntype WrapTool<T extends AnyTool, R2, E2> =\n  T extends Tool<infer N, infer I, infer Ev, infer O, infer E, infer R>\n    ? Tool<N, I, Ev, O, E | E2, R | R2>\n    : T\n\ntype WrapToolkit<T extends ToolMap, R2, E2> = {\n  readonly [K in keyof T]: T[K] extends AnyTool ? WrapTool<T[K], R2, E2> : T[K]\n}\n\n/**\n * Wrap every local tool's `run` with a middleware, preserving each tool's\n * `Input`/`Output` and unioning the middleware's requirement `R2` into the\n * toolkit's `ToolkitR`. Non-local kinds pass through unchanged. Stack with\n * `pipe` - inner-first, so the last `wrap` applied is the outermost and runs\n * first:\n *\n *   const observed = pipe(toolkit, Toolkit.wrap(logging), Toolkit.wrap(authz))\n *   Toolkit.run(observed, calls) // authz runs, then logging, then the tool\n *\n * A middleware that fails with `string` / `ToolFailed` is absorbed by the\n * executor into a `ToolResult.Failure`; any other error propagates typed. Use\n * `describeFailures` for the total \"everything to the model\" case, or the\n * `Approval` flow for a distinct \"denied\" verdict.\n */\nexport const wrap: {\n  <R2, E2>(\n    middleware: Middleware<R2, E2>,\n  ): <T extends Toolkit>(toolkit: T) => WrapToolkit<T, R2, E2>\n  <T extends Toolkit, R2, E2>(toolkit: T, middleware: Middleware<R2, E2>): WrapToolkit<T, R2, E2>\n} = Function.dual(\n  2,\n  <T extends Toolkit, R2, E2>(toolkit: T, middleware: Middleware<R2, E2>): WrapToolkit<T, R2, E2> =>\n    Record.map(toolkit, (tool) =>\n      tool._tag === \"LocalTool\" ? { ...tool, run: middleware(tool.run, tool.name) } : tool,\n    ) as WrapToolkit<T, R2, E2>,\n)\n\n// ---------------------------------------------------------------------------\n// describeFailures: map every local tool's error to a model-visible string,\n// opting its failures into recovery. Group tools by recovery policy, wrap\n// each group, then compose.\n// ---------------------------------------------------------------------------\n\ntype DescribeTool<T extends AnyTool> =\n  T extends Tool<infer N, infer I, infer Ev, infer O, any, infer R>\n    ? Tool<N, I, Ev, O, string, R>\n    : T\n\ntype DescribeToolkit<T extends ToolMap> = {\n  readonly [K in keyof T]: T[K] extends AnyTool ? DescribeTool<T[K]> : T[K]\n}\n\n/**\n * Map every local tool's error to a `string`, so `Toolkit.run` absorbs those\n * failures into `ToolResult.Failure` the model reads and adapts to. Pairs\n * with the domain `describe` helpers (`AiError.describe`,\n * `BrowserError.describe`). Non-local kinds pass through.\n *\n *   const kit = yield* Toolkit.compose(\n *     Toolkit.describeFailures(searchKit, AiError.describe),\n *     browserToolkit(session), // failures stay typed\n *   )\n */\nexport const describeFailures: {\n  <E>(describe: (e: E) => string): <T extends Toolkit>(toolkit: T) => DescribeToolkit<T>\n  <T extends Toolkit>(toolkit: T, describe: (e: ToolkitE<T>) => string): DescribeToolkit<T>\n} = Function.dual(\n  2,\n  <T extends Toolkit>(toolkit: T, describe: (e: any) => string): DescribeToolkit<T> =>\n    Record.map(toolkit, (tool) =>\n      tool._tag === \"LocalTool\"\n        ? {\n            ...tool,\n            run: (input: unknown, emit: Emit<unknown>) =>\n              (tool as AnyLocalTool).run(input, emit).pipe(Effect.mapError(describe)),\n          }\n        : tool,\n    ) as DescribeToolkit<T>,\n)\n\n// ---------------------------------------------------------------------------\n// Tool executor. Streams `ToolEvent`s in real time. Policy stays outside this\n// module: callers pass only the calls they have already decided should run.\n// ---------------------------------------------------------------------------\n\nexport type ExecuteOptions = {\n  readonly concurrency?: number | \"unbounded\"\n}\n\n/**\n * Execute every provided call. Approval/rejection policy belongs upstream.\n *\n * String and `ToolFailed` failures are absorbed into `ToolResult.Failure`\n * (the model reads and adapts to them); every other tool error propagates\n * typed on the stream, so `Exclude<ToolkitE<T>, string | ToolFailed>` is\n * what a caller catches or lets end the run. If one call in a concurrent\n * batch fails the stream, siblings may go unanswered: a loop that catches\n * and continues must reconcile history first (`HistoryCheck.cancelAllPending`).\n */\nexport const run = <T extends Toolkit>(\n  toolkit: T,\n  calls: ReadonlyArray<ToolCall>,\n  options?: ExecuteOptions,\n): Stream.Stream<ToolEvent, Exclude<ToolkitE<T>, string | ToolFailed>, ToolkitR<T>> =>\n  Stream.fromIterable(calls).pipe(\n    Stream.flatMap((call) => runOne(toolkit, call), {\n      concurrency: options?.concurrency ?? \"unbounded\",\n    }),\n  ) as Stream.Stream<ToolEvent, Exclude<ToolkitE<T>, string | ToolFailed>, ToolkitR<T>>\n\nconst okResult = (call: ToolCall, tool: string, value: unknown): ToolResult =>\n  ToolResult.Ok({ call_id: call.call_id, tool, value })\n\nconst outputEvent = (result: ToolResult): Stream.Stream<ToolEvent, never, any> =>\n  Stream.succeed(ToolEvent.Output({ result }))\n\nconst runOne = (toolkit: ToolMap, call: ToolCall): Stream.Stream<ToolEvent, unknown, any> => {\n  // Own-property lookup: a hallucinated call named `constructor` / `toString`\n  // must not resolve to a prototype method.\n  const tool = Object.hasOwn(toolkit, call.name) ? toolkit[call.name] : undefined\n  return Match.value(tool).pipe(\n    // No such tool. Graceful: emit a synthetic Failure so OTHER calls in this\n    // turn still execute. LLMs hallucinate tool names; MCP tools come and go.\n    Match.when(Match.undefined, () =>\n      outputEvent(failed(call, \"unknown_tool\", `No tool registered with name \"${call.name}\"`)),\n    ),\n    Match.tag(\"LocalTool\", (local) => runTool(local, call)),\n    // Provider/signal/interaction tools are model-visible but not locally\n    // executable. The loop is expected to intercept these (decode + act) before\n    // execution; reaching here means it didn't, so report it rather than crash.\n    Match.orElse(() => outputEvent(nonLocalTool(call))),\n  )\n}\n\nconst describeIssues = (issues: ReadonlyArray<StandardSchemaV1.Issue>): string =>\n  issues\n    .map((issue) => {\n      const path = (issue.path ?? [])\n        .map((seg) => (typeof seg === \"object\" && seg !== null ? String(seg.key) : String(seg)))\n        .join(\".\")\n      return path === \"\" ? issue.message : `${path}: ${issue.message}`\n    })\n    .join(\"; \")\n    .slice(0, 500)\n\n// A decode failure is the model's contract violation: report it as a result\n// (never a stream failure) so the model can correct its next call.\nconst runTool = (tool: AnyLocalTool, call: ToolCall): Stream.Stream<ToolEvent, unknown, any> =>\n  Stream.unwrap(\n    decodeCallInput(tool, call).pipe(\n      Effect.map(\n        Match.type<DecodeResult<unknown>>().pipe(\n          Match.tag(\"parseError\", () =>\n            outputEvent(validationError(call, \"arguments are not valid JSON\")),\n          ),\n          Match.tag(\"invalid\", ({ issues }) =>\n            outputEvent(validationError(call, describeIssues(issues))),\n          ),\n          Match.tag(\"ok\", ({ input }) => runValidated(tool, call, input)),\n          Match.exhaustive,\n        ),\n      ),\n    ),\n  )\n\nconst runValidated = (\n  tool: AnyLocalTool,\n  call: ToolCall,\n  input: unknown,\n): Stream.Stream<ToolEvent, unknown, any> =>\n  Stream.unwrap(\n    Effect.gen(function* () {\n      // Per-call queue: `emit` offers events as `run` produces them; the\n      // progress stream drains them in real time; `Queue.end` (in the\n      // `ensuring`) flushes pending events then signals a clean end, which\n      // `Stream.fromQueue` treats as completion. `Queue.shutdown` would clear\n      // queued items and interrupt pending takes — wrong for graceful teardown.\n      const queue = yield* Queue.make<unknown, Cause.Done>({ capacity: tool.emitBufferSize })\n      const emit = (event: unknown) => Effect.asVoid(Queue.offer(queue, event))\n      const fiber = yield* tool\n        .run(input, emit)\n        .pipe(Effect.ensuring(Queue.end(queue)), Effect.forkScoped)\n\n      const progress = Stream.fromQueue(queue).pipe(\n        Stream.map((data) => ToolEvent.Progress({ call_id: call.call_id, tool: tool.name, data })),\n      )\n      const output = Stream.fromEffect(\n        Fiber.join(fiber).pipe(\n          Effect.matchCauseEffect({\n            onSuccess: (value: unknown) =>\n              Effect.succeed(ToolEvent.Output({ result: okResult(call, tool.name, value) })),\n            onFailure: (cause: Cause.Cause<unknown>) => routeCause(call, cause),\n          }),\n        ),\n      )\n      return progress.pipe(Stream.concat(output))\n    }),\n  )\n\n// A clean single string / ToolFailed failure is absorbed as a model-visible\n// result; interruption, defects, and typed non-sentinel errors propagate.\nconst routeCause = (\n  call: ToolCall,\n  cause: Cause.Cause<unknown>,\n): Effect.Effect<ToolEvent, unknown> => {\n  const only = cause.reasons.length === 1 ? cause.reasons[0] : undefined\n  if (only !== undefined && Cause.isFailReason(only)) {\n    const error = only.error\n    if (typeof error === \"string\") {\n      return Effect.succeed(ToolEvent.Output({ result: failed(call, \"tool_failed\", error) }))\n    }\n    if (error instanceof ToolFailed) {\n      return Effect.succeed(\n        ToolEvent.Output({ result: failed(call, error.kind ?? \"tool_failed\", error.message) }),\n      )\n    }\n  }\n  return Effect.failCause(cause)\n}\n\n// ---------------------------------------------------------------------------\n// `continueWithResults` - bridge from a `Stream<ToolEvent>` to the loop's\n// emit shape. Drains the stream to the consumer in real-time, taps every\n// `Output` into an internal Ref, and at end-of-stream emits\n// `Loop.next(build(results))`. Recipe never sees the Ref.\n//\n// Dual: data-first `continueWithResults(stream, build)` and data-last\n// `stream.pipe(continueWithResults(build))` both work.\n// ---------------------------------------------------------------------------\n\n/**\n * Append a completed turn plus tool results to a state's history, converting\n * the results to wire-format `ToolCallOutput`s. Curried so it slots directly\n * into `continueWithResults`:\n *\n *   Toolkit.run(toolkit, calls).pipe(\n *     Toolkit.continueWithResults(Toolkit.appendToolResults(state, turn)),\n *   )\n *\n * Equivalent to `appendToHistory(state, turn, results.map(toToolCallOutput))`\n * — the helper just hides the wire-conversion step.\n */\nexport const appendToolResults =\n  <S extends { readonly history: ReadonlyArray<HistoryItem> }>(state: S, turn: Turn) =>\n  (results: ReadonlyArray<ToolResult>): S =>\n    appendToHistory(state, turn, results.map(toToolCallOutput))\n\n/**\n * Drain a `Stream<ToolEvent>` and return the accumulated `ToolResult`s\n * from every `Output` event. One-shot — the type is `Effect<results>`,\n * not a one-element stream — so it composes naturally with `Effect.map`\n * to build state.\n *\n * Counterpart to `continueWithResults`: `continueWithResults` bundles\n * drain + emit Next into one bridge; this one is the right arm of a\n * broadcast/fork-and-merge for callers that want to vary the left arm\n * (e.g., filter/tap ToolEvents before forwarding).\n */\nexport const collectResults = <E, R>(\n  stream: Stream.Stream<ToolEvent, E, R>,\n): Effect.Effect<ReadonlyArray<ToolResult>, E, R> =>\n  stream.pipe(\n    Stream.filter(isOutput),\n    Stream.map((e) => e.result),\n    Stream.runCollect,\n  )\n\n/**\n * Bridge from a `Stream<ToolEvent>` to the loop's emit shape. Forwards\n * every ToolEvent downstream as a `Loop.value` and at end-of-stream emits\n * one `Loop.next(build(results))` carrying the accumulated `ToolResult`s\n * from terminal `Output` events.\n *\n * Conceptually a broadcast fork (one arm passes events through, the other\n * drains them into a state). Implemented as a single-pass Ref tap + concat\n * for zero buffering — the broadcast version is observationally equivalent\n * but holds events in a PubSub until both arms drain. The public primitives\n * (`Loop.value`, `collectResults`, `Loop.next`) compose the same pattern\n * when you need to vary an arm.\n *\n * Dual: data-first `continueWithResults(stream, build)` and data-last\n * `stream.pipe(continueWithResults(build))` both work.\n */\nexport const continueWithResults: {\n  <S>(\n    build: (results: ReadonlyArray<ToolResult>) => S,\n  ): <E, R>(stream: Stream.Stream<ToolEvent, E, R>) => Stream.Stream<Loop.Step<ToolEvent, S>, E, R>\n  <S, E, R>(\n    stream: Stream.Stream<ToolEvent, E, R>,\n    build: (results: ReadonlyArray<ToolResult>) => S,\n  ): Stream.Stream<Loop.Step<ToolEvent, S>, E, R>\n} = Function.dual(\n  2,\n  <S, E, R>(\n    stream: Stream.Stream<ToolEvent, E, R>,\n    build: (results: ReadonlyArray<ToolResult>) => S,\n  ): Stream.Stream<Loop.Step<ToolEvent, S>, E, R> =>\n    Stream.unwrap(\n      Effect.gen(function* () {\n        const ref = yield* Ref.make<ReadonlyArray<ToolResult>>([])\n        const tapped = stream.pipe(\n          Stream.tap((e) =>\n            isOutput(e) ? Ref.update(ref, (acc) => Arr.append(acc, e.result)) : Effect.void,\n          ),\n          Stream.map(Loop.value),\n        )\n        const continuation = Stream.unwrap(\n          Ref.get(ref).pipe(Effect.map((acc) => Loop.next(build(acc)))),\n        )\n        return tapped.pipe(Stream.concat(continuation))\n      }),\n    ),\n)\n"],"mappings":"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"}