@nhtio/adk 0.1.0-master-f0aa531d

package/tool-D2WB1EA1.mjs

@@ -0,0 +1,296 @@
+import { a as validateOrThrow, i as passesSchema, n as ValidationException, r as asyncValidateOrThrow } from "./exceptions-NrzIHw_R.mjs";
+import { n as canonicalStringify, o as isError, r as Registry, s as isInstanceOf } from "./tool_registry-DqLOyGyG.mjs";
+import { D as E_TOOL_DOWNSTREAM_ERROR, d as E_INVALID_INITIAL_TOOL_VALUE, h as E_INVALID_TOOL_ARGS } from "./runtime-CrEPIFgr.mjs";
+import { validator } from "@nhtio/validation";
+import { DateTime } from "luxon";
+import { sha256 } from "js-sha256";
+//#region src/lib/contracts/spooled_artifact_constructor.ts
+var ARTIFACT_METHODS = [
+	"head",
+	"tail",
+	"grep",
+	"cat",
+	"byteLength",
+	"lineCount",
+	"estimateTokens"
+];
+/**
+* Validator schema used to validate a {@link SpooledArtifactConstructorLike} value.
+*
+* @remarks
+* Because the validator is invoked at validate-time (not at module-load), it is safe to inspect
+* the constructor's prototype here. The check is duck-typed: the value must be a function whose
+* `prototype` carries every canonical artifact instance method (`head`, `tail`, `grep`, `cat`,
+* `byteLength`, `lineCount`, `estimateTokens`). This mirrors {@link spoolReaderSchema}'s
+* cross-realm-safe duck-type pattern — `instanceof SpooledArtifact` would be tighter but would
+* force a value-import of the class and reopen the module cycle.
+*/
+var spooledArtifactConstructorSchema = validator.any().custom((value, helpers) => {
+	if (typeof value !== "function") return helpers.error("any.invalid");
+	const proto = value.prototype;
+	if (proto === void 0 || proto === null) return helpers.error("any.invalid");
+	if (ARTIFACT_METHODS.every((m) => typeof proto[m] === "function")) return value;
+	return helpers.error("any.invalid");
+});
+/**
+* Returns `true` if `value` is a constructor whose prototype carries every canonical
+* {@link @nhtio/adk!SpooledArtifact} instance method.
+*
+* @remarks
+* Duck-typed; does not use `instanceof SpooledArtifact`. Used by the `Tool.artifactConstructor`
+* resolver validator and any other site that needs to recognise a `SpooledArtifact`-like
+* constructor without pulling the class into its module-load graph.
+*
+* @param value - The value to test.
+* @returns `true` when `value` is a `SpooledArtifact`-shaped constructor.
+*/
+var implementsSpooledArtifactConstructor = (value) => {
+	return passesSchema(spooledArtifactConstructorSchema, value);
+};
+//#endregion
+//#region src/lib/classes/tool.ts
+/**
+* Validator schema for a {@link RawTool}.
+*/
+var rawToolSchema = validator.object({
+	name: validator.string().required(),
+	description: validator.string().required(),
+	inputSchema: validator.any().custom((value, helpers) => {
+		if (validator.isSchema(value) && value.type === "object") return value;
+		return helpers.error("any.invalid");
+	}).required(),
+	handler: validator.function().required(),
+	artifactConstructor: validator.any().custom((value, helpers) => {
+		if (typeof value !== "function") return helpers.error("any.invalid");
+		let resolved;
+		try {
+			resolved = value();
+		} catch {
+			return helpers.error("any.invalid");
+		}
+		if (implementsSpooledArtifactConstructor(resolved)) return value;
+		return helpers.error("any.invalid");
+	}).optional(),
+	meta: validator.object().pattern(validator.string(), validator.any()).default({}),
+	ephemeral: validator.boolean().default(false),
+	trusted: validator.boolean().default(false),
+	onCollision: validator.string().valid("throw", "replace", "keep").default("throw")
+});
+/**
+* A tool definition that serves as the single source of truth for a callable tool: its name,
+* description, input schema, execution handler, and the {@link @nhtio/adk!SpooledArtifact} subclass that
+* wraps its serialised output.
+*
+* @typeParam A - The {@link @nhtio/adk!SpooledArtifact} subtype this tool's results should be wrapped in.
+*   Defaults to {@link @nhtio/adk!SpooledArtifact}.
+*
+* @remarks
+* The `inputSchema` is a `@nhtio/validation` schema. It is used at runtime to validate incoming
+* arguments before the handler is called, and its `.describe()` output provides all the metadata
+* needed to build a provider-specific LLM tool definition — annotate the schema with
+* `.description()`, `.note()`, `.example()` etc. once, and that information is available in both
+* contexts without duplication.
+*
+* The handler is private — invoke it only through `executor(ctx)` which validates args, fires
+* observability events (with a stable `callId` derived from the tool name and arguments), and
+* wraps handler errors in {@link @nhtio/adk!E_TOOL_DOWNSTREAM_ERROR}. The handler returns serialised bytes
+* (`string | Uint8Array`); persistence is the consumer's responsibility.
+*
+* `artifactConstructor` is the {@link @nhtio/adk!SpooledArtifact} subclass the consumer should use when
+* wrapping the handler's output into a `ToolCall.results` field. The author declares it once
+* on the tool instance; the consumer reads it when assembling persisted records.
+*/
+var Tool = class Tool {
+	/**
+	* Validator schema that accepts a {@link RawTool} object.
+	*
+	* @remarks
+	* Reusable fragment for any schema that needs to validate or nest a tool entry
+	* (e.g. `TurnRunnerConfig.tools`).
+	*/
+	static schema = rawToolSchema;
+	/**
+	* Returns `true` if `value` is a {@link Tool} instance.
+	*
+	* @param value - The value to test.
+	* @returns `true` when `value` is a {@link Tool} instance.
+	*/
+	static isTool(value) {
+		return isInstanceOf(value, "Tool", Tool);
+	}
+	#name;
+	#description;
+	#inputSchema;
+	#handler;
+	#artifactConstructor;
+	#meta;
+	#ephemeral;
+	#trusted;
+	#onCollision;
+	/**
+	* @param raw - The raw tool input validated against `rawToolSchema`.
+	* @throws {@link @nhtio/adk!E_INVALID_INITIAL_TOOL_VALUE} when `raw` does not satisfy the schema.
+	*/
+	constructor(raw) {
+		let resolved;
+		try {
+			resolved = validateOrThrow(rawToolSchema, raw, true);
+		} catch (err) {
+			throw new E_INVALID_INITIAL_TOOL_VALUE({ cause: isError(err) ? err : void 0 });
+		}
+		this.#name = resolved.name;
+		this.#description = resolved.description;
+		this.#inputSchema = resolved.inputSchema;
+		this.#handler = resolved.handler;
+		this.#artifactConstructor = resolved.artifactConstructor;
+		this.#meta = new Registry(resolved.meta);
+		this.#ephemeral = resolved.ephemeral;
+		this.#trusted = resolved.trusted;
+		this.#onCollision = resolved.onCollision;
+		Object.defineProperties(this, {
+			name: {
+				get: () => this.#name,
+				enumerable: true,
+				configurable: false
+			},
+			description: {
+				get: () => this.#description,
+				enumerable: true,
+				configurable: false
+			},
+			inputSchema: {
+				get: () => this.#inputSchema,
+				enumerable: true,
+				configurable: false
+			},
+			artifactConstructor: {
+				get: () => this.#artifactConstructor,
+				enumerable: true,
+				configurable: false
+			},
+			meta: {
+				get: () => this.#meta,
+				enumerable: true,
+				configurable: false
+			},
+			ephemeral: {
+				get: () => this.#ephemeral,
+				enumerable: true,
+				configurable: false
+			},
+			trusted: {
+				get: () => this.#trusted,
+				enumerable: true,
+				configurable: false
+			},
+			onCollision: {
+				get: () => this.#onCollision,
+				enumerable: true,
+				configurable: false
+			}
+		});
+	}
+	/**
+	* Validates `args` against the tool's input schema asynchronously.
+	*
+	* @remarks
+	* Async to support schemas with external validators (e.g. database lookups, API calls).
+	* A validation failure throws {@link @nhtio/adk!E_INVALID_TOOL_ARGS} — this indicates a programming error
+	* in the tool call loop, not a downstream failure.
+	*
+	* @param args - The arguments to validate.
+	* @returns The validated (and coerced) arguments.
+	* @throws {@link @nhtio/adk!E_INVALID_TOOL_ARGS} when `args` does not satisfy the input schema.
+	*/
+	async validate(args) {
+		try {
+			return await asyncValidateOrThrow(this.#inputSchema, args);
+		} catch (err) {
+			if (isInstanceOf(err, "ValidationException", ValidationException)) throw new E_INVALID_TOOL_ARGS({ cause: err });
+			throw err;
+		}
+	}
+	/**
+	* Returns a bound executor function for this tool against the given turn context.
+	*
+	* @remarks
+	* The executor: (1) computes a stable `callId` as `sha256(canonicalStringify({tool, args}))`
+	* over the **raw, pre-validation args**, (2) validates `args` via {@link Tool.validate},
+	* (3) emits `toolExecutionStart` on the context (with the computed `callId`), (4) calls the
+	* handler, (5) emits `toolExecutionEnd` (with the same `callId`), (6) wraps any handler error
+	* in {@link @nhtio/adk!E_TOOL_DOWNSTREAM_ERROR} before re-throwing.
+	*
+	* The handler returns serialised bytes (`string | Uint8Array`) — persistence is the consumer's
+	* concern. Use {@link Tool.artifactConstructor} when wrapping the bytes into a
+	* `ToolCall.results` field.
+	*
+	* Pattern mirrors `Middleware.runner()` — call once per turn, reuse the returned function.
+	*
+	* @param ctx - The active turn context. Provides emit functions and turn ID.
+	* @returns An async function `(args) => Promise<string | Uint8Array>`.
+	*/
+	executor(ctx) {
+		return async (args) => {
+			const callId = sha256(canonicalStringify({
+				tool: this.#name,
+				args
+			}));
+			const validatedArgs = await this.validate(args);
+			const startedAt = DateTime.now();
+			ctx.emitToolExecutionStart({
+				toolName: this.#name,
+				turnId: ctx.id,
+				callId,
+				args: validatedArgs,
+				startedAt
+			});
+			try {
+				const result = await this.#handler(validatedArgs, ctx, this.#meta);
+				const endedAt = DateTime.now();
+				ctx.emitToolExecutionEnd({
+					toolName: this.#name,
+					turnId: ctx.id,
+					callId,
+					startedAt,
+					endedAt,
+					durationMs: endedAt.diff(startedAt).milliseconds,
+					isError: false
+				});
+				return result;
+			} catch (err) {
+				const endedAt = DateTime.now();
+				ctx.emitToolExecutionEnd({
+					toolName: this.#name,
+					turnId: ctx.id,
+					callId,
+					startedAt,
+					endedAt,
+					durationMs: endedAt.diff(startedAt).milliseconds,
+					isError: true
+				});
+				throw new E_TOOL_DOWNSTREAM_ERROR({ cause: isError(err) ? err : void 0 });
+			}
+		};
+	}
+	/**
+	* Returns a fully serialisable snapshot of this tool's definition.
+	*
+	* @remarks
+	* The `inputSchema` property is the result of calling `.describe()` on the raw schema — a plain
+	* object carrying all the annotation metadata (descriptions, notes, examples, types) without any
+	* validator functions. Use this to build provider-specific LLM tool definitions.
+	*
+	* @returns `{ name, description, inputSchema }` where `inputSchema` is the schema description.
+	*/
+	describe() {
+		return {
+			name: this.#name,
+			description: this.#description,
+			inputSchema: this.#inputSchema.describe()
+		};
+	}
+};
+//#endregion
+export { Tool as t };
+
+//# sourceMappingURL=tool-D2WB1EA1.mjs.map

package/tool-D2WB1EA1.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-D2WB1EA1.mjs","names":["#name","#description","#inputSchema","#handler","#artifactConstructor","#meta","#ephemeral","#trusted","#onCollision"],"sources":["../src/lib/contracts/spooled_artifact_constructor.ts","../src/lib/classes/tool.ts"],"sourcesContent":["import { validator } from '@nhtio/validation'\nimport { passesSchema } from '../utils/validation'\nimport type { SpooledArtifact } from '../classes/spooled_artifact'\n\n/**\n * Constructor signature for any {@link @nhtio/adk!SpooledArtifact} (the class itself or a subclass).\n *\n * @remarks\n * Re-declared here at the contract level so consumers — and the `Tool.artifactConstructor`\n * resolver validator in particular — can talk about the constructor shape without value-importing\n * the {@link @nhtio/adk!SpooledArtifact} class (which would close the `tool.ts` ↔ `spooled_artifact.ts` ↔\n * `artifact_tool.ts` module cycle at load time and TDZ-crash `ArtifactTool extends Tool`).\n *\n * @typeParam A - The {@link @nhtio/adk!SpooledArtifact} subtype the constructor produces.\n */\nexport type SpooledArtifactConstructorLike<A extends SpooledArtifact = SpooledArtifact> = new (\n  ...args: any[]\n) => A\n\nconst ARTIFACT_METHODS = [\n  'head',\n  'tail',\n  'grep',\n  'cat',\n  'byteLength',\n  'lineCount',\n  'estimateTokens',\n] as const\n\n/**\n * Validator schema used to validate a {@link SpooledArtifactConstructorLike} value.\n *\n * @remarks\n * Because the validator is invoked at validate-time (not at module-load), it is safe to inspect\n * the constructor's prototype here. The check is duck-typed: the value must be a function whose\n * `prototype` carries every canonical artifact instance method (`head`, `tail`, `grep`, `cat`,\n * `byteLength`, `lineCount`, `estimateTokens`). This mirrors {@link spoolReaderSchema}'s\n * cross-realm-safe duck-type pattern — `instanceof SpooledArtifact` would be tighter but would\n * force a value-import of the class and reopen the module cycle.\n */\nexport const spooledArtifactConstructorSchema = validator.any().custom((value, helpers) => {\n  if (typeof value !== 'function') return helpers.error('any.invalid')\n  const proto = (value as { prototype?: unknown }).prototype\n  if (proto === undefined || proto === null) return helpers.error('any.invalid')\n  if (ARTIFACT_METHODS.every((m) => typeof (proto as Record<string, unknown>)[m] === 'function')) {\n    return value\n  }\n  return helpers.error('any.invalid')\n})\n\n/**\n * Returns `true` if `value` is a constructor whose prototype carries every canonical\n * {@link @nhtio/adk!SpooledArtifact} instance method.\n *\n * @remarks\n * Duck-typed; does not use `instanceof SpooledArtifact`. Used by the `Tool.artifactConstructor`\n * resolver validator and any other site that needs to recognise a `SpooledArtifact`-like\n * constructor without pulling the class into its module-load graph.\n *\n * @param value - The value to test.\n * @returns `true` when `value` is a `SpooledArtifact`-shaped constructor.\n */\nexport const implementsSpooledArtifactConstructor = (\n  value: unknown\n): value is SpooledArtifactConstructorLike => {\n  return passesSchema(spooledArtifactConstructorSchema, value)\n}\n","import { DateTime } from 'luxon'\nimport { sha256 } from 'js-sha256'\nimport { Registry } from './registry'\nimport { validator } from '@nhtio/validation'\nimport { isInstanceOf, isError } from '../utils/guards'\nimport { canonicalStringify } from '../utils/canonical_json'\nimport { validateOrThrow, asyncValidateOrThrow, ValidationException } from '../utils/validation'\nimport { implementsSpooledArtifactConstructor } from '../contracts/spooled_artifact_constructor'\nimport {\n  E_INVALID_INITIAL_TOOL_VALUE,\n  E_INVALID_TOOL_ARGS,\n  E_TOOL_DOWNSTREAM_ERROR,\n} from '../exceptions/runtime'\nimport type { Media } from './media'\nimport type { Schema, Description } from '@nhtio/validation'\nimport type { DispatchContext } from '../contracts/dispatch_context'\nimport type { SpooledArtifact, SpooledArtifactConstructor } from './spooled_artifact'\n\n/**\n * A zero-arg function that returns the {@link @nhtio/adk!SpooledArtifactConstructor} the consumer should\n * use when wrapping this tool's serialised output into a `ToolCall.results` field.\n *\n * @remarks\n * Why a resolver (and not the constructor itself)? `tool.ts` participates in a module-load\n * cycle with `spooled_artifact.ts` and `artifact_tool.ts` (`ArtifactTool extends Tool` closes\n * the loop). Any eager value-level reference to `SpooledArtifact` in `tool.ts` would crash the\n * cycle with a TDZ error. A resolver lets `tool.ts` validate \"is a function\" at module-load\n * time and defer the actual constructor check to validate-time (which always runs after every\n * module body has executed). Wrap-sites invoke `tool.artifactConstructor?.() ?? SpooledArtifact`\n * to obtain the final constructor.\n */\nexport type ArtifactConstructorResolver<A extends SpooledArtifact = SpooledArtifact> =\n  () => SpooledArtifactConstructor<A>\n\n/**\n * The execution function for a {@link Tool}.\n *\n * @remarks\n * Receives the raw arguments passed to the executor, the active {@link @nhtio/adk!DispatchContext}, and the\n * tool's metadata registry.\n *\n * Return shapes:\n * - `string` / `Uint8Array` — opaque serialised output. The ADK does not persist the bytes\n *   itself; the consumer's executor middleware is responsible for storing them and wrapping\n *   them via `tool.artifactConstructor?.() ?? SpooledArtifact` when assembling the `ToolCall`\n *   record.\n * - {@link @nhtio/adk!Media} / `Media[]` — explicit-modality silo. Bypasses\n *   {@link Tool.artifactConstructor} — the handler returns the final result shape directly.\n *   The LLM battery renders each `Media` as a provider-specific content block.\n */\nexport type ToolHandler = (\n  args: unknown,\n  ctx: DispatchContext,\n  meta: Registry\n) => string | Uint8Array | Media | Media[] | Promise<string | Uint8Array | Media | Media[]>\n\n/**\n * Plain input object supplied to {@link Tool} at construction time.\n *\n * @typeParam A - The {@link @nhtio/adk!SpooledArtifact} subtype used to wrap this tool's results when\n *   the consumer assembles a `ToolCall.results` field. Defaults to {@link @nhtio/adk!SpooledArtifact}\n *   (plain text). Tools producing JSON output should set this to `SpooledJsonArtifact`; tools\n *   producing markdown should set it to `SpooledMarkdownArtifact`; consumers can also pass a\n *   custom subclass.\n */\nexport interface RawTool<A extends SpooledArtifact = SpooledArtifact> {\n  /** Unique identifier used in LLM tool definitions. Recommend lowercase snake_case. */\n  name: string\n  /** Human-readable description passed to the model to explain what the tool does. */\n  description: string\n  /** @nhtio/validation schema for the tool's input arguments. Annotate with `.description()`, `.note()`, `.example()` etc. to produce rich LLM tool definitions via `.describe()`. */\n  inputSchema: Schema\n  /** Execution function. Not exposed as a public property — invoke via `executor()`. */\n  handler: ToolHandler\n  /**\n   * Zero-arg resolver returning the {@link @nhtio/adk!SpooledArtifactConstructor} the consumer should use\n   * when wrapping this tool's serialised output into a `ToolCall.results` field. Optional —\n   * when omitted, wrap-sites fall back to {@link @nhtio/adk!SpooledArtifact} (plain text).\n   *\n   * @remarks\n   * Recommended call shape: `artifactConstructor: () => SpooledJsonArtifact`. The closure is\n   * the indirection that lets `tool.ts` validate this field without eagerly importing\n   * `SpooledArtifact` (which would crash the `tool.ts ↔ spooled_artifact.ts ↔ artifact_tool.ts`\n   * module-load cycle). At validate time the schema invokes the resolver and verifies its\n   * return value is a `SpooledArtifact`-derived constructor — wrong-shape resolvers throw\n   * {@link @nhtio/adk!E_INVALID_INITIAL_TOOL_VALUE}.\n   *\n   * Wrap-sites (storage batteries, scripted executors) read the constructor via\n   * `tool.artifactConstructor?.() ?? SpooledArtifact`.\n   */\n  artifactConstructor?: ArtifactConstructorResolver<A>\n  /** Optional arbitrary metadata for this tool (e.g. RBAC scopes, feature flags). Defaults to `{}`. Stored in a {@link @nhtio/adk!Registry} for dot-path access. */\n  meta?: Record<string, unknown>\n  /**\n   * When `true`, marks this tool as owned by a specific {@link @nhtio/adk!DispatchContext} so that\n   * `ToolRegistry.pruneEphemeral()` will drop it at ctx-completion.\n   *\n   * @remarks\n   * The flag is advisory at the `Tool` level — registries decide what to do with it. The canonical\n   * producer of ephemeral tools is `SpooledArtifact.forgeTools(ctx)`, which sets this to `true`\n   * on every artifact-query tool it emits.\n   *\n   * @defaultValue `false`\n   */\n  ephemeral?: boolean\n  /**\n   * When `true`, declares that this tool's output should be treated as **trusted developer/user\n   * intent** rather than as untrusted third-party text when surfaced to the model.\n   *\n   * @remarks\n   * LLM batteries read this flag per call when rendering tool-call results. The default\n   * untrusted envelope (e.g. `<untrusted_content>` in the OpenAI Chat Completions battery) is the\n   * secure-by-default treatment for arbitrary tool output. A tool whose output is authored by the\n   * user or operator (Q&A tools surfacing user-authored answers, human-in-the-loop approval\n   * gates, feedback-collection tools, configuration tools returning developer-authored\n   * constants) sets this to `true` so the LLM battery routes the result through its trusted\n   * envelope (`<trusted_content>` in the OpenAI Chat Completions battery).\n   *\n   * Trust is a property of the tool's output, not a property of how a particular battery is\n   * wired — putting the flag here means the trust signal travels with the tool wherever it is\n   * registered, no per-battery string lists, no name-matching to fail-open on typos.\n   *\n   * @defaultValue `false`\n   */\n  trusted?: boolean\n  /**\n   * Self-declared merge collision policy. Honoured by `ToolRegistry.merge` (NOT by\n   * `ToolRegistry.register`) when this tool collides with another of the same name.\n   *\n   * @remarks\n   * - `'throw'` (default): defer to the merge-level `options.onCollision`. If that is also\n   *   `'throw'`, the merge raises `E_TOOL_ALREADY_REGISTERED`. This matches the default behaviour\n   *   of `ToolRegistry.register`.\n   * - `'replace'`: this tool always wins the collision, regardless of the merge-level option.\n   * - `'keep'`: this tool always loses to any previously-registered tool of the same name.\n   *\n   * Forged artifact-query tools set this to `'replace'` so that merging multiple\n   * `Subclass.forgeTools(ctx)` outputs (whose base-method tools overlap by name) resolves\n   * silently — the descriptors, snapshot, and handler behaviour are interchangeable across\n   * subclasses, so replacement is a behavioural no-op.\n   *\n   * @defaultValue `'throw'`\n   */\n  onCollision?: 'throw' | 'replace' | 'keep'\n}\n\n/**\n * Validator schema for a {@link RawTool}.\n */\nconst rawToolSchema = validator.object<RawTool>({\n  name: validator.string().required(),\n  description: validator.string().required(),\n  inputSchema: validator\n    .any()\n    .custom((value, helpers) => {\n      if (validator.isSchema(value) && (value as any).type === 'object') return value\n      return helpers.error('any.invalid')\n    })\n    .required(),\n  handler: validator.function().required(),\n  artifactConstructor: validator\n    .any()\n    .custom((value, helpers) => {\n      if (typeof value !== 'function') return helpers.error('any.invalid')\n      // The resolver runs at validate time — well after the tool.ts ↔ spooled_artifact.ts ↔\n      // artifact_tool.ts module cycle has fully unwound — so invoking it is safe. Delegate the\n      // \"is this a SpooledArtifact-shaped constructor?\" check to the contract-level guard so\n      // there's one canonical duck-type test (mirrors `implementsSpoolReader`'s pattern).\n      let resolved: unknown\n      try {\n        resolved = (value as () => unknown)()\n      } catch {\n        return helpers.error('any.invalid')\n      }\n      if (implementsSpooledArtifactConstructor(resolved)) return value\n      return helpers.error('any.invalid')\n    })\n    .optional(),\n  meta: validator.object().pattern(validator.string(), validator.any()).default({}),\n  ephemeral: validator.boolean().default(false),\n  trusted: validator.boolean().default(false),\n  onCollision: validator.string().valid('throw', 'replace', 'keep').default('throw'),\n})\n\n/**\n * A tool definition that serves as the single source of truth for a callable tool: its name,\n * description, input schema, execution handler, and the {@link @nhtio/adk!SpooledArtifact} subclass that\n * wraps its serialised output.\n *\n * @typeParam A - The {@link @nhtio/adk!SpooledArtifact} subtype this tool's results should be wrapped in.\n *   Defaults to {@link @nhtio/adk!SpooledArtifact}.\n *\n * @remarks\n * The `inputSchema` is a `@nhtio/validation` schema. It is used at runtime to validate incoming\n * arguments before the handler is called, and its `.describe()` output provides all the metadata\n * needed to build a provider-specific LLM tool definition — annotate the schema with\n * `.description()`, `.note()`, `.example()` etc. once, and that information is available in both\n * contexts without duplication.\n *\n * The handler is private — invoke it only through `executor(ctx)` which validates args, fires\n * observability events (with a stable `callId` derived from the tool name and arguments), and\n * wraps handler errors in {@link @nhtio/adk!E_TOOL_DOWNSTREAM_ERROR}. The handler returns serialised bytes\n * (`string | Uint8Array`); persistence is the consumer's responsibility.\n *\n * `artifactConstructor` is the {@link @nhtio/adk!SpooledArtifact} subclass the consumer should use when\n * wrapping the handler's output into a `ToolCall.results` field. The author declares it once\n * on the tool instance; the consumer reads it when assembling persisted records.\n */\nexport class Tool<A extends SpooledArtifact = SpooledArtifact> {\n  /**\n   * Validator schema that accepts a {@link RawTool} object.\n   *\n   * @remarks\n   * Reusable fragment for any schema that needs to validate or nest a tool entry\n   * (e.g. `TurnRunnerConfig.tools`).\n   */\n  public static schema = rawToolSchema\n\n  /**\n   * Returns `true` if `value` is a {@link Tool} instance.\n   *\n   * @param value - The value to test.\n   * @returns `true` when `value` is a {@link Tool} instance.\n   */\n  public static isTool(value: unknown): value is Tool {\n    return isInstanceOf(value, 'Tool', Tool)\n  }\n\n  declare readonly name: string\n  declare readonly description: string\n  declare readonly inputSchema: Schema\n  declare readonly artifactConstructor: ArtifactConstructorResolver<A> | undefined\n  declare readonly meta: Registry\n  declare readonly ephemeral: boolean\n  declare readonly trusted: boolean\n  declare readonly onCollision: 'throw' | 'replace' | 'keep'\n\n  #name: string\n  #description: string\n  #inputSchema: Schema\n  #handler: ToolHandler\n  #artifactConstructor: ArtifactConstructorResolver<A> | undefined\n  #meta: Registry\n  #ephemeral: boolean\n  #trusted: boolean\n  #onCollision: 'throw' | 'replace' | 'keep'\n\n  /**\n   * @param raw - The raw tool input validated against `rawToolSchema`.\n   * @throws {@link @nhtio/adk!E_INVALID_INITIAL_TOOL_VALUE} when `raw` does not satisfy the schema.\n   */\n  constructor(raw: RawTool<A>) {\n    let resolved: RawTool<A> & {\n      meta: Record<string, unknown>\n      ephemeral: boolean\n      trusted: boolean\n      onCollision: 'throw' | 'replace' | 'keep'\n    }\n    try {\n      resolved = validateOrThrow<typeof resolved>(\n        rawToolSchema,\n        raw as RawTool,\n        true\n      ) as typeof resolved\n    } catch (err) {\n      throw new E_INVALID_INITIAL_TOOL_VALUE({ cause: isError(err) ? err : undefined })\n    }\n\n    this.#name = resolved.name\n    this.#description = resolved.description\n    this.#inputSchema = resolved.inputSchema\n    this.#handler = resolved.handler\n    this.#artifactConstructor = resolved.artifactConstructor as\n      | ArtifactConstructorResolver<A>\n      | undefined\n    this.#meta = new Registry(resolved.meta)\n    this.#ephemeral = resolved.ephemeral\n    this.#trusted = resolved.trusted\n    this.#onCollision = resolved.onCollision\n\n    Object.defineProperties(this, {\n      name: {\n        get: () => this.#name,\n        enumerable: true,\n        configurable: false,\n      },\n      description: {\n        get: () => this.#description,\n        enumerable: true,\n        configurable: false,\n      },\n      inputSchema: {\n        get: () => this.#inputSchema,\n        enumerable: true,\n        configurable: false,\n      },\n      artifactConstructor: {\n        get: () => this.#artifactConstructor,\n        enumerable: true,\n        configurable: false,\n      },\n      meta: {\n        get: () => this.#meta,\n        enumerable: true,\n        configurable: false,\n      },\n      ephemeral: {\n        get: () => this.#ephemeral,\n        enumerable: true,\n        configurable: false,\n      },\n      trusted: {\n        get: () => this.#trusted,\n        enumerable: true,\n        configurable: false,\n      },\n      onCollision: {\n        get: () => this.#onCollision,\n        enumerable: true,\n        configurable: false,\n      },\n    })\n  }\n\n  /**\n   * Validates `args` against the tool's input schema asynchronously.\n   *\n   * @remarks\n   * Async to support schemas with external validators (e.g. database lookups, API calls).\n   * A validation failure throws {@link @nhtio/adk!E_INVALID_TOOL_ARGS} — this indicates a programming error\n   * in the tool call loop, not a downstream failure.\n   *\n   * @param args - The arguments to validate.\n   * @returns The validated (and coerced) arguments.\n   * @throws {@link @nhtio/adk!E_INVALID_TOOL_ARGS} when `args` does not satisfy the input schema.\n   */\n  async validate(args: unknown): Promise<unknown> {\n    try {\n      return await asyncValidateOrThrow(this.#inputSchema, args)\n    } catch (err) {\n      if (isInstanceOf(err, 'ValidationException', ValidationException)) {\n        throw new E_INVALID_TOOL_ARGS({ cause: err })\n      }\n      throw err\n    }\n  }\n\n  /**\n   * Returns a bound executor function for this tool against the given turn context.\n   *\n   * @remarks\n   * The executor: (1) computes a stable `callId` as `sha256(canonicalStringify({tool, args}))`\n   * over the **raw, pre-validation args**, (2) validates `args` via {@link Tool.validate},\n   * (3) emits `toolExecutionStart` on the context (with the computed `callId`), (4) calls the\n   * handler, (5) emits `toolExecutionEnd` (with the same `callId`), (6) wraps any handler error\n   * in {@link @nhtio/adk!E_TOOL_DOWNSTREAM_ERROR} before re-throwing.\n   *\n   * The handler returns serialised bytes (`string | Uint8Array`) — persistence is the consumer's\n   * concern. Use {@link Tool.artifactConstructor} when wrapping the bytes into a\n   * `ToolCall.results` field.\n   *\n   * Pattern mirrors `Middleware.runner()` — call once per turn, reuse the returned function.\n   *\n   * @param ctx - The active turn context. Provides emit functions and turn ID.\n   * @returns An async function `(args) => Promise<string | Uint8Array>`.\n   */\n  executor(\n    ctx: DispatchContext\n  ): (args: unknown) => Promise<string | Uint8Array | Media | Media[]> {\n    return async (args: unknown): Promise<string | Uint8Array | Media | Media[]> => {\n      // Compute callId over raw args (pre-validation) so two invocations with the same\n      // (tool, raw args) produce the same identifier even if validation coerces values.\n      const callId = sha256(canonicalStringify({ tool: this.#name, args }))\n      const validatedArgs = await this.validate(args)\n      const startedAt = DateTime.now()\n      ctx.emitToolExecutionStart({\n        toolName: this.#name,\n        turnId: ctx.id,\n        callId,\n        args: validatedArgs,\n        startedAt,\n      })\n      try {\n        const result = await this.#handler(validatedArgs, ctx, this.#meta)\n        const endedAt = DateTime.now()\n        ctx.emitToolExecutionEnd({\n          toolName: this.#name,\n          turnId: ctx.id,\n          callId,\n          startedAt,\n          endedAt,\n          durationMs: endedAt.diff(startedAt).milliseconds,\n          isError: false,\n        })\n        return result\n      } catch (err) {\n        const endedAt = DateTime.now()\n        ctx.emitToolExecutionEnd({\n          toolName: this.#name,\n          turnId: ctx.id,\n          callId,\n          startedAt,\n          endedAt,\n          durationMs: endedAt.diff(startedAt).milliseconds,\n          isError: true,\n        })\n        throw new E_TOOL_DOWNSTREAM_ERROR({ cause: isError(err) ? err : undefined })\n      }\n    }\n  }\n\n  /**\n   * Returns a fully serialisable snapshot of this tool's definition.\n   *\n   * @remarks\n   * The `inputSchema` property is the result of calling `.describe()` on the raw schema — a plain\n   * object carrying all the annotation metadata (descriptions, notes, examples, types) without any\n   * validator functions. Use this to build provider-specific LLM tool definitions.\n   *\n   * @returns `{ name, description, inputSchema }` where `inputSchema` is the schema description.\n   */\n  describe(): { name: string; description: string; inputSchema: Description } {\n    return {\n      name: this.#name,\n      description: this.#description,\n      inputSchema: this.#inputSchema.describe(),\n    }\n  }\n}\n"],"mappings":"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"}