@hoilab/ada-cli 0.84.22 → 0.85.1

package/dist/core/credenciales/pool.js

@@ -0,0 +1,177 @@
+/**
+ * Piscina de credenciales por proveedor.
+ *
+ * El hueco que esto tapa: hoy cada desarrollador tiene sus claves en su propio
+ * portátil. `oh-my-pi` (packages/ai/src/auth-broker de ese repo) resuelve esto
+ * con un servidor que guarda las credenciales y las reparte; lo que se copia
+ * aquí de su diseño son dos decisiones concretas, no el código:
+ *
+ * 1. **Conmutación a una hermana cuando una cuenta falla de verdad.** Un 401
+ *    (`credencial-invalida` o `sin-credencial` en la taxonomía de
+ *    `../errores/proveedor.ts`) saca la credencial del pool: la siguiente
+ *    petición usa otra. Un 429 (`limite-de-tasa`) NO la saca — la cuenta sigue
+ *    siendo buena, solo está ocupada un rato. Confundir los dos es el fallo
+ *    que quema cuentas sanas: se ha visto documentado en el propio
+ *    `errores/proveedor.ts` como el error más caro de mezclar.
+ * 2. **Pegajosidad por sesión vía `prompt_cache_key`.** Sin esto, repartir
+ *    entre cuentas rompería el caché de prompts del proveedor en cada turno —
+ *    cada petición de la misma conversación pagaría el prefijo entero de
+ *    nuevo. Una `prompt_cache_key` se queda pegada a la misma credencial
+ *    mientras esa credencial siga activa; solo se realoja cuando la que tenía
+ *    pegada se bloquea.
+ *
+ * Lo que NO se copia: el pool vive en memoria del proceso `ada-cli serve
+ * --broker`, no en SQLite. Reiniciar el broker olvida qué estaba bloqueado y
+ * la pegajosidad — aceptable para el alcance de hoy (equipos pequeños, un
+ * broker por equipo); si hace falta sobrevivir a reinicios, el punto de
+ * extensión es cargar/guardar `estado()` a un fichero en `iniciar`/`cerrar`.
+ */
+import { clasificarError } from "../errores/proveedor.js";
+import { huellaDeCredencial } from "./ratelimit.js";
+function publica(fila) {
+    return { id: fila.id, proveedor: fila.proveedor, estado: fila.estado, motivoBloqueo: fila.motivoBloqueo };
+}
+export class CredencialPool {
+    porId = new Map();
+    porProveedor = new Map();
+    /** `proveedor\0promptCacheKey` -> id de la credencial pegada a esa sesión. */
+    pegajosidad = new Map();
+    /** Cursor de reparto round-robin por proveedor, para las peticiones sin pegajosidad. */
+    cursores = new Map();
+    /** Contador de usos reportados por credencial (memoria; alimenta el ranking). */
+    usos = new Map();
+    selector;
+    constructor(credenciales, opciones) {
+        this.selector = opciones?.selector;
+        for (const [proveedor, lista] of Object.entries(credenciales)) {
+            const filas = lista.map((c) => ({ ...c, proveedor, estado: "activa" }));
+            this.porProveedor.set(proveedor, filas);
+            for (const fila of filas)
+                this.porId.set(fila.id, fila);
+        }
+    }
+    clavePegajosidad(proveedor, promptCacheKey) {
+        return `${proveedor} ${promptCacheKey}`;
+    }
+    siguiente(proveedor, activas) {
+        const cursor = this.cursores.get(proveedor) ?? 0;
+        this.cursores.set(proveedor, cursor + 1);
+        return activas[cursor % activas.length];
+    }
+    /**
+     * Elige una credencial activa para `proveedor`.
+     *
+     * Sin `promptCacheKey`: reparto round-robin entre las activas. Con
+     * `promptCacheKey`: si la sesión ya tenía una credencial pegada y sigue
+     * activa, se reutiliza (no rompe el caché de prompts); si no, se elige una
+     * nueva y se fija para las próximas llamadas con la misma clave.
+     *
+     * `null` = no hay ninguna credencial activa para ese proveedor. Es "no hay
+     * nada", no "no he podido" — todas las filas existen, todas están
+     * bloqueadas, y decirlo así es lo que distingue esto de un fallo del pool.
+     */
+    elegir(proveedor, promptCacheKey) {
+        const filas = this.porProveedor.get(proveedor) ?? [];
+        const activas = filas.filter((f) => f.estado === "activa");
+        if (activas.length === 0)
+            return null;
+        if (this.selector) {
+            // El hook decide entre las activas y su veredicto es FINAL: si dice
+            // «ninguna sirve» (todas enfriadas por rate-limit, p. ej.), el pool
+            // devuelve null en vez de colarse al round-robin y entregar justo la
+            // cuenta que el proveedor nos pidió descansar. La pegajosa activa
+            // viaja en el contexto; si el hook la fija, se ancla igual que el
+            // camino por defecto — misma promesa de caché de prompts.
+            const pegajosaId = promptCacheKey ? this.filaPegadaActiva(proveedor, promptCacheKey)?.id : undefined;
+            const idDelHook = this.selector(activas.map(publica), {
+                usoReciente: this.usosSnapshot(),
+                rotacion: () => this.siguiente(proveedor, activas).id,
+                huella: (id) => this.huellaDe(id),
+                pegajosaId,
+            });
+            if (!idDelHook)
+                return null;
+            const filaHook = this.porId.get(idDelHook);
+            if (!filaHook || filaHook.estado !== "activa")
+                return null;
+            if (promptCacheKey)
+                this.pegajosidad.set(this.clavePegajosidad(proveedor, promptCacheKey), filaHook.id);
+            return { id: filaHook.id, proveedor, valor: filaHook.valor };
+        }
+        if (promptCacheKey) {
+            const clave = this.clavePegajosidad(proveedor, promptCacheKey);
+            const idPegado = this.pegajosidad.get(clave);
+            const fila = idPegado ? this.porId.get(idPegado) : undefined;
+            if (fila && fila.estado === "activa") {
+                return { id: fila.id, proveedor, valor: fila.valor };
+            }
+            // Sin pegajosidad válida (primera vez, o la que tenía pegada se bloqueó):
+            // elige una hermana y la fija para las próximas peticiones de esta sesión.
+            const elegida = this.siguiente(proveedor, activas);
+            this.pegajosidad.set(clave, elegida.id);
+            return { id: elegida.id, proveedor, valor: elegida.valor };
+        }
+        const elegida = this.siguiente(proveedor, activas);
+        return { id: elegida.id, proveedor, valor: elegida.valor };
+    }
+    filaPegadaActiva(proveedor, promptCacheKey) {
+        const idPegado = this.pegajosidad.get(this.clavePegajosidad(proveedor, promptCacheKey));
+        const fila = idPegado ? this.porId.get(idPegado) : undefined;
+        return fila && fila.estado === "activa" ? fila : undefined;
+    }
+    usosSnapshot() {
+        const tabla = {};
+        for (const [id, n] of this.usos)
+            tabla[id] = n;
+        return tabla;
+    }
+    /**
+     * Huella SHA-256 del valor de una credencial: lo único que sale del valor
+     * hacia registros de rate-limit o diagnóstico. `undefined` = id desconocido.
+     */
+    huellaDe(id) {
+        const fila = this.porId.get(id);
+        return fila ? huellaDeCredencial(fila.valor) : undefined;
+    }
+    /**
+     * Registra el resultado de usar una credencial ya entregada.
+     *
+     * `null` = id desconocido (no hay tal credencial en el pool) — se distingue
+     * de "la marcó y sigue activa" para que quien llama pueda contestar 404 en
+     * vez de fingir un 200.
+     */
+    marcarUso(id, resultado) {
+        const fila = this.porId.get(id);
+        if (!fila)
+            return null;
+        // Todo uso reportado cuenta — también el fallo: una cuenta que lleva
+        // tres 429 esta hora está más "usada" que su hermana descansada, y el
+        // ranking por cuota debe verlo.
+        this.usos.set(id, (this.usos.get(id) ?? 0) + 1);
+        if (resultado.ok)
+            return { clase: "ok", estado: fila.estado };
+        const clasificado = clasificarError({ mensaje: resultado.mensaje, estado: resultado.estadoHttp });
+        // Solo un 401/403 de credencial mala saca la fila del pool. Un 429
+        // (`limite-de-tasa`) deja `fila.estado` intacto a propósito: es la
+        // distinción que pide la tarea, y confundirla quema cuentas que solo
+        // estaban ocupadas.
+        if (clasificado.clase === "credencial-invalida" || clasificado.clase === "sin-credencial") {
+            fila.estado = "bloqueada";
+            fila.motivoBloqueo = clasificado.clase;
+            fila.bloqueadaEn = Date.now();
+            // Toda sesión pegada a esta credencial se suelta: la próxima `elegir`
+            // con la misma prompt_cache_key tiene que caer en una hermana, no
+            // seguir devolviendo la que ya sabemos que está mala.
+            for (const [clave, idPegado] of this.pegajosidad) {
+                if (idPegado === id)
+                    this.pegajosidad.delete(clave);
+            }
+        }
+        return { clase: clasificado.clase, estado: fila.estado };
+    }
+    /** Vista pública del pool: sin secretos, para `/v1/snapshot`. */
+    snapshot() {
+        return [...this.porId.values()].map(publica);
+    }
+}
+//# sourceMappingURL=pool.js.map

package/dist/core/credenciales/pool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool.js","sourceRoot":"","sources":["../../../src/core/credenciales/pool.ts"],"names":[],"mappings":"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"}

package/dist/core/credenciales/ranking.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Ranking de credenciales del pool por cuota real.
+ *
+ * El hueco (AUDITORIA-OMP.md, clúster E: «pools multi-cuenta round-robin +
+ * sticky por sesión, ranking por cuota real»): el round-robin reparte al
+ * margen — la cuenta que lleva tres 429 esta hora recibe el mismo tráfico
+ * que su hermana descansada. Este módulo es la capa superior que ordena los
+ * candidatos antes de entregarlos:
+ *
+ * 1. **Disponible ahora** — descarta las enfriadas por rate-limit (huella
+ *    consultada en el registro persistente de `ratelimit.ts`).
+ * 2. **Pegajosa si sigue disponible** — una `prompt_cache_key` ya anclada a
+ *    una credencial sana se queda donde está. Va antes del balanceo a
+ *    propósito: moverla "para equilibrar" rompe el caché de prompts del
+ *    proveedor y cuesta más de lo que ahorra.
+ * 3. **Menor uso reciente** — contador en memoria (`marcarUso` del pool lo
+ *    alimenta); empate → orden de declaración, estable.
+ * 4. **Round-robin del pool como degradación** — sin ningún dato de cuota
+ *    (ningún contador), no inventa señales: delega en el cursor del propio
+ *    pool, que es el comportamiento previo.
+ */
+import type { FilaPublica, SelectorDeCredencial } from "./pool.ts";
+import type { RegistroEnfriamiento } from "./ratelimit.ts";
+/** Candidata al ranking: fila pública + huella opcional para el enfriamiento. */
+export type Candidata = FilaPublica & {
+    huella?: string;
+};
+export interface EstadoEleccion {
+    /** Instante de la decisión (ms). Default: Date.now(). */
+    ahora?: number;
+    /** id -> usos registrados en memoria desde el arranque. */
+    usoReciente?: Record<string, number>;
+    /** huella -> epoch (ms) hasta el que está enfriada por rate-limit. */
+    enfriadasHasta?: Record<string, number>;
+    /** Id de la credencial pegada a la sesión, si existe. */
+    pegajosaId?: string;
+    /**
+     * Siguiente credencial según el round-robin del pool — la degradación
+     * cuando no hay datos de cuota. Puede devolver una enfriada: se valida.
+     */
+    rotacion?: () => Candidata | null;
+}
+/**
+ * Elige una credencial entre `candidatos`, o `null` si ninguna está
+ * disponible (todas enfriadas). Nunca lanza por datos ausentes: cada pieza
+ * de `estado` es opcional y su falta degrada al criterio anterior.
+ */
+export declare function elegirCredencial(candidatos: readonly Candidata[], estado: EstadoEleccion): Candidata | null;
+/**
+ * Adaptador listo para el hook `selector` de `CredencialPool`: traduce el
+ * contexto del pool (contadores, rotación, huellas) al estado del ranking y
+ * consulta el registro de enfriamiento vivo en cada elección — un 429
+ * reportado hace un segundo cambia ya la próxima resolución.
+ */
+export declare function crearSelectorRanking(enfriamiento: RegistroEnfriamiento): SelectorDeCredencial;
+//# sourceMappingURL=ranking.d.ts.map

package/dist/core/credenciales/ranking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ranking.d.ts","sourceRoot":"","sources":["../../../src/core/credenciales/ranking.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAqB,WAAW,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AACtF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAE3D,iFAAiF;AACjF,MAAM,MAAM,SAAS,GAAG,WAAW,GAAG;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1D,MAAM,WAAW,cAAc;IAC9B,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,sEAAsE;IACtE,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,yDAAyD;IACzD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,SAAS,GAAG,IAAI,CAAC;CAClC;AAQD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,SAAS,SAAS,EAAE,EAAE,MAAM,EAAE,cAAc,GAAG,SAAS,GAAG,IAAI,CAkC3G;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,oBAAoB,GAAG,oBAAoB,CAmB7F"}

package/dist/core/credenciales/ranking.js

@@ -0,0 +1,94 @@
+/**
+ * Ranking de credenciales del pool por cuota real.
+ *
+ * El hueco (AUDITORIA-OMP.md, clúster E: «pools multi-cuenta round-robin +
+ * sticky por sesión, ranking por cuota real»): el round-robin reparte al
+ * margen — la cuenta que lleva tres 429 esta hora recibe el mismo tráfico
+ * que su hermana descansada. Este módulo es la capa superior que ordena los
+ * candidatos antes de entregarlos:
+ *
+ * 1. **Disponible ahora** — descarta las enfriadas por rate-limit (huella
+ *    consultada en el registro persistente de `ratelimit.ts`).
+ * 2. **Pegajosa si sigue disponible** — una `prompt_cache_key` ya anclada a
+ *    una credencial sana se queda donde está. Va antes del balanceo a
+ *    propósito: moverla "para equilibrar" rompe el caché de prompts del
+ *    proveedor y cuesta más de lo que ahorra.
+ * 3. **Menor uso reciente** — contador en memoria (`marcarUso` del pool lo
+ *    alimenta); empate → orden de declaración, estable.
+ * 4. **Round-robin del pool como degradación** — sin ningún dato de cuota
+ *    (ningún contador), no inventa señales: delega en el cursor del propio
+ *    pool, que es el comportamiento previo.
+ */
+function enfriadaHasta(candidata, estado) {
+    if (!candidata.huella)
+        return undefined;
+    const hasta = estado.enfriadasHasta?.[candidata.huella];
+    return typeof hasta === "number" ? hasta : undefined;
+}
+/**
+ * Elige una credencial entre `candidatos`, o `null` si ninguna está
+ * disponible (todas enfriadas). Nunca lanza por datos ausentes: cada pieza
+ * de `estado` es opcional y su falta degrada al criterio anterior.
+ */
+export function elegirCredencial(candidatos, estado) {
+    const ahora = estado.ahora ?? Date.now();
+    const disponibles = candidatos.filter((c) => {
+        const hasta = enfriadaHasta(c, estado);
+        // Disponible si no hay enfriamiento o ya venció (hasta <= ahora).
+        return hasta === undefined || hasta <= ahora;
+    });
+    if (disponibles.length === 0)
+        return null;
+    if (estado.pegajosaId) {
+        const pegajosa = disponibles.find((c) => c.id === estado.pegajosaId);
+        if (pegajosa)
+            return pegajosa;
+    }
+    const uso = estado.usoReciente ?? {};
+    const conDatos = disponibles.some((c) => typeof uso[c.id] === "number" && uso[c.id] > 0);
+    if (!conDatos) {
+        // Sin datos de cuota no se inventa señal: round-robin del pool, validado
+        // contra el enfriamiento. Se prueban tantas pasadas como candidatos — el
+        // cursor puede apuntar varias veces seguidas a cuentas enfriadas.
+        for (let i = 0; i < candidatos.length; i++) {
+            const rotada = estado.rotacion?.() ?? null;
+            if (rotada && disponibles.some((c) => c.id === rotada.id))
+                return rotada;
+        }
+        return disponibles[0];
+    }
+    let mejor = disponibles[0];
+    for (const candidata of disponibles) {
+        if ((uso[candidata.id] ?? Number.MAX_SAFE_INTEGER) < (uso[mejor.id] ?? Number.MAX_SAFE_INTEGER)) {
+            mejor = candidata;
+        }
+    }
+    return mejor;
+}
+/**
+ * Adaptador listo para el hook `selector` de `CredencialPool`: traduce el
+ * contexto del pool (contadores, rotación, huellas) al estado del ranking y
+ * consulta el registro de enfriamiento vivo en cada elección — un 429
+ * reportado hace un segundo cambia ya la próxima resolución.
+ */
+export function crearSelectorRanking(enfriamiento) {
+    return (candidatos, contexto) => {
+        const enfriadasHasta = {};
+        for (const entrada of enfriamiento.enfriadas())
+            enfriadasHasta[entrada.huella] = entrada.hasta;
+        const conHuella = candidatos.map((c) => ({ ...c, huella: contexto.huella(c.id) }));
+        const elegida = elegirCredencial(conHuella, {
+            ahora: Date.now(),
+            usoReciente: contexto.usoReciente,
+            enfriadasHasta,
+            pegajosaId: contexto.pegajosaId,
+            rotacion: () => {
+                const id = contexto.rotacion();
+                const encontrada = id ? candidatos.find((c) => c.id === id) : undefined;
+                return encontrada ? { ...encontrada, huella: contexto.huella(encontrada.id) } : null;
+            },
+        });
+        return elegida?.id ?? null;
+    };
+}
+//# sourceMappingURL=ranking.js.map

package/dist/core/credenciales/ranking.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ranking.js","sourceRoot":"","sources":["../../../src/core/credenciales/ranking.ts"],"names":[],"mappings":"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"}

package/dist/core/credenciales/ratelimit.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Registro persistente de enfriamiento por rate-limit (429) del pool de
+ * credenciales.
+ *
+ * El hueco que tapa (AUDITORIA-OMP.md, clúster E): el pool en memoria sabe
+ * que un 429 no bloquea la cuenta, pero olvida el enfriamiento al reiniciar
+ * el broker — y una cuenta recién reiniciada vuelve a recibir tráfico que el
+ * proveedor sigue rechazando, quemando el Retry-After. Aquí el enfriamiento
+ * sobrevive a reinicios: JSON atómico (`writeTextAtomicSync`, temporal +
+ * rename + fsync) releído en cada arranque.
+ *
+ * La decisión de privacidad es dura y está probada: en el fichero NUNCA hay
+ * claves — solo huellas SHA-256 del valor. Un disco comprometido revela que
+ * «la cuenta con huella ab12… está enfriada hasta las 14:05», nada más.
+ */
+/** Una entrada del registro: huella (jamás el valor), hasta qué epoch y por qué. */
+export interface EntradaEnfriamiento {
+    huella: string;
+    /** Epoch en milisegundos hasta el que la credencial descansa. */
+    hasta: number;
+    motivo?: string;
+}
+/**
+ * Huella estable de una credencial: SHA-256 del valor, hex. Es lo único que
+ * sale del valor hacia cualquier superficie persistente o consultable — ni
+ * argv, ni campos, ni este fichero ven nunca la clave entera.
+ */
+export declare function huellaDeCredencial(valor: string): string;
+export declare class RegistroEnfriamiento {
+    private readonly entradas;
+    /** Ruta del JSON persistente; `undefined` = solo memoria (tests). */
+    readonly fichero: string | undefined;
+    constructor(fichero?: string);
+    /**
+     * Marca la credencial como enfriada hasta `hastaEpoch` (ms). Si ya había
+     * una entrada, gana la más lejana: dos clientes que reportan 429 con
+     * Retry-After distintos no deben acortar el descanso que el proveedor pidió.
+     */
+    marcarEnfriada(huella: string, hastaEpoch: number, motivo?: string): void;
+    /** `true` si la credencial puede usarse ahora mismo. */
+    disponible(huella: string, ahora?: number): boolean;
+    /** Epoch hasta el que está enfriada, o `undefined` si está disponible. */
+    enfriadaHasta(huella: string, ahora?: number): number | undefined;
+    /** Las credenciales enfriadas AHORA (las expiradas se podan antes). */
+    enfriadas(ahora?: number): EntradaEnfriamiento[];
+    /**
+     * Relee el fichero de disco. Es lo que un reinicio del broker ejecuta vía
+     * constructor; existe como método público porque la prueba de persistencia
+     * simula el reinicio sobre una segunda instancia sin tirar la primera.
+     */
+    recargar(): void;
+    private persistir;
+}
+//# sourceMappingURL=ratelimit.d.ts.map

package/dist/core/credenciales/ratelimit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ratelimit.d.ts","sourceRoot":"","sources":["../../../src/core/credenciales/ratelimit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAQH,oFAAoF;AACpF,MAAM,WAAW,mBAAmB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAOD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,qBAAa,oBAAoB;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA0C;IAEnE,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;gBAEzB,OAAO,CAAC,EAAE,MAAM;IAK5B;;;;OAIG;IACH,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAOzE,wDAAwD;IACxD,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,GAAE,MAAmB,GAAG,OAAO;IAI/D,0EAA0E;IAC1E,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,GAAE,MAAmB,GAAG,MAAM,GAAG,SAAS;IAY7E,uEAAuE;IACvE,SAAS,CAAC,KAAK,GAAE,MAAmB,GAAG,mBAAmB,EAAE;IAU5D;;;;OAIG;IACH,QAAQ,IAAI,IAAI;IAuBhB,OAAO,CAAC,SAAS;CAKjB"}

package/dist/core/credenciales/ratelimit.js

@@ -0,0 +1,116 @@
+/**
+ * Registro persistente de enfriamiento por rate-limit (429) del pool de
+ * credenciales.
+ *
+ * El hueco que tapa (AUDITORIA-OMP.md, clúster E): el pool en memoria sabe
+ * que un 429 no bloquea la cuenta, pero olvida el enfriamiento al reiniciar
+ * el broker — y una cuenta recién reiniciada vuelve a recibir tráfico que el
+ * proveedor sigue rechazando, quemando el Retry-After. Aquí el enfriamiento
+ * sobrevive a reinicios: JSON atómico (`writeTextAtomicSync`, temporal +
+ * rename + fsync) releído en cada arranque.
+ *
+ * La decisión de privacidad es dura y está probada: en el fichero NUNCA hay
+ * claves — solo huellas SHA-256 del valor. Un disco comprometido revela que
+ * «la cuenta con huella ab12… está enfriada hasta las 14:05», nada más.
+ */
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { writeTextAtomicSync } from "../utils/atomic-write.js";
+const VERSION_FORMATO = 1;
+/**
+ * Huella estable de una credencial: SHA-256 del valor, hex. Es lo único que
+ * sale del valor hacia cualquier superficie persistente o consultable — ni
+ * argv, ni campos, ni este fichero ven nunca la clave entera.
+ */
+export function huellaDeCredencial(valor) {
+    return createHash("sha256").update(valor, "utf-8").digest("hex");
+}
+export class RegistroEnfriamiento {
+    entradas = new Map();
+    /** Ruta del JSON persistente; `undefined` = solo memoria (tests). */
+    fichero;
+    constructor(fichero) {
+        this.fichero = fichero;
+        this.recargar();
+    }
+    /**
+     * Marca la credencial como enfriada hasta `hastaEpoch` (ms). Si ya había
+     * una entrada, gana la más lejana: dos clientes que reportan 429 con
+     * Retry-After distintos no deben acortar el descanso que el proveedor pidió.
+     */
+    marcarEnfriada(huella, hastaEpoch, motivo) {
+        const previa = this.entradas.get(huella);
+        if (previa && previa.hasta >= hastaEpoch)
+            return;
+        this.entradas.set(huella, { huella, hasta: hastaEpoch, motivo });
+        this.persistir();
+    }
+    /** `true` si la credencial puede usarse ahora mismo. */
+    disponible(huella, ahora = Date.now()) {
+        return !this.enfriadaHasta(huella, ahora);
+    }
+    /** Epoch hasta el que está enfriada, o `undefined` si está disponible. */
+    enfriadaHasta(huella, ahora = Date.now()) {
+        const entrada = this.entradas.get(huella);
+        if (!entrada)
+            return undefined;
+        if (entrada.hasta <= ahora) {
+            // Expiró: se poda al leerla, para que el fichero no engorde para siempre.
+            this.entradas.delete(huella);
+            this.persistir();
+            return undefined;
+        }
+        return entrada.hasta;
+    }
+    /** Las credenciales enfriadas AHORA (las expiradas se podan antes). */
+    enfriadas(ahora = Date.now()) {
+        const vivas = [];
+        for (const entrada of this.entradas.values()) {
+            if (entrada.hasta > ahora)
+                vivas.push(entrada);
+            else
+                this.entradas.delete(entrada.huella);
+        }
+        if (vivas.length !== this.entradas.size)
+            this.persistir();
+        return vivas;
+    }
+    /**
+     * Relee el fichero de disco. Es lo que un reinicio del broker ejecuta vía
+     * constructor; existe como método público porque la prueba de persistencia
+     * simula el reinicio sobre una segunda instancia sin tirar la primera.
+     */
+    recargar() {
+        this.entradas.clear();
+        if (!this.fichero)
+            return;
+        let crudo;
+        try {
+            crudo = readFileSync(this.fichero, "utf-8");
+        }
+        catch {
+            return; // No existe todavía: arranque limpio, nunca bloquea el broker.
+        }
+        try {
+            const datos = JSON.parse(crudo);
+            if (datos.version !== VERSION_FORMATO || !Array.isArray(datos.enfriadas))
+                return;
+            for (const e of datos.enfriadas) {
+                if (typeof e?.huella === "string" && typeof e?.hasta === "number") {
+                    this.entradas.set(e.huella, { huella: e.huella, hasta: e.hasta, motivo: e.motivo });
+                }
+            }
+        }
+        catch {
+            // Fichero corrupto: mejor arrancar sin enfriamientos que sin broker.
+            this.entradas.clear();
+        }
+    }
+    persistir() {
+        if (!this.fichero)
+            return;
+        const cuerpo = { version: VERSION_FORMATO, enfriadas: [...this.entradas.values()] };
+        writeTextAtomicSync(this.fichero, `${JSON.stringify(cuerpo, null, "\t")}\n`);
+    }
+}
+//# sourceMappingURL=ratelimit.js.map

package/dist/core/credenciales/ratelimit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ratelimit.js","sourceRoot":"","sources":["../../../src/core/credenciales/ratelimit.ts"],"names":[],"mappings":"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"}

package/dist/core/credenciales/reposo.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Cifrado en reposo de `<agentDir>/auth.json`.
+ *
+ * EL HUECO: vendemos "vault cifrado con clasificación y auditoría"
+ * (memory-engine/vault.ts) mientras las claves de API y los tokens OAuth de
+ * los proveedores viven en auth.json EN CLARO, con permisos 0600 pero
+ * legibles por cualquier proceso del usuario. La política de aprobación
+ * (aprobacion/politica.ts) ya le impide leerlo a NUESTRO agente; esto le
+ * cierra la puerta a cualquier OTRO proceso.
+ *
+ * DISEÑO — envolver, no sustituir:
+ * `auth-storage.ts` es de upstream y el presupuesto de fork está agotado
+ * (ver scripts/sync-ada.sh --check). No podemos reescribir su lectura/
+ * escritura de fichero ni su bloqueo entre procesos (proper-lockfile) sin
+ * pagar hunks que no tenemos. En vez de eso, ENVOLVEMOS su
+ * `AuthStorageBackend`: el interior (`FileAuthStorageBackend`) sigue
+ * poseyendo el candado y el `ensureFileExists`/`ensureParentDir`; nosotros
+ * solo transformamos el CONTENIDO que entra y sale del candado. Todo el
+ * cifrado ocurre DENTRO de la sección crítica del candado que ya existía,
+ * así que la seguridad frente a otros procesos de Ada no cambia.
+ *
+ * CLAVE: un secreto aleatorio de 256 bits en el LLAVERO del sistema (no una
+ * passphrase memorizable — nadie va a teclear una contraseña para que el
+ * CLI arranque). Se deriva de nada: se genera con randomBytes y se guarda
+ * en Keychain la primera vez que hace falta. Sin llavero disponible (CI,
+ * contenedor, Linux sin secret-service) NO SE CIFRA: una clave que vive en
+ * el mismo disco que el fichero que protege es ofuscación, no cifrado, y
+ * llamarlo cifrado sería mentir en la única parte del producto donde no se
+ * puede mentir. Se avisa una vez, con una línea clara, y se sigue
+ * funcionando en claro (mismo comportamiento que hoy).
+ *
+ * FORMATO: una cabecera literal al principio del fichero distingue claro de
+ * cifrado — nunca adivinamos intentando JSON.parse (un fichero cifrado
+ * corrupto a medias podría parsear igual como JSON basura y confundirse con
+ * "en claro", perdiendo credenciales calladamente).
+ *
+ * MIGRACIÓN: en cada lectura, si el contenido está en claro se devuelve tal
+ * cual (nunca bloquea al llamador) y se agenda un recifrado en segundo
+ * plano con `setImmediate` — nunca DENTRO del candado que la propia lectura
+ * mantiene abierto, porque volver a pedirlo desde dentro se autobloquearía.
+ * En cada escritura (a través del wrapper) se cifra antes de tocar disco,
+ * con copia de seguridad y escritura atómica (fichero temporal + rename):
+ * si esto corrompe auth.json, el usuario pierde el acceso a TODOS sus
+ * proveedores, así que no se sustituye el fichero real hasta que el
+ * temporal esté completo en disco.
+ */
+import type { Credential } from "@earendil-works/pi-ai";
+import type { AuthStorageBackend } from "../auth-storage.ts";
+/**
+ * True cuando hay un llavero de sistema utilizable en esta máquina.
+ *
+ * `ADA_SIN_LLAVERO=1` fuerza "no disponible" aunque estemos en macOS — es la
+ * única forma de probar de verdad la rama "sin llavero" (headless/CI) sin
+ * necesitar una máquina Linux, y también sirve de escape manual para quien
+ * quiera desactivar el uso del Keychain explícitamente.
+ */
+export declare function hayLlaveroDisponible(): boolean;
+/**
+ * auth.json cifrado que no se puede leer: auth tag inválido, JSON del sobre
+ * truncado, o llavero sin la clave que lo cifró (p.ej. copiado desde otra
+ * máquina). "no he podido leerlo" y "no hay credenciales" son cosas
+ * distintas: esto SIEMPRE es lo primero, nunca se confunde con un auth.json
+ * vacío legítimo.
+ */
+export declare class AuthJsonCorruptoError extends Error {
+    constructor(authPath: string, causa: unknown);
+}
+/**
+ * Envuelve un `AuthStorageBackend` (normalmente un `FileAuthStorageBackend`
+ * ya construido, que sigue poseyendo el candado entre procesos) para que
+ * cifre/descifre en reposo de forma transparente para quien lo use.
+ */
+export declare function envolverBackendCifrado(interno: AuthStorageBackend, authPath: string): AuthStorageBackend;
+/**
+ * Lectura síncrona de UNA credencial ya guardada, descifrando si hace falta.
+ *
+ * Sustituye a `readStoredCredential` (upstream, `auth-storage.ts`), exportada
+ * en `index.ts` como parte de la API pública del SDK (`@hoilab/ada-cli`) para
+ * lecturas puntuales sin instanciar `AuthStorage`. Esa función hace su propio
+ * `readFileSync` + `JSON.parse` sin pasar por este módulo: con auth.json ya
+ * migrado a cifrado, la cabecera `ADA-AUTHJSON-CIFRADO-V1\n` delante del JSON
+ * hace que `JSON.parse` lance un `SyntaxError` que su `catch { return
+ * undefined; }` convierte en "no hay credencial" — indistinguible de un
+ * proveedor sin configurar, para CUALQUIER consumidor de esta función
+ * pública, presente o futuro. Mismo nombre y misma firma (con el mismo valor
+ * por defecto de `authPath`) para seguir siendo un reemplazo directo.
+ */
+export declare function leerCredencialGuardada(providerId: string, authPath?: string): Credential | undefined;
+/** Solo para pruebas: limpia el estado en memoria del módulo entre casos. */
+export declare function __resetEstadoParaPruebas(): void;
+/** Solo para pruebas: borra la clave maestra del llavero real de esta máquina. */
+export declare function __eliminarClaveDeLlaveroParaPruebas(): void;
+//# sourceMappingURL=reposo.d.ts.map

package/dist/core/credenciales/reposo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reposo.d.ts","sourceRoot":"","sources":["../../../src/core/credenciales/reposo.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAMH,OAAO,KAAK,EAAwB,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAG9E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAmE7D;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,IAAI,OAAO,CAE9C;AA4KD;;;;;;GAMG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;gBACnC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO;CAa5C;AAwJD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,GAAG,kBAAkB,CA4BxG;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CACrC,UAAU,EAAE,MAAM,EAClB,QAAQ,GAAE,MAAyC,GACjD,UAAU,GAAG,SAAS,CAUxB;AAED,6EAA6E;AAC7E,wBAAgB,wBAAwB,IAAI,IAAI,CAK/C;AAED,kFAAkF;AAClF,wBAAgB,mCAAmC,IAAI,IAAI,CAY1D"}