@hoilab/ada-cli 0.84.21 → 0.85.0

package/dist/core/browser/cdp.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Cliente mínimo del Chrome DevTools Protocol.
+ *
+ * Sin Playwright ni Puppeteer a propósito. Playwright son cientos de megas y
+ * se descarga sus propios navegadores; el mismo coste de cadena de suministro
+ * que ya rechazamos dos veces en este repo. CDP es un WebSocket con JSON, y
+ * Node trae `WebSocket` nativo desde la 22.
+ *
+ * Solo cubre lo que necesitan las tools: conectar, pedir y escuchar. No
+ * pretende ser una librería.
+ */
+export interface OpcionesCdp {
+    /** Tope por petición. Una página colgada no puede colgar el turno. */
+    timeoutMs?: number;
+    /** Inyectable para poder probar el enmarcado sin un navegador. */
+    crearSocket?: (url: string) => WebSocketLike;
+}
+/** Lo mínimo que usamos de un WebSocket, para poder falsearlo en pruebas. */
+export interface WebSocketLike {
+    send(datos: string): void;
+    close(): void;
+    addEventListener(tipo: "message" | "open" | "close" | "error", handler: (evento: unknown) => void): void;
+}
+export declare class ClienteCdp {
+    private socket;
+    private siguienteId;
+    private pendientes;
+    private oyentes;
+    private cerrado;
+    private timeoutMs;
+    private constructor();
+    static conectar(url: string, opciones?: OpcionesCdp): Promise<ClienteCdp>;
+    /** Para pruebas: cliente sobre un socket ya "abierto". */
+    static sobreSocket(socket: WebSocketLike, timeoutMs?: number): ClienteCdp;
+    private recibir;
+    private alCerrar;
+    enviar<T = unknown>(method: string, params?: Record<string, unknown>, sessionId?: string): Promise<T>;
+    escuchar(method: string, handler: (params: unknown) => void): () => void;
+    cerrar(): void;
+}
+//# sourceMappingURL=cdp.d.ts.map

package/dist/core/browser/cdp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdp.d.ts","sourceRoot":"","sources":["../../../src/core/browser/cdp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAQH,MAAM,WAAW,WAAW;IAC3B,wEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kEAAkE;IAClE,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,aAAa,CAAC;CAC7C;AAED,8EAA6E;AAC7E,MAAM,WAAW,aAAa;IAC7B,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,KAAK,IAAI,IAAI,CAAC;IACd,gBAAgB,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,EAAE,OAAO,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI,CAAC;CACzG;AAID,qBAAa,UAAU;IACtB,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,UAAU,CAAgC;IAClD,OAAO,CAAC,OAAO,CAAqD;IACpE,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,SAAS,CAAS;IAE1B,OAAO,eAQN;IAED,OAAa,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,CAAC,CAkBlF;IAED,0DAA0D;IAC1D,MAAM,CAAC,WAAW,CAAC,MAAM,EAAE,aAAa,EAAE,SAAS,SAAsB,GAAG,UAAU,CAErF;IAED,OAAO,CAAC,OAAO;IAwBf,OAAO,CAAC,QAAQ;IAaV,MAAM,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAY9G;IAED,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,GAAG,MAAM,IAAI,CAKvE;IAED,MAAM,IAAI,IAAI,CAOb;CACD","sourcesContent":["/**\n * Cliente mínimo del Chrome DevTools Protocol.\n *\n * Sin Playwright ni Puppeteer a propósito. Playwright son cientos de megas y\n * se descarga sus propios navegadores; el mismo coste de cadena de suministro\n * que ya rechazamos dos veces en este repo. CDP es un WebSocket con JSON, y\n * Node trae `WebSocket` nativo desde la 22.\n *\n * Solo cubre lo que necesitan las tools: conectar, pedir y escuchar. No\n * pretende ser una librería.\n */\n\ninterface Pendiente {\n\tresolve: (valor: unknown) => void;\n\treject: (error: Error) => void;\n\ttemporizador: ReturnType<typeof setTimeout>;\n}\n\nexport interface OpcionesCdp {\n\t/** Tope por petición. Una página colgada no puede colgar el turno. */\n\ttimeoutMs?: number;\n\t/** Inyectable para poder probar el enmarcado sin un navegador. */\n\tcrearSocket?: (url: string) => WebSocketLike;\n}\n\n/** Lo mínimo que usamos de un WebSocket, para poder falsearlo en pruebas. */\nexport interface WebSocketLike {\n\tsend(datos: string): void;\n\tclose(): void;\n\taddEventListener(tipo: \"message\" | \"open\" | \"close\" | \"error\", handler: (evento: unknown) => void): void;\n}\n\nconst TIMEOUT_POR_DEFECTO = 30_000;\n\nexport class ClienteCdp {\n\tprivate socket: WebSocketLike;\n\tprivate siguienteId = 1;\n\tprivate pendientes = new Map<number, Pendiente>();\n\tprivate oyentes = new Map<string, Set<(params: unknown) => void>>();\n\tprivate cerrado = false;\n\tprivate timeoutMs: number;\n\n\tprivate constructor(socket: WebSocketLike, timeoutMs: number) {\n\t\tthis.socket = socket;\n\t\tthis.timeoutMs = timeoutMs;\n\t\tthis.socket.addEventListener(\"message\", (evento) => {\n\t\t\tthis.recibir((evento as { data?: unknown }).data);\n\t\t});\n\t\tthis.socket.addEventListener(\"close\", () => this.alCerrar(new Error(\"el navegador cerró la conexión\")));\n\t\tthis.socket.addEventListener(\"error\", () => this.alCerrar(new Error(\"error de conexión con el navegador\")));\n\t}\n\n\tstatic async conectar(url: string, opciones: OpcionesCdp = {}): Promise<ClienteCdp> {\n\t\tconst crear = opciones.crearSocket ?? ((u: string) => new WebSocket(u) as unknown as WebSocketLike);\n\t\tconst socket = crear(url);\n\t\tawait new Promise<void>((resolve, reject) => {\n\t\t\tconst temporizador = setTimeout(\n\t\t\t\t() => reject(new Error(`no se pudo conectar a ${url} en ${opciones.timeoutMs ?? TIMEOUT_POR_DEFECTO} ms`)),\n\t\t\t\topciones.timeoutMs ?? TIMEOUT_POR_DEFECTO,\n\t\t\t);\n\t\t\tsocket.addEventListener(\"open\", () => {\n\t\t\t\tclearTimeout(temporizador);\n\t\t\t\tresolve();\n\t\t\t});\n\t\t\tsocket.addEventListener(\"error\", () => {\n\t\t\t\tclearTimeout(temporizador);\n\t\t\t\treject(new Error(`no se pudo conectar a ${url}`));\n\t\t\t});\n\t\t});\n\t\treturn new ClienteCdp(socket, opciones.timeoutMs ?? TIMEOUT_POR_DEFECTO);\n\t}\n\n\t/** Para pruebas: cliente sobre un socket ya \"abierto\". */\n\tstatic sobreSocket(socket: WebSocketLike, timeoutMs = TIMEOUT_POR_DEFECTO): ClienteCdp {\n\t\treturn new ClienteCdp(socket, timeoutMs);\n\t}\n\n\tprivate recibir(datos: unknown): void {\n\t\tif (typeof datos !== \"string\") return;\n\t\tlet mensaje: { id?: number; method?: string; params?: unknown; result?: unknown; error?: { message?: string } };\n\t\ttry {\n\t\t\tmensaje = JSON.parse(datos);\n\t\t} catch {\n\t\t\treturn;\n\t\t}\n\n\t\tif (typeof mensaje.id === \"number\") {\n\t\t\tconst pendiente = this.pendientes.get(mensaje.id);\n\t\t\tif (!pendiente) return;\n\t\t\tthis.pendientes.delete(mensaje.id);\n\t\t\tclearTimeout(pendiente.temporizador);\n\t\t\tif (mensaje.error) pendiente.reject(new Error(mensaje.error.message ?? \"error del navegador\"));\n\t\t\telse pendiente.resolve(mensaje.result ?? {});\n\t\t\treturn;\n\t\t}\n\n\t\tif (mensaje.method) {\n\t\t\tfor (const oyente of this.oyentes.get(mensaje.method) ?? []) oyente(mensaje.params);\n\t\t}\n\t}\n\n\tprivate alCerrar(error: Error): void {\n\t\tif (this.cerrado) return;\n\t\tthis.cerrado = true;\n\t\t// Rechazar TODO lo pendiente: si no, una petición hecha justo antes de que\n\t\t// el navegador se cierre se queda esperando hasta su temporizador y el\n\t\t// turno espera con ella sin motivo.\n\t\tfor (const [, pendiente] of this.pendientes) {\n\t\t\tclearTimeout(pendiente.temporizador);\n\t\t\tpendiente.reject(error);\n\t\t}\n\t\tthis.pendientes.clear();\n\t}\n\n\tasync enviar<T = unknown>(method: string, params: Record<string, unknown> = {}, sessionId?: string): Promise<T> {\n\t\tif (this.cerrado) throw new Error(\"la conexión con el navegador está cerrada\");\n\t\tconst id = this.siguienteId++;\n\t\tconst promesa = new Promise<T>((resolve, reject) => {\n\t\t\tconst temporizador = setTimeout(() => {\n\t\t\t\tthis.pendientes.delete(id);\n\t\t\t\treject(new Error(`'${method}' no respondió en ${this.timeoutMs} ms`));\n\t\t\t}, this.timeoutMs);\n\t\t\tthis.pendientes.set(id, { resolve: resolve as (v: unknown) => void, reject, temporizador });\n\t\t});\n\t\tthis.socket.send(JSON.stringify(sessionId ? { id, method, params, sessionId } : { id, method, params }));\n\t\treturn promesa;\n\t}\n\n\tescuchar(method: string, handler: (params: unknown) => void): () => void {\n\t\tconst conjunto = this.oyentes.get(method) ?? new Set();\n\t\tconjunto.add(handler);\n\t\tthis.oyentes.set(method, conjunto);\n\t\treturn () => conjunto.delete(handler);\n\t}\n\n\tcerrar(): void {\n\t\tthis.alCerrar(new Error(\"conexión cerrada por el agente\"));\n\t\ttry {\n\t\t\tthis.socket.close();\n\t\t} catch {\n\t\t\t// Ya estaba cerrado.\n\t\t}\n\t}\n}\n"]}

package/dist/core/browser/cdp.js

@@ -0,0 +1,119 @@
+/**
+ * Cliente mínimo del Chrome DevTools Protocol.
+ *
+ * Sin Playwright ni Puppeteer a propósito. Playwright son cientos de megas y
+ * se descarga sus propios navegadores; el mismo coste de cadena de suministro
+ * que ya rechazamos dos veces en este repo. CDP es un WebSocket con JSON, y
+ * Node trae `WebSocket` nativo desde la 22.
+ *
+ * Solo cubre lo que necesitan las tools: conectar, pedir y escuchar. No
+ * pretende ser una librería.
+ */
+const TIMEOUT_POR_DEFECTO = 30_000;
+export class ClienteCdp {
+    socket;
+    siguienteId = 1;
+    pendientes = new Map();
+    oyentes = new Map();
+    cerrado = false;
+    timeoutMs;
+    constructor(socket, timeoutMs) {
+        this.socket = socket;
+        this.timeoutMs = timeoutMs;
+        this.socket.addEventListener("message", (evento) => {
+            this.recibir(evento.data);
+        });
+        this.socket.addEventListener("close", () => this.alCerrar(new Error("el navegador cerró la conexión")));
+        this.socket.addEventListener("error", () => this.alCerrar(new Error("error de conexión con el navegador")));
+    }
+    static async conectar(url, opciones = {}) {
+        const crear = opciones.crearSocket ?? ((u) => new WebSocket(u));
+        const socket = crear(url);
+        await new Promise((resolve, reject) => {
+            const temporizador = setTimeout(() => reject(new Error(`no se pudo conectar a ${url} en ${opciones.timeoutMs ?? TIMEOUT_POR_DEFECTO} ms`)), opciones.timeoutMs ?? TIMEOUT_POR_DEFECTO);
+            socket.addEventListener("open", () => {
+                clearTimeout(temporizador);
+                resolve();
+            });
+            socket.addEventListener("error", () => {
+                clearTimeout(temporizador);
+                reject(new Error(`no se pudo conectar a ${url}`));
+            });
+        });
+        return new ClienteCdp(socket, opciones.timeoutMs ?? TIMEOUT_POR_DEFECTO);
+    }
+    /** Para pruebas: cliente sobre un socket ya "abierto". */
+    static sobreSocket(socket, timeoutMs = TIMEOUT_POR_DEFECTO) {
+        return new ClienteCdp(socket, timeoutMs);
+    }
+    recibir(datos) {
+        if (typeof datos !== "string")
+            return;
+        let mensaje;
+        try {
+            mensaje = JSON.parse(datos);
+        }
+        catch {
+            return;
+        }
+        if (typeof mensaje.id === "number") {
+            const pendiente = this.pendientes.get(mensaje.id);
+            if (!pendiente)
+                return;
+            this.pendientes.delete(mensaje.id);
+            clearTimeout(pendiente.temporizador);
+            if (mensaje.error)
+                pendiente.reject(new Error(mensaje.error.message ?? "error del navegador"));
+            else
+                pendiente.resolve(mensaje.result ?? {});
+            return;
+        }
+        if (mensaje.method) {
+            for (const oyente of this.oyentes.get(mensaje.method) ?? [])
+                oyente(mensaje.params);
+        }
+    }
+    alCerrar(error) {
+        if (this.cerrado)
+            return;
+        this.cerrado = true;
+        // Rechazar TODO lo pendiente: si no, una petición hecha justo antes de que
+        // el navegador se cierre se queda esperando hasta su temporizador y el
+        // turno espera con ella sin motivo.
+        for (const [, pendiente] of this.pendientes) {
+            clearTimeout(pendiente.temporizador);
+            pendiente.reject(error);
+        }
+        this.pendientes.clear();
+    }
+    async enviar(method, params = {}, sessionId) {
+        if (this.cerrado)
+            throw new Error("la conexión con el navegador está cerrada");
+        const id = this.siguienteId++;
+        const promesa = new Promise((resolve, reject) => {
+            const temporizador = setTimeout(() => {
+                this.pendientes.delete(id);
+                reject(new Error(`'${method}' no respondió en ${this.timeoutMs} ms`));
+            }, this.timeoutMs);
+            this.pendientes.set(id, { resolve: resolve, reject, temporizador });
+        });
+        this.socket.send(JSON.stringify(sessionId ? { id, method, params, sessionId } : { id, method, params }));
+        return promesa;
+    }
+    escuchar(method, handler) {
+        const conjunto = this.oyentes.get(method) ?? new Set();
+        conjunto.add(handler);
+        this.oyentes.set(method, conjunto);
+        return () => conjunto.delete(handler);
+    }
+    cerrar() {
+        this.alCerrar(new Error("conexión cerrada por el agente"));
+        try {
+            this.socket.close();
+        }
+        catch {
+            // Ya estaba cerrado.
+        }
+    }
+}
+//# sourceMappingURL=cdp.js.map

package/dist/core/browser/cdp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdp.js","sourceRoot":"","sources":["../../../src/core/browser/cdp.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Cliente mínimo del Chrome DevTools Protocol.\n *\n * Sin Playwright ni Puppeteer a propósito. Playwright son cientos de megas y\n * se descarga sus propios navegadores; el mismo coste de cadena de suministro\n * que ya rechazamos dos veces en este repo. CDP es un WebSocket con JSON, y\n * Node trae `WebSocket` nativo desde la 22.\n *\n * Solo cubre lo que necesitan las tools: conectar, pedir y escuchar. No\n * pretende ser una librería.\n */\n\ninterface Pendiente {\n\tresolve: (valor: unknown) => void;\n\treject: (error: Error) => void;\n\ttemporizador: ReturnType<typeof setTimeout>;\n}\n\nexport interface OpcionesCdp {\n\t/** Tope por petición. Una página colgada no puede colgar el turno. */\n\ttimeoutMs?: number;\n\t/** Inyectable para poder probar el enmarcado sin un navegador. */\n\tcrearSocket?: (url: string) => WebSocketLike;\n}\n\n/** Lo mínimo que usamos de un WebSocket, para poder falsearlo en pruebas. */\nexport interface WebSocketLike {\n\tsend(datos: string): void;\n\tclose(): void;\n\taddEventListener(tipo: \"message\" | \"open\" | \"close\" | \"error\", handler: (evento: unknown) => void): void;\n}\n\nconst TIMEOUT_POR_DEFECTO = 30_000;\n\nexport class ClienteCdp {\n\tprivate socket: WebSocketLike;\n\tprivate siguienteId = 1;\n\tprivate pendientes = new Map<number, Pendiente>();\n\tprivate oyentes = new Map<string, Set<(params: unknown) => void>>();\n\tprivate cerrado = false;\n\tprivate timeoutMs: number;\n\n\tprivate constructor(socket: WebSocketLike, timeoutMs: number) {\n\t\tthis.socket = socket;\n\t\tthis.timeoutMs = timeoutMs;\n\t\tthis.socket.addEventListener(\"message\", (evento) => {\n\t\t\tthis.recibir((evento as { data?: unknown }).data);\n\t\t});\n\t\tthis.socket.addEventListener(\"close\", () => this.alCerrar(new Error(\"el navegador cerró la conexión\")));\n\t\tthis.socket.addEventListener(\"error\", () => this.alCerrar(new Error(\"error de conexión con el navegador\")));\n\t}\n\n\tstatic async conectar(url: string, opciones: OpcionesCdp = {}): Promise<ClienteCdp> {\n\t\tconst crear = opciones.crearSocket ?? ((u: string) => new WebSocket(u) as unknown as WebSocketLike);\n\t\tconst socket = crear(url);\n\t\tawait new Promise<void>((resolve, reject) => {\n\t\t\tconst temporizador = setTimeout(\n\t\t\t\t() => reject(new Error(`no se pudo conectar a ${url} en ${opciones.timeoutMs ?? TIMEOUT_POR_DEFECTO} ms`)),\n\t\t\t\topciones.timeoutMs ?? TIMEOUT_POR_DEFECTO,\n\t\t\t);\n\t\t\tsocket.addEventListener(\"open\", () => {\n\t\t\t\tclearTimeout(temporizador);\n\t\t\t\tresolve();\n\t\t\t});\n\t\t\tsocket.addEventListener(\"error\", () => {\n\t\t\t\tclearTimeout(temporizador);\n\t\t\t\treject(new Error(`no se pudo conectar a ${url}`));\n\t\t\t});\n\t\t});\n\t\treturn new ClienteCdp(socket, opciones.timeoutMs ?? TIMEOUT_POR_DEFECTO);\n\t}\n\n\t/** Para pruebas: cliente sobre un socket ya \"abierto\". */\n\tstatic sobreSocket(socket: WebSocketLike, timeoutMs = TIMEOUT_POR_DEFECTO): ClienteCdp {\n\t\treturn new ClienteCdp(socket, timeoutMs);\n\t}\n\n\tprivate recibir(datos: unknown): void {\n\t\tif (typeof datos !== \"string\") return;\n\t\tlet mensaje: { id?: number; method?: string; params?: unknown; result?: unknown; error?: { message?: string } };\n\t\ttry {\n\t\t\tmensaje = JSON.parse(datos);\n\t\t} catch {\n\t\t\treturn;\n\t\t}\n\n\t\tif (typeof mensaje.id === \"number\") {\n\t\t\tconst pendiente = this.pendientes.get(mensaje.id);\n\t\t\tif (!pendiente) return;\n\t\t\tthis.pendientes.delete(mensaje.id);\n\t\t\tclearTimeout(pendiente.temporizador);\n\t\t\tif (mensaje.error) pendiente.reject(new Error(mensaje.error.message ?? \"error del navegador\"));\n\t\t\telse pendiente.resolve(mensaje.result ?? {});\n\t\t\treturn;\n\t\t}\n\n\t\tif (mensaje.method) {\n\t\t\tfor (const oyente of this.oyentes.get(mensaje.method) ?? []) oyente(mensaje.params);\n\t\t}\n\t}\n\n\tprivate alCerrar(error: Error): void {\n\t\tif (this.cerrado) return;\n\t\tthis.cerrado = true;\n\t\t// Rechazar TODO lo pendiente: si no, una petición hecha justo antes de que\n\t\t// el navegador se cierre se queda esperando hasta su temporizador y el\n\t\t// turno espera con ella sin motivo.\n\t\tfor (const [, pendiente] of this.pendientes) {\n\t\t\tclearTimeout(pendiente.temporizador);\n\t\t\tpendiente.reject(error);\n\t\t}\n\t\tthis.pendientes.clear();\n\t}\n\n\tasync enviar<T = unknown>(method: string, params: Record<string, unknown> = {}, sessionId?: string): Promise<T> {\n\t\tif (this.cerrado) throw new Error(\"la conexión con el navegador está cerrada\");\n\t\tconst id = this.siguienteId++;\n\t\tconst promesa = new Promise<T>((resolve, reject) => {\n\t\t\tconst temporizador = setTimeout(() => {\n\t\t\t\tthis.pendientes.delete(id);\n\t\t\t\treject(new Error(`'${method}' no respondió en ${this.timeoutMs} ms`));\n\t\t\t}, this.timeoutMs);\n\t\t\tthis.pendientes.set(id, { resolve: resolve as (v: unknown) => void, reject, temporizador });\n\t\t});\n\t\tthis.socket.send(JSON.stringify(sessionId ? { id, method, params, sessionId } : { id, method, params }));\n\t\treturn promesa;\n\t}\n\n\tescuchar(method: string, handler: (params: unknown) => void): () => void {\n\t\tconst conjunto = this.oyentes.get(method) ?? new Set();\n\t\tconjunto.add(handler);\n\t\tthis.oyentes.set(method, conjunto);\n\t\treturn () => conjunto.delete(handler);\n\t}\n\n\tcerrar(): void {\n\t\tthis.alCerrar(new Error(\"conexión cerrada por el agente\"));\n\t\ttry {\n\t\t\tthis.socket.close();\n\t\t} catch {\n\t\t\t// Ya estaba cerrado.\n\t\t}\n\t}\n}\n"]}

package/dist/core/browser/politica.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Reglas del navegador. Puro: sin sockets ni procesos.
+ *
+ * Un agente que conduce un navegador es la superficie más peligrosa que tiene
+ * este producto: hay sesiones iniciadas, cookies, correo y banca detrás de las
+ * pestañas que ya están abiertas. Por eso las reglas viven aparte y se prueban
+ * solas, en vez de estar repartidas por el código que habla con Chrome.
+ *
+ * Las tres:
+ *
+ * 1. **Solo se conducen las pestañas que abrió el agente.** Nunca las del
+ *    usuario. Es la regla que copiamos de ZCode y la más importante: sin ella,
+ *    "resume esta página" puede acabar leyendo el banco.
+ * 2. **Las URL pasan por la misma guarda SSRF que `web_fetch`.** Un navegador
+ *    que puede ir a `169.254.169.254` es una fuga de credenciales de nube.
+ * 3. **Nunca se escribe en un campo de contraseña.** Ni aunque se lo pidan.
+ */
+/** Una pestaña conocida por el agente. */
+export interface Pestaña {
+    targetId: string;
+    url: string;
+    /** `true` solo si la abrió el agente. */
+    propia: boolean;
+}
+export declare class PestañaAjenaError extends Error {
+    constructor(targetId: string);
+}
+/** Lanza si la pestaña no es del agente. Ver regla 1. */
+export declare function exigirPestañaPropia(pestañas: Map<string, Pestaña>, targetId: string): Pestaña;
+export interface CampoFormulario {
+    type?: string;
+    name?: string;
+    id?: string;
+    autocomplete?: string;
+    placeholder?: string;
+    ariaLabel?: string;
+}
+export declare function esCampoSecreto(campo: CampoFormulario): boolean;
+export declare class CampoSecretoError extends Error {
+    constructor();
+}
+/**
+ * Acciones que no se hacen sin que una persona lo diga en el chat.
+ *
+ * No es una lista de botones prohibidos: es qué hay que preguntar antes. El
+ * agente puede navegar y leer sin permiso; enviar, comprar o publicar, no.
+ */
+export declare const ACCIONES_QUE_PIDEN_PERMISO: readonly ["enviar un formulario", "publicar contenido", "comprar o pagar", "aceptar términos o consentimientos", "conceder permisos OAuth", "borrar datos"];
+export declare function urlNavegable(bruta: string): URL;
+export declare function pareceIrreversible(textoDelBoton: string): boolean;
+//# sourceMappingURL=politica.d.ts.map

package/dist/core/browser/politica.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"politica.d.ts","sourceRoot":"","sources":["../../../src/core/browser/politica.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,2CAA0C;AAC1C,MAAM,WAAW,QAAO;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,0CAAyC;IACzC,MAAM,EAAE,OAAO,CAAC;CAChB;AAED,qBAAa,kBAAkB,SAAQ,KAAK;IAC3C,YAAY,QAAQ,EAAE,MAAM,EAM3B;CACD;AAED,0DAAyD;AACzD,wBAAgB,oBAAmB,CAAC,SAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,QAAO,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,QAAO,CAI7F;AAWD,MAAM,WAAW,eAAe;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAK9D;AAED,qBAAa,iBAAkB,SAAQ,KAAK;IAC3C,cAMC;CACD;AAED;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,8JAO7B,CAAC;AA2BX,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,CAoB/C;AAYD,wBAAgB,kBAAkB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAEjE","sourcesContent":["/**\n * Reglas del navegador. Puro: sin sockets ni procesos.\n *\n * Un agente que conduce un navegador es la superficie más peligrosa que tiene\n * este producto: hay sesiones iniciadas, cookies, correo y banca detrás de las\n * pestañas que ya están abiertas. Por eso las reglas viven aparte y se prueban\n * solas, en vez de estar repartidas por el código que habla con Chrome.\n *\n * Las tres:\n *\n * 1. **Solo se conducen las pestañas que abrió el agente.** Nunca las del\n *    usuario. Es la regla que copiamos de ZCode y la más importante: sin ella,\n *    \"resume esta página\" puede acabar leyendo el banco.\n * 2. **Las URL pasan por la misma guarda SSRF que `web_fetch`.** Un navegador\n *    que puede ir a `169.254.169.254` es una fuga de credenciales de nube.\n * 3. **Nunca se escribe en un campo de contraseña.** Ni aunque se lo pidan.\n */\n\n/** Una pestaña conocida por el agente. */\nexport interface Pestaña {\n\ttargetId: string;\n\turl: string;\n\t/** `true` solo si la abrió el agente. */\n\tpropia: boolean;\n}\n\nexport class PestañaAjenaError extends Error {\n\tconstructor(targetId: string) {\n\t\tsuper(\n\t\t\t`La pestaña ${targetId} no la abrió el agente. Solo se pueden conducir pestañas abiertas con browser_open; ` +\n\t\t\t\t`las del usuario tienen sesiones iniciadas detrás.`,\n\t\t);\n\t\tthis.name = \"PestañaAjenaError\";\n\t}\n}\n\n/** Lanza si la pestaña no es del agente. Ver regla 1. */\nexport function exigirPestañaPropia(pestañas: Map<string, Pestaña>, targetId: string): Pestaña {\n\tconst pestaña = pestañas.get(targetId);\n\tif (!pestaña || !pestaña.propia) throw new PestañaAjenaError(targetId);\n\treturn pestaña;\n}\n\n/**\n * Campos donde el agente no escribe nunca.\n *\n * Se mira el tipo, el nombre, el id y el autocomplete: un formulario puede\n * usar `type=\"text\"` con `autocomplete=\"current-password\"` para su propio\n * gestor, y sigue siendo una contraseña.\n */\nconst PISTAS_SECRETO = /pass(word|wd)?|contrase|secret|token|api[-_ ]?key|cvv|cvc|card[-_ ]?number|tarjeta|iban|ssn/i;\n\nexport interface CampoFormulario {\n\ttype?: string;\n\tname?: string;\n\tid?: string;\n\tautocomplete?: string;\n\tplaceholder?: string;\n\tariaLabel?: string;\n}\n\nexport function esCampoSecreto(campo: CampoFormulario): boolean {\n\tif ((campo.type ?? \"\").toLowerCase() === \"password\") return true;\n\treturn [campo.name, campo.id, campo.autocomplete, campo.placeholder, campo.ariaLabel].some(\n\t\t(v) => typeof v === \"string\" && PISTAS_SECRETO.test(v),\n\t);\n}\n\nexport class CampoSecretoError extends Error {\n\tconstructor() {\n\t\tsuper(\n\t\t\t\"Ese campo pide una credencial. El agente no escribe contraseñas, tokens ni datos de tarjeta: \" +\n\t\t\t\t\"escríbelo tú, o usa el gestor de contraseñas.\",\n\t\t);\n\t\tthis.name = \"CampoSecretoError\";\n\t}\n}\n\n/**\n * Acciones que no se hacen sin que una persona lo diga en el chat.\n *\n * No es una lista de botones prohibidos: es qué hay que preguntar antes. El\n * agente puede navegar y leer sin permiso; enviar, comprar o publicar, no.\n */\nexport const ACCIONES_QUE_PIDEN_PERMISO = [\n\t\"enviar un formulario\",\n\t\"publicar contenido\",\n\t\"comprar o pagar\",\n\t\"aceptar términos o consentimientos\",\n\t\"conceder permisos OAuth\",\n\t\"borrar datos\",\n] as const;\n\n/**\n * URL a las que el navegador del agente puede ir.\n *\n * Es MÁS PERMISIVA que la de `web_fetch`, y a propósito: `web_fetch` descarga\n * una URL que ha propuesto el modelo, muchas veces leída de un README, y ahí\n * `localhost` no tiene por qué ser cosa del usuario. El navegador es otra cosa:\n * mirar `http://localhost:3000` es EL caso de uso de un agente de programación.\n * Bloquearlo dejaría la herramienta sin su motivo de existir.\n *\n * Lo que sigue prohibido es lo que nunca es \"mi aplicación\":\n * - los endpoints de metadatos de nube, que devuelven credenciales de la\n *   instancia y son el objetivo clásico de un SSRF;\n * - el resto de la red privada, que son OTRAS máquinas, no la del usuario;\n * - todo lo que no sea http o https — nada de `file:`, que daría acceso al\n *   disco entero a través del navegador.\n */\nconst METADATOS_NUBE = new Set([\"169.254.169.254\", \"metadata.google.internal\", \"metadata\", \"100.100.100.200\"]);\nconst LOOPBACK = /^(?:127\\.\\d+\\.\\d+\\.\\d+|::1|localhost)$/i;\n// Incluye 127/8 a propósito, aunque el loopback se permita: la lista describe\n// \"esto no es internet público\", y la excepción se hace ARRIBA y explícita. Sin\n// el 127 aquí, la rama de loopback era código muerto — quitarla no rompía nada,\n// y una prueba que intentó romperla pasó igual.\nconst RANGOS_NO_PUBLICOS =\n\t/^(?:10\\.|127\\.|192\\.168\\.|172\\.(?:1[6-9]|2\\d|3[01])\\.|169\\.254\\.|100\\.(?:6[4-9]|[7-9]\\d|1[01]\\d|12[0-7])\\.)/;\n\nexport function urlNavegable(bruta: string): URL {\n\tlet url: URL;\n\ttry {\n\t\turl = new URL(bruta);\n\t} catch {\n\t\tthrow new Error(`URL inválida: ${bruta}`);\n\t}\n\tif (url.protocol !== \"http:\" && url.protocol !== \"https:\") {\n\t\tthrow new Error(`Solo se permiten http y https (recibido: ${url.protocol})`);\n\t}\n\tconst host = url.hostname.replace(/^\\[|\\]$/g, \"\").toLowerCase();\n\tif (METADATOS_NUBE.has(host)) {\n\t\tthrow new Error(`Bloqueado: ${host} es el endpoint de metadatos de la nube y devuelve credenciales.`);\n\t}\n\t// El loopback SÍ se permite: es la aplicación del propio usuario.\n\tif (LOOPBACK.test(host)) return url;\n\tif (RANGOS_NO_PUBLICOS.test(host)) {\n\t\tthrow new Error(`Bloqueado: ${host} es una máquina de la red interna, no tu aplicación local.`);\n\t}\n\treturn url;\n}\n\n/**\n * Texto de botones que casi siempre son irreversibles.\n *\n * Sirve para AVISAR, no para bloquear: la decisión es del usuario y una lista\n * de palabras nunca va a ser completa. Bloquear con ella daría una falsa\n * sensación de seguridad y rompería páginas legítimas.\n */\nconst TEXTO_IRREVERSIBLE =\n\t/^\\s*(enviar|send|submit|publicar|publish|post|comprar|buy|pagar|pay|confirmar|confirm|borrar|delete|eliminar|aceptar|accept|agree|allow|permitir)\\b/i;\n\nexport function pareceIrreversible(textoDelBoton: string): boolean {\n\treturn TEXTO_IRREVERSIBLE.test(textoDelBoton);\n}\n"]}

package/dist/core/browser/politica.js

@@ -0,0 +1,123 @@
+/**
+ * Reglas del navegador. Puro: sin sockets ni procesos.
+ *
+ * Un agente que conduce un navegador es la superficie más peligrosa que tiene
+ * este producto: hay sesiones iniciadas, cookies, correo y banca detrás de las
+ * pestañas que ya están abiertas. Por eso las reglas viven aparte y se prueban
+ * solas, en vez de estar repartidas por el código que habla con Chrome.
+ *
+ * Las tres:
+ *
+ * 1. **Solo se conducen las pestañas que abrió el agente.** Nunca las del
+ *    usuario. Es la regla que copiamos de ZCode y la más importante: sin ella,
+ *    "resume esta página" puede acabar leyendo el banco.
+ * 2. **Las URL pasan por la misma guarda SSRF que `web_fetch`.** Un navegador
+ *    que puede ir a `169.254.169.254` es una fuga de credenciales de nube.
+ * 3. **Nunca se escribe en un campo de contraseña.** Ni aunque se lo pidan.
+ */
+export class PestañaAjenaError extends Error {
+    constructor(targetId) {
+        super(`La pestaña ${targetId} no la abrió el agente. Solo se pueden conducir pestañas abiertas con browser_open; ` +
+            `las del usuario tienen sesiones iniciadas detrás.`);
+        this.name = "PestañaAjenaError";
+    }
+}
+/** Lanza si la pestaña no es del agente. Ver regla 1. */
+export function exigirPestañaPropia(pestañas, targetId) {
+    const pestaña = pestañas.get(targetId);
+    if (!pestaña || !pestaña.propia)
+        throw new PestañaAjenaError(targetId);
+    return pestaña;
+}
+/**
+ * Campos donde el agente no escribe nunca.
+ *
+ * Se mira el tipo, el nombre, el id y el autocomplete: un formulario puede
+ * usar `type="text"` con `autocomplete="current-password"` para su propio
+ * gestor, y sigue siendo una contraseña.
+ */
+const PISTAS_SECRETO = /pass(word|wd)?|contrase|secret|token|api[-_ ]?key|cvv|cvc|card[-_ ]?number|tarjeta|iban|ssn/i;
+export function esCampoSecreto(campo) {
+    if ((campo.type ?? "").toLowerCase() === "password")
+        return true;
+    return [campo.name, campo.id, campo.autocomplete, campo.placeholder, campo.ariaLabel].some((v) => typeof v === "string" && PISTAS_SECRETO.test(v));
+}
+export class CampoSecretoError extends Error {
+    constructor() {
+        super("Ese campo pide una credencial. El agente no escribe contraseñas, tokens ni datos de tarjeta: " +
+            "escríbelo tú, o usa el gestor de contraseñas.");
+        this.name = "CampoSecretoError";
+    }
+}
+/**
+ * Acciones que no se hacen sin que una persona lo diga en el chat.
+ *
+ * No es una lista de botones prohibidos: es qué hay que preguntar antes. El
+ * agente puede navegar y leer sin permiso; enviar, comprar o publicar, no.
+ */
+export const ACCIONES_QUE_PIDEN_PERMISO = [
+    "enviar un formulario",
+    "publicar contenido",
+    "comprar o pagar",
+    "aceptar términos o consentimientos",
+    "conceder permisos OAuth",
+    "borrar datos",
+];
+/**
+ * URL a las que el navegador del agente puede ir.
+ *
+ * Es MÁS PERMISIVA que la de `web_fetch`, y a propósito: `web_fetch` descarga
+ * una URL que ha propuesto el modelo, muchas veces leída de un README, y ahí
+ * `localhost` no tiene por qué ser cosa del usuario. El navegador es otra cosa:
+ * mirar `http://localhost:3000` es EL caso de uso de un agente de programación.
+ * Bloquearlo dejaría la herramienta sin su motivo de existir.
+ *
+ * Lo que sigue prohibido es lo que nunca es "mi aplicación":
+ * - los endpoints de metadatos de nube, que devuelven credenciales de la
+ *   instancia y son el objetivo clásico de un SSRF;
+ * - el resto de la red privada, que son OTRAS máquinas, no la del usuario;
+ * - todo lo que no sea http o https — nada de `file:`, que daría acceso al
+ *   disco entero a través del navegador.
+ */
+const METADATOS_NUBE = new Set(["169.254.169.254", "metadata.google.internal", "metadata", "100.100.100.200"]);
+const LOOPBACK = /^(?:127\.\d+\.\d+\.\d+|::1|localhost)$/i;
+// Incluye 127/8 a propósito, aunque el loopback se permita: la lista describe
+// "esto no es internet público", y la excepción se hace ARRIBA y explícita. Sin
+// el 127 aquí, la rama de loopback era código muerto — quitarla no rompía nada,
+// y una prueba que intentó romperla pasó igual.
+const RANGOS_NO_PUBLICOS = /^(?:10\.|127\.|192\.168\.|172\.(?:1[6-9]|2\d|3[01])\.|169\.254\.|100\.(?:6[4-9]|[7-9]\d|1[01]\d|12[0-7])\.)/;
+export function urlNavegable(bruta) {
+    let url;
+    try {
+        url = new URL(bruta);
+    }
+    catch {
+        throw new Error(`URL inválida: ${bruta}`);
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new Error(`Solo se permiten http y https (recibido: ${url.protocol})`);
+    }
+    const host = url.hostname.replace(/^\[|\]$/g, "").toLowerCase();
+    if (METADATOS_NUBE.has(host)) {
+        throw new Error(`Bloqueado: ${host} es el endpoint de metadatos de la nube y devuelve credenciales.`);
+    }
+    // El loopback SÍ se permite: es la aplicación del propio usuario.
+    if (LOOPBACK.test(host))
+        return url;
+    if (RANGOS_NO_PUBLICOS.test(host)) {
+        throw new Error(`Bloqueado: ${host} es una máquina de la red interna, no tu aplicación local.`);
+    }
+    return url;
+}
+/**
+ * Texto de botones que casi siempre son irreversibles.
+ *
+ * Sirve para AVISAR, no para bloquear: la decisión es del usuario y una lista
+ * de palabras nunca va a ser completa. Bloquear con ella daría una falsa
+ * sensación de seguridad y rompería páginas legítimas.
+ */
+const TEXTO_IRREVERSIBLE = /^\s*(enviar|send|submit|publicar|publish|post|comprar|buy|pagar|pay|confirmar|confirm|borrar|delete|eliminar|aceptar|accept|agree|allow|permitir)\b/i;
+export function pareceIrreversible(textoDelBoton) {
+    return TEXTO_IRREVERSIBLE.test(textoDelBoton);
+}
+//# sourceMappingURL=politica.js.map

package/dist/core/browser/politica.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"politica.js","sourceRoot":"","sources":["../../../src/core/browser/politica.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAUH,MAAM,OAAO,kBAAkB,SAAQ,KAAK;IAC3C,YAAY,QAAgB,EAAE;QAC7B,KAAK,CACJ,eAAc,QAAQ,wFAAsF;YAC3G,oDAAmD,CACpD,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,oBAAmB,CAAC;IAAA,CAChC;CACD;AAED,0DAAyD;AACzD,MAAM,UAAU,oBAAmB,CAAC,SAA8B,EAAE,QAAgB,EAAW;IAC9F,MAAM,QAAO,GAAG,SAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACvC,IAAI,CAAC,QAAO,IAAI,CAAC,QAAO,CAAC,MAAM;QAAE,MAAM,IAAI,kBAAiB,CAAC,QAAQ,CAAC,CAAC;IACvE,OAAO,QAAO,CAAC;AAAA,CACf;AAED;;;;;;GAMG;AACH,MAAM,cAAc,GAAG,8FAA8F,CAAC;AAWtH,MAAM,UAAU,cAAc,CAAC,KAAsB,EAAW;IAC/D,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,KAAK,UAAU;QAAE,OAAO,IAAI,CAAC;IACjE,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,YAAY,EAAE,KAAK,CAAC,WAAW,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,IAAI,CACzF,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,CACtD,CAAC;AAAA,CACF;AAED,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC3C,cAAc;QACb,KAAK,CACJ,gGAA+F;YAC9F,kDAA+C,CAChD,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAAA,CAChC;CACD;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG;IACzC,sBAAsB;IACtB,oBAAoB;IACpB,iBAAiB;IACjB,qCAAoC;IACpC,yBAAyB;IACzB,cAAc;CACL,CAAC;AAEX;;;;;;;;;;;;;;;GAeG;AACH,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC,CAAC,iBAAiB,EAAE,0BAA0B,EAAE,UAAU,EAAE,iBAAiB,CAAC,CAAC,CAAC;AAC/G,MAAM,QAAQ,GAAG,yCAAyC,CAAC;AAC3D,+EAA8E;AAC9E,mFAAgF;AAChF,qFAAgF;AAChF,kDAAgD;AAChD,MAAM,kBAAkB,GACvB,6GAA6G,CAAC;AAE/G,MAAM,UAAU,YAAY,CAAC,KAAa,EAAO;IAChD,IAAI,GAAQ,CAAC;IACb,IAAI,CAAC;QACJ,GAAG,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;IAAC,MAAM,CAAC;QACR,MAAM,IAAI,KAAK,CAAC,kBAAiB,KAAK,EAAE,CAAC,CAAC;IAC3C,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,KAAK,OAAO,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC3D,MAAM,IAAI,KAAK,CAAC,4CAA4C,GAAG,CAAC,QAAQ,GAAG,CAAC,CAAC;IAC9E,CAAC;IACD,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;IAChE,IAAI,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,cAAc,IAAI,kEAAkE,CAAC,CAAC;IACvG,CAAC;IACD,oEAAkE;IAClE,IAAI,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,GAAG,CAAC;IACpC,IAAI,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,KAAK,CAAC,cAAc,IAAI,8DAA4D,CAAC,CAAC;IACjG,CAAC;IACD,OAAO,GAAG,CAAC;AAAA,CACX;AAED;;;;;;GAMG;AACH,MAAM,kBAAkB,GACvB,sJAAsJ,CAAC;AAExJ,MAAM,UAAU,kBAAkB,CAAC,aAAqB,EAAW;IAClE,OAAO,kBAAkB,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;AAAA,CAC9C","sourcesContent":["/**\n * Reglas del navegador. Puro: sin sockets ni procesos.\n *\n * Un agente que conduce un navegador es la superficie más peligrosa que tiene\n * este producto: hay sesiones iniciadas, cookies, correo y banca detrás de las\n * pestañas que ya están abiertas. Por eso las reglas viven aparte y se prueban\n * solas, en vez de estar repartidas por el código que habla con Chrome.\n *\n * Las tres:\n *\n * 1. **Solo se conducen las pestañas que abrió el agente.** Nunca las del\n *    usuario. Es la regla que copiamos de ZCode y la más importante: sin ella,\n *    \"resume esta página\" puede acabar leyendo el banco.\n * 2. **Las URL pasan por la misma guarda SSRF que `web_fetch`.** Un navegador\n *    que puede ir a `169.254.169.254` es una fuga de credenciales de nube.\n * 3. **Nunca se escribe en un campo de contraseña.** Ni aunque se lo pidan.\n */\n\n/** Una pestaña conocida por el agente. */\nexport interface Pestaña {\n\ttargetId: string;\n\turl: string;\n\t/** `true` solo si la abrió el agente. */\n\tpropia: boolean;\n}\n\nexport class PestañaAjenaError extends Error {\n\tconstructor(targetId: string) {\n\t\tsuper(\n\t\t\t`La pestaña ${targetId} no la abrió el agente. Solo se pueden conducir pestañas abiertas con browser_open; ` +\n\t\t\t\t`las del usuario tienen sesiones iniciadas detrás.`,\n\t\t);\n\t\tthis.name = \"PestañaAjenaError\";\n\t}\n}\n\n/** Lanza si la pestaña no es del agente. Ver regla 1. */\nexport function exigirPestañaPropia(pestañas: Map<string, Pestaña>, targetId: string): Pestaña {\n\tconst pestaña = pestañas.get(targetId);\n\tif (!pestaña || !pestaña.propia) throw new PestañaAjenaError(targetId);\n\treturn pestaña;\n}\n\n/**\n * Campos donde el agente no escribe nunca.\n *\n * Se mira el tipo, el nombre, el id y el autocomplete: un formulario puede\n * usar `type=\"text\"` con `autocomplete=\"current-password\"` para su propio\n * gestor, y sigue siendo una contraseña.\n */\nconst PISTAS_SECRETO = /pass(word|wd)?|contrase|secret|token|api[-_ ]?key|cvv|cvc|card[-_ ]?number|tarjeta|iban|ssn/i;\n\nexport interface CampoFormulario {\n\ttype?: string;\n\tname?: string;\n\tid?: string;\n\tautocomplete?: string;\n\tplaceholder?: string;\n\tariaLabel?: string;\n}\n\nexport function esCampoSecreto(campo: CampoFormulario): boolean {\n\tif ((campo.type ?? \"\").toLowerCase() === \"password\") return true;\n\treturn [campo.name, campo.id, campo.autocomplete, campo.placeholder, campo.ariaLabel].some(\n\t\t(v) => typeof v === \"string\" && PISTAS_SECRETO.test(v),\n\t);\n}\n\nexport class CampoSecretoError extends Error {\n\tconstructor() {\n\t\tsuper(\n\t\t\t\"Ese campo pide una credencial. El agente no escribe contraseñas, tokens ni datos de tarjeta: \" +\n\t\t\t\t\"escríbelo tú, o usa el gestor de contraseñas.\",\n\t\t);\n\t\tthis.name = \"CampoSecretoError\";\n\t}\n}\n\n/**\n * Acciones que no se hacen sin que una persona lo diga en el chat.\n *\n * No es una lista de botones prohibidos: es qué hay que preguntar antes. El\n * agente puede navegar y leer sin permiso; enviar, comprar o publicar, no.\n */\nexport const ACCIONES_QUE_PIDEN_PERMISO = [\n\t\"enviar un formulario\",\n\t\"publicar contenido\",\n\t\"comprar o pagar\",\n\t\"aceptar términos o consentimientos\",\n\t\"conceder permisos OAuth\",\n\t\"borrar datos\",\n] as const;\n\n/**\n * URL a las que el navegador del agente puede ir.\n *\n * Es MÁS PERMISIVA que la de `web_fetch`, y a propósito: `web_fetch` descarga\n * una URL que ha propuesto el modelo, muchas veces leída de un README, y ahí\n * `localhost` no tiene por qué ser cosa del usuario. El navegador es otra cosa:\n * mirar `http://localhost:3000` es EL caso de uso de un agente de programación.\n * Bloquearlo dejaría la herramienta sin su motivo de existir.\n *\n * Lo que sigue prohibido es lo que nunca es \"mi aplicación\":\n * - los endpoints de metadatos de nube, que devuelven credenciales de la\n *   instancia y son el objetivo clásico de un SSRF;\n * - el resto de la red privada, que son OTRAS máquinas, no la del usuario;\n * - todo lo que no sea http o https — nada de `file:`, que daría acceso al\n *   disco entero a través del navegador.\n */\nconst METADATOS_NUBE = new Set([\"169.254.169.254\", \"metadata.google.internal\", \"metadata\", \"100.100.100.200\"]);\nconst LOOPBACK = /^(?:127\\.\\d+\\.\\d+\\.\\d+|::1|localhost)$/i;\n// Incluye 127/8 a propósito, aunque el loopback se permita: la lista describe\n// \"esto no es internet público\", y la excepción se hace ARRIBA y explícita. Sin\n// el 127 aquí, la rama de loopback era código muerto — quitarla no rompía nada,\n// y una prueba que intentó romperla pasó igual.\nconst RANGOS_NO_PUBLICOS =\n\t/^(?:10\\.|127\\.|192\\.168\\.|172\\.(?:1[6-9]|2\\d|3[01])\\.|169\\.254\\.|100\\.(?:6[4-9]|[7-9]\\d|1[01]\\d|12[0-7])\\.)/;\n\nexport function urlNavegable(bruta: string): URL {\n\tlet url: URL;\n\ttry {\n\t\turl = new URL(bruta);\n\t} catch {\n\t\tthrow new Error(`URL inválida: ${bruta}`);\n\t}\n\tif (url.protocol !== \"http:\" && url.protocol !== \"https:\") {\n\t\tthrow new Error(`Solo se permiten http y https (recibido: ${url.protocol})`);\n\t}\n\tconst host = url.hostname.replace(/^\\[|\\]$/g, \"\").toLowerCase();\n\tif (METADATOS_NUBE.has(host)) {\n\t\tthrow new Error(`Bloqueado: ${host} es el endpoint de metadatos de la nube y devuelve credenciales.`);\n\t}\n\t// El loopback SÍ se permite: es la aplicación del propio usuario.\n\tif (LOOPBACK.test(host)) return url;\n\tif (RANGOS_NO_PUBLICOS.test(host)) {\n\t\tthrow new Error(`Bloqueado: ${host} es una máquina de la red interna, no tu aplicación local.`);\n\t}\n\treturn url;\n}\n\n/**\n * Texto de botones que casi siempre son irreversibles.\n *\n * Sirve para AVISAR, no para bloquear: la decisión es del usuario y una lista\n * de palabras nunca va a ser completa. Bloquear con ella daría una falsa\n * sensación de seguridad y rompería páginas legítimas.\n */\nconst TEXTO_IRREVERSIBLE =\n\t/^\\s*(enviar|send|submit|publicar|publish|post|comprar|buy|pagar|pay|confirmar|confirm|borrar|delete|eliminar|aceptar|accept|agree|allow|permitir)\\b/i;\n\nexport function pareceIrreversible(textoDelBoton: string): boolean {\n\treturn TEXTO_IRREVERSIBLE.test(textoDelBoton);\n}\n"]}

package/dist/core/browser/sesion.d.ts

@@ -0,0 +1,52 @@
+/**
+ * El navegador del agente.
+ *
+ * Arranca Chrome con un **perfil propio y vacío** (`--user-data-dir` dentro de
+ * `<agentDir>/browser`). Eso no es un detalle de limpieza: convierte la regla
+ * de "solo se conducen las pestañas del agente" en algo estructural en vez de
+ * una promesa. En ese perfil no hay cookies, ni sesiones iniciadas, ni el
+ * correo del usuario — aunque el agente se equivoque, no hay nada que filtrar.
+ *
+ * El precio es que no puede usar sitios donde el usuario ya está identificado.
+ * Es el precio correcto: la alternativa es un agente con acceso al banco.
+ */
+import { type Pestaña } from "./politica.ts";
+export declare function buscarNavegador(candidatos?: string[]): string | null;
+export interface OpcionesNavegador {
+    agentDir: string;
+    /** 0 = que el sistema elija uno libre, que es lo que queremos. */
+    puerto?: number;
+    headless?: boolean;
+    ejecutable?: string;
+    /** Ancho y alto iniciales; `browser_viewport` los cambia después. */
+    viewport?: {
+        width: number;
+        height: number;
+    };
+}
+export declare class NavegadorAgente {
+    private proceso;
+    private cliente;
+    private pestañas;
+    private sesionesPorTarget;
+    private viewport;
+    private constructor();
+    static abrir(opciones: OpcionesNavegador): Promise<NavegadorAgente>;
+    private exigirCliente;
+    /** Abre una pestaña NUEVA. Es la única forma de que el agente tenga una. */
+    abrirPestaña(url: string): Promise<Pestaña>;
+    private sesionDe;
+    navegar(targetId: string, url: string): Promise<void>;
+    /** Evalúa JavaScript en la pestaña y devuelve el valor serializado. */
+    evaluar<T = unknown>(targetId: string, expresion: string): Promise<T>;
+    capturar(targetId: string): Promise<string>;
+    cambiarViewport(targetId: string, width: number, height: number, movil?: boolean): Promise<void>;
+    get viewportActual(): {
+        width: number;
+        height: number;
+    };
+    cerrarPestaña(targetId: string): Promise<void>;
+    listarPestañas(): Pestaña[];
+    cerrar(): void;
+}
+//# sourceMappingURL=sesion.d.ts.map

package/dist/core/browser/sesion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sesion.d.ts","sourceRoot":"","sources":["../../../src/core/browser/sesion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,OAAO,EAAuB,KAAK,QAAO,EAAE,MAAM,eAAe,CAAC;AAclE,wBAAgB,eAAe,CAAC,UAAU,GAAE,MAAM,EAAsB,GAAG,MAAM,GAAG,IAAI,CAEvF;AAED,MAAM,WAAW,iBAAiB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,kEAAkE;IAClE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sEAAqE;IACrE,QAAQ,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7C;AAED,qBAAa,eAAe;IAC3B,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,OAAO,CAA2B;IAC1C,OAAO,CAAC,SAAQ,CAA8B;IAC9C,OAAO,CAAC,iBAAiB,CAA6B;IAItD,OAAO,CAAC,QAAQ,CAAoC;IAEpD,OAAO,eAIN;IAED,OAAa,KAAK,CAAC,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAAC,eAAe,CAAC,CAiCxE;IAED,OAAO,CAAC,aAAa;IAKrB,8EAA4E;IACtE,aAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,QAAO,CAAC,CAahD;IAED,OAAO,CAAC,QAAQ;IAOV,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAK1D;IAED,yEAAuE;IACjE,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAc1E;IAEK,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAQhD;IAEK,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,UAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAQnG;IAED,IAAI,cAAc,IAAI;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAEtD;IAEK,cAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAKnD;IAED,eAAc,IAAI,QAAO,EAAE,CAE1B;IAED,MAAM,IAAI,IAAI,CAOb;CACD","sourcesContent":["/**\n * El navegador del agente.\n *\n * Arranca Chrome con un **perfil propio y vacío** (`--user-data-dir` dentro de\n * `<agentDir>/browser`). Eso no es un detalle de limpieza: convierte la regla\n * de \"solo se conducen las pestañas del agente\" en algo estructural en vez de\n * una promesa. En ese perfil no hay cookies, ni sesiones iniciadas, ni el\n * correo del usuario — aunque el agente se equivoque, no hay nada que filtrar.\n *\n * El precio es que no puede usar sitios donde el usuario ya está identificado.\n * Es el precio correcto: la alternativa es un agente con acceso al banco.\n */\n\nimport { type ChildProcess, spawn } from \"node:child_process\";\nimport { existsSync, mkdirSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { ClienteCdp } from \"./cdp.ts\";\nimport { exigirPestañaPropia, type Pestaña } from \"./politica.ts\";\n\nconst CANDIDATOS_CHROME = [\n\t\"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome\",\n\t\"/Applications/Chromium.app/Contents/MacOS/Chromium\",\n\t\"/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge\",\n\t\"/Applications/Brave Browser.app/Contents/MacOS/Brave Browser\",\n\t\"/usr/bin/google-chrome\",\n\t\"/usr/bin/chromium\",\n\t\"/usr/bin/chromium-browser\",\n\t\"C:\\\\Program Files\\\\Google\\\\Chrome\\\\Application\\\\chrome.exe\",\n\t\"C:\\\\Program Files (x86)\\\\Google\\\\Chrome\\\\Application\\\\chrome.exe\",\n];\n\nexport function buscarNavegador(candidatos: string[] = CANDIDATOS_CHROME): string | null {\n\treturn candidatos.find((ruta) => existsSync(ruta)) ?? null;\n}\n\nexport interface OpcionesNavegador {\n\tagentDir: string;\n\t/** 0 = que el sistema elija uno libre, que es lo que queremos. */\n\tpuerto?: number;\n\theadless?: boolean;\n\tejecutable?: string;\n\t/** Ancho y alto iniciales; `browser_viewport` los cambia después. */\n\tviewport?: { width: number; height: number };\n}\n\nexport class NavegadorAgente {\n\tprivate proceso: ChildProcess | null = null;\n\tprivate cliente: ClienteCdp | null = null;\n\tprivate pestañas = new Map<string, Pestaña>();\n\tprivate sesionesPorTarget = new Map<string, string>();\n\n\t// Campo normal y no propiedad de constructor: el repo compila con\n\t// `erasableSyntaxOnly`, que prohíbe la forma corta.\n\tprivate viewport: { width: number; height: number };\n\n\tprivate constructor(proceso: ChildProcess, cliente: ClienteCdp, viewport: { width: number; height: number }) {\n\t\tthis.proceso = proceso;\n\t\tthis.cliente = cliente;\n\t\tthis.viewport = viewport;\n\t}\n\n\tstatic async abrir(opciones: OpcionesNavegador): Promise<NavegadorAgente> {\n\t\tconst ejecutable = opciones.ejecutable ?? buscarNavegador();\n\t\tif (!ejecutable) {\n\t\t\tthrow new Error(\n\t\t\t\t\"No se encontró Chrome, Chromium, Edge ni Brave. Instala uno o pasa la ruta en la configuración.\",\n\t\t\t);\n\t\t}\n\t\tconst perfil = join(opciones.agentDir, \"browser\", \"perfil\");\n\t\tmkdirSync(perfil, { recursive: true, mode: 0o700 });\n\t\tconst viewport = opciones.viewport ?? { width: 1280, height: 800 };\n\n\t\tconst puerto = opciones.puerto ?? 0;\n\t\tconst proceso = spawn(\n\t\t\tejecutable,\n\t\t\t[\n\t\t\t\t`--remote-debugging-port=${puerto}`,\n\t\t\t\t// Perfil propio y vacío: ver la cabecera del fichero.\n\t\t\t\t`--user-data-dir=${perfil}`,\n\t\t\t\t\"--no-first-run\",\n\t\t\t\t\"--no-default-browser-check\",\n\t\t\t\t// Sin esto, Chrome puede reutilizar una instancia ya abierta del\n\t\t\t\t// usuario y acabaríamos conduciendo SU navegador.\n\t\t\t\t\"--disable-features=ChromeWhatsNewUI\",\n\t\t\t\t`--window-size=${viewport.width},${viewport.height}`,\n\t\t\t\t...(opciones.headless ? [\"--headless=new\"] : []),\n\t\t\t\t\"about:blank\",\n\t\t\t],\n\t\t\t{ stdio: [\"ignore\", \"ignore\", \"pipe\"] },\n\t\t);\n\n\t\tconst urlWs = await leerUrlDevTools(proceso);\n\t\tconst cliente = await ClienteCdp.conectar(urlWs);\n\t\treturn new NavegadorAgente(proceso, cliente, viewport);\n\t}\n\n\tprivate exigirCliente(): ClienteCdp {\n\t\tif (!this.cliente) throw new Error(\"el navegador está cerrado\");\n\t\treturn this.cliente;\n\t}\n\n\t/** Abre una pestaña NUEVA. Es la única forma de que el agente tenga una. */\n\tasync abrirPestaña(url: string): Promise<Pestaña> {\n\t\tconst cliente = this.exigirCliente();\n\t\tconst { targetId } = await cliente.enviar<{ targetId: string }>(\"Target.createTarget\", { url });\n\t\tconst { sessionId } = await cliente.enviar<{ sessionId: string }>(\"Target.attachToTarget\", {\n\t\t\ttargetId,\n\t\t\tflatten: true,\n\t\t});\n\t\tthis.sesionesPorTarget.set(targetId, sessionId);\n\t\tconst pestaña: Pestaña = { targetId, url, propia: true };\n\t\tthis.pestañas.set(targetId, pestaña);\n\t\tawait cliente.enviar(\"Page.enable\", {}, sessionId);\n\t\tawait cliente.enviar(\"Runtime.enable\", {}, sessionId);\n\t\treturn pestaña;\n\t}\n\n\tprivate sesionDe(targetId: string): string {\n\t\texigirPestañaPropia(this.pestañas, targetId);\n\t\tconst sessionId = this.sesionesPorTarget.get(targetId);\n\t\tif (!sessionId) throw new Error(`la pestaña ${targetId} no está conectada`);\n\t\treturn sessionId;\n\t}\n\n\tasync navegar(targetId: string, url: string): Promise<void> {\n\t\tconst sessionId = this.sesionDe(targetId);\n\t\tawait this.exigirCliente().enviar(\"Page.navigate\", { url }, sessionId);\n\t\tconst pestaña = this.pestañas.get(targetId);\n\t\tif (pestaña) pestaña.url = url;\n\t}\n\n\t/** Evalúa JavaScript en la pestaña y devuelve el valor serializado. */\n\tasync evaluar<T = unknown>(targetId: string, expresion: string): Promise<T> {\n\t\tconst sessionId = this.sesionDe(targetId);\n\t\tconst respuesta = await this.exigirCliente().enviar<{\n\t\t\tresult?: { value?: T };\n\t\t\texceptionDetails?: { text?: string; exception?: { description?: string } };\n\t\t}>(\"Runtime.evaluate\", { expression: expresion, returnByValue: true, awaitPromise: true }, sessionId);\n\t\tif (respuesta.exceptionDetails) {\n\t\t\tthrow new Error(\n\t\t\t\trespuesta.exceptionDetails.exception?.description ??\n\t\t\t\t\trespuesta.exceptionDetails.text ??\n\t\t\t\t\t\"error en la página\",\n\t\t\t);\n\t\t}\n\t\treturn respuesta.result?.value as T;\n\t}\n\n\tasync capturar(targetId: string): Promise<string> {\n\t\tconst sessionId = this.sesionDe(targetId);\n\t\tconst { data } = await this.exigirCliente().enviar<{ data: string }>(\n\t\t\t\"Page.captureScreenshot\",\n\t\t\t{ format: \"png\" },\n\t\t\tsessionId,\n\t\t);\n\t\treturn data;\n\t}\n\n\tasync cambiarViewport(targetId: string, width: number, height: number, movil = false): Promise<void> {\n\t\tconst sessionId = this.sesionDe(targetId);\n\t\tawait this.exigirCliente().enviar(\n\t\t\t\"Emulation.setDeviceMetricsOverride\",\n\t\t\t{ width, height, deviceScaleFactor: 1, mobile: movil },\n\t\t\tsessionId,\n\t\t);\n\t\tthis.viewport = { width, height };\n\t}\n\n\tget viewportActual(): { width: number; height: number } {\n\t\treturn { ...this.viewport };\n\t}\n\n\tasync cerrarPestaña(targetId: string): Promise<void> {\n\t\tthis.sesionDe(targetId);\n\t\tawait this.exigirCliente().enviar(\"Target.closeTarget\", { targetId });\n\t\tthis.pestañas.delete(targetId);\n\t\tthis.sesionesPorTarget.delete(targetId);\n\t}\n\n\tlistarPestañas(): Pestaña[] {\n\t\treturn [...this.pestañas.values()];\n\t}\n\n\tcerrar(): void {\n\t\tthis.cliente?.cerrar();\n\t\tthis.cliente = null;\n\t\tthis.proceso?.kill();\n\t\tthis.proceso = null;\n\t\tthis.pestañas.clear();\n\t\tthis.sesionesPorTarget.clear();\n\t}\n}\n\n/**\n * Lee la URL de DevTools que Chrome escribe en stderr al arrancar.\n *\n * Se lee del proceso en vez de sondear `http://localhost:<puerto>/json/version`\n * porque con `--remote-debugging-port=0` el puerto lo elige el sistema y no lo\n * sabemos de antemano. Sondear un puerto fijo, además, podría acertar con una\n * instancia de Chrome que ya tuviera el usuario abierta — y acabaríamos\n * conduciendo su navegador con sus sesiones.\n */\nfunction leerUrlDevTools(proceso: ChildProcess, timeoutMs = 15_000): Promise<string> {\n\treturn new Promise((resolve, reject) => {\n\t\tlet acumulado = \"\";\n\t\tconst temporizador = setTimeout(() => {\n\t\t\treject(new Error(`el navegador no anunció su puerto de depuración en ${timeoutMs} ms`));\n\t\t}, timeoutMs);\n\n\t\tconst terminar = (fn: () => void) => {\n\t\t\tclearTimeout(temporizador);\n\t\t\tfn();\n\t\t};\n\n\t\tproceso.stderr?.on(\"data\", (trozo: Buffer) => {\n\t\t\tacumulado += trozo.toString(\"utf8\");\n\t\t\tconst encontrado = acumulado.match(/ws:\\/\\/[^\\s]+/);\n\t\t\tif (encontrado) terminar(() => resolve(encontrado[0]));\n\t\t});\n\t\tproceso.on(\"error\", (error) => terminar(() => reject(error)));\n\t\tproceso.on(\"exit\", (codigo) =>\n\t\t\tterminar(() => reject(new Error(`el navegador se cerró con código ${codigo} antes de arrancar`))),\n\t\t);\n\t});\n}\n"]}