@hoilab/ada-cli 0.84.21 → 0.85.0

package/dist/core/context-breakdown.js

@@ -0,0 +1,87 @@
+/**
+ * Desglose de qué está llenando la ventana de contexto.
+ *
+ * POR QUÉ IMPORTA AQUÍ MÁS QUE EN OTROS PRODUCTOS: con caché por prefijo, el
+ * coste de un cambio depende de su POSICIÓN, no de su tamaño. Saber que las
+ * definiciones de tools ocupan 11 K y van delante te dice que tocarlas invalida
+ * todo lo que viene detrás. Sin este desglose, optimizar la caché es a ciegas.
+ *
+ * HONESTIDAD DEL DATO — la parte que las referencias no resuelven:
+ *
+ * El único número REAL es el total, que lo da el proveedor en el `usage` de la
+ * última respuesta. Los trozos se estiman con `chars/4`, que es una heurística.
+ * Presentar estimaciones como si fueran medidas sería mentir con precisión
+ * falsa, así que:
+ *
+ *   - Si hay total real, se REPARTE ese total según las proporciones estimadas.
+ *     El total cuadra siempre y el reparto se marca como estimado.
+ *   - Si no lo hay (recién compactado, antes de la primera respuesta), se
+ *     devuelve la suma de estimaciones y se dice que TODO es estimado.
+ */
+/**
+ * Estimación de tokens de un texto.
+ *
+ * `chars/4` es la misma heurística que ya usa la compactación
+ * (`compaction.ts:estimateTokens`). Se mantiene idéntica a propósito: dos
+ * estimadores distintos darían cifras que no cuadran entre la barra de contexto
+ * y el momento en que salta la compactación, y el usuario no tendría forma de
+ * saber cuál creer.
+ */
+export function estimarTokensTexto(texto) {
+    return Math.ceil(texto.length / 4);
+}
+function sumar(textos) {
+    let total = 0;
+    for (const t of textos)
+        total += estimarTokensTexto(t);
+    return total;
+}
+/**
+ * Construye el desglose.
+ *
+ * Las categorías con cero tokens se omiten: una lista con seis ceros no informa
+ * de nada y esconde las dos que sí pesan.
+ */
+export function construirDesglose(entrada) {
+    const crudos = [
+        ["systemPrompt", estimarTokensTexto(entrada.systemPrompt)],
+        ["toolDefinitions", sumar(entrada.toolDefinitions)],
+        ["skills", sumar(entrada.skills)],
+        ["mcpTools", sumar(entrada.mcpTools)],
+        ["contextFiles", sumar(entrada.contextFiles)],
+        ["memory", sumar(entrada.memory)],
+        ["conversation", Math.max(0, entrada.conversationTokens)],
+    ];
+    const sumaEstimada = crudos.reduce((s, [, n]) => s + n, 0);
+    const totalExacto = entrada.tokensReales !== null && entrada.tokensReales > 0;
+    const total = totalExacto ? entrada.tokensReales : sumaEstimada;
+    // Reparto proporcional sobre el total real. Si la suma estimada es cero no se
+    // puede repartir nada: se devuelven las piezas a cero en vez de dividir por
+    // cero y producir NaN, que en la interfaz se vería como "—" o como 0 aleatorio.
+    const escala = totalExacto && sumaEstimada > 0 ? entrada.tokensReales / sumaEstimada : 1;
+    const piezas = crudos
+        .filter(([, n]) => n > 0)
+        .map(([categoria, n]) => {
+        const tokens = Math.round(n * escala);
+        return { categoria, tokens, fraccion: total > 0 ? tokens / total : 0 };
+    })
+        .sort((a, b) => b.tokens - a.tokens);
+    return {
+        total,
+        contextWindow: entrada.contextWindow,
+        ocupacion: entrada.contextWindow > 0 ? Math.min(1, total / entrada.contextWindow) : 0,
+        totalExacto,
+        piezas,
+    };
+}
+/** Etiquetas legibles. La interfaz traduce; esto es el orden y el nombre canónico. */
+export const ETIQUETAS_CONTEXTO = {
+    systemPrompt: "System prompt",
+    toolDefinitions: "Tool definitions",
+    skills: "Skills",
+    mcpTools: "MCP tools",
+    contextFiles: "Context files",
+    memory: "Memory",
+    conversation: "Conversation",
+};
+//# sourceMappingURL=context-breakdown.js.map

package/dist/core/context-breakdown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-breakdown.js","sourceRoot":"","sources":["../../src/core/context-breakdown.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAkCH;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAa,EAAU;IACzD,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AAAA,CACnC;AAqBD,SAAS,KAAK,CAAC,MAAgB,EAAU;IACxC,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,CAAC,IAAI,MAAM;QAAE,KAAK,IAAI,kBAAkB,CAAC,CAAC,CAAC,CAAC;IACvD,OAAO,KAAK,CAAC;AAAA,CACb;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAwB,EAAoB;IAC7E,MAAM,MAAM,GAAuC;QAClD,CAAC,cAAc,EAAE,kBAAkB,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;QAC1D,CAAC,iBAAiB,EAAE,KAAK,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;QACnD,CAAC,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACjC,CAAC,UAAU,EAAE,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACrC,CAAC,cAAc,EAAE,KAAK,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;QAC7C,CAAC,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACjC,CAAC,cAAc,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC,CAAC;KACzD,CAAC;IAEF,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IAC3D,MAAM,WAAW,GAAG,OAAO,CAAC,YAAY,KAAK,IAAI,IAAI,OAAO,CAAC,YAAY,GAAG,CAAC,CAAC;IAC9E,MAAM,KAAK,GAAG,WAAW,CAAC,CAAC,CAAE,OAAO,CAAC,YAAuB,CAAC,CAAC,CAAC,YAAY,CAAC;IAE5E,8EAA8E;IAC9E,4EAA4E;IAC5E,mFAAgF;IAChF,MAAM,MAAM,GAAG,WAAW,IAAI,YAAY,GAAG,CAAC,CAAC,CAAC,CAAE,OAAO,CAAC,YAAuB,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;IAErG,MAAM,MAAM,GAAoB,MAAM;SACpC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;SACxB,GAAG,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC;QACxB,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC;QACtC,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAAA,CACvE,CAAC;SACD,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC;IAEtC,OAAO;QACN,KAAK;QACL,aAAa,EAAE,OAAO,CAAC,aAAa;QACpC,SAAS,EAAE,OAAO,CAAC,aAAa,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;QACrF,WAAW;QACX,MAAM;KACN,CAAC;AAAA,CACF;AAED,uFAAsF;AACtF,MAAM,CAAC,MAAM,kBAAkB,GAAsC;IACpE,YAAY,EAAE,eAAe;IAC7B,eAAe,EAAE,kBAAkB;IACnC,MAAM,EAAE,QAAQ;IAChB,QAAQ,EAAE,WAAW;IACrB,YAAY,EAAE,eAAe;IAC7B,MAAM,EAAE,QAAQ;IAChB,YAAY,EAAE,cAAc;CAC5B,CAAC","sourcesContent":["/**\n * Desglose de qué está llenando la ventana de contexto.\n *\n * POR QUÉ IMPORTA AQUÍ MÁS QUE EN OTROS PRODUCTOS: con caché por prefijo, el\n * coste de un cambio depende de su POSICIÓN, no de su tamaño. Saber que las\n * definiciones de tools ocupan 11 K y van delante te dice que tocarlas invalida\n * todo lo que viene detrás. Sin este desglose, optimizar la caché es a ciegas.\n *\n * HONESTIDAD DEL DATO — la parte que las referencias no resuelven:\n *\n * El único número REAL es el total, que lo da el proveedor en el `usage` de la\n * última respuesta. Los trozos se estiman con `chars/4`, que es una heurística.\n * Presentar estimaciones como si fueran medidas sería mentir con precisión\n * falsa, así que:\n *\n *   - Si hay total real, se REPARTE ese total según las proporciones estimadas.\n *     El total cuadra siempre y el reparto se marca como estimado.\n *   - Si no lo hay (recién compactado, antes de la primera respuesta), se\n *     devuelve la suma de estimaciones y se dice que TODO es estimado.\n */\n\n/** Categorías. El orden es el del prompt: lo estable primero. */\nexport type CategoriaContexto =\n\t| \"systemPrompt\"\n\t| \"toolDefinitions\"\n\t| \"skills\"\n\t| \"mcpTools\"\n\t| \"contextFiles\"\n\t| \"memory\"\n\t| \"conversation\";\n\nexport interface PiezaContexto {\n\tcategoria: CategoriaContexto;\n\t/** Tokens atribuidos. Estimados salvo que `exacto` sea true. */\n\ttokens: number;\n\t/** Fracción del total, entre 0 y 1. */\n\tfraccion: number;\n}\n\nexport interface DesgloseContexto {\n\t/** Total de tokens en contexto. Exacto si vino del proveedor. */\n\ttotal: number;\n\tcontextWindow: number;\n\t/** Fracción de la ventana ocupada, entre 0 y 1. */\n\tocupacion: number;\n\t/**\n\t * True cuando `total` viene del `usage` del proveedor. False significa que\n\t * todo el desglose, total incluido, es una estimación.\n\t */\n\ttotalExacto: boolean;\n\tpiezas: PiezaContexto[];\n}\n\n/**\n * Estimación de tokens de un texto.\n *\n * `chars/4` es la misma heurística que ya usa la compactación\n * (`compaction.ts:estimateTokens`). Se mantiene idéntica a propósito: dos\n * estimadores distintos darían cifras que no cuadran entre la barra de contexto\n * y el momento en que salta la compactación, y el usuario no tendría forma de\n * saber cuál creer.\n */\nexport function estimarTokensTexto(texto: string): number {\n\treturn Math.ceil(texto.length / 4);\n}\n\nexport interface EntradaDesglose {\n\tcontextWindow: number;\n\t/** Tokens reales del proveedor. `null` = desconocido (p. ej. tras compactar). */\n\ttokensReales: number | null;\n\tsystemPrompt: string;\n\t/** Nombre + descripción + esquema serializado de cada tool. */\n\ttoolDefinitions: string[];\n\t/** Nombre + descripción de cada skill visible para el modelo. */\n\tskills: string[];\n\t/** Definiciones de tools MCP, aparte porque son las que más se disparan. */\n\tmcpTools: string[];\n\t/** Ficheros de contexto inyectados (AGENTS.md y compañía). */\n\tcontextFiles: string[];\n\t/** Bloques de memoria inyectados. */\n\tmemory: string[];\n\t/** Tokens de la conversación, ya estimados por el llamante. */\n\tconversationTokens: number;\n}\n\nfunction sumar(textos: string[]): number {\n\tlet total = 0;\n\tfor (const t of textos) total += estimarTokensTexto(t);\n\treturn total;\n}\n\n/**\n * Construye el desglose.\n *\n * Las categorías con cero tokens se omiten: una lista con seis ceros no informa\n * de nada y esconde las dos que sí pesan.\n */\nexport function construirDesglose(entrada: EntradaDesglose): DesgloseContexto {\n\tconst crudos: Array<[CategoriaContexto, number]> = [\n\t\t[\"systemPrompt\", estimarTokensTexto(entrada.systemPrompt)],\n\t\t[\"toolDefinitions\", sumar(entrada.toolDefinitions)],\n\t\t[\"skills\", sumar(entrada.skills)],\n\t\t[\"mcpTools\", sumar(entrada.mcpTools)],\n\t\t[\"contextFiles\", sumar(entrada.contextFiles)],\n\t\t[\"memory\", sumar(entrada.memory)],\n\t\t[\"conversation\", Math.max(0, entrada.conversationTokens)],\n\t];\n\n\tconst sumaEstimada = crudos.reduce((s, [, n]) => s + n, 0);\n\tconst totalExacto = entrada.tokensReales !== null && entrada.tokensReales > 0;\n\tconst total = totalExacto ? (entrada.tokensReales as number) : sumaEstimada;\n\n\t// Reparto proporcional sobre el total real. Si la suma estimada es cero no se\n\t// puede repartir nada: se devuelven las piezas a cero en vez de dividir por\n\t// cero y producir NaN, que en la interfaz se vería como \"—\" o como 0 aleatorio.\n\tconst escala = totalExacto && sumaEstimada > 0 ? (entrada.tokensReales as number) / sumaEstimada : 1;\n\n\tconst piezas: PiezaContexto[] = crudos\n\t\t.filter(([, n]) => n > 0)\n\t\t.map(([categoria, n]) => {\n\t\t\tconst tokens = Math.round(n * escala);\n\t\t\treturn { categoria, tokens, fraccion: total > 0 ? tokens / total : 0 };\n\t\t})\n\t\t.sort((a, b) => b.tokens - a.tokens);\n\n\treturn {\n\t\ttotal,\n\t\tcontextWindow: entrada.contextWindow,\n\t\tocupacion: entrada.contextWindow > 0 ? Math.min(1, total / entrada.contextWindow) : 0,\n\t\ttotalExacto,\n\t\tpiezas,\n\t};\n}\n\n/** Etiquetas legibles. La interfaz traduce; esto es el orden y el nombre canónico. */\nexport const ETIQUETAS_CONTEXTO: Record<CategoriaContexto, string> = {\n\tsystemPrompt: \"System prompt\",\n\ttoolDefinitions: \"Tool definitions\",\n\tskills: \"Skills\",\n\tmcpTools: \"MCP tools\",\n\tcontextFiles: \"Context files\",\n\tmemory: \"Memory\",\n\tconversation: \"Conversation\",\n};\n"]}

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

@@ -0,0 +1,60 @@
+/**
+ * Cliente del broker de credenciales.
+ *
+ * Regla de diseño, y es la que hace verificable "el cliente no tiene el token
+ * en su proceso": el secreto que devuelve `resolverCredencial` NUNCA se asigna
+ * a un campo de esta clase. Sale de la función, el llamador decide qué hacer
+ * con él, y esta instancia no guarda nada más que la URL y el bearer del
+ * broker (que no son el secreto de ningún proveedor). Ningún método escribe a
+ * disco — la credencial vive, como mucho, en la pila de quien la usó para una
+ * sola petición.
+ */
+export interface OpcionesClienteBroker {
+    url: string;
+    token: string;
+    /** Nombre identificador de este cliente, para que el libro de sesión diga quién pidió qué. */
+    cliente?: string;
+}
+export interface CredencialResuelta {
+    id: string;
+    valor: string;
+}
+export type ResultadoDeUso = {
+    ok: true;
+} | {
+    ok: false;
+    estadoHttp?: number;
+    mensaje: string;
+};
+export interface EfectoDeUso {
+    clase: string;
+    estado: "activa" | "bloqueada";
+}
+export interface FilaSnapshot {
+    id: string;
+    proveedor: string;
+    estado: "activa" | "bloqueada";
+    motivoBloqueo?: string;
+}
+export declare class ClienteBroker {
+    private readonly url;
+    private readonly token;
+    private readonly nombreCliente?;
+    constructor(opciones: OpcionesClienteBroker);
+    private cabeceras;
+    /**
+     * Pide una credencial al broker y la devuelve para uso inmediato.
+     *
+     * `null` = el broker no tiene ninguna credencial activa para ese proveedor
+     * (todas bloqueadas, o proveedor sin dar de alta) — "no hay nada", que se
+     * distingue de una excepción, que es "no he podido hablar con el broker".
+     */
+    resolverCredencial(proveedor: string, promptCacheKey?: string): Promise<CredencialResuelta | null>;
+    /** Reporta cómo fue usar una credencial ya entregada. El broker distingue 401 de 429 con esto. */
+    reportarUso(id: string, resultado: ResultadoDeUso): Promise<EfectoDeUso | null>;
+    /** Vista del pool sin secretos: qué credenciales hay y en qué estado. */
+    snapshot(): Promise<FilaSnapshot[]>;
+    /** Liveness sin bearer. `false` en cualquier fallo de red, no lanza. */
+    salud(): Promise<boolean>;
+}
+//# sourceMappingURL=cliente.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cliente.d.ts","sourceRoot":"","sources":["../../../src/core/credenciales/cliente.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,qBAAqB;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,kGAA8F;IAC9F,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,cAAc,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhG,MAAM,WAAW,WAAW;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,QAAQ,GAAG,WAAW,CAAC;CAC/B;AAED,MAAM,WAAW,YAAY;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,QAAQ,GAAG,WAAW,CAAC;IAC/B,aAAa,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,qBAAa,aAAa;IACzB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAS;IAExC,YAAY,QAAQ,EAAE,qBAAqB,EAI1C;IAED,OAAO,CAAC,SAAS;IAIjB;;;;;;OAMG;IACG,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAcvG;IAED,mGAAkG;IAC5F,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,cAAc,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAWpF;IAED,2EAAyE;IACnE,QAAQ,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC,CAOxC;IAED,wEAAwE;IAClE,KAAK,IAAI,OAAO,CAAC,OAAO,CAAC,CAO9B;CACD","sourcesContent":["/**\n * Cliente del broker de credenciales.\n *\n * Regla de diseño, y es la que hace verificable \"el cliente no tiene el token\n * en su proceso\": el secreto que devuelve `resolverCredencial` NUNCA se asigna\n * a un campo de esta clase. Sale de la función, el llamador decide qué hacer\n * con él, y esta instancia no guarda nada más que la URL y el bearer del\n * broker (que no son el secreto de ningún proveedor). Ningún método escribe a\n * disco — la credencial vive, como mucho, en la pila de quien la usó para una\n * sola petición.\n */\n\nexport interface OpcionesClienteBroker {\n\turl: string;\n\ttoken: string;\n\t/** Nombre identificador de este cliente, para que el libro de sesión diga quién pidió qué. */\n\tcliente?: string;\n}\n\nexport interface CredencialResuelta {\n\tid: string;\n\tvalor: string;\n}\n\nexport type ResultadoDeUso = { ok: true } | { ok: false; estadoHttp?: number; mensaje: string };\n\nexport interface EfectoDeUso {\n\tclase: string;\n\testado: \"activa\" | \"bloqueada\";\n}\n\nexport interface FilaSnapshot {\n\tid: string;\n\tproveedor: string;\n\testado: \"activa\" | \"bloqueada\";\n\tmotivoBloqueo?: string;\n}\n\nexport class ClienteBroker {\n\tprivate readonly url: string;\n\tprivate readonly token: string;\n\tprivate readonly nombreCliente?: string;\n\n\tconstructor(opciones: OpcionesClienteBroker) {\n\t\tthis.url = opciones.url.replace(/\\/$/, \"\");\n\t\tthis.token = opciones.token;\n\t\tthis.nombreCliente = opciones.cliente;\n\t}\n\n\tprivate cabeceras(): Record<string, string> {\n\t\treturn { \"content-type\": \"application/json\", authorization: `Bearer ${this.token}` };\n\t}\n\n\t/**\n\t * Pide una credencial al broker y la devuelve para uso inmediato.\n\t *\n\t * `null` = el broker no tiene ninguna credencial activa para ese proveedor\n\t * (todas bloqueadas, o proveedor sin dar de alta) — \"no hay nada\", que se\n\t * distingue de una excepción, que es \"no he podido hablar con el broker\".\n\t */\n\tasync resolverCredencial(proveedor: string, promptCacheKey?: string): Promise<CredencialResuelta | null> {\n\t\tconst respuesta = await fetch(`${this.url}/v1/credential`, {\n\t\t\tmethod: \"POST\",\n\t\t\theaders: this.cabeceras(),\n\t\t\tbody: JSON.stringify({ proveedor, promptCacheKey, cliente: this.nombreCliente }),\n\t\t});\n\t\tif (respuesta.status === 404) return null;\n\t\tif (!respuesta.ok) {\n\t\t\tthrow new Error(`broker /v1/credential: ${respuesta.status} ${await respuesta.text()}`);\n\t\t}\n\t\tconst datos = (await respuesta.json()) as { id: string; valor: string };\n\t\t// Deliberado: no `this.ultimaCredencial = datos` ni nada parecido. El\n\t\t// valor cruza esta función y desaparece de aquí.\n\t\treturn { id: datos.id, valor: datos.valor };\n\t}\n\n\t/** Reporta cómo fue usar una credencial ya entregada. El broker distingue 401 de 429 con esto. */\n\tasync reportarUso(id: string, resultado: ResultadoDeUso): Promise<EfectoDeUso | null> {\n\t\tconst respuesta = await fetch(`${this.url}/v1/usage`, {\n\t\t\tmethod: \"POST\",\n\t\t\theaders: this.cabeceras(),\n\t\t\tbody: JSON.stringify({ id, ...resultado }),\n\t\t});\n\t\tif (respuesta.status === 404) return null;\n\t\tif (!respuesta.ok) {\n\t\t\tthrow new Error(`broker /v1/usage: ${respuesta.status} ${await respuesta.text()}`);\n\t\t}\n\t\treturn (await respuesta.json()) as EfectoDeUso;\n\t}\n\n\t/** Vista del pool sin secretos: qué credenciales hay y en qué estado. */\n\tasync snapshot(): Promise<FilaSnapshot[]> {\n\t\tconst respuesta = await fetch(`${this.url}/v1/snapshot`, { headers: this.cabeceras() });\n\t\tif (!respuesta.ok) {\n\t\t\tthrow new Error(`broker /v1/snapshot: ${respuesta.status} ${await respuesta.text()}`);\n\t\t}\n\t\tconst datos = (await respuesta.json()) as { credenciales: FilaSnapshot[] };\n\t\treturn datos.credenciales;\n\t}\n\n\t/** Liveness sin bearer. `false` en cualquier fallo de red, no lanza. */\n\tasync salud(): Promise<boolean> {\n\t\ttry {\n\t\t\tconst respuesta = await fetch(`${this.url}/v1/health`);\n\t\t\treturn respuesta.ok;\n\t\t} catch {\n\t\t\treturn false;\n\t\t}\n\t}\n}\n"]}

package/dist/core/credenciales/cliente.js

@@ -0,0 +1,81 @@
+/**
+ * Cliente del broker de credenciales.
+ *
+ * Regla de diseño, y es la que hace verificable "el cliente no tiene el token
+ * en su proceso": el secreto que devuelve `resolverCredencial` NUNCA se asigna
+ * a un campo de esta clase. Sale de la función, el llamador decide qué hacer
+ * con él, y esta instancia no guarda nada más que la URL y el bearer del
+ * broker (que no son el secreto de ningún proveedor). Ningún método escribe a
+ * disco — la credencial vive, como mucho, en la pila de quien la usó para una
+ * sola petición.
+ */
+export class ClienteBroker {
+    url;
+    token;
+    nombreCliente;
+    constructor(opciones) {
+        this.url = opciones.url.replace(/\/$/, "");
+        this.token = opciones.token;
+        this.nombreCliente = opciones.cliente;
+    }
+    cabeceras() {
+        return { "content-type": "application/json", authorization: `Bearer ${this.token}` };
+    }
+    /**
+     * Pide una credencial al broker y la devuelve para uso inmediato.
+     *
+     * `null` = el broker no tiene ninguna credencial activa para ese proveedor
+     * (todas bloqueadas, o proveedor sin dar de alta) — "no hay nada", que se
+     * distingue de una excepción, que es "no he podido hablar con el broker".
+     */
+    async resolverCredencial(proveedor, promptCacheKey) {
+        const respuesta = await fetch(`${this.url}/v1/credential`, {
+            method: "POST",
+            headers: this.cabeceras(),
+            body: JSON.stringify({ proveedor, promptCacheKey, cliente: this.nombreCliente }),
+        });
+        if (respuesta.status === 404)
+            return null;
+        if (!respuesta.ok) {
+            throw new Error(`broker /v1/credential: ${respuesta.status} ${await respuesta.text()}`);
+        }
+        const datos = (await respuesta.json());
+        // Deliberado: no `this.ultimaCredencial = datos` ni nada parecido. El
+        // valor cruza esta función y desaparece de aquí.
+        return { id: datos.id, valor: datos.valor };
+    }
+    /** Reporta cómo fue usar una credencial ya entregada. El broker distingue 401 de 429 con esto. */
+    async reportarUso(id, resultado) {
+        const respuesta = await fetch(`${this.url}/v1/usage`, {
+            method: "POST",
+            headers: this.cabeceras(),
+            body: JSON.stringify({ id, ...resultado }),
+        });
+        if (respuesta.status === 404)
+            return null;
+        if (!respuesta.ok) {
+            throw new Error(`broker /v1/usage: ${respuesta.status} ${await respuesta.text()}`);
+        }
+        return (await respuesta.json());
+    }
+    /** Vista del pool sin secretos: qué credenciales hay y en qué estado. */
+    async snapshot() {
+        const respuesta = await fetch(`${this.url}/v1/snapshot`, { headers: this.cabeceras() });
+        if (!respuesta.ok) {
+            throw new Error(`broker /v1/snapshot: ${respuesta.status} ${await respuesta.text()}`);
+        }
+        const datos = (await respuesta.json());
+        return datos.credenciales;
+    }
+    /** Liveness sin bearer. `false` en cualquier fallo de red, no lanza. */
+    async salud() {
+        try {
+            const respuesta = await fetch(`${this.url}/v1/health`);
+            return respuesta.ok;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+//# sourceMappingURL=cliente.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cliente.js","sourceRoot":"","sources":["../../../src/core/credenciales/cliente.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Cliente del broker de credenciales.\n *\n * Regla de diseño, y es la que hace verificable \"el cliente no tiene el token\n * en su proceso\": el secreto que devuelve `resolverCredencial` NUNCA se asigna\n * a un campo de esta clase. Sale de la función, el llamador decide qué hacer\n * con él, y esta instancia no guarda nada más que la URL y el bearer del\n * broker (que no son el secreto de ningún proveedor). Ningún método escribe a\n * disco — la credencial vive, como mucho, en la pila de quien la usó para una\n * sola petición.\n */\n\nexport interface OpcionesClienteBroker {\n\turl: string;\n\ttoken: string;\n\t/** Nombre identificador de este cliente, para que el libro de sesión diga quién pidió qué. */\n\tcliente?: string;\n}\n\nexport interface CredencialResuelta {\n\tid: string;\n\tvalor: string;\n}\n\nexport type ResultadoDeUso = { ok: true } | { ok: false; estadoHttp?: number; mensaje: string };\n\nexport interface EfectoDeUso {\n\tclase: string;\n\testado: \"activa\" | \"bloqueada\";\n}\n\nexport interface FilaSnapshot {\n\tid: string;\n\tproveedor: string;\n\testado: \"activa\" | \"bloqueada\";\n\tmotivoBloqueo?: string;\n}\n\nexport class ClienteBroker {\n\tprivate readonly url: string;\n\tprivate readonly token: string;\n\tprivate readonly nombreCliente?: string;\n\n\tconstructor(opciones: OpcionesClienteBroker) {\n\t\tthis.url = opciones.url.replace(/\\/$/, \"\");\n\t\tthis.token = opciones.token;\n\t\tthis.nombreCliente = opciones.cliente;\n\t}\n\n\tprivate cabeceras(): Record<string, string> {\n\t\treturn { \"content-type\": \"application/json\", authorization: `Bearer ${this.token}` };\n\t}\n\n\t/**\n\t * Pide una credencial al broker y la devuelve para uso inmediato.\n\t *\n\t * `null` = el broker no tiene ninguna credencial activa para ese proveedor\n\t * (todas bloqueadas, o proveedor sin dar de alta) — \"no hay nada\", que se\n\t * distingue de una excepción, que es \"no he podido hablar con el broker\".\n\t */\n\tasync resolverCredencial(proveedor: string, promptCacheKey?: string): Promise<CredencialResuelta | null> {\n\t\tconst respuesta = await fetch(`${this.url}/v1/credential`, {\n\t\t\tmethod: \"POST\",\n\t\t\theaders: this.cabeceras(),\n\t\t\tbody: JSON.stringify({ proveedor, promptCacheKey, cliente: this.nombreCliente }),\n\t\t});\n\t\tif (respuesta.status === 404) return null;\n\t\tif (!respuesta.ok) {\n\t\t\tthrow new Error(`broker /v1/credential: ${respuesta.status} ${await respuesta.text()}`);\n\t\t}\n\t\tconst datos = (await respuesta.json()) as { id: string; valor: string };\n\t\t// Deliberado: no `this.ultimaCredencial = datos` ni nada parecido. El\n\t\t// valor cruza esta función y desaparece de aquí.\n\t\treturn { id: datos.id, valor: datos.valor };\n\t}\n\n\t/** Reporta cómo fue usar una credencial ya entregada. El broker distingue 401 de 429 con esto. */\n\tasync reportarUso(id: string, resultado: ResultadoDeUso): Promise<EfectoDeUso | null> {\n\t\tconst respuesta = await fetch(`${this.url}/v1/usage`, {\n\t\t\tmethod: \"POST\",\n\t\t\theaders: this.cabeceras(),\n\t\t\tbody: JSON.stringify({ id, ...resultado }),\n\t\t});\n\t\tif (respuesta.status === 404) return null;\n\t\tif (!respuesta.ok) {\n\t\t\tthrow new Error(`broker /v1/usage: ${respuesta.status} ${await respuesta.text()}`);\n\t\t}\n\t\treturn (await respuesta.json()) as EfectoDeUso;\n\t}\n\n\t/** Vista del pool sin secretos: qué credenciales hay y en qué estado. */\n\tasync snapshot(): Promise<FilaSnapshot[]> {\n\t\tconst respuesta = await fetch(`${this.url}/v1/snapshot`, { headers: this.cabeceras() });\n\t\tif (!respuesta.ok) {\n\t\t\tthrow new Error(`broker /v1/snapshot: ${respuesta.status} ${await respuesta.text()}`);\n\t\t}\n\t\tconst datos = (await respuesta.json()) as { credenciales: FilaSnapshot[] };\n\t\treturn datos.credenciales;\n\t}\n\n\t/** Liveness sin bearer. `false` en cualquier fallo de red, no lanza. */\n\tasync salud(): Promise<boolean> {\n\t\ttry {\n\t\t\tconst respuesta = await fetch(`${this.url}/v1/health`);\n\t\t\treturn respuesta.ok;\n\t\t} catch {\n\t\t\treturn false;\n\t\t}\n\t}\n}\n"]}

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

@@ -0,0 +1,96 @@
+/**
+ * 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`.
+ */
+/** Una credencial tal como la da quien configura el pool: sin estado todavía. */
+export interface CredencialDelPool {
+    id: string;
+    proveedor: string;
+    valor: string;
+}
+export type EstadoCredencial = "activa" | "bloqueada";
+/** Lo que se le enseña a un cliente que pide credencial: el secreto, para usarlo. */
+export interface CredencialElegida {
+    id: string;
+    proveedor: string;
+    valor: string;
+}
+/** Lo que reporta el cliente tras usar una credencial. */
+export type ResultadoDeUso = {
+    ok: true;
+} | {
+    ok: false;
+    estadoHttp?: number;
+    mensaje: string;
+};
+/** Lo que devuelve `marcarUso`: la clase de error (o "ok") y el estado resultante. */
+export interface EfectoDeUso {
+    clase: string;
+    estado: EstadoCredencial;
+}
+/** Fila sin el secreto — lo que se puede enseñar por `/v1/snapshot` sin filtrar nada. */
+export interface FilaPublica {
+    id: string;
+    proveedor: string;
+    estado: EstadoCredencial;
+    motivoBloqueo?: string;
+}
+export declare class CredencialPool {
+    private readonly porId;
+    private readonly porProveedor;
+    /** `proveedor\0promptCacheKey` -> id de la credencial pegada a esa sesión. */
+    private readonly pegajosidad;
+    /** Cursor de reparto round-robin por proveedor, para las peticiones sin pegajosidad. */
+    private readonly cursores;
+    constructor(credenciales: Record<string, CredencialDelPool[]>);
+    private clavePegajosidad;
+    private siguiente;
+    /**
+     * 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: string, promptCacheKey?: string): CredencialElegida | null;
+    /**
+     * 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: string, resultado: ResultadoDeUso): EfectoDeUso | null;
+    /** Vista pública del pool: sin secretos, para `/v1/snapshot`. */
+    snapshot(): FilaPublica[];
+}
+//# sourceMappingURL=pool.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../../../src/core/credenciales/pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAIH,kFAAiF;AACjF,MAAM,WAAW,iBAAiB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,WAAW,CAAC;AAQtD,sFAAqF;AACrF,MAAM,WAAW,iBAAiB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACd;AAED,0DAA0D;AAC1D,MAAM,MAAM,cAAc,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhG,sFAAsF;AACtF,MAAM,WAAW,WAAW;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,gBAAgB,CAAC;CACzB;AAED,4FAAyF;AACzF,MAAM,WAAW,WAAW;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,gBAAgB,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,qBAAa,cAAc;IAC1B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA2B;IACjD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA6B;IAC1D,+EAA8E;IAC9E,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;IACzD,wFAAwF;IACxF,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6B;IAEtD,YAAY,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,EAAE,CAAC,EAM5D;IAED,OAAO,CAAC,gBAAgB;IAIxB,OAAO,CAAC,SAAS;IAMjB;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI,CAqB3E;IAED;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,cAAc,GAAG,WAAW,GAAG,IAAI,CAyBnE;IAED,kEAAiE;IACjE,QAAQ,IAAI,WAAW,EAAE,CAOxB;CACD","sourcesContent":["/**\n * Piscina de credenciales por proveedor.\n *\n * El hueco que esto tapa: hoy cada desarrollador tiene sus claves en su propio\n * portátil. `oh-my-pi` (packages/ai/src/auth-broker de ese repo) resuelve esto\n * con un servidor que guarda las credenciales y las reparte; lo que se copia\n * aquí de su diseño son dos decisiones concretas, no el código:\n *\n * 1. **Conmutación a una hermana cuando una cuenta falla de verdad.** Un 401\n *    (`credencial-invalida` o `sin-credencial` en la taxonomía de\n *    `../errores/proveedor.ts`) saca la credencial del pool: la siguiente\n *    petición usa otra. Un 429 (`limite-de-tasa`) NO la saca — la cuenta sigue\n *    siendo buena, solo está ocupada un rato. Confundir los dos es el fallo\n *    que quema cuentas sanas: se ha visto documentado en el propio\n *    `errores/proveedor.ts` como el error más caro de mezclar.\n * 2. **Pegajosidad por sesión vía `prompt_cache_key`.** Sin esto, repartir\n *    entre cuentas rompería el caché de prompts del proveedor en cada turno —\n *    cada petición de la misma conversación pagaría el prefijo entero de\n *    nuevo. Una `prompt_cache_key` se queda pegada a la misma credencial\n *    mientras esa credencial siga activa; solo se realoja cuando la que tenía\n *    pegada se bloquea.\n *\n * Lo que NO se copia: el pool vive en memoria del proceso `ada-cli serve\n * --broker`, no en SQLite. Reiniciar el broker olvida qué estaba bloqueado y\n * la pegajosidad — aceptable para el alcance de hoy (equipos pequeños, un\n * broker por equipo); si hace falta sobrevivir a reinicios, el punto de\n * extensión es cargar/guardar `estado()` a un fichero en `iniciar`/`cerrar`.\n */\n\nimport { clasificarError } from \"../errores/proveedor.ts\";\n\n/** Una credencial tal como la da quien configura el pool: sin estado todavía. */\nexport interface CredencialDelPool {\n\tid: string;\n\tproveedor: string;\n\tvalor: string;\n}\n\nexport type EstadoCredencial = \"activa\" | \"bloqueada\";\n\ninterface Fila extends CredencialDelPool {\n\testado: EstadoCredencial;\n\tmotivoBloqueo?: string;\n\tbloqueadaEn?: number;\n}\n\n/** Lo que se le enseña a un cliente que pide credencial: el secreto, para usarlo. */\nexport interface CredencialElegida {\n\tid: string;\n\tproveedor: string;\n\tvalor: string;\n}\n\n/** Lo que reporta el cliente tras usar una credencial. */\nexport type ResultadoDeUso = { ok: true } | { ok: false; estadoHttp?: number; mensaje: string };\n\n/** Lo que devuelve `marcarUso`: la clase de error (o \"ok\") y el estado resultante. */\nexport interface EfectoDeUso {\n\tclase: string;\n\testado: EstadoCredencial;\n}\n\n/** Fila sin el secreto — lo que se puede enseñar por `/v1/snapshot` sin filtrar nada. */\nexport interface FilaPublica {\n\tid: string;\n\tproveedor: string;\n\testado: EstadoCredencial;\n\tmotivoBloqueo?: string;\n}\n\nexport class CredencialPool {\n\tprivate readonly porId = new Map<string, Fila>();\n\tprivate readonly porProveedor = new Map<string, Fila[]>();\n\t/** `proveedor\\0promptCacheKey` -> id de la credencial pegada a esa sesión. */\n\tprivate readonly pegajosidad = new Map<string, string>();\n\t/** Cursor de reparto round-robin por proveedor, para las peticiones sin pegajosidad. */\n\tprivate readonly cursores = new Map<string, number>();\n\n\tconstructor(credenciales: Record<string, CredencialDelPool[]>) {\n\t\tfor (const [proveedor, lista] of Object.entries(credenciales)) {\n\t\t\tconst filas = lista.map((c): Fila => ({ ...c, proveedor, estado: \"activa\" }));\n\t\t\tthis.porProveedor.set(proveedor, filas);\n\t\t\tfor (const fila of filas) this.porId.set(fila.id, fila);\n\t\t}\n\t}\n\n\tprivate clavePegajosidad(proveedor: string, promptCacheKey: string): string {\n\t\treturn `${proveedor} ${promptCacheKey}`;\n\t}\n\n\tprivate siguiente(proveedor: string, activas: Fila[]): Fila {\n\t\tconst cursor = this.cursores.get(proveedor) ?? 0;\n\t\tthis.cursores.set(proveedor, cursor + 1);\n\t\treturn activas[cursor % activas.length];\n\t}\n\n\t/**\n\t * Elige una credencial activa para `proveedor`.\n\t *\n\t * Sin `promptCacheKey`: reparto round-robin entre las activas. Con\n\t * `promptCacheKey`: si la sesión ya tenía una credencial pegada y sigue\n\t * activa, se reutiliza (no rompe el caché de prompts); si no, se elige una\n\t * nueva y se fija para las próximas llamadas con la misma clave.\n\t *\n\t * `null` = no hay ninguna credencial activa para ese proveedor. Es \"no hay\n\t * nada\", no \"no he podido\" — todas las filas existen, todas están\n\t * bloqueadas, y decirlo así es lo que distingue esto de un fallo del pool.\n\t */\n\telegir(proveedor: string, promptCacheKey?: string): CredencialElegida | null {\n\t\tconst filas = this.porProveedor.get(proveedor) ?? [];\n\t\tconst activas = filas.filter((f) => f.estado === \"activa\");\n\t\tif (activas.length === 0) return null;\n\n\t\tif (promptCacheKey) {\n\t\t\tconst clave = this.clavePegajosidad(proveedor, promptCacheKey);\n\t\t\tconst idPegado = this.pegajosidad.get(clave);\n\t\t\tconst fila = idPegado ? this.porId.get(idPegado) : undefined;\n\t\t\tif (fila && fila.estado === \"activa\") {\n\t\t\t\treturn { id: fila.id, proveedor, valor: fila.valor };\n\t\t\t}\n\t\t\t// Sin pegajosidad válida (primera vez, o la que tenía pegada se bloqueó):\n\t\t\t// elige una hermana y la fija para las próximas peticiones de esta sesión.\n\t\t\tconst elegida = this.siguiente(proveedor, activas);\n\t\t\tthis.pegajosidad.set(clave, elegida.id);\n\t\t\treturn { id: elegida.id, proveedor, valor: elegida.valor };\n\t\t}\n\n\t\tconst elegida = this.siguiente(proveedor, activas);\n\t\treturn { id: elegida.id, proveedor, valor: elegida.valor };\n\t}\n\n\t/**\n\t * Registra el resultado de usar una credencial ya entregada.\n\t *\n\t * `null` = id desconocido (no hay tal credencial en el pool) — se distingue\n\t * de \"la marcó y sigue activa\" para que quien llama pueda contestar 404 en\n\t * vez de fingir un 200.\n\t */\n\tmarcarUso(id: string, resultado: ResultadoDeUso): EfectoDeUso | null {\n\t\tconst fila = this.porId.get(id);\n\t\tif (!fila) return null;\n\n\t\tif (resultado.ok) return { clase: \"ok\", estado: fila.estado };\n\n\t\tconst clasificado = clasificarError({ mensaje: resultado.mensaje, estado: resultado.estadoHttp });\n\n\t\t// Solo un 401/403 de credencial mala saca la fila del pool. Un 429\n\t\t// (`limite-de-tasa`) deja `fila.estado` intacto a propósito: es la\n\t\t// distinción que pide la tarea, y confundirla quema cuentas que solo\n\t\t// estaban ocupadas.\n\t\tif (clasificado.clase === \"credencial-invalida\" || clasificado.clase === \"sin-credencial\") {\n\t\t\tfila.estado = \"bloqueada\";\n\t\t\tfila.motivoBloqueo = clasificado.clase;\n\t\t\tfila.bloqueadaEn = Date.now();\n\t\t\t// Toda sesión pegada a esta credencial se suelta: la próxima `elegir`\n\t\t\t// con la misma prompt_cache_key tiene que caer en una hermana, no\n\t\t\t// seguir devolviendo la que ya sabemos que está mala.\n\t\t\tfor (const [clave, idPegado] of this.pegajosidad) {\n\t\t\t\tif (idPegado === id) this.pegajosidad.delete(clave);\n\t\t\t}\n\t\t}\n\n\t\treturn { clase: clasificado.clase, estado: fila.estado };\n\t}\n\n\t/** Vista pública del pool: sin secretos, para `/v1/snapshot`. */\n\tsnapshot(): FilaPublica[] {\n\t\treturn [...this.porId.values()].map((f) => ({\n\t\t\tid: f.id,\n\t\t\tproveedor: f.proveedor,\n\t\t\testado: f.estado,\n\t\t\tmotivoBloqueo: f.motivoBloqueo,\n\t\t}));\n\t}\n}\n"]}

package/dist/core/credenciales/pool.js

@@ -0,0 +1,128 @@
+/**
+ * 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";
+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();
+    constructor(credenciales) {
+        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 (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 };
+    }
+    /**
+     * 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;
+        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((f) => ({
+            id: f.id,
+            proveedor: f.proveedor,
+            estado: f.estado,
+            motivoBloqueo: f.motivoBloqueo,
+        }));
+    }
+}
+//# 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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","sourcesContent":["/**\n * Piscina de credenciales por proveedor.\n *\n * El hueco que esto tapa: hoy cada desarrollador tiene sus claves en su propio\n * portátil. `oh-my-pi` (packages/ai/src/auth-broker de ese repo) resuelve esto\n * con un servidor que guarda las credenciales y las reparte; lo que se copia\n * aquí de su diseño son dos decisiones concretas, no el código:\n *\n * 1. **Conmutación a una hermana cuando una cuenta falla de verdad.** Un 401\n *    (`credencial-invalida` o `sin-credencial` en la taxonomía de\n *    `../errores/proveedor.ts`) saca la credencial del pool: la siguiente\n *    petición usa otra. Un 429 (`limite-de-tasa`) NO la saca — la cuenta sigue\n *    siendo buena, solo está ocupada un rato. Confundir los dos es el fallo\n *    que quema cuentas sanas: se ha visto documentado en el propio\n *    `errores/proveedor.ts` como el error más caro de mezclar.\n * 2. **Pegajosidad por sesión vía `prompt_cache_key`.** Sin esto, repartir\n *    entre cuentas rompería el caché de prompts del proveedor en cada turno —\n *    cada petición de la misma conversación pagaría el prefijo entero de\n *    nuevo. Una `prompt_cache_key` se queda pegada a la misma credencial\n *    mientras esa credencial siga activa; solo se realoja cuando la que tenía\n *    pegada se bloquea.\n *\n * Lo que NO se copia: el pool vive en memoria del proceso `ada-cli serve\n * --broker`, no en SQLite. Reiniciar el broker olvida qué estaba bloqueado y\n * la pegajosidad — aceptable para el alcance de hoy (equipos pequeños, un\n * broker por equipo); si hace falta sobrevivir a reinicios, el punto de\n * extensión es cargar/guardar `estado()` a un fichero en `iniciar`/`cerrar`.\n */\n\nimport { clasificarError } from \"../errores/proveedor.ts\";\n\n/** Una credencial tal como la da quien configura el pool: sin estado todavía. */\nexport interface CredencialDelPool {\n\tid: string;\n\tproveedor: string;\n\tvalor: string;\n}\n\nexport type EstadoCredencial = \"activa\" | \"bloqueada\";\n\ninterface Fila extends CredencialDelPool {\n\testado: EstadoCredencial;\n\tmotivoBloqueo?: string;\n\tbloqueadaEn?: number;\n}\n\n/** Lo que se le enseña a un cliente que pide credencial: el secreto, para usarlo. */\nexport interface CredencialElegida {\n\tid: string;\n\tproveedor: string;\n\tvalor: string;\n}\n\n/** Lo que reporta el cliente tras usar una credencial. */\nexport type ResultadoDeUso = { ok: true } | { ok: false; estadoHttp?: number; mensaje: string };\n\n/** Lo que devuelve `marcarUso`: la clase de error (o \"ok\") y el estado resultante. */\nexport interface EfectoDeUso {\n\tclase: string;\n\testado: EstadoCredencial;\n}\n\n/** Fila sin el secreto — lo que se puede enseñar por `/v1/snapshot` sin filtrar nada. */\nexport interface FilaPublica {\n\tid: string;\n\tproveedor: string;\n\testado: EstadoCredencial;\n\tmotivoBloqueo?: string;\n}\n\nexport class CredencialPool {\n\tprivate readonly porId = new Map<string, Fila>();\n\tprivate readonly porProveedor = new Map<string, Fila[]>();\n\t/** `proveedor\\0promptCacheKey` -> id de la credencial pegada a esa sesión. */\n\tprivate readonly pegajosidad = new Map<string, string>();\n\t/** Cursor de reparto round-robin por proveedor, para las peticiones sin pegajosidad. */\n\tprivate readonly cursores = new Map<string, number>();\n\n\tconstructor(credenciales: Record<string, CredencialDelPool[]>) {\n\t\tfor (const [proveedor, lista] of Object.entries(credenciales)) {\n\t\t\tconst filas = lista.map((c): Fila => ({ ...c, proveedor, estado: \"activa\" }));\n\t\t\tthis.porProveedor.set(proveedor, filas);\n\t\t\tfor (const fila of filas) this.porId.set(fila.id, fila);\n\t\t}\n\t}\n\n\tprivate clavePegajosidad(proveedor: string, promptCacheKey: string): string {\n\t\treturn `${proveedor} ${promptCacheKey}`;\n\t}\n\n\tprivate siguiente(proveedor: string, activas: Fila[]): Fila {\n\t\tconst cursor = this.cursores.get(proveedor) ?? 0;\n\t\tthis.cursores.set(proveedor, cursor + 1);\n\t\treturn activas[cursor % activas.length];\n\t}\n\n\t/**\n\t * Elige una credencial activa para `proveedor`.\n\t *\n\t * Sin `promptCacheKey`: reparto round-robin entre las activas. Con\n\t * `promptCacheKey`: si la sesión ya tenía una credencial pegada y sigue\n\t * activa, se reutiliza (no rompe el caché de prompts); si no, se elige una\n\t * nueva y se fija para las próximas llamadas con la misma clave.\n\t *\n\t * `null` = no hay ninguna credencial activa para ese proveedor. Es \"no hay\n\t * nada\", no \"no he podido\" — todas las filas existen, todas están\n\t * bloqueadas, y decirlo así es lo que distingue esto de un fallo del pool.\n\t */\n\telegir(proveedor: string, promptCacheKey?: string): CredencialElegida | null {\n\t\tconst filas = this.porProveedor.get(proveedor) ?? [];\n\t\tconst activas = filas.filter((f) => f.estado === \"activa\");\n\t\tif (activas.length === 0) return null;\n\n\t\tif (promptCacheKey) {\n\t\t\tconst clave = this.clavePegajosidad(proveedor, promptCacheKey);\n\t\t\tconst idPegado = this.pegajosidad.get(clave);\n\t\t\tconst fila = idPegado ? this.porId.get(idPegado) : undefined;\n\t\t\tif (fila && fila.estado === \"activa\") {\n\t\t\t\treturn { id: fila.id, proveedor, valor: fila.valor };\n\t\t\t}\n\t\t\t// Sin pegajosidad válida (primera vez, o la que tenía pegada se bloqueó):\n\t\t\t// elige una hermana y la fija para las próximas peticiones de esta sesión.\n\t\t\tconst elegida = this.siguiente(proveedor, activas);\n\t\t\tthis.pegajosidad.set(clave, elegida.id);\n\t\t\treturn { id: elegida.id, proveedor, valor: elegida.valor };\n\t\t}\n\n\t\tconst elegida = this.siguiente(proveedor, activas);\n\t\treturn { id: elegida.id, proveedor, valor: elegida.valor };\n\t}\n\n\t/**\n\t * Registra el resultado de usar una credencial ya entregada.\n\t *\n\t * `null` = id desconocido (no hay tal credencial en el pool) — se distingue\n\t * de \"la marcó y sigue activa\" para que quien llama pueda contestar 404 en\n\t * vez de fingir un 200.\n\t */\n\tmarcarUso(id: string, resultado: ResultadoDeUso): EfectoDeUso | null {\n\t\tconst fila = this.porId.get(id);\n\t\tif (!fila) return null;\n\n\t\tif (resultado.ok) return { clase: \"ok\", estado: fila.estado };\n\n\t\tconst clasificado = clasificarError({ mensaje: resultado.mensaje, estado: resultado.estadoHttp });\n\n\t\t// Solo un 401/403 de credencial mala saca la fila del pool. Un 429\n\t\t// (`limite-de-tasa`) deja `fila.estado` intacto a propósito: es la\n\t\t// distinción que pide la tarea, y confundirla quema cuentas que solo\n\t\t// estaban ocupadas.\n\t\tif (clasificado.clase === \"credencial-invalida\" || clasificado.clase === \"sin-credencial\") {\n\t\t\tfila.estado = \"bloqueada\";\n\t\t\tfila.motivoBloqueo = clasificado.clase;\n\t\t\tfila.bloqueadaEn = Date.now();\n\t\t\t// Toda sesión pegada a esta credencial se suelta: la próxima `elegir`\n\t\t\t// con la misma prompt_cache_key tiene que caer en una hermana, no\n\t\t\t// seguir devolviendo la que ya sabemos que está mala.\n\t\t\tfor (const [clave, idPegado] of this.pegajosidad) {\n\t\t\t\tif (idPegado === id) this.pegajosidad.delete(clave);\n\t\t\t}\n\t\t}\n\n\t\treturn { clase: clasificado.clase, estado: fila.estado };\n\t}\n\n\t/** Vista pública del pool: sin secretos, para `/v1/snapshot`. */\n\tsnapshot(): FilaPublica[] {\n\t\treturn [...this.porId.values()].map((f) => ({\n\t\t\tid: f.id,\n\t\t\tproveedor: f.proveedor,\n\t\t\testado: f.estado,\n\t\t\tmotivoBloqueo: f.motivoBloqueo,\n\t\t}));\n\t}\n}\n"]}

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