@nhtio/adk 1.20260609.0 → 1.20260609.1

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

@@ -0,0 +1,172 @@
+/**
+ * Factories for configured Scrapper web-extraction tools (article + links).
+ *
+ * @module @nhtio/adk/batteries/tools/scrapper
+ *
+ * @remarks
+ * [Scrapper](https://github.com/amerkurev/scrapper) is a self-hosted service that loads a page in a
+ * real headless browser and extracts either the readable article (`/api/article`) or the page's
+ * links (`/api/links`). It gives an agent browser-grade reading power — JS-rendered pages a
+ * renderless fetcher can't see — but as a **stateless** HTTP call: each request runs in a fresh
+ * incognito context, stores no session or credentials, and shares nothing with any other call.
+ *
+ * Like the SearXNG battery, this exports **factories** (not ready-made `Tool` constants), because a
+ * scrape tool needs per-deployment config (instance URL + custom auth headers). Two verbs, each with
+ * an async factory ({@link createScrapperArticleTool} / {@link createScrapperLinksTool}, accepting a
+ * dynamic-import `artifact` resolver) and a sync variant ({@link createScrapperArticleToolSync} /
+ * {@link createScrapperLinksToolSync}). Because these are factories, they MUST NOT be bulk-registered
+ * via `Object.values(batteries)` — call one, then register the returned tool.
+ *
+ * @see https://github.com/amerkurev/scrapper
+ */
+import { type ScrapperBaseConfig } from "./shared";
+import type { Tool } from "../../../forge";
+import type { ArtifactResolver, SyncArtifactResolver } from "../_shared/index";
+export { E_INVALID_SCRAPPER_CONFIG } from "./exceptions";
+export type { ScrapperRequestContext, ScrapperResponseContext, ScrapperInputMiddlewareFn, ScrapperOutputMiddlewareFn, } from "./shared";
+/** Model-facing params common to both verbs (snake_case; mapped to kebab on the wire). */
+export interface ScrapperCommonParams {
+    /** Return a cached result when available instead of re-scraping. */
+    cache?: boolean;
+    /** Capture a screenshot; the result carries a `screenshotUri`. */
+    screenshot?: boolean;
+    /** Run in an incognito browser context (no persisted browsing data). Default true upstream. */
+    incognito?: boolean;
+    /** Browser navigation timeout in ms (`0` disables). Distinct from the tool's own fetch timeout. */
+    timeout?: number;
+    /** When navigation is considered finished. */
+    wait_until?: 'load' | 'domcontentloaded' | 'networkidle' | 'commit';
+    /** Wait this many ms after load before parsing. */
+    sleep?: number;
+    /** Scroll down N pixels for lazy-loading pages. Requires a positive `sleep`. */
+    scroll_down?: number;
+    /** Emulated device, e.g. `Desktop Chrome`. Overrides individual viewport/UA settings. */
+    device?: string;
+    /** Explicit user-agent (prefer `device`). */
+    user_agent?: string;
+    /** Extra headers the SCRAPER's browser sends to the TARGET site, `K:v;K2:v2` (NOT instance auth). */
+    extra_http_headers?: string;
+    /** Upstream proxy, e.g. `http://host:3128` or `socks5://host:1080`. */
+    proxy_server?: string;
+}
+/** Model-facing params for `/api/article`. */
+export interface ScrapperArticleParams extends ScrapperCommonParams {
+    /** Populate `fullContent` with the page's full HTML. */
+    full_content?: boolean;
+}
+/** Model-facing params for `/api/links`. */
+export interface ScrapperLinksParams extends ScrapperCommonParams {
+    /** Median link-text length threshold for the link parser. */
+    text_len_threshold?: number;
+    /** Median words-per-link threshold for the link parser. */
+    words_threshold?: number;
+}
+/** A normalised Scrapper article (loose/nullable upstream). */
+export interface ScrapperArticle {
+    /** The page URL the article was extracted from. */
+    url?: string;
+    /** Article title. */
+    title?: string;
+    /** Author / byline metadata. */
+    byline?: string;
+    /** Short excerpt or description of the article. */
+    excerpt?: string;
+    /** Name of the site the article came from. */
+    siteName?: string;
+    /** Detected content language. */
+    lang?: string;
+    /** Character count of the extracted article text. */
+    length?: number;
+    /** Publication time, when the page exposed one. */
+    publishedTime?: string;
+    /** Scrapper's own date field for the result. */
+    date?: string;
+    /** Article text with HTML stripped. */
+    textContent?: string;
+    /** Processed article HTML; present when the caller requested it. */
+    content?: string;
+    /** Full page HTML; present only when `full_content` was set. */
+    fullContent?: string;
+    /** Screenshot URI; present only when `screenshot` was set. */
+    screenshotUri?: string;
+}
+/** A single link from `/api/links` (verified live: `{ url, text }`). */
+export interface ScrapperLink {
+    /** The link's target URL. */
+    url?: string;
+    /** The link's anchor text. */
+    text?: string;
+}
+/** A normalised Scrapper links payload. */
+export interface ScrapperLinks {
+    /** The page URL the links were collected from. */
+    url?: string;
+    /** The page title. */
+    title?: string;
+    /** The page's domain. */
+    domain?: string;
+    /** Scrapper's own date field for the result. */
+    date?: string;
+    /** The collected links, each `{ url, text }`. */
+    links: ScrapperLink[];
+    /** Screenshot URI; present only when `screenshot` was set. */
+    screenshotUri?: string;
+}
+/** Async-factory config for `/api/article` (full `artifact` resolver, incl. dynamic import). */
+export type ScrapperArticleConfig = ScrapperBaseConfig<ScrapperArticleParams, ScrapperArticle, ArtifactResolver>;
+/** Sync-factory config for `/api/article` (`artifact` narrowed to the sync subset). */
+export type ScrapperArticleConfigSync = ScrapperBaseConfig<ScrapperArticleParams, ScrapperArticle, SyncArtifactResolver>;
+/** Async-factory config for `/api/links`. */
+export type ScrapperLinksConfig = ScrapperBaseConfig<ScrapperLinksParams, ScrapperLinks, ArtifactResolver>;
+/** Sync-factory config for `/api/links`. */
+export type ScrapperLinksConfigSync = ScrapperBaseConfig<ScrapperLinksParams, ScrapperLinks, SyncArtifactResolver>;
+/**
+ * Create a configured Scrapper **article** {@link Tool} (async — accepts a dynamic-import `artifact`).
+ *
+ * @remarks
+ * Async because `artifact` may be an async / dynamic-import resolver, which must resolve to the sync
+ * `() => Ctor` `Tool.artifactConstructor` requires before the tool is built. For the common case,
+ * use {@link createScrapperArticleToolSync} and skip the `await`.
+ *
+ * @warning
+ * Two distinct "headers": `config.headers` authenticates to the Scrapper *instance*; the
+ * `extra_http_headers` *parameter* is what the scraper's browser sends to the *target site* — do not
+ * conflate them. Also note `scroll_down` requires a positive `sleep`, and `resultUri`/`screenshotUri`
+ * are instance-relative and may come back `http://` even over HTTPS — do not assume they match
+ * `instanceUrl`.
+ *
+ * @param config - Instance URL, instance-auth headers, output policy, `artifact` resolver,
+ *   per-parameter disposition (`fixed`/`defaults`/`fixedQuery`), and middleware pipelines.
+ * @returns A promise of a `Tool` ready to register in a `ToolRegistry`.
+ * @throws {@link E_INVALID_SCRAPPER_CONFIG} when `instanceUrl` or `artifact` is invalid.
+ */
+export declare const createScrapperArticleTool: (config: ScrapperArticleConfig) => Promise<Tool>;
+/**
+ * Synchronous {@link createScrapperArticleTool} — `artifact` narrowed to the sync subset.
+ *
+ * @param config - Same as {@link createScrapperArticleTool}, with a sync-only `artifact`.
+ * @returns A `Tool` ready to register in a `ToolRegistry`.
+ * @throws {@link E_INVALID_SCRAPPER_CONFIG} when `instanceUrl` or `artifact` is invalid (incl. an async resolver).
+ */
+export declare const createScrapperArticleToolSync: (config: ScrapperArticleConfigSync) => Tool;
+/**
+ * Create a configured Scrapper **links** {@link Tool} (async — accepts a dynamic-import `artifact`).
+ *
+ * @remarks
+ * See {@link createScrapperArticleTool} for the two-headers caveat and the async rationale. Each
+ * `links` item is `{ url, text }`.
+ *
+ * @param config - Instance URL, instance-auth headers, output policy, `artifact` resolver,
+ *   per-parameter disposition, and middleware pipelines.
+ * @returns A promise of a `Tool` ready to register in a `ToolRegistry`.
+ * @throws {@link E_INVALID_SCRAPPER_CONFIG} when `instanceUrl` or `artifact` is invalid.
+ */
+export declare const createScrapperLinksTool: (config: ScrapperLinksConfig) => Promise<Tool>;
+/**
+ * Synchronous {@link createScrapperLinksTool} — `artifact` narrowed to the sync subset.
+ *
+ * @param config - Same as {@link createScrapperLinksTool}, with a sync-only `artifact`.
+ * @returns A `Tool` ready to register in a `ToolRegistry`.
+ * @throws {@link E_INVALID_SCRAPPER_CONFIG} when `instanceUrl` or `artifact` is invalid (incl. an async resolver).
+ */
+export declare const createScrapperLinksToolSync: (config: ScrapperLinksConfigSync) => Tool;

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

@@ -0,0 +1,139 @@
+/**
+ * Internal core shared by both Scrapper verbs (article / links).
+ *
+ * @remarks
+ * No `@module` tag — this is a sibling of `index.ts`, relative-imported, not its own entrypoint.
+ * Houses the per-parameter disposition machinery (schema building from `fixed`/`defaults`), the
+ * snake→kebab wire mapping, the request/response contexts, and the `fetch`+pipeline handler core.
+ * Generic harness helpers (artifact/header resolution, pipeline runners) come from `../_shared`.
+ */
+import { Tool } from "../../../forge";
+import { type ToolHeaders, type ToolHeadersResolver, type SpooledArtifactCtor } from "../_shared/index";
+import type { Schema } from '@nhtio/validation';
+import type { NextFn } from '@nhtio/middleware';
+/** Throw the battery-scoped config error. */
+export declare const failConfig: (reason: string) => never;
+/** The wire type of a Scrapper query parameter — controls serialisation. */
+export type ScrapperParamType = 'string' | 'number' | 'boolean';
+/**
+ * One curated, model-facing Scrapper parameter: its snake_case key (used in the model schema and
+ * in `fixed`/`defaults`), its kebab-case wire name, its type, the base validator, and a description.
+ */
+export interface ScrapperParamSpec {
+    /** snake_case key as seen by the model and in `config.fixed` / `config.defaults`. */
+    key: string;
+    /** kebab-case name sent to the Scrapper API. */
+    wire: string;
+    /** Wire type, controlling string/number/boolean serialisation. */
+    type: ScrapperParamType;
+    /** Base `@nhtio/validation` schema (no `.required()`/`.default()`/`.optional()` applied yet). */
+    schema: Schema;
+    /** Human-readable description surfaced to the model. */
+    description: string;
+}
+/**
+ * Build the model-facing input schema from a verb's param specs and the factory's disposition.
+ * `url` is always required. A `fixed` param is omitted (the model can't set it); a `defaults` param
+ * gets `.default(value)`; everything else is `.optional()`.
+ */
+export declare const buildScrapperSchema: (specs: ScrapperParamSpec[], fixed: Record<string, unknown> | undefined, defaults: Record<string, unknown> | undefined, extra?: Record<string, Schema>) => Schema;
+/**
+ * Assemble the wire-kebab query params for one request: each spec's value is `fixed` (if pinned)
+ * else the validated model/default value; then `fixedQuery` raw passthrough is layered on. `url`
+ * is handled separately (it is the search target, never pinned).
+ */
+export declare const buildWireParams: (args: Record<string, unknown>, specs: ScrapperParamSpec[], fixed: Record<string, unknown> | undefined, fixedQuery: Record<string, string> | undefined) => Record<string, string>;
+/**
+ * Mutable context handed to each input-pipeline stage **before** the HTTP request is sent.
+ * Identical for both verbs.
+ */
+export interface ScrapperRequestContext {
+    /** The tool's name (read-only). */
+    readonly toolName: string;
+    /** The target page URL (the `url` argument). Mutable. */
+    url: string;
+    /** Wire-kebab query params (everything except `url`). Mutable. */
+    params: Record<string, string>;
+    /** Resolved request headers sent to the SCRAPPER INSTANCE (auth). Mutable. */
+    headers: ToolHeaders;
+    /** The Scrapper instance base URL (read-only). */
+    readonly instanceUrl: string;
+    /** Cross-stage scratch space; also carried onto the response context. */
+    readonly stash: Map<string, unknown>;
+    /** Skip the fetch and return `result` verbatim as the tool's output (e.g. a cache hit). */
+    shortCircuit(result: string): void;
+}
+/**
+ * Mutable context handed to each output-pipeline stage **after** the response JSON is parsed.
+ *
+ * @typeParam R - The verb's normalised result type (article object or links payload).
+ */
+export interface ScrapperResponseContext<R> {
+    /** The tool's name (read-only). */
+    readonly toolName: string;
+    /** The request context as it was sent (post-input-pipeline). */
+    readonly request: ScrapperRequestContext;
+    /** The parsed Scrapper JSON body. Mutable (used when `format` is `raw`). */
+    raw: unknown;
+    /** The normalised result. Mutable — reshape, redact, enrich. */
+    result: R;
+    /** The effective payload shape for this call. */
+    format: 'normalized' | 'raw';
+    /** When set, used verbatim as the tool's output (overrides serialisation). */
+    output?: string;
+    /** Cross-stage scratch space; carried over from the request context. */
+    readonly stash: Map<string, unknown>;
+}
+/** An input-pipeline stage. Onion middleware over {@link ScrapperRequestContext}. */
+export type ScrapperInputMiddlewareFn = (ctx: ScrapperRequestContext, next: NextFn) => void | Promise<void>;
+/** An output-pipeline stage over a verb's {@link ScrapperResponseContext}. */
+export type ScrapperOutputMiddlewareFn<R> = (ctx: ScrapperResponseContext<R>, next: NextFn) => void | Promise<void>;
+/** Configuration common to every Scrapper factory. `A` is the accepted `artifact` resolver type. */
+export interface ScrapperBaseConfig<P, R, A> {
+    /** Base URL of the Scrapper instance, e.g. `https://scrapper.example.org`. Required. */
+    instanceUrl: string;
+    /** Headers sent to the Scrapper INSTANCE for auth (X-API-Key / Basic) — static or resolver. */
+    headers?: ToolHeaders | ToolHeadersResolver;
+    /** The tool's own `fetch` AbortController timeout in ms. Default `65_000` (> Scrapper's 60s browser default). */
+    requestTimeoutMs?: number;
+    /** Output shape. `normalized`/`raw` pin it; `either` (default) exposes a `format` arg to the model. */
+    resultFormat?: 'normalized' | 'raw' | 'either';
+    /** Spool-artifact resolver for the output. Default `() => SpooledJsonArtifact`. */
+    artifact?: A;
+    /** Tool name override. */
+    name?: string;
+    /** Tool description override. */
+    description?: string;
+    /** Pinned params — sent always, removed from the model schema. */
+    fixed?: Partial<P>;
+    /** Model-overridable default param values. */
+    defaults?: Partial<P>;
+    /** Raw, un-modeled wire params (kebab keys) — always sent, never model-visible. Keeps the battery generic. */
+    fixedQuery?: Record<string, string>;
+    /** Stages run before the HTTP request. See {@link ScrapperRequestContext}. */
+    inputPipeline?: ScrapperInputMiddlewareFn[];
+    /** Stages run after the response is parsed. See {@link ScrapperResponseContext}. */
+    outputPipeline?: ScrapperOutputMiddlewareFn<R>[];
+}
+/** Verb-specific wiring passed to {@link assembleScrapperTool}. */
+export interface ScrapperVerb<R> {
+    /** Scrapper endpoint path, e.g. `/api/article`. */
+    endpoint: string;
+    /** The curated param specs for this verb. */
+    specs: ScrapperParamSpec[];
+    /** Default tool name (`scrapper_article` / `scrapper_links`). */
+    defaultName: string;
+    /** Default tool description. */
+    defaultDescription: string;
+    /** Map a parsed Scrapper body to the verb's normalised result. */
+    normalize: (body: Record<string, unknown>) => R;
+}
+/**
+ * Build a configured Scrapper {@link Tool} from validated config + an already-resolved sync
+ * artifact constructor. Shared by every verb and by both the async and sync factories.
+ */
+export declare const assembleScrapperTool: <P, R>(verb: ScrapperVerb<R>, config: ScrapperBaseConfig<P, R, unknown>, instanceUrl: string, artifactConstructor: () => SpooledArtifactCtor) => Tool;
+/** Validate `instanceUrl` and return the trailing-slash-normalised base. */
+export declare const validateScrapperInstanceUrl: (config: {
+    instanceUrl?: string;
+}) => string;

package/batteries/tools/scrapper.cjs

@@ -0,0 +1,8 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+require("../../chunk-Ble4zEEl.js");
+const require_scrapper = require("../../scrapper-BeweWurk.js");
+exports.E_INVALID_SCRAPPER_CONFIG = require_scrapper.E_INVALID_SCRAPPER_CONFIG;
+exports.createScrapperArticleTool = require_scrapper.createScrapperArticleTool;
+exports.createScrapperArticleToolSync = require_scrapper.createScrapperArticleToolSync;
+exports.createScrapperLinksTool = require_scrapper.createScrapperLinksTool;
+exports.createScrapperLinksToolSync = require_scrapper.createScrapperLinksToolSync;

package/batteries/tools/scrapper.mjs

@@ -0,0 +1,2 @@
+import { a as E_INVALID_SCRAPPER_CONFIG, i as createScrapperLinksToolSync, n as createScrapperArticleToolSync, r as createScrapperLinksTool, t as createScrapperArticleTool } from "../../scrapper-BHM1mCde.mjs";
+export { E_INVALID_SCRAPPER_CONFIG, createScrapperArticleTool, createScrapperArticleToolSync, createScrapperLinksTool, createScrapperLinksToolSync };

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

@@ -5,18 +5,19 @@
  *
  * @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.
+ * stateless `Tool` constant — the SearXNG battery exports **factories**,
+ * {@link createSearxngSearchTool} (async) and {@link createSearxngSearchToolSync}. 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 })])`.
+ * Because this module exports factories rather than `Tool` instances, they MUST NOT be
+ * bulk-registered via `Object.values(batteries)`. Call a factory first, then register the
+ * returned tool: `new ToolRegistry([await createSearxngSearchTool({ instanceUrl })])`.
  *
  * @see https://docs.searxng.org/dev/search_api.html
  */
-import { Tool, type ArtifactConstructorResolver } from "../../../common";
+import { Tool } from "../../../forge";
+import { type ArtifactResolver, type SyncArtifactResolver } from "../_shared/index";
 import type { NextFn } from '@nhtio/middleware';
 export { E_INVALID_SEARXNG_CONFIG } from "./exceptions";
 /** A static set of request headers (used for custom authentication). */
@@ -76,7 +77,7 @@ export interface SearxngRequestContext {
  * @remarks
  * Stages reshape, redact, enrich, or re-rank {@link SearxngResponseContext.results}, mutate the
  * raw body, or set {@link SearxngResponseContext.output} to override the serialised string
- * verbatim (e.g. to render markdown that matches a markdown `artifactConstructor`).
+ * verbatim (e.g. to render markdown that matches a markdown `artifact` resolver).
  */
 export interface SearxngResponseContext {
     /** The tool's name (read-only). */
@@ -98,8 +99,14 @@ export interface SearxngResponseContext {
 export type SearxngInputMiddlewareFn = (ctx: SearxngRequestContext, next: NextFn) => void | Promise<void>;
 /** An output-pipeline stage. Onion middleware over {@link SearxngResponseContext}. */
 export type SearxngOutputMiddlewareFn = (ctx: SearxngResponseContext, next: NextFn) => void | Promise<void>;
-/** Configuration for {@link createSearxngSearchTool}. */
-export interface SearxngToolConfig {
+/**
+ * Configuration for {@link createSearxngSearchTool} (async) and
+ * {@link createSearxngSearchToolSync} (sync — `artifact` narrowed to the sync subset).
+ *
+ * @typeParam A - The {@link ArtifactResolver} variant accepted: the full resolver (async factory)
+ *   or the sync subset ({@link createSearxngSearchToolSync}).
+ */
+export interface SearxngToolConfig<A = ArtifactResolver> {
     /** Base URL of the SearXNG instance, e.g. `https://searx.example.org`. Required. */
     instanceUrl: string;
     /** Custom request headers — a static object or a (sync/async) resolver for refreshable auth. */
@@ -116,20 +123,26 @@ export interface SearxngToolConfig {
     /** Tool description override. */
     description?: string;
     /**
-     * Spool artifact constructor for the tool's output. Default `() => SpooledJsonArtifact`.
-     * Pass `() => SpooledMarkdownArtifact` (paired with an output stage that renders markdown into
-     * `ctx.output`) or `() => SpooledArtifact` for plain text.
+     * Spool-artifact resolver for the tool's output. Default `() => SpooledJsonArtifact`. Accepts a
+     * constructor, a sync resolver, or — via {@link createSearxngSearchTool} — an async /
+     * dynamic-import resolver. Pass `() => SpooledMarkdownArtifact` (paired with an output stage that
+     * renders markdown into `ctx.output`) or `() => SpooledArtifact` for plain text.
      */
-    artifactConstructor?: ArtifactConstructorResolver;
+    artifact?: A;
     /** Stages run before the HTTP request. See {@link SearxngRequestContext}. */
     inputPipeline?: SearxngInputMiddlewareFn[];
     /** Stages run after the response is parsed. See {@link SearxngResponseContext}. */
     outputPipeline?: SearxngOutputMiddlewareFn[];
 }
 /**
- * Create a configured SearXNG search {@link Tool}.
+ * Create a configured SearXNG search {@link Tool} (async — accepts a dynamic-import `artifact`).
  *
  * @remarks
+ * Async because `artifact` may be an async / dynamic-import resolver, which must be resolved to the
+ * sync `() => Ctor` that `Tool.artifactConstructor` requires before the tool is built (the
+ * wrap-site invokes it synchronously). For the common case where you reference the artifact class
+ * directly, use {@link createSearxngSearchToolSync} and skip the `await`.
+ *
  * 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
@@ -142,9 +155,23 @@ export interface SearxngToolConfig {
  * {@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}.
+ * @param config - The instance URL, optional custom headers, output-format policy, `artifact`
+ *   resolver, and input/output middleware pipelines. See {@link SearxngToolConfig}.
+ * @returns A promise of a `Tool` ready to register in a `ToolRegistry`.
+ * @throws {@link E_INVALID_SEARXNG_CONFIG} when `instanceUrl` or `artifact` is invalid.
+ */
+export declare const createSearxngSearchTool: (config: SearxngToolConfig<ArtifactResolver>) => Promise<Tool>;
+/**
+ * Synchronous {@link createSearxngSearchTool} — the ergonomic common path.
+ *
+ * @remarks
+ * `artifact` is narrowed to the sync subset (a constructor or a sync resolver). Passing an async
+ * resolver is a compile-time type error and a runtime {@link E_INVALID_SEARXNG_CONFIG}; for
+ * dynamic-import resolvers use the async {@link createSearxngSearchTool}. See its docs for the
+ * `number_of_results` caveat and 403/JSON-disabled behaviour.
+ *
+ * @param config - Same as {@link SearxngToolConfig}, with `artifact` restricted to the sync subset.
  * @returns A `Tool` ready to register in a `ToolRegistry`.
- * @throws {@link E_INVALID_SEARXNG_CONFIG} when `instanceUrl` is missing or unparseable.
+ * @throws {@link E_INVALID_SEARXNG_CONFIG} when `instanceUrl` or `artifact` is invalid (incl. an async resolver).
  */
-export declare const createSearxngSearchTool: (config: SearxngToolConfig) => Tool;
+export declare const createSearxngSearchToolSync: (config: SearxngToolConfig<SyncArtifactResolver>) => Tool;

package/batteries/tools/searxng.cjs

@@ -1,5 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 require("../../chunk-Ble4zEEl.js");
-const require_searxng = require("../../searxng-Bkrwhwhw.js");
+const require_searxng = require("../../searxng-B_D--V5q.js");
 exports.E_INVALID_SEARXNG_CONFIG = require_searxng.E_INVALID_SEARXNG_CONFIG;
 exports.createSearxngSearchTool = require_searxng.createSearxngSearchTool;
+exports.createSearxngSearchToolSync = require_searxng.createSearxngSearchToolSync;

package/batteries/tools/searxng.mjs

@@ -1,2 +1,2 @@
-import { n as E_INVALID_SEARXNG_CONFIG, t as createSearxngSearchTool } from "../../searxng-CyA-nEu5.mjs";
-export { E_INVALID_SEARXNG_CONFIG, createSearxngSearchTool };
+import { n as createSearxngSearchToolSync, r as E_INVALID_SEARXNG_CONFIG, t as createSearxngSearchTool } from "../../searxng-BJFulNcK.mjs";
+export { E_INVALID_SEARXNG_CONFIG, createSearxngSearchTool, createSearxngSearchToolSync };

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

@@ -0,0 +1,186 @@
+/**
+ * RAG glue: turn web-search and web-scrape results into `Retrievable` records for a turn.
+ *
+ * @module @nhtio/adk/batteries/tools/web_retrieval
+ *
+ * @remarks
+ * The seam from "I searched / scraped something" to "it is in the turn as a `Retrievable`",
+ * shared by the SearXNG and Scrapper batteries. It is deliberately **decoupled** from the ADK
+ * core at runtime:
+ *
+ * - The converters are **pure** `(payload) => RawRetrievable[]` — they build plain data objects and
+ *   never instantiate a core class, so the module's only core coupling is erased `import type`.
+ * - The recommended spool-artifact type travels as an **open resolver**
+ *   ({@link @nhtio/adk/forge!ArtifactConstructorResolver}), never a closed string enum — a consumer's
+ *   future YAML/HTML `SpooledArtifact` subclass works with no change here. The converter hands the
+ *   recommendation to the caller's `spool` hook; the caller owns the actual class import.
+ * - The one helper that must construct a `Retrievable` ({@link storeRetrievables}) takes the
+ *   constructor via a **resolver** (constructor / sync / async / dynamic-import), exactly like the
+ *   vector battery's `createVectorStore` `client`.
+ *
+ * Web content is `'third-party-public'` by default — a definitional constant for open-web data
+ * (NOT inferred from the URL, which CONTRIBUTING Design Decision #12 forbids); override via
+ * `trustTier` when you know better.
+ */
+import type { SpooledArtifact } from "../../../spooled_artifact";
+import type { ArtifactConstructorResolver } from "../../../forge";
+import type { RawRetrievable, Retrievable, RetrievableTrustTier } from "../../../common";
+/** A constructor that builds a {@link @nhtio/adk!Retrievable} from a {@link @nhtio/adk!RawRetrievable}. */
+export type RetrievableCtor = new (raw: RawRetrievable) => Retrievable;
+/** A resolver of `T`: the value itself, or a (sync/async) thunk, optionally a module `{ default }`. */
+export type Resolver<T> = T | (() => T | {
+    default: T;
+}) | (() => Promise<T | {
+    default: T;
+}>);
+/**
+ * A reader-backed-artifact hook. Called by a converter for content that may be large; the
+ * converter passes the artifact constructor it **recommends** for this content (an open
+ * {@link @nhtio/adk/forge!ArtifactConstructorResolver}) so the caller can wrap with the right
+ * subclass — preserving its forged query tools — using the caller's own core import. Return a
+ * {@link @nhtio/adk!SpooledArtifact} to store the content reader-backed, or `undefined` to keep it
+ * inline as a string.
+ */
+export type SpoolHook = (id: string, text: string, recommended: ArtifactConstructorResolver) => SpooledArtifact | undefined;
+/** Options common to every converter. */
+export interface ToRetrievableOptions {
+    /**
+     * Trust tier for the produced records. Default `'third-party-public'` (web content is
+     * third-party by definition — this is a constant, not URL inference).
+     */
+    trustTier?: RetrievableTrustTier;
+    /** Semantic `kind` label, e.g. `'web-search-result'`, `'web-article'`, `'web-links'`. */
+    kind?: string;
+    /** Prefix for the stable, hashed record id (namespacing across sources). */
+    idPrefix?: string;
+    /** Optional reader-backed-artifact hook for large content. See {@link SpoolHook}. */
+    spool?: SpoolHook;
+}
+/**
+ * The artifact-resolver recommendations a caller may supply so the glue names no concrete class
+ * itself. Each converter asks for the relevant key; if the caller omits it, content stays inline.
+ */
+export interface ArtifactRecommendations {
+    /** Recommended for plain-text / HTML content (base `SpooledArtifact`). */
+    text?: ArtifactConstructorResolver;
+    /** Recommended for markdown content (`SpooledMarkdownArtifact`). */
+    markdown?: ArtifactConstructorResolver;
+    /** Recommended for JSON content (`SpooledJsonArtifact`). */
+    json?: ArtifactConstructorResolver;
+}
+/** Minimal structural shape of a SearXNG normalised result the converter reads. */
+export interface SearxngResultLike {
+    /** Result URL (becomes the record's `source`). */
+    url?: string;
+    /** Result title (joined into the inline content). */
+    title?: string;
+    /** Result snippet (joined into the inline content). */
+    content?: string;
+    /** Relevance score (clamped to `[0,1]` on the record). */
+    score?: number;
+}
+/** Minimal structural shape of a SearXNG normalised payload. */
+export interface SearxngPayloadLike {
+    /** The result list. */
+    results?: SearxngResultLike[];
+}
+/**
+ * Convert a SearXNG normalised payload into one {@link @nhtio/adk!RawRetrievable} per result.
+ *
+ * @remarks
+ * Snippets are short, so `content` stays an inline string (the `spool` hook, if any, is still
+ * offered the `text` recommendation). `source` is the result URL; `score` is clamped to `[0,1]`.
+ *
+ * @param payload - The SearXNG normalised payload (`{ results: [{ url, title, content, score }] }`).
+ * @param opts - Trust tier, kind, id prefix, optional spool hook.
+ * @param recommend - Optional artifact-resolver recommendations (the glue names no class itself).
+ * @returns One `RawRetrievable` per result.
+ */
+export declare const searxngResultsToRetrievables: (payload: SearxngPayloadLike, opts?: ToRetrievableOptions, recommend?: ArtifactRecommendations) => RawRetrievable[];
+/** Minimal structural shape of a Scrapper normalised article. */
+export interface ScrapperArticleLike {
+    /** The page URL (becomes the record's `source`). */
+    url?: string;
+    /** Article title. */
+    title?: string;
+    /** Article text with HTML stripped (the default content source). */
+    textContent?: string;
+    /** Processed article HTML (the `'content'` content source). */
+    content?: string;
+}
+/** Which article text field to use as the record content. */
+export type ArticleContentSource = 'textContent' | 'content';
+/** Options for {@link scrapperArticleToRetrievable}. */
+export interface ArticleToRetrievableOptions extends ToRetrievableOptions {
+    /** Which field to use as content (default `'textContent'`). `'content'` is HTML. */
+    contentSource?: ArticleContentSource;
+    /**
+     * Whether the chosen content is markdown (recommend `markdown`) rather than plain text.
+     * Default false. Use when an output pipeline rendered the article to markdown.
+     */
+    asMarkdown?: boolean;
+}
+/**
+ * Convert a Scrapper normalised article into a single {@link @nhtio/adk!RawRetrievable}.
+ *
+ * @remarks
+ * Long article text is exactly what a reader-backed {@link @nhtio/adk!SpooledArtifact} is for: pass a
+ * `spool` hook and the converter offers it the recommended artifact resolver (markdown when
+ * `asMarkdown`, else text/HTML) so the model gets the right forged query tools. Without a hook,
+ * content stays inline.
+ *
+ * @param article - The Scrapper normalised article.
+ * @param opts - Trust tier, kind, id prefix, content source, markdown flag, optional spool hook.
+ * @param recommend - Optional artifact-resolver recommendations.
+ * @returns A single `RawRetrievable`.
+ */
+export declare const scrapperArticleToRetrievable: (article: ScrapperArticleLike, opts?: ArticleToRetrievableOptions, recommend?: ArtifactRecommendations) => RawRetrievable;
+/** Minimal structural shape of a Scrapper normalised link. */
+export interface ScrapperLinkLike {
+    /** The link's target URL (becomes the record's `source`). */
+    url?: string;
+    /** The link's anchor text (becomes the record's content). */
+    text?: string;
+}
+/** Minimal structural shape of a Scrapper normalised links payload. */
+export interface ScrapperLinksLike {
+    /** The page URL the links were collected from. */
+    url?: string;
+    /** The collected links. */
+    links?: ScrapperLinkLike[];
+}
+/**
+ * Convert a Scrapper normalised links payload into one {@link @nhtio/adk!RawRetrievable} per link.
+ *
+ * @remarks
+ * Each link's `text` becomes the (inline) content and its `url` the `source`. Link text is short,
+ * so no spooling is applied.
+ *
+ * @param payload - The Scrapper normalised links payload (`{ links: [{ url, text }] }`).
+ * @param opts - Trust tier, kind, id prefix.
+ * @returns One `RawRetrievable` per link.
+ */
+export declare const scrapperLinksToRetrievables: (payload: ScrapperLinksLike, opts?: ToRetrievableOptions) => RawRetrievable[];
+/** The minimal context surface {@link storeRetrievables} needs. */
+export interface RetrievableStoreCtx {
+    /** Persist a single `Retrievable` into the turn (a `DispatchContext` method, or a stub). */
+    storeRetrievable: (v: Retrievable) => unknown | Promise<unknown>;
+}
+/**
+ * Construct {@link @nhtio/adk!Retrievable}s from `RawRetrievable`s and store each via `ctx`.
+ *
+ * @remarks
+ * This is the only function here that touches a core class, and it does so through an injected
+ * **resolver** (`deps.retrievable`) so the glue itself never value-imports `Retrievable`. Each
+ * record's `RawRetrievable` validation (including the required `trustTier`) fires at construction.
+ * For reader-backed content, the caller's `spool` hook will typically have used
+ * `ctx.storeRetrievableBytes` already; this helper just persists the records into the turn.
+ *
+ * @param ctx - Anything with a `storeRetrievable` method (a `DispatchContext`, or a stub).
+ * @param raws - The plain records from the converters.
+ * @param deps - `{ retrievable }`: the `Retrievable` constructor or a resolver of it.
+ * @returns The constructed `Retrievable` instances, in input order.
+ */
+export declare const storeRetrievables: (ctx: RetrievableStoreCtx, raws: RawRetrievable[], deps: {
+    retrievable: Resolver<RetrievableCtor>;
+}) => Promise<Retrievable[]>;