@mnemom/mnemom 0.16.1 → 0.17.0-next.0

package/dist/commands/protection.js

@@ -7,6 +7,7 @@ import { PROTECTION_CARD_MAX_BYTES, getProtectionCard, putProtectionCard, resolv
 import { requireAuth } from "../lib/auth.js";
 import { fmt } from "../lib/format.js";
 import { askYesNo, isInteractive } from "../lib/prompt.js";
+import { compareProtectionCards, formatDriftReport, isDrift } from "../lib/protection-drift.js";
 const PROTECTION_MODES = ["off", "observe", "nudge", "enforce"];
 const SURFACE_KEYS = ["incoming", "outgoing", "tool_calls", "tool_responses"];
 // Mirrors mnemom-api/src/composition/validate.ts OP_SEVERITIES (MNE-833).
@@ -822,3 +823,111 @@ export async function protectionEditCommand(agentName, options = {}) {
         process.exit(1);
     }
 }
+// ============================================================================
+// Drift check — committed snapshot vs live canonical card
+//
+// Closes the gap that the live posture had no committed representation: an
+// out-of-band SQL write to the canonical row (or a recompose that reverts one)
+// changed what every turn is screened against, with no diff and no alert. This
+// command is the alert. See `cards/README.md` for the full mechanism and for
+// why the repo file is a SNAPSHOT rather than the source of truth.
+// ============================================================================
+/**
+ * Compare a committed protection-card snapshot against the live CANONICAL
+ * (composed) card. Read-only: never writes, never publishes.
+ *
+ * Exit 0 = no drift, exit 1 = drift or error, so a scheduled job can gate on it.
+ */
+export async function protectionDriftCommand(file, agentName, opts = {}) {
+    const filePath = path.resolve(file);
+    if (!fs.existsSync(filePath)) {
+        console.log("\n" + fmt.error(`File not found: ${filePath}`) + "\n");
+        process.exit(1);
+    }
+    let parsed;
+    try {
+        parsed = parseProtectionFile(filePath);
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        console.log("\n" + fmt.error(`Could not parse file: ${msg}`) + "\n");
+        process.exit(1);
+    }
+    // Prefer the agent_id the snapshot itself declares — the snapshot is per-agent
+    // and pointing it at a different agent would compare two unrelated cards.
+    const declaredAgentId = typeof parsed.parsed.agent_id === "string" ? parsed.parsed.agent_id : undefined;
+    let agentId;
+    if (agentName) {
+        try {
+            agentId = await resolveAgentId(agentName);
+        }
+        catch (error) {
+            // Resolution needs auth + a network round trip. Report it as a drift-check
+            // failure (exit 1) rather than letting a raw stack reach a scheduled job.
+            const message = error instanceof Error ? error.message : String(error);
+            console.log("\n" + fmt.error(`Could not resolve agent "${agentName}": ${message}`) + "\n");
+            process.exit(1);
+        }
+    }
+    else {
+        agentId = declaredAgentId;
+    }
+    if (!agentId) {
+        console.log("\n" +
+            fmt.error("No agent to compare against: the snapshot declares no agent_id and no --agent was given.") +
+            "\n");
+        process.exit(1);
+    }
+    if (declaredAgentId && agentId !== declaredAgentId) {
+        console.log("\n" +
+            fmt.error(`Refusing to compare: --agent resolves to ${agentId} but the snapshot declares ${declaredAgentId}.`) +
+            "\n");
+        process.exit(1);
+    }
+    let live;
+    try {
+        const { body, contentType } = await getProtectionCard(agentId, "json");
+        if (!body) {
+            console.log("\n" +
+                fmt.error(`No live protection card for ${agentId}, but a committed snapshot exists at ${filePath}.`) +
+                "\n");
+            process.exit(1);
+        }
+        const decoded = contentType.includes("yaml") ? yaml.load(body) : JSON.parse(body);
+        if (!decoded || typeof decoded !== "object" || Array.isArray(decoded)) {
+            throw new Error("live card did not decode to an object");
+        }
+        live = decoded;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.log("\n" + fmt.error(`Failed to fetch live protection card: ${message}`) + "\n");
+        process.exit(1);
+        return;
+    }
+    const result = compareProtectionCards(parsed.parsed, live);
+    const drifted = isDrift(result, { strict: opts.strict });
+    if (opts.json) {
+        console.log(JSON.stringify({ agent_id: agentId, snapshot: filePath, strict: opts.strict === true, drifted, ...result }, null, 2));
+    }
+    else {
+        console.log(fmt.header("Protection Card Drift"));
+        console.log();
+        console.log(fmt.label("  Snapshot:", ` ${filePath}`));
+        console.log(fmt.label("  Agent:", ` ${agentId}`));
+        console.log(fmt.label("  Compared against:", " live canonical (composed) card"));
+        console.log();
+        console.log(formatDriftReport(result, { strict: opts.strict }));
+        console.log();
+        if (drifted) {
+            console.log(fmt.error("DRIFT: the live posture differs from the committed snapshot.") +
+                "\n\n  Reconcile deliberately — see cards/README.md. Do not publish the snapshot\n" +
+                "  to 'fix' the diff without first confirming what the sources compose to.\n");
+        }
+        else {
+            console.log(fmt.success("No drift.") + "\n");
+        }
+    }
+    if (drifted)
+        process.exit(1);
+}

package/dist/commands/status.js

@@ -188,6 +188,11 @@ async function showTraceSummary(agentId) {
             if (integrity.violation_count > 0) {
                 console.log(`Violations:      ${integrity.violation_count}`);
             }
+            // MNE-596: logged/visible but NOT subtracted from Verified and NOT part
+            // of Violations above — a correctly policy-refused attack, not a real one.
+            if (integrity.bounded_refusal_count && integrity.bounded_refusal_count > 0) {
+                console.log(`Bounded Refusals: ${integrity.bounded_refusal_count} (policy-enforced, not counted)`);
+            }
         }
         else {
             console.log("Integrity: No data yet");

package/dist/commands/try-me.js

@@ -28,8 +28,9 @@ import { putAlignmentCard, putProtectionCard, listOrgAgents, MnemomApiError } fr
 import { resolveAuth, loginWithBrowser, loginWithDeviceFlow } from "../lib/auth.js";
 import { openBrowser } from "../lib/oauth.js";
 import { askSelect, askInput, askYesNo, isInteractive } from "../lib/prompt.js";
-import { getApiUrl } from "../lib/config.js";
+import { getApiUrl, setApiUrlOverride } from "../lib/config.js";
 import { fmt } from "../lib/format.js";
+import { getAgentName, mergeAgentConfig } from "../lib/agent-config.js";
 const POLL_INTERVAL_MS = 3000;
 /**
  * Entry point for `mnemom try-me <token>`. Throws on fatal misconfiguration
@@ -58,6 +59,12 @@ export async function tryMeCommand(token, options = {}) {
         throw new Error(`'${token}' doesn't look like a try-me token (expected e.g. tryme_…). ` +
             "Copy the token from your Dojo /try-me invite.");
     }
+    // Point EVERY API surface for this run at the ring the operator chose via
+    // `--api` — including OAuth discovery + the one-click claim login, which
+    // otherwise fall back to getApiUrl()'s prod default and leak the sign-in to
+    // prod even though resolve/birth ran on the ring.
+    if (options.api)
+        setApiUrlOverride(options.api);
     // ── State: resolve ────────────────────────────────────────────────────────
     say(fmt.header("Mnemom Dojo — try-me"));
     say();
@@ -114,6 +121,8 @@ export async function tryMeCommand(token, options = {}) {
     result.claimed = true;
     result.steps.push({ step: "claim", status: "ok", detail: agentId });
     say(fmt.success("Claimed — you now own this agent."));
+    // Persist identity so subsequent skill invocations skip the identity prompts.
+    mergeAgentConfig({ agent_id: agentId, agent_name: name, gateway_url: manifest.gateway.endpoint });
     // The session context the card writes share: ensureSession + writeCardWithRetry
     // both need it (the latter re-triggers ensureSession on a persistent auth 403).
     const sessionCtx = { nonInteractive, autoOpen, agentId, say };
@@ -156,6 +165,12 @@ export async function tryMeCommand(token, options = {}) {
 async function pickName(manifest, options, skipPrompt, say) {
     if (options.name && options.name.trim())
         return options.name.trim();
+    // On repeat invocations, use the saved name so the identity prompt is skipped.
+    const savedName = getAgentName();
+    if (savedName) {
+        say(fmt.dim(`Using saved agent name "${savedName}" (override with --name).`));
+        return savedName;
+    }
     const opts = manifest.handoff.name_options ?? [];
     const fallback = opts[0] ?? "mnemom-dojo-agent";
     if (skipPrompt) {

package/dist/commands/usage.d.ts

@@ -0,0 +1,35 @@
+import { type UsageDays } from "../lib/api.js";
+export interface UsageCommandOptions {
+    org: string;
+    days?: number;
+    person?: string;
+    provider?: string;
+    model?: string;
+    limit?: number;
+    cursor?: string;
+    json?: boolean;
+}
+/**
+ * Parse a numeric CLI flag, warning and falling back to the caller's default
+ * on anything that is not a whole number of at least 1.
+ *
+ * Exported (rather than closed over inside the command registration) so the
+ * reject-and-warn arm is directly testable — it is the only branch here with
+ * observable behaviour, and reaching it through Commander would mean driving
+ * the whole CLI just to assert one stderr line.
+ *
+ * Strict on purpose. `parseInt("2abc", 10)` returns `2`, so an `isNaN` guard
+ * accepts partial-numeric input and silently acts on a value the user did not
+ * type; `--limit -1` is likewise nonsense that the server would have to
+ * reject. A whole-digits test rejects both up front.
+ */
+export declare function parseNumericFlag(flag: string, raw?: string): number | undefined;
+/**
+ * Validate `--days` against the window enum the endpoint actually accepts.
+ *
+ * The server 400s on anything outside {7, 30, 90}. Rejecting locally turns a
+ * round-trip and a raw API error into an immediate message that names the
+ * allowed values.
+ */
+export declare function parseDaysFlag(raw?: string): UsageDays | undefined;
+export declare function usageCommand(opts: UsageCommandOptions): Promise<void>;

package/dist/commands/usage.js

@@ -0,0 +1,265 @@
+import { getOrgUsage, MnemomApiError, USAGE_ALLOWED_DAYS, } from "../lib/api.js";
+import { requireAuth } from "../lib/auth.js";
+import { fmt } from "../lib/format.js";
+/**
+ * Parse a numeric CLI flag, warning and falling back to the caller's default
+ * on anything that is not a whole number of at least 1.
+ *
+ * Exported (rather than closed over inside the command registration) so the
+ * reject-and-warn arm is directly testable — it is the only branch here with
+ * observable behaviour, and reaching it through Commander would mean driving
+ * the whole CLI just to assert one stderr line.
+ *
+ * Strict on purpose. `parseInt("2abc", 10)` returns `2`, so an `isNaN` guard
+ * accepts partial-numeric input and silently acts on a value the user did not
+ * type; `--limit -1` is likewise nonsense that the server would have to
+ * reject. A whole-digits test rejects both up front.
+ */
+export function parseNumericFlag(flag, raw) {
+    if (raw === undefined)
+        return undefined;
+    if (!/^\d+$/.test(raw.trim()) || Number(raw.trim()) < 1) {
+        // Echo the offending value back, but stripped: it is user-supplied and
+        // lands unescaped in a terminal, so control characters (ANSI cursor/colour
+        // sequences) are removed and the length is capped before it is printed.
+        const safe = raw.replace(/[^\x20-\x7e]/g, "?").slice(0, 32);
+        console.error(`Warning: ${flag} must be a whole number of 1 or more; ignoring '${safe}' and using default.`);
+        return undefined;
+    }
+    return Number(raw.trim());
+}
+/**
+ * Validate `--days` against the window enum the endpoint actually accepts.
+ *
+ * The server 400s on anything outside {7, 30, 90}. Rejecting locally turns a
+ * round-trip and a raw API error into an immediate message that names the
+ * allowed values.
+ */
+export function parseDaysFlag(raw) {
+    if (raw === undefined)
+        return undefined;
+    const n = parseNumericFlag("--days", raw);
+    if (n === undefined)
+        return undefined;
+    if (!USAGE_ALLOWED_DAYS.includes(n)) {
+        console.error(`Warning: --days must be one of ${USAGE_ALLOWED_DAYS.join(", ")}; ` +
+            `ignoring '${n}' and using default.`);
+        return undefined;
+    }
+    return n;
+}
+const HEADERS = {
+    person: "Person",
+    provider: "Provider",
+    model: "Model",
+    tokensIn: "Tokens in",
+    tokensOut: "Tokens out",
+    requests: "Requests",
+};
+// Control and bidi/invisible characters are stripped from every API-sourced string
+// before it reaches the terminal. A crafted display name, email or error body
+// ("\x1b[2J\x1b[H" to clear the screen, a right-to-left override to reorder a row)
+// would otherwise let table content repaint or scramble an operator's terminal.
+//
+// Only the dangerous characters go: the C0/C1 control block, zero-width
+// space/non-joiner, the LRM/RLM marks, the bidi embedding+override block, the
+// directional isolates, and the BOM/zero-width no-break space. Printable
+// non-ASCII is PRESERVED — a real name like "José" or "田中" must render as
+// itself — which is why this is deliberately NOT the ASCII-only strip
+// `parseNumericFlag` applies to flag input (there the value is supposed to be
+// digits, so collapsing everything else is the right call). U+200D ZWJ is left
+// alone so emoji sequences in a display name do not shatter into components.
+//
+// The control block is matched as `\p{Cc}` rather than an explicit
+// `\u0000-\u001f\u007f-\u009f` range. The two are exactly equivalent (verified
+// across all 1.1M code points), but the range form puts control characters in
+// the regex literal, which `no-control-regex` blocks — and silencing that rule
+// here would silence it for any accidental control character added later.
+const UNSAFE_TERMINAL_CHARS = /[\p{Cc}\u200b\u200c\u200e\u200f\u2028-\u202e\u2066-\u2069\ufeff]/gu;
+/** Replace terminal-control characters with `?` so tampering is visible rather than silent. */
+function sanitizeForTerminal(s) {
+    return s.replace(UNSAFE_TERMINAL_CHARS, "?");
+}
+/**
+ * The endpoint is hidden behind USAGE_ATTRIBUTION_API_ENABLED, and when that
+ * flag is off it answers **404, not 403** — deliberately, so a disabled feature
+ * looks exactly like a route that was never deployed. A genuinely unknown org,
+ * and a caller the org is not visible to, also produce 404.
+ *
+ * So 404 is irreducibly ambiguous and this message must not pick one cause. The
+ * first version of this command labelled it "Org not found or not accessible",
+ * which reads as a mistyped org id when the overwhelmingly common cause is
+ * simply that the flag is off in that environment.
+ */
+const NOT_AVAILABLE_MSG = "Usage attribution is not available for this org. It may not be enabled in " +
+    "this environment yet, or the org may not exist or not be visible to you. " +
+    "Contact your Mnemom account team to enable it.";
+export async function usageCommand(opts) {
+    await requireAuth();
+    let data;
+    try {
+        data = await getOrgUsage(opts.org, {
+            days: opts.days,
+            personId: opts.person,
+            provider: opts.provider,
+            model: opts.model,
+            limit: opts.limit,
+            cursor: opts.cursor,
+        });
+    }
+    catch (err) {
+        if (err instanceof MnemomApiError) {
+            if (err.effectiveStatus === 404) {
+                console.error(fmt.error(NOT_AVAILABLE_MSG));
+                process.exit(1);
+            }
+            // 403 stays distinct from the not-available path above: it is a real role
+            // deny (member/viewer), and telling that caller "not enabled" would send
+            // them to the account team for something their own org admin can grant.
+            if (err.effectiveStatus === 403) {
+                console.error(fmt.error("You do not have permission to view usage for this org " +
+                    "(requires owner, admin, or auditor)."));
+                process.exit(1);
+            }
+            // Same sanitize as the identity column below: an error body is API-sourced
+            // and lands unescaped in a terminal. One rule for every API-sourced string.
+            console.error(fmt.error(sanitizeForTerminal(err.message)));
+            process.exit(1);
+        }
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(fmt.error(sanitizeForTerminal(msg)));
+        process.exit(1);
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(data, null, 2));
+        return;
+    }
+    // Rendered as UTC calendar days. The window is `from` inclusive / `to`
+    // exclusive, so the last day a reader should expect to see is the day BEFORE
+    // `to` — printing `to` raw invites "why is the last day empty?".
+    const windowLabel = `${utcDay(data.from)} to ${utcDay(dayBefore(data.to))} (UTC)`;
+    console.log(fmt.header(`mnemom usage — ${windowLabel}`));
+    console.log();
+    console.log(fmt.label("Org:", sanitizeForTerminal(opts.org)));
+    console.log(fmt.label("Window:", windowLabel));
+    if (data.collection_started_at) {
+        console.log(fmt.label("Reporting since:", utcDay(data.collection_started_at)));
+    }
+    if (data.data.length === 0) {
+        console.log();
+        // Deliberately distinguishable from the not-available path above: this is a
+        // successful, authorized read that found nothing, not a hidden failure.
+        console.log(fmt.dim("No consumption recorded for this window."));
+        console.log();
+        return;
+    }
+    console.log();
+    console.log(fmt.section("Consumption by person"));
+    console.log();
+    // The numeric columns size themselves to their widest value rather than
+    // taking a fixed width. A 64-bit total runs to 20 digits (max uint64 is
+    // 18446744073709551615) and would overflow any narrower column, ragging
+    // every column to its right. padLeft deliberately does NOT truncate — a
+    // clipped token count is wrong data, not just untidy layout — so the column
+    // grows instead. `data.data` is non-empty here (the zero-row case returned
+    // above), so each spread always has an argument.
+    const rows = data.data;
+    const colW = {
+        person: 30,
+        provider: Math.max(HEADERS.provider.length, ...rows.map((r) => label(r.provider).length)),
+        model: Math.max(HEADERS.model.length, ...rows.map((r) => label(r.model).length)),
+        tokensIn: Math.max(HEADERS.tokensIn.length, ...rows.map((r) => r.tokens_in.length)),
+        tokensOut: Math.max(HEADERS.tokensOut.length, ...rows.map((r) => r.tokens_out.length)),
+        requests: Math.max(HEADERS.requests.length, ...rows.map((r) => r.request_count.length)),
+    };
+    console.log(fmt.dim([
+        padRight(HEADERS.person, colW.person),
+        padRight(HEADERS.provider, colW.provider),
+        padRight(HEADERS.model, colW.model),
+        padLeft(HEADERS.tokensIn, colW.tokensIn),
+        padLeft(HEADERS.tokensOut, colW.tokensOut),
+        padLeft(HEADERS.requests, colW.requests),
+    ].join("  ")));
+    for (const row of rows) {
+        console.log(formatRow(row, colW));
+    }
+    console.log();
+    // Coverage is reported from the server's pre-pagination totals, never counted
+    // from the rows on screen: totals cover the complete filtered result, so a
+    // per-page count would understate consumption on every page but the last.
+    const totals = data.totals;
+    console.log(fmt.dim(`Totals — tokens in ${totals.tokens_in}, out ${totals.tokens_out}, ` +
+        `requests ${totals.request_count}.`));
+    console.log(fmt.dim(`Attributed to a person: ${totals.attributed_request_count} of ` +
+        `${totals.request_count} requests (${formatRate(totals.attribution_rate)}). ` +
+        `Unattributed: ${totals.unattributed_request_count}.`));
+    if (data.next_cursor) {
+        console.log();
+        // The cursor is opaque and API-sourced, so it gets the same treatment as
+        // every other API-sourced string here — no exception for "it's just an id".
+        // An unsanitized cursor is the worst of the lot: this line invites the user
+        // to copy it back onto their command line, so a bidi override inside it
+        // could make the pasted command read as something other than what it runs.
+        console.log(fmt.dim(`More rows available. Use --cursor '${sanitizeForTerminal(data.next_cursor)}' to continue.`));
+    }
+    console.log();
+}
+/** Render the attribution rate as a percentage without inventing precision. */
+function formatRate(rate) {
+    return `${(rate * 100).toFixed(1)}%`;
+}
+/** ISO timestamp to `YYYY-MM-DD`, keeping the server's UTC framing. */
+function utcDay(iso) {
+    return sanitizeForTerminal(iso).slice(0, 10);
+}
+/** One UTC day before an ISO timestamp, so an exclusive bound reads inclusively. */
+function dayBefore(iso) {
+    const t = Date.parse(iso);
+    // A malformed bound is echoed as-is rather than becoming "Invalid Date": the
+    // window label is disclosure copy, and it must never be the thing that fails.
+    if (Number.isNaN(t))
+        return iso;
+    return new Date(t - 24 * 60 * 60 * 1000).toISOString();
+}
+/** Blank provider/model values still occupy a column; the server sends "Unknown". */
+function label(value) {
+    return sanitizeForTerminal(value || "Unknown");
+}
+/**
+ * The person column. The server has already resolved the display label and
+ * guarantees a raw user UUID is never it — former or deleted members come back
+ * as "Former or deleted member". So this prefers `display_name`, falls back to
+ * `email`, and must NOT fall back to `user_id`, which would leak the UUID the
+ * API deliberately withholds. `user_id` is null on the unattributed row, which
+ * the server labels for us; the literal here is only a last-resort guard.
+ */
+function personLabel(row) {
+    return sanitizeForTerminal(row.display_name || row.email || "Unattributed");
+}
+function formatRow(row, colW) {
+    // Sanitized before padding, not after: the identity is an API-sourced display
+    // string (a platform user's own email/name), and it is printed straight to a
+    // terminal. Stripping first also keeps the column width honest — a control
+    // sequence occupies string length but no screen columns, so padding an
+    // unsanitized value would rag the table even without any attack.
+    return [
+        padRight(personLabel(row), colW.person),
+        padRight(label(row.provider), colW.provider),
+        padRight(label(row.model), colW.model),
+        padLeft(row.tokens_in, colW.tokensIn),
+        padLeft(row.tokens_out, colW.tokensOut),
+        padLeft(row.request_count, colW.requests),
+    ].join("  ");
+}
+// `> width`, not `>= width`: a value whose length equals the column width fits
+// exactly, and truncating it would destroy its last character for no gain. Both
+// arms return a `width`-wide string, so the table stayed aligned either way —
+// the bug was invisible in the layout and only ever lost data.
+function padRight(s, width) {
+    return s.length > width ? s.slice(0, width - 1) + "…" : s.padEnd(width);
+}
+// Never truncates: callers pass numeric totals, and a clipped total would
+// misreport consumption. Columns are sized to fit instead (see colW above).
+function padLeft(s, width) {
+    return s.length >= width ? s : s.padStart(width);
+}

package/dist/commands/wrap.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `mnemom wrap` — instrument an existing production agent through the Mnemom gateway (MNE-935, A4).
+ *
+ * Asks the developer for their provider + framework + agent name, makes a birth
+ * call to the gateway to provision the agent identity, seeds starter alignment +
+ * protection cards, and emits a drop-in code example. No reasoning change to the
+ * host agent.
+ *
+ * AUTH MODEL: Two credentials are involved:
+ *   - Mnemom auth (MNEMOM_API_KEY or `mnemom login` JWT) — used for card writes
+ *   - Provider API key (ANTHROPIC_API_KEY / OPENAI_API_KEY / GOOGLE_API_KEY) — used
+ *     for the one-time gateway birth call; this is the same key the user's agent
+ *     already holds, so the birth requires no new credential
+ *
+ * See SKILL-RUNNER-CONTRACT.md §2–§4 for the lifecycle + output contract.
+ */
+type Provider = "anthropic" | "openai" | "gemini";
+export interface WrapOptions {
+    json?: boolean;
+    yes?: boolean;
+    provider?: string;
+    framework?: string;
+    name?: string;
+    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 {};