@mnemom/mnemom 0.10.0 → 0.12.0

package/README.md

@@ -26,23 +26,23 @@ That's it. `mnemom init` detects your configured AI provider API keys (Anthropic
 
 ## Supported Providers
 
-| Provider | Models | Thinking/AIP | Auth |
-|----------|--------|-------------|------|
-| Anthropic | Claude Opus 4.6, Opus 4.5, Sonnet 4.5 | Full (thinking blocks) | `x-api-key` |
-| OpenAI | GPT-5.2, GPT-5.2 Pro, GPT-5 | Via reasoning summaries | `Authorization: Bearer` |
-| Gemini | Gemini 2.5 Pro, Gemini 3 Pro | Full (thought parts) | `x-goog-api-key` |
+| Provider  | Models                                | Thinking/AIP            | Auth                    |
+| --------- | ------------------------------------- | ----------------------- | ----------------------- |
+| Anthropic | Claude Opus 4.6, Opus 4.5, Sonnet 4.5 | Full (thinking blocks)  | `x-api-key`             |
+| OpenAI    | GPT-5.2, GPT-5.2 Pro, GPT-5           | Via reasoning summaries | `Authorization: Bearer` |
+| Gemini    | Gemini 2.5 Pro, Gemini 3 Pro          | Full (thought parts)    | `x-goog-api-key`        |
 
 ## CLI Commands
 
-| Command | Description |
-|---------|-------------|
-| `mnemom init` | Configure tracing for your AI agent (multi-provider) |
-| `mnemom status` | Show agent status, providers, and connection info |
-| `mnemom integrity` | Display integrity score and verification stats |
-| `mnemom logs [-l N]` | Show recent traces and actions |
-| `mnemom card show` | Display active alignment card |
-| `mnemom card publish <file>` | Publish alignment card from JSON file |
-| `mnemom card validate <file>` | Validate card JSON locally |
+| Command                       | Description                                          |
+| ----------------------------- | ---------------------------------------------------- |
+| `mnemom init`                 | Configure tracing for your AI agent (multi-provider) |
+| `mnemom status`               | Show agent status, providers, and connection info    |
+| `mnemom integrity`            | Display integrity score and verification stats       |
+| `mnemom logs [-l N]`          | Show recent traces and actions                       |
+| `mnemom card show`            | Display active alignment card                        |
+| `mnemom card publish <file>`  | Publish alignment card from JSON file                |
+| `mnemom card validate <file>` | Validate card JSON locally                           |
 
 ## How It Works
 
@@ -84,20 +84,20 @@ What is **not** stored: your prompts, responses, or API key.
 
 ### AIP Compatibility Matrix
 
-| Provider/Model | AIP Support | Method |
-|----------------|-------------|--------|
-| Anthropic reasoning models (Opus, Sonnet) | Full | Thinking blocks analyzed directly |
-| OpenAI GPT-5 Thinking series | Partial | Reasoning summaries (reduced confidence) |
-| Gemini 2.5/3 with thinking | Full | Thought parts analyzed directly |
-| Non-reasoning models | Tracing only | Synthetic clear verdict |
+| Provider/Model                            | AIP Support  | Method                                   |
+| ----------------------------------------- | ------------ | ---------------------------------------- |
+| Anthropic reasoning models (Opus, Sonnet) | Full         | Thinking blocks analyzed directly        |
+| OpenAI GPT-5 Thinking series              | Partial      | Reasoning summaries (reduced confidence) |
+| Gemini 2.5/3 with thinking                | Full         | Thought parts analyzed directly          |
+| Non-reasoning models                      | Tracing only | Synthetic clear verdict                  |
 
 ## Enforcement Modes
 
-| Mode | Behavior |
-|------|----------|
-| `observe` | Detect violations, record them, take no action (default) |
-| `nudge` | Detect violations, inject feedback into the agent's next request via system prompt — the agent sees it and can self-correct |
-| `enforce` | Hard block with 403 for non-streaming; falls back to nudge for streaming |
+| Mode      | Behavior                                                                                                                    |
+| --------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `observe` | Detect violations, record them, take no action (default)                                                                    |
+| `nudge`   | Detect violations, inject feedback into the agent's next request via system prompt — the agent sees it and can self-correct |
+| `enforce` | Hard block with 403 for non-streaming; falls back to nudge for streaming                                                    |
 
 Enforcement works across all providers where AIP is supported.
 

package/dist/commands/agents.js

@@ -23,18 +23,13 @@ export async function agentsListCommand() {
     const idW = 40;
     const seenW = 14;
     const statusW = 14;
-    const header = "Name".padEnd(nameW) +
-        "ID".padEnd(idW) +
-        "Last Seen".padEnd(seenW) +
-        "Containment";
+    const header = "Name".padEnd(nameW) + "ID".padEnd(idW) + "Last Seen".padEnd(seenW) + "Containment";
     console.log(`  ${header}`);
     console.log(`  ${"─".repeat(nameW + idW + seenW + statusW)}`);
     for (const agent of agents) {
         const name = (agent.name ?? "-").slice(0, nameW - 2).padEnd(nameW);
         const id = agent.id.padEnd(idW);
-        const lastSeen = agent.last_seen
-            ? new Date(agent.last_seen).toLocaleDateString()
-            : "-";
+        const lastSeen = agent.last_seen ? new Date(agent.last_seen).toLocaleDateString() : "-";
         const seen = lastSeen.padEnd(seenW);
         const containment = agent.containment_status ?? "-";
         console.log(`  ${name}${id}${seen}${containment}`);

package/dist/commands/api-key.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `mnemom api-key ...` commands — capability-based API key management
+ * (ADR-049). Mirrors the dashboard scope picker and the API mint-time
+ * vocabulary; one CLI surface for the same key lifecycle operations.
+ *
+ *   mnemom api-key list                              — list active personal keys
+ *   mnemom api-key create --name <name> [--scopes a,b,c]
+ *                                                    — mint a new key
+ *   mnemom api-key rotate <key_id>                   — atomic mint-new + revoke-old
+ *   mnemom api-key revoke <key_id>                   — soft-delete
+ *
+ * Auth: any of the standard CLI auth methods — JWT (`mnemom login`),
+ * MNEMOM_API_KEY env, or a stored API key. Note the chicken-and-egg:
+ * to mint your first key you'll need a JWT (the website's create-key
+ * dialog is the alternative). After that, an `api:write` key can mint
+ * additional keys for itself.
+ */
+import { type ApiKeyScope } from "../lib/api.js";
+/**
+ * Exported for tests. Parses a comma-separated `--scopes` flag value,
+ * accepts legacy `api` for backward compat, and returns a typed array.
+ * Throws on unknown scope names so users get a clear error instead of
+ * silently dropping intent.
+ */
+export declare function parseScopes(input: string | undefined): ApiKeyScope[];
+export declare function apiKeyListCommand(opts: {
+    json?: boolean;
+}): Promise<void>;
+export declare function apiKeyCreateCommand(opts: {
+    name?: string;
+    scopes?: string;
+    json?: boolean;
+}): Promise<void>;
+export declare function apiKeyRotateCommand(keyId: string | undefined, opts: {
+    json?: boolean;
+}): Promise<void>;
+export declare function apiKeyRevokeCommand(keyId: string | undefined): Promise<void>;

package/dist/commands/api-key.js

@@ -0,0 +1,179 @@
+/**
+ * `mnemom api-key ...` commands — capability-based API key management
+ * (ADR-049). Mirrors the dashboard scope picker and the API mint-time
+ * vocabulary; one CLI surface for the same key lifecycle operations.
+ *
+ *   mnemom api-key list                              — list active personal keys
+ *   mnemom api-key create --name <name> [--scopes a,b,c]
+ *                                                    — mint a new key
+ *   mnemom api-key rotate <key_id>                   — atomic mint-new + revoke-old
+ *   mnemom api-key revoke <key_id>                   — soft-delete
+ *
+ * Auth: any of the standard CLI auth methods — JWT (`mnemom login`),
+ * MNEMOM_API_KEY env, or a stored API key. Note the chicken-and-egg:
+ * to mint your first key you'll need a JWT (the website's create-key
+ * dialog is the alternative). After that, an `api:write` key can mint
+ * additional keys for itself.
+ */
+import { listApiKeys, createApiKey, rotateApiKey, revokeApiKey, isLegacyScopeSet, API_KEY_SCOPES, DEFAULT_API_KEY_SCOPES, } from "../lib/api.js";
+import { requireAuth } from "../lib/auth.js";
+import { fmt } from "../lib/format.js";
+// ─── Helpers ─────────────────────────────────────────────────────────────
+/**
+ * Exported for tests. Parses a comma-separated `--scopes` flag value,
+ * accepts legacy `api` for backward compat, and returns a typed array.
+ * Throws on unknown scope names so users get a clear error instead of
+ * silently dropping intent.
+ */
+export function parseScopes(input) {
+    if (!input)
+        return [...DEFAULT_API_KEY_SCOPES];
+    const raw = input
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+    if (raw.length === 0)
+        return [...DEFAULT_API_KEY_SCOPES];
+    const valid = new Set(API_KEY_SCOPES);
+    // Accept legacy 'api' input here so users who copy-paste from older
+    // docs/scripts get a clean canonicalization. The API also aliases.
+    valid.add("api");
+    const unknown = raw.filter((s) => !valid.has(s));
+    if (unknown.length > 0) {
+        throw new Error(`Unknown scope(s): ${unknown.join(", ")}. ` +
+            `Valid: ${Array.from(API_KEY_SCOPES).join(", ")}`);
+    }
+    return raw;
+}
+function renderScopeBadge(scope) {
+    // Admin scopes get a visual marker so the audit trail in the CLI
+    // makes elevated keys obvious at a glance.
+    if (scope === "admin:platform" || scope === "admin:org") {
+        return fmt.warn(`[${scope}]`);
+    }
+    return `[${scope}]`;
+}
+function formatRow(key) {
+    const created = key.created_at ? new Date(key.created_at).toISOString().slice(0, 10) : "?";
+    const lastUsed = key.last_used_at
+        ? new Date(key.last_used_at).toISOString().slice(0, 10)
+        : "never";
+    const scopes = (key.scopes ?? []).map(renderScopeBadge).join(" ");
+    const legacy = isLegacyScopeSet(key.scopes) ? fmt.dim(" (legacy)") : "";
+    return `  ${key.key_id}  ${key.key_prefix}…  ${key.name.padEnd(24)}  ${scopes}${legacy}\n    created ${created} · last used ${lastUsed}`;
+}
+// ─── mnemom api-key list ─────────────────────────────────────────────────
+export async function apiKeyListCommand(opts) {
+    await requireAuth();
+    let keys;
+    try {
+        keys = await listApiKeys();
+    }
+    catch (err) {
+        console.error(fmt.error(`Failed to list api keys: ${err instanceof Error ? err.message : err}`));
+        process.exit(1);
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(keys, null, 2));
+        return;
+    }
+    if (keys.length === 0) {
+        console.log("\nNo active api keys.\n");
+        console.log("Create one with `mnemom api-key create --name <name>`.\n");
+        return;
+    }
+    console.log();
+    console.log(fmt.header(`Active api keys (${keys.length})`));
+    console.log();
+    for (const k of keys) {
+        console.log(formatRow(k));
+        console.log();
+    }
+}
+// ─── mnemom api-key create ───────────────────────────────────────────────
+export async function apiKeyCreateCommand(opts) {
+    await requireAuth();
+    if (!opts.name || opts.name.trim() === "") {
+        console.error(fmt.error("--name is required. Example: --name 'ci-prod'"));
+        process.exit(1);
+    }
+    let scopes;
+    try {
+        scopes = parseScopes(opts.scopes);
+    }
+    catch (err) {
+        console.error(fmt.error(err instanceof Error ? err.message : String(err)));
+        process.exit(1);
+    }
+    let created;
+    try {
+        created = await createApiKey(opts.name.trim(), scopes);
+    }
+    catch (err) {
+        console.error(fmt.error(`Create failed: ${err instanceof Error ? err.message : err}`));
+        process.exit(1);
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(created, null, 2));
+        return;
+    }
+    console.log();
+    console.log(fmt.success(`Created ${created.key_id}`));
+    console.log();
+    console.log(fmt.label("  Name:    ", ` ${created.name}`));
+    console.log(fmt.label("  Scopes:  ", ` ${(created.scopes ?? []).join(", ")}`));
+    console.log(fmt.label("  Created: ", ` ${created.created_at}`));
+    console.log();
+    console.log(fmt.warn("  Cleartext (shown once — copy now):"));
+    console.log(`    ${created.key}`);
+    console.log();
+    console.log(fmt.dim("  This is the only time the cleartext is returned."));
+    console.log(fmt.dim("  Mnemom stores only the SHA-256 hash; the key cannot be retrieved later."));
+    console.log();
+}
+// ─── mnemom api-key rotate ───────────────────────────────────────────────
+export async function apiKeyRotateCommand(keyId, opts) {
+    await requireAuth();
+    if (!keyId) {
+        console.error(fmt.error("Usage: mnemom api-key rotate <key_id>"));
+        process.exit(1);
+    }
+    let rotated;
+    try {
+        rotated = await rotateApiKey(keyId);
+    }
+    catch (err) {
+        console.error(fmt.error(`Rotate failed: ${err instanceof Error ? err.message : err}`));
+        process.exit(1);
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(rotated, null, 2));
+        return;
+    }
+    console.log();
+    console.log(fmt.success(`Rotated. Old key ${keyId} is now revoked.`));
+    console.log();
+    console.log(fmt.label("  New key id:", ` ${rotated.key_id}`));
+    console.log(fmt.label("  Name:      ", ` ${rotated.name}`));
+    console.log(fmt.label("  Scopes:    ", ` ${(rotated.scopes ?? []).join(", ")}`));
+    console.log();
+    console.log(fmt.warn("  New cleartext (shown once — copy now):"));
+    console.log(`    ${rotated.key}`);
+    console.log();
+}
+// ─── mnemom api-key revoke ───────────────────────────────────────────────
+export async function apiKeyRevokeCommand(keyId) {
+    await requireAuth();
+    if (!keyId) {
+        console.error(fmt.error("Usage: mnemom api-key revoke <key_id>"));
+        process.exit(1);
+    }
+    try {
+        await revokeApiKey(keyId);
+    }
+    catch (err) {
+        console.error(fmt.error(`Revoke failed: ${err instanceof Error ? err.message : err}`));
+        process.exit(1);
+    }
+    console.log(fmt.success(`Revoked ${keyId}.`));
+}

package/dist/commands/auth.js

@@ -1,5 +1,4 @@
-import { getAuthInfo, clearAuthTokens } from "../lib/auth.js";
-import { loginWithBrowser, loginWithPassword } from "../lib/auth.js";
+import { getAuthInfo, clearAuthTokens, loginWithBrowser, loginWithPassword } from "../lib/auth.js";
 import { fmt } from "../lib/format.js";
 import { askInput } from "../lib/prompt.js";
 export async function loginCommand(options = {}) {

package/dist/commands/card.js

@@ -7,7 +7,7 @@ import { ALIGNMENT_CARD_MAX_BYTES, getAlignmentCard, putAlignmentCard, resolveAg
 import { requireAuth } from "../lib/auth.js";
 import { fmt } from "../lib/format.js";
 import { askYesNo, isInteractive } from "../lib/prompt.js";
-import { evaluatePolicy, } from "@mnemom/policy-engine";
+import { evaluatePolicy } from "@mnemom/policy-engine";
 function detectFormat(filePath) {
     const ext = path.extname(filePath).toLowerCase();
     if (ext === ".yaml" || ext === ".yml")
@@ -201,7 +201,7 @@ export function validateUnifiedCard(card) {
                 message: "Must contain at least one value.",
             });
         }
-        else if (!decl.every(s => typeof s === "string")) {
+        else if (!decl.every((s) => typeof s === "string")) {
             checks.push({
                 name: "values.declared",
                 passed: false,
@@ -238,7 +238,8 @@ export function validateUnifiedCard(card) {
             }
         }
         // hierarchy enum
-        if (v.hierarchy !== undefined && !VALUE_HIERARCHIES.includes(String(v.hierarchy))) {
+        if (v.hierarchy !== undefined &&
+            !VALUE_HIERARCHIES.includes(String(v.hierarchy))) {
             checks.push({
                 name: "values.hierarchy",
                 passed: false,
@@ -247,7 +248,8 @@ export function validateUnifiedCard(card) {
         }
     }
     // ── autonomy.bounded_actions (required, non-empty; disjoint from forbidden_actions) ──
-    if (!isObj(card.autonomy) || !Array.isArray(card.autonomy.bounded_actions)) {
+    if (!isObj(card.autonomy) ||
+        !Array.isArray(card.autonomy.bounded_actions)) {
         checks.push({
             name: "autonomy.bounded_actions",
             passed: false,
@@ -428,7 +430,8 @@ export function validateUnifiedCard(card) {
                             message: "Required (non-empty string).",
                         });
                     }
-                    if (cv.severity !== undefined && !CONSCIENCE_SEVERITIES.includes(String(cv.severity))) {
+                    if (cv.severity !== undefined &&
+                        !CONSCIENCE_SEVERITIES.includes(String(cv.severity))) {
                         checks.push({
                             name: `conscience.values[${i}].severity`,
                             passed: false,
@@ -676,20 +679,21 @@ export async function cardEditCommand(agentName, options = {}) {
     if (!original) {
         console.log(fmt.warn("No alignment card found. Creating a template..."));
     }
-    const cardYaml = original || yaml.dump({
-        card_version: "unified/2026-04-26",
-        agent_id: agentId,
-        autonomy_mode: "observe",
-        integrity_mode: "observe",
-        principal: { type: "agent", identifier: agentId, relationship: "delegated_authority" },
-        values: { declared: ["transparency", "safety", "honesty"] },
-        autonomy: {
-            bounded_actions: ["respond_to_prompts"],
-            forbidden_actions: [],
-            escalation_triggers: [],
-        },
-        audit: { retention_days: 30, queryable: false, trace_format: "otel" },
-    }, { lineWidth: 120, noRefs: true });
+    const cardYaml = original ||
+        yaml.dump({
+            card_version: "unified/2026-04-26",
+            agent_id: agentId,
+            autonomy_mode: "observe",
+            integrity_mode: "observe",
+            principal: { type: "agent", identifier: agentId, relationship: "delegated_authority" },
+            values: { declared: ["transparency", "safety", "honesty"] },
+            autonomy: {
+                bounded_actions: ["respond_to_prompts"],
+                forbidden_actions: [],
+                escalation_triggers: [],
+            },
+            audit: { retention_days: 30, queryable: false, trace_format: "otel" },
+        }, { lineWidth: 120, noRefs: true });
     // Write to temp file
     const tmpDir = os.tmpdir();
     const tmpFile = path.join(tmpDir, `mnemom-card-${agentId}.yaml`);
@@ -703,7 +707,9 @@ export async function cardEditCommand(agentName, options = {}) {
         try {
             fs.unlinkSync(tmpFile);
         }
-        catch { /* ignore */ }
+        catch {
+            /* ignore */
+        }
         process.exit(1);
     }
     // Read back and compare
@@ -711,7 +717,9 @@ export async function cardEditCommand(agentName, options = {}) {
     try {
         fs.unlinkSync(tmpFile);
     }
-    catch { /* ignore */ }
+    catch {
+        /* ignore */
+    }
     if (edited === cardYaml) {
         console.log("\nNo changes made.\n");
         return;
@@ -808,7 +816,10 @@ export async function cardEvaluateCommand(file, options) {
     // 2. Parse tool list from --tools or --tool-manifest
     let tools = [];
     if (options.tools) {
-        tools = options.tools.split(",").map((t) => ({ name: t.trim() })).filter((t) => t.name);
+        tools = options.tools
+            .split(",")
+            .map((t) => ({ name: t.trim() }))
+            .filter((t) => t.name);
     }
     else if (options.toolManifest) {
         const manifestPath = path.resolve(options.toolManifest);

package/dist/commands/governance.d.ts

@@ -0,0 +1,85 @@
+/**
+ * `mnemom governance` — operator CLI for governance signals (ADR-048).
+ *
+ * Subcommands:
+ *
+ *   signals      list | show | ack | resolve | dismiss
+ *   destinations list | add | remove | test
+ *   rules        list | add | remove
+ *
+ * The signal surface is operator-actionable: cron-driven sideband
+ * detections, future protection / posture observations. Distinct from
+ * `mnemom advisories list` (now narrowed to runtime.* / manual.* per
+ * ADR-048 §1).
+ */
+interface ListOpts {
+    org?: string;
+    team?: string;
+    agent?: string;
+    source?: string;
+    severity?: string;
+    status?: string;
+    scope?: string;
+    patternType?: string;
+    limit?: string;
+    since?: string;
+    json?: boolean;
+}
+interface AckOpts {
+    action?: string;
+    json?: boolean;
+}
+interface ResolveOpts {
+    status: string;
+    action?: string;
+    json?: boolean;
+}
+interface DismissOpts {
+    reason?: string;
+    json?: boolean;
+}
+interface DestAddOpts {
+    org: string;
+    channel: string;
+    config: string;
+    name?: string;
+    filter?: string;
+    json?: boolean;
+}
+interface RuleAddOpts {
+    org: string;
+    name: string;
+    predicate: string;
+    destinations: string;
+    json?: boolean;
+}
+export declare function governanceSignalsListCommand(opts: ListOpts): Promise<void>;
+export declare function governanceSignalsShowCommand(signalId: string, opts: {
+    json?: boolean;
+}): Promise<void>;
+export declare function governanceSignalsAckCommand(signalId: string, opts: AckOpts): Promise<void>;
+export declare function governanceSignalsResolveCommand(signalId: string, opts: ResolveOpts): Promise<void>;
+export declare function governanceSignalsDismissCommand(signalId: string, opts: DismissOpts): Promise<void>;
+export declare function governanceDestinationsListCommand(opts: {
+    org: string;
+    json?: boolean;
+}): Promise<void>;
+export declare function governanceDestinationsAddCommand(opts: DestAddOpts): Promise<void>;
+export declare function governanceDestinationsRemoveCommand(destinationId: string, opts: {
+    org: string;
+    json?: boolean;
+}): Promise<void>;
+export declare function governanceDestinationsTestCommand(destinationId: string, opts: {
+    org: string;
+    json?: boolean;
+}): Promise<void>;
+export declare function governanceRulesListCommand(opts: {
+    org: string;
+    json?: boolean;
+}): Promise<void>;
+export declare function governanceRulesAddCommand(opts: RuleAddOpts): Promise<void>;
+export declare function governanceRulesRemoveCommand(ruleId: string, opts: {
+    org: string;
+    json?: boolean;
+}): Promise<void>;
+export {};