@nhtio/adk 1.20260607.2 → 1.20260609.1

package/CHANGELOG.md

@@ -5,6 +5,236 @@ All notable changes to `@nhtio/adk` are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 2026-06-09
+
+### Fixed
+
+- **OpenAI Chat Completions battery now accepts `reasoning_effort: 'none'`.** The request
+  validator constrained `reasoning_effort` to `['minimal', 'low', 'medium', 'high']` and rejects
+  unknown top-level keys (`.unknown(false)`), so there was no way to send `none` — the documented
+  value Ollama's OpenAI-compatible `/v1/chat/completions` needs to turn a thinking model's (e.g.
+  Gemma's) reasoning **off**. `'none'` is now in the enum (and the `reasoning_effort` type union);
+  it flows to the wire through the existing body-assembly passthrough, and the strict-unknown-key
+  protection is unchanged. The WebLLM battery is unaffected — upstream WebLLM has no
+  `reasoning_effort` field and disables thinking via `extra_body.enable_thinking`, already an open
+  passthrough there.
+
+- **OpenAI Chat Completions battery now retries transport failures (HTTP status 0).** When `fetch`
+  rejected before any HTTP response arrived (DNS failure, connection refused, TLS error, socket
+  drop), the adapter immediately `nack`'d with status 0 **without consulting `retry.maxAttempts`** —
+  so a single transient network blip killed the turn even when retries were configured. The
+  transport-failure branch now retries with backoff up to `maxAttempts` before surfacing the error,
+  matching the request-timeout branch beside it and the sibling embeddings adapter. Governed by the
+  existing `retry.maxAttempts` knob; `retriableStatuses` is untouched (it gates HTTP responses,
+  which transport errors never produce).
+
+- **Bundled deterministic tools now do exactly what their descriptions say.** A correctness audit
+  of the 17 deterministic tool batteries (`src/batteries/tools/*`) — driven by a schema-fuzzing
+  invariant harness and two independent model reviews, with every finding verified against the
+  running tool — surfaced a class of defects where a tool would throw an unexpected runtime error,
+  refuse work it advertised, or silently return a wrong value. All are fixed; each tool was changed
+  to meet its label (no description or test was weakened to match broken behaviour):
+  - **`json_transform`** — `top_n` returned the wrong end of the range (comparator inverted; `desc`
+    now returns the largest *n*, `asc` the smallest); `unique_by` never deduplicated object/array
+    key values (reference-identity `Set` → now value-serialised); `sum` over a non-numeric array
+    silently returned `0` (now a clear error); a `null` operation entry crashed the dispatch (now a
+    clean schema rejection).
+  - **`compare_records`** — a nested array and an integer-keyed object (`[1,2]` vs `{"0":1,"1":2}`)
+    were reported equal; they are now distinct.
+  - **`color_contrast` / `color_scheme` / `color_adjust`** — `hexToRgb` accepted hex strings with
+    trailing non-hex characters (`#1Z2Z3Z` → silent `rgb(1,2,3)`); invalid hex is now rejected.
+  - **`string_transform`** — `reverse` split astral characters/emoji into broken surrogate halves
+    (`A💥B` now reverses to `B💥A`); `slug` destroyed non-decomposing Latin-1 letters (`føtex` →
+    `f-tex`), now transliterated (`fotex`).
+  - **`parse_yaml`** — an empty/whitespace/BOM-only document returned a non-string (`undefined`),
+    now `null`; `.NaN` / `.inf` / `-.inf` were silently corrupted to `null`, now preserved.
+  - **`format_table`** — null/primitive rows threw; they now render empty cells or return a clear
+    "provide columns" error.
+  - **`format_list`** — an unbounded `indent` threw `RangeError`; it is now clamped to 100.
+  - **`evaluate_katex`** — scientific notation (`2e3`) misparsed, and `\log_b(x)` change-of-base
+    produced malformed output; both now evaluate correctly.
+  - **`encode_text`** — HTML-entity decoding of astral code points used `String.fromCharCode`
+    (truncating to 16 bits); `🎉` / `🎉` now decode to 🎉 via `String.fromCodePoint`.
+  - **`date_period`** — fiscal-quarter boundaries spanning the calendar-year boundary were computed
+    in the wrong year (e.g. FY-Feb, `2024-01-15` → now correctly `2023-11-01`).
+  - **`convert_unit`** — temperatures below absolute zero are now rejected instead of silently
+    returned.
+  - **`calculate`** — a non-finite scalar result (`1/0`, `2^5000`) now returns a clear error rather
+    than printing `Result: Infinity`.
+
+- **Updated three stale functional tests to the corrected `stats_describe` contract.** The
+  `statistics`/`flydrive` through-runner tests still passed `stats_describe`'s `numbers` as a JSON
+  **string** and asserted numeric `mean`/`sum` — both invalidated by the tool-correctness pass above,
+  which retyped `numbers` to a real array (restoring NaN/∞/`>2^53` rejection) and emits computed
+  aggregates as precision-formatted BigNumber **strings**. The tests now pass actual arrays and
+  assert the string-valued aggregates; no production behaviour changed.
+
+### 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 **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`.
+  - **Two-level output-format control** — `config.resultFormat: 'normalized' | 'raw' | 'either'`
+    (default `'either'`). Pinning it forces the shape AND removes the model-facing `format` arg from
+    the schema; leaving it neutral lets the model choose per call. `normalized` trims each result to
+    `{title,url,content,engine,score,publishedDate}` plus non-empty `answers`/`infoboxes`/
+    `suggestions`/`corrections`; `raw` returns the full SearXNG JSON.
+  - **Input/output middleware pipelines** — `config.inputPipeline` / `config.outputPipeline` are
+    onion middleware `(ctx, next)` built on `@nhtio/middleware`. Input stages mutate the
+    query/params/headers before the request or `ctx.shortCircuit(string)` to skip the fetch (cache
+    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 (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
+    battery-scoped `E_INVALID_SEARXNG_CONFIG` at factory-call time.
+  - Documented as a featured-battery page, with a TypeDoc `@warning` recording the upstream quirk
+    that SearXNG's `number_of_results` is frequently `0` even when results exist
+    ([searxng#2987](https://github.com/searxng/searxng/issues/2987),
+    [searxng#2457](https://github.com/searxng/searxng/issues/2457)) — the tool passes it through
+    verbatim; use `results.length`. Covered by a cross-env unit spec (stubbed `fetch`, all three
+    artifact types round-tripped) and an env-gated live integration spec
+    (`TEST_SEARXNG_URL` / `TEST_SEARXNG_HEADERS`).
+
+- **Documentation-coverage gate (`bin/doc_coverage.ts`, `pnpm run doc:coverage`).** A standalone
+  helper that bootstraps TypeDoc read-only over the same entrypoints the published docs use
+  (`bin/utils/index.ts` `getEntries`) and reports every public API symbol missing a TSDoc comment,
+  grouped by its deepest `@module` submodule. Modes: a human report (default), `--json`, `--ci`
+  (non-zero exit when any non-allowlisted symbol is undocumented — wired into CI as a job, currently
+  `allow_failure: true`), `--hook` (emits a Claude Code `additionalContext` envelope and always exits
+  0), and `--primary` (audits `@primaryExport` placement). The shared `blockTags` list moved to an
+  exported `BLOCK_TAGS` const so the helper and `makeApiDocs` never drift. **The entire public API
+  surface is now documented — the gate reports zero undocumented symbols.** Every interface,
+  type, class member, options field, wire shape, and exported function across the LLM, vector,
+  embeddings, storage, and ESLint-rule batteries carries an accurate TSDoc comment.
+
+  The API-doc build is also link-clean: every TypeDoc cross-reference now resolves. Types that
+  documented symbols referenced but that were not themselves exported are now public —
+  `ArtifactConstructorResolver` (`@nhtio/adk/forge`), the four `DispatchRetrievable*Fn` callback
+  types (`@nhtio/adk/types`), and the pgvector / sqlite-vec adapter options interfaces, renamed for
+  consistency with the other 24 adapters to `PgVectorStoreOptions` and
+  `SqliteVecVectorStoreOptions`. Vendor types referenced in comments (`BigNumber`, `Set`, `Disk`)
+  now link to their upstream docs via `externalSymbolLinkMappings`, and broken `{@link}` targets
+  (wrong or non-exported names) were corrected. The internal, sentinel-gated `DispatchRunner`
+  constructor is marked `@internal` (construct via the static `DispatchRunner.dispatch`).
+
+- **Native Ollama LLM battery (`@nhtio/adk/batteries/llm/ollama`).** Ships `OllamaAdapter`, an
+  executor targeting Ollama's **native `/api/chat`** endpoint — distinct from pointing the OpenAI
+  Chat Completions battery at `/v1`, which it complements rather than replaces. Works with both
+  local Ollama (`http://localhost:11434`, no auth — the default `baseURL`) and cloud Ollama
+  (`https://ollama.com`, `apiKey` → `Authorization: Bearer`); only `baseURL` plus the auth header
+  differ. Native-only capabilities the `/v1` compat layer cannot express are first-class: per-request
+  context size via the nested `options.num_ctx`, native reasoning via `think`
+  (`boolean | 'low' | 'medium' | 'high'`) surfaced as `message.thinking`, structured output via
+  `format` (`'json'` or a JSON schema), and model lifecycle via `keep_alive`. Generation params live
+  in a nested `options` block (not at the top level, unlike the OpenAI wire). The adapter parses
+  NDJSON streaming (terminated by `done: true`, no `[DONE]` sentinel), takes tool-call `arguments` as
+  a JSON object (no `JSON.parse`), labels tool-result history messages with `tool_name` (not
+  `tool_call_id`), and follows every cross-battery design rule (trust-framed envelopes, per-tool
+  trust, swappable helpers, `ctx.stash.ollama` per-iteration overrides, `ToolCall.inline` handling,
+  trust-tier-distinct buckets). Native `/api/chat` carries images only; other modalities route
+  through `unsupportedMediaPolicy`. `tool_choice` is intentionally unsupported (native `/api/chat`
+  has no such field). Ollama is HTTP-only — Unix-socket deployments are reached via a bridge or a
+  custom `fetch`.
+
+- **Dedicated generation-stats observability channel on `DispatchRunner`.** Executors can emit
+  provider-agnostic generation accounting (token counts, nanosecond durations, finish reason, model,
+  provider, plus the raw provider object) via a new `helpers.reportGenerationStats(stats)` method;
+  the runner enriches each record with `dispatchId` / `iteration` / `emittedAt` and fires it on a new
+  `generationStats` observability hook (subscribe through `observers.generationStats`). This is
+  additive and non-breaking — `DispatchExecutorHelpers` is runner-produced, so existing executors
+  gain the method without change. The native Ollama battery emits its terminal-chunk stats through
+  this channel; the new `GenerationStats` / `GenerationStatsEvent` types are exported from
+  `@nhtio/adk/dispatch_runner`.
+
+- **Shared Chat-family helper submodule.** The wire-shape-agnostic translation helpers (trust
+  envelopes, memory/retrievable/standing-instruction rendering, system-prompt assembly, JSON-schema
+  and function-tool conversion, thought filtering) were extracted to an internal
+  `src/batteries/llm/chat_common` module shared by the OpenAI Chat Completions and native Ollama
+  batteries. Behaviour-preserving: every existing `@nhtio/adk/batteries/llm/openai_chat_completions`
+  helper export keeps its name and value identity (the battery re-exports the shared names), and the
+  WebLLM battery is untouched. The shared module is internal — not a public package subpath.
+
+- **NDJSON cassette support in the cross-env test harness.** `tests/_fixtures/cassette.ts` gained an
+  `ndjson` response mode (parallel to the existing SSE `sse` mode) plus Ollama-native programmatic
+  builders (`buildOllamaChatResponse`, `buildOllamaStreamFrames`, `singleOllamaResponseCassette`,
+  `singleOllamaStreamCassette`) for deterministic native-wire replay.
+
+- **Arbitrary-precision numeric handling across the math tools.** A shared
+  `src/lib/helpers/bignum.ts` (a BigNumber-configured `mathjs` instance) backs the numeric
+  batteries so float64 limitations no longer corrupt results: large in-range sums stay exact
+  instead of overflowing to `Infinity`, tiny ratios don't underflow to `0`, and precision is
+  preserved end-to-end (`sum([0.1, 0.2]) → 0.3`). `statistics`, `data_structure`, and
+  `unit_conversion` now compute aggregates/conversions through it. The `statistics` tools take
+  typed number arrays (`validator.array().items(validator.number())`) instead of JSON strings —
+  restoring schema rejection of `NaN`/`Infinity`/`> 2^53` at the boundary and removing the prior
+  silent-drop behaviour. Tools that format numeric output gained an optional `precision` argument
+  (significant digits, default 8). **This changes those tool signatures and some output shapes**
+  (computed aggregates may be precision-formatted strings).
+
+- **Tool correctness test infrastructure.** A `callTool` helper in
+  `tests/_fixtures/tool_ctx_stub.ts` captures a tool invocation's resolve-vs-throw outcome as a
+  value (making the no-crash contract directly assertable), and a new
+  `tests/unit/batteries/tools/fuzz.node.spec.ts` invariant harness introspects every bundled tool's
+  schema, feeds adversarial input, and asserts each call either resolves to a string/`Uint8Array`
+  or rejects with `E_INVALID_TOOL_ARGS` — never any other throw.
+
 ## 2026-06-07
 
 ### Added

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-DYUYqXvo.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-D1pSSlsd.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/openai/exceptions.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 require("../../../chunk-Ble4zEEl.js");
-const require_exceptions = require("../../../exceptions-CitH5wZI.js");
+const require_exceptions = require("../../../exceptions-BRXrUKiW.js");
 require("../../../factories.cjs");
 //#region src/batteries/embeddings/openai/exceptions.ts
 /**

package/batteries/embeddings/openai/exceptions.mjs

@@ -1,4 +1,4 @@
-import { t as createException } from "../../../exceptions-BeWH2FwP.mjs";
+import { t as createException } from "../../../exceptions-BDhN0Xzr.mjs";
 import "../../../factories.mjs";
 //#region src/batteries/embeddings/openai/exceptions.ts
 /**

package/batteries/embeddings/openai/types.d.ts

@@ -105,19 +105,26 @@ export interface OpenAIEmbeddingsAdapterOptions extends BaseEmbeddingsAdapterOpt
  * The JSON request body POSTed to `/v1/embeddings`.
  */
 export interface OpenAIEmbeddingsRequestBody {
+    /** ID of the embedding model to use. */
     model: string;
+    /** The batch of texts to embed. */
     input: string[];
+    /** Wire encoding for the returned vectors; always `'float'`. */
     encoding_format: 'float';
+    /** Optional output dimensionality for models that support truncation. */
     dimensions?: number;
 }
 /**
  * The relevant subset of the `/v1/embeddings` JSON response shape.
  */
 export interface OpenAIEmbeddingsResponseBody {
+    /** The embedding vectors, each tagged with its input `index`. */
     data: Array<{
         embedding: number[];
         index: number;
     }>;
+    /** Model that produced the embeddings. */
     model?: string;
+    /** Object type reported by the API (e.g. `'list'`). */
     object?: string;
 }

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-DYUYqXvo.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-D1pSSlsd.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/embeddings/webllm/exceptions.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 require("../../../chunk-Ble4zEEl.js");
-const require_exceptions = require("../../../exceptions-CitH5wZI.js");
+const require_exceptions = require("../../../exceptions-BRXrUKiW.js");
 require("../../../factories.cjs");
 //#region src/batteries/embeddings/webllm/exceptions.ts
 /**

package/batteries/embeddings/webllm/exceptions.mjs

@@ -1,4 +1,4 @@
-import { t as createException } from "../../../exceptions-BeWH2FwP.mjs";
+import { t as createException } from "../../../exceptions-BDhN0Xzr.mjs";
 import "../../../factories.mjs";
 //#region src/batteries/embeddings/webllm/exceptions.ts
 /**

package/batteries/llm/chat_common/helpers.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Wire-shape-agnostic translation helpers shared across the Chat-family LLM batteries.
+ *
+ * @remarks
+ * INTERNAL to the bundled LLM batteries — intentionally **not** `@module`-tagged, so it stays a
+ * private, inlined module (see the note in `./types`). These helpers turn ADK primitives into
+ * plain strings (or the family-identical JSON Schema / function-tool wire), independent of any
+ * single battery's message-object shape. The OpenAI Chat Completions battery and the native Ollama
+ * battery both re-export every name here from their own `helpers.ts` barrels (each under its
+ * unprefixed name AND a `default*` alias) so consumer override composition is unchanged.
+ *
+ * Helpers that compose other helpers receive their dependents via explicit `deps` arguments typed
+ * against {@link ChatHelpersCommon} — never against a battery-specific helper bag — so this module
+ * carries no import edge back to any individual battery.
+ */
+import type { Tool, ArtifactTool, Tokenizable, Memory, Thought, Retrievable } from "../../../common";
+import type { ChatCompletionsBucketOrder, ChatCompletionsTool, DescriptionLike, JsonSchema, MemoryAttrs, RetrievableAttrs, StandingInstructionAttrs, ThoughtAttrs, TrustedContentAttrs, UntrustedContentAttrs, ChatHelpersCommon } from "./types";
+export declare const escapeXmlAttribute: (value: string) => string;
+export declare const memoryToAttrs: (m: Memory) => {
+    memory: Memory;
+    attrs: MemoryAttrs;
+};
+export declare const retrievableToAttrs: (r: Retrievable) => {
+    retrievable: Retrievable;
+    attrs: RetrievableAttrs;
+};
+export declare const sanitiseNameField: (raw: string) => string;
+/** Implements {@link ChatHelpersCommon.descriptionToChatCompletionsJsonSchema}. */
+export declare const descriptionToChatCompletionsJsonSchema: (d: DescriptionLike) => JsonSchema;
+/** Default JSON-Schema renderer; alias of {@link descriptionToChatCompletionsJsonSchema}. */
+export declare const defaultDescriptionToChatCompletionsJsonSchema: (d: DescriptionLike) => JsonSchema;
+/** Implements {@link ChatHelpersCommon.renderUntrustedContent}. */
+export declare const renderUntrustedContent: (content: string, attrs: UntrustedContentAttrs) => string;
+/** Default untrusted-content renderer; alias of {@link renderUntrustedContent}. */
+export declare const defaultRenderUntrustedContent: (content: string, attrs: UntrustedContentAttrs) => string;
+/** Implements {@link ChatHelpersCommon.renderTrustedContent}. */
+export declare const renderTrustedContent: (content: string, attrs: TrustedContentAttrs) => string;
+/** Default trusted-content renderer; alias of {@link renderTrustedContent}. */
+export declare const defaultRenderTrustedContent: (content: string, attrs: TrustedContentAttrs) => string;
+/** Implements {@link ChatHelpersCommon.renderStandingInstructions}. */
+export declare const renderStandingInstructions: (items: Iterable<Tokenizable>, attrs?: StandingInstructionAttrs) => string;
+/** Default standing-instructions renderer; alias of {@link renderStandingInstructions}. */
+export declare const defaultRenderStandingInstructions: (items: Iterable<Tokenizable>, attrs?: StandingInstructionAttrs) => string;
+/** Implements {@link ChatHelpersCommon.renderMemories}. */
+export declare const renderMemories: (items: Iterable<{
+    memory: Memory;
+    attrs: MemoryAttrs;
+}>) => string;
+/** Default memories renderer; alias of {@link renderMemories}. */
+export declare const defaultRenderMemories: (items: Iterable<{
+    memory: Memory;
+    attrs: MemoryAttrs;
+}>) => string;
+/** Implements {@link ChatHelpersCommon.renderRetrievableSafetyDirective}. */
+export declare const renderRetrievableSafetyDirective: () => string;
+/** Default safety-directive renderer; alias of {@link renderRetrievableSafetyDirective}. */
+export declare const defaultRenderRetrievableSafetyDirective: () => string;
+/** Implements {@link ChatHelpersCommon.renderFirstPartyRetrievables}. */
+export declare const renderFirstPartyRetrievables: (items: Iterable<{
+    retrievable: Retrievable;
+    attrs: RetrievableAttrs;
+}>) => Promise<string>;
+/** Default first-party retrievables renderer; alias of {@link renderFirstPartyRetrievables}. */
+export declare const defaultRenderFirstPartyRetrievables: (items: Iterable<{
+    retrievable: Retrievable;
+    attrs: RetrievableAttrs;
+}>) => Promise<string>;
+/** Implements {@link ChatHelpersCommon.renderThirdPartyPublicRetrievables}. */
+export declare const renderThirdPartyPublicRetrievables: (items: Iterable<{
+    retrievable: Retrievable;
+    attrs: RetrievableAttrs;
+}>, deps: {
+    renderUntrustedContent: ChatHelpersCommon["renderUntrustedContent"];
+}) => Promise<string>;
+/** Default third-party-public retrievables renderer; alias of {@link renderThirdPartyPublicRetrievables}. */
+export declare const defaultRenderThirdPartyPublicRetrievables: (items: Iterable<{
+    retrievable: Retrievable;
+    attrs: RetrievableAttrs;
+}>, deps: {
+    renderUntrustedContent: ChatHelpersCommon["renderUntrustedContent"];
+}) => Promise<string>;
+/** Implements {@link ChatHelpersCommon.renderThirdPartyPrivateRetrievables}. */
+export declare const renderThirdPartyPrivateRetrievables: (items: Iterable<{
+    retrievable: Retrievable;
+    attrs: RetrievableAttrs;
+}>, deps: {
+    renderUntrustedContent: ChatHelpersCommon["renderUntrustedContent"];
+}) => Promise<string>;
+/** Default third-party-private retrievables renderer; alias of {@link renderThirdPartyPrivateRetrievables}. */
+export declare const defaultRenderThirdPartyPrivateRetrievables: (items: Iterable<{
+    retrievable: Retrievable;
+    attrs: RetrievableAttrs;
+}>, deps: {
+    renderUntrustedContent: ChatHelpersCommon["renderUntrustedContent"];
+}) => Promise<string>;
+/** Implements {@link ChatHelpersCommon.renderRetrievables}. */
+export declare const renderRetrievables: (items: Iterable<{
+    retrievable: Retrievable;
+    attrs: RetrievableAttrs;
+}>, deps: {
+    renderRetrievableSafetyDirective: ChatHelpersCommon["renderRetrievableSafetyDirective"];
+    renderFirstPartyRetrievables: ChatHelpersCommon["renderFirstPartyRetrievables"];
+    renderThirdPartyPublicRetrievables: ChatHelpersCommon["renderThirdPartyPublicRetrievables"];
+    renderThirdPartyPrivateRetrievables: ChatHelpersCommon["renderThirdPartyPrivateRetrievables"];
+    renderUntrustedContent: ChatHelpersCommon["renderUntrustedContent"];
+}) => Promise<string>;
+/** Default retrievables orchestrator; alias of {@link renderRetrievables}. */
+export declare const defaultRenderRetrievables: (items: Iterable<{
+    retrievable: Retrievable;
+    attrs: RetrievableAttrs;
+}>, deps: {
+    renderRetrievableSafetyDirective: ChatHelpersCommon["renderRetrievableSafetyDirective"];
+    renderFirstPartyRetrievables: ChatHelpersCommon["renderFirstPartyRetrievables"];
+    renderThirdPartyPublicRetrievables: ChatHelpersCommon["renderThirdPartyPublicRetrievables"];
+    renderThirdPartyPrivateRetrievables: ChatHelpersCommon["renderThirdPartyPrivateRetrievables"];
+    renderUntrustedContent: ChatHelpersCommon["renderUntrustedContent"];
+}) => Promise<string>;
+/** Implements {@link ChatHelpersCommon.renderThought}. */
+export declare const renderThought: (content: string, attrs: ThoughtAttrs, payload?: unknown) => string;
+/** Default thought renderer; alias of {@link renderThought}. */
+export declare const defaultRenderThought: (content: string, attrs: ThoughtAttrs, payload?: unknown) => string;
+/** Implements {@link ChatHelpersCommon.filterThoughts}. */
+export declare const filterThoughts: (thoughts: Iterable<Thought>, mode: "all-self" | "latest-self" | "all", selfIdentity: string, replayCompatibility: ReadonlyArray<string>) => Thought[];
+/** Default thought filter; alias of {@link filterThoughts}. */
+export declare const defaultFilterThoughts: (thoughts: Iterable<Thought>, mode: "all-self" | "latest-self" | "all", selfIdentity: string, replayCompatibility: ReadonlyArray<string>) => Thought[];
+/** Implements {@link ChatHelpersCommon.toolsToChatCompletionsTools}. */
+export declare const toolsToChatCompletionsTools: (tools: ReadonlyArray<Tool | ArtifactTool>, deps: {
+    descriptionToChatCompletionsJsonSchema: (d: DescriptionLike) => JsonSchema;
+}) => ChatCompletionsTool[];
+/** Default tool-translation helper; alias of {@link toolsToChatCompletionsTools}. */
+export declare const defaultToolsToChatCompletionsTools: (tools: ReadonlyArray<Tool | ArtifactTool>, deps: {
+    descriptionToChatCompletionsJsonSchema: (d: DescriptionLike) => JsonSchema;
+}) => ChatCompletionsTool[];
+/** Implements {@link ChatHelpersCommon.renderChatCompletionsSystemPrompt}. */
+export declare const renderChatCompletionsSystemPrompt: (input: {
+    systemPrompt: Tokenizable;
+    standingInstructions: Iterable<Tokenizable>;
+    memories: Iterable<Memory>;
+    retrievables: Iterable<Retrievable>;
+    bucketOrder: ChatCompletionsBucketOrder;
+    renderStandingInstructions: ChatHelpersCommon["renderStandingInstructions"];
+    renderMemories: ChatHelpersCommon["renderMemories"];
+    renderRetrievables: ChatHelpersCommon["renderRetrievables"];
+    renderRetrievableSafetyDirective: ChatHelpersCommon["renderRetrievableSafetyDirective"];
+    renderFirstPartyRetrievables: ChatHelpersCommon["renderFirstPartyRetrievables"];
+    renderThirdPartyPublicRetrievables: ChatHelpersCommon["renderThirdPartyPublicRetrievables"];
+    renderThirdPartyPrivateRetrievables: ChatHelpersCommon["renderThirdPartyPrivateRetrievables"];
+    renderUntrustedContent: ChatHelpersCommon["renderUntrustedContent"];
+}) => Promise<string>;
+/** Default system-prompt renderer; alias of {@link renderChatCompletionsSystemPrompt}. */
+export declare const defaultRenderChatCompletionsSystemPrompt: (input: {
+    systemPrompt: Tokenizable;
+    standingInstructions: Iterable<Tokenizable>;
+    memories: Iterable<Memory>;
+    retrievables: Iterable<Retrievable>;
+    bucketOrder: ChatCompletionsBucketOrder;
+    renderStandingInstructions: ChatHelpersCommon["renderStandingInstructions"];
+    renderMemories: ChatHelpersCommon["renderMemories"];
+    renderRetrievables: ChatHelpersCommon["renderRetrievables"];
+    renderRetrievableSafetyDirective: ChatHelpersCommon["renderRetrievableSafetyDirective"];
+    renderFirstPartyRetrievables: ChatHelpersCommon["renderFirstPartyRetrievables"];
+    renderThirdPartyPublicRetrievables: ChatHelpersCommon["renderThirdPartyPublicRetrievables"];
+    renderThirdPartyPrivateRetrievables: ChatHelpersCommon["renderThirdPartyPrivateRetrievables"];
+    renderUntrustedContent: ChatHelpersCommon["renderUntrustedContent"];
+}) => Promise<string>;