@mnemom/mnemom 0.17.33 → 0.17.34-next.1

package/dist/lib/scan/spend/spend-tiers.js

@@ -0,0 +1,42 @@
+export const ORG_SCAN_ENV = "MNEMOM_ORG_SCAN_MODE";
+/** Default OFF: only the exact string "true" turns the tiers on. */
+export const isSpendTiersEnabled = (env = process.env) => env[ORG_SCAN_ENV] === "true";
+export const NOT_ENABLED_MSG = "The spend fallback is not enabled.";
+export const SPEND_INVALID_MSG = "Monthly spend must be a dollar amount above zero, like 5000.";
+export const SPEND_NO_TERMINAL_MSG = "Pass --monthly-spend <usd> (there is no terminal to ask on).";
+export const MAX_MONTHLY_SPEND_USD = 10_000_000;
+const SPEND_RE = /^\$?\s*(\d{1,3}(,\d{3})+|\d+)(\.\d{1,2})?$/;
+/** Dollars, or null if the text is not a positive, plausible amount. */
+export function parseMonthlySpendUsd(raw) {
+    const t = raw.trim();
+    if (!SPEND_RE.test(t))
+        return null;
+    const n = Number(t.replace(/[$,\s]/g, ""));
+    return Number.isFinite(n) && n > 0 && n <= MAX_MONTHLY_SPEND_USD ? n : null;
+}
+const usd = (n) => `$${n.toLocaleString("en-US", { maximumFractionDigits: 2 })}`;
+const isUsd = (n) => typeof n === "number" && Number.isFinite(n) && n > 0;
+const pct = (f) => `${Math.round(f * 100)}%`;
+const isShare = (n) => typeof n === "number" && Number.isFinite(n) && n >= 0 && n <= 1;
+export function selectSpend(i) {
+    if (isUsd(i.measuredUsd)) {
+        return {
+            tier: 1,
+            line: `Tier 1, measured: ${usd(i.measuredUsd)} of Anthropic usage over the period${isShare(i.over200kShare)
+                ? ` (${pct(i.over200kShare)} of tokens in requests over 200k context)`
+                : ""}.`,
+            shareable: true,
+        };
+    }
+    if (isUsd(i.selfReportedUsd)) {
+        return {
+            tier: 2,
+            line: `Tier 2, self-reported: about ${usd(i.selfReportedUsd)} a month (given by you; not verified, not sent, not saved).`,
+            shareable: false,
+        };
+    }
+    if (i.estimate.kind === "range") {
+        return { tier: 3, line: `Tier 3, ${i.estimate.line}`, shareable: true };
+    }
+    return { tier: null, line: null, shareable: false };
+}

package/dist/lib/scan/spend/token-rate.d.ts

@@ -0,0 +1,30 @@
+/** Rows needed before the rate is trusted at all (data sufficiency, not a group size). */
+export declare const MIN_CORPUS_ROWS = 5;
+export interface CostRowShape {
+    repo: string;
+    pr: number;
+    additions: number;
+    deletions: number;
+    cost_usd: number;
+    runs: number;
+    models: string[];
+}
+export interface TokenRate {
+    /** Price-equivalent tokens per changed (added + deleted) line: 25th percentile. */
+    low: number;
+    median: number;
+    /** 75th percentile. */
+    high: number;
+    rows: number;
+}
+/** Linear-interpolated quantile of a sorted array. */
+export declare function quantile(sorted: number[], q: number): number;
+/**
+ * Derive the rate from corpus rows: per-row tokens/line, then the 25th, 50th and 75th percentile.
+ * Rows that fail validation are dropped (not repaired); fewer than MIN_CORPUS_ROWS valid rows
+ * returns null, never a rate built on a handful.
+ */
+export declare function deriveTokenRate(rows: unknown): TokenRate | null;
+export declare const CORPUS_AS_OF: string;
+/** The shipped rate: derived once from the committed fixture. */
+export declare const DERIVED_TOKEN_RATE: TokenRate | null;

package/dist/lib/scan/spend/token-rate.js

@@ -0,0 +1,54 @@
+// MNE-9268: tokens-per-changed-line and its spread, DERIVED from our own agents' PRs whose run cost is
+// known (cost-corpus.v1.json, built by build-cost-corpus.mjs from the ADW "Run cost" PR comments).
+// Nothing here is a typed-in rate: change the fixture and the rate moves, and token-rate.test.ts pins
+// the derivation. Tokens are price-equivalent: cost / (our model's blended list price per token).
+import rawCorpus from "./cost-corpus.v1.js";
+import { TOOL_PRICES, blendedUsdPerToken } from "./prices.js";
+/** Rows needed before the rate is trusted at all (data sufficiency, not a group size). */
+export const MIN_CORPUS_ROWS = 5;
+/** Our agents ran on Sonnet-family models in every corpus row; price their tokens as that. */
+const BASIS_USD_PER_TOKEN = blendedUsdPerToken(TOOL_PRICES.claude_code.low);
+const isCount = (n) => typeof n === "number" && Number.isFinite(n) && n >= 0;
+function validRow(r) {
+    if (typeof r !== "object" || r === null)
+        return false;
+    const o = r;
+    return (isCount(o.additions) &&
+        isCount(o.deletions) &&
+        o.additions + o.deletions > 0 &&
+        isCount(o.cost_usd) &&
+        o.cost_usd > 0);
+}
+/** Linear-interpolated quantile of a sorted array. */
+export function quantile(sorted, q) {
+    if (sorted.length === 0)
+        return NaN;
+    const pos = (sorted.length - 1) * q;
+    const lo = Math.floor(pos);
+    const hi = Math.ceil(pos);
+    return sorted[lo] + (sorted[hi] - sorted[lo]) * (pos - lo);
+}
+/**
+ * Derive the rate from corpus rows: per-row tokens/line, then the 25th, 50th and 75th percentile.
+ * Rows that fail validation are dropped (not repaired); fewer than MIN_CORPUS_ROWS valid rows
+ * returns null, never a rate built on a handful.
+ */
+export function deriveTokenRate(rows) {
+    if (!Array.isArray(rows))
+        return null;
+    const per = rows
+        .filter(validRow)
+        .map((r) => r.cost_usd / (r.additions + r.deletions) / BASIS_USD_PER_TOKEN)
+        .sort((a, b) => a - b);
+    if (per.length < MIN_CORPUS_ROWS)
+        return null;
+    return {
+        low: quantile(per, 0.25),
+        median: quantile(per, 0.5),
+        high: quantile(per, 0.75),
+        rows: per.length,
+    };
+}
+export const CORPUS_AS_OF = rawCorpus.as_of;
+/** The shipped rate: derived once from the committed fixture. */
+export const DERIVED_TOKEN_RATE = deriveTokenRate(rawCorpus.rows);

package/dist/lib/session-key.d.ts

@@ -66,3 +66,44 @@ export declare function mintSessionGatewayKey(deps: SessionKeyDeps, args: {
  * one. Never called with the owner's own key id.
  */
 export declare function revokeSessionGatewayKey(deps: SessionKeyDeps, keyId: string): Promise<void>;
+/** When to renew a key expiring at `expiresAt`, measured from `now` (ms). */
+export declare function renewDelayMs(expiresAt: string, now: number): number;
+/** What {@link mintSessionGatewayKey} mints for: the same arguments at launch and at each renewal. */
+export interface SessionKeyMintArgs {
+    agentId: string;
+    orgId?: string;
+    sessionId?: string;
+}
+export interface SessionKeyRenewalOptions {
+    /** `say` is where renewal events go: the proxy log, never the terminal the session draws on. */
+    deps: SessionKeyDeps;
+    mintArgs: SessionKeyMintArgs;
+    initial: {
+        keyId: string;
+        expiresAt: string;
+    };
+    /** Hand the new key to the running proxy. Throws when it cannot (the pipe is gone). */
+    deliver: (minted: MintedSessionGatewayKey) => void;
+    /** Tell the proxy its re-mint request failed, so it stops waiting and answers the 401. */
+    refuse: (reason: string) => void;
+    now?: () => number;
+}
+export interface SessionKeyRenewal {
+    /**
+     * Re-mint now. `rejected` is the proxy's request after a gateway 401, naming the key id it sent;
+     * a request about a key that is no longer current is a no-op (the proxy already has the newer
+     * one). Resolves true when a new key was delivered. Never rejects.
+     */
+    renew(reason: "scheduled" | "rejected", rejectedKeyId?: string): Promise<boolean>;
+    /** The key the proxy holds now: the one to revoke on exit. */
+    currentKeyId(): string;
+    stop(): void;
+}
+/**
+ * Keep the proxy's session key fresh: renew at ~80% of its remaining lifetime (floor 60s), retry a
+ * failed renewal every 5 minutes, and after each swap revoke the old key (best effort, like the
+ * exit revoke). Every new key goes through {@link mintSessionGatewayKey}, so a renewal is held to
+ * the same fail-closed checks as the launch: a key that is not exactly a `['gateway']` session key
+ * is never delivered. Logs key ids and expiry times only, never a key.
+ */
+export declare function startSessionKeyRenewal(opts: SessionKeyRenewalOptions): SessionKeyRenewal;

package/dist/lib/session-key.js

@@ -99,3 +99,127 @@ export async function revokeSessionGatewayKey(deps, keyId) {
         deps.say(`mnemom agent: could not revoke the session key (non-fatal — it expires on its own within 24h): ${err instanceof Error ? err.message : String(err)}`);
     }
 }
+// ───────────────────────────────────────────────────────────────────────────
+// Renewal for long-lived Remote Control sessions
+// ───────────────────────────────────────────────────────────────────────────
+//
+// The minted key is 24h-TTL'd, and a `--remote-control` seat outlives that: before this, every
+// model turn failed with the gateway's `401 Invalid Mnemom API key` exactly 24h after launch. The
+// launcher (the CLI PARENT, which holds ambient auth) therefore re-mints before expiry and hands
+// the new key to the running proxy over its control pipe — never argv, env or disk — then revokes
+// the old one. The proxy can also ask for one immediate re-mint when the gateway rejects its key.
+/** Renew once this share of the key's remaining lifetime has passed. */
+const RENEW_AT_FRACTION = 0.8;
+/** Never schedule a renewal sooner than this (a key that is nearly or already expired). */
+const RENEW_FLOOR_MS = 60_000;
+/** The lifetime assumed when `expiresAt` does not parse: the route's documented 24h. */
+const ASSUMED_TTL_MS = 24 * 60 * 60 * 1000;
+/** After a failed renewal, try again this much later. */
+const RENEW_RETRY_MS = 5 * 60 * 1000;
+/**
+ * A re-mint the proxy asks for (its key was rejected) is refused if one was attempted this
+ * recently, so a gateway that keeps rejecting fresh keys cannot turn every request into a mint.
+ */
+const REJECTED_COOLDOWN_MS = 60_000;
+/** setTimeout's ceiling (a larger delay fires at once). */
+const MAX_TIMER_MS = 2 ** 31 - 1;
+/** When to renew a key expiring at `expiresAt`, measured from `now` (ms). */
+export function renewDelayMs(expiresAt, now) {
+    const exp = Date.parse(expiresAt);
+    const left = Number.isFinite(exp) ? exp - now : ASSUMED_TTL_MS;
+    return Math.min(MAX_TIMER_MS, Math.max(RENEW_FLOOR_MS, Math.floor(left * RENEW_AT_FRACTION)));
+}
+/**
+ * Keep the proxy's session key fresh: renew at ~80% of its remaining lifetime (floor 60s), retry a
+ * failed renewal every 5 minutes, and after each swap revoke the old key (best effort, like the
+ * exit revoke). Every new key goes through {@link mintSessionGatewayKey}, so a renewal is held to
+ * the same fail-closed checks as the launch: a key that is not exactly a `['gateway']` session key
+ * is never delivered. Logs key ids and expiry times only, never a key.
+ */
+export function startSessionKeyRenewal(opts) {
+    const now = opts.now ?? Date.now;
+    const say = opts.deps.say;
+    let current = { ...opts.initial };
+    let timer;
+    let inflight;
+    let lastAttempt = Number.NEGATIVE_INFINITY;
+    let stopped = false;
+    const schedule = (ms) => {
+        if (stopped)
+            return;
+        clearTimeout(timer);
+        timer = setTimeout(() => void renew("scheduled"), ms);
+        timer.unref?.();
+    };
+    const attempt = async (reason) => {
+        lastAttempt = now();
+        let minted;
+        try {
+            minted = await mintSessionGatewayKey(opts.deps, opts.mintArgs);
+        }
+        catch (err) {
+            // mintSessionGatewayKey always throws an Error wrapping the mint's own failure in `cause`,
+            // with launch-refusal wording that is wrong mid-session: log the cause when it is an Error.
+            const e = err;
+            const msg = e.cause instanceof Error ? e.cause.message : e.message;
+            say(`session key renewal (${reason}) FAILED: ${msg}; keeping id=${current.keyId} expires=${current.expiresAt}, retrying in ${RENEW_RETRY_MS / 1000}s`);
+            schedule(RENEW_RETRY_MS);
+            return false;
+        }
+        if (stopped) {
+            await revokeSessionGatewayKey(opts.deps, minted.keyId); // nobody will ever use it
+            return false;
+        }
+        try {
+            opts.deliver(minted);
+        }
+        catch (err) {
+            say(`session key renewal (${reason}): could not hand id=${minted.keyId} to the proxy (${err instanceof Error ? err.message : String(err)}); revoking it and keeping id=${current.keyId}`);
+            await revokeSessionGatewayKey(opts.deps, minted.keyId);
+            schedule(RENEW_RETRY_MS);
+            return false;
+        }
+        const old = current;
+        current = { keyId: minted.keyId, expiresAt: minted.expiresAt };
+        say(`session key renewed (${reason}): id=${current.keyId} expires=${current.expiresAt}; revoking id=${old.keyId}`);
+        schedule(renewDelayMs(current.expiresAt, now()));
+        await revokeSessionGatewayKey(opts.deps, old.keyId);
+        return true;
+    };
+    const renew = (reason, rejectedKeyId) => {
+        if (stopped)
+            return Promise.resolve(false);
+        if (reason === "rejected") {
+            // The proxy sent a key that is no longer current: the newer one is already on its way.
+            if (rejectedKeyId && rejectedKeyId !== current.keyId)
+                return Promise.resolve(true);
+            if (!inflight && now() - lastAttempt < REJECTED_COOLDOWN_MS) {
+                say(`session key id=${current.keyId} rejected by the gateway; not re-minting (last attempt under ${REJECTED_COOLDOWN_MS / 1000}s ago)`);
+                opts.refuse("cooldown");
+                return Promise.resolve(false);
+            }
+        }
+        // One mint at a time: a rejection that arrives mid-renewal waits on that renewal.
+        inflight ??= attempt(reason).finally(() => {
+            inflight = undefined;
+        });
+        const p = inflight;
+        if (reason === "rejected") {
+            void p.then((ok) => {
+                if (!ok)
+                    opts.refuse("mint failed");
+            });
+        }
+        return p;
+    };
+    // The launch key's id and expiry are logged by the proxy at startup.
+    schedule(renewDelayMs(current.expiresAt, now()));
+    return {
+        renew,
+        currentKeyId: () => current.keyId,
+        stop: () => {
+            stopped = true;
+            clearTimeout(timer);
+        },
+    };
+}

package/dist/rc-key-401.mjs

@@ -0,0 +1,75 @@
+// rc-key-401 — the Remote Control proxy's handling of a gateway 401 it may be able to fix.
+//
+// A 401 on a buffered /v1/messages request may be the Mnemom session key expiring under a long
+// session (rc-proxy.mjs, SESSION KEY RENEWAL). The proxy holds that 401 back from the client until
+// the whole body is in, then asks isMnemomKeyRejection() whether a fresh key would fix it. Split out
+// of rc-proxy.mjs (a script that reads stdin and listens at import) so each branch is unit-tested
+// (rc-key-401.test.ts). Node ≥ 18, no deps.
+import { Buffer } from "node:buffer";
+import zlib from "node:zlib";
+
+// A held-back 401 body (and its decompressed form) is read up to this size. The gateway's key
+// rejection is a few hundred bytes; anything larger is not one and is streamed to the client as is.
+export const KEY_401_BODY_MAX = 64 * 1024;
+
+// How long a key-rejected request waits for the launcher's re-mint (its mint call is bounded at
+// 10s): MNEMOM_RC_REMINT_WAIT_MS when set and non-empty ("0" included), else 20s.
+export const REMINT_WAIT_DEFAULT_MS = 20_000;
+export function remintWaitMs(env) {
+  const v = env.MNEMOM_RC_REMINT_WAIT_MS;
+  return v ? Number(v) : REMINT_WAIT_DEFAULT_MS;
+}
+
+// Whether a held-back gateway 401 body says the Mnemom key itself was refused (unknown, revoked or
+// expired): the only 401 a fresh key can fix. Anything it cannot decode is not one.
+export function isMnemomKeyRejection(raw, enc, max = KEY_401_BODY_MAX) {
+  let text;
+  try {
+    const b =
+      enc === "gzip" || enc === "x-gzip"
+        ? zlib.gunzipSync(raw, { maxOutputLength: max })
+        : enc === "deflate"
+          ? zlib.inflateSync(raw, { maxOutputLength: max })
+          : enc === "br"
+            ? zlib.brotliDecompressSync(raw, { maxOutputLength: max })
+            : raw;
+    text = b.toString("utf8");
+  } catch {
+    return false;
+  }
+  return /invalid[ _]mnemom[ _](api[ _])?key/i.test(text);
+}
+
+// Hold the upstream response `ur` back from the client response `res`. Up to `max` bytes,
+// `onBody(raw)` gets the whole body at its end and nothing has reached the client. Past `max` the
+// body is not a key rejection: the status, headers and every byte so far go to the client, the rest
+// streams through, and `onOverflow(bytes)` runs at the end. Every write first checks that the client
+// is still there: a hang-up destroys `res` (and, via rc-proxy.mjs, the upstream request), and a
+// chunk already in flight must not write to it.
+export function holdBack401(ur, res, { max = KEY_401_BODY_MAX, onBody, onOverflow }) {
+  const chunks = [];
+  let held = 0;
+  let overflow = false;
+  ur.on("data", (c) => {
+    if (overflow) {
+      if (!res.destroyed) res.write(c);
+      return;
+    }
+    chunks.push(c);
+    held += c.length;
+    if (held > max) {
+      overflow = true;
+      if (res.destroyed) return;
+      res.writeHead(ur.statusCode, ur.headers);
+      for (const x of chunks.splice(0)) res.write(x);
+    }
+  });
+  ur.on("end", () => {
+    if (overflow) {
+      if (!res.destroyed) res.end();
+      onOverflow(held);
+      return;
+    }
+    onBody(Buffer.concat(chunks));
+  });
+}