@echomem/mcp 1.4.18 → 1.4.19

package/dist/hud/efficiency.js

@@ -0,0 +1,447 @@
+import crypto from "node:crypto";
+import { adapters } from "./adapters.js";
+import { readJsonl } from "./fs.js";
+import { formatTokens, shellRead } from "./metric.js";
+const RULES = [
+    "repeated_file_read",
+    "repeated_git_output",
+    "repeated_search_output",
+    "compaction_rediscovery",
+    "aborted_or_limit_ended_turn",
+];
+const SEARCH_BINS = new Set(["rg", "grep", "find"]);
+export function runEfficiencyReport(flags = {}) {
+    const session = typeof flags.session === "string" ? flags.session : adapters.codex.findActive();
+    if (!session)
+        throw new Error("No active Codex session found.");
+    return analyzeCodexEfficiency(session);
+}
+export function analyzeCodexEfficiency(file) {
+    const turns = new Map();
+    const calls = new Map();
+    const readHist = new Map();
+    const editTurn = new Map();
+    const gitOutputs = new Map();
+    const searchOutputs = new Map();
+    const seenBeforeCompaction = new Set();
+    const chargedCalls = new Set();
+    const abortedTurns = new Map();
+    let turn = 0;
+    let lastCompactionTurn = -1;
+    for (const record of readJsonl(file)) {
+        const top = isRecord(record) ? record : {};
+        const payload = isRecord(top.payload) ? top.payload : {};
+        const payloadType = typeof payload.type === "string" ? payload.type : "";
+        if (payloadType === "task_started") {
+            turn += 1;
+            ensureTurn(turns, turn);
+        }
+        else if (payloadType === "token_count") {
+            const info = isRecord(payload.info) ? payload.info : {};
+            const last = isRecord(info.last_token_usage) ? info.last_token_usage : {};
+            const inputTokens = readNumber(last.input_tokens);
+            if (inputTokens > 0) {
+                const row = ensureTurn(turns, turn);
+                row.contextTokens = Math.max(row.contextTokens, inputTokens);
+            }
+        }
+        else if (payloadType === "function_call") {
+            const meta = callMeta(payload, turn);
+            if (meta)
+                calls.set(meta.id, meta);
+        }
+        else if (payloadType === "function_call_output") {
+            const callId = typeof payload.call_id === "string" ? payload.call_id : "";
+            const meta = calls.get(callId);
+            if (!meta)
+                continue;
+            const output = typeof payload.output === "string" ? payload.output : JSON.stringify(payload.output || "");
+            processOutput({
+                turns,
+                call: meta,
+                output,
+                readHist,
+                editTurn,
+                gitOutputs,
+                searchOutputs,
+                seenBeforeCompaction,
+                chargedCalls,
+                lastCompactionTurn,
+            });
+        }
+        else if (payloadType === "patch_apply_end") {
+            const changes = isRecord(payload.changes) ? payload.changes : {};
+            for (const changed of Object.keys(changes))
+                editTurn.set(changed, turn);
+        }
+        else if (payloadType === "context_compacted" || top.type === "compacted") {
+            lastCompactionTurn = turn;
+            seenBeforeCompaction.clear();
+            for (const filePath of readHist.keys())
+                seenBeforeCompaction.add(`read:${filePath}`);
+            for (const query of searchOutputs.keys())
+                seenBeforeCompaction.add(`search:${query}`);
+            for (const query of gitOutputs.keys())
+                seenBeforeCompaction.add(`git:${query}`);
+        }
+        else if (payloadType === "agent_message") {
+            const message = typeof payload.message === "string" ? payload.message : "";
+            if (isAbortOrLimitMessage(message))
+                abortedTurns.set(turn, abortLabel(message));
+        }
+        else if (payloadType === "message") {
+            const message = messageText(payload);
+            const phase = typeof payload.phase === "string" ? payload.phase : "";
+            if (phase === "final_answer" && isAbortOrLimitMessage(message))
+                abortedTurns.set(turn, abortLabel(message));
+        }
+    }
+    const rows = [...turns.values()].filter((row) => row.turn > 0).sort((a, b) => a.turn - b.turn);
+    for (const row of rows)
+        addAbortedTurnWaste(row, abortedTurns.get(row.turn));
+    finalizeRows(rows);
+    const totals = sumTotals(rows);
+    return {
+        client: "codex",
+        sourcePath: file,
+        basis: "deterministic-resident-lower-bound-v1",
+        turns: rows,
+        totals,
+        generatedAt: new Date().toISOString(),
+    };
+}
+export function renderEfficiencyReportText(report) {
+    const noisy = report.turns
+        .filter((turn) => turn.estimatedWasteTokens > 0)
+        .sort((a, b) => b.estimatedWasteTokens - a.estimatedWasteTokens)
+        .slice(0, 8);
+    const lines = [
+        `EchoMem deterministic efficiency — ${report.client}`,
+        "",
+        `Turns: ${report.turns.length}`,
+        `Context tokens: ${formatTokens(report.totals.contextTokens)}`,
+        `Resident dirty context: ≥ ${formatTokens(report.totals.residentDirtyTokens)}`,
+        `New waste created: ≥ ${formatTokens(report.totals.newWasteTokens)}`,
+        `Efficiency: ${pct(report.totals.efficiencyEstimate)} clean (${pct(report.totals.noiseEstimate)} noise)`,
+        "",
+        "Resident dirty by rule",
+    ];
+    for (const rule of RULES)
+        lines.push(`  ${rule.padEnd(28)} ${formatTokens(report.totals.residentDirtyTokensByRule[rule])}`);
+    lines.push("");
+    lines.push("New waste by rule");
+    for (const rule of RULES)
+        lines.push(`  ${rule.padEnd(28)} ${formatTokens(report.totals.newWasteTokensByRule[rule])}`);
+    lines.push("");
+    lines.push("Noisiest turns");
+    if (!noisy.length)
+        lines.push("  none detected");
+    for (const row of noisy) {
+        const topRule = topRuleName(row.wasteTokensByRule);
+        lines.push(`  T${String(row.turn).padStart(3, "0")}  waste ≥ ${formatTokens(row.estimatedWasteTokens).padStart(5)} / ${formatTokens(row.contextTokens).padStart(5)}  efficiency ${pct(row.efficiencyEstimate)}  ${topRule}`);
+    }
+    lines.push("");
+    lines.push("Honesty: resident dirty context is carried forward as a lower-bound estimate; provider eviction is not observable.");
+    return lines.join("\n");
+}
+function processOutput(params) {
+    const tokens = outputTokens(params.output);
+    const hash = hashText(params.output);
+    const call = params.call;
+    if (!tokens)
+        return;
+    if (call.kind === "read" && call.file && call.start !== undefined && call.end !== undefined) {
+        const previous = params.readHist.get(call.file) || [];
+        const lastEdit = params.editTurn.get(call.file) ?? -1;
+        const redundant = previous.some((read) => read.turn >= lastEdit && call.start <= read.end && call.end >= read.start);
+        if (redundant) {
+            addWaste(params.turns, params.chargedCalls, call, {
+                rule: "repeated_file_read",
+                turn: call.turn,
+                tokens,
+                sourceTurn: previous.find((read) => read.turn >= lastEdit && call.start <= read.end && call.end >= read.start)?.turn,
+                label: "overlapping file range read again before edit",
+                tool: call.name,
+                command: call.command,
+                file: call.file,
+            });
+        }
+        previous.push({ start: call.start, end: call.end, turn: call.turn });
+        params.readHist.set(call.file, previous);
+    }
+    if (call.kind === "git") {
+        const previous = params.gitOutputs.get(call.normalized);
+        if (previous && previous.hash === hash) {
+            addWaste(params.turns, params.chargedCalls, call, {
+                rule: "repeated_git_output",
+                turn: call.turn,
+                tokens,
+                sourceTurn: previous.turn,
+                label: "same git command produced identical output",
+                tool: call.name,
+                command: call.command,
+                carriesForward: true,
+            });
+        }
+        params.gitOutputs.set(call.normalized, { hash, turn: call.turn });
+    }
+    if (call.kind === "search") {
+        const previous = params.searchOutputs.get(call.normalized);
+        if (previous && previous.hash === hash) {
+            addWaste(params.turns, params.chargedCalls, call, {
+                rule: "repeated_search_output",
+                turn: call.turn,
+                tokens,
+                sourceTurn: previous.turn,
+                label: "same search produced identical output",
+                tool: call.name,
+                command: call.command,
+                carriesForward: true,
+            });
+        }
+        params.searchOutputs.set(call.normalized, { hash, turn: call.turn });
+    }
+    if (params.lastCompactionTurn > 0 && call.turn > params.lastCompactionTurn && call.turn <= params.lastCompactionTurn + 3) {
+        const key = rediscoveryKey(call);
+        if (key && params.seenBeforeCompaction.has(key)) {
+            addWaste(params.turns, params.chargedCalls, call, {
+                rule: "compaction_rediscovery",
+                turn: call.turn,
+                tokens,
+                sourceTurn: params.lastCompactionTurn,
+                label: "post-compaction rediscovery output",
+                tool: call.name,
+                command: call.command,
+                file: call.file,
+                carriesForward: true,
+            });
+        }
+    }
+}
+function callMeta(payload, turn) {
+    const id = typeof payload.call_id === "string" ? payload.call_id : "";
+    const name = typeof payload.name === "string" ? payload.name : "";
+    if (!id || !name)
+        return null;
+    const args = parseArguments(payload.arguments);
+    const command = isRecord(args) && typeof args.cmd === "string" ? args.cmd : "";
+    const read = command && (name === "exec_command" || name === "shell") ? shellRead(command) : null;
+    if (read) {
+        return {
+            id,
+            turn,
+            name,
+            command,
+            kind: "read",
+            normalized: `read:${read.file}:${read.start}:${read.end}`,
+            file: read.file,
+            start: read.start,
+            end: read.end,
+        };
+    }
+    const normalized = normalizeCommand(command);
+    if (isGitCommand(command))
+        return { id, turn, name, command, kind: "git", normalized };
+    if (isSearchCommand(command))
+        return { id, turn, name, command, kind: "search", normalized };
+    return { id, turn, name, command, kind: "other", normalized };
+}
+function addWaste(turns, chargedCalls, call, event) {
+    if (chargedCalls.has(call.id))
+        return;
+    chargedCalls.add(call.id);
+    const row = ensureTurn(turns, event.turn);
+    row.events.push(event);
+    row.newWasteTokensByRule[event.rule] += event.tokens;
+    row.newWasteTokens += event.tokens;
+}
+function addAbortedTurnWaste(row, label) {
+    if (!label || row.contextTokens <= 0)
+        return;
+    const event = {
+        rule: "aborted_or_limit_ended_turn",
+        turn: row.turn,
+        tokens: row.contextTokens,
+        label,
+        carriesForward: false,
+    };
+    row.events.push(event);
+    row.newWasteTokensByRule[event.rule] += event.tokens;
+    row.newWasteTokens += event.tokens;
+}
+function ensureTurn(turns, turn) {
+    const safeTurn = Math.max(0, turn);
+    const existing = turns.get(safeTurn);
+    if (existing)
+        return existing;
+    const row = {
+        turn: safeTurn,
+        contextTokens: 0,
+        newWasteTokens: 0,
+        residentDirtyTokens: 0,
+        estimatedWasteTokens: 0,
+        efficiencyEstimate: null,
+        noiseEstimate: null,
+        newWasteTokensByRule: zeroRules(),
+        residentDirtyTokensByRule: zeroRules(),
+        wasteTokensByRule: zeroRules(),
+        events: [],
+    };
+    turns.set(safeTurn, row);
+    return row;
+}
+function finalizeRows(rows) {
+    const residentByRule = zeroRules();
+    for (const row of rows) {
+        const transientByRule = zeroRules();
+        for (const event of row.events) {
+            if (event.carriesForward === false)
+                transientByRule[event.rule] += event.tokens;
+        }
+        const combinedByRule = zeroRules();
+        for (const rule of RULES)
+            combinedByRule[rule] = residentByRule[rule] + transientByRule[rule];
+        const dirtyTokens = sumRules(combinedByRule);
+        row.residentDirtyTokensByRule = combinedByRule;
+        row.wasteTokensByRule = combinedByRule;
+        row.residentDirtyTokens = row.contextTokens > 0 ? Math.min(row.contextTokens, dirtyTokens) : dirtyTokens;
+        row.estimatedWasteTokens = row.residentDirtyTokens;
+        finalizeTurn(row);
+        for (const event of row.events) {
+            if (event.carriesForward === true)
+                residentByRule[event.rule] += event.tokens;
+        }
+    }
+}
+function finalizeTurn(row) {
+    row.noiseEstimate = row.contextTokens > 0 ? round(row.residentDirtyTokens / row.contextTokens) : null;
+    row.efficiencyEstimate = row.noiseEstimate === null ? null : round(1 - row.noiseEstimate);
+}
+function sumTotals(rows) {
+    const totals = {
+        contextTokens: 0,
+        newWasteTokens: 0,
+        residentDirtyTokens: 0,
+        estimatedWasteTokens: 0,
+        efficiencyEstimate: null,
+        noiseEstimate: null,
+        newWasteTokensByRule: zeroRules(),
+        residentDirtyTokensByRule: zeroRules(),
+        wasteTokensByRule: zeroRules(),
+    };
+    for (const row of rows) {
+        totals.contextTokens += row.contextTokens;
+        totals.newWasteTokens += row.newWasteTokens;
+        totals.residentDirtyTokens += row.residentDirtyTokens;
+        totals.estimatedWasteTokens += row.estimatedWasteTokens;
+        for (const rule of RULES) {
+            totals.newWasteTokensByRule[rule] += row.newWasteTokensByRule[rule];
+            totals.residentDirtyTokensByRule[rule] += row.residentDirtyTokensByRule[rule];
+            totals.wasteTokensByRule[rule] += row.wasteTokensByRule[rule];
+        }
+    }
+    totals.noiseEstimate = totals.contextTokens > 0 ? round(totals.residentDirtyTokens / totals.contextTokens) : null;
+    totals.efficiencyEstimate = totals.noiseEstimate === null ? null : round(1 - totals.noiseEstimate);
+    return totals;
+}
+function zeroRules() {
+    return {
+        repeated_file_read: 0,
+        repeated_git_output: 0,
+        repeated_search_output: 0,
+        compaction_rediscovery: 0,
+        aborted_or_limit_ended_turn: 0,
+    };
+}
+function sumRules(map) {
+    return RULES.reduce((sum, rule) => sum + map[rule], 0);
+}
+function outputTokens(output) {
+    return Math.max(0, Math.round(Buffer.byteLength(output || "", "utf8") / 4));
+}
+function hashText(output) {
+    return crypto.createHash("sha256").update(output || "").digest("hex");
+}
+function normalizeCommand(command) {
+    return String(command || "").trim().replace(/\s+/g, " ");
+}
+function isGitCommand(command) {
+    return /^git(?:\s|$)/.test(normalizeCommand(command));
+}
+function isSearchCommand(command) {
+    const first = normalizeCommand(command).split(/[|;&]/)[0].trim();
+    const bin = first.split(/\s+/)[0]?.split("/").pop() || "";
+    return SEARCH_BINS.has(bin);
+}
+function rediscoveryKey(call) {
+    if (call.kind === "read" && call.file)
+        return `read:${call.file}`;
+    if (call.kind === "search")
+        return `search:${call.normalized}`;
+    if (call.kind === "git")
+        return `git:${call.normalized}`;
+    return null;
+}
+function isAbortOrLimitMessage(message) {
+    const text = message.trim();
+    if (!text || text.length > 320)
+        return false;
+    return /^(?:you(?:'ve| have) hit your session limit|session limit\b|rate limit(?: reached)?\b|limit reached\b|request timed out\b|timed out\b|timeout\b|cancelled\b|canceled\b|aborted\b|interrupted\b)/i.test(text);
+}
+function abortLabel(message) {
+    if (/limit/i.test(message))
+        return "turn ended by limit message before useful completion";
+    if (/timed?\s*out|timeout/i.test(message))
+        return "turn ended by timeout before useful completion";
+    if (/cancelled|canceled|aborted|interrupted/i.test(message))
+        return "turn ended by abort/cancel before useful completion";
+    return "turn ended without useful completion";
+}
+function messageText(payload) {
+    const content = payload.content;
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .map((block) => {
+        if (typeof block === "string")
+            return block;
+        if (!isRecord(block))
+            return "";
+        return typeof block.text === "string" ? block.text : "";
+    })
+        .join("\n");
+}
+function topRuleName(map) {
+    const [name, value] = Object.entries(map).sort((a, b) => b[1] - a[1])[0] || ["", 0];
+    return value ? name : "";
+}
+function pct(value) {
+    if (value === null)
+        return "n/a";
+    return `${Math.round(value * 1000) / 10}%`;
+}
+function parseArguments(value) {
+    if (!value)
+        return {};
+    if (isRecord(value))
+        return value;
+    if (typeof value !== "string")
+        return {};
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return {};
+    }
+}
+function readNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function round(value) {
+    return Math.round(value * 10000) / 10000;
+}

package/dist/hud/server.js

@@ -319,6 +319,9 @@ async function handleBillingStatus(res) {
     }
     let plan = "unknown";
     let paid = false;
+    let historicalConversationQuota = null;
+    let memoryProcessingQuota = null;
+    let memorySearchQuota = null;
     try {
         const response = await fetch(`${API_BASE}/api/extension/account/bootstrap`, {
             headers: { Authorization: `Bearer ${token}` },
@@ -327,34 +330,35 @@ async function handleBillingStatus(res) {
         if (response.ok) {
             plan = typeof data.plan === "string" ? data.plan.toLowerCase() : "free";
             paid = ["pro", "power", "team", "enterprise"].includes(plan);
+            historicalConversationQuota = data.historicalConversationQuota ?? null;
+            memoryProcessingQuota = data.memoryProcessingQuota ?? null;
+            memorySearchQuota = data.memorySearchQuota ?? null;
         }
     }
     catch {
         /* Local alert still gives the HUD something useful. */
     }
-    if (alert && (alert.kind === "quota_exceeded" || !paid)) {
+    const quotaPayload = {
+        historicalConversationQuota,
+        memoryProcessingQuota,
+        memorySearchQuota,
+    };
+    // Free now includes recall. Ignore old plan_required alerts that may still
+    // be present on disk from a previous bridge version.
+    if (alert && (alert.kind === "quota_exceeded" || alert.kind === "billing_attention")) {
         return respond({
             ok: true,
             state: alert.kind,
             plan: alert.plan || plan,
-            message: alert.kind === "quota_exceeded" ? "Recall limit reached." : "Recall needs a plan.",
+            message: alert.kind === "quota_exceeded" ? "Plan limit reached." : "Billing needs attention.",
             detail: alert.message,
             code: alert.code,
             pricingUrl: appendSource(alert.pricingUrl || pricingUrl, "hud"),
             updatedAt: alert.updatedAt,
+            ...quotaPayload,
         });
     }
-    if (!paid && plan === "free") {
-        return respond({
-            ok: true,
-            state: "plan_required",
-            plan,
-            message: "Recall needs a plan.",
-            detail: "Search and recall require Echo Pro or Power. Saving conversations keeps working.",
-            pricingUrl,
-        });
-    }
-    respond({ ok: true, state: "ok", plan, paid, pricingUrl });
+    respond({ ok: true, state: "ok", plan, paid, pricingUrl, ...quotaPayload });
 }
 function appendSource(url, source) {
     try {