@hoilab/ada-cli 0.84.21 → 0.85.0

package/dist/core/usage/cuota/openai-codex.js

@@ -0,0 +1,59 @@
+/**
+ * Cuota de OpenAI Codex (ChatGPT) — endpoint interno de cuenta, no la API de
+ * pago por token. Vive en `chatgpt.com`, no en `api.openai.com`: no hay
+ * override de `baseUrl` que valga aquí, un proxy de streaming lo devolvería
+ * en 404.
+ */
+import { ErrorConsultaCuota } from "./tipos.js";
+const ENDPOINT = "https://chatgpt.com/backend-api/wham/usage";
+function aVentana(etiqueta, cubo) {
+    if (!cubo || typeof cubo.used_percent !== "number")
+        return undefined;
+    const seReinicia = typeof cubo.reset_at === "number" && cubo.reset_at > 0 ? cubo.reset_at * 1000 : null;
+    return {
+        etiqueta,
+        usado: Math.min(Math.max(cubo.used_percent, 0), 100),
+        limite: 100,
+        seReinicia,
+        unidad: "porcentaje",
+    };
+}
+export const consultorOpenAiCodex = {
+    id: "openai-codex",
+    soporta: (credencial) => credencial.type === "oauth",
+    async consultar({ credencial, fetch: fetchImpl = fetch, señal }) {
+        if (credencial.type !== "oauth")
+            return null;
+        const headers = { authorization: `Bearer ${credencial.access}` };
+        const accountId = credencial.accountId;
+        if (typeof accountId === "string" && accountId)
+            headers["chatgpt-account-id"] = accountId;
+        let respuesta;
+        try {
+            respuesta = await fetchImpl(ENDPOINT, { headers, signal: señal });
+        }
+        catch (error) {
+            throw new ErrorConsultaCuota("openai-codex", `no se pudo contactar con OpenAI Codex: ${String(error)}`, {
+                cause: error,
+            });
+        }
+        if (!respuesta.ok) {
+            throw new ErrorConsultaCuota("openai-codex", `OpenAI Codex respondió ${respuesta.status} ${respuesta.statusText}`);
+        }
+        let datos;
+        try {
+            datos = (await respuesta.json());
+        }
+        catch (error) {
+            throw new ErrorConsultaCuota("openai-codex", `la respuesta de OpenAI Codex no es JSON válido: ${String(error)}`, {
+                cause: error,
+            });
+        }
+        const ventanas = [
+            aVentana("Ventana principal", datos.rate_limit?.primary_window),
+            aVentana("Ventana secundaria", datos.rate_limit?.secondary_window),
+        ].filter((v) => v !== undefined);
+        return ventanas.length > 0 ? ventanas : null;
+    },
+};
+//# sourceMappingURL=openai-codex.js.map

package/dist/core/usage/cuota/openai-codex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai-codex.js","sourceRoot":"","sources":["../../../../src/core/usage/cuota/openai-codex.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAuB,kBAAkB,EAAqB,MAAM,YAAY,CAAC;AAExF,MAAM,QAAQ,GAAG,4CAA4C,CAAC;AAc9D,SAAS,QAAQ,CAAC,QAAgB,EAAE,IAAqC,EAA4B;IACpG,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,CAAC,YAAY,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IACrE,MAAM,UAAU,GAAG,OAAO,IAAI,CAAC,QAAQ,KAAK,QAAQ,IAAI,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;IACxG,OAAO;QACN,QAAQ;QACR,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC;QACpD,MAAM,EAAE,GAAG;QACX,UAAU;QACV,MAAM,EAAE,YAAY;KACpB,CAAC;AAAA,CACF;AAED,MAAM,CAAC,MAAM,oBAAoB,GAAmB;IACnD,EAAE,EAAE,cAAc;IAClB,OAAO,EAAE,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,KAAK,OAAO;IACpD,KAAK,CAAC,SAAS,CAAC,EAAE,UAAU,EAAE,KAAK,EAAE,SAAS,GAAG,KAAK,EAAE,MAAK,EAAE,EAAE;QAChE,IAAI,UAAU,CAAC,IAAI,KAAK,OAAO;YAAE,OAAO,IAAI,CAAC;QAE7C,MAAM,OAAO,GAA2B,EAAE,aAAa,EAAE,UAAU,UAAU,CAAC,MAAM,EAAE,EAAE,CAAC;QACzF,MAAM,SAAS,GAAG,UAAU,CAAC,SAAS,CAAC;QACvC,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS;YAAE,OAAO,CAAC,oBAAoB,CAAC,GAAG,SAAS,CAAC;QAE1F,IAAI,SAAmB,CAAC;QACxB,IAAI,CAAC;YACJ,SAAS,GAAG,MAAM,SAAS,CAAC,QAAQ,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,MAAK,EAAE,CAAC,CAAC;QACnE,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,MAAM,IAAI,kBAAkB,CAAC,cAAc,EAAE,0CAA0C,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE;gBACvG,KAAK,EAAE,KAAK;aACZ,CAAC,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,CAAC;YACnB,MAAM,IAAI,kBAAkB,CAC3B,cAAc,EACd,2BAA0B,SAAS,CAAC,MAAM,IAAI,SAAS,CAAC,UAAU,EAAE,CACpE,CAAC;QACH,CAAC;QAED,IAAI,KAAqB,CAAC;QAC1B,IAAI,CAAC;YACJ,KAAK,GAAG,CAAC,MAAM,SAAS,CAAC,IAAI,EAAE,CAAmB,CAAC;QACpD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,MAAM,IAAI,kBAAkB,CAC3B,cAAc,EACd,oDAAmD,MAAM,CAAC,KAAK,CAAC,EAAE,EAClE;gBACC,KAAK,EAAE,KAAK;aACZ,CACD,CAAC;QACH,CAAC;QAED,MAAM,QAAQ,GAAG;YAChB,QAAQ,CAAC,mBAAmB,EAAE,KAAK,CAAC,UAAU,EAAE,cAAc,CAAC;YAC/D,QAAQ,CAAC,oBAAoB,EAAE,KAAK,CAAC,UAAU,EAAE,gBAAgB,CAAC;SAClE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAqB,EAAE,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC;QACpD,OAAO,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC;IAAA,CAC7C;CACD,CAAC","sourcesContent":["/**\n * Cuota de OpenAI Codex (ChatGPT) — endpoint interno de cuenta, no la API de\n * pago por token. Vive en `chatgpt.com`, no en `api.openai.com`: no hay\n * override de `baseUrl` que valga aquí, un proxy de streaming lo devolvería\n * en 404.\n */\n\nimport { type ConsultorCuota, ErrorConsultaCuota, type VentanaCuota } from \"./tipos.ts\";\n\nconst ENDPOINT = \"https://chatgpt.com/backend-api/wham/usage\";\n\ninterface VentanaBruta {\n\tused_percent?: number;\n\treset_at?: number;\n}\n\ninterface RespuestaCodex {\n\trate_limit?: {\n\t\tprimary_window?: VentanaBruta | null;\n\t\tsecondary_window?: VentanaBruta | null;\n\t} | null;\n}\n\nfunction aVentana(etiqueta: string, cubo: VentanaBruta | null | undefined): VentanaCuota | undefined {\n\tif (!cubo || typeof cubo.used_percent !== \"number\") return undefined;\n\tconst seReinicia = typeof cubo.reset_at === \"number\" && cubo.reset_at > 0 ? cubo.reset_at * 1000 : null;\n\treturn {\n\t\tetiqueta,\n\t\tusado: Math.min(Math.max(cubo.used_percent, 0), 100),\n\t\tlimite: 100,\n\t\tseReinicia,\n\t\tunidad: \"porcentaje\",\n\t};\n}\n\nexport const consultorOpenAiCodex: ConsultorCuota = {\n\tid: \"openai-codex\",\n\tsoporta: (credencial) => credencial.type === \"oauth\",\n\tasync consultar({ credencial, fetch: fetchImpl = fetch, señal }) {\n\t\tif (credencial.type !== \"oauth\") return null;\n\n\t\tconst headers: Record<string, string> = { authorization: `Bearer ${credencial.access}` };\n\t\tconst accountId = credencial.accountId;\n\t\tif (typeof accountId === \"string\" && accountId) headers[\"chatgpt-account-id\"] = accountId;\n\n\t\tlet respuesta: Response;\n\t\ttry {\n\t\t\trespuesta = await fetchImpl(ENDPOINT, { headers, signal: señal });\n\t\t} catch (error) {\n\t\t\tthrow new ErrorConsultaCuota(\"openai-codex\", `no se pudo contactar con OpenAI Codex: ${String(error)}`, {\n\t\t\t\tcause: error,\n\t\t\t});\n\t\t}\n\t\tif (!respuesta.ok) {\n\t\t\tthrow new ErrorConsultaCuota(\n\t\t\t\t\"openai-codex\",\n\t\t\t\t`OpenAI Codex respondió ${respuesta.status} ${respuesta.statusText}`,\n\t\t\t);\n\t\t}\n\n\t\tlet datos: RespuestaCodex;\n\t\ttry {\n\t\t\tdatos = (await respuesta.json()) as RespuestaCodex;\n\t\t} catch (error) {\n\t\t\tthrow new ErrorConsultaCuota(\n\t\t\t\t\"openai-codex\",\n\t\t\t\t`la respuesta de OpenAI Codex no es JSON válido: ${String(error)}`,\n\t\t\t\t{\n\t\t\t\t\tcause: error,\n\t\t\t\t},\n\t\t\t);\n\t\t}\n\n\t\tconst ventanas = [\n\t\t\taVentana(\"Ventana principal\", datos.rate_limit?.primary_window),\n\t\t\taVentana(\"Ventana secundaria\", datos.rate_limit?.secondary_window),\n\t\t].filter((v): v is VentanaCuota => v !== undefined);\n\t\treturn ventanas.length > 0 ? ventanas : null;\n\t},\n};\n"]}

package/dist/core/usage/cuota/openrouter.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Cuota de OpenRouter — saldo de créditos, no una ventana de tiempo.
+ *
+ * `GET /credits` devuelve el total comprado y el total gastado. Una cuenta de
+ * pago-por-uso que nunca compró crédito no tiene techo: eso también es "no
+ * publica cuota", no "cero disponible".
+ */
+import { type ConsultorCuota } from "./tipos.ts";
+export declare const consultorOpenRouter: ConsultorCuota;
+//# sourceMappingURL=openrouter.d.ts.map

package/dist/core/usage/cuota/openrouter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openrouter.d.ts","sourceRoot":"","sources":["../../../../src/core/usage/cuota/openrouter.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,KAAK,cAAc,EAAsB,MAAM,YAAY,CAAC;AAQrE,eAAO,MAAM,mBAAmB,EAAE,cAmCjC,CAAC","sourcesContent":["/**\n * Cuota de OpenRouter — saldo de créditos, no una ventana de tiempo.\n *\n * `GET /credits` devuelve el total comprado y el total gastado. Una cuenta de\n * pago-por-uso que nunca compró crédito no tiene techo: eso también es \"no\n * publica cuota\", no \"cero disponible\".\n */\n\nimport { type ConsultorCuota, ErrorConsultaCuota } from \"./tipos.ts\";\n\nconst ENDPOINT = \"https://openrouter.ai/api/v1/credits\";\n\ninterface RespuestaOpenRouter {\n\tdata?: { total_credits?: number; total_usage?: number };\n}\n\nexport const consultorOpenRouter: ConsultorCuota = {\n\tid: \"openrouter\",\n\tsoporta: (credencial) => credencial.type === \"api_key\" && Boolean(credencial.key),\n\tasync consultar({ credencial, fetch: fetchImpl = fetch, señal }) {\n\t\tif (credencial.type !== \"api_key\" || !credencial.key) return null;\n\n\t\tlet respuesta: Response;\n\t\ttry {\n\t\t\trespuesta = await fetchImpl(ENDPOINT, {\n\t\t\t\theaders: { authorization: `Bearer ${credencial.key}` },\n\t\t\t\tsignal: señal,\n\t\t\t});\n\t\t} catch (error) {\n\t\t\tthrow new ErrorConsultaCuota(\"openrouter\", `no se pudo contactar con OpenRouter: ${String(error)}`, {\n\t\t\t\tcause: error,\n\t\t\t});\n\t\t}\n\t\tif (!respuesta.ok) {\n\t\t\tthrow new ErrorConsultaCuota(\"openrouter\", `OpenRouter respondió ${respuesta.status} ${respuesta.statusText}`);\n\t\t}\n\n\t\tlet datos: RespuestaOpenRouter;\n\t\ttry {\n\t\t\tdatos = (await respuesta.json()) as RespuestaOpenRouter;\n\t\t} catch (error) {\n\t\t\tthrow new ErrorConsultaCuota(\"openrouter\", `la respuesta de OpenRouter no es JSON válido: ${String(error)}`, {\n\t\t\t\tcause: error,\n\t\t\t});\n\t\t}\n\n\t\tconst limite = datos.data?.total_credits;\n\t\tconst usado = datos.data?.total_usage;\n\t\tif (typeof limite !== \"number\" || limite <= 0 || typeof usado !== \"number\") return null;\n\t\treturn [{ etiqueta: \"Saldo\", usado, limite, seReinicia: null, unidad: \"usd\" }];\n\t},\n};\n"]}

package/dist/core/usage/cuota/openrouter.js

@@ -0,0 +1,47 @@
+/**
+ * Cuota de OpenRouter — saldo de créditos, no una ventana de tiempo.
+ *
+ * `GET /credits` devuelve el total comprado y el total gastado. Una cuenta de
+ * pago-por-uso que nunca compró crédito no tiene techo: eso también es "no
+ * publica cuota", no "cero disponible".
+ */
+import { ErrorConsultaCuota } from "./tipos.js";
+const ENDPOINT = "https://openrouter.ai/api/v1/credits";
+export const consultorOpenRouter = {
+    id: "openrouter",
+    soporta: (credencial) => credencial.type === "api_key" && Boolean(credencial.key),
+    async consultar({ credencial, fetch: fetchImpl = fetch, señal }) {
+        if (credencial.type !== "api_key" || !credencial.key)
+            return null;
+        let respuesta;
+        try {
+            respuesta = await fetchImpl(ENDPOINT, {
+                headers: { authorization: `Bearer ${credencial.key}` },
+                signal: señal,
+            });
+        }
+        catch (error) {
+            throw new ErrorConsultaCuota("openrouter", `no se pudo contactar con OpenRouter: ${String(error)}`, {
+                cause: error,
+            });
+        }
+        if (!respuesta.ok) {
+            throw new ErrorConsultaCuota("openrouter", `OpenRouter respondió ${respuesta.status} ${respuesta.statusText}`);
+        }
+        let datos;
+        try {
+            datos = (await respuesta.json());
+        }
+        catch (error) {
+            throw new ErrorConsultaCuota("openrouter", `la respuesta de OpenRouter no es JSON válido: ${String(error)}`, {
+                cause: error,
+            });
+        }
+        const limite = datos.data?.total_credits;
+        const usado = datos.data?.total_usage;
+        if (typeof limite !== "number" || limite <= 0 || typeof usado !== "number")
+            return null;
+        return [{ etiqueta: "Saldo", usado, limite, seReinicia: null, unidad: "usd" }];
+    },
+};
+//# sourceMappingURL=openrouter.js.map

package/dist/core/usage/cuota/openrouter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openrouter.js","sourceRoot":"","sources":["../../../../src/core/usage/cuota/openrouter.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAuB,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErE,MAAM,QAAQ,GAAG,sCAAsC,CAAC;AAMxD,MAAM,CAAC,MAAM,mBAAmB,GAAmB;IAClD,EAAE,EAAE,YAAY;IAChB,OAAO,EAAE,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,KAAK,SAAS,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC;IACjF,KAAK,CAAC,SAAS,CAAC,EAAE,UAAU,EAAE,KAAK,EAAE,SAAS,GAAG,KAAK,EAAE,MAAK,EAAE,EAAE;QAChE,IAAI,UAAU,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,UAAU,CAAC,GAAG;YAAE,OAAO,IAAI,CAAC;QAElE,IAAI,SAAmB,CAAC;QACxB,IAAI,CAAC;YACJ,SAAS,GAAG,MAAM,SAAS,CAAC,QAAQ,EAAE;gBACrC,OAAO,EAAE,EAAE,aAAa,EAAE,UAAU,UAAU,CAAC,GAAG,EAAE,EAAE;gBACtD,MAAM,EAAE,MAAK;aACb,CAAC,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,MAAM,IAAI,kBAAkB,CAAC,YAAY,EAAE,wCAAwC,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE;gBACnG,KAAK,EAAE,KAAK;aACZ,CAAC,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,CAAC;YACnB,MAAM,IAAI,kBAAkB,CAAC,YAAY,EAAE,yBAAwB,SAAS,CAAC,MAAM,IAAI,SAAS,CAAC,UAAU,EAAE,CAAC,CAAC;QAChH,CAAC;QAED,IAAI,KAA0B,CAAC;QAC/B,IAAI,CAAC;YACJ,KAAK,GAAG,CAAC,MAAM,SAAS,CAAC,IAAI,EAAE,CAAwB,CAAC;QACzD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,MAAM,IAAI,kBAAkB,CAAC,YAAY,EAAE,kDAAiD,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE;gBAC5G,KAAK,EAAE,KAAK;aACZ,CAAC,CAAC;QACJ,CAAC;QAED,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,EAAE,aAAa,CAAC;QACzC,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,EAAE,WAAW,CAAC;QACtC,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,IAAI,CAAC,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QACxF,OAAO,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;IAAA,CAC/E;CACD,CAAC","sourcesContent":["/**\n * Cuota de OpenRouter — saldo de créditos, no una ventana de tiempo.\n *\n * `GET /credits` devuelve el total comprado y el total gastado. Una cuenta de\n * pago-por-uso que nunca compró crédito no tiene techo: eso también es \"no\n * publica cuota\", no \"cero disponible\".\n */\n\nimport { type ConsultorCuota, ErrorConsultaCuota } from \"./tipos.ts\";\n\nconst ENDPOINT = \"https://openrouter.ai/api/v1/credits\";\n\ninterface RespuestaOpenRouter {\n\tdata?: { total_credits?: number; total_usage?: number };\n}\n\nexport const consultorOpenRouter: ConsultorCuota = {\n\tid: \"openrouter\",\n\tsoporta: (credencial) => credencial.type === \"api_key\" && Boolean(credencial.key),\n\tasync consultar({ credencial, fetch: fetchImpl = fetch, señal }) {\n\t\tif (credencial.type !== \"api_key\" || !credencial.key) return null;\n\n\t\tlet respuesta: Response;\n\t\ttry {\n\t\t\trespuesta = await fetchImpl(ENDPOINT, {\n\t\t\t\theaders: { authorization: `Bearer ${credencial.key}` },\n\t\t\t\tsignal: señal,\n\t\t\t});\n\t\t} catch (error) {\n\t\t\tthrow new ErrorConsultaCuota(\"openrouter\", `no se pudo contactar con OpenRouter: ${String(error)}`, {\n\t\t\t\tcause: error,\n\t\t\t});\n\t\t}\n\t\tif (!respuesta.ok) {\n\t\t\tthrow new ErrorConsultaCuota(\"openrouter\", `OpenRouter respondió ${respuesta.status} ${respuesta.statusText}`);\n\t\t}\n\n\t\tlet datos: RespuestaOpenRouter;\n\t\ttry {\n\t\t\tdatos = (await respuesta.json()) as RespuestaOpenRouter;\n\t\t} catch (error) {\n\t\t\tthrow new ErrorConsultaCuota(\"openrouter\", `la respuesta de OpenRouter no es JSON válido: ${String(error)}`, {\n\t\t\t\tcause: error,\n\t\t\t});\n\t\t}\n\n\t\tconst limite = datos.data?.total_credits;\n\t\tconst usado = datos.data?.total_usage;\n\t\tif (typeof limite !== \"number\" || limite <= 0 || typeof usado !== \"number\") return null;\n\t\treturn [{ etiqueta: \"Saldo\", usado, limite, seReinicia: null, unidad: \"usd\" }];\n\t},\n};\n"]}

package/dist/core/usage/cuota/tipos.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Cuánto QUEDA del plan, por proveedor — no cuánto se ha gastado.
+ *
+ * `ada-cli usage` (ver `../aggregate.ts`) lee los JSONL de sesión y suma lo
+ * que ya se consumió. Eso no dice si a un equipo le quedan dos peticiones o
+ * dos mil: ese dato no vive en la sesión, vive en el proveedor, así que hay
+ * que preguntárselo a él.
+ */
+import type { Credential } from "@earendil-works/pi-ai";
+export type UnidadCuota = "porcentaje" | "peticiones" | "usd";
+/** Una ventana de cuota ya lista para mostrar (p.ej. "5 horas" o "Semanal"). */
+export interface VentanaCuota {
+    etiqueta: string;
+    usado: number;
+    limite: number;
+    /** Epoch ms en que se reinicia esta ventana; `null` si el proveedor no lo dice. */
+    seReinicia: number | null;
+    unidad: UnidadCuota;
+}
+/**
+ * La consulta a la cuota falló de verdad (red, HTTP, JSON roto).
+ *
+ * A propósito NO es lo mismo que "el proveedor no publica cuota"
+ * (`consultar` devuelve `null` para eso): confundir ambos casos hace que un
+ * fallo de red se enseñe como "sin límite", que es la mentira que esta pieza
+ * existe para evitar.
+ */
+export declare class ErrorConsultaCuota extends Error {
+    readonly proveedor: string;
+    constructor(proveedor: string, mensaje: string, options?: ErrorOptions);
+}
+/** Lo mínimo para preguntarle a un proveedor: con qué credencial y por qué canal. */
+export interface ContextoConsulta {
+    credencial: Credential;
+    fetch?: typeof fetch;
+    señal?: AbortSignal;
+}
+/** Un proveedor: cómo se llama y cómo se le pregunta cuánto queda. */
+export interface ConsultorCuota {
+    id: string;
+    /** true si esta credencial es del tipo que este proveedor sabe consultar. */
+    soporta(credencial: Credential): boolean;
+    /**
+     * `null` = el proveedor no publica cuota para esta credencial (p.ej. la
+     * API key de pago-por-token de Anthropic no tiene techo que consultar).
+     * Lanza {@link ErrorConsultaCuota} si la consulta falla de verdad.
+     */
+    consultar(ctx: ContextoConsulta): Promise<VentanaCuota[] | null>;
+}
+//# sourceMappingURL=tipos.d.ts.map

package/dist/core/usage/cuota/tipos.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tipos.d.ts","sourceRoot":"","sources":["../../../../src/core/usage/cuota/tipos.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAExD,MAAM,MAAM,WAAW,GAAG,YAAY,GAAG,YAAY,GAAG,KAAK,CAAC;AAE9D,gFAAgF;AAChF,MAAM,WAAW,YAAY;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,mFAAmF;IACnF,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,MAAM,EAAE,WAAW,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,YAAY,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,EAIrE;CACD;AAED,wFAAqF;AACrF,MAAM,WAAW,gBAAgB;IAChC,UAAU,EAAE,UAAU,CAAC;IACvB,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,MAAK,CAAC,EAAE,WAAW,CAAC;CACpB;AAED,yEAAsE;AACtE,MAAM,WAAW,cAAc;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,6EAA6E;IAC7E,OAAO,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC;IACzC;;;;OAIG;IACH,SAAS,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,YAAY,EAAE,GAAG,IAAI,CAAC,CAAC;CACjE","sourcesContent":["/**\n * Cuánto QUEDA del plan, por proveedor — no cuánto se ha gastado.\n *\n * `ada-cli usage` (ver `../aggregate.ts`) lee los JSONL de sesión y suma lo\n * que ya se consumió. Eso no dice si a un equipo le quedan dos peticiones o\n * dos mil: ese dato no vive en la sesión, vive en el proveedor, así que hay\n * que preguntárselo a él.\n */\n\nimport type { Credential } from \"@earendil-works/pi-ai\";\n\nexport type UnidadCuota = \"porcentaje\" | \"peticiones\" | \"usd\";\n\n/** Una ventana de cuota ya lista para mostrar (p.ej. \"5 horas\" o \"Semanal\"). */\nexport interface VentanaCuota {\n\tetiqueta: string;\n\tusado: number;\n\tlimite: number;\n\t/** Epoch ms en que se reinicia esta ventana; `null` si el proveedor no lo dice. */\n\tseReinicia: number | null;\n\tunidad: UnidadCuota;\n}\n\n/**\n * La consulta a la cuota falló de verdad (red, HTTP, JSON roto).\n *\n * A propósito NO es lo mismo que \"el proveedor no publica cuota\"\n * (`consultar` devuelve `null` para eso): confundir ambos casos hace que un\n * fallo de red se enseñe como \"sin límite\", que es la mentira que esta pieza\n * existe para evitar.\n */\nexport class ErrorConsultaCuota extends Error {\n\treadonly proveedor: string;\n\n\tconstructor(proveedor: string, mensaje: string, options?: ErrorOptions) {\n\t\tsuper(mensaje, options);\n\t\tthis.name = \"ErrorConsultaCuota\";\n\t\tthis.proveedor = proveedor;\n\t}\n}\n\n/** Lo mínimo para preguntarle a un proveedor: con qué credencial y por qué canal. */\nexport interface ContextoConsulta {\n\tcredencial: Credential;\n\tfetch?: typeof fetch;\n\tseñal?: AbortSignal;\n}\n\n/** Un proveedor: cómo se llama y cómo se le pregunta cuánto queda. */\nexport interface ConsultorCuota {\n\tid: string;\n\t/** true si esta credencial es del tipo que este proveedor sabe consultar. */\n\tsoporta(credencial: Credential): boolean;\n\t/**\n\t * `null` = el proveedor no publica cuota para esta credencial (p.ej. la\n\t * API key de pago-por-token de Anthropic no tiene techo que consultar).\n\t * Lanza {@link ErrorConsultaCuota} si la consulta falla de verdad.\n\t */\n\tconsultar(ctx: ContextoConsulta): Promise<VentanaCuota[] | null>;\n}\n"]}

package/dist/core/usage/cuota/tipos.js

@@ -0,0 +1,25 @@
+/**
+ * Cuánto QUEDA del plan, por proveedor — no cuánto se ha gastado.
+ *
+ * `ada-cli usage` (ver `../aggregate.ts`) lee los JSONL de sesión y suma lo
+ * que ya se consumió. Eso no dice si a un equipo le quedan dos peticiones o
+ * dos mil: ese dato no vive en la sesión, vive en el proveedor, así que hay
+ * que preguntárselo a él.
+ */
+/**
+ * La consulta a la cuota falló de verdad (red, HTTP, JSON roto).
+ *
+ * A propósito NO es lo mismo que "el proveedor no publica cuota"
+ * (`consultar` devuelve `null` para eso): confundir ambos casos hace que un
+ * fallo de red se enseñe como "sin límite", que es la mentira que esta pieza
+ * existe para evitar.
+ */
+export class ErrorConsultaCuota extends Error {
+    proveedor;
+    constructor(proveedor, mensaje, options) {
+        super(mensaje, options);
+        this.name = "ErrorConsultaCuota";
+        this.proveedor = proveedor;
+    }
+}
+//# sourceMappingURL=tipos.js.map

package/dist/core/usage/cuota/tipos.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tipos.js","sourceRoot":"","sources":["../../../../src/core/usage/cuota/tipos.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAgBH;;;;;;;GAOG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IACnC,SAAS,CAAS;IAE3B,YAAY,SAAiB,EAAE,OAAe,EAAE,OAAsB,EAAE;QACvE,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAAA,CAC3B;CACD","sourcesContent":["/**\n * Cuánto QUEDA del plan, por proveedor — no cuánto se ha gastado.\n *\n * `ada-cli usage` (ver `../aggregate.ts`) lee los JSONL de sesión y suma lo\n * que ya se consumió. Eso no dice si a un equipo le quedan dos peticiones o\n * dos mil: ese dato no vive en la sesión, vive en el proveedor, así que hay\n * que preguntárselo a él.\n */\n\nimport type { Credential } from \"@earendil-works/pi-ai\";\n\nexport type UnidadCuota = \"porcentaje\" | \"peticiones\" | \"usd\";\n\n/** Una ventana de cuota ya lista para mostrar (p.ej. \"5 horas\" o \"Semanal\"). */\nexport interface VentanaCuota {\n\tetiqueta: string;\n\tusado: number;\n\tlimite: number;\n\t/** Epoch ms en que se reinicia esta ventana; `null` si el proveedor no lo dice. */\n\tseReinicia: number | null;\n\tunidad: UnidadCuota;\n}\n\n/**\n * La consulta a la cuota falló de verdad (red, HTTP, JSON roto).\n *\n * A propósito NO es lo mismo que \"el proveedor no publica cuota\"\n * (`consultar` devuelve `null` para eso): confundir ambos casos hace que un\n * fallo de red se enseñe como \"sin límite\", que es la mentira que esta pieza\n * existe para evitar.\n */\nexport class ErrorConsultaCuota extends Error {\n\treadonly proveedor: string;\n\n\tconstructor(proveedor: string, mensaje: string, options?: ErrorOptions) {\n\t\tsuper(mensaje, options);\n\t\tthis.name = \"ErrorConsultaCuota\";\n\t\tthis.proveedor = proveedor;\n\t}\n}\n\n/** Lo mínimo para preguntarle a un proveedor: con qué credencial y por qué canal. */\nexport interface ContextoConsulta {\n\tcredencial: Credential;\n\tfetch?: typeof fetch;\n\tseñal?: AbortSignal;\n}\n\n/** Un proveedor: cómo se llama y cómo se le pregunta cuánto queda. */\nexport interface ConsultorCuota {\n\tid: string;\n\t/** true si esta credencial es del tipo que este proveedor sabe consultar. */\n\tsoporta(credencial: Credential): boolean;\n\t/**\n\t * `null` = el proveedor no publica cuota para esta credencial (p.ej. la\n\t * API key de pago-por-token de Anthropic no tiene techo que consultar).\n\t * Lanza {@link ErrorConsultaCuota} si la consulta falla de verdad.\n\t */\n\tconsultar(ctx: ContextoConsulta): Promise<VentanaCuota[] | null>;\n}\n"]}

package/dist/core/web/busqueda-nativa.d.ts

@@ -0,0 +1,82 @@
+/**
+ * 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.
+ */
+/** Un resultado, ya normalizado. */
+export interface ResultadoWeb {
+    titulo: string;
+    url: string;
+    /** Antigüedad tal y como la da el proveedor ("3 weeks ago", "June 8, 2026"). */
+    edad?: string;
+}
+/** Proveedores cuyo modelo sabe buscar por su cuenta. */
+export declare function soportaBusquedaNativa(proveedor: string): boolean;
+/**
+ * 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 declare function conToolDeBusqueda(carga: unknown, maxUsos?: number): unknown;
+/**
+ * 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 declare function recolectarResultados(valor: unknown, acumulado?: ResultadoWeb[]): ResultadoWeb[];
+/** Quita repetidos por URL, conservando el orden de aparición. */
+export declare function sinRepetidos(resultados: ResultadoWeb[]): ResultadoWeb[];
+/**
+ * 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 declare function fetchQueRecolecta(base: typeof fetch, destino: ResultadoWeb[]): typeof fetch;
+/** Lo que hace falta para buscar, inyectado para poder probarlo sin red. */
+export interface DependenciasBusqueda {
+    /** Ejecuta una consulta contra el modelo con las opciones dadas. */
+    completar: (consulta: string, opciones: {
+        fetch: typeof fetch;
+        onPayload: (c: unknown) => unknown;
+    }) => Promise<void>;
+    fetchBase?: typeof fetch;
+    maxResultados?: number;
+}
+/**
+ * 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 declare function buscarConElModelo(consulta: string, deps: DependenciasBusqueda): Promise<ResultadoWeb[]>;
+//# sourceMappingURL=busqueda-nativa.d.ts.map

package/dist/core/web/busqueda-nativa.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"busqueda-nativa.d.ts","sourceRoot":"","sources":["../../../src/core/web/busqueda-nativa.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,oCAAoC;AACpC,MAAM,WAAW,YAAY;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,iFAAgF;IAChF,IAAI,CAAC,EAAE,MAAM,CAAC;CACd;AAKD,yDAAyD;AACzD,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAEhE;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,SAAI,GAAG,OAAO,CAKtE;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,GAAE,YAAY,EAAO,GAAG,YAAY,EAAE,CAgBnG;AAED,mEAAkE;AAClE,wBAAgB,YAAY,CAAC,UAAU,EAAE,YAAY,EAAE,GAAG,YAAY,EAAE,CASvE;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,GAAG,OAAO,KAAK,CAgD3F;AAED,4EAA4E;AAC5E,MAAM,WAAW,oBAAoB;IACpC,oEAAoE;IACpE,SAAS,EAAE,CACV,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE;QAAE,KAAK,EAAE,OAAO,KAAK,CAAC;QAAC,SAAS,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,OAAO,CAAA;KAAE,KACjE,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAO7G","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/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"]}