@nhtio/adk 1.20260924.0 → 1.20260928.0

package/{spooled_artifact-BkOe4-j-.mjs → spooled_artifact-Bw_7swIp.mjs}

@@ -1,308 +1,143 @@
 import { a as passesSchema, i as asyncValidateOrThrow, o as validateOrThrow, r as ValidationException } from "./exceptions-DRYLe-J4.mjs";
 import { n as isInstanceOf, r as isObject, t as isError } from "./guards-BEpY7lBI.mjs";
-import { C as E_INVALID_TOOL_ARGS, F as E_READER_NOT_DESCRIBABLE, L as E_TOOL_ALREADY_REGISTERED, M as E_NO_READER_RESOLVER, R as E_TOOL_DOWNSTREAM_ERROR, c as E_ARTIFACT_ID_COLLISION, h as E_INVALID_INITIAL_REGISTRY_VALUE, j as E_NOT_A_SPOOL_READER, n as TokenEncoding, o as DECODE_METHOD, r as Tokenizable, s as ENCODE_METHOD, y as E_INVALID_INITIAL_TOOL_VALUE } from "./tokenizable-xPXj1AQX.mjs";
-import { DateTime } from "luxon";
-import { sha256 } from "js-sha256";
+import { A as E_NO_READER_RESOLVER, B as ENCODE_METHOD, F as E_TOOL_ALREADY_REGISTERED, I as E_TOOL_DOWNSTREAM_ERROR, N as E_READER_NOT_DESCRIBABLE, _ as E_INVALID_INITIAL_TOOL_VALUE, k as E_NOT_A_SPOOL_READER, n as TokenEncoding, o as E_ARTIFACT_ID_COLLISION, p as E_INVALID_INITIAL_REGISTRY_VALUE, r as Tokenizable, x as E_INVALID_TOOL_ARGS, z as DECODE_METHOD } from "./tokenizable-VB4Av8GF.mjs";
 import { decode, encode, validator } from "@nhtio/validation";
 import { dset } from "dset";
 import { klona } from "klona";
 import delve from "dlv";
-//#region src/lib/classes/tool_registry.ts
+import { DateTime } from "luxon";
+import { sha256 } from "js-sha256";
+//#region src/lib/classes/registry.ts
 /**
-* A mutable, turn-scoped collection of {@link @nhtio/adk!Tool} instances.
+* A controlled-mutation key-value store with dot-path access and deep-clone isolation.
 *
 * @remarks
-* Each `TurnRunner.run()` call constructs a fresh `ToolRegistry` from the runner's configured
-* baseline tools, so middleware edits are isolated to the current turn and cannot bleed across
-* concurrent or subsequent turns.
-*
-* `Tool` instances are immutable, so `all()` returns a fresh array without deep-cloning.
-*
-* `register()` throws {@link @nhtio/adk!E_TOOL_ALREADY_REGISTERED} if a tool with the same name is already
-* present — pass `overwrite: true` to replace it explicitly.
+* The registry enforces a safe read/write contract: callers never hold a live reference into
+* the internal store. Every value that enters (`set`) or leaves (`get`, `all`) is deep-cloned
+* via `klona`, so mutations to a retrieved value cannot affect stored state and vice versa.
 *
-* Tools can be **hidden** — registered and callable, but excluded from the default tool list
-* rendered to the model. This is useful for discovery patterns where an agent has a tool that
-* enumerates available tools, and the model picks one to call by name in a subsequent iteration.
-* Hidden state is a property of the registry, not the tool: the same tool can be visible in one
-* registry and hidden in another. See {@link hide}, {@link visible}, {@link hidden}.
+* Keys are dot-delimited paths (e.g. `"user.profile.name"`), resolved via `dlv` for reads and
+* `dset` for writes; intermediate objects are created automatically on write.
 */
-var ToolRegistry = class ToolRegistry {
-	#tools;
-	#hidden;
-	/**
-	* Returns `true` if `value` is a {@link ToolRegistry} instance.
-	*
-	* @param value - The value to test.
-	* @returns `true` when `value` is a {@link ToolRegistry} instance.
-	*/
-	static isToolRegistry(value) {
-		return isInstanceOf(value, "ToolRegistry", ToolRegistry);
-	}
-	/**
-	* @param tools - Optional initial tools. Insertion order is preserved. Duplicate names throw
-	*   {@link @nhtio/adk!E_TOOL_ALREADY_REGISTERED} — ensure each tool has a unique name.
-	* @throws {@link @nhtio/adk!E_TOOL_ALREADY_REGISTERED} when two tools in `tools` share a name.
-	*/
-	constructor(tools) {
-		this.#tools = /* @__PURE__ */ new Map();
-		this.#hidden = /* @__PURE__ */ new Set();
-		for (const tool of tools ?? []) this.register(tool);
-	}
+var Registry = class Registry {
+	#store;
 	/**
-	* Adds a tool to the registry.
-	*
-	* @param tool - The tool to register.
-	* @param overwrite - When `true`, silently replaces an existing tool with the same name.
-	*   Defaults to `false`.
-	* @throws {@link @nhtio/adk!E_TOOL_ALREADY_REGISTERED} when a tool with the same name is already registered
-	*   and `overwrite` is not `true`.
+	* @param initial - Optional plain object to seed the registry. Deep-cloned on construction.
+	* @throws {@link @nhtio/adk!E_INVALID_INITIAL_REGISTRY_VALUE} when `initial` is defined but not a plain object.
 	*/
-	register(tool, overwrite) {
-		if (this.#tools.has(tool.name) && !overwrite) throw new E_TOOL_ALREADY_REGISTERED();
-		this.#tools.set(tool.name, tool);
+	constructor(initial) {
+		if ("undefined" !== typeof initial && !isObject(initial)) throw new E_INVALID_INITIAL_REGISTRY_VALUE();
+		this.#store = initial ? klona(initial) : {};
 	}
 	/**
-	* Removes the tool with the given name from the registry.
+	* Returns `true` if `value` is a {@link Registry} instance.
 	*
 	* @remarks
-	* Also removes the name from the hidden set if present. No-ops if no tool with that name is
-	* registered.
-	*
-	* @param name - The name of the tool to remove.
-	*/
-	unregister(name) {
-		this.#tools.delete(name);
-		this.#hidden.delete(name);
-	}
-	/**
-	* Returns the tool registered under `name`, or `undefined` if not present.
-	*
-	* @param name - The tool name to look up.
-	*/
-	get(name) {
-		return this.#tools.get(name);
-	}
-	/**
-	* Returns `true` if a tool with the given name is registered.
+	* Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety.
 	*
-	* @param name - The tool name to test.
+	* @param value - The value to test.
+	* @returns `true` when `value` is a {@link Registry} instance.
 	*/
-	has(name) {
-		return this.#tools.has(name);
+	static isRegistry(value) {
+		return isInstanceOf(value, "Registry", Registry);
 	}
 	/**
-	* Returns a fresh array of all registered tools in insertion order.
+	* Retrieves the value at `key`, returning `defaultValue` if the path is absent.
 	*
 	* @remarks
-	* Includes both visible and hidden tools. Use {@link visible} to get only non-hidden tools, or
-	* {@link hidden} to get only hidden tools.
+	* The returned value is a deep clone — mutating it will not affect the stored state.
 	*
-	* Since {@link @nhtio/adk!Tool} instances are immutable, no deep-cloning is needed.
+	* @typeParam T - Expected type of the value at `key`.
+	* @param key - Dot-delimited path into the store (e.g. `"user.name"`).
+	* @param defaultValue - Fallback returned when the path resolves to `undefined`.
+	* @returns A deep clone of the stored value cast to `T`, or `defaultValue` when the path is absent.
 	*/
-	all() {
-		return Array.from(this.#tools.values());
+	get(key, defaultValue) {
+		const value = delve(klona(this.#store), key);
+		return "undefined" === typeof value ? defaultValue : value;
 	}
 	/**
-	* Returns a fresh array of registered tools that are **not** hidden, in insertion order.
+	* Sets the value at `key`, creating intermediate objects as needed.
 	*
 	* @remarks
-	* This is the accessor LLM batteries should use when building the tool list for the model.
-	* Hidden tools are still callable (they resolve via {@link get}) but are excluded from the
-	* rendered tool definitions.
-	*/
-	visible() {
-		return this.all().filter((t) => !this.#hidden.has(t.name));
-	}
-	/**
-	* Returns a fresh array of registered tools that **are** hidden, in insertion order.
+	* The stored value is isolated from the caller — mutating `value` after this call will not
+	* affect what is held in the registry.
 	*
-	* @remarks
-	* The converse of {@link visible}. Useful for discovery tools that enumerate all available
-	* tools, and for propagating hidden state across {@link merge}.
+	* @param key - Dot-delimited path into the store (e.g. `"user.name"`).
+	* @param value - Value to store at the path.
 	*/
-	hidden() {
-		return this.all().filter((t) => this.#hidden.has(t.name));
+	set(key, value) {
+		dset(this.#store, key, value);
 	}
 	/**
-	* Marks one or more registered tools as hidden.
+	* Returns `true` if the registry has a value at `key`, `false` otherwise.
 	*
 	* @remarks
-	* Hidden tools remain registered and callable via {@link get}, but are excluded from
-	* {@link visible} (and therefore from the LLM tool list). No-ops for any name that is not
-	* currently registered — the end result (the tool is not visible) matches the intent.
+	* A key resolving to `undefined` is treated as absent — same convention as {@link Registry.get}'s
+	* `defaultValue` fallback. No clone is performed; this is a pure existence check.
 	*
-	* @param names - One or more tool names to hide.
+	* @param key - Dot-delimited path into the store (e.g. `"user.name"`).
+	* @returns `true` when the path resolves to a value other than `undefined`.
 	*/
-	hide(...names) {
-		for (const name of names) this.#hidden.add(name);
+	has(key) {
+		return "undefined" !== typeof delve(this.#store, key);
 	}
 	/**
-	* Unmarks one or more tools as hidden, making them visible again.
+	* Returns all leaf dot-paths present in the registry.
 	*
 	* @remarks
-	* No-ops for any name that is not currently hidden.
+	* The store is deep-cloned before traversal. Plain objects are walked recursively with path
+	* segments joined by dots; arrays, primitives, `null`, and class instances are treated as leaves.
 	*
-	* @param names - One or more tool names to unhide.
+	* @returns A string array of dot-delimited paths to leaf values in the store.
 	*/
-	unhide(...names) {
-		for (const name of names) this.#hidden.delete(name);
+	keys() {
+		const store = klona(this.#store);
+		const keys = [];
+		const isPlainRecord = (value) => {
+			if (!isObject(value)) return false;
+			const prototype = Object.getPrototypeOf(value);
+			return prototype === Object.prototype || prototype === null;
+		};
+		const walk = (value, segments) => {
+			if (!isPlainRecord(value)) {
+				if (segments.length > 0) keys.push(segments.join("."));
+				return;
+			}
+			for (const [segment, child] of Object.entries(value)) walk(child, [...segments, segment]);
+		};
+		walk(store, []);
+		return keys;
 	}
 	/**
-	* Replaces the entire hidden set with the given tool names.
-	*
-	* @remarks
-	* Any previously hidden tool not in `names` becomes visible. Names that are not registered are
-	* silently ignored — they are added to the set but have no effect until a tool with that name
-	* is registered.
+	* Returns a deep clone of the entire store contents.
 	*
-	* @param names - The complete set of tool names to hide.
-	*/
-	setHidden(...names) {
-		this.#hidden = new Set(names);
-	}
-	/**
-	* Unhides every tool in the registry.
+	* @returns A plain object snapshot of all stored key-value pairs.
 	*/
-	clearHidden() {
-		this.#hidden.clear();
+	all() {
+		return klona(this.#store);
 	}
 	/**
-	* Removes every tool whose {@link @nhtio/adk!Tool.ephemeral} flag is `true`.
+	* Serialise this Registry into an `@nhtio/encoder` snapshot.
 	*
 	* @remarks
-	* Also removes pruned tool names from the hidden set. Synchronous and idempotent — calling it
-	* twice in a row is a no-op the second time. The canonical caller is
-	* {@link ToolRegistry.bindContext}, which schedules this method to run at
-	* {@link @nhtio/adk!DispatchContext.ack}. Non-ephemeral tools are left untouched.
+	* The snapshot is a deep clone of the store ({@link Registry.all}). Leaf values that are themselves
+	* registered encodable instances round-trip; anything the encoder cannot serialise throws at encode
+	* time (standard encoder behaviour). Round-trips via {@link Registry.[DECODE_METHOD]}.
+	*
+	* @returns A deep-cloned plain-object snapshot of the store.
 	*/
-	pruneEphemeral() {
-		for (const [name, tool] of this.#tools) if (tool.ephemeral) {
-			this.#tools.delete(name);
-			this.#hidden.delete(name);
-		}
+	[ENCODE_METHOD]() {
+		return this.all();
 	}
 	/**
-	* Binds this registry to a {@link @nhtio/adk!DispatchContext} so that {@link pruneEphemeral} runs
-	* automatically when the context is acked.
-	*
-	* @remarks
-	* The handler does NOT fire on {@link @nhtio/adk!DispatchContext.nack} — failed executor runs leave
-	* any forged tools in place so the consumer can inspect what was registered when debugging the
-	* failure. Subscriptions are short-lived and die with the context regardless.
-	*
-	* ARTIFACT READERS ARE FORGED BY THE CORE. As of the core-forge change, the `DispatchRunner` forges
-	* artifact-reader tools from prior-turn `SpooledArtifact` results into `ctx.tools` (and calls
-	* `ctx.tools.bindContext(ctx)`) once per iteration, BEFORE the input pipeline — so a battery executor no
-	* longer forges or binds; it reads the already-forged `ctx.tools` for both representation (rendering the
-	* tool declarations) and resolution (looking up an incoming call by name). The lifecycle is unchanged:
-	* ephemeral readers are still pruned on `ack`, and the core re-forges each iteration (prune-then-forge) so
-	* the `callId` enum never goes stale.
-	*
-	* `bindContext` remains the public seam for a CUSTOM consumer that forges its own ephemeral tools outside
-	* the core path. If you forge into a long-lived registry yourself, bind it (or prune manually) or the
-	* ephemeral tools accumulate and later `forgeTools(ctx)` calls see a stale `callId` enum. The pattern for a
-	* hand-rolled forge is:
-	*
-	* ```ts
-	* // Custom forge (the core already does this for artifact readers on ctx.tools):
-	* const forged = SpooledArtifact.forgeTools(ctx)
-	* for (const tool of forged.all()) ctx.tools.register(tool, true)
-	* ctx.tools.bindContext(ctx) // prune the ephemeral readers when the dispatch acks
-	* ```
-	*
-	* @param ctx - The execution context whose `ack` event should trigger pruning.
-	* @returns An unsubscribe function — calling it before `ctx.ack()` prevents pruning. Rarely
-	*   useful outside of tests.
+	* Reconstruct a {@link Registry} from a {@link Registry.[ENCODE_METHOD]} snapshot.
 	*
-	* @see {@link @nhtio/adk!SpooledArtifact.forgeTools}
-	* @see {@link @nhtio/adk!DispatchContext.onAck}
+	* @param data - The store snapshot produced by {@link Registry.[ENCODE_METHOD]}.
+	* @returns A fresh {@link Registry} seeded with the snapshot.
 	*/
-	bindContext(ctx) {
-		return ctx.onAck(() => this.pruneEphemeral());
-	}
-	/**
-	* Combines multiple {@link ToolRegistry} instances into a fresh registry without mutating any
-	* input.
-	*
-	* @remarks
-	* Iteration is left-to-right across `registries` and then in each registry's insertion order.
-	* Collisions are resolved by consulting the **incoming** tool's {@link @nhtio/adk!Tool.onCollision} first:
-	*
-	* - `'replace'` (per-tool): the incoming tool wins, replacing the existing entry.
-	* - `'keep'` (per-tool): the existing entry wins; the incoming tool is dropped.
-	* - `'throw'` (per-tool, the default): fall back to the merge-level `options.onCollision`.
-	*
-	* The merge-level `options.onCollision` defaults to `'throw'`, which mirrors {@link register}.
-	*
-	* The result is a brand-new registry; no input is mutated and no event subscription is
-	* propagated. Each `Tool`'s `ephemeral` flag carries through unchanged — the flag lives on the
-	* tool, not the registry, so `bindContext(ctx)` on the merged registry will prune the forged
-	* tools as expected.
-	*
-	* Hidden state is also propagated: a tool that is hidden in any source registry remains hidden
-	* in the merged result, provided it survives collision resolution.
-	*
-	* @param registries - Registries to merge, in priority order (left-to-right insertion).
-	* @param options - Merge-level collision policy. Defaults to `{ onCollision: 'throw' }`.
-	* @returns A fresh {@link ToolRegistry} containing the resolved union of all inputs.
-	* @throws {@link @nhtio/adk!E_TOOL_ALREADY_REGISTERED} when the resolved collision policy is `'throw'`
-	*   and a collision occurs.
-	*/
-	static merge(registries, options) {
-		const policy = options?.onCollision ?? "throw";
-		const merged = new ToolRegistry();
-		for (const registry of registries) {
-			for (const tool of registry.all()) {
-				if (!merged.get(tool.name)) {
-					merged.register(tool);
-					continue;
-				}
-				const incomingPolicy = tool.onCollision;
-				if (incomingPolicy === "replace") {
-					merged.register(tool, true);
-					continue;
-				}
-				if (incomingPolicy === "keep") continue;
-				if (policy === "replace") {
-					merged.register(tool, true);
-					continue;
-				}
-				if (policy === "keep") continue;
-				throw new E_TOOL_ALREADY_REGISTERED();
-			}
-			for (const tool of registry.hidden()) if (merged.has(tool.name)) merged.hide(tool.name);
-		}
-		return merged;
-	}
-	/**
-	* Serialise this ToolRegistry into an `@nhtio/encoder` snapshot.
-	*
-	* @remarks
-	* Emits the live {@link @nhtio/adk!Tool} instances (the encoder recurses into each — so every tool's
-	* handler-closure caveat from {@link Tool.[ENCODE_METHOD]} applies) plus the hidden-set names. Both
-	* {@link @nhtio/adk!Tool} and {@link @nhtio/adk!ArtifactTool} entries round-trip to their correct
-	* subtype. Round-trips via {@link ToolRegistry.[DECODE_METHOD]}.
-	*
-	* @returns A `{ tools, hidden }` snapshot.
-	*/
-	[ENCODE_METHOD]() {
-		return {
-			tools: this.all(),
-			hidden: this.hidden().map((tool) => tool.name)
-		};
-	}
-	/**
-	* Reconstruct a {@link ToolRegistry} from a {@link ToolRegistry.[ENCODE_METHOD]} snapshot.
-	*
-	* @param data - The snapshot produced by {@link ToolRegistry.[ENCODE_METHOD]}.
-	* @returns A fresh {@link ToolRegistry} with the same tools and hidden set.
-	*/
-	static [DECODE_METHOD](data) {
-		const snapshot = data;
-		const registry = new ToolRegistry(snapshot.tools);
-		registry.setHidden(...snapshot.hidden);
-		return registry;
+	static [DECODE_METHOD](data) {
+		return new Registry(data);
 	}
 };
 //#endregion
@@ -331,140 +166,6 @@ function canonicalStringify(value) {
 	return "{" + Object.keys(obj).sort().map((k) => JSON.stringify(k) + ":" + canonicalStringify(obj[k])).join(",") + "}";
 }
 //#endregion
-//#region src/lib/classes/registry.ts
-/**
-* A controlled-mutation key-value store with dot-path access and deep-clone isolation.
-*
-* @remarks
-* The registry enforces a safe read/write contract: callers never hold a live reference into
-* the internal store. Every value that enters (`set`) or leaves (`get`, `all`) is deep-cloned
-* via `klona`, so mutations to a retrieved value cannot affect stored state and vice versa.
-*
-* Keys are dot-delimited paths (e.g. `"user.profile.name"`), resolved via `dlv` for reads and
-* `dset` for writes; intermediate objects are created automatically on write.
-*/
-var Registry = class Registry {
-	#store;
-	/**
-	* @param initial - Optional plain object to seed the registry. Deep-cloned on construction.
-	* @throws {@link @nhtio/adk!E_INVALID_INITIAL_REGISTRY_VALUE} when `initial` is defined but not a plain object.
-	*/
-	constructor(initial) {
-		if ("undefined" !== typeof initial && !isObject(initial)) throw new E_INVALID_INITIAL_REGISTRY_VALUE();
-		this.#store = initial ? klona(initial) : {};
-	}
-	/**
-	* Returns `true` if `value` is a {@link Registry} instance.
-	*
-	* @remarks
-	* Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety.
-	*
-	* @param value - The value to test.
-	* @returns `true` when `value` is a {@link Registry} instance.
-	*/
-	static isRegistry(value) {
-		return isInstanceOf(value, "Registry", Registry);
-	}
-	/**
-	* Retrieves the value at `key`, returning `defaultValue` if the path is absent.
-	*
-	* @remarks
-	* The returned value is a deep clone — mutating it will not affect the stored state.
-	*
-	* @typeParam T - Expected type of the value at `key`.
-	* @param key - Dot-delimited path into the store (e.g. `"user.name"`).
-	* @param defaultValue - Fallback returned when the path resolves to `undefined`.
-	* @returns A deep clone of the stored value cast to `T`, or `defaultValue` when the path is absent.
-	*/
-	get(key, defaultValue) {
-		const value = delve(klona(this.#store), key);
-		return "undefined" === typeof value ? defaultValue : value;
-	}
-	/**
-	* Sets the value at `key`, creating intermediate objects as needed.
-	*
-	* @remarks
-	* The stored value is isolated from the caller — mutating `value` after this call will not
-	* affect what is held in the registry.
-	*
-	* @param key - Dot-delimited path into the store (e.g. `"user.name"`).
-	* @param value - Value to store at the path.
-	*/
-	set(key, value) {
-		dset(this.#store, key, value);
-	}
-	/**
-	* Returns `true` if the registry has a value at `key`, `false` otherwise.
-	*
-	* @remarks
-	* A key resolving to `undefined` is treated as absent — same convention as {@link Registry.get}'s
-	* `defaultValue` fallback. No clone is performed; this is a pure existence check.
-	*
-	* @param key - Dot-delimited path into the store (e.g. `"user.name"`).
-	* @returns `true` when the path resolves to a value other than `undefined`.
-	*/
-	has(key) {
-		return "undefined" !== typeof delve(this.#store, key);
-	}
-	/**
-	* Returns all leaf dot-paths present in the registry.
-	*
-	* @remarks
-	* The store is deep-cloned before traversal. Plain objects are walked recursively with path
-	* segments joined by dots; arrays, primitives, `null`, and class instances are treated as leaves.
-	*
-	* @returns A string array of dot-delimited paths to leaf values in the store.
-	*/
-	keys() {
-		const store = klona(this.#store);
-		const keys = [];
-		const isPlainRecord = (value) => {
-			if (!isObject(value)) return false;
-			const prototype = Object.getPrototypeOf(value);
-			return prototype === Object.prototype || prototype === null;
-		};
-		const walk = (value, segments) => {
-			if (!isPlainRecord(value)) {
-				if (segments.length > 0) keys.push(segments.join("."));
-				return;
-			}
-			for (const [segment, child] of Object.entries(value)) walk(child, [...segments, segment]);
-		};
-		walk(store, []);
-		return keys;
-	}
-	/**
-	* Returns a deep clone of the entire store contents.
-	*
-	* @returns A plain object snapshot of all stored key-value pairs.
-	*/
-	all() {
-		return klona(this.#store);
-	}
-	/**
-	* Serialise this Registry into an `@nhtio/encoder` snapshot.
-	*
-	* @remarks
-	* The snapshot is a deep clone of the store ({@link Registry.all}). Leaf values that are themselves
-	* registered encodable instances round-trip; anything the encoder cannot serialise throws at encode
-	* time (standard encoder behaviour). Round-trips via {@link Registry.[DECODE_METHOD]}.
-	*
-	* @returns A deep-cloned plain-object snapshot of the store.
-	*/
-	[ENCODE_METHOD]() {
-		return this.all();
-	}
-	/**
-	* Reconstruct a {@link Registry} from a {@link Registry.[ENCODE_METHOD]} snapshot.
-	*
-	* @param data - The store snapshot produced by {@link Registry.[ENCODE_METHOD]}.
-	* @returns A fresh {@link Registry} seeded with the snapshot.
-	*/
-	static [DECODE_METHOD](data) {
-		return new Registry(data);
-	}
-};
-//#endregion
 //#region src/lib/contracts/spooled_artifact_constructor.ts
 var ARTIFACT_METHODS = [
 	"head",
@@ -933,6 +634,305 @@ var ArtifactTool = class ArtifactTool extends Tool {
 	}
 };
 //#endregion
+//#region src/lib/classes/tool_registry.ts
+/**
+* A mutable, turn-scoped collection of {@link @nhtio/adk!Tool} instances.
+*
+* @remarks
+* Each `TurnRunner.run()` call constructs a fresh `ToolRegistry` from the runner's configured
+* baseline tools, so middleware edits are isolated to the current turn and cannot bleed across
+* concurrent or subsequent turns.
+*
+* `Tool` instances are immutable, so `all()` returns a fresh array without deep-cloning.
+*
+* `register()` throws {@link @nhtio/adk!E_TOOL_ALREADY_REGISTERED} if a tool with the same name is already
+* present — pass `overwrite: true` to replace it explicitly.
+*
+* Tools can be **hidden** — registered and callable, but excluded from the default tool list
+* rendered to the model. This is useful for discovery patterns where an agent has a tool that
+* enumerates available tools, and the model picks one to call by name in a subsequent iteration.
+* Hidden state is a property of the registry, not the tool: the same tool can be visible in one
+* registry and hidden in another. See {@link hide}, {@link visible}, {@link hidden}.
+*/
+var ToolRegistry = class ToolRegistry {
+	#tools;
+	#hidden;
+	/**
+	* Returns `true` if `value` is a {@link ToolRegistry} instance.
+	*
+	* @param value - The value to test.
+	* @returns `true` when `value` is a {@link ToolRegistry} instance.
+	*/
+	static isToolRegistry(value) {
+		return isInstanceOf(value, "ToolRegistry", ToolRegistry);
+	}
+	/**
+	* @param tools - Optional initial tools. Insertion order is preserved. Duplicate names throw
+	*   {@link @nhtio/adk!E_TOOL_ALREADY_REGISTERED} — ensure each tool has a unique name.
+	* @throws {@link @nhtio/adk!E_TOOL_ALREADY_REGISTERED} when two tools in `tools` share a name.
+	*/
+	constructor(tools) {
+		this.#tools = /* @__PURE__ */ new Map();
+		this.#hidden = /* @__PURE__ */ new Set();
+		for (const tool of tools ?? []) this.register(tool);
+	}
+	/**
+	* Adds a tool to the registry.
+	*
+	* @param tool - The tool to register.
+	* @param overwrite - When `true`, silently replaces an existing tool with the same name.
+	*   Defaults to `false`.
+	* @throws {@link @nhtio/adk!E_TOOL_ALREADY_REGISTERED} when a tool with the same name is already registered
+	*   and `overwrite` is not `true`.
+	*/
+	register(tool, overwrite) {
+		if (this.#tools.has(tool.name) && !overwrite) throw new E_TOOL_ALREADY_REGISTERED();
+		this.#tools.set(tool.name, tool);
+	}
+	/**
+	* Removes the tool with the given name from the registry.
+	*
+	* @remarks
+	* Also removes the name from the hidden set if present. No-ops if no tool with that name is
+	* registered.
+	*
+	* @param name - The name of the tool to remove.
+	*/
+	unregister(name) {
+		this.#tools.delete(name);
+		this.#hidden.delete(name);
+	}
+	/**
+	* Returns the tool registered under `name`, or `undefined` if not present.
+	*
+	* @param name - The tool name to look up.
+	*/
+	get(name) {
+		return this.#tools.get(name);
+	}
+	/**
+	* Returns `true` if a tool with the given name is registered.
+	*
+	* @param name - The tool name to test.
+	*/
+	has(name) {
+		return this.#tools.has(name);
+	}
+	/**
+	* Returns a fresh array of all registered tools in insertion order.
+	*
+	* @remarks
+	* Includes both visible and hidden tools. Use {@link visible} to get only non-hidden tools, or
+	* {@link hidden} to get only hidden tools.
+	*
+	* Since {@link @nhtio/adk!Tool} instances are immutable, no deep-cloning is needed.
+	*/
+	all() {
+		return Array.from(this.#tools.values());
+	}
+	/**
+	* Returns a fresh array of registered tools that are **not** hidden, in insertion order.
+	*
+	* @remarks
+	* This is the accessor LLM batteries should use when building the tool list for the model.
+	* Hidden tools are still callable (they resolve via {@link get}) but are excluded from the
+	* rendered tool definitions.
+	*/
+	visible() {
+		return this.all().filter((t) => !this.#hidden.has(t.name));
+	}
+	/**
+	* Returns a fresh array of registered tools that **are** hidden, in insertion order.
+	*
+	* @remarks
+	* The converse of {@link visible}. Useful for discovery tools that enumerate all available
+	* tools, and for propagating hidden state across {@link merge}.
+	*/
+	hidden() {
+		return this.all().filter((t) => this.#hidden.has(t.name));
+	}
+	/**
+	* Marks one or more registered tools as hidden.
+	*
+	* @remarks
+	* Hidden tools remain registered and callable via {@link get}, but are excluded from
+	* {@link visible} (and therefore from the LLM tool list). No-ops for any name that is not
+	* currently registered — the end result (the tool is not visible) matches the intent.
+	*
+	* @param names - One or more tool names to hide.
+	*/
+	hide(...names) {
+		for (const name of names) this.#hidden.add(name);
+	}
+	/**
+	* Unmarks one or more tools as hidden, making them visible again.
+	*
+	* @remarks
+	* No-ops for any name that is not currently hidden.
+	*
+	* @param names - One or more tool names to unhide.
+	*/
+	unhide(...names) {
+		for (const name of names) this.#hidden.delete(name);
+	}
+	/**
+	* Replaces the entire hidden set with the given tool names.
+	*
+	* @remarks
+	* Any previously hidden tool not in `names` becomes visible. Names that are not registered are
+	* silently ignored — they are added to the set but have no effect until a tool with that name
+	* is registered.
+	*
+	* @param names - The complete set of tool names to hide.
+	*/
+	setHidden(...names) {
+		this.#hidden = new Set(names);
+	}
+	/**
+	* Unhides every tool in the registry.
+	*/
+	clearHidden() {
+		this.#hidden.clear();
+	}
+	/**
+	* Removes every tool whose {@link @nhtio/adk!Tool.ephemeral} flag is `true`.
+	*
+	* @remarks
+	* Also removes pruned tool names from the hidden set. Synchronous and idempotent — calling it
+	* twice in a row is a no-op the second time. The canonical caller is
+	* {@link ToolRegistry.bindContext}, which schedules this method to run at
+	* {@link @nhtio/adk!DispatchContext.ack}. Non-ephemeral tools are left untouched.
+	*/
+	pruneEphemeral() {
+		for (const [name, tool] of this.#tools) if (tool.ephemeral) {
+			this.#tools.delete(name);
+			this.#hidden.delete(name);
+		}
+	}
+	/**
+	* Binds this registry to a {@link @nhtio/adk!DispatchContext} so that {@link pruneEphemeral} runs
+	* automatically when the context is acked.
+	*
+	* @remarks
+	* The handler does NOT fire on {@link @nhtio/adk!DispatchContext.nack} — failed executor runs leave
+	* any forged tools in place so the consumer can inspect what was registered when debugging the
+	* failure. Subscriptions are short-lived and die with the context regardless.
+	*
+	* ARTIFACT READERS ARE FORGED BY THE CORE. As of the core-forge change, the `DispatchRunner` forges
+	* artifact-reader tools from prior-turn `SpooledArtifact` results into `ctx.tools` (and calls
+	* `ctx.tools.bindContext(ctx)`) once per iteration, BEFORE the input pipeline — so a battery executor no
+	* longer forges or binds; it reads the already-forged `ctx.tools` for both representation (rendering the
+	* tool declarations) and resolution (looking up an incoming call by name). The lifecycle is unchanged:
+	* ephemeral readers are still pruned on `ack`, and the core re-forges each iteration (prune-then-forge) so
+	* the `callId` enum never goes stale.
+	*
+	* `bindContext` remains the public seam for a CUSTOM consumer that forges its own ephemeral tools outside
+	* the core path. If you forge into a long-lived registry yourself, bind it (or prune manually) or the
+	* ephemeral tools accumulate and later `forgeTools(ctx)` calls see a stale `callId` enum. The pattern for a
+	* hand-rolled forge is:
+	*
+	* ```ts
+	* // Custom forge (the core already does this for artifact readers on ctx.tools):
+	* const forged = SpooledArtifact.forgeTools(ctx)
+	* for (const tool of forged.all()) ctx.tools.register(tool, true)
+	* ctx.tools.bindContext(ctx) // prune the ephemeral readers when the dispatch acks
+	* ```
+	*
+	* @param ctx - The execution context whose `ack` event should trigger pruning.
+	* @returns An unsubscribe function — calling it before `ctx.ack()` prevents pruning. Rarely
+	*   useful outside of tests.
+	*
+	* @see {@link @nhtio/adk!SpooledArtifact.forgeTools}
+	* @see {@link @nhtio/adk!DispatchContext.onAck}
+	*/
+	bindContext(ctx) {
+		return ctx.onAck(() => this.pruneEphemeral());
+	}
+	/**
+	* Combines multiple {@link ToolRegistry} instances into a fresh registry without mutating any
+	* input.
+	*
+	* @remarks
+	* Iteration is left-to-right across `registries` and then in each registry's insertion order.
+	* Collisions are resolved by consulting the **incoming** tool's {@link @nhtio/adk!Tool.onCollision} first:
+	*
+	* - `'replace'` (per-tool): the incoming tool wins, replacing the existing entry.
+	* - `'keep'` (per-tool): the existing entry wins; the incoming tool is dropped.
+	* - `'throw'` (per-tool, the default): fall back to the merge-level `options.onCollision`.
+	*
+	* The merge-level `options.onCollision` defaults to `'throw'`, which mirrors {@link register}.
+	*
+	* The result is a brand-new registry; no input is mutated and no event subscription is
+	* propagated. Each `Tool`'s `ephemeral` flag carries through unchanged — the flag lives on the
+	* tool, not the registry, so `bindContext(ctx)` on the merged registry will prune the forged
+	* tools as expected.
+	*
+	* Hidden state is also propagated: a tool that is hidden in any source registry remains hidden
+	* in the merged result, provided it survives collision resolution.
+	*
+	* @param registries - Registries to merge, in priority order (left-to-right insertion).
+	* @param options - Merge-level collision policy. Defaults to `{ onCollision: 'throw' }`.
+	* @returns A fresh {@link ToolRegistry} containing the resolved union of all inputs.
+	* @throws {@link @nhtio/adk!E_TOOL_ALREADY_REGISTERED} when the resolved collision policy is `'throw'`
+	*   and a collision occurs.
+	*/
+	static merge(registries, options) {
+		const policy = options?.onCollision ?? "throw";
+		const merged = new ToolRegistry();
+		for (const registry of registries) {
+			for (const tool of registry.all()) {
+				if (!merged.get(tool.name)) {
+					merged.register(tool);
+					continue;
+				}
+				const incomingPolicy = tool.onCollision;
+				if (incomingPolicy === "replace") {
+					merged.register(tool, true);
+					continue;
+				}
+				if (incomingPolicy === "keep") continue;
+				if (policy === "replace") {
+					merged.register(tool, true);
+					continue;
+				}
+				if (policy === "keep") continue;
+				throw new E_TOOL_ALREADY_REGISTERED();
+			}
+			for (const tool of registry.hidden()) if (merged.has(tool.name)) merged.hide(tool.name);
+		}
+		return merged;
+	}
+	/**
+	* Serialise this ToolRegistry into an `@nhtio/encoder` snapshot.
+	*
+	* @remarks
+	* Emits the live {@link @nhtio/adk!Tool} instances (the encoder recurses into each — so every tool's
+	* handler-closure caveat from {@link Tool.[ENCODE_METHOD]} applies) plus the hidden-set names. Both
+	* {@link @nhtio/adk!Tool} and {@link @nhtio/adk!ArtifactTool} entries round-trip to their correct
+	* subtype. Round-trips via {@link ToolRegistry.[DECODE_METHOD]}.
+	*
+	* @returns A `{ tools, hidden }` snapshot.
+	*/
+	[ENCODE_METHOD]() {
+		return {
+			tools: this.all(),
+			hidden: this.hidden().map((tool) => tool.name)
+		};
+	}
+	/**
+	* Reconstruct a {@link ToolRegistry} from a {@link ToolRegistry.[ENCODE_METHOD]} snapshot.
+	*
+	* @param data - The snapshot produced by {@link ToolRegistry.[ENCODE_METHOD]}.
+	* @returns A fresh {@link ToolRegistry} with the same tools and hidden set.
+	*/
+	static [DECODE_METHOD](data) {
+		const snapshot = data;
+		const registry = new ToolRegistry(snapshot.tools);
+		registry.setHidden(...snapshot.hidden);
+		return registry;
+	}
+};
+//#endregion
 //#region src/lib/contracts/spool_reader.ts
 /**
 * Validator schema used to validate a {@link SpoolReader} value.
@@ -1628,6 +1628,6 @@ var SpooledArtifact = class SpooledArtifact {
 	}
 };
 //#endregion
-export { resolveArtifactById as a, resolveMediaReader as c, ArtifactTool as d, Tool as f, ToolRegistry as g, canonicalStringify as h, effectiveToolMethods as i, resolveSpoolReader as l, Registry as m, collectArtifactCompatibleIds as n, registerMediaReaderResolver as o, artifactConstructorResolverSchema as p, defaultSerialise as r, registerSpoolReaderResolver as s, SpooledArtifact as t, implementsSpoolReader as u };
+export { resolveArtifactById as a, resolveMediaReader as c, ToolRegistry as d, ArtifactTool as f, Registry as g, canonicalStringify as h, effectiveToolMethods as i, resolveSpoolReader as l, artifactConstructorResolverSchema as m, collectArtifactCompatibleIds as n, registerMediaReaderResolver as o, Tool as p, defaultSerialise as r, registerSpoolReaderResolver as s, SpooledArtifact as t, implementsSpoolReader as u };
 
-//# sourceMappingURL=spooled_artifact-BkOe4-j-.mjs.map
+//# sourceMappingURL=spooled_artifact-Bw_7swIp.mjs.map