@mnemom/mnemom 0.17.4-next.5 → 0.17.4-next.6

package/dist/commands/agent-setup.d.ts

@@ -74,11 +74,20 @@ export interface EnsureAgentOptions {
     gatewayHost: string;
     /** Override interactivity (defaults to isInteractive()). */
     interactive?: boolean;
+    /** Where the served-agent cache lives (defaults to ~/.mnemom). */
+    cacheDir?: string;
 }
+/** A bare launch never waits on the served-agent probe longer than this. */
+export declare const SERVED_PROBE_TIMEOUT_MS = 10000;
 export interface EnsureAgentResult {
     slug: string;
     /** true only when this call actually birthed/claimed/published. */
     provisioned: boolean;
+    /**
+     * The mnm- id the gateway serves for (key, slug), when this call learned it (a verified name
+     * match, a mismatch, or a fresh birth). Absent when it never asked the gateway.
+     */
+    agentId?: string;
 }
 /**
  * Ensure `slug` is a usable governed agent in the customer's org. Returns

package/dist/commands/agent-setup.js

@@ -26,11 +26,12 @@
 import { claimAgent, getAgentByName, getMe, getMuBalance, getMyPersonalOrg, MnemomApiError, mintProtectionCapability, putAlignmentCard, putProtectionCard, } from "../lib/api.js";
 import { getAuthInfo, isLoggedIn, loginWithBrowser, loginWithDeviceFlow, resolveAuth, } from "../lib/auth.js";
 import { getActiveOrg } from "../lib/cli-config.js";
-import { getApiUrl, getGatewayUrl, getWebsiteUrl } from "../lib/config.js";
+import { getApiUrl, getGatewayUrl, getWebsiteUrl, MNEMOM_DIR } from "../lib/config.js";
 import { fmt } from "../lib/format.js";
 import { askYesNo, isInteractive } from "../lib/prompt.js";
 import { resolveAnthropicDoor, resolveGatewayHost, sanitizeAgentName, singleCellError, } from "../lib/agent.js";
 import { configKeySpec, loadLauncherConfig, writeLauncherConfig } from "../lib/launcher-config.js";
+import { readServedAgent, servedFingerprint, writeServedAgent } from "../lib/served-agent-cache.js";
 import { deriveHashProof } from "./agents.js";
 import { birthThroughGateway } from "./wrap.js";
 import { resolveAnthropicKey } from "./agent.js";
@@ -104,6 +105,8 @@ export class AgentIdentityMismatchError extends Error {
         this.name = "AgentIdentityMismatchError";
     }
 }
+/** A bare launch never waits on the served-agent probe longer than this. */
+export const SERVED_PROBE_TIMEOUT_MS = 10_000;
 /**
  * Ensure `slug` is a usable governed agent in the customer's org. Returns
  * {provisioned:false} when it is already usable, when provisioning is not
@@ -115,33 +118,61 @@ export class AgentIdentityMismatchError extends Error {
  */
 export async function ensureGovernedAgent(opts) {
     const slug = opts.slug;
+    const cacheDir = opts.cacheDir ?? MNEMOM_DIR;
     const interactive = opts.interactive ?? isInteractive();
     // 1. Already usable? A named agent in the caller's fleet is claimed by them.
     const loggedIn = await isLoggedIn();
     if (loggedIn) {
         const existing = await getAgentByName(slug).catch(() => null);
         if (existing) {
+            // MNE-7650: the name is client-controlled and the API exposes no
+            // agent_hash, so a name match proves nothing about which agent the
+            // gateway will serve for (key, slug) — it looks agents up by
+            // hash(credential, name) only. Ask the gateway on EVERY launch, not just
+            // under --setup: the same 16-token "hello" the birth path uses answers
+            // with the served mnm- id on x-mnemom-agent. A bare launch that trusted
+            // the name recorded and reported an org agent while the gateway governed
+            // a different, unclaimed one (a second Anthropic key on a shared name).
+            //
+            // The answer is stable per (key, name, gateway), so a bare launch reuses a cached one and
+            // only probes (time-boxed) the first time; --setup always re-asks.
+            const gatewayUrl = opts.gatewayHost.replace(/\/+$/, "");
+            const fp = servedFingerprint(opts.anthropicKey, slug, gatewayUrl);
+            const cached = opts.setup === true ? null : readServedAgent(cacheDir, fp);
+            let served;
+            try {
+                served =
+                    cached ??
+                        (await birthThroughGateway(gatewayUrl, "anthropic", slug, opts.anthropicKey, {
+                            timeoutMs: opts.setup === true ? undefined : SERVED_PROBE_TIMEOUT_MS,
+                        }));
+            }
+            catch (err) {
+                // --setup must know which agent it governs; a bare launch carries on
+                // with the id unresolved rather than guessing it from the name.
+                if (opts.setup === true)
+                    throw err;
+                say(fmt.dim(`mnemom agent: couldn't confirm which agent the gateway serves for '${slug}' (${err instanceof Error ? err.message : String(err)}) — launching anyway.`));
+                return { slug, provisioned: false };
+            }
+            if (!cached)
+                writeServedAgent(cacheDir, fp, served);
+            if (served !== existing.id) {
+                if (opts.setup === true)
+                    throw new AgentIdentityMismatchError(slug, existing.id, served);
+                warnServedMismatch(slug, existing.id, served);
+                return { slug, provisioned: false, agentId: served };
+            }
             // On an EXPLICIT `mnemom agent setup`, repair/complete the cards on the
             // already-claimed agent (e.g. a protection card that failed on a prior run
             // before we minted its one-time grant). A bare launch leaves it alone.
             if (opts.setup === true) {
-                // MNE-7650: the name is client-controlled and the API exposes no
-                // agent_hash, so a name match proves nothing about which agent the
-                // gateway will serve for (key, slug) — it looks agents up by
-                // hash(credential, name) only. Ask the gateway: the same 16-token
-                // "hello" the birth path uses answers with the served mnm- id on
-                // x-mnemom-agent. Govern that agent or none.
-                const gatewayUrl = opts.gatewayHost.replace(/\/+$/, "");
-                const served = await birthThroughGateway(gatewayUrl, "anthropic", slug, opts.anthropicKey);
-                if (served !== existing.id) {
-                    throw new AgentIdentityMismatchError(slug, existing.id, served);
-                }
                 say(fmt.dim(`mnemom agent: '${slug}' is already claimed (${existing.id}, the agent the gateway serves) — refreshing its cards.`));
                 await publishDefaultCards(existing.id);
                 persistAgentSlug(slug);
-                return { slug, provisioned: true };
+                return { slug, provisioned: true, agentId: existing.id };
             }
-            return { slug, provisioned: false };
+            return { slug, provisioned: false, agentId: existing.id };
         }
     }
     // 2. Are we allowed to provision here?
@@ -186,7 +217,17 @@ export async function ensureGovernedAgent(opts) {
     await publishDefaultCards(agentId);
     // 6. Remember the slug so future launches skip straight to usable.
     persistAgentSlug(slug);
-    return { slug, provisioned: true };
+    return { slug, provisioned: true, agentId };
+}
+/**
+ * A bare launch whose name matches an org agent the gateway does NOT serve for this key. Not
+ * fatal (no --setup asked to govern it), but the user must know their governance lands on the
+ * served agent, and how to get a governed one of their own.
+ */
+function warnServedMismatch(slug, namedId, servedId) {
+    say(fmt.warn(`mnemom agent: '${slug}' in your org is ${namedId}, but the gateway serves ${servedId} for this Anthropic key + name — this session is governed as ${servedId}, which is not claimed to your org.`));
+    say(fmt.dim("  The gateway identity is hash(Anthropic key, name), so another key on the same name is a different agent. " +
+        `Use a name of your own: \`mnemom agent <scenario> --agent <unique-name> --setup\` (or claim the served one: \`mnemom agent claim ${servedId} --key <this key>\`).`));
 }
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 /**

package/dist/commands/agent.d.ts

@@ -141,6 +141,11 @@ export declare function recordSessionLaunch(ctx: {
     session: string;
     conversationId: string;
     agent: string;
+    /**
+     * The id the gateway serves, as setup learned it (null = asked, unknown). Undefined = setup
+     * never asked, so fall back to the org's name lookup.
+     */
+    agentId?: string | null;
     account: {
         orgId: string;
         orgLabel: string;

package/dist/commands/agent.js

@@ -297,19 +297,24 @@ export async function agentCommand(scenarioArg, options = {}) {
     // provisions-with-confirm when interactive; warns and continues otherwise.
     // Skipped entirely by `--no-setup`. A provisioning failure never blocks the
     // launch — it degrades to the unclaimed (fail-open) identity with a warning.
+    // The agent id the gateway serves, when setup asked it (undefined = never asked, so the ledger
+    // falls back to the org's name lookup).
+    let servedAgentId;
     if (options.setup !== false && !anthropicKey) {
         // Subscription login: the gateway creates the agent in the Mnemom key's org on the first
         // turn, so there is nothing to birth or claim here.
         say(`mnemom agent: subscription login — '${agent}' is created in your org on the first turn (identity: your Mnemom API key).`);
     }
     else if (options.setup !== false && anthropicKey) {
+        servedAgentId = null; // asked below; stays null if setup can't tell
         try {
-            await ensureGovernedAgent({
+            const ensured = await ensureGovernedAgent({
                 slug: agent,
                 anthropicKey,
                 setup: options.setup,
                 gatewayHost,
             });
+            servedAgentId = ensured.agentId ?? null;
         }
         catch (err) {
             // An identity mismatch is the one setup failure that must NOT degrade: the
@@ -368,6 +373,7 @@ export async function agentCommand(scenarioArg, options = {}) {
         session: scenario,
         conversationId,
         agent,
+        agentId: servedAgentId,
         account,
         gatewayHost,
         shape,
@@ -523,12 +529,19 @@ export async function resolveLaunchConversationId(input) {
  * ledger write failure warns to stderr and the launch proceeds regardless.
  */
 export async function recordSessionLaunch(ctx) {
+    // Never re-derive a known id from the name: the name can match an org agent the gateway does
+    // not serve for this key (MNE-7650), which is exactly what the ledger must not record.
     let agentId;
-    try {
-        agentId = (await getAgentByName(ctx.agent))?.id ?? null;
+    if (ctx.agentId !== undefined) {
+        agentId = ctx.agentId;
     }
-    catch {
-        agentId = null; // unresolvable right now — the ledger still records the launch
+    else {
+        try {
+            agentId = (await getAgentByName(ctx.agent))?.id ?? null;
+        }
+        catch {
+            agentId = null; // unresolvable right now — the ledger still records the launch
+        }
     }
     const result = appendSessionRecord({
         session: ctx.session,

package/dist/commands/wrap.d.ts

@@ -24,5 +24,7 @@ export interface WrapOptions {
     providerKey?: string;
 }
 export declare function wrapCommand(options?: WrapOptions): Promise<void>;
-export declare function birthThroughGateway(gatewayUrl: string, provider: Provider, agentName: string, providerKey: string): Promise<string>;
+export declare function birthThroughGateway(gatewayUrl: string, provider: Provider, agentName: string, providerKey: string, opts?: {
+    timeoutMs?: number;
+}): Promise<string>;
 export {};

package/dist/commands/wrap.js

@@ -199,7 +199,7 @@ async function resolveProviderKey(options, prov, nonInteractive, say) {
     return key;
 }
 // ── Birth call ────────────────────────────────────────────────────────────────
-export async function birthThroughGateway(gatewayUrl, provider, agentName, providerKey) {
+export async function birthThroughGateway(gatewayUrl, provider, agentName, providerKey, opts = {}) {
     const prov = PROVIDERS[provider];
     const authValue = provider === "openai" ? `Bearer ${providerKey}` : providerKey;
     const headers = {
@@ -235,7 +235,12 @@ export async function birthThroughGateway(gatewayUrl, provider, agentName, provi
                 messages: [{ role: "user", content: "hello" }],
             });
     }
-    const response = await fetch(url, { method: "POST", headers, body });
+    const response = await fetch(url, {
+        method: "POST",
+        headers,
+        body,
+        signal: opts.timeoutMs ? AbortSignal.timeout(opts.timeoutMs) : undefined,
+    });
     const agentId = response.headers.get(AGENT_HEADER);
     if (!response.ok && !agentId) {
         const text = await response.text().catch(() => "");

package/dist/lib/served-agent-cache.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Which mnm- agent the gateway serves for (Anthropic key, agent name, gateway).
+ *
+ * The gateway identity is hash(key, name), so the answer for one (key, name, gateway) is stable:
+ * once a launch has asked, later launches reuse it instead of paying for another probe
+ * completion. Entries are keyed by a one-way fingerprint and never hold the key itself (nor the
+ * sha256(key|name) claim proof). `--setup` always re-asks and overwrites.
+ */
+/**
+ * A slow KDF (scrypt), not a fast hash: the fingerprint is derived from a credential and lands on
+ * disk, so recovering the key from it must cost what guessing a password would. Name and
+ * gateway are the salt — the lookup has to be deterministic, and they make each entry unique.
+ */
+export declare function servedFingerprint(anthropicKey: string, slug: string, gateway: string): string;
+/** The cached served id, or null (missing, unreadable, or not an mnm- id). */
+export declare function readServedAgent(dir: string, fingerprint: string): string | null;
+/** Best effort: a failed write only means the next launch asks again. */
+export declare function writeServedAgent(dir: string, fingerprint: string, agentId: string): void;

package/dist/lib/served-agent-cache.js

@@ -0,0 +1,50 @@
+/**
+ * Which mnm- agent the gateway serves for (Anthropic key, agent name, gateway).
+ *
+ * The gateway identity is hash(key, name), so the answer for one (key, name, gateway) is stable:
+ * once a launch has asked, later launches reuse it instead of paying for another probe
+ * completion. Entries are keyed by a one-way fingerprint and never hold the key itself (nor the
+ * sha256(key|name) claim proof). `--setup` always re-asks and overwrites.
+ */
+import { scryptSync } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+const FILE = "served-agents.json";
+/**
+ * A slow KDF (scrypt), not a fast hash: the fingerprint is derived from a credential and lands on
+ * disk, so recovering the key from it must cost what guessing a password would. Name and
+ * gateway are the salt — the lookup has to be deterministic, and they make each entry unique.
+ */
+export function servedFingerprint(anthropicKey, slug, gateway) {
+    return scryptSync(anthropicKey, `mnemom-served-agent-v1\n${slug}\n${gateway}`, 32).toString("hex");
+}
+function readAll(dir) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(dir, FILE), "utf8"));
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** The cached served id, or null (missing, unreadable, or not an mnm- id). */
+export function readServedAgent(dir, fingerprint) {
+    const id = readAll(dir)[fingerprint];
+    return typeof id === "string" && /^mnm-/.test(id) ? id : null;
+}
+/** Best effort: a failed write only means the next launch asks again. */
+export function writeServedAgent(dir, fingerprint, agentId) {
+    try {
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const tmp = path.join(dir, `${FILE}.${process.pid}.tmp`);
+        fs.writeFileSync(tmp, JSON.stringify({ ...readAll(dir), [fingerprint]: agentId }, null, 2), {
+            mode: 0o600,
+        });
+        fs.renameSync(tmp, path.join(dir, FILE));
+    }
+    catch {
+        /* best effort */
+    }
+}

package/package.json

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