@hoilab/ada-cli 0.84.22 → 0.85.0

package/dist/core/web/busqueda-nativa.js

@@ -0,0 +1,163 @@
+/**
+ * Búsqueda web con la credencial que el usuario YA tiene.
+ *
+ * Hasta ahora `web_search` exigía una clave de Serper aparte, así que la
+ * respuesta de fábrica era «Búsqueda web no configurada». Un agente de código
+ * que no puede mirar la documentación de una librería está cojo, y pedir una
+ * segunda cuenta para eso es una fricción que el usuario paga antes de haber
+ * visto ningún valor.
+ *
+ * Los modelos de Anthropic traen búsqueda de servidor (`web_search_20250305`).
+ * Si hay credencial de Anthropic —y la hay, porque es con lo que corre el
+ * agente— buscar puede funcionar sin configurar nada.
+ *
+ * Dos detalles que no son evidentes y que se descubrieron probándolo:
+ *
+ * 1. **Los resultados no llegan por el contenido del mensaje.** Nuestra capa de
+ *    modelos normaliza la respuesta a texto/razonamiento/llamadas, y los
+ *    bloques `web_search_tool_result` se pierden por el camino. Pedirle al
+ *    modelo que los liste en el texto tampoco vale: se probó, y contesta la
+ *    pregunta en vez de listar fuentes. Hay que leer el flujo crudo.
+ *
+ * 2. **Se lee sin tocar la capa de modelos**, pasando un `fetch` propio que
+ *    duplica el cuerpo con `tee()`: una rama sigue al SDK intacta y la otra se
+ *    analiza aquí. `agent-session.ts` y `packages/ai` son de upstream y el
+ *    presupuesto de fork está en el tope; esto no cuesta ni un hunk.
+ */
+/** La tool de servidor de Anthropic. */
+const TOOL_BUSQUEDA = "web_search_20250305";
+/** Proveedores cuyo modelo sabe buscar por su cuenta. */
+export function soportaBusquedaNativa(proveedor) {
+    return proveedor === "anthropic";
+}
+/**
+ * Añade la tool de búsqueda a la carga de la petición, sin pisar las que haya.
+ *
+ * Pura y separada para poder probarla: si esto machacara `tools`, el modelo se
+ * quedaría sin sus herramientas y el fallo aparecería en cualquier otro sitio.
+ */
+export function conToolDeBusqueda(carga, maxUsos = 5) {
+    if (!carga || typeof carga !== "object")
+        return carga;
+    const p = carga;
+    p.tools = [...(p.tools ?? []), { type: TOOL_BUSQUEDA, name: "web_search", max_uses: maxUsos }];
+    return p;
+}
+/**
+ * Recorre cualquier estructura y recoge los resultados de búsqueda.
+ *
+ * Se busca por el campo `type` en vez de por la ruta exacta del evento a
+ * propósito: el formato de los eventos SSE puede cambiar de sitio los bloques,
+ * y un recolector que dependa de la ruta se rompe en silencio —devolviendo cero
+ * resultados, que se lee igual que «no hay nada»—.
+ */
+export function recolectarResultados(valor, acumulado = []) {
+    if (Array.isArray(valor)) {
+        for (const v of valor)
+            recolectarResultados(v, acumulado);
+        return acumulado;
+    }
+    if (!valor || typeof valor !== "object")
+        return acumulado;
+    const o = valor;
+    if (o.type === "web_search_result" && typeof o.url === "string") {
+        acumulado.push({
+            titulo: typeof o.title === "string" ? o.title : o.url,
+            url: o.url,
+            edad: typeof o.page_age === "string" ? o.page_age : undefined,
+        });
+    }
+    for (const v of Object.values(o))
+        recolectarResultados(v, acumulado);
+    return acumulado;
+}
+/** Quita repetidos por URL, conservando el orden de aparición. */
+export function sinRepetidos(resultados) {
+    const vistas = new Set();
+    const unicos = [];
+    for (const r of resultados) {
+        if (vistas.has(r.url))
+            continue;
+        vistas.add(r.url);
+        unicos.push(r);
+    }
+    return unicos;
+}
+/**
+ * Envuelve un `fetch` para leer los resultados sin estorbar a quien lo usa.
+ *
+ * `tee()` da dos flujos: uno se devuelve intacto —el SDK tiene que recibir
+ * exactamente lo que habría recibido— y el otro se analiza aquí. Si el análisis
+ * falla, falla solo: una búsqueda sin fuentes es peor que una con fuentes, pero
+ * una sesión rota por el analizador es mucho peor que las dos.
+ */
+export function fetchQueRecolecta(base, destino) {
+    return async (...args) => {
+        const respuesta = await base(...args);
+        if (!respuesta.body)
+            return respuesta;
+        const [paraElSdk, paraNosotros] = respuesta.body.tee();
+        void (async () => {
+            const lector = paraNosotros.getReader();
+            const decodificador = new TextDecoder();
+            let pendiente = "";
+            try {
+                for (;;) {
+                    const { done, value } = await lector.read();
+                    if (done)
+                        break;
+                    pendiente += decodificador.decode(value, { stream: true });
+                    const lineas = pendiente.split("\n");
+                    // La última puede estar a medias: se queda para la próxima vuelta.
+                    pendiente = lineas.pop() ?? "";
+                    for (const linea of lineas) {
+                        if (!linea.startsWith("data: "))
+                            continue;
+                        try {
+                            recolectarResultados(JSON.parse(linea.slice(6)), destino);
+                        }
+                        catch {
+                            // Una línea que no es JSON no dice nada del resto del flujo.
+                        }
+                    }
+                }
+                // El flujo puede acabar sin salto final, y entonces el último evento
+                // se queda en `pendiente`. Perderlo silenciosamente equivaldría a
+                // devolver una fuente menos sin que nadie lo note.
+                if (pendiente.startsWith("data: ")) {
+                    try {
+                        recolectarResultados(JSON.parse(pendiente.slice(6)), destino);
+                    }
+                    catch {
+                        // Una cola incompleta no es un error: es una cola incompleta.
+                    }
+                }
+            }
+            catch {
+                // La rama de análisis nunca puede tumbar la petición.
+            }
+        })();
+        return new Response(paraElSdk, {
+            status: respuesta.status,
+            statusText: respuesta.statusText,
+            headers: respuesta.headers,
+        });
+    };
+}
+/**
+ * Busca y devuelve las fuentes.
+ *
+ * No devuelve la síntesis del modelo a propósito: quien llama es el agente, que
+ * ya sabe leer. Lo que necesita de una búsqueda son URLs a las que ir con
+ * `web_fetch`, no un resumen de segunda mano que ya viene con la
+ * interpretación de otro modelo encima.
+ */
+export async function buscarConElModelo(consulta, deps) {
+    const encontrados = [];
+    await deps.completar(consulta, {
+        fetch: fetchQueRecolecta(deps.fetchBase ?? fetch, encontrados),
+        onPayload: (carga) => conToolDeBusqueda(carga),
+    });
+    return sinRepetidos(encontrados).slice(0, deps.maxResultados ?? 10);
+}
+//# sourceMappingURL=busqueda-nativa.js.map

package/dist/core/web/busqueda-nativa.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"busqueda-nativa.js","sourceRoot":"","sources":["../../../src/core/web/busqueda-nativa.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Búsqueda web con la credencial que el usuario YA tiene.\n *\n * Hasta ahora `web_search` exigía una clave de Serper aparte, así que la\n * respuesta de fábrica era «Búsqueda web no configurada». Un agente de código\n * que no puede mirar la documentación de una librería está cojo, y pedir una\n * segunda cuenta para eso es una fricción que el usuario paga antes de haber\n * visto ningún valor.\n *\n * Los modelos de Anthropic traen búsqueda de servidor (`web_search_20250305`).\n * Si hay credencial de Anthropic —y la hay, porque es con lo que corre el\n * agente— buscar puede funcionar sin configurar nada.\n *\n * Dos detalles que no son evidentes y que se descubrieron probándolo:\n *\n * 1. **Los resultados no llegan por el contenido del mensaje.** Nuestra capa de\n *    modelos normaliza la respuesta a texto/razonamiento/llamadas, y los\n *    bloques `web_search_tool_result` se pierden por el camino. Pedirle al\n *    modelo que los liste en el texto tampoco vale: se probó, y contesta la\n *    pregunta en vez de listar fuentes. Hay que leer el flujo crudo.\n *\n * 2. **Se lee sin tocar la capa de modelos**, pasando un `fetch` propio que\n *    duplica el cuerpo con `tee()`: una rama sigue al SDK intacta y la otra se\n *    analiza aquí. `agent-session.ts` y `packages/ai` son de upstream y el\n *    presupuesto de fork está en el tope; esto no cuesta ni un hunk.\n */\n\n/** Un resultado, ya normalizado. */\nexport interface ResultadoWeb {\n\ttitulo: string;\n\turl: string;\n\t/** Antigüedad tal y como la da el proveedor (\"3 weeks ago\", \"June 8, 2026\"). */\n\tedad?: string;\n}\n\n/** La tool de servidor de Anthropic. */\nconst TOOL_BUSQUEDA = \"web_search_20250305\";\n\n/** Proveedores cuyo modelo sabe buscar por su cuenta. */\nexport function soportaBusquedaNativa(proveedor: string): boolean {\n\treturn proveedor === \"anthropic\";\n}\n\n/**\n * Añade la tool de búsqueda a la carga de la petición, sin pisar las que haya.\n *\n * Pura y separada para poder probarla: si esto machacara `tools`, el modelo se\n * quedaría sin sus herramientas y el fallo aparecería en cualquier otro sitio.\n */\nexport function conToolDeBusqueda(carga: unknown, maxUsos = 5): unknown {\n\tif (!carga || typeof carga !== \"object\") return carga;\n\tconst p = carga as { tools?: unknown[] };\n\tp.tools = [...(p.tools ?? []), { type: TOOL_BUSQUEDA, name: \"web_search\", max_uses: maxUsos }];\n\treturn p;\n}\n\n/**\n * Recorre cualquier estructura y recoge los resultados de búsqueda.\n *\n * Se busca por el campo `type` en vez de por la ruta exacta del evento a\n * propósito: el formato de los eventos SSE puede cambiar de sitio los bloques,\n * y un recolector que dependa de la ruta se rompe en silencio —devolviendo cero\n * resultados, que se lee igual que «no hay nada»—.\n */\nexport function recolectarResultados(valor: unknown, acumulado: ResultadoWeb[] = []): ResultadoWeb[] {\n\tif (Array.isArray(valor)) {\n\t\tfor (const v of valor) recolectarResultados(v, acumulado);\n\t\treturn acumulado;\n\t}\n\tif (!valor || typeof valor !== \"object\") return acumulado;\n\tconst o = valor as Record<string, unknown>;\n\tif (o.type === \"web_search_result\" && typeof o.url === \"string\") {\n\t\tacumulado.push({\n\t\t\ttitulo: typeof o.title === \"string\" ? o.title : o.url,\n\t\t\turl: o.url,\n\t\t\tedad: typeof o.page_age === \"string\" ? o.page_age : undefined,\n\t\t});\n\t}\n\tfor (const v of Object.values(o)) recolectarResultados(v, acumulado);\n\treturn acumulado;\n}\n\n/** Quita repetidos por URL, conservando el orden de aparición. */\nexport function sinRepetidos(resultados: ResultadoWeb[]): ResultadoWeb[] {\n\tconst vistas = new Set<string>();\n\tconst unicos: ResultadoWeb[] = [];\n\tfor (const r of resultados) {\n\t\tif (vistas.has(r.url)) continue;\n\t\tvistas.add(r.url);\n\t\tunicos.push(r);\n\t}\n\treturn unicos;\n}\n\n/**\n * Envuelve un `fetch` para leer los resultados sin estorbar a quien lo usa.\n *\n * `tee()` da dos flujos: uno se devuelve intacto —el SDK tiene que recibir\n * exactamente lo que habría recibido— y el otro se analiza aquí. Si el análisis\n * falla, falla solo: una búsqueda sin fuentes es peor que una con fuentes, pero\n * una sesión rota por el analizador es mucho peor que las dos.\n */\nexport function fetchQueRecolecta(base: typeof fetch, destino: ResultadoWeb[]): typeof fetch {\n\treturn async (...args) => {\n\t\tconst respuesta = await base(...args);\n\t\tif (!respuesta.body) return respuesta;\n\t\tconst [paraElSdk, paraNosotros] = respuesta.body.tee();\n\n\t\tvoid (async () => {\n\t\t\tconst lector = paraNosotros.getReader();\n\t\t\tconst decodificador = new TextDecoder();\n\t\t\tlet pendiente = \"\";\n\t\t\ttry {\n\t\t\t\tfor (;;) {\n\t\t\t\t\tconst { done, value } = await lector.read();\n\t\t\t\t\tif (done) break;\n\t\t\t\t\tpendiente += decodificador.decode(value, { stream: true });\n\t\t\t\t\tconst lineas = pendiente.split(\"\\n\");\n\t\t\t\t\t// La última puede estar a medias: se queda para la próxima vuelta.\n\t\t\t\t\tpendiente = lineas.pop() ?? \"\";\n\t\t\t\t\tfor (const linea of lineas) {\n\t\t\t\t\t\tif (!linea.startsWith(\"data: \")) continue;\n\t\t\t\t\t\ttry {\n\t\t\t\t\t\t\trecolectarResultados(JSON.parse(linea.slice(6)), destino);\n\t\t\t\t\t\t} catch {\n\t\t\t\t\t\t\t// Una línea que no es JSON no dice nada del resto del flujo.\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\t// El flujo puede acabar sin salto final, y entonces el último evento\n\t\t\t\t// se queda en `pendiente`. Perderlo silenciosamente equivaldría a\n\t\t\t\t// devolver una fuente menos sin que nadie lo note.\n\t\t\t\tif (pendiente.startsWith(\"data: \")) {\n\t\t\t\t\ttry {\n\t\t\t\t\t\trecolectarResultados(JSON.parse(pendiente.slice(6)), destino);\n\t\t\t\t\t} catch {\n\t\t\t\t\t\t// Una cola incompleta no es un error: es una cola incompleta.\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t} catch {\n\t\t\t\t// La rama de análisis nunca puede tumbar la petición.\n\t\t\t}\n\t\t})();\n\n\t\treturn new Response(paraElSdk, {\n\t\t\tstatus: respuesta.status,\n\t\t\tstatusText: respuesta.statusText,\n\t\t\theaders: respuesta.headers,\n\t\t});\n\t};\n}\n\n/** Lo que hace falta para buscar, inyectado para poder probarlo sin red. */\nexport interface DependenciasBusqueda {\n\t/** Ejecuta una consulta contra el modelo con las opciones dadas. */\n\tcompletar: (\n\t\tconsulta: string,\n\t\topciones: { fetch: typeof fetch; onPayload: (c: unknown) => unknown },\n\t) => Promise<void>;\n\tfetchBase?: typeof fetch;\n\tmaxResultados?: number;\n}\n\n/**\n * Busca y devuelve las fuentes.\n *\n * No devuelve la síntesis del modelo a propósito: quien llama es el agente, que\n * ya sabe leer. Lo que necesita de una búsqueda son URLs a las que ir con\n * `web_fetch`, no un resumen de segunda mano que ya viene con la\n * interpretación de otro modelo encima.\n */\nexport async function buscarConElModelo(consulta: string, deps: DependenciasBusqueda): Promise<ResultadoWeb[]> {\n\tconst encontrados: ResultadoWeb[] = [];\n\tawait deps.completar(consulta, {\n\t\tfetch: fetchQueRecolecta(deps.fetchBase ?? fetch, encontrados),\n\t\tonPayload: (carga) => conToolDeBusqueda(carga),\n\t});\n\treturn sinRepetidos(encontrados).slice(0, deps.maxResultados ?? 10);\n}\n"]}

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

@@ -0,0 +1,58 @@
+/**
+ * ¿A dónde va de verdad esta URL?
+ *
+ * EL FALLO. `assertFetchableUrl` compara el NOMBRE del host contra una lista y
+ * unas expresiones regulares. Eso para lo evidente y deja pasar todo lo que
+ * llega a la misma dirección por otro camino. Medido sobre nuestra guarda:
+ *
+ *     http://127.0.0.1:8080/secreto          bloqueado
+ *     http://localhost:8080/secreto          bloqueado
+ *     http://[::1]:8080/secreto              bloqueado
+ *     http://[::ffff:127.0.0.1]:8080/secreto PASA   ← IPv4 mapeada en IPv6
+ *     http://localtest.me:8080/secreto       PASA   ← resuelve a 127.0.0.1
+ *
+ * Y había un tercero: `redirect: "follow"`. Una URL pública que responde 302
+ * hacia loopback llega igual, porque la guarda solo mira la primera.
+ *
+ * Para un agente esto es serio: el modelo puede pedir una descarga con una URL
+ * que parece de internet y acabar leyendo el panel de administración de la red
+ * interna, o el endpoint de metadatos de la nube — que es donde viven las
+ * credenciales de la máquina.
+ *
+ * LA CAUSA RAÍZ, y por eso este módulo existe aparte: un nombre no es un
+ * destino. Lo único que dice a dónde va una petición es la DIRECCIÓN a la que
+ * resuelve, así que hay que resolverla y mirarla. Las comprobaciones por nombre
+ * se quedan, pero como filtro barato de primera pasada, no como la defensa.
+ *
+ * LO QUE NO RESUELVE, dicho antes de que lo descubra nadie: entre que
+ * resolvemos y que la petición sale, el DNS puede cambiar de respuesta —el
+ * ataque clásico de «rebind». Cerrarlo del todo exige fijar la dirección
+ * resuelta al abrir la conexión, que es cosa del agente HTTP y no de aquí.
+ * Contra un servidor hostil que controle su propio DNS esto sube el listón; no
+ * lo cierra.
+ */
+/** Por qué se rechaza un destino. Nunca una lista vacía silenciosa. */
+export interface DestinoRechazado {
+    motivo: string;
+    /** La dirección concreta que lo delató, cuando la hay. */
+    direccion?: string;
+}
+/**
+ * ¿Esta dirección IP es de una red que no debe alcanzarse desde una tool web?
+ *
+ * Se trabaja sobre la dirección ya resuelta, así que da igual cómo se escribió
+ * el host: decimal, octal, mapeada en IPv6 o un dominio que apunta ahí.
+ */
+export declare function direccionInterna(ip: string): string | null;
+/**
+ * Resuelve el host y comprueba TODAS las direcciones que devuelve.
+ *
+ * Todas, no la primera: un dominio puede devolver una dirección pública y otra
+ * interna, y quedarse con una sola convierte la defensa en una moneda al aire.
+ *
+ * Un fallo de resolución NO es un permiso. Se devuelve rechazo con su motivo:
+ * «no he podido comprobarlo» y «está bien» son cosas distintas, y aquí
+ * confundirlas es abrir la puerta.
+ */
+export declare function destinoPermitido(url: URL): Promise<DestinoRechazado | null>;
+//# sourceMappingURL=destino.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"destino.d.ts","sourceRoot":"","sources":["../../../src/core/web/destino.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAIH,yEAAuE;AACvE,MAAM,WAAW,gBAAgB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,4DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAwC1D;AAED;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAwBjF","sourcesContent":["/**\n * ¿A dónde va de verdad esta URL?\n *\n * EL FALLO. `assertFetchableUrl` compara el NOMBRE del host contra una lista y\n * unas expresiones regulares. Eso para lo evidente y deja pasar todo lo que\n * llega a la misma dirección por otro camino. Medido sobre nuestra guarda:\n *\n *     http://127.0.0.1:8080/secreto          bloqueado\n *     http://localhost:8080/secreto          bloqueado\n *     http://[::1]:8080/secreto              bloqueado\n *     http://[::ffff:127.0.0.1]:8080/secreto PASA   ← IPv4 mapeada en IPv6\n *     http://localtest.me:8080/secreto       PASA   ← resuelve a 127.0.0.1\n *\n * Y había un tercero: `redirect: \"follow\"`. Una URL pública que responde 302\n * hacia loopback llega igual, porque la guarda solo mira la primera.\n *\n * Para un agente esto es serio: el modelo puede pedir una descarga con una URL\n * que parece de internet y acabar leyendo el panel de administración de la red\n * interna, o el endpoint de metadatos de la nube — que es donde viven las\n * credenciales de la máquina.\n *\n * LA CAUSA RAÍZ, y por eso este módulo existe aparte: un nombre no es un\n * destino. Lo único que dice a dónde va una petición es la DIRECCIÓN a la que\n * resuelve, así que hay que resolverla y mirarla. Las comprobaciones por nombre\n * se quedan, pero como filtro barato de primera pasada, no como la defensa.\n *\n * LO QUE NO RESUELVE, dicho antes de que lo descubra nadie: entre que\n * resolvemos y que la petición sale, el DNS puede cambiar de respuesta —el\n * ataque clásico de «rebind». Cerrarlo del todo exige fijar la dirección\n * resuelta al abrir la conexión, que es cosa del agente HTTP y no de aquí.\n * Contra un servidor hostil que controle su propio DNS esto sube el listón; no\n * lo cierra.\n */\n\nimport { lookup } from \"node:dns/promises\";\n\n/** Por qué se rechaza un destino. Nunca una lista vacía silenciosa. */\nexport interface DestinoRechazado {\n\tmotivo: string;\n\t/** La dirección concreta que lo delató, cuando la hay. */\n\tdireccion?: string;\n}\n\n/**\n * ¿Esta dirección IP es de una red que no debe alcanzarse desde una tool web?\n *\n * Se trabaja sobre la dirección ya resuelta, así que da igual cómo se escribió\n * el host: decimal, octal, mapeada en IPv6 o un dominio que apunta ahí.\n */\nexport function direccionInterna(ip: string): string | null {\n\tconst limpia = ip.toLowerCase().replace(/^\\[|\\]$/g, \"\");\n\n\t// IPv4 mapeada en IPv6: se desenvuelve y se juzga como IPv4, que es lo que\n\t// era. Sin esto, `[::ffff:127.0.0.1]` pasaba entera.\n\t//\n\t// Hay que cubrir LAS DOS FORMAS, y esto casi se me escapa: `new URL()`\n\t// normaliza `[::ffff:127.0.0.1]` a `[::ffff:7f00:1]`, en hexadecimal. Una\n\t// guarda que solo mirara la forma decimal daría verde sobre la única forma\n\t// que llega de verdad desde una URL.\n\tlet dir = limpia;\n\tconst decimal = limpia.match(/^::ffff:(\\d+\\.\\d+\\.\\d+\\.\\d+)$/);\n\tif (decimal) {\n\t\tdir = decimal[1];\n\t} else {\n\t\tconst hex = limpia.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);\n\t\tif (hex) {\n\t\t\tconst alto = Number.parseInt(hex[1], 16);\n\t\t\tconst bajo = Number.parseInt(hex[2], 16);\n\t\t\tdir = `${alto >> 8}.${alto & 0xff}.${bajo >> 8}.${bajo & 0xff}`;\n\t\t}\n\t}\n\n\tif (/^\\d+\\.\\d+\\.\\d+\\.\\d+$/.test(dir)) {\n\t\tconst [a, b] = dir.split(\".\").map(Number);\n\t\tif (a === 127) return \"loopback\";\n\t\tif (a === 10) return \"red privada (10/8)\";\n\t\tif (a === 172 && b >= 16 && b <= 31) return \"red privada (172.16/12)\";\n\t\tif (a === 192 && b === 168) return \"red privada (192.168/16)\";\n\t\tif (a === 169 && b === 254) return \"enlace local (169.254/16), donde vive el endpoint de metadatos\";\n\t\tif (a === 100 && b >= 64 && b <= 127) return \"CGNAT (100.64/10)\";\n\t\tif (a === 0) return \"esta red (0/8)\";\n\t\treturn null;\n\t}\n\n\tif (dir === \"::1\" || dir === \"::\") return \"loopback IPv6\";\n\t// `fc00::/7` son las direcciones únicas locales; `fe80::/10`, el enlace local.\n\tif (/^f[cd]/.test(dir)) return \"red privada IPv6 (fc00::/7)\";\n\tif (/^fe[89ab]/.test(dir)) return \"enlace local IPv6 (fe80::/10)\";\n\treturn null;\n}\n\n/**\n * Resuelve el host y comprueba TODAS las direcciones que devuelve.\n *\n * Todas, no la primera: un dominio puede devolver una dirección pública y otra\n * interna, y quedarse con una sola convierte la defensa en una moneda al aire.\n *\n * Un fallo de resolución NO es un permiso. Se devuelve rechazo con su motivo:\n * «no he podido comprobarlo» y «está bien» son cosas distintas, y aquí\n * confundirlas es abrir la puerta.\n */\nexport async function destinoPermitido(url: URL): Promise<DestinoRechazado | null> {\n\tconst host = url.hostname.toLowerCase().replace(/^\\[|\\]$/g, \"\");\n\n\t// Si el host YA es una dirección, no hay nada que resolver.\n\tconst directa = direccionInterna(host);\n\tif (directa) return { motivo: directa, direccion: host };\n\tif (/^[\\d.]+$/.test(host) || host.includes(\":\")) return null;\n\n\tlet direcciones: Array<{ address: string }>;\n\ttry {\n\t\tdirecciones = await lookup(host, { all: true });\n\t} catch (error) {\n\t\treturn {\n\t\t\tmotivo: `no se ha podido resolver el nombre (${(error as NodeJS.ErrnoException).code ?? \"error\"}), y sin saber a dónde apunta no se descarga`,\n\t\t};\n\t}\n\tif (direcciones.length === 0) {\n\t\treturn { motivo: \"el nombre no resuelve a ninguna dirección\" };\n\t}\n\tfor (const { address } of direcciones) {\n\t\tconst que = direccionInterna(address);\n\t\tif (que) return { motivo: `el nombre resuelve a ${que}`, direccion: address };\n\t}\n\treturn null;\n}\n"]}

package/dist/core/web/destino.js

@@ -0,0 +1,127 @@
+/**
+ * ¿A dónde va de verdad esta URL?
+ *
+ * EL FALLO. `assertFetchableUrl` compara el NOMBRE del host contra una lista y
+ * unas expresiones regulares. Eso para lo evidente y deja pasar todo lo que
+ * llega a la misma dirección por otro camino. Medido sobre nuestra guarda:
+ *
+ *     http://127.0.0.1:8080/secreto          bloqueado
+ *     http://localhost:8080/secreto          bloqueado
+ *     http://[::1]:8080/secreto              bloqueado
+ *     http://[::ffff:127.0.0.1]:8080/secreto PASA   ← IPv4 mapeada en IPv6
+ *     http://localtest.me:8080/secreto       PASA   ← resuelve a 127.0.0.1
+ *
+ * Y había un tercero: `redirect: "follow"`. Una URL pública que responde 302
+ * hacia loopback llega igual, porque la guarda solo mira la primera.
+ *
+ * Para un agente esto es serio: el modelo puede pedir una descarga con una URL
+ * que parece de internet y acabar leyendo el panel de administración de la red
+ * interna, o el endpoint de metadatos de la nube — que es donde viven las
+ * credenciales de la máquina.
+ *
+ * LA CAUSA RAÍZ, y por eso este módulo existe aparte: un nombre no es un
+ * destino. Lo único que dice a dónde va una petición es la DIRECCIÓN a la que
+ * resuelve, así que hay que resolverla y mirarla. Las comprobaciones por nombre
+ * se quedan, pero como filtro barato de primera pasada, no como la defensa.
+ *
+ * LO QUE NO RESUELVE, dicho antes de que lo descubra nadie: entre que
+ * resolvemos y que la petición sale, el DNS puede cambiar de respuesta —el
+ * ataque clásico de «rebind». Cerrarlo del todo exige fijar la dirección
+ * resuelta al abrir la conexión, que es cosa del agente HTTP y no de aquí.
+ * Contra un servidor hostil que controle su propio DNS esto sube el listón; no
+ * lo cierra.
+ */
+import { lookup } from "node:dns/promises";
+/**
+ * ¿Esta dirección IP es de una red que no debe alcanzarse desde una tool web?
+ *
+ * Se trabaja sobre la dirección ya resuelta, así que da igual cómo se escribió
+ * el host: decimal, octal, mapeada en IPv6 o un dominio que apunta ahí.
+ */
+export function direccionInterna(ip) {
+    const limpia = ip.toLowerCase().replace(/^\[|\]$/g, "");
+    // IPv4 mapeada en IPv6: se desenvuelve y se juzga como IPv4, que es lo que
+    // era. Sin esto, `[::ffff:127.0.0.1]` pasaba entera.
+    //
+    // Hay que cubrir LAS DOS FORMAS, y esto casi se me escapa: `new URL()`
+    // normaliza `[::ffff:127.0.0.1]` a `[::ffff:7f00:1]`, en hexadecimal. Una
+    // guarda que solo mirara la forma decimal daría verde sobre la única forma
+    // que llega de verdad desde una URL.
+    let dir = limpia;
+    const decimal = limpia.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+    if (decimal) {
+        dir = decimal[1];
+    }
+    else {
+        const hex = limpia.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+        if (hex) {
+            const alto = Number.parseInt(hex[1], 16);
+            const bajo = Number.parseInt(hex[2], 16);
+            dir = `${alto >> 8}.${alto & 0xff}.${bajo >> 8}.${bajo & 0xff}`;
+        }
+    }
+    if (/^\d+\.\d+\.\d+\.\d+$/.test(dir)) {
+        const [a, b] = dir.split(".").map(Number);
+        if (a === 127)
+            return "loopback";
+        if (a === 10)
+            return "red privada (10/8)";
+        if (a === 172 && b >= 16 && b <= 31)
+            return "red privada (172.16/12)";
+        if (a === 192 && b === 168)
+            return "red privada (192.168/16)";
+        if (a === 169 && b === 254)
+            return "enlace local (169.254/16), donde vive el endpoint de metadatos";
+        if (a === 100 && b >= 64 && b <= 127)
+            return "CGNAT (100.64/10)";
+        if (a === 0)
+            return "esta red (0/8)";
+        return null;
+    }
+    if (dir === "::1" || dir === "::")
+        return "loopback IPv6";
+    // `fc00::/7` son las direcciones únicas locales; `fe80::/10`, el enlace local.
+    if (/^f[cd]/.test(dir))
+        return "red privada IPv6 (fc00::/7)";
+    if (/^fe[89ab]/.test(dir))
+        return "enlace local IPv6 (fe80::/10)";
+    return null;
+}
+/**
+ * Resuelve el host y comprueba TODAS las direcciones que devuelve.
+ *
+ * Todas, no la primera: un dominio puede devolver una dirección pública y otra
+ * interna, y quedarse con una sola convierte la defensa en una moneda al aire.
+ *
+ * Un fallo de resolución NO es un permiso. Se devuelve rechazo con su motivo:
+ * «no he podido comprobarlo» y «está bien» son cosas distintas, y aquí
+ * confundirlas es abrir la puerta.
+ */
+export async function destinoPermitido(url) {
+    const host = url.hostname.toLowerCase().replace(/^\[|\]$/g, "");
+    // Si el host YA es una dirección, no hay nada que resolver.
+    const directa = direccionInterna(host);
+    if (directa)
+        return { motivo: directa, direccion: host };
+    if (/^[\d.]+$/.test(host) || host.includes(":"))
+        return null;
+    let direcciones;
+    try {
+        direcciones = await lookup(host, { all: true });
+    }
+    catch (error) {
+        return {
+            motivo: `no se ha podido resolver el nombre (${error.code ?? "error"}), y sin saber a dónde apunta no se descarga`,
+        };
+    }
+    if (direcciones.length === 0) {
+        return { motivo: "el nombre no resuelve a ninguna dirección" };
+    }
+    for (const { address } of direcciones) {
+        const que = direccionInterna(address);
+        if (que)
+            return { motivo: `el nombre resuelve a ${que}`, direccion: address };
+    }
+    return null;
+}
+//# sourceMappingURL=destino.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"destino.js","sourceRoot":"","sources":["../../../src/core/web/destino.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * ¿A dónde va de verdad esta URL?\n *\n * EL FALLO. `assertFetchableUrl` compara el NOMBRE del host contra una lista y\n * unas expresiones regulares. Eso para lo evidente y deja pasar todo lo que\n * llega a la misma dirección por otro camino. Medido sobre nuestra guarda:\n *\n *     http://127.0.0.1:8080/secreto          bloqueado\n *     http://localhost:8080/secreto          bloqueado\n *     http://[::1]:8080/secreto              bloqueado\n *     http://[::ffff:127.0.0.1]:8080/secreto PASA   ← IPv4 mapeada en IPv6\n *     http://localtest.me:8080/secreto       PASA   ← resuelve a 127.0.0.1\n *\n * Y había un tercero: `redirect: \"follow\"`. Una URL pública que responde 302\n * hacia loopback llega igual, porque la guarda solo mira la primera.\n *\n * Para un agente esto es serio: el modelo puede pedir una descarga con una URL\n * que parece de internet y acabar leyendo el panel de administración de la red\n * interna, o el endpoint de metadatos de la nube — que es donde viven las\n * credenciales de la máquina.\n *\n * LA CAUSA RAÍZ, y por eso este módulo existe aparte: un nombre no es un\n * destino. Lo único que dice a dónde va una petición es la DIRECCIÓN a la que\n * resuelve, así que hay que resolverla y mirarla. Las comprobaciones por nombre\n * se quedan, pero como filtro barato de primera pasada, no como la defensa.\n *\n * LO QUE NO RESUELVE, dicho antes de que lo descubra nadie: entre que\n * resolvemos y que la petición sale, el DNS puede cambiar de respuesta —el\n * ataque clásico de «rebind». Cerrarlo del todo exige fijar la dirección\n * resuelta al abrir la conexión, que es cosa del agente HTTP y no de aquí.\n * Contra un servidor hostil que controle su propio DNS esto sube el listón; no\n * lo cierra.\n */\n\nimport { lookup } from \"node:dns/promises\";\n\n/** Por qué se rechaza un destino. Nunca una lista vacía silenciosa. */\nexport interface DestinoRechazado {\n\tmotivo: string;\n\t/** La dirección concreta que lo delató, cuando la hay. */\n\tdireccion?: string;\n}\n\n/**\n * ¿Esta dirección IP es de una red que no debe alcanzarse desde una tool web?\n *\n * Se trabaja sobre la dirección ya resuelta, así que da igual cómo se escribió\n * el host: decimal, octal, mapeada en IPv6 o un dominio que apunta ahí.\n */\nexport function direccionInterna(ip: string): string | null {\n\tconst limpia = ip.toLowerCase().replace(/^\\[|\\]$/g, \"\");\n\n\t// IPv4 mapeada en IPv6: se desenvuelve y se juzga como IPv4, que es lo que\n\t// era. Sin esto, `[::ffff:127.0.0.1]` pasaba entera.\n\t//\n\t// Hay que cubrir LAS DOS FORMAS, y esto casi se me escapa: `new URL()`\n\t// normaliza `[::ffff:127.0.0.1]` a `[::ffff:7f00:1]`, en hexadecimal. Una\n\t// guarda que solo mirara la forma decimal daría verde sobre la única forma\n\t// que llega de verdad desde una URL.\n\tlet dir = limpia;\n\tconst decimal = limpia.match(/^::ffff:(\\d+\\.\\d+\\.\\d+\\.\\d+)$/);\n\tif (decimal) {\n\t\tdir = decimal[1];\n\t} else {\n\t\tconst hex = limpia.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);\n\t\tif (hex) {\n\t\t\tconst alto = Number.parseInt(hex[1], 16);\n\t\t\tconst bajo = Number.parseInt(hex[2], 16);\n\t\t\tdir = `${alto >> 8}.${alto & 0xff}.${bajo >> 8}.${bajo & 0xff}`;\n\t\t}\n\t}\n\n\tif (/^\\d+\\.\\d+\\.\\d+\\.\\d+$/.test(dir)) {\n\t\tconst [a, b] = dir.split(\".\").map(Number);\n\t\tif (a === 127) return \"loopback\";\n\t\tif (a === 10) return \"red privada (10/8)\";\n\t\tif (a === 172 && b >= 16 && b <= 31) return \"red privada (172.16/12)\";\n\t\tif (a === 192 && b === 168) return \"red privada (192.168/16)\";\n\t\tif (a === 169 && b === 254) return \"enlace local (169.254/16), donde vive el endpoint de metadatos\";\n\t\tif (a === 100 && b >= 64 && b <= 127) return \"CGNAT (100.64/10)\";\n\t\tif (a === 0) return \"esta red (0/8)\";\n\t\treturn null;\n\t}\n\n\tif (dir === \"::1\" || dir === \"::\") return \"loopback IPv6\";\n\t// `fc00::/7` son las direcciones únicas locales; `fe80::/10`, el enlace local.\n\tif (/^f[cd]/.test(dir)) return \"red privada IPv6 (fc00::/7)\";\n\tif (/^fe[89ab]/.test(dir)) return \"enlace local IPv6 (fe80::/10)\";\n\treturn null;\n}\n\n/**\n * Resuelve el host y comprueba TODAS las direcciones que devuelve.\n *\n * Todas, no la primera: un dominio puede devolver una dirección pública y otra\n * interna, y quedarse con una sola convierte la defensa en una moneda al aire.\n *\n * Un fallo de resolución NO es un permiso. Se devuelve rechazo con su motivo:\n * «no he podido comprobarlo» y «está bien» son cosas distintas, y aquí\n * confundirlas es abrir la puerta.\n */\nexport async function destinoPermitido(url: URL): Promise<DestinoRechazado | null> {\n\tconst host = url.hostname.toLowerCase().replace(/^\\[|\\]$/g, \"\");\n\n\t// Si el host YA es una dirección, no hay nada que resolver.\n\tconst directa = direccionInterna(host);\n\tif (directa) return { motivo: directa, direccion: host };\n\tif (/^[\\d.]+$/.test(host) || host.includes(\":\")) return null;\n\n\tlet direcciones: Array<{ address: string }>;\n\ttry {\n\t\tdirecciones = await lookup(host, { all: true });\n\t} catch (error) {\n\t\treturn {\n\t\t\tmotivo: `no se ha podido resolver el nombre (${(error as NodeJS.ErrnoException).code ?? \"error\"}), y sin saber a dónde apunta no se descarga`,\n\t\t};\n\t}\n\tif (direcciones.length === 0) {\n\t\treturn { motivo: \"el nombre no resuelve a ninguna dirección\" };\n\t}\n\tfor (const { address } of direcciones) {\n\t\tconst que = direccionInterna(address);\n\t\tif (que) return { motivo: `el nombre resuelve a ${que}`, direccion: address };\n\t}\n\treturn null;\n}\n"]}

package/dist/core/web/proveedores/brave.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Brave Search API. Requiere clave (`brave` en el vault, o BRAVE_API_KEY).
+ */
+import type { FuncionBuscar } from "./tipos.ts";
+export declare const buscar: FuncionBuscar;
+//# sourceMappingURL=brave.d.ts.map

package/dist/core/web/proveedores/brave.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brave.d.ts","sourceRoot":"","sources":["../../../../src/core/web/proveedores/brave.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,aAAa,EAAsB,MAAM,YAAY,CAAC;AAQpE,eAAO,MAAM,MAAM,EAAE,aAepB,CAAC","sourcesContent":["/**\n * Brave Search API. Requiere clave (`brave` en el vault, o BRAVE_API_KEY).\n */\nimport type { FuncionBuscar, ResultadoProveedor } from \"./tipos.ts\";\n\nconst ENDPOINT = \"https://api.search.brave.com/res/v1/web/search\";\n\ninterface RespuestaBrave {\n\tweb?: { results?: Array<{ title?: string; url?: string; description?: string }> };\n}\n\nexport const buscar: FuncionBuscar = async (consulta, maximo, clave, fetchImpl, signal) => {\n\tif (!clave) throw new Error(\"Brave requiere clave.\");\n\tconst url = new URL(ENDPOINT);\n\turl.searchParams.set(\"q\", consulta);\n\turl.searchParams.set(\"count\", String(Math.min(Math.max(maximo, 1), 20)));\n\tconst respuesta = await fetchImpl(url, {\n\t\theaders: { Accept: \"application/json\", \"X-Subscription-Token\": clave },\n\t\tsignal,\n\t});\n\tif (!respuesta.ok) throw new Error(`Brave respondió HTTP ${respuesta.status}.`);\n\tconst datos = (await respuesta.json()) as RespuestaBrave;\n\tconst resultados: ResultadoProveedor[] = (datos.web?.results ?? [])\n\t\t.filter((r) => typeof r.url === \"string\" && r.url)\n\t\t.map((r) => ({ titulo: r.title || r.url!, url: r.url!, resumen: r.description }));\n\treturn resultados.slice(0, maximo);\n};\n"]}

package/dist/core/web/proveedores/brave.js

@@ -0,0 +1,20 @@
+const ENDPOINT = "https://api.search.brave.com/res/v1/web/search";
+export const buscar = async (consulta, maximo, clave, fetchImpl, signal) => {
+    if (!clave)
+        throw new Error("Brave requiere clave.");
+    const url = new URL(ENDPOINT);
+    url.searchParams.set("q", consulta);
+    url.searchParams.set("count", String(Math.min(Math.max(maximo, 1), 20)));
+    const respuesta = await fetchImpl(url, {
+        headers: { Accept: "application/json", "X-Subscription-Token": clave },
+        signal,
+    });
+    if (!respuesta.ok)
+        throw new Error(`Brave respondió HTTP ${respuesta.status}.`);
+    const datos = (await respuesta.json());
+    const resultados = (datos.web?.results ?? [])
+        .filter((r) => typeof r.url === "string" && r.url)
+        .map((r) => ({ titulo: r.title || r.url, url: r.url, resumen: r.description }));
+    return resultados.slice(0, maximo);
+};
+//# sourceMappingURL=brave.js.map

package/dist/core/web/proveedores/brave.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"brave.js","sourceRoot":"","sources":["../../../../src/core/web/proveedores/brave.ts"],"names":[],"mappings":"AAKA,MAAM,QAAQ,GAAG,gDAAgD,CAAC;AAMlE,MAAM,CAAC,MAAM,MAAM,GAAkB,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,CAAC;IAC1F,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,uBAAuB,CAAC,CAAC;IACrD,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC9B,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IACpC,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;IACzE,MAAM,SAAS,GAAG,MAAM,SAAS,CAAC,GAAG,EAAE;QACtC,OAAO,EAAE,EAAE,MAAM,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,KAAK,EAAE;QACtE,MAAM;KACN,CAAC,CAAC;IACH,IAAI,CAAC,SAAS,CAAC,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,yBAAwB,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC;IAChF,MAAM,KAAK,GAAG,CAAC,MAAM,SAAS,CAAC,IAAI,EAAE,CAAmB,CAAC;IACzD,MAAM,UAAU,GAAyB,CAAC,KAAK,CAAC,GAAG,EAAE,OAAO,IAAI,EAAE,CAAC;SACjE,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,GAAG,KAAK,QAAQ,IAAI,CAAC,CAAC,GAAG,CAAC;SACjD,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,GAAI,EAAE,GAAG,EAAE,CAAC,CAAC,GAAI,EAAE,OAAO,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;IACnF,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;AAAA,CACnC,CAAC","sourcesContent":["/**\n * Brave Search API. Requiere clave (`brave` en el vault, o BRAVE_API_KEY).\n */\nimport type { FuncionBuscar, ResultadoProveedor } from \"./tipos.ts\";\n\nconst ENDPOINT = \"https://api.search.brave.com/res/v1/web/search\";\n\ninterface RespuestaBrave {\n\tweb?: { results?: Array<{ title?: string; url?: string; description?: string }> };\n}\n\nexport const buscar: FuncionBuscar = async (consulta, maximo, clave, fetchImpl, signal) => {\n\tif (!clave) throw new Error(\"Brave requiere clave.\");\n\tconst url = new URL(ENDPOINT);\n\turl.searchParams.set(\"q\", consulta);\n\turl.searchParams.set(\"count\", String(Math.min(Math.max(maximo, 1), 20)));\n\tconst respuesta = await fetchImpl(url, {\n\t\theaders: { Accept: \"application/json\", \"X-Subscription-Token\": clave },\n\t\tsignal,\n\t});\n\tif (!respuesta.ok) throw new Error(`Brave respondió HTTP ${respuesta.status}.`);\n\tconst datos = (await respuesta.json()) as RespuestaBrave;\n\tconst resultados: ResultadoProveedor[] = (datos.web?.results ?? [])\n\t\t.filter((r) => typeof r.url === \"string\" && r.url)\n\t\t.map((r) => ({ titulo: r.title || r.url!, url: r.url!, resumen: r.description }));\n\treturn resultados.slice(0, maximo);\n};\n"]}

package/dist/core/web/proveedores/claves.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Resuelve la clave de un proveedor de búsqueda: vault primero, variable de
+ * entorno después (la que usa CI, donde no hay vault desbloqueado).
+ *
+ * Vive separado del registro para que `agent-session.ts` —de upstream, con el
+ * presupuesto de sincronización agotado— pueda enchufarlo con una sola
+ * llamada en vez de repetir aquí la lógica try/vault/env por cada proveedor.
+ */
+/** Lo mínimo que hace falta del vault: buscar un secreto por nombre. */
+export interface FuenteDeVault {
+    getSecret(nombre: string): string | null | undefined;
+}
+/**
+ * Construye el `obtenerClave` que espera `createWebTools`, atado a un vault
+ * concreto. `obtenerVault` se llama en cada búsqueda, no una vez: el vault
+ * puede desbloquearse o bloquearse durante la sesión.
+ */
+export declare function crearObtenerClave(obtenerVault: () => FuenteDeVault | null | undefined): (nombreProveedor: string) => Promise<string | undefined>;
+//# sourceMappingURL=claves.d.ts.map

package/dist/core/web/proveedores/claves.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claves.d.ts","sourceRoot":"","sources":["../../../../src/core/web/proveedores/claves.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAWH,yEAAwE;AACxE,MAAM,WAAW,aAAa;IAC7B,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;CACrD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAChC,YAAY,EAAE,MAAM,aAAa,GAAG,IAAI,GAAG,SAAS,GAClD,CAAC,eAAe,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAW1D","sourcesContent":["/**\n * Resuelve la clave de un proveedor de búsqueda: vault primero, variable de\n * entorno después (la que usa CI, donde no hay vault desbloqueado).\n *\n * Vive separado del registro para que `agent-session.ts` —de upstream, con el\n * presupuesto de sincronización agotado— pueda enchufarlo con una sola\n * llamada en vez de repetir aquí la lógica try/vault/env por cada proveedor.\n */\n\n/** Nombre de proveedor → variable de entorno donde puede vivir su clave. */\nconst VARIABLE_ENTORNO: Record<string, string> = {\n\tserper: \"SERPER_API_KEY\",\n\tbrave: \"BRAVE_API_KEY\",\n\ttavily: \"TAVILY_API_KEY\",\n\texa: \"EXA_API_KEY\",\n\tsearxng: \"SEARXNG_URL\",\n};\n\n/** Lo mínimo que hace falta del vault: buscar un secreto por nombre. */\nexport interface FuenteDeVault {\n\tgetSecret(nombre: string): string | null | undefined;\n}\n\n/**\n * Construye el `obtenerClave` que espera `createWebTools`, atado a un vault\n * concreto. `obtenerVault` se llama en cada búsqueda, no una vez: el vault\n * puede desbloquearse o bloquearse durante la sesión.\n */\nexport function crearObtenerClave(\n\tobtenerVault: () => FuenteDeVault | null | undefined,\n): (nombreProveedor: string) => Promise<string | undefined> {\n\treturn async (nombreProveedor: string) => {\n\t\tconst variable = VARIABLE_ENTORNO[nombreProveedor];\n\t\ttry {\n\t\t\tconst delVault = obtenerVault()?.getSecret(nombreProveedor);\n\t\t\tif (delVault) return delVault;\n\t\t} catch {\n\t\t\t// Vault bloqueado o no inicializado: caer a la variable de entorno.\n\t\t}\n\t\treturn variable ? process.env[variable] : undefined;\n\t};\n}\n"]}

package/dist/core/web/proveedores/claves.js

@@ -0,0 +1,36 @@
+/**
+ * Resuelve la clave de un proveedor de búsqueda: vault primero, variable de
+ * entorno después (la que usa CI, donde no hay vault desbloqueado).
+ *
+ * Vive separado del registro para que `agent-session.ts` —de upstream, con el
+ * presupuesto de sincronización agotado— pueda enchufarlo con una sola
+ * llamada en vez de repetir aquí la lógica try/vault/env por cada proveedor.
+ */
+/** Nombre de proveedor → variable de entorno donde puede vivir su clave. */
+const VARIABLE_ENTORNO = {
+    serper: "SERPER_API_KEY",
+    brave: "BRAVE_API_KEY",
+    tavily: "TAVILY_API_KEY",
+    exa: "EXA_API_KEY",
+    searxng: "SEARXNG_URL",
+};
+/**
+ * Construye el `obtenerClave` que espera `createWebTools`, atado a un vault
+ * concreto. `obtenerVault` se llama en cada búsqueda, no una vez: el vault
+ * puede desbloquearse o bloquearse durante la sesión.
+ */
+export function crearObtenerClave(obtenerVault) {
+    return async (nombreProveedor) => {
+        const variable = VARIABLE_ENTORNO[nombreProveedor];
+        try {
+            const delVault = obtenerVault()?.getSecret(nombreProveedor);
+            if (delVault)
+                return delVault;
+        }
+        catch {
+            // Vault bloqueado o no inicializado: caer a la variable de entorno.
+        }
+        return variable ? process.env[variable] : undefined;
+    };
+}
+//# sourceMappingURL=claves.js.map

package/dist/core/web/proveedores/claves.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claves.js","sourceRoot":"","sources":["../../../../src/core/web/proveedores/claves.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,8EAA4E;AAC5E,MAAM,gBAAgB,GAA2B;IAChD,MAAM,EAAE,gBAAgB;IACxB,KAAK,EAAE,eAAe;IACtB,MAAM,EAAE,gBAAgB;IACxB,GAAG,EAAE,aAAa;IAClB,OAAO,EAAE,aAAa;CACtB,CAAC;AAOF;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAChC,YAAoD,EACO;IAC3D,OAAO,KAAK,EAAE,eAAuB,EAAE,EAAE,CAAC;QACzC,MAAM,QAAQ,GAAG,gBAAgB,CAAC,eAAe,CAAC,CAAC;QACnD,IAAI,CAAC;YACJ,MAAM,QAAQ,GAAG,YAAY,EAAE,EAAE,SAAS,CAAC,eAAe,CAAC,CAAC;YAC5D,IAAI,QAAQ;gBAAE,OAAO,QAAQ,CAAC;QAC/B,CAAC;QAAC,MAAM,CAAC;YACR,oEAAoE;QACrE,CAAC;QACD,OAAO,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAAA,CACpD,CAAC;AAAA,CACF","sourcesContent":["/**\n * Resuelve la clave de un proveedor de búsqueda: vault primero, variable de\n * entorno después (la que usa CI, donde no hay vault desbloqueado).\n *\n * Vive separado del registro para que `agent-session.ts` —de upstream, con el\n * presupuesto de sincronización agotado— pueda enchufarlo con una sola\n * llamada en vez de repetir aquí la lógica try/vault/env por cada proveedor.\n */\n\n/** Nombre de proveedor → variable de entorno donde puede vivir su clave. */\nconst VARIABLE_ENTORNO: Record<string, string> = {\n\tserper: \"SERPER_API_KEY\",\n\tbrave: \"BRAVE_API_KEY\",\n\ttavily: \"TAVILY_API_KEY\",\n\texa: \"EXA_API_KEY\",\n\tsearxng: \"SEARXNG_URL\",\n};\n\n/** Lo mínimo que hace falta del vault: buscar un secreto por nombre. */\nexport interface FuenteDeVault {\n\tgetSecret(nombre: string): string | null | undefined;\n}\n\n/**\n * Construye el `obtenerClave` que espera `createWebTools`, atado a un vault\n * concreto. `obtenerVault` se llama en cada búsqueda, no una vez: el vault\n * puede desbloquearse o bloquearse durante la sesión.\n */\nexport function crearObtenerClave(\n\tobtenerVault: () => FuenteDeVault | null | undefined,\n): (nombreProveedor: string) => Promise<string | undefined> {\n\treturn async (nombreProveedor: string) => {\n\t\tconst variable = VARIABLE_ENTORNO[nombreProveedor];\n\t\ttry {\n\t\t\tconst delVault = obtenerVault()?.getSecret(nombreProveedor);\n\t\t\tif (delVault) return delVault;\n\t\t} catch {\n\t\t\t// Vault bloqueado o no inicializado: caer a la variable de entorno.\n\t\t}\n\t\treturn variable ? process.env[variable] : undefined;\n\t};\n}\n"]}

package/dist/core/web/proveedores/duckduckgo.d.ts

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

package/dist/core/web/proveedores/duckduckgo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"duckduckgo.d.ts","sourceRoot":"","sources":["../../../../src/core/web/proveedores/duckduckgo.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,aAAa,EAAsB,MAAM,YAAY,CAAC;AA8EpE,eAAO,MAAM,MAAM,EAAE,aAepB,CAAC","sourcesContent":["/**\n * DuckDuckGo, vía su frontend HTML sin JS (`html.duckduckgo.com/html/`).\n *\n * Sin clave: es el único de los tres proveedores gratuitos que responde con\n * resultados reales desde una red de centro de datos en la práctica —Mojeek y\n * Ecosia sirven un captcha o un firewall a cualquier cliente sin navegador\n * real la mayoría de las veces—. Por eso va primero en el grupo sin clave: es\n * el que de verdad sostiene la puerta «sin ninguna clave, hay resultados».\n *\n * DuckDuckGo enruta cada resultado por `//duckduckgo.com/l/?uddg=<url>` para\n * medir clics; hay que desenvolverlo o el agente termina con enlaces inútiles.\n */\nimport { CABECERAS_NAVEGADOR } from \"./navegador.ts\";\nimport type { FuncionBuscar, ResultadoProveedor } from \"./tipos.ts\";\n\nconst ENDPOINT = \"https://html.duckduckgo.com/html/\";\n\n/** `true` cuando la página es el modal anti-bot, no resultados. DDG mezcla 200 y 202 en este caso. */\nfunction esBloqueoAntiBot(html: string): boolean {\n\treturn html.includes(\"anomaly-modal\") || html.includes(\"anomaly.js\");\n}\n\n/**\n * Desenvuelve la URL real de un resultado. Los orgánicos van envueltos en\n * `uddg=`; los ANUNCIOS (`//duckduckgo.com/y.js?ad_domain=…`) no llevan ese\n * envoltorio porque no apuntan a un destino final, sino al propio tracker de\n * clics de DDG — por eso, tras desenvolver, cualquier URL que SIGA en\n * duckduckgo.com se descarta: es un anuncio, no un resultado.\n */\nfunction desenvolverUrl(href: string): string | undefined {\n\tconst decodificado = href.replace(/&amp;/gi, \"&\");\n\tlet resuelta: string | undefined;\n\tconst match = decodificado.match(/[?&]uddg=([^&]+)/);\n\tif (match) {\n\t\ttry {\n\t\t\tresuelta = decodeURIComponent(match[1]);\n\t\t} catch {\n\t\t\treturn undefined;\n\t\t}\n\t} else if (decodificado.startsWith(\"//\")) {\n\t\tresuelta = `https:${decodificado}`;\n\t} else if (decodificado.startsWith(\"http://\") || decodificado.startsWith(\"https://\")) {\n\t\tresuelta = decodificado;\n\t} else {\n\t\treturn undefined;\n\t}\n\ttry {\n\t\tif (new URL(resuelta).hostname.endsWith(\"duckduckgo.com\")) return undefined;\n\t} catch {\n\t\treturn undefined;\n\t}\n\treturn resuelta;\n}\n\nfunction limpiarTexto(html: string): string {\n\treturn html\n\t\t.replace(/<[^>]*>/g, \" \")\n\t\t.replace(/&amp;/gi, \"&\")\n\t\t.replace(/&lt;/gi, \"<\")\n\t\t.replace(/&gt;/gi, \">\")\n\t\t.replace(/&quot;/gi, '\"')\n\t\t.replace(/&#39;|&apos;/gi, \"'\")\n\t\t.replace(/&nbsp;/gi, \" \")\n\t\t.replace(/\\s+/g, \" \")\n\t\t.trim();\n}\n\nconst RE_BLOQUE =\n\t/<div\\b[^>]*\\bclass=\"[^\"]*\\bresult\\b[^\"]*\"[^>]*>([\\s\\S]*?)(?=<div\\b[^>]*\\bclass=\"[^\"]*\\bresult\\b|<div\\b[^>]*\\bclass=\"[^\"]*\\bnav-link\\b|$)/g;\nconst RE_TITULO = /<a\\b[^>]*\\bclass=\"[^\"]*\\bresult__a\\b[^\"]*\"[^>]*\\bhref=\"([^\"]+)\"[^>]*>([\\s\\S]*?)<\\/a>/;\nconst RE_SNIPPET = /<(?:a|div|span)\\b[^>]*\\bclass=\"[^\"]*\\bresult__snippet\\b[^\"]*\"[^>]*>([\\s\\S]*?)<\\/(?:a|div|span)>/;\n\nfunction parsear(html: string): ResultadoProveedor[] {\n\tconst resultados: ResultadoProveedor[] = [];\n\tfor (const bloque of html.matchAll(RE_BLOQUE)) {\n\t\tconst titulo = bloque[1].match(RE_TITULO);\n\t\tif (!titulo) continue;\n\t\tconst url = desenvolverUrl(titulo[1]);\n\t\tif (!url) continue;\n\t\tconst tituloTexto = limpiarTexto(titulo[2]);\n\t\tif (!tituloTexto) continue;\n\t\tconst snippet = bloque[1].match(RE_SNIPPET);\n\t\tresultados.push({\n\t\t\ttitulo: tituloTexto,\n\t\t\turl,\n\t\t\tresumen: snippet ? limpiarTexto(snippet[1]) || undefined : undefined,\n\t\t});\n\t}\n\treturn resultados;\n}\n\nexport const buscar: FuncionBuscar = async (consulta, maximo, _clave, fetchImpl, signal) => {\n\t// GET, no POST: probado en vivo contra `html.duckduckgo.com` — el mismo\n\t// endpoint trata el POST (el envío \"de formulario real\" que usan otros\n\t// scrapers) con más sospecha que un GET con la consulta en la query, al\n\t// menos desde redes de centro de datos. Con GET responde con resultados\n\t// reales de forma consistente; con POST, con el modal anti-bot.\n\tconst url = new URL(ENDPOINT);\n\turl.searchParams.set(\"q\", consulta);\n\tconst respuesta = await fetchImpl(url, { headers: CABECERAS_NAVEGADOR, signal });\n\tif (!respuesta.ok) throw new Error(`DuckDuckGo respondió HTTP ${respuesta.status}.`);\n\tconst html = await respuesta.text();\n\tif (esBloqueoAntiBot(html)) {\n\t\tthrow new Error(\"DuckDuckGo bloqueó la petición con su captcha anti-bot.\");\n\t}\n\treturn parsear(html).slice(0, maximo);\n};\n"]}