@mnemom/mnemom 0.14.6 → 0.15.1-next.0

package/dist/commands/activity.d.ts

@@ -0,0 +1,2 @@
+export declare function activityCommand(agentName?: string): Promise<void>;
+export declare const integrityCommand: typeof activityCommand;

package/dist/commands/{integrity.js → activity.js}

@@ -1,7 +1,7 @@
 import { resolveAgentId, getIntegrity, MnemomApiError } from "../lib/api.js";
 import { fmt } from "../lib/format.js";
 import { TRACES_PENDING_NOTE } from "../lib/onboarding.js";
-export async function integrityCommand(agentName) {
+export async function activityCommand(agentName) {
     const agentId = await resolveAgentId(agentName);
     console.log("\nFetching agent activity...\n");
     try {
@@ -47,6 +47,9 @@ export async function integrityCommand(agentName) {
         }
     }
 }
+// `mnemom integrity` is retained as a deprecated alias of `mnemom activity`
+// (AAP = Activity). It still works and prints a deprecation notice; no breaking change.
+export const integrityCommand = activityCommand;
 function generateScoreBar(score) {
     const filled = Math.round(score * 10);
     const empty = 10 - filled;

package/dist/commands/agents.js

@@ -66,7 +66,7 @@ const FULL_PROOF_RE = /^[0-9a-f]{64}$/;
 // digest and break the claim handshake entirely, so SHA-256 is mandated by the
 // protocol — the "insufficient computational effort" alert is a false positive.
 function sha256Hex(input) {
-    // lgtm[js/insufficient-password-hash] — protocol proof, not password storage (see note above)
+    // codeql[js/insufficient-password-hash] — protocol proof, not password storage; see block comment above
     return createHash("sha256").update(input, "utf8").digest("hex"); // codeql[js/insufficient-password-hash]
 }
 /**
@@ -289,8 +289,25 @@ export async function agentsClaimCommand(idOrName, options = {}) {
     }
     console.log(fmt.success(`Claimed ${result.agent_id}.`));
     console.log(fmt.label("  Landed in:", where));
+    if (derivationName) {
+        console.log(fmt.label("  Name:", derivationName));
+    }
     if (result.claimed_at) {
         console.log(fmt.label("  Claimed at:", new Date(result.claimed_at).toLocaleString()));
     }
+    // Bridge to the next step (MNE-610). The dogfood dead-end was: claim with a
+    // friendly --name, then `mnemom card publish --agent <name>` returns an
+    // opaque "agent not found" while the freshly-claimed agent propagates into
+    // the listing the name-resolver reads. Always surface a ready-to-paste
+    // command keyed on the CANONICAL agent id, which `resolveAgentId` accepts
+    // verbatim (no list lookup) — so the publish step never dead-ends regardless
+    // of listing propagation. The friendly name is shown as the eventual
+    // shorthand, not the recommended first move.
+    console.log();
+    console.log(fmt.dim("  Next — publish your alignment card with the canonical id:"));
+    console.log(fmt.dim(`    mnemom card publish <file.yaml> --agent ${result.agent_id}`));
+    if (derivationName) {
+        console.log(fmt.dim(`  Once it appears in \`mnemom agents\`, you can use the name instead: --agent ${derivationName}`));
+    }
     console.log();
 }

package/dist/commands/api-key.js

@@ -64,7 +64,11 @@ function formatRow(key) {
 }
 // ─── mnemom api-key list ─────────────────────────────────────────────────
 export async function apiKeyListCommand(opts) {
-    await requireAuth();
+    const cred = await requireAuth();
+    if (cred.type === "api-key") {
+        console.log(fmt.warn("API keys are agent-scoped; run mnemom login to manage personal API keys"));
+        return;
+    }
     let keys;
     try {
         keys = await listApiKeys();
@@ -92,7 +96,11 @@ export async function apiKeyListCommand(opts) {
 }
 // ─── mnemom api-key create ───────────────────────────────────────────────
 export async function apiKeyCreateCommand(opts) {
-    await requireAuth();
+    const cred = await requireAuth();
+    if (cred.type === "api-key") {
+        console.log(fmt.warn("API keys are agent-scoped; run mnemom login to manage personal API keys"));
+        return;
+    }
     if (!opts.name || opts.name.trim() === "") {
         console.error(fmt.error("--name is required. Example: --name 'ci-prod'"));
         process.exit(1);
@@ -133,7 +141,11 @@ export async function apiKeyCreateCommand(opts) {
 }
 // ─── mnemom api-key rotate ───────────────────────────────────────────────
 export async function apiKeyRotateCommand(keyId, opts) {
-    await requireAuth();
+    const cred = await requireAuth();
+    if (cred.type === "api-key") {
+        console.log(fmt.warn("API keys are agent-scoped; run mnemom login to manage personal API keys"));
+        return;
+    }
     if (!keyId) {
         console.error(fmt.error("Usage: mnemom api-key rotate <key_id>"));
         process.exit(1);
@@ -163,7 +175,11 @@ export async function apiKeyRotateCommand(keyId, opts) {
 }
 // ─── mnemom api-key revoke ───────────────────────────────────────────────
 export async function apiKeyRevokeCommand(keyId) {
-    await requireAuth();
+    const cred = await requireAuth();
+    if (cred.type === "api-key") {
+        console.log(fmt.warn("API keys are agent-scoped; run mnemom login to manage personal API keys"));
+        return;
+    }
     if (!keyId) {
         console.error(fmt.error("Usage: mnemom api-key revoke <key_id>"));
         process.exit(1);

package/dist/commands/auth.js

@@ -1,38 +1,13 @@
-import { getAuthInfo, clearAuthTokens, loginWithBrowser, loginWithPassword } from "../lib/auth.js";
+import { getAuthInfo, clearAuthTokens, loginWithBrowser, loginWithDeviceFlow, resolveAuth, } from "../lib/auth.js";
 import { fmt } from "../lib/format.js";
-import { askInput } from "../lib/prompt.js";
 export async function loginCommand(options = {}) {
     try {
-        let tokens;
-        if (options.noBrowser) {
-            // Non-interactive hint: when stdin is piped, credentials are read as two
-            // lines (email, then password). If either is missing we fail loudly with
-            // a non-zero exit and never touch the stored session (MNE-269).
-            const piped = !process.stdin.isTTY;
-            const pipeHint = "Pipe credentials as two lines: printf 'EMAIL\\nPASSWORD\\n' | mnemom login --no-browser";
-            const email = await askInput("Email:");
-            if (!email) {
-                console.log(fmt.error("Email is required."));
-                if (piped)
-                    console.log(fmt.error(`No email received on stdin. ${pipeHint}`));
-                process.exit(1);
-            }
-            const password = await askInput("Password:", true);
-            if (!password) {
-                console.log(fmt.error("Password is required."));
-                if (piped)
-                    console.log(fmt.error(`No password received on stdin. ${pipeHint}`));
-                process.exit(1);
-            }
-            tokens = await loginWithPassword(email, password);
-        }
-        else {
-            tokens = await loginWithBrowser();
-        }
+        // --no-browser → RFC 8628 device flow (headless / SSH / no local browser).
+        // Default → OAuth 2.1 authorization-code + PKCE with a loopback redirect.
+        const tokens = options.noBrowser ? await loginWithDeviceFlow() : await loginWithBrowser();
         console.log();
         console.log(fmt.success("Logged in successfully!"));
-        console.log(fmt.label("  Email:  ", ` ${tokens.email}`));
-        console.log(fmt.label("  User ID:", ` ${tokens.userId}`));
+        printGrant(tokens);
         console.log();
     }
     catch (error) {
@@ -41,11 +16,37 @@ export async function loginCommand(options = {}) {
         process.exit(1);
     }
 }
+/**
+ * Print what the issued token actually grants. OAuth access tokens are scoped
+ * and (deliberately) carry no user identity, so we show scope + expiry rather
+ * than fabricating an email/user id we don't have.
+ */
+function printGrant(tokens) {
+    if (tokens.email)
+        console.log(fmt.label("  Email:  ", ` ${tokens.email}`));
+    if (tokens.scope)
+        console.log(fmt.label("  Scope:  ", ` ${tokens.scope}`));
+    const expiresDate = new Date(tokens.expiresAt * 1000).toISOString();
+    console.log(fmt.label("  Expires:", ` ${expiresDate}`));
+}
 export async function logoutCommand() {
     clearAuthTokens();
     console.log(fmt.success("Logged out."));
 }
 export async function whoamiCommand() {
+    const cred = await resolveAuth();
+    if (cred.type === "none") {
+        console.log("\nNot logged in. Run `mnemom login` to authenticate.\n");
+        return;
+    }
+    if (cred.type === "api-key") {
+        console.log(fmt.header("Auth Status"));
+        console.log();
+        console.log(fmt.label("  Credential Type:", " API key"));
+        console.log(fmt.label("  Status:         ", " valid (no expiry)"));
+        console.log();
+        return;
+    }
     const auth = getAuthInfo();
     if (!auth) {
         console.log("\nNot logged in. Run `mnemom login` to authenticate.\n");
@@ -56,8 +57,14 @@ export async function whoamiCommand() {
     const expiresDate = new Date(auth.expiresAt * 1000).toISOString();
     console.log(fmt.header("Auth Status"));
     console.log();
-    console.log(fmt.label("  Email:  ", ` ${auth.email}`));
-    console.log(fmt.label("  User ID:", ` ${auth.userId}`));
+    // OAuth access tokens are opaque and carry no identity; legacy sessions may
+    // still have email/userId. Show whatever the stored grant actually has.
+    if (auth.email)
+        console.log(fmt.label("  Email:  ", ` ${auth.email}`));
+    if (auth.userId)
+        console.log(fmt.label("  User ID:", ` ${auth.userId}`));
+    if (auth.scope)
+        console.log(fmt.label("  Scope:  ", ` ${auth.scope}`));
     console.log(fmt.label("  Token:  ", expired ? " expired" : ` valid until ${expiresDate}`));
     console.log();
 }

package/dist/commands/card.js

@@ -654,8 +654,23 @@ export async function cardPublishCommand(file, agentName, options = {}) {
         console.log();
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        console.log("\n" + fmt.error(`Failed to publish card: ${message}`) + "\n");
+        if (error instanceof MnemomApiError) {
+            if (error.effectiveStatus === 404) {
+                console.log("\n" +
+                    fmt.error("Agent found but not writable: you can see this agent locally, but cannot publish to it in its current organization context.") +
+                    "\n");
+            }
+            else if (error.effectiveStatus === 401) {
+                console.log("\n" + fmt.error(`Authentication failed: ${error.message}`) + "\n");
+            }
+            else {
+                console.log("\n" + fmt.error(`Failed to publish card: ${error.message}`) + "\n");
+            }
+        }
+        else {
+            const message = error instanceof Error ? error.message : String(error);
+            console.log("\n" + fmt.error(`Failed to publish card: ${message}`) + "\n");
+        }
         process.exit(1);
     }
 }

package/dist/commands/org.js

@@ -10,7 +10,11 @@ import { fmt } from "../lib/format.js";
  * machine-readable output.
  */
 export async function orgListCommand(opts) {
-    await requireAuth();
+    const cred = await requireAuth();
+    if (cred.type === "api-key") {
+        console.log(fmt.warn("API keys are agent-scoped; run mnemom login for org/key management"));
+        return;
+    }
     let orgs;
     try {
         orgs = await listMyOrgs();
@@ -56,7 +60,16 @@ export async function orgListCommand(opts) {
  * exactly one membership, that one).
  */
 export async function orgShowCommand(orgIdArg, opts) {
-    await requireAuth();
+    const cred = await requireAuth();
+    if (cred.type === "api-key") {
+        if (opts.personal || orgIdArg) {
+            console.log(fmt.warn("API keys cannot filter by organization. Run mnemom login to authenticate as a user and list org-scoped agents."));
+        }
+        else {
+            console.log(fmt.warn("API keys are agent-scoped; run mnemom login for org/key management"));
+        }
+        return;
+    }
     let target;
     try {
         if (opts.personal) {

package/dist/commands/protection.d.ts

@@ -9,7 +9,8 @@ export interface ValidationCheck {
  * Required: card_version, agent_id, mode (off|observe|nudge|enforce).
  * Optional: thresholds (warn ≤ quarantine ≤ block, all in [0,1]),
  *           screen_surfaces (object of bools with the four named keys),
- *           trusted_sources (object of typed buckets, per-bucket deny-lists).
+ *           trusted_sources (object of typed buckets, per-bucket deny-lists),
+ *           protected_surface (org-declared asset policy — MNE-830/833).
  */
 export declare function validateProtectionCard(card: Record<string, unknown>): ValidationCheck[];
 export declare function protectionShowCommand(agentName?: string): Promise<void>;

package/dist/commands/protection.js

@@ -9,6 +9,8 @@ import { fmt } from "../lib/format.js";
 import { askYesNo, isInteractive } from "../lib/prompt.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).
+const OP_SEVERITIES = ["low", "medium", "high", "critical"];
 // Per ADR-037 Decision 4: deny public LLM endpoints + public DNS providers,
 // and the any-host CIDRs, at write time.
 // T8-4 (2026-05-19) extended the corpus per
@@ -133,13 +135,152 @@ function validateTrustedBucket(name, bucket, checks, perEntry) {
         });
     }
 }
+// ── protected_surface helpers (MNE-833) ─────────────────────────────────────
+// Mirrors mnemom-api/src/composition/validate.ts validateProtectedSurface +
+// validateOpArray. Both codebases live in different repos; keep in sync.
+function validateOpArray(name, value, checks, withSeverity) {
+    if (value === undefined)
+        return;
+    if (!Array.isArray(value)) {
+        checks.push({
+            name: `protected_surface.${name}`,
+            passed: false,
+            message: `protected_surface.${name} must be an array.`,
+        });
+        return;
+    }
+    value.forEach((entry, i) => {
+        if (!isObject(entry)) {
+            checks.push({
+                name: `protected_surface.${name}[${i}]`,
+                passed: false,
+                message: `each protected_surface.${name} entry must be an object.`,
+            });
+            return;
+        }
+        const op = entry;
+        if (typeof op.pattern !== "string" || op.pattern.length === 0) {
+            checks.push({
+                name: `protected_surface.${name}[${i}].pattern`,
+                passed: false,
+                message: `protected_surface.${name}[].pattern is required (non-empty string).`,
+            });
+        }
+        if (op.applies_to !== undefined) {
+            if (!Array.isArray(op.applies_to)) {
+                checks.push({
+                    name: `protected_surface.${name}[${i}].applies_to`,
+                    passed: false,
+                    message: `protected_surface.${name}[].applies_to must be an array of asset-identity strings.`,
+                });
+            }
+            else if (!op.applies_to.every((x) => typeof x === "string")) {
+                checks.push({
+                    name: `protected_surface.${name}[${i}].applies_to`,
+                    passed: false,
+                    message: `protected_surface.${name}[].applies_to entries must be strings.`,
+                });
+            }
+        }
+        if (withSeverity &&
+            op.severity !== undefined &&
+            !OP_SEVERITIES.includes(String(op.severity))) {
+            checks.push({
+                name: `protected_surface.${name}[${i}].severity`,
+                passed: false,
+                message: `protected_surface.${name}[].severity must be one of: ${OP_SEVERITIES.join(", ")}.`,
+            });
+        }
+        if (op.reason !== undefined && typeof op.reason !== "string") {
+            checks.push({
+                name: `protected_surface.${name}[${i}].reason`,
+                passed: false,
+                message: `protected_surface.${name}[].reason must be a string.`,
+            });
+        }
+    });
+}
+function validateProtectedSurface(input, checks) {
+    if (!isObject(input)) {
+        checks.push({
+            name: "protected_surface",
+            passed: false,
+            message: "protected_surface must be an object with assets, forbidden_operations, escalation_required arrays.",
+        });
+        return;
+    }
+    const ps = input;
+    // assets[] — each needs a non-empty string kind + selector (intrinsic identity).
+    if (ps.assets !== undefined) {
+        if (!Array.isArray(ps.assets)) {
+            checks.push({
+                name: "protected_surface.assets",
+                passed: false,
+                message: "protected_surface.assets must be an array.",
+            });
+        }
+        else {
+            ps.assets.forEach((entry, i) => {
+                if (!isObject(entry)) {
+                    checks.push({
+                        name: `protected_surface.assets[${i}]`,
+                        passed: false,
+                        message: "each protected_surface.assets entry must be an object.",
+                    });
+                    return;
+                }
+                const a = entry;
+                if (typeof a.kind !== "string" || a.kind.length === 0) {
+                    checks.push({
+                        name: `protected_surface.assets[${i}].kind`,
+                        passed: false,
+                        message: "protected_surface.assets[].kind is required (non-empty string).",
+                    });
+                }
+                if (typeof a.selector !== "string" || a.selector.length === 0) {
+                    checks.push({
+                        name: `protected_surface.assets[${i}].selector`,
+                        passed: false,
+                        message: "protected_surface.assets[].selector is required (non-empty string).",
+                    });
+                }
+                if (a.label !== undefined && typeof a.label !== "string") {
+                    checks.push({
+                        name: `protected_surface.assets[${i}].label`,
+                        passed: false,
+                        message: "protected_surface.assets[].label must be a string.",
+                    });
+                }
+                if (a.reason !== undefined && typeof a.reason !== "string") {
+                    checks.push({
+                        name: `protected_surface.assets[${i}].reason`,
+                        passed: false,
+                        message: "protected_surface.assets[].reason must be a string.",
+                    });
+                }
+            });
+        }
+    }
+    validateOpArray("forbidden_operations", ps.forbidden_operations, checks, /* withSeverity */ true);
+    validateOpArray("escalation_required", ps.escalation_required, checks, /* withSeverity */ false);
+    for (const key of Object.keys(ps)) {
+        if (!["assets", "forbidden_operations", "escalation_required"].includes(key)) {
+            checks.push({
+                name: `protected_surface.${key}`,
+                passed: false,
+                message: `protected_surface.${key} is not a recognized key (allowed: assets, forbidden_operations, escalation_required).`,
+            });
+        }
+    }
+}
 /**
  * Validate a protection card against ADR-037 canonical form.
  *
  * Required: card_version, agent_id, mode (off|observe|nudge|enforce).
  * Optional: thresholds (warn ≤ quarantine ≤ block, all in [0,1]),
  *           screen_surfaces (object of bools with the four named keys),
- *           trusted_sources (object of typed buckets, per-bucket deny-lists).
+ *           trusted_sources (object of typed buckets, per-bucket deny-lists),
+ *           protected_surface (org-declared asset policy — MNE-830/833).
  */
 export function validateProtectionCard(card) {
     const checks = [];
@@ -324,6 +465,10 @@ export function validateProtectionCard(card) {
             }
         }
     }
+    // ── protected_surface (optional, MNE-830/833) ──
+    if (card.protected_surface !== undefined) {
+        validateProtectedSurface(card.protected_surface, checks);
+    }
     return checks;
 }
 // ============================================================================
@@ -438,8 +583,23 @@ export async function protectionPublishCommand(file, agentName, options = {}) {
         console.log();
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        console.log("\n" + fmt.error(`Failed to publish protection card: ${message}`) + "\n");
+        if (error instanceof MnemomApiError) {
+            if (error.effectiveStatus === 404) {
+                console.log("\n" +
+                    fmt.error("Agent found but not writable: you can see this agent locally, but cannot publish to it in its current organization context.") +
+                    "\n");
+            }
+            else if (error.effectiveStatus === 401) {
+                console.log("\n" + fmt.error(`Authentication failed: ${error.message}`) + "\n");
+            }
+            else {
+                console.log("\n" + fmt.error(`Failed to publish protection card: ${error.message}`) + "\n");
+            }
+        }
+        else {
+            const message = error instanceof Error ? error.message : String(error);
+            console.log("\n" + fmt.error(`Failed to publish protection card: ${message}`) + "\n");
+        }
         process.exit(1);
     }
 }

package/dist/commands/status.js

@@ -64,10 +64,13 @@ async function checkAuthStatus() {
     }
     const auth = getAuthInfo();
     if (auth) {
+        // OAuth tokens carry no identity; fall back to the granted scope (or a
+        // generic message) rather than printing "Logged in as undefined".
+        const who = auth.email ?? (auth.scope ? `scope ${auth.scope}` : "OAuth session");
         return {
             name: "Authentication",
             status: "ok",
-            message: `Logged in as ${auth.email}`,
+            message: `Logged in as ${who}`,
         };
     }
     // API key auth (no email available)

package/dist/commands/try-me.d.ts

@@ -0,0 +1,52 @@
+/**
+ * `mnemom try-me <token>` — the universal, deterministic Dojo-onboarding runner
+ * (MNE-934, epic MNE-931).
+ *
+ * Executes the shipped v5.0 briefing manifest's flow so an arbitrary agent/human
+ * on a fresh machine doesn't have to improvise it: resolve → name → be born →
+ * hand off (human claims in the browser) → set alignment → open a one-time grant
+ * (human approves in the browser) → set protection → hand off to the Dojo.
+ *
+ * DEMO-SAFE BY CONSTRUCTION:
+ *   - Additive: a NEW verb; it modifies no existing command and touches no
+ *     backend/website. It consumes Alex's shipped endpoints READ-ONLY (resolve,
+ *     gateway birth, public claim poll) + the canonical card-write client.
+ *   - The two privileged human acts stay in the human's browser: the claim
+ *     sign-in (step 4) and the one-time protection grant (step 6). The command
+ *     only orchestrates + polls — it never forges the human's session.
+ *
+ * AUTH MODEL (see the runner report / MNE-934): the canonical card-write PUTs
+ * (`/v1/{alignment,protection}/agent/:id`) authorize on the human's ORG
+ * MEMBERSHIP (ADR-062) and accept the human's `mnemom login` JWT or
+ * `MNEMOM_API_KEY` — NOT the birth token. So before the card writes the runner
+ * ensures a CLI session (offering `mnemom login`, one-click after the claim
+ * sign-in). That session IS the human's own — it is the headless twin of the
+ * host-connector authorization in the MCP flow, not a forged credential.
+ */
+import { type BriefingManifest } from "../lib/try-me.js";
+export interface TryMeOptions {
+    /** Print the resolved plan and exit — no birth, claim, card writes, or sim. */
+    dryRun?: boolean;
+    /** Machine-readable output (implies non-interactive). */
+    json?: boolean;
+    /** Non-interactive: auto-pick defaults and auto-open URLs (no prompts). */
+    yes?: boolean;
+    /** Pre-choose the agent's name (skips the name prompt). */
+    name?: string;
+    /** Resume from an already-born agent (skip birth) — e.g. a manual/legacy birth. */
+    agent?: string;
+    /** Override the API base used to resolve the token (default: env). */
+    api?: string;
+    /** Commander `--no-open` sets this false → never auto-open URLs, just print. */
+    open?: boolean;
+    /** Seconds to keep polling the claim / grant before giving up (default 600). */
+    pollTimeout?: number;
+}
+/**
+ * Entry point for `mnemom try-me <token>`. Throws on fatal misconfiguration
+ * (caught by the index.ts wrapper, which prints + exits non-zero); soft failures
+ * are surfaced as human guidance.
+ */
+export declare function tryMeCommand(token: string, options?: TryMeOptions): Promise<void>;
+/** Render the resolved plan as human-readable text (no side effects). */
+export declare function renderPlan(manifest: BriefingManifest): string;