@nhtio/adk 1.20260924.0 → 1.20260928.0

package/{spooled_artifact-BLgbGT8b.cjs → spooled_artifact---DmicFW.cjs}

@@ -1,310 +1,145 @@
 const require_chunk = require("./chunk-Cek0wNdY.cjs");
 const require_exceptions = require("./exceptions-DrHnAGQz.cjs");
 const require_guards = require("./guards-5-XmJgD2.cjs");
-const require_tokenizable = require("./tokenizable-DDIdXbJN.cjs");
-let luxon = require("luxon");
-let js_sha256 = require("js-sha256");
+const require_tokenizable = require("./tokenizable-BcodRtoW.cjs");
 let _nhtio_validation = require("@nhtio/validation");
 let dset = require("dset");
 let klona = require("klona");
 let dlv = require("dlv");
 dlv = require_chunk.__toESM(dlv);
-//#region src/lib/classes/tool_registry.ts
+let luxon = require("luxon");
+let js_sha256 = require("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 require_guards.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 require_tokenizable.E_TOOL_ALREADY_REGISTERED();
-		this.#tools.set(tool.name, tool);
+	constructor(initial) {
+		if ("undefined" !== typeof initial && !require_guards.isObject(initial)) throw new require_tokenizable.E_INVALID_INITIAL_REGISTRY_VALUE();
+		this.#store = initial ? (0, klona.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 require_guards.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 = (0, dlv.default)((0, klona.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) {
+		(0, dset.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 (0, dlv.default)(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 = (0, klona.klona)(this.#store);
+		const keys = [];
+		const isPlainRecord = (value) => {
+			if (!require_guards.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 (0, klona.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);
-		}
+	[require_tokenizable.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 require_tokenizable.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.
-	*/
-	[require_tokenizable.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 [require_tokenizable.DECODE_METHOD](data) {
-		const snapshot = data;
-		const registry = new ToolRegistry(snapshot.tools);
-		registry.setHidden(...snapshot.hidden);
-		return registry;
+	static [require_tokenizable.DECODE_METHOD](data) {
+		return new Registry(data);
 	}
 };
 //#endregion
@@ -333,140 +168,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 && !require_guards.isObject(initial)) throw new require_tokenizable.E_INVALID_INITIAL_REGISTRY_VALUE();
-		this.#store = initial ? (0, klona.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 require_guards.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 = (0, dlv.default)((0, klona.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) {
-		(0, dset.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 (0, dlv.default)(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 = (0, klona.klona)(this.#store);
-		const keys = [];
-		const isPlainRecord = (value) => {
-			if (!require_guards.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 (0, klona.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.
-	*/
-	[require_tokenizable.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 [require_tokenizable.DECODE_METHOD](data) {
-		return new Registry(data);
-	}
-};
-//#endregion
 //#region src/lib/contracts/spooled_artifact_constructor.ts
 var ARTIFACT_METHODS = [
 	"head",
@@ -935,6 +636,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 require_guards.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 require_tokenizable.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 require_tokenizable.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.
+	*/
+	[require_tokenizable.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 [require_tokenizable.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.
@@ -1727,4 +1727,4 @@ Object.defineProperty(exports, "resolveSpoolReader", {
 	}
 });
 
-//# sourceMappingURL=spooled_artifact-BLgbGT8b.cjs.map
+//# sourceMappingURL=spooled_artifact---DmicFW.cjs.map