@mnemom/mnemom 0.17.5 → 0.17.6-next.1

package/dist/lib/statusline.d.ts

@@ -0,0 +1,86 @@
+/**
+ * The `mnemom agent` status-bar savings counter: a Claude Code statusLine command that
+ * prints "mnemom saved ~$X this session".
+ *
+ * The number is the first-run look's estimator (first-run/backtest.ts), applied live to this
+ * session's own transcript: each request priced at API list prices, times the empirical
+ * curve's lower-bound saving rate for its original context. So the counter and the
+ * first-run screen always agree, and it rounds DOWN to the cent.
+ *
+ * Claude Code runs the command on every status update with its status JSON on stdin
+ * (session_id, transcript_path, …). It must be fast, so the transcript is read
+ * incrementally: per session, a state file (~/.mnemom/statusline/<session>.json, 0600)
+ * keeps each file's byte offset and each message id's contribution, and a tick reads at
+ * most MAX_BYTES_PER_TICK of new bytes (a big resumed session catches up over ticks).
+ *
+ * A user's own statusLine is never replaced: the launch passes it in
+ * MNEMOM_STATUSLINE_INNER, it runs with the same stdin, and our segment is appended.
+ * Read-only on every transcript; no network. It lives outside lib/first-run because it runs
+ * the user's own statusLine command, and the first-run code is held to spawning nothing.
+ */
+export declare const STATE_DIR = "statusline";
+export declare const MAX_BYTES_PER_TICK: number;
+/** The launcher passes the user's own statusLine command here. */
+export declare const INNER_ENV = "MNEMOM_STATUSLINE_INNER";
+/** Set to 1 to launch without the counter. */
+export declare const NO_STATUSLINE_ENV = "MNEMOM_AGENT_NO_STATUSLINE";
+export declare const INNER_TIMEOUT_MS = 2000;
+export interface SessionState {
+    v: 1;
+    /** Byte offset read so far, per transcript file. */
+    files: Record<string, number>;
+    /** Per message id: [list-price cost, saving]. A re-written id replaces its old share. */
+    ids: Record<string, [number, number]>;
+    actual: number;
+    saved: number;
+}
+export declare function freshState(): SessionState;
+/** The main transcript, then its subagent transcripts (sorted). */
+export declare function sessionFiles(transcriptPath: string): string[];
+/**
+ * The complete lines of `path` from `offset`, at most `maxBytes` of them, and the offset
+ * after the last complete line. null: the file is unreadable or shorter than `offset`.
+ */
+export declare function readNewLines(path: string, offset: number, maxBytes: number): {
+    lines: Buffer[];
+    next: number;
+} | null;
+/** Read what is new in the session's files into `st`. A file that shrank resets the count. */
+export declare function update(st: SessionState, files: string[], maxBytes?: number): SessionState;
+/** The segment, rounded DOWN to the cent and never below $0.00. */
+export declare function segment(saved: number): string;
+export declare function loadState(path: string): SessionState;
+export declare function saveState(path: string, st: SessionState): void;
+/** Run the user's own statusLine command with the same stdin; its first line, or "". */
+export declare function runInner(command: string, input: string): string;
+export interface RenderDeps {
+    stateDir: string;
+    inner?: string;
+    runInner?: (command: string, input: string) => string;
+}
+/** Claude Code's status JSON → the one status line. Never throws. */
+export declare function render(stdin: string, deps: RenderDeps): string;
+export interface UserStatusLine {
+    command: string;
+    padding?: number;
+}
+/**
+ * The statusLine Claude Code would use without us: the first settings file (highest
+ * precedence first) that sets one. Only a `command` statusLine can be wrapped.
+ */
+export declare function userStatusLine(cwd: string, configDir: string): UserStatusLine | null;
+/**
+ * Launch args + env that add the counter, or null when it should stay off: the opt-out
+ * env, or the user passing their own --settings (two would fight over precedence).
+ */
+export declare function statuslineLaunch(o: {
+    passthrough: readonly string[];
+    env: NodeJS.ProcessEnv;
+    cwd: string;
+    home?: string;
+    node: string;
+    bin: string;
+}): {
+    args: string[];
+    env: Record<string, string>;
+} | null;

package/dist/lib/statusline.js

@@ -0,0 +1,240 @@
+/**
+ * The `mnemom agent` status-bar savings counter: a Claude Code statusLine command that
+ * prints "mnemom saved ~$X this session".
+ *
+ * The number is the first-run look's estimator (first-run/backtest.ts), applied live to this
+ * session's own transcript: each request priced at API list prices, times the empirical
+ * curve's lower-bound saving rate for its original context. So the counter and the
+ * first-run screen always agree, and it rounds DOWN to the cent.
+ *
+ * Claude Code runs the command on every status update with its status JSON on stdin
+ * (session_id, transcript_path, …). It must be fast, so the transcript is read
+ * incrementally: per session, a state file (~/.mnemom/statusline/<session>.json, 0600)
+ * keeps each file's byte offset and each message id's contribution, and a tick reads at
+ * most MAX_BYTES_PER_TICK of new bytes (a big resumed session catches up over ticks).
+ *
+ * A user's own statusLine is never replaced: the launch passes it in
+ * MNEMOM_STATUSLINE_INNER, it runs with the same stdin, and our segment is appended.
+ * Read-only on every transcript; no network. It lives outside lib/first-run because it runs
+ * the user's own statusLine command, and the first-run code is held to spawning nothing.
+ */
+import { execSync } from "node:child_process";
+import { closeSync, fstatSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, renameSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { origContext, parseUsageLine, rowCost, ruleRate } from "./first-run/backtest.js";
+import { parseJson } from "./first-run/lines.js";
+export const STATE_DIR = "statusline";
+export const MAX_BYTES_PER_TICK = 8 * 1024 * 1024;
+/** The launcher passes the user's own statusLine command here. */
+export const INNER_ENV = "MNEMOM_STATUSLINE_INNER";
+/** Set to 1 to launch without the counter. */
+export const NO_STATUSLINE_ENV = "MNEMOM_AGENT_NO_STATUSLINE";
+export const INNER_TIMEOUT_MS = 2000;
+export function freshState() {
+    return { v: 1, files: {}, ids: {}, actual: 0, saved: 0 };
+}
+/** The main transcript, then its subagent transcripts (sorted). */
+export function sessionFiles(transcriptPath) {
+    const dir = join(transcriptPath.replace(/\.jsonl$/, ""), "subagents");
+    let subs = [];
+    try {
+        subs = readdirSync(dir)
+            .filter((f) => f.endsWith(".jsonl"))
+            .sort()
+            .map((f) => join(dir, f));
+    }
+    catch {
+        /* no subagents */
+    }
+    return [transcriptPath, ...subs];
+}
+/**
+ * The complete lines of `path` from `offset`, at most `maxBytes` of them, and the offset
+ * after the last complete line. null: the file is unreadable or shorter than `offset`.
+ */
+export function readNewLines(path, offset, maxBytes) {
+    let fd;
+    try {
+        fd = openSync(path, "r");
+    }
+    catch {
+        return null;
+    }
+    try {
+        const size = fstatSync(fd).size;
+        if (size < offset)
+            return null;
+        const n = Math.min(size - offset, maxBytes);
+        if (n <= 0)
+            return { lines: [], next: offset };
+        const buf = Buffer.allocUnsafe(n);
+        const got = readSync(fd, buf, 0, n, offset);
+        const view = buf.subarray(0, got);
+        const last = view.lastIndexOf(0x0a);
+        // One line longer than the whole budget: skip past it rather than stall forever.
+        if (last === -1)
+            return { lines: [], next: got === maxBytes ? offset + got : offset };
+        const lines = [];
+        let start = 0;
+        for (let nl = view.indexOf(0x0a); nl !== -1 && nl <= last; nl = view.indexOf(0x0a, start)) {
+            lines.push(view.subarray(start, nl));
+            start = nl + 1;
+        }
+        return { lines, next: offset + last + 1 };
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** Read what is new in the session's files into `st`. A file that shrank resets the count. */
+export function update(st, files, maxBytes = MAX_BYTES_PER_TICK) {
+    let budget = maxBytes;
+    for (const f of files) {
+        if (budget <= 0)
+            break;
+        const from = st.files[f] ?? 0;
+        const r = readNewLines(f, from, budget);
+        if (r === null) {
+            if (from > 0)
+                return update(freshState(), files, maxBytes);
+            continue;
+        }
+        budget -= r.next - from;
+        const subagent = f.includes("/subagents/");
+        r.lines.forEach((line, i) => {
+            const p = parseUsageLine(line, subagent);
+            if (!p)
+                return;
+            const key = p.id ?? `anon-${f}-${from}-${i}`;
+            const cost = rowCost(p.row);
+            const saved = ruleRate(origContext(p.row)).screen * cost;
+            const prev = st.ids[key];
+            if (prev) {
+                st.actual -= prev[0];
+                st.saved -= prev[1];
+            }
+            st.ids[key] = [cost, saved];
+            st.actual += cost;
+            st.saved += saved;
+        });
+        st.files[f] = r.next;
+    }
+    return st;
+}
+/** The segment, rounded DOWN to the cent and never below $0.00. */
+export function segment(saved) {
+    const cents = Math.max(Math.floor(saved * 100 + 1e-9), 0);
+    return `mnemom saved ~$${(cents / 100).toFixed(2)} this session`;
+}
+function statePath(stateDir, sessionId) {
+    return join(stateDir, `${sessionId.replace(/[^A-Za-z0-9_-]/g, "_")}.json`);
+}
+export function loadState(path) {
+    try {
+        const v = parseJson(readFileSync(path, "utf8"));
+        if (v && v.v === 1 && v.files && v.ids)
+            return v;
+    }
+    catch {
+        /* none yet */
+    }
+    return freshState();
+}
+export function saveState(path, st) {
+    mkdirSync(join(path, ".."), { recursive: true, mode: 0o700 });
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(st), { mode: 0o600 });
+    renameSync(tmp, path);
+}
+/** Run the user's own statusLine command with the same stdin; its first line, or "". */
+export function runInner(command, input) {
+    try {
+        const out = execSync(command, {
+            input,
+            encoding: "utf8",
+            timeout: INNER_TIMEOUT_MS,
+            stdio: ["pipe", "pipe", "ignore"],
+        });
+        return (out.split("\n")[0] ?? "").trimEnd();
+    }
+    catch {
+        return "";
+    }
+}
+/** Claude Code's status JSON → the one status line. Never throws. */
+export function render(stdin, deps) {
+    const innerOut = deps.inner ? (deps.runInner ?? runInner)(deps.inner, stdin) : "";
+    let seg = "mnemom";
+    try {
+        const d = parseJson(stdin);
+        const tp = typeof d?.transcript_path === "string" ? d.transcript_path : null;
+        const sid = typeof d?.session_id === "string" && d.session_id ? d.session_id : null;
+        if (tp && sid) {
+            const path = statePath(deps.stateDir, sid);
+            const st = update(loadState(path), sessionFiles(tp));
+            seg = segment(st.saved);
+            try {
+                saveState(path, st);
+            }
+            catch {
+                /* an unwritable state dir only means the next tick re-reads */
+            }
+        }
+    }
+    catch {
+        /* the counter never breaks the status bar */
+    }
+    return innerOut ? `${innerOut} · ${seg}` : seg;
+}
+/**
+ * The statusLine Claude Code would use without us: the first settings file (highest
+ * precedence first) that sets one. Only a `command` statusLine can be wrapped.
+ */
+export function userStatusLine(cwd, configDir) {
+    for (const p of [
+        join(cwd, ".claude", "settings.local.json"),
+        join(cwd, ".claude", "settings.json"),
+        join(configDir, "settings.json"),
+    ]) {
+        let d;
+        try {
+            d = parseJson(readFileSync(p, "utf8"));
+        }
+        catch {
+            continue;
+        }
+        const sl = d?.statusLine;
+        if (!sl || typeof sl !== "object")
+            continue;
+        if (sl.type !== "command" || typeof sl.command !== "string" || !sl.command)
+            return null;
+        return typeof sl.padding === "number"
+            ? { command: sl.command, padding: sl.padding }
+            : { command: sl.command };
+    }
+    return null;
+}
+const sq = (s) => `'${s.replace(/'/g, `'\\''`)}'`;
+/**
+ * Launch args + env that add the counter, or null when it should stay off: the opt-out
+ * env, or the user passing their own --settings (two would fight over precedence).
+ */
+export function statuslineLaunch(o) {
+    if (o.env[NO_STATUSLINE_ENV] === "1")
+        return null;
+    if (o.passthrough.some((a) => a === "--settings" || a.startsWith("--settings=")))
+        return null;
+    const configDir = o.env.CLAUDE_CONFIG_DIR || join(o.home ?? homedir(), ".claude");
+    const user = userStatusLine(o.cwd, configDir);
+    const statusLine = {
+        type: "command",
+        command: `${sq(o.node)} ${sq(o.bin)}`,
+    };
+    if (user?.padding !== undefined)
+        statusLine.padding = user.padding;
+    return {
+        args: ["--settings", JSON.stringify({ statusLine })],
+        env: user ? { [INNER_ENV]: user.command } : {},
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnemom/mnemom",
-  "version": "0.17.5",
+  "version": "0.17.6-next.1",
   "description": "Transparent AI agent tracing",
   "type": "module",
   "bin": {