@mnemom/mnemom 0.12.1 → 0.14.0

package/dist/commands/logs.js

@@ -1,4 +1,4 @@
-import { resolveAgentId, getTraces } from "../lib/api.js";
+import { resolveAgentId, getTraces, MnemomApiError } from "../lib/api.js";
 import { getGatewayUrl } from "../lib/config.js";
 import { fmt } from "../lib/format.js";
 export async function logsCommand(options = {}) {
@@ -23,12 +23,16 @@ export async function logsCommand(options = {}) {
         console.log(`Dashboard: https://mnemon.ai/dashboard/${agentId}\n`);
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        if (message.includes("404") || message.includes("not found")) {
+        // A 404 means the agent isn't registered yet — treat as the empty state.
+        // Branch on effectiveStatus (not status): the enforce hook rewrites an
+        // undocumented 404 to a synthetic 500 carrying spec_deviation.original_status;
+        // effectiveStatus surfaces the true status (=== status when documented).
+        if (error instanceof MnemomApiError && error.effectiveStatus === 404) {
             console.log(fmt.header("No traces found"));
             console.log("\nStart using Claude to generate traces.\n");
         }
         else {
+            const message = error instanceof Error ? error.message : String(error);
             console.log("\n" + fmt.error(`Failed to fetch traces: ${message}`) + "\n");
             process.exit(1);
         }
@@ -36,16 +40,28 @@ export async function logsCommand(options = {}) {
 }
 function displayTrace(trace) {
     const timestamp = formatTimestamp(trace.timestamp);
-    const statusMsg = trace.verified ? fmt.success(timestamp) : fmt.error(`${timestamp} [VIOLATION]`);
+    // `verification` is null when the trace hasn't been verified yet — that is NOT
+    // a violation. Only flag [VIOLATION] when verification exists AND verified===false.
+    // (The old flat `trace.verified` was always undefined on the nested wire → every
+    // trace was mis-flagged [VIOLATION] and the action rendered as "[object Object]".)
+    const verified = trace.verification?.verified ?? true;
+    const statusMsg = verified ? fmt.success(timestamp) : fmt.error(`${timestamp} [VIOLATION]`);
     console.log(`\n  ${statusMsg}`);
-    console.log(`  ${fmt.label("Action:", ` ${trace.action}`)}`);
-    if (trace.tool_name) {
-        console.log(`  ${fmt.label("Tool:  ", ` ${trace.tool_name}`)}`);
+    // action.name is the canonical label (the tool name lives here in the AIP-nested
+    // shape); fall back to the action type, then a dash.
+    const actionLabel = trace.action?.name ?? trace.action?.type ?? "—";
+    console.log(`  ${fmt.label("Action:", ` ${actionLabel}`)}`);
+    if (trace.action?.category) {
+        console.log(`  ${fmt.label("Type:  ", ` ${trace.action.category}`)}`);
     }
-    if (trace.reasoning) {
-        const preview = truncate(trace.reasoning, 60);
+    const reasoning = trace.decision?.selection_reasoning;
+    if (reasoning) {
+        const preview = truncate(reasoning, 60);
         console.log(`  ${fmt.label("Reason:", ` ${preview}`)}`);
     }
+    if (trace.verification && trace.verification.violations.length > 0) {
+        console.log(`  ${fmt.label("Issues:", ` ${trace.verification.violations.join(", ")}`)}`);
+    }
 }
 function formatTimestamp(iso) {
     try {

package/dist/commands/protection.d.ts

@@ -16,7 +16,10 @@ export declare function protectionShowCommand(agentName?: string): Promise<void>
 export declare function protectionPublishCommand(file: string, agentName?: string, options?: {
     idempotencyKey?: string;
 }): Promise<void>;
-export declare function protectionValidateCommand(file: string): Promise<void>;
+export declare function protectionValidateCommand(file: string, opts?: {
+    offline?: boolean;
+    agent?: string;
+}): Promise<void>;
 export declare function protectionEditCommand(agentName?: string, options?: {
     idempotencyKey?: string;
 }): Promise<void>;

package/dist/commands/protection.js

@@ -3,7 +3,7 @@ import * as path from "node:path";
 import * as os from "node:os";
 import { spawnSync } from "node:child_process";
 import yaml from "js-yaml";
-import { PROTECTION_CARD_MAX_BYTES, getProtectionCard, putProtectionCard, resolveAgentId, } from "../lib/api.js";
+import { PROTECTION_CARD_MAX_BYTES, getProtectionCard, putProtectionCard, resolveAgentId, getAgentByName, previewComposeAgentCard, MnemomApiError, } from "../lib/api.js";
 import { requireAuth } from "../lib/auth.js";
 import { fmt } from "../lib/format.js";
 import { askYesNo, isInteractive } from "../lib/prompt.js";
@@ -443,7 +443,28 @@ export async function protectionPublishCommand(file, agentName, options = {}) {
         process.exit(1);
     }
 }
-export async function protectionValidateCommand(file) {
+// Agent-resolution regex (distinct from the trusted-sources AGENT_ID_RE above,
+// which validates card-embedded agent ids). This matches the gateway agent-id
+// shapes used by resolveAgentId so we can use a value directly without a lookup.
+const RESOLVE_AGENT_ID_RE = /^(smolt-[0-9a-f]{8}|mnm-[0-9a-f-]{36})$/;
+/**
+ * Soft agent resolution for `validate`: returns an agent id WITHOUT exiting the
+ * process. null ⇒ no agent configured / unresolvable → offline fallback.
+ */
+async function softResolveAgentId(agent) {
+    const name = agent ?? process.env.MNEMOM_AGENT;
+    if (!name)
+        return null;
+    if (RESOLVE_AGENT_ID_RE.test(name))
+        return name;
+    try {
+        return (await getAgentByName(name))?.id ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function protectionValidateCommand(file, opts = {}) {
     const filePath = path.resolve(file);
     if (!fs.existsSync(filePath)) {
         console.log("\n" + fmt.error(`File not found: ${filePath}`) + "\n");
@@ -458,6 +479,30 @@ export async function protectionValidateCommand(file) {
         console.log("\n" + fmt.error(`Could not parse file: ${msg}`) + "\n");
         process.exit(1);
     }
+    // Prefer server-authoritative validation when online + an agent is available;
+    // fall back to the local validator on 401/network. `--offline` forces local. (#9)
+    if (!opts.offline) {
+        const agentId = await softResolveAgentId(opts.agent);
+        if (agentId) {
+            const contentType = parsed.format === "yaml" ? "text/yaml" : "application/json";
+            try {
+                const result = await previewComposeAgentCard(agentId, "protection", parsed.raw, contentType);
+                renderServerProtectionValidation(result, filePath, parsed.format);
+                return;
+            }
+            catch (err) {
+                if (err instanceof MnemomApiError && err.status !== 401) {
+                    console.log("\n" + fmt.error(`Server validation failed: ${err.message}`) + "\n");
+                    process.exit(1);
+                }
+                process.stderr.write(fmt.warn("offline validation — server rules may differ") + "\n");
+            }
+        }
+        else if (!opts.agent && !process.env.MNEMOM_AGENT) {
+            process.stderr.write(fmt.dim("tip: pass --agent <name> to validate against the server (org/platform floor)") +
+                "\n");
+        }
+    }
     const checks = validateProtectionCard(parsed.parsed);
     const allPassed = checks.every((c) => c.passed);
     const passCount = checks.filter((c) => c.passed).length;
@@ -484,6 +529,33 @@ export async function protectionValidateCommand(file) {
         process.exit(1);
     }
 }
+/** Render a server-authoritative preview-compose result; exit 1 if invalid. */
+function renderServerProtectionValidation(result, filePath, format) {
+    console.log(fmt.header("Protection Card Validation (server-authoritative)"));
+    console.log();
+    console.log(fmt.label("  File:", ` ${filePath}`));
+    console.log(fmt.label("  Format:", ` ${format.toUpperCase()}`));
+    console.log();
+    if (result.valid) {
+        console.log(fmt.success("Server accepted and composed the card."));
+        const conflicts = result.conflicts ?? [];
+        if (conflicts.length > 0) {
+            console.log(fmt.warn(`${conflicts.length} field(s) tightened by the org/platform floor:`));
+            console.log(fmt.json(conflicts));
+        }
+        console.log();
+        return;
+    }
+    console.log(fmt.error(`Server rejected the card${result.error?.code ? ` (${result.error.code})` : ""}:`));
+    if (result.error?.message)
+        console.log(`  ${result.error.message}`);
+    if (result.error?.details !== undefined) {
+        console.log();
+        console.log(fmt.json(result.error.details));
+    }
+    console.log();
+    process.exit(1);
+}
 export async function protectionEditCommand(agentName, options = {}) {
     const agentId = await resolveAgentId(agentName);
     await requireAuth();
@@ -506,8 +578,11 @@ export async function protectionEditCommand(agentName, options = {}) {
             },
             trusted_sources: { domains: [], agent_ids: [], ip_ranges: [] },
         }, { lineWidth: 120, noRefs: true });
-    const tmpDir = os.tmpdir();
-    const tmpFile = path.join(tmpDir, `mnemom-protection-${agentId}.yaml`);
+    // Per-invocation temp dir via mkdtemp (mode 0700, unpredictable suffix) so
+    // the editor file can't be pre-created or symlink-raced by another user in
+    // the shared os.tmpdir().
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "mnemom-protection-"));
+    const tmpFile = path.join(tmpDir, `${agentId}.yaml`);
     fs.writeFileSync(tmpFile, cardYaml);
     const editor = process.env.EDITOR || process.env.VISUAL || "vi";
     console.log(`Opening ${editor}...`);

package/dist/commands/status.js

@@ -1,5 +1,5 @@
 import { getGatewayUrl } from "../lib/config.js";
-import { resolveAgentId, getAgent, getIntegrity, getTraces } from "../lib/api.js";
+import { resolveAgentId, getAgent, getIntegrity, getTraces, MnemomApiError } from "../lib/api.js";
 import { isLoggedIn, getAuthInfo } from "../lib/auth.js";
 import { fmt } from "../lib/format.js";
 const DASHBOARD_URL = "https://mnemom.ai";
@@ -133,8 +133,10 @@ async function checkApiConnectivity(agentId) {
         };
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        if (message.includes("404") || message.includes("not found")) {
+        // 404 = agent not registered yet. Branch on effectiveStatus (enforce hook may
+        // rewrite an undocumented 404 → synthetic 500 + spec_deviation.original_status;
+        // effectiveStatus === status when documented). getAgent → fetchApi → MnemomApiError.
+        if (error instanceof MnemomApiError && error.effectiveStatus === 404) {
             return {
                 name: "API",
                 status: "warning",
@@ -142,7 +144,13 @@ async function checkApiConnectivity(agentId) {
                 details: "Will register on first traced API call",
             };
         }
-        if (message.includes("timeout") || message.includes("TIMEOUT")) {
+        const message = error instanceof Error ? error.message : String(error);
+        // Transport-level timeout (no HTTP status, not an envelope error) — detect by
+        // the AbortSignal.timeout error name, with a message fallback for runtimes that
+        // don't set it.
+        if ((error instanceof Error && error.name === "TimeoutError") ||
+            message.includes("timeout") ||
+            message.includes("TIMEOUT")) {
             return {
                 name: "API",
                 status: "error",

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 #!/usr/bin/env node
-export {};
+import { program } from "commander";
+export { program };

package/dist/index.js

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
+import { pathToFileURL } from "node:url";
 import { program } from "commander";
+import { CLI_VERSION } from "./version.js";
 import { statusCommand } from "./commands/status.js";
 import { integrityCommand } from "./commands/integrity.js";
 import { logsCommand } from "./commands/logs.js";
@@ -7,7 +9,7 @@ import { licenseActivateCommand, licenseStatusCommand, licenseDeactivateCommand,
 import { cardShowCommand, cardPublishCommand, cardValidateCommand, cardEditCommand, cardEvaluateCommand, } from "./commands/card.js";
 import { policyInitCommand, policyValidateCommand, policyPublishCommand, policyListCommand, policyTestCommand, policyEvaluateCommand, } from "./commands/policy.js";
 import { protectionShowCommand, protectionPublishCommand, protectionValidateCommand, protectionEditCommand, } from "./commands/protection.js";
-import { agentsListCommand } from "./commands/agents.js";
+import { agentsListCommand, agentsClaimCommand } from "./commands/agents.js";
 import { orgListCommand, orgShowCommand } from "./commands/org.js";
 import { teamListCommand, teamShowCommand, teamTemplateCommand, teamPreviewComposeCommand, teamAdminGrantCommand, teamAdminRevokeCommand, teamAdminListCommand, teamCoverageCommand, } from "./commands/team.js";
 import { advisoriesListCommand, advisoriesShowCommand } from "./commands/advisories.js";
@@ -20,7 +22,7 @@ import { listenCommand } from "./commands/listen.js";
 program
     .name("mnemom")
     .description("Transparent AI agent tracing")
-    .version("0.9.1")
+    .version(CLI_VERSION)
     .option("--agent <name>", "Select agent by name (or set MNEMOM_AGENT)");
 program
     .command("status")
@@ -149,10 +151,12 @@ cardCmd
 cardCmd
     .command("validate")
     .argument("<file>", "Path to alignment card file (YAML or JSON)")
-    .description("Validate alignment card locally")
-    .action(async (file) => {
+    .description("Validate an alignment card (server-authoritative when --agent is set; --offline forces local)")
+    .option("--offline", "Validate locally only (skip the server preview-compose)")
+    .action(async (file, subOpts) => {
     try {
-        await cardValidateCommand(file);
+        const opts = program.opts();
+        await cardValidateCommand(file, { offline: subOpts.offline, agent: opts.agent });
     }
     catch (error) {
         console.error("Error:", error instanceof Error ? error.message : error);
@@ -224,10 +228,12 @@ protectionCmd
 protectionCmd
     .command("validate")
     .argument("<file>", "Path to protection card file (YAML or JSON)")
-    .description("Validate protection card locally")
-    .action(async (file) => {
+    .description("Validate a protection card (server-authoritative when --agent is set; --offline forces local)")
+    .option("--offline", "Validate locally only (skip the server preview-compose)")
+    .action(async (file, subOpts) => {
     try {
-        await protectionValidateCommand(file);
+        const opts = program.opts();
+        await protectionValidateCommand(file, { offline: subOpts.offline, agent: opts.agent });
     }
     catch (error) {
         console.error("Error:", error instanceof Error ? error.message : error);
@@ -290,12 +296,36 @@ policyCmd
 // ============================================================================
 // Agent management
 // ============================================================================
-program
+const agentsCmd = program
     .command("agents")
-    .description("List agents in your account")
-    .action(async () => {
+    .description("List agents across the orgs you belong to (ADR-062 org-scoped)")
+    .option("--org <id>", "Scope to a single org (default: all orgs you belong to)")
+    .action(async (opts) => {
     try {
-        await agentsListCommand();
+        await agentsListCommand({ org: opts.org });
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
+agentsCmd
+    .command("claim <id-or-name>")
+    .description("Claim an agent into an org (ADR-062 claim-to-org)")
+    .option("--org <slug>", "Org slug or id to claim into (default: your personal org)")
+    .option("--key <key>", "The agent's provider API key — the CLI derives the hash proof from it")
+    .option("--hash-proof <hex>", "A pre-computed 64-hex SHA-256 proof (advanced/CI; alternative to --key)")
+    .option("--name <name>", "Provisioned agent name used in proof derivation (defaults to a name-shaped positional arg)")
+    .option("--json", "Output JSON instead of human-readable text")
+    .action(async (idOrName, opts) => {
+    try {
+        await agentsClaimCommand(idOrName, {
+            org: opts.org,
+            key: opts.key,
+            hashProof: opts.hashProof,
+            name: opts.name,
+            json: opts.json,
+        });
     }
     catch (error) {
         console.error("Error:", error instanceof Error ? error.message : error);
@@ -1291,4 +1321,13 @@ program
         process.exit(1);
     }
 });
-program.parse();
+// Export the fully-assembled commander program so tooling (e.g. the
+// command-tree snapshot generator in scripts/gen-command-tree.mjs) can
+// statically introspect the command surface WITHOUT executing the CLI.
+export { program };
+// Parse argv only when invoked as the CLI entrypoint — not when imported.
+// (ESM has no `require.main`; compare this module's URL to argv[1].)
+const invokedDirectly = process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (invokedDirectly) {
+    program.parse();
+}