@nhtio/adk 0.1.0-master-e068b986 → 0.1.0-master-0c6d984f

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/embeddings/openai/adapter.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 require("../../../chunk-Ble4zEEl.js");
-const require_tool_registry = require("../../../tool_registry-C5wfDxaq.js");
+const require_tool_registry = require("../../../tool_registry-CKJPze3j.js");
 require("../../../guards.cjs");
 const require_lib_utils_retry = require("../../../lib/utils/retry.cjs");
 const require_batteries_embeddings_openai_exceptions = require("./exceptions.cjs");

package/batteries/embeddings/openai/adapter.mjs

@@ -1,4 +1,4 @@
-import { o as isError } from "../../../tool_registry-BuMKln6b.mjs";
+import { o as isError } from "../../../tool_registry-791Vrjtf.mjs";
 import "../../../guards.mjs";
 import { computeBackoff, parseRetryAfter, sleepWithJitter } from "../../../lib/utils/retry.mjs";
 import { E_OPENAI_EMBEDDINGS_HTTP_ERROR, E_OPENAI_EMBEDDINGS_MALFORMED_RESPONSE, E_OPENAI_EMBEDDINGS_REQUEST_TIMEOUT } from "./exceptions.mjs";

package/batteries/embeddings/webllm/adapter.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 require("../../../chunk-Ble4zEEl.js");
-const require_tool_registry = require("../../../tool_registry-C5wfDxaq.js");
+const require_tool_registry = require("../../../tool_registry-CKJPze3j.js");
 require("../../../guards.cjs");
 const require_batteries_embeddings_openai_helpers = require("../openai/helpers.cjs");
 const require_batteries_embeddings_webllm_exceptions = require("./exceptions.cjs");

package/batteries/embeddings/webllm/adapter.mjs

@@ -1,4 +1,4 @@
-import { o as isError } from "../../../tool_registry-BuMKln6b.mjs";
+import { o as isError } from "../../../tool_registry-791Vrjtf.mjs";
 import "../../../guards.mjs";
 import { applyEmbeddingPrefix } from "../openai/helpers.mjs";
 import { E_INVALID_WEBLLM_EMBEDDINGS_OPTIONS, E_WEBLLM_EMBEDDINGS_ENGINE_ERROR } from "./exceptions.mjs";

package/batteries/llm/ollama/adapter.cjs

@@ -1,10 +1,10 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 require("../../../chunk-Ble4zEEl.js");
-const require_tool_registry = require("../../../tool_registry-C5wfDxaq.js");
-const require_thought = require("../../../thought-DhElxSkZ.js");
-const require_spooled_artifact = require("../../../spooled_artifact-B6XRZYFt.js");
-require("../../../common-Do0PmqEC.js");
-const require_tool_call = require("../../../tool_call-CGec5078.js");
+const require_tool_registry = require("../../../tool_registry-CKJPze3j.js");
+const require_thought = require("../../../thought-DLwpF7MI.js");
+const require_spooled_artifact = require("../../../spooled_artifact-DX8LLyUX.js");
+require("../../../common-DZl3ADJs.js");
+const require_tool_call = require("../../../tool_call-DixVlW40.js");
 require("../../../guards.cjs");
 const require_lib_utils_retry = require("../../../lib/utils/retry.cjs");
 const require_batteries_storage_in_memory = require("../../storage/in_memory.cjs");

package/batteries/llm/ollama/adapter.mjs

@@ -1,8 +1,8 @@
-import { a as canonicalStringify, c as isObject, o as isError, r as Tokenizable, s as isInstanceOf, t as ToolRegistry } from "../../../tool_registry-BuMKln6b.mjs";
-import { n as Message, t as Thought } from "../../../thought-DzcSu2Y6.mjs";
-import { i as ArtifactTool, t as SpooledArtifact } from "../../../spooled_artifact-BsM1EfRB.mjs";
-import "../../../common-DwyIhf5B.mjs";
-import { n as Media, t as ToolCall } from "../../../tool_call-DhAW70EY.mjs";
+import { a as Tokenizable, c as isObject, n as canonicalStringify, o as isError, s as isInstanceOf, t as ToolRegistry } from "../../../tool_registry-791Vrjtf.mjs";
+import { n as Message, t as Thought } from "../../../thought-B_vxAiKU.mjs";
+import { i as ArtifactTool, t as SpooledArtifact } from "../../../spooled_artifact-7eePq7JA.mjs";
+import "../../../common-DYDUi99O.mjs";
+import { n as Media, t as ToolCall } from "../../../tool_call-B4-_-vjG.mjs";
 import "../../../guards.mjs";
 import { computeBackoff, linkAbortSignals, parseRetryAfter, sleepWithJitter } from "../../../lib/utils/retry.mjs";
 import { InMemorySpoolStore } from "../../storage/in_memory.mjs";

package/batteries/llm/ollama/helpers.cjs

@@ -1,7 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 require("../../../chunk-Ble4zEEl.js");
-require("../../../common-Do0PmqEC.js");
-const require_tool_call = require("../../../tool_call-CGec5078.js");
+require("../../../common-DZl3ADJs.js");
+const require_tool_call = require("../../../tool_call-DixVlW40.js");
 require("../../../guards.cjs");
 const require_helpers = require("../../../helpers-DSTFxTiC.js");
 const require_batteries_llm_ollama_exceptions = require("./exceptions.cjs");

package/batteries/llm/ollama/helpers.mjs

@@ -1,5 +1,5 @@
-import "../../../common-DwyIhf5B.mjs";
-import { n as Media } from "../../../tool_call-DhAW70EY.mjs";
+import "../../../common-DYDUi99O.mjs";
+import { n as Media } from "../../../tool_call-B4-_-vjG.mjs";
 import "../../../guards.mjs";
 import { A as retrievableToAttrs, C as renderRetrievables, D as renderThought, E as renderThirdPartyPublicRetrievables, M as toolsToChatCompletionsTools, O as renderTrustedContent, S as renderRetrievableSafetyDirective, T as renderThirdPartyPrivateRetrievables, _ as filterThoughts, a as defaultRenderMemories, b as renderFirstPartyRetrievables, c as defaultRenderStandingInstructions, d as defaultRenderThought, f as defaultRenderTrustedContent, g as escapeXmlAttribute, h as descriptionToChatCompletionsJsonSchema, i as defaultRenderFirstPartyRetrievables, k as renderUntrustedContent, l as defaultRenderThirdPartyPrivateRetrievables, m as defaultToolsToChatCompletionsTools, n as defaultFilterThoughts, o as defaultRenderRetrievableSafetyDirective, p as defaultRenderUntrustedContent, r as defaultRenderChatCompletionsSystemPrompt, s as defaultRenderRetrievables, t as defaultDescriptionToChatCompletionsJsonSchema, u as defaultRenderThirdPartyPublicRetrievables, v as memoryToAttrs, w as renderStandingInstructions, x as renderMemories, y as renderChatCompletionsSystemPrompt } from "../../../helpers-xhrQbMAG.mjs";
 import { E_OLLAMA_UNSUPPORTED_MEDIA_MODALITY } from "./exceptions.mjs";

package/batteries/llm/ollama/validation.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 require("../../../chunk-Ble4zEEl.js");
-const require_common = require("../../../common-Do0PmqEC.js");
+const require_common = require("../../../common-DZl3ADJs.js");
 require("../../../guards.cjs");
 const require_batteries_llm_ollama_exceptions = require("./exceptions.cjs");
 let _nhtio_validation = require("@nhtio/validation");

package/batteries/llm/ollama/validation.mjs

@@ -1,4 +1,4 @@
-import { i as byteStoreSchema } from "../../../common-DwyIhf5B.mjs";
+import { i as byteStoreSchema } from "../../../common-DYDUi99O.mjs";
 import "../../../guards.mjs";
 import { E_INVALID_OLLAMA_OPTIONS } from "./exceptions.mjs";
 import { validator } from "@nhtio/validation";

package/batteries/llm/openai_chat_completions/adapter.cjs

@@ -1,10 +1,10 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 require("../../../chunk-Ble4zEEl.js");
-const require_tool_registry = require("../../../tool_registry-C5wfDxaq.js");
-const require_thought = require("../../../thought-DhElxSkZ.js");
-const require_spooled_artifact = require("../../../spooled_artifact-B6XRZYFt.js");
-require("../../../common-Do0PmqEC.js");
-const require_tool_call = require("../../../tool_call-CGec5078.js");
+const require_tool_registry = require("../../../tool_registry-CKJPze3j.js");
+const require_thought = require("../../../thought-DLwpF7MI.js");
+const require_spooled_artifact = require("../../../spooled_artifact-DX8LLyUX.js");
+require("../../../common-DZl3ADJs.js");
+const require_tool_call = require("../../../tool_call-DixVlW40.js");
 require("../../../guards.cjs");
 const require_lib_utils_retry = require("../../../lib/utils/retry.cjs");
 const require_batteries_llm_openai_chat_completions_exceptions = require("./exceptions.cjs");

package/batteries/llm/openai_chat_completions/adapter.mjs

@@ -1,8 +1,8 @@
-import { a as canonicalStringify, c as isObject, o as isError, r as Tokenizable, s as isInstanceOf, t as ToolRegistry } from "../../../tool_registry-BuMKln6b.mjs";
-import { n as Message, t as Thought } from "../../../thought-DzcSu2Y6.mjs";
-import { i as ArtifactTool, t as SpooledArtifact } from "../../../spooled_artifact-BsM1EfRB.mjs";
-import "../../../common-DwyIhf5B.mjs";
-import { n as Media, t as ToolCall } from "../../../tool_call-DhAW70EY.mjs";
+import { a as Tokenizable, c as isObject, n as canonicalStringify, o as isError, s as isInstanceOf, t as ToolRegistry } from "../../../tool_registry-791Vrjtf.mjs";
+import { n as Message, t as Thought } from "../../../thought-B_vxAiKU.mjs";
+import { i as ArtifactTool, t as SpooledArtifact } from "../../../spooled_artifact-7eePq7JA.mjs";
+import "../../../common-DYDUi99O.mjs";
+import { n as Media, t as ToolCall } from "../../../tool_call-B4-_-vjG.mjs";
 import "../../../guards.mjs";
 import { computeBackoff, linkAbortSignals, parseRetryAfter, sleepWithJitter } from "../../../lib/utils/retry.mjs";
 import { E_INVALID_OPENAI_CHAT_COMPLETIONS_OPTIONS, E_OPENAI_CHAT_COMPLETIONS_CONTEXT_OVERFLOW, E_OPENAI_CHAT_COMPLETIONS_HTTP_ERROR, E_OPENAI_CHAT_COMPLETIONS_INVALID_TOOL_CALL_ARGS, E_OPENAI_CHAT_COMPLETIONS_REQUEST_TIMEOUT, E_OPENAI_CHAT_COMPLETIONS_STREAM_ERROR, E_OPENAI_CHAT_COMPLETIONS_STREAM_STALLED } from "./exceptions.mjs";

package/batteries/llm/openai_chat_completions/helpers.cjs

@@ -1,7 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 require("../../../chunk-Ble4zEEl.js");
-require("../../../common-Do0PmqEC.js");
-const require_tool_call = require("../../../tool_call-CGec5078.js");
+require("../../../common-DZl3ADJs.js");
+const require_tool_call = require("../../../tool_call-DixVlW40.js");
 require("../../../guards.cjs");
 const require_batteries_llm_openai_chat_completions_exceptions = require("./exceptions.cjs");
 const require_helpers = require("../../../helpers-DSTFxTiC.js");

package/batteries/llm/openai_chat_completions/helpers.mjs

@@ -1,5 +1,5 @@
-import "../../../common-DwyIhf5B.mjs";
-import { n as Media } from "../../../tool_call-DhAW70EY.mjs";
+import "../../../common-DYDUi99O.mjs";
+import { n as Media } from "../../../tool_call-B4-_-vjG.mjs";
 import "../../../guards.mjs";
 import { E_UNSUPPORTED_MEDIA_MODALITY } from "./exceptions.mjs";
 import { A as retrievableToAttrs, C as renderRetrievables, D as renderThought, E as renderThirdPartyPublicRetrievables, M as toolsToChatCompletionsTools, O as renderTrustedContent, S as renderRetrievableSafetyDirective, T as renderThirdPartyPrivateRetrievables, _ as filterThoughts, a as defaultRenderMemories, b as renderFirstPartyRetrievables, c as defaultRenderStandingInstructions, d as defaultRenderThought, f as defaultRenderTrustedContent, g as escapeXmlAttribute, h as descriptionToChatCompletionsJsonSchema, i as defaultRenderFirstPartyRetrievables, j as sanitiseNameField, k as renderUntrustedContent, l as defaultRenderThirdPartyPrivateRetrievables, m as defaultToolsToChatCompletionsTools, n as defaultFilterThoughts, o as defaultRenderRetrievableSafetyDirective, p as defaultRenderUntrustedContent, r as defaultRenderChatCompletionsSystemPrompt, s as defaultRenderRetrievables, t as defaultDescriptionToChatCompletionsJsonSchema, u as defaultRenderThirdPartyPublicRetrievables, v as memoryToAttrs, w as renderStandingInstructions, x as renderMemories, y as renderChatCompletionsSystemPrompt } from "../../../helpers-xhrQbMAG.mjs";

package/batteries/llm/openai_chat_completions/validation.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 require("../../../chunk-Ble4zEEl.js");
-const require_common = require("../../../common-Do0PmqEC.js");
+const require_common = require("../../../common-DZl3ADJs.js");
 require("../../../guards.cjs");
 const require_batteries_llm_openai_chat_completions_exceptions = require("./exceptions.cjs");
 let _nhtio_validation = require("@nhtio/validation");

package/batteries/llm/openai_chat_completions/validation.mjs

@@ -1,4 +1,4 @@
-import { i as byteStoreSchema } from "../../../common-DwyIhf5B.mjs";
+import { i as byteStoreSchema } from "../../../common-DYDUi99O.mjs";
 import "../../../guards.mjs";
 import { E_INVALID_OPENAI_CHAT_COMPLETIONS_OPTIONS } from "./exceptions.mjs";
 import { validator } from "@nhtio/validation";

package/batteries/llm/webllm_chat_completions/adapter.cjs

@@ -1,10 +1,10 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 require("../../../chunk-Ble4zEEl.js");
-const require_tool_registry = require("../../../tool_registry-C5wfDxaq.js");
-const require_thought = require("../../../thought-DhElxSkZ.js");
-const require_spooled_artifact = require("../../../spooled_artifact-B6XRZYFt.js");
-require("../../../common-Do0PmqEC.js");
-const require_tool_call = require("../../../tool_call-CGec5078.js");
+const require_tool_registry = require("../../../tool_registry-CKJPze3j.js");
+const require_thought = require("../../../thought-DLwpF7MI.js");
+const require_spooled_artifact = require("../../../spooled_artifact-DX8LLyUX.js");
+require("../../../common-DZl3ADJs.js");
+const require_tool_call = require("../../../tool_call-DixVlW40.js");
 require("../../../guards.cjs");
 const require_batteries_storage_in_memory = require("../../storage/in_memory.cjs");
 const require_helpers = require("../../../helpers-DSTFxTiC.js");

package/batteries/llm/webllm_chat_completions/adapter.mjs

@@ -1,8 +1,8 @@
-import { a as canonicalStringify, c as isObject, o as isError, r as Tokenizable, s as isInstanceOf, t as ToolRegistry } from "../../../tool_registry-BuMKln6b.mjs";
-import { n as Message, t as Thought } from "../../../thought-DzcSu2Y6.mjs";
-import { i as ArtifactTool, t as SpooledArtifact } from "../../../spooled_artifact-BsM1EfRB.mjs";
-import "../../../common-DwyIhf5B.mjs";
-import { n as Media, t as ToolCall } from "../../../tool_call-DhAW70EY.mjs";
+import { a as Tokenizable, c as isObject, n as canonicalStringify, o as isError, s as isInstanceOf, t as ToolRegistry } from "../../../tool_registry-791Vrjtf.mjs";
+import { n as Message, t as Thought } from "../../../thought-B_vxAiKU.mjs";
+import { i as ArtifactTool, t as SpooledArtifact } from "../../../spooled_artifact-7eePq7JA.mjs";
+import "../../../common-DYDUi99O.mjs";
+import { n as Media, t as ToolCall } from "../../../tool_call-B4-_-vjG.mjs";
 import "../../../guards.mjs";
 import { InMemorySpoolStore } from "../../storage/in_memory.mjs";
 import { a as defaultRenderMemories, c as defaultRenderStandingInstructions, d as defaultRenderThought, f as defaultRenderTrustedContent, i as defaultRenderFirstPartyRetrievables, l as defaultRenderThirdPartyPrivateRetrievables, m as defaultToolsToChatCompletionsTools, n as defaultFilterThoughts, o as defaultRenderRetrievableSafetyDirective, p as defaultRenderUntrustedContent, r as defaultRenderChatCompletionsSystemPrompt, s as defaultRenderRetrievables, t as defaultDescriptionToChatCompletionsJsonSchema, u as defaultRenderThirdPartyPublicRetrievables } from "../../../helpers-xhrQbMAG.mjs";

package/batteries/llm/webllm_chat_completions/validation.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 require("../../../chunk-Ble4zEEl.js");
-const require_common = require("../../../common-Do0PmqEC.js");
+const require_common = require("../../../common-DZl3ADJs.js");
 require("../../../guards.cjs");
 const require_batteries_llm_webllm_chat_completions_exceptions = require("./exceptions.cjs");
 let _nhtio_validation = require("@nhtio/validation");

package/batteries/llm/webllm_chat_completions/validation.mjs

@@ -1,4 +1,4 @@
-import { i as byteStoreSchema } from "../../../common-DwyIhf5B.mjs";
+import { i as byteStoreSchema } from "../../../common-DYDUi99O.mjs";
 import "../../../guards.mjs";
 import { E_INVALID_WEBLLM_CHAT_COMPLETIONS_OPTIONS } from "./exceptions.mjs";
 import { validator } from "@nhtio/validation";

package/batteries/storage/flydrive.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_chunk = require("../../chunk-Ble4zEEl.js");
-const require_tool_registry = require("../../tool_registry-C5wfDxaq.js");
+const require_tool_registry = require("../../tool_registry-CKJPze3j.js");
 require("../../guards.cjs");
 //#endregion
 //#region src/batteries/storage/flydrive/index.ts

package/batteries/storage/flydrive.mjs

@@ -1,5 +1,5 @@
 import { t as __commonJSMin } from "../../chunk-Bpcn9VDT.mjs";
-import { s as isInstanceOf } from "../../tool_registry-BuMKln6b.mjs";
+import { s as isInstanceOf } from "../../tool_registry-791Vrjtf.mjs";
 import "../../guards.mjs";
 //#endregion
 //#region src/batteries/storage/flydrive/index.ts

package/batteries/storage/in_memory.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 require("../../chunk-Ble4zEEl.js");
-const require_tool_registry = require("../../tool_registry-C5wfDxaq.js");
+const require_tool_registry = require("../../tool_registry-CKJPze3j.js");
 require("../../guards.cjs");
 //#region src/batteries/storage/in_memory/index.ts
 /**

package/batteries/storage/in_memory.mjs

@@ -1,4 +1,4 @@
-import { s as isInstanceOf } from "../../tool_registry-BuMKln6b.mjs";
+import { s as isInstanceOf } from "../../tool_registry-791Vrjtf.mjs";
 import "../../guards.mjs";
 //#region src/batteries/storage/in_memory/index.ts
 /**

package/batteries/storage/opfs.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 require("../../chunk-Ble4zEEl.js");
-const require_tool_registry = require("../../tool_registry-C5wfDxaq.js");
+const require_tool_registry = require("../../tool_registry-CKJPze3j.js");
 require("../../guards.cjs");
 //#region src/batteries/storage/opfs/index.ts
 /**

package/batteries/storage/opfs.mjs

@@ -1,4 +1,4 @@
-import { s as isInstanceOf } from "../../tool_registry-BuMKln6b.mjs";
+import { s as isInstanceOf } from "../../tool_registry-791Vrjtf.mjs";
 import "../../guards.mjs";
 //#region src/batteries/storage/opfs/index.ts
 /**

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>;