@hoilab/ada-cli 0.84.21 → 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/prompt-optimizer.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Optimizador de prompt autónomo (Ada Intelligence Engine).
+ *
+ * Antes de procesar la petición del usuario, el sistema la analiza contra las
+ * mejores prácticas de ingeniería de prompts (basadas en las guías de Claude —
+ * claridad, contexto, ejemplos, estructura XML, rol, formato de salida, criterios
+ * de éxito, alcance) y decide:
+ *
+ *   1. CLARIFY  — hay gaps de información críticos → genera preguntas de
+ *                 clarificación (máx. 3) para dejar el prompt sin huecos.
+ *   2. ENHANCE  — la petición es suficiente → la reescribe como un prompt
+ *                 estructurado y sin ambigüedad.
+ *
+ * El resultado es un JSON estructurado (never free-text) para consumo fiable
+ * por la sesión, el CLI y el desktop.
+ */
+export type PromptOptimizerDecision = "clarify" | "enhance";
+export interface PromptOptimizerInput {
+    /** La petición original del usuario. */
+    text: string;
+    /** Contexto disponible: proyecto, objetivo activo, mensajes recientes. */
+    context?: {
+        projectDir?: string;
+        activeGoal?: string;
+        recentMessages?: string[];
+    };
+    /** Máximo de preguntas de clarificación (default 3). */
+    maxQuestions?: number;
+    /**
+     * Modo "auto": si el LLM pide clarificar, NO preguntar al usuario —
+     * hacer una segunda pasada que fuerza un prompt mejorado con supuestos
+     * razonables (mejora sin interrumpir).
+     */
+    forceEnhance?: boolean;
+}
+export interface PromptOptimizerResult {
+    decision: PromptOptimizerDecision;
+    /** Preguntas de clarificación (solo si decision === "clarify"). */
+    questions: string[];
+    /** Prompt mejorado y estructurado (solo si decision === "enhance"). */
+    enhanced: string;
+    /** Resumen breve de qué se mejoró (para mostrar al usuario). */
+    summary: string;
+}
+/** Callback que ejecuta una llamada LLM (inyectado por la sesión). */
+export type PromptOptimizerComplete = (systemPrompt: string, userContent: string) => Promise<string>;
+/**
+ * Optimiza (o solicita clarificación para) la petición del usuario.
+ * Usa el callback LLM inyectado. Nunca lanza: en fallo devuelve la petición
+ * original sin cambios con decision "enhance".
+ */
+export declare function optimizeUserPrompt(input: PromptOptimizerInput, complete: PromptOptimizerComplete): Promise<PromptOptimizerResult>;
+//# sourceMappingURL=prompt-optimizer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-optimizer.d.ts","sourceRoot":"","sources":["../../src/core/prompt-optimizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,MAAM,uBAAuB,GAAG,SAAS,GAAG,SAAS,CAAC;AAE5D,MAAM,WAAW,oBAAoB;IACpC,yCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,OAAO,CAAC,EAAE;QACT,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;KAC1B,CAAC;IACF,0DAAwD;IACxD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,qBAAqB;IACrC,QAAQ,EAAE,uBAAuB,CAAC;IAClC,oEAAmE;IACnE,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,uEAAuE;IACvE,QAAQ,EAAE,MAAM,CAAC;IACjB,kEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,uEAAsE;AACtE,MAAM,MAAM,uBAAuB,GAAG,CAAC,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAgCrG;;;;GAIG;AACH,wBAAsB,kBAAkB,CACvC,KAAK,EAAE,oBAAoB,EAC3B,QAAQ,EAAE,uBAAuB,GAC/B,OAAO,CAAC,qBAAqB,CAAC,CAmEhC","sourcesContent":["/**\n * Optimizador de prompt autónomo (Ada Intelligence Engine).\n *\n * Antes de procesar la petición del usuario, el sistema la analiza contra las\n * mejores prácticas de ingeniería de prompts (basadas en las guías de Claude —\n * claridad, contexto, ejemplos, estructura XML, rol, formato de salida, criterios\n * de éxito, alcance) y decide:\n *\n *   1. CLARIFY  — hay gaps de información críticos → genera preguntas de\n *                 clarificación (máx. 3) para dejar el prompt sin huecos.\n *   2. ENHANCE  — la petición es suficiente → la reescribe como un prompt\n *                 estructurado y sin ambigüedad.\n *\n * El resultado es un JSON estructurado (never free-text) para consumo fiable\n * por la sesión, el CLI y el desktop.\n */\n\nexport type PromptOptimizerDecision = \"clarify\" | \"enhance\";\n\nexport interface PromptOptimizerInput {\n\t/** La petición original del usuario. */\n\ttext: string;\n\t/** Contexto disponible: proyecto, objetivo activo, mensajes recientes. */\n\tcontext?: {\n\t\tprojectDir?: string;\n\t\tactiveGoal?: string;\n\t\trecentMessages?: string[];\n\t};\n\t/** Máximo de preguntas de clarificación (default 3). */\n\tmaxQuestions?: number;\n\t/**\n\t * Modo \"auto\": si el LLM pide clarificar, NO preguntar al usuario —\n\t * hacer una segunda pasada que fuerza un prompt mejorado con supuestos\n\t * razonables (mejora sin interrumpir).\n\t */\n\tforceEnhance?: boolean;\n}\n\nexport interface PromptOptimizerResult {\n\tdecision: PromptOptimizerDecision;\n\t/** Preguntas de clarificación (solo si decision === \"clarify\"). */\n\tquestions: string[];\n\t/** Prompt mejorado y estructurado (solo si decision === \"enhance\"). */\n\tenhanced: string;\n\t/** Resumen breve de qué se mejoró (para mostrar al usuario). */\n\tsummary: string;\n}\n\n/** Callback que ejecuta una llamada LLM (inyectado por la sesión). */\nexport type PromptOptimizerComplete = (systemPrompt: string, userContent: string) => Promise<string>;\n\n/** Guías de ingeniería de prompts que codifica el optimizador. */\nconst OPTIMIZER_SYSTEM_PROMPT = `Eres un experto en ingeniería de prompts. Tu trabajo es tomar la petición de un usuario y producir una versión perfecta, sin huecos, que maximice la calidad de la respuesta de cualquier modelo LLM.\n\nAplica estas mejores prácticas (basadas en las guías de referencia de Anthropic):\n\n1. CLARIDAD: sé específico sobre qué se quiere, el formato de salida deseado y las restricciones. Instrucciones como pasos numerados o bullets cuando el orden importa.\n2. CONTEXTO: añade el contexto o motivación detrás de la petición (\"por qué es importante\") para que el modelo entienda el objetivo.\n3. ROL: da al modelo un rol claro y enfocado (\"Actúa como un ingeniero de software senior especializado en X\").\n4. ESTRUCTURA XML: organiza el prompt con etiquetas descriptivas (<context>, <instructions>, <input>, <constraints>, <output_format>) para eliminar ambigüedad de parseo.\n5. EJEMPLOS: incluye 1-3 ejemplos concretos (few-shot) cuando el formato de salida no sea obvio.\n6. FORMATO DE SALIDA: especifica exactamente el formato esperado (JSON, markdown, resumen de N líneas, código con tests...).\n7. CRITERIOS DE ÉXITO: define qué constituye un resultado correcto y verificación (por ejemplo, \"ejecuta los tests antes de terminar\").\n8. ALCANCE: limita el trabajo (\"no añadas features fuera de lo pedido\", \"solo modifica estos archivos\").\n9. ACCIÓN vs SUGERENCIA: si el usuario pide un cambio, sé explícito sobre que debe IMPLEMENTARLO, no solo sugerirlo (\"Implementa X\" en vez de \"¿podrías sugerir cambios a X?\").\n10. SIN GAPS: identifica la información que falta y que cambiaría materialmente el resultado.\n\nRUTINA:\nPaso 1 — Analiza la petición del usuario contra las 10 prácticas.\nPaso 2 — Decide si hay gaps CRÍTICOS (falta de contexto, ambigüedad sobre alcance/formato/destino que cambiaría el resultado):\n  - Si SÍ: decision = \"clarify\". Genera como máximo ${\"{{MAX_QUESTIONS}}\"} preguntas, cada una específica y accionable, que el usuario pueda responder en una línea. No hagas preguntas triviales.\n  - Si NO (o los gaps son menores): decision = \"enhance\". Reescribe el prompt completo como un prompt estructurado y profesional, SIN preguntar nada.\nPaso 3 — summary: una frase corta (máx. 12 palabras, en el idioma del usuario) sobre lo que se mejoró (o que se necesitan aclaraciones).\n\nREGLAS DE SALIDA:\n- Responde SOLO JSON válido con esta forma exacta:\n  {\"decision\":\"clarify\"|\"enhance\",\"questions\":[...],\"enhanced\":\"...\",\"summary\":\"...\"}\n- questions vacío si decision es enhance. enhanced vacío si decision es clarify.\n- Si el prompt ya es excelente, enhance puede devolverlo casi igual (solo estructura) — no inflar.\n- Preserva el idioma del usuario en el prompt mejorado y en summary.`;\n\n/**\n * Optimiza (o solicita clarificación para) la petición del usuario.\n * Usa el callback LLM inyectado. Nunca lanza: en fallo devuelve la petición\n * original sin cambios con decision \"enhance\".\n */\nexport async function optimizeUserPrompt(\n\tinput: PromptOptimizerInput,\n\tcomplete: PromptOptimizerComplete,\n): Promise<PromptOptimizerResult> {\n\tconst maxQuestions = input.maxQuestions ?? 3;\n\n\tconst userContent = [\n\t\t\"<user_request>\",\n\t\tinput.text,\n\t\t\"</user_request>\",\n\t\tinput.context?.projectDir ? `<project_dir>${input.context.projectDir}</project_dir>` : \"\",\n\t\tinput.context?.activeGoal ? `<active_goal>${input.context.activeGoal}</active_goal>` : \"\",\n\t\tinput.context?.recentMessages?.length\n\t\t\t? `<conversation_context>\\n${input.context.recentMessages.slice(-4).join(\"\\n---\\n\")}\\n</conversation_context>`\n\t\t\t: \"\",\n\t]\n\t\t.filter(Boolean)\n\t\t.join(\"\\n\");\n\n\tconst systemPrompt = OPTIMIZER_SYSTEM_PROMPT.replace(\"{{MAX_QUESTIONS}}\", String(maxQuestions));\n\n\ttry {\n\t\tconst raw = await complete(systemPrompt, userContent);\n\t\tconst parsed = parseOptimizerJson(raw);\n\t\tif (!parsed) return fallbackEnhance(input.text);\n\t\tif (parsed.decision === \"clarify\" && input.forceEnhance) {\n\t\t\t// Segunda pasada: mejorar sin preguntar (modo auto).\n\t\t\tconst forcedRaw = await complete(\n\t\t\t\tsystemPrompt,\n\t\t\t\tuserContent +\n\t\t\t\t\t\"\\n\\nIMPORTANTE: modo automático — NO hagas preguntas. \" +\n\t\t\t\t\t\"Resuelve los gaps con supuestos razonables y devuelve SOLO un \" +\n\t\t\t\t\t'prompt mejorado con decision \"enhance\".',\n\t\t\t);\n\t\t\tconst forced = parseOptimizerJson(forcedRaw);\n\t\t\tif (forced && forced.decision === \"enhance\" && typeof forced.enhanced === \"string\" && forced.enhanced.trim()) {\n\t\t\t\treturn {\n\t\t\t\t\tdecision: \"enhance\",\n\t\t\t\t\tquestions: [],\n\t\t\t\t\tenhanced: forced.enhanced.trim(),\n\t\t\t\t\tsummary: typeof forced.summary === \"string\" ? forced.summary : \"\",\n\t\t\t\t};\n\t\t\t}\n\t\t\treturn fallbackEnhance(input.text);\n\t\t}\n\t\tif (parsed.decision === \"clarify\") {\n\t\t\tconst questions = Array.isArray(parsed.questions)\n\t\t\t\t? parsed.questions\n\t\t\t\t\t\t.filter((q): q is string => typeof q === \"string\" && q.trim().length > 0)\n\t\t\t\t\t\t.slice(0, maxQuestions)\n\t\t\t\t: [];\n\t\t\tif (questions.length === 0) return fallbackEnhance(input.text);\n\t\t\treturn {\n\t\t\t\tdecision: \"clarify\",\n\t\t\t\tquestions,\n\t\t\t\tenhanced: \"\",\n\t\t\t\tsummary: typeof parsed.summary === \"string\" && parsed.summary ? parsed.summary : \"\",\n\t\t\t};\n\t\t}\n\t\tconst enhanced =\n\t\t\ttypeof parsed.enhanced === \"string\" && parsed.enhanced.trim() ? parsed.enhanced.trim() : input.text;\n\t\treturn {\n\t\t\tdecision: \"enhance\",\n\t\t\tquestions: [],\n\t\t\tenhanced,\n\t\t\tsummary: typeof parsed.summary === \"string\" ? parsed.summary : \"\",\n\t\t};\n\t} catch {\n\t\treturn fallbackEnhance(input.text);\n\t}\n}\n\n/** Extrae JSON robusto de la salida del LLM (tolera texto alrededor y fences). */\nfunction parseOptimizerJson(raw: string): {\n\tdecision?: string;\n\tquestions?: unknown;\n\tenhanced?: unknown;\n\tsummary?: unknown;\n} | null {\n\tconst cleaned = raw\n\t\t.trim()\n\t\t.replace(/^```(?:json)?/i, \"\")\n\t\t.replace(/```$/, \"\")\n\t\t.trim();\n\t// Buscar el primer objeto JSON balanceado.\n\tconst start = cleaned.indexOf(\"{\");\n\tconst end = cleaned.lastIndexOf(\"}\");\n\tif (start === -1 || end === -1 || end <= start) return null;\n\ttry {\n\t\treturn JSON.parse(cleaned.slice(start, end + 1)) as {\n\t\t\tdecision?: string;\n\t\t\tquestions?: unknown;\n\t\t\tenhanced?: unknown;\n\t\t\tsummary?: unknown;\n\t\t};\n\t} catch {\n\t\treturn null;\n\t}\n}\n\n/** Fallback seguro: devuelve la petición tal cual (nunca degrada la experiencia). */\nfunction fallbackEnhance(text: string): PromptOptimizerResult {\n\treturn { decision: \"enhance\", questions: [], enhanced: text, summary: \"\" };\n}\n"]}