@echomem/mcp 1.4.9 → 1.4.12

package/dist/context-metrics/ledger.js

@@ -0,0 +1,507 @@
+// Context ledger + per-turn useful/waste classifier.
+//
+// Faithful TypeScript port of the Context Golden Standard scorer
+// (context-golden-standard/ErikMachine-Context_Golden_Standard/tools/optimizable_detail.mjs),
+// validated turn-by-turn against it (0.00pp divergence on 6 codex sessions, 2026-07-12).
+//
+// Two scoring modes over one item ledger:
+//   "episode-outcome"  offline truth: judges every carried item against its episode's
+//                      final/anchor turn. Needs the whole session; eval/regression only.
+//   "live-causal"      HUD estimator: same partition using only information available at
+//                      turn t, plus per-category uncertainty totals that the calibrated
+//                      rates (calibration.ts) convert into an expected-value estimate.
+//
+// Every turn's real input window C_t is partitioned into:
+//   keep_oh + keep_prod + opt_dup + opt_refind + opt_dead  (sums to C_t)
+// signal% = 100 − optimizable%, where optimizable = opt_dup + opt_refind + opt_dead.
+// ---- golden token model ----
+export const R_CODE = 3.3;
+export const R_TEXT = 4.0;
+export const IMG_TOK = 4000;
+export const TRUNC_CAP = 12000;
+const SER_FRAC = 0.03;
+const IMG_FRESH_AGE = 2; // kept screenshots older than this survived the edit cycle
+const CONTENT = new Set(["read", "search", "command", "image", "written", "conv_user", "conv_agent"]);
+const BANDS = ["keep_oh", "keep_prod", "opt_dup", "opt_refind", "opt_dead"];
+const USER_REFERENCE_REPLACEMENT = /\b(use this instead|instead use|replace|updated|new mockup|new reference|ignore (?:the )?(?:previous|old)|actually use|latest version|use this version)\b/i;
+// ---- ground-truth anchors (port of golden_anchors.mjs) ----
+export function isStrongPositiveFeedback(message) {
+    const text = String(message || "").toLowerCase().replace(/[’]/g, "'").replace(/\s+/g, " ").trim();
+    if (!text)
+        return false;
+    if (/\b(no|not|wrong|incorrect|fix|bad|worse|broken|laggy|shaking|remove|revert|don't|do not|doesn't|does not|didn't|did not|isn't|is not)\b/.test(text)) {
+        if (!/\b(save this|looks good|perfect|exactly what i want|that's what i want|that is what i want)\b/.test(text))
+            return false;
+    }
+    return [
+        /\blooks? good\b/, /\bthis is good\b/, /\bcaveat font is good\b/, /\bperfect\b/,
+        /\bthis is exactly\b/, /\bthat's exactly\b/, /\bthat is exactly\b/, /\bexactly what i want\b/,
+        /\bthat's what i want\b/, /\bthat is what i want\b/, /\bwhat i want\b/,
+        /\byes[,.\s].*\blet'?s do it\b/, /\bok[,.\s].*\blet'?s do it\b/, /\blet'?s do it\b/,
+        /\bsave this\b/, /\bship it\b/, /\bapproved\b/,
+    ].some((pattern) => pattern.test(text));
+}
+function chooseAnchors(ledger, userTurns) {
+    const commits = [...ledger.commitTurns].sort((a, b) => a - b);
+    if (commits.length)
+        return { source: "commit", turns: commits };
+    const positive = userTurns.filter((turn) => isStrongPositiveFeedback(ledger.userMessages.get(turn) || ""));
+    if (positive.length)
+        return { source: "positive-user-feedback", turns: positive };
+    const lastTurn = userTurns[userTurns.length - 1];
+    return lastTurn ? { source: "final-fallback", turns: [lastTurn] } : { source: "none", turns: [] };
+}
+// ---- shared text signals (golden tier-2 detection) ----
+function signals(text) {
+    const out = new Set();
+    for (const m of text.matchAll(/#[0-9a-fA-F]{3,8}\b/g))
+        out.add("c:" + m[0].toLowerCase());
+    for (const m of text.matchAll(/--[a-zA-Z][\w-]{2,}/g))
+        out.add("v:" + m[0].toLowerCase());
+    for (const m of text.matchAll(/\b\d{1,4}(?:\.\d+)?(?:px|rem|em|vh|vw|ms)\b/g))
+        out.add("u:" + m[0].toLowerCase());
+    return out;
+}
+const rangeOverlap = (a, b) => !a || !b || (a[0] <= b[1] && b[0] <= a[1]);
+function firstGreaterIndex(sorted, value) {
+    let lo = 0, hi = sorted.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >> 1;
+        if (sorted[mid] <= value)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    return lo;
+}
+const anyInRange = (sorted, gt, lte) => {
+    const i = firstGreaterIndex(sorted, gt);
+    return i < sorted.length && sorted[i] <= lte;
+};
+export function classifySession(ledger, scoringMode, onlyLatestTurn = false) {
+    const isOutcome = scoringMode === "episode-outcome";
+    const { items, usage, overhead, compactionTurns, editEpoch, userMessages } = ledger;
+    const allUserTurns = [...new Set(items.filter((i) => i.kind === "conv_user" && !i.compactSummary && i.turn).map((i) => i.turn))]
+        .sort((a, b) => a - b)
+        .filter((t) => (usage.get(t) || 0) > 0);
+    const userTurns = onlyLatestTurn ? allUserTurns.slice(-1) : allUserTurns;
+    const lastCompBefore = (t) => { let c = 0; for (const x of compactionTurns)
+        if (x < t)
+            c = x; return c; };
+    const anchors = chooseAnchors(ledger, allUserTurns);
+    const commits = anchors.turns;
+    const episodeOf = (t) => { let e = 1; for (const c of commits) {
+        if (t <= c)
+            return e;
+        e++;
+    } return e; };
+    const firstUserTurn = allUserTurns[0] || 1;
+    const lastUserTurn = allUserTurns[allUserTurns.length - 1] || 1;
+    const episodeStartTurn = (e) => (e <= 1 ? firstUserTurn : (commits[e - 2] || firstUserTurn - 1) + 1);
+    const episodeEndTurn = (e) => commits[e - 1] || lastUserTurn;
+    // causal episode boundaries: only commits that have already happened by turn t
+    const commitAnchorsAsc = [...ledger.commitTurns].sort((a, b) => a - b);
+    const episodeOfAt = (turn, t) => { let e = 1; for (const c of commitAnchorsAsc) {
+        if (c > t)
+            break;
+        if (turn <= c)
+            return e;
+        e++;
+    } return e; };
+    const causalEpisodeStart = (t) => { let s = 1; for (const c of commitAnchorsAsc) {
+        if (c < t)
+            s = c + 1;
+        else
+            break;
+    } return s; };
+    const causalAnchorTurn = (t) => ledger.commitTurns.has(t) || isStrongPositiveFeedback(userMessages.get(t) || "");
+    // ---- indexes (all built once; every per-turn helper is a bounded scan or binary search) ----
+    const editTurnsSorted = [...editEpoch.values()].flat().sort((a, b) => a - b);
+    const readsByFile = new Map();
+    for (const it of items) {
+        if (it.kind !== "read" || !it.file)
+            continue;
+        const list = readsByFile.get(it.file) || [];
+        list.push(it);
+        readsByFile.set(it.file, list);
+    }
+    const screenshotTurnsByTarget = new Map();
+    const refItems = [];
+    for (const it of items) {
+        if (it.kind !== "image")
+            continue;
+        if (it.source === "tool_screenshot") {
+            const key = it.target || "tool_image";
+            const list = screenshotTurnsByTarget.get(key) || [];
+            list.push(it.turn);
+            screenshotTurnsByTarget.set(key, list);
+        }
+        else if (it.source === "user_reference")
+            refItems.push(it);
+    }
+    for (const list of screenshotTurnsByTarget.values())
+        list.sort((a, b) => a - b);
+    // turns whose user message uses replacement language AND posts a reference image
+    const replacementRefTurnsSorted = [...new Set(refItems.map((r) => r.turn))]
+        .filter((turn) => USER_REFERENCE_REPLACEMENT.test(userMessages.get(turn) || ""))
+        .sort((a, b) => a - b);
+    const firstRefTurn = refItems.length ? Math.min(...refItems.map((r) => r.turn)) : Infinity;
+    const churnFromTurn = replacementRefTurnsSorted.find((rt) => rt > firstRefTurn) ?? Infinity;
+    const editsOfFile = (f) => (f ? editEpoch.get(f) || [] : []);
+    const editBetween = (f, gt, lte) => anyInRange(editsOfFile(f), gt, lte);
+    const hasEditAfter = (gt, lte) => anyInRange(editTurnsSorted, gt, lte);
+    const hasLaterScreenshot = (it, endTurn) => anyInRange(screenshotTurnsByTarget.get(it.target || "tool_image") || [], it.turn, endTurn);
+    const userReferenceSuperseded = (it, endTurn) => anyInRange(replacementRefTurnsSorted, it.turn, endTurn);
+    // duplicate reads — golden semantics; the "at" variant is the causal mirror where the newest
+    // copy stays fresh and superseded older copies become the duplicates.
+    const isDupRead = (it) => it.kind === "read" && !!it.file &&
+        (readsByFile.get(it.file) || []).some((h) => h.turn < it.turn && rangeOverlap(h.range, it.range) && !editBetween(it.file, h.turn, it.turn));
+    const isDupReadAt = (it, t) => it.kind === "read" && !!it.file &&
+        (readsByFile.get(it.file) || []).some((h) => h.turn > it.turn && h.turn <= t && rangeOverlap(h.range, it.range) && !editBetween(it.file, it.turn, h.turn));
+    const hasLaterDuplicateReadBeforeOutcome = (it, end) => isDupReadAt(it, end);
+    // ---- tier model: does an unedited file's content connect to what got written? ----
+    const writeSigTimeline = [];
+    {
+        let cum = new Set();
+        for (const ch of ledger.writeChunks) {
+            cum = new Set(cum);
+            for (const s of signals(ch.text))
+                cum.add(s);
+            writeSigTimeline.push({ turn: ch.turn, cum });
+        }
+    }
+    const readSigTimeline = new Map();
+    for (const ch of ledger.readChunks) {
+        const arr = readSigTimeline.get(ch.file) || [];
+        const prev = arr.length ? arr[arr.length - 1].cum : new Set();
+        const cum = new Set(prev);
+        for (const s of signals(ch.text))
+            cum.add(s);
+        arr.push({ turn: ch.turn, cum });
+        readSigTimeline.set(ch.file, arr);
+    }
+    const latestAt = (arr, t) => {
+        let out = null;
+        for (const e of arr) {
+            if (e.turn <= t)
+                out = e.cum;
+            else
+                break;
+        }
+        return out;
+    };
+    const tierMatches = (sig, ws) => {
+        if (!sig)
+            return false;
+        let m = 0;
+        for (const x of sig)
+            if (ws.has(x))
+                m++;
+        return m >= 4 || (sig.size >= 8 && m / sig.size >= 0.15);
+    };
+    const fullWriteSig = writeSigTimeline.length ? writeSigTimeline[writeSigTimeline.length - 1].cum : new Set();
+    const editedByTurn = (f, t) => anyInRange(editsOfFile(f), 0, t);
+    const tierOf = (f) => {
+        if (!f)
+            return 3;
+        if (editEpoch.has(f))
+            return 1;
+        const arr = readSigTimeline.get(f);
+        return tierMatches(arr ? arr[arr.length - 1].cum : null, fullWriteSig) ? 2 : 3;
+    };
+    const tierOfCausal = (f, t) => {
+        if (!f)
+            return 3;
+        if (editedByTurn(f, t))
+            return 1;
+        const ws = latestAt(writeSigTimeline, t) || new Set();
+        return tierMatches(latestAt(readSigTimeline.get(f) || [], t), ws) ? 2 : 3;
+    };
+    const editedThisEpisodeByT = (f, t) => anyInRange(editsOfFile(f), causalEpisodeStart(t) - 1, t);
+    const transientKey = (it) => {
+        if (it.kind === "search")
+            return `search:${it.searchPattern || it.normalizedCommand || ""}`;
+        if (it.kind === "command")
+            return `command:${it.normalizedCommand || ""}`;
+        return "";
+    };
+    const episodeOutcome = new Map();
+    if (isOutcome) {
+        const maxEpisode = Math.max(1, ...allUserTurns.map((t) => episodeOf(t)));
+        for (let e = 1; e <= maxEpisode; e++) {
+            const start = episodeStartTurn(e);
+            const end = episodeEndTurn(e);
+            const editedFiles = new Set();
+            for (const [file, turns] of editEpoch.entries())
+                if (turns.some((x) => x >= start && x <= end))
+                    editedFiles.add(file);
+            const writtenItems = items.filter((it) => it.kind === "written" && it.turn >= start && it.turn <= end).sort((a, b) => b.seq - a.seq);
+            const usefulWrittenSeqs = new Set();
+            const latestWrittenByFile = new Map();
+            const unfiled = [];
+            for (const it of writtenItems) {
+                const files = it.files?.length ? it.files : it.file ? [it.file] : [];
+                if (!files.length) {
+                    unfiled.push(it);
+                    continue;
+                }
+                for (const file of files) {
+                    const n = latestWrittenByFile.get(file) || 0;
+                    if (n < 2) {
+                        usefulWrittenSeqs.add(it.seq);
+                        latestWrittenByFile.set(file, n + 1);
+                    }
+                }
+            }
+            for (const it of unfiled.slice(0, 2))
+                usefulWrittenSeqs.add(it.seq);
+            const latestTransientByKey = new Map();
+            for (const it of items) {
+                if (it.turn < start || it.turn > end)
+                    continue;
+                if (it.kind !== "search" && it.kind !== "command")
+                    continue;
+                const key = transientKey(it);
+                if (!key)
+                    continue;
+                const prev = latestTransientByKey.get(key);
+                if (prev === undefined || it.seq > prev)
+                    latestTransientByKey.set(key, it.seq);
+            }
+            episodeOutcome.set(e, { start, end, editedFiles, usefulWrittenSeqs, latestTransientByKey });
+        }
+    }
+    const imageBucket = (it, currentTurn, epOf) => {
+        if (it.source === "user_reference") {
+            if (epOf(it.turn) !== epOf(currentTurn))
+                return "opt_dead";
+            return userReferenceSuperseded(it, currentTurn) ? "opt_dead" : "keep_prod";
+        }
+        if (it.source === "tool_screenshot") {
+            if (hasEditAfter(it.turn, currentTurn) || hasLaterScreenshot(it, currentTurn))
+                return "opt_dead";
+            return "keep_prod";
+        }
+        return "opt_dead";
+    };
+    const outcomeBucket = (it, currentTurn) => {
+        const e = episodeOf(currentTurn);
+        const outcome = episodeOutcome.get(e) || { start: episodeStartTurn(e), end: episodeEndTurn(e), editedFiles: new Set(), usefulWrittenSeqs: new Set(), latestTransientByKey: new Map() };
+        if (it.kind === "conv_user")
+            return episodeOf(it.turn) === e ? "keep_prod" : "opt_dead";
+        if (it.kind === "conv_agent")
+            return it.turn === outcome.end && currentTurn === outcome.end ? "keep_prod" : "opt_refind";
+        if (it.kind === "search" || it.kind === "command") {
+            const key = transientKey(it);
+            const latest = key ? outcome.latestTransientByKey.get(key) : undefined;
+            if (latest !== undefined && latest !== it.seq)
+                return "opt_refind";
+            return it.turn === outcome.end && currentTurn === outcome.end ? "keep_prod" : "opt_refind";
+        }
+        if (it.kind === "image")
+            return imageBucket(it, outcome.end, episodeOf);
+        if (it.kind === "written")
+            return outcome.usefulWrittenSeqs.has(it.seq) ? "keep_prod" : "opt_dup";
+        if (it.kind === "read") {
+            if (hasLaterDuplicateReadBeforeOutcome(it, outcome.end))
+                return "opt_dup";
+            if (outcome.editedFiles.size)
+                return it.file && outcome.editedFiles.has(it.file) ? "keep_prod" : "opt_dead";
+            return tierOf(it.file) <= 2 ? "keep_prod" : "opt_dead";
+        }
+        return null;
+    };
+    // codex cumulative reasoning -> per-turn segments since the last compaction
+    const maxReasoningAt = new Map();
+    for (const x of ledger.reasoningCalls)
+        maxReasoningAt.set(x.turn, Math.max(maxReasoningAt.get(x.turn) || 0, x.tokens));
+    const reasoningSegments = (lastCompactionTurn, currentTurn) => {
+        const segments = [];
+        let previous = 0;
+        for (let k = lastCompactionTurn + 1; k <= currentTurn; k++) {
+            const cumulative = Math.max(previous, maxReasoningAt.get(k) || previous);
+            if (cumulative - previous > 0)
+                segments.push({ turn: k, tokens: cumulative - previous });
+            previous = cumulative;
+        }
+        return segments;
+    };
+    const series = [];
+    const agg = { keep_oh: 0, keep_prod: 0, opt_dup: 0, opt_refind: 0, opt_dead: 0 };
+    for (const t of userTurns) {
+        const lc = lastCompBefore(t);
+        const C_t = usage.get(t) || 0;
+        const b = { keep_oh: 0, keep_prod: 0, opt_dup: 0, opt_refind: 0, opt_dead: 0 };
+        let deadReadTokens = 0;
+        let deadImageTokens = 0;
+        let dupCount = 0;
+        let reasoning = 0;
+        if (ledger.reasoningStyle === "cumulative") {
+            for (const segment of reasoningSegments(lc, t)) {
+                reasoning += segment.tokens;
+                const keep = isOutcome
+                    ? segment.turn === t && t === episodeEndTurn(episodeOf(t))
+                    : segment.turn === t;
+                b[keep ? "keep_prod" : "opt_refind"] += segment.tokens;
+            }
+        }
+        const structureFloor = Math.round(SER_FRAC * C_t);
+        b.keep_oh = overhead + structureFloor;
+        const budget = Math.max(0, C_t - overhead - reasoning - structureFloor);
+        const carried = [];
+        for (const it of items) {
+            if (it.turn > t)
+                break;
+            if (ledger.hardCompactionDrop && it.turn <= lc && !(it.compactSummary && it.turn >= lc))
+                continue;
+            if (it.kind === "reasoning") {
+                if (it.turn === t)
+                    carried.push(it);
+                continue;
+            }
+            if (it.compactSummary || CONTENT.has(it.kind))
+                carried.push(it);
+        }
+        carried.reverse();
+        const un = { stReads: 0, cReads: 0, stTransients: 0, stAgent: 0, stReasoning: 0, deadReads: 0, imgRefs: 0, imgRefsCalm: 0, imgShots: 0 };
+        const anchorNow = !isOutcome && causalAnchorTurn(t);
+        const commitHappened = commitAnchorsAsc.length > 0 && commitAnchorsAsc[0] <= t;
+        const episodeHasEdits = anyInRange(editTurnsSorted, causalEpisodeStart(t) - 1, t);
+        const cReadsExempt = commitHappened && !episodeHasEdits;
+        const refChurnObserved = churnFromTurn <= t;
+        const epOfLive = (turn) => episodeOfAt(turn, t);
+        let running = 0;
+        const seenWriteByFile = new Map();
+        const seenSameTurnTransient = new Set();
+        for (const it of carried) {
+            if (running >= budget)
+                break;
+            const tok = Math.min(it.tokens, budget - running);
+            running += tok;
+            let bucket = null;
+            let isDeadRead = false;
+            let isDeadImage = false;
+            if (it.compactSummary)
+                bucket = "keep_prod"; // distilled carried state
+            else if (it.kind === "reasoning") {
+                // items-style reasoning is only carried same-turn; the outcome judge keeps it only
+                // when this turn is its episode's anchor
+                bucket = isOutcome ? (t === episodeEndTurn(episodeOf(t)) ? "keep_prod" : "opt_refind") : "keep_prod";
+                if (!isOutcome && !anchorNow)
+                    un.stReasoning += tok;
+            }
+            else if (isOutcome) {
+                bucket = outcomeBucket(it, t);
+                if (bucket === "opt_dead") {
+                    isDeadRead = it.kind === "read";
+                    isDeadImage = it.kind === "image";
+                }
+                if (bucket === "opt_dup" && it.kind === "read")
+                    dupCount += 1;
+            }
+            else {
+                if (it.kind === "conv_user")
+                    bucket = it.turn < causalEpisodeStart(t) ? "opt_dead" : "keep_prod";
+                else if (it.kind === "conv_agent") {
+                    bucket = it.turn === t ? "keep_prod" : "opt_refind";
+                    if (bucket === "keep_prod" && !anchorNow)
+                        un.stAgent += tok;
+                }
+                else if (it.kind === "search" || it.kind === "command") {
+                    if (it.turn === t) {
+                        const key = transientKey(it);
+                        bucket = key && seenSameTurnTransient.has(key) ? "opt_refind" : "keep_prod";
+                        if (key)
+                            seenSameTurnTransient.add(key);
+                        if (bucket === "keep_prod" && !anchorNow)
+                            un.stTransients += tok;
+                    }
+                    else
+                        bucket = "opt_refind";
+                }
+                else if (it.kind === "image") {
+                    bucket = imageBucket(it, t, epOfLive);
+                    if (bucket === "keep_prod") {
+                        if (it.source === "user_reference")
+                            un[refChurnObserved ? "imgRefs" : "imgRefsCalm"] += tok;
+                        else if (t - it.turn <= IMG_FRESH_AGE)
+                            un.imgShots += tok;
+                    }
+                    else
+                        isDeadImage = true;
+                }
+                else if (it.kind === "written") {
+                    if (it.turn < causalEpisodeStart(t))
+                        bucket = "opt_dup"; // superseded copies from closed episodes
+                    else {
+                        const wf = it.file || (it.files?.length === 1 ? it.files[0] : "__unfiled__");
+                        const seen = seenWriteByFile.get(wf) || 0;
+                        if (seen < 2) {
+                            bucket = "keep_prod";
+                            seenWriteByFile.set(wf, seen + 1);
+                        }
+                        else
+                            bucket = "opt_dup";
+                    }
+                }
+                else if (it.kind === "read") {
+                    if (isDupReadAt(it, t)) {
+                        bucket = "opt_dup";
+                        dupCount += 1;
+                    }
+                    else if (editedThisEpisodeByT(it.file, t))
+                        bucket = "keep_prod"; // connects to episode edits
+                    else if (it.turn === t) {
+                        bucket = "keep_prod";
+                        un.stReads += tok;
+                    }
+                    else if (tierOfCausal(it.file, t) === 3) {
+                        bucket = "opt_dead";
+                        isDeadRead = true;
+                        un.deadReads += tok;
+                    }
+                    else {
+                        bucket = "keep_prod";
+                        if (!cReadsExempt)
+                            un.cReads += tok;
+                    }
+                }
+            }
+            if (bucket) {
+                b[bucket] += tok;
+                if (isDeadRead)
+                    deadReadTokens += tok;
+                if (isDeadImage)
+                    deadImageTokens += tok;
+            }
+        }
+        const residual = C_t - BANDS.reduce((a, x) => a + b[x], 0);
+        b.opt_refind += residual; // reconcile serialization not represented by a concrete item
+        for (const x of BANDS)
+            agg[x] += b[x];
+        const opt = b.opt_dup + b.opt_refind + b.opt_dead;
+        const row = {
+            turn: t,
+            episode: episodeOf(t),
+            C_t,
+            ...b,
+            deadReadTokens,
+            deadImageTokens,
+            dupCount,
+            optimizablePct: C_t > 0 ? +(100 * opt / C_t).toFixed(1) : 0,
+        };
+        if (!isOutcome)
+            row.uncertain = un;
+        series.push(row);
+    }
+    const billTot = series.reduce((a, r) => a + r.C_t, 0) || 1;
+    const optTot = agg.opt_dup + agg.opt_refind + agg.opt_dead;
+    return {
+        turns: userTurns.length,
+        anchorSource: anchors.source,
+        anchorTurns: commits,
+        series,
+        billTot,
+        optimizablePct: +(100 * optTot / billTot).toFixed(1),
+    };
+}