@mnemom/mnemom 0.17.15-next.0 → 0.17.16-next.0

package/dist/commands/agent.d.ts

@@ -251,6 +251,8 @@ export interface ResolvedCli {
     /** The basename, e.g. "claude" — selects the launch adapter. */
     name: string;
 }
+/** The CLI asked for — `--cli`, else MNEMOM_AGENT_CLI, else "claude" — before any lookup. */
+export declare function requestedCli(cliOpt: string | undefined, env: NodeJS.ProcessEnv): string;
 /**
  * Resolve which coding-agent CLI to launch. `--cli` (or MNEMOM_AGENT_CLI) is a
  * name or a full path; default "claude". A value with a path separator is used

package/dist/commands/agent.js

@@ -31,7 +31,7 @@ import { randomUUID } from "node:crypto";
 import { tmpdir, homedir, hostname, userInfo } from "node:os";
 import { basename, join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
-import { statuslineLaunch } from "../lib/statusline.js";
+import { MEASURED_ENV, statuslineLaunch } from "../lib/statusline.js";
 import { getApiUrl, getGatewayUrl, MNEMOM_DIR } from "../lib/config.js";
 import { createApiKey } from "../lib/api.js";
 import { MNEMOM_KEY_STORE_FIELD, resolveAgentAuth, resolveSubscriptionMnemomKey, subscriptionChildEnv, subscriptionShape, } from "../lib/subscription-login.js";
@@ -46,7 +46,7 @@ import { authConfigured, chooseAuth, detectClaudeLogin, readClaudeLoginState, }
 import { requireConsoleKey, readConsoleKey } from "../lib/console-key.js";
 import { goalAlignmentLine, resolveSessionSetup } from "./agent-session.js";
 import { defaultAgentSlug, ensureClaimedServedAgent, ensureSessionAndBalance, isQuietPreambleExit, resolveDefaultSlug, resolvePreflightedAccount, } from "./agent-setup.js";
-import { assembleContract, buildGoalModeHeader, buildCustomHeaders, buildHandoffMcpConfigJson, buildSessionConfig, buildSessionConfigB64, assertCompactAtCompatible, assertOffProfileCompatible, compactAtWindowWarning, describeCompactAt, launchWindow, resolveCompactAt, applyGatewayHintHeaders, resolveCompactionIntercept, resolveContextHandoff, resolveContextProfile, resolveHandoffGatewayHost, HANDOFF_RC_KEY_ENV_NAME, isProdGateway, launchPreferenceExplicit, launchPreflighted, remoteControlAllowed, applyToolSearchDefault, DISABLE_1M_ENV, readCcSettings, resolveWindowModel, resolveAnthropicDoor, resolveLaunchModel, resolveConversationId, resolveGatewayHost, singleCellError, resolveLaunchShape, resolveRemoteControlShape, passthroughName, sanitizeAgentName, resumeCommand, sessionDisplayName, SESSION_NAME_ENV, SESSION_CONFIG_HEADER, } from "../lib/agent.js";
+import { assembleContract, buildGoalModeHeader, buildCustomHeaders, buildHandoffMcpConfigJson, buildSessionConfig, buildSessionConfigB64, assertCompactAtCompatible, assertOffProfileCompatible, compactAtWindowWarning, describeCompactAt, launchWindow, resolveCompactAt, applyGatewayHintHeaders, resolveCompactionIntercept, resolveContextHandoff, resolveContextProfile, resolveHandoffGatewayHost, resolveUsageSavings, HANDOFF_RC_KEY_ENV_NAME, isProdGateway, launchPreferenceExplicit, launchPreflighted, remoteControlAllowed, applyToolSearchDefault, DISABLE_1M_ENV, readCcSettings, resolveWindowModel, resolveAnthropicDoor, resolveLaunchModel, resolveConversationId, resolveGatewayHost, singleCellError, resolveLaunchShape, resolveRemoteControlShape, passthroughName, sanitizeAgentName, resumeCommand, sessionDisplayName, SESSION_NAME_ENV, SESSION_CONFIG_HEADER, } from "../lib/agent.js";
 import { LAUNCHER_STORE_PATH, mergeStore } from "../lib/launcher-store.js";
 import { slackChannelArgs } from "../lib/slack-launch.js";
 /** The CLI's own provider-key store (zero 1Password): ~/.mnemom/launcher.json, 0600. */
@@ -232,17 +232,24 @@ export async function agentCommand(scenarioArg, options = {}) {
         compactAt: options.compactAt,
     });
     const experimental = options.experimental ?? [];
+    // Decided from the REQUESTED CLI: the header is built before the executable is resolved.
+    const usageSavings = resolveUsageSavings({
+        experimental,
+        cliName: basename(requestedCli(options.cli, env)),
+    });
     const sessionConfig = buildSessionConfig({
         profile: contextProfile,
         contextHandoff,
         compactionIntercept,
         compactAt,
+        usageSavings,
     });
     let sessionConfigB64 = buildSessionConfigB64({
         profile: contextProfile,
         contextHandoff,
         compactionIntercept,
         compactAt,
+        usageSavings,
         experimental,
     });
     const expNotice = experimentalNotice(experimental);
@@ -269,7 +276,7 @@ export async function agentCommand(scenarioArg, options = {}) {
     if (options.dryRun) {
         const planCli = cli ?? {
             bin: "(not found — pass --cli <path> or `mnemom agent config set cli <path>`)",
-            name: basename((options.cli || env.MNEMOM_AGENT_CLI || "claude").trim()),
+            name: basename(requestedCli(options.cli, env)),
         };
         // A defaulted slug is `agent-<handle>` from the login (resolved for real after
         // sign-in, below). Signed in: show that name. Signed out, or no usable handle:
@@ -475,6 +482,7 @@ export async function agentCommand(scenarioArg, options = {}) {
                 contextHandoff,
                 compactionIntercept,
                 compactAt,
+                usageSavings,
                 experimental,
             });
         }
@@ -571,6 +579,7 @@ export async function agentCommand(scenarioArg, options = {}) {
             envelope,
             goalMode,
             sessionConfigB64,
+            usageSavings,
             options: launchOptions,
             yolo,
             contextHint,
@@ -923,6 +932,10 @@ function storeKey(key) {
         // best effort — the launch proceeds with the in-memory key either way
     }
 }
+/** The CLI asked for — `--cli`, else MNEMOM_AGENT_CLI, else "claude" — before any lookup. */
+export function requestedCli(cliOpt, env) {
+    return (cliOpt || env.MNEMOM_AGENT_CLI || "claude").trim();
+}
 /**
  * Resolve which coding-agent CLI to launch. `--cli` (or MNEMOM_AGENT_CLI) is a
  * name or a full path; default "claude". A value with a path separator is used
@@ -932,7 +945,7 @@ function storeKey(key) {
  * a non-claude executable is launched through it with a warning.
  */
 export function resolveCliBin(cliOpt, env) {
-    const requested = (cliOpt || env.MNEMOM_AGENT_CLI || "claude").trim();
+    const requested = requestedCli(cliOpt, env);
     const name = basename(requested);
     if (requested.includes("/")) {
         if (existsSync(requested))
@@ -985,7 +998,7 @@ export /**
  * so they never retype it). A non-interactive session re-throws the clear,
  * actionable error rather than hanging on a prompt.
  */ async function promptForCliPath(cliOpt, env, origErr) {
-    const requested = (cliOpt || env.MNEMOM_AGENT_CLI || "claude").trim();
+    const requested = requestedCli(cliOpt, env);
     if (!isInteractive()) {
         throw origErr ?? new Error(`mnemom agent: coding-agent CLI '${requested}' not found.`);
     }
@@ -1121,7 +1134,9 @@ function launchTerminal(ctx) {
     if (ctx.options.slack)
         args.push(...slackChannelArgs(sessionName));
     // The status-bar savings counter (lib/statusline.ts). Claude Code only; the
-    // user's own statusLine keeps running in front of it.
+    // user's own statusLine keeps running in front of it. Measured mode is this launch's
+    // decision alone: a value inherited from an outer `mnemom agent` session never rides along.
+    Reflect.deleteProperty(childEnv, MEASURED_ENV);
     if (ctx.cli.name === "claude") {
         const sl = statuslineLaunch({
             passthrough: ctx.options.passthrough ?? [],
@@ -1129,6 +1144,7 @@ function launchTerminal(ctx) {
             cwd: process.cwd(),
             node: process.execPath,
             bin: join(dirname(fileURLToPath(import.meta.url)), "..", "lib", "statusline-bin.js"),
+            measured: ctx.usageSavings,
         });
         if (sl) {
             args.push(...sl.args);

package/dist/lib/agent.d.ts

@@ -325,6 +325,15 @@ export declare const CONTEXT_SIZE_POLICY_KEY = "CONTEXT_RUNTIME_SIZE_POLICY";
  */
 export declare const USAGE_REAL_SIZE_KEY = "GATEWAY_USAGE_REAL_SIZE";
 export declare const COMPACTION_INTERCEPT_KEY = "GATEWAY_COMPACTION_INTERCEPT";
+/**
+ * The gateway env key that has it measure each request's saving for a single session and put
+ * it in the client-facing usage (`mnemom_savings` in the read `usage.iterations` entry), where
+ * the status bar reads it from Claude Code's transcript. Default OFF on the gateway; sent `"on"`
+ * only while the `measured-savings` experimental feature is on and the launched CLI is Claude
+ * Code (`resolveUsageSavings`). Independent of folding, so every profile sends it — `off` too,
+ * where the measured saving is honestly $0.00.
+ */
+export declare const USAGE_SAVINGS_KEY = "GATEWAY_USAGE_SAVINGS";
 /**
  * The named presets for how the gateway folds a session's context (`--context-profile`,
  * launcher.toml `context_profile`, `MNEMOM_AGENT_CONTEXT_PROFILE`). Choosing NONE sends no fold
@@ -607,6 +616,7 @@ export declare function resolveContextProfile(opts: {
  * (`CONTEXT_RUNTIME_ENABLED: "false"` + real-size and intercept `"off"` for `off`; the three fold-tuning keys + size policy off for
  * `aggressive`; size policy off for `balanced`; size policy banded for `adaptive`; nothing when
  * no profile was chosen), then `CONTEXT_HANDOFF_ENABLED: "true"` when context handoff is ON, then
+ * `GATEWAY_USAGE_SAVINGS: "on"` when measured savings is ON (under every profile), then
  * `GATEWAY_USAGE_REAL_SIZE: "on"` + `GATEWAY_COMPACTION_INTERCEPT: "on"` when EITHER the
  * `compaction_intercept` setting is ON OR `--compact-at` arms a target below 1M (the target
  * cannot be honored without the intercept), then `GATEWAY_COMPACTION_UPLOAD_TARGET_TOKENS: "<N>"`
@@ -623,6 +633,8 @@ export declare function buildSessionConfig(opts: {
     compactionIntercept?: boolean;
     /** `resolveCompactAt` output: `null` (or absent) ⇒ no target, send nothing new. */
     compactAt?: number | null;
+    /** `resolveUsageSavings` output: true ⇒ the gateway measures the session's saving. */
+    usageSavings?: boolean;
 }): Record<string, string>;
 /**
  * The `x-mnemom-session-config` payload: `{ v: 1, config, experimental? }`. The active
@@ -634,6 +646,7 @@ export declare function buildSessionConfigPayload(opts: {
     contextHandoff: boolean;
     compactionIntercept?: boolean;
     compactAt?: number | null;
+    usageSavings?: boolean;
     experimental?: readonly string[];
 }): {
     v: 1;
@@ -656,7 +669,8 @@ export declare function buildSessionConfigPayload(opts: {
  *   - `contextHandoff: true` → `CONTEXT_HANDOFF_ENABLED: "true"` (the `context_handoff`
  *     setting) — the SAME header the `handoff` MCP tool's own call to
  *     `/mnemom/context/handoff` must also send, since the gateway resolves the flag
- *     per request (see `commands/agent.ts` handoff MCP wiring).
+ *     per request (see `commands/agent.ts` handoff MCP wiring);
+ *   - `usageSavings: true` → `GATEWAY_USAGE_SAVINGS: "on"` (`resolveUsageSavings`).
  * base64url so it survives the gateway's inbound strip.
  */
 export declare function buildSessionConfigB64(opts: {
@@ -664,6 +678,7 @@ export declare function buildSessionConfigB64(opts: {
     contextHandoff: boolean;
     compactionIntercept?: boolean;
     compactAt?: number | null;
+    usageSavings?: boolean;
     experimental?: readonly string[];
 }): string | undefined;
 /**
@@ -689,6 +704,16 @@ export declare function resolveCompactionIntercept(opts: {
     compactionIntercept?: boolean;
     env?: NodeJS.ProcessEnv;
 }): boolean;
+/**
+ * Does the gateway measure this launch's saving (`GATEWAY_USAGE_SAVINGS` in the header, and the
+ * status bar in measured mode)? Only with the `measured-savings` experimental feature on, and
+ * only for Claude Code — the one CLI whose status bar reads the measurement. No flag or
+ * launcher.toml key: `mnemom experimental enable measured-savings` is the switch.
+ */
+export declare function resolveUsageSavings(opts: {
+    experimental: readonly string[];
+    cliName: string;
+}): boolean;
 /** The name the `handoff` MCP tool server is registered under in `--mcp-config`. */
 export declare const HANDOFF_MCP_SERVER_NAME = "mnemom-handoff";
 /**

package/dist/lib/agent.js

@@ -487,6 +487,15 @@ export const CONTEXT_SIZE_POLICY_KEY = "CONTEXT_RUNTIME_SIZE_POLICY";
  */
 export const USAGE_REAL_SIZE_KEY = "GATEWAY_USAGE_REAL_SIZE";
 export const COMPACTION_INTERCEPT_KEY = "GATEWAY_COMPACTION_INTERCEPT";
+/**
+ * The gateway env key that has it measure each request's saving for a single session and put
+ * it in the client-facing usage (`mnemom_savings` in the read `usage.iterations` entry), where
+ * the status bar reads it from Claude Code's transcript. Default OFF on the gateway; sent `"on"`
+ * only while the `measured-savings` experimental feature is on and the launched CLI is Claude
+ * Code (`resolveUsageSavings`). Independent of folding, so every profile sends it — `off` too,
+ * where the measured saving is honestly $0.00.
+ */
+export const USAGE_SAVINGS_KEY = "GATEWAY_USAGE_SAVINGS";
 /**
  * The named presets for how the gateway folds a session's context (`--context-profile`,
  * launcher.toml `context_profile`, `MNEMOM_AGENT_CONTEXT_PROFILE`). Choosing NONE sends no fold
@@ -997,6 +1006,7 @@ export function resolveContextProfile(opts) {
  * (`CONTEXT_RUNTIME_ENABLED: "false"` + real-size and intercept `"off"` for `off`; the three fold-tuning keys + size policy off for
  * `aggressive`; size policy off for `balanced`; size policy banded for `adaptive`; nothing when
  * no profile was chosen), then `CONTEXT_HANDOFF_ENABLED: "true"` when context handoff is ON, then
+ * `GATEWAY_USAGE_SAVINGS: "on"` when measured savings is ON (under every profile), then
  * `GATEWAY_USAGE_REAL_SIZE: "on"` + `GATEWAY_COMPACTION_INTERCEPT: "on"` when EITHER the
  * `compaction_intercept` setting is ON OR `--compact-at` arms a target below 1M (the target
  * cannot be honored without the intercept), then `GATEWAY_COMPACTION_UPLOAD_TARGET_TOKENS: "<N>"`
@@ -1014,6 +1024,9 @@ export function buildSessionConfig(opts) {
     }
     if (opts.contextHandoff)
         config[CONTEXT_HANDOFF_KEY] = "true";
+    // Before the `off` return: measuring is not folding, so an off session sends it too.
+    if (opts.usageSavings)
+        config[USAGE_SAVINGS_KEY] = "on";
     const hasCompactionTarget = opts.compactAt !== undefined && opts.compactAt !== null;
     // A target needs the compaction intercept + real-size rewrite to arm (#2216) — without them
     // the upload-target key is silently inert (compaction-align.ts: "armed only inside the
@@ -1059,7 +1072,8 @@ export function buildSessionConfigPayload(opts) {
  *   - `contextHandoff: true` → `CONTEXT_HANDOFF_ENABLED: "true"` (the `context_handoff`
  *     setting) — the SAME header the `handoff` MCP tool's own call to
  *     `/mnemom/context/handoff` must also send, since the gateway resolves the flag
- *     per request (see `commands/agent.ts` handoff MCP wiring).
+ *     per request (see `commands/agent.ts` handoff MCP wiring);
+ *   - `usageSavings: true` → `GATEWAY_USAGE_SAVINGS: "on"` (`resolveUsageSavings`).
  * base64url so it survives the gateway's inbound strip.
  */
 export function buildSessionConfigB64(opts) {
@@ -1099,6 +1113,15 @@ export function resolveCompactionIntercept(opts) {
         return false;
     return raw === "1" || raw === "true" || raw === "on" || raw === "yes";
 }
+/**
+ * Does the gateway measure this launch's saving (`GATEWAY_USAGE_SAVINGS` in the header, and the
+ * status bar in measured mode)? Only with the `measured-savings` experimental feature on, and
+ * only for Claude Code — the one CLI whose status bar reads the measurement. No flag or
+ * launcher.toml key: `mnemom experimental enable measured-savings` is the switch.
+ */
+export function resolveUsageSavings(opts) {
+    return opts.experimental.includes("measured-savings") && opts.cliName === "claude";
+}
 /** The name the `handoff` MCP tool server is registered under in `--mcp-config`. */
 export const HANDOFF_MCP_SERVER_NAME = "mnemom-handoff";
 /**

package/dist/lib/experimental.d.ts

@@ -12,7 +12,7 @@
  * Everything here is pure or dependency-injected; index.ts and the command
  * modules are the thin drivers.
  */
-export type ExperimentalId = "context-handoff" | "slack" | "implicit" | "compaction-intercept";
+export type ExperimentalId = "context-handoff" | "slack" | "implicit" | "compaction-intercept" | "measured-savings";
 /**
  * Is a `compact_at` / `MNEMOM_COMPACT_AT` value (trimmed, case-insensitive) an ARMED gateway
  * target, as opposed to "no target" (`""`, `"1m"`, `"off"`)? Deliberately duplicates

package/dist/lib/experimental.js

@@ -69,6 +69,18 @@ export const EXPERIMENTAL_FEATURES = [
             env: ["MNEMOM_AGENT_COMPACTION_INTERCEPT"],
         },
     },
+    {
+        // No flag, launcher.toml key or env of its own: `mnemom experimental enable` is the switch.
+        id: "measured-savings",
+        summary: "The status bar shows the saving the gateway measured on this session instead of the benchmark estimate",
+        since: "0.17.16",
+        gates: {
+            flags: [],
+            configKeys: [],
+            commands: [],
+            env: [],
+        },
+    },
 ];
 export const EXPERIMENTAL_IDS = EXPERIMENTAL_FEATURES.map((f) => f.id);
 export const EXPERIMENTAL_ENV = "MNEMOM_EXPERIMENTAL";

package/dist/lib/statusline-bin.js

@@ -4,13 +4,14 @@
  */
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { INNER_ENV, render } from "./statusline.js";
+import { INNER_ENV, measuredMode, render } from "./statusline.js";
 const chunks = [];
 process.stdin.on("data", (c) => chunks.push(c));
 process.stdin.on("end", () => {
     const line = render(Buffer.concat(chunks).toString("utf8"), {
         stateDir: join(homedir(), ".mnemom", "statusline"),
         inner: process.env[INNER_ENV] || undefined,
+        measured: measuredMode(process.env),
     });
     process.stdout.write(`${line}\n`);
 });

package/dist/lib/statusline.d.ts

@@ -13,6 +13,15 @@
  * 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).
  *
+ * Measured mode (the `measured-savings` experimental feature; the launch sets
+ * MNEMOM_STATUSLINE_MEASURED=1): the gateway measures each request's saving — the stock
+ * request's input cost minus what it billed — and writes it into the response usage as
+ * `mnemom_savings` inside a `usage.iterations` entry, the one place Claude Code keeps an
+ * unknown usage key in its transcript. The counter sums those per message id
+ * ("mnemom saved $X this session", no "~": it is measured) and makes no claim before the
+ * first one arrives. Its state lives in its own file (<session>.measured.json), so the two
+ * modes never share a count.
+ *
  * 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
@@ -24,6 +33,8 @@ export declare const MAX_BYTES_PER_TICK: number;
 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";
+/** The launcher sets this to 1 when the gateway measures the session's saving. */
+export declare const MEASURED_ENV = "MNEMOM_STATUSLINE_MEASURED";
 export declare const INNER_TIMEOUT_MS = 2000;
 export interface SessionState {
     v: 1;
@@ -35,6 +46,17 @@ export interface SessionState {
     saved: number;
 }
 export declare function freshState(): SessionState;
+/** Measured mode's state (<session>.measured.json). */
+export interface MeasuredState {
+    v: 1;
+    files: Record<string, number>;
+    /** Per message id: the gateway's measured saving (USD). A re-written id replaces its old share. */
+    ids: Record<string, number>;
+    saved: number;
+    /** Has any record carried a measurement yet? Until then the segment makes no claim. */
+    seen: boolean;
+}
+export declare function freshMeasuredState(): MeasuredState;
 /** The main transcript, then its subagent transcripts (sorted). */
 export declare function sessionFiles(transcriptPath: string): string[];
 /**
@@ -47,17 +69,38 @@ export declare function readNewLines(path: string, offset: number, maxBytes: num
 } | 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;
+/** A `usage.iterations` entry's measured saving (`mnemom_savings` v1), or null. */
+export declare function measuredSaving(entry: unknown): number | null;
+/**
+ * One transcript line → the gateway's measured saving for its request, or null (not an
+ * assistant record, or no measurement in its `message.usage.iterations`). `id` is the message
+ * id (or record uuid); null when the record carries neither. Claude Code writes one record per
+ * content block, all with the same id and usage, so the id is what dedupes them.
+ */
+export declare function parseMeasuredLine(line: Buffer): {
+    id: string | null;
+    saved: number;
+} | null;
+/** Measured mode's `update`: sums each request's measured saving, replace-by-id. */
+export declare function updateMeasured(st: MeasuredState, files: string[], maxBytes?: number): MeasuredState;
 /** The segment, rounded DOWN to the cent and never below $0.00. */
 export declare function segment(saved: number): string;
+/** Measured mode's segment: no claim until the gateway has measured something; no "~". */
+export declare function measuredSegment(st: MeasuredState): string;
 export declare function loadState(path: string): SessionState;
-export declare function saveState(path: string, st: SessionState): void;
+export declare function loadMeasuredState(path: string): MeasuredState;
+export declare function saveState(path: string, st: SessionState | MeasuredState): 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;
+    /** Measured mode (`measuredMode`): the gateway's measured saving, not the estimate. */
+    measured?: boolean;
     runInner?: (command: string, input: string) => string;
 }
+/** Is the counter in measured mode? The launch's MEASURED_ENV, exactly "1". */
+export declare function measuredMode(env: NodeJS.ProcessEnv): boolean;
 /** Claude Code's status JSON → the one status line. Never throws. */
 export declare function render(stdin: string, deps: RenderDeps): string;
 export interface UserStatusLine {
@@ -72,6 +115,7 @@ export declare function userStatusLine(cwd: string, configDir: string): UserStat
 /**
  * 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).
+ * `measured` puts the counter in measured mode (MEASURED_ENV).
  */
 export declare function statuslineLaunch(o: {
     passthrough: readonly string[];
@@ -80,6 +124,7 @@ export declare function statuslineLaunch(o: {
     home?: string;
     node: string;
     bin: string;
+    measured?: boolean;
 }): {
     args: string[];
     env: Record<string, string>;

package/dist/lib/statusline.js

@@ -13,6 +13,15 @@
  * 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).
  *
+ * Measured mode (the `measured-savings` experimental feature; the launch sets
+ * MNEMOM_STATUSLINE_MEASURED=1): the gateway measures each request's saving — the stock
+ * request's input cost minus what it billed — and writes it into the response usage as
+ * `mnemom_savings` inside a `usage.iterations` entry, the one place Claude Code keeps an
+ * unknown usage key in its transcript. The counter sums those per message id
+ * ("mnemom saved $X this session", no "~": it is measured) and makes no claim before the
+ * first one arrives. Its state lives in its own file (<session>.measured.json), so the two
+ * modes never share a count.
+ *
  * 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
@@ -30,10 +39,15 @@ export const MAX_BYTES_PER_TICK = 8 * 1024 * 1024;
 export const INNER_ENV = "MNEMOM_STATUSLINE_INNER";
 /** Set to 1 to launch without the counter. */
 export const NO_STATUSLINE_ENV = "MNEMOM_AGENT_NO_STATUSLINE";
+/** The launcher sets this to 1 when the gateway measures the session's saving. */
+export const MEASURED_ENV = "MNEMOM_STATUSLINE_MEASURED";
 export const INNER_TIMEOUT_MS = 2000;
 export function freshState() {
     return { v: 1, files: {}, ids: {}, actual: 0, saved: 0 };
 }
+export function freshMeasuredState() {
+    return { v: 1, files: {}, ids: {}, saved: 0, seen: false };
+}
 /** The main transcript, then its subagent transcripts (sorted). */
 export function sessionFiles(transcriptPath) {
     const dir = join(transcriptPath.replace(/\.jsonl$/, ""), "subagents");
@@ -87,8 +101,12 @@ export function readNewLines(path, offset, maxBytes) {
         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) {
+/**
+ * The incremental read both modes share: each file's new complete lines, within the tick's
+ * byte budget, go to `add` (with the key a record without an id is counted under). A file
+ * that shrank or vanished starts over from `fresh()`.
+ */
+function readSession(st, files, maxBytes, fresh, add) {
     let budget = maxBytes;
     for (const f of files) {
         if (budget <= 0)
@@ -97,38 +115,97 @@ export function update(st, files, maxBytes = MAX_BYTES_PER_TICK) {
         const r = readNewLines(f, from, budget);
         if (r === null) {
             if (from > 0)
-                return update(freshState(), files, maxBytes);
+                return readSession(fresh(), files, maxBytes, fresh, add);
             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;
-        });
+        r.lines.forEach((line, i) => add(st, line, subagent, `anon-${f}-${from}-${i}`));
         st.files[f] = r.next;
     }
     return st;
 }
+/** 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) {
+    return readSession(st, files, maxBytes, freshState, (s, line, subagent, anonKey) => {
+        const p = parseUsageLine(line, subagent);
+        if (!p)
+            return;
+        const key = p.id ?? anonKey;
+        const cost = rowCost(p.row);
+        const saved = ruleRate(origContext(p.row)).screen * cost;
+        const prev = s.ids[key];
+        if (prev) {
+            s.actual -= prev[0];
+            s.saved -= prev[1];
+        }
+        s.ids[key] = [cost, saved];
+        s.actual += cost;
+        s.saved += saved;
+    });
+}
+const SAVINGS = Buffer.from('"mnemom_savings"');
+const ASSISTANT = Buffer.from('"assistant"');
+/** A `usage.iterations` entry's measured saving (`mnemom_savings` v1), or null. */
+export function measuredSaving(entry) {
+    const m = entry?.mnemom_savings;
+    return m?.v === 1 && Number.isFinite(m.saved_usd) ? m.saved_usd : null;
+}
+/**
+ * One transcript line → the gateway's measured saving for its request, or null (not an
+ * assistant record, or no measurement in its `message.usage.iterations`). `id` is the message
+ * id (or record uuid); null when the record carries neither. Claude Code writes one record per
+ * content block, all with the same id and usage, so the id is what dedupes them.
+ */
+export function parseMeasuredLine(line) {
+    if (line.indexOf(SAVINGS) === -1 || line.indexOf(ASSISTANT) === -1)
+        return null;
+    const d = parseJson(line);
+    if (d?.type !== "assistant")
+        return null;
+    const m = d.message;
+    const iterations = m?.usage?.iterations;
+    if (!Array.isArray(iterations))
+        return null;
+    const saved = iterations.map(measuredSaving).find((v) => v !== null);
+    if (saved === undefined)
+        return null;
+    const id = (typeof m?.id === "string" && m.id) || (typeof d.uuid === "string" && d.uuid) || null;
+    return { id, saved };
+}
+/** Measured mode's `update`: sums each request's measured saving, replace-by-id. */
+export function updateMeasured(st, files, maxBytes = MAX_BYTES_PER_TICK) {
+    return readSession(st, files, maxBytes, freshMeasuredState, (s, line, _subagent, anonKey) => {
+        const p = parseMeasuredLine(line);
+        if (!p)
+            return;
+        const key = p.id ?? anonKey;
+        s.saved += p.saved - (s.ids[key] ?? 0);
+        s.ids[key] = p.saved;
+        s.seen = true;
+    });
+}
+/** USD rounded DOWN to the cent and never below 0.00. */
+function cents(usd) {
+    return (Math.max(Math.floor(usd * 100 + 1e-9), 0) / 100).toFixed(2);
+}
 /** 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`;
+    return `mnemom saved ~$${cents(saved)} this session`;
+}
+/** Measured mode's segment: no claim until the gateway has measured something; no "~". */
+export function measuredSegment(st) {
+    return st.seen ? `mnemom saved $${cents(st.saved)} this session` : "mnemom";
+}
+function stateName(sessionId) {
+    return sessionId.replace(/[^A-Za-z0-9_-]/g, "_");
 }
 function statePath(stateDir, sessionId) {
-    return join(stateDir, `${sessionId.replace(/[^A-Za-z0-9_-]/g, "_")}.json`);
+    return join(stateDir, `${stateName(sessionId)}.json`);
+}
+/** Measured mode's own file: a sanitized id has no ".", so it never collides with statePath. */
+function measuredStatePath(stateDir, sessionId) {
+    return join(stateDir, `${stateName(sessionId)}.measured.json`);
 }
 export function loadState(path) {
     try {
@@ -141,6 +218,18 @@ export function loadState(path) {
     }
     return freshState();
 }
+export function loadMeasuredState(path) {
+    try {
+        const v = parseJson(readFileSync(path, "utf8"));
+        if (v && v.v === 1 && v.files && v.ids && typeof v.seen === "boolean") {
+            return v;
+        }
+    }
+    catch {
+        /* none yet */
+    }
+    return freshMeasuredState();
+}
 export function saveState(path, st) {
     mkdirSync(join(path, ".."), { recursive: true, mode: 0o700 });
     const tmp = `${path}.${process.pid}.tmp`;
@@ -162,6 +251,18 @@ export function runInner(command, input) {
         return "";
     }
 }
+/** Is the counter in measured mode? The launch's MEASURED_ENV, exactly "1". */
+export function measuredMode(env) {
+    return env[MEASURED_ENV] === "1";
+}
+function saveQuietly(path, st) {
+    try {
+        saveState(path, st);
+    }
+    catch {
+        /* an unwritable state dir only means the next tick re-reads */
+    }
+}
 /** 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) : "";
@@ -170,16 +271,17 @@ export function render(stdin, deps) {
         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) {
+        if (tp && sid && deps.measured) {
+            const path = measuredStatePath(deps.stateDir, sid);
+            const st = updateMeasured(loadMeasuredState(path), sessionFiles(tp));
+            seg = measuredSegment(st);
+            saveQuietly(path, st);
+        }
+        else 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 */
-            }
+            saveQuietly(path, st);
         }
     }
     catch {
@@ -219,6 +321,7 @@ 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).
+ * `measured` puts the counter in measured mode (MEASURED_ENV).
  */
 export function statuslineLaunch(o) {
     if (o.env[NO_STATUSLINE_ENV] === "1")
@@ -233,8 +336,8 @@ export function statuslineLaunch(o) {
     };
     if (user?.padding !== undefined)
         statusLine.padding = user.padding;
-    return {
-        args: ["--settings", JSON.stringify({ statusLine })],
-        env: user ? { [INNER_ENV]: user.command } : {},
-    };
+    const env = user ? { [INNER_ENV]: user.command } : {};
+    if (o.measured)
+        env[MEASURED_ENV] = "1";
+    return { args: ["--settings", JSON.stringify({ statusLine })], env };
 }

package/package.json

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