@nhtio/adk 1.20260607.2 → 1.20260609.1

package/batteries/tools/parsing.cjs

@@ -1,9 +1,9 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_chunk = require("../../chunk-Ble4zEEl.js");
-const require_tool_registry = require("../../tool_registry-DYUYqXvo.js");
-const require_tool = require("../../tool-CVyZkFC7.js");
-require("../../common-Cj8TaQ9U.js");
-const require_spooled_markdown_artifact = require("../../spooled_markdown_artifact-CALSDxIx.js");
+const require_tool_registry = require("../../tool_registry-CKJPze3j.js");
+const require_tool = require("../../tool-D5WGVIcI.js");
+require("../../common-DZl3ADJs.js");
+const require_spooled_markdown_artifact = require("../../spooled_markdown_artifact-ClX72lek.js");
 require("../../guards.cjs");
 let _nhtio_validation = require("@nhtio/validation");
 let js_yaml = require("js-yaml");
@@ -73,7 +73,11 @@ var parseYamlTool = new require_tool.Tool({
 		const { text } = args;
 		try {
 			const parsed = (0, js_yaml.load)(text);
-			return JSON.stringify(parsed, null, 2);
+			if (parsed === void 0) return "null";
+			return JSON.stringify(parsed, (_key, value) => {
+				if (typeof value === "number" && !Number.isFinite(value)) return Number.isNaN(value) ? ".NaN" : value > 0 ? ".inf" : "-.inf";
+				return value;
+			}, 2);
 		} catch (err) {
 			return `Error: Invalid YAML — ${require_tool_registry.isError(err) ? err.message : String(err)}`;
 		}

package/batteries/tools/parsing.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"parsing.cjs","names":[],"sources":["../../../src/batteries/tools/parsing/index.ts"],"sourcesContent":["/**\n * Pre-constructed tools for parsing CSV, TSV, JSON, YAML, and other structured text formats.\n *\n * @module @nhtio/adk/batteries/tools/parsing\n *\n * @remarks\n * Pre-constructed bundled tools for the `parsing` category. Import individually, the whole\n * category, or import every tool via `@nhtio/adk/batteries`.\n */\n\nimport { load as parseYaml } from 'js-yaml'\nimport { default as Papa } from 'papaparse'\nimport { isError } from '@nhtio/adk/guards'\nimport { validator } from '@nhtio/validation'\nimport { Tool, SpooledJsonArtifact } from '@nhtio/adk/common'\n\n/**\n * Parse a CSV or TSV string into a JSON array.\n *\n * @remarks\n * With `has_header: true` (default), each row becomes an object keyed by column name. Without a\n * header, rows are returned as positional arrays. `delimiter` auto-detects when omitted; pass\n * `\"\\t\"` for TSV. Rows are clipped to `limit` (default 1000, max 10000). Parse warnings are\n * prepended to the output.\n */\nexport const parseCsvTool = new Tool({\n  name: 'parse_csv',\n  description:\n    'Parse a CSV or TSV string into a JSON array. With a header row, returns objects keyed by column name. Without, returns arrays of values.',\n  inputSchema: validator.object({\n    text: validator.string().required().description('CSV or TSV text to parse'),\n    has_header: validator\n      .boolean()\n      .default(true)\n      .description('First row is a header row (default: true)'),\n    delimiter: validator\n      .string()\n      .default('')\n      .allow('')\n      .description('Field delimiter — auto-detected if omitted. Use \"\\\\t\" for TSV.'),\n    limit: validator.number().default(1000).description('Maximum rows to return (default: 1000)'),\n  }),\n  artifactConstructor: () => SpooledJsonArtifact,\n  handler: async (args) => {\n    const {\n      text,\n      has_header: hasHeader,\n      delimiter,\n      limit: rawLimit,\n    } = args as {\n      text: string\n      has_header: boolean\n      delimiter: string\n      limit: number\n    }\n    const limit = Math.min(10_000, Math.max(1, Math.floor(rawLimit)))\n\n    try {\n      const result = Papa.parse<unknown>(text.trim(), {\n        header: hasHeader,\n        delimiter: delimiter || undefined,\n        skipEmptyLines: true,\n        dynamicTyping: true,\n      })\n\n      const rows = (result.data as unknown[]).slice(0, limit)\n      const warnings =\n        result.errors.length > 0\n          ? `Parse warnings: ${result.errors\n              .slice(0, 3)\n              .map((e) => e.message)\n              .join('; ')}\\n\\n`\n          : ''\n      const truncated =\n        result.data.length > limit ? `\\n\\n(Showing ${limit} of ${result.data.length} rows)` : ''\n\n      return warnings + JSON.stringify(rows, null, 2) + truncated\n    } catch (err) {\n      return `Error: ${isError(err) ? err.message : String(err)}`\n    }\n  },\n})\n\n/**\n * Parse a YAML string into JSON.\n *\n * @remarks\n * Returns a pretty-printed JSON representation of the parsed YAML document. Invalid YAML\n * returns an error string.\n */\nexport const parseYamlTool = new Tool({\n  name: 'parse_yaml',\n  description: 'Parse a YAML string and return the equivalent JSON.',\n  inputSchema: validator.object({\n    text: validator.string().required().description('YAML text to parse'),\n  }),\n  artifactConstructor: () => SpooledJsonArtifact,\n  handler: async (args) => {\n    const { text } = args as { text: string }\n    try {\n      const parsed = parseYaml(text)\n      return JSON.stringify(parsed, null, 2)\n    } catch (err) {\n      return `Error: Invalid YAML — ${isError(err) ? err.message : String(err)}`\n    }\n  },\n})\n\n/**\n * Extract key-value pairs from text.\n *\n * @remarks\n * Handles `.env` files, config files, and query strings. `kv_delimiter` chooses the\n * key→value separator (`=`, `:`, or `auto`); `pair_delimiter` selects how pairs are separated\n * (`newline`, `comma`, `semicolon`, `ampersand`). Surrounding single or double quotes around\n * values are stripped. Comment lines starting with `#` are skipped by default.\n */\nexport const parseKvTool = new Tool({\n  name: 'parse_kv',\n  description:\n    'Extract key-value pairs from text (e.g. .env files, config files, query strings). Returns a JSON object.',\n  inputSchema: validator.object({\n    text: validator.string().required().description('Text containing key-value pairs'),\n    kv_delimiter: validator\n      .string()\n      .valid('=', ':', 'auto')\n      .default('auto')\n      .description('Separator between key and value (default: auto-detect)'),\n    pair_delimiter: validator\n      .string()\n      .valid('newline', 'comma', 'semicolon', 'ampersand')\n      .default('newline')\n      .description('Separator between pairs (default: newline)'),\n    skip_comments: validator\n      .boolean()\n      .default(true)\n      .description('Skip lines starting with # (default: true)'),\n  }),\n  artifactConstructor: () => SpooledJsonArtifact,\n  handler: async (args) => {\n    const {\n      text,\n      kv_delimiter: kvDelim,\n      pair_delimiter: pairDelimKey,\n      skip_comments: skipComments,\n    } = args as {\n      text: string\n      kv_delimiter: string\n      pair_delimiter: string\n      skip_comments: boolean\n    }\n\n    const pairDelimMap: Record<string, string> = {\n      newline: '\\n',\n      comma: ',',\n      semicolon: ';',\n      ampersand: '&',\n    }\n    const pairDelim = pairDelimMap[pairDelimKey] ?? '\\n'\n\n    const result: Record<string, string> = {}\n\n    for (const raw of text.split(pairDelim)) {\n      const line = raw.trim()\n      if (line === '') continue\n      if (skipComments && line.startsWith('#')) continue\n\n      const delim =\n        kvDelim === 'auto' ? (line.includes('=') ? '=' : line.includes(':') ? ':' : null) : kvDelim\n      if (!delim) continue\n\n      const sepIdx = line.indexOf(delim)\n      if (sepIdx === -1) continue\n\n      const key = line.slice(0, sepIdx).trim()\n      let value = line.slice(sepIdx + delim.length).trim()\n\n      if (\n        (value.startsWith('\"') && value.endsWith('\"')) ||\n        (value.startsWith(\"'\") && value.endsWith(\"'\"))\n      ) {\n        value = value.slice(1, -1)\n      }\n\n      if (key) result[key] = value\n    }\n\n    return JSON.stringify(result, null, 2)\n  },\n})\n\n/**\n * Detect the most likely field delimiter in a CSV-like text sample.\n *\n * @remarks\n * Tries comma, tab, semicolon, pipe, and colon. Scores each by mean field count divided by\n * variance (so consistent row widths beat noisy splits). Looks at up to the first 20 lines of\n * the first 5000 characters.\n */\nexport const detectDelimiterTool = new Tool({\n  name: 'detect_delimiter',\n  description: 'Detect the most likely field delimiter in a CSV-like text sample.',\n  inputSchema: validator.object({\n    text: validator.string().required().description('Sample of the delimited text to analyze'),\n  }),\n  handler: async (args) => {\n    const { text } = args as { text: string }\n    const sample = text.slice(0, 5000)\n    const lines = sample\n      .split('\\n')\n      .map((l) => l.trim())\n      .filter((l) => l.length > 0)\n      .slice(0, 20)\n\n    if (lines.length === 0) return 'Error: No lines to analyze.'\n\n    const candidates: Array<{ delim: string; name: string }> = [\n      { delim: ',', name: 'comma' },\n      { delim: '\\t', name: 'tab' },\n      { delim: ';', name: 'semicolon' },\n      { delim: '|', name: 'pipe' },\n      { delim: ':', name: 'colon' },\n    ]\n\n    let best = { name: 'comma', delim: ',', score: -1, avgFields: 0 }\n\n    for (const { delim, name } of candidates) {\n      const counts = lines.map((l) => l.split(delim).length - 1)\n      const avg = counts.reduce((a, b) => a + b, 0) / counts.length\n      if (avg === 0) continue\n      const fieldVariance = counts.reduce((a, b) => a + (b - avg) ** 2, 0) / counts.length\n      const score = avg / (1 + fieldVariance)\n      if (score > best.score) {\n        best = { name, delim, score, avgFields: Number.parseFloat((avg + 1).toFixed(1)) }\n      }\n    }\n\n    return `Detected delimiter: ${best.name} (\"${best.delim === '\\t' ? '\\\\t' : best.delim}\") — ~${best.avgFields} fields per row`\n  },\n})\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,IAAa,eAAe,IAAI,aAAA,KAAK;CACnC,MAAM;CACN,aACE;CACF,aAAa,kBAAA,UAAU,OAAO;EAC5B,MAAM,kBAAA,UAAU,OAAO,EAAE,SAAS,EAAE,YAAY,0BAA0B;EAC1E,YAAY,kBAAA,UACT,QAAQ,EACR,QAAQ,IAAI,EACZ,YAAY,2CAA2C;EAC1D,WAAW,kBAAA,UACR,OAAO,EACP,QAAQ,EAAE,EACV,MAAM,EAAE,EACR,YAAY,kEAAgE;EAC/E,OAAO,kBAAA,UAAU,OAAO,EAAE,QAAQ,GAAI,EAAE,YAAY,wCAAwC;CAC9F,CAAC;CACD,2BAA2B,kCAAA;CAC3B,SAAS,OAAO,SAAS;EACvB,MAAM,EACJ,MACA,YAAY,WACZ,WACA,OAAO,aACL;EAMJ,MAAM,QAAQ,KAAK,IAAI,KAAQ,KAAK,IAAI,GAAG,KAAK,MAAM,QAAQ,CAAC,CAAC;EAEhE,IAAI;GACF,MAAM,SAAS,UAAA,QAAK,MAAe,KAAK,KAAK,GAAG;IAC9C,QAAQ;IACR,WAAW,aAAa,KAAA;IACxB,gBAAgB;IAChB,eAAe;GACjB,CAAC;GAED,MAAM,OAAQ,OAAO,KAAmB,MAAM,GAAG,KAAK;GACtD,MAAM,WACJ,OAAO,OAAO,SAAS,IACnB,mBAAmB,OAAO,OACvB,MAAM,GAAG,CAAC,EACV,KAAK,MAAM,EAAE,OAAO,EACpB,KAAK,IAAI,EAAE,QACd;GACN,MAAM,YACJ,OAAO,KAAK,SAAS,QAAQ,gBAAgB,MAAM,MAAM,OAAO,KAAK,OAAO,UAAU;GAExF,OAAO,WAAW,KAAK,UAAU,MAAM,MAAM,CAAC,IAAI;EACpD,SAAS,KAAK;GACZ,OAAO,UAAU,sBAAA,QAAQ,GAAG,IAAI,IAAI,UAAU,OAAO,GAAG;EAC1D;CACF;AACF,CAAC;;;;;;;;AASD,IAAa,gBAAgB,IAAI,aAAA,KAAK;CACpC,MAAM;CACN,aAAa;CACb,aAAa,kBAAA,UAAU,OAAO,EAC5B,MAAM,kBAAA,UAAU,OAAO,EAAE,SAAS,EAAE,YAAY,oBAAoB,EACtE,CAAC;CACD,2BAA2B,kCAAA;CAC3B,SAAS,OAAO,SAAS;EACvB,MAAM,EAAE,SAAS;EACjB,IAAI;GACF,MAAM,UAAA,GAAA,QAAA,MAAmB,IAAI;GAC7B,OAAO,KAAK,UAAU,QAAQ,MAAM,CAAC;EACvC,SAAS,KAAK;GACZ,OAAO,yBAAyB,sBAAA,QAAQ,GAAG,IAAI,IAAI,UAAU,OAAO,GAAG;EACzE;CACF;AACF,CAAC;;;;;;;;;;AAWD,IAAa,cAAc,IAAI,aAAA,KAAK;CAClC,MAAM;CACN,aACE;CACF,aAAa,kBAAA,UAAU,OAAO;EAC5B,MAAM,kBAAA,UAAU,OAAO,EAAE,SAAS,EAAE,YAAY,iCAAiC;EACjF,cAAc,kBAAA,UACX,OAAO,EACP,MAAM,KAAK,KAAK,MAAM,EACtB,QAAQ,MAAM,EACd,YAAY,wDAAwD;EACvE,gBAAgB,kBAAA,UACb,OAAO,EACP,MAAM,WAAW,SAAS,aAAa,WAAW,EAClD,QAAQ,SAAS,EACjB,YAAY,4CAA4C;EAC3D,eAAe,kBAAA,UACZ,QAAQ,EACR,QAAQ,IAAI,EACZ,YAAY,4CAA4C;CAC7D,CAAC;CACD,2BAA2B,kCAAA;CAC3B,SAAS,OAAO,SAAS;EACvB,MAAM,EACJ,MACA,cAAc,SACd,gBAAgB,cAChB,eAAe,iBACb;EAaJ,MAAM,YAAY;GALhB,SAAS;GACT,OAAO;GACP,WAAW;GACX,WAAW;EAEK,EAAa,iBAAiB;EAEhD,MAAM,SAAiC,CAAC;EAExC,KAAK,MAAM,OAAO,KAAK,MAAM,SAAS,GAAG;GACvC,MAAM,OAAO,IAAI,KAAK;GACtB,IAAI,SAAS,IAAI;GACjB,IAAI,gBAAgB,KAAK,WAAW,GAAG,GAAG;GAE1C,MAAM,QACJ,YAAY,SAAU,KAAK,SAAS,GAAG,IAAI,MAAM,KAAK,SAAS,GAAG,IAAI,MAAM,OAAQ;GACtF,IAAI,CAAC,OAAO;GAEZ,MAAM,SAAS,KAAK,QAAQ,KAAK;GACjC,IAAI,WAAW,IAAI;GAEnB,MAAM,MAAM,KAAK,MAAM,GAAG,MAAM,EAAE,KAAK;GACvC,IAAI,QAAQ,KAAK,MAAM,SAAS,MAAM,MAAM,EAAE,KAAK;GAEnD,IACG,MAAM,WAAW,IAAG,KAAK,MAAM,SAAS,IAAG,KAC3C,MAAM,WAAW,GAAG,KAAK,MAAM,SAAS,GAAG,GAE5C,QAAQ,MAAM,MAAM,GAAG,EAAE;GAG3B,IAAI,KAAK,OAAO,OAAO;EACzB;EAEA,OAAO,KAAK,UAAU,QAAQ,MAAM,CAAC;CACvC;AACF,CAAC;;;;;;;;;AAUD,IAAa,sBAAsB,IAAI,aAAA,KAAK;CAC1C,MAAM;CACN,aAAa;CACb,aAAa,kBAAA,UAAU,OAAO,EAC5B,MAAM,kBAAA,UAAU,OAAO,EAAE,SAAS,EAAE,YAAY,yCAAyC,EAC3F,CAAC;CACD,SAAS,OAAO,SAAS;EACvB,MAAM,EAAE,SAAS;EAEjB,MAAM,QADS,KAAK,MAAM,GAAG,GACf,EACX,MAAM,IAAI,EACV,KAAK,MAAM,EAAE,KAAK,CAAC,EACnB,QAAQ,MAAM,EAAE,SAAS,CAAC,EAC1B,MAAM,GAAG,EAAE;EAEd,IAAI,MAAM,WAAW,GAAG,OAAO;EAE/B,MAAM,aAAqD;GACzD;IAAE,OAAO;IAAK,MAAM;GAAQ;GAC5B;IAAE,OAAO;IAAM,MAAM;GAAM;GAC3B;IAAE,OAAO;IAAK,MAAM;GAAY;GAChC;IAAE,OAAO;IAAK,MAAM;GAAO;GAC3B;IAAE,OAAO;IAAK,MAAM;GAAQ;EAC9B;EAEA,IAAI,OAAO;GAAE,MAAM;GAAS,OAAO;GAAK,OAAO;GAAI,WAAW;EAAE;EAEhE,KAAK,MAAM,EAAE,OAAO,UAAU,YAAY;GACxC,MAAM,SAAS,MAAM,KAAK,MAAM,EAAE,MAAM,KAAK,EAAE,SAAS,CAAC;GACzD,MAAM,MAAM,OAAO,QAAQ,GAAG,MAAM,IAAI,GAAG,CAAC,IAAI,OAAO;GACvD,IAAI,QAAQ,GAAG;GAEf,MAAM,QAAQ,OAAO,IADC,OAAO,QAAQ,GAAG,MAAM,KAAK,IAAI,QAAQ,GAAG,CAAC,IAAI,OAAO;GAE9E,IAAI,QAAQ,KAAK,OACf,OAAO;IAAE;IAAM;IAAO;IAAO,WAAW,OAAO,YAAY,MAAM,GAAG,QAAQ,CAAC,CAAC;GAAE;EAEpF;EAEA,OAAO,uBAAuB,KAAK,KAAK,KAAK,KAAK,UAAU,MAAO,QAAQ,KAAK,MAAM,QAAQ,KAAK,UAAU;CAC/G;AACF,CAAC"}
+{"version":3,"file":"parsing.cjs","names":[],"sources":["../../../src/batteries/tools/parsing/index.ts"],"sourcesContent":["/**\n * Pre-constructed tools for parsing CSV, TSV, JSON, YAML, and other structured text formats.\n *\n * @module @nhtio/adk/batteries/tools/parsing\n *\n * @remarks\n * Pre-constructed bundled tools for the `parsing` category. Import individually, the whole\n * category, or import every tool via `@nhtio/adk/batteries`.\n */\n\nimport { load as parseYaml } from 'js-yaml'\nimport { default as Papa } from 'papaparse'\nimport { isError } from '@nhtio/adk/guards'\nimport { validator } from '@nhtio/validation'\nimport { Tool, SpooledJsonArtifact } from '@nhtio/adk/common'\n\n/**\n * Parse a CSV or TSV string into a JSON array.\n *\n * @remarks\n * With `has_header: true` (default), each row becomes an object keyed by column name. Without a\n * header, rows are returned as positional arrays. `delimiter` auto-detects when omitted; pass\n * `\"\\t\"` for TSV. Rows are clipped to `limit` (default 1000, max 10000). Parse warnings are\n * prepended to the output.\n */\nexport const parseCsvTool = new Tool({\n  name: 'parse_csv',\n  description:\n    'Parse a CSV or TSV string into a JSON array. With a header row, returns objects keyed by column name. Without, returns arrays of values.',\n  inputSchema: validator.object({\n    text: validator.string().required().description('CSV or TSV text to parse'),\n    has_header: validator\n      .boolean()\n      .default(true)\n      .description('First row is a header row (default: true)'),\n    delimiter: validator\n      .string()\n      .default('')\n      .allow('')\n      .description('Field delimiter — auto-detected if omitted. Use \"\\\\t\" for TSV.'),\n    limit: validator.number().default(1000).description('Maximum rows to return (default: 1000)'),\n  }),\n  artifactConstructor: () => SpooledJsonArtifact,\n  handler: async (args) => {\n    const {\n      text,\n      has_header: hasHeader,\n      delimiter,\n      limit: rawLimit,\n    } = args as {\n      text: string\n      has_header: boolean\n      delimiter: string\n      limit: number\n    }\n    const limit = Math.min(10_000, Math.max(1, Math.floor(rawLimit)))\n\n    try {\n      const result = Papa.parse<unknown>(text.trim(), {\n        header: hasHeader,\n        delimiter: delimiter || undefined,\n        skipEmptyLines: true,\n        dynamicTyping: true,\n      })\n\n      const rows = (result.data as unknown[]).slice(0, limit)\n      const warnings =\n        result.errors.length > 0\n          ? `Parse warnings: ${result.errors\n              .slice(0, 3)\n              .map((e) => e.message)\n              .join('; ')}\\n\\n`\n          : ''\n      const truncated =\n        result.data.length > limit ? `\\n\\n(Showing ${limit} of ${result.data.length} rows)` : ''\n\n      return warnings + JSON.stringify(rows, null, 2) + truncated\n    } catch (err) {\n      return `Error: ${isError(err) ? err.message : String(err)}`\n    }\n  },\n})\n\n/**\n * Parse a YAML string into JSON.\n *\n * @remarks\n * Returns a pretty-printed JSON representation of the parsed YAML document. Invalid YAML\n * returns an error string.\n */\nexport const parseYamlTool = new Tool({\n  name: 'parse_yaml',\n  description: 'Parse a YAML string and return the equivalent JSON.',\n  inputSchema: validator.object({\n    text: validator.string().required().description('YAML text to parse'),\n  }),\n  artifactConstructor: () => SpooledJsonArtifact,\n  handler: async (args) => {\n    const { text } = args as { text: string }\n    try {\n      const parsed = parseYaml(text)\n      // An empty / whitespace-only / BOM-only document parses to `undefined`, and\n      // `JSON.stringify(undefined)` returns the JS value `undefined` (not a string), breaking the\n      // tool's string-return contract. Normalise that empty document to JSON `null`.\n      if (parsed === undefined) return 'null'\n      // YAML permits .NaN / .inf / -.inf, which `JSON.stringify` would silently turn into `null`,\n      // losing the value. Render non-finite numbers as their YAML token strings so the information\n      // survives the JSON round-trip instead of being corrupted to null.\n      return JSON.stringify(\n        parsed,\n        (_key, value) => {\n          if (typeof value === 'number' && !Number.isFinite(value)) {\n            return Number.isNaN(value) ? '.NaN' : value > 0 ? '.inf' : '-.inf'\n          }\n          return value\n        },\n        2\n      )\n    } catch (err) {\n      return `Error: Invalid YAML — ${isError(err) ? err.message : String(err)}`\n    }\n  },\n})\n\n/**\n * Extract key-value pairs from text.\n *\n * @remarks\n * Handles `.env` files, config files, and query strings. `kv_delimiter` chooses the\n * key→value separator (`=`, `:`, or `auto`); `pair_delimiter` selects how pairs are separated\n * (`newline`, `comma`, `semicolon`, `ampersand`). Surrounding single or double quotes around\n * values are stripped. Comment lines starting with `#` are skipped by default.\n */\nexport const parseKvTool = new Tool({\n  name: 'parse_kv',\n  description:\n    'Extract key-value pairs from text (e.g. .env files, config files, query strings). Returns a JSON object.',\n  inputSchema: validator.object({\n    text: validator.string().required().description('Text containing key-value pairs'),\n    kv_delimiter: validator\n      .string()\n      .valid('=', ':', 'auto')\n      .default('auto')\n      .description('Separator between key and value (default: auto-detect)'),\n    pair_delimiter: validator\n      .string()\n      .valid('newline', 'comma', 'semicolon', 'ampersand')\n      .default('newline')\n      .description('Separator between pairs (default: newline)'),\n    skip_comments: validator\n      .boolean()\n      .default(true)\n      .description('Skip lines starting with # (default: true)'),\n  }),\n  artifactConstructor: () => SpooledJsonArtifact,\n  handler: async (args) => {\n    const {\n      text,\n      kv_delimiter: kvDelim,\n      pair_delimiter: pairDelimKey,\n      skip_comments: skipComments,\n    } = args as {\n      text: string\n      kv_delimiter: string\n      pair_delimiter: string\n      skip_comments: boolean\n    }\n\n    const pairDelimMap: Record<string, string> = {\n      newline: '\\n',\n      comma: ',',\n      semicolon: ';',\n      ampersand: '&',\n    }\n    const pairDelim = pairDelimMap[pairDelimKey] ?? '\\n'\n\n    const result: Record<string, string> = {}\n\n    for (const raw of text.split(pairDelim)) {\n      const line = raw.trim()\n      if (line === '') continue\n      if (skipComments && line.startsWith('#')) continue\n\n      const delim =\n        kvDelim === 'auto' ? (line.includes('=') ? '=' : line.includes(':') ? ':' : null) : kvDelim\n      if (!delim) continue\n\n      const sepIdx = line.indexOf(delim)\n      if (sepIdx === -1) continue\n\n      const key = line.slice(0, sepIdx).trim()\n      let value = line.slice(sepIdx + delim.length).trim()\n\n      if (\n        (value.startsWith('\"') && value.endsWith('\"')) ||\n        (value.startsWith(\"'\") && value.endsWith(\"'\"))\n      ) {\n        value = value.slice(1, -1)\n      }\n\n      if (key) result[key] = value\n    }\n\n    return JSON.stringify(result, null, 2)\n  },\n})\n\n/**\n * Detect the most likely field delimiter in a CSV-like text sample.\n *\n * @remarks\n * Tries comma, tab, semicolon, pipe, and colon. Scores each by mean field count divided by\n * variance (so consistent row widths beat noisy splits). Looks at up to the first 20 lines of\n * the first 5000 characters.\n */\nexport const detectDelimiterTool = new Tool({\n  name: 'detect_delimiter',\n  description: 'Detect the most likely field delimiter in a CSV-like text sample.',\n  inputSchema: validator.object({\n    text: validator.string().required().description('Sample of the delimited text to analyze'),\n  }),\n  handler: async (args) => {\n    const { text } = args as { text: string }\n    const sample = text.slice(0, 5000)\n    const lines = sample\n      .split('\\n')\n      .map((l) => l.trim())\n      .filter((l) => l.length > 0)\n      .slice(0, 20)\n\n    if (lines.length === 0) return 'Error: No lines to analyze.'\n\n    const candidates: Array<{ delim: string; name: string }> = [\n      { delim: ',', name: 'comma' },\n      { delim: '\\t', name: 'tab' },\n      { delim: ';', name: 'semicolon' },\n      { delim: '|', name: 'pipe' },\n      { delim: ':', name: 'colon' },\n    ]\n\n    let best = { name: 'comma', delim: ',', score: -1, avgFields: 0 }\n\n    for (const { delim, name } of candidates) {\n      const counts = lines.map((l) => l.split(delim).length - 1)\n      const avg = counts.reduce((a, b) => a + b, 0) / counts.length\n      if (avg === 0) continue\n      const fieldVariance = counts.reduce((a, b) => a + (b - avg) ** 2, 0) / counts.length\n      const score = avg / (1 + fieldVariance)\n      if (score > best.score) {\n        best = { name, delim, score, avgFields: Number.parseFloat((avg + 1).toFixed(1)) }\n      }\n    }\n\n    return `Detected delimiter: ${best.name} (\"${best.delim === '\\t' ? '\\\\t' : best.delim}\") — ~${best.avgFields} fields per row`\n  },\n})\n"],"mappings":"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"}

package/batteries/tools/parsing.mjs

@@ -1,7 +1,7 @@
-import { o as isError } from "../../tool_registry-D1pSSlsd.mjs";
-import { t as Tool } from "../../tool-CMhaDRNd.mjs";
-import "../../common-BT0nfCi9.mjs";
-import { n as SpooledJsonArtifact } from "../../spooled_markdown_artifact-Ci5UL7l4.mjs";
+import { o as isError } from "../../tool_registry-791Vrjtf.mjs";
+import { t as Tool } from "../../tool-wMYMVl60.mjs";
+import "../../common-DYDUi99O.mjs";
+import { n as SpooledJsonArtifact } from "../../spooled_markdown_artifact-wkrBF3oX.mjs";
 import "../../guards.mjs";
 import { validator } from "@nhtio/validation";
 import { load } from "js-yaml";
@@ -70,7 +70,11 @@ var parseYamlTool = new Tool({
 		const { text } = args;
 		try {
 			const parsed = load(text);
-			return JSON.stringify(parsed, null, 2);
+			if (parsed === void 0) return "null";
+			return JSON.stringify(parsed, (_key, value) => {
+				if (typeof value === "number" && !Number.isFinite(value)) return Number.isNaN(value) ? ".NaN" : value > 0 ? ".inf" : "-.inf";
+				return value;
+			}, 2);
 		} catch (err) {
 			return `Error: Invalid YAML — ${isError(err) ? err.message : String(err)}`;
 		}

package/batteries/tools/parsing.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"parsing.mjs","names":[],"sources":["../../../src/batteries/tools/parsing/index.ts"],"sourcesContent":["/**\n * Pre-constructed tools for parsing CSV, TSV, JSON, YAML, and other structured text formats.\n *\n * @module @nhtio/adk/batteries/tools/parsing\n *\n * @remarks\n * Pre-constructed bundled tools for the `parsing` category. Import individually, the whole\n * category, or import every tool via `@nhtio/adk/batteries`.\n */\n\nimport { load as parseYaml } from 'js-yaml'\nimport { default as Papa } from 'papaparse'\nimport { isError } from '@nhtio/adk/guards'\nimport { validator } from '@nhtio/validation'\nimport { Tool, SpooledJsonArtifact } from '@nhtio/adk/common'\n\n/**\n * Parse a CSV or TSV string into a JSON array.\n *\n * @remarks\n * With `has_header: true` (default), each row becomes an object keyed by column name. Without a\n * header, rows are returned as positional arrays. `delimiter` auto-detects when omitted; pass\n * `\"\\t\"` for TSV. Rows are clipped to `limit` (default 1000, max 10000). Parse warnings are\n * prepended to the output.\n */\nexport const parseCsvTool = new Tool({\n  name: 'parse_csv',\n  description:\n    'Parse a CSV or TSV string into a JSON array. With a header row, returns objects keyed by column name. Without, returns arrays of values.',\n  inputSchema: validator.object({\n    text: validator.string().required().description('CSV or TSV text to parse'),\n    has_header: validator\n      .boolean()\n      .default(true)\n      .description('First row is a header row (default: true)'),\n    delimiter: validator\n      .string()\n      .default('')\n      .allow('')\n      .description('Field delimiter — auto-detected if omitted. Use \"\\\\t\" for TSV.'),\n    limit: validator.number().default(1000).description('Maximum rows to return (default: 1000)'),\n  }),\n  artifactConstructor: () => SpooledJsonArtifact,\n  handler: async (args) => {\n    const {\n      text,\n      has_header: hasHeader,\n      delimiter,\n      limit: rawLimit,\n    } = args as {\n      text: string\n      has_header: boolean\n      delimiter: string\n      limit: number\n    }\n    const limit = Math.min(10_000, Math.max(1, Math.floor(rawLimit)))\n\n    try {\n      const result = Papa.parse<unknown>(text.trim(), {\n        header: hasHeader,\n        delimiter: delimiter || undefined,\n        skipEmptyLines: true,\n        dynamicTyping: true,\n      })\n\n      const rows = (result.data as unknown[]).slice(0, limit)\n      const warnings =\n        result.errors.length > 0\n          ? `Parse warnings: ${result.errors\n              .slice(0, 3)\n              .map((e) => e.message)\n              .join('; ')}\\n\\n`\n          : ''\n      const truncated =\n        result.data.length > limit ? `\\n\\n(Showing ${limit} of ${result.data.length} rows)` : ''\n\n      return warnings + JSON.stringify(rows, null, 2) + truncated\n    } catch (err) {\n      return `Error: ${isError(err) ? err.message : String(err)}`\n    }\n  },\n})\n\n/**\n * Parse a YAML string into JSON.\n *\n * @remarks\n * Returns a pretty-printed JSON representation of the parsed YAML document. Invalid YAML\n * returns an error string.\n */\nexport const parseYamlTool = new Tool({\n  name: 'parse_yaml',\n  description: 'Parse a YAML string and return the equivalent JSON.',\n  inputSchema: validator.object({\n    text: validator.string().required().description('YAML text to parse'),\n  }),\n  artifactConstructor: () => SpooledJsonArtifact,\n  handler: async (args) => {\n    const { text } = args as { text: string }\n    try {\n      const parsed = parseYaml(text)\n      return JSON.stringify(parsed, null, 2)\n    } catch (err) {\n      return `Error: Invalid YAML — ${isError(err) ? err.message : String(err)}`\n    }\n  },\n})\n\n/**\n * Extract key-value pairs from text.\n *\n * @remarks\n * Handles `.env` files, config files, and query strings. `kv_delimiter` chooses the\n * key→value separator (`=`, `:`, or `auto`); `pair_delimiter` selects how pairs are separated\n * (`newline`, `comma`, `semicolon`, `ampersand`). Surrounding single or double quotes around\n * values are stripped. Comment lines starting with `#` are skipped by default.\n */\nexport const parseKvTool = new Tool({\n  name: 'parse_kv',\n  description:\n    'Extract key-value pairs from text (e.g. .env files, config files, query strings). Returns a JSON object.',\n  inputSchema: validator.object({\n    text: validator.string().required().description('Text containing key-value pairs'),\n    kv_delimiter: validator\n      .string()\n      .valid('=', ':', 'auto')\n      .default('auto')\n      .description('Separator between key and value (default: auto-detect)'),\n    pair_delimiter: validator\n      .string()\n      .valid('newline', 'comma', 'semicolon', 'ampersand')\n      .default('newline')\n      .description('Separator between pairs (default: newline)'),\n    skip_comments: validator\n      .boolean()\n      .default(true)\n      .description('Skip lines starting with # (default: true)'),\n  }),\n  artifactConstructor: () => SpooledJsonArtifact,\n  handler: async (args) => {\n    const {\n      text,\n      kv_delimiter: kvDelim,\n      pair_delimiter: pairDelimKey,\n      skip_comments: skipComments,\n    } = args as {\n      text: string\n      kv_delimiter: string\n      pair_delimiter: string\n      skip_comments: boolean\n    }\n\n    const pairDelimMap: Record<string, string> = {\n      newline: '\\n',\n      comma: ',',\n      semicolon: ';',\n      ampersand: '&',\n    }\n    const pairDelim = pairDelimMap[pairDelimKey] ?? '\\n'\n\n    const result: Record<string, string> = {}\n\n    for (const raw of text.split(pairDelim)) {\n      const line = raw.trim()\n      if (line === '') continue\n      if (skipComments && line.startsWith('#')) continue\n\n      const delim =\n        kvDelim === 'auto' ? (line.includes('=') ? '=' : line.includes(':') ? ':' : null) : kvDelim\n      if (!delim) continue\n\n      const sepIdx = line.indexOf(delim)\n      if (sepIdx === -1) continue\n\n      const key = line.slice(0, sepIdx).trim()\n      let value = line.slice(sepIdx + delim.length).trim()\n\n      if (\n        (value.startsWith('\"') && value.endsWith('\"')) ||\n        (value.startsWith(\"'\") && value.endsWith(\"'\"))\n      ) {\n        value = value.slice(1, -1)\n      }\n\n      if (key) result[key] = value\n    }\n\n    return JSON.stringify(result, null, 2)\n  },\n})\n\n/**\n * Detect the most likely field delimiter in a CSV-like text sample.\n *\n * @remarks\n * Tries comma, tab, semicolon, pipe, and colon. Scores each by mean field count divided by\n * variance (so consistent row widths beat noisy splits). Looks at up to the first 20 lines of\n * the first 5000 characters.\n */\nexport const detectDelimiterTool = new Tool({\n  name: 'detect_delimiter',\n  description: 'Detect the most likely field delimiter in a CSV-like text sample.',\n  inputSchema: validator.object({\n    text: validator.string().required().description('Sample of the delimited text to analyze'),\n  }),\n  handler: async (args) => {\n    const { text } = args as { text: string }\n    const sample = text.slice(0, 5000)\n    const lines = sample\n      .split('\\n')\n      .map((l) => l.trim())\n      .filter((l) => l.length > 0)\n      .slice(0, 20)\n\n    if (lines.length === 0) return 'Error: No lines to analyze.'\n\n    const candidates: Array<{ delim: string; name: string }> = [\n      { delim: ',', name: 'comma' },\n      { delim: '\\t', name: 'tab' },\n      { delim: ';', name: 'semicolon' },\n      { delim: '|', name: 'pipe' },\n      { delim: ':', name: 'colon' },\n    ]\n\n    let best = { name: 'comma', delim: ',', score: -1, avgFields: 0 }\n\n    for (const { delim, name } of candidates) {\n      const counts = lines.map((l) => l.split(delim).length - 1)\n      const avg = counts.reduce((a, b) => a + b, 0) / counts.length\n      if (avg === 0) continue\n      const fieldVariance = counts.reduce((a, b) => a + (b - avg) ** 2, 0) / counts.length\n      const score = avg / (1 + fieldVariance)\n      if (score > best.score) {\n        best = { name, delim, score, avgFields: Number.parseFloat((avg + 1).toFixed(1)) }\n      }\n    }\n\n    return `Detected delimiter: ${best.name} (\"${best.delim === '\\t' ? '\\\\t' : best.delim}\") — ~${best.avgFields} fields per row`\n  },\n})\n"],"mappings":"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"}
+{"version":3,"file":"parsing.mjs","names":[],"sources":["../../../src/batteries/tools/parsing/index.ts"],"sourcesContent":["/**\n * Pre-constructed tools for parsing CSV, TSV, JSON, YAML, and other structured text formats.\n *\n * @module @nhtio/adk/batteries/tools/parsing\n *\n * @remarks\n * Pre-constructed bundled tools for the `parsing` category. Import individually, the whole\n * category, or import every tool via `@nhtio/adk/batteries`.\n */\n\nimport { load as parseYaml } from 'js-yaml'\nimport { default as Papa } from 'papaparse'\nimport { isError } from '@nhtio/adk/guards'\nimport { validator } from '@nhtio/validation'\nimport { Tool, SpooledJsonArtifact } from '@nhtio/adk/common'\n\n/**\n * Parse a CSV or TSV string into a JSON array.\n *\n * @remarks\n * With `has_header: true` (default), each row becomes an object keyed by column name. Without a\n * header, rows are returned as positional arrays. `delimiter` auto-detects when omitted; pass\n * `\"\\t\"` for TSV. Rows are clipped to `limit` (default 1000, max 10000). Parse warnings are\n * prepended to the output.\n */\nexport const parseCsvTool = new Tool({\n  name: 'parse_csv',\n  description:\n    'Parse a CSV or TSV string into a JSON array. With a header row, returns objects keyed by column name. Without, returns arrays of values.',\n  inputSchema: validator.object({\n    text: validator.string().required().description('CSV or TSV text to parse'),\n    has_header: validator\n      .boolean()\n      .default(true)\n      .description('First row is a header row (default: true)'),\n    delimiter: validator\n      .string()\n      .default('')\n      .allow('')\n      .description('Field delimiter — auto-detected if omitted. Use \"\\\\t\" for TSV.'),\n    limit: validator.number().default(1000).description('Maximum rows to return (default: 1000)'),\n  }),\n  artifactConstructor: () => SpooledJsonArtifact,\n  handler: async (args) => {\n    const {\n      text,\n      has_header: hasHeader,\n      delimiter,\n      limit: rawLimit,\n    } = args as {\n      text: string\n      has_header: boolean\n      delimiter: string\n      limit: number\n    }\n    const limit = Math.min(10_000, Math.max(1, Math.floor(rawLimit)))\n\n    try {\n      const result = Papa.parse<unknown>(text.trim(), {\n        header: hasHeader,\n        delimiter: delimiter || undefined,\n        skipEmptyLines: true,\n        dynamicTyping: true,\n      })\n\n      const rows = (result.data as unknown[]).slice(0, limit)\n      const warnings =\n        result.errors.length > 0\n          ? `Parse warnings: ${result.errors\n              .slice(0, 3)\n              .map((e) => e.message)\n              .join('; ')}\\n\\n`\n          : ''\n      const truncated =\n        result.data.length > limit ? `\\n\\n(Showing ${limit} of ${result.data.length} rows)` : ''\n\n      return warnings + JSON.stringify(rows, null, 2) + truncated\n    } catch (err) {\n      return `Error: ${isError(err) ? err.message : String(err)}`\n    }\n  },\n})\n\n/**\n * Parse a YAML string into JSON.\n *\n * @remarks\n * Returns a pretty-printed JSON representation of the parsed YAML document. Invalid YAML\n * returns an error string.\n */\nexport const parseYamlTool = new Tool({\n  name: 'parse_yaml',\n  description: 'Parse a YAML string and return the equivalent JSON.',\n  inputSchema: validator.object({\n    text: validator.string().required().description('YAML text to parse'),\n  }),\n  artifactConstructor: () => SpooledJsonArtifact,\n  handler: async (args) => {\n    const { text } = args as { text: string }\n    try {\n      const parsed = parseYaml(text)\n      // An empty / whitespace-only / BOM-only document parses to `undefined`, and\n      // `JSON.stringify(undefined)` returns the JS value `undefined` (not a string), breaking the\n      // tool's string-return contract. Normalise that empty document to JSON `null`.\n      if (parsed === undefined) return 'null'\n      // YAML permits .NaN / .inf / -.inf, which `JSON.stringify` would silently turn into `null`,\n      // losing the value. Render non-finite numbers as their YAML token strings so the information\n      // survives the JSON round-trip instead of being corrupted to null.\n      return JSON.stringify(\n        parsed,\n        (_key, value) => {\n          if (typeof value === 'number' && !Number.isFinite(value)) {\n            return Number.isNaN(value) ? '.NaN' : value > 0 ? '.inf' : '-.inf'\n          }\n          return value\n        },\n        2\n      )\n    } catch (err) {\n      return `Error: Invalid YAML — ${isError(err) ? err.message : String(err)}`\n    }\n  },\n})\n\n/**\n * Extract key-value pairs from text.\n *\n * @remarks\n * Handles `.env` files, config files, and query strings. `kv_delimiter` chooses the\n * key→value separator (`=`, `:`, or `auto`); `pair_delimiter` selects how pairs are separated\n * (`newline`, `comma`, `semicolon`, `ampersand`). Surrounding single or double quotes around\n * values are stripped. Comment lines starting with `#` are skipped by default.\n */\nexport const parseKvTool = new Tool({\n  name: 'parse_kv',\n  description:\n    'Extract key-value pairs from text (e.g. .env files, config files, query strings). Returns a JSON object.',\n  inputSchema: validator.object({\n    text: validator.string().required().description('Text containing key-value pairs'),\n    kv_delimiter: validator\n      .string()\n      .valid('=', ':', 'auto')\n      .default('auto')\n      .description('Separator between key and value (default: auto-detect)'),\n    pair_delimiter: validator\n      .string()\n      .valid('newline', 'comma', 'semicolon', 'ampersand')\n      .default('newline')\n      .description('Separator between pairs (default: newline)'),\n    skip_comments: validator\n      .boolean()\n      .default(true)\n      .description('Skip lines starting with # (default: true)'),\n  }),\n  artifactConstructor: () => SpooledJsonArtifact,\n  handler: async (args) => {\n    const {\n      text,\n      kv_delimiter: kvDelim,\n      pair_delimiter: pairDelimKey,\n      skip_comments: skipComments,\n    } = args as {\n      text: string\n      kv_delimiter: string\n      pair_delimiter: string\n      skip_comments: boolean\n    }\n\n    const pairDelimMap: Record<string, string> = {\n      newline: '\\n',\n      comma: ',',\n      semicolon: ';',\n      ampersand: '&',\n    }\n    const pairDelim = pairDelimMap[pairDelimKey] ?? '\\n'\n\n    const result: Record<string, string> = {}\n\n    for (const raw of text.split(pairDelim)) {\n      const line = raw.trim()\n      if (line === '') continue\n      if (skipComments && line.startsWith('#')) continue\n\n      const delim =\n        kvDelim === 'auto' ? (line.includes('=') ? '=' : line.includes(':') ? ':' : null) : kvDelim\n      if (!delim) continue\n\n      const sepIdx = line.indexOf(delim)\n      if (sepIdx === -1) continue\n\n      const key = line.slice(0, sepIdx).trim()\n      let value = line.slice(sepIdx + delim.length).trim()\n\n      if (\n        (value.startsWith('\"') && value.endsWith('\"')) ||\n        (value.startsWith(\"'\") && value.endsWith(\"'\"))\n      ) {\n        value = value.slice(1, -1)\n      }\n\n      if (key) result[key] = value\n    }\n\n    return JSON.stringify(result, null, 2)\n  },\n})\n\n/**\n * Detect the most likely field delimiter in a CSV-like text sample.\n *\n * @remarks\n * Tries comma, tab, semicolon, pipe, and colon. Scores each by mean field count divided by\n * variance (so consistent row widths beat noisy splits). Looks at up to the first 20 lines of\n * the first 5000 characters.\n */\nexport const detectDelimiterTool = new Tool({\n  name: 'detect_delimiter',\n  description: 'Detect the most likely field delimiter in a CSV-like text sample.',\n  inputSchema: validator.object({\n    text: validator.string().required().description('Sample of the delimited text to analyze'),\n  }),\n  handler: async (args) => {\n    const { text } = args as { text: string }\n    const sample = text.slice(0, 5000)\n    const lines = sample\n      .split('\\n')\n      .map((l) => l.trim())\n      .filter((l) => l.length > 0)\n      .slice(0, 20)\n\n    if (lines.length === 0) return 'Error: No lines to analyze.'\n\n    const candidates: Array<{ delim: string; name: string }> = [\n      { delim: ',', name: 'comma' },\n      { delim: '\\t', name: 'tab' },\n      { delim: ';', name: 'semicolon' },\n      { delim: '|', name: 'pipe' },\n      { delim: ':', name: 'colon' },\n    ]\n\n    let best = { name: 'comma', delim: ',', score: -1, avgFields: 0 }\n\n    for (const { delim, name } of candidates) {\n      const counts = lines.map((l) => l.split(delim).length - 1)\n      const avg = counts.reduce((a, b) => a + b, 0) / counts.length\n      if (avg === 0) continue\n      const fieldVariance = counts.reduce((a, b) => a + (b - avg) ** 2, 0) / counts.length\n      const score = avg / (1 + fieldVariance)\n      if (score > best.score) {\n        best = { name, delim, score, avgFields: Number.parseFloat((avg + 1).toFixed(1)) }\n      }\n    }\n\n    return `Detected delimiter: ${best.name} (\"${best.delim === '\\t' ? '\\\\t' : best.delim}\") — ~${best.avgFields} fields per row`\n  },\n})\n"],"mappings":"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"}

package/batteries/tools/retrievables.cjs

@@ -1,9 +1,9 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 require("../../chunk-Ble4zEEl.js");
-const require_tool_registry = require("../../tool_registry-DYUYqXvo.js");
-const require_tool = require("../../tool-CVyZkFC7.js");
-const require_common = require("../../common-Cj8TaQ9U.js");
-const require_spooled_markdown_artifact = require("../../spooled_markdown_artifact-CALSDxIx.js");
+const require_tool_registry = require("../../tool_registry-CKJPze3j.js");
+const require_tool = require("../../tool-D5WGVIcI.js");
+const require_common = require("../../common-DZl3ADJs.js");
+const require_spooled_markdown_artifact = require("../../spooled_markdown_artifact-ClX72lek.js");
 require("../../guards.cjs");
 let _nhtio_validation = require("@nhtio/validation");
 let luxon = require("luxon");

package/batteries/tools/retrievables.mjs

@@ -1,7 +1,7 @@
-import { o as isError } from "../../tool_registry-D1pSSlsd.mjs";
-import { t as Tool } from "../../tool-CMhaDRNd.mjs";
-import { o as Retrievable } from "../../common-BT0nfCi9.mjs";
-import { n as SpooledJsonArtifact } from "../../spooled_markdown_artifact-Ci5UL7l4.mjs";
+import { o as isError } from "../../tool_registry-791Vrjtf.mjs";
+import { t as Tool } from "../../tool-wMYMVl60.mjs";
+import { o as Retrievable } from "../../common-DYDUi99O.mjs";
+import { n as SpooledJsonArtifact } from "../../spooled_markdown_artifact-wkrBF3oX.mjs";
 import "../../guards.mjs";
 import { validator } from "@nhtio/validation";
 import { DateTime } from "luxon";

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

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

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

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

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

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

package/batteries/tools/scrapper.cjs

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

package/batteries/tools/scrapper.mjs

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

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

@@ -0,0 +1,21 @@
+/**
+ * Battery-scoped exception constructors for the SearXNG search tool.
+ *
+ * @remarks
+ * Battery-scoped exception classes owned by the SearXNG tool battery (not the ADK core). Minted
+ * via `createException` from `@nhtio/adk/factories` and re-exported from the battery's barrel
+ * (`@nhtio/adk/batteries/tools/searxng`). This file intentionally carries **no** `@module` tag:
+ * it is an internal sibling relative-imported by `index.ts`, so it does not mint its own
+ * `…/searxng/exceptions` entrypoint (whose `exceptions` leaf basename would collide with sibling
+ * batteries under the `vite-plugin-dts` rolled-up `.d.ts` rule).
+ */
+/**
+ * Thrown when {@link createSearxngSearchTool} receives invalid configuration.
+ *
+ * @remarks
+ * Fatal: config bugs (missing or unparseable `instanceUrl`) fail loud at factory-call time
+ * rather than at the first search.
+ */
+export declare const E_INVALID_SEARXNG_CONFIG: import("../../../factories").CreatedException<[
+    string
+]>;