changebook 0.7.0 → 0.8.0

package/dist/toolUsage.js

@@ -0,0 +1,128 @@
+/**
+ * `atlas_usage`: coste, ahorro y valor de las consultas al atlas.
+ *
+ * PORTADA DEL HOSPEDADO EL 09/08. Nació allí de una pregunta de Raúl el
+ * 2026-07-18: «¿cuánto llevamos gastado / ahorrado?» era incontestable para
+ * cualquier agente, porque el dato solo vivía detrás de la sesión web. Las
+ * preguntas de dinero son preguntas de fundador; el atlas tiene que
+ * responderlas.
+ *
+ * NIVEL DE CUENTA, NO DE PROYECTO: la facturación es por cuenta, así que esta
+ * herramienta NO lleva `project`. Es la única del servidor que no lo lleva, y
+ * es a propósito.
+ */
+import { z } from "zod";
+import { recordRead } from "./agregados.js";
+import { RO, errorResult, servedCharsOf, toolResult, } from "./respuestas.js";
+import { fmtUsd, latencyByTool, summarizeUsage, } from "./usage.js";
+/**
+ * Tope de filas por consulta de PostgREST. Se pagina hasta agotarlo y se AVISA
+ * si se alcanzó: un truncamiento leído como total convierte «has ahorrado $X»
+ * en una cifra que nadie puede auditar (AUD-C9). El techo de 20 páginas es un
+ * cortafuegos, no un limite de negocio — al alcanzarlo se marca truncado.
+ */
+const PAGINA = 1000;
+const MAX_PAGINAS = 20;
+async function paginar(db, tabla, query, orden) {
+    const filas = [];
+    for (let i = 0; i < MAX_PAGINAS; i += 1) {
+        const page = await db.rest(`${tabla}?${query}&order=${orden}&limit=${PAGINA}&offset=${i * PAGINA}`);
+        filas.push(...page);
+        if (page.length < PAGINA)
+            return { filas, truncado: false };
+    }
+    return { filas, truncado: true };
+}
+export function registrarUsage(server, db) {
+    server.registerTool("atlas_usage", {
+        title: "Cost, savings and consultation value",
+        description: "Account-level usage summary: what the owner paid for analyses this period, what ChangeBook's optimizations avoided (compression, prompt cache, Batch API, model routing, dedup skips) and how much agents consulted the atlas (with a conservative exploration-avoided estimate). Use when the owner asks about spend, savings, cost or usage. Args: period 'month' (default) or 'all'.",
+        inputSchema: { period: z.enum(["month", "all"]).default("month") },
+        annotations: RO,
+    }, async ({ period }) => {
+        const t0 = Date.now();
+        try {
+            const now = new Date();
+            const since = period === "month"
+                ? new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 1)).toISOString()
+                : "1970-01-01T00:00:00Z";
+            const [ledgerP, skipsP, readsP, rolledUpP] = await Promise.all([
+                paginar(db, "usage_ledger", `select=model,action,input_tokens,output_tokens,cache_creation_input_tokens,cache_read_input_tokens,diff_chars,raw_diff_chars&created_at=gte.${since}`, "id.asc"),
+                paginar(db, "analysis_skips", `select=id&created_at=gte.${since}`, "id.asc").catch(() => ({ filas: [], truncado: false })),
+                paginar(db, "atlas_reads", `select=chars_served,source,tool,latency_ms&created_at=gte.${since}`, "id.asc").catch(() => ({ filas: [], truncado: false })),
+                // El resumen mensual de lo ya purgado. Sin esto, «all time» empezaría
+                // a significar «el último año» en cuanto la purga se llevara el primer
+                // mes, sin dejar de llamarse total (QA 2026-07-19). En period=month no
+                // aporta nada: el mes en curso nunca está purgado.
+                period === "all"
+                    ? paginar(db, "atlas_reads_monthly", "select=reads,chars_served", "month.asc").catch(() => ({ filas: [], truncado: false }))
+                    : Promise.resolve({ filas: [], truncado: false }),
+            ]);
+            const ledger = ledgerP.filas;
+            const reads = readsP.filas;
+            const rolledUp = rolledUpP.filas;
+            // SI CUALQUIERA SE TRUNCÓ, todo lo de abajo es un SUELO. Se dice en la
+            // salida en vez de servir la cifra a secas: quien lee «has ahorrado $X»
+            // tiene derecho a saber si eso es X o «al menos X».
+            const truncado = ledgerP.truncado ||
+                skipsP.truncado ||
+                readsP.truncado ||
+                rolledUpP.truncado;
+            // Los caracteres del guardián quedan FUERA de la estimación de
+            // exploración evitada: su contrafáctico es otro (evita un error, no una
+            // lectura). El resumen mensual ya viene guardado con esa exclusión.
+            const readsChars = reads
+                .filter((r) => r.source !== "guard")
+                .reduce((a, r) => a + (r.chars_served ?? 0), 0) +
+                rolledUp.reduce((a, r) => a + (r.chars_served ?? 0), 0);
+            const readsCount = reads.length + rolledUp.reduce((a, r) => a + (r.reads ?? 0), 0);
+            const u = summarizeUsage(ledger, skipsP.filas.length, readsCount, readsChars);
+            const naive = u.realCost + u.savedTotal;
+            const pct = naive > 0 ? Math.round((u.savedTotal / naive) * 100) : 0;
+            const lines = [
+                `# ChangeBook usage (${period === "month" ? "this month" : "all time"})`,
+                "",
+                ...(truncado
+                    ? [
+                        `> **These numbers are a FLOOR, not a total.** The usage tables for this period exceeded the read cap, so some rows were not counted. Every figure below is at least this much, possibly more.`,
+                        "",
+                    ]
+                    : []),
+                `- Analyses paid: ${u.analyses} → ${fmtUsd(u.realCost)}`,
+                `- Avoided by optimizations: ${fmtUsd(u.savedTotal)} (${pct}% of the naive cost ${fmtUsd(naive)})`,
+                `  - Dedup skips (${u.skipsCount}): ${fmtUsd(u.saved.skips)}`,
+                `  - Batch API: ${fmtUsd(u.saved.batch)}`,
+                `  - Model routing: ${fmtUsd(u.saved.routing)}`,
+                `  - Prompt cache: ${fmtUsd(u.saved.cache)}`,
+                `  - Diff compression: ${fmtUsd(u.saved.compression)}`,
+                `- Agent consultations: ${u.reads.count} (≈${Math.round(u.reads.chars / 4)} tokens served; estimated exploration avoided ${fmtUsd(u.reads.explorationEstimate)} — conservative estimate, kept OUT of the hard savings above)`,
+            ];
+            const latency = latencyByTool(reads);
+            if (latency.length > 0) {
+                lines.push(`- Read latency by tool (server-side, ms):`);
+                for (const t of latency) {
+                    lines.push(`  - ${t.tool}: p50 ${t.p50_ms} · p95 ${t.p95_ms} (n=${t.n})`);
+                }
+            }
+            const salida = toolResult(lines.join("\n"), {
+                period,
+                // Que el consumidor programático también pueda distinguir un total de
+                // un suelo: si esto solo saliera en la prosa, cualquier panel que lea
+                // el JSON volvería a publicar la cifra truncada como exacta.
+                truncated: truncado,
+                analyses: u.analyses,
+                real_cost_usd: u.realCost,
+                saved_usd: u.saved,
+                saved_total_usd: u.savedTotal,
+                reads: u.reads,
+                latency_by_tool: latency,
+            });
+            recordRead(db, "atlas_usage", "", servedCharsOf(salida), Date.now() - t0);
+            return salida;
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+}
+//# sourceMappingURL=toolUsage.js.map