@mnemom/mnemom 0.17.0-next.7 → 0.17.0-next.9

package/dist/lib/launcher-config.d.ts

@@ -15,7 +15,7 @@
  * resolvers in lib/code.ts keep the built-in default as the final fallback);
  * the caller folds the plain-value settings under the CLI flags.
  */
-import { type LaunchShape } from "./agent.js";
+import { type GoalModeDefault, type LaunchShape } from "./agent.js";
 /** The human-editable settings file. Secret key lives elsewhere (launcher.json). */
 export declare const LAUNCHER_CONFIG_PATH: string;
 /** Where the CLI resolves the Anthropic key from; advisory ordering/restriction. */
@@ -29,6 +29,8 @@ export interface LauncherConfig {
     cli?: string;
     launch?: LaunchShape;
     keySource?: KeySource;
+    /** Standing goal-alignment default when neither --goal nor --implicit is given. */
+    goalMode?: GoalModeDefault;
     guardrails?: {
         maxTurns?: number;
         budgetUsd?: number;

package/dist/lib/launcher-config.js

@@ -19,12 +19,13 @@ import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "
 import { dirname, join } from "node:path";
 import { parse as parseToml, stringify as stringifyToml, TomlError } from "smol-toml";
 import { MNEMOM_DIR } from "./config.js";
-import { isPositiveInt, isPositiveNumber } from "./agent.js";
+import { isPositiveInt, isPositiveNumber, } from "./agent.js";
 /** The human-editable settings file. Secret key lives elsewhere (launcher.json). */
 export const LAUNCHER_CONFIG_PATH = join(MNEMOM_DIR, "launcher.toml");
 const LAUNCH_SHAPES = ["terminal", "remote-control", "server"];
 const EFFORTS = ["low", "medium", "high", "xhigh", "max"];
 const KEY_SOURCES = ["env", "store", "prompt"];
+const GOAL_MODES = ["implicit", "off"];
 function coerceLaunch(raw) {
     const v = raw.trim();
     if (LAUNCH_SHAPES.includes(v))
@@ -43,6 +44,12 @@ function coerceKeySource(raw) {
         return v;
     throw new Error(`key_source must be one of ${KEY_SOURCES.join(", ")} (got '${raw}').`);
 }
+function coerceGoalMode(raw) {
+    const v = raw.trim().toLowerCase();
+    if (GOAL_MODES.includes(v))
+        return v;
+    throw new Error(`goal_mode must be one of ${GOAL_MODES.join(", ")} (got '${raw}'). A sealed contract needs a statement, so it is always a per-launch --goal.`);
+}
 function coerceNonEmpty(name, raw) {
     const v = raw.trim();
     if (!v)
@@ -112,6 +119,14 @@ export const CONFIG_KEYS = [
             c.keySource = coerceKeySource(v);
         },
     },
+    {
+        key: "goal_mode",
+        describe: `Goal alignment when no --goal/--implicit is given (${GOAL_MODES.join("|")}); a sealed contract needs a per-launch --goal`,
+        get: (c) => c.goalMode,
+        set: (c, v) => {
+            c.goalMode = coerceGoalMode(v);
+        },
+    },
     {
         key: "guardrails.max_turns",
         describe: "Contract guardrail: turn ceiling (positive integer)",
@@ -176,6 +191,8 @@ export function parseLauncherConfig(text) {
         cfg.launch = coerceLaunch(str(raw.launch) ?? "");
     if (raw.key_source !== undefined)
         cfg.keySource = coerceKeySource(str(raw.key_source) ?? "");
+    if (raw.goal_mode !== undefined)
+        cfg.goalMode = coerceGoalMode(str(raw.goal_mode) ?? "");
     const g = raw.guardrails;
     if (g !== undefined) {
         if (typeof g !== "object" || g === null || Array.isArray(g)) {
@@ -232,6 +249,8 @@ export function serializeLauncherConfig(cfg) {
         doc.launch = cfg.launch;
     if (cfg.keySource !== undefined)
         doc.key_source = cfg.keySource;
+    if (cfg.goalMode !== undefined)
+        doc.goal_mode = cfg.goalMode;
     const g = cfg.guardrails;
     if (g && (g.maxTurns !== undefined || g.budgetUsd !== undefined || g.stallTurns !== undefined)) {
         const gr = {};

package/dist/lib/oauth.d.ts

@@ -105,11 +105,33 @@ export declare function loginWithDevice(opts?: {
     sleep?: (ms: number) => Promise<void>;
 }): Promise<DeviceResult>;
 /**
- * Exchange a refresh token for a fresh access token. Returns null if refresh is
- * not possible (no refresh token, or the AS rejects it — e.g. revoked/expired),
- * so callers can fall back to prompting for re-login rather than crashing.
+ * Exchange a refresh token for a fresh access token.
+ *
+ * Failure classification (R6 / MNE-7394) — a transient failure must never be
+ * indistinguishable from a revoked credential:
+ *   - 2xx → return the fresh tokens (carrying the prior refresh token forward
+ *     per RFC 6749 §6 when the AS omits a new one).
+ *   - A 4xx whose OAuth body `error` is `invalid_grant` / `invalid_client` →
+ *     return `null`, the re-login signal. RFC 6749 §5.2 defines these as the
+ *     errors that mean the presented grant/client credential is genuinely no
+ *     longer valid, so a fresh login is the correct remedy. No retry.
+ *   - Any other 4xx (e.g. `invalid_request`, `429`, an unrecognized/absent body
+ *     error, a non-JSON body) → throw. Something is wrong, but it does NOT mean
+ *     the credentials are revoked, so we must not discard the session.
+ *   - `res.status >= 500` or a fetch/network exception → retry with bounded
+ *     exponential backoff (~1s/2s/4s, REFRESH_MAX_ATTEMPTS attempts); if the
+ *     retries are exhausted, throw. Exhausting transient retries must NOT
+ *     masquerade as "credentials revoked" (fail-closed, MNE-442) — throwing
+ *     preserves the stored session so a later invocation can succeed once the
+ *     AS recovers.
+ *
+ * `null` is therefore narrowed to exactly the two re-login errors; every other
+ * outcome is a success, a retry, or a thrown error. `opts.sleep` is injectable
+ * so tests drive the backoff without real timers.
  */
-export declare function refreshTokens(refreshToken: string, clientId: string): Promise<OAuthTokens | null>;
+export declare function refreshTokens(refreshToken: string, clientId: string, opts?: {
+    sleep?: (ms: number) => Promise<void>;
+}): Promise<OAuthTokens | null>;
 /**
  * Open `url` in the user's default browser WITHOUT a shell. The URL is always
  * passed as a separate argv element (never concatenated into a command string),

package/dist/lib/oauth.js

@@ -39,6 +39,14 @@ const LOOPBACK_TIMEOUT_MS = 5 * 60 * 1000;
 // both interactive login poll loops emit, so a multi-minute browser sign-in
 // doesn't read as a hung CLI (matches the card-write retry tick in try-me).
 const LOGIN_HEARTBEAT_MS = 15 * 1000;
+// Refresh-token retry policy (R6 / MNE-7394). A transient AS 5xx or a dropped
+// network connection during refresh must be retried with bounded exponential
+// backoff rather than collapsed into the re-login signal — a one-second AS
+// hiccup or a flaky Wi-Fi moment must not invalidate a valid, long-lived
+// session. Per-attempt delay is REFRESH_BACKOFF_BASE_MS * 2**attemptIndex →
+// ~1s / 2s / 4s across REFRESH_MAX_ATTEMPTS attempts.
+const REFRESH_MAX_ATTEMPTS = 3;
+const REFRESH_BACKOFF_BASE_MS = 1000;
 let cachedMetadata = null;
 /**
  * Fetch (and process-cache) the AS metadata document. We resolve it relative to
@@ -359,40 +367,101 @@ async function pollDeviceToken(meta, clientId, authz, sleep, display) {
 // Refresh (RFC 6749 §6)
 // ============================================================================
 /**
- * Exchange a refresh token for a fresh access token. Returns null if refresh is
- * not possible (no refresh token, or the AS rejects it — e.g. revoked/expired),
- * so callers can fall back to prompting for re-login rather than crashing.
+ * Exchange a refresh token for a fresh access token.
+ *
+ * Failure classification (R6 / MNE-7394) — a transient failure must never be
+ * indistinguishable from a revoked credential:
+ *   - 2xx → return the fresh tokens (carrying the prior refresh token forward
+ *     per RFC 6749 §6 when the AS omits a new one).
+ *   - A 4xx whose OAuth body `error` is `invalid_grant` / `invalid_client` →
+ *     return `null`, the re-login signal. RFC 6749 §5.2 defines these as the
+ *     errors that mean the presented grant/client credential is genuinely no
+ *     longer valid, so a fresh login is the correct remedy. No retry.
+ *   - Any other 4xx (e.g. `invalid_request`, `429`, an unrecognized/absent body
+ *     error, a non-JSON body) → throw. Something is wrong, but it does NOT mean
+ *     the credentials are revoked, so we must not discard the session.
+ *   - `res.status >= 500` or a fetch/network exception → retry with bounded
+ *     exponential backoff (~1s/2s/4s, REFRESH_MAX_ATTEMPTS attempts); if the
+ *     retries are exhausted, throw. Exhausting transient retries must NOT
+ *     masquerade as "credentials revoked" (fail-closed, MNE-442) — throwing
+ *     preserves the stored session so a later invocation can succeed once the
+ *     AS recovers.
+ *
+ * `null` is therefore narrowed to exactly the two re-login errors; every other
+ * outcome is a success, a retry, or a thrown error. `opts.sleep` is injectable
+ * so tests drive the backoff without real timers.
  */
-export async function refreshTokens(refreshToken, clientId) {
+export async function refreshTokens(refreshToken, clientId, opts) {
     if (!refreshToken || !clientId)
         return null;
-    try {
-        const meta = await discover();
-        const res = await fetch(meta.token_endpoint, {
-            method: "POST",
-            headers: {
-                "Content-Type": "application/x-www-form-urlencoded",
-                Accept: "application/json",
-            },
-            body: new URLSearchParams({
-                grant_type: "refresh_token",
-                refresh_token: refreshToken,
-                client_id: clientId,
-            }),
-        });
-        if (!res.ok)
+    const sleep = opts?.sleep ?? defaultSleep;
+    // Discovery is not part of the refresh retry budget; a discovery failure
+    // propagates as it does today (it is already thrown by discover()).
+    const meta = await discover();
+    let lastTransient = "";
+    for (let attempt = 0; attempt < REFRESH_MAX_ATTEMPTS; attempt++) {
+        let res;
+        try {
+            res = await fetch(meta.token_endpoint, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/x-www-form-urlencoded",
+                    Accept: "application/json",
+                },
+                body: new URLSearchParams({
+                    grant_type: "refresh_token",
+                    refresh_token: refreshToken,
+                    client_id: clientId,
+                }),
+            });
+        }
+        catch (err) {
+            // Network/fetch exception (DNS failure, connection reset, timeout) — this
+            // is unrelated to the validity of the refresh token, so retry it.
+            lastTransient = err instanceof Error ? err.message : String(err);
+            if (attempt < REFRESH_MAX_ATTEMPTS - 1) {
+                await sleep(REFRESH_BACKOFF_BASE_MS * 2 ** attempt);
+                continue;
+            }
+            break;
+        }
+        if (res.ok) {
+            const data = (await res.json());
+            const tokens = tokensFromResponse(data);
+            // Per RFC 6749 §6, a refresh response MAY omit a new refresh token, in
+            // which case the old one remains valid — preserve it so the next refresh
+            // works.
+            if (!tokens.refreshToken)
+                tokens.refreshToken = refreshToken;
+            return tokens;
+        }
+        if (res.status >= 500) {
+            // Transient AS outage — retry with backoff, then fall through to the
+            // "exhausted" throw once no attempts remain.
+            lastTransient = `HTTP ${res.status}`;
+            if (attempt < REFRESH_MAX_ATTEMPTS - 1) {
+                await sleep(REFRESH_BACKOFF_BASE_MS * 2 ** attempt);
+                continue;
+            }
+            break;
+        }
+        // 4xx — a definitive client-side rejection, never retried. Only
+        // invalid_grant / invalid_client map to the null re-login signal; every
+        // other 4xx surfaces as a thrown error rather than a silent null that would
+        // wrongly discard a valid session.
+        const body = (await res.json().catch(() => ({})));
+        if (body.error === "invalid_grant" || body.error === "invalid_client") {
             return null;
-        const data = (await res.json());
-        const tokens = tokensFromResponse(data);
-        // Per RFC 6749 §6, a refresh response MAY omit a new refresh token, in which
-        // case the old one remains valid — preserve it so the next refresh works.
-        if (!tokens.refreshToken)
-            tokens.refreshToken = refreshToken;
-        return tokens;
-    }
-    catch {
-        return null;
+        }
+        const detail = body.error
+            ? body.error + (body.error_description ? ` — ${body.error_description}` : "")
+            : `HTTP ${res.status}`;
+        throw new Error(`Token refresh failed: ${detail}`);
     }
+    // Retries exhausted on a 5xx or a network exception (fail-closed, MNE-442):
+    // throw rather than return null so the session is preserved for a later retry.
+    throw new Error(`Token refresh failed after ${REFRESH_MAX_ATTEMPTS} attempts ` +
+        `(last error: ${lastTransient || "unknown transient failure"}).`);
 }
 // ============================================================================
 // Helpers

package/dist/rc-proxy.mjs

@@ -19,7 +19,7 @@
 //   * Inside api.anthropic.com, only `POST /v1/messages[?…]` is rewritten to the Mnemom
 //     gateway door: the real Anthropic key rides as `x-api-key` (API-key billing), plus
 //     `x-mnemom-agent`, `x-mnemom-conversation-id`, and optionally `x-mnemom-api-key`,
-//     `x-mnemom-provider`, `x-mnemom-egress-key`, `x-mnemom-contract` — the exact header set
+//     `x-mnemom-provider`, `x-mnemom-egress-key`, `x-mnemom-contract` / `x-mnemom-goal-mode` — the exact header set
 //     the non-RC launch sends via ANTHROPIC_CUSTOM_HEADERS. The OAuth `authorization` bearer
 //     is STRIPPED on that leg (it never leaves the machine) and `oauth-*` tokens are removed
 //     from `anthropic-beta`. Everything else under api.anthropic.com (OAuth refresh, the
@@ -62,6 +62,8 @@
 //   MNEMOM_AGENT_RC_AGENT             x-mnemom-agent value (required)
 //   MNEMOM_AGENT_RC_CONVERSATION_ID   x-mnemom-conversation-id value (required)
 //   MNEMOM_AGENT_RC_CONTRACT_B64      base64 contract for x-mnemom-contract (optional)
+//   MNEMOM_AGENT_RC_GOAL_MODE         x-mnemom-goal-mode value (optional; `--implicit` — no contract,
+//                                  the gateway infers the goal from the user's messages)
 //   MNEMOM_AGENT_RC_PROVIDER          x-mnemom-provider directive JSON (optional; router door)
 //   MNEMOM_AGENT_RC_THREAD_MODE       `reject` (default: answer thread-bearing requests locally,
 //                                  see above) | `strip` (legacy: delete `thread`, forward)
@@ -98,6 +100,7 @@ const AGENT = env.MNEMOM_AGENT_RC_AGENT || die("MNEMOM_AGENT_RC_AGENT is require
 const CONV =
   env.MNEMOM_AGENT_RC_CONVERSATION_ID || die("MNEMOM_AGENT_RC_CONVERSATION_ID is required");
 const CONTRACT_B64 = env.MNEMOM_AGENT_RC_CONTRACT_B64 || "";
+const GOAL_MODE = env.MNEMOM_AGENT_RC_GOAL_MODE || "";
 const PROVIDER = env.MNEMOM_AGENT_RC_PROVIDER || "";
 const THREAD_MODE = env.MNEMOM_AGENT_RC_THREAD_MODE || "reject";
 if (THREAD_MODE !== "reject" && THREAD_MODE !== "strip")
@@ -107,7 +110,9 @@ const PARENT = Number(env.MNEMOM_AGENT_RC_PARENT_PID || 0);
 const PORT = Number(env.MNEMOM_AGENT_RC_PORT || 0);
 
 const log = (line) => {
-  const s = `${new Date().toISOString()} ${line}\n`;
+  // One record per line: gateway header values and error bodies are spliced into log lines, so a
+  // CR/LF inside them must not fabricate extra records (log injection).
+  const s = `${new Date().toISOString()} ${String(line).replace(/[\r\n]+/g, " ")}\n`;
   if (LOGFILE) {
     try {
       fs.appendFileSync(LOGFILE, s);
@@ -345,6 +350,7 @@ function handle(req, res, viaPlain) {
     if (PROVIDER) headers["x-mnemom-provider"] = PROVIDER;
     if (secrets.openai) headers["x-mnemom-egress-key"] = secrets.openai;
     if (CONTRACT_B64) headers["x-mnemom-contract"] = CONTRACT_B64;
+    if (GOAL_MODE) headers["x-mnemom-goal-mode"] = GOAL_MODE;
     if (headers["anthropic-beta"]) {
       // drop the OAuth-only beta tokens
       const b = String(headers["anthropic-beta"])
@@ -388,8 +394,12 @@ function handle(req, res, viaPlain) {
         });
       }
       ur.pipe(res);
+      const goalRev = ur.headers["x-mnemom-goal-revision"];
+      const steer = ur.headers["x-mnemom-goal-steer"];
       const ident = toGateway
-        ? ` agent=${ur.headers["x-mnemom-agent"] || "-"} verdict=${ur.headers["x-mnemom-goal-verdict"] || "-"}`
+        ? ` agent=${ur.headers["x-mnemom-agent"] || "-"} verdict=${ur.headers["x-mnemom-goal-verdict"] || "-"}` +
+          (goalRev ? ` goal-rev=${goalRev}` : "") +
+          (steer ? ` steer=${steer}` : "")
         : "";
       ur.on("end", () => {
         let bodyNote = "";
@@ -488,7 +498,7 @@ proxy.on("clientError", (e, sock) => {
 proxy.listen(PORT, "127.0.0.1", () => {
   const { port } = proxy.address();
   log(
-    `listening 127.0.0.1:${port} agent=${AGENT} conv=${CONV} door=${GATEWAY.href} contract=${CONTRACT_B64 ? "yes" : "no"} provider=${PROVIDER || "-"} thread=${THREAD_MODE}`,
+    `listening 127.0.0.1:${port} agent=${AGENT} conv=${CONV} door=${GATEWAY.href} contract=${CONTRACT_B64 ? "yes" : "no"} goal_mode=${GOAL_MODE || "-"} provider=${PROVIDER || "-"} thread=${THREAD_MODE}`,
   );
   process.stdout.write(`READY ${port} ${p("ca.pem")}\n`);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnemom/mnemom",
-  "version": "0.17.0-next.7",
+  "version": "0.17.0-next.9",
   "description": "Transparent AI agent tracing",
   "type": "module",
   "bin": {
@@ -26,10 +26,10 @@
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^20.10.0",
-    "@vitest/coverage-v8": "^4.1.10",
+    "@vitest/coverage-v8": "^4.1.11",
     "tsx": "^4.23.1",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.10"
+    "vitest": "^4.1.11"
   },
   "files": [
     "dist",
@@ -65,5 +65,9 @@
   },
   "engines": {
     "node": ">=18.0.0"
+  },
+  "overrides": {
+    "@vitest/mocker": "^4.1.11",
+    "nanoid": "^3.3.18"
   }
 }