@hoilab/ada-cli 0.84.22 → 0.85.0

package/dist/core/web/scrapers/rubygems.js

@@ -0,0 +1,23 @@
+export const scrapear = async (url, fetchImpl, signal) => {
+    if (url.hostname !== "rubygems.org")
+        return null;
+    const match = url.pathname.match(/^\/gems\/([^/]+)/);
+    if (!match)
+        return null;
+    const gema = decodeURIComponent(match[1]);
+    const respuesta = await fetchImpl(`https://rubygems.org/api/v1/gems/${encodeURIComponent(gema)}.json`, { signal });
+    if (respuesta.status === 404)
+        return null;
+    if (!respuesta.ok)
+        throw new Error(`RubyGems respondió HTTP ${respuesta.status}.`);
+    const doc = (await respuesta.json());
+    if (!doc.name)
+        return null;
+    return {
+        titulo: `${doc.name}@${doc.version ?? "?"}`,
+        url: `https://rubygems.org/gems/${doc.name}`,
+        resumen: doc.info ?? "",
+        datos: { nombre: doc.name, version: doc.version, licencias: doc.licenses ?? [], homepage: doc.homepage_uri },
+    };
+};
+//# sourceMappingURL=rubygems.js.map

package/dist/core/web/scrapers/rubygems.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rubygems.js","sourceRoot":"","sources":["../../../../src/core/web/scrapers/rubygems.ts"],"names":[],"mappings":"AAaA,MAAM,CAAC,MAAM,QAAQ,GAAmB,KAAK,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,CAAC;IACzE,IAAI,GAAG,CAAC,QAAQ,KAAK,cAAc;QAAE,OAAO,IAAI,CAAC;IACjD,MAAM,KAAK,GAAG,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC;IACrD,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,MAAM,IAAI,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAE1C,MAAM,SAAS,GAAG,MAAM,SAAS,CAAC,oCAAoC,kBAAkB,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;IACnH,IAAI,SAAS,CAAC,MAAM,KAAK,GAAG;QAAE,OAAO,IAAI,CAAC;IAC1C,IAAI,CAAC,SAAS,CAAC,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,4BAA2B,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC;IACnF,MAAM,GAAG,GAAG,CAAC,MAAM,SAAS,CAAC,IAAI,EAAE,CAAgB,CAAC;IACpD,IAAI,CAAC,GAAG,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IAE3B,OAAO;QACN,MAAM,EAAE,GAAG,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,OAAO,IAAI,GAAG,EAAE;QAC3C,GAAG,EAAE,6BAA6B,GAAG,CAAC,IAAI,EAAE;QAC5C,OAAO,EAAE,GAAG,CAAC,IAAI,IAAI,EAAE;QACvB,KAAK,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,CAAC,QAAQ,IAAI,EAAE,EAAE,QAAQ,EAAE,GAAG,CAAC,YAAY,EAAE;KAC5G,CAAC;AAAA,CACF,CAAC","sourcesContent":["/**\n * RubyGems, vía su API pública (`rubygems.org/api/v1/gems/<gema>.json`).\n */\nimport type { FuncionScraper } from \"./tipos.ts\";\n\ninterface DocRubyGems {\n\tname?: string;\n\tversion?: string;\n\tlicenses?: string[] | null;\n\tinfo?: string;\n\thomepage_uri?: string;\n}\n\nexport const scrapear: FuncionScraper = async (url, fetchImpl, signal) => {\n\tif (url.hostname !== \"rubygems.org\") return null;\n\tconst match = url.pathname.match(/^\\/gems\\/([^/]+)/);\n\tif (!match) return null;\n\tconst gema = decodeURIComponent(match[1]);\n\n\tconst respuesta = await fetchImpl(`https://rubygems.org/api/v1/gems/${encodeURIComponent(gema)}.json`, { signal });\n\tif (respuesta.status === 404) return null;\n\tif (!respuesta.ok) throw new Error(`RubyGems respondió HTTP ${respuesta.status}.`);\n\tconst doc = (await respuesta.json()) as DocRubyGems;\n\tif (!doc.name) return null;\n\n\treturn {\n\t\ttitulo: `${doc.name}@${doc.version ?? \"?\"}`,\n\t\turl: `https://rubygems.org/gems/${doc.name}`,\n\t\tresumen: doc.info ?? \"\",\n\t\tdatos: { nombre: doc.name, version: doc.version, licencias: doc.licenses ?? [], homepage: doc.homepage_uri },\n\t};\n};\n"]}

package/dist/core/web/scrapers/stackoverflow.d.ts

@@ -0,0 +1,3 @@
+import type { FuncionScraper } from "./tipos.ts";
+export declare const scrapear: FuncionScraper;
+//# sourceMappingURL=stackoverflow.d.ts.map

package/dist/core/web/scrapers/stackoverflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stackoverflow.d.ts","sourceRoot":"","sources":["../../../../src/core/web/scrapers/stackoverflow.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAmBjD,eAAO,MAAM,QAAQ,EAAE,cAwCtB,CAAC","sourcesContent":["/**\n * Stack Overflow, vía la API pública de Stack Exchange (sin clave, con\n * cuota compartida). Trae la pregunta y, si la hay, la respuesta aceptada —\n * es lo que un agente de código va a buscar en la URL, no el layout de la\n * página.\n */\nimport { htmlToText } from \"../texto.ts\";\nimport type { FuncionScraper } from \"./tipos.ts\";\n\ninterface Pregunta {\n\ttitle?: string;\n\tbody?: string;\n\tscore?: number;\n\ttags?: string[];\n\tanswer_count?: number;\n\tis_answered?: boolean;\n\taccepted_answer_id?: number;\n}\n\ninterface Respuesta {\n\tbody?: string;\n\tscore?: number;\n}\n\nconst RESUMEN_MAX = 600;\n\nexport const scrapear: FuncionScraper = async (url, fetchImpl, signal) => {\n\tif (url.hostname !== \"stackoverflow.com\" && url.hostname !== \"www.stackoverflow.com\") return null;\n\tconst match = url.pathname.match(/\\/questions\\/(\\d+)/);\n\tif (!match) return null;\n\tconst id = match[1];\n\n\tconst respuesta = await fetchImpl(\n\t\t`https://api.stackexchange.com/2.3/questions/${id}?order=desc&sort=votes&site=stackoverflow&filter=withbody`,\n\t\t{ signal },\n\t);\n\tif (!respuesta.ok) throw new Error(`Stack Overflow respondió HTTP ${respuesta.status}.`);\n\tconst doc = (await respuesta.json()) as { items?: Pregunta[] };\n\tconst pregunta = doc.items?.[0];\n\tif (!pregunta?.title) return null;\n\n\tlet respuestaAceptada: string | undefined;\n\tif (pregunta.accepted_answer_id) {\n\t\tconst respAns = await fetchImpl(\n\t\t\t`https://api.stackexchange.com/2.3/answers/${pregunta.accepted_answer_id}?order=desc&sort=votes&site=stackoverflow&filter=withbody`,\n\t\t\t{ signal },\n\t\t);\n\t\tif (respAns.ok) {\n\t\t\tconst docAns = (await respAns.json()) as { items?: Respuesta[] };\n\t\t\tconst cuerpo = docAns.items?.[0]?.body;\n\t\t\tif (cuerpo) respuestaAceptada = htmlToText(cuerpo);\n\t\t}\n\t}\n\n\treturn {\n\t\ttitulo: pregunta.title,\n\t\turl: `https://stackoverflow.com/questions/${id}`,\n\t\tresumen: htmlToText(pregunta.body ?? \"\").slice(0, RESUMEN_MAX),\n\t\tdatos: {\n\t\t\tpuntuacion: pregunta.score,\n\t\t\trespuestas: pregunta.answer_count,\n\t\t\tresuelta: pregunta.is_answered ?? false,\n\t\t\tetiquetas: pregunta.tags ?? [],\n\t\t\trespuestaAceptada,\n\t\t},\n\t};\n};\n"]}

package/dist/core/web/scrapers/stackoverflow.js

@@ -0,0 +1,46 @@
+/**
+ * Stack Overflow, vía la API pública de Stack Exchange (sin clave, con
+ * cuota compartida). Trae la pregunta y, si la hay, la respuesta aceptada —
+ * es lo que un agente de código va a buscar en la URL, no el layout de la
+ * página.
+ */
+import { htmlToText } from "../texto.js";
+const RESUMEN_MAX = 600;
+export const scrapear = async (url, fetchImpl, signal) => {
+    if (url.hostname !== "stackoverflow.com" && url.hostname !== "www.stackoverflow.com")
+        return null;
+    const match = url.pathname.match(/\/questions\/(\d+)/);
+    if (!match)
+        return null;
+    const id = match[1];
+    const respuesta = await fetchImpl(`https://api.stackexchange.com/2.3/questions/${id}?order=desc&sort=votes&site=stackoverflow&filter=withbody`, { signal });
+    if (!respuesta.ok)
+        throw new Error(`Stack Overflow respondió HTTP ${respuesta.status}.`);
+    const doc = (await respuesta.json());
+    const pregunta = doc.items?.[0];
+    if (!pregunta?.title)
+        return null;
+    let respuestaAceptada;
+    if (pregunta.accepted_answer_id) {
+        const respAns = await fetchImpl(`https://api.stackexchange.com/2.3/answers/${pregunta.accepted_answer_id}?order=desc&sort=votes&site=stackoverflow&filter=withbody`, { signal });
+        if (respAns.ok) {
+            const docAns = (await respAns.json());
+            const cuerpo = docAns.items?.[0]?.body;
+            if (cuerpo)
+                respuestaAceptada = htmlToText(cuerpo);
+        }
+    }
+    return {
+        titulo: pregunta.title,
+        url: `https://stackoverflow.com/questions/${id}`,
+        resumen: htmlToText(pregunta.body ?? "").slice(0, RESUMEN_MAX),
+        datos: {
+            puntuacion: pregunta.score,
+            respuestas: pregunta.answer_count,
+            resuelta: pregunta.is_answered ?? false,
+            etiquetas: pregunta.tags ?? [],
+            respuestaAceptada,
+        },
+    };
+};
+//# sourceMappingURL=stackoverflow.js.map

package/dist/core/web/scrapers/stackoverflow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stackoverflow.js","sourceRoot":"","sources":["../../../../src/core/web/scrapers/stackoverflow.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAkBzC,MAAM,WAAW,GAAG,GAAG,CAAC;AAExB,MAAM,CAAC,MAAM,QAAQ,GAAmB,KAAK,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,CAAC;IACzE,IAAI,GAAG,CAAC,QAAQ,KAAK,mBAAmB,IAAI,GAAG,CAAC,QAAQ,KAAK,uBAAuB;QAAE,OAAO,IAAI,CAAC;IAClG,MAAM,KAAK,GAAG,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC;IACvD,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IAEpB,MAAM,SAAS,GAAG,MAAM,SAAS,CAChC,+CAA+C,EAAE,2DAA2D,EAC5G,EAAE,MAAM,EAAE,CACV,CAAC;IACF,IAAI,CAAC,SAAS,CAAC,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,kCAAiC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC;IACzF,MAAM,GAAG,GAAG,CAAC,MAAM,SAAS,CAAC,IAAI,EAAE,CAA2B,CAAC;IAC/D,MAAM,QAAQ,GAAG,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;IAChC,IAAI,CAAC,QAAQ,EAAE,KAAK;QAAE,OAAO,IAAI,CAAC;IAElC,IAAI,iBAAqC,CAAC;IAC1C,IAAI,QAAQ,CAAC,kBAAkB,EAAE,CAAC;QACjC,MAAM,OAAO,GAAG,MAAM,SAAS,CAC9B,6CAA6C,QAAQ,CAAC,kBAAkB,2DAA2D,EACnI,EAAE,MAAM,EAAE,CACV,CAAC;QACF,IAAI,OAAO,CAAC,EAAE,EAAE,CAAC;YAChB,MAAM,MAAM,GAAG,CAAC,MAAM,OAAO,CAAC,IAAI,EAAE,CAA4B,CAAC;YACjE,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC;YACvC,IAAI,MAAM;gBAAE,iBAAiB,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;QACpD,CAAC;IACF,CAAC;IAED,OAAO;QACN,MAAM,EAAE,QAAQ,CAAC,KAAK;QACtB,GAAG,EAAE,uCAAuC,EAAE,EAAE;QAChD,OAAO,EAAE,UAAU,CAAC,QAAQ,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,WAAW,CAAC;QAC9D,KAAK,EAAE;YACN,UAAU,EAAE,QAAQ,CAAC,KAAK;YAC1B,UAAU,EAAE,QAAQ,CAAC,YAAY;YACjC,QAAQ,EAAE,QAAQ,CAAC,WAAW,IAAI,KAAK;YACvC,SAAS,EAAE,QAAQ,CAAC,IAAI,IAAI,EAAE;YAC9B,iBAAiB;SACjB;KACD,CAAC;AAAA,CACF,CAAC","sourcesContent":["/**\n * Stack Overflow, vía la API pública de Stack Exchange (sin clave, con\n * cuota compartida). Trae la pregunta y, si la hay, la respuesta aceptada —\n * es lo que un agente de código va a buscar en la URL, no el layout de la\n * página.\n */\nimport { htmlToText } from \"../texto.ts\";\nimport type { FuncionScraper } from \"./tipos.ts\";\n\ninterface Pregunta {\n\ttitle?: string;\n\tbody?: string;\n\tscore?: number;\n\ttags?: string[];\n\tanswer_count?: number;\n\tis_answered?: boolean;\n\taccepted_answer_id?: number;\n}\n\ninterface Respuesta {\n\tbody?: string;\n\tscore?: number;\n}\n\nconst RESUMEN_MAX = 600;\n\nexport const scrapear: FuncionScraper = async (url, fetchImpl, signal) => {\n\tif (url.hostname !== \"stackoverflow.com\" && url.hostname !== \"www.stackoverflow.com\") return null;\n\tconst match = url.pathname.match(/\\/questions\\/(\\d+)/);\n\tif (!match) return null;\n\tconst id = match[1];\n\n\tconst respuesta = await fetchImpl(\n\t\t`https://api.stackexchange.com/2.3/questions/${id}?order=desc&sort=votes&site=stackoverflow&filter=withbody`,\n\t\t{ signal },\n\t);\n\tif (!respuesta.ok) throw new Error(`Stack Overflow respondió HTTP ${respuesta.status}.`);\n\tconst doc = (await respuesta.json()) as { items?: Pregunta[] };\n\tconst pregunta = doc.items?.[0];\n\tif (!pregunta?.title) return null;\n\n\tlet respuestaAceptada: string | undefined;\n\tif (pregunta.accepted_answer_id) {\n\t\tconst respAns = await fetchImpl(\n\t\t\t`https://api.stackexchange.com/2.3/answers/${pregunta.accepted_answer_id}?order=desc&sort=votes&site=stackoverflow&filter=withbody`,\n\t\t\t{ signal },\n\t\t);\n\t\tif (respAns.ok) {\n\t\t\tconst docAns = (await respAns.json()) as { items?: Respuesta[] };\n\t\t\tconst cuerpo = docAns.items?.[0]?.body;\n\t\t\tif (cuerpo) respuestaAceptada = htmlToText(cuerpo);\n\t\t}\n\t}\n\n\treturn {\n\t\ttitulo: pregunta.title,\n\t\turl: `https://stackoverflow.com/questions/${id}`,\n\t\tresumen: htmlToText(pregunta.body ?? \"\").slice(0, RESUMEN_MAX),\n\t\tdatos: {\n\t\t\tpuntuacion: pregunta.score,\n\t\t\trespuestas: pregunta.answer_count,\n\t\t\tresuelta: pregunta.is_answered ?? false,\n\t\t\tetiquetas: pregunta.tags ?? [],\n\t\t\trespuestaAceptada,\n\t\t},\n\t};\n};\n"]}

package/dist/core/web/scrapers/tipos.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Tipos compartidos por los scrapers de `web_fetch`.
+ *
+ * Un scraper devuelve datos ESTRUCTURADOS de una API pública en vez del HTML
+ * crudo de la página — un agente de código quiere la versión y la licencia de
+ * un paquete, no el DOM de `npmjs.com` con su menú y su footer. `null` cuando
+ * la URL entra en el sitio pero no en una forma reconocida (p.ej. la portada
+ * de npmjs.com, sin ruta de paquete): `web_fetch` cae entonces al fetch
+ * genérico, nunca se inventa un resultado vacío.
+ */
+export interface ResultadoScraper {
+    titulo: string;
+    url: string;
+    resumen: string;
+    datos: unknown;
+}
+/**
+ * Debe LANZAR ante un fallo real (red, HTTP, JSON roto) para que `web_fetch`
+ * lo distinga de «esta URL no es mía» (`null`, sin lanzar).
+ */
+export type FuncionScraper = (url: URL, fetchImpl: typeof fetch, signal?: AbortSignal) => Promise<ResultadoScraper | null>;
+export interface ModuloScraper {
+    scrapear: FuncionScraper;
+}
+export interface DescriptorScraper {
+    nombre: string;
+    /** Barato y síncrono: decide si esta URL es de su sitio, sin tocar la red. */
+    encaja: (url: URL) => boolean;
+    /** Import perezoso: no se ejecuta hasta que la URL encaja de verdad. */
+    cargar: () => Promise<ModuloScraper>;
+}
+/**
+ * `hostname === dominio` o subdominio real de `dominio` (con el punto).
+ *
+ * Un `endsWith(dominio)` a secas confunde cualquier host que termine con
+ * los mismos caracteres sin ser un subdominio real —`notcisa.gov` con
+ * `cisa.gov`, `xnvd.nist.gov` con `nvd.nist.gov`— con el sitio de verdad.
+ * Comparar con el punto delante evita ese falso positivo sin perder los
+ * subdominios legítimos (`www.cisa.gov` sí encaja).
+ */
+export declare function esHostOSubdominio(hostname: string, dominio: string): boolean;
+//# sourceMappingURL=tipos.d.ts.map

package/dist/core/web/scrapers/tipos.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tipos.d.ts","sourceRoot":"","sources":["../../../../src/core/web/scrapers/tipos.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,WAAW,gBAAgB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;CACf;AAED;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,CAC5B,GAAG,EAAE,GAAG,EACR,SAAS,EAAE,OAAO,KAAK,EACvB,MAAM,CAAC,EAAE,WAAW,KAChB,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;AAEtC,MAAM,WAAW,aAAa;IAC7B,QAAQ,EAAE,cAAc,CAAC;CACzB;AAED,MAAM,WAAW,iBAAiB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,+EAA8E;IAC9E,MAAM,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC;IAC9B,wEAAwE;IACxE,MAAM,EAAE,MAAM,OAAO,CAAC,aAAa,CAAC,CAAC;CACrC;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAE5E","sourcesContent":["/**\n * Tipos compartidos por los scrapers de `web_fetch`.\n *\n * Un scraper devuelve datos ESTRUCTURADOS de una API pública en vez del HTML\n * crudo de la página — un agente de código quiere la versión y la licencia de\n * un paquete, no el DOM de `npmjs.com` con su menú y su footer. `null` cuando\n * la URL entra en el sitio pero no en una forma reconocida (p.ej. la portada\n * de npmjs.com, sin ruta de paquete): `web_fetch` cae entonces al fetch\n * genérico, nunca se inventa un resultado vacío.\n */\n\nexport interface ResultadoScraper {\n\ttitulo: string;\n\turl: string;\n\tresumen: string;\n\tdatos: unknown;\n}\n\n/**\n * Debe LANZAR ante un fallo real (red, HTTP, JSON roto) para que `web_fetch`\n * lo distinga de «esta URL no es mía» (`null`, sin lanzar).\n */\nexport type FuncionScraper = (\n\turl: URL,\n\tfetchImpl: typeof fetch,\n\tsignal?: AbortSignal,\n) => Promise<ResultadoScraper | null>;\n\nexport interface ModuloScraper {\n\tscrapear: FuncionScraper;\n}\n\nexport interface DescriptorScraper {\n\tnombre: string;\n\t/** Barato y síncrono: decide si esta URL es de su sitio, sin tocar la red. */\n\tencaja: (url: URL) => boolean;\n\t/** Import perezoso: no se ejecuta hasta que la URL encaja de verdad. */\n\tcargar: () => Promise<ModuloScraper>;\n}\n\n/**\n * `hostname === dominio` o subdominio real de `dominio` (con el punto).\n *\n * Un `endsWith(dominio)` a secas confunde cualquier host que termine con\n * los mismos caracteres sin ser un subdominio real —`notcisa.gov` con\n * `cisa.gov`, `xnvd.nist.gov` con `nvd.nist.gov`— con el sitio de verdad.\n * Comparar con el punto delante evita ese falso positivo sin perder los\n * subdominios legítimos (`www.cisa.gov` sí encaja).\n */\nexport function esHostOSubdominio(hostname: string, dominio: string): boolean {\n\treturn hostname === dominio || hostname.endsWith(`.${dominio}`);\n}\n"]}

package/dist/core/web/scrapers/tipos.js

@@ -0,0 +1,23 @@
+/**
+ * Tipos compartidos por los scrapers de `web_fetch`.
+ *
+ * Un scraper devuelve datos ESTRUCTURADOS de una API pública en vez del HTML
+ * crudo de la página — un agente de código quiere la versión y la licencia de
+ * un paquete, no el DOM de `npmjs.com` con su menú y su footer. `null` cuando
+ * la URL entra en el sitio pero no en una forma reconocida (p.ej. la portada
+ * de npmjs.com, sin ruta de paquete): `web_fetch` cae entonces al fetch
+ * genérico, nunca se inventa un resultado vacío.
+ */
+/**
+ * `hostname === dominio` o subdominio real de `dominio` (con el punto).
+ *
+ * Un `endsWith(dominio)` a secas confunde cualquier host que termine con
+ * los mismos caracteres sin ser un subdominio real —`notcisa.gov` con
+ * `cisa.gov`, `xnvd.nist.gov` con `nvd.nist.gov`— con el sitio de verdad.
+ * Comparar con el punto delante evita ese falso positivo sin perder los
+ * subdominios legítimos (`www.cisa.gov` sí encaja).
+ */
+export function esHostOSubdominio(hostname, dominio) {
+    return hostname === dominio || hostname.endsWith(`.${dominio}`);
+}
+//# sourceMappingURL=tipos.js.map

package/dist/core/web/scrapers/tipos.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tipos.js","sourceRoot":"","sources":["../../../../src/core/web/scrapers/tipos.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AA+BH;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAgB,EAAE,OAAe,EAAW;IAC7E,OAAO,QAAQ,KAAK,OAAO,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,OAAO,EAAE,CAAC,CAAC;AAAA,CAChE","sourcesContent":["/**\n * Tipos compartidos por los scrapers de `web_fetch`.\n *\n * Un scraper devuelve datos ESTRUCTURADOS de una API pública en vez del HTML\n * crudo de la página — un agente de código quiere la versión y la licencia de\n * un paquete, no el DOM de `npmjs.com` con su menú y su footer. `null` cuando\n * la URL entra en el sitio pero no en una forma reconocida (p.ej. la portada\n * de npmjs.com, sin ruta de paquete): `web_fetch` cae entonces al fetch\n * genérico, nunca se inventa un resultado vacío.\n */\n\nexport interface ResultadoScraper {\n\ttitulo: string;\n\turl: string;\n\tresumen: string;\n\tdatos: unknown;\n}\n\n/**\n * Debe LANZAR ante un fallo real (red, HTTP, JSON roto) para que `web_fetch`\n * lo distinga de «esta URL no es mía» (`null`, sin lanzar).\n */\nexport type FuncionScraper = (\n\turl: URL,\n\tfetchImpl: typeof fetch,\n\tsignal?: AbortSignal,\n) => Promise<ResultadoScraper | null>;\n\nexport interface ModuloScraper {\n\tscrapear: FuncionScraper;\n}\n\nexport interface DescriptorScraper {\n\tnombre: string;\n\t/** Barato y síncrono: decide si esta URL es de su sitio, sin tocar la red. */\n\tencaja: (url: URL) => boolean;\n\t/** Import perezoso: no se ejecuta hasta que la URL encaja de verdad. */\n\tcargar: () => Promise<ModuloScraper>;\n}\n\n/**\n * `hostname === dominio` o subdominio real de `dominio` (con el punto).\n *\n * Un `endsWith(dominio)` a secas confunde cualquier host que termine con\n * los mismos caracteres sin ser un subdominio real —`notcisa.gov` con\n * `cisa.gov`, `xnvd.nist.gov` con `nvd.nist.gov`— con el sitio de verdad.\n * Comparar con el punto delante evita ese falso positivo sin perder los\n * subdominios legítimos (`www.cisa.gov` sí encaja).\n */\nexport function esHostOSubdominio(hostname: string, dominio: string): boolean {\n\treturn hostname === dominio || hostname.endsWith(`.${dominio}`);\n}\n"]}

package/dist/core/web/texto.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Limpieza de HTML a texto plano, compartida por `web_fetch` y los scrapers.
+ *
+ * Vive separada de `tools.ts` para que los scrapers puedan usarla sin crear
+ * un ciclo de imports estáticos con el fichero que orquesta su propio
+ * registro perezoso.
+ */
+/** Extrae texto legible de HTML, sin dependencias. */
+export declare function htmlToText(html: string): string;
+//# sourceMappingURL=texto.d.ts.map

package/dist/core/web/texto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"texto.d.ts","sourceRoot":"","sources":["../../../src/core/web/texto.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,sDAAsD;AACtD,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAkB/C","sourcesContent":["/**\n * Limpieza de HTML a texto plano, compartida por `web_fetch` y los scrapers.\n *\n * Vive separada de `tools.ts` para que los scrapers puedan usarla sin crear\n * un ciclo de imports estáticos con el fichero que orquesta su propio\n * registro perezoso.\n */\n\n/** Extrae texto legible de HTML, sin dependencias. */\nexport function htmlToText(html: string): string {\n\treturn (\n\t\thtml\n\t\t\t.replace(/<script[\\s\\S]*?<\\/script>/gi, \" \")\n\t\t\t.replace(/<style[\\s\\S]*?<\\/style>/gi, \" \")\n\t\t\t.replace(/<!--[\\s\\S]*?-->/g, \" \")\n\t\t\t.replace(/<[^>]+>/g, \" \")\n\t\t\t.replace(/&nbsp;/g, \" \")\n\t\t\t.replace(/&lt;/g, \"<\")\n\t\t\t.replace(/&gt;/g, \">\")\n\t\t\t.replace(/&quot;/g, '\"')\n\t\t\t.replace(/&#39;/g, \"'\")\n\t\t\t// `&amp;` va AL FINAL: hacerlo antes reintroduciría `&` y convertiría\n\t\t\t// `&amp;lt;` (un `&lt;` literal escapado) en `<`.\n\t\t\t.replace(/&amp;/g, \"&\")\n\t\t\t.replace(/\\s+/g, \" \")\n\t\t\t.trim()\n\t);\n}\n"]}

package/dist/core/web/texto.js

@@ -0,0 +1,26 @@
+/**
+ * Limpieza de HTML a texto plano, compartida por `web_fetch` y los scrapers.
+ *
+ * Vive separada de `tools.ts` para que los scrapers puedan usarla sin crear
+ * un ciclo de imports estáticos con el fichero que orquesta su propio
+ * registro perezoso.
+ */
+/** Extrae texto legible de HTML, sin dependencias. */
+export function htmlToText(html) {
+    return (html
+        .replace(/<script[\s\S]*?<\/script>/gi, " ")
+        .replace(/<style[\s\S]*?<\/style>/gi, " ")
+        .replace(/<!--[\s\S]*?-->/g, " ")
+        .replace(/<[^>]+>/g, " ")
+        .replace(/&nbsp;/g, " ")
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        // `&amp;` va AL FINAL: hacerlo antes reintroduciría `&` y convertiría
+        // `&amp;lt;` (un `&lt;` literal escapado) en `<`.
+        .replace(/&amp;/g, "&")
+        .replace(/\s+/g, " ")
+        .trim());
+}
+//# sourceMappingURL=texto.js.map

package/dist/core/web/texto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"texto.js","sourceRoot":"","sources":["../../../src/core/web/texto.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,sDAAsD;AACtD,MAAM,UAAU,UAAU,CAAC,IAAY,EAAU;IAChD,OAAO,CACN,IAAI;SACF,OAAO,CAAC,6BAA6B,EAAE,GAAG,CAAC;SAC3C,OAAO,CAAC,2BAA2B,EAAE,GAAG,CAAC;SACzC,OAAO,CAAC,kBAAkB,EAAE,GAAG,CAAC;SAChC,OAAO,CAAC,UAAU,EAAE,GAAG,CAAC;SACxB,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC;SACvB,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC;SACrB,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC;SACrB,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC;SACvB,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC;QACvB,wEAAsE;QACtE,kDAAkD;SACjD,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC;SACtB,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC;SACpB,IAAI,EAAE,CACR,CAAC;AAAA,CACF","sourcesContent":["/**\n * Limpieza de HTML a texto plano, compartida por `web_fetch` y los scrapers.\n *\n * Vive separada de `tools.ts` para que los scrapers puedan usarla sin crear\n * un ciclo de imports estáticos con el fichero que orquesta su propio\n * registro perezoso.\n */\n\n/** Extrae texto legible de HTML, sin dependencias. */\nexport function htmlToText(html: string): string {\n\treturn (\n\t\thtml\n\t\t\t.replace(/<script[\\s\\S]*?<\\/script>/gi, \" \")\n\t\t\t.replace(/<style[\\s\\S]*?<\\/style>/gi, \" \")\n\t\t\t.replace(/<!--[\\s\\S]*?-->/g, \" \")\n\t\t\t.replace(/<[^>]+>/g, \" \")\n\t\t\t.replace(/&nbsp;/g, \" \")\n\t\t\t.replace(/&lt;/g, \"<\")\n\t\t\t.replace(/&gt;/g, \">\")\n\t\t\t.replace(/&quot;/g, '\"')\n\t\t\t.replace(/&#39;/g, \"'\")\n\t\t\t// `&amp;` va AL FINAL: hacerlo antes reintroduciría `&` y convertiría\n\t\t\t// `&amp;lt;` (un `&lt;` literal escapado) en `<`.\n\t\t\t.replace(/&amp;/g, \"&\")\n\t\t\t.replace(/\\s+/g, \" \")\n\t\t\t.trim()\n\t);\n}\n"]}

package/dist/core/web/tools.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Tools de web: `web_search` y `web_fetch`.
+ *
+ * Existían por su NOMBRE en el builtin `deep_research` pero nadie las
+ * registraba, así que ese workflow —uno de los cinco que anunciamos— no podía
+ * funcionar: le pedía al agente usar herramientas inexistentes. Un nombre de
+ * tool dentro de un prompt no lo comprueba ni el compilador ni los tests.
+ *
+ * `web_search` prueba, en orden: la búsqueda nativa del proveedor de modelo
+ * activo (ya es la credencial con la que corre el agente) → el registro de
+ * proveedores de terceros con clave configurada (`proveedores/registro.ts`,
+ * vault primero, variable de entorno después) → los proveedores sin clave
+ * (DuckDuckGo, Mojeek, Ecosia), que garantizan que `web_search` funciona de
+ * fábrica incluso sin ninguna credencial de terceros y con un modelo que no
+ * traiga búsqueda propia.
+ *
+ * `web_fetch` prueba primero un scraper especializado (`scrapers/registro.ts`)
+ * que devuelve datos ESTRUCTURADOS de la API pública del sitio —versión y
+ * licencia de un paquete, no el HTML de la página—; si ninguno encaja o falla,
+ * cae al fetch genérico + limpieza de HTML de siempre.
+ *
+ * `web_fetch` trae guardas contra SSRF. Una tool que descarga cualquier URL que
+ * el modelo proponga es, sin ellas, una puerta a la red interna: basta con que
+ * el modelo lea una URL en un README para que acabe pidiéndola.
+ *
+ * El acceso a estas tools es opt-in por agente (`web: true`), nunca implícito
+ * en `readOnly` — ver `resolveAllowedTools` en workflows/agent-runner.ts.
+ */
+import type { ToolDefinition } from "../extensions/types.ts";
+import type { ResultadoWeb } from "./busqueda-nativa.ts";
+import { htmlToText } from "./texto.ts";
+export { htmlToText };
+export interface WebToolsOptions {
+    /**
+     * Clave de un proveedor de búsqueda de terceros, por nombre (`serper`,
+     * `brave`, `tavily`, `exa`, `searxng`): vault primero, variable de entorno
+     * después. `undefined` cuando ese proveedor concreto no está configurado —
+     * eso lo salta, no lo hace fallar.
+     */
+    obtenerClave: (nombreProveedor: string) => Promise<string | undefined>;
+    /**
+     * Búsqueda con la credencial del modelo, cuando el proveedor la trae.
+     *
+     * Es lo que hace que `web_search` funcione sin configurar nada: el usuario ya
+     * tiene credencial —es con la que corre el agente— y los modelos de Anthropic
+     * saben buscar solos. Sin esto, la respuesta de fábrica era «Búsqueda web no
+     * configurada», que para un agente de código equivale a no poder mirar la
+     * documentación de ninguna librería.
+     *
+     * Va PRIMERO: es la credencial que el usuario ya está pagando, así que no
+     * tiene sentido preguntar por una clave de terceros antes de intentarla.
+     *
+     * Devuelve `null` cuando NO puede buscar (el proveedor activo no trae
+     * búsqueda propia) y `[]` cuando ha buscado y no ha encontrado nada. Los dos
+     * casos se leen igual desde fuera y no son lo mismo: al agente hay que
+     * decirle «no puedo» para que cambie de estrategia, no «no hay» para que se
+     * rinda. Se cometió justo ese fallo aquí, y solo salió ejecutando el
+     * producto: con un modelo de OpenRouter la tool contestaba «Sin resultados»
+     * cuando en realidad no había buscado.
+     */
+    buscarNativo?: (consulta: string, maximo: number) => Promise<ResultadoWeb[] | null>;
+    fetchImpl?: typeof fetch;
+    /**
+     * Anota una salida a la red en el libro de sesión: art. 44 y ss. del RGPD,
+     * "qué salió de la máquina y hacia dónde".
+     *
+     * El tipo `red` del libro existía sin que nadie lo anotara. Se engancha aquí y
+     * no en el manejador de tools de `agent-session.ts` porque desde allí el único
+     * destino visible es la URL que pidió el modelo, y la petición de verdad la
+     * hacen los scrapers y los proveedores de búsqueda a OTROS dominios (la API de
+     * npm, DuckDuckGo…). Envolviendo el `fetchImpl` que todos ellos comparten, el
+     * destino que se registra es el real y no el pedido.
+     *
+     * Solo el DOMINIO, nunca la ruta ni los parámetros: una query string lleva
+     * tokens y términos de búsqueda, y el libro guarda la forma, no el contenido.
+     *
+     * Nunca debe lanzar: un fallo del registro no puede tumbar una descarga.
+     */
+    anotarRed?: (dominio: string, permitido: boolean, motivo?: string) => void;
+    timeoutMs?: number;
+}
+/**
+ * Valida una URL antes de pedirla.
+ *
+ * Bloquea esquemas no-HTTP, loopback, rangos privados y el endpoint de metadatos
+ * de los proveedores cloud — que es el objetivo clásico de un SSRF y devuelve
+ * credenciales de la instancia.
+ */
+export declare function assertFetchableUrl(raw: string): URL;
+export declare function createWebTools(options: WebToolsOptions): Record<string, ToolDefinition>;
+//# sourceMappingURL=tools.d.ts.map

package/dist/core/web/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/core/web/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAGH,OAAO,KAAK,EAAmB,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC9E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAIzD,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAExC,OAAO,EAAE,UAAU,EAAE,CAAC;AAKtB,MAAM,WAAW,eAAe;IAC/B;;;;;OAKG;IACH,YAAY,EAAE,CAAC,eAAe,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACvE;;;;;;;;;;;;;;;;;;;OAmBG;IACH,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,YAAY,EAAE,GAAG,IAAI,CAAC,CAAC;IACpF,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB;;;;;;;;;;;;;;;OAeG;IACH,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3E,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAcD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAmBnD;AA2CD,wBAAgB,cAAc,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAuMvF","sourcesContent":["/**\n * Tools de web: `web_search` y `web_fetch`.\n *\n * Existían por su NOMBRE en el builtin `deep_research` pero nadie las\n * registraba, así que ese workflow —uno de los cinco que anunciamos— no podía\n * funcionar: le pedía al agente usar herramientas inexistentes. Un nombre de\n * tool dentro de un prompt no lo comprueba ni el compilador ni los tests.\n *\n * `web_search` prueba, en orden: la búsqueda nativa del proveedor de modelo\n * activo (ya es la credencial con la que corre el agente) → el registro de\n * proveedores de terceros con clave configurada (`proveedores/registro.ts`,\n * vault primero, variable de entorno después) → los proveedores sin clave\n * (DuckDuckGo, Mojeek, Ecosia), que garantizan que `web_search` funciona de\n * fábrica incluso sin ninguna credencial de terceros y con un modelo que no\n * traiga búsqueda propia.\n *\n * `web_fetch` prueba primero un scraper especializado (`scrapers/registro.ts`)\n * que devuelve datos ESTRUCTURADOS de la API pública del sitio —versión y\n * licencia de un paquete, no el HTML de la página—; si ninguno encaja o falla,\n * cae al fetch genérico + limpieza de HTML de siempre.\n *\n * `web_fetch` trae guardas contra SSRF. Una tool que descarga cualquier URL que\n * el modelo proponga es, sin ellas, una puerta a la red interna: basta con que\n * el modelo lea una URL en un README para que acabe pidiéndola.\n *\n * El acceso a estas tools es opt-in por agente (`web: true`), nunca implícito\n * en `readOnly` — ver `resolveAllowedTools` en workflows/agent-runner.ts.\n */\n\nimport { Type } from \"typebox\";\nimport type { AgentToolResult, ToolDefinition } from \"../extensions/types.ts\";\nimport type { ResultadoWeb } from \"./busqueda-nativa.ts\";\nimport { destinoPermitido } from \"./destino.ts\";\nimport { buscarConProveedores } from \"./proveedores/registro.ts\";\nimport { encontrarScraper } from \"./scrapers/registro.ts\";\nimport { htmlToText } from \"./texto.ts\";\n\nexport { htmlToText };\n\nconst MAX_FETCH_BYTES = 512 * 1024;\nconst DEFAULT_TIMEOUT_MS = 20_000;\n\nexport interface WebToolsOptions {\n\t/**\n\t * Clave de un proveedor de búsqueda de terceros, por nombre (`serper`,\n\t * `brave`, `tavily`, `exa`, `searxng`): vault primero, variable de entorno\n\t * después. `undefined` cuando ese proveedor concreto no está configurado —\n\t * eso lo salta, no lo hace fallar.\n\t */\n\tobtenerClave: (nombreProveedor: string) => Promise<string | undefined>;\n\t/**\n\t * Búsqueda con la credencial del modelo, cuando el proveedor la trae.\n\t *\n\t * Es lo que hace que `web_search` funcione sin configurar nada: el usuario ya\n\t * tiene credencial —es con la que corre el agente— y los modelos de Anthropic\n\t * saben buscar solos. Sin esto, la respuesta de fábrica era «Búsqueda web no\n\t * configurada», que para un agente de código equivale a no poder mirar la\n\t * documentación de ninguna librería.\n\t *\n\t * Va PRIMERO: es la credencial que el usuario ya está pagando, así que no\n\t * tiene sentido preguntar por una clave de terceros antes de intentarla.\n\t *\n\t * Devuelve `null` cuando NO puede buscar (el proveedor activo no trae\n\t * búsqueda propia) y `[]` cuando ha buscado y no ha encontrado nada. Los dos\n\t * casos se leen igual desde fuera y no son lo mismo: al agente hay que\n\t * decirle «no puedo» para que cambie de estrategia, no «no hay» para que se\n\t * rinda. Se cometió justo ese fallo aquí, y solo salió ejecutando el\n\t * producto: con un modelo de OpenRouter la tool contestaba «Sin resultados»\n\t * cuando en realidad no había buscado.\n\t */\n\tbuscarNativo?: (consulta: string, maximo: number) => Promise<ResultadoWeb[] | null>;\n\tfetchImpl?: typeof fetch;\n\t/**\n\t * Anota una salida a la red en el libro de sesión: art. 44 y ss. del RGPD,\n\t * \"qué salió de la máquina y hacia dónde\".\n\t *\n\t * El tipo `red` del libro existía sin que nadie lo anotara. Se engancha aquí y\n\t * no en el manejador de tools de `agent-session.ts` porque desde allí el único\n\t * destino visible es la URL que pidió el modelo, y la petición de verdad la\n\t * hacen los scrapers y los proveedores de búsqueda a OTROS dominios (la API de\n\t * npm, DuckDuckGo…). Envolviendo el `fetchImpl` que todos ellos comparten, el\n\t * destino que se registra es el real y no el pedido.\n\t *\n\t * Solo el DOMINIO, nunca la ruta ni los parámetros: una query string lleva\n\t * tokens y términos de búsqueda, y el libro guarda la forma, no el contenido.\n\t *\n\t * Nunca debe lanzar: un fallo del registro no puede tumbar una descarga.\n\t */\n\tanotarRed?: (dominio: string, permitido: boolean, motivo?: string) => void;\n\ttimeoutMs?: number;\n}\n\nfunction textResult(text: string): AgentToolResult<unknown> {\n\treturn { content: [{ type: \"text\" as const, text }], details: undefined };\n}\n\n/** Hosts que nunca deben alcanzarse desde una URL propuesta por el modelo. */\nconst BLOCKED_HOSTNAMES = new Set([\"localhost\", \"metadata.google.internal\", \"metadata\"]);\n\n/** Cuántos saltos se siguen antes de rendirse. Cada uno se revalida. */\nconst MAX_REDIRECCIONES = 5;\nconst PRIVATE_IPV4 =\n\t/^(?:10\\.|127\\.|0\\.|169\\.254\\.|192\\.168\\.|172\\.(?:1[6-9]|2\\d|3[01])\\.|100\\.(?:6[4-9]|[7-9]\\d|1[01]\\d|12[0-7])\\.)/;\n\n/**\n * Valida una URL antes de pedirla.\n *\n * Bloquea esquemas no-HTTP, loopback, rangos privados y el endpoint de metadatos\n * de los proveedores cloud — que es el objetivo clásico de un SSRF y devuelve\n * credenciales de la instancia.\n */\nexport function assertFetchableUrl(raw: string): URL {\n\tlet url: URL;\n\ttry {\n\t\turl = new URL(raw);\n\t} catch {\n\t\tthrow new Error(`URL inválida: ${raw}`);\n\t}\n\tif (url.protocol !== \"http:\" && url.protocol !== \"https:\") {\n\t\tthrow new Error(`Solo se permiten http y https (recibido: ${url.protocol}).`);\n\t}\n\tconst host = url.hostname.toLowerCase().replace(/^\\[|\\]$/g, \"\");\n\tif (host === \"169.254.169.254\") throw new Error(\"Endpoint de metadatos cloud bloqueado.\");\n\tif (BLOCKED_HOSTNAMES.has(host) || host.endsWith(\".localhost\")) {\n\t\tthrow new Error(`Host bloqueado: ${host}`);\n\t}\n\tif (PRIVATE_IPV4.test(host) || host === \"::1\" || host.startsWith(\"fc\") || host.startsWith(\"fd\")) {\n\t\tthrow new Error(`Dirección de red privada bloqueada: ${host}`);\n\t}\n\treturn url;\n}\n\nconst searchParams = Type.Object({\n\tquery: Type.String({ description: \"Consulta de búsqueda.\" }),\n\tcount: Type.Optional(Type.Number({ description: \"Número de resultados (por defecto 5, máximo 10).\" })),\n});\n\nconst fetchParams = Type.Object({\n\turl: Type.String({ description: \"URL http(s) a descargar.\" }),\n});\n\n/** Formatea resultados de búsqueda (nativos o de un proveedor) como texto numerado. */\nfunction formatearResultados(\n\tresultados: Array<{ titulo: string; url: string; resumen?: string; edad?: string }>,\n): string {\n\treturn resultados\n\t\t.map((r, i) => {\n\t\t\tconst partes = [`${i + 1}. ${r.titulo}`, `   ${r.url}`];\n\t\t\tif (r.resumen) partes.push(`   ${r.resumen}`);\n\t\t\tif (r.edad) partes.push(`   (${r.edad})`);\n\t\t\treturn partes.join(\"\\n\");\n\t\t})\n\t\t.join(\"\\n\\n\");\n}\n\n/**\n * El dominio de destino, o `null` si no se puede leer.\n *\n * Solo el hostname: la ruta y la query se descartan aquí a propósito, porque es\n * el único sitio por el que pasan y un `?api_key=…` en el libro sería la fuga\n * que el libro existe para no tener.\n */\n// `Parameters<typeof fetch>[0]` y no `RequestInfo`: el proyecto compila sin la\n// librería DOM, así que ese nombre global no existe aquí.\nfunction dominioDe(destino: Parameters<typeof fetch>[0]): string | null {\n\ttry {\n\t\tconst crudo = typeof destino === \"string\" ? destino : destino instanceof URL ? destino.href : destino.url;\n\t\treturn new URL(crudo).hostname || null;\n\t} catch {\n\t\treturn null;\n\t}\n}\n\nexport function createWebTools(options: WebToolsOptions): Record<string, ToolDefinition> {\n\tconst fetchCrudo = options.fetchImpl ?? fetch;\n\tconst anotarRed = options.anotarRed;\n\t// Un solo punto para todas las salidas: este `fetchImpl` es el que reciben los\n\t// scrapers (`modulo.scrapear(url, fetchImpl, …)`) y los proveedores de\n\t// búsqueda (`buscarConProveedores(…, { fetchImpl })`), así que envolverlo una\n\t// vez registra las salidas de los tres caminos y no solo del fetch genérico.\n\tconst fetchImpl: typeof fetch = anotarRed\n\t\t? (destino, init) => {\n\t\t\t\tconst dominio = dominioDe(destino);\n\t\t\t\t// `try` porque el registro es best-effort y la descarga no lo es.\n\t\t\t\tif (dominio) {\n\t\t\t\t\ttry {\n\t\t\t\t\t\tanotarRed(dominio, true);\n\t\t\t\t\t} catch {\n\t\t\t\t\t\t// Un fallo del libro no puede impedir una descarga.\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\treturn fetchCrudo(destino, init);\n\t\t\t}\n\t\t: fetchCrudo;\n\tconst timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;\n\n\t/** Aborta la petición si tarda demasiado, y respeta el abort del agente. */\n\tconst withTimeout = async (\n\t\touter: AbortSignal | undefined,\n\t\trun: (signal: AbortSignal) => Promise<Response>,\n\t): Promise<Response> => {\n\t\tconst controller = new AbortController();\n\t\tconst timer = setTimeout(() => controller.abort(), timeoutMs);\n\t\tconst onAbort = () => controller.abort();\n\t\touter?.addEventListener(\"abort\", onAbort);\n\t\ttry {\n\t\t\treturn await run(controller.signal);\n\t\t} finally {\n\t\t\tclearTimeout(timer);\n\t\t\touter?.removeEventListener(\"abort\", onAbort);\n\t\t}\n\t};\n\n\tconst webSearch: ToolDefinition<typeof searchParams> = {\n\t\tname: \"web_search\",\n\t\tlabel: \"Buscar en la web\",\n\t\tdescription:\n\t\t\t\"Busca en la web y devuelve resultados con título, URL y extracto. \" +\n\t\t\t\"Úsalo para hechos que puedan haber cambiado o que no estén en el repositorio. \" +\n\t\t\t\"Cita siempre la URL exacta: un resultado sin fuente no vale como evidencia.\",\n\t\tpromptSnippet: \"buscar en la web\",\n\t\tparameters: searchParams,\n\t\tasync execute(_toolCallId, input, signal): Promise<AgentToolResult<unknown>> {\n\t\t\tconst query = String(input.query ?? \"\").trim();\n\t\t\tif (!query) return textResult(\"Error: 'query' es obligatorio.\");\n\t\t\tconst count = Math.min(Math.max(Number(input.count) || 5, 1), 10);\n\n\t\t\t// 1) Nativo del proveedor de modelo: la credencial que el usuario ya paga.\n\t\t\tif (options.buscarNativo) {\n\t\t\t\ttry {\n\t\t\t\t\tconst nativos = await options.buscarNativo(query, count);\n\t\t\t\t\tif (nativos !== null) {\n\t\t\t\t\t\tif (nativos.length === 0) return textResult(`Sin resultados para: ${query}`);\n\t\t\t\t\t\treturn textResult(formatearResultados(nativos));\n\t\t\t\t\t}\n\t\t\t\t\t// null: el proveedor activo no trae búsqueda propia — seguir al registro.\n\t\t\t\t} catch (error) {\n\t\t\t\t\treturn textResult(\n\t\t\t\t\t\t`La búsqueda con el modelo falló: ${error instanceof Error ? error.message : String(error)}`,\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t}\n\n\t\t\t// 2) Registro de proveedores: clave configurada > sin clave. Los tres sin\n\t\t\t// clave (duckduckgo, mojeek, ecosia) están siempre en la lista, así que\n\t\t\t// esto SIEMPRE tiene algo que probar — nunca \"no configurado\".\n\t\t\ttry {\n\t\t\t\tconst { resultados } = await buscarConProveedores(query, count, {\n\t\t\t\t\tobtenerClave: options.obtenerClave,\n\t\t\t\t\tfetchImpl,\n\t\t\t\t\tsignal,\n\t\t\t\t});\n\t\t\t\tif (resultados.length === 0) return textResult(`Sin resultados para: ${query}`);\n\t\t\t\treturn textResult(formatearResultados(resultados));\n\t\t\t} catch (error) {\n\t\t\t\t// Un fallo de red o de todos los proveedores es un FALLO, no \"sin\n\t\t\t\t// resultados\": el agente debe saber que no se ha buscado de verdad.\n\t\t\t\treturn textResult(`La búsqueda falló: ${error instanceof Error ? error.message : String(error)}`);\n\t\t\t}\n\t\t},\n\t};\n\n\tconst webFetch: ToolDefinition<typeof fetchParams> = {\n\t\tname: \"web_fetch\",\n\t\tlabel: \"Descargar URL\",\n\t\tdescription:\n\t\t\t\"Descarga una URL y devuelve su texto. Úsalo tras web_search para leer una fuente concreta. \" +\n\t\t\t\"Para registros de paquetes (npm, PyPI, crates.io…), GitHub, MDN, Stack Overflow y CVEs (NVD, CISA \" +\n\t\t\t\"KEV) devuelve datos estructurados en vez de HTML. Solo http/https públicos: la red interna está bloqueada.\",\n\t\tpromptSnippet: \"leer el contenido de una URL\",\n\t\tparameters: fetchParams,\n\t\tasync execute(_toolCallId, input, signal): Promise<AgentToolResult<unknown>> {\n\t\t\tconst raw = String(input.url ?? \"\").trim();\n\t\t\tif (!raw) return textResult(\"Error: 'url' es obligatorio.\");\n\t\t\tlet url: URL;\n\t\t\ttry {\n\t\t\t\turl = assertFetchableUrl(raw);\n\t\t\t} catch (error) {\n\t\t\t\tconst motivo = error instanceof Error ? error.message : String(error);\n\t\t\t\t// Un intento BLOQUEADO es tan auditable como una salida consumada, y es\n\t\t\t\t// el único que no pasa por el `fetchImpl` envuelto: la guarda SSRF corta\n\t\t\t\t// antes. Sin esta línea el libro solo tendría `permitido: true` y el\n\t\t\t\t// campo `permitido` sería decorativo — un registro que dice siempre lo\n\t\t\t\t// mismo no distingue nada.\n\t\t\t\ttry {\n\t\t\t\t\tanotarRed?.(dominioDe(raw) ?? \"(url ilegible)\", false, motivo);\n\t\t\t\t} catch {\n\t\t\t\t\t// best-effort, igual que arriba.\n\t\t\t\t}\n\t\t\t\treturn textResult(`Error: ${motivo}`);\n\t\t\t}\n\n\t\t\t// Scraper especializado primero: datos estructurados de la API del sitio\n\t\t\t// en vez del HTML de la página. Si no encaja o falla, se cae al fetch\n\t\t\t// genérico de siempre — la URL sigue siendo legible aunque no se pueda\n\t\t\t// enriquecer.\n\t\t\tconst descriptor = encontrarScraper(url);\n\t\t\tif (descriptor) {\n\t\t\t\ttry {\n\t\t\t\t\tconst modulo = await descriptor.cargar();\n\t\t\t\t\tconst resultado = await modulo.scrapear(url, fetchImpl, signal);\n\t\t\t\t\tif (resultado) {\n\t\t\t\t\t\treturn textResult(\n\t\t\t\t\t\t\t`${resultado.titulo}\\n${resultado.url}\\n\\n${resultado.resumen}\\n\\nDatos estructurados:\\n` +\n\t\t\t\t\t\t\t\tJSON.stringify(resultado.datos, null, 2),\n\t\t\t\t\t\t);\n\t\t\t\t\t}\n\t\t\t\t} catch {\n\t\t\t\t\t// El scraper falló: se cae al fetch genérico en vez de dejar la\n\t\t\t\t\t// tool en blanco. La URL sigue siendo lo que el usuario pidió leer.\n\t\t\t\t}\n\t\t\t}\n\n\t\t\t// La dirección, no el nombre. `assertFetchableUrl` compara cadenas y deja\n\t\t\t// pasar todo lo que llega al mismo sitio por otro camino: medido,\n\t\t\t// `[::ffff:127.0.0.1]` y un dominio que resuelve a 127.0.0.1 pasaban\n\t\t\t// enteros. Ver `core/web/destino.ts`.\n\t\t\tconst rechazo = await destinoPermitido(url);\n\t\t\tif (rechazo) {\n\t\t\t\tanotarRed?.(url.hostname, false, rechazo.motivo);\n\t\t\t\treturn textResult(\n\t\t\t\t\t`Descarga bloqueada: ${rechazo.motivo}${rechazo.direccion ? ` (${rechazo.direccion})` : \"\"}. ` +\n\t\t\t\t\t\t\"Las tools web no alcanzan la red interna ni la propia máquina.\",\n\t\t\t\t);\n\t\t\t}\n\n\t\t\ttry {\n\t\t\t\t// `redirect: \"manual\"` y cada salto revalidado. Con `follow`, una URL\n\t\t\t\t// pública que responde 302 hacia loopback llegaba igual, porque solo se\n\t\t\t\t// miraba la primera — era el tercer camino abierto de los tres.\n\t\t\t\tlet destino = url;\n\t\t\t\tlet response: Response | undefined;\n\t\t\t\tfor (let salto = 0; salto <= MAX_REDIRECCIONES; salto++) {\n\t\t\t\t\tresponse = await withTimeout(signal, (s) =>\n\t\t\t\t\t\tfetchImpl(destino.toString(), {\n\t\t\t\t\t\t\tredirect: \"manual\",\n\t\t\t\t\t\t\tsignal: s,\n\t\t\t\t\t\t\theaders: { \"user-agent\": \"ada-cli\" },\n\t\t\t\t\t\t}),\n\t\t\t\t\t);\n\t\t\t\t\tif (response.status < 300 || response.status >= 400) break;\n\t\t\t\t\tconst siguiente = response.headers.get(\"location\");\n\t\t\t\t\tif (!siguiente) break;\n\t\t\t\t\tif (salto === MAX_REDIRECCIONES) {\n\t\t\t\t\t\treturn textResult(`La descarga dio más de ${MAX_REDIRECCIONES} redirecciones y se ha parado.`);\n\t\t\t\t\t}\n\t\t\t\t\t// Relativa respecto al destino actual, como manda el estándar.\n\t\t\t\t\tdestino = new URL(siguiente, destino);\n\t\t\t\t\tassertFetchableUrl(destino.toString());\n\t\t\t\t\tconst rechazoSalto = await destinoPermitido(destino);\n\t\t\t\t\tif (rechazoSalto) {\n\t\t\t\t\t\tanotarRed?.(destino.hostname, false, `redirección a ${rechazoSalto.motivo}`);\n\t\t\t\t\t\treturn textResult(\n\t\t\t\t\t\t\t`Descarga bloqueada: la redirección lleva a ${rechazoSalto.motivo}` +\n\t\t\t\t\t\t\t\t`${rechazoSalto.direccion ? ` (${rechazoSalto.direccion})` : \"\"}.`,\n\t\t\t\t\t\t);\n\t\t\t\t\t}\n\t\t\t\t\tanotarRed?.(destino.hostname, true, \"redirección\");\n\t\t\t\t}\n\t\t\t\tif (!response) return textResult(\"La descarga no devolvió respuesta.\");\n\t\t\t\tif (!response.ok) return textResult(`La descarga devolvió HTTP ${response.status}.`);\n\t\t\t\tconst body = await response.text();\n\t\t\t\tconst truncated = body.length > MAX_FETCH_BYTES;\n\t\t\t\tconst text = htmlToText(body.slice(0, MAX_FETCH_BYTES));\n\t\t\t\treturn textResult(truncated ? `${text}\\n\\n[truncado en ${MAX_FETCH_BYTES} bytes]` : text);\n\t\t\t} catch (error) {\n\t\t\t\treturn textResult(`La descarga falló: ${error instanceof Error ? error.message : String(error)}`);\n\t\t\t}\n\t\t},\n\t};\n\n\treturn { web_search: webSearch as ToolDefinition, web_fetch: webFetch as ToolDefinition };\n}\n"]}