@nhtio/adk 1.20260607.2 → 1.20260609.0

package/lib/classes/spooled_markdown_artifact.d.ts

@@ -41,6 +41,7 @@ export interface MarkdownCodeEntry {
  * requests it via `cat(bodyStartLine, bodyEndLine + 1)`.
  */
 export interface MarkdownSection {
+    /** ATX heading depth: 1 (`#`) through 6 (`######`). */
     depth: 1 | 2 | 3 | 4 | 5 | 6;
     /** The heading text. */
     heading: string;

package/lib/classes/tokenizable.d.ts

@@ -54,6 +54,7 @@ export type TokenEncoding = (typeof TokenEncoding)[number];
  */
 export declare class Tokenizable {
     #private;
+    /** The set of supported token-encoding identifiers, re-exposed as a static for convenience. */
     static TokenEncoding: readonly [
         "gpt2",
         "r50k_base",
@@ -77,7 +78,9 @@ export declare class Tokenizable {
     toString: () => string;
     valueOf: () => string;
     toLocaleString: () => string;
+    /** Replace the wrapped string value (and invalidate the cached token estimates). */
     set: (value: string) => void;
+    /** Estimate the token count of the wrapped string under the given {@link TokenEncoding}. */
     estimateTokens: (encoding: TokenEncoding) => number;
     /**
      * @param value - The initial string value to wrap.

package/lib/classes/tool.d.ts

@@ -164,13 +164,21 @@ export declare class Tool<A extends SpooledArtifact = SpooledArtifact> {
      * @returns `true` when `value` is a {@link Tool} instance.
      */
     static isTool(value: unknown): value is Tool;
+    /** The tool's unique name, as exposed to the model in the tool definition. */
     readonly name: string;
+    /** Human/model-facing description of what the tool does. */
     readonly description: string;
+    /** Validation schema for the tool's arguments; also drives the generated parameter definition. */
     readonly inputSchema: Schema;
+    /** Resolver for the artifact constructor used to wrap the handler's output, if any. */
     readonly artifactConstructor: ArtifactConstructorResolver<A> | undefined;
+    /** Arbitrary per-tool metadata registry, passed through to the handler. */
     readonly meta: Registry;
+    /** When `true`, the tool's results are not persisted to history (transient/one-shot). */
     readonly ephemeral: boolean;
+    /** When `true`, the tool's output is treated as trusted content by the LLM battery's envelopes. */
     readonly trusted: boolean;
+    /** How registration resolves a name clash in a {@link ToolRegistry}: throw, replace, or keep the existing. */
     readonly onCollision: 'throw' | 'replace' | 'keep';
     /**
      * @param raw - The raw tool input validated against `rawToolSchema`.

package/lib/classes/turn_gate.d.ts

@@ -63,11 +63,17 @@ export declare class TurnGate<T = unknown> {
      * @returns `true` when `value` is a {@link TurnGate} instance.
      */
     static isTurnGate(value: unknown): value is TurnGate;
+    /** Unique identifier for this gate instance. */
     readonly id: string;
+    /** Id of the turn this gate belongs to. */
     readonly turnId: string;
+    /** Human-readable reason the gate was opened. */
     readonly reason: string;
+    /** Optional caller-supplied payload describing what the gate is waiting on. */
     readonly payload: unknown;
+    /** When the gate was created. */
     readonly createdAt: DateTime;
+    /** Whether the gate has been settled (resolved or rejected) and no longer blocks the turn. */
     readonly isSettled: boolean;
     /**
      * @param raw - The raw gate input validated against `rawTurnGateSchema`.

package/lib/dispatch_runner.d.ts

@@ -35,40 +35,13 @@ export interface RawDispatchRunnerInput {
     observers?: DispatchRunnerObservabilityHookRegistrations;
 }
 /**
- * Orchestrates a single LLM execution dispatch — input pipeline → executor → output pipeline —
- * looped until middleware/executor signals completion via {@link @nhtio/adk!DispatchContext.ack} /
- * {@link @nhtio/adk!DispatchContext.nack} or the abort signal fires.
- *
- * @remarks
- * `DispatchRunner` has a private constructor and is invoked via the static `dispatch()`
- * method. Each dispatch creates a fresh single-use runner that is garbage-collected after the
- * call completes — matching the `@nhtio/hooks` GC rationale already baked into the context.
- *
- * The runner owns the relationship between an {@link @nhtio/adk!DispatchContext} and its parent
- * {@link @nhtio/adk!TurnContext} (when given a source). It subscribes to the context's mutation hooks,
- * queues `ContextDelta` entries, and flushes them to the parent's Sets at the end of every
- * iteration. Emits propagate from the context's hooks → the runner's hooks → (optionally) the
- * parent `TurnContext`'s emit methods → the `TurnRunner`'s buses.
- *
- * Two hook buses, mirroring `TurnRunner`'s pattern:
- *
- * - **Functional** (`hooks`): `message`, `thought`, `toolCall` — pipeline-affecting events
- * - **Observability** (`observers`): `iterationStart`, `iterationEnd`, `dispatchStart`,
- *   `dispatchEnd`, `error`, `toolExecutionStart`, `toolExecutionEnd` — instrumentation only
- *
- * The runner has no `maxIterations`, no `maxToolCallChecksumRepeats`. Implementers use the
- * primitives — `ctx.iteration`, `ctx.toolCallCount(checksum)`, `ctx.ack()`, `ctx.nack()`,
- * `ctx.abortSignal` — to build any termination bounds they need in their own middleware.
- */
-/**
- * Module-private token gating direct construction of {@link DispatchRunner}. Callers must use
- * {@link DispatchRunner.dispatch}; the symbol is not exported, so external code cannot satisfy
- * the guard at runtime.
+ * Runs a single dispatch iteration of an agentic turn: it drives the executor through the
+ * input/output middleware pipelines, emitting functional and observability hook events along the
+ * way. Construction is gated — obtain one via the static {@link DispatchRunner.dispatch} entry
+ * point rather than `new`.
  */
-declare const CONSTRUCT_TOKEN: unique symbol;
 export declare class DispatchRunner {
     #private;
-    constructor(token: typeof CONSTRUCT_TOKEN, sourceCtx: TurnContext | undefined, turnInputPipeline: DispatchPipelineMiddlewareFn[], turnOutputPipeline: DispatchPipelineMiddlewareFn[], hooks: DispatchRunnerFunctionalHookRegistrations | undefined, observers: DispatchRunnerObservabilityHookRegistrations | undefined);
     /**
      * Returns `true` if `value` is a {@link DispatchRunner} instance.
      *
@@ -95,4 +68,3 @@ export declare class DispatchRunner {
      */
     static dispatch(input: RawDispatchRunnerInput): Promise<void>;
 }
-export {};

package/lib/helpers/bignum.cjs

@@ -0,0 +1,82 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+require("../../chunk-Ble4zEEl.js");
+let mathjs = require("mathjs");
+//#region src/lib/helpers/bignum.ts
+/**
+* Arbitrary-precision numeric helpers for the bundled tools.
+*
+* @module @nhtio/adk/lib/helpers/bignum
+*
+* @remarks
+* ECMAScript numbers are IEEE-754 float64: arithmetic on user-supplied values can overflow to
+* `Infinity`, underflow to `0`, or silently lose precision (`0.1 + 0.2 === 0.30000000000000004`).
+* The numeric tool batteries (`statistics`, `data_structure`, `unit_conversion`, `math`) route
+* their aggregations and result formatting through this module so that:
+*
+* - large in-range sums stay exact instead of overflowing (`sum([1e308, 1e308]) → 2e308`),
+* - precision is preserved end-to-end (`sum([0.1, 0.2]) → 0.3`),
+* - output is rendered to a caller-chosen number of significant digits (default 8) without the
+*   lossy `Number.prototype.toPrecision`/`toFixed` round-trip that mangles even safe integers
+*   (e.g. `9007199254740991` rendered as `9007199255000`).
+*
+* Internally this is backed by a single {@link https://mathjs.org | mathjs} instance configured
+* for `BigNumber` (which bundles `decimal.js`) at 64 significant digits — comfortably more than
+* float64's ~15-17 and enough for the tools' needs without unbounded growth.
+*
+* The tools still RECEIVE float64 numbers (the model's tool-call arguments are JSON-parsed to
+* float64 upstream, and the typed-array input schemas reject `NaN`/`Infinity`/`> 2^53` before the
+* handler runs). BigNumber's job is the math and formatting in between, not the input boundary.
+*/
+/**
+* Precision (significant digits) the internal BigNumber engine computes with. Distinct from the
+* per-call display precision passed to {@link formatBig} — this is the working precision so that
+* intermediate results don't accumulate rounding error before they are formatted down.
+*/
+var WORKING_PRECISION = 64;
+/** Default display precision (significant digits) for tool output. */
+var DEFAULT_PRECISION = 8;
+var math = (0, mathjs.create)(mathjs.all, {
+	number: "BigNumber",
+	precision: WORKING_PRECISION
+});
+/** Coerce a JS number to a {@link BigNumber}. Non-finite inputs are a caller bug (schemas reject them). */
+var toBig = (n) => math.bignumber(n);
+/** Exact sum of a numeric array as a {@link BigNumber} (no float64 overflow/precision loss). */
+var bigSum = (nums) => nums.reduce((acc, n) => math.add(acc, math.bignumber(n)), math.bignumber(0));
+/** Exact arithmetic mean as a {@link BigNumber}. Caller guarantees `nums.length > 0`. */
+var bigMean = (nums) => math.divide(bigSum(nums), nums.length);
+/** `value * fromFactor / toFactor` computed without intermediate float64 over/underflow. */
+var bigScale = (value, fromFactor, toFactor) => math.divide(math.multiply(math.bignumber(value), math.bignumber(fromFactor)), math.bignumber(toFactor));
+/**
+* Render a {@link BigNumber} (or JS number) to a string at `precision` significant digits.
+*
+* @remarks
+* - An EXACT INTEGER is rendered in full fixed notation regardless of `precision`: an integer
+*   carries no fractional precision to lose, so `8000000000000` stays `8000000000000` rather than
+*   being truncated to `8e+12`. (Bounded at 30 digits to avoid pathological astronomically-large
+*   integers printing thousands of characters; beyond that, sig-fig exponential is used.)
+* - Non-integers are rendered at `precision` significant digits (default 8), stripping trailing
+*   zeros — avoiding the `toPrecision` artifact that mangled safe values, while still giving the
+*   caller control over how many digits they want (raise `precision` for more).
+* - Exact zero renders as `'0'`. (Genuinely tiny values like `2.54e-5` are preserved, NOT snapped.)
+*/
+var formatBig = (value, precision = 8) => {
+	const b = typeof value === "number" ? math.bignumber(value) : value;
+	if (math.equal(b, 0)) return "0";
+	const p = Number.isFinite(precision) ? Math.max(1, Math.min(64, Math.floor(precision))) : 8;
+	const fixed = math.format(b, { notation: "fixed" });
+	if (!fixed.includes(".") && fixed.replace("-", "").length <= 31) return fixed;
+	return math.format(b, { precision: p });
+};
+/** Convert a {@link BigNumber} back to a JS number (for cases that must hand off a float64). */
+var bigToNumber = (b) => math.number(b);
+//#endregion
+exports.DEFAULT_PRECISION = DEFAULT_PRECISION;
+exports.bigMean = bigMean;
+exports.bigScale = bigScale;
+exports.bigSum = bigSum;
+exports.bigToNumber = bigToNumber;
+exports.formatBig = formatBig;
+exports.toBig = toBig;
+
+//# sourceMappingURL=bignum.cjs.map

package/lib/helpers/bignum.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"bignum.cjs","names":[],"sources":["../../../src/lib/helpers/bignum.ts"],"sourcesContent":["/**\n * Arbitrary-precision numeric helpers for the bundled tools.\n *\n * @module @nhtio/adk/lib/helpers/bignum\n *\n * @remarks\n * ECMAScript numbers are IEEE-754 float64: arithmetic on user-supplied values can overflow to\n * `Infinity`, underflow to `0`, or silently lose precision (`0.1 + 0.2 === 0.30000000000000004`).\n * The numeric tool batteries (`statistics`, `data_structure`, `unit_conversion`, `math`) route\n * their aggregations and result formatting through this module so that:\n *\n * - large in-range sums stay exact instead of overflowing (`sum([1e308, 1e308]) → 2e308`),\n * - precision is preserved end-to-end (`sum([0.1, 0.2]) → 0.3`),\n * - output is rendered to a caller-chosen number of significant digits (default 8) without the\n *   lossy `Number.prototype.toPrecision`/`toFixed` round-trip that mangles even safe integers\n *   (e.g. `9007199254740991` rendered as `9007199255000`).\n *\n * Internally this is backed by a single {@link https://mathjs.org | mathjs} instance configured\n * for `BigNumber` (which bundles `decimal.js`) at 64 significant digits — comfortably more than\n * float64's ~15-17 and enough for the tools' needs without unbounded growth.\n *\n * The tools still RECEIVE float64 numbers (the model's tool-call arguments are JSON-parsed to\n * float64 upstream, and the typed-array input schemas reject `NaN`/`Infinity`/`> 2^53` before the\n * handler runs). BigNumber's job is the math and formatting in between, not the input boundary.\n */\n\nimport { create, all, type BigNumber } from 'mathjs'\n\n/**\n * Precision (significant digits) the internal BigNumber engine computes with. Distinct from the\n * per-call display precision passed to {@link formatBig} — this is the working precision so that\n * intermediate results don't accumulate rounding error before they are formatted down.\n */\nconst WORKING_PRECISION = 64\n\n/** Default display precision (significant digits) for tool output. */\nexport const DEFAULT_PRECISION = 8\n\nconst math = create(all, { number: 'BigNumber', precision: WORKING_PRECISION })\n\n/** Coerce a JS number to a {@link BigNumber}. Non-finite inputs are a caller bug (schemas reject them). */\nexport const toBig = (n: number): BigNumber => math.bignumber(n)\n\n/** Exact sum of a numeric array as a {@link BigNumber} (no float64 overflow/precision loss). */\nexport const bigSum = (nums: number[]): BigNumber =>\n  nums.reduce<BigNumber>((acc, n) => math.add(acc, math.bignumber(n)), math.bignumber(0))\n\n/** Exact arithmetic mean as a {@link BigNumber}. Caller guarantees `nums.length > 0`. */\nexport const bigMean = (nums: number[]): BigNumber =>\n  math.divide(bigSum(nums), nums.length) as BigNumber\n\n/** `value * fromFactor / toFactor` computed without intermediate float64 over/underflow. */\nexport const bigScale = (value: number, fromFactor: number, toFactor: number): BigNumber =>\n  math.divide(\n    math.multiply(math.bignumber(value), math.bignumber(fromFactor)),\n    math.bignumber(toFactor)\n  ) as BigNumber\n\n/**\n * Render a {@link BigNumber} (or JS number) to a string at `precision` significant digits.\n *\n * @remarks\n * - An EXACT INTEGER is rendered in full fixed notation regardless of `precision`: an integer\n *   carries no fractional precision to lose, so `8000000000000` stays `8000000000000` rather than\n *   being truncated to `8e+12`. (Bounded at 30 digits to avoid pathological astronomically-large\n *   integers printing thousands of characters; beyond that, sig-fig exponential is used.)\n * - Non-integers are rendered at `precision` significant digits (default 8), stripping trailing\n *   zeros — avoiding the `toPrecision` artifact that mangled safe values, while still giving the\n *   caller control over how many digits they want (raise `precision` for more).\n * - Exact zero renders as `'0'`. (Genuinely tiny values like `2.54e-5` are preserved, NOT snapped.)\n */\nexport const formatBig = (\n  value: BigNumber | number,\n  precision: number = DEFAULT_PRECISION\n): string => {\n  const b = typeof value === 'number' ? math.bignumber(value) : value\n  if (math.equal(b, 0)) return '0'\n  const p = Number.isFinite(precision)\n    ? Math.max(1, Math.min(64, Math.floor(precision)))\n    : DEFAULT_PRECISION\n  // Exact integers up to 30 digits: print in full, no precision truncation, no exponent. The\n  // fixed-notation full string is the source of truth for \"is this an exact integer\" — mathjs's\n  // `isInteger` is unreliable for Decimals carrying a fractional part under some configs.\n  const fixed = math.format(b, { notation: 'fixed' })\n  if (!fixed.includes('.') && fixed.replace('-', '').length <= 31) {\n    return fixed\n  }\n  return math.format(b, { precision: p })\n}\n\n/** Convert a {@link BigNumber} back to a JS number (for cases that must hand off a float64). */\nexport const bigToNumber = (b: BigNumber): number => math.number(b)\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiCA,IAAM,oBAAoB;;AAG1B,IAAa,oBAAoB;AAEjC,IAAM,QAAA,GAAA,OAAA,QAAc,OAAA,KAAK;CAAE,QAAQ;CAAa,WAAW;AAAkB,CAAC;;AAG9E,IAAa,SAAS,MAAyB,KAAK,UAAU,CAAC;;AAG/D,IAAa,UAAU,SACrB,KAAK,QAAmB,KAAK,MAAM,KAAK,IAAI,KAAK,KAAK,UAAU,CAAC,CAAC,GAAG,KAAK,UAAU,CAAC,CAAC;;AAGxF,IAAa,WAAW,SACtB,KAAK,OAAO,OAAO,IAAI,GAAG,KAAK,MAAM;;AAGvC,IAAa,YAAY,OAAe,YAAoB,aAC1D,KAAK,OACH,KAAK,SAAS,KAAK,UAAU,KAAK,GAAG,KAAK,UAAU,UAAU,CAAC,GAC/D,KAAK,UAAU,QAAQ,CACzB;;;;;;;;;;;;;;AAeF,IAAa,aACX,OACA,YAAA,MACW;CACX,MAAM,IAAI,OAAO,UAAU,WAAW,KAAK,UAAU,KAAK,IAAI;CAC9D,IAAI,KAAK,MAAM,GAAG,CAAC,GAAG,OAAO;CAC7B,MAAM,IAAI,OAAO,SAAS,SAAS,IAC/B,KAAK,IAAI,GAAG,KAAK,IAAI,IAAI,KAAK,MAAM,SAAS,CAAC,CAAC,IAAA;CAKnD,MAAM,QAAQ,KAAK,OAAO,GAAG,EAAE,UAAU,QAAQ,CAAC;CAClD,IAAI,CAAC,MAAM,SAAS,GAAG,KAAK,MAAM,QAAQ,KAAK,EAAE,EAAE,UAAU,IAC3D,OAAO;CAET,OAAO,KAAK,OAAO,GAAG,EAAE,WAAW,EAAE,CAAC;AACxC;;AAGA,IAAa,eAAe,MAAyB,KAAK,OAAO,CAAC"}

package/lib/helpers/bignum.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Arbitrary-precision numeric helpers for the bundled tools.
+ *
+ * @module @nhtio/adk/lib/helpers/bignum
+ *
+ * @remarks
+ * ECMAScript numbers are IEEE-754 float64: arithmetic on user-supplied values can overflow to
+ * `Infinity`, underflow to `0`, or silently lose precision (`0.1 + 0.2 === 0.30000000000000004`).
+ * The numeric tool batteries (`statistics`, `data_structure`, `unit_conversion`, `math`) route
+ * their aggregations and result formatting through this module so that:
+ *
+ * - large in-range sums stay exact instead of overflowing (`sum([1e308, 1e308]) → 2e308`),
+ * - precision is preserved end-to-end (`sum([0.1, 0.2]) → 0.3`),
+ * - output is rendered to a caller-chosen number of significant digits (default 8) without the
+ *   lossy `Number.prototype.toPrecision`/`toFixed` round-trip that mangles even safe integers
+ *   (e.g. `9007199254740991` rendered as `9007199255000`).
+ *
+ * Internally this is backed by a single {@link https://mathjs.org | mathjs} instance configured
+ * for `BigNumber` (which bundles `decimal.js`) at 64 significant digits — comfortably more than
+ * float64's ~15-17 and enough for the tools' needs without unbounded growth.
+ *
+ * The tools still RECEIVE float64 numbers (the model's tool-call arguments are JSON-parsed to
+ * float64 upstream, and the typed-array input schemas reject `NaN`/`Infinity`/`> 2^53` before the
+ * handler runs). BigNumber's job is the math and formatting in between, not the input boundary.
+ */
+import { type BigNumber } from 'mathjs';
+/** Default display precision (significant digits) for tool output. */
+export declare const DEFAULT_PRECISION = 8;
+/** Coerce a JS number to a {@link BigNumber}. Non-finite inputs are a caller bug (schemas reject them). */
+export declare const toBig: (n: number) => BigNumber;
+/** Exact sum of a numeric array as a {@link BigNumber} (no float64 overflow/precision loss). */
+export declare const bigSum: (nums: number[]) => BigNumber;
+/** Exact arithmetic mean as a {@link BigNumber}. Caller guarantees `nums.length > 0`. */
+export declare const bigMean: (nums: number[]) => BigNumber;
+/** `value * fromFactor / toFactor` computed without intermediate float64 over/underflow. */
+export declare const bigScale: (value: number, fromFactor: number, toFactor: number) => BigNumber;
+/**
+ * Render a {@link BigNumber} (or JS number) to a string at `precision` significant digits.
+ *
+ * @remarks
+ * - An EXACT INTEGER is rendered in full fixed notation regardless of `precision`: an integer
+ *   carries no fractional precision to lose, so `8000000000000` stays `8000000000000` rather than
+ *   being truncated to `8e+12`. (Bounded at 30 digits to avoid pathological astronomically-large
+ *   integers printing thousands of characters; beyond that, sig-fig exponential is used.)
+ * - Non-integers are rendered at `precision` significant digits (default 8), stripping trailing
+ *   zeros — avoiding the `toPrecision` artifact that mangled safe values, while still giving the
+ *   caller control over how many digits they want (raise `precision` for more).
+ * - Exact zero renders as `'0'`. (Genuinely tiny values like `2.54e-5` are preserved, NOT snapped.)
+ */
+export declare const formatBig: (value: BigNumber | number, precision?: number) => string;
+/** Convert a {@link BigNumber} back to a JS number (for cases that must hand off a float64). */
+export declare const bigToNumber: (b: BigNumber) => number;

package/lib/helpers/bignum.mjs

@@ -0,0 +1,74 @@
+import { all, create } from "mathjs";
+//#region src/lib/helpers/bignum.ts
+/**
+* Arbitrary-precision numeric helpers for the bundled tools.
+*
+* @module @nhtio/adk/lib/helpers/bignum
+*
+* @remarks
+* ECMAScript numbers are IEEE-754 float64: arithmetic on user-supplied values can overflow to
+* `Infinity`, underflow to `0`, or silently lose precision (`0.1 + 0.2 === 0.30000000000000004`).
+* The numeric tool batteries (`statistics`, `data_structure`, `unit_conversion`, `math`) route
+* their aggregations and result formatting through this module so that:
+*
+* - large in-range sums stay exact instead of overflowing (`sum([1e308, 1e308]) → 2e308`),
+* - precision is preserved end-to-end (`sum([0.1, 0.2]) → 0.3`),
+* - output is rendered to a caller-chosen number of significant digits (default 8) without the
+*   lossy `Number.prototype.toPrecision`/`toFixed` round-trip that mangles even safe integers
+*   (e.g. `9007199254740991` rendered as `9007199255000`).
+*
+* Internally this is backed by a single {@link https://mathjs.org | mathjs} instance configured
+* for `BigNumber` (which bundles `decimal.js`) at 64 significant digits — comfortably more than
+* float64's ~15-17 and enough for the tools' needs without unbounded growth.
+*
+* The tools still RECEIVE float64 numbers (the model's tool-call arguments are JSON-parsed to
+* float64 upstream, and the typed-array input schemas reject `NaN`/`Infinity`/`> 2^53` before the
+* handler runs). BigNumber's job is the math and formatting in between, not the input boundary.
+*/
+/**
+* Precision (significant digits) the internal BigNumber engine computes with. Distinct from the
+* per-call display precision passed to {@link formatBig} — this is the working precision so that
+* intermediate results don't accumulate rounding error before they are formatted down.
+*/
+var WORKING_PRECISION = 64;
+/** Default display precision (significant digits) for tool output. */
+var DEFAULT_PRECISION = 8;
+var math = create(all, {
+	number: "BigNumber",
+	precision: WORKING_PRECISION
+});
+/** Coerce a JS number to a {@link BigNumber}. Non-finite inputs are a caller bug (schemas reject them). */
+var toBig = (n) => math.bignumber(n);
+/** Exact sum of a numeric array as a {@link BigNumber} (no float64 overflow/precision loss). */
+var bigSum = (nums) => nums.reduce((acc, n) => math.add(acc, math.bignumber(n)), math.bignumber(0));
+/** Exact arithmetic mean as a {@link BigNumber}. Caller guarantees `nums.length > 0`. */
+var bigMean = (nums) => math.divide(bigSum(nums), nums.length);
+/** `value * fromFactor / toFactor` computed without intermediate float64 over/underflow. */
+var bigScale = (value, fromFactor, toFactor) => math.divide(math.multiply(math.bignumber(value), math.bignumber(fromFactor)), math.bignumber(toFactor));
+/**
+* Render a {@link BigNumber} (or JS number) to a string at `precision` significant digits.
+*
+* @remarks
+* - An EXACT INTEGER is rendered in full fixed notation regardless of `precision`: an integer
+*   carries no fractional precision to lose, so `8000000000000` stays `8000000000000` rather than
+*   being truncated to `8e+12`. (Bounded at 30 digits to avoid pathological astronomically-large
+*   integers printing thousands of characters; beyond that, sig-fig exponential is used.)
+* - Non-integers are rendered at `precision` significant digits (default 8), stripping trailing
+*   zeros — avoiding the `toPrecision` artifact that mangled safe values, while still giving the
+*   caller control over how many digits they want (raise `precision` for more).
+* - Exact zero renders as `'0'`. (Genuinely tiny values like `2.54e-5` are preserved, NOT snapped.)
+*/
+var formatBig = (value, precision = 8) => {
+	const b = typeof value === "number" ? math.bignumber(value) : value;
+	if (math.equal(b, 0)) return "0";
+	const p = Number.isFinite(precision) ? Math.max(1, Math.min(64, Math.floor(precision))) : 8;
+	const fixed = math.format(b, { notation: "fixed" });
+	if (!fixed.includes(".") && fixed.replace("-", "").length <= 31) return fixed;
+	return math.format(b, { precision: p });
+};
+/** Convert a {@link BigNumber} back to a JS number (for cases that must hand off a float64). */
+var bigToNumber = (b) => math.number(b);
+//#endregion
+export { DEFAULT_PRECISION, bigMean, bigScale, bigSum, bigToNumber, formatBig, toBig };
+
+//# sourceMappingURL=bignum.mjs.map

package/lib/helpers/bignum.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"bignum.mjs","names":[],"sources":["../../../src/lib/helpers/bignum.ts"],"sourcesContent":["/**\n * Arbitrary-precision numeric helpers for the bundled tools.\n *\n * @module @nhtio/adk/lib/helpers/bignum\n *\n * @remarks\n * ECMAScript numbers are IEEE-754 float64: arithmetic on user-supplied values can overflow to\n * `Infinity`, underflow to `0`, or silently lose precision (`0.1 + 0.2 === 0.30000000000000004`).\n * The numeric tool batteries (`statistics`, `data_structure`, `unit_conversion`, `math`) route\n * their aggregations and result formatting through this module so that:\n *\n * - large in-range sums stay exact instead of overflowing (`sum([1e308, 1e308]) → 2e308`),\n * - precision is preserved end-to-end (`sum([0.1, 0.2]) → 0.3`),\n * - output is rendered to a caller-chosen number of significant digits (default 8) without the\n *   lossy `Number.prototype.toPrecision`/`toFixed` round-trip that mangles even safe integers\n *   (e.g. `9007199254740991` rendered as `9007199255000`).\n *\n * Internally this is backed by a single {@link https://mathjs.org | mathjs} instance configured\n * for `BigNumber` (which bundles `decimal.js`) at 64 significant digits — comfortably more than\n * float64's ~15-17 and enough for the tools' needs without unbounded growth.\n *\n * The tools still RECEIVE float64 numbers (the model's tool-call arguments are JSON-parsed to\n * float64 upstream, and the typed-array input schemas reject `NaN`/`Infinity`/`> 2^53` before the\n * handler runs). BigNumber's job is the math and formatting in between, not the input boundary.\n */\n\nimport { create, all, type BigNumber } from 'mathjs'\n\n/**\n * Precision (significant digits) the internal BigNumber engine computes with. Distinct from the\n * per-call display precision passed to {@link formatBig} — this is the working precision so that\n * intermediate results don't accumulate rounding error before they are formatted down.\n */\nconst WORKING_PRECISION = 64\n\n/** Default display precision (significant digits) for tool output. */\nexport const DEFAULT_PRECISION = 8\n\nconst math = create(all, { number: 'BigNumber', precision: WORKING_PRECISION })\n\n/** Coerce a JS number to a {@link BigNumber}. Non-finite inputs are a caller bug (schemas reject them). */\nexport const toBig = (n: number): BigNumber => math.bignumber(n)\n\n/** Exact sum of a numeric array as a {@link BigNumber} (no float64 overflow/precision loss). */\nexport const bigSum = (nums: number[]): BigNumber =>\n  nums.reduce<BigNumber>((acc, n) => math.add(acc, math.bignumber(n)), math.bignumber(0))\n\n/** Exact arithmetic mean as a {@link BigNumber}. Caller guarantees `nums.length > 0`. */\nexport const bigMean = (nums: number[]): BigNumber =>\n  math.divide(bigSum(nums), nums.length) as BigNumber\n\n/** `value * fromFactor / toFactor` computed without intermediate float64 over/underflow. */\nexport const bigScale = (value: number, fromFactor: number, toFactor: number): BigNumber =>\n  math.divide(\n    math.multiply(math.bignumber(value), math.bignumber(fromFactor)),\n    math.bignumber(toFactor)\n  ) as BigNumber\n\n/**\n * Render a {@link BigNumber} (or JS number) to a string at `precision` significant digits.\n *\n * @remarks\n * - An EXACT INTEGER is rendered in full fixed notation regardless of `precision`: an integer\n *   carries no fractional precision to lose, so `8000000000000` stays `8000000000000` rather than\n *   being truncated to `8e+12`. (Bounded at 30 digits to avoid pathological astronomically-large\n *   integers printing thousands of characters; beyond that, sig-fig exponential is used.)\n * - Non-integers are rendered at `precision` significant digits (default 8), stripping trailing\n *   zeros — avoiding the `toPrecision` artifact that mangled safe values, while still giving the\n *   caller control over how many digits they want (raise `precision` for more).\n * - Exact zero renders as `'0'`. (Genuinely tiny values like `2.54e-5` are preserved, NOT snapped.)\n */\nexport const formatBig = (\n  value: BigNumber | number,\n  precision: number = DEFAULT_PRECISION\n): string => {\n  const b = typeof value === 'number' ? math.bignumber(value) : value\n  if (math.equal(b, 0)) return '0'\n  const p = Number.isFinite(precision)\n    ? Math.max(1, Math.min(64, Math.floor(precision)))\n    : DEFAULT_PRECISION\n  // Exact integers up to 30 digits: print in full, no precision truncation, no exponent. The\n  // fixed-notation full string is the source of truth for \"is this an exact integer\" — mathjs's\n  // `isInteger` is unreliable for Decimals carrying a fractional part under some configs.\n  const fixed = math.format(b, { notation: 'fixed' })\n  if (!fixed.includes('.') && fixed.replace('-', '').length <= 31) {\n    return fixed\n  }\n  return math.format(b, { precision: p })\n}\n\n/** Convert a {@link BigNumber} back to a JS number (for cases that must hand off a float64). */\nexport const bigToNumber = (b: BigNumber): number => math.number(b)\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiCA,IAAM,oBAAoB;;AAG1B,IAAa,oBAAoB;AAEjC,IAAM,OAAO,OAAO,KAAK;CAAE,QAAQ;CAAa,WAAW;AAAkB,CAAC;;AAG9E,IAAa,SAAS,MAAyB,KAAK,UAAU,CAAC;;AAG/D,IAAa,UAAU,SACrB,KAAK,QAAmB,KAAK,MAAM,KAAK,IAAI,KAAK,KAAK,UAAU,CAAC,CAAC,GAAG,KAAK,UAAU,CAAC,CAAC;;AAGxF,IAAa,WAAW,SACtB,KAAK,OAAO,OAAO,IAAI,GAAG,KAAK,MAAM;;AAGvC,IAAa,YAAY,OAAe,YAAoB,aAC1D,KAAK,OACH,KAAK,SAAS,KAAK,UAAU,KAAK,GAAG,KAAK,UAAU,UAAU,CAAC,GAC/D,KAAK,UAAU,QAAQ,CACzB;;;;;;;;;;;;;;AAeF,IAAa,aACX,OACA,YAAA,MACW;CACX,MAAM,IAAI,OAAO,UAAU,WAAW,KAAK,UAAU,KAAK,IAAI;CAC9D,IAAI,KAAK,MAAM,GAAG,CAAC,GAAG,OAAO;CAC7B,MAAM,IAAI,OAAO,SAAS,SAAS,IAC/B,KAAK,IAAI,GAAG,KAAK,IAAI,IAAI,KAAK,MAAM,SAAS,CAAC,CAAC,IAAA;CAKnD,MAAM,QAAQ,KAAK,OAAO,GAAG,EAAE,UAAU,QAAQ,CAAC;CAClD,IAAI,CAAC,MAAM,SAAS,GAAG,KAAK,MAAM,QAAQ,KAAK,EAAE,EAAE,UAAU,IAC3D,OAAO;CAET,OAAO,KAAK,OAAO,GAAG,EAAE,WAAW,EAAE,CAAC;AACxC;;AAGA,IAAa,eAAe,MAAyB,KAAK,OAAO,CAAC"}

package/lib/turn_runner.d.ts

@@ -63,7 +63,7 @@ export declare class TurnRunner {
      */
     static isTurnRunner(value: unknown): value is TurnRunner;
     /**
-     * @param config - Construction-time configuration validated against {@link turnRunnerConfigSchema}.
+     * @param config - Construction-time configuration validated against the turn-runner config schema.
      * @throws {@link @nhtio/adk!E_INVALID_TURN_RUNNER_CONFIG} when `config` does not satisfy the schema.
      */
     constructor(config: TurnRunnerConfig);

package/lib/types/dispatch_runner.d.ts

@@ -118,6 +118,24 @@ export interface DispatchExecutorHelpers {
      * warnings, context-window perBucket breakdowns. Use it instead of `console.*`.
      */
     log: DispatchExecutorLogChannel;
+    /**
+     * Emit a provider-agnostic {@link GenerationStats} record for the generation that just
+     * completed this iteration (token usage, wall-clock durations, finish reason).
+     *
+     * @remarks
+     * A dedicated egress for *generation accounting*, distinct from the diagnostic `log` channel:
+     * subscribers (cost meters, latency dashboards, token-budget guards) listen on the runner's
+     * `generationStats` observability hook without string-matching a log `kind`. The runner
+     * enriches every emission with the active `dispatchId` and 0-based `iteration` index, mirroring
+     * {@link DispatchExecutorHelpers.log}.
+     *
+     * Emit-only and side-effect-only — like `log`, it never throws, never mutates the
+     * {@link @nhtio/adk!DispatchContext}, and never participates in ack / nack flow. Every field on
+     * {@link GenerationStats} is optional, so a provider supplies only what its wire format reports
+     * (e.g. OpenAI surfaces token counts but no durations; Ollama surfaces both). Call it at most
+     * once per generation, after the response (or stream) has settled.
+     */
+    reportGenerationStats(stats: GenerationStats): void;
 }
 /**
  * Severity of a structured log event emitted by an executor via {@link DispatchExecutorHelpers.log}.
@@ -190,6 +208,63 @@ export interface LogEvent {
     /** Optional structured detail block. */
     payload?: Record<string, unknown>;
 }
+/**
+ * Provider-agnostic generation accounting for a single completed generation, emitted via
+ * {@link DispatchExecutorHelpers.reportGenerationStats}.
+ *
+ * @remarks
+ * Every field is optional so each battery supplies only what its wire format reports — OpenAI
+ * Chat Completions surfaces token counts (its `usage` block) but no wall-clock durations; Ollama's
+ * native `/api/chat` surfaces both token counts and nanosecond durations on its terminal chunk.
+ *
+ * Durations are carried in their **native nanosecond** unit (the `Ns` suffix is load-bearing) and
+ * are never normalised here — normalising to milliseconds would be lossy and providers without
+ * durations would gain meaningless zeros. `raw` preserves the full provider-native stats object
+ * verbatim for forward-compatibility, so a subscriber can read a field this shape has not yet
+ * promoted to a typed member.
+ */
+export interface GenerationStats {
+    /** Tokens in the prompt / input (OpenAI `usage.prompt_tokens`, Ollama `prompt_eval_count`). */
+    promptTokens?: number;
+    /** Tokens in the completion / output (OpenAI `usage.completion_tokens`, Ollama `eval_count`). */
+    completionTokens?: number;
+    /** Total tokens, when the provider reports a combined figure. */
+    totalTokens?: number;
+    /** Total wall-clock generation time in nanoseconds (Ollama `total_duration`). */
+    totalDurationNs?: number;
+    /** Time spent loading the model in nanoseconds (Ollama `load_duration`). */
+    loadDurationNs?: number;
+    /** Time spent evaluating the prompt in nanoseconds (Ollama `prompt_eval_duration`). */
+    promptEvalDurationNs?: number;
+    /** Time spent generating the response in nanoseconds (Ollama `eval_duration`). */
+    evalDurationNs?: number;
+    /** Why generation stopped (Ollama `done_reason`, OpenAI `finish_reason`). */
+    finishReason?: string;
+    /** Model identifier the provider echoed back. */
+    model?: string;
+    /** Stable provider discriminator (e.g. `'ollama'`, `'openai_chat_completions'`). */
+    provider?: string;
+    /** Full provider-native stats object, verbatim, for forward-compatibility. */
+    raw?: Record<string, unknown>;
+}
+/**
+ * Payload fired on the observability `generationStats` hook for every record emitted via
+ * {@link DispatchExecutorHelpers.reportGenerationStats}.
+ *
+ * @remarks
+ * The runner enriches the executor-supplied {@link GenerationStats} with the active `dispatchId`
+ * and 0-based `iteration` index (and an `emittedAt` timestamp) so subscribers can correlate stats
+ * across multiple in-flight dispatches without threading extra context — exactly as {@link LogEvent}
+ * does for the `log` channel.
+ */
+export interface GenerationStatsEvent extends GenerationStats {
+    /** Stable identifier for the dispatch that produced the event. */
+    dispatchId: string;
+    /** 0-based iteration index within the dispatch. */
+    iteration: number;
+    /** When the event was emitted. */
+    emittedAt: DateTime;
+}
 /**
  * The user-supplied callback that performs the actual LLM API call within a dispatch.
  *
@@ -372,6 +447,14 @@ export type DispatchRunnerObservabilityHooks = {
         [
         ]
     ];
+    /** Fired for every generation-stats record emitted via {@link DispatchExecutorHelpers.reportGenerationStats}. */
+    generationStats: [
+        [
+            GenerationStatsEvent
+        ],
+        [
+        ]
+    ];
 };
 /**
  * Optional functional hook registrations supplied to {@link @nhtio/adk!DispatchRunner.dispatch}.

package/lib/utils/exceptions.d.ts

@@ -36,7 +36,7 @@ export type CreatedException<T extends any[] = [
  * @typeParam T - Tuple of printf format argument types. Pass a non-empty tuple to require
  *   callers to supply interpolation values at the throw site.
  *
- * @param name - The `name` property set on thrown instances (used by {@link isNamedException}).
+ * @param name - The `name` property set on thrown instances (used by `isNamedException`).
  * @param message - Printf-style template string for the error message.
  * @param code - Machine-readable error code stored on the static and instance `code` property.
  * @param status - HTTP status code associated with this exception class.

package/lib/utils/retry.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"retry.cjs","names":[],"sources":["../../../src/lib/utils/retry.ts"],"sourcesContent":["/**\n * Environment-neutral retry/backoff/timeout primitives shared across HTTP-backed batteries.\n *\n * @module @nhtio/adk/lib/utils/retry\n *\n * @remarks\n * These are pure helpers — no DOM, no Node built-ins, only `setTimeout`, `AbortController`, and\n * `AbortSignal`, all of which exist in every target runtime (Node, browser, edge, workers). They\n * are shared (not duplicated) by the OpenAI Chat Completions battery and the OpenAI Embeddings\n * battery so retry behavior stays identical across the bundled batteries. The bundler inlines this\n * module into each consumer, so sharing introduces no build coupling.\n */\n\n/**\n * Minimal backoff configuration shape. Any retry config carrying `baseDelayMs`/`maxDelayMs`\n * satisfies it structurally, so batteries can pass their own richer config objects directly.\n */\nexport interface BackoffConfig {\n  baseDelayMs?: number\n  maxDelayMs?: number\n}\n\n/**\n * Exponential backoff with a ceiling: `min(baseDelayMs * 2^(attempt-1), maxDelayMs)`.\n *\n * @param attempt - 1-based attempt number.\n * @param cfg - Carries `baseDelayMs` (default 500) and `maxDelayMs` (default 30_000).\n * @returns The (un-jittered) delay in ms.\n */\nexport const computeBackoff = (attempt: number, cfg: BackoffConfig): number => {\n  const base = cfg.baseDelayMs ?? 500\n  const max = cfg.maxDelayMs ?? 30_000\n  return Math.min(base * Math.pow(2, attempt - 1), max)\n}\n\n/**\n * Abort-aware jittered sleep used for retry backoff.\n *\n * @remarks\n * Resolves (never rejects) the instant `signal` aborts, so an aborted caller does not stay parked\n * in a backoff delay — the caller's retry loop re-checks abort state immediately after and bails.\n * The timer and the abort listener are both torn down on whichever fires first, so nothing leaks.\n *\n * @param ms - Base delay in ms; jittered by ±10%.\n * @param signal - Optional abort signal that short-circuits the sleep.\n */\nexport const sleepWithJitter = (ms: number, signal?: AbortSignal): Promise<void> => {\n  const jittered = ms * (0.9 + Math.random() * 0.2)\n  return new Promise((resolve) => {\n    if (signal?.aborted) {\n      resolve()\n      return\n    }\n    let onAbort: (() => void) | undefined\n    const timer = setTimeout(() => {\n      if (onAbort && signal) signal.removeEventListener('abort', onAbort)\n      resolve()\n    }, jittered)\n    if (signal) {\n      onAbort = () => {\n        clearTimeout(timer)\n        resolve()\n      }\n      signal.addEventListener('abort', onAbort, { once: true })\n    }\n  })\n}\n\n/**\n * Parses an HTTP `Retry-After` header value (delta-seconds or HTTP-date) into milliseconds.\n *\n * @param raw - The header value.\n * @returns Milliseconds to wait, or `0` when the value cannot be parsed or is in the past.\n */\nexport const parseRetryAfter = (raw: string): number => {\n  const asNum = Number(raw)\n  if (Number.isFinite(asNum)) return asNum * 1000\n  const asDate = Date.parse(raw)\n  if (Number.isFinite(asDate)) return Math.max(0, asDate - Date.now())\n  return 0\n}\n\n/**\n * Combines several abort signals into one.\n *\n * @remarks\n * Returns the linked signal plus a `dispose` that detaches any listeners the fallback path\n * attached, so repeated links on a long-lived signal (one per retry attempt) do not accumulate\n * listeners. The native `AbortSignal.any` path self-manages its listeners, so `dispose` is a no-op\n * there.\n *\n * @param signals - The signals to combine.\n * @returns The linked signal and a `dispose` to tear down fallback listeners.\n */\nexport const linkAbortSignals = (\n  signals: ReadonlyArray<AbortSignal>\n): { signal: AbortSignal; dispose: () => void } => {\n  const anyFn = (AbortSignal as unknown as { any?: (sigs: AbortSignal[]) => AbortSignal }).any\n  if (typeof anyFn === 'function') {\n    return { signal: anyFn(signals as AbortSignal[]), dispose: () => {} }\n  }\n  // Fallback for older runtimes: hand-link via a fresh controller.\n  const ctrl = new AbortController()\n  const links: Array<{ sig: AbortSignal; handler: () => void }> = []\n  for (const sig of signals) {\n    if (sig.aborted) {\n      ctrl.abort()\n      break\n    }\n    const handler = () => ctrl.abort()\n    sig.addEventListener('abort', handler, { once: true })\n    links.push({ sig, handler })\n  }\n  return {\n    signal: ctrl.signal,\n    dispose: () => {\n      for (const { sig, handler } of links) sig.removeEventListener('abort', handler)\n      links.length = 0\n    },\n  }\n}\n"],"mappings":";;;;;;;;;;AA6BA,IAAa,kBAAkB,SAAiB,QAA+B;CAC7E,MAAM,OAAO,IAAI,eAAe;CAChC,MAAM,MAAM,IAAI,cAAc;CAC9B,OAAO,KAAK,IAAI,OAAO,KAAK,IAAI,GAAG,UAAU,CAAC,GAAG,GAAG;AACtD;;;;;;;;;;;;AAaA,IAAa,mBAAmB,IAAY,WAAwC;CAClF,MAAM,WAAW,MAAM,KAAM,KAAK,OAAO,IAAI;CAC7C,OAAO,IAAI,SAAS,YAAY;EAC9B,IAAI,QAAQ,SAAS;GACnB,QAAQ;GACR;EACF;EACA,IAAI;EACJ,MAAM,QAAQ,iBAAiB;GAC7B,IAAI,WAAW,QAAQ,OAAO,oBAAoB,SAAS,OAAO;GAClE,QAAQ;EACV,GAAG,QAAQ;EACX,IAAI,QAAQ;GACV,gBAAgB;IACd,aAAa,KAAK;IAClB,QAAQ;GACV;GACA,OAAO,iBAAiB,SAAS,SAAS,EAAE,MAAM,KAAK,CAAC;EAC1D;CACF,CAAC;AACH;;;;;;;AAQA,IAAa,mBAAmB,QAAwB;CACtD,MAAM,QAAQ,OAAO,GAAG;CACxB,IAAI,OAAO,SAAS,KAAK,GAAG,OAAO,QAAQ;CAC3C,MAAM,SAAS,KAAK,MAAM,GAAG;CAC7B,IAAI,OAAO,SAAS,MAAM,GAAG,OAAO,KAAK,IAAI,GAAG,SAAS,KAAK,IAAI,CAAC;CACnE,OAAO;AACT;;;;;;;;;;;;;AAcA,IAAa,oBACX,YACiD;CACjD,MAAM,QAAS,YAA0E;CACzF,IAAI,OAAO,UAAU,YACnB,OAAO;EAAE,QAAQ,MAAM,OAAwB;EAAG,eAAe,CAAC;CAAE;CAGtE,MAAM,OAAO,IAAI,gBAAgB;CACjC,MAAM,QAA0D,CAAC;CACjE,KAAK,MAAM,OAAO,SAAS;EACzB,IAAI,IAAI,SAAS;GACf,KAAK,MAAM;GACX;EACF;EACA,MAAM,gBAAgB,KAAK,MAAM;EACjC,IAAI,iBAAiB,SAAS,SAAS,EAAE,MAAM,KAAK,CAAC;EACrD,MAAM,KAAK;GAAE;GAAK;EAAQ,CAAC;CAC7B;CACA,OAAO;EACL,QAAQ,KAAK;EACb,eAAe;GACb,KAAK,MAAM,EAAE,KAAK,aAAa,OAAO,IAAI,oBAAoB,SAAS,OAAO;GAC9E,MAAM,SAAS;EACjB;CACF;AACF"}
+{"version":3,"file":"retry.cjs","names":[],"sources":["../../../src/lib/utils/retry.ts"],"sourcesContent":["/**\n * Environment-neutral retry/backoff/timeout primitives shared across HTTP-backed batteries.\n *\n * @module @nhtio/adk/lib/utils/retry\n *\n * @remarks\n * These are pure helpers — no DOM, no Node built-ins, only `setTimeout`, `AbortController`, and\n * `AbortSignal`, all of which exist in every target runtime (Node, browser, edge, workers). They\n * are shared (not duplicated) by the OpenAI Chat Completions battery and the OpenAI Embeddings\n * battery so retry behavior stays identical across the bundled batteries. The bundler inlines this\n * module into each consumer, so sharing introduces no build coupling.\n */\n\n/**\n * Minimal backoff configuration shape. Any retry config carrying `baseDelayMs`/`maxDelayMs`\n * satisfies it structurally, so batteries can pass their own richer config objects directly.\n */\nexport interface BackoffConfig {\n  /** Base delay in milliseconds for the first retry; doubles each attempt (default 500). */\n  baseDelayMs?: number\n  /** Upper bound in milliseconds on any single backoff delay (default 30_000). */\n  maxDelayMs?: number\n}\n\n/**\n * Exponential backoff with a ceiling: `min(baseDelayMs * 2^(attempt-1), maxDelayMs)`.\n *\n * @param attempt - 1-based attempt number.\n * @param cfg - Carries `baseDelayMs` (default 500) and `maxDelayMs` (default 30_000).\n * @returns The (un-jittered) delay in ms.\n */\nexport const computeBackoff = (attempt: number, cfg: BackoffConfig): number => {\n  const base = cfg.baseDelayMs ?? 500\n  const max = cfg.maxDelayMs ?? 30_000\n  return Math.min(base * Math.pow(2, attempt - 1), max)\n}\n\n/**\n * Abort-aware jittered sleep used for retry backoff.\n *\n * @remarks\n * Resolves (never rejects) the instant `signal` aborts, so an aborted caller does not stay parked\n * in a backoff delay — the caller's retry loop re-checks abort state immediately after and bails.\n * The timer and the abort listener are both torn down on whichever fires first, so nothing leaks.\n *\n * @param ms - Base delay in ms; jittered by ±10%.\n * @param signal - Optional abort signal that short-circuits the sleep.\n */\nexport const sleepWithJitter = (ms: number, signal?: AbortSignal): Promise<void> => {\n  const jittered = ms * (0.9 + Math.random() * 0.2)\n  return new Promise((resolve) => {\n    if (signal?.aborted) {\n      resolve()\n      return\n    }\n    let onAbort: (() => void) | undefined\n    const timer = setTimeout(() => {\n      if (onAbort && signal) signal.removeEventListener('abort', onAbort)\n      resolve()\n    }, jittered)\n    if (signal) {\n      onAbort = () => {\n        clearTimeout(timer)\n        resolve()\n      }\n      signal.addEventListener('abort', onAbort, { once: true })\n    }\n  })\n}\n\n/**\n * Parses an HTTP `Retry-After` header value (delta-seconds or HTTP-date) into milliseconds.\n *\n * @param raw - The header value.\n * @returns Milliseconds to wait, or `0` when the value cannot be parsed or is in the past.\n */\nexport const parseRetryAfter = (raw: string): number => {\n  const asNum = Number(raw)\n  if (Number.isFinite(asNum)) return asNum * 1000\n  const asDate = Date.parse(raw)\n  if (Number.isFinite(asDate)) return Math.max(0, asDate - Date.now())\n  return 0\n}\n\n/**\n * Combines several abort signals into one.\n *\n * @remarks\n * Returns the linked signal plus a `dispose` that detaches any listeners the fallback path\n * attached, so repeated links on a long-lived signal (one per retry attempt) do not accumulate\n * listeners. The native `AbortSignal.any` path self-manages its listeners, so `dispose` is a no-op\n * there.\n *\n * @param signals - The signals to combine.\n * @returns The linked signal and a `dispose` to tear down fallback listeners.\n */\nexport const linkAbortSignals = (\n  signals: ReadonlyArray<AbortSignal>\n): { signal: AbortSignal; dispose: () => void } => {\n  const anyFn = (AbortSignal as unknown as { any?: (sigs: AbortSignal[]) => AbortSignal }).any\n  if (typeof anyFn === 'function') {\n    return { signal: anyFn(signals as AbortSignal[]), dispose: () => {} }\n  }\n  // Fallback for older runtimes: hand-link via a fresh controller.\n  const ctrl = new AbortController()\n  const links: Array<{ sig: AbortSignal; handler: () => void }> = []\n  for (const sig of signals) {\n    if (sig.aborted) {\n      ctrl.abort()\n      break\n    }\n    const handler = () => ctrl.abort()\n    sig.addEventListener('abort', handler, { once: true })\n    links.push({ sig, handler })\n  }\n  return {\n    signal: ctrl.signal,\n    dispose: () => {\n      for (const { sig, handler } of links) sig.removeEventListener('abort', handler)\n      links.length = 0\n    },\n  }\n}\n"],"mappings":";;;;;;;;;;AA+BA,IAAa,kBAAkB,SAAiB,QAA+B;CAC7E,MAAM,OAAO,IAAI,eAAe;CAChC,MAAM,MAAM,IAAI,cAAc;CAC9B,OAAO,KAAK,IAAI,OAAO,KAAK,IAAI,GAAG,UAAU,CAAC,GAAG,GAAG;AACtD;;;;;;;;;;;;AAaA,IAAa,mBAAmB,IAAY,WAAwC;CAClF,MAAM,WAAW,MAAM,KAAM,KAAK,OAAO,IAAI;CAC7C,OAAO,IAAI,SAAS,YAAY;EAC9B,IAAI,QAAQ,SAAS;GACnB,QAAQ;GACR;EACF;EACA,IAAI;EACJ,MAAM,QAAQ,iBAAiB;GAC7B,IAAI,WAAW,QAAQ,OAAO,oBAAoB,SAAS,OAAO;GAClE,QAAQ;EACV,GAAG,QAAQ;EACX,IAAI,QAAQ;GACV,gBAAgB;IACd,aAAa,KAAK;IAClB,QAAQ;GACV;GACA,OAAO,iBAAiB,SAAS,SAAS,EAAE,MAAM,KAAK,CAAC;EAC1D;CACF,CAAC;AACH;;;;;;;AAQA,IAAa,mBAAmB,QAAwB;CACtD,MAAM,QAAQ,OAAO,GAAG;CACxB,IAAI,OAAO,SAAS,KAAK,GAAG,OAAO,QAAQ;CAC3C,MAAM,SAAS,KAAK,MAAM,GAAG;CAC7B,IAAI,OAAO,SAAS,MAAM,GAAG,OAAO,KAAK,IAAI,GAAG,SAAS,KAAK,IAAI,CAAC;CACnE,OAAO;AACT;;;;;;;;;;;;;AAcA,IAAa,oBACX,YACiD;CACjD,MAAM,QAAS,YAA0E;CACzF,IAAI,OAAO,UAAU,YACnB,OAAO;EAAE,QAAQ,MAAM,OAAwB;EAAG,eAAe,CAAC;CAAE;CAGtE,MAAM,OAAO,IAAI,gBAAgB;CACjC,MAAM,QAA0D,CAAC;CACjE,KAAK,MAAM,OAAO,SAAS;EACzB,IAAI,IAAI,SAAS;GACf,KAAK,MAAM;GACX;EACF;EACA,MAAM,gBAAgB,KAAK,MAAM;EACjC,IAAI,iBAAiB,SAAS,SAAS,EAAE,MAAM,KAAK,CAAC;EACrD,MAAM,KAAK;GAAE;GAAK;EAAQ,CAAC;CAC7B;CACA,OAAO;EACL,QAAQ,KAAK;EACb,eAAe;GACb,KAAK,MAAM,EAAE,KAAK,aAAa,OAAO,IAAI,oBAAoB,SAAS,OAAO;GAC9E,MAAM,SAAS;EACjB;CACF;AACF"}

package/lib/utils/retry.d.ts

@@ -15,7 +15,9 @@
  * satisfies it structurally, so batteries can pass their own richer config objects directly.
  */
 export interface BackoffConfig {
+    /** Base delay in milliseconds for the first retry; doubles each attempt (default 500). */
     baseDelayMs?: number;
+    /** Upper bound in milliseconds on any single backoff delay (default 30_000). */
     maxDelayMs?: number;
 }
 /**

package/lib/utils/retry.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"retry.mjs","names":[],"sources":["../../../src/lib/utils/retry.ts"],"sourcesContent":["/**\n * Environment-neutral retry/backoff/timeout primitives shared across HTTP-backed batteries.\n *\n * @module @nhtio/adk/lib/utils/retry\n *\n * @remarks\n * These are pure helpers — no DOM, no Node built-ins, only `setTimeout`, `AbortController`, and\n * `AbortSignal`, all of which exist in every target runtime (Node, browser, edge, workers). They\n * are shared (not duplicated) by the OpenAI Chat Completions battery and the OpenAI Embeddings\n * battery so retry behavior stays identical across the bundled batteries. The bundler inlines this\n * module into each consumer, so sharing introduces no build coupling.\n */\n\n/**\n * Minimal backoff configuration shape. Any retry config carrying `baseDelayMs`/`maxDelayMs`\n * satisfies it structurally, so batteries can pass their own richer config objects directly.\n */\nexport interface BackoffConfig {\n  baseDelayMs?: number\n  maxDelayMs?: number\n}\n\n/**\n * Exponential backoff with a ceiling: `min(baseDelayMs * 2^(attempt-1), maxDelayMs)`.\n *\n * @param attempt - 1-based attempt number.\n * @param cfg - Carries `baseDelayMs` (default 500) and `maxDelayMs` (default 30_000).\n * @returns The (un-jittered) delay in ms.\n */\nexport const computeBackoff = (attempt: number, cfg: BackoffConfig): number => {\n  const base = cfg.baseDelayMs ?? 500\n  const max = cfg.maxDelayMs ?? 30_000\n  return Math.min(base * Math.pow(2, attempt - 1), max)\n}\n\n/**\n * Abort-aware jittered sleep used for retry backoff.\n *\n * @remarks\n * Resolves (never rejects) the instant `signal` aborts, so an aborted caller does not stay parked\n * in a backoff delay — the caller's retry loop re-checks abort state immediately after and bails.\n * The timer and the abort listener are both torn down on whichever fires first, so nothing leaks.\n *\n * @param ms - Base delay in ms; jittered by ±10%.\n * @param signal - Optional abort signal that short-circuits the sleep.\n */\nexport const sleepWithJitter = (ms: number, signal?: AbortSignal): Promise<void> => {\n  const jittered = ms * (0.9 + Math.random() * 0.2)\n  return new Promise((resolve) => {\n    if (signal?.aborted) {\n      resolve()\n      return\n    }\n    let onAbort: (() => void) | undefined\n    const timer = setTimeout(() => {\n      if (onAbort && signal) signal.removeEventListener('abort', onAbort)\n      resolve()\n    }, jittered)\n    if (signal) {\n      onAbort = () => {\n        clearTimeout(timer)\n        resolve()\n      }\n      signal.addEventListener('abort', onAbort, { once: true })\n    }\n  })\n}\n\n/**\n * Parses an HTTP `Retry-After` header value (delta-seconds or HTTP-date) into milliseconds.\n *\n * @param raw - The header value.\n * @returns Milliseconds to wait, or `0` when the value cannot be parsed or is in the past.\n */\nexport const parseRetryAfter = (raw: string): number => {\n  const asNum = Number(raw)\n  if (Number.isFinite(asNum)) return asNum * 1000\n  const asDate = Date.parse(raw)\n  if (Number.isFinite(asDate)) return Math.max(0, asDate - Date.now())\n  return 0\n}\n\n/**\n * Combines several abort signals into one.\n *\n * @remarks\n * Returns the linked signal plus a `dispose` that detaches any listeners the fallback path\n * attached, so repeated links on a long-lived signal (one per retry attempt) do not accumulate\n * listeners. The native `AbortSignal.any` path self-manages its listeners, so `dispose` is a no-op\n * there.\n *\n * @param signals - The signals to combine.\n * @returns The linked signal and a `dispose` to tear down fallback listeners.\n */\nexport const linkAbortSignals = (\n  signals: ReadonlyArray<AbortSignal>\n): { signal: AbortSignal; dispose: () => void } => {\n  const anyFn = (AbortSignal as unknown as { any?: (sigs: AbortSignal[]) => AbortSignal }).any\n  if (typeof anyFn === 'function') {\n    return { signal: anyFn(signals as AbortSignal[]), dispose: () => {} }\n  }\n  // Fallback for older runtimes: hand-link via a fresh controller.\n  const ctrl = new AbortController()\n  const links: Array<{ sig: AbortSignal; handler: () => void }> = []\n  for (const sig of signals) {\n    if (sig.aborted) {\n      ctrl.abort()\n      break\n    }\n    const handler = () => ctrl.abort()\n    sig.addEventListener('abort', handler, { once: true })\n    links.push({ sig, handler })\n  }\n  return {\n    signal: ctrl.signal,\n    dispose: () => {\n      for (const { sig, handler } of links) sig.removeEventListener('abort', handler)\n      links.length = 0\n    },\n  }\n}\n"],"mappings":";;;;;;;;AA6BA,IAAa,kBAAkB,SAAiB,QAA+B;CAC7E,MAAM,OAAO,IAAI,eAAe;CAChC,MAAM,MAAM,IAAI,cAAc;CAC9B,OAAO,KAAK,IAAI,OAAO,KAAK,IAAI,GAAG,UAAU,CAAC,GAAG,GAAG;AACtD;;;;;;;;;;;;AAaA,IAAa,mBAAmB,IAAY,WAAwC;CAClF,MAAM,WAAW,MAAM,KAAM,KAAK,OAAO,IAAI;CAC7C,OAAO,IAAI,SAAS,YAAY;EAC9B,IAAI,QAAQ,SAAS;GACnB,QAAQ;GACR;EACF;EACA,IAAI;EACJ,MAAM,QAAQ,iBAAiB;GAC7B,IAAI,WAAW,QAAQ,OAAO,oBAAoB,SAAS,OAAO;GAClE,QAAQ;EACV,GAAG,QAAQ;EACX,IAAI,QAAQ;GACV,gBAAgB;IACd,aAAa,KAAK;IAClB,QAAQ;GACV;GACA,OAAO,iBAAiB,SAAS,SAAS,EAAE,MAAM,KAAK,CAAC;EAC1D;CACF,CAAC;AACH;;;;;;;AAQA,IAAa,mBAAmB,QAAwB;CACtD,MAAM,QAAQ,OAAO,GAAG;CACxB,IAAI,OAAO,SAAS,KAAK,GAAG,OAAO,QAAQ;CAC3C,MAAM,SAAS,KAAK,MAAM,GAAG;CAC7B,IAAI,OAAO,SAAS,MAAM,GAAG,OAAO,KAAK,IAAI,GAAG,SAAS,KAAK,IAAI,CAAC;CACnE,OAAO;AACT;;;;;;;;;;;;;AAcA,IAAa,oBACX,YACiD;CACjD,MAAM,QAAS,YAA0E;CACzF,IAAI,OAAO,UAAU,YACnB,OAAO;EAAE,QAAQ,MAAM,OAAwB;EAAG,eAAe,CAAC;CAAE;CAGtE,MAAM,OAAO,IAAI,gBAAgB;CACjC,MAAM,QAA0D,CAAC;CACjE,KAAK,MAAM,OAAO,SAAS;EACzB,IAAI,IAAI,SAAS;GACf,KAAK,MAAM;GACX;EACF;EACA,MAAM,gBAAgB,KAAK,MAAM;EACjC,IAAI,iBAAiB,SAAS,SAAS,EAAE,MAAM,KAAK,CAAC;EACrD,MAAM,KAAK;GAAE;GAAK;EAAQ,CAAC;CAC7B;CACA,OAAO;EACL,QAAQ,KAAK;EACb,eAAe;GACb,KAAK,MAAM,EAAE,KAAK,aAAa,OAAO,IAAI,oBAAoB,SAAS,OAAO;GAC9E,MAAM,SAAS;EACjB;CACF;AACF"}
+{"version":3,"file":"retry.mjs","names":[],"sources":["../../../src/lib/utils/retry.ts"],"sourcesContent":["/**\n * Environment-neutral retry/backoff/timeout primitives shared across HTTP-backed batteries.\n *\n * @module @nhtio/adk/lib/utils/retry\n *\n * @remarks\n * These are pure helpers — no DOM, no Node built-ins, only `setTimeout`, `AbortController`, and\n * `AbortSignal`, all of which exist in every target runtime (Node, browser, edge, workers). They\n * are shared (not duplicated) by the OpenAI Chat Completions battery and the OpenAI Embeddings\n * battery so retry behavior stays identical across the bundled batteries. The bundler inlines this\n * module into each consumer, so sharing introduces no build coupling.\n */\n\n/**\n * Minimal backoff configuration shape. Any retry config carrying `baseDelayMs`/`maxDelayMs`\n * satisfies it structurally, so batteries can pass their own richer config objects directly.\n */\nexport interface BackoffConfig {\n  /** Base delay in milliseconds for the first retry; doubles each attempt (default 500). */\n  baseDelayMs?: number\n  /** Upper bound in milliseconds on any single backoff delay (default 30_000). */\n  maxDelayMs?: number\n}\n\n/**\n * Exponential backoff with a ceiling: `min(baseDelayMs * 2^(attempt-1), maxDelayMs)`.\n *\n * @param attempt - 1-based attempt number.\n * @param cfg - Carries `baseDelayMs` (default 500) and `maxDelayMs` (default 30_000).\n * @returns The (un-jittered) delay in ms.\n */\nexport const computeBackoff = (attempt: number, cfg: BackoffConfig): number => {\n  const base = cfg.baseDelayMs ?? 500\n  const max = cfg.maxDelayMs ?? 30_000\n  return Math.min(base * Math.pow(2, attempt - 1), max)\n}\n\n/**\n * Abort-aware jittered sleep used for retry backoff.\n *\n * @remarks\n * Resolves (never rejects) the instant `signal` aborts, so an aborted caller does not stay parked\n * in a backoff delay — the caller's retry loop re-checks abort state immediately after and bails.\n * The timer and the abort listener are both torn down on whichever fires first, so nothing leaks.\n *\n * @param ms - Base delay in ms; jittered by ±10%.\n * @param signal - Optional abort signal that short-circuits the sleep.\n */\nexport const sleepWithJitter = (ms: number, signal?: AbortSignal): Promise<void> => {\n  const jittered = ms * (0.9 + Math.random() * 0.2)\n  return new Promise((resolve) => {\n    if (signal?.aborted) {\n      resolve()\n      return\n    }\n    let onAbort: (() => void) | undefined\n    const timer = setTimeout(() => {\n      if (onAbort && signal) signal.removeEventListener('abort', onAbort)\n      resolve()\n    }, jittered)\n    if (signal) {\n      onAbort = () => {\n        clearTimeout(timer)\n        resolve()\n      }\n      signal.addEventListener('abort', onAbort, { once: true })\n    }\n  })\n}\n\n/**\n * Parses an HTTP `Retry-After` header value (delta-seconds or HTTP-date) into milliseconds.\n *\n * @param raw - The header value.\n * @returns Milliseconds to wait, or `0` when the value cannot be parsed or is in the past.\n */\nexport const parseRetryAfter = (raw: string): number => {\n  const asNum = Number(raw)\n  if (Number.isFinite(asNum)) return asNum * 1000\n  const asDate = Date.parse(raw)\n  if (Number.isFinite(asDate)) return Math.max(0, asDate - Date.now())\n  return 0\n}\n\n/**\n * Combines several abort signals into one.\n *\n * @remarks\n * Returns the linked signal plus a `dispose` that detaches any listeners the fallback path\n * attached, so repeated links on a long-lived signal (one per retry attempt) do not accumulate\n * listeners. The native `AbortSignal.any` path self-manages its listeners, so `dispose` is a no-op\n * there.\n *\n * @param signals - The signals to combine.\n * @returns The linked signal and a `dispose` to tear down fallback listeners.\n */\nexport const linkAbortSignals = (\n  signals: ReadonlyArray<AbortSignal>\n): { signal: AbortSignal; dispose: () => void } => {\n  const anyFn = (AbortSignal as unknown as { any?: (sigs: AbortSignal[]) => AbortSignal }).any\n  if (typeof anyFn === 'function') {\n    return { signal: anyFn(signals as AbortSignal[]), dispose: () => {} }\n  }\n  // Fallback for older runtimes: hand-link via a fresh controller.\n  const ctrl = new AbortController()\n  const links: Array<{ sig: AbortSignal; handler: () => void }> = []\n  for (const sig of signals) {\n    if (sig.aborted) {\n      ctrl.abort()\n      break\n    }\n    const handler = () => ctrl.abort()\n    sig.addEventListener('abort', handler, { once: true })\n    links.push({ sig, handler })\n  }\n  return {\n    signal: ctrl.signal,\n    dispose: () => {\n      for (const { sig, handler } of links) sig.removeEventListener('abort', handler)\n      links.length = 0\n    },\n  }\n}\n"],"mappings":";;;;;;;;AA+BA,IAAa,kBAAkB,SAAiB,QAA+B;CAC7E,MAAM,OAAO,IAAI,eAAe;CAChC,MAAM,MAAM,IAAI,cAAc;CAC9B,OAAO,KAAK,IAAI,OAAO,KAAK,IAAI,GAAG,UAAU,CAAC,GAAG,GAAG;AACtD;;;;;;;;;;;;AAaA,IAAa,mBAAmB,IAAY,WAAwC;CAClF,MAAM,WAAW,MAAM,KAAM,KAAK,OAAO,IAAI;CAC7C,OAAO,IAAI,SAAS,YAAY;EAC9B,IAAI,QAAQ,SAAS;GACnB,QAAQ;GACR;EACF;EACA,IAAI;EACJ,MAAM,QAAQ,iBAAiB;GAC7B,IAAI,WAAW,QAAQ,OAAO,oBAAoB,SAAS,OAAO;GAClE,QAAQ;EACV,GAAG,QAAQ;EACX,IAAI,QAAQ;GACV,gBAAgB;IACd,aAAa,KAAK;IAClB,QAAQ;GACV;GACA,OAAO,iBAAiB,SAAS,SAAS,EAAE,MAAM,KAAK,CAAC;EAC1D;CACF,CAAC;AACH;;;;;;;AAQA,IAAa,mBAAmB,QAAwB;CACtD,MAAM,QAAQ,OAAO,GAAG;CACxB,IAAI,OAAO,SAAS,KAAK,GAAG,OAAO,QAAQ;CAC3C,MAAM,SAAS,KAAK,MAAM,GAAG;CAC7B,IAAI,OAAO,SAAS,MAAM,GAAG,OAAO,KAAK,IAAI,GAAG,SAAS,KAAK,IAAI,CAAC;CACnE,OAAO;AACT;;;;;;;;;;;;;AAcA,IAAa,oBACX,YACiD;CACjD,MAAM,QAAS,YAA0E;CACzF,IAAI,OAAO,UAAU,YACnB,OAAO;EAAE,QAAQ,MAAM,OAAwB;EAAG,eAAe,CAAC;CAAE;CAGtE,MAAM,OAAO,IAAI,gBAAgB;CACjC,MAAM,QAA0D,CAAC;CACjE,KAAK,MAAM,OAAO,SAAS;EACzB,IAAI,IAAI,SAAS;GACf,KAAK,MAAM;GACX;EACF;EACA,MAAM,gBAAgB,KAAK,MAAM;EACjC,IAAI,iBAAiB,SAAS,SAAS,EAAE,MAAM,KAAK,CAAC;EACrD,MAAM,KAAK;GAAE;GAAK;EAAQ,CAAC;CAC7B;CACA,OAAO;EACL,QAAQ,KAAK;EACb,eAAe;GACb,KAAK,MAAM,EAAE,KAAK,aAAa,OAAO,IAAI,oBAAoB,SAAS,OAAO;GAC9E,MAAM,SAAS;EACjB;CACF;AACF"}