@hoilab/ada-cli 0.84.21 → 0.85.0

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

@@ -0,0 +1,189 @@
+/**
+ * Ada Prompt Cache — optimizador de aciertos de caché de prompt.
+ *
+ * Se registra como extensión inline por defecto. Vive entero en ficheros
+ * propiedad de Ada, así que no cuesta nada contra el presupuesto de sync, y usa
+ * la API pública de extensiones, que es estable.
+ *
+ * Qué hace, y por qué cada cosa:
+ *
+ * - Reordena el system prompt para que lo estable quede delante (`stabilize`).
+ *   Con caché por prefijo, el coste de un cambio depende de su POSICIÓN, no de
+ *   su tamaño.
+ * - Rellena `prompt_cache_key` donde el core no lo pone: endpoints de terceros
+ *   con retención corta, que es justo el caso de un gateway propio.
+ * - Quita `prompt_cache_retention` de endpoints que no lo soportan (un 400 tumba
+ *   la petición entera) y APRENDE de los 400 que ve.
+ * - Repara el orden de TTL de `cache_control` de Anthropic.
+ * - Mide el hit rate real por proveedor y lo muestra en el footer. Sin medición
+ *   todo lo anterior es fe.
+ *
+ * Se desactiva con `promptCache: false` en settings o `ADA_NO_PROMPT_CACHE=1`.
+ */
+import { diagnose, missingCompatFlags, renderDiagnosis } from "./diagnostics.js";
+import { normalizeAnthropicTtlOrder, withCacheKey, withRetentionGuard } from "./payload.js";
+import { stabilizeSystemPrompt } from "./stabilize.js";
+import { CacheStatsStore, formatStats, readCacheUsage } from "./stats.js";
+export { diagnose } from "./diagnostics.js";
+export { stabilizeSystemPrompt } from "./stabilize.js";
+export { CacheStatsStore, readCacheUsage } from "./stats.js";
+function today() {
+    return new Date().toISOString().slice(0, 10);
+}
+/** Etiqueta corta por familia, para el footer. */
+function labelFor(modelId) {
+    const id = modelId.toLowerCase();
+    if (id.includes("deepseek"))
+        return "DS cache";
+    if (id.includes("claude"))
+        return "Claude cache";
+    if (id.includes("gemini"))
+        return "Gemini cache";
+    if (id.includes("gpt") || id.includes("o1") || id.includes("o3"))
+        return "OpenAI cache";
+    return "cache";
+}
+export function createPromptCacheExtension(options) {
+    return (pi) => {
+        if (options.disabled)
+            return;
+        const store = new CacheStatsStore(options.agentDir);
+        void store.load();
+        /** Modelos a los que este proceso ya vio rechazar la retención. */
+        const retentionRejected = new Set();
+        /** ¿La última petición llevó `prompt_cache_retention`? Ver el 400 de abajo. */
+        let sentRetentionLastRequest = false;
+        let currentModelKey = "unknown";
+        let integrityRolledBack = false;
+        // ── 1. Prefijo estable ────────────────────────────────────────────────
+        pi.on("before_agent_start", async (event) => {
+            const opts = event.systemPromptOptions;
+            const result = stabilizeSystemPrompt({
+                prompt: event.systemPrompt,
+                customPrompt: opts.customPrompt,
+                appendSystemPrompt: opts.appendSystemPrompt,
+                promptGuidelines: opts.promptGuidelines,
+                contextFiles: opts.contextFiles,
+            });
+            if (result.rolledBack)
+                integrityRolledBack = true;
+            if (result.lifted === 0)
+                return undefined;
+            return { systemPrompt: result.prompt };
+        });
+        // ── 2. Payload ────────────────────────────────────────────────────────
+        pi.on("before_provider_request", async (event) => {
+            const payload = event.payload;
+            if (!payload || typeof payload !== "object")
+                return undefined;
+            const record = payload;
+            const api = typeof record.__api === "string" ? record.__api : inferApi(record);
+            let next = withCacheKey(record, {
+                api,
+                sessionId: currentSessionId,
+                baseUrl: currentBaseUrl,
+            });
+            next = withRetentionGuard(next, {
+                api,
+                baseUrl: currentBaseUrl,
+                supportsLongRetention: currentSupportsLongRetention,
+                retentionRejected: retentionRejected.has(currentModelKey),
+            });
+            if (api === "anthropic-messages")
+                next = normalizeAnthropicTtlOrder(next);
+            // Se recuerda si viajó retención, para poder atribuir un 400 posterior.
+            sentRetentionLastRequest = typeof next.prompt_cache_retention === "string";
+            return next === record ? undefined : next;
+        });
+        // ── 3. Aprender de los errores del proveedor ──────────────────────────
+        pi.on("after_provider_response", async (event) => {
+            // El cuerpo no viaja en este evento, así que no se puede clasificar el
+            // error por texto. Se usa la única evidencia disponible: un 400 JUSTO
+            // DESPUÉS de haber enviado retención. Sin esa condición, un 400 por
+            // cualquier otro motivo (contexto demasiado largo, argumento inválido)
+            // desactivaría la retención de ese modelo para siempre.
+            if (event.status === 400 && sentRetentionLastRequest) {
+                retentionRejected.add(currentModelKey);
+            }
+            sentRetentionLastRequest = false;
+        });
+        // ── 4. Medición ───────────────────────────────────────────────────────
+        let currentSessionId;
+        let currentBaseUrl;
+        let currentSupportsLongRetention;
+        pi.on("session_start", async (_event, ctx) => {
+            currentSessionId = ctx?.sessionManager?.getSessionId?.();
+        });
+        pi.on("message_end", async (event, ctx) => {
+            const message = event.message;
+            if (!message || message.role !== "assistant")
+                return;
+            // Un reintento del host emite message_end con usage a cero: contarlo
+            // hundiría el ratio con peticiones que nunca llegaron al proveedor.
+            const stop = message.stopReason;
+            if (stop === "error" || stop === "aborted")
+                return;
+            const usage = readCacheUsage(message.usage);
+            if (usage.totalInput === 0)
+                return;
+            const stats = store.record(currentModelKey, today(), usage);
+            const text = formatStats(labelFor(currentModelKey), stats);
+            if (text)
+                ctx?.ui?.setStatus("ada-prompt-cache", integrityRolledBack ? `${text} ⚠️ integridad` : text);
+        });
+        pi.on("model_select", async (event) => {
+            const model = event
+                .model;
+            if (!model)
+                return;
+            currentModelKey = `${model.provider ?? "?"}/${model.id ?? "?"}`;
+            currentBaseUrl = model.baseUrl;
+            const compat = model.compat;
+            currentSupportsLongRetention = compat?.supportsLongCacheRetention;
+        });
+        pi.on("session_shutdown", async () => {
+            await store.flush();
+        });
+        // ── 5. Comando ────────────────────────────────────────────────────────
+        pi.registerCommand("cache", {
+            description: "Estadísticas y diagnóstico de la caché de prompt",
+            handler: async (args, cmdCtx) => {
+                const say = (text) => cmdCtx.ui?.notify(text, "info");
+                const sub = args.trim().split(/\s+/)[0] || "stats";
+                const stats = store.get(currentModelKey);
+                if (sub === "reset") {
+                    store.reset();
+                    say("Contadores de caché reiniciados.");
+                    return;
+                }
+                if (sub === "doctor") {
+                    const d = diagnose(stats, {
+                        api: inferApiFromKey(currentModelKey),
+                        baseUrl: currentBaseUrl,
+                        supportsLongRetention: currentSupportsLongRetention,
+                    });
+                    const missing = missingCompatFlags({
+                        api: inferApiFromKey(currentModelKey),
+                        baseUrl: currentBaseUrl,
+                        supportsLongRetention: currentSupportsLongRetention,
+                    });
+                    const extra = missing.length ? `\n\nFlags de compat que faltan: ${missing.join(", ")}` : "";
+                    say(`${currentModelKey}\n\n${renderDiagnosis(d)}${extra}`);
+                    return;
+                }
+                say(stats ? formatStats(labelFor(currentModelKey), stats) : "Sin datos de caché todavía.");
+            },
+        });
+    };
+}
+function inferApi(payload) {
+    if ("anthropic_version" in payload || "system" in payload)
+        return "anthropic-messages";
+    if ("input" in payload && !("messages" in payload))
+        return "openai-responses";
+    return "openai-completions";
+}
+function inferApiFromKey(modelKey) {
+    return modelKey.toLowerCase().includes("claude") ? "anthropic-messages" : "openai-completions";
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/prompt-cache/index.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Ada Prompt Cache — optimizador de aciertos de caché de prompt.\n *\n * Se registra como extensión inline por defecto. Vive entero en ficheros\n * propiedad de Ada, así que no cuesta nada contra el presupuesto de sync, y usa\n * la API pública de extensiones, que es estable.\n *\n * Qué hace, y por qué cada cosa:\n *\n * - Reordena el system prompt para que lo estable quede delante (`stabilize`).\n *   Con caché por prefijo, el coste de un cambio depende de su POSICIÓN, no de\n *   su tamaño.\n * - Rellena `prompt_cache_key` donde el core no lo pone: endpoints de terceros\n *   con retención corta, que es justo el caso de un gateway propio.\n * - Quita `prompt_cache_retention` de endpoints que no lo soportan (un 400 tumba\n *   la petición entera) y APRENDE de los 400 que ve.\n * - Repara el orden de TTL de `cache_control` de Anthropic.\n * - Mide el hit rate real por proveedor y lo muestra en el footer. Sin medición\n *   todo lo anterior es fe.\n *\n * Se desactiva con `promptCache: false` en settings o `ADA_NO_PROMPT_CACHE=1`.\n */\n\nimport type { ExtensionAPI } from \"../extensions/types.ts\";\nimport { diagnose, missingCompatFlags, renderDiagnosis } from \"./diagnostics.ts\";\nimport { normalizeAnthropicTtlOrder, withCacheKey, withRetentionGuard } from \"./payload.ts\";\nimport { stabilizeSystemPrompt } from \"./stabilize.ts\";\nimport { CacheStatsStore, formatStats, readCacheUsage } from \"./stats.ts\";\n\nexport { diagnose } from \"./diagnostics.ts\";\nexport { stabilizeSystemPrompt } from \"./stabilize.ts\";\nexport { CacheStatsStore, readCacheUsage } from \"./stats.ts\";\n\nfunction today(): string {\n\treturn new Date().toISOString().slice(0, 10);\n}\n\n/** Etiqueta corta por familia, para el footer. */\nfunction labelFor(modelId: string): string {\n\tconst id = modelId.toLowerCase();\n\tif (id.includes(\"deepseek\")) return \"DS cache\";\n\tif (id.includes(\"claude\")) return \"Claude cache\";\n\tif (id.includes(\"gemini\")) return \"Gemini cache\";\n\tif (id.includes(\"gpt\") || id.includes(\"o1\") || id.includes(\"o3\")) return \"OpenAI cache\";\n\treturn \"cache\";\n}\n\nexport interface PromptCacheOptions {\n\tagentDir: string;\n\t/** Desactiva todo (settings o variable de entorno). */\n\tdisabled?: boolean;\n}\n\nexport function createPromptCacheExtension(options: PromptCacheOptions) {\n\treturn (pi: ExtensionAPI): void => {\n\t\tif (options.disabled) return;\n\n\t\tconst store = new CacheStatsStore(options.agentDir);\n\t\tvoid store.load();\n\n\t\t/** Modelos a los que este proceso ya vio rechazar la retención. */\n\t\tconst retentionRejected = new Set<string>();\n\t\t/** ¿La última petición llevó `prompt_cache_retention`? Ver el 400 de abajo. */\n\t\tlet sentRetentionLastRequest = false;\n\t\tlet currentModelKey = \"unknown\";\n\t\tlet integrityRolledBack = false;\n\n\t\t// ── 1. Prefijo estable ────────────────────────────────────────────────\n\t\tpi.on(\"before_agent_start\", async (event) => {\n\t\t\tconst opts = event.systemPromptOptions;\n\t\t\tconst result = stabilizeSystemPrompt({\n\t\t\t\tprompt: event.systemPrompt,\n\t\t\t\tcustomPrompt: opts.customPrompt,\n\t\t\t\tappendSystemPrompt: opts.appendSystemPrompt,\n\t\t\t\tpromptGuidelines: opts.promptGuidelines,\n\t\t\t\tcontextFiles: opts.contextFiles,\n\t\t\t});\n\t\t\tif (result.rolledBack) integrityRolledBack = true;\n\t\t\tif (result.lifted === 0) return undefined;\n\t\t\treturn { systemPrompt: result.prompt };\n\t\t});\n\n\t\t// ── 2. Payload ────────────────────────────────────────────────────────\n\t\tpi.on(\"before_provider_request\", async (event) => {\n\t\t\tconst payload = event.payload;\n\t\t\tif (!payload || typeof payload !== \"object\") return undefined;\n\t\t\tconst record = payload as Record<string, unknown>;\n\t\t\tconst api = typeof record.__api === \"string\" ? record.__api : inferApi(record);\n\n\t\t\tlet next = withCacheKey(record, {\n\t\t\t\tapi,\n\t\t\t\tsessionId: currentSessionId,\n\t\t\t\tbaseUrl: currentBaseUrl,\n\t\t\t});\n\t\t\tnext = withRetentionGuard(next, {\n\t\t\t\tapi,\n\t\t\t\tbaseUrl: currentBaseUrl,\n\t\t\t\tsupportsLongRetention: currentSupportsLongRetention,\n\t\t\t\tretentionRejected: retentionRejected.has(currentModelKey),\n\t\t\t});\n\t\t\tif (api === \"anthropic-messages\") next = normalizeAnthropicTtlOrder(next);\n\t\t\t// Se recuerda si viajó retención, para poder atribuir un 400 posterior.\n\t\t\tsentRetentionLastRequest = typeof next.prompt_cache_retention === \"string\";\n\t\t\treturn next === record ? undefined : next;\n\t\t});\n\n\t\t// ── 3. Aprender de los errores del proveedor ──────────────────────────\n\t\tpi.on(\"after_provider_response\", async (event) => {\n\t\t\t// El cuerpo no viaja en este evento, así que no se puede clasificar el\n\t\t\t// error por texto. Se usa la única evidencia disponible: un 400 JUSTO\n\t\t\t// DESPUÉS de haber enviado retención. Sin esa condición, un 400 por\n\t\t\t// cualquier otro motivo (contexto demasiado largo, argumento inválido)\n\t\t\t// desactivaría la retención de ese modelo para siempre.\n\t\t\tif (event.status === 400 && sentRetentionLastRequest) {\n\t\t\t\tretentionRejected.add(currentModelKey);\n\t\t\t}\n\t\t\tsentRetentionLastRequest = false;\n\t\t});\n\n\t\t// ── 4. Medición ───────────────────────────────────────────────────────\n\t\tlet currentSessionId: string | undefined;\n\t\tlet currentBaseUrl: string | undefined;\n\t\tlet currentSupportsLongRetention: boolean | undefined;\n\n\t\tpi.on(\"session_start\", async (_event, ctx) => {\n\t\t\tcurrentSessionId = ctx?.sessionManager?.getSessionId?.();\n\t\t});\n\n\t\tpi.on(\"message_end\", async (event, ctx) => {\n\t\t\tconst message = event.message as unknown as Record<string, unknown> | undefined;\n\t\t\tif (!message || message.role !== \"assistant\") return;\n\t\t\t// Un reintento del host emite message_end con usage a cero: contarlo\n\t\t\t// hundiría el ratio con peticiones que nunca llegaron al proveedor.\n\t\t\tconst stop = message.stopReason;\n\t\t\tif (stop === \"error\" || stop === \"aborted\") return;\n\t\t\tconst usage = readCacheUsage(message.usage);\n\t\t\tif (usage.totalInput === 0) return;\n\t\t\tconst stats = store.record(currentModelKey, today(), usage);\n\t\t\tconst text = formatStats(labelFor(currentModelKey), stats);\n\t\t\tif (text) ctx?.ui?.setStatus(\"ada-prompt-cache\", integrityRolledBack ? `${text} ⚠️ integridad` : text);\n\t\t});\n\n\t\tpi.on(\"model_select\", async (event) => {\n\t\t\tconst model = (event as { model?: { id?: string; provider?: string; baseUrl?: string; compat?: unknown } })\n\t\t\t\t.model;\n\t\t\tif (!model) return;\n\t\t\tcurrentModelKey = `${model.provider ?? \"?\"}/${model.id ?? \"?\"}`;\n\t\t\tcurrentBaseUrl = model.baseUrl;\n\t\t\tconst compat = model.compat as { supportsLongCacheRetention?: boolean } | undefined;\n\t\t\tcurrentSupportsLongRetention = compat?.supportsLongCacheRetention;\n\t\t});\n\n\t\tpi.on(\"session_shutdown\", async () => {\n\t\t\tawait store.flush();\n\t\t});\n\n\t\t// ── 5. Comando ────────────────────────────────────────────────────────\n\t\tpi.registerCommand(\"cache\", {\n\t\t\tdescription: \"Estadísticas y diagnóstico de la caché de prompt\",\n\t\t\thandler: async (args: string, cmdCtx): Promise<void> => {\n\t\t\t\tconst say = (text: string) => cmdCtx.ui?.notify(text, \"info\");\n\t\t\t\tconst sub = args.trim().split(/\\s+/)[0] || \"stats\";\n\t\t\t\tconst stats = store.get(currentModelKey);\n\t\t\t\tif (sub === \"reset\") {\n\t\t\t\t\tstore.reset();\n\t\t\t\t\tsay(\"Contadores de caché reiniciados.\");\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t\tif (sub === \"doctor\") {\n\t\t\t\t\tconst d = diagnose(stats, {\n\t\t\t\t\t\tapi: inferApiFromKey(currentModelKey),\n\t\t\t\t\t\tbaseUrl: currentBaseUrl,\n\t\t\t\t\t\tsupportsLongRetention: currentSupportsLongRetention,\n\t\t\t\t\t});\n\t\t\t\t\tconst missing = missingCompatFlags({\n\t\t\t\t\t\tapi: inferApiFromKey(currentModelKey),\n\t\t\t\t\t\tbaseUrl: currentBaseUrl,\n\t\t\t\t\t\tsupportsLongRetention: currentSupportsLongRetention,\n\t\t\t\t\t});\n\t\t\t\t\tconst extra = missing.length ? `\\n\\nFlags de compat que faltan: ${missing.join(\", \")}` : \"\";\n\t\t\t\t\tsay(`${currentModelKey}\\n\\n${renderDiagnosis(d)}${extra}`);\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t\tsay(stats ? formatStats(labelFor(currentModelKey), stats) : \"Sin datos de caché todavía.\");\n\t\t\t},\n\t\t});\n\t};\n}\n\nfunction inferApi(payload: Record<string, unknown>): string {\n\tif (\"anthropic_version\" in payload || \"system\" in payload) return \"anthropic-messages\";\n\tif (\"input\" in payload && !(\"messages\" in payload)) return \"openai-responses\";\n\treturn \"openai-completions\";\n}\n\nfunction inferApiFromKey(modelKey: string): string {\n\treturn modelKey.toLowerCase().includes(\"claude\") ? \"anthropic-messages\" : \"openai-completions\";\n}\n"]}

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

@@ -0,0 +1,58 @@
+/**
+ * Mutaciones del payload de proveedor para maximizar aciertos de caché.
+ *
+ * Tres cosas, cada una por un motivo distinto:
+ *
+ * 1. `prompt_cache_key` de respaldo. Ada core ya lo pone, pero solo para la URL
+ *    oficial de OpenAI o cuando hay retención larga declarada
+ *    (`openai-completions.ts`). Un endpoint de terceros con retención corta —
+ *    justo el caso de un gateway propio o un proxy — se queda sin clave, y sin
+ *    clave el backend no puede enrutar a un worker con la caché caliente.
+ *
+ * 2. Seguridad de `prompt_cache_retention`. Enviarlo a un endpoint que no lo
+ *    entiende devuelve 400 y tumba la petición entera. Se envía solo cuando se
+ *    sabe que se soporta, y se APRENDE de los 400 vistos.
+ *
+ * 3. Orden de TTL en `cache_control` de Anthropic. La API rechaza un breakpoint
+ *    de 1h que venga detrás de uno de 5m. Es un fallo de orden, no de contenido,
+ *    y se puede reparar sin cambiar nada semántico.
+ */
+export declare function clampCacheKey(sessionId: string | undefined): string | undefined;
+/** ¿El payload ya trae una clave efectiva? Nunca se pisa la del host. */
+export declare function hasCacheKey(payload: Record<string, unknown>): boolean;
+export interface PayloadContext {
+    api: string;
+    baseUrl?: string;
+    sessionId?: string;
+    /** `compat.supportsLongCacheRetention` del modelo. */
+    supportsLongRetention?: boolean;
+    /** Modelos a los que este proceso ya vio devolver 400 por retención. */
+    retentionRejected?: boolean;
+}
+/**
+ * Añade la clave de caché si falta. No sobrescribe nunca: una clave que cambia
+ * entre peticiones es PEOR que ninguna, porque fragmenta el enrutado.
+ */
+export declare function withCacheKey(payload: Record<string, unknown>, ctx: PayloadContext): Record<string, unknown>;
+/**
+ * Decide si `prompt_cache_retention` puede viajar.
+ *
+ * El orden importa: la evidencia empírica (un 400 ya visto) manda sobre la
+ * configuración del usuario. Si no, un opt-in equivocado contra un endpoint que
+ * lo rechaza devuelve 400 para siempre.
+ */
+export declare function retentionAllowed(ctx: PayloadContext): boolean;
+export declare function withRetentionGuard(payload: Record<string, unknown>, ctx: PayloadContext): Record<string, unknown>;
+/** ¿Este error del proveedor es "no entiendo prompt_cache_retention"? */
+export declare function isRetentionUnsupportedError(text: string): boolean;
+/** ¿Es el error de Anthropic por orden de TTL en cache_control? */
+export declare function isAnthropicTtlOrderError(text: string): boolean;
+/**
+ * Recorre los bloques con `cache_control` en ORDEN DE CABLE (tools → system →
+ * messages) y degrada cualquier TTL largo que venga detrás de uno corto.
+ *
+ * Degradar es seguro: se pierde duración de caché, no corrección. Reordenar los
+ * breakpoints sí cambiaría qué se cachea, y eso no es nuestro para decidir.
+ */
+export declare function normalizeAnthropicTtlOrder(payload: Record<string, unknown>): Record<string, unknown>;
+//# sourceMappingURL=payload.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"payload.d.ts","sourceRoot":"","sources":["../../../src/core/prompt-cache/payload.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAKH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAI/E;AAED,0EAAyE;AACzE,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAErE;AAED,MAAM,WAAW,cAAc;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,yEAAwE;IACxE,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAKD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAM3G;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAI7D;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAKjH;AAED,0EAAyE;AACzE,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEjE;AAED,oEAAmE;AACnE,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE9D;AAOD;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAiCpG","sourcesContent":["/**\n * Mutaciones del payload de proveedor para maximizar aciertos de caché.\n *\n * Tres cosas, cada una por un motivo distinto:\n *\n * 1. `prompt_cache_key` de respaldo. Ada core ya lo pone, pero solo para la URL\n *    oficial de OpenAI o cuando hay retención larga declarada\n *    (`openai-completions.ts`). Un endpoint de terceros con retención corta —\n *    justo el caso de un gateway propio o un proxy — se queda sin clave, y sin\n *    clave el backend no puede enrutar a un worker con la caché caliente.\n *\n * 2. Seguridad de `prompt_cache_retention`. Enviarlo a un endpoint que no lo\n *    entiende devuelve 400 y tumba la petición entera. Se envía solo cuando se\n *    sabe que se soporta, y se APRENDE de los 400 vistos.\n *\n * 3. Orden de TTL en `cache_control` de Anthropic. La API rechaza un breakpoint\n *    de 1h que venga detrás de uno de 5m. Es un fallo de orden, no de contenido,\n *    y se puede reparar sin cambiar nada semántico.\n */\n\n/** Límite documentado de OpenAI para prompt_cache_key. */\nconst MAX_CACHE_KEY_LENGTH = 64;\n\nexport function clampCacheKey(sessionId: string | undefined): string | undefined {\n\tconst trimmed = sessionId?.trim();\n\tif (!trimmed) return undefined;\n\treturn [...trimmed].slice(0, MAX_CACHE_KEY_LENGTH).join(\"\");\n}\n\n/** ¿El payload ya trae una clave efectiva? Nunca se pisa la del host. */\nexport function hasCacheKey(payload: Record<string, unknown>): boolean {\n\treturn typeof payload.prompt_cache_key === \"string\" || typeof payload.promptCacheKey === \"string\";\n}\n\nexport interface PayloadContext {\n\tapi: string;\n\tbaseUrl?: string;\n\tsessionId?: string;\n\t/** `compat.supportsLongCacheRetention` del modelo. */\n\tsupportsLongRetention?: boolean;\n\t/** Modelos a los que este proceso ya vio devolver 400 por retención. */\n\tretentionRejected?: boolean;\n}\n\n/** APIs con forma OpenAI donde `prompt_cache_key` significa algo. */\nconst OPENAI_SHAPED = new Set([\"openai-completions\", \"openai-responses\"]);\n\n/**\n * Añade la clave de caché si falta. No sobrescribe nunca: una clave que cambia\n * entre peticiones es PEOR que ninguna, porque fragmenta el enrutado.\n */\nexport function withCacheKey(payload: Record<string, unknown>, ctx: PayloadContext): Record<string, unknown> {\n\tif (!OPENAI_SHAPED.has(ctx.api)) return payload;\n\tif (hasCacheKey(payload)) return payload;\n\tconst key = clampCacheKey(ctx.sessionId);\n\tif (!key) return payload;\n\treturn { ...payload, prompt_cache_key: key };\n}\n\n/**\n * Decide si `prompt_cache_retention` puede viajar.\n *\n * El orden importa: la evidencia empírica (un 400 ya visto) manda sobre la\n * configuración del usuario. Si no, un opt-in equivocado contra un endpoint que\n * lo rechaza devuelve 400 para siempre.\n */\nexport function retentionAllowed(ctx: PayloadContext): boolean {\n\tif (ctx.baseUrl?.includes(\"api.openai.com\")) return true;\n\tif (ctx.retentionRejected) return false;\n\treturn ctx.supportsLongRetention === true;\n}\n\nexport function withRetentionGuard(payload: Record<string, unknown>, ctx: PayloadContext): Record<string, unknown> {\n\tif (typeof payload.prompt_cache_retention !== \"string\") return payload;\n\tif (retentionAllowed(ctx)) return payload;\n\tconst { prompt_cache_retention: _dropped, ...rest } = payload;\n\treturn rest;\n}\n\n/** ¿Este error del proveedor es \"no entiendo prompt_cache_retention\"? */\nexport function isRetentionUnsupportedError(text: string): boolean {\n\treturn /prompt_cache_retention/i.test(text) && /unsupported|unknown|unrecognized|invalid/i.test(text);\n}\n\n/** ¿Es el error de Anthropic por orden de TTL en cache_control? */\nexport function isAnthropicTtlOrderError(text: string): boolean {\n\treturn /cache_control/i.test(text) && /ttl/i.test(text) && /order|1h|5m/i.test(text);\n}\n\ninterface CacheControlHolder {\n\tcache_control?: { type?: string; ttl?: string };\n\t[key: string]: unknown;\n}\n\n/**\n * Recorre los bloques con `cache_control` en ORDEN DE CABLE (tools → system →\n * messages) y degrada cualquier TTL largo que venga detrás de uno corto.\n *\n * Degradar es seguro: se pierde duración de caché, no corrección. Reordenar los\n * breakpoints sí cambiaría qué se cachea, y eso no es nuestro para decidir.\n */\nexport function normalizeAnthropicTtlOrder(payload: Record<string, unknown>): Record<string, unknown> {\n\tconst holders: CacheControlHolder[] = [];\n\tconst collect = (value: unknown): void => {\n\t\tif (Array.isArray(value)) {\n\t\t\tfor (const item of value) collect(item);\n\t\t\treturn;\n\t\t}\n\t\tif (!value || typeof value !== \"object\") return;\n\t\tconst record = value as CacheControlHolder;\n\t\tif (record.cache_control && typeof record.cache_control === \"object\") holders.push(record);\n\t\tfor (const nested of Object.values(record)) {\n\t\t\tif (nested && typeof nested === \"object\") collect(nested);\n\t\t}\n\t};\n\t// Orden de cable, no de objeto: es el que valida Anthropic.\n\tcollect(payload.tools);\n\tcollect(payload.system);\n\tcollect(payload.messages);\n\n\tlet seenShort = false;\n\tlet changed = false;\n\tfor (const holder of holders) {\n\t\tconst ttl = holder.cache_control?.ttl;\n\t\tif (ttl === \"5m\" || ttl === undefined) {\n\t\t\tseenShort = true;\n\t\t\tcontinue;\n\t\t}\n\t\tif (ttl === \"1h\" && seenShort) {\n\t\t\tholder.cache_control = { ...holder.cache_control, ttl: \"5m\" };\n\t\t\tchanged = true;\n\t\t}\n\t}\n\treturn changed ? { ...payload } : payload;\n}\n"]}

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

@@ -0,0 +1,122 @@
+/**
+ * Mutaciones del payload de proveedor para maximizar aciertos de caché.
+ *
+ * Tres cosas, cada una por un motivo distinto:
+ *
+ * 1. `prompt_cache_key` de respaldo. Ada core ya lo pone, pero solo para la URL
+ *    oficial de OpenAI o cuando hay retención larga declarada
+ *    (`openai-completions.ts`). Un endpoint de terceros con retención corta —
+ *    justo el caso de un gateway propio o un proxy — se queda sin clave, y sin
+ *    clave el backend no puede enrutar a un worker con la caché caliente.
+ *
+ * 2. Seguridad de `prompt_cache_retention`. Enviarlo a un endpoint que no lo
+ *    entiende devuelve 400 y tumba la petición entera. Se envía solo cuando se
+ *    sabe que se soporta, y se APRENDE de los 400 vistos.
+ *
+ * 3. Orden de TTL en `cache_control` de Anthropic. La API rechaza un breakpoint
+ *    de 1h que venga detrás de uno de 5m. Es un fallo de orden, no de contenido,
+ *    y se puede reparar sin cambiar nada semántico.
+ */
+/** Límite documentado de OpenAI para prompt_cache_key. */
+const MAX_CACHE_KEY_LENGTH = 64;
+export function clampCacheKey(sessionId) {
+    const trimmed = sessionId?.trim();
+    if (!trimmed)
+        return undefined;
+    return [...trimmed].slice(0, MAX_CACHE_KEY_LENGTH).join("");
+}
+/** ¿El payload ya trae una clave efectiva? Nunca se pisa la del host. */
+export function hasCacheKey(payload) {
+    return typeof payload.prompt_cache_key === "string" || typeof payload.promptCacheKey === "string";
+}
+/** APIs con forma OpenAI donde `prompt_cache_key` significa algo. */
+const OPENAI_SHAPED = new Set(["openai-completions", "openai-responses"]);
+/**
+ * Añade la clave de caché si falta. No sobrescribe nunca: una clave que cambia
+ * entre peticiones es PEOR que ninguna, porque fragmenta el enrutado.
+ */
+export function withCacheKey(payload, ctx) {
+    if (!OPENAI_SHAPED.has(ctx.api))
+        return payload;
+    if (hasCacheKey(payload))
+        return payload;
+    const key = clampCacheKey(ctx.sessionId);
+    if (!key)
+        return payload;
+    return { ...payload, prompt_cache_key: key };
+}
+/**
+ * Decide si `prompt_cache_retention` puede viajar.
+ *
+ * El orden importa: la evidencia empírica (un 400 ya visto) manda sobre la
+ * configuración del usuario. Si no, un opt-in equivocado contra un endpoint que
+ * lo rechaza devuelve 400 para siempre.
+ */
+export function retentionAllowed(ctx) {
+    if (ctx.baseUrl?.includes("api.openai.com"))
+        return true;
+    if (ctx.retentionRejected)
+        return false;
+    return ctx.supportsLongRetention === true;
+}
+export function withRetentionGuard(payload, ctx) {
+    if (typeof payload.prompt_cache_retention !== "string")
+        return payload;
+    if (retentionAllowed(ctx))
+        return payload;
+    const { prompt_cache_retention: _dropped, ...rest } = payload;
+    return rest;
+}
+/** ¿Este error del proveedor es "no entiendo prompt_cache_retention"? */
+export function isRetentionUnsupportedError(text) {
+    return /prompt_cache_retention/i.test(text) && /unsupported|unknown|unrecognized|invalid/i.test(text);
+}
+/** ¿Es el error de Anthropic por orden de TTL en cache_control? */
+export function isAnthropicTtlOrderError(text) {
+    return /cache_control/i.test(text) && /ttl/i.test(text) && /order|1h|5m/i.test(text);
+}
+/**
+ * Recorre los bloques con `cache_control` en ORDEN DE CABLE (tools → system →
+ * messages) y degrada cualquier TTL largo que venga detrás de uno corto.
+ *
+ * Degradar es seguro: se pierde duración de caché, no corrección. Reordenar los
+ * breakpoints sí cambiaría qué se cachea, y eso no es nuestro para decidir.
+ */
+export function normalizeAnthropicTtlOrder(payload) {
+    const holders = [];
+    const collect = (value) => {
+        if (Array.isArray(value)) {
+            for (const item of value)
+                collect(item);
+            return;
+        }
+        if (!value || typeof value !== "object")
+            return;
+        const record = value;
+        if (record.cache_control && typeof record.cache_control === "object")
+            holders.push(record);
+        for (const nested of Object.values(record)) {
+            if (nested && typeof nested === "object")
+                collect(nested);
+        }
+    };
+    // Orden de cable, no de objeto: es el que valida Anthropic.
+    collect(payload.tools);
+    collect(payload.system);
+    collect(payload.messages);
+    let seenShort = false;
+    let changed = false;
+    for (const holder of holders) {
+        const ttl = holder.cache_control?.ttl;
+        if (ttl === "5m" || ttl === undefined) {
+            seenShort = true;
+            continue;
+        }
+        if (ttl === "1h" && seenShort) {
+            holder.cache_control = { ...holder.cache_control, ttl: "5m" };
+            changed = true;
+        }
+    }
+    return changed ? { ...payload } : payload;
+}
+//# sourceMappingURL=payload.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"payload.js","sourceRoot":"","sources":["../../../src/core/prompt-cache/payload.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Mutaciones del payload de proveedor para maximizar aciertos de caché.\n *\n * Tres cosas, cada una por un motivo distinto:\n *\n * 1. `prompt_cache_key` de respaldo. Ada core ya lo pone, pero solo para la URL\n *    oficial de OpenAI o cuando hay retención larga declarada\n *    (`openai-completions.ts`). Un endpoint de terceros con retención corta —\n *    justo el caso de un gateway propio o un proxy — se queda sin clave, y sin\n *    clave el backend no puede enrutar a un worker con la caché caliente.\n *\n * 2. Seguridad de `prompt_cache_retention`. Enviarlo a un endpoint que no lo\n *    entiende devuelve 400 y tumba la petición entera. Se envía solo cuando se\n *    sabe que se soporta, y se APRENDE de los 400 vistos.\n *\n * 3. Orden de TTL en `cache_control` de Anthropic. La API rechaza un breakpoint\n *    de 1h que venga detrás de uno de 5m. Es un fallo de orden, no de contenido,\n *    y se puede reparar sin cambiar nada semántico.\n */\n\n/** Límite documentado de OpenAI para prompt_cache_key. */\nconst MAX_CACHE_KEY_LENGTH = 64;\n\nexport function clampCacheKey(sessionId: string | undefined): string | undefined {\n\tconst trimmed = sessionId?.trim();\n\tif (!trimmed) return undefined;\n\treturn [...trimmed].slice(0, MAX_CACHE_KEY_LENGTH).join(\"\");\n}\n\n/** ¿El payload ya trae una clave efectiva? Nunca se pisa la del host. */\nexport function hasCacheKey(payload: Record<string, unknown>): boolean {\n\treturn typeof payload.prompt_cache_key === \"string\" || typeof payload.promptCacheKey === \"string\";\n}\n\nexport interface PayloadContext {\n\tapi: string;\n\tbaseUrl?: string;\n\tsessionId?: string;\n\t/** `compat.supportsLongCacheRetention` del modelo. */\n\tsupportsLongRetention?: boolean;\n\t/** Modelos a los que este proceso ya vio devolver 400 por retención. */\n\tretentionRejected?: boolean;\n}\n\n/** APIs con forma OpenAI donde `prompt_cache_key` significa algo. */\nconst OPENAI_SHAPED = new Set([\"openai-completions\", \"openai-responses\"]);\n\n/**\n * Añade la clave de caché si falta. No sobrescribe nunca: una clave que cambia\n * entre peticiones es PEOR que ninguna, porque fragmenta el enrutado.\n */\nexport function withCacheKey(payload: Record<string, unknown>, ctx: PayloadContext): Record<string, unknown> {\n\tif (!OPENAI_SHAPED.has(ctx.api)) return payload;\n\tif (hasCacheKey(payload)) return payload;\n\tconst key = clampCacheKey(ctx.sessionId);\n\tif (!key) return payload;\n\treturn { ...payload, prompt_cache_key: key };\n}\n\n/**\n * Decide si `prompt_cache_retention` puede viajar.\n *\n * El orden importa: la evidencia empírica (un 400 ya visto) manda sobre la\n * configuración del usuario. Si no, un opt-in equivocado contra un endpoint que\n * lo rechaza devuelve 400 para siempre.\n */\nexport function retentionAllowed(ctx: PayloadContext): boolean {\n\tif (ctx.baseUrl?.includes(\"api.openai.com\")) return true;\n\tif (ctx.retentionRejected) return false;\n\treturn ctx.supportsLongRetention === true;\n}\n\nexport function withRetentionGuard(payload: Record<string, unknown>, ctx: PayloadContext): Record<string, unknown> {\n\tif (typeof payload.prompt_cache_retention !== \"string\") return payload;\n\tif (retentionAllowed(ctx)) return payload;\n\tconst { prompt_cache_retention: _dropped, ...rest } = payload;\n\treturn rest;\n}\n\n/** ¿Este error del proveedor es \"no entiendo prompt_cache_retention\"? */\nexport function isRetentionUnsupportedError(text: string): boolean {\n\treturn /prompt_cache_retention/i.test(text) && /unsupported|unknown|unrecognized|invalid/i.test(text);\n}\n\n/** ¿Es el error de Anthropic por orden de TTL en cache_control? */\nexport function isAnthropicTtlOrderError(text: string): boolean {\n\treturn /cache_control/i.test(text) && /ttl/i.test(text) && /order|1h|5m/i.test(text);\n}\n\ninterface CacheControlHolder {\n\tcache_control?: { type?: string; ttl?: string };\n\t[key: string]: unknown;\n}\n\n/**\n * Recorre los bloques con `cache_control` en ORDEN DE CABLE (tools → system →\n * messages) y degrada cualquier TTL largo que venga detrás de uno corto.\n *\n * Degradar es seguro: se pierde duración de caché, no corrección. Reordenar los\n * breakpoints sí cambiaría qué se cachea, y eso no es nuestro para decidir.\n */\nexport function normalizeAnthropicTtlOrder(payload: Record<string, unknown>): Record<string, unknown> {\n\tconst holders: CacheControlHolder[] = [];\n\tconst collect = (value: unknown): void => {\n\t\tif (Array.isArray(value)) {\n\t\t\tfor (const item of value) collect(item);\n\t\t\treturn;\n\t\t}\n\t\tif (!value || typeof value !== \"object\") return;\n\t\tconst record = value as CacheControlHolder;\n\t\tif (record.cache_control && typeof record.cache_control === \"object\") holders.push(record);\n\t\tfor (const nested of Object.values(record)) {\n\t\t\tif (nested && typeof nested === \"object\") collect(nested);\n\t\t}\n\t};\n\t// Orden de cable, no de objeto: es el que valida Anthropic.\n\tcollect(payload.tools);\n\tcollect(payload.system);\n\tcollect(payload.messages);\n\n\tlet seenShort = false;\n\tlet changed = false;\n\tfor (const holder of holders) {\n\t\tconst ttl = holder.cache_control?.ttl;\n\t\tif (ttl === \"5m\" || ttl === undefined) {\n\t\t\tseenShort = true;\n\t\t\tcontinue;\n\t\t}\n\t\tif (ttl === \"1h\" && seenShort) {\n\t\t\tholder.cache_control = { ...holder.cache_control, ttl: \"5m\" };\n\t\t\tchanged = true;\n\t\t}\n\t}\n\treturn changed ? { ...payload } : payload;\n}\n"]}

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

@@ -0,0 +1,65 @@
+/**
+ * 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.
+ */
+/** Separador entre la zona estable y la dinámica. */
+export declare const STABLE_SEPARATOR = "\n\n---\n\n";
+export declare function isStableContextFile(path: string): boolean;
+export interface StabilizeInput {
+    /** El system prompt ya ensamblado. */
+    prompt: string;
+    /** Prompt de sistema propio del usuario, si lo hay. */
+    customPrompt?: string;
+    /** Bloques añadidos al final (incluye la personalidad del engine). */
+    appendSystemPrompt?: string;
+    /** Guidelines por tool. */
+    promptGuidelines?: string[];
+    /** Ficheros de contexto cargados. */
+    contextFiles?: Array<{
+        path: string;
+        content: string;
+    }>;
+}
+export interface StabilizeResult {
+    prompt: string;
+    /** Cuántos bloques se subieron al prefijo estable. */
+    lifted: number;
+    /** True si la guardia de integridad descartó la reescritura. */
+    rolledBack: boolean;
+}
+/**
+ * Marcadores estructurales: etiquetas y delimitadores de bloque. Si el
+ * reordenado pierde alguno, algo se ha comido texto.
+ */
+export declare function extractStructuralMarkers(text: string): string[];
+/** Construye los bloques candidatos a subir, en orden determinista. */
+export declare function buildStableCandidates(input: StabilizeInput): string[];
+/**
+ * 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 declare function stabilizeSystemPrompt(input: StabilizeInput): StabilizeResult;
+//# sourceMappingURL=stabilize.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stabilize.d.ts","sourceRoot":"","sources":["../../../src/core/prompt-cache/stabilize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAKH,sDAAqD;AACrD,eAAO,MAAM,gBAAgB,gBAAgB,CAAC;AAW9C,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED,MAAM,WAAW,cAAc;IAC9B,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uEAAsE;IACtE,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,2BAA2B;IAC3B,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,qCAAqC;IACrC,YAAY,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACxD;AAED,MAAM,WAAW,eAAe;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,uDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC;IACf,iEAAgE;IAChE,UAAU,EAAE,OAAO,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAK/D;AAED,uEAAuE;AACvE,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,EAAE,CAkBrE;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,cAAc,GAAG,eAAe,CAuD5E","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"]}