@nhtio/adk 1.20260609.0 → 1.20260609.1

package/CHANGELOG.md

@@ -71,13 +71,55 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **Scrapper web-extraction tool battery (`@nhtio/adk/batteries/tools/scrapper`).** Tools for any
+  [Scrapper](https://github.com/amerkurev/scrapper) instance — a headless-browser service that gives
+  an agent browser-grade page reading (JS-rendered pages a plain fetch can't see) as a **stateless**
+  HTTP call: fresh incognito context per request, no stored session/cookies/credentials. Two verbs,
+  each with an async factory (accepts a dynamic-import `artifact` resolver) and a sync variant:
+  `createScrapperArticleTool`/`…Sync` (`/api/article`) and `createScrapperLinksTool`/`…Sync`
+  (`/api/links`). Like the SearXNG battery these are factories (not constants) and must not be
+  bulk-registered via `Object.values(batteries)`.
+  - **Per-parameter disposition** — for every modeled knob the factory chooses: `fixed` (pinned;
+    sent always, removed from the model schema), `defaults` (model-overridable), or open
+    (model-settable). `url` is always required; `fixedQuery` is a raw kebab passthrough for
+    un-modeled params, keeping the battery generic across instances/versions.
+  - **Two distinct header channels** — `config.headers` (static or sync/async resolver) authenticates
+    to the Scrapper *instance*; the `extra_http_headers` *param* (`'K:v;K2:v2'`) is what the scraper's
+    browser sends to the *target site*.
+  - Same SearXNG-style two-level output (`resultFormat` normalized/raw/either), `artifact` resolver,
+    and input/output middleware pipelines (`shortCircuit`, fresh runner per call). Errors degrade to
+    `Error:` strings (parses Scrapper's `{detail:[{msg}]}`; missing `url` → HTTP 422); bad config →
+    `E_INVALID_SCRAPPER_CONFIG`. Documented as a featured-battery page with TSDoc `@warning`s for the
+    `scroll_down`-needs-`sleep` and instance-relative-URI gotchas. Cross-env unit spec (stubbed
+    `fetch`, disposition, resolver, all-three-artifact round-trips) + env-gated live integration spec
+    (`TEST_SCRAPPER_URL` / `TEST_SCRAPPER_HEADERS`).
+
+- **Web-retrieval RAG glue (`@nhtio/adk/batteries/tools/web_retrieval`).** The shared seam from
+  search/scrape results to turn `Retrievable`s, used by both the Scrapper and SearXNG batteries.
+  Pure converters — `searxngResultsToRetrievables`, `scrapperArticleToRetrievable`,
+  `scrapperLinksToRetrievables` — return plain `RawRetrievable[]` (zero core-class instantiation;
+  core referenced as `import type` only). `storeRetrievables(ctx, raws, { retrievable })` constructs
+  and stores records via a **resolver-injected** `Retrievable` constructor (ctor / sync / async /
+  dynamic-import), so the module never value-imports core. Long page text becomes a reader-backed
+  `SpooledArtifact` via a caller `spool` hook (the converter recommends an open
+  `ArtifactConstructorResolver` for the content — markdown/json/text — so a consumer's own subclass
+  works unchanged; no chunker). Web content defaults to `trustTier: 'third-party-public'` (a
+  constant, not URL inference — CONTRIBUTING DD#12).
+
+- **Shared tool-battery helpers (`@nhtio/adk/batteries/tools/_shared`).** Internal building blocks
+  for the configured-HTTP tool batteries: `resolveArtifact`/`resolveArtifactSync` (resolver → sync
+  `() => Ctor`), the onion middleware-pipeline runners (fresh runner per call, short-circuit +
+  non-terminal detection), header resolution, and the `ArtifactResolver`/`SyncArtifactResolver`
+  types. SearXNG and Scrapper both build on it instead of carrying copies.
+
 - **SearXNG search tool battery (`@nhtio/adk/batteries/tools/searxng`).** A web-search tool for any
-  [SearXNG](https://docs.searxng.org/dev/search_api.html) instance, exposed via a **factory** —
-  `createSearxngSearchTool(config)` — rather than a ready-made constant. It is the first
-  factory-style tool battery: a search tool has to know *which* instance to query and is usually
-  behind custom authentication, so it needs per-deployment config that cannot be baked in at module
-  load. Because it exports a factory (not a `Tool`), it must not be bulk-registered via
-  `Object.values(batteries)` — call the factory first, then register the returned tool.
+  [SearXNG](https://docs.searxng.org/dev/search_api.html) instance, exposed via **factories** —
+  async `createSearxngSearchTool(config)` and sync `createSearxngSearchToolSync(config)` — rather
+  than a ready-made constant. It is the first factory-style tool battery: a search tool has to know
+  *which* instance to query and is usually behind custom authentication, so it needs per-deployment
+  config that cannot be baked in at module load. Because it exports factories (not a `Tool`), they
+  must not be bulk-registered via `Object.values(batteries)` — call a factory first, then register
+  the returned tool.
   - **Custom-header auth** — `config.headers` accepts a static `Record<string,string>` or a
     sync/async resolver (`() => headers | Promise<headers>`); the resolver runs on every search, so
     refreshable bearer tokens work. Caller headers override the default `Accept`/`User-Agent`.
@@ -92,9 +134,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     hit); output stages filter/re-rank `ctx.results`, mutate `ctx.raw`, or set `ctx.output` verbatim
     (e.g. rendered markdown). A `ctx.stash` Map carries across both; a fresh runner is minted per
     invocation (middleware runners are single-use).
-  - **Configurable spool artifact** — `config.artifactConstructor` (default `() => SpooledJsonArtifact`)
-    is passed straight through to the `Tool`; set `() => SpooledMarkdownArtifact` or
-    `() => SpooledArtifact` to match a custom `outputPipeline` render.
+  - **Configurable spool artifact (resolver)** — `config.artifact` (default `() => SpooledJsonArtifact`)
+    is an open `ArtifactConstructorResolver`: a ctor, a sync resolver, or — via the async factory —
+    an async/dynamic-import resolver (`() => import('@nhtio/adk/spooled_artifact').then(m => m.SpooledMarkdownArtifact)`),
+    so a consumer's own `SpooledArtifact` subclass works with no battery change. The async factory
+    resolves it before building the `Tool` (whose `artifactConstructor` must be sync); the sync
+    factory accepts only the sync subset.
   - **Graceful failures** — a disabled-JSON instance (SearXNG disables JSON by default → HTTP 403),
     network errors, timeouts, and thrown pipeline stages all return `Error:` strings the model can
     react to; only malformed args throw (`E_INVALID_TOOL_ARGS`). Invalid config throws the

package/batteries/tools/_shared/index.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Cross-battery helpers shared by the configured HTTP tool batteries (SearXNG, Scrapper, …).
+ *
+ * @module @nhtio/adk/batteries/tools/_shared
+ *
+ * @remarks
+ * These are internal building blocks for the *factory-style* tool batteries — the ones that talk
+ * to a configured HTTP instance behind custom auth and expose input/output middleware pipelines.
+ * Rather than each battery carry its own copy, the common machinery lives here:
+ *
+ * - {@link resolveArtifact} / {@link resolveArtifactSync} — turn an {@link ArtifactResolver}
+ *   (a constructor, a sync resolver, or an async / dynamic-import resolver) into the **sync**
+ *   `() => SpooledArtifactConstructor` that `Tool.artifactConstructor` requires. Mirrors the vector
+ *   battery's `resolveClientCtor`.
+ * - {@link resolveHeaders} — collapse a static header object or a (sync/async) resolver into a
+ *   plain header record for one request (refreshable-auth friendly).
+ * - {@link runInputPipeline} / {@link runOutputPipeline} — the onion middleware runners (fresh
+ *   runner per call, short-circuit + non-terminal detection), generic over the context type.
+ *
+ * This module imports harness primitives only through their specific subpath barrels
+ * (`@nhtio/adk/spooled_artifact`, `@nhtio/adk/forge`, `@nhtio/adk/guards`) per the batteries
+ * barrel-only rule.
+ */
+import { Middleware } from '@nhtio/middleware';
+import type { NextFn } from '@nhtio/middleware';
+import type { SpooledArtifactConstructor } from "../../../forge";
+/** A static set of request headers (used for custom instance authentication). */
+export type ToolHeaders = Record<string, string>;
+/**
+ * A resolver returning request headers, sync or async. Use this form when the auth token is
+ * refreshable — the resolver runs on every request, so a fresh token can be minted per call.
+ */
+export type ToolHeadersResolver = () => ToolHeaders | Promise<ToolHeaders>;
+/**
+ * Resolve the configured headers (a static object or a sync/async resolver) for a single request.
+ *
+ * @param headers - The static header record, the resolver, or `undefined`.
+ * @returns A fresh, owned copy of the resolved headers (`{}` when none supplied).
+ */
+export declare const resolveHeaders: (headers: ToolHeaders | ToolHeadersResolver | undefined) => Promise<ToolHeaders>;
+/** Convenience alias for the spooled-artifact constructor a tool wraps its output in. */
+export type SpooledArtifactCtor = SpooledArtifactConstructor;
+/**
+ * The artifact configuration accepted by a factory: a constructor, a sync resolver, or an async /
+ * dynamic-import resolver (which may yield a module namespace whose `default` is the constructor).
+ *
+ * @remarks
+ * Mirrors the vector battery's `client` resolver and `Tool.artifactConstructor`'s indirection. The
+ * async form lets a consumer `() => import('@nhtio/adk/spooled_artifact').then(m => m.SpooledMarkdownArtifact)`
+ * so the artifact class never enters their static module graph.
+ */
+export type ArtifactResolver = SpooledArtifactCtor | (() => SpooledArtifactCtor | {
+    default: SpooledArtifactCtor;
+}) | (() => Promise<SpooledArtifactCtor | {
+    default: SpooledArtifactCtor;
+}>);
+/** The sync subset of {@link ArtifactResolver} — a constructor or a sync resolver (no Promise). */
+export type SyncArtifactResolver = SpooledArtifactCtor | (() => SpooledArtifactCtor | {
+    default: SpooledArtifactCtor;
+});
+/**
+ * Resolve an {@link ArtifactResolver} to the **sync** `() => SpooledArtifactCtor` that
+ * `Tool.artifactConstructor` requires (the wrap-site and the construction-time validator both
+ * invoke it synchronously, so an async resolver cannot be passed straight through).
+ *
+ * @remarks
+ * A bare constructor is itself a function, so it is distinguished from a resolver via
+ * `SpooledArtifact.isSpooledArtifactConstructor` (the same duck-typed guard the core validator
+ * uses) rather than by arity. Async because a dynamic-import resolver must be awaited here.
+ *
+ * @param resolver - The artifact configuration. When `undefined`, callers should fall back to
+ *   their own default (this function rejects `undefined` so the default lives with the caller).
+ * @param onInvalid - Throws a battery-scoped error; receives a human-readable reason.
+ * @returns A sync `() => SpooledArtifactCtor` suitable for `Tool.artifactConstructor`.
+ */
+export declare const resolveArtifact: (resolver: ArtifactResolver, onInvalid: (reason: string) => never) => Promise<() => SpooledArtifactCtor>;
+/**
+ * Synchronous {@link resolveArtifact}: accepts only the {@link SyncArtifactResolver} subset and
+ * throws (via `onInvalid`) on an async resolver — a runtime guard for JS callers who bypass the
+ * compile-time narrowing.
+ *
+ * @param resolver - A constructor or a sync resolver.
+ * @param onInvalid - Throws a battery-scoped error; receives a human-readable reason.
+ * @returns A sync `() => SpooledArtifactCtor` suitable for `Tool.artifactConstructor`.
+ */
+export declare const resolveArtifactSync: (resolver: SyncArtifactResolver, onInvalid: (reason: string) => never) => (() => SpooledArtifactCtor);
+/** `true` when `value` is the short-circuit sentinel produced by {@link makeShortCircuit}. */
+export declare const isShortCircuit: (value: unknown) => value is {
+    result: string;
+};
+/**
+ * Build a `shortCircuit(result)` function for an input-pipeline context. Calling it throws the
+ * internal sentinel, which {@link runInputPipeline} catches and converts into the verbatim result
+ * (skipping the HTTP request entirely — e.g. a cache hit).
+ *
+ * @returns A function that, when called with a result string, throws the short-circuit sentinel.
+ */
+export declare const makeShortCircuit: () => ((result: string) => never);
+/** A generic onion middleware stage over a mutable context `C`. */
+export type MiddlewareFn<C> = (ctx: C, next: NextFn) => void | Promise<void>;
+/**
+ * Run an input pipeline over `ctx`. 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) throws — the caller converts it to an
+ * `Error:` string.
+ *
+ * @param mw - The `Middleware` instance holding the stages (a fresh `.runner()` is minted here).
+ * @param ctx - The mutable input context handed to each stage.
+ * @param label - Battery name, used in the non-terminal error message.
+ * @returns The short-circuit result string, or `undefined` if the pipeline ran to completion.
+ */
+export declare const runInputPipeline: <C>(mw: Middleware<MiddlewareFn<C>>, ctx: C, label: string) => Promise<string | undefined>;
+/**
+ * Run an output pipeline over `ctx`; rethrow any stage error to the caller's try/catch. A
+ * non-terminal pipeline (no `next()`) throws.
+ *
+ * @param mw - The `Middleware` instance holding the stages (a fresh `.runner()` is minted here).
+ * @param ctx - The mutable output context handed to each stage.
+ * @param label - Battery name, used in the non-terminal error message.
+ */
+export declare const runOutputPipeline: <C>(mw: Middleware<MiddlewareFn<C>>, ctx: C, label: string) => Promise<void>;

package/batteries/tools/_shared.cjs

@@ -0,0 +1,157 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+require("../../chunk-Ble4zEEl.js");
+const require_tool_registry = require("../../tool_registry-CKJPze3j.js");
+const require_spooled_artifact = require("../../spooled_artifact-DX8LLyUX.js");
+require("../../guards.cjs");
+require("../../spooled_artifact.cjs");
+//#region src/batteries/tools/_shared/index.ts
+/**
+* Resolve the configured headers (a static object or a sync/async resolver) for a single request.
+*
+* @param headers - The static header record, the resolver, or `undefined`.
+* @returns A fresh, owned copy of the resolved headers (`{}` when none supplied).
+*/
+var resolveHeaders = async (headers) => {
+	if (typeof headers === "function") return { ...await headers() };
+	return { ...headers ?? {} };
+};
+/** Unwrap a resolved value that may be a module namespace whose `default` is the constructor. */
+var unwrapDefault = (value) => {
+	if (require_tool_registry.isObject(value) && "default" in value) {
+		const def = value.default;
+		if (require_spooled_artifact.SpooledArtifact.isSpooledArtifactConstructor(def)) return def;
+	}
+	return value;
+};
+/**
+* Resolve an {@link ArtifactResolver} to the **sync** `() => SpooledArtifactCtor` that
+* `Tool.artifactConstructor` requires (the wrap-site and the construction-time validator both
+* invoke it synchronously, so an async resolver cannot be passed straight through).
+*
+* @remarks
+* A bare constructor is itself a function, so it is distinguished from a resolver via
+* `SpooledArtifact.isSpooledArtifactConstructor` (the same duck-typed guard the core validator
+* uses) rather than by arity. Async because a dynamic-import resolver must be awaited here.
+*
+* @param resolver - The artifact configuration. When `undefined`, callers should fall back to
+*   their own default (this function rejects `undefined` so the default lives with the caller).
+* @param onInvalid - Throws a battery-scoped error; receives a human-readable reason.
+* @returns A sync `() => SpooledArtifactCtor` suitable for `Tool.artifactConstructor`.
+*/
+var resolveArtifact = async (resolver, onInvalid) => {
+	if (require_spooled_artifact.SpooledArtifact.isSpooledArtifactConstructor(resolver)) {
+		const ctor = resolver;
+		return () => ctor;
+	}
+	if (typeof resolver !== "function") onInvalid("artifact must be a SpooledArtifact constructor or a resolver returning one");
+	let resolved;
+	try {
+		resolved = await resolver();
+	} catch (err) {
+		onInvalid(`artifact resolver threw: ${require_tool_registry.isError(err) ? err.message : String(err)}`);
+	}
+	resolved = unwrapDefault(resolved);
+	if (!require_spooled_artifact.SpooledArtifact.isSpooledArtifactConstructor(resolved)) onInvalid("artifact resolver did not resolve to a SpooledArtifact constructor");
+	const ctor = resolved;
+	return () => ctor;
+};
+/**
+* Synchronous {@link resolveArtifact}: accepts only the {@link SyncArtifactResolver} subset and
+* throws (via `onInvalid`) on an async resolver — a runtime guard for JS callers who bypass the
+* compile-time narrowing.
+*
+* @param resolver - A constructor or a sync resolver.
+* @param onInvalid - Throws a battery-scoped error; receives a human-readable reason.
+* @returns A sync `() => SpooledArtifactCtor` suitable for `Tool.artifactConstructor`.
+*/
+var resolveArtifactSync = (resolver, onInvalid) => {
+	if (require_spooled_artifact.SpooledArtifact.isSpooledArtifactConstructor(resolver)) {
+		const ctor = resolver;
+		return () => ctor;
+	}
+	if (typeof resolver !== "function") onInvalid("artifact must be a SpooledArtifact constructor or a resolver returning one");
+	let resolved;
+	try {
+		resolved = resolver();
+	} catch (err) {
+		onInvalid(`artifact resolver threw: ${require_tool_registry.isError(err) ? err.message : String(err)}`);
+	}
+	if (require_tool_registry.isInstanceOf(resolved, "Promise", Promise)) onInvalid("artifact resolver is async; use the async factory variant for dynamic-import resolvers");
+	resolved = unwrapDefault(resolved);
+	if (!require_spooled_artifact.SpooledArtifact.isSpooledArtifactConstructor(resolved)) onInvalid("artifact resolver did not resolve to a SpooledArtifact constructor");
+	const ctor = resolved;
+	return () => ctor;
+};
+/** Internal sentinel a short-circuiting input stage throws to unwind the pipeline immediately. */
+var SHORT_CIRCUIT = Symbol("adk.tools.shortCircuit");
+/** `true` when `value` is the short-circuit sentinel produced by {@link makeShortCircuit}. */
+var isShortCircuit = (value) => require_tool_registry.isObject(value) && value[SHORT_CIRCUIT] === true;
+/**
+* Build a `shortCircuit(result)` function for an input-pipeline context. Calling it throws the
+* internal sentinel, which {@link runInputPipeline} catches and converts into the verbatim result
+* (skipping the HTTP request entirely — e.g. a cache hit).
+*
+* @returns A function that, when called with a result string, throws the short-circuit sentinel.
+*/
+var makeShortCircuit = () => {
+	return (result) => {
+		throw {
+			[SHORT_CIRCUIT]: true,
+			result
+		};
+	};
+};
+/**
+* Run an input pipeline over `ctx`. 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) throws — the caller converts it to an
+* `Error:` string.
+*
+* @param mw - The `Middleware` instance holding the stages (a fresh `.runner()` is minted here).
+* @param ctx - The mutable input context handed to each stage.
+* @param label - Battery name, used in the non-terminal error message.
+* @returns The short-circuit result string, or `undefined` if the pipeline ran to completion.
+*/
+var runInputPipeline = async (mw, ctx, label) => {
+	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) {
+		if (isShortCircuit(caught)) return caught.result;
+		throw caught;
+	}
+	if (!reached) throw new Error(`${label} input pipeline did not call next() and did not short-circuit.`);
+};
+/**
+* Run an output pipeline over `ctx`; rethrow any stage error to the caller's try/catch. A
+* non-terminal pipeline (no `next()`) throws.
+*
+* @param mw - The `Middleware` instance holding the stages (a fresh `.runner()` is minted here).
+* @param ctx - The mutable output context handed to each stage.
+* @param label - Battery name, used in the non-terminal error message.
+*/
+var runOutputPipeline = async (mw, ctx, label) => {
+	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(`${label} output pipeline did not call next().`);
+};
+//#endregion
+exports.isShortCircuit = isShortCircuit;
+exports.makeShortCircuit = makeShortCircuit;
+exports.resolveArtifact = resolveArtifact;
+exports.resolveArtifactSync = resolveArtifactSync;
+exports.resolveHeaders = resolveHeaders;
+exports.runInputPipeline = runInputPipeline;
+exports.runOutputPipeline = runOutputPipeline;
+
+//# sourceMappingURL=_shared.cjs.map

package/batteries/tools/_shared.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"_shared.cjs","names":[],"sources":["../../../src/batteries/tools/_shared/index.ts"],"sourcesContent":["/**\n * Cross-battery helpers shared by the configured HTTP tool batteries (SearXNG, Scrapper, …).\n *\n * @module @nhtio/adk/batteries/tools/_shared\n *\n * @remarks\n * These are internal building blocks for the *factory-style* tool batteries — the ones that talk\n * to a configured HTTP instance behind custom auth and expose input/output middleware pipelines.\n * Rather than each battery carry its own copy, the common machinery lives here:\n *\n * - {@link resolveArtifact} / {@link resolveArtifactSync} — turn an {@link ArtifactResolver}\n *   (a constructor, a sync resolver, or an async / dynamic-import resolver) into the **sync**\n *   `() => SpooledArtifactConstructor` that `Tool.artifactConstructor` requires. Mirrors the vector\n *   battery's `resolveClientCtor`.\n * - {@link resolveHeaders} — collapse a static header object or a (sync/async) resolver into a\n *   plain header record for one request (refreshable-auth friendly).\n * - {@link runInputPipeline} / {@link runOutputPipeline} — the onion middleware runners (fresh\n *   runner per call, short-circuit + non-terminal detection), generic over the context type.\n *\n * This module imports harness primitives only through their specific subpath barrels\n * (`@nhtio/adk/spooled_artifact`, `@nhtio/adk/forge`, `@nhtio/adk/guards`) per the batteries\n * barrel-only rule.\n */\n\nimport { Middleware } from '@nhtio/middleware'\nimport { SpooledArtifact } from '@nhtio/adk/spooled_artifact'\nimport { isError, isObject, isInstanceOf } from '@nhtio/adk/guards'\nimport type { NextFn } from '@nhtio/middleware'\nimport type { SpooledArtifactConstructor } from '@nhtio/adk/forge'\n\n// ── Header resolution ────────────────────────────────────────────────────────\n\n/** A static set of request headers (used for custom instance authentication). */\nexport type ToolHeaders = 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 request, so a fresh token can be minted per call.\n */\nexport type ToolHeadersResolver = () => ToolHeaders | Promise<ToolHeaders>\n\n/**\n * Resolve the configured headers (a static object or a sync/async resolver) for a single request.\n *\n * @param headers - The static header record, the resolver, or `undefined`.\n * @returns A fresh, owned copy of the resolved headers (`{}` when none supplied).\n */\nexport const resolveHeaders = async (\n  headers: ToolHeaders | ToolHeadersResolver | undefined\n): Promise<ToolHeaders> => {\n  if (typeof headers === 'function') return { ...(await headers()) }\n  return { ...(headers ?? {}) }\n}\n\n// ── Artifact resolver ────────────────────────────────────────────────────────\n\n/** Convenience alias for the spooled-artifact constructor a tool wraps its output in. */\nexport type SpooledArtifactCtor = SpooledArtifactConstructor\n\n/**\n * The artifact configuration accepted by a factory: a constructor, a sync resolver, or an async /\n * dynamic-import resolver (which may yield a module namespace whose `default` is the constructor).\n *\n * @remarks\n * Mirrors the vector battery's `client` resolver and `Tool.artifactConstructor`'s indirection. The\n * async form lets a consumer `() => import('@nhtio/adk/spooled_artifact').then(m => m.SpooledMarkdownArtifact)`\n * so the artifact class never enters their static module graph.\n */\nexport type ArtifactResolver =\n  | SpooledArtifactCtor\n  | (() => SpooledArtifactCtor | { default: SpooledArtifactCtor })\n  | (() => Promise<SpooledArtifactCtor | { default: SpooledArtifactCtor }>)\n\n/** The sync subset of {@link ArtifactResolver} — a constructor or a sync resolver (no Promise). */\nexport type SyncArtifactResolver =\n  | SpooledArtifactCtor\n  | (() => SpooledArtifactCtor | { default: SpooledArtifactCtor })\n\n/** Unwrap a resolved value that may be a module namespace whose `default` is the constructor. */\nconst unwrapDefault = (value: unknown): unknown => {\n  if (isObject(value) && 'default' in value) {\n    const def = (value as { default?: unknown }).default\n    if (SpooledArtifact.isSpooledArtifactConstructor(def)) return def\n  }\n  return value\n}\n\n/**\n * Resolve an {@link ArtifactResolver} to the **sync** `() => SpooledArtifactCtor` that\n * `Tool.artifactConstructor` requires (the wrap-site and the construction-time validator both\n * invoke it synchronously, so an async resolver cannot be passed straight through).\n *\n * @remarks\n * A bare constructor is itself a function, so it is distinguished from a resolver via\n * `SpooledArtifact.isSpooledArtifactConstructor` (the same duck-typed guard the core validator\n * uses) rather than by arity. Async because a dynamic-import resolver must be awaited here.\n *\n * @param resolver - The artifact configuration. When `undefined`, callers should fall back to\n *   their own default (this function rejects `undefined` so the default lives with the caller).\n * @param onInvalid - Throws a battery-scoped error; receives a human-readable reason.\n * @returns A sync `() => SpooledArtifactCtor` suitable for `Tool.artifactConstructor`.\n */\nexport const resolveArtifact = async (\n  resolver: ArtifactResolver,\n  onInvalid: (reason: string) => never\n): Promise<() => SpooledArtifactCtor> => {\n  // A constructor: hand back a thunk that returns it.\n  if (SpooledArtifact.isSpooledArtifactConstructor(resolver)) {\n    const ctor = resolver\n    return () => ctor\n  }\n  // Otherwise it must be a resolver function.\n  if (typeof resolver !== 'function') {\n    onInvalid('artifact must be a SpooledArtifact constructor or a resolver returning one')\n  }\n  let resolved: unknown\n  try {\n    resolved = await (resolver as () => unknown)()\n  } catch (err) {\n    onInvalid(`artifact resolver threw: ${isError(err) ? err.message : String(err)}`)\n  }\n  resolved = unwrapDefault(resolved)\n  if (!SpooledArtifact.isSpooledArtifactConstructor(resolved)) {\n    onInvalid('artifact resolver did not resolve to a SpooledArtifact constructor')\n  }\n  const ctor = resolved as SpooledArtifactCtor\n  return () => ctor\n}\n\n/**\n * Synchronous {@link resolveArtifact}: accepts only the {@link SyncArtifactResolver} subset and\n * throws (via `onInvalid`) on an async resolver — a runtime guard for JS callers who bypass the\n * compile-time narrowing.\n *\n * @param resolver - A constructor or a sync resolver.\n * @param onInvalid - Throws a battery-scoped error; receives a human-readable reason.\n * @returns A sync `() => SpooledArtifactCtor` suitable for `Tool.artifactConstructor`.\n */\nexport const resolveArtifactSync = (\n  resolver: SyncArtifactResolver,\n  onInvalid: (reason: string) => never\n): (() => SpooledArtifactCtor) => {\n  if (SpooledArtifact.isSpooledArtifactConstructor(resolver)) {\n    const ctor = resolver\n    return () => ctor\n  }\n  if (typeof resolver !== 'function') {\n    onInvalid('artifact must be a SpooledArtifact constructor or a resolver returning one')\n  }\n  let resolved: unknown\n  try {\n    resolved = (resolver as () => unknown)()\n  } catch (err) {\n    onInvalid(`artifact resolver threw: ${isError(err) ? err.message : String(err)}`)\n  }\n  if (isInstanceOf(resolved, 'Promise', Promise)) {\n    onInvalid(\n      'artifact resolver is async; use the async factory variant for dynamic-import resolvers'\n    )\n  }\n  resolved = unwrapDefault(resolved)\n  if (!SpooledArtifact.isSpooledArtifactConstructor(resolved)) {\n    onInvalid('artifact resolver did not resolve to a SpooledArtifact constructor')\n  }\n  const ctor = resolved as SpooledArtifactCtor\n  return () => ctor\n}\n\n// ── Middleware pipeline runners ──────────────────────────────────────────────\n\n/** Internal sentinel a short-circuiting input stage throws to unwind the pipeline immediately. */\nconst SHORT_CIRCUIT = Symbol('adk.tools.shortCircuit')\n\ninterface ShortCircuitSignal {\n  [SHORT_CIRCUIT]: true\n  result: string\n}\n\n/** `true` when `value` is the short-circuit sentinel produced by {@link makeShortCircuit}. */\nexport const isShortCircuit = (value: unknown): value is { result: string } =>\n  isObject(value) && (value as Record<symbol, unknown>)[SHORT_CIRCUIT] === true\n\n/**\n * Build a `shortCircuit(result)` function for an input-pipeline context. Calling it throws the\n * internal sentinel, which {@link runInputPipeline} catches and converts into the verbatim result\n * (skipping the HTTP request entirely — e.g. a cache hit).\n *\n * @returns A function that, when called with a result string, throws the short-circuit sentinel.\n */\nexport const makeShortCircuit = (): ((result: string) => never) => {\n  return (result: string): never => {\n    const signal: ShortCircuitSignal = { [SHORT_CIRCUIT]: true, result }\n    throw signal\n  }\n}\n\n/** A generic onion middleware stage over a mutable context `C`. */\nexport type MiddlewareFn<C> = (ctx: C, next: NextFn) => void | Promise<void>\n\n/**\n * Run an input pipeline over `ctx`. Returns the short-circuit string when a stage short-circuited,\n * or `undefined` when the pipeline reached its terminal handler. A non-terminal pipeline (a stage\n * that neither called `next()` nor short-circuited) throws — the caller converts it to an\n * `Error:` string.\n *\n * @param mw - The `Middleware` instance holding the stages (a fresh `.runner()` is minted here).\n * @param ctx - The mutable input context handed to each stage.\n * @param label - Battery name, used in the non-terminal error message.\n * @returns The short-circuit result string, or `undefined` if the pipeline ran to completion.\n */\nexport const runInputPipeline = async <C>(\n  mw: Middleware<MiddlewareFn<C>>,\n  ctx: C,\n  label: string\n): Promise<string | undefined> => {\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) {\n    if (isShortCircuit(caught)) return caught.result\n    throw caught\n  }\n  if (!reached) {\n    throw new Error(`${label} input pipeline did not call next() and did not short-circuit.`)\n  }\n  return undefined\n}\n\n/**\n * Run an output pipeline over `ctx`; rethrow any stage error to the caller's try/catch. A\n * non-terminal pipeline (no `next()`) throws.\n *\n * @param mw - The `Middleware` instance holding the stages (a fresh `.runner()` is minted here).\n * @param ctx - The mutable output context handed to each stage.\n * @param label - Battery name, used in the non-terminal error message.\n */\nexport const runOutputPipeline = async <C>(\n  mw: Middleware<MiddlewareFn<C>>,\n  ctx: C,\n  label: string\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) throw new Error(`${label} output pipeline did not call next().`)\n}\n"],"mappings":";;;;;;;;;;;;;AA+CA,IAAa,iBAAiB,OAC5B,YACyB;CACzB,IAAI,OAAO,YAAY,YAAY,OAAO,EAAE,GAAI,MAAM,QAAQ,EAAG;CACjE,OAAO,EAAE,GAAI,WAAW,CAAC,EAAG;AAC9B;;AA2BA,IAAM,iBAAiB,UAA4B;CACjD,IAAI,sBAAA,SAAS,KAAK,KAAK,aAAa,OAAO;EACzC,MAAM,MAAO,MAAgC;EAC7C,IAAI,yBAAA,gBAAgB,6BAA6B,GAAG,GAAG,OAAO;CAChE;CACA,OAAO;AACT;;;;;;;;;;;;;;;;AAiBA,IAAa,kBAAkB,OAC7B,UACA,cACuC;CAEvC,IAAI,yBAAA,gBAAgB,6BAA6B,QAAQ,GAAG;EAC1D,MAAM,OAAO;EACb,aAAa;CACf;CAEA,IAAI,OAAO,aAAa,YACtB,UAAU,4EAA4E;CAExF,IAAI;CACJ,IAAI;EACF,WAAW,MAAO,SAA2B;CAC/C,SAAS,KAAK;EACZ,UAAU,4BAA4B,sBAAA,QAAQ,GAAG,IAAI,IAAI,UAAU,OAAO,GAAG,GAAG;CAClF;CACA,WAAW,cAAc,QAAQ;CACjC,IAAI,CAAC,yBAAA,gBAAgB,6BAA6B,QAAQ,GACxD,UAAU,oEAAoE;CAEhF,MAAM,OAAO;CACb,aAAa;AACf;;;;;;;;;;AAWA,IAAa,uBACX,UACA,cACgC;CAChC,IAAI,yBAAA,gBAAgB,6BAA6B,QAAQ,GAAG;EAC1D,MAAM,OAAO;EACb,aAAa;CACf;CACA,IAAI,OAAO,aAAa,YACtB,UAAU,4EAA4E;CAExF,IAAI;CACJ,IAAI;EACF,WAAY,SAA2B;CACzC,SAAS,KAAK;EACZ,UAAU,4BAA4B,sBAAA,QAAQ,GAAG,IAAI,IAAI,UAAU,OAAO,GAAG,GAAG;CAClF;CACA,IAAI,sBAAA,aAAa,UAAU,WAAW,OAAO,GAC3C,UACE,wFACF;CAEF,WAAW,cAAc,QAAQ;CACjC,IAAI,CAAC,yBAAA,gBAAgB,6BAA6B,QAAQ,GACxD,UAAU,oEAAoE;CAEhF,MAAM,OAAO;CACb,aAAa;AACf;;AAKA,IAAM,gBAAgB,OAAO,wBAAwB;;AAQrD,IAAa,kBAAkB,UAC7B,sBAAA,SAAS,KAAK,KAAM,MAAkC,mBAAmB;;;;;;;;AAS3E,IAAa,yBAAsD;CACjE,QAAQ,WAA0B;EAEhC,MAAM;IADgC,gBAAgB;GAAM;EACtD;CACR;AACF;;;;;;;;;;;;AAgBA,IAAa,mBAAmB,OAC9B,IACA,KACA,UACgC;CAChC,IAAI,UAAU;CACd,IAAI;CACJ,MAAM,GACH,OAAO,EACP,aAAa,OAAO,UAAmB;EACtC,SAAS;CACX,CAAC,EACA,aAAa,YAAY;EACxB,UAAU;CACZ,CAAC,EACA,KAAK,IAAI,SAAS,QAAQ,QAAQ,GAAG,KAAK,IAAI,CAAC,CAAC;CAEnD,IAAI,WAAW,KAAA,GAAW;EACxB,IAAI,eAAe,MAAM,GAAG,OAAO,OAAO;EAC1C,MAAM;CACR;CACA,IAAI,CAAC,SACH,MAAM,IAAI,MAAM,GAAG,MAAM,+DAA+D;AAG5F;;;;;;;;;AAUA,IAAa,oBAAoB,OAC/B,IACA,KACA,UACkB;CAClB,IAAI,UAAU;CACd,IAAI;CACJ,MAAM,GACH,OAAO,EACP,aAAa,OAAO,UAAmB;EACtC,SAAS;CACX,CAAC,EACA,aAAa,YAAY;EACxB,UAAU;CACZ,CAAC,EACA,KAAK,IAAI,SAAS,QAAQ,QAAQ,GAAG,KAAK,IAAI,CAAC,CAAC;CAEnD,IAAI,WAAW,KAAA,GAAW,MAAM;CAChC,IAAI,CAAC,SAAS,MAAM,IAAI,MAAM,GAAG,MAAM,sCAAsC;AAC/E"}

package/batteries/tools/_shared.mjs

@@ -0,0 +1,149 @@
+import { c as isObject, o as isError, s as isInstanceOf } from "../../tool_registry-791Vrjtf.mjs";
+import { t as SpooledArtifact } from "../../spooled_artifact-7eePq7JA.mjs";
+import "../../guards.mjs";
+import "../../spooled_artifact.mjs";
+//#region src/batteries/tools/_shared/index.ts
+/**
+* Resolve the configured headers (a static object or a sync/async resolver) for a single request.
+*
+* @param headers - The static header record, the resolver, or `undefined`.
+* @returns A fresh, owned copy of the resolved headers (`{}` when none supplied).
+*/
+var resolveHeaders = async (headers) => {
+	if (typeof headers === "function") return { ...await headers() };
+	return { ...headers ?? {} };
+};
+/** Unwrap a resolved value that may be a module namespace whose `default` is the constructor. */
+var unwrapDefault = (value) => {
+	if (isObject(value) && "default" in value) {
+		const def = value.default;
+		if (SpooledArtifact.isSpooledArtifactConstructor(def)) return def;
+	}
+	return value;
+};
+/**
+* Resolve an {@link ArtifactResolver} to the **sync** `() => SpooledArtifactCtor` that
+* `Tool.artifactConstructor` requires (the wrap-site and the construction-time validator both
+* invoke it synchronously, so an async resolver cannot be passed straight through).
+*
+* @remarks
+* A bare constructor is itself a function, so it is distinguished from a resolver via
+* `SpooledArtifact.isSpooledArtifactConstructor` (the same duck-typed guard the core validator
+* uses) rather than by arity. Async because a dynamic-import resolver must be awaited here.
+*
+* @param resolver - The artifact configuration. When `undefined`, callers should fall back to
+*   their own default (this function rejects `undefined` so the default lives with the caller).
+* @param onInvalid - Throws a battery-scoped error; receives a human-readable reason.
+* @returns A sync `() => SpooledArtifactCtor` suitable for `Tool.artifactConstructor`.
+*/
+var resolveArtifact = async (resolver, onInvalid) => {
+	if (SpooledArtifact.isSpooledArtifactConstructor(resolver)) {
+		const ctor = resolver;
+		return () => ctor;
+	}
+	if (typeof resolver !== "function") onInvalid("artifact must be a SpooledArtifact constructor or a resolver returning one");
+	let resolved;
+	try {
+		resolved = await resolver();
+	} catch (err) {
+		onInvalid(`artifact resolver threw: ${isError(err) ? err.message : String(err)}`);
+	}
+	resolved = unwrapDefault(resolved);
+	if (!SpooledArtifact.isSpooledArtifactConstructor(resolved)) onInvalid("artifact resolver did not resolve to a SpooledArtifact constructor");
+	const ctor = resolved;
+	return () => ctor;
+};
+/**
+* Synchronous {@link resolveArtifact}: accepts only the {@link SyncArtifactResolver} subset and
+* throws (via `onInvalid`) on an async resolver — a runtime guard for JS callers who bypass the
+* compile-time narrowing.
+*
+* @param resolver - A constructor or a sync resolver.
+* @param onInvalid - Throws a battery-scoped error; receives a human-readable reason.
+* @returns A sync `() => SpooledArtifactCtor` suitable for `Tool.artifactConstructor`.
+*/
+var resolveArtifactSync = (resolver, onInvalid) => {
+	if (SpooledArtifact.isSpooledArtifactConstructor(resolver)) {
+		const ctor = resolver;
+		return () => ctor;
+	}
+	if (typeof resolver !== "function") onInvalid("artifact must be a SpooledArtifact constructor or a resolver returning one");
+	let resolved;
+	try {
+		resolved = resolver();
+	} catch (err) {
+		onInvalid(`artifact resolver threw: ${isError(err) ? err.message : String(err)}`);
+	}
+	if (isInstanceOf(resolved, "Promise", Promise)) onInvalid("artifact resolver is async; use the async factory variant for dynamic-import resolvers");
+	resolved = unwrapDefault(resolved);
+	if (!SpooledArtifact.isSpooledArtifactConstructor(resolved)) onInvalid("artifact resolver did not resolve to a SpooledArtifact constructor");
+	const ctor = resolved;
+	return () => ctor;
+};
+/** Internal sentinel a short-circuiting input stage throws to unwind the pipeline immediately. */
+var SHORT_CIRCUIT = Symbol("adk.tools.shortCircuit");
+/** `true` when `value` is the short-circuit sentinel produced by {@link makeShortCircuit}. */
+var isShortCircuit = (value) => isObject(value) && value[SHORT_CIRCUIT] === true;
+/**
+* Build a `shortCircuit(result)` function for an input-pipeline context. Calling it throws the
+* internal sentinel, which {@link runInputPipeline} catches and converts into the verbatim result
+* (skipping the HTTP request entirely — e.g. a cache hit).
+*
+* @returns A function that, when called with a result string, throws the short-circuit sentinel.
+*/
+var makeShortCircuit = () => {
+	return (result) => {
+		throw {
+			[SHORT_CIRCUIT]: true,
+			result
+		};
+	};
+};
+/**
+* Run an input pipeline over `ctx`. 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) throws — the caller converts it to an
+* `Error:` string.
+*
+* @param mw - The `Middleware` instance holding the stages (a fresh `.runner()` is minted here).
+* @param ctx - The mutable input context handed to each stage.
+* @param label - Battery name, used in the non-terminal error message.
+* @returns The short-circuit result string, or `undefined` if the pipeline ran to completion.
+*/
+var runInputPipeline = async (mw, ctx, label) => {
+	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) {
+		if (isShortCircuit(caught)) return caught.result;
+		throw caught;
+	}
+	if (!reached) throw new Error(`${label} input pipeline did not call next() and did not short-circuit.`);
+};
+/**
+* Run an output pipeline over `ctx`; rethrow any stage error to the caller's try/catch. A
+* non-terminal pipeline (no `next()`) throws.
+*
+* @param mw - The `Middleware` instance holding the stages (a fresh `.runner()` is minted here).
+* @param ctx - The mutable output context handed to each stage.
+* @param label - Battery name, used in the non-terminal error message.
+*/
+var runOutputPipeline = async (mw, ctx, label) => {
+	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(`${label} output pipeline did not call next().`);
+};
+//#endregion
+export { isShortCircuit, makeShortCircuit, resolveArtifact, resolveArtifactSync, resolveHeaders, runInputPipeline, runOutputPipeline };
+
+//# sourceMappingURL=_shared.mjs.map

package/batteries/tools/_shared.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"_shared.mjs","names":[],"sources":["../../../src/batteries/tools/_shared/index.ts"],"sourcesContent":["/**\n * Cross-battery helpers shared by the configured HTTP tool batteries (SearXNG, Scrapper, …).\n *\n * @module @nhtio/adk/batteries/tools/_shared\n *\n * @remarks\n * These are internal building blocks for the *factory-style* tool batteries — the ones that talk\n * to a configured HTTP instance behind custom auth and expose input/output middleware pipelines.\n * Rather than each battery carry its own copy, the common machinery lives here:\n *\n * - {@link resolveArtifact} / {@link resolveArtifactSync} — turn an {@link ArtifactResolver}\n *   (a constructor, a sync resolver, or an async / dynamic-import resolver) into the **sync**\n *   `() => SpooledArtifactConstructor` that `Tool.artifactConstructor` requires. Mirrors the vector\n *   battery's `resolveClientCtor`.\n * - {@link resolveHeaders} — collapse a static header object or a (sync/async) resolver into a\n *   plain header record for one request (refreshable-auth friendly).\n * - {@link runInputPipeline} / {@link runOutputPipeline} — the onion middleware runners (fresh\n *   runner per call, short-circuit + non-terminal detection), generic over the context type.\n *\n * This module imports harness primitives only through their specific subpath barrels\n * (`@nhtio/adk/spooled_artifact`, `@nhtio/adk/forge`, `@nhtio/adk/guards`) per the batteries\n * barrel-only rule.\n */\n\nimport { Middleware } from '@nhtio/middleware'\nimport { SpooledArtifact } from '@nhtio/adk/spooled_artifact'\nimport { isError, isObject, isInstanceOf } from '@nhtio/adk/guards'\nimport type { NextFn } from '@nhtio/middleware'\nimport type { SpooledArtifactConstructor } from '@nhtio/adk/forge'\n\n// ── Header resolution ────────────────────────────────────────────────────────\n\n/** A static set of request headers (used for custom instance authentication). */\nexport type ToolHeaders = 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 request, so a fresh token can be minted per call.\n */\nexport type ToolHeadersResolver = () => ToolHeaders | Promise<ToolHeaders>\n\n/**\n * Resolve the configured headers (a static object or a sync/async resolver) for a single request.\n *\n * @param headers - The static header record, the resolver, or `undefined`.\n * @returns A fresh, owned copy of the resolved headers (`{}` when none supplied).\n */\nexport const resolveHeaders = async (\n  headers: ToolHeaders | ToolHeadersResolver | undefined\n): Promise<ToolHeaders> => {\n  if (typeof headers === 'function') return { ...(await headers()) }\n  return { ...(headers ?? {}) }\n}\n\n// ── Artifact resolver ────────────────────────────────────────────────────────\n\n/** Convenience alias for the spooled-artifact constructor a tool wraps its output in. */\nexport type SpooledArtifactCtor = SpooledArtifactConstructor\n\n/**\n * The artifact configuration accepted by a factory: a constructor, a sync resolver, or an async /\n * dynamic-import resolver (which may yield a module namespace whose `default` is the constructor).\n *\n * @remarks\n * Mirrors the vector battery's `client` resolver and `Tool.artifactConstructor`'s indirection. The\n * async form lets a consumer `() => import('@nhtio/adk/spooled_artifact').then(m => m.SpooledMarkdownArtifact)`\n * so the artifact class never enters their static module graph.\n */\nexport type ArtifactResolver =\n  | SpooledArtifactCtor\n  | (() => SpooledArtifactCtor | { default: SpooledArtifactCtor })\n  | (() => Promise<SpooledArtifactCtor | { default: SpooledArtifactCtor }>)\n\n/** The sync subset of {@link ArtifactResolver} — a constructor or a sync resolver (no Promise). */\nexport type SyncArtifactResolver =\n  | SpooledArtifactCtor\n  | (() => SpooledArtifactCtor | { default: SpooledArtifactCtor })\n\n/** Unwrap a resolved value that may be a module namespace whose `default` is the constructor. */\nconst unwrapDefault = (value: unknown): unknown => {\n  if (isObject(value) && 'default' in value) {\n    const def = (value as { default?: unknown }).default\n    if (SpooledArtifact.isSpooledArtifactConstructor(def)) return def\n  }\n  return value\n}\n\n/**\n * Resolve an {@link ArtifactResolver} to the **sync** `() => SpooledArtifactCtor` that\n * `Tool.artifactConstructor` requires (the wrap-site and the construction-time validator both\n * invoke it synchronously, so an async resolver cannot be passed straight through).\n *\n * @remarks\n * A bare constructor is itself a function, so it is distinguished from a resolver via\n * `SpooledArtifact.isSpooledArtifactConstructor` (the same duck-typed guard the core validator\n * uses) rather than by arity. Async because a dynamic-import resolver must be awaited here.\n *\n * @param resolver - The artifact configuration. When `undefined`, callers should fall back to\n *   their own default (this function rejects `undefined` so the default lives with the caller).\n * @param onInvalid - Throws a battery-scoped error; receives a human-readable reason.\n * @returns A sync `() => SpooledArtifactCtor` suitable for `Tool.artifactConstructor`.\n */\nexport const resolveArtifact = async (\n  resolver: ArtifactResolver,\n  onInvalid: (reason: string) => never\n): Promise<() => SpooledArtifactCtor> => {\n  // A constructor: hand back a thunk that returns it.\n  if (SpooledArtifact.isSpooledArtifactConstructor(resolver)) {\n    const ctor = resolver\n    return () => ctor\n  }\n  // Otherwise it must be a resolver function.\n  if (typeof resolver !== 'function') {\n    onInvalid('artifact must be a SpooledArtifact constructor or a resolver returning one')\n  }\n  let resolved: unknown\n  try {\n    resolved = await (resolver as () => unknown)()\n  } catch (err) {\n    onInvalid(`artifact resolver threw: ${isError(err) ? err.message : String(err)}`)\n  }\n  resolved = unwrapDefault(resolved)\n  if (!SpooledArtifact.isSpooledArtifactConstructor(resolved)) {\n    onInvalid('artifact resolver did not resolve to a SpooledArtifact constructor')\n  }\n  const ctor = resolved as SpooledArtifactCtor\n  return () => ctor\n}\n\n/**\n * Synchronous {@link resolveArtifact}: accepts only the {@link SyncArtifactResolver} subset and\n * throws (via `onInvalid`) on an async resolver — a runtime guard for JS callers who bypass the\n * compile-time narrowing.\n *\n * @param resolver - A constructor or a sync resolver.\n * @param onInvalid - Throws a battery-scoped error; receives a human-readable reason.\n * @returns A sync `() => SpooledArtifactCtor` suitable for `Tool.artifactConstructor`.\n */\nexport const resolveArtifactSync = (\n  resolver: SyncArtifactResolver,\n  onInvalid: (reason: string) => never\n): (() => SpooledArtifactCtor) => {\n  if (SpooledArtifact.isSpooledArtifactConstructor(resolver)) {\n    const ctor = resolver\n    return () => ctor\n  }\n  if (typeof resolver !== 'function') {\n    onInvalid('artifact must be a SpooledArtifact constructor or a resolver returning one')\n  }\n  let resolved: unknown\n  try {\n    resolved = (resolver as () => unknown)()\n  } catch (err) {\n    onInvalid(`artifact resolver threw: ${isError(err) ? err.message : String(err)}`)\n  }\n  if (isInstanceOf(resolved, 'Promise', Promise)) {\n    onInvalid(\n      'artifact resolver is async; use the async factory variant for dynamic-import resolvers'\n    )\n  }\n  resolved = unwrapDefault(resolved)\n  if (!SpooledArtifact.isSpooledArtifactConstructor(resolved)) {\n    onInvalid('artifact resolver did not resolve to a SpooledArtifact constructor')\n  }\n  const ctor = resolved as SpooledArtifactCtor\n  return () => ctor\n}\n\n// ── Middleware pipeline runners ──────────────────────────────────────────────\n\n/** Internal sentinel a short-circuiting input stage throws to unwind the pipeline immediately. */\nconst SHORT_CIRCUIT = Symbol('adk.tools.shortCircuit')\n\ninterface ShortCircuitSignal {\n  [SHORT_CIRCUIT]: true\n  result: string\n}\n\n/** `true` when `value` is the short-circuit sentinel produced by {@link makeShortCircuit}. */\nexport const isShortCircuit = (value: unknown): value is { result: string } =>\n  isObject(value) && (value as Record<symbol, unknown>)[SHORT_CIRCUIT] === true\n\n/**\n * Build a `shortCircuit(result)` function for an input-pipeline context. Calling it throws the\n * internal sentinel, which {@link runInputPipeline} catches and converts into the verbatim result\n * (skipping the HTTP request entirely — e.g. a cache hit).\n *\n * @returns A function that, when called with a result string, throws the short-circuit sentinel.\n */\nexport const makeShortCircuit = (): ((result: string) => never) => {\n  return (result: string): never => {\n    const signal: ShortCircuitSignal = { [SHORT_CIRCUIT]: true, result }\n    throw signal\n  }\n}\n\n/** A generic onion middleware stage over a mutable context `C`. */\nexport type MiddlewareFn<C> = (ctx: C, next: NextFn) => void | Promise<void>\n\n/**\n * Run an input pipeline over `ctx`. Returns the short-circuit string when a stage short-circuited,\n * or `undefined` when the pipeline reached its terminal handler. A non-terminal pipeline (a stage\n * that neither called `next()` nor short-circuited) throws — the caller converts it to an\n * `Error:` string.\n *\n * @param mw - The `Middleware` instance holding the stages (a fresh `.runner()` is minted here).\n * @param ctx - The mutable input context handed to each stage.\n * @param label - Battery name, used in the non-terminal error message.\n * @returns The short-circuit result string, or `undefined` if the pipeline ran to completion.\n */\nexport const runInputPipeline = async <C>(\n  mw: Middleware<MiddlewareFn<C>>,\n  ctx: C,\n  label: string\n): Promise<string | undefined> => {\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) {\n    if (isShortCircuit(caught)) return caught.result\n    throw caught\n  }\n  if (!reached) {\n    throw new Error(`${label} input pipeline did not call next() and did not short-circuit.`)\n  }\n  return undefined\n}\n\n/**\n * Run an output pipeline over `ctx`; rethrow any stage error to the caller's try/catch. A\n * non-terminal pipeline (no `next()`) throws.\n *\n * @param mw - The `Middleware` instance holding the stages (a fresh `.runner()` is minted here).\n * @param ctx - The mutable output context handed to each stage.\n * @param label - Battery name, used in the non-terminal error message.\n */\nexport const runOutputPipeline = async <C>(\n  mw: Middleware<MiddlewareFn<C>>,\n  ctx: C,\n  label: string\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) throw new Error(`${label} output pipeline did not call next().`)\n}\n"],"mappings":";;;;;;;;;;;AA+CA,IAAa,iBAAiB,OAC5B,YACyB;CACzB,IAAI,OAAO,YAAY,YAAY,OAAO,EAAE,GAAI,MAAM,QAAQ,EAAG;CACjE,OAAO,EAAE,GAAI,WAAW,CAAC,EAAG;AAC9B;;AA2BA,IAAM,iBAAiB,UAA4B;CACjD,IAAI,SAAS,KAAK,KAAK,aAAa,OAAO;EACzC,MAAM,MAAO,MAAgC;EAC7C,IAAI,gBAAgB,6BAA6B,GAAG,GAAG,OAAO;CAChE;CACA,OAAO;AACT;;;;;;;;;;;;;;;;AAiBA,IAAa,kBAAkB,OAC7B,UACA,cACuC;CAEvC,IAAI,gBAAgB,6BAA6B,QAAQ,GAAG;EAC1D,MAAM,OAAO;EACb,aAAa;CACf;CAEA,IAAI,OAAO,aAAa,YACtB,UAAU,4EAA4E;CAExF,IAAI;CACJ,IAAI;EACF,WAAW,MAAO,SAA2B;CAC/C,SAAS,KAAK;EACZ,UAAU,4BAA4B,QAAQ,GAAG,IAAI,IAAI,UAAU,OAAO,GAAG,GAAG;CAClF;CACA,WAAW,cAAc,QAAQ;CACjC,IAAI,CAAC,gBAAgB,6BAA6B,QAAQ,GACxD,UAAU,oEAAoE;CAEhF,MAAM,OAAO;CACb,aAAa;AACf;;;;;;;;;;AAWA,IAAa,uBACX,UACA,cACgC;CAChC,IAAI,gBAAgB,6BAA6B,QAAQ,GAAG;EAC1D,MAAM,OAAO;EACb,aAAa;CACf;CACA,IAAI,OAAO,aAAa,YACtB,UAAU,4EAA4E;CAExF,IAAI;CACJ,IAAI;EACF,WAAY,SAA2B;CACzC,SAAS,KAAK;EACZ,UAAU,4BAA4B,QAAQ,GAAG,IAAI,IAAI,UAAU,OAAO,GAAG,GAAG;CAClF;CACA,IAAI,aAAa,UAAU,WAAW,OAAO,GAC3C,UACE,wFACF;CAEF,WAAW,cAAc,QAAQ;CACjC,IAAI,CAAC,gBAAgB,6BAA6B,QAAQ,GACxD,UAAU,oEAAoE;CAEhF,MAAM,OAAO;CACb,aAAa;AACf;;AAKA,IAAM,gBAAgB,OAAO,wBAAwB;;AAQrD,IAAa,kBAAkB,UAC7B,SAAS,KAAK,KAAM,MAAkC,mBAAmB;;;;;;;;AAS3E,IAAa,yBAAsD;CACjE,QAAQ,WAA0B;EAEhC,MAAM;IADgC,gBAAgB;GAAM;EACtD;CACR;AACF;;;;;;;;;;;;AAgBA,IAAa,mBAAmB,OAC9B,IACA,KACA,UACgC;CAChC,IAAI,UAAU;CACd,IAAI;CACJ,MAAM,GACH,OAAO,EACP,aAAa,OAAO,UAAmB;EACtC,SAAS;CACX,CAAC,EACA,aAAa,YAAY;EACxB,UAAU;CACZ,CAAC,EACA,KAAK,IAAI,SAAS,QAAQ,QAAQ,GAAG,KAAK,IAAI,CAAC,CAAC;CAEnD,IAAI,WAAW,KAAA,GAAW;EACxB,IAAI,eAAe,MAAM,GAAG,OAAO,OAAO;EAC1C,MAAM;CACR;CACA,IAAI,CAAC,SACH,MAAM,IAAI,MAAM,GAAG,MAAM,+DAA+D;AAG5F;;;;;;;;;AAUA,IAAa,oBAAoB,OAC/B,IACA,KACA,UACkB;CAClB,IAAI,UAAU;CACd,IAAI;CACJ,MAAM,GACH,OAAO,EACP,aAAa,OAAO,UAAmB;EACtC,SAAS;CACX,CAAC,EACA,aAAa,YAAY;EACxB,UAAU;CACZ,CAAC,EACA,KAAK,IAAI,SAAS,QAAQ,QAAQ,GAAG,KAAK,IAAI,CAAC,CAAC;CAEnD,IAAI,WAAW,KAAA,GAAW,MAAM;CAChC,IAAI,CAAC,SAAS,MAAM,IAAI,MAAM,GAAG,MAAM,sCAAsC;AAC/E"}

package/batteries/tools/index.d.ts

@@ -22,6 +22,7 @@ export * from "./math/index";
 export * from "./memory/index";
 export * from "./parsing/index";
 export * from "./retrievables/index";
+export * from "./scrapper/index";
 export * from "./searxng/index";
 export * from "./standing_instructions/index";
 export * from "./statistics/index";
@@ -29,5 +30,6 @@ export * from "./string_processing/index";
 export * from "./structured_data/index";
 export * from "./text_analysis/index";
 export * from "./text_comparison/index";
+export * from "./web_retrieval/index";
 export * from "./time/index";
 export * from "./unit_conversion/index";

package/batteries/tools/scrapper/exceptions.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Battery-scoped exception constructors for the Scrapper web-extraction tool.
+ *
+ * @remarks
+ * Battery-scoped exception classes owned by the Scrapper 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/scrapper`). This file intentionally carries **no** `@module` tag:
+ * it is an internal sibling relative-imported by `index.ts`, so it does not mint its own
+ * `…/scrapper/exceptions` entrypoint (whose `exceptions` leaf basename would collide with sibling
+ * batteries under the `vite-plugin-dts` rolled-up `.d.ts` rule).
+ */
+/**
+ * Thrown when a Scrapper factory receives invalid configuration.
+ *
+ * @remarks
+ * Fatal: config bugs (missing/unparseable `instanceUrl`, a bad `artifact` resolver, or an async
+ * resolver passed to a `*Sync` factory) fail loud at factory-call time rather than at first scrape.
+ */
+export declare const E_INVALID_SCRAPPER_CONFIG: import("../../../factories").CreatedException<[
+    string
+]>;