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

package/dist/tool/Toolkit.test.mjs

@@ -1,434 +1,476 @@
-import { RateLimited, describe } from "../domain/AiError.mjs";
-import { isFailure, isOk, toToolCallOutput } from "./ToolResult.mjs";
-import { fail, fromEffectSchema, make, provider, signal, toDescriptors } from "./Tool.mjs";
-import { isOutput, isProgress } from "./ToolEvent.mjs";
-import { compose, describeFailures, fromArray, make as make$1, makeNamespaced, namespace, run, wrap } from "./Toolkit.mjs";
-import { b as it, m as describe$1 } from "../dist-DzeSyeYF.mjs";
+import { ToolFailed, declare, make, noInput, withFailures } from "./Tool.mjs";
+import { imageBytes } from "../domain/Image.mjs";
+import { Value, image } from "./Content.mjs";
+import { Cancelled, CoreError, InputInvalid, OutputInvalid, failure } from "./ToolOutput.mjs";
+import { DuplicateToolName, UndeclaredFailure, close, complete, compose, decode, describeFailures, fromArray, isOutcome, make as make$1, makeNamespaced, namespace, next, output, run, split, withFailures as withFailures$1, wrap } from "./Toolkit.mjs";
+import { m as describe } from "../dist-DzeSyeYF.mjs";
 import { n as globalExpect } from "../index.C4tKZ0yW-LuFnBtmu.mjs";
 import { t as import_dist } from "../dist-DNeuh84d.mjs";
-import { Context, Effect, Layer, Schema, Stream, pipe } from "effect";
+import { t as it } from "../dist-B5K-y4Be.mjs";
+import { Cause, Context, Deferred, Effect, Exit, Layer, Match, Result, Schema, Stream, pipe } from "effect";
 //#region src/tool/Toolkit.test.ts
-const Empty = Schema.Struct({});
-const toolCall = (name, id, args = "{}") => ({
+const call = (name, id, args = "{}") => ({
 	type: "function_call",
 	call_id: id,
 	name,
 	arguments: args
 });
-const runToArray = (toolkit, calls, options) => run(toolkit, calls, options).pipe(Stream.runCollect, Effect.map((events) => Array.from(events)));
-describe$1("Tool.toDescriptors", () => {
-	const GetWeatherInput = Schema.Struct({ city: Schema.String });
-	const getWeather = make({
-		name: "get_weather",
-		description: "Look up the current temperature for a city.",
-		inputSchema: fromEffectSchema(GetWeatherInput),
-		run: ({ city }) => Effect.succeed({
+const collect = (toolkit, calls, options) => Stream.runCollect(run(toolkit, calls, options));
+const outcomes = (toolkit, calls) => run(toolkit, calls, { concurrency: 1 }).pipe(Stream.filter(isOutcome), Stream.runCollect);
+const failureOf = (r) => r._tag === "Failure" ? r.failure : void 0;
+var CityNotFound = class extends Schema.TaggedError()("CityNotFound", { city: Schema.String }) {};
+var ApiDown = class extends Schema.TaggedError()("ApiDown", {}) {};
+const Weather = Schema.Struct({
+	city: Schema.String,
+	at: Schema.DateFromString
+});
+const at = /* @__PURE__ */ new Date("2026-01-01T12:00:00.000Z");
+const weather = make({
+	name: "weather",
+	description: "Weather for a city.",
+	inputSchema: Schema.Struct({ city: Schema.String }),
+	outputSchema: Weather,
+	failureSchema: CityNotFound,
+	run: ({ city }) => Effect.gen(function* () {
+		if (city === "Atlantis") return yield* new CityNotFound({ city });
+		if (city === "down") return yield* new ApiDown();
+		if (city === "bug") return yield* Effect.die("defect");
+		return {
 			city,
-			tempC: 18
-		})
-	});
-	it("renders the input schema as a JSON Schema document", () => {
-		const [desc] = toDescriptors([getWeather]);
-		globalExpect(desc?.name).toBe("get_weather");
-		globalExpect(desc?.description).toBe("Look up the current temperature for a city.");
-		globalExpect(desc?.inputSchema).toMatchObject({
-			type: "object",
-			properties: { city: { type: "string" } },
-			required: ["city"]
-		});
-	});
-	it("includes strict flag only when set on the tool", () => {
-		const strictTool = make({
-			name: "strict_one",
+			at
+		};
+	})
+});
+const search = make({
+	name: "search",
+	description: "Search, reporting hits as it reads pages.",
+	inputSchema: Schema.Struct({ query: Schema.String }),
+	outputSchema: Schema.Struct({ hits: Schema.Number }),
+	run: () => Stream.fromIterable([
+		{ hits: 1 },
+		{ hits: 3 },
+		{ hits: 4 }
+	])
+});
+const escalate = declare({
+	name: "escalate",
+	description: "",
+	inputSchema: noInput
+});
+const kit = make$1(weather, search, escalate);
+describe("Toolkit.run", () => {
+	it.effect("emits each of a Stream tool's values as a partial, then the last as the result", () => Effect.gen(function* () {
+		const events = yield* collect(kit, [call("search", "s1", "{\"query\":\"x\"}")]);
+		globalExpect(events.map((e) => e._tag === "Partial" ? e.value : e.result)).toEqual([
+			{ hits: 1 },
+			{ hits: 3 },
+			{ hits: 4 },
+			Result.succeed({ hits: 4 })
+		]);
+	}));
+	it.effect("emits a partial as soon as the tool produces it, not when the next arrives", () => Effect.gen(function* () {
+		const gate = yield* Deferred.make();
+		const slow = make({
+			name: "slow",
 			description: "",
-			inputSchema: fromEffectSchema(GetWeatherInput),
-			run: () => Effect.succeed({}),
-			strict: true
+			inputSchema: noInput,
+			outputSchema: Schema.String,
+			run: () => Stream.concat(Stream.succeed("searching..."), Stream.fromEffect(Effect.as(Deferred.await(gate), "found")))
 		});
-		const looseTool = make({
-			name: "loose_one",
+		const events = yield* run(make$1(slow), [call("slow", "1")]).pipe(Stream.tap((e) => e._tag === "Partial" && e.value === "searching..." ? Deferred.succeed(gate, void 0) : Effect.void), Stream.runCollect);
+		globalExpect(events.map((e) => e._tag === "Partial" ? e.value : e.result)).toEqual([
+			"searching...",
+			"found",
+			Result.succeed("found")
+		]);
+	}));
+	it.effect("an Effect tool emits only its result, also after describeFailures", () => Effect.gen(function* () {
+		const lisbon = [call("weather", "w1", "{\"city\":\"Lisbon\"}")];
+		const plain = yield* collect(kit, lisbon);
+		const described = yield* collect(describeFailures(kit, () => "failed"), lisbon);
+		globalExpect(plain.map((e) => e._tag)).toEqual(["Output"]);
+		globalExpect(described.map((e) => e._tag)).toEqual(["Output"]);
+	}));
+	it.effect("hands on decoded values: a DateFromString field stays a Date", () => Effect.gen(function* () {
+		const [event] = yield* outcomes(kit, [call("weather", "w1", "{\"city\":\"Lisbon\"}")]);
+		globalExpect(event?.result).toEqual(Result.succeed({
+			city: "Lisbon",
+			at
+		}));
+	}));
+	it.effect("a declared error becomes a Failure; an undeclared one fails the stream", () => Effect.gen(function* () {
+		const [event] = yield* outcomes(kit, [call("weather", "w1", "{\"city\":\"Atlantis\"}")]);
+		globalExpect(failureOf(event.result)).toEqual(new CityNotFound({ city: "Atlantis" }));
+		const down = yield* Effect.flip(collect(kit, [call("weather", "w2", "{\"city\":\"down\"}")]));
+		globalExpect(down).toEqual(new ApiDown());
+		const bug = yield* Effect.exit(collect(kit, [call("weather", "w3", "{\"city\":\"bug\"}")]));
+		globalExpect(Exit.isFailure(bug) && Cause.hasDies(bug.cause)).toBe(true);
+	}));
+	it.effect("reports what it could not run as core errors, without stopping other calls", () => Effect.gen(function* () {
+		const events = yield* outcomes(kit, [
+			call("weather", "1", "{\"city\":7}"),
+			call("weather", "2", "not json"),
+			call("nope", "3"),
+			call("escalate", "4"),
+			call("constructor", "5"),
+			call("search", "6", "{\"query\":\"x\"}")
+		]);
+		globalExpect(events.map((e) => failureOf(e.result)?._tag)).toEqual([
+			"InputInvalid",
+			"InputInvalid",
+			"UnknownTool",
+			"UnknownTool",
+			"UnknownTool",
+			void 0
+		]);
+		globalExpect(failureOf(events[0].result)).toMatchObject({ message: globalExpect.stringContaining("city") });
+	}));
+	it.effect("reports a value outputSchema rejects, or no value at all, as OutputInvalid", () => Effect.gen(function* () {
+		const count = (values) => make({
+			name: "count",
 			description: "",
-			inputSchema: fromEffectSchema(GetWeatherInput),
-			run: () => Effect.succeed({})
-		});
-		const [s, l] = toDescriptors([strictTool, looseTool]);
-		globalExpect(s?.strict).toBe(true);
-		globalExpect(l).not.toHaveProperty("strict");
-	});
-});
-describe$1("Toolkit.run - tools with R requirements", () => {
-	class WeatherApiKey extends Context.Service()("test/WeatherApiKey") {}
-	class GeoApiKey extends Context.Service()("test/GeoApiKey") {}
-	const Empty = Schema.Struct({});
-	const getWeather = make({
-		name: "get_weather",
-		description: "",
-		inputSchema: fromEffectSchema(Empty),
-		run: () => Effect.gen(function* () {
-			const { key } = yield* WeatherApiKey;
-			return {
-				source: "weather",
-				key
-			};
-		})
-	});
-	const getCoords = make({
-		name: "get_coords",
-		description: "",
-		inputSchema: fromEffectSchema(Empty),
-		run: () => Effect.gen(function* () {
-			const { key } = yield* GeoApiKey;
-			return {
-				source: "geo",
-				key
-			};
-		})
-	});
-	const call = (name, id) => ({
-		type: "function_call",
-		call_id: id,
-		name,
-		arguments: "{}"
-	});
-	it("propagates each tool's R into the resulting Stream's requirements", () => {
-		const stream = run(make$1(getWeather, getCoords), []);
-		(0, import_dist.expectTypeOf)(stream).toEqualTypeOf();
-	});
-	it("runs each tool with its own service injected", async () => {
-		const layer = Layer.mergeAll(Layer.succeed(WeatherApiKey, { key: "weather-123" }), Layer.succeed(GeoApiKey, { key: "geo-456" }));
-		const program = run(make$1(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);
-		const byCall = new Map(outputs.map((e) => [e.result.call_id, e.result]));
-		const w = byCall.get("c1");
-		const g = byCall.get("c2");
-		globalExpect(w !== void 0 && isOk(w) && w.value).toEqual({
-			source: "weather",
-			key: "weather-123"
-		});
-		globalExpect(g !== void 0 && isOk(g) && g.value).toEqual({
-			source: "geo",
-			key: "geo-456"
+			inputSchema: noInput,
+			outputSchema: Schema.Int,
+			run: () => Stream.fromIterable(values)
 		});
+		const [rejected] = yield* outcomes(make$1(count([1, 1.5])), [call("count", "1")]);
+		const [empty] = yield* outcomes(make$1(count([])), [call("count", "2")]);
+		globalExpect(failureOf(rejected.result)).toBeInstanceOf(OutputInvalid);
+		globalExpect(failureOf(empty.result)).toBeInstanceOf(OutputInvalid);
+	}));
+	it("type: events narrow per tool, the stream fails with each tool's undeclared errors", () => {
+		run(kit, []);
+		(0, import_dist.expectTypeOf)().toEqualTypeOf();
+		(0, import_dist.expectTypeOf)().toEqualTypeOf();
+		(0, import_dist.expectTypeOf)().toEqualTypeOf();
 	});
-	it("reports non-local kinds as non_local_tool while local calls in the same turn still run", async () => {
-		const escalate = signal({
-			name: "escalate",
+	it("type: an error one tool declares still fails the stream when another throws it", () => {
+		make({
+			name: "loose",
 			description: "",
-			inputSchema: fromEffectSchema(Empty)
+			inputSchema: noInput,
+			outputSchema: Schema.String,
+			run: () => Effect.fail(new CityNotFound({ city: "x" }))
 		});
-		const localPlain = make({
-			name: "plain",
-			description: "",
-			inputSchema: fromEffectSchema(Empty),
-			run: () => Effect.succeed({ ok: true })
-		});
-		const events = await Effect.runPromise(run(make$1(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]));
-		const s = byCall.get("s1");
-		globalExpect(s?._tag === "Failure" && s.kind).toBe("non_local_tool");
-		const g = byCall.get("g1");
-		globalExpect(g?._tag === "Failure" && g.kind).toBe("unknown_tool");
-		const p = byCall.get("p1");
-		globalExpect(p !== void 0 && isOk(p) && p.value).toEqual({ ok: true });
+		(0, import_dist.expectTypeOf)().toEqualTypeOf();
 	});
-	it("with no service-needing tools, R is never", () => {
-		const plain = make({
-			name: "plain",
+	it.effect("provides each tool's own requirements", () => Effect.gen(function* () {
+		class Geo extends Context.Service()("test/Geo") {}
+		const where = make({
+			name: "where",
 			description: "",
-			inputSchema: fromEffectSchema(Empty),
-			run: () => Effect.succeed(0)
+			inputSchema: noInput,
+			outputSchema: Schema.String,
+			run: () => Effect.gen(function* () {
+				return (yield* Geo).place;
+			})
 		});
-		const stream = run(make$1(plain), []);
-		(0, import_dist.expectTypeOf)(stream).toEqualTypeOf();
-	});
+		const stream = run(make$1(where), [call("where", "1")]);
+		(0, import_dist.expectTypeOf)().toEqualTypeOf();
+		const [event] = yield* stream.pipe(Stream.filter(isOutcome), Stream.runCollect, Effect.provide(Layer.succeed(Geo, { place: "Lisbon" })));
+		globalExpect(event?.result).toEqual(Result.succeed("Lisbon"));
+	}));
 });
-describe$1("Toolkit.make / compose / namespace - uniqueness", () => {
-	const Empty = Schema.Struct({});
-	const tool = (name) => make({
-		name,
-		description: "",
-		inputSchema: fromEffectSchema(Empty),
-		run: () => Effect.succeed(0)
-	});
-	it("rejects a duplicate literal name at compile time", () => {
-		const a = tool("search");
-		const b = provider({
-			name: "search",
+describe("Toolkit.output and Toolkit.decode", () => {
+	it.effect("encode with the tool's schemas and decode back to the same typed Result", () => Effect.gen(function* () {
+		const events = yield* outcomes(kit, [call("weather", "1", "{\"city\":\"Lisbon\"}"), call("weather", "2", "{\"city\":\"Atlantis\"}")]);
+		const items = yield* Effect.forEach(events, output(kit));
+		globalExpect(items.map((i) => [i.output, i.isError])).toEqual([[[{
+			type: "input_json",
+			value: {
+				city: "Lisbon",
+				at: at.toISOString()
+			}
+		}], void 0], [[{
+			type: "input_json",
+			value: {
+				_tag: "CityNotFound",
+				city: "Atlantis"
+			}
+		}], true]]);
+		const decoded = yield* Effect.forEach(items, (item) => decode(kit, "weather", item));
+		globalExpect(decoded).toEqual(events.map((e) => e.result));
+		(0, import_dist.expectTypeOf)(decoded[0]).toEqualTypeOf();
+	}));
+	it.effect("with Content.Value, media gets its own part and reads back as a class", () => Effect.gen(function* () {
+		const png = image(imageBytes(new Uint8Array([1, 2]), "image/png"));
+		const shot = make({
+			name: "shot",
 			description: "",
-			inputSchema: fromEffectSchema(Empty),
-			provider: "demo",
-			config: {}
-		});
-		make$1(a, b);
-	});
-	it("fails compose with DuplicateToolName naming the colliding sources (dynamic)", async () => {
-		const github = fromArray([tool("search")]);
-		const linear = fromArray([tool("search")]);
-		const exit = await Effect.runPromiseExit(compose(github, linear));
-		globalExpect(exit._tag).toBe("Failure");
-		if (exit._tag === "Failure") {
-			const json = JSON.stringify(exit.cause);
-			globalExpect(json).toContain("DuplicateToolName");
-			globalExpect(json).toContain("toolkit-0");
-			globalExpect(json).toContain("toolkit-1");
-		}
-	});
-	it("namespaces names so generic names from two sources compose cleanly", async () => {
-		const github = namespace("github", fromArray([tool("search")]));
-		const linear = namespace("linear", fromArray([tool("search")]));
-		const composed = await Effect.runPromise(compose(github, linear));
-		globalExpect(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* compose(make$1(tool("a")), make$1(tool("b")));
-			return run(composed, []);
+			inputSchema: noInput,
+			outputSchema: Value,
+			run: () => Effect.succeed([{ title: "Home" }, png])
 		});
-		(0, import_dist.expectTypeOf)(stream).toEqualTypeOf();
-	});
+		const shots = make$1(shot);
+		const [event] = yield* outcomes(shots, [call("shot", "1")]);
+		const item = yield* output(shots, event);
+		globalExpect(item.output.map((p) => p.type)).toEqual(["input_json", "input_image"]);
+		globalExpect(yield* decode(shots, "shot", item)).toEqual(Result.succeed([{ title: "Home" }, png]));
+	}));
+	it.effect("decodes a call closed with core's Cancelled", () => Effect.gen(function* () {
+		const cancelled = new Cancelled({ message: "user moved on" });
+		const item = yield* failure({ call_id: "1" }, CoreError, cancelled);
+		globalExpect(yield* decode(kit, "weather", item)).toEqual(Result.fail(cancelled));
+	}));
 });
-describe$1("Toolkit.namespace - typed toolkits", () => {
-	const Query = Schema.Struct({ q: Schema.String });
-	class Geo extends Context.Service()("test/Geo") {}
-	const search = make({
-		name: "search",
-		description: "",
-		inputSchema: fromEffectSchema(Query),
-		run: ({ q }) => Effect.gen(function* () {
-			const geo = yield* Geo;
-			if (q === "") return yield* Effect.fail("empty_query");
-			return yield* geo.lookup(q);
-		})
-	});
-	const kit = namespace("geo", make$1(search));
-	it("type: prefixes the name literal of a service-requiring tool", () => {
-		(0, import_dist.expectTypeOf)(kit.geo__search.name).toEqualTypeOf();
-	});
-	it("type: preserves E and R through namespace", () => {
-		(0, import_dist.expectTypeOf)().toEqualTypeOf();
-		(0, import_dist.expectTypeOf)().toEqualTypeOf();
-	});
-	it("type: preserves E and R through makeNamespaced", () => {
-		const namespaced = makeNamespaced("geo", search);
-		(0, import_dist.expectTypeOf)(namespaced.geo__search.name).toEqualTypeOf();
-		(0, import_dist.expectTypeOf)().toEqualTypeOf();
-		(0, import_dist.expectTypeOf)().toEqualTypeOf();
-	});
-	it("type: Toolkit.run surfaces the namespaced tool's R (string E is absorbed)", () => {
-		const stream = run(kit, []);
-		(0, import_dist.expectTypeOf)(stream).toEqualTypeOf();
-	});
-	it("runtime: renames the tool and executes it under the prefixed name", async () => {
-		const outputs = (await Effect.runPromise(Stream.runCollect(run(kit, [{
-			type: "function_call",
-			call_id: "call_1",
-			name: "geo__search",
-			arguments: "{\"q\":\"lisbon\"}"
-		}])).pipe(Effect.provide(Layer.succeed(Geo, { lookup: (q) => Effect.succeed(`geo:${q}`) }))))).filter(isOutput).map((e) => e.result);
-		globalExpect(outputs).toHaveLength(1);
-		globalExpect(outputs[0]).toMatchObject({
-			_tag: "Ok",
-			tool: "geo__search",
-			value: "geo:lisbon"
+describe("Tool.withFailures and Toolkit.close", () => {
+	class Denied extends Schema.TaggedError()("Denied", { message: Schema.String }) {}
+	const gated = make$1(withFailures(weather, Denied), search);
+	const denied = new Denied({ message: "not now" });
+	it.effect("a closing the tool declares round-trips through history", () => Effect.gen(function* () {
+		const closed = yield* close(gated, call("weather", "1"), denied);
+		const item = yield* output(gated, closed);
+		globalExpect(item.isError).toBe(true);
+		globalExpect(yield* decode(gated, "weather", item)).toEqual(Result.fail(denied));
+	}));
+	it.effect("closing with an error the call's tool doesn't declare fails at close", () => Effect.gen(function* () {
+		const error = yield* Effect.flip(close(gated, call("search", "2"), denied));
+		globalExpect(error).toBeInstanceOf(UndeclaredFailure);
+		globalExpect(error.tool).toBe("search");
+	}));
+	it.effect("with the tool's name, close checks the call belongs to that tool", () => Effect.gen(function* () {
+		const closed = yield* close(gated, "weather", call("weather", "5"), denied);
+		globalExpect(closed.tool).toBe("weather");
+		const error = yield* Effect.flip(close(gated, "weather", call("search", "6"), denied));
+		globalExpect(error).toBeInstanceOf(UndeclaredFailure);
+	}));
+	it("type: with the tool's name, the error must be that tool's", () => {
+		close(gated, "search", call("search", "7"), denied);
+	});
+	it.effect("core's errors close any call", () => Effect.gen(function* () {
+		const cancelled = new Cancelled({ message: "moved on" });
+		const closed = yield* close(gated, call("search", "3"), cancelled);
+		globalExpect(closed.result).toEqual(Result.fail(cancelled));
+	}));
+	it.effect("Toolkit.withFailures declares the closing on every local tool", () => Effect.gen(function* () {
+		const all = withFailures$1(kit, Denied);
+		const closed = yield* close(all, call("search", "4"), denied);
+		const item = yield* output(all, closed);
+		globalExpect(yield* decode(all, "search", item)).toEqual(Result.fail(denied));
+	}));
+	it.effect("keeps the tool's own failures declared", () => Effect.gen(function* () {
+		const [event] = yield* outcomes(gated, [call("weather", "3", "{\"city\":\"Atlantis\"}")]);
+		globalExpect(failureOf(event.result)).toEqual(new CityNotFound({ city: "Atlantis" }));
+	}));
+	it("type: close takes only errors the toolkit declares", () => {
+		decode(gated, "weather", {
+			type: "function_call_output",
+			call_id: "1",
+			output: []
 		});
+		(0, import_dist.expectTypeOf)().toEqualTypeOf();
+		close(gated, call("weather", "4"), new ApiDown());
 	});
 });
-describe$1("Toolkit.wrap - middleware", () => {
-	const Empty = Schema.Struct({});
-	class Audit extends Context.Service()("test/Audit") {}
-	const getWeather = make({
-		name: "get_weather",
+describe("Toolkit.split and Toolkit.complete", () => {
+	const askUser = declare({
+		name: "ask_user",
 		description: "",
-		inputSchema: fromEffectSchema(Empty),
-		run: () => Effect.succeed({ tempC: 18 })
+		inputSchema: Schema.Struct({ question: Schema.String }),
+		outputSchema: Schema.String
 	});
-	const escalate = signal({
-		name: "escalate",
+	const finish = declare({
+		name: "finish",
 		description: "",
-		inputSchema: fromEffectSchema(Empty)
-	});
-	const audited = (run, name) => (input, emit) => Effect.gen(function* () {
-		yield* (yield* Audit).record(name);
-		return yield* run(input, emit);
-	});
-	const call = (name, id) => ({
-		type: "function_call",
-		call_id: id,
-		name,
-		arguments: "{}"
-	});
-	it("unions the middleware's R2 into the toolkit's requirements", () => {
-		const wrapped = wrap(make$1(getWeather), audited);
-		const stream = run(wrapped, []);
-		(0, import_dist.expectTypeOf)(stream).toEqualTypeOf();
-	});
-	it("runs the wrapped handler and leaves non-local kinds untouched", async () => {
-		const recorded = [];
-		const wrapped = pipe(make$1(getWeather, escalate), wrap(audited));
-		const events = await Effect.runPromise(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]));
-		globalExpect(recorded).toEqual(["get_weather"]);
-		const w = byCall.get("w1");
-		globalExpect(w !== void 0 && isOk(w) && w.value).toEqual({ tempC: 18 });
-		const s = byCall.get("s1");
-		globalExpect(s?._tag === "Failure" && s.kind).toBe("non_local_tool");
-	});
-});
-describe$1("Toolkit.run - executor outcomes", () => {
-	const plain = (name, out) => make({
-		name,
-		description: "",
-		inputSchema: fromEffectSchema(Empty),
-		run: () => Effect.succeed(out)
-	});
-	it("absorbs a bare string failure as a tool_failed result", async () => {
-		const t = make({
-			name: "t",
-			description: "",
-			inputSchema: fromEffectSchema(Empty),
-			run: () => Effect.fail("nope")
-		});
-		const result = (await Effect.runPromise(runToArray(make$1(t), [toolCall("t", "1")]))).filter(isOutput)[0]?.result;
-		globalExpect(result).toMatchObject({
-			_tag: "Failure",
-			kind: "tool_failed",
-			reason: "nope"
-		});
-	});
-	it("absorbs Tool.fail with a custom kind", async () => {
-		const t = make({
-			name: "t",
-			description: "",
-			inputSchema: fromEffectSchema(Empty),
-			run: () => fail("missing", { kind: "not_found" })
+		inputSchema: Schema.Struct({ report: Schema.String })
+	});
+	const agent = make$1(weather, askUser, finish);
+	const turnOf = (...calls) => ({
+		items: calls,
+		usage: {},
+		stop_reason: "tool_calls"
+	});
+	it.effect("sorts a turn's calls: run, declared (decoded), invalid (closed)", () => Effect.gen(function* () {
+		const { run, declared, invalid } = yield* split(agent, turnOf(call("weather", "1", `{"city":"Lisbon"}`), call("ask_user", "2", `{"question":"Which city?"}`), call("nope", "3"), call("finish", "4", `{}`)));
+		globalExpect(run.map((c) => c.call_id)).toEqual(["1", "3"]);
+		globalExpect(declared).toEqual([{
+			tool: "ask_user",
+			call: call("ask_user", "2", `{"question":"Which city?"}`),
+			input: { question: "Which city?" }
+		}]);
+		globalExpect(invalid).toHaveLength(1);
+		globalExpect(invalid[0]).toMatchObject({
+			call_id: "4",
+			tool: "finish"
 		});
-		const result = (await Effect.runPromise(runToArray(make$1(t), [toolCall("t", "1")]))).filter(isOutput)[0]?.result;
-		globalExpect(result).toMatchObject({
-			_tag: "Failure",
-			kind: "not_found",
-			reason: "missing"
-		});
-	});
-	it("propagates a typed non-sentinel failure on the stream", async () => {
-		const t = make({
-			name: "t",
-			description: "",
-			inputSchema: fromEffectSchema(Empty),
-			run: () => Effect.fail(new RateLimited({
-				provider: "x",
-				raw: null
-			}))
+		globalExpect(failureOf(invalid[0].result)).toBeInstanceOf(InputInvalid);
+	}));
+	it.effect("declared calls are typed per tool: an exhaustive Match handles each", () => Effect.gen(function* () {
+		const { declared } = yield* split(agent, turnOf(call("finish", "1", `{"report":"done"}`), call("ask_user", "2", `{"question":"?"}`)));
+		const route = Match.type().pipe(Match.discriminatorsExhaustive("tool")({
+			ask_user: (c) => `ask ${c.input.question}`,
+			finish: (c) => `end ${c.input.report}`
+		}));
+		globalExpect(declared.map(route)).toEqual(["end done", "ask ?"]);
+		Match.type().pipe(Match.discriminatorsExhaustive("tool")({ ask_user: () => "ask" }));
+		(0, import_dist.expectTypeOf)().toEqualTypeOf();
+	}));
+	it.effect("complete answers a call with a value typed by outputSchema", () => Effect.gen(function* () {
+		const answered = yield* complete(agent, "ask_user", call("ask_user", "1"), "Lisbon");
+		globalExpect(answered).toEqual({
+			_tag: "Output",
+			call_id: "1",
+			tool: "ask_user",
+			result: Result.succeed("Lisbon")
 		});
-		const exit = await Effect.runPromiseExit(runToArray(make$1(t), [toolCall("t", "1")]));
-		globalExpect(exit._tag).toBe("Failure");
-	});
-	it("dies on a defect instead of masking it as a result", async () => {
-		const t = make({
-			name: "t",
-			description: "",
-			inputSchema: fromEffectSchema(Empty),
-			run: () => Effect.die(/* @__PURE__ */ new Error("boom"))
+		const item = yield* output(agent, answered);
+		globalExpect(yield* decode(agent, "ask_user", item)).toEqual(Result.succeed("Lisbon"));
+	}));
+	it.effect("complete fails with UndeclaredFailure for another tool's call", () => Effect.gen(function* () {
+		const error = yield* Effect.flip(complete(agent, "ask_user", call("finish", "1"), "Lisbon"));
+		globalExpect(error).toMatchObject({
+			_tag: "UndeclaredFailure",
+			tool: "ask_user"
 		});
-		const exit = await Effect.runPromiseExit(runToArray(make$1(t), [toolCall("t", "1")]));
-		globalExpect(exit._tag).toBe("Failure");
+	}));
+	it("type: complete's value is the tool's output", () => {
+		complete(agent, "ask_user", call("ask_user", "1"), 42);
+		complete(agent, "finish", call("finish", "1"), "done");
 	});
-	it("streams progress events strictly before the terminal output", async () => {
-		const t = make({
-			name: "t",
-			description: "",
-			inputSchema: fromEffectSchema(Empty),
-			run: (_input, emit) => emit("a").pipe(Effect.andThen(emit("b")), Effect.andThen(Effect.succeed("done")))
-		});
-		const events = await Effect.runPromise(runToArray(make$1(t), [toolCall("t", "1")]));
-		globalExpect(events.map((e) => e._tag)).toEqual([
-			"Progress",
-			"Progress",
-			"Output"
+});
+describe("Toolkit.next", () => {
+	it.effect("forwards every event, then continues with the turn and encoded outputs appended", () => Effect.gen(function* () {
+		const calls = [call("weather", "1", "{\"city\":\"Lisbon\"}"), call("search", "2", "{\"query\":\"x\"}")];
+		const turn = {
+			items: calls,
+			usage: {},
+			stop_reason: "tool_calls"
+		};
+		const steps = yield* run(kit, calls, { concurrency: 1 }).pipe(next(kit, {
+			history: [],
+			round: 1
+		}, turn), Stream.runCollect);
+		globalExpect(steps.map((s) => s._tag)).toEqual([
+			"Value",
+			"Value",
+			"Value",
+			"Value",
+			"Value",
+			"Next"
 		]);
-		globalExpect(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 = make({
-			name: "t",
-			description: "",
-			inputSchema: fromEffectSchema(Schema.Struct({ x: Schema.Number })),
-			run: () => Effect.succeed(1)
-		});
-		const result = (await Effect.runPromise(runToArray(make$1(t), [toolCall("t", "1", "{\"x\":\"nope\"}")]))).filter(isOutput)[0]?.result;
-		globalExpect(result).toMatchObject({
-			_tag: "Failure",
-			kind: "input_validation_error"
+		const last = steps.at(-1);
+		globalExpect(last?._tag === "Next" && last.state).toEqual({
+			round: 1,
+			history: [
+				...calls,
+				{
+					type: "function_call_output",
+					call_id: "1",
+					output: [{
+						type: "input_json",
+						value: {
+							city: "Lisbon",
+							at: at.toISOString()
+						}
+					}]
+				},
+				{
+					type: "function_call_output",
+					call_id: "2",
+					output: [{
+						type: "input_json",
+						value: { hits: 4 }
+					}]
+				}
+			]
 		});
-		globalExpect(result !== void 0 && isFailure(result) && result.reason).toBeTruthy();
-	});
-	it("normalizes empty arguments to {} for a zero-arg tool", async () => {
-		const result = (await Effect.runPromise(runToArray(make$1(plain("t", "ok")), [toolCall("t", "1", "")]))).filter(isOutput)[0]?.result;
-		globalExpect(result).toMatchObject({
-			_tag: "Ok",
-			value: "ok"
-		});
-	});
-	it("reports unparseable arguments as input_validation_error", async () => {
-		const result = (await Effect.runPromise(runToArray(make$1(plain("t", "ok")), [toolCall("t", "1", "not json")]))).filter(isOutput)[0]?.result;
-		globalExpect(result).toMatchObject({
-			_tag: "Failure",
-			kind: "input_validation_error"
-		});
-	});
-	it("a call named constructor is unknown_tool, not non_local_tool", async () => {
-		const result = (await Effect.runPromise(runToArray(make$1(plain("t", "ok")), [toolCall("constructor", "1")]))).filter(isOutput)[0]?.result;
-		globalExpect(result).toMatchObject({
-			_tag: "Failure",
-			kind: "unknown_tool"
-		});
-	});
-	it("serializes an undefined output as \"null\" on the wire", async () => {
-		const t = make({
-			name: "t",
+	}));
+});
+describe("Toolkit.wrap and Toolkit.describeFailures", () => {
+	class Audit extends Context.Service()("test/Audit") {}
+	const audited = (run, name) => (input) => Stream.unwrap(Effect.gen(function* () {
+		yield* (yield* Audit).record(name);
+		return run(input);
+	}));
+	it.effect("wrap runs local tools through the middleware and tracks its requirement", () => Effect.gen(function* () {
+		const recorded = [];
+		const wrapped = pipe(kit, wrap(audited));
+		const stream = run(wrapped, [call("search", "1", "{\"query\":\"x\"}"), call("escalate", "2")], { concurrency: 1 });
+		(0, import_dist.expectTypeOf)().toEqualTypeOf();
+		const events = yield* stream.pipe(Stream.filter(isOutcome), Stream.runCollect, Effect.provideService(Audit, { record: (n) => Effect.sync(() => void recorded.push(n)) }));
+		globalExpect(recorded).toEqual(["search"]);
+		globalExpect(events.map((e) => e.result._tag)).toEqual(["Success", "Failure"]);
+	}));
+	it.effect("wrap keeps each tool's shape: an Effect tool emits no partials", () => Effect.gen(function* () {
+		const wrapped = pipe(kit, wrap(audited));
+		const events = yield* run(wrapped, [call("weather", "1", "{\"city\":\"Lisbon\"}"), call("search", "2", "{\"query\":\"x\"}")], { concurrency: 1 }).pipe(Stream.runCollect, Effect.provideService(Audit, { record: () => Effect.void }));
+		globalExpect(events.map((e) => `${e.tool}:${e._tag}`)).toEqual([
+			"weather:Output",
+			"search:Partial",
+			"search:Partial",
+			"search:Partial",
+			"search:Output"
+		]);
+	}));
+	it.effect("describeFailures turns undeclared errors into ToolFailed and keeps declared ones", () => Effect.gen(function* () {
+		const described = describeFailures(kit, (e) => `upstream: ${e._tag}`);
+		(0, import_dist.expectTypeOf)().toEqualTypeOf();
+		const events = yield* outcomes(described, [call("weather", "1", "{\"city\":\"down\"}"), call("weather", "2", "{\"city\":\"Atlantis\"}")]);
+		globalExpect(events.map((e) => failureOf(e.result))).toEqual([new ToolFailed({ message: "upstream: ApiDown" }), new CityNotFound({ city: "Atlantis" })]);
+		const item = yield* output(described, events[0]);
+		globalExpect(item.output).toEqual([{
+			type: "input_json",
+			value: {
+				_tag: "ToolFailed",
+				message: "upstream: ApiDown"
+			}
+		}]);
+	}));
+	it.effect("describeFailures keeps an error fatal when describe returns undefined", () => Effect.gen(function* () {
+		class SessionGone extends Schema.TaggedError()("SessionGone", {}) {}
+		const click = make({
+			name: "click",
 			description: "",
-			inputSchema: fromEffectSchema(Empty),
-			run: () => Effect.void
+			inputSchema: Schema.Struct({ ref: Schema.String }),
+			outputSchema: Schema.String,
+			run: ({ ref }) => Effect.gen(function* () {
+				if (ref === "gone") return yield* new SessionGone();
+				return yield* new ApiDown();
+			})
 		});
-		const result = (await Effect.runPromise(runToArray(make$1(t), [toolCall("t", "1")]))).filter(isOutput)[0]?.result;
-		globalExpect(result !== void 0 && toToolCallOutput(result).output).toBe("null");
-	});
-	it("preserves call order with concurrency 1", async () => {
-		const kit = make$1(plain("a", "A"), plain("b", "B"));
-		const events = await Effect.runPromise(runToArray(kit, [toolCall("a", "a1"), toolCall("b", "b1")], { concurrency: 1 }));
-		globalExpect(events.filter(isOutput).map((e) => e.result.call_id)).toEqual(["a1", "b1"]);
+		const kit = describeFailures(make$1(click), (e) => e._tag === "ApiDown" ? "the button did nothing" : void 0);
+		(0, import_dist.expectTypeOf)().toEqualTypeOf();
+		const [stale] = yield* outcomes(kit, [call("click", "1", "{\"ref\":\"b1\"}")]);
+		globalExpect(failureOf(stale.result)).toEqual(new ToolFailed({ message: "the button did nothing" }));
+		const gone = yield* Effect.flip(collect(kit, [call("click", "2", "{\"ref\":\"gone\"}")]));
+		globalExpect(gone).toEqual(new SessionGone());
+	}));
+});
+describe("Toolkit.make, namespace and compose", () => {
+	const tool = (name) => make({
+		name,
+		description: "",
+		inputSchema: noInput,
+		outputSchema: Schema.Number,
+		run: () => Effect.succeed(0)
 	});
-	it("type: run of a describeFailures toolkit has no stream error", () => {
-		const t = make({
-			name: "t",
+	it("rejects a duplicate literal name at compile time", () => {
+		const a = tool("search");
+		const b = declare({
+			name: "search",
 			description: "",
-			inputSchema: fromEffectSchema(Empty),
-			run: () => Effect.fail(new RateLimited({
-				provider: "x",
-				raw: null
-			}))
+			inputSchema: noInput
 		});
-		const kit = describeFailures(make$1(t), describe);
-		const stream = run(kit, []);
-		(0, import_dist.expectTypeOf)(stream).toEqualTypeOf();
+		make$1(a, b);
 	});
-	it("type: run of a typed toolkit propagates the tool's E", () => {
-		const t = make({
-			name: "t",
-			description: "",
-			inputSchema: fromEffectSchema(Empty),
-			run: () => Effect.fail(new RateLimited({
-				provider: "x",
-				raw: null
-			}))
+	it.effect("compose fails on a clash between dynamic toolkits, naming both sources", () => Effect.gen(function* () {
+		const error = yield* Effect.flip(compose(fromArray([tool("search")]), fromArray([tool("search")])));
+		globalExpect(error).toEqual(new DuplicateToolName({
+			name: "search",
+			sources: ["toolkit-0", "toolkit-1"]
+		}));
+	}));
+	it.effect("namespaced tools compose and run under their prefixed, typed names", () => Effect.gen(function* () {
+		const github = makeNamespaced("github", tool("search"));
+		const linear = namespace("linear", make$1(tool("search")));
+		(0, import_dist.expectTypeOf)(github.github__search.name).toEqualTypeOf();
+		const both = yield* compose(github, linear);
+		const [event] = yield* outcomes(both, [call("linear__search", "1")]);
+		globalExpect(event).toMatchObject({
+			tool: "linear__search",
+			result: Result.succeed(0)
 		});
-		const stream = run(make$1(t), []);
-		(0, import_dist.expectTypeOf)(stream).toEqualTypeOf();
-	});
+	}));
 });
 //#endregion
 export {};