@nhtio/adk 0.1.0-master-f0aa531d

package/tool_registry-Dkfprsck.js

@@ -0,0 +1,641 @@
+const require_chunk = require("./chunk-KmRHZBOW.js");
+const require_exceptions = require("./exceptions-D5YrO9Vm.js");
+const require_runtime = require("./runtime-BJVkrGQe.js");
+let js_tiktoken = require("js-tiktoken");
+let _nhtio_validation = require("@nhtio/validation");
+let llama_tokenizer_js = require("llama-tokenizer-js");
+let _lenml_tokenizer_gemini = require("@lenml/tokenizer-gemini");
+let dset = require("dset");
+let klona = require("klona");
+let dlv = require("dlv");
+dlv = require_chunk.__toESM(dlv);
+//#region src/lib/utils/guards.ts
+/**
+* Returns `true` if `value` is an instance of the class identified by `type` (and optionally `ctor`).
+*
+* @remarks
+* Performs three checks in order: `instanceof ctor`, `Symbol.hasInstance`, then constructor-name
+* comparison. The constructor-name fallback handles cross-realm cases where `instanceof` fails.
+*
+* @typeParam T - The expected instance type.
+* @param value - The value to test.
+* @param type - The constructor name to compare against when `instanceof` is unavailable.
+* @param ctor - Optional constructor to use for `instanceof` and `Symbol.hasInstance` checks.
+* @returns `true` when `value` is an instance of the class described by `type`/`ctor`.
+*/
+var isInstanceOf = (value, type, ctor) => {
+	if ("undefined" !== typeof ctor && value instanceof ctor) return true;
+	/* istanbul ignore next 4 */
+	if ("undefined" !== typeof ctor && typeof ctor[Symbol.hasInstance] === "function" && ctor[Symbol.hasInstance](value))
+ /* istanbul ignore next */
+	return true;
+	if ("object" === typeof value && null !== value) return value.constructor?.name === type;
+	return false;
+};
+var errorSchema = _nhtio_validation.validator.any().custom((value, helpers) => {
+	if (isInstanceOf(value, "Error", Error)) return value;
+	return helpers.error("any.invalid");
+}).required();
+/**
+* Returns `true` if `value` is an `Error` instance or satisfies the `Error` duck-type shape.
+*
+* @remarks
+* Returns `false` for `undefined` and `null` — the `Error` contract requires an actual instance.
+*
+* @param value - The value to test.
+* @returns `true` when `value` conforms to the `Error` shape.
+*/
+var isError = (value) => {
+	return require_exceptions.passesSchema(errorSchema, value);
+};
+/**
+* Type guard to check if a value is a plain object (not null, not array)
+* @param value - The value to check
+* @returns True if the value is a plain object, false otherwise
+*/
+var isObject = (value) => {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+};
+//#endregion
+//#region src/lib/classes/tokenizable.ts
+/**
+* The set of supported token encoding identifiers.
+*
+* @remarks
+* Each value maps to a specific estimation backend:
+* - `gpt2`, `r50k_base`, `p50k_base`, `p50k_edit`, `cl100k_base`, `o200k_base` — exact counts
+*   via `js-tiktoken` (OpenAI / tiktoken-compatible models).
+* - `gemini` — exact counts via `@lenml/tokenizer-gemini`, which embeds Gemini's actual
+*   SentencePiece vocabulary locally with no API call required.
+* - `llama2` — exact counts via `llama-tokenizer-js` (Llama 1 and 2). Llama 3+ uses a
+*   different vocabulary and should use the `llama3` identifier once a suitable sync backend
+*   is available.
+* - `claude` — heuristic approximation using Anthropic's published ~3.5 chars/token ratio.
+*   No local tokenizer is available for Claude 3+ models; the Anthropic SDK's
+*   `messages.countTokens()` API is the only exact path but requires a network call.
+*
+* When adding a new encoding, add a case to {@link Tokenizable.estimateTokens}.
+*/
+var TokenEncoding = [
+	"gpt2",
+	"r50k_base",
+	"p50k_base",
+	"p50k_edit",
+	"cl100k_base",
+	"o200k_base",
+	"gemini",
+	"llama2",
+	"claude"
+];
+/**
+* Backing schema for {@link Tokenizable.schema}.
+*
+* @remarks
+* Accepts a plain `string` or an existing {@link Tokenizable} instance. Strings pass through
+* unchanged; {@link Tokenizable} instances are accepted via {@link Tokenizable.isTokenizable}
+* to remain cross-realm safe.
+*/
+var stringOrTokenizableSchema = _nhtio_validation.validator.alternatives(_nhtio_validation.validator.string(), _nhtio_validation.validator.custom((value, helpers) => {
+	if (Tokenizable.isTokenizable(value)) return value;
+	return helpers.error("any.invalid");
+}));
+var geminiTokenizerInstance;
+var llamaTokenizerInstance;
+var getGeminiTokenizer = () => {
+	if (!geminiTokenizerInstance) geminiTokenizerInstance = (0, _lenml_tokenizer_gemini.fromPreTrained)();
+	return geminiTokenizerInstance;
+};
+var getLlamaTokenizer = () => {
+	if (!llamaTokenizerInstance) llamaTokenizerInstance = new llama_tokenizer_js.LlamaTokenizer();
+	return llamaTokenizerInstance;
+};
+/**
+* A mutable string with a built-in token counter.
+*
+* @remarks
+* The wrapped string can be read via the standard coercion protocol and updated at any time via
+* {@link Tokenizable.set}. Token counts are computed lazily on first access per encoding and
+* cached until the value changes, avoiding redundant encoder invocations when the same content
+* is measured multiple times across a pipeline.
+*
+* Estimation is dispatched by encoding identifier — see {@link TokenEncoding} for the full list
+* of supported backends and their accuracy characteristics. Unrecognised encodings fall back to
+* a `ceil(length / 4)` character heuristic.
+*
+* The class implements the standard JS value-coercion protocol (`toString`, `valueOf`,
+* `toJSON`, `toLocaleString`, `Symbol.for('nodejs.util.inspect.custom')`) so instances behave
+* transparently as strings in most contexts.
+*/
+var Tokenizable = class Tokenizable {
+	static TokenEncoding = TokenEncoding;
+	/**
+	* Validator schema that accepts a plain `string` or a {@link Tokenizable} instance.
+	*
+	* @remarks
+	* Reusable fragment for any schema that wants to accept either form — for example,
+	* `systemPrompt` and each item in `standingInstructions` in `turnContextSchema`.
+	*/
+	static schema = stringOrTokenizableSchema;
+	#value;
+	#cache = /* @__PURE__ */ new Map();
+	/**
+	* @param value - The initial string value to wrap.
+	*/
+	constructor(value) {
+		this.#value = value;
+		const estimateTokensWithTiktoken = (encoding) => {
+			try {
+				return (0, js_tiktoken.getEncoding)(encoding).encode(this.#value, []).length;
+			} catch {
+				return Number.POSITIVE_INFINITY;
+			}
+		};
+		const estimateTokensWithGemini = () => {
+			try {
+				return getGeminiTokenizer().encode(this.#value).length;
+			} catch {
+				return Number.POSITIVE_INFINITY;
+			}
+		};
+		const estimateTokensWithLlama2 = () => {
+			try {
+				return getLlamaTokenizer().encode(this.#value, false).length;
+			} catch {
+				return Number.POSITIVE_INFINITY;
+			}
+		};
+		const estimateTokensWithClaudeHeuristic = () => {
+			try {
+				return Math.ceil(this.#value.length / 3.5);
+			} catch {
+				return Number.POSITIVE_INFINITY;
+			}
+		};
+		Object.defineProperties(this, {
+			toJSON: {
+				value: () => this.#value,
+				enumerable: false,
+				configurable: false,
+				writable: false
+			},
+			toString: {
+				value: () => this.#value,
+				enumerable: false,
+				configurable: false,
+				writable: false
+			},
+			valueOf: {
+				value: () => this.#value,
+				enumerable: false,
+				configurable: false,
+				writable: false
+			},
+			toLocaleString: {
+				value: () => this.#value,
+				enumerable: false,
+				configurable: false,
+				writable: false
+			},
+			[Symbol.for("nodejs.util.inspect.custom")]: {
+				value: () => this.#value,
+				enumerable: false,
+				configurable: false,
+				writable: false
+			},
+			set: {
+				value: (next) => {
+					this.#value = next;
+					this.#cache.clear();
+				},
+				enumerable: false,
+				configurable: false,
+				writable: false
+			},
+			estimateTokens: {
+				value: (encoding) => {
+					if (this.#cache.has(encoding)) return this.#cache.get(encoding);
+					let estimate;
+					switch (encoding) {
+						case "gpt2":
+						case "r50k_base":
+						case "p50k_base":
+						case "p50k_edit":
+						case "cl100k_base":
+						case "o200k_base":
+							estimate = estimateTokensWithTiktoken(encoding);
+							break;
+						case "gemini":
+							estimate = estimateTokensWithGemini();
+							break;
+						case "llama2":
+							estimate = estimateTokensWithLlama2();
+							break;
+						case "claude":
+							estimate = estimateTokensWithClaudeHeuristic();
+							break;
+					}
+					if (estimate === Number.POSITIVE_INFINITY) estimate = Math.ceil(this.#value.length / 4);
+					else this.#cache.set(encoding, estimate);
+					return estimate;
+				},
+				enumerable: false,
+				configurable: false,
+				writable: false
+			}
+		});
+	}
+	/**
+	* Convenience overload for one-off token counting without managing a {@link Tokenizable} instance.
+	*
+	* @remarks
+	* Creates a temporary instance and immediately discards it — no caching benefit. Use the
+	* instance method when you need to count the same value under multiple encodings or when the
+	* value may change over time.
+	*
+	* @param value - The string to count tokens for.
+	* @param encoding - The encoding identifier to use for counting.
+	* @returns The estimated number of tokens.
+	*/
+	static estimateTokens(value, encoding) {
+		return new Tokenizable(value).estimateTokens(encoding);
+	}
+	/**
+	* Returns `true` if `value` is a {@link Tokenizable} instance.
+	*
+	* @remarks
+	* Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety — `instanceof` would fail for instances
+	* created in a different module copy or VM context.
+	*
+	* @param value - The value to test.
+	* @returns `true` when `value` is a {@link Tokenizable} instance.
+	*/
+	static isTokenizable(value) {
+		return isInstanceOf(value, "Tokenizable", Tokenizable);
+	}
+};
+//#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 require_runtime.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 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 (!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);
+	}
+};
+//#endregion
+//#region src/lib/utils/canonical_json.ts
+/**
+* Canonical `JSON.stringify` that sorts object keys recursively so that semantically-equal
+* objects produce identical strings.
+*
+* @remarks
+* Used wherever the ADK derives a stable identity from a structured value — for example,
+* `Tool.executor` computing the `callId` for `ToolExecutionStart`/`End` events, and the
+* `reportToolCall` executor helper computing the `checksum` field on `TurnToolCallContent`.
+* Both code paths hash `canonicalStringify({ tool, args })` so that argument key order does not
+* affect the resulting identifier.
+*
+* Arrays are serialised in their declared order (order is meaningful for an array). Object keys
+* are sorted with `Array.prototype.sort()`'s default lexicographic comparator.
+*
+* @param value - The value to serialise.
+* @returns A canonical JSON string representation of `value`.
+*/
+function canonicalStringify(value) {
+	if (value === null || typeof value !== "object") return JSON.stringify(value);
+	if (Array.isArray(value)) return "[" + value.map((v) => canonicalStringify(v)).join(",") + "]";
+	const obj = value;
+	return "{" + Object.keys(obj).sort().map((k) => JSON.stringify(k) + ":" + canonicalStringify(obj[k])).join(",") + "}";
+}
+//#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.
+*/
+var ToolRegistry = class ToolRegistry {
+	#tools;
+	/**
+	* 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();
+		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_runtime.E_TOOL_ALREADY_REGISTERED();
+		this.#tools.set(tool.name, tool);
+	}
+	/**
+	* Removes the tool with the given name from the registry.
+	*
+	* @remarks
+	* 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);
+	}
+	/**
+	* 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
+	* Since {@link @nhtio/adk!Tool} instances are immutable, no deep-cloning is needed.
+	*/
+	all() {
+		return Array.from(this.#tools.values());
+	}
+	/**
+	* Removes every tool whose {@link @nhtio/adk!Tool.ephemeral} flag is `true`.
+	*
+	* @remarks
+	* 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);
+	}
+	/**
+	* 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.
+	*
+	* Forgetting this call after merging in `Subclass.forgeTools(ctx)` output means ephemeral tools
+	* accumulate across executor invocations, and subsequent `forgeTools(ctx)` calls in later
+	* iterations will see a stale `callId` enum that excludes new tool calls. The plan-documented
+	* pattern is:
+	*
+	* ```ts
+	* const executor: DispatchExecutorFn = async (ctx) => {
+	*   const forged = SpooledArtifact.forgeTools(ctx)
+	*   const merged = ToolRegistry.merge([main, forged])
+	*   main.bindContext(ctx)
+	*   const result = await llm.invoke({ tools: merged.all(), ... })
+	*   ctx.ack()
+	* }
+	* ```
+	*
+	* @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.
+	*
+	* @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_runtime.E_TOOL_ALREADY_REGISTERED();
+		}
+		return merged;
+	}
+};
+//#endregion
+Object.defineProperty(exports, "Registry", {
+	enumerable: true,
+	get: function() {
+		return Registry;
+	}
+});
+Object.defineProperty(exports, "TokenEncoding", {
+	enumerable: true,
+	get: function() {
+		return TokenEncoding;
+	}
+});
+Object.defineProperty(exports, "Tokenizable", {
+	enumerable: true,
+	get: function() {
+		return Tokenizable;
+	}
+});
+Object.defineProperty(exports, "ToolRegistry", {
+	enumerable: true,
+	get: function() {
+		return ToolRegistry;
+	}
+});
+Object.defineProperty(exports, "canonicalStringify", {
+	enumerable: true,
+	get: function() {
+		return canonicalStringify;
+	}
+});
+Object.defineProperty(exports, "isError", {
+	enumerable: true,
+	get: function() {
+		return isError;
+	}
+});
+Object.defineProperty(exports, "isInstanceOf", {
+	enumerable: true,
+	get: function() {
+		return isInstanceOf;
+	}
+});
+Object.defineProperty(exports, "isObject", {
+	enumerable: true,
+	get: function() {
+		return isObject;
+	}
+});
+
+//# sourceMappingURL=tool_registry-Dkfprsck.js.map