@hoilab/ada-cli 0.84.22 → 0.85.0

package/dist/core/prompt-cache/stabilize.js

@@ -0,0 +1,137 @@
+/**
+ * Estabilización del prefijo del prompt.
+ *
+ * Las cachés de prompt (DeepSeek, OpenAI, Anthropic) casan por PREFIJO: un byte
+ * distinto en la posición N invalida todo lo que va detrás. En DeepSeek el hit
+ * cuesta ~31x menos que el miss, así que el coste de un cambio no es
+ * proporcional a su tamaño sino a su POSICIÓN.
+ *
+ * Esto reordena el system prompt para que todo lo estable quede por delante y lo
+ * dinámico detrás de un separador, de modo que el sufijo invalidado sea lo más
+ * pequeño posible.
+ *
+ * Dos decisiones de diseño que no son obvias:
+ *
+ * 1. Los candidatos ANIDAN — el bloque de un context file contiene su propio
+ *    contenido a secas. Por eso las ocurrencias se cuentan contra UNA instantánea
+ *    inmutable del prompt original, no contra el texto que va quedando: recontar
+ *    tras cada extracción daría resultados incoherentes. Cualquier candidato que
+ *    no aparezca EXACTAMENTE una vez se deja en su sitio.
+ *
+ * 2. Hay guardia de integridad. Si tras reordenar desaparece cualquier marcador
+ *    estructural (una etiqueta, un delimitador), se descarta la reescritura
+ *    entera y se devuelve el original. Un reordenado con un bug que corrompe el
+ *    prompt en silencio es mucho peor que no cachear.
+ */
+/** Por debajo de esto un "candidato" es ruido que aparece en cualquier sitio. */
+const MIN_CANDIDATE_LENGTH = 8;
+/** Separador entre la zona estable y la dinámica. */
+export const STABLE_SEPARATOR = "\n\n---\n\n";
+/**
+ * Ficheros de contexto que se consideran estables.
+ *
+ * El tamaño NO es criterio: un fichero grande puede cambiar cada turno. Solo se
+ * suben ficheros de instrucciones cuyo contenido se sabe estable durante la
+ * sesión.
+ */
+const STABLE_CONTEXT_FILES = /(^|\/)(agents(\.override)?\.md|claude\.md|gemini\.md|cursor\.md)$/i;
+export function isStableContextFile(path) {
+    return STABLE_CONTEXT_FILES.test(path.replace(/\\/g, "/").toLowerCase());
+}
+/**
+ * Marcadores estructurales: etiquetas y delimitadores de bloque. Si el
+ * reordenado pierde alguno, algo se ha comido texto.
+ */
+export function extractStructuralMarkers(text) {
+    const markers = [];
+    for (const match of text.matchAll(/<\/?[a-zA-Z][\w-]*>/g))
+        markers.push(match[0]);
+    for (const match of text.matchAll(/<!--\s*[A-Z_]+:(START|END)\s*-->/g))
+        markers.push(match[0]);
+    return markers.sort();
+}
+/** Construye los bloques candidatos a subir, en orden determinista. */
+export function buildStableCandidates(input) {
+    const candidates = [];
+    const push = (value) => {
+        const trimmed = value?.trim();
+        if (trimmed && trimmed.length >= MIN_CANDIDATE_LENGTH)
+            candidates.push(trimmed);
+    };
+    push(input.customPrompt);
+    push(input.appendSystemPrompt);
+    for (const guideline of input.promptGuidelines ?? [])
+        push(`- ${guideline}`);
+    for (const file of input.contextFiles ?? []) {
+        if (!isStableContextFile(file.path))
+            continue;
+        // Dos formas: con cabecera de ruta y sin ella. El ensamblador puede usar
+        // cualquiera de las dos y solo una casará.
+        push(`## ${file.path}\n\n${file.content}`);
+        push(file.content);
+    }
+    return candidates;
+}
+/**
+ * Reordena el prompt: estable primero, dinámico después del separador.
+ *
+ * No-op seguro: si nada casa exactamente una vez, o si la guardia de integridad
+ * salta, devuelve el prompt original sin tocar.
+ */
+export function stabilizeSystemPrompt(input) {
+    const original = input.prompt;
+    if (!original.trim())
+        return { prompt: original, lifted: 0, rolledBack: false };
+    const candidates = buildStableCandidates(input);
+    if (candidates.length === 0)
+        return { prompt: original, lifted: 0, rolledBack: false };
+    // Contar SIEMPRE contra la instantánea original: los candidatos anidan.
+    const snapshot = original;
+    const occurrencesOf = (needle) => {
+        let count = 0;
+        let from = 0;
+        while (true) {
+            const at = snapshot.indexOf(needle, from);
+            if (at === -1)
+                break;
+            count++;
+            from = at + needle.length;
+            if (count > 1)
+                break; // con saber que hay más de una basta
+        }
+        return count;
+    };
+    const stable = [];
+    let rest = original;
+    const seen = new Set();
+    for (const candidate of candidates) {
+        if (seen.has(candidate))
+            continue;
+        if (occurrencesOf(candidate) !== 1)
+            continue;
+        const at = rest.indexOf(candidate);
+        if (at === -1)
+            continue; // ya extraído dentro de otro candidato
+        seen.add(candidate);
+        stable.push(candidate);
+        rest = rest.slice(0, at) + rest.slice(at + candidate.length);
+    }
+    if (stable.length === 0)
+        return { prompt: original, lifted: 0, rolledBack: false };
+    const stableJoined = stable.join("\n\n");
+    // Ya estabilizado: sin esto una segunda pasada apilaría otro separador y el
+    // prefijo se movería en cada turno — exactamente lo contrario de lo que
+    // buscamos. La idempotencia no es elegancia aquí, es la propiedad.
+    if (original.startsWith(stableJoined + STABLE_SEPARATOR)) {
+        return { prompt: original, lifted: 0, rolledBack: false };
+    }
+    const rewritten = `${stableJoined}${STABLE_SEPARATOR}${rest.trim()}`;
+    // Guardia de integridad: ningún marcador estructural puede desaparecer.
+    const before = extractStructuralMarkers(original);
+    const after = extractStructuralMarkers(rewritten);
+    if (before.length !== after.length || before.some((m, i) => m !== after[i])) {
+        return { prompt: original, lifted: 0, rolledBack: true };
+    }
+    return { prompt: rewritten, lifted: stable.length, rolledBack: false };
+}
+//# sourceMappingURL=stabilize.js.map

package/dist/core/prompt-cache/stabilize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stabilize.js","sourceRoot":"","sources":["../../../src/core/prompt-cache/stabilize.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Estabilización del prefijo del prompt.\n *\n * Las cachés de prompt (DeepSeek, OpenAI, Anthropic) casan por PREFIJO: un byte\n * distinto en la posición N invalida todo lo que va detrás. En DeepSeek el hit\n * cuesta ~31x menos que el miss, así que el coste de un cambio no es\n * proporcional a su tamaño sino a su POSICIÓN.\n *\n * Esto reordena el system prompt para que todo lo estable quede por delante y lo\n * dinámico detrás de un separador, de modo que el sufijo invalidado sea lo más\n * pequeño posible.\n *\n * Dos decisiones de diseño que no son obvias:\n *\n * 1. Los candidatos ANIDAN — el bloque de un context file contiene su propio\n *    contenido a secas. Por eso las ocurrencias se cuentan contra UNA instantánea\n *    inmutable del prompt original, no contra el texto que va quedando: recontar\n *    tras cada extracción daría resultados incoherentes. Cualquier candidato que\n *    no aparezca EXACTAMENTE una vez se deja en su sitio.\n *\n * 2. Hay guardia de integridad. Si tras reordenar desaparece cualquier marcador\n *    estructural (una etiqueta, un delimitador), se descarta la reescritura\n *    entera y se devuelve el original. Un reordenado con un bug que corrompe el\n *    prompt en silencio es mucho peor que no cachear.\n */\n\n/** Por debajo de esto un \"candidato\" es ruido que aparece en cualquier sitio. */\nconst MIN_CANDIDATE_LENGTH = 8;\n\n/** Separador entre la zona estable y la dinámica. */\nexport const STABLE_SEPARATOR = \"\\n\\n---\\n\\n\";\n\n/**\n * Ficheros de contexto que se consideran estables.\n *\n * El tamaño NO es criterio: un fichero grande puede cambiar cada turno. Solo se\n * suben ficheros de instrucciones cuyo contenido se sabe estable durante la\n * sesión.\n */\nconst STABLE_CONTEXT_FILES = /(^|\\/)(agents(\\.override)?\\.md|claude\\.md|gemini\\.md|cursor\\.md)$/i;\n\nexport function isStableContextFile(path: string): boolean {\n\treturn STABLE_CONTEXT_FILES.test(path.replace(/\\\\/g, \"/\").toLowerCase());\n}\n\nexport interface StabilizeInput {\n\t/** El system prompt ya ensamblado. */\n\tprompt: string;\n\t/** Prompt de sistema propio del usuario, si lo hay. */\n\tcustomPrompt?: string;\n\t/** Bloques añadidos al final (incluye la personalidad del engine). */\n\tappendSystemPrompt?: string;\n\t/** Guidelines por tool. */\n\tpromptGuidelines?: string[];\n\t/** Ficheros de contexto cargados. */\n\tcontextFiles?: Array<{ path: string; content: string }>;\n}\n\nexport interface StabilizeResult {\n\tprompt: string;\n\t/** Cuántos bloques se subieron al prefijo estable. */\n\tlifted: number;\n\t/** True si la guardia de integridad descartó la reescritura. */\n\trolledBack: boolean;\n}\n\n/**\n * Marcadores estructurales: etiquetas y delimitadores de bloque. Si el\n * reordenado pierde alguno, algo se ha comido texto.\n */\nexport function extractStructuralMarkers(text: string): string[] {\n\tconst markers: string[] = [];\n\tfor (const match of text.matchAll(/<\\/?[a-zA-Z][\\w-]*>/g)) markers.push(match[0]);\n\tfor (const match of text.matchAll(/<!--\\s*[A-Z_]+:(START|END)\\s*-->/g)) markers.push(match[0]);\n\treturn markers.sort();\n}\n\n/** Construye los bloques candidatos a subir, en orden determinista. */\nexport function buildStableCandidates(input: StabilizeInput): string[] {\n\tconst candidates: string[] = [];\n\tconst push = (value: string | undefined) => {\n\t\tconst trimmed = value?.trim();\n\t\tif (trimmed && trimmed.length >= MIN_CANDIDATE_LENGTH) candidates.push(trimmed);\n\t};\n\n\tpush(input.customPrompt);\n\tpush(input.appendSystemPrompt);\n\tfor (const guideline of input.promptGuidelines ?? []) push(`- ${guideline}`);\n\tfor (const file of input.contextFiles ?? []) {\n\t\tif (!isStableContextFile(file.path)) continue;\n\t\t// Dos formas: con cabecera de ruta y sin ella. El ensamblador puede usar\n\t\t// cualquiera de las dos y solo una casará.\n\t\tpush(`## ${file.path}\\n\\n${file.content}`);\n\t\tpush(file.content);\n\t}\n\treturn candidates;\n}\n\n/**\n * Reordena el prompt: estable primero, dinámico después del separador.\n *\n * No-op seguro: si nada casa exactamente una vez, o si la guardia de integridad\n * salta, devuelve el prompt original sin tocar.\n */\nexport function stabilizeSystemPrompt(input: StabilizeInput): StabilizeResult {\n\tconst original = input.prompt;\n\tif (!original.trim()) return { prompt: original, lifted: 0, rolledBack: false };\n\n\tconst candidates = buildStableCandidates(input);\n\tif (candidates.length === 0) return { prompt: original, lifted: 0, rolledBack: false };\n\n\t// Contar SIEMPRE contra la instantánea original: los candidatos anidan.\n\tconst snapshot = original;\n\tconst occurrencesOf = (needle: string): number => {\n\t\tlet count = 0;\n\t\tlet from = 0;\n\t\twhile (true) {\n\t\t\tconst at = snapshot.indexOf(needle, from);\n\t\t\tif (at === -1) break;\n\t\t\tcount++;\n\t\t\tfrom = at + needle.length;\n\t\t\tif (count > 1) break; // con saber que hay más de una basta\n\t\t}\n\t\treturn count;\n\t};\n\n\tconst stable: string[] = [];\n\tlet rest = original;\n\tconst seen = new Set<string>();\n\tfor (const candidate of candidates) {\n\t\tif (seen.has(candidate)) continue;\n\t\tif (occurrencesOf(candidate) !== 1) continue;\n\t\tconst at = rest.indexOf(candidate);\n\t\tif (at === -1) continue; // ya extraído dentro de otro candidato\n\t\tseen.add(candidate);\n\t\tstable.push(candidate);\n\t\trest = rest.slice(0, at) + rest.slice(at + candidate.length);\n\t}\n\n\tif (stable.length === 0) return { prompt: original, lifted: 0, rolledBack: false };\n\n\tconst stableJoined = stable.join(\"\\n\\n\");\n\t// Ya estabilizado: sin esto una segunda pasada apilaría otro separador y el\n\t// prefijo se movería en cada turno — exactamente lo contrario de lo que\n\t// buscamos. La idempotencia no es elegancia aquí, es la propiedad.\n\tif (original.startsWith(stableJoined + STABLE_SEPARATOR)) {\n\t\treturn { prompt: original, lifted: 0, rolledBack: false };\n\t}\n\n\tconst rewritten = `${stableJoined}${STABLE_SEPARATOR}${rest.trim()}`;\n\n\t// Guardia de integridad: ningún marcador estructural puede desaparecer.\n\tconst before = extractStructuralMarkers(original);\n\tconst after = extractStructuralMarkers(rewritten);\n\tif (before.length !== after.length || before.some((m, i) => m !== after[i])) {\n\t\treturn { prompt: original, lifted: 0, rolledBack: true };\n\t}\n\n\treturn { prompt: rewritten, lifted: stable.length, rolledBack: false };\n}\n"]}

package/dist/core/prompt-cache/stats.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Lectura y persistencia de estadísticas de caché.
+ *
+ * Sin medición, todo lo demás es fe. Cada familia de proveedor reporta el uso de
+ * caché con nombres distintos, y algunos proxies los omiten — en cuyo caso hay
+ * que decirlo en vez de mostrar un 0% que parece un problema de caché cuando en
+ * realidad es un problema de telemetría.
+ */
+export interface CacheUsage {
+    /** Tokens de entrada servidos desde caché. */
+    cacheRead: number;
+    /** Tokens escritos a la caché (Anthropic los cobra aparte). */
+    cacheWrite: number;
+    /** Total de tokens de entrada, incluyendo los cacheados. */
+    totalInput: number;
+    /** True si el proveedor no reportó campos de caché (≠ 0 aciertos). */
+    missingFields: boolean;
+}
+/**
+ * Normaliza el usage de cualquier familia de proveedor.
+ *
+ * Los nombres NO son intercambiables:
+ * - DeepSeek: `prompt_cache_hit_tokens` + `prompt_cache_miss_tokens` suman el total.
+ * - OpenAI: `prompt_tokens_details.cached_tokens` es un SUBCONJUNTO de `prompt_tokens`.
+ * - Anthropic: `input_tokens` EXCLUYE lo cacheado, así que hay que sumarlo.
+ * - Gemini: `cachedContentTokenCount` sobre `promptTokenCount`.
+ */
+export declare function readCacheUsage(raw: unknown): CacheUsage;
+export interface ModelCacheStats {
+    day: string;
+    requests: number;
+    hits: number;
+    cachedTokens: number;
+    totalTokens: number;
+    missingFieldRequests: number;
+}
+export declare function emptyStats(day: string): ModelCacheStats;
+export declare function accumulate(stats: ModelCacheStats, usage: CacheUsage): ModelCacheStats;
+/** Línea del footer: `DS cache 42/57·1.20M/1.85M 64.9%`. */
+export declare function formatStats(label: string, stats: ModelCacheStats): string;
+/** Persistencia con escritura debounced; el disco nunca bloquea una petición. */
+export declare class CacheStatsStore {
+    private path;
+    private data;
+    private timer;
+    constructor(agentDir: string);
+    load(): Promise<void>;
+    record(modelKey: string, day: string, usage: CacheUsage): ModelCacheStats;
+    get(modelKey: string): ModelCacheStats | undefined;
+    all(): Record<string, ModelCacheStats>;
+    reset(modelKey?: string): void;
+    private schedulePersist;
+    flush(): Promise<void>;
+}
+//# sourceMappingURL=stats.d.ts.map

package/dist/core/prompt-cache/stats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stats.d.ts","sourceRoot":"","sources":["../../../src/core/prompt-cache/stats.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,MAAM,WAAW,UAAU;IAC1B,+CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,gEAA+D;IAC/D,UAAU,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,UAAU,EAAE,MAAM,CAAC;IACnB,0EAAsE;IACtE,aAAa,EAAE,OAAO,CAAC;CACvB;AAQD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,UAAU,CAyDvD;AAED,MAAM,WAAW,eAAe;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,oBAAoB,EAAE,MAAM,CAAC;CAC7B;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,CAEvD;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,UAAU,GAAG,eAAe,CASrF;AAED,8DAA4D;AAC5D,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,MAAM,CAMzE;AAOD,kFAAiF;AACjF,qBAAa,eAAe;IAC3B,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,IAAI,CAA0C;IACtD,OAAO,CAAC,KAAK,CAA8C;IAE3D,YAAY,QAAQ,EAAE,MAAM,EAE3B;IAEK,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAO1B;IAED,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,eAAe,CAOxE;IAED,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAEjD;IAED,GAAG,IAAI,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAErC;IAED,KAAK,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAI7B;IAED,OAAO,CAAC,eAAe;IAMjB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAW3B;CACD","sourcesContent":["/**\n * Lectura y persistencia de estadísticas de caché.\n *\n * Sin medición, todo lo demás es fe. Cada familia de proveedor reporta el uso de\n * caché con nombres distintos, y algunos proxies los omiten — en cuyo caso hay\n * que decirlo en vez de mostrar un 0% que parece un problema de caché cuando en\n * realidad es un problema de telemetría.\n */\n\nimport { mkdir, readFile, writeFile } from \"node:fs/promises\";\nimport { dirname, join } from \"node:path\";\n\nexport interface CacheUsage {\n\t/** Tokens de entrada servidos desde caché. */\n\tcacheRead: number;\n\t/** Tokens escritos a la caché (Anthropic los cobra aparte). */\n\tcacheWrite: number;\n\t/** Total de tokens de entrada, incluyendo los cacheados. */\n\ttotalInput: number;\n\t/** True si el proveedor no reportó campos de caché (≠ 0 aciertos). */\n\tmissingFields: boolean;\n}\n\nconst ZERO: CacheUsage = { cacheRead: 0, cacheWrite: 0, totalInput: 0, missingFields: true };\n\nfunction num(value: unknown): number {\n\treturn typeof value === \"number\" && Number.isFinite(value) ? value : 0;\n}\n\n/**\n * Normaliza el usage de cualquier familia de proveedor.\n *\n * Los nombres NO son intercambiables:\n * - DeepSeek: `prompt_cache_hit_tokens` + `prompt_cache_miss_tokens` suman el total.\n * - OpenAI: `prompt_tokens_details.cached_tokens` es un SUBCONJUNTO de `prompt_tokens`.\n * - Anthropic: `input_tokens` EXCLUYE lo cacheado, así que hay que sumarlo.\n * - Gemini: `cachedContentTokenCount` sobre `promptTokenCount`.\n */\nexport function readCacheUsage(raw: unknown): CacheUsage {\n\tif (!raw || typeof raw !== \"object\") return { ...ZERO };\n\tconst u = raw as Record<string, unknown>;\n\n\t// DeepSeek\n\tif (\"prompt_cache_hit_tokens\" in u || \"prompt_cache_miss_tokens\" in u) {\n\t\tconst hit = num(u.prompt_cache_hit_tokens);\n\t\tconst miss = num(u.prompt_cache_miss_tokens);\n\t\treturn { cacheRead: hit, cacheWrite: 0, totalInput: hit + miss || num(u.prompt_tokens), missingFields: false };\n\t}\n\n\t// Anthropic: input_tokens NO incluye lo cacheado.\n\tif (\"cache_read_input_tokens\" in u || \"cache_creation_input_tokens\" in u) {\n\t\tconst read = num(u.cache_read_input_tokens);\n\t\tconst write = num(u.cache_creation_input_tokens);\n\t\treturn {\n\t\t\tcacheRead: read,\n\t\t\tcacheWrite: write,\n\t\t\ttotalInput: num(u.input_tokens) + read + write,\n\t\t\tmissingFields: false,\n\t\t};\n\t}\n\n\t// OpenAI: cached_tokens es subconjunto de prompt_tokens.\n\tconst details = (u.prompt_tokens_details ?? u.input_tokens_details) as Record<string, unknown> | undefined;\n\tif (details && typeof details === \"object\" && \"cached_tokens\" in details) {\n\t\tconst read = num(details.cached_tokens);\n\t\treturn {\n\t\t\tcacheRead: read,\n\t\t\tcacheWrite: num(u.cache_write_tokens),\n\t\t\ttotalInput: num(u.prompt_tokens) || num(u.input_tokens) || read,\n\t\t\tmissingFields: false,\n\t\t};\n\t}\n\n\t// Gemini\n\tconst meta = u.usageMetadata as Record<string, unknown> | undefined;\n\tif (meta && typeof meta === \"object\" && \"cachedContentTokenCount\" in meta) {\n\t\tconst read = num(meta.cachedContentTokenCount);\n\t\treturn { cacheRead: read, cacheWrite: 0, totalInput: num(meta.promptTokenCount) || read, missingFields: false };\n\t}\n\n\t// Forma ya normalizada por el SDK.\n\tif (\"cacheRead\" in u || \"input\" in u) {\n\t\tconst read = num(u.cacheRead);\n\t\tconst write = num(u.cacheWrite);\n\t\treturn {\n\t\t\tcacheRead: read,\n\t\t\tcacheWrite: write,\n\t\t\t// Suelo: el total nunca puede ser menor que lo cacheado, o saldrían\n\t\t\t// ratios por encima del 100% cuando un proxy omite el total.\n\t\t\ttotalInput: Math.max(num(u.input), read + write),\n\t\t\tmissingFields: !(\"cacheRead\" in u),\n\t\t};\n\t}\n\n\treturn { ...ZERO };\n}\n\nexport interface ModelCacheStats {\n\tday: string;\n\trequests: number;\n\thits: number;\n\tcachedTokens: number;\n\ttotalTokens: number;\n\tmissingFieldRequests: number;\n}\n\nexport function emptyStats(day: string): ModelCacheStats {\n\treturn { day, requests: 0, hits: 0, cachedTokens: 0, totalTokens: 0, missingFieldRequests: 0 };\n}\n\nexport function accumulate(stats: ModelCacheStats, usage: CacheUsage): ModelCacheStats {\n\treturn {\n\t\t...stats,\n\t\trequests: stats.requests + 1,\n\t\thits: stats.hits + (usage.cacheRead > 0 ? 1 : 0),\n\t\tcachedTokens: stats.cachedTokens + usage.cacheRead,\n\t\ttotalTokens: stats.totalTokens + usage.totalInput,\n\t\tmissingFieldRequests: stats.missingFieldRequests + (usage.missingFields ? 1 : 0),\n\t};\n}\n\n/** Línea del footer: `DS cache 42/57·1.20M/1.85M 64.9%`. */\nexport function formatStats(label: string, stats: ModelCacheStats): string {\n\tif (stats.requests === 0) return \"\";\n\tconst pct = stats.totalTokens > 0 ? ((stats.cachedTokens / stats.totalTokens) * 100).toFixed(1) : \"0.0\";\n\tconst m = (n: number) => `${(n / 1_000_000).toFixed(2)}M`;\n\tconst warn = stats.missingFieldRequests > 0 ? \" ⚠️ sin datos de caché\" : \"\";\n\treturn `${label} ${stats.hits}/${stats.requests}·${m(stats.cachedTokens)}/${m(stats.totalTokens)} ${pct}%${warn}`;\n}\n\ninterface StatsFile {\n\tversion: 1;\n\tbyModel: Record<string, ModelCacheStats>;\n}\n\n/** Persistencia con escritura debounced; el disco nunca bloquea una petición. */\nexport class CacheStatsStore {\n\tprivate path: string;\n\tprivate data: StatsFile = { version: 1, byModel: {} };\n\tprivate timer: ReturnType<typeof setTimeout> | null = null;\n\n\tconstructor(agentDir: string) {\n\t\tthis.path = join(agentDir, \"prompt-cache-stats.json\");\n\t}\n\n\tasync load(): Promise<void> {\n\t\ttry {\n\t\t\tconst parsed = JSON.parse(await readFile(this.path, \"utf-8\")) as StatsFile;\n\t\t\tif (parsed.version === 1 && parsed.byModel) this.data = parsed;\n\t\t} catch {\n\t\t\t// primer arranque / fichero corrupto: se empieza de cero\n\t\t}\n\t}\n\n\trecord(modelKey: string, day: string, usage: CacheUsage): ModelCacheStats {\n\t\tconst current = this.data.byModel[modelKey];\n\t\tconst base = current && current.day === day ? current : emptyStats(day);\n\t\tconst next = accumulate(base, usage);\n\t\tthis.data.byModel[modelKey] = next;\n\t\tthis.schedulePersist();\n\t\treturn next;\n\t}\n\n\tget(modelKey: string): ModelCacheStats | undefined {\n\t\treturn this.data.byModel[modelKey];\n\t}\n\n\tall(): Record<string, ModelCacheStats> {\n\t\treturn { ...this.data.byModel };\n\t}\n\n\treset(modelKey?: string): void {\n\t\tif (modelKey) delete this.data.byModel[modelKey];\n\t\telse this.data.byModel = {};\n\t\tthis.schedulePersist();\n\t}\n\n\tprivate schedulePersist(): void {\n\t\tif (this.timer) clearTimeout(this.timer);\n\t\tthis.timer = setTimeout(() => void this.flush(), 2000);\n\t\t(this.timer as unknown as { unref?: () => void }).unref?.();\n\t}\n\n\tasync flush(): Promise<void> {\n\t\tif (this.timer) {\n\t\t\tclearTimeout(this.timer);\n\t\t\tthis.timer = null;\n\t\t}\n\t\ttry {\n\t\t\tawait mkdir(dirname(this.path), { recursive: true });\n\t\t\tawait writeFile(this.path, JSON.stringify(this.data), \"utf-8\");\n\t\t} catch {\n\t\t\t// las estadísticas nunca deben romper una sesión\n\t\t}\n\t}\n}\n"]}

package/dist/core/prompt-cache/stats.js

@@ -0,0 +1,158 @@
+/**
+ * Lectura y persistencia de estadísticas de caché.
+ *
+ * Sin medición, todo lo demás es fe. Cada familia de proveedor reporta el uso de
+ * caché con nombres distintos, y algunos proxies los omiten — en cuyo caso hay
+ * que decirlo en vez de mostrar un 0% que parece un problema de caché cuando en
+ * realidad es un problema de telemetría.
+ */
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+const ZERO = { cacheRead: 0, cacheWrite: 0, totalInput: 0, missingFields: true };
+function num(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+/**
+ * Normaliza el usage de cualquier familia de proveedor.
+ *
+ * Los nombres NO son intercambiables:
+ * - DeepSeek: `prompt_cache_hit_tokens` + `prompt_cache_miss_tokens` suman el total.
+ * - OpenAI: `prompt_tokens_details.cached_tokens` es un SUBCONJUNTO de `prompt_tokens`.
+ * - Anthropic: `input_tokens` EXCLUYE lo cacheado, así que hay que sumarlo.
+ * - Gemini: `cachedContentTokenCount` sobre `promptTokenCount`.
+ */
+export function readCacheUsage(raw) {
+    if (!raw || typeof raw !== "object")
+        return { ...ZERO };
+    const u = raw;
+    // DeepSeek
+    if ("prompt_cache_hit_tokens" in u || "prompt_cache_miss_tokens" in u) {
+        const hit = num(u.prompt_cache_hit_tokens);
+        const miss = num(u.prompt_cache_miss_tokens);
+        return { cacheRead: hit, cacheWrite: 0, totalInput: hit + miss || num(u.prompt_tokens), missingFields: false };
+    }
+    // Anthropic: input_tokens NO incluye lo cacheado.
+    if ("cache_read_input_tokens" in u || "cache_creation_input_tokens" in u) {
+        const read = num(u.cache_read_input_tokens);
+        const write = num(u.cache_creation_input_tokens);
+        return {
+            cacheRead: read,
+            cacheWrite: write,
+            totalInput: num(u.input_tokens) + read + write,
+            missingFields: false,
+        };
+    }
+    // OpenAI: cached_tokens es subconjunto de prompt_tokens.
+    const details = (u.prompt_tokens_details ?? u.input_tokens_details);
+    if (details && typeof details === "object" && "cached_tokens" in details) {
+        const read = num(details.cached_tokens);
+        return {
+            cacheRead: read,
+            cacheWrite: num(u.cache_write_tokens),
+            totalInput: num(u.prompt_tokens) || num(u.input_tokens) || read,
+            missingFields: false,
+        };
+    }
+    // Gemini
+    const meta = u.usageMetadata;
+    if (meta && typeof meta === "object" && "cachedContentTokenCount" in meta) {
+        const read = num(meta.cachedContentTokenCount);
+        return { cacheRead: read, cacheWrite: 0, totalInput: num(meta.promptTokenCount) || read, missingFields: false };
+    }
+    // Forma ya normalizada por el SDK.
+    if ("cacheRead" in u || "input" in u) {
+        const read = num(u.cacheRead);
+        const write = num(u.cacheWrite);
+        return {
+            cacheRead: read,
+            cacheWrite: write,
+            // Suelo: el total nunca puede ser menor que lo cacheado, o saldrían
+            // ratios por encima del 100% cuando un proxy omite el total.
+            totalInput: Math.max(num(u.input), read + write),
+            missingFields: !("cacheRead" in u),
+        };
+    }
+    return { ...ZERO };
+}
+export function emptyStats(day) {
+    return { day, requests: 0, hits: 0, cachedTokens: 0, totalTokens: 0, missingFieldRequests: 0 };
+}
+export function accumulate(stats, usage) {
+    return {
+        ...stats,
+        requests: stats.requests + 1,
+        hits: stats.hits + (usage.cacheRead > 0 ? 1 : 0),
+        cachedTokens: stats.cachedTokens + usage.cacheRead,
+        totalTokens: stats.totalTokens + usage.totalInput,
+        missingFieldRequests: stats.missingFieldRequests + (usage.missingFields ? 1 : 0),
+    };
+}
+/** Línea del footer: `DS cache 42/57·1.20M/1.85M 64.9%`. */
+export function formatStats(label, stats) {
+    if (stats.requests === 0)
+        return "";
+    const pct = stats.totalTokens > 0 ? ((stats.cachedTokens / stats.totalTokens) * 100).toFixed(1) : "0.0";
+    const m = (n) => `${(n / 1_000_000).toFixed(2)}M`;
+    const warn = stats.missingFieldRequests > 0 ? " ⚠️ sin datos de caché" : "";
+    return `${label} ${stats.hits}/${stats.requests}·${m(stats.cachedTokens)}/${m(stats.totalTokens)} ${pct}%${warn}`;
+}
+/** Persistencia con escritura debounced; el disco nunca bloquea una petición. */
+export class CacheStatsStore {
+    path;
+    data = { version: 1, byModel: {} };
+    timer = null;
+    constructor(agentDir) {
+        this.path = join(agentDir, "prompt-cache-stats.json");
+    }
+    async load() {
+        try {
+            const parsed = JSON.parse(await readFile(this.path, "utf-8"));
+            if (parsed.version === 1 && parsed.byModel)
+                this.data = parsed;
+        }
+        catch {
+            // primer arranque / fichero corrupto: se empieza de cero
+        }
+    }
+    record(modelKey, day, usage) {
+        const current = this.data.byModel[modelKey];
+        const base = current && current.day === day ? current : emptyStats(day);
+        const next = accumulate(base, usage);
+        this.data.byModel[modelKey] = next;
+        this.schedulePersist();
+        return next;
+    }
+    get(modelKey) {
+        return this.data.byModel[modelKey];
+    }
+    all() {
+        return { ...this.data.byModel };
+    }
+    reset(modelKey) {
+        if (modelKey)
+            delete this.data.byModel[modelKey];
+        else
+            this.data.byModel = {};
+        this.schedulePersist();
+    }
+    schedulePersist() {
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = setTimeout(() => void this.flush(), 2000);
+        this.timer.unref?.();
+    }
+    async flush() {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        try {
+            await mkdir(dirname(this.path), { recursive: true });
+            await writeFile(this.path, JSON.stringify(this.data), "utf-8");
+        }
+        catch {
+            // las estadísticas nunca deben romper una sesión
+        }
+    }
+}
+//# sourceMappingURL=stats.js.map

package/dist/core/prompt-cache/stats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stats.js","sourceRoot":"","sources":["../../../src/core/prompt-cache/stats.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Lectura y persistencia de estadísticas de caché.\n *\n * Sin medición, todo lo demás es fe. Cada familia de proveedor reporta el uso de\n * caché con nombres distintos, y algunos proxies los omiten — en cuyo caso hay\n * que decirlo en vez de mostrar un 0% que parece un problema de caché cuando en\n * realidad es un problema de telemetría.\n */\n\nimport { mkdir, readFile, writeFile } from \"node:fs/promises\";\nimport { dirname, join } from \"node:path\";\n\nexport interface CacheUsage {\n\t/** Tokens de entrada servidos desde caché. */\n\tcacheRead: number;\n\t/** Tokens escritos a la caché (Anthropic los cobra aparte). */\n\tcacheWrite: number;\n\t/** Total de tokens de entrada, incluyendo los cacheados. */\n\ttotalInput: number;\n\t/** True si el proveedor no reportó campos de caché (≠ 0 aciertos). */\n\tmissingFields: boolean;\n}\n\nconst ZERO: CacheUsage = { cacheRead: 0, cacheWrite: 0, totalInput: 0, missingFields: true };\n\nfunction num(value: unknown): number {\n\treturn typeof value === \"number\" && Number.isFinite(value) ? value : 0;\n}\n\n/**\n * Normaliza el usage de cualquier familia de proveedor.\n *\n * Los nombres NO son intercambiables:\n * - DeepSeek: `prompt_cache_hit_tokens` + `prompt_cache_miss_tokens` suman el total.\n * - OpenAI: `prompt_tokens_details.cached_tokens` es un SUBCONJUNTO de `prompt_tokens`.\n * - Anthropic: `input_tokens` EXCLUYE lo cacheado, así que hay que sumarlo.\n * - Gemini: `cachedContentTokenCount` sobre `promptTokenCount`.\n */\nexport function readCacheUsage(raw: unknown): CacheUsage {\n\tif (!raw || typeof raw !== \"object\") return { ...ZERO };\n\tconst u = raw as Record<string, unknown>;\n\n\t// DeepSeek\n\tif (\"prompt_cache_hit_tokens\" in u || \"prompt_cache_miss_tokens\" in u) {\n\t\tconst hit = num(u.prompt_cache_hit_tokens);\n\t\tconst miss = num(u.prompt_cache_miss_tokens);\n\t\treturn { cacheRead: hit, cacheWrite: 0, totalInput: hit + miss || num(u.prompt_tokens), missingFields: false };\n\t}\n\n\t// Anthropic: input_tokens NO incluye lo cacheado.\n\tif (\"cache_read_input_tokens\" in u || \"cache_creation_input_tokens\" in u) {\n\t\tconst read = num(u.cache_read_input_tokens);\n\t\tconst write = num(u.cache_creation_input_tokens);\n\t\treturn {\n\t\t\tcacheRead: read,\n\t\t\tcacheWrite: write,\n\t\t\ttotalInput: num(u.input_tokens) + read + write,\n\t\t\tmissingFields: false,\n\t\t};\n\t}\n\n\t// OpenAI: cached_tokens es subconjunto de prompt_tokens.\n\tconst details = (u.prompt_tokens_details ?? u.input_tokens_details) as Record<string, unknown> | undefined;\n\tif (details && typeof details === \"object\" && \"cached_tokens\" in details) {\n\t\tconst read = num(details.cached_tokens);\n\t\treturn {\n\t\t\tcacheRead: read,\n\t\t\tcacheWrite: num(u.cache_write_tokens),\n\t\t\ttotalInput: num(u.prompt_tokens) || num(u.input_tokens) || read,\n\t\t\tmissingFields: false,\n\t\t};\n\t}\n\n\t// Gemini\n\tconst meta = u.usageMetadata as Record<string, unknown> | undefined;\n\tif (meta && typeof meta === \"object\" && \"cachedContentTokenCount\" in meta) {\n\t\tconst read = num(meta.cachedContentTokenCount);\n\t\treturn { cacheRead: read, cacheWrite: 0, totalInput: num(meta.promptTokenCount) || read, missingFields: false };\n\t}\n\n\t// Forma ya normalizada por el SDK.\n\tif (\"cacheRead\" in u || \"input\" in u) {\n\t\tconst read = num(u.cacheRead);\n\t\tconst write = num(u.cacheWrite);\n\t\treturn {\n\t\t\tcacheRead: read,\n\t\t\tcacheWrite: write,\n\t\t\t// Suelo: el total nunca puede ser menor que lo cacheado, o saldrían\n\t\t\t// ratios por encima del 100% cuando un proxy omite el total.\n\t\t\ttotalInput: Math.max(num(u.input), read + write),\n\t\t\tmissingFields: !(\"cacheRead\" in u),\n\t\t};\n\t}\n\n\treturn { ...ZERO };\n}\n\nexport interface ModelCacheStats {\n\tday: string;\n\trequests: number;\n\thits: number;\n\tcachedTokens: number;\n\ttotalTokens: number;\n\tmissingFieldRequests: number;\n}\n\nexport function emptyStats(day: string): ModelCacheStats {\n\treturn { day, requests: 0, hits: 0, cachedTokens: 0, totalTokens: 0, missingFieldRequests: 0 };\n}\n\nexport function accumulate(stats: ModelCacheStats, usage: CacheUsage): ModelCacheStats {\n\treturn {\n\t\t...stats,\n\t\trequests: stats.requests + 1,\n\t\thits: stats.hits + (usage.cacheRead > 0 ? 1 : 0),\n\t\tcachedTokens: stats.cachedTokens + usage.cacheRead,\n\t\ttotalTokens: stats.totalTokens + usage.totalInput,\n\t\tmissingFieldRequests: stats.missingFieldRequests + (usage.missingFields ? 1 : 0),\n\t};\n}\n\n/** Línea del footer: `DS cache 42/57·1.20M/1.85M 64.9%`. */\nexport function formatStats(label: string, stats: ModelCacheStats): string {\n\tif (stats.requests === 0) return \"\";\n\tconst pct = stats.totalTokens > 0 ? ((stats.cachedTokens / stats.totalTokens) * 100).toFixed(1) : \"0.0\";\n\tconst m = (n: number) => `${(n / 1_000_000).toFixed(2)}M`;\n\tconst warn = stats.missingFieldRequests > 0 ? \" ⚠️ sin datos de caché\" : \"\";\n\treturn `${label} ${stats.hits}/${stats.requests}·${m(stats.cachedTokens)}/${m(stats.totalTokens)} ${pct}%${warn}`;\n}\n\ninterface StatsFile {\n\tversion: 1;\n\tbyModel: Record<string, ModelCacheStats>;\n}\n\n/** Persistencia con escritura debounced; el disco nunca bloquea una petición. */\nexport class CacheStatsStore {\n\tprivate path: string;\n\tprivate data: StatsFile = { version: 1, byModel: {} };\n\tprivate timer: ReturnType<typeof setTimeout> | null = null;\n\n\tconstructor(agentDir: string) {\n\t\tthis.path = join(agentDir, \"prompt-cache-stats.json\");\n\t}\n\n\tasync load(): Promise<void> {\n\t\ttry {\n\t\t\tconst parsed = JSON.parse(await readFile(this.path, \"utf-8\")) as StatsFile;\n\t\t\tif (parsed.version === 1 && parsed.byModel) this.data = parsed;\n\t\t} catch {\n\t\t\t// primer arranque / fichero corrupto: se empieza de cero\n\t\t}\n\t}\n\n\trecord(modelKey: string, day: string, usage: CacheUsage): ModelCacheStats {\n\t\tconst current = this.data.byModel[modelKey];\n\t\tconst base = current && current.day === day ? current : emptyStats(day);\n\t\tconst next = accumulate(base, usage);\n\t\tthis.data.byModel[modelKey] = next;\n\t\tthis.schedulePersist();\n\t\treturn next;\n\t}\n\n\tget(modelKey: string): ModelCacheStats | undefined {\n\t\treturn this.data.byModel[modelKey];\n\t}\n\n\tall(): Record<string, ModelCacheStats> {\n\t\treturn { ...this.data.byModel };\n\t}\n\n\treset(modelKey?: string): void {\n\t\tif (modelKey) delete this.data.byModel[modelKey];\n\t\telse this.data.byModel = {};\n\t\tthis.schedulePersist();\n\t}\n\n\tprivate schedulePersist(): void {\n\t\tif (this.timer) clearTimeout(this.timer);\n\t\tthis.timer = setTimeout(() => void this.flush(), 2000);\n\t\t(this.timer as unknown as { unref?: () => void }).unref?.();\n\t}\n\n\tasync flush(): Promise<void> {\n\t\tif (this.timer) {\n\t\t\tclearTimeout(this.timer);\n\t\t\tthis.timer = null;\n\t\t}\n\t\ttry {\n\t\t\tawait mkdir(dirname(this.path), { recursive: true });\n\t\t\tawait writeFile(this.path, JSON.stringify(this.data), \"utf-8\");\n\t\t} catch {\n\t\t\t// las estadísticas nunca deben romper una sesión\n\t\t}\n\t}\n}\n"]}

package/dist/core/prompt-eleccion.d.ts

@@ -0,0 +1,38 @@
+/**
+ * La regla de elección de herramienta, en un solo sitio y construida con lo que
+ * de verdad está disponible.
+ *
+ * Antes vivía duplicada literalmente en `browser/tools.ts` y `computer/tools.ts`,
+ * y cada copia enrutaba a las cuatro familias — incluida la que su propio
+ * fichero no podía garantizar. Con el control del ordenador apagado, el prompt
+ * seguía diciendo "una aplicación de escritorio → computer_*" y esas tools no
+ * existían para el modelo. El agente las pedía, recibía un error opaco, y desde
+ * fuera parecía que "no sabe elegir herramienta".
+ *
+ * Una regla que nombra destinos inexistentes es peor que no tener regla: manda
+ * en la dirección equivocada con la autoridad del prompt de sistema.
+ */
+export interface DestinosDisponibles {
+    /** Las tools `browser_*` están registradas. */
+    navegador: boolean;
+    /** Las tools `computer_*` están registradas. */
+    ordenador: boolean;
+}
+/**
+ * Devuelve la línea de enrutado, omitiendo lo que no existe.
+ *
+ * `web_fetch` y `bash` van siempre porque siempre están: son el suelo del
+ * agente. Los otros dos son opcionales y cada uno tiene su interruptor.
+ */
+export declare function reglaDeEleccion(disponibles: DestinosDisponibles): string;
+/**
+ * Qué decirle al agente sobre los navegadores cuando NO tiene tools de
+ * navegador.
+ *
+ * La política del control del ordenador impide teclear en un navegador, y su
+ * mensaje de error redirige a `browser_*`. Si esas tools están apagadas, esa
+ * redirección apunta al vacío y el agente se queda sin salida. Mejor decírselo
+ * antes: no es que deba usar otra cosa, es que no puede hacerlo.
+ */
+export declare function avisoSinNavegador(): string;
+//# sourceMappingURL=prompt-eleccion.d.ts.map

package/dist/core/prompt-eleccion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-eleccion.d.ts","sourceRoot":"","sources":["../../src/core/prompt-eleccion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,WAAW,mBAAmB;IACnC,gDAA+C;IAC/C,SAAS,EAAE,OAAO,CAAC;IACnB,iDAAgD;IAChD,SAAS,EAAE,OAAO,CAAC;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,mBAAmB,GAAG,MAAM,CAUxE;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAM1C","sourcesContent":["/**\n * La regla de elección de herramienta, en un solo sitio y construida con lo que\n * de verdad está disponible.\n *\n * Antes vivía duplicada literalmente en `browser/tools.ts` y `computer/tools.ts`,\n * y cada copia enrutaba a las cuatro familias — incluida la que su propio\n * fichero no podía garantizar. Con el control del ordenador apagado, el prompt\n * seguía diciendo \"una aplicación de escritorio → computer_*\" y esas tools no\n * existían para el modelo. El agente las pedía, recibía un error opaco, y desde\n * fuera parecía que \"no sabe elegir herramienta\".\n *\n * Una regla que nombra destinos inexistentes es peor que no tener regla: manda\n * en la dirección equivocada con la autoridad del prompt de sistema.\n */\n\nexport interface DestinosDisponibles {\n\t/** Las tools `browser_*` están registradas. */\n\tnavegador: boolean;\n\t/** Las tools `computer_*` están registradas. */\n\tordenador: boolean;\n}\n\n/**\n * Devuelve la línea de enrutado, omitiendo lo que no existe.\n *\n * `web_fetch` y `bash` van siempre porque siempre están: son el suelo del\n * agente. Los otros dos son opcionales y cada uno tiene su interruptor.\n */\nexport function reglaDeEleccion(disponibles: DestinosDisponibles): string {\n\tconst destinos = [\"leer una URL sin tocar nada → web_fetch\"];\n\tif (disponibles.navegador) {\n\t\tdestinos.push(\"interactuar con una web, incluida tu app en localhost → browser_*\");\n\t}\n\tdestinos.push(\"ejecutar comandos, git o mover ficheros → bash\");\n\tif (disponibles.ordenador) {\n\t\tdestinos.push(\"una aplicación de escritorio que no sea navegador ni terminal → computer_*\");\n\t}\n\treturn `Elegir herramienta: ${destinos.join(\"; \")}.`;\n}\n\n/**\n * Qué decirle al agente sobre los navegadores cuando NO tiene tools de\n * navegador.\n *\n * La política del control del ordenador impide teclear en un navegador, y su\n * mensaje de error redirige a `browser_*`. Si esas tools están apagadas, esa\n * redirección apunta al vacío y el agente se queda sin salida. Mejor decírselo\n * antes: no es que deba usar otra cosa, es que no puede hacerlo.\n */\nexport function avisoSinNavegador(): string {\n\treturn (\n\t\t\"No tienes tools de navegador en esta sesión: no puedes manejar páginas web. \" +\n\t\t\"Para leer una URL usa web_fetch. Si la tarea necesita interactuar con una web, \" +\n\t\t\"díselo al usuario en vez de intentarlo por otra vía.\"\n\t);\n}\n"]}

package/dist/core/prompt-eleccion.js

@@ -0,0 +1,46 @@
+/**
+ * La regla de elección de herramienta, en un solo sitio y construida con lo que
+ * de verdad está disponible.
+ *
+ * Antes vivía duplicada literalmente en `browser/tools.ts` y `computer/tools.ts`,
+ * y cada copia enrutaba a las cuatro familias — incluida la que su propio
+ * fichero no podía garantizar. Con el control del ordenador apagado, el prompt
+ * seguía diciendo "una aplicación de escritorio → computer_*" y esas tools no
+ * existían para el modelo. El agente las pedía, recibía un error opaco, y desde
+ * fuera parecía que "no sabe elegir herramienta".
+ *
+ * Una regla que nombra destinos inexistentes es peor que no tener regla: manda
+ * en la dirección equivocada con la autoridad del prompt de sistema.
+ */
+/**
+ * Devuelve la línea de enrutado, omitiendo lo que no existe.
+ *
+ * `web_fetch` y `bash` van siempre porque siempre están: son el suelo del
+ * agente. Los otros dos son opcionales y cada uno tiene su interruptor.
+ */
+export function reglaDeEleccion(disponibles) {
+    const destinos = ["leer una URL sin tocar nada → web_fetch"];
+    if (disponibles.navegador) {
+        destinos.push("interactuar con una web, incluida tu app en localhost → browser_*");
+    }
+    destinos.push("ejecutar comandos, git o mover ficheros → bash");
+    if (disponibles.ordenador) {
+        destinos.push("una aplicación de escritorio que no sea navegador ni terminal → computer_*");
+    }
+    return `Elegir herramienta: ${destinos.join("; ")}.`;
+}
+/**
+ * Qué decirle al agente sobre los navegadores cuando NO tiene tools de
+ * navegador.
+ *
+ * La política del control del ordenador impide teclear en un navegador, y su
+ * mensaje de error redirige a `browser_*`. Si esas tools están apagadas, esa
+ * redirección apunta al vacío y el agente se queda sin salida. Mejor decírselo
+ * antes: no es que deba usar otra cosa, es que no puede hacerlo.
+ */
+export function avisoSinNavegador() {
+    return ("No tienes tools de navegador en esta sesión: no puedes manejar páginas web. " +
+        "Para leer una URL usa web_fetch. Si la tarea necesita interactuar con una web, " +
+        "díselo al usuario en vez de intentarlo por otra vía.");
+}
+//# sourceMappingURL=prompt-eleccion.js.map

package/dist/core/prompt-eleccion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-eleccion.js","sourceRoot":"","sources":["../../src/core/prompt-eleccion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AASH;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,WAAgC,EAAU;IACzE,MAAM,QAAQ,GAAG,CAAC,2CAAyC,CAAC,CAAC;IAC7D,IAAI,WAAW,CAAC,SAAS,EAAE,CAAC;QAC3B,QAAQ,CAAC,IAAI,CAAC,qEAAmE,CAAC,CAAC;IACpF,CAAC;IACD,QAAQ,CAAC,IAAI,CAAC,kDAAgD,CAAC,CAAC;IAChE,IAAI,WAAW,CAAC,SAAS,EAAE,CAAC;QAC3B,QAAQ,CAAC,IAAI,CAAC,+EAA4E,CAAC,CAAC;IAC7F,CAAC;IACD,OAAO,uBAAuB,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;AAAA,CACrD;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,GAAW;IAC3C,OAAO,CACN,gFAA8E;QAC9E,iFAAiF;QACjF,wDAAsD,CACtD,CAAC;AAAA,CACF","sourcesContent":["/**\n * La regla de elección de herramienta, en un solo sitio y construida con lo que\n * de verdad está disponible.\n *\n * Antes vivía duplicada literalmente en `browser/tools.ts` y `computer/tools.ts`,\n * y cada copia enrutaba a las cuatro familias — incluida la que su propio\n * fichero no podía garantizar. Con el control del ordenador apagado, el prompt\n * seguía diciendo \"una aplicación de escritorio → computer_*\" y esas tools no\n * existían para el modelo. El agente las pedía, recibía un error opaco, y desde\n * fuera parecía que \"no sabe elegir herramienta\".\n *\n * Una regla que nombra destinos inexistentes es peor que no tener regla: manda\n * en la dirección equivocada con la autoridad del prompt de sistema.\n */\n\nexport interface DestinosDisponibles {\n\t/** Las tools `browser_*` están registradas. */\n\tnavegador: boolean;\n\t/** Las tools `computer_*` están registradas. */\n\tordenador: boolean;\n}\n\n/**\n * Devuelve la línea de enrutado, omitiendo lo que no existe.\n *\n * `web_fetch` y `bash` van siempre porque siempre están: son el suelo del\n * agente. Los otros dos son opcionales y cada uno tiene su interruptor.\n */\nexport function reglaDeEleccion(disponibles: DestinosDisponibles): string {\n\tconst destinos = [\"leer una URL sin tocar nada → web_fetch\"];\n\tif (disponibles.navegador) {\n\t\tdestinos.push(\"interactuar con una web, incluida tu app en localhost → browser_*\");\n\t}\n\tdestinos.push(\"ejecutar comandos, git o mover ficheros → bash\");\n\tif (disponibles.ordenador) {\n\t\tdestinos.push(\"una aplicación de escritorio que no sea navegador ni terminal → computer_*\");\n\t}\n\treturn `Elegir herramienta: ${destinos.join(\"; \")}.`;\n}\n\n/**\n * Qué decirle al agente sobre los navegadores cuando NO tiene tools de\n * navegador.\n *\n * La política del control del ordenador impide teclear en un navegador, y su\n * mensaje de error redirige a `browser_*`. Si esas tools están apagadas, esa\n * redirección apunta al vacío y el agente se queda sin salida. Mejor decírselo\n * antes: no es que deba usar otra cosa, es que no puede hacerlo.\n */\nexport function avisoSinNavegador(): string {\n\treturn (\n\t\t\"No tienes tools de navegador en esta sesión: no puedes manejar páginas web. \" +\n\t\t\"Para leer una URL usa web_fetch. Si la tarea necesita interactuar con una web, \" +\n\t\t\"díselo al usuario en vez de intentarlo por otra vía.\"\n\t);\n}\n"]}

package/dist/core/prompts/montar.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Monta el prompt del sistema desde `sistema.md`.
+ *
+ * DE DÓNDE VIENE ESTO. El prompt de Ada era una cadena dentro de
+ * `system-prompt.ts` con dos directrices —«Be concise» y «Show file paths
+ * clearly»— más un bloque sobre dónde vive la documentación de Ada. Es decir:
+ * le explicábamos al modelo dónde están NUESTROS documentos y no le
+ * explicábamos cómo programar bien.
+ *
+ * Y había un dato peor, medido: de las TRECE capacidades construidas en cuatro
+ * tandas de trabajo (`lsp`, `ast_edit`, `hashline`, `remoto`, `web_search`,
+ * `computer`, `browser`, `audit`, `banco`, `cleanse`, `discover`, `review`,
+ * `ast_search`), **ninguna aparecía en el prompt**. De nuestras tools, solo UNA
+ * definía `promptSnippet`. El modelo veía el nombre y nada más: ni cuándo usar
+ * `lsp_references` antes de renombrar, ni que `ast_edit` es para codemods.
+ *
+ * Es capacidad construida y desenchufada en su forma más difícil de ver: la
+ * herramienta está registrada, así que NADA FALLA. Solo hay un agente peor de
+ * lo que debería, sin error que investigar.
+ *
+ * DOS DECISIONES QUE NO SON DE ESTILO:
+ *
+ * 1. **Si falta el `.md`, se LANZA.** Un `catch` que devolviera cadena vacía
+ *    dejaría al agente sin prompt del sistema —sin doctrina, sin contrato de
+ *    entrega, sin las reglas de cumplimiento— y arrancaría igual. Sería el
+ *    fallo que se lee como éxito en el sitio más caro posible. Como `dist/` es
+ *    superficie ciega para vitest (las pruebas leen `src/`, el paquete
+ *    publicado lee `dist/`), esto además convierte un `copy-assets` olvidado en
+ *    un arranque roto y visible en vez de en un agente silenciosamente tonto.
+ *
+ * 2. **Los nombres de herramienta salen del registro, no de la plantilla.** Si
+ *    alguien renombra `ast_search`, la línea del prompt que lo menciona se
+ *    queda mintiendo, y un prompt que nombra una tool inexistente le enseña al
+ *    modelo a desconfiar de sus instrucciones. Aquí la lista se construye desde
+ *    los nombres reales que recibe `montarPromptDelSistema`.
+ */
+import { type Contexto } from "./plantilla.ts";
+/** Qué sabe el montador sobre la sesión. Todo opcional salvo las tools. */
+export interface EntradaDelPrompt {
+    /** Los nombres de tool REALES y activos de esta sesión. */
+    nombresDeHerramienta: readonly string[];
+    /** Frases de una línea por tool, si la tool las aporta. */
+    frasesDeHerramienta?: Readonly<Record<string, string>>;
+    personalidad?: string;
+    /**
+     * `true` cuando la política de aprobación está en modo plan.
+     *
+     * Existe porque el modo plan estaba impuesto SOLO en código: `decidir()`
+     * devuelve `denegada` con política `modo-plan` para toda escritura y toda
+     * ejecución, y el prompt no lo mencionaba. El modelo intentaba editar, se
+     * llevaba un rechazo que no esperaba, y gastaba turnos aprendiendo por
+     * golpes una regla que se le podía haber dicho: el guardián estaba
+     * construido y el modelo no lo conocía.
+     */
+    modoPlan?: boolean;
+    /**
+     * Tools que el usuario ha denegado (`permissions.denied`).
+     *
+     * No es lo mismo que «no activa»: una tool denegada SIGUE en el inventario y
+     * en el conjunto activo, y lo que la para es `decidir()`, que consulta el
+     * `deny` del usuario en el paso 3 —antes del modo— y contesta `denegada` con
+     * política `deny-de-usuario`. Filtrar solo por `nivelDe` dejaba a la sección
+     * de modo plan prometiendo, por ejemplo, `web_fetch` con `permissions.denied:
+     * ["web_fetch"]` en settings: el rechazo inesperado que esta sección existe
+     * para evitar, servido por la propia sección.
+     */
+    toolsDenegadas?: readonly string[];
+}
+/** El contexto que ve la plantilla. Público porque las pruebas lo comprueban. */
+export declare function contextoDelPrompt(entrada: EntradaDelPrompt): Contexto;
+/** Solo para pruebas: olvida la plantilla cacheada. */
+export declare function __olvidarPlantillaParaPruebas(): void;
+/** El prompt del sistema de Ada, con las secciones que la sesión merece. */
+export declare function montarPromptDelSistema(entrada: EntradaDelPrompt): string;
+//# sourceMappingURL=montar.d.ts.map

package/dist/core/prompts/montar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"montar.d.ts","sourceRoot":"","sources":["../../../src/core/prompts/montar.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAMH,OAAO,EAAE,KAAK,QAAQ,EAAc,MAAM,gBAAgB,CAAC;AAI3D,6EAA2E;AAC3E,MAAM,WAAW,gBAAgB;IAChC,4DAA2D;IAC3D,oBAAoB,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,4DAA2D;IAC3D,mBAAmB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACvD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;;;;;;OAUG;IACH,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAgDD,kFAAiF;AACjF,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,gBAAgB,GAAG,QAAQ,CAgCrE;AAsBD,uDAAuD;AACvD,wBAAgB,6BAA6B,IAAI,IAAI,CAEpD;AAED,6EAA4E;AAC5E,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,gBAAgB,GAAG,MAAM,CAIxE","sourcesContent":["/**\n * Monta el prompt del sistema desde `sistema.md`.\n *\n * DE DÓNDE VIENE ESTO. El prompt de Ada era una cadena dentro de\n * `system-prompt.ts` con dos directrices —«Be concise» y «Show file paths\n * clearly»— más un bloque sobre dónde vive la documentación de Ada. Es decir:\n * le explicábamos al modelo dónde están NUESTROS documentos y no le\n * explicábamos cómo programar bien.\n *\n * Y había un dato peor, medido: de las TRECE capacidades construidas en cuatro\n * tandas de trabajo (`lsp`, `ast_edit`, `hashline`, `remoto`, `web_search`,\n * `computer`, `browser`, `audit`, `banco`, `cleanse`, `discover`, `review`,\n * `ast_search`), **ninguna aparecía en el prompt**. De nuestras tools, solo UNA\n * definía `promptSnippet`. El modelo veía el nombre y nada más: ni cuándo usar\n * `lsp_references` antes de renombrar, ni que `ast_edit` es para codemods.\n *\n * Es capacidad construida y desenchufada en su forma más difícil de ver: la\n * herramienta está registrada, así que NADA FALLA. Solo hay un agente peor de\n * lo que debería, sin error que investigar.\n *\n * DOS DECISIONES QUE NO SON DE ESTILO:\n *\n * 1. **Si falta el `.md`, se LANZA.** Un `catch` que devolviera cadena vacía\n *    dejaría al agente sin prompt del sistema —sin doctrina, sin contrato de\n *    entrega, sin las reglas de cumplimiento— y arrancaría igual. Sería el\n *    fallo que se lee como éxito en el sitio más caro posible. Como `dist/` es\n *    superficie ciega para vitest (las pruebas leen `src/`, el paquete\n *    publicado lee `dist/`), esto además convierte un `copy-assets` olvidado en\n *    un arranque roto y visible en vez de en un agente silenciosamente tonto.\n *\n * 2. **Los nombres de herramienta salen del registro, no de la plantilla.** Si\n *    alguien renombra `ast_search`, la línea del prompt que lo menciona se\n *    queda mintiendo, y un prompt que nombra una tool inexistente le enseña al\n *    modelo a desconfiar de sus instrucciones. Aquí la lista se construye desde\n *    los nombres reales que recibe `montarPromptDelSistema`.\n */\n\nimport { readFileSync } from \"node:fs\";\nimport { dirname, join } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { nivelDe } from \"../aprobacion/politica.ts\";\nimport { type Contexto, renderizar } from \"./plantilla.ts\";\n\nconst NOMBRE = \"sistema.md\";\n\n/** Qué sabe el montador sobre la sesión. Todo opcional salvo las tools. */\nexport interface EntradaDelPrompt {\n\t/** Los nombres de tool REALES y activos de esta sesión. */\n\tnombresDeHerramienta: readonly string[];\n\t/** Frases de una línea por tool, si la tool las aporta. */\n\tfrasesDeHerramienta?: Readonly<Record<string, string>>;\n\tpersonalidad?: string;\n\t/**\n\t * `true` cuando la política de aprobación está en modo plan.\n\t *\n\t * Existe porque el modo plan estaba impuesto SOLO en código: `decidir()`\n\t * devuelve `denegada` con política `modo-plan` para toda escritura y toda\n\t * ejecución, y el prompt no lo mencionaba. El modelo intentaba editar, se\n\t * llevaba un rechazo que no esperaba, y gastaba turnos aprendiendo por\n\t * golpes una regla que se le podía haber dicho: el guardián estaba\n\t * construido y el modelo no lo conocía.\n\t */\n\tmodoPlan?: boolean;\n\t/**\n\t * Tools que el usuario ha denegado (`permissions.denied`).\n\t *\n\t * No es lo mismo que «no activa»: una tool denegada SIGUE en el inventario y\n\t * en el conjunto activo, y lo que la para es `decidir()`, que consulta el\n\t * `deny` del usuario en el paso 3 —antes del modo— y contesta `denegada` con\n\t * política `deny-de-usuario`. Filtrar solo por `nivelDe` dejaba a la sección\n\t * de modo plan prometiendo, por ejemplo, `web_fetch` con `permissions.denied:\n\t * [\"web_fetch\"]` en settings: el rechazo inesperado que esta sección existe\n\t * para evitar, servido por la propia sección.\n\t */\n\ttoolsDenegadas?: readonly string[];\n}\n\n/**\n * Una línea por herramienta especializada, construida desde los nombres reales.\n *\n * Solo se listan las que el modelo confunde con `bash` — es donde la guía paga.\n * Enumerar `read` junto a veinte más diluye las que importan.\n */\nconst GUIA: ReadonlyArray<{ tool: string; linea: (n: string) => string }> = [\n\t{ tool: \"read\", linea: (n) => `File and directory reads → \\`${n}\\`, never \\`cat\\` or \\`ls\\` through the shell.` },\n\t{ tool: \"grep\", linea: (n) => `Regex search → \\`${n}\\`, never shell \\`grep\\`, \\`rg\\` or \\`awk\\`.` },\n\t{ tool: \"find\", linea: (n) => `Locating files by name or glob → \\`${n}\\`, never \\`find\\` or \\`fd\\`.` },\n\t{ tool: \"edit\", linea: (n) => `Surgical edits → \\`${n}\\`. Never rewrite a whole file to change a few lines.` },\n\t{ tool: \"write\", linea: (n) => `Creating or fully replacing a file → \\`${n}\\`.` },\n\t{\n\t\ttool: \"web_search\",\n\t\tlinea: (n) => `Anything you do not know and cannot read locally → \\`${n}\\`. Do not guess an API from memory.`,\n\t},\n];\n\n/**\n * La línea del modo plan que dice qué tools SIGUEN valiendo.\n *\n * Los nombres salen del conjunto REAL de tools activas filtrado por `nivelDe`,\n * el mismo clasificador que usa la política de aprobación: si alguien mueve una\n * tool de `LECTURA` a `ESCRITURA`, esta línea se mueve con ella. Escribirlos a\n * mano en la plantilla sería prometerle al modelo tools que quizá no tiene, y\n * un prompt que nombra una tool inexistente le enseña a desconfiar de sus\n * instrucciones.\n *\n * El filtro son las DOS condiciones que `decidir()` aplica antes de dejar pasar\n * una lectura en modo plan: nivel de lectura (paso 4) y no estar en el `deny`\n * del usuario (paso 3). Con solo la primera, `permissions.denied: [\"web_fetch\"]`\n * dejaba la línea prometiendo `web_fetch`.\n *\n * El caso vacío (`ada-cli --tools bash` en modo plan) no es decorativo: ahí el\n * agente no puede ni leer, y decirlo es mejor que dejar una lista en blanco que\n * el modelo interpretará como que puede con todo. Se calcula aquí en vez de con\n * un `{{#si}}` dentro del `{{#si modoPlan}}` porque anidar dos bloques del\n * mismo tipo borraba el resto de la sección en silencio (ver `plantilla.ts`).\n */\nfunction lineaDePlan(lectura: readonly string[]): string {\n\tif (lectura.length === 0) {\n\t\treturn \"No read-only tool is active in this session, so you cannot investigate either. Say exactly that and stop.\";\n\t}\n\treturn `Still available in this mode: ${lectura.map((n) => `\\`${n}\\``).join(\", \")}. Nothing else is.`;\n}\n\n/** El contexto que ve la plantilla. Público porque las pruebas lo comprueban. */\nexport function contextoDelPrompt(entrada: EntradaDelPrompt): Contexto {\n\tconst activas = new Set(entrada.nombresDeHerramienta);\n\tconst denegadas = new Set(entrada.toolsDenegadas ?? []);\n\tconst tiene = (prefijo: string) => [...activas].some((n) => n === prefijo || n.startsWith(`${prefijo}_`));\n\n\tconst herramientas: string[] = [];\n\tfor (const { tool, linea } of GUIA) {\n\t\tif (activas.has(tool)) herramientas.push(linea(tool));\n\t}\n\t// Y las que aportan su propia frase, que nadie más conoce.\n\tfor (const [nombre, frase] of Object.entries(entrada.frasesDeHerramienta ?? {})) {\n\t\tif (activas.has(nombre) && !GUIA.some((g) => g.tool === nombre)) {\n\t\t\therramientas.push(`\\`${nombre}\\`: ${frase}`);\n\t\t}\n\t}\n\n\treturn {\n\t\therramientas,\n\t\tpersonalidad: entrada.personalidad,\n\t\tmodoPlan: entrada.modoPlan === true,\n\t\tlineaHerramientasDePlan: lineaDePlan(\n\t\t\t[...activas].filter((n) => nivelDe(n) === \"lectura\" && !denegadas.has(n)).sort(),\n\t\t),\n\t\ttieneLsp: tiene(\"lsp\"),\n\t\ttieneEstructural: activas.has(\"ast_search\") || activas.has(\"ast_edit\"),\n\t\ttieneBash: activas.has(\"bash\"),\n\t\ttieneNavegador: tiene(\"browser\"),\n\t\ttieneEscritorio: tiene(\"computer\"),\n\t\t// El libro de auditoría no es una tool: es una propiedad del arnés, y\n\t\t// siempre está. Se declara explícito para que la plantilla no adivine.\n\t\ttieneAudit: true,\n\t};\n}\n\nlet cacheDeLaPlantilla: string | undefined;\n\n/** Lee `sistema.md` de junto a este módulo. Lanza si no está. */\nfunction leerPlantilla(): string {\n\tif (cacheDeLaPlantilla !== undefined) return cacheDeLaPlantilla;\n\tconst ruta = join(dirname(fileURLToPath(import.meta.url)), NOMBRE);\n\ttry {\n\t\tcacheDeLaPlantilla = readFileSync(ruta, \"utf-8\");\n\t} catch (error) {\n\t\tthrow new Error(\n\t\t\t`No se ha podido leer el prompt del sistema (${ruta}).\\n` +\n\t\t\t\t\"Arrancar sin él dejaría al agente sin doctrina, sin contrato de entrega y sin\\n\" +\n\t\t\t\t\"las reglas de cumplimiento, y lo haría en silencio. Si esto sale desde el\\n\" +\n\t\t\t\t\"paquete compilado, falta el paso `copy-assets` que lleva los .md a dist/.\\n\" +\n\t\t\t\t`Causa: ${error instanceof Error ? error.message : String(error)}`,\n\t\t);\n\t}\n\treturn cacheDeLaPlantilla;\n}\n\n/** Solo para pruebas: olvida la plantilla cacheada. */\nexport function __olvidarPlantillaParaPruebas(): void {\n\tcacheDeLaPlantilla = undefined;\n}\n\n/** El prompt del sistema de Ada, con las secciones que la sesión merece. */\nexport function montarPromptDelSistema(entrada: EntradaDelPrompt): string {\n\treturn renderizar(leerPlantilla(), contextoDelPrompt(entrada), NOMBRE)\n\t\t.replace(/\\n{3,}/g, \"\\n\\n\")\n\t\t.trim();\n}\n"]}