@nhtio/adk 1.20260607.2 → 1.20260609.0

package/searxng-CyA-nEu5.mjs

@@ -0,0 +1,257 @@
+import { t as createException } from "./exceptions-BDhN0Xzr.mjs";
+import { c as isObject, o as isError } from "./tool_registry-791Vrjtf.mjs";
+import { t as Tool } from "./tool-wMYMVl60.mjs";
+import "./common-DYDUi99O.mjs";
+import { n as SpooledJsonArtifact } from "./spooled_markdown_artifact-wkrBF3oX.mjs";
+import "./factories.mjs";
+import "./guards.mjs";
+import { validator } from "@nhtio/validation";
+import { Middleware } from "@nhtio/middleware";
+//#region src/batteries/tools/searxng/exceptions.ts
+/**
+* Battery-scoped exception constructors for the SearXNG search tool.
+*
+* @remarks
+* Battery-scoped exception classes owned by the SearXNG tool battery (not the ADK core). Minted
+* via `createException` from `@nhtio/adk/factories` and re-exported from the battery's barrel
+* (`@nhtio/adk/batteries/tools/searxng`). This file intentionally carries **no** `@module` tag:
+* it is an internal sibling relative-imported by `index.ts`, so it does not mint its own
+* `…/searxng/exceptions` entrypoint (whose `exceptions` leaf basename would collide with sibling
+* batteries under the `vite-plugin-dts` rolled-up `.d.ts` rule).
+*/
+/**
+* Thrown when {@link createSearxngSearchTool} receives invalid configuration.
+*
+* @remarks
+* Fatal: config bugs (missing or unparseable `instanceUrl`) fail loud at factory-call time
+* rather than at the first search.
+*/
+var E_INVALID_SEARXNG_CONFIG = createException("E_INVALID_SEARXNG_CONFIG", "Invalid SearXNG tool config: %s", "E_INVALID_SEARXNG_CONFIG", 529, true);
+//#endregion
+//#region src/batteries/tools/searxng/index.ts
+/**
+* Factory for a configured SearXNG metasearch tool.
+*
+* @module @nhtio/adk/batteries/tools/searxng
+*
+* @remarks
+* Unlike the other bundled tool categories — every one of which exports a ready-made,
+* stateless `Tool` constant — the SearXNG battery exports a **factory**,
+* {@link createSearxngSearchTool}. A search tool has to talk to a *specific* SearXNG instance,
+* usually behind custom authentication, so it needs per-deployment configuration (a base URL
+* and headers) that cannot be baked in at module load.
+*
+* Because this module exports a factory rather than a `Tool` instance, it MUST NOT be
+* bulk-registered via `Object.values(batteries)`. Call the factory first, then register the
+* returned tool: `new ToolRegistry([createSearxngSearchTool({ instanceUrl })])`.
+*
+* @see https://docs.searxng.org/dev/search_api.html
+*/
+var DEFAULT_NAME = "searxng_search";
+var DEFAULT_TIMEOUT = 1e4;
+var DEFAULT_DESCRIPTION = "Search the web via a SearXNG metasearch instance. Returns aggregated results (title, url, snippet, source engine) plus any answers, infoboxes, and suggestions.";
+/** Internal sentinel a short-circuiting input stage throws to unwind the pipeline immediately. */
+var SHORT_CIRCUIT = Symbol("searxng.shortCircuit");
+var isShortCircuit = (value) => isObject(value) && value[SHORT_CIRCUIT] === true;
+/** Normalise a loose SearXNG result item into a {@link SearxngResult}. */
+var normaliseResult = (raw) => {
+	const r = raw ?? {};
+	const out = {};
+	if (typeof r.title === "string") out.title = r.title;
+	if (typeof r.url === "string") out.url = r.url;
+	if (typeof r.content === "string") out.content = r.content;
+	if (typeof r.engine === "string") out.engine = r.engine;
+	if (typeof r.score === "number") out.score = r.score;
+	if (typeof r.publishedDate === "string") out.publishedDate = r.publishedDate;
+	return out;
+};
+/** Resolve the configured headers (static object or resolver) for a single request. */
+var resolveHeaders = async (headers) => {
+	if (typeof headers === "function") return { ...await headers() };
+	return { ...headers ?? {} };
+};
+/**
+* Create a configured SearXNG search {@link Tool}.
+*
+* @remarks
+* The handler always requests `format=json`. Note that SearXNG ships with JSON output
+* **disabled** by default (it is abused by bots); an instance that has not enabled
+* `search.formats: [json]` in its `settings.yml` answers with HTTP 403, which the tool returns
+* as a graceful `Error:` string naming the setting.
+*
+* @warning
+* Do not trust the `number_of_results` field for a result count — SearXNG frequently reports `0`
+* in JSON output even when `results` is non-empty. This is a long-standing upstream quirk, not a
+* tool defect (see {@link https://github.com/searxng/searxng/issues/2987 | searxng#2987} and
+* {@link https://github.com/searxng/searxng/issues/2457 | searxng#2457}). The tool passes the
+* field through verbatim; use `results.length` as the authoritative count.
+*
+* @param config - The instance URL, optional custom headers, output-format policy, artifact
+*   type, and input/output middleware pipelines. See {@link SearxngToolConfig}.
+* @returns A `Tool` ready to register in a `ToolRegistry`.
+* @throws {@link E_INVALID_SEARXNG_CONFIG} when `instanceUrl` is missing or unparseable.
+*/
+var createSearxngSearchTool = (config) => {
+	if (typeof config?.instanceUrl !== "string" || config.instanceUrl.trim() === "") throw new E_INVALID_SEARXNG_CONFIG(["instanceUrl is required"]);
+	try {
+		new URL(config.instanceUrl);
+	} catch {
+		throw new E_INVALID_SEARXNG_CONFIG([`instanceUrl is not a valid URL: ${config.instanceUrl}`]);
+	}
+	const instanceUrl = config.instanceUrl.replace(/\/+$/, "");
+	const timeout = config.timeout ?? DEFAULT_TIMEOUT;
+	const resultFormat = config.resultFormat ?? "either";
+	const toolName = config.name ?? DEFAULT_NAME;
+	const artifactConstructor = config.artifactConstructor ?? (() => SpooledJsonArtifact);
+	const inputMw = new Middleware();
+	for (const fn of config.inputPipeline ?? []) inputMw.add(fn);
+	const outputMw = new Middleware();
+	for (const fn of config.outputPipeline ?? []) outputMw.add(fn);
+	const hasInput = (config.inputPipeline ?? []).length > 0;
+	const hasOutput = (config.outputPipeline ?? []).length > 0;
+	const schemaShape = {
+		query: validator.string().required().description("The search query."),
+		categories: validator.string().optional().description("Comma-separated SearXNG categories (e.g. \"general,news\")."),
+		engines: validator.string().optional().description("Comma-separated SearXNG engines (e.g. \"google,duckduckgo\")."),
+		language: validator.string().optional().description("Language code (e.g. \"en\", \"de\")."),
+		pageno: validator.number().min(1).default(1).description("Result page number (1-based)."),
+		time_range: validator.string().valid("day", "month", "year").optional().description("Restrict results to a time range."),
+		safesearch: validator.number().valid(0, 1, 2).optional().description("Safe-search level: 0 (off), 1 (moderate), 2 (strict).")
+	};
+	if (resultFormat === "either") schemaShape.format = validator.string().valid("normalized", "raw").default("normalized").description("Output shape: \"normalized\" (trimmed) or \"raw\" (full SearXNG JSON).");
+	const inputSchema = validator.object(schemaShape);
+	return new Tool({
+		name: toolName,
+		description: config.description ?? DEFAULT_DESCRIPTION,
+		inputSchema,
+		artifactConstructor,
+		handler: async (args) => {
+			const a = args;
+			try {
+				const format = resultFormat === "either" ? a.format ?? "normalized" : resultFormat;
+				const headers = {
+					"Accept": "application/json",
+					"User-Agent": "adk-searxng-tool",
+					...await resolveHeaders(config.headers)
+				};
+				const params = {};
+				if (a.categories) params.categories = a.categories;
+				if (a.engines) params.engines = a.engines;
+				if (a.language) params.language = a.language;
+				if (a.pageno && a.pageno !== 1) params.pageno = String(a.pageno);
+				if (a.time_range) params.time_range = a.time_range;
+				if (typeof a.safesearch === "number") params.safesearch = String(a.safesearch);
+				const stash = /* @__PURE__ */ new Map();
+				const requestCtx = {
+					toolName,
+					query: a.query,
+					params,
+					headers,
+					instanceUrl,
+					stash,
+					shortCircuit: (result) => {
+						throw {
+							[SHORT_CIRCUIT]: true,
+							result
+						};
+					}
+				};
+				if (hasInput) {
+					const short = await runInputPipeline(inputMw, requestCtx);
+					if (short !== void 0) return short;
+				}
+				const url = new URL("/search", instanceUrl + "/");
+				url.searchParams.set("q", requestCtx.query);
+				for (const [k, v] of Object.entries(requestCtx.params)) url.searchParams.set(k, v);
+				url.searchParams.set("format", "json");
+				const controller = new AbortController();
+				const timer = setTimeout(() => controller.abort(), timeout);
+				let response;
+				try {
+					response = await fetch(url, {
+						method: "GET",
+						headers: requestCtx.headers,
+						signal: controller.signal
+					});
+				} finally {
+					clearTimeout(timer);
+				}
+				if (!response.ok) {
+					if (response.status === 403) return "Error: SearXNG returned 403 Forbidden. The instance likely has the JSON output format disabled — enable it under \"search.formats: [json]\" in its settings.yml.";
+					return `Error: SearXNG returned HTTP ${response.status} ${response.statusText}.`;
+				}
+				const body = await response.json();
+				const responseCtx = {
+					toolName,
+					request: requestCtx,
+					raw: body,
+					results: Array.isArray(body.results) ? body.results.map(normaliseResult) : [],
+					format,
+					stash
+				};
+				if (hasOutput) await runOutputPipeline(outputMw, responseCtx);
+				if (typeof responseCtx.output === "string") return responseCtx.output;
+				if (responseCtx.format === "raw") return JSON.stringify(responseCtx.raw, null, 2);
+				return JSON.stringify(buildNormalisedPayload(responseCtx), null, 2);
+			} catch (err) {
+				if (isShortCircuit(err)) return err.result;
+				return `Error: ${isError(err) ? err.message : String(err)}`;
+			}
+		}
+	});
+};
+/** Assemble the trimmed normalised payload, dropping empty aggregate arrays. */
+var buildNormalisedPayload = (ctx) => {
+	const raw = ctx.raw ?? {};
+	const payload = {
+		query: typeof raw.query === "string" ? raw.query : ctx.request.query,
+		results: ctx.results
+	};
+	if (typeof raw.number_of_results === "number") payload.number_of_results = raw.number_of_results;
+	for (const key of [
+		"answers",
+		"infoboxes",
+		"suggestions",
+		"corrections"
+	]) {
+		const value = raw[key];
+		if (Array.isArray(value) && value.length > 0) payload[key] = value;
+	}
+	return payload;
+};
+/**
+* Run the input pipeline. Returns the short-circuit string when a stage short-circuited, or
+* `undefined` when the pipeline reached its terminal handler. A non-terminal pipeline (a stage
+* that neither called `next()` nor short-circuited) is surfaced as a thrown Error so the handler
+* converts it to an `Error:` string.
+*/
+var runInputPipeline = async (mw, ctx) => {
+	let reached = false;
+	let shortResult;
+	let caught;
+	await mw.runner().errorHandler(async (error) => {
+		caught = error;
+	}).finalHandler(async () => {
+		reached = true;
+	}).run((fn, next) => Promise.resolve(fn(ctx, next)));
+	if (caught !== void 0) if (isShortCircuit(caught)) shortResult = caught.result;
+	else throw caught;
+	else if (!reached) throw new Error("SearXNG input pipeline did not call next() and did not short-circuit.");
+	return shortResult;
+};
+/** Run the output pipeline; rethrow any stage error to the handler's try/catch. */
+var runOutputPipeline = async (mw, ctx) => {
+	let reached = false;
+	let caught;
+	await mw.runner().errorHandler(async (error) => {
+		caught = error;
+	}).finalHandler(async () => {
+		reached = true;
+	}).run((fn, next) => Promise.resolve(fn(ctx, next)));
+	if (caught !== void 0) throw caught;
+	if (!reached) throw new Error("SearXNG output pipeline did not call next().");
+};
+//#endregion
+export { E_INVALID_SEARXNG_CONFIG as n, createSearxngSearchTool as t };
+
+//# sourceMappingURL=searxng-CyA-nEu5.mjs.map

package/searxng-CyA-nEu5.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"searxng-CyA-nEu5.mjs","names":[],"sources":["../src/batteries/tools/searxng/exceptions.ts","../src/batteries/tools/searxng/index.ts"],"sourcesContent":["/**\n * Battery-scoped exception constructors for the SearXNG search tool.\n *\n * @remarks\n * Battery-scoped exception classes owned by the SearXNG tool battery (not the ADK core). Minted\n * via `createException` from `@nhtio/adk/factories` and re-exported from the battery's barrel\n * (`@nhtio/adk/batteries/tools/searxng`). This file intentionally carries **no** `@module` tag:\n * it is an internal sibling relative-imported by `index.ts`, so it does not mint its own\n * `…/searxng/exceptions` entrypoint (whose `exceptions` leaf basename would collide with sibling\n * batteries under the `vite-plugin-dts` rolled-up `.d.ts` rule).\n */\n\nimport { createException } from '@nhtio/adk/factories'\n\n/**\n * Thrown when {@link createSearxngSearchTool} receives invalid configuration.\n *\n * @remarks\n * Fatal: config bugs (missing or unparseable `instanceUrl`) fail loud at factory-call time\n * rather than at the first search.\n */\nexport const E_INVALID_SEARXNG_CONFIG = createException<[string]>(\n  'E_INVALID_SEARXNG_CONFIG',\n  'Invalid SearXNG tool config: %s',\n  'E_INVALID_SEARXNG_CONFIG',\n  529,\n  true\n)\n","/**\n * Factory for a configured SearXNG metasearch tool.\n *\n * @module @nhtio/adk/batteries/tools/searxng\n *\n * @remarks\n * Unlike the other bundled tool categories — every one of which exports a ready-made,\n * stateless `Tool` constant — the SearXNG battery exports a **factory**,\n * {@link createSearxngSearchTool}. A search tool has to talk to a *specific* SearXNG instance,\n * usually behind custom authentication, so it needs per-deployment configuration (a base URL\n * and headers) that cannot be baked in at module load.\n *\n * Because this module exports a factory rather than a `Tool` instance, it MUST NOT be\n * bulk-registered via `Object.values(batteries)`. Call the factory first, then register the\n * returned tool: `new ToolRegistry([createSearxngSearchTool({ instanceUrl })])`.\n *\n * @see https://docs.searxng.org/dev/search_api.html\n */\n\nimport { validator } from '@nhtio/validation'\nimport { Middleware } from '@nhtio/middleware'\nimport { isError, isObject } from '@nhtio/adk/guards'\nimport { E_INVALID_SEARXNG_CONFIG } from './exceptions'\nimport { Tool, SpooledJsonArtifact, type ArtifactConstructorResolver } from '@nhtio/adk/common'\nimport type { Schema } from '@nhtio/validation'\nimport type { NextFn } from '@nhtio/middleware'\n\nexport { E_INVALID_SEARXNG_CONFIG } from './exceptions'\n\n/** A static set of request headers (used for custom authentication). */\nexport type SearxngHeaders = Record<string, string>\n\n/**\n * A resolver returning request headers, sync or async. Use this form when the auth token is\n * refreshable — the resolver runs on every search, so a fresh token can be minted per call.\n */\nexport type SearxngHeadersResolver = () => SearxngHeaders | Promise<SearxngHeaders>\n\n/** The output shape the tool serialises. `either` lets the model pick per call. */\nexport type SearxngResultFormat = 'normalized' | 'raw' | 'either'\n\n/**\n * A single normalised SearXNG result. SearXNG result items are deliberately untyped upstream,\n * so every field except a best-effort `title`/`url` is optional.\n */\nexport interface SearxngResult {\n  /** Result title, when the source engine provided one. */\n  title?: string\n  /** Result URL, when the source engine provided one. */\n  url?: string\n  /** Snippet / summary text for the result. */\n  content?: string\n  /** The SearXNG engine that produced this result (e.g. `google`, `duckduckgo`). */\n  engine?: string\n  /** Relevance score as reported by SearXNG (higher is more relevant). */\n  score?: number\n  /** Publication date, when the source engine exposed one (ISO-ish string, engine-dependent). */\n  publishedDate?: string\n}\n\n/**\n * Mutable context handed to each input-pipeline stage **before** the HTTP request is sent.\n *\n * @remarks\n * Stages mutate this in place (onion `(ctx, next)` style) to adjust the outgoing request —\n * inject or rotate auth headers, force a language, rewrite the query — or call\n * {@link SearxngRequestContext.shortCircuit} to skip the fetch entirely (e.g. a cache hit).\n */\nexport interface SearxngRequestContext {\n  /** The tool's name (read-only). */\n  readonly toolName: string\n  /** The search query. Mutable. */\n  query: string\n  /** Extra SearXNG query parameters (`categories`, `engines`, `language`, …). Mutable. */\n  params: Record<string, string>\n  /** Resolved request headers. Mutable — inject, redact, or rotate auth here. */\n  headers: SearxngHeaders\n  /** The target instance base URL (read-only). */\n  readonly instanceUrl: string\n  /** Cross-stage scratch space; also carried onto the response context. */\n  readonly stash: Map<string, unknown>\n  /** Skip the fetch and return `result` verbatim as the tool's output. */\n  shortCircuit(result: string): void\n}\n\n/**\n * Mutable context handed to each output-pipeline stage **after** the response JSON is parsed.\n *\n * @remarks\n * Stages reshape, redact, enrich, or re-rank {@link SearxngResponseContext.results}, mutate the\n * raw body, or set {@link SearxngResponseContext.output} to override the serialised string\n * verbatim (e.g. to render markdown that matches a markdown `artifactConstructor`).\n */\nexport interface SearxngResponseContext {\n  /** The tool's name (read-only). */\n  readonly toolName: string\n  /** The request context as it was sent (post-input-pipeline). */\n  readonly request: SearxngRequestContext\n  /** The parsed SearXNG JSON body. Mutable (used when `format` is `raw`). */\n  raw: unknown\n  /** The normalised result list. Mutable — filter, redact, or re-rank. */\n  results: SearxngResult[]\n  /** The effective payload shape for this call. */\n  format: 'normalized' | 'raw'\n  /** When set, used verbatim as the tool's output (overrides serialisation). */\n  output?: string\n  /** Cross-stage scratch space; carried over from the request context. */\n  readonly stash: Map<string, unknown>\n}\n\n/** An input-pipeline stage. Onion middleware over {@link SearxngRequestContext}. */\nexport type SearxngInputMiddlewareFn = (\n  ctx: SearxngRequestContext,\n  next: NextFn\n) => void | Promise<void>\n\n/** An output-pipeline stage. Onion middleware over {@link SearxngResponseContext}. */\nexport type SearxngOutputMiddlewareFn = (\n  ctx: SearxngResponseContext,\n  next: NextFn\n) => void | Promise<void>\n\n/** Configuration for {@link createSearxngSearchTool}. */\nexport interface SearxngToolConfig {\n  /** Base URL of the SearXNG instance, e.g. `https://searx.example.org`. Required. */\n  instanceUrl: string\n  /** Custom request headers — a static object or a (sync/async) resolver for refreshable auth. */\n  headers?: SearxngHeaders | SearxngHeadersResolver\n  /** Request timeout in milliseconds. Default `10_000`. */\n  timeout?: number\n  /**\n   * Output shape. `normalized`/`raw` pin the shape (the model cannot change it); `either`\n   * (default) exposes a `format` argument so the model chooses per call.\n   */\n  resultFormat?: SearxngResultFormat\n  /** Tool name. Default `searxng_search`. */\n  name?: string\n  /** Tool description override. */\n  description?: string\n  /**\n   * Spool artifact constructor for the tool's output. Default `() => SpooledJsonArtifact`.\n   * Pass `() => SpooledMarkdownArtifact` (paired with an output stage that renders markdown into\n   * `ctx.output`) or `() => SpooledArtifact` for plain text.\n   */\n  artifactConstructor?: ArtifactConstructorResolver\n  /** Stages run before the HTTP request. See {@link SearxngRequestContext}. */\n  inputPipeline?: SearxngInputMiddlewareFn[]\n  /** Stages run after the response is parsed. See {@link SearxngResponseContext}. */\n  outputPipeline?: SearxngOutputMiddlewareFn[]\n}\n\nconst DEFAULT_NAME = 'searxng_search'\nconst DEFAULT_TIMEOUT = 10_000\nconst DEFAULT_DESCRIPTION =\n  'Search the web via a SearXNG metasearch instance. Returns aggregated results (title, url, ' +\n  'snippet, source engine) plus any answers, infoboxes, and suggestions.'\n\n/** Internal sentinel a short-circuiting input stage throws to unwind the pipeline immediately. */\nconst SHORT_CIRCUIT = Symbol('searxng.shortCircuit')\n\ninterface ShortCircuitSignal {\n  [SHORT_CIRCUIT]: true\n  result: string\n}\n\nconst isShortCircuit = (value: unknown): value is ShortCircuitSignal =>\n  isObject(value) && (value as Record<symbol, unknown>)[SHORT_CIRCUIT] === true\n\n/** Normalise a loose SearXNG result item into a {@link SearxngResult}. */\nconst normaliseResult = (raw: unknown): SearxngResult => {\n  const r = (raw ?? {}) as Record<string, unknown>\n  const out: SearxngResult = {}\n  if (typeof r.title === 'string') out.title = r.title\n  if (typeof r.url === 'string') out.url = r.url\n  if (typeof r.content === 'string') out.content = r.content\n  if (typeof r.engine === 'string') out.engine = r.engine\n  if (typeof r.score === 'number') out.score = r.score\n  if (typeof r.publishedDate === 'string') out.publishedDate = r.publishedDate\n  return out\n}\n\n/** Resolve the configured headers (static object or resolver) for a single request. */\nconst resolveHeaders = async (headers: SearxngToolConfig['headers']): Promise<SearxngHeaders> => {\n  if (typeof headers === 'function') return { ...(await headers()) }\n  return { ...(headers ?? {}) }\n}\n\n/**\n * Create a configured SearXNG search {@link Tool}.\n *\n * @remarks\n * The handler always requests `format=json`. Note that SearXNG ships with JSON output\n * **disabled** by default (it is abused by bots); an instance that has not enabled\n * `search.formats: [json]` in its `settings.yml` answers with HTTP 403, which the tool returns\n * as a graceful `Error:` string naming the setting.\n *\n * @warning\n * Do not trust the `number_of_results` field for a result count — SearXNG frequently reports `0`\n * in JSON output even when `results` is non-empty. This is a long-standing upstream quirk, not a\n * tool defect (see {@link https://github.com/searxng/searxng/issues/2987 | searxng#2987} and\n * {@link https://github.com/searxng/searxng/issues/2457 | searxng#2457}). The tool passes the\n * field through verbatim; use `results.length` as the authoritative count.\n *\n * @param config - The instance URL, optional custom headers, output-format policy, artifact\n *   type, and input/output middleware pipelines. See {@link SearxngToolConfig}.\n * @returns A `Tool` ready to register in a `ToolRegistry`.\n * @throws {@link E_INVALID_SEARXNG_CONFIG} when `instanceUrl` is missing or unparseable.\n */\nexport const createSearxngSearchTool = (config: SearxngToolConfig): Tool => {\n  if (typeof config?.instanceUrl !== 'string' || config.instanceUrl.trim() === '') {\n    throw new E_INVALID_SEARXNG_CONFIG(['instanceUrl is required'])\n  }\n  try {\n    // Parse-validate only; the normalised string below is what we actually use.\n    new URL(config.instanceUrl)\n  } catch {\n    throw new E_INVALID_SEARXNG_CONFIG([`instanceUrl is not a valid URL: ${config.instanceUrl}`])\n  }\n  // Normalise away a trailing slash so `new URL('/search', base)` resolves cleanly.\n  const instanceUrl = config.instanceUrl.replace(/\\/+$/, '')\n\n  const timeout = config.timeout ?? DEFAULT_TIMEOUT\n  const resultFormat: SearxngResultFormat = config.resultFormat ?? 'either'\n  const toolName = config.name ?? DEFAULT_NAME\n  const artifactConstructor: ArtifactConstructorResolver =\n    config.artifactConstructor ?? (() => SpooledJsonArtifact)\n\n  // Stages are fixed at factory time; build the Middleware shells once. A fresh `.runner()` is\n  // minted per invocation inside the handler (runners are single-use).\n  const inputMw = new Middleware<SearxngInputMiddlewareFn>()\n  for (const fn of config.inputPipeline ?? []) inputMw.add(fn)\n  const outputMw = new Middleware<SearxngOutputMiddlewareFn>()\n  for (const fn of config.outputPipeline ?? []) outputMw.add(fn)\n  const hasInput = (config.inputPipeline ?? []).length > 0\n  const hasOutput = (config.outputPipeline ?? []).length > 0\n\n  // Build the input schema, conditionally exposing `format` only when the factory is neutral.\n  const schemaShape: Record<string, Schema> = {\n    query: validator.string().required().description('The search query.'),\n    categories: validator\n      .string()\n      .optional()\n      .description('Comma-separated SearXNG categories (e.g. \"general,news\").'),\n    engines: validator\n      .string()\n      .optional()\n      .description('Comma-separated SearXNG engines (e.g. \"google,duckduckgo\").'),\n    language: validator.string().optional().description('Language code (e.g. \"en\", \"de\").'),\n    pageno: validator.number().min(1).default(1).description('Result page number (1-based).'),\n    time_range: validator\n      .string()\n      .valid('day', 'month', 'year')\n      .optional()\n      .description('Restrict results to a time range.'),\n    safesearch: validator\n      .number()\n      .valid(0, 1, 2)\n      .optional()\n      .description('Safe-search level: 0 (off), 1 (moderate), 2 (strict).'),\n  }\n  if (resultFormat === 'either') {\n    schemaShape.format = validator\n      .string()\n      .valid('normalized', 'raw')\n      .default('normalized')\n      .description('Output shape: \"normalized\" (trimmed) or \"raw\" (full SearXNG JSON).')\n  }\n  const inputSchema = validator.object(schemaShape)\n\n  return new Tool({\n    name: toolName,\n    description: config.description ?? DEFAULT_DESCRIPTION,\n    inputSchema,\n    artifactConstructor,\n    handler: async (args) => {\n      const a = args as {\n        query: string\n        categories?: string\n        engines?: string\n        language?: string\n        pageno?: number\n        time_range?: string\n        safesearch?: number\n        format?: 'normalized' | 'raw'\n      }\n\n      try {\n        // 1. Effective output format: a pinned factory format wins; else the model's choice.\n        const format: 'normalized' | 'raw' =\n          resultFormat === 'either' ? (a.format ?? 'normalized') : resultFormat\n\n        // 2. Resolve headers, merged over portable defaults (caller headers win).\n        const headers: SearxngHeaders = {\n          'Accept': 'application/json',\n          'User-Agent': 'adk-searxng-tool',\n          ...(await resolveHeaders(config.headers)),\n        }\n\n        // 3. Assemble the SearXNG query params from validated args.\n        const params: Record<string, string> = {}\n        if (a.categories) params.categories = a.categories\n        if (a.engines) params.engines = a.engines\n        if (a.language) params.language = a.language\n        if (a.pageno && a.pageno !== 1) params.pageno = String(a.pageno)\n        if (a.time_range) params.time_range = a.time_range\n        if (typeof a.safesearch === 'number') params.safesearch = String(a.safesearch)\n\n        const stash = new Map<string, unknown>()\n\n        // 4. Run the input pipeline (fresh runner) over a mutable request context.\n        const requestCtx: SearxngRequestContext = {\n          toolName,\n          query: a.query,\n          params,\n          headers,\n          instanceUrl,\n          stash,\n          shortCircuit: (result: string) => {\n            const signal: ShortCircuitSignal = { [SHORT_CIRCUIT]: true, result }\n            throw signal\n          },\n        }\n\n        if (hasInput) {\n          const short = await runInputPipeline(inputMw, requestCtx)\n          if (short !== undefined) return short\n        }\n\n        // 5. Build the request URL from the (possibly mutated) query + params.\n        const url = new URL('/search', instanceUrl + '/')\n        url.searchParams.set('q', requestCtx.query)\n        for (const [k, v] of Object.entries(requestCtx.params)) url.searchParams.set(k, v)\n        url.searchParams.set('format', 'json')\n\n        // 6. Fetch with an AbortController timeout.\n        const controller = new AbortController()\n        const timer = setTimeout(() => controller.abort(), timeout)\n        let response: Response\n        try {\n          response = await fetch(url, {\n            method: 'GET',\n            headers: requestCtx.headers,\n            signal: controller.signal,\n          })\n        } finally {\n          clearTimeout(timer)\n        }\n\n        if (!response.ok) {\n          if (response.status === 403) {\n            return (\n              `Error: SearXNG returned 403 Forbidden. The instance likely has the JSON output ` +\n              `format disabled — enable it under \"search.formats: [json]\" in its settings.yml.`\n            )\n          }\n          return `Error: SearXNG returned HTTP ${response.status} ${response.statusText}.`\n        }\n\n        const body = (await response.json()) as Record<string, unknown>\n\n        // 7. Run the output pipeline (fresh runner) over a mutable response context.\n        const responseCtx: SearxngResponseContext = {\n          toolName,\n          request: requestCtx,\n          raw: body,\n          results: Array.isArray(body.results) ? body.results.map(normaliseResult) : [],\n          format,\n          stash,\n        }\n\n        if (hasOutput) await runOutputPipeline(outputMw, responseCtx)\n\n        // 8. Serialise and return.\n        if (typeof responseCtx.output === 'string') return responseCtx.output\n        if (responseCtx.format === 'raw') return JSON.stringify(responseCtx.raw, null, 2)\n        return JSON.stringify(buildNormalisedPayload(responseCtx), null, 2)\n      } catch (err) {\n        if (isShortCircuit(err)) return err.result\n        return `Error: ${isError(err) ? err.message : String(err)}`\n      }\n    },\n  })\n}\n\n/** Assemble the trimmed normalised payload, dropping empty aggregate arrays. */\nconst buildNormalisedPayload = (ctx: SearxngResponseContext): Record<string, unknown> => {\n  const raw = (ctx.raw ?? {}) as Record<string, unknown>\n  const payload: Record<string, unknown> = {\n    query: typeof raw.query === 'string' ? raw.query : ctx.request.query,\n    results: ctx.results,\n  }\n  // NOTE: SearXNG's `number_of_results` is frequently `0` in JSON output even when `results`\n  // is non-empty — a long-standing upstream quirk, not a tool bug (see\n  // https://github.com/searxng/searxng/issues/2987 and\n  // https://github.com/searxng/searxng/issues/2457). We pass through whatever the instance\n  // reports; treat `results.length` as the authoritative count, not this field.\n  if (typeof raw.number_of_results === 'number') payload.number_of_results = raw.number_of_results\n  for (const key of ['answers', 'infoboxes', 'suggestions', 'corrections'] as const) {\n    const value = raw[key]\n    if (Array.isArray(value) && value.length > 0) payload[key] = value\n  }\n  return payload\n}\n\n/**\n * Run the input pipeline. Returns the short-circuit string when a stage short-circuited, or\n * `undefined` when the pipeline reached its terminal handler. A non-terminal pipeline (a stage\n * that neither called `next()` nor short-circuited) is surfaced as a thrown Error so the handler\n * converts it to an `Error:` string.\n */\nconst runInputPipeline = async (\n  mw: Middleware<SearxngInputMiddlewareFn>,\n  ctx: SearxngRequestContext\n): Promise<string | undefined> => {\n  let reached = false\n  let shortResult: string | undefined\n  let caught: unknown\n  await mw\n    .runner()\n    .errorHandler(async (error: unknown) => {\n      caught = error\n    })\n    .finalHandler(async () => {\n      reached = true\n    })\n    .run((fn, next) => Promise.resolve(fn(ctx, next)))\n\n  if (caught !== undefined) {\n    if (isShortCircuit(caught)) {\n      shortResult = caught.result\n    } else {\n      throw caught\n    }\n  } else if (!reached) {\n    throw new Error('SearXNG input pipeline did not call next() and did not short-circuit.')\n  }\n  return shortResult\n}\n\n/** Run the output pipeline; rethrow any stage error to the handler's try/catch. */\nconst runOutputPipeline = async (\n  mw: Middleware<SearxngOutputMiddlewareFn>,\n  ctx: SearxngResponseContext\n): Promise<void> => {\n  let reached = false\n  let caught: unknown\n  await mw\n    .runner()\n    .errorHandler(async (error: unknown) => {\n      caught = error\n    })\n    .finalHandler(async () => {\n      reached = true\n    })\n    .run((fn, next) => Promise.resolve(fn(ctx, next)))\n\n  if (caught !== undefined) throw caught\n  if (!reached) {\n    throw new Error('SearXNG output pipeline did not call next().')\n  }\n}\n"],"mappings":"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"}

package/skills/adk-assembly/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: "Requires TypeScript/JavaScript project using @nhtio/adk; examples assume Node 20+ or compatible browser/runtime."
 metadata:
   package: "@nhtio/adk"
-  version: "1.20260607.2"
+  version: "1.20260609.0"
   author: "Jak Giveon <jak@nht.io>"
   copyright: "© 2025-present New Horizon Technology LTD"
 ---
@@ -17,7 +17,7 @@ Use this skill to help users build or review an `@nhtio/adk` assembly: the appli
 ## Package Metadata
 
 - Package: `@nhtio/adk`
-- Version: `1.20260607.2`
+- Version: `1.20260609.0`
 - License: MIT
 - Author: Jak Giveon <jak@nht.io>
 - Copyright: © 2025-present New Horizon Technology LTD

package/{spooled_artifact-CHoZgWwI.mjs → spooled_artifact-7eePq7JA.mjs}

@@ -1,7 +1,7 @@
-import { a as validateOrThrow, i as passesSchema, n as ValidationException } from "./exceptions-BeWH2FwP.mjs";
-import { a as Tokenizable, i as TokenEncoding, s as isInstanceOf, t as ToolRegistry } from "./tool_registry-D1pSSlsd.mjs";
-import { C as E_NOT_A_SPOOL_READER, d as E_INVALID_INITIAL_TOOL_VALUE } from "./runtime-j92CNi5z.mjs";
-import { t as Tool } from "./tool-CMhaDRNd.mjs";
+import { a as validateOrThrow, i as passesSchema, n as ValidationException } from "./exceptions-BDhN0Xzr.mjs";
+import { a as Tokenizable, i as TokenEncoding, s as isInstanceOf, t as ToolRegistry } from "./tool_registry-791Vrjtf.mjs";
+import { C as E_NOT_A_SPOOL_READER, d as E_INVALID_INITIAL_TOOL_VALUE } from "./runtime-Bz5zA8wc.mjs";
+import { t as Tool } from "./tool-wMYMVl60.mjs";
 import { validator } from "@nhtio/validation";
 //#region src/lib/classes/artifact_tool.ts
 /**
@@ -541,4 +541,4 @@ var SpooledArtifact = class SpooledArtifact {
 //#endregion
 export { ArtifactTool as i, defaultSerialise as n, implementsSpoolReader as r, SpooledArtifact as t };
 
-//# sourceMappingURL=spooled_artifact-CHoZgWwI.mjs.map
+//# sourceMappingURL=spooled_artifact-7eePq7JA.mjs.map

package/{spooled_artifact-CHoZgWwI.mjs.map → spooled_artifact-7eePq7JA.mjs.map}

@@ -1 +1 @@
-{"version":3,"file":"spooled_artifact-CHoZgWwI.mjs","names":["#reader"],"sources":["../src/lib/classes/artifact_tool.ts","../src/lib/contracts/spool_reader.ts","../src/lib/classes/spooled_artifact.ts"],"sourcesContent":["import { Tool } from './tool'\nimport { validator } from '@nhtio/validation'\nimport { isInstanceOf } from '../utils/guards'\nimport { E_INVALID_INITIAL_TOOL_VALUE } from '../exceptions/runtime'\nimport { validateOrThrow, ValidationException } from '../utils/validation'\nimport type { Registry } from './registry'\nimport type { Schema } from '@nhtio/validation'\nimport type { Tokenizable } from './tokenizable'\nimport type { DispatchContext } from '../contracts/dispatch_context'\n\n/**\n * The execution function for an {@link ArtifactTool}.\n *\n * @remarks\n * Identical to the base tool handler except the return type is narrowed to\n * `string | Tokenizable | Promise<string | Tokenizable>`. Forged artifact-query tools emit\n * model-visible strings — the ADK wraps a bare-string return into a {@link @nhtio/adk!Tokenizable}\n * at the result-wrapping site so downstream code can rely on\n * `ToolCall.results instanceof Tokenizable` for every `ArtifactTool` invocation.\n */\nexport type ArtifactToolHandler = (\n  args: unknown,\n  ctx: DispatchContext,\n  meta: Registry\n) => string | Tokenizable | Promise<string | Tokenizable>\n\n/**\n * Plain input object supplied to {@link ArtifactTool} at construction time.\n *\n * @remarks\n * Mirrors the base `RawTool` except `artifactConstructor` is forbidden — an `ArtifactTool`\n * emits a {@link @nhtio/adk!Tokenizable} directly into `ToolCall.results` and explicitly opts out of\n * `SpooledArtifact` wrapping. The forbidden field is enforced by {@link ArtifactTool.schema}\n * at construction time.\n */\nexport interface RawArtifactTool {\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. */\n  inputSchema: Schema\n  /** Execution function. Returns a string or {@link @nhtio/adk!Tokenizable}; the ADK wraps a bare string into a `Tokenizable` at the result-wrapping site. */\n  handler: ArtifactToolHandler\n  /** Optional arbitrary metadata for this tool. Defaults to `{}`. */\n  meta?: Record<string, unknown>\n  /**\n   * When `true`, marks this tool as owned by a specific {@link @nhtio/adk!DispatchContext}.\n   *\n   * @remarks\n   * `ArtifactTool` instances produced by `SpooledArtifact.forgeTools(ctx)` set this to `true`\n   * so that `ToolRegistry.pruneEphemeral()` drops them at ctx-completion.\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   * Forged artifact-query tools default to `false` because their results are derived from\n   * spooled artifact bodies — which may themselves be untrusted upstream tool output. The\n   * trust signal does not promote handle-query results above the trust tier of the underlying\n   * artifact.\n   *\n   * @defaultValue `false`\n   */\n  trusted?: boolean\n  /**\n   * Self-declared merge collision policy honoured by `ToolRegistry.merge`.\n   *\n   * @remarks\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 RawArtifactTool}.\n *\n * @remarks\n * Mirrors the base tool schema but explicitly forbids `artifactConstructor` — the entire\n * point of `ArtifactTool` is to opt out of `SpooledArtifact` wrapping.\n */\nconst rawArtifactToolSchema = validator.object<RawArtifactTool & { artifactConstructor?: never }>({\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  // eslint-disable-next-line adk/require-validator-any-required -- map value type-arg: meta holds arbitrary values; disposition is set by .default({}) on the object\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  artifactConstructor: validator.any().forbidden(),\n})\n\n/**\n * A {@link @nhtio/adk!Tool} subclass whose handler return value is wrapped directly in a\n * {@link @nhtio/adk!Tokenizable} (not a {@link @nhtio/adk!SpooledArtifact}) when it\n * lands on `ToolCall.results`.\n *\n * @remarks\n * `ArtifactTool` is the canonical producer for **forged artifact-query tools** — the tools\n * `SpooledArtifact.forgeTools(ctx)` emits so the model can `head`, `tail`, `grep`, `json_get`,\n * `md_headings` (etc.) an artifact that is already in `ctx.turnToolCalls`.\n *\n * The difference from {@link @nhtio/adk!Tool} is structural, not stylistic:\n *\n * - A normal `Tool`'s handler returns bytes the ADK wraps in a fresh `SpooledArtifact`.\n *   The artifact lands in `ToolCall.results`, joins `ctx.turnToolCalls`, and is itself a\n *   first-class queryable artifact in the turn.\n * - An `ArtifactTool`'s handler returns a string that is **already the model-visible answer**\n *   to a query against an existing artifact. The ADK wraps it in a `Tokenizable` rather\n *   than a `SpooledArtifact`; nothing new is queryable on its own. Subsequent\n *   `forgeTools(ctx)` calls exclude `ToolCall`s produced by an `ArtifactTool` from the\n *   `callId` enum (via the `ToolCall.fromArtifactTool` marker) — this is the structural fix\n *   that breaks the otherwise-recursive grep-on-the-grep-result loop.\n *\n * Consumers who want to build their own artifact-query tools (e.g. for a domain-specific\n * spooled subclass not shipped by the ADK) should extend or instantiate this class.\n */\nexport class ArtifactTool extends Tool {\n  /**\n   * Validator schema that accepts a {@link RawArtifactTool} object.\n   *\n   * @remarks\n   * Differs from {@link @nhtio/adk!Tool.schema} by forbidding `artifactConstructor` — wrapping is\n   * exactly the thing this class opts out of. Typed identically to {@link @nhtio/adk!Tool.schema} so the\n   * subclass relationship `class ArtifactTool extends Tool` remains structurally sound; the\n   * runtime validation rules still differ as declared by `rawArtifactToolSchema`.\n   */\n  public static schema = rawArtifactToolSchema as unknown as typeof Tool.schema\n\n  /**\n   * Returns `true` if `value` is an {@link ArtifactTool} instance.\n   *\n   * @remarks\n   * Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety — `instanceof` would fail for instances\n   * created in a different module copy or VM context.\n   *\n   * @param value - The value to test.\n   * @returns `true` when `value` is an {@link ArtifactTool} instance.\n   */\n  public static isArtifactTool(value: unknown): value is ArtifactTool {\n    return isInstanceOf(value, 'ArtifactTool', ArtifactTool)\n  }\n\n  /**\n   * @param raw - Raw tool input validated against {@link ArtifactTool.schema}.\n   *\n   * @throws {@link @nhtio/adk!E_INVALID_INITIAL_TOOL_VALUE} when `raw` does not satisfy\n   *   {@link ArtifactTool.schema} (most commonly, when `artifactConstructor` is supplied — it is\n   *   explicitly forbidden on this class) or when the base {@link @nhtio/adk!Tool} constructor rejects the\n   *   input for any reason.\n   */\n  constructor(raw: RawArtifactTool) {\n    // Enforce the forbidden `artifactConstructor` field up-front so the error reports against\n    // ArtifactTool's contract, not the base Tool's. The base Tool constructor re-validates\n    // against its own schema and stores the resolved fields.\n    try {\n      validateOrThrow(rawArtifactToolSchema, raw, true)\n    } catch (err) {\n      if (isInstanceOf(err, 'ValidationException', ValidationException)) {\n        throw new E_INVALID_INITIAL_TOOL_VALUE({ cause: err })\n      }\n      throw err\n    }\n    super(raw as never)\n  }\n}\n","import { validator } from '@nhtio/validation'\nimport { passesSchema } from '../utils/validation'\n\n/**\n * Backing store contract for a {@link @nhtio/adk!SpooledArtifact}.\n *\n * @remarks\n * Implementations may read from memory, a file handle, a network stream, or any other byte\n * source. The interface is intentionally minimal — the artifact layer handles all higher-level\n * operations (`head`, `tail`, `grep`, etc.) by composing calls to these three primitives.\n *\n * Line indexing is 0-based. Implementations must return `undefined` from {@link SpoolReader.line}\n * when the index is out of range rather than throwing.\n *\n * All three methods may be synchronous or asynchronous to accommodate both in-memory and I/O-\n * backed implementations without forcing unnecessary promise overhead on simple cases.\n */\nexport interface SpoolReader {\n  /**\n   * Returns the line at the given 0-based index, or `undefined` when out of range.\n   *\n   * @param index - 0-based line index.\n   * @returns The raw line string (without trailing newline), or `undefined`.\n   */\n  line(index: number): string | undefined | Promise<string | undefined>\n\n  /**\n   * Returns the total number of bytes in the underlying data.\n   *\n   * @remarks\n   * Used for reporting and token-estimation purposes. Byte length is distinct from character\n   * length for multi-byte encodings.\n   *\n   * @returns The byte length of the underlying data.\n   */\n  byteLength(): number | Promise<number>\n\n  /**\n   * Returns the total number of lines in the underlying data.\n   *\n   * @remarks\n   * Required so consumers know when to stop iterating; the line count must remain stable for the\n   * lifetime of the reader.\n   *\n   * @returns The total line count.\n   */\n  lineCount(): number | Promise<number>\n\n  /**\n   * Returns the full underlying content as a single decoded string, byte-faithful to the source.\n   *\n   * @remarks\n   * Unlike {@link SpoolReader.line}, this method preserves trailing newlines and any non-`\\n`\n   * line terminators (e.g. `\\r\\n`) present in the original bytes. It is the primitive that\n   * powers `SpooledArtifact.asString()` — the round-trip-faithful alternative to assembling\n   * the artifact body from per-line reads.\n   *\n   * Implementations should make this O(n) in the size of the underlying data and may cache the\n   * result if the read source is durable. Streaming implementations may choose not to cache.\n   *\n   * @returns The full underlying content as a single string.\n   */\n  readAll(): string | Promise<string>\n}\n\n/**\n * Validator schema used to validate a {@link SpoolReader} value.\n *\n * @remarks\n * Because `SpoolReader` is a structural interface with no associated constructor, validation is\n * duck-typed: the value must be an object, class instance, or function with `line`, `byteLength`,\n * and `lineCount` present as callable properties. Arity is not enforced — implementations may add\n * optional parameters beyond the contract.\n */\nexport const spoolReaderSchema = validator\n  .any()\n  .required()\n  .custom((value, helpers) => {\n    if (\n      value !== null &&\n      value !== undefined &&\n      typeof (value as any).line === 'function' &&\n      typeof (value as any).byteLength === 'function' &&\n      typeof (value as any).lineCount === 'function' &&\n      typeof (value as any).readAll === 'function'\n    ) {\n      return value as SpoolReader\n    }\n    return helpers.error('any.invalid')\n  })\n\n/**\n * Returns `true` if `value` implements the {@link SpoolReader} interface.\n *\n * @remarks\n * Duck-typed: checks that `value` is non-null with `line`, `byteLength`, `lineCount`, and\n * `readAll` as callable functions. Does not use `instanceof` — there is no `SpoolReader`\n * constructor.\n *\n * @param value - The value to test.\n * @returns `true` when `value` conforms to the {@link SpoolReader} interface.\n */\nexport const implementsSpoolReader = (value: unknown): value is SpoolReader => {\n  return passesSchema(spoolReaderSchema, value)\n}\n","import { validator } from '@nhtio/validation'\nimport { isInstanceOf } from '../utils/guards'\nimport { ArtifactTool } from './artifact_tool'\nimport { ToolRegistry } from './tool_registry'\nimport { Tokenizable, TokenEncoding } from './tokenizable'\nimport { E_NOT_A_SPOOL_READER } from '../exceptions/runtime'\nimport { implementsSpoolReader } from '../contracts/spool_reader'\nimport type { ObjectSchema } from '@nhtio/validation'\nimport type { SpoolReader } from '../contracts/spool_reader'\nimport type { DispatchContext } from '../contracts/dispatch_context'\n\n/**\n * Constructor signature for {@link SpooledArtifact} and any subclass.\n *\n * @remarks\n * Used by {@link @nhtio/adk!Tool} to declare the artifact subclass the consumer should use when wrapping\n * the handler's serialised output. The variadic rest parameter accommodates subclass-specific\n * constructor arguments (e.g. `SpooledJsonArtifact(reader, format?)`).\n *\n * @typeParam A - The {@link SpooledArtifact} subtype the constructor produces.\n */\nexport type SpooledArtifactConstructor<A extends SpooledArtifact = SpooledArtifact> = new (\n  reader: SpoolReader,\n  ...rest: any[]\n) => A\n\n/**\n * Metadata table entry for one of the artifact's existing query methods, used by\n * {@link SpooledArtifact.forgeTools} to surface that method as an {@link @nhtio/adk!ArtifactTool}.\n *\n * @remarks\n * This is a metadata shape, not a general method → tool pipeline. `forgeTools` knows how to\n * marshal arguments for a fixed, closed set of method names (the base seven on\n * {@link SpooledArtifact} and the JSON/Markdown methods on the bundled subclasses); a\n * descriptor is the place to attach a tool name, description, args schema, and optional\n * serializer to one of those methods. Adding a descriptor for a method whose name is not\n * in that closed set will produce a tool whose handler invokes the method with no arguments.\n *\n * For new methods that require custom argument marshalling, branching, multi-step logic,\n * cross-artifact joins, or any other behaviour beyond \"call this existing method,\" override\n * {@link SpooledArtifact.forgeTools} and mint the {@link @nhtio/adk!ArtifactTool} directly — do not try\n * to express it through a descriptor.\n *\n * Zero-arg methods are the exception: a descriptor with no `argsSchema` (or one that adds\n * only `callId`-adjacent fields you don't consume) works for any method that takes no\n * arguments, regardless of name.\n */\nexport interface ToolMethodDescriptor {\n  /** Absolute tool name as exposed to the LLM (e.g. `'artifact_head'`). */\n  name: string\n  /** Method to invoke on the resolved artifact instance (e.g. `'head'`, `'json_get'`). */\n  method: string\n  /** Human-readable description passed to the model. Should mention \"in this turn\" so the model understands the artifact's lifecycle scope. */\n  description: string\n  /** Schema for the method's own args, NOT including `callId`. `forgeTools()` injects `callId`. */\n  argsSchema?: ObjectSchema\n  /** Optional formatter for non-string return values. Defaults: string → as-is; string[] → newline-join; number → `String(n)`; otherwise `JSON.stringify(value, null, 2)`. */\n  serialise?: (result: unknown) => string\n}\n\nconst noArgsSchema = validator.object<Record<string, never>>({})\n\n/**\n * Default serialiser for {@link @nhtio/adk!ArtifactTool} handler return values when a descriptor does not\n * provide its own. Exported for reuse by subclass `forgeTools` overrides.\n *\n * @param result - The artifact-method return value.\n * @returns A string suitable for inclusion in an LLM tool-call response.\n */\nexport const defaultSerialise = (result: unknown): string => {\n  if (result === undefined) return '(undefined)'\n  if (result === null) return 'null'\n  if (typeof result === 'string') return result\n  if (Array.isArray(result) && result.every((r) => typeof r === 'string')) {\n    if (result.length === 0) return '(empty list)'\n    return (result as string[]).join('\\n')\n  }\n  if (typeof result === 'number') return String(result)\n  return JSON.stringify(result, null, 2)\n}\n\nconst baseToolMethods: ReadonlyArray<ToolMethodDescriptor> = Object.freeze([\n  {\n    name: 'artifact_head',\n    method: 'head',\n    description:\n      'Return the first n lines of a spooled artifact produced earlier in this turn. Takes a callId selecting which artifact to inspect.',\n    argsSchema: validator.object({\n      n: validator.number().integer().min(1).default(10).description('Number of lines to return.'),\n    }),\n  },\n  {\n    name: 'artifact_tail',\n    method: 'tail',\n    description:\n      'Return the last n lines of a spooled artifact produced earlier in this turn. Takes a callId selecting which artifact to inspect.',\n    argsSchema: validator.object({\n      n: validator.number().integer().min(1).default(10).description('Number of lines to return.'),\n    }),\n  },\n  {\n    name: 'artifact_grep',\n    method: 'grep',\n    description:\n      'Return all lines matching a regular expression pattern from a spooled artifact produced earlier in this turn.',\n    argsSchema: validator.object({\n      pattern: validator\n        .string()\n        .required()\n        .description('Regular expression pattern, applied via JavaScript RegExp.'),\n      flags: validator\n        .string()\n        .pattern(/^[imsu]*$/)\n        .optional()\n        .description(\n          \"Optional RegExp flags. Allowed: 'i' (case-insensitive), 'm' (multiline), 's' (dotAll), 'u' (unicode). 'g' and 'y' are disallowed because per-line matching is stateless.\"\n        ),\n    }),\n  },\n  {\n    name: 'artifact_cat',\n    method: 'cat',\n    description:\n      'Return lines from a spooled artifact produced earlier in this turn, optionally bounded to a range.',\n    argsSchema: validator.object({\n      start: validator.number().integer().min(0).optional().description('Start line (inclusive).'),\n      end: validator.number().integer().min(0).optional().description('End line (exclusive).'),\n    }),\n  },\n  {\n    name: 'artifact_byte_length',\n    method: 'byteLength',\n    description:\n      'Return the total byte length of a spooled artifact produced earlier in this turn.',\n    argsSchema: noArgsSchema,\n  },\n  {\n    name: 'artifact_line_count',\n    method: 'lineCount',\n    description: 'Return the total line count of a spooled artifact produced earlier in this turn.',\n    argsSchema: noArgsSchema,\n  },\n  {\n    name: 'artifact_estimate_tokens',\n    method: 'estimateTokens',\n    description:\n      'Estimate the total token count of a spooled artifact produced earlier in this turn under a named encoding.',\n    argsSchema: validator.object({\n      encoding: validator\n        .string()\n        .valid(...TokenEncoding)\n        .required()\n        .description('Token encoding identifier.'),\n    }),\n  },\n])\n\n/**\n * A lazy, line-oriented view over an arbitrary backing store.\n *\n * @remarks\n * All I/O methods are async to remain compatible with both in-memory and streaming\n * {@link @nhtio/adk!SpoolReader} implementations. Token estimation delegates to\n * {@link @nhtio/adk!Tokenizable.estimateTokens} — the same backends used elsewhere in the ADK.\n *\n * The class is read-only by design: mutation of the underlying data is the responsibility of the\n * producer that created the {@link @nhtio/adk!SpoolReader}, not the consumer reading from this artifact.\n */\nexport class SpooledArtifact {\n  /**\n   * The set of artifact-query methods this class surfaces via {@link SpooledArtifact.forgeTools}.\n   *\n   * @remarks\n   * The base set covers the generic line-oriented operations every artifact supports:\n   * `artifact_head`, `artifact_tail`, `artifact_grep`, `artifact_cat`, `artifact_byte_length`,\n   * `artifact_line_count`, `artifact_estimate_tokens`. Each `toolMethods` array lists **only**\n   * its own class's descriptors — subclasses do not concatenate inherited descriptors. The\n   * subclass instead overrides {@link SpooledArtifact.forgeTools} to merge the base registry\n   * (produced by `SpooledArtifact.forgeTools(ctx)`) with its own — see\n   * {@link @nhtio/adk!SpooledJsonArtifact.forgeTools} and {@link @nhtio/adk!SpooledMarkdownArtifact.forgeTools} for\n   * the canonical shape and the pattern downstream consumers should follow when building\n   * their own `SpooledArtifact` subclasses.\n   *\n   * Tool names are absolute (not subclass-prefixed). Forged tools carry\n   * `Tool.onCollision = 'replace'` so merging multiple subclasses' `forgeTools()` outputs is\n   * silent — every same-named tool dispatches the same method on whatever artifact the\n   * `callId` resolves to, so the overlap is behaviourally interchangeable.\n   *\n   * Frozen at module load.\n   */\n  public static toolMethods: ReadonlyArray<ToolMethodDescriptor> = baseToolMethods\n\n  #reader: SpoolReader\n\n  /**\n   * @param reader - The backing store to read from.\n   * @throws {@link @nhtio/adk!E_NOT_A_SPOOL_READER} when `reader` does not implement {@link @nhtio/adk!SpoolReader}.\n   */\n  constructor(reader: SpoolReader) {\n    if (!implementsSpoolReader(reader)) {\n      throw new E_NOT_A_SPOOL_READER()\n    }\n    this.#reader = reader\n  }\n\n  /**\n   * Returns the line at the given 0-based index, or `undefined` when out of range.\n   *\n   * @remarks\n   * Protected so subclasses can scan the backing store line-by-line without allocating\n   * intermediate arrays. Delegates directly to the {@link @nhtio/adk!SpoolReader}.\n   *\n   * @param index - 0-based line index.\n   * @returns The raw line string, or `undefined` when out of range.\n   */\n  protected async line(index: number): Promise<string | undefined> {\n    return this.#reader.line(index)\n  }\n\n  /**\n   * Returns `true` if `value` is a {@link SpooledArtifact} instance (including any subclass).\n   *\n   * @remarks\n   * Uses the cross-realm-safe {@link @nhtio/adk!isInstanceOf} guard: `instanceof` first, then\n   * `Symbol.hasInstance`, then a `constructor.name` fallback. Subclass instances (e.g.\n   * {@link @nhtio/adk!SpooledJsonArtifact}) satisfy this guard because `instanceof` walks the prototype\n   * chain. The fallbacks handle the dual-module-copy case where two distinct `SpooledArtifact`\n   * classes coexist in the same realm (e.g. one bundled into a downstream library, one in the\n   * consumer's `node_modules`).\n   *\n   * @param value - The value to test.\n   * @returns `true` when `value` is a {@link SpooledArtifact} instance.\n   */\n  public static isSpooledArtifact(value: unknown): value is SpooledArtifact {\n    return isInstanceOf(value, 'SpooledArtifact', SpooledArtifact)\n  }\n\n  /**\n   * Returns `true` if `value` is a constructor function whose prototype chain includes\n   * {@link SpooledArtifact} (including `SpooledArtifact` itself).\n   *\n   * @remarks\n   * Used by {@link @nhtio/adk!Tool} to validate the optional `artifactConstructor` field. Performs an\n   * `instanceof`-based check on the prototype chain; falls back to a duck-type test that looks\n   * for the canonical SpooledArtifact instance methods on `value.prototype` for cross-realm\n   * safety (constructors passed from a different module copy or VM context).\n   *\n   * @param value - The value to test.\n   * @returns `true` when `value` is a constructor for `SpooledArtifact` or a subclass.\n   */\n  public static isSpooledArtifactConstructor(\n    value: unknown\n  ): value is SpooledArtifactConstructor<SpooledArtifact> {\n    if (typeof value !== 'function') return false\n    if (value === SpooledArtifact) return true\n    const proto = (value as { prototype?: unknown }).prototype\n    if (proto === undefined || proto === null) return false\n    if (isInstanceOf(proto, 'SpooledArtifact', SpooledArtifact)) return true\n    // Cross-realm duck-type fallback: prototype carries the canonical SpooledArtifact methods\n    const methods = ['head', 'tail', 'grep', 'cat', 'byteLength', 'lineCount', 'estimateTokens']\n    return methods.every((m) => typeof (proto as Record<string, unknown>)[m] === 'function')\n  }\n\n  /**\n   * Returns the first `n` lines of the artifact.\n   *\n   * @remarks\n   * If the artifact contains fewer than `n` lines, all available lines are returned. Matches the\n   * behaviour of POSIX `head -n`.\n   *\n   * @param n - Number of lines to return. Defaults to 10.\n   * @returns Array of line strings, without trailing newlines.\n   */\n  async head(n: number = 10): Promise<string[]> {\n    const count = await this.#reader.lineCount()\n    const limit = Math.min(n, count)\n    const lines: string[] = []\n    for (let i = 0; i < limit; i++) {\n      const line = await this.#reader.line(i)\n      if (line !== undefined) {\n        lines.push(line)\n      }\n    }\n    return lines\n  }\n\n  /**\n   * Returns the last `n` lines of the artifact.\n   *\n   * @remarks\n   * If the artifact contains fewer than `n` lines, all available lines are returned. Matches the\n   * behaviour of POSIX `tail -n`.\n   *\n   * @param n - Number of lines to return. Defaults to 10.\n   * @returns Array of line strings, without trailing newlines.\n   */\n  async tail(n: number = 10): Promise<string[]> {\n    const count = await this.#reader.lineCount()\n    const start = Math.max(0, count - n)\n    const lines: string[] = []\n    for (let i = start; i < count; i++) {\n      const line = await this.#reader.line(i)\n      if (line !== undefined) {\n        lines.push(line)\n      }\n    }\n    return lines\n  }\n\n  /**\n   * Returns all lines that match `pattern`.\n   *\n   * @remarks\n   * Behaves like POSIX `grep`: each line is tested against the pattern and included in the result\n   * when it matches. The pattern is applied as a JavaScript `RegExp`; flags (e.g. case-\n   * insensitivity) should be encoded in the expression itself.\n   *\n   * Stateful flags (`g`, `y`) on the supplied `RegExp` would normally cause `pattern.test()` to\n   * advance `lastIndex` across calls, producing skipped matches and order-dependent results. To\n   * keep the per-line semantics stateless, `grep` resets `pattern.lastIndex` to `0` before each\n   * line test. The forged `artifact_grep` tool also rejects `g` and `y` flags up-front at schema\n   * validation time.\n   *\n   * @param pattern - The regular expression to test each line against.\n   * @returns Array of matching line strings, in order.\n   */\n  async grep(pattern: RegExp): Promise<string[]> {\n    const count = await this.#reader.lineCount()\n    const matches: string[] = []\n    for (let i = 0; i < count; i++) {\n      const line = await this.#reader.line(i)\n      if (line !== undefined) {\n        pattern.lastIndex = 0\n        if (pattern.test(line)) {\n          matches.push(line)\n        }\n      }\n    }\n    return matches\n  }\n\n  /**\n   * Returns lines from the artifact, optionally bounded to a range.\n   *\n   * @remarks\n   * Without arguments, returns all lines — equivalent to POSIX `cat`. With `start` and/or `end`,\n   * behaves like `Array.prototype.slice`: `start` defaults to `0`, `end` defaults to the total\n   * line count, and only lines in `[start, end)` are fetched from the backing store. For large\n   * artifacts, prefer a bounded range or {@link SpooledArtifact.head} / {@link SpooledArtifact.tail}.\n   *\n   * @param start - 0-based start line index (inclusive). Defaults to `0`.\n   * @param end - 0-based end line index (exclusive). Defaults to `lineCount()`.\n   * @returns Array of line strings in the requested range.\n   */\n  async cat(start?: number, end?: number): Promise<string[]> {\n    const count = await this.#reader.lineCount()\n    const from = Math.max(0, start ?? 0)\n    const to = Math.min(count, end ?? count)\n    const lines: string[] = []\n    for (let i = from; i < to; i++) {\n      const line = await this.#reader.line(i)\n      if (line !== undefined) {\n        lines.push(line)\n      }\n    }\n    return lines\n  }\n\n  /**\n   * Returns the total byte length of the underlying data.\n   *\n   * @returns The byte length as reported by the {@link @nhtio/adk!SpoolReader}.\n   */\n  async byteLength(): Promise<number> {\n    return this.#reader.byteLength()\n  }\n\n  /**\n   * Returns the total number of lines in the artifact.\n   *\n   * @returns The line count as reported by the {@link @nhtio/adk!SpoolReader}.\n   */\n  async lineCount(): Promise<number> {\n    return this.#reader.lineCount()\n  }\n\n  /**\n   * Estimates the total token count of the artifact under `encoding`.\n   *\n   * @remarks\n   * Reads the full byte-faithful content via {@link SpooledArtifact.asString} (which delegates to\n   * {@link @nhtio/adk!SpoolReader.readAll}) and delegates to {@link @nhtio/adk!Tokenizable.estimateTokens}. The estimate\n   * therefore reflects the actual source bytes — including trailing newlines and non-`\\n` line\n   * terminators that the line-based {@link SpooledArtifact.cat} view would otherwise discard or\n   * misrepresent.\n   *\n   * @param encoding - The encoding identifier to use for counting.\n   * @returns The estimated number of tokens.\n   */\n  async estimateTokens(encoding: TokenEncoding): Promise<number> {\n    const content = await this.#reader.readAll()\n    return Tokenizable.estimateTokens(content, encoding)\n  }\n\n  /**\n   * Returns the full artifact body as a single byte-faithful string.\n   *\n   * @remarks\n   * Round-trip faithful to whatever bytes the {@link @nhtio/adk!SpoolReader} was constructed over —\n   * preserves trailing newlines and non-`\\n` line terminators that {@link SpooledArtifact.cat}\n   * discards via its line-based view. This is the canonical primitive for \"inline the artifact\n   * content directly into a message\" use cases.\n   *\n   * `asString()` and the static `forgeTools(ctx)` factory on each subclass are independent\n   * alternatives — a consumer chooses per turn whether to inline the body in a message\n   * (`await tc.results.asString()`) or hand the model query tools\n   * (`SpooledArtifact.forgeTools(ctx)`). Neither calls the other; either works with neither.\n   *\n   * @returns The full content as a single string.\n   */\n  async asString(): Promise<string> {\n    return this.#reader.readAll()\n  }\n\n  /**\n   * Forges a fresh {@link @nhtio/adk!ToolRegistry} of ephemeral {@link @nhtio/adk!ArtifactTool} instances that let the\n   * LLM query artifacts already present in `ctx.turnToolCalls`.\n   *\n   * @remarks\n   * Standard subclass extension pattern — each class owns only its own `toolMethods` and its\n   * own `forgeTools`. The base `SpooledArtifact.forgeTools(ctx)` narrows the `callId` enum to\n   * any `tc.results instanceof SpooledArtifact` (so subclass instances are included — that's\n   * the whole point of inheritance) and dispatches the seven base methods (`head`, `tail`,\n   * `grep`, `cat`, `byteLength`, `lineCount`, `estimateTokens`) on the resolved artifact.\n   * Subclasses override `forgeTools` to call this static first and then register their own\n   * tools on the returned registry — see {@link @nhtio/adk!SpooledJsonArtifact.forgeTools} and\n   * {@link @nhtio/adk!SpooledMarkdownArtifact.forgeTools} for the canonical shape. There is no\n   * `requiresSubclass` field, no helper indirection, and no `this`-based class narrowing —\n   * just plain `instanceof ThisClass` at each subclass's own filter site.\n   *\n   * For each descriptor in this class's `toolMethods`, the factory:\n   *\n   * 1. Walks `ctx.turnToolCalls` to find `ToolCall`s whose `results instanceof SpooledArtifact`.\n   *    `ToolCall`s flagged `fromArtifactTool === true` are excluded — they carry a\n   *    {@link @nhtio/adk!Tokenizable}, not a `SpooledArtifact`, and including them would let the model\n   *    `artifact_grep` on a previous `artifact_grep` result (an infinite-recursion hazard with\n   *    no semantic value).\n   * 2. Returns an empty registry if no compatible callIds are found — no point shipping tools\n   *    whose `callId` enum is empty.\n   * 3. Otherwise mints an {@link @nhtio/adk!ArtifactTool} with `ephemeral: true` and `onCollision: 'replace'`\n   *    so multiple `Subclass.forgeTools(ctx)` outputs merge silently. The tool's `inputSchema`\n   *    includes a required `callId` field with `.valid(...compatibleIds)`, plus the descriptor's\n   *    own `argsSchema` fields.\n   *\n   * The handler resolves the artifact via `[...ctx.turnToolCalls].find(t => t.id === callId)`,\n   * dispatches the descriptor's method, and serialises the return value (string → as-is;\n   * string[] → newline-join; number → `String(n)`; otherwise `JSON.stringify(value, null, 2)`;\n   * `descriptor.serialise` overrides the defaults). `grep` is special-cased: the handler\n   * constructs `new RegExp(pattern, flags ?? '')` before invoking the artifact's `grep` method.\n   *\n   * The returned registry must be merged into the consumer's main registry and the main\n   * registry must be bound to `ctx` via {@link @nhtio/adk!ToolRegistry.bindContext}:\n   *\n   * ```ts\n   * const executor: DispatchExecutorFn = async (ctx) => {\n   *   const forged = SpooledArtifact.forgeTools(ctx)\n   *   const merged = ToolRegistry.merge([main, forged])\n   *   main.bindContext(ctx)\n   *   const result = await llm.invoke({ tools: merged.all(), ... })\n   *   ctx.ack() // ← ephemeral cleanup fires here\n   * }\n   * ```\n   *\n   * @warning You **must** call `registry.bindContext(ctx)` on the registry hosting these tools,\n   * or ephemeral cleanup will not run and the `callId` enum in subsequent executor calls will\n   * be stale (excluding new tool calls produced in the meantime).\n   *\n   * @param ctx - The execution context whose `turnToolCalls` snapshot defines the `callId` enum.\n   * @returns A fresh `ToolRegistry`. Empty when `turnToolCalls` contains no compatible artifacts.\n   *\n   * @see {@link @nhtio/adk!ToolRegistry.bindContext}\n   * @see {@link @nhtio/adk!ToolRegistry.merge}\n   * @see {@link @nhtio/adk!DispatchContext.onAck}\n   */\n  public static forgeTools(ctx: DispatchContext): ToolRegistry {\n    const requires: SpooledArtifactConstructor = SpooledArtifact\n    const calls = [...ctx.turnToolCalls]\n    const compatibleIds = calls\n      .filter((tc) => !tc.fromArtifactTool && isInstanceOf(tc.results, requires.name, requires))\n      .map((tc) => tc.id)\n    if (compatibleIds.length === 0) return new ToolRegistry([])\n\n    const tools: ArtifactTool[] = []\n    for (const descriptor of this.toolMethods) {\n      const callIdSchema = validator\n        .string()\n        .valid(...compatibleIds)\n        .required()\n        .description('ToolCall id of the artifact to query.')\n\n      const argsSchema = (descriptor.argsSchema ?? noArgsSchema).append({\n        callId: callIdSchema,\n      })\n\n      const serialise = descriptor.serialise ?? defaultSerialise\n\n      const tool = new ArtifactTool({\n        name: descriptor.name,\n        description: descriptor.description,\n        inputSchema: argsSchema,\n        ephemeral: true,\n        onCollision: 'replace',\n        handler: async (rawArgs, ctxInner) => {\n          const args = rawArgs as Record<string, unknown> & { callId: string }\n          const tc = [...ctxInner.turnToolCalls].find((t) => t.id === args.callId)\n          if (!tc) {\n            return `Error: no tool call with id ${args.callId} in this turn`\n          }\n          const artifact = tc.results\n          if (!isInstanceOf(artifact, requires.name, requires)) {\n            return `Error: tool call ${args.callId} results are not a ${requires.name} instance`\n          }\n          const methodArgs: unknown[] = []\n          if (descriptor.method === 'grep') {\n            const pattern = args.pattern as string\n            const flags = (args.flags as string | undefined) ?? ''\n            methodArgs.push(new RegExp(pattern, flags))\n          } else if (descriptor.method === 'head' || descriptor.method === 'tail') {\n            methodArgs.push((args.n as number | undefined) ?? 10)\n          } else if (descriptor.method === 'cat') {\n            methodArgs.push(args.start as number | undefined, args.end as number | undefined)\n          } else if (descriptor.method === 'estimateTokens') {\n            methodArgs.push(args.encoding as TokenEncoding)\n          }\n          const fn = (artifact as unknown as Record<string, (...a: unknown[]) => unknown>)[\n            descriptor.method\n          ]\n          if (typeof fn !== 'function') {\n            return `Error: artifact has no method ${descriptor.method}`\n          }\n          const result = await Promise.resolve(fn.apply(artifact, methodArgs))\n          return serialise(result)\n        },\n      })\n      tools.push(tool)\n    }\n    return new ToolRegistry(tools)\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"spooled_artifact-7eePq7JA.mjs","names":["#reader"],"sources":["../src/lib/classes/artifact_tool.ts","../src/lib/contracts/spool_reader.ts","../src/lib/classes/spooled_artifact.ts"],"sourcesContent":["import { Tool } from './tool'\nimport { validator } from '@nhtio/validation'\nimport { isInstanceOf } from '../utils/guards'\nimport { E_INVALID_INITIAL_TOOL_VALUE } from '../exceptions/runtime'\nimport { validateOrThrow, ValidationException } from '../utils/validation'\nimport type { Registry } from './registry'\nimport type { Schema } from '@nhtio/validation'\nimport type { Tokenizable } from './tokenizable'\nimport type { DispatchContext } from '../contracts/dispatch_context'\n\n/**\n * The execution function for an {@link ArtifactTool}.\n *\n * @remarks\n * Identical to the base tool handler except the return type is narrowed to\n * `string | Tokenizable | Promise<string | Tokenizable>`. Forged artifact-query tools emit\n * model-visible strings — the ADK wraps a bare-string return into a {@link @nhtio/adk!Tokenizable}\n * at the result-wrapping site so downstream code can rely on\n * `ToolCall.results instanceof Tokenizable` for every `ArtifactTool` invocation.\n */\nexport type ArtifactToolHandler = (\n  args: unknown,\n  ctx: DispatchContext,\n  meta: Registry\n) => string | Tokenizable | Promise<string | Tokenizable>\n\n/**\n * Plain input object supplied to {@link ArtifactTool} at construction time.\n *\n * @remarks\n * Mirrors the base `RawTool` except `artifactConstructor` is forbidden — an `ArtifactTool`\n * emits a {@link @nhtio/adk!Tokenizable} directly into `ToolCall.results` and explicitly opts out of\n * `SpooledArtifact` wrapping. The forbidden field is enforced by {@link ArtifactTool.schema}\n * at construction time.\n */\nexport interface RawArtifactTool {\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. */\n  inputSchema: Schema\n  /** Execution function. Returns a string or {@link @nhtio/adk!Tokenizable}; the ADK wraps a bare string into a `Tokenizable` at the result-wrapping site. */\n  handler: ArtifactToolHandler\n  /** Optional arbitrary metadata for this tool. Defaults to `{}`. */\n  meta?: Record<string, unknown>\n  /**\n   * When `true`, marks this tool as owned by a specific {@link @nhtio/adk!DispatchContext}.\n   *\n   * @remarks\n   * `ArtifactTool` instances produced by `SpooledArtifact.forgeTools(ctx)` set this to `true`\n   * so that `ToolRegistry.pruneEphemeral()` drops them at ctx-completion.\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   * Forged artifact-query tools default to `false` because their results are derived from\n   * spooled artifact bodies — which may themselves be untrusted upstream tool output. The\n   * trust signal does not promote handle-query results above the trust tier of the underlying\n   * artifact.\n   *\n   * @defaultValue `false`\n   */\n  trusted?: boolean\n  /**\n   * Self-declared merge collision policy honoured by `ToolRegistry.merge`.\n   *\n   * @remarks\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 RawArtifactTool}.\n *\n * @remarks\n * Mirrors the base tool schema but explicitly forbids `artifactConstructor` — the entire\n * point of `ArtifactTool` is to opt out of `SpooledArtifact` wrapping.\n */\nconst rawArtifactToolSchema = validator.object<RawArtifactTool & { artifactConstructor?: never }>({\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  // eslint-disable-next-line adk/require-validator-any-required -- map value type-arg: meta holds arbitrary values; disposition is set by .default({}) on the object\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  artifactConstructor: validator.any().forbidden(),\n})\n\n/**\n * A {@link @nhtio/adk!Tool} subclass whose handler return value is wrapped directly in a\n * {@link @nhtio/adk!Tokenizable} (not a {@link @nhtio/adk!SpooledArtifact}) when it\n * lands on `ToolCall.results`.\n *\n * @remarks\n * `ArtifactTool` is the canonical producer for **forged artifact-query tools** — the tools\n * `SpooledArtifact.forgeTools(ctx)` emits so the model can `head`, `tail`, `grep`, `json_get`,\n * `md_headings` (etc.) an artifact that is already in `ctx.turnToolCalls`.\n *\n * The difference from {@link @nhtio/adk!Tool} is structural, not stylistic:\n *\n * - A normal `Tool`'s handler returns bytes the ADK wraps in a fresh `SpooledArtifact`.\n *   The artifact lands in `ToolCall.results`, joins `ctx.turnToolCalls`, and is itself a\n *   first-class queryable artifact in the turn.\n * - An `ArtifactTool`'s handler returns a string that is **already the model-visible answer**\n *   to a query against an existing artifact. The ADK wraps it in a `Tokenizable` rather\n *   than a `SpooledArtifact`; nothing new is queryable on its own. Subsequent\n *   `forgeTools(ctx)` calls exclude `ToolCall`s produced by an `ArtifactTool` from the\n *   `callId` enum (via the `ToolCall.fromArtifactTool` marker) — this is the structural fix\n *   that breaks the otherwise-recursive grep-on-the-grep-result loop.\n *\n * Consumers who want to build their own artifact-query tools (e.g. for a domain-specific\n * spooled subclass not shipped by the ADK) should extend or instantiate this class.\n */\nexport class ArtifactTool extends Tool {\n  /**\n   * Validator schema that accepts a {@link RawArtifactTool} object.\n   *\n   * @remarks\n   * Differs from {@link @nhtio/adk!Tool.schema} by forbidding `artifactConstructor` — wrapping is\n   * exactly the thing this class opts out of. Typed identically to {@link @nhtio/adk!Tool.schema} so the\n   * subclass relationship `class ArtifactTool extends Tool` remains structurally sound; the\n   * runtime validation rules still differ as declared by `rawArtifactToolSchema`.\n   */\n  public static schema = rawArtifactToolSchema as unknown as typeof Tool.schema\n\n  /**\n   * Returns `true` if `value` is an {@link ArtifactTool} instance.\n   *\n   * @remarks\n   * Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety — `instanceof` would fail for instances\n   * created in a different module copy or VM context.\n   *\n   * @param value - The value to test.\n   * @returns `true` when `value` is an {@link ArtifactTool} instance.\n   */\n  public static isArtifactTool(value: unknown): value is ArtifactTool {\n    return isInstanceOf(value, 'ArtifactTool', ArtifactTool)\n  }\n\n  /**\n   * @param raw - Raw tool input validated against {@link ArtifactTool.schema}.\n   *\n   * @throws {@link @nhtio/adk!E_INVALID_INITIAL_TOOL_VALUE} when `raw` does not satisfy\n   *   {@link ArtifactTool.schema} (most commonly, when `artifactConstructor` is supplied — it is\n   *   explicitly forbidden on this class) or when the base {@link @nhtio/adk!Tool} constructor rejects the\n   *   input for any reason.\n   */\n  constructor(raw: RawArtifactTool) {\n    // Enforce the forbidden `artifactConstructor` field up-front so the error reports against\n    // ArtifactTool's contract, not the base Tool's. The base Tool constructor re-validates\n    // against its own schema and stores the resolved fields.\n    try {\n      validateOrThrow(rawArtifactToolSchema, raw, true)\n    } catch (err) {\n      if (isInstanceOf(err, 'ValidationException', ValidationException)) {\n        throw new E_INVALID_INITIAL_TOOL_VALUE({ cause: err })\n      }\n      throw err\n    }\n    super(raw as never)\n  }\n}\n","import { validator } from '@nhtio/validation'\nimport { passesSchema } from '../utils/validation'\n\n/**\n * Backing store contract for a {@link @nhtio/adk!SpooledArtifact}.\n *\n * @remarks\n * Implementations may read from memory, a file handle, a network stream, or any other byte\n * source. The interface is intentionally minimal — the artifact layer handles all higher-level\n * operations (`head`, `tail`, `grep`, etc.) by composing calls to these three primitives.\n *\n * Line indexing is 0-based. Implementations must return `undefined` from {@link SpoolReader.line}\n * when the index is out of range rather than throwing.\n *\n * All three methods may be synchronous or asynchronous to accommodate both in-memory and I/O-\n * backed implementations without forcing unnecessary promise overhead on simple cases.\n */\nexport interface SpoolReader {\n  /**\n   * Returns the line at the given 0-based index, or `undefined` when out of range.\n   *\n   * @param index - 0-based line index.\n   * @returns The raw line string (without trailing newline), or `undefined`.\n   */\n  line(index: number): string | undefined | Promise<string | undefined>\n\n  /**\n   * Returns the total number of bytes in the underlying data.\n   *\n   * @remarks\n   * Used for reporting and token-estimation purposes. Byte length is distinct from character\n   * length for multi-byte encodings.\n   *\n   * @returns The byte length of the underlying data.\n   */\n  byteLength(): number | Promise<number>\n\n  /**\n   * Returns the total number of lines in the underlying data.\n   *\n   * @remarks\n   * Required so consumers know when to stop iterating; the line count must remain stable for the\n   * lifetime of the reader.\n   *\n   * @returns The total line count.\n   */\n  lineCount(): number | Promise<number>\n\n  /**\n   * Returns the full underlying content as a single decoded string, byte-faithful to the source.\n   *\n   * @remarks\n   * Unlike {@link SpoolReader.line}, this method preserves trailing newlines and any non-`\\n`\n   * line terminators (e.g. `\\r\\n`) present in the original bytes. It is the primitive that\n   * powers `SpooledArtifact.asString()` — the round-trip-faithful alternative to assembling\n   * the artifact body from per-line reads.\n   *\n   * Implementations should make this O(n) in the size of the underlying data and may cache the\n   * result if the read source is durable. Streaming implementations may choose not to cache.\n   *\n   * @returns The full underlying content as a single string.\n   */\n  readAll(): string | Promise<string>\n}\n\n/**\n * Validator schema used to validate a {@link SpoolReader} value.\n *\n * @remarks\n * Because `SpoolReader` is a structural interface with no associated constructor, validation is\n * duck-typed: the value must be an object, class instance, or function with `line`, `byteLength`,\n * and `lineCount` present as callable properties. Arity is not enforced — implementations may add\n * optional parameters beyond the contract.\n */\nexport const spoolReaderSchema = validator\n  .any()\n  .required()\n  .custom((value, helpers) => {\n    if (\n      value !== null &&\n      value !== undefined &&\n      typeof (value as any).line === 'function' &&\n      typeof (value as any).byteLength === 'function' &&\n      typeof (value as any).lineCount === 'function' &&\n      typeof (value as any).readAll === 'function'\n    ) {\n      return value as SpoolReader\n    }\n    return helpers.error('any.invalid')\n  })\n\n/**\n * Returns `true` if `value` implements the {@link SpoolReader} interface.\n *\n * @remarks\n * Duck-typed: checks that `value` is non-null with `line`, `byteLength`, `lineCount`, and\n * `readAll` as callable functions. Does not use `instanceof` — there is no `SpoolReader`\n * constructor.\n *\n * @param value - The value to test.\n * @returns `true` when `value` conforms to the {@link SpoolReader} interface.\n */\nexport const implementsSpoolReader = (value: unknown): value is SpoolReader => {\n  return passesSchema(spoolReaderSchema, value)\n}\n","import { validator } from '@nhtio/validation'\nimport { isInstanceOf } from '../utils/guards'\nimport { ArtifactTool } from './artifact_tool'\nimport { ToolRegistry } from './tool_registry'\nimport { Tokenizable, TokenEncoding } from './tokenizable'\nimport { E_NOT_A_SPOOL_READER } from '../exceptions/runtime'\nimport { implementsSpoolReader } from '../contracts/spool_reader'\nimport type { ObjectSchema } from '@nhtio/validation'\nimport type { SpoolReader } from '../contracts/spool_reader'\nimport type { DispatchContext } from '../contracts/dispatch_context'\n\n/**\n * Constructor signature for {@link SpooledArtifact} and any subclass.\n *\n * @remarks\n * Used by {@link @nhtio/adk!Tool} to declare the artifact subclass the consumer should use when wrapping\n * the handler's serialised output. The variadic rest parameter accommodates subclass-specific\n * constructor arguments (e.g. `SpooledJsonArtifact(reader, format?)`).\n *\n * @typeParam A - The {@link SpooledArtifact} subtype the constructor produces.\n */\nexport type SpooledArtifactConstructor<A extends SpooledArtifact = SpooledArtifact> = new (\n  reader: SpoolReader,\n  ...rest: any[]\n) => A\n\n/**\n * Metadata table entry for one of the artifact's existing query methods, used by\n * {@link SpooledArtifact.forgeTools} to surface that method as an {@link @nhtio/adk!ArtifactTool}.\n *\n * @remarks\n * This is a metadata shape, not a general method → tool pipeline. `forgeTools` knows how to\n * marshal arguments for a fixed, closed set of method names (the base seven on\n * {@link SpooledArtifact} and the JSON/Markdown methods on the bundled subclasses); a\n * descriptor is the place to attach a tool name, description, args schema, and optional\n * serializer to one of those methods. Adding a descriptor for a method whose name is not\n * in that closed set will produce a tool whose handler invokes the method with no arguments.\n *\n * For new methods that require custom argument marshalling, branching, multi-step logic,\n * cross-artifact joins, or any other behaviour beyond \"call this existing method,\" override\n * {@link SpooledArtifact.forgeTools} and mint the {@link @nhtio/adk!ArtifactTool} directly — do not try\n * to express it through a descriptor.\n *\n * Zero-arg methods are the exception: a descriptor with no `argsSchema` (or one that adds\n * only `callId`-adjacent fields you don't consume) works for any method that takes no\n * arguments, regardless of name.\n */\nexport interface ToolMethodDescriptor {\n  /** Absolute tool name as exposed to the LLM (e.g. `'artifact_head'`). */\n  name: string\n  /** Method to invoke on the resolved artifact instance (e.g. `'head'`, `'json_get'`). */\n  method: string\n  /** Human-readable description passed to the model. Should mention \"in this turn\" so the model understands the artifact's lifecycle scope. */\n  description: string\n  /** Schema for the method's own args, NOT including `callId`. `forgeTools()` injects `callId`. */\n  argsSchema?: ObjectSchema\n  /** Optional formatter for non-string return values. Defaults: string → as-is; string[] → newline-join; number → `String(n)`; otherwise `JSON.stringify(value, null, 2)`. */\n  serialise?: (result: unknown) => string\n}\n\nconst noArgsSchema = validator.object<Record<string, never>>({})\n\n/**\n * Default serialiser for {@link @nhtio/adk!ArtifactTool} handler return values when a descriptor does not\n * provide its own. Exported for reuse by subclass `forgeTools` overrides.\n *\n * @param result - The artifact-method return value.\n * @returns A string suitable for inclusion in an LLM tool-call response.\n */\nexport const defaultSerialise = (result: unknown): string => {\n  if (result === undefined) return '(undefined)'\n  if (result === null) return 'null'\n  if (typeof result === 'string') return result\n  if (Array.isArray(result) && result.every((r) => typeof r === 'string')) {\n    if (result.length === 0) return '(empty list)'\n    return (result as string[]).join('\\n')\n  }\n  if (typeof result === 'number') return String(result)\n  return JSON.stringify(result, null, 2)\n}\n\nconst baseToolMethods: ReadonlyArray<ToolMethodDescriptor> = Object.freeze([\n  {\n    name: 'artifact_head',\n    method: 'head',\n    description:\n      'Return the first n lines of a spooled artifact produced earlier in this turn. Takes a callId selecting which artifact to inspect.',\n    argsSchema: validator.object({\n      n: validator.number().integer().min(1).default(10).description('Number of lines to return.'),\n    }),\n  },\n  {\n    name: 'artifact_tail',\n    method: 'tail',\n    description:\n      'Return the last n lines of a spooled artifact produced earlier in this turn. Takes a callId selecting which artifact to inspect.',\n    argsSchema: validator.object({\n      n: validator.number().integer().min(1).default(10).description('Number of lines to return.'),\n    }),\n  },\n  {\n    name: 'artifact_grep',\n    method: 'grep',\n    description:\n      'Return all lines matching a regular expression pattern from a spooled artifact produced earlier in this turn.',\n    argsSchema: validator.object({\n      pattern: validator\n        .string()\n        .required()\n        .description('Regular expression pattern, applied via JavaScript RegExp.'),\n      flags: validator\n        .string()\n        .pattern(/^[imsu]*$/)\n        .optional()\n        .description(\n          \"Optional RegExp flags. Allowed: 'i' (case-insensitive), 'm' (multiline), 's' (dotAll), 'u' (unicode). 'g' and 'y' are disallowed because per-line matching is stateless.\"\n        ),\n    }),\n  },\n  {\n    name: 'artifact_cat',\n    method: 'cat',\n    description:\n      'Return lines from a spooled artifact produced earlier in this turn, optionally bounded to a range.',\n    argsSchema: validator.object({\n      start: validator.number().integer().min(0).optional().description('Start line (inclusive).'),\n      end: validator.number().integer().min(0).optional().description('End line (exclusive).'),\n    }),\n  },\n  {\n    name: 'artifact_byte_length',\n    method: 'byteLength',\n    description:\n      'Return the total byte length of a spooled artifact produced earlier in this turn.',\n    argsSchema: noArgsSchema,\n  },\n  {\n    name: 'artifact_line_count',\n    method: 'lineCount',\n    description: 'Return the total line count of a spooled artifact produced earlier in this turn.',\n    argsSchema: noArgsSchema,\n  },\n  {\n    name: 'artifact_estimate_tokens',\n    method: 'estimateTokens',\n    description:\n      'Estimate the total token count of a spooled artifact produced earlier in this turn under a named encoding.',\n    argsSchema: validator.object({\n      encoding: validator\n        .string()\n        .valid(...TokenEncoding)\n        .required()\n        .description('Token encoding identifier.'),\n    }),\n  },\n])\n\n/**\n * A lazy, line-oriented view over an arbitrary backing store.\n *\n * @remarks\n * All I/O methods are async to remain compatible with both in-memory and streaming\n * {@link @nhtio/adk!SpoolReader} implementations. Token estimation delegates to\n * {@link @nhtio/adk!Tokenizable.estimateTokens} — the same backends used elsewhere in the ADK.\n *\n * The class is read-only by design: mutation of the underlying data is the responsibility of the\n * producer that created the {@link @nhtio/adk!SpoolReader}, not the consumer reading from this artifact.\n */\nexport class SpooledArtifact {\n  /**\n   * The set of artifact-query methods this class surfaces via {@link SpooledArtifact.forgeTools}.\n   *\n   * @remarks\n   * The base set covers the generic line-oriented operations every artifact supports:\n   * `artifact_head`, `artifact_tail`, `artifact_grep`, `artifact_cat`, `artifact_byte_length`,\n   * `artifact_line_count`, `artifact_estimate_tokens`. Each `toolMethods` array lists **only**\n   * its own class's descriptors — subclasses do not concatenate inherited descriptors. The\n   * subclass instead overrides {@link SpooledArtifact.forgeTools} to merge the base registry\n   * (produced by `SpooledArtifact.forgeTools(ctx)`) with its own — see\n   * {@link @nhtio/adk!SpooledJsonArtifact.forgeTools} and {@link @nhtio/adk!SpooledMarkdownArtifact.forgeTools} for\n   * the canonical shape and the pattern downstream consumers should follow when building\n   * their own `SpooledArtifact` subclasses.\n   *\n   * Tool names are absolute (not subclass-prefixed). Forged tools carry\n   * `Tool.onCollision = 'replace'` so merging multiple subclasses' `forgeTools()` outputs is\n   * silent — every same-named tool dispatches the same method on whatever artifact the\n   * `callId` resolves to, so the overlap is behaviourally interchangeable.\n   *\n   * Frozen at module load.\n   */\n  public static toolMethods: ReadonlyArray<ToolMethodDescriptor> = baseToolMethods\n\n  #reader: SpoolReader\n\n  /**\n   * @param reader - The backing store to read from.\n   * @throws {@link @nhtio/adk!E_NOT_A_SPOOL_READER} when `reader` does not implement {@link @nhtio/adk!SpoolReader}.\n   */\n  constructor(reader: SpoolReader) {\n    if (!implementsSpoolReader(reader)) {\n      throw new E_NOT_A_SPOOL_READER()\n    }\n    this.#reader = reader\n  }\n\n  /**\n   * Returns the line at the given 0-based index, or `undefined` when out of range.\n   *\n   * @remarks\n   * Protected so subclasses can scan the backing store line-by-line without allocating\n   * intermediate arrays. Delegates directly to the {@link @nhtio/adk!SpoolReader}.\n   *\n   * @param index - 0-based line index.\n   * @returns The raw line string, or `undefined` when out of range.\n   */\n  protected async line(index: number): Promise<string | undefined> {\n    return this.#reader.line(index)\n  }\n\n  /**\n   * Returns `true` if `value` is a {@link SpooledArtifact} instance (including any subclass).\n   *\n   * @remarks\n   * Uses the cross-realm-safe {@link @nhtio/adk!isInstanceOf} guard: `instanceof` first, then\n   * `Symbol.hasInstance`, then a `constructor.name` fallback. Subclass instances (e.g.\n   * {@link @nhtio/adk!SpooledJsonArtifact}) satisfy this guard because `instanceof` walks the prototype\n   * chain. The fallbacks handle the dual-module-copy case where two distinct `SpooledArtifact`\n   * classes coexist in the same realm (e.g. one bundled into a downstream library, one in the\n   * consumer's `node_modules`).\n   *\n   * @param value - The value to test.\n   * @returns `true` when `value` is a {@link SpooledArtifact} instance.\n   */\n  public static isSpooledArtifact(value: unknown): value is SpooledArtifact {\n    return isInstanceOf(value, 'SpooledArtifact', SpooledArtifact)\n  }\n\n  /**\n   * Returns `true` if `value` is a constructor function whose prototype chain includes\n   * {@link SpooledArtifact} (including `SpooledArtifact` itself).\n   *\n   * @remarks\n   * Used by {@link @nhtio/adk!Tool} to validate the optional `artifactConstructor` field. Performs an\n   * `instanceof`-based check on the prototype chain; falls back to a duck-type test that looks\n   * for the canonical SpooledArtifact instance methods on `value.prototype` for cross-realm\n   * safety (constructors passed from a different module copy or VM context).\n   *\n   * @param value - The value to test.\n   * @returns `true` when `value` is a constructor for `SpooledArtifact` or a subclass.\n   */\n  public static isSpooledArtifactConstructor(\n    value: unknown\n  ): value is SpooledArtifactConstructor<SpooledArtifact> {\n    if (typeof value !== 'function') return false\n    if (value === SpooledArtifact) return true\n    const proto = (value as { prototype?: unknown }).prototype\n    if (proto === undefined || proto === null) return false\n    if (isInstanceOf(proto, 'SpooledArtifact', SpooledArtifact)) return true\n    // Cross-realm duck-type fallback: prototype carries the canonical SpooledArtifact methods\n    const methods = ['head', 'tail', 'grep', 'cat', 'byteLength', 'lineCount', 'estimateTokens']\n    return methods.every((m) => typeof (proto as Record<string, unknown>)[m] === 'function')\n  }\n\n  /**\n   * Returns the first `n` lines of the artifact.\n   *\n   * @remarks\n   * If the artifact contains fewer than `n` lines, all available lines are returned. Matches the\n   * behaviour of POSIX `head -n`.\n   *\n   * @param n - Number of lines to return. Defaults to 10.\n   * @returns Array of line strings, without trailing newlines.\n   */\n  async head(n: number = 10): Promise<string[]> {\n    const count = await this.#reader.lineCount()\n    const limit = Math.min(n, count)\n    const lines: string[] = []\n    for (let i = 0; i < limit; i++) {\n      const line = await this.#reader.line(i)\n      if (line !== undefined) {\n        lines.push(line)\n      }\n    }\n    return lines\n  }\n\n  /**\n   * Returns the last `n` lines of the artifact.\n   *\n   * @remarks\n   * If the artifact contains fewer than `n` lines, all available lines are returned. Matches the\n   * behaviour of POSIX `tail -n`.\n   *\n   * @param n - Number of lines to return. Defaults to 10.\n   * @returns Array of line strings, without trailing newlines.\n   */\n  async tail(n: number = 10): Promise<string[]> {\n    const count = await this.#reader.lineCount()\n    const start = Math.max(0, count - n)\n    const lines: string[] = []\n    for (let i = start; i < count; i++) {\n      const line = await this.#reader.line(i)\n      if (line !== undefined) {\n        lines.push(line)\n      }\n    }\n    return lines\n  }\n\n  /**\n   * Returns all lines that match `pattern`.\n   *\n   * @remarks\n   * Behaves like POSIX `grep`: each line is tested against the pattern and included in the result\n   * when it matches. The pattern is applied as a JavaScript `RegExp`; flags (e.g. case-\n   * insensitivity) should be encoded in the expression itself.\n   *\n   * Stateful flags (`g`, `y`) on the supplied `RegExp` would normally cause `pattern.test()` to\n   * advance `lastIndex` across calls, producing skipped matches and order-dependent results. To\n   * keep the per-line semantics stateless, `grep` resets `pattern.lastIndex` to `0` before each\n   * line test. The forged `artifact_grep` tool also rejects `g` and `y` flags up-front at schema\n   * validation time.\n   *\n   * @param pattern - The regular expression to test each line against.\n   * @returns Array of matching line strings, in order.\n   */\n  async grep(pattern: RegExp): Promise<string[]> {\n    const count = await this.#reader.lineCount()\n    const matches: string[] = []\n    for (let i = 0; i < count; i++) {\n      const line = await this.#reader.line(i)\n      if (line !== undefined) {\n        pattern.lastIndex = 0\n        if (pattern.test(line)) {\n          matches.push(line)\n        }\n      }\n    }\n    return matches\n  }\n\n  /**\n   * Returns lines from the artifact, optionally bounded to a range.\n   *\n   * @remarks\n   * Without arguments, returns all lines — equivalent to POSIX `cat`. With `start` and/or `end`,\n   * behaves like `Array.prototype.slice`: `start` defaults to `0`, `end` defaults to the total\n   * line count, and only lines in `[start, end)` are fetched from the backing store. For large\n   * artifacts, prefer a bounded range or {@link SpooledArtifact.head} / {@link SpooledArtifact.tail}.\n   *\n   * @param start - 0-based start line index (inclusive). Defaults to `0`.\n   * @param end - 0-based end line index (exclusive). Defaults to `lineCount()`.\n   * @returns Array of line strings in the requested range.\n   */\n  async cat(start?: number, end?: number): Promise<string[]> {\n    const count = await this.#reader.lineCount()\n    const from = Math.max(0, start ?? 0)\n    const to = Math.min(count, end ?? count)\n    const lines: string[] = []\n    for (let i = from; i < to; i++) {\n      const line = await this.#reader.line(i)\n      if (line !== undefined) {\n        lines.push(line)\n      }\n    }\n    return lines\n  }\n\n  /**\n   * Returns the total byte length of the underlying data.\n   *\n   * @returns The byte length as reported by the {@link @nhtio/adk!SpoolReader}.\n   */\n  async byteLength(): Promise<number> {\n    return this.#reader.byteLength()\n  }\n\n  /**\n   * Returns the total number of lines in the artifact.\n   *\n   * @returns The line count as reported by the {@link @nhtio/adk!SpoolReader}.\n   */\n  async lineCount(): Promise<number> {\n    return this.#reader.lineCount()\n  }\n\n  /**\n   * Estimates the total token count of the artifact under `encoding`.\n   *\n   * @remarks\n   * Reads the full byte-faithful content via {@link SpooledArtifact.asString} (which delegates to\n   * {@link @nhtio/adk!SpoolReader.readAll}) and delegates to {@link @nhtio/adk!Tokenizable.estimateTokens}. The estimate\n   * therefore reflects the actual source bytes — including trailing newlines and non-`\\n` line\n   * terminators that the line-based {@link SpooledArtifact.cat} view would otherwise discard or\n   * misrepresent.\n   *\n   * @param encoding - The encoding identifier to use for counting.\n   * @returns The estimated number of tokens.\n   */\n  async estimateTokens(encoding: TokenEncoding): Promise<number> {\n    const content = await this.#reader.readAll()\n    return Tokenizable.estimateTokens(content, encoding)\n  }\n\n  /**\n   * Returns the full artifact body as a single byte-faithful string.\n   *\n   * @remarks\n   * Round-trip faithful to whatever bytes the {@link @nhtio/adk!SpoolReader} was constructed over —\n   * preserves trailing newlines and non-`\\n` line terminators that {@link SpooledArtifact.cat}\n   * discards via its line-based view. This is the canonical primitive for \"inline the artifact\n   * content directly into a message\" use cases.\n   *\n   * `asString()` and the static `forgeTools(ctx)` factory on each subclass are independent\n   * alternatives — a consumer chooses per turn whether to inline the body in a message\n   * (`await tc.results.asString()`) or hand the model query tools\n   * (`SpooledArtifact.forgeTools(ctx)`). Neither calls the other; either works with neither.\n   *\n   * @returns The full content as a single string.\n   */\n  async asString(): Promise<string> {\n    return this.#reader.readAll()\n  }\n\n  /**\n   * Forges a fresh {@link @nhtio/adk!ToolRegistry} of ephemeral {@link @nhtio/adk!ArtifactTool} instances that let the\n   * LLM query artifacts already present in `ctx.turnToolCalls`.\n   *\n   * @remarks\n   * Standard subclass extension pattern — each class owns only its own `toolMethods` and its\n   * own `forgeTools`. The base `SpooledArtifact.forgeTools(ctx)` narrows the `callId` enum to\n   * any `tc.results instanceof SpooledArtifact` (so subclass instances are included — that's\n   * the whole point of inheritance) and dispatches the seven base methods (`head`, `tail`,\n   * `grep`, `cat`, `byteLength`, `lineCount`, `estimateTokens`) on the resolved artifact.\n   * Subclasses override `forgeTools` to call this static first and then register their own\n   * tools on the returned registry — see {@link @nhtio/adk!SpooledJsonArtifact.forgeTools} and\n   * {@link @nhtio/adk!SpooledMarkdownArtifact.forgeTools} for the canonical shape. There is no\n   * `requiresSubclass` field, no helper indirection, and no `this`-based class narrowing —\n   * just plain `instanceof ThisClass` at each subclass's own filter site.\n   *\n   * For each descriptor in this class's `toolMethods`, the factory:\n   *\n   * 1. Walks `ctx.turnToolCalls` to find `ToolCall`s whose `results instanceof SpooledArtifact`.\n   *    `ToolCall`s flagged `fromArtifactTool === true` are excluded — they carry a\n   *    {@link @nhtio/adk!Tokenizable}, not a `SpooledArtifact`, and including them would let the model\n   *    `artifact_grep` on a previous `artifact_grep` result (an infinite-recursion hazard with\n   *    no semantic value).\n   * 2. Returns an empty registry if no compatible callIds are found — no point shipping tools\n   *    whose `callId` enum is empty.\n   * 3. Otherwise mints an {@link @nhtio/adk!ArtifactTool} with `ephemeral: true` and `onCollision: 'replace'`\n   *    so multiple `Subclass.forgeTools(ctx)` outputs merge silently. The tool's `inputSchema`\n   *    includes a required `callId` field with `.valid(...compatibleIds)`, plus the descriptor's\n   *    own `argsSchema` fields.\n   *\n   * The handler resolves the artifact via `[...ctx.turnToolCalls].find(t => t.id === callId)`,\n   * dispatches the descriptor's method, and serialises the return value (string → as-is;\n   * string[] → newline-join; number → `String(n)`; otherwise `JSON.stringify(value, null, 2)`;\n   * `descriptor.serialise` overrides the defaults). `grep` is special-cased: the handler\n   * constructs `new RegExp(pattern, flags ?? '')` before invoking the artifact's `grep` method.\n   *\n   * The returned registry must be merged into the consumer's main registry and the main\n   * registry must be bound to `ctx` via {@link @nhtio/adk!ToolRegistry.bindContext}:\n   *\n   * ```ts\n   * const executor: DispatchExecutorFn = async (ctx) => {\n   *   const forged = SpooledArtifact.forgeTools(ctx)\n   *   const merged = ToolRegistry.merge([main, forged])\n   *   main.bindContext(ctx)\n   *   const result = await llm.invoke({ tools: merged.all(), ... })\n   *   ctx.ack() // ← ephemeral cleanup fires here\n   * }\n   * ```\n   *\n   * @warning You **must** call `registry.bindContext(ctx)` on the registry hosting these tools,\n   * or ephemeral cleanup will not run and the `callId` enum in subsequent executor calls will\n   * be stale (excluding new tool calls produced in the meantime).\n   *\n   * @param ctx - The execution context whose `turnToolCalls` snapshot defines the `callId` enum.\n   * @returns A fresh `ToolRegistry`. Empty when `turnToolCalls` contains no compatible artifacts.\n   *\n   * @see {@link @nhtio/adk!ToolRegistry.bindContext}\n   * @see {@link @nhtio/adk!ToolRegistry.merge}\n   * @see {@link @nhtio/adk!DispatchContext.onAck}\n   */\n  public static forgeTools(ctx: DispatchContext): ToolRegistry {\n    const requires: SpooledArtifactConstructor = SpooledArtifact\n    const calls = [...ctx.turnToolCalls]\n    const compatibleIds = calls\n      .filter((tc) => !tc.fromArtifactTool && isInstanceOf(tc.results, requires.name, requires))\n      .map((tc) => tc.id)\n    if (compatibleIds.length === 0) return new ToolRegistry([])\n\n    const tools: ArtifactTool[] = []\n    for (const descriptor of this.toolMethods) {\n      const callIdSchema = validator\n        .string()\n        .valid(...compatibleIds)\n        .required()\n        .description('ToolCall id of the artifact to query.')\n\n      const argsSchema = (descriptor.argsSchema ?? noArgsSchema).append({\n        callId: callIdSchema,\n      })\n\n      const serialise = descriptor.serialise ?? defaultSerialise\n\n      const tool = new ArtifactTool({\n        name: descriptor.name,\n        description: descriptor.description,\n        inputSchema: argsSchema,\n        ephemeral: true,\n        onCollision: 'replace',\n        handler: async (rawArgs, ctxInner) => {\n          const args = rawArgs as Record<string, unknown> & { callId: string }\n          const tc = [...ctxInner.turnToolCalls].find((t) => t.id === args.callId)\n          if (!tc) {\n            return `Error: no tool call with id ${args.callId} in this turn`\n          }\n          const artifact = tc.results\n          if (!isInstanceOf(artifact, requires.name, requires)) {\n            return `Error: tool call ${args.callId} results are not a ${requires.name} instance`\n          }\n          const methodArgs: unknown[] = []\n          if (descriptor.method === 'grep') {\n            const pattern = args.pattern as string\n            const flags = (args.flags as string | undefined) ?? ''\n            methodArgs.push(new RegExp(pattern, flags))\n          } else if (descriptor.method === 'head' || descriptor.method === 'tail') {\n            methodArgs.push((args.n as number | undefined) ?? 10)\n          } else if (descriptor.method === 'cat') {\n            methodArgs.push(args.start as number | undefined, args.end as number | undefined)\n          } else if (descriptor.method === 'estimateTokens') {\n            methodArgs.push(args.encoding as TokenEncoding)\n          }\n          const fn = (artifact as unknown as Record<string, (...a: unknown[]) => unknown>)[\n            descriptor.method\n          ]\n          if (typeof fn !== 'function') {\n            return `Error: artifact has no method ${descriptor.method}`\n          }\n          const result = await Promise.resolve(fn.apply(artifact, methodArgs))\n          return serialise(result)\n        },\n      })\n      tools.push(tool)\n    }\n    return new ToolRegistry(tools)\n  }\n}\n"],"mappings":"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"}

package/{spooled_artifact-BTq6Nzfy.js → spooled_artifact-DX8LLyUX.js}

@@ -1,8 +1,8 @@
 require("./chunk-Ble4zEEl.js");
-const require_exceptions = require("./exceptions-CitH5wZI.js");
-const require_tool_registry = require("./tool_registry-DYUYqXvo.js");
-const require_runtime = require("./runtime-MFFcJrRv.js");
-const require_tool = require("./tool-CVyZkFC7.js");
+const require_exceptions = require("./exceptions-BRXrUKiW.js");
+const require_tool_registry = require("./tool_registry-CKJPze3j.js");
+const require_runtime = require("./runtime-DslE1aBw.js");
+const require_tool = require("./tool-D5WGVIcI.js");
 let _nhtio_validation = require("@nhtio/validation");
 //#region src/lib/classes/artifact_tool.ts
 /**
@@ -565,4 +565,4 @@ Object.defineProperty(exports, "implementsSpoolReader", {
 	}
 });
 
-//# sourceMappingURL=spooled_artifact-BTq6Nzfy.js.map
+//# sourceMappingURL=spooled_artifact-DX8LLyUX.js.map