@mnemom/mnemom 0.17.33 → 0.17.34-next.2

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/lib/subscription-login.d.ts

@@ -79,6 +79,21 @@ export declare function resolveSubscriptionMnemomKey(deps: MnemomKeyDeps, purpos
  * a non-entitled account to terminal; this is the fail-closed backstop.)
  */
 export declare function subscriptionShape(shape: LaunchShape, shapeExplicit: boolean, rcAllowed: boolean, say: (line: string) => void): LaunchShape;
+/**
+ * The coding agent's env for either auth arm: what `mnemom agent` launches claude with, and what a
+ * durable seat launches its claude with (host/seat-launch.ts, dogfood B6). With an Anthropic key:
+ * Claude Code logged in via claude.ai (OAuth) PREEMPTS ANTHROPIC_API_KEY, so it is force-unset;
+ * the real key rides in ANTHROPIC_CUSTOM_HEADERS (`headers`) and ANTHROPIC_AUTH_TOKEN is a fixed
+ * non-secret placeholder. Without one (a subscription launch) NO auth token is set: Claude Code
+ * then sends its own claude.ai login. Either way the owner's own Mnemom credential env is
+ * stripped (MNE-8245), as is MNEMOM_AGENT_ANTHROPIC_KEY (the key reaches the child only in the
+ * headers: C14, B6), and Claude Code's gateway hint headers are on (a value the owner set wins):
+ * the seat proxy chains each turn by x-claude-code-prompt-id, and without it a seat's first typed
+ * turn chained to the launch prompt (dogfood B8). Set here so the two callers cannot drift apart.
+ */
+export declare function launchChildEnv(base: NodeJS.ProcessEnv, door: string, headers: string, anthropicKey: string | undefined): NodeJS.ProcessEnv;
+/** The fixed, non-secret ANTHROPIC_AUTH_TOKEN of an api-key launch (the key rides in a header). */
+export declare const GATEWAY_AUTH_PLACEHOLDER = "mnemom-gateway";
 /**
  * The child env for a subscription launch: the gateway door, the Mnemom headers, and
  * NOTHING that would make Claude Code send a key instead of its claude.ai login.

package/dist/lib/subscription-login.js

@@ -16,7 +16,7 @@
  *
  * Pure apart from the injected deps, so every arm is unit-tested.
  */
-import { stripOwnerCredentialEnv } from "./agent.js";
+import { applyGatewayHintHeaders, stripOwnerCredentialEnv } from "./agent.js";
 export const AGENT_AUTHS = ["api-key", "subscription"];
 /**
  * The retired `console` value (it read the key Claude Code's Anthropic Console /login
@@ -132,6 +132,32 @@ export function subscriptionShape(shape, shapeExplicit, rcAllowed, say) {
     say("mnemom agent: subscription login runs terminal-only for now — launching in this terminal.");
     return "terminal";
 }
+/**
+ * The coding agent's env for either auth arm: what `mnemom agent` launches claude with, and what a
+ * durable seat launches its claude with (host/seat-launch.ts, dogfood B6). With an Anthropic key:
+ * Claude Code logged in via claude.ai (OAuth) PREEMPTS ANTHROPIC_API_KEY, so it is force-unset;
+ * the real key rides in ANTHROPIC_CUSTOM_HEADERS (`headers`) and ANTHROPIC_AUTH_TOKEN is a fixed
+ * non-secret placeholder. Without one (a subscription launch) NO auth token is set: Claude Code
+ * then sends its own claude.ai login. Either way the owner's own Mnemom credential env is
+ * stripped (MNE-8245), as is MNEMOM_AGENT_ANTHROPIC_KEY (the key reaches the child only in the
+ * headers: C14, B6), and Claude Code's gateway hint headers are on (a value the owner set wins):
+ * the seat proxy chains each turn by x-claude-code-prompt-id, and without it a seat's first typed
+ * turn chained to the launch prompt (dogfood B8). Set here so the two callers cannot drift apart.
+ */
+export function launchChildEnv(base, door, headers, anthropicKey) {
+    if (!anthropicKey)
+        return applyGatewayHintHeaders(subscriptionChildEnv(base, door, headers));
+    const env = { ...base };
+    delete env.ANTHROPIC_API_KEY;
+    delete env.MNEMOM_AGENT_ANTHROPIC_KEY;
+    env.ANTHROPIC_BASE_URL = door;
+    env.ANTHROPIC_AUTH_TOKEN = GATEWAY_AUTH_PLACEHOLDER;
+    env.ANTHROPIC_CUSTOM_HEADERS = headers;
+    stripOwnerCredentialEnv(env);
+    return applyGatewayHintHeaders(env);
+}
+/** The fixed, non-secret ANTHROPIC_AUTH_TOKEN of an api-key launch (the key rides in a header). */
+export const GATEWAY_AUTH_PLACEHOLDER = "mnemom-gateway";
 /**
  * The child env for a subscription launch: the gateway door, the Mnemom headers, and
  * NOTHING that would make Claude Code send a key instead of its claude.ai login.
@@ -139,6 +165,7 @@ export function subscriptionShape(shape, shapeExplicit, rcAllowed, say) {
 export function subscriptionChildEnv(base, door, headers) {
     const env = { ...base };
     delete env.ANTHROPIC_API_KEY;
+    delete env.MNEMOM_AGENT_ANTHROPIC_KEY;
     delete env.ANTHROPIC_AUTH_TOKEN;
     // The key already rides in the headers; the child process has no other use for it.
     // MNE-8245 defense-in-depth: also strips MNEMOM_API_KEY/MNEMOM_TOKEN, in case the

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));
+  });
+}