@hoilab/ada-cli 0.84.22 → 0.85.1

package/dist/core/browser/tools.js

@@ -0,0 +1,279 @@
+/**
+ * Tools de navegador para el agente.
+ *
+ * El navegador arranca perezosamente: la primera tool que lo necesita lo abre.
+ * Nadie paga un proceso de Chrome por tener las tools registradas.
+ *
+ * Las tres reglas viven en `politica.ts` y aquí solo se aplican. La que más se
+ * nota en el uso: el agente **solo conduce las pestañas que abrió él**, y
+ * además lo hace en un perfil vacío sin ninguna sesión del usuario.
+ */
+import { Type } from "typebox";
+import { reglaDeEleccion } from "../prompt-eleccion.js";
+import { CampoSecretoError, esCampoSecreto, pareceIrreversible, urlNavegable } from "./politica.js";
+import { NavegadorAgente } from "./sesion.js";
+/**
+ * Cómo usar el navegador, no solo que existe.
+ *
+ * Sin esto el modelo intentaría conducir pestañas que no abrió (y que fallan
+ * con un error que no entiende), o pulsaría "Comprar" sin preguntar.
+ */
+function guiaNavegador(ordenador) {
+    return [
+        reglaDeEleccion({ navegador: true, ordenador }),
+        "Abre las páginas con browser_open: no puedes conducir las pestañas del usuario, solo las que abras tú.",
+        "Usa browser_read antes de pulsar o escribir, y actúa por la referencia que devuelve; vuelve a leer después de navegar.",
+        "Si un control envía, compra, publica, borra o acepta condiciones, pregunta al usuario ANTES de pulsarlo.",
+        "El navegador del agente usa un perfil vacío: no hay sesiones iniciadas, así que no cuentes con estar identificado en ningún sitio.",
+    ];
+}
+function texto(t) {
+    return { content: [{ type: "text", text: t }], details: undefined };
+}
+function fallo(error) {
+    return texto(`Error: ${error instanceof Error ? error.message : String(error)}`);
+}
+/**
+ * Script que se inyecta para leer la página.
+ *
+ * Devuelve el texto y los elementos con los que se puede interactuar, cada uno
+ * con una referencia estable dentro de la lectura. Se marcan los campos que
+ * piden credenciales y los botones que parecen irreversibles, para que el
+ * agente lo sepa ANTES de tocarlos, no después.
+ */
+const LEER_PAGINA = `(() => {
+  const interactivos = [...document.querySelectorAll('a[href],button,input,select,textarea,[role=button],[role=link],[onclick]')];
+  window.__adaRefs = interactivos;
+  const visible = (el) => { const r = el.getBoundingClientRect(); return r.width > 0 && r.height > 0; };
+  return {
+    url: location.href,
+    titulo: document.title,
+    texto: (document.body?.innerText ?? '').slice(0, 20000),
+    elementos: interactivos.map((el, i) => ({
+      ref: i,
+      etiqueta: el.tagName.toLowerCase(),
+      type: el.getAttribute('type') ?? undefined,
+      name: el.getAttribute('name') ?? undefined,
+      id: el.id || undefined,
+      autocomplete: el.getAttribute('autocomplete') ?? undefined,
+      placeholder: el.getAttribute('placeholder') ?? undefined,
+      ariaLabel: el.getAttribute('aria-label') ?? undefined,
+      texto: (el.innerText || el.value || '').trim().slice(0, 120),
+      visible: visible(el),
+    })).filter((e) => e.visible).slice(0, 200),
+  };
+})()`;
+export function crearBrowserTools(opciones) {
+    // La regla de elección solo puede nombrar `computer_*` si esas tools existen.
+    const guia = guiaNavegador(opciones.ordenador === true);
+    let navegador = null;
+    const exigirNavegador = async () => {
+        if (!navegador)
+            navegador = await NavegadorAgente.abrir(opciones);
+        return navegador;
+    };
+    const abrir = {
+        name: "browser_open",
+        label: "Abrir pestaña",
+        promptGuidelines: guia,
+        description: "Abre una pestaña NUEVA en el navegador del agente y devuelve su id. " +
+            "Es la única forma de tener una pestaña: las del usuario no se pueden conducir. " +
+            "El navegador usa un perfil vacío, así que no hay sesiones iniciadas.",
+        promptSnippet: "abrir una página web para interactuar con ella",
+        parameters: Type.Object({ url: Type.String({ description: "URL http(s) a abrir" }) }),
+        async execute(_id, input) {
+            try {
+                const url = urlNavegable(String(input.url ?? ""));
+                const nav = await exigirNavegador();
+                const pestaña = await nav.abrirPestaña(url.toString());
+                return texto(`Pestaña abierta: ${pestaña.targetId}\nURL: ${pestaña.url}`);
+            }
+            catch (error) {
+                return fallo(error);
+            }
+        },
+    };
+    const navegar = {
+        name: "browser_navigate",
+        label: "Navegar",
+        description: "Lleva una pestaña del agente a otra URL.",
+        promptSnippet: "cambiar de página en una pestaña ya abierta",
+        parameters: Type.Object({ tabId: Type.String(), url: Type.String() }),
+        async execute(_id, input) {
+            try {
+                const url = urlNavegable(String(input.url ?? ""));
+                const nav = await exigirNavegador();
+                await nav.navegar(String(input.tabId), url.toString());
+                return texto(`Navegado a ${url}`);
+            }
+            catch (error) {
+                return fallo(error);
+            }
+        },
+    };
+    const leer = {
+        name: "browser_read",
+        label: "Leer página",
+        description: "Devuelve el texto de la página y sus elementos interactivos con una referencia cada uno. " +
+            "Usa esas referencias en browser_click y browser_type. Hay que volver a leer tras navegar.",
+        promptSnippet: "leer el contenido y los controles de una página",
+        parameters: Type.Object({ tabId: Type.String() }),
+        async execute(_id, input) {
+            try {
+                const nav = await exigirNavegador();
+                const pagina = await nav.evaluar(String(input.tabId), LEER_PAGINA);
+                const lineas = pagina.elementos.map((e) => {
+                    const marcas = [
+                        esCampoSecreto(e) ? "CREDENCIAL — el agente no escribe aquí" : "",
+                        pareceIrreversible(e.texto) ? "parece irreversible: pregunta antes" : "",
+                    ].filter(Boolean);
+                    const desc = e.texto || e.placeholder || e.ariaLabel || e.name || e.id || "(sin texto)";
+                    return `  [${e.ref}] <${e.etiqueta}${e.type ? ` type=${e.type}` : ""}> ${desc}${marcas.length ? ` ⚠ ${marcas.join("; ")}` : ""}`;
+                });
+                return texto(`${pagina.titulo}\n${pagina.url}\n\n${pagina.texto}\n\nElementos interactivos:\n${lineas.join("\n") || "  (ninguno)"}`);
+            }
+            catch (error) {
+                return fallo(error);
+            }
+        },
+    };
+    const pulsar = {
+        name: "browser_click",
+        label: "Pulsar",
+        promptGuidelines: guia,
+        description: "Pulsa un elemento por su referencia de browser_read. " +
+            "Si el botón parece irreversible (enviar, comprar, publicar, borrar), pregunta al usuario antes.",
+        promptSnippet: "pulsar un botón o enlace de la página",
+        parameters: Type.Object({ tabId: Type.String(), ref: Type.Number() }),
+        async execute(_id, input) {
+            try {
+                const nav = await exigirNavegador();
+                const r = await nav.evaluar(String(input.tabId), `(() => {
+					  const el = (window.__adaRefs || [])[${Number(input.ref)}];
+					  if (!el) return { ok: false, motivo: 'referencia desconocida; vuelve a leer la página' };
+					  const t = (el.innerText || el.value || '').trim();
+					  el.click();
+					  return { ok: true, texto: t };
+					})()`);
+                if (!r.ok)
+                    return texto(`No se pudo pulsar: ${r.motivo}`);
+                return texto(`Pulsado: ${r.texto || "(sin texto)"}`);
+            }
+            catch (error) {
+                return fallo(error);
+            }
+        },
+    };
+    const escribir = {
+        name: "browser_type",
+        label: "Escribir",
+        promptGuidelines: guia,
+        description: "Escribe texto en un campo por su referencia. " +
+            "Nunca escribe en campos de contraseña, token o tarjeta: eso lo hace el usuario.",
+        promptSnippet: "rellenar un campo de un formulario",
+        parameters: Type.Object({ tabId: Type.String(), ref: Type.Number(), texto: Type.String() }),
+        async execute(_id, input) {
+            try {
+                const nav = await exigirNavegador();
+                const tabId = String(input.tabId);
+                // Se comprueba en el momento, no con lo leído antes: la página pudo
+                // cambiar el campo entre la lectura y ahora.
+                const campo = await nav.evaluar(tabId, `(() => {
+					  const el = (window.__adaRefs || [])[${Number(input.ref)}];
+					  if (!el) return null;
+					  return { ref: ${Number(input.ref)}, etiqueta: el.tagName.toLowerCase(), type: el.getAttribute('type') ?? undefined,
+					    name: el.getAttribute('name') ?? undefined, id: el.id || undefined,
+					    autocomplete: el.getAttribute('autocomplete') ?? undefined,
+					    placeholder: el.getAttribute('placeholder') ?? undefined,
+					    ariaLabel: el.getAttribute('aria-label') ?? undefined, texto: '' };
+					})()`);
+                if (!campo)
+                    return texto("No se pudo escribir: referencia desconocida; vuelve a leer la página.");
+                if (esCampoSecreto(campo))
+                    return fallo(new CampoSecretoError());
+                await nav.evaluar(tabId, `(() => {
+					  const el = window.__adaRefs[${Number(input.ref)}];
+					  const setter = Object.getOwnPropertyDescriptor(el.constructor.prototype, 'value')?.set;
+					  // El setter del prototipo, no el de la instancia: React sobrescribe
+					  // el de la instancia y su onChange no se enteraría del cambio.
+					  if (setter) setter.call(el, ${JSON.stringify(String(input.texto ?? ""))});
+					  else el.value = ${JSON.stringify(String(input.texto ?? ""))};
+					  el.dispatchEvent(new Event('input', { bubbles: true }));
+					  el.dispatchEvent(new Event('change', { bubbles: true }));
+					})()`);
+                return texto(`Escrito en [${Number(input.ref)}].`);
+            }
+            catch (error) {
+                return fallo(error);
+            }
+        },
+    };
+    const capturar = {
+        name: "browser_screenshot",
+        label: "Captura",
+        description: "Captura la pestaña y devuelve la imagen.",
+        promptSnippet: "ver cómo se ve la página",
+        parameters: Type.Object({ tabId: Type.String() }),
+        async execute(_id, input) {
+            try {
+                const nav = await exigirNavegador();
+                const data = await nav.capturar(String(input.tabId));
+                return { content: [{ type: "image", data, mimeType: "image/png" }], details: undefined };
+            }
+            catch (error) {
+                return fallo(error);
+            }
+        },
+    };
+    const viewport = {
+        name: "browser_viewport",
+        label: "Cambiar viewport",
+        description: "Cambia el tamaño de la ventana emulada. Con movil=true, una página SIN <meta name=viewport> " +
+            "usará el viewport heredado de 980 px: es lo que hace un teléfono de verdad, no un fallo.",
+        promptSnippet: "probar la página en otro tamaño de pantalla",
+        parameters: Type.Object({
+            tabId: Type.String(),
+            width: Type.Number(),
+            height: Type.Number(),
+            movil: Type.Optional(Type.Boolean()),
+        }),
+        async execute(_id, input) {
+            try {
+                const nav = await exigirNavegador();
+                await nav.cambiarViewport(String(input.tabId), Number(input.width), Number(input.height), input.movil === true);
+                return texto(`Viewport: ${Number(input.width)}x${Number(input.height)}${input.movil ? " (móvil)" : ""}`);
+            }
+            catch (error) {
+                return fallo(error);
+            }
+        },
+    };
+    const cerrar = {
+        name: "browser_close",
+        label: "Cerrar pestaña",
+        description: "Cierra una pestaña del agente.",
+        promptSnippet: "cerrar una pestaña que ya no hace falta",
+        parameters: Type.Object({ tabId: Type.String() }),
+        async execute(_id, input) {
+            try {
+                const nav = await exigirNavegador();
+                await nav.cerrarPestaña(String(input.tabId));
+                return texto("Pestaña cerrada.");
+            }
+            catch (error) {
+                return fallo(error);
+            }
+        },
+    };
+    return {
+        browser_open: abrir,
+        browser_navigate: navegar,
+        browser_read: leer,
+        browser_click: pulsar,
+        browser_type: escribir,
+        browser_screenshot: capturar,
+        browser_viewport: viewport,
+        browser_close: cerrar,
+    };
+}
+//# sourceMappingURL=tools.js.map

package/dist/core/browser/tools.js.map

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

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

@@ -1 +1 @@
-{"version":3,"file":"cache-stats.d.ts","sourceRoot":"","sources":["../../src/core/cache-stats.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEzD;;;GAGG;AACH,eAAO,MAAM,YAAY,QAAgB,CAAC;AAK1C,0DAA0D;AAC1D,MAAM,WAAW,SAAS;IACzB,qFAAqF;IACrF,YAAY,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,UAAU,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,MAAM,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,YAAY,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAC;CAClB;AAED,mFAAmF;AACnF,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE;YAAE,SAAS,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,GAAG,SAAS,CAAC;CACzF;AAmGD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,YAAY,EAAE,EAAE,MAAM,EAAE,gBAAgB,GAAG,gBAAgB,CAErG;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CACjC,OAAO,EAAE,YAAY,EAAE,EACvB,MAAM,EAAE,gBAAgB,GACtB,GAAG,CAAC,gBAAgB,EAAE,SAAS,CAAC,CAElC;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC9B,OAAO,EAAE,YAAY,EAAE,EACvB,OAAO,EAAE,gBAAgB,EACzB,MAAM,EAAE,gBAAgB,GACtB,SAAS,GAAG,SAAS,CAEvB","sourcesContent":["import type { AssistantMessage } from \"@earendil-works/pi-ai\";\nimport type { SessionEntry } from \"./session-manager.ts\";\n\n/**\n * Prompt-cache TTL: idle gaps longer than this are worth mentioning as the\n * likely cause of a miss. Anthropic's default cache TTL is 5 minutes.\n */\nexport const CACHE_TTL_MS = 5 * 60 * 1000;\n\n/** Per-turn misses at or below this are cache breakpoint granularity noise. */\nconst NOISE_FLOOR_TOKENS = 1024;\n\n/** A counted cache miss on a single assistant message. */\nexport interface CacheMiss {\n\t/** Prompt tokens that were in the previous turn's prompt but not read from cache. */\n\tmissedTokens: number;\n\t/** Extra dollars paid vs. a full cache hit; 0 when pricing is unknown. */\n\tmissedCost: number;\n\t/** Milliseconds since the previous request (which last refreshed the cache). */\n\tidleMs: number;\n\t/** True when the model changed relative to the previous request. */\n\tmodelChanged: boolean;\n}\n\nexport interface CacheWasteTotals {\n\tmissedTokens: number;\n\tmissedCost: number;\n\t/** Number of counted misses (turns above the noise floor). */\n\tmissCount: number;\n}\n\n/** Minimal pricing lookup, satisfied by ModelRuntime. Cost is $/million tokens. */\nexport interface ModelPriceSource {\n\tgetModel(provider: string, modelId: string): { cost: { cacheRead: number } } | undefined;\n}\n\n/** The last request seen by the scan; everything in its prompt should be cached. */\ninterface PreviousRequest {\n\tpromptTokens: number;\n\tmodelKey: string;\n\ttimestamp: number;\n\t/**\n\t * Sticky: some earlier request in this scan segment reported cache activity.\n\t * Distinguishes a total miss on a cache-read-only provider (OpenAI-style,\n\t * writes unreported) from a provider that never reports caching at all.\n\t */\n\treportedCache: boolean;\n}\n\n/**\n * Compute the cache miss for one assistant message relative to the previous\n * request. Returns undefined when nothing is counted: first turn, after a\n * reset, no cache activity ever reported (provider without cache support), or\n * miss below the noise floor.\n */\nfunction detectMiss(\n\tprev: PreviousRequest | undefined,\n\tmessage: AssistantMessage,\n\tmodels: ModelPriceSource,\n): CacheMiss | undefined {\n\tconst usage = message.usage;\n\tconst promptTokens = usage.input + usage.cacheRead + usage.cacheWrite;\n\t// A zero-cache turn only counts when cache activity was reported before:\n\t// on cache-read-only providers that is a total miss, while on providers\n\t// that never report caching it means nothing.\n\tif (!prev || promptTokens <= 0 || (usage.cacheRead + usage.cacheWrite === 0 && !prev.reportedCache)) {\n\t\treturn undefined;\n\t}\n\n\tconst missedTokens = Math.min(prev.promptTokens, promptTokens) - usage.cacheRead;\n\tif (missedTokens <= NOISE_FLOOR_TOKENS) return undefined;\n\n\t// Extra cost = missed tokens billed at the actual paid rate (input/cacheWrite,\n\t// incl. write premium) instead of the cache-read rate. Missed tokens can only\n\t// land in the input or cacheWrite buckets, so the paid rate comes straight\n\t// from this message's own cost breakdown.\n\tconst paidTokens = usage.input + usage.cacheWrite;\n\tconst paidPerToken = paidTokens > 0 ? (usage.cost.input + usage.cost.cacheWrite) / paidTokens : 0;\n\tconst readPerToken =\n\t\tusage.cacheRead > 0\n\t\t\t? usage.cost.cacheRead / usage.cacheRead\n\t\t\t: (models.getModel(message.provider, message.model)?.cost.cacheRead ?? 0) / 1_000_000;\n\n\treturn {\n\t\tmissedTokens,\n\t\tmissedCost: missedTokens * Math.max(0, paidPerToken - readPerToken),\n\t\tidleMs: Math.max(0, message.timestamp - prev.timestamp),\n\t\tmodelChanged: `${message.provider}/${message.model}` !== prev.modelKey,\n\t};\n}\n\nfunction asPreviousRequest(message: AssistantMessage, reportedCache: boolean): PreviousRequest | undefined {\n\tconst usage = message.usage;\n\tconst promptTokens = usage.input + usage.cacheRead + usage.cacheWrite;\n\tif (promptTokens <= 0) return undefined;\n\treturn {\n\t\tpromptTokens,\n\t\tmodelKey: `${message.provider}/${message.model}`,\n\t\ttimestamp: message.timestamp,\n\t\treportedCache: reportedCache || usage.cacheRead + usage.cacheWrite > 0,\n\t};\n}\n\nfunction scan(\n\tentries: SessionEntry[],\n\tmodels: ModelPriceSource,\n): { prev: PreviousRequest | undefined; totals: CacheWasteTotals; misses: Map<AssistantMessage, CacheMiss> } {\n\tlet prev: PreviousRequest | undefined;\n\tconst totals: CacheWasteTotals = { missedTokens: 0, missedCost: 0, missCount: 0 };\n\tconst misses = new Map<AssistantMessage, CacheMiss>();\n\n\tfor (const entry of entries) {\n\t\tif (entry.type === \"compaction\" || entry.type === \"branch_summary\") {\n\t\t\t// The context legitimately changed; the next turn's prompt is new content,\n\t\t\t// not re-billed content. Model switches are NOT exempt: they re-bill the\n\t\t\t// full prompt and should be counted.\n\t\t\tprev = undefined;\n\t\t\tcontinue;\n\t\t}\n\t\tif (entry.type === \"message\" && entry.message.role === \"assistant\") {\n\t\t\tconst miss = detectMiss(prev, entry.message, models);\n\t\t\tif (miss) {\n\t\t\t\ttotals.missedTokens += miss.missedTokens;\n\t\t\t\ttotals.missedCost += miss.missedCost;\n\t\t\t\ttotals.missCount += 1;\n\t\t\t\tmisses.set(entry.message, miss);\n\t\t\t}\n\t\t\tprev = asPreviousRequest(entry.message, prev?.reportedCache ?? false) ?? prev;\n\t\t}\n\t}\n\treturn { prev, totals, misses };\n}\n\n/**\n * Cumulative cache waste across a session: prompt tokens that should have been\n * cache reads (they were in the previous turn's prompt) but were re-billed.\n */\nexport function computeCacheWaste(entries: SessionEntry[], models: ModelPriceSource): CacheWasteTotals {\n\treturn scan(entries, models).totals;\n}\n\n/**\n * All counted cache misses across a session, keyed by the assistant message\n * (by reference) that paid for them. Used to re-derive transcript notices when\n * rebuilding the chat from entries (resume, post-compaction rebuild).\n */\nexport function collectCacheMisses(\n\tentries: SessionEntry[],\n\tmodels: ModelPriceSource,\n): Map<AssistantMessage, CacheMiss> {\n\treturn scan(entries, models).misses;\n}\n\n/**\n * Detect a cache miss on a just-completed assistant message.\n * `entries` must not yet contain `message` (message_end fires before persistence).\n */\nexport function detectCacheMiss(\n\tentries: SessionEntry[],\n\tmessage: AssistantMessage,\n\tmodels: ModelPriceSource,\n): CacheMiss | undefined {\n\treturn detectMiss(scan(entries, models).prev, message, models);\n}\n"]}
+{"version":3,"file":"cache-stats.d.ts","sourceRoot":"","sources":["../../src/core/cache-stats.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEzD;;;GAGG;AACH,eAAO,MAAM,YAAY,QAAgB,CAAC;AAK1C,0DAA0D;AAC1D,MAAM,WAAW,SAAS;IACzB,qFAAqF;IACrF,YAAY,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,UAAU,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,MAAM,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,YAAY,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAC;CAClB;AAED,mFAAmF;AACnF,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE;YAAE,SAAS,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,GAAG,SAAS,CAAC;CACzF;AAmGD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,YAAY,EAAE,EAAE,MAAM,EAAE,gBAAgB,GAAG,gBAAgB,CAErG;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CACjC,OAAO,EAAE,YAAY,EAAE,EACvB,MAAM,EAAE,gBAAgB,GACtB,GAAG,CAAC,gBAAgB,EAAE,SAAS,CAAC,CAElC;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC9B,OAAO,EAAE,YAAY,EAAE,EACvB,OAAO,EAAE,gBAAgB,EACzB,MAAM,EAAE,gBAAgB,GACtB,SAAS,GAAG,SAAS,CAEvB"}

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

@@ -1 +1 @@
-{"version":3,"file":"cache-stats.js","sourceRoot":"","sources":["../../src/core/cache-stats.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;AAE1C,+EAA+E;AAC/E,MAAM,kBAAkB,GAAG,IAAI,CAAC;AAuChC;;;;;GAKG;AACH,SAAS,UAAU,CAClB,IAAiC,EACjC,OAAyB,EACzB,MAAwB,EACA;IACxB,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;IAC5B,MAAM,YAAY,GAAG,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,SAAS,GAAG,KAAK,CAAC,UAAU,CAAC;IACtE,yEAAyE;IACzE,wEAAwE;IACxE,8CAA8C;IAC9C,IAAI,CAAC,IAAI,IAAI,YAAY,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,KAAK,CAAC,UAAU,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,EAAE,CAAC;QACrG,OAAO,SAAS,CAAC;IAClB,CAAC;IAED,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,YAAY,EAAE,YAAY,CAAC,GAAG,KAAK,CAAC,SAAS,CAAC;IACjF,IAAI,YAAY,IAAI,kBAAkB;QAAE,OAAO,SAAS,CAAC;IAEzD,+EAA+E;IAC/E,8EAA8E;IAC9E,2EAA2E;IAC3E,0CAA0C;IAC1C,MAAM,UAAU,GAAG,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,UAAU,CAAC;IAClD,MAAM,YAAY,GAAG,UAAU,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;IAClG,MAAM,YAAY,GACjB,KAAK,CAAC,SAAS,GAAG,CAAC;QAClB,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC,SAAS;QACxC,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,SAAS,IAAI,CAAC,CAAC,GAAG,SAAS,CAAC;IAExF,OAAO;QACN,YAAY;QACZ,UAAU,EAAE,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,YAAY,GAAG,YAAY,CAAC;QACnE,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;QACvD,YAAY,EAAE,GAAG,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,KAAK,EAAE,KAAK,IAAI,CAAC,QAAQ;KACtE,CAAC;AAAA,CACF;AAED,SAAS,iBAAiB,CAAC,OAAyB,EAAE,aAAsB,EAA+B;IAC1G,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;IAC5B,MAAM,YAAY,GAAG,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,SAAS,GAAG,KAAK,CAAC,UAAU,CAAC;IACtE,IAAI,YAAY,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC;IACxC,OAAO;QACN,YAAY;QACZ,QAAQ,EAAE,GAAG,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,KAAK,EAAE;QAChD,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,aAAa,EAAE,aAAa,IAAI,KAAK,CAAC,SAAS,GAAG,KAAK,CAAC,UAAU,GAAG,CAAC;KACtE,CAAC;AAAA,CACF;AAED,SAAS,IAAI,CACZ,OAAuB,EACvB,MAAwB,EACoF;IAC5G,IAAI,IAAiC,CAAC;IACtC,MAAM,MAAM,GAAqB,EAAE,YAAY,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC;IAClF,MAAM,MAAM,GAAG,IAAI,GAAG,EAA+B,CAAC;IAEtD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,IAAI,KAAK,CAAC,IAAI,KAAK,gBAAgB,EAAE,CAAC;YACpE,2EAA2E;YAC3E,yEAAyE;YACzE,qCAAqC;YACrC,IAAI,GAAG,SAAS,CAAC;YACjB,SAAS;QACV,CAAC;QACD,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;YACpE,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,EAAE,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;YACrD,IAAI,IAAI,EAAE,CAAC;gBACV,MAAM,CAAC,YAAY,IAAI,IAAI,CAAC,YAAY,CAAC;gBACzC,MAAM,CAAC,UAAU,IAAI,IAAI,CAAC,UAAU,CAAC;gBACrC,MAAM,CAAC,SAAS,IAAI,CAAC,CAAC;gBACtB,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;YACjC,CAAC;YACD,IAAI,GAAG,iBAAiB,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,aAAa,IAAI,KAAK,CAAC,IAAI,IAAI,CAAC;QAC/E,CAAC;IACF,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;AAAA,CAChC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAuB,EAAE,MAAwB,EAAoB;IACtG,OAAO,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC;AAAA,CACpC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CACjC,OAAuB,EACvB,MAAwB,EACW;IACnC,OAAO,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC;AAAA,CACpC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC9B,OAAuB,EACvB,OAAyB,EACzB,MAAwB,EACA;IACxB,OAAO,UAAU,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;AAAA,CAC/D","sourcesContent":["import type { AssistantMessage } from \"@earendil-works/pi-ai\";\nimport type { SessionEntry } from \"./session-manager.ts\";\n\n/**\n * Prompt-cache TTL: idle gaps longer than this are worth mentioning as the\n * likely cause of a miss. Anthropic's default cache TTL is 5 minutes.\n */\nexport const CACHE_TTL_MS = 5 * 60 * 1000;\n\n/** Per-turn misses at or below this are cache breakpoint granularity noise. */\nconst NOISE_FLOOR_TOKENS = 1024;\n\n/** A counted cache miss on a single assistant message. */\nexport interface CacheMiss {\n\t/** Prompt tokens that were in the previous turn's prompt but not read from cache. */\n\tmissedTokens: number;\n\t/** Extra dollars paid vs. a full cache hit; 0 when pricing is unknown. */\n\tmissedCost: number;\n\t/** Milliseconds since the previous request (which last refreshed the cache). */\n\tidleMs: number;\n\t/** True when the model changed relative to the previous request. */\n\tmodelChanged: boolean;\n}\n\nexport interface CacheWasteTotals {\n\tmissedTokens: number;\n\tmissedCost: number;\n\t/** Number of counted misses (turns above the noise floor). */\n\tmissCount: number;\n}\n\n/** Minimal pricing lookup, satisfied by ModelRuntime. Cost is $/million tokens. */\nexport interface ModelPriceSource {\n\tgetModel(provider: string, modelId: string): { cost: { cacheRead: number } } | undefined;\n}\n\n/** The last request seen by the scan; everything in its prompt should be cached. */\ninterface PreviousRequest {\n\tpromptTokens: number;\n\tmodelKey: string;\n\ttimestamp: number;\n\t/**\n\t * Sticky: some earlier request in this scan segment reported cache activity.\n\t * Distinguishes a total miss on a cache-read-only provider (OpenAI-style,\n\t * writes unreported) from a provider that never reports caching at all.\n\t */\n\treportedCache: boolean;\n}\n\n/**\n * Compute the cache miss for one assistant message relative to the previous\n * request. Returns undefined when nothing is counted: first turn, after a\n * reset, no cache activity ever reported (provider without cache support), or\n * miss below the noise floor.\n */\nfunction detectMiss(\n\tprev: PreviousRequest | undefined,\n\tmessage: AssistantMessage,\n\tmodels: ModelPriceSource,\n): CacheMiss | undefined {\n\tconst usage = message.usage;\n\tconst promptTokens = usage.input + usage.cacheRead + usage.cacheWrite;\n\t// A zero-cache turn only counts when cache activity was reported before:\n\t// on cache-read-only providers that is a total miss, while on providers\n\t// that never report caching it means nothing.\n\tif (!prev || promptTokens <= 0 || (usage.cacheRead + usage.cacheWrite === 0 && !prev.reportedCache)) {\n\t\treturn undefined;\n\t}\n\n\tconst missedTokens = Math.min(prev.promptTokens, promptTokens) - usage.cacheRead;\n\tif (missedTokens <= NOISE_FLOOR_TOKENS) return undefined;\n\n\t// Extra cost = missed tokens billed at the actual paid rate (input/cacheWrite,\n\t// incl. write premium) instead of the cache-read rate. Missed tokens can only\n\t// land in the input or cacheWrite buckets, so the paid rate comes straight\n\t// from this message's own cost breakdown.\n\tconst paidTokens = usage.input + usage.cacheWrite;\n\tconst paidPerToken = paidTokens > 0 ? (usage.cost.input + usage.cost.cacheWrite) / paidTokens : 0;\n\tconst readPerToken =\n\t\tusage.cacheRead > 0\n\t\t\t? usage.cost.cacheRead / usage.cacheRead\n\t\t\t: (models.getModel(message.provider, message.model)?.cost.cacheRead ?? 0) / 1_000_000;\n\n\treturn {\n\t\tmissedTokens,\n\t\tmissedCost: missedTokens * Math.max(0, paidPerToken - readPerToken),\n\t\tidleMs: Math.max(0, message.timestamp - prev.timestamp),\n\t\tmodelChanged: `${message.provider}/${message.model}` !== prev.modelKey,\n\t};\n}\n\nfunction asPreviousRequest(message: AssistantMessage, reportedCache: boolean): PreviousRequest | undefined {\n\tconst usage = message.usage;\n\tconst promptTokens = usage.input + usage.cacheRead + usage.cacheWrite;\n\tif (promptTokens <= 0) return undefined;\n\treturn {\n\t\tpromptTokens,\n\t\tmodelKey: `${message.provider}/${message.model}`,\n\t\ttimestamp: message.timestamp,\n\t\treportedCache: reportedCache || usage.cacheRead + usage.cacheWrite > 0,\n\t};\n}\n\nfunction scan(\n\tentries: SessionEntry[],\n\tmodels: ModelPriceSource,\n): { prev: PreviousRequest | undefined; totals: CacheWasteTotals; misses: Map<AssistantMessage, CacheMiss> } {\n\tlet prev: PreviousRequest | undefined;\n\tconst totals: CacheWasteTotals = { missedTokens: 0, missedCost: 0, missCount: 0 };\n\tconst misses = new Map<AssistantMessage, CacheMiss>();\n\n\tfor (const entry of entries) {\n\t\tif (entry.type === \"compaction\" || entry.type === \"branch_summary\") {\n\t\t\t// The context legitimately changed; the next turn's prompt is new content,\n\t\t\t// not re-billed content. Model switches are NOT exempt: they re-bill the\n\t\t\t// full prompt and should be counted.\n\t\t\tprev = undefined;\n\t\t\tcontinue;\n\t\t}\n\t\tif (entry.type === \"message\" && entry.message.role === \"assistant\") {\n\t\t\tconst miss = detectMiss(prev, entry.message, models);\n\t\t\tif (miss) {\n\t\t\t\ttotals.missedTokens += miss.missedTokens;\n\t\t\t\ttotals.missedCost += miss.missedCost;\n\t\t\t\ttotals.missCount += 1;\n\t\t\t\tmisses.set(entry.message, miss);\n\t\t\t}\n\t\t\tprev = asPreviousRequest(entry.message, prev?.reportedCache ?? false) ?? prev;\n\t\t}\n\t}\n\treturn { prev, totals, misses };\n}\n\n/**\n * Cumulative cache waste across a session: prompt tokens that should have been\n * cache reads (they were in the previous turn's prompt) but were re-billed.\n */\nexport function computeCacheWaste(entries: SessionEntry[], models: ModelPriceSource): CacheWasteTotals {\n\treturn scan(entries, models).totals;\n}\n\n/**\n * All counted cache misses across a session, keyed by the assistant message\n * (by reference) that paid for them. Used to re-derive transcript notices when\n * rebuilding the chat from entries (resume, post-compaction rebuild).\n */\nexport function collectCacheMisses(\n\tentries: SessionEntry[],\n\tmodels: ModelPriceSource,\n): Map<AssistantMessage, CacheMiss> {\n\treturn scan(entries, models).misses;\n}\n\n/**\n * Detect a cache miss on a just-completed assistant message.\n * `entries` must not yet contain `message` (message_end fires before persistence).\n */\nexport function detectCacheMiss(\n\tentries: SessionEntry[],\n\tmessage: AssistantMessage,\n\tmodels: ModelPriceSource,\n): CacheMiss | undefined {\n\treturn detectMiss(scan(entries, models).prev, message, models);\n}\n"]}
+{"version":3,"file":"cache-stats.js","sourceRoot":"","sources":["../../src/core/cache-stats.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;AAE1C,+EAA+E;AAC/E,MAAM,kBAAkB,GAAG,IAAI,CAAC;AAuChC;;;;;GAKG;AACH,SAAS,UAAU,CAClB,IAAiC,EACjC,OAAyB,EACzB,MAAwB;IAExB,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;IAC5B,MAAM,YAAY,GAAG,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,SAAS,GAAG,KAAK,CAAC,UAAU,CAAC;IACtE,yEAAyE;IACzE,wEAAwE;IACxE,8CAA8C;IAC9C,IAAI,CAAC,IAAI,IAAI,YAAY,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,KAAK,CAAC,UAAU,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,EAAE,CAAC;QACrG,OAAO,SAAS,CAAC;IAClB,CAAC;IAED,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,YAAY,EAAE,YAAY,CAAC,GAAG,KAAK,CAAC,SAAS,CAAC;IACjF,IAAI,YAAY,IAAI,kBAAkB;QAAE,OAAO,SAAS,CAAC;IAEzD,+EAA+E;IAC/E,8EAA8E;IAC9E,2EAA2E;IAC3E,0CAA0C;IAC1C,MAAM,UAAU,GAAG,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,UAAU,CAAC;IAClD,MAAM,YAAY,GAAG,UAAU,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;IAClG,MAAM,YAAY,GACjB,KAAK,CAAC,SAAS,GAAG,CAAC;QAClB,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC,SAAS;QACxC,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,SAAS,IAAI,CAAC,CAAC,GAAG,SAAS,CAAC;IAExF,OAAO;QACN,YAAY;QACZ,UAAU,EAAE,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,YAAY,GAAG,YAAY,CAAC;QACnE,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;QACvD,YAAY,EAAE,GAAG,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,KAAK,EAAE,KAAK,IAAI,CAAC,QAAQ;KACtE,CAAC;AACH,CAAC;AAED,SAAS,iBAAiB,CAAC,OAAyB,EAAE,aAAsB;IAC3E,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;IAC5B,MAAM,YAAY,GAAG,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,SAAS,GAAG,KAAK,CAAC,UAAU,CAAC;IACtE,IAAI,YAAY,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC;IACxC,OAAO;QACN,YAAY;QACZ,QAAQ,EAAE,GAAG,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,KAAK,EAAE;QAChD,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,aAAa,EAAE,aAAa,IAAI,KAAK,CAAC,SAAS,GAAG,KAAK,CAAC,UAAU,GAAG,CAAC;KACtE,CAAC;AACH,CAAC;AAED,SAAS,IAAI,CACZ,OAAuB,EACvB,MAAwB;IAExB,IAAI,IAAiC,CAAC;IACtC,MAAM,MAAM,GAAqB,EAAE,YAAY,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC;IAClF,MAAM,MAAM,GAAG,IAAI,GAAG,EAA+B,CAAC;IAEtD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,IAAI,KAAK,CAAC,IAAI,KAAK,gBAAgB,EAAE,CAAC;YACpE,2EAA2E;YAC3E,yEAAyE;YACzE,qCAAqC;YACrC,IAAI,GAAG,SAAS,CAAC;YACjB,SAAS;QACV,CAAC;QACD,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;YACpE,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,EAAE,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;YACrD,IAAI,IAAI,EAAE,CAAC;gBACV,MAAM,CAAC,YAAY,IAAI,IAAI,CAAC,YAAY,CAAC;gBACzC,MAAM,CAAC,UAAU,IAAI,IAAI,CAAC,UAAU,CAAC;gBACrC,MAAM,CAAC,SAAS,IAAI,CAAC,CAAC;gBACtB,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;YACjC,CAAC;YACD,IAAI,GAAG,iBAAiB,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,aAAa,IAAI,KAAK,CAAC,IAAI,IAAI,CAAC;QAC/E,CAAC;IACF,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;AACjC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAuB,EAAE,MAAwB;IAClF,OAAO,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC;AACrC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CACjC,OAAuB,EACvB,MAAwB;IAExB,OAAO,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC;AACrC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC9B,OAAuB,EACvB,OAAyB,EACzB,MAAwB;IAExB,OAAO,UAAU,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;AAChE,CAAC"}

package/dist/core/capability/capability.test.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Tests del capability registry multi-origen (B01).
+ *
+ * Valida el contrato central: providers priorizados con dedup first-wins,
+ * y las tres semánticas que lo hacen útil en la práctica:
+ * filter (no reclama clave) vs suppress (sí reclama, ensombrece) vs
+ * equivalent (dedup semántico entre claves distintas), más validación
+ * post-dedup. Cada test tiene su mitad que distingue (el mismo setup con la
+ * variante contraria) para que un verde no sea por comparar dos vacíos.
+ */
+export {};
+//# sourceMappingURL=capability.test.d.ts.map

package/dist/core/capability/capability.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability.test.d.ts","sourceRoot":"","sources":["../../../src/core/capability/capability.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/dist/core/capability/capability.test.js

@@ -0,0 +1,258 @@
+/**
+ * Tests del capability registry multi-origen (B01).
+ *
+ * Valida el contrato central: providers priorizados con dedup first-wins,
+ * y las tres semánticas que lo hacen útil en la práctica:
+ * filter (no reclama clave) vs suppress (sí reclama, ensombrece) vs
+ * equivalent (dedup semántico entre claves distintas), más validación
+ * post-dedup. Cada test tiene su mitad que distingue (el mismo setup con la
+ * variante contraria) para que un verde no sea por comparar dos vacíos.
+ */
+import { describe, expect, it } from "vitest";
+import { clearRegistryForTesting, defineCapability, loadCapabilities, loadCapability, registerProvider, } from "./index.js";
+function source(provider, filePath, level = "project") {
+    return { provider, providerName: provider, path: filePath, level };
+}
+function ctx() {
+    return { cwd: "/tmp/proj", home: "/home/test", repoRoot: "/tmp" };
+}
+function provider(id, priority, items, opts = {}) {
+    return {
+        id,
+        displayName: id,
+        description: `provider ${id}`,
+        priority,
+        async load() {
+            if (opts.fail)
+                throw new Error(`fail ${id}`);
+            return { items, warnings: opts.warnings };
+        },
+    };
+}
+describe("capability registry — B01", () => {
+    it("dedup first-wins: a igualdad de clave gana el de mayor prioridad", async () => {
+        const cap = {
+            id: "test",
+            displayName: "Test",
+            description: "test",
+            key: (it) => it.name,
+        };
+        const low = {
+            name: "shared",
+            value: "from-low",
+            _source: source("low", "/tmp/low.json", "user"),
+        };
+        const high = {
+            name: "shared",
+            value: "from-high",
+            _source: source("high", "/tmp/high.json", "project"),
+        };
+        // Providers desordenados a propósito: el registry debe reordenar por priority.
+        const result = await loadCapabilities(cap, [provider("low", 10, [low]), provider("high", 100, [high])], ctx());
+        expect(result.items).toHaveLength(1);
+        expect(result.items[0].value).toBe("from-high");
+        expect(result.items[0]._source.provider).toBe("high");
+        // El duplicado queda en `all` marcado como shadowed.
+        expect(result.all).toHaveLength(2);
+        expect(result.all.find((i) => i.value === "from-low")?._shadowed).toBe(true);
+    });
+    it("prioridad: respeta orden descendente aunque los providers lleguen al revés", async () => {
+        const cap = {
+            id: "prio",
+            displayName: "Prio",
+            description: "test",
+            key: (it) => it.name,
+        };
+        const a = { name: "a", value: "a-low", _source: source("low", "/a.json") };
+        const b = { name: "b", value: "b-mid", _source: source("mid", "/b.json") };
+        const c = { name: "c", value: "c-high", _source: source("high", "/c.json") };
+        const result = await loadCapabilities(cap, [provider("low", 1, [a]), provider("high", 100, [c]), provider("mid", 50, [b])], ctx());
+        // Todos con claves distintas: sobreviven los tres, pero en orden de prioridad.
+        expect(result.items.map((i) => i.name)).toEqual(["c", "b", "a"]);
+        expect(result.providers).toEqual(["high", "mid", "low"]);
+    });
+    it("filter: item filtrado no reclama clave — homónimo de menor prioridad sí sobrevive", async () => {
+        const cap = {
+            id: "filter-test",
+            displayName: "Filter",
+            description: "test",
+            key: (it) => it.name,
+        };
+        const high = {
+            name: "shared",
+            value: "high-filtered",
+            _source: source("high", "/high.json"),
+        };
+        const low = {
+            name: "shared",
+            value: "low-survives",
+            _source: source("low", "/low.json"),
+        };
+        const result = await loadCapabilities(cap, [provider("high", 100, [high]), provider("low", 10, [low])], ctx(), {
+            filter: (item) => item.value !== "high-filtered",
+        });
+        expect(result.items).toHaveLength(1);
+        expect(result.items[0].value).toBe("low-survives");
+        // El filtrado no está en `all` (como si nunca hubiera existido).
+        expect(result.all).toHaveLength(1);
+        expect(result.all[0].value).toBe("low-survives");
+    });
+    it("suppress: item suprimido SÍ reclama clave y ensombrece homónimo de menor prioridad", async () => {
+        const cap = {
+            id: "suppress-test",
+            displayName: "Suppress",
+            description: "test",
+            key: (it) => it.name,
+        };
+        const high = {
+            name: "shared",
+            value: "high-suppressed",
+            _source: source("high", "/high.json"),
+        };
+        const low = {
+            name: "shared",
+            value: "low-shadowed",
+            _source: source("low", "/low.json"),
+        };
+        const result = await loadCapabilities(cap, [provider("high", 100, [high]), provider("low", 10, [low])], ctx(), {
+            suppress: (item) => item.value === "high-suppressed",
+        });
+        // Ninguno sobrevive: el de proyecto suprimido ensombrece al de usuario.
+        expect(result.items).toHaveLength(0);
+        // El suprimido no se expone en `all` (igual que omp), el low queda como shadowed.
+        expect(result.all).toHaveLength(1);
+        expect(result.all[0].value).toBe("low-shadowed");
+        expect(result.all[0]._shadowed).toBe(true);
+    });
+    it("suppress no hace equivalence-shadow a survivor con clave distinta", async () => {
+        const cap = {
+            id: "mcp",
+            displayName: "MCP",
+            description: "test",
+            key: (it) => it.name,
+            equivalent: (a, b) => a.url === b.url,
+        };
+        const suppressed = {
+            name: "alias",
+            url: "https://example.com",
+            _source: source("high", "/high.json"),
+        };
+        const survivor = {
+            name: "real",
+            url: "https://example.com",
+            _source: source("low", "/low.json"),
+        };
+        const result = await loadCapabilities(cap, [provider("high", 100, [suppressed]), provider("low", 10, [survivor])], ctx(), {
+            suppress: (item) => {
+                const typed = item;
+                return typed.name === "alias";
+            },
+        });
+        // El suprimido reclama "alias" pero no "real", y no equivalence-shadowea.
+        expect(result.items).toHaveLength(1);
+        expect(result.items[0].name).toBe("real");
+    });
+    it("equivalent: dos claves distintas pero conectivamente iguales — solo el primero sobrevive", async () => {
+        const cap = {
+            id: "mcp-equiv",
+            displayName: "MCP",
+            description: "test",
+            key: (it) => it.name,
+            equivalent: (a, b) => a.url === b.url,
+        };
+        const first = {
+            name: "server-a",
+            url: "https://api.example.com",
+            _source: source("high", "/high.json"),
+        };
+        const second = {
+            name: "server-b",
+            url: "https://api.example.com",
+            _source: source("low", "/low.json"),
+        };
+        const result = await loadCapabilities(cap, [provider("high", 100, [first]), provider("low", 10, [second])], ctx());
+        expect(result.items).toHaveLength(1);
+        expect(result.items[0].name).toBe("server-a");
+        expect(result.all.find((i) => i.name === "server-b")?._shadowed).toBe(true);
+    });
+    it("key undefined: nunca deduplicar — todos sobreviven aunque compartan contenido", async () => {
+        const cap = {
+            id: "no-dedup",
+            displayName: "NoDedup",
+            description: "test",
+            key: () => undefined,
+        };
+        const a = { name: "x", value: "v", _source: source("p1", "/a.json") };
+        const b = { name: "x", value: "v", _source: source("p2", "/b.json") };
+        const result = await loadCapabilities(cap, [provider("p1", 100, [a]), provider("p2", 10, [b])], ctx());
+        expect(result.items).toHaveLength(2);
+    });
+    it("validación post-dedup: inválidos se descartan con warning y sin abortar", async () => {
+        const cap = {
+            id: "validate",
+            displayName: "Validate",
+            description: "test",
+            key: (it) => it.name,
+            validate: (it) => (it.value === "bad" ? "value no puede ser 'bad'" : undefined),
+        };
+        const good = { name: "ok", value: "good", _source: source("p1", "/ok.json") };
+        const bad = { name: "bad", value: "bad", _source: source("p1", "/bad.json") };
+        const result = await loadCapabilities(cap, [provider("p1", 100, [good, bad])], ctx());
+        expect(result.items).toHaveLength(1);
+        expect(result.items[0].name).toBe("ok");
+        expect(result.warnings.some((w) => w.includes("bad"))).toBe(true);
+        // Con includeInvalid, el inválido sí sobrevive.
+        const withInvalid = await loadCapabilities(cap, [provider("p1", 100, [good, bad])], ctx(), {
+            includeInvalid: true,
+        });
+        expect(withInvalid.items).toHaveLength(2);
+    });
+    it("un provider que falla no aborta la carga de los demás (warning y sigue)", async () => {
+        const cap = {
+            id: "resilient",
+            displayName: "Resilient",
+            description: "test",
+            key: (it) => it.name,
+        };
+        const good = { name: "ok", value: "fine", _source: source("good", "/good.json") };
+        const result = await loadCapabilities(cap, [
+            provider("bad", 100, [], { fail: true }),
+            provider("good", 10, [good]),
+        ], ctx());
+        expect(result.items).toHaveLength(1);
+        expect(result.items[0].value).toBe("fine");
+        expect(result.warnings.some((w) => w.includes("bad"))).toBe(true);
+    });
+    it("warnings de providers se agregan y se prefijan con el displayName", async () => {
+        const cap = {
+            id: "warnings",
+            displayName: "Warnings",
+            description: "test",
+            key: (it) => it.name,
+        };
+        const item = { name: "x", value: "v", _source: source("p1", "/x.json") };
+        const result = await loadCapabilities(cap, [provider("p1", 10, [item], { warnings: ["algo raro"] })], ctx());
+        expect(result.warnings.some((w) => w.includes("[p1]") && w.includes("algo raro"))).toBe(true);
+    });
+    it("registro global: defineCapability + registerProvider + loadCapability", async () => {
+        clearRegistryForTesting();
+        const cap = {
+            id: "reg-test",
+            displayName: "Reg",
+            description: "test",
+            key: (it) => it.name,
+        };
+        defineCapability(cap);
+        const item = {
+            name: "hello",
+            value: "world",
+            _source: source("native", "/native.json"),
+        };
+        registerProvider("reg-test", provider("native", 100, [item]));
+        const result = await loadCapability("reg-test", { ctx: ctx() });
+        expect(result.items).toHaveLength(1);
+        expect(result.items[0].name).toBe("hello");
+        clearRegistryForTesting();
+    });
+});
+//# sourceMappingURL=capability.test.js.map