fraim-hub 2.0.338 → 2.0.340

package/dist/src/local-mcp-server/learning-usage-events.js

@@ -0,0 +1,267 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveEventDir = resolveEventDir;
+exports.resolveMachineId = resolveMachineId;
+exports.appendEvents = appendEvents;
+exports.listEventLogs = listEventLogs;
+exports.readEventsSince = readEventsSince;
+exports.compactEventLogs = compactEventLogs;
+/**
+ * Per-machine usage journals: job runs append complete JSON lines; sleep folds
+ * them into a recoverable snapshot and removes processed records.
+ *
+ * A cleared journal contains only {_usageJournalThroughBytes:N}. This framing
+ * marker preserves its logical position across atomic replacement, so a crash
+ * between checkpoint publication and journal cleanup cannot reset offsets or
+ * count an event twice. It contains no activity details. New appends continue
+ * from N; an older/missing snapshot cannot silently cold-fold compacted history.
+ *
+ * Maintenance requires no concurrent writers or sync activity. Ordinary writers
+ * append one payload; different machines use different filenames.
+ */
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+/** Subdirectory of the usage folder holding the per-machine logs. */
+const EVENT_DIR_NAME = 'events';
+const LOG_SUFFIX = '.jsonl';
+const CHECKPOINT_MARKER = '_usageJournalThroughBytes';
+/** The log directory that belongs to a snapshot: `<usage>/events/`. */
+function resolveEventDir(snapshotPath) {
+    return (0, path_1.join)((0, path_1.dirname)(snapshotPath), EVENT_DIR_NAME);
+}
+/**
+ * The filename component identifying this machine. Two machines must never write
+ * one file, which is the entire cross-machine safety argument, so anything that
+ * is not a safe filename character is replaced rather than dropped (dropping can
+ * collide two different hostnames onto one name).
+ */
+function resolveMachineId() {
+    const raw = (() => { try {
+        return (0, os_1.hostname)();
+    }
+    catch {
+        return '';
+    } })();
+    const safe = String(raw || 'unknown-machine').trim().replace(/[^A-Za-z0-9._-]/g, '_');
+    return safe || 'unknown-machine';
+}
+function logPathFor(eventDir, machineId) {
+    return (0, path_1.join)(eventDir, `${machineId}${LOG_SUFFIX}`);
+}
+/**
+ * Append one JSON line per record. No read, so there is no lost-update window to
+ * narrow: the window is gone rather than smaller.
+ */
+function appendEvents(eventDir, records, machineId = resolveMachineId()) {
+    if (records.length === 0)
+        return 0;
+    (0, fs_1.mkdirSync)(eventDir, { recursive: true });
+    const logPath = logPathFor(eventDir, machineId);
+    const separator = endsOnARecordBoundary(logPath) ? '' : '\n';
+    const payload = `${separator}${records.map((record) => JSON.stringify(record)).join('\n')}\n`;
+    (0, fs_1.appendFileSync)(logPath, payload, 'utf8');
+    return records.length;
+}
+/**
+ * Does the log already end where a record ends?
+ *
+ * A process killed part-way through an append leaves a line with no terminator.
+ * Appending straight onto it concatenates the torn record and the new one into a
+ * single unparseable line, so one interrupted write costs two events rather than
+ * one. Found in the #1752 bug bash. Closing the boundary first means a torn write
+ * loses only itself.
+ *
+ * One byte read per append, and only when the log already exists.
+ */
+function endsOnARecordBoundary(logPath) {
+    try {
+        const fd = (0, fs_1.openSync)(logPath, 'r');
+        try {
+            const size = (0, fs_1.fstatSync)(fd).size;
+            if (size === 0)
+                return true;
+            const last = Buffer.alloc(1);
+            (0, fs_1.readSync)(fd, last, 0, 1, size - 1);
+            return last[0] === 0x0a;
+        }
+        finally {
+            (0, fs_1.closeSync)(fd);
+        }
+    }
+    catch {
+        // No log yet, or it cannot be read. A fresh file starts on a boundary, and an
+        // unreadable one is the fold's problem rather than the append's.
+        return true;
+    }
+}
+function listEventLogs(eventDir) {
+    if (!(0, fs_1.existsSync)(eventDir))
+        return [];
+    let names;
+    try {
+        names = (0, fs_1.readdirSync)(eventDir);
+    }
+    catch {
+        return [];
+    }
+    const logs = [];
+    for (const name of names) {
+        if (!name.endsWith(LOG_SUFFIX))
+            continue;
+        const path = (0, path_1.join)(eventDir, name);
+        let size = 0;
+        let baseOffset = 0;
+        let headerBytes = 0;
+        try {
+            const fd = (0, fs_1.openSync)(path, 'r');
+            try {
+                size = (0, fs_1.fstatSync)(fd).size;
+                const prefix = Buffer.alloc(Math.min(size, 128));
+                (0, fs_1.readSync)(fd, prefix, 0, prefix.length, 0);
+                const newline = prefix.indexOf(0x0a);
+                if (newline >= 0) {
+                    try {
+                        const header = JSON.parse(prefix.subarray(0, newline).toString('utf8'));
+                        if (Object.keys(header).length === 1 && Number.isSafeInteger(header[CHECKPOINT_MARKER]) && header[CHECKPOINT_MARKER] >= 0) {
+                            baseOffset = header[CHECKPOINT_MARKER];
+                            headerBytes = newline + 1;
+                        }
+                    }
+                    catch { /* An ordinary first event, not a checkpoint marker. */ }
+                }
+            }
+            finally {
+                (0, fs_1.closeSync)(fd);
+            }
+        }
+        catch {
+            continue;
+        }
+        logs.push({ machineId: name.slice(0, -LOG_SUFFIX.length), path, size, baseOffset, headerBytes });
+    }
+    return logs.sort((a, b) => a.machineId.localeCompare(b.machineId));
+}
+function readTail(log, from) {
+    const end = log.baseOffset + log.size - log.headerBytes;
+    if (from < log.baseOffset)
+        throw new Error('Usage checkpoint is missing or older than the consolidated journal. Restore learning-usage.json or its .checkpoint backup; raw retrospectives cannot restore runtime offers.');
+    const restarted = from > end;
+    if (restarted && log.baseOffset > 0)
+        throw new Error('Usage journal is behind its checkpoint; restore matching files before continuing.');
+    const start = restarted ? 0 : Math.max(0, from);
+    const physicalStart = start - log.baseOffset + log.headerBytes;
+    const length = log.size - physicalStart;
+    if (length <= 0) {
+        return { ...log, records: [], skippedLines: 0, through: start, restarted };
+    }
+    let text;
+    try {
+        const fd = (0, fs_1.openSync)(log.path, 'r');
+        try {
+            const buffer = Buffer.alloc(length);
+            const read = (0, fs_1.readSync)(fd, buffer, 0, length, physicalStart);
+            text = buffer.subarray(0, read).toString('utf8');
+        }
+        finally {
+            (0, fs_1.closeSync)(fd);
+        }
+    }
+    catch {
+        // Unreadable right now (locked, mid-sync). The checkpoint does not advance,
+        // so the next reader picks it up. Degrading to what is readable is the
+        // existing contract for this derived data.
+        return { ...log, records: [], skippedLines: 0, through: start, restarted };
+    }
+    // Only complete lines are consumed. A trailing partial is what an interrupted
+    // append leaves behind, and advancing past it would lose the record for good.
+    const lastNewline = text.lastIndexOf('\n');
+    if (lastNewline === -1) {
+        return { ...log, records: [], skippedLines: 0, through: start, restarted };
+    }
+    const complete = text.slice(0, lastNewline);
+    const partialBytes = Buffer.byteLength(text.slice(lastNewline + 1), 'utf8');
+    const records = [];
+    let skippedLines = 0;
+    for (const line of complete.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
+                records.push(parsed);
+            else
+                skippedLines += 1;
+        }
+        catch {
+            skippedLines += 1;
+        }
+    }
+    return { ...log, records, skippedLines, through: end - partialBytes, restarted };
+}
+/**
+ * Read every log's tail past its checkpoint.
+ *
+ * A checkpoint past the end of its log means the log was compacted or replaced
+ * underneath the snapshot. `restarted` says so, and the caller discards the whole
+ * snapshot rather than returning a short count that looks like real data.
+ */
+function readEventsSince(eventDir, checkpoints) {
+    const reads = listEventLogs(eventDir).map((log) => readTail(log, checkpoints[log.machineId] ?? 0));
+    return {
+        reads,
+        skippedLines: reads.reduce((sum, r) => sum + r.skippedLines, 0),
+        restarted: reads.some((r) => r.restarted),
+    };
+}
+/**
+ * Clear fully checkpointed logs whose records are all understood by this reader.
+ * Preserve unknown, malformed, partial or newly appended logs byte-for-byte.
+ * Flush then atomically replace each log with its logical-position header; the
+ * checkpoint saved before this call remains correct on either side of a crash.
+ */
+function compactEventLogs(eventDir, keep, checkpoints) {
+    const result = { scanned: 0, kept: 0, dropped: 0, skippedLines: 0, logs: [], checkpoints: { ...checkpoints } };
+    for (const log of listEventLogs(eventDir)) {
+        const read = readTail(log, log.baseOffset);
+        result.scanned += read.records.length;
+        result.skippedLines += read.skippedLines;
+        result.kept += read.records.length;
+        // The snapshot knows nothing about a later append or torn
+        // tail. Leave that log and its old checkpoint alone for the next fold.
+        if (read.through !== log.baseOffset + log.size - log.headerBytes
+            || read.through !== (checkpoints[log.machineId] ?? 0) || read.skippedLines > 0)
+            continue;
+        const retained = read.records.filter(keep);
+        // Unknown records may belong to a newer reader. Leave their whole log
+        // intact so their original positions remain meaningful.
+        if (retained.length > 0 || read.records.length === 0)
+            continue;
+        const temp = `${log.path}.compacting`;
+        try {
+            const payload = `${JSON.stringify({ [CHECKPOINT_MARKER]: read.through })}\n`;
+            (0, fs_1.writeFileSync)(temp, payload, { encoding: 'utf8', flush: true });
+            if ((0, fs_1.statSync)(log.path).size !== log.size) {
+                (0, fs_1.rmSync)(temp, { force: true });
+                continue;
+            }
+            (0, fs_1.renameSync)(temp, log.path);
+            const dropped = read.records.length - retained.length;
+            result.kept -= dropped;
+            result.dropped += dropped;
+            // The logical checkpoint remains unchanged across the atomic replacement.
+            result.checkpoints[log.machineId] = read.through;
+        }
+        catch {
+            // The log is authoritative and the original is still intact, so a failed
+            // compaction costs a slower cold fold and nothing else.
+            try {
+                (0, fs_1.rmSync)(temp, { force: true });
+            }
+            catch { /* best effort */ }
+        }
+    }
+    result.logs = listEventLogs(eventDir);
+    return result;
+}

package/dist/src/local-mcp-server/learning-usage-projection.js

@@ -50,30 +50,34 @@ function buildUsageLookup(store) {
 /**
  * Resolve the usage for one entry from whichever handles it has. Prefers the id,
  * because a title is only a fallback for entries the id migration has not reached.
+ *
+ * Issue #1752 A1: the preference order is `resolveEntryIdentity`'s, not a second
+ * copy of it. The title key is still tried afterwards, because a record written
+ * before the entry was stamped is reachable only by title.
  */
 function lookupUsage(lookup, id, fileType, title) {
-    if (id) {
-        const byId = lookup.get(id);
-        if (byId)
-            return byId;
-    }
-    return lookup.get((0, learning_usage_store_1.titleUsageKey)(fileType, title));
+    const identity = (0, learning_usage_store_1.resolveEntryIdentity)({ id, fileType, title });
+    const resolved = lookup.get(identity.key);
+    if (resolved)
+        return resolved;
+    return identity.source === 'id' ? lookup.get((0, learning_usage_store_1.titleUsageKey)(fileType, title)) : undefined;
 }
 /**
- * The model with the most recent offer. Used as "the current model" for the
- * per-model retirement question, so it follows the agent in use rather than
- * needing to be configured.
+ * Issue #1752 C1 — "the current model" comes from the caller, never from the store.
+ *
+ * This used to return the model of the globally most-recent offer. The store is
+ * shared by concurrent sessions from two machines and two agents, so that reports
+ * whichever agent wrote last. On the sleep-on-learnings run of 2026-09-18 it
+ * answered `gpt-5` while the session was Claude Opus 5, and since retirement
+ * candidacy is computed per model, every per-model conclusion in that run was
+ * computed against a model that was not running.
+ *
+ * Resolution order is the explicit flag, then `FRAIM_ACTIVE_MODEL`, then null.
+ * That follows the existing `FRAIM_ACTIVE_USER_EMAIL` convention, which is
+ * read-only and operator-set, so it introduces no new configuration mechanism.
+ * Null is reported as `unknown` and suppresses every per-model conclusion rather
+ * than being computed against a null bucket.
  */
-function resolveCurrentModel(store) {
-    let bestDate = '';
-    let bestModel = null;
-    for (const record of Object.values(store.entries)) {
-        for (const entry of record.offered.log) {
-            if (entry.model && entry.date >= bestDate) {
-                bestDate = entry.date;
-                bestModel = entry.model;
-            }
-        }
-    }
-    return bestModel;
+function resolveCurrentModel(explicit) {
+    return (0, learning_usage_store_1.normalizeModelName)(explicit) ?? (0, learning_usage_store_1.normalizeModelName)(process.env.FRAIM_ACTIVE_MODEL);
 }