@mnemom/mnemom 0.17.21 → 0.17.22

package/README.md

@@ -45,6 +45,7 @@ That's it. `mnemom init` detects your configured AI provider API keys (Anthropic
 | `mnemom card validate <file>` | Validate card JSON locally                           |
 | `mnemom usage --org <id>`     | Show per-person token and request consumption        |
 | `mnemom agent [name]`         | Launch a governed coding agent through the gateway   |
+| `mnemom agent export [agent]` | Save an agent's full record to a file (JSON or CSV)  |
 
 ### `mnemom agent` — goal alignment
 
@@ -244,6 +245,31 @@ export MNEMOM_COMPACT_AT=200k                   # for every launch in this shell
 Code default (1M)`) and, when a target is set, the decoded session-config keys; the session
 ledger records the effective value.
 
+### `mnemom agent export` — an agent's full record
+
+`mnemom agent export [id-or-name]` saves the agent's full record — integrity checkpoints, score
+history, reclassifications, card amendments, disagreement reviews and policy evaluations with
+gaps — to `./mnemom-record-<agent>-<date>.json` (`--format csv` for CSV). Without an agent it
+uses `MNEMOM_AGENT`, else the agent saved in `~/.mnemom/launcher.toml` (`mnemom agent config
+set agent …`), else the agent of your latest `mnemom agent` launch. You need to be a member of
+the org that owns the agent.
+
+```bash
+mnemom agent export my-agent                        # everything, as JSON
+mnemom agent export my-agent --since 30d            # the last 30 days
+mnemom agent export my-agent --from 2026-09-01 --to 2026-09-30 --format csv
+mnemom agent export my-agent -o - | jq '.checkpoints | length'   # stdout; summary on stderr
+```
+
+`--from`/`--to` take an ISO-8601 date or datetime (a bare `--to` date includes that whole UTC
+day). The command refuses to overwrite an existing file unless you pass `--force`, and prints a
+summary: the period, rows per section, a SHA-256 checksum of the file (so a recipient can
+confirm it was not altered in transit) and the agent's public verification links. The file
+holds full checkpoint reasoning that outsiders normally see redacted, so it is written
+readable by you only (mode 0600); to prove the agent's record to someone without sharing the
+contents, send the public verification link instead. If the period is too large to export in
+one go, narrow it with `--since`, `--from` or `--to`.
+
 ## How It Works
 
 ```

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

@@ -0,0 +1,53 @@
+/**
+ * `mnemom agent export [id-or-name]` — download an agent's full record
+ * (`GET /v1/agents/{id}/compliance-export`) to a file, or to stdout with `-o -`.
+ *
+ * Without `[id-or-name]` the agent is, in order: MNEMOM_AGENT, the saved
+ * `agent` in ~/.mnemom/launcher.toml, then the agent of the newest launch in the
+ * session ledger (lib/agent-export.ts pickAgentRef).
+ *
+ * Pure apart from the injected deps (`resolveAgentId`, `agentSources`,
+ * `fetchExport`, `writeFile`, `writeStdout`, `out`, `err`, `now`), so every arm is
+ * unit-tested; `liveExportDeps` is the thin driver index.ts wires in. The
+ * parsing, counts, summary and error wording live in lib/agent-export.ts.
+ *
+ * Returns the process exit code (0 ok, 1 on any error) instead of exiting, so
+ * index.ts sets `process.exitCode` from it.
+ */
+import { type DefaultAgentSources, type ExportFlags } from "../lib/agent-export.js";
+export interface AgentExportDeps {
+    /** id-or-name → agent id. Exits itself when unresolvable. */
+    resolveAgentId: (ref: string) => Promise<string>;
+    /** Where the agent comes from when no `[id-or-name]` is given. */
+    agentSources: DefaultAgentSources;
+    fetchExport: (agentId: string, query: string) => Promise<{
+        body: Uint8Array;
+        headers: Headers;
+    }>;
+    /** Write owner-only (0600). Without `force`, throws EEXIST when the file exists. */
+    writeFile: (path: string, bytes: Uint8Array, force: boolean) => void;
+    writeStdout: (bytes: Uint8Array) => void;
+    out: (line: string) => void;
+    err: (line: string) => void;
+    now: () => Date;
+    apiBase: () => string;
+    websiteBase: () => string;
+}
+export interface PrivateFileOps {
+    chmodSync: (path: string, mode: number) => void;
+    writeFileSync: (path: string, bytes: Uint8Array, opts: {
+        mode: number;
+        flag: string;
+    }) => void;
+}
+/**
+ * Write `bytes` to `path` readable by the owner only. Without `force`, `wx`
+ * makes the no-overwrite check and the create one step. With `force`, an
+ * existing file is narrowed to 0600 BEFORE the write (so the new contents are
+ * never readable under its old mode) — chmod-and-catch-ENOENT rather than
+ * exists-then-chmod — and chmod'ed again after, since `writeFileSync` only
+ * applies `mode` to a file it creates.
+ */
+export declare function writePrivateFile(path: string, bytes: Uint8Array, force: boolean, ops?: PrivateFileOps): void;
+export declare const liveExportDeps: AgentExportDeps;
+export declare function agentExportCommand(ref: string | undefined, flags: ExportFlags, deps: AgentExportDeps): Promise<number>;

package/dist/commands/agent-export.js

@@ -0,0 +1,127 @@
+/**
+ * `mnemom agent export [id-or-name]` — download an agent's full record
+ * (`GET /v1/agents/{id}/compliance-export`) to a file, or to stdout with `-o -`.
+ *
+ * Without `[id-or-name]` the agent is, in order: MNEMOM_AGENT, the saved
+ * `agent` in ~/.mnemom/launcher.toml, then the agent of the newest launch in the
+ * session ledger (lib/agent-export.ts pickAgentRef).
+ *
+ * Pure apart from the injected deps (`resolveAgentId`, `agentSources`,
+ * `fetchExport`, `writeFile`, `writeStdout`, `out`, `err`, `now`), so every arm is
+ * unit-tested; `liveExportDeps` is the thin driver index.ts wires in. The
+ * parsing, counts, summary and error wording live in lib/agent-export.ts.
+ *
+ * Returns the process exit code (0 ok, 1 on any error) instead of exiting, so
+ * index.ts sets `process.exitCode` from it.
+ */
+import { chmodSync, writeFileSync } from "node:fs";
+import { readSessionRecords } from "../lib/agent-ledger.js";
+import { getComplianceExport, resolveAgentId } from "../lib/api.js";
+import { getApiUrl, getWebsiteUrl, MNEMOM_DIR } from "../lib/config.js";
+import { loadLauncherConfig } from "../lib/launcher-config.js";
+import { buildExportQuery, buildSummary, defaultOutputPath, exportErrorMessage, extractCounts, filenameLabel, formatSummaryLines, NO_AGENT_MESSAGE, parseExportFlags, pickAgentRef, sensitivityNote, writeErrorMessage, } from "../lib/agent-export.js";
+import { fmt } from "../lib/format.js";
+/**
+ * Write `bytes` to `path` readable by the owner only. Without `force`, `wx`
+ * makes the no-overwrite check and the create one step. With `force`, an
+ * existing file is narrowed to 0600 BEFORE the write (so the new contents are
+ * never readable under its old mode) — chmod-and-catch-ENOENT rather than
+ * exists-then-chmod — and chmod'ed again after, since `writeFileSync` only
+ * applies `mode` to a file it creates.
+ */
+export function writePrivateFile(path, bytes, force, ops = { chmodSync, writeFileSync }) {
+    if (force) {
+        try {
+            ops.chmodSync(path, 0o600);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+    ops.writeFileSync(path, bytes, { mode: 0o600, flag: force ? "w" : "wx" });
+    ops.chmodSync(path, 0o600);
+}
+export const liveExportDeps = {
+    resolveAgentId: (ref) => resolveAgentId(ref),
+    agentSources: {
+        env: () => process.env.MNEMOM_AGENT,
+        configAgent: () => loadLauncherConfig().agent,
+        // The ledger is oldest-first on disk.
+        ledger: () => readSessionRecords({ dir: MNEMOM_DIR }).reverse(),
+    },
+    fetchExport: (agentId, query) => getComplianceExport(agentId, query),
+    writeFile: (path, bytes, force) => writePrivateFile(path, bytes, force),
+    writeStdout: (bytes) => {
+        process.stdout.write(bytes);
+    },
+    out: (line) => console.log(line),
+    err: (line) => console.error(line),
+    now: () => new Date(),
+    apiBase: getApiUrl,
+    websiteBase: getWebsiteUrl,
+};
+export async function agentExportCommand(ref, flags, deps) {
+    const now = deps.now();
+    let parsed;
+    try {
+        parsed = parseExportFlags(flags, now);
+    }
+    catch (error) {
+        deps.err(fmt.error(error.message));
+        return 1;
+    }
+    let target;
+    try {
+        target = pickAgentRef(ref, deps.agentSources);
+    }
+    catch (error) {
+        // A malformed ~/.mnemom/launcher.toml — its message names the file to fix.
+        deps.err(fmt.error(error.message));
+        return 1;
+    }
+    if (target === null) {
+        deps.err(fmt.error(NO_AGENT_MESSAGE));
+        return 1;
+    }
+    const agentId = await deps.resolveAgentId(target.ref);
+    const output = parsed.output ?? defaultOutputPath(filenameLabel(target.label, agentId), parsed.format, now);
+    const toStdout = output === "-";
+    let response;
+    try {
+        response = await deps.fetchExport(agentId, buildExportQuery(parsed.format, parsed.period));
+    }
+    catch (error) {
+        deps.err(fmt.error(exportErrorMessage(error, agentId)));
+        return 1;
+    }
+    try {
+        if (toStdout)
+            deps.writeStdout(response.body);
+        else
+            deps.writeFile(output, response.body, parsed.force);
+    }
+    catch (error) {
+        deps.err(fmt.error(writeErrorMessage(error, output)));
+        return 1;
+    }
+    const summary = buildSummary({
+        agentId,
+        output,
+        format: parsed.format,
+        period: parsed.period,
+        body: response.body,
+        counts: extractCounts(parsed.format, response.body, response.headers),
+        websiteBase: deps.websiteBase(),
+        apiBase: deps.apiBase(),
+    });
+    // With `-o -` stdout carries the record itself, so the summary goes to stderr.
+    const say = toStdout ? deps.err : deps.out;
+    if (parsed.json)
+        say(JSON.stringify(summary, null, 2));
+    else
+        for (const line of formatSummaryLines(summary))
+            say(line);
+    deps.err(fmt.dim(sensitivityNote(toStdout)));
+    return 0;
+}

package/dist/index.js

@@ -13,6 +13,7 @@ import { cardShowCommand, cardPublishCommand, cardValidateCommand, cardEditComma
 import { policyInitCommand, policyValidateCommand, policyPublishCommand, policyListCommand, policyTestCommand, policyEvaluateCommand, } from "./commands/policy.js";
 import { protectionShowCommand, protectionPublishCommand, protectionValidateCommand, protectionEditCommand, protectionDriftCommand, } from "./commands/protection.js";
 import { agentsListCommand, agentsClaimCommand, agentsMoveCommand } from "./commands/agents.js";
+import { agentExportCommand, liveExportDeps } from "./commands/agent-export.js";
 import { agentSessionsCommand, agentShowCommand, liveSessionDeps, } from "./commands/agent-sessions.js";
 import { agentGoalPinCommand, agentGoalResetCommand, agentGoalShowCommand, liveGoalDeps, } from "./commands/agent-goal.js";
 import { orgListCommand, orgShowCommand, orgUseCommand } from "./commands/org.js";
@@ -144,7 +145,7 @@ function printAgentHelp(verb) {
 const agentCmd = program
     .command("agent [session] [passthrough...]")
     .description("Launch your governed agent (Claude Code in v1) through the Mnemom gateway — governed identity + optional sealed goal contract. Plain `mnemom agent` asks for a session name. " +
-    "Sub-verbs: `setup` provisions your governed agent; `doctor` preflights prerequisites; `config …` manages persistent settings (~/.mnemom/launcher.toml); `--invite <token>` redeems a Mnemom Agent invitation (the one-liner your invitation email shows; `invite <token>` is its alias); `list` / `claim` / `move` manage the agents in your orgs; `sessions` lists your past launches and `show [ref]` merges one with its live goal state; `help [verb]` prints help and never launches.")
+    "Sub-verbs: `setup` provisions your governed agent; `doctor` preflights prerequisites; `config …` manages persistent settings (~/.mnemom/launcher.toml); `--invite <token>` redeems a Mnemom Agent invitation (the one-liner your invitation email shows; `invite <token>` is its alias); `list` / `claim` / `move` manage the agents in your orgs; `export` saves an agent's full record to a file; `sessions` lists your past launches and `show [ref]` merges one with its live goal state; `help [verb]` prints help and never launches.")
     .option("--goal <statement>", "Contract goal statement (required if any contract flag is given)")
     .option("--requirement <text>", "Contract requirement (repeatable)", collectRepeatable, [])
     .option("--allow <glob>", "Allowed path/glob (repeatable)", collectRepeatable, [])
@@ -875,6 +876,20 @@ agentCmd
         process.exit(1);
     }
 });
+agentCmd
+    .command("export [id-or-name]")
+    .description("Save an agent's full record (checkpoints, score history, corrections) to a file. " +
+    "Without id-or-name: MNEMOM_AGENT, else the saved agent (mnemom agent config), else the agent of your latest launch")
+    .option("--format <json|csv>", "File format (default: json)")
+    .option("--since <Nd|Nh>", "Only the last N days or hours (instead of --from)")
+    .option("--from <date>", "Start of the period (ISO-8601 date or datetime)")
+    .option("--to <date>", "End of the period (ISO-8601 date or datetime; a date includes that day)")
+    .option("-o, --output <file|->", "Where to write it; - for stdout (default: ./mnemom-record-<agent>-<date>.<format>)")
+    .option("--force", "Overwrite the output file if it exists")
+    .option("--json", "Print the summary as JSON")
+    .action(async (idOrName, opts) => {
+    process.exitCode = await agentExportCommand(idOrName, opts, liveExportDeps);
+});
 agentCmd
     .command("sessions")
     .description("List your Mnemom Agent sessions from the local ledger (~/.mnemom/sessions.jsonl), newest first — the last 20 unless --all")

package/dist/lib/agent-export.d.ts

@@ -0,0 +1,133 @@
+/**
+ * `mnemom agent export` — the pure half: option parsing (format, --since /
+ * --from / --to), the default output filename, the per-section counts (from the
+ * JSON body / the CSV `X-Mnemom-Export-Counts` header), the summary, and the
+ * error-message mapping. No I/O here; the command driver
+ * (commands/agent-export.ts) does the network and filesystem work, so every
+ * branch below is unit-tested directly.
+ *
+ * Server side: `GET /v1/agents/{id}/compliance-export?format=json|csv&from=&to=`
+ * (mnemom-api reclassification/handlers.ts handleComplianceExport). `from`/`to`
+ * are passed straight into PostgREST `gte.`/`lte.` filters, so they are
+ * normalised here to full UTC ISO timestamps.
+ */
+import type { SessionRecord } from "./agent-ledger.js";
+export type ExportFormat = "json" | "csv";
+/** The record's sections, in the order the summary prints them. */
+export declare const EXPORT_SECTIONS: readonly ["checkpoints", "score_history", "reclassifications", "card_amendments", "disagreement_reviews", "policy_evaluations_with_gaps"];
+export type ExportSection = (typeof EXPORT_SECTIONS)[number];
+/** Rows per section; null = the server didn't say (and it couldn't be derived). */
+export type ExportCounts = Record<ExportSection, number | null>;
+export declare const COUNTS_HEADER = "X-Mnemom-Export-Counts";
+/** A bad flag value — reported as-is, before any network call. */
+export declare class ExportUsageError extends Error {
+    constructor(message: string);
+}
+export interface ExportFlags {
+    format?: string;
+    since?: string;
+    from?: string;
+    to?: string;
+    output?: string;
+    force?: boolean;
+    json?: boolean;
+}
+export interface ExportPeriod {
+    from: string | null;
+    to: string | null;
+}
+export interface ParsedExportFlags {
+    format: ExportFormat;
+    period: ExportPeriod;
+    /** The -o value as given; undefined = use the default filename. "-" = stdout. */
+    output?: string;
+    force: boolean;
+    json: boolean;
+}
+export declare function parseFormat(raw: string | undefined): ExportFormat;
+/** `--since 7d` / `--since 12h` → the UTC ISO timestamp that long before `now`. */
+export declare function parseSince(raw: string, now: Date): string;
+/**
+ * Validate an ISO-8601 date or datetime for `--from` / `--to` and normalise it to
+ * a UTC ISO timestamp. A bare date is a UTC day: `--from` starts at its first
+ * millisecond and `--to` includes the whole day (ends at its last millisecond).
+ * A datetime with no offset is read in local time, like `new Date()` does.
+ */
+export declare function parseDateBound(raw: string, flag: "--from" | "--to"): string;
+/** Resolve `--since` / `--from` / `--to` into the period sent to the server. */
+export declare function resolvePeriod(flags: ExportFlags, now: Date): ExportPeriod;
+/** All the flag validation, done locally before any network call. */
+export declare function parseExportFlags(flags: ExportFlags, now: Date): ParsedExportFlags;
+/** `?format=…&from=…&to=…` for the compliance-export route. */
+export declare function buildExportQuery(format: ExportFormat, period: ExportPeriod): string;
+export declare const NO_AGENT_MESSAGE = "No agent given. Pass one: mnemom agent export <id-or-name> (see mnemom agent list)";
+/** What to resolve (`ref`, an id or name) and what to name the default file after (`label`). */
+export interface AgentRef {
+    ref: string;
+    label: string;
+}
+/** Where the no-argument default comes from; each is read only if the ones before it are empty. */
+export interface DefaultAgentSources {
+    /** MNEMOM_AGENT. */
+    env: () => string | undefined;
+    /** The saved `agent` in ~/.mnemom/launcher.toml (throws on a malformed file). */
+    configAgent: () => string | undefined;
+    /** The session ledger, newest launch first. */
+    ledger: () => SessionRecord[];
+}
+/**
+ * The agent to export: the positional `[id-or-name]` when given; else, in
+ * order, MNEMOM_AGENT, the saved launcher-config `agent`, and the agent of the
+ * newest launch in the session ledger that resolved one (resolved by id, named
+ * after its slug). null when none of them has an agent.
+ */
+export declare function pickAgentRef(given: string | undefined, sources: DefaultAgentSources): AgentRef | null;
+/** The filename-safe agent label: `label` sanitised; the resolved id when that leaves nothing. */
+export declare function filenameLabel(label: string, agentId: string): string;
+/** `./mnemom-record-<label>-<YYYY-MM-DD>.<json|csv>` (UTC date). */
+export declare function defaultOutputPath(label: string, format: ExportFormat, now: Date): string;
+/**
+ * Counts from a JSON export body: the server's `counts` object where it has a
+ * section, else the length of that section's array. null when the body is not
+ * a JSON object.
+ */
+export declare function countsFromJsonBody(text: string): ExportCounts | null;
+export declare function countsFromHeader(header: string | null): ExportCounts | null;
+export declare function extractCounts(format: ExportFormat, body: Uint8Array, headers: Headers): ExportCounts | null;
+export declare function sha256Hex(bytes: Uint8Array): string;
+export interface VerificationLinks {
+    reputation_url: string;
+    verify_url: string;
+}
+export declare function verificationLinks(agentId: string, websiteBase: string, apiBase: string): VerificationLinks;
+export interface ExportSummary {
+    agent_id: string;
+    /** The file written, or "-" for stdout. */
+    output: string;
+    format: ExportFormat;
+    period: ExportPeriod;
+    counts: ExportCounts | null;
+    bytes: number;
+    /** SHA-256 of the exact bytes written — a file checksum, not a signature. */
+    sha256: string;
+    verification: VerificationLinks;
+}
+export declare function buildSummary(input: {
+    agentId: string;
+    output: string;
+    format: ExportFormat;
+    period: ExportPeriod;
+    body: Uint8Array;
+    counts: ExportCounts | null;
+    websiteBase: string;
+    apiBase: string;
+}): ExportSummary;
+export declare function describePeriod(period: ExportPeriod): string;
+/** The human summary, one line per entry (no colour; the driver adds none). */
+export declare function formatSummaryLines(summary: ExportSummary): string[];
+/** The one-line sensitivity note (the driver prints it dim, on stderr). */
+export declare function sensitivityNote(toStdout: boolean): string;
+/** The user-facing message for a failed export request. */
+export declare function exportErrorMessage(error: unknown, agentId: string): string;
+/** The user-facing message for a failed file write. */
+export declare function writeErrorMessage(error: unknown, path: string): string;

package/dist/lib/agent-export.js

@@ -0,0 +1,293 @@
+/**
+ * `mnemom agent export` — the pure half: option parsing (format, --since /
+ * --from / --to), the default output filename, the per-section counts (from the
+ * JSON body / the CSV `X-Mnemom-Export-Counts` header), the summary, and the
+ * error-message mapping. No I/O here; the command driver
+ * (commands/agent-export.ts) does the network and filesystem work, so every
+ * branch below is unit-tested directly.
+ *
+ * Server side: `GET /v1/agents/{id}/compliance-export?format=json|csv&from=&to=`
+ * (mnemom-api reclassification/handlers.ts handleComplianceExport). `from`/`to`
+ * are passed straight into PostgREST `gte.`/`lte.` filters, so they are
+ * normalised here to full UTC ISO timestamps.
+ */
+import { createHash } from "node:crypto";
+import { sanitizeAgentName } from "./agent.js";
+import { MnemomApiError } from "./api.js";
+/** The record's sections, in the order the summary prints them. */
+export const EXPORT_SECTIONS = [
+    "checkpoints",
+    "score_history",
+    "reclassifications",
+    "card_amendments",
+    "disagreement_reviews",
+    "policy_evaluations_with_gaps",
+];
+export const COUNTS_HEADER = "X-Mnemom-Export-Counts";
+/** A bad flag value — reported as-is, before any network call. */
+export class ExportUsageError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ExportUsageError";
+    }
+}
+// ─── option parsing ───────────────────────────────────────────────────────────
+export function parseFormat(raw) {
+    const v = (raw ?? "json").trim().toLowerCase();
+    if (v === "json" || v === "csv")
+        return v;
+    throw new ExportUsageError(`--format must be json or csv (got "${raw}").`);
+}
+const SINCE_RE = /^(\d+)([dh])$/i;
+const HOUR_MS = 3_600_000;
+/** `--since 7d` / `--since 12h` → the UTC ISO timestamp that long before `now`. */
+export function parseSince(raw, now) {
+    const m = SINCE_RE.exec(raw.trim());
+    const n = m ? Number(m[1]) : 0;
+    if (!m || n <= 0) {
+        throw new ExportUsageError(`--since must be a positive number of days or hours, like 7d or 12h (got "${raw}").`);
+    }
+    const unitMs = m[2].toLowerCase() === "d" ? 24 * HOUR_MS : HOUR_MS;
+    return new Date(now.getTime() - n * unitMs).toISOString();
+}
+const DATE_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
+const DATETIME_RE = /^(\d{4})-(\d{2})-(\d{2})T\d{2}:\d{2}(:\d{2}(\.\d{1,9})?)?(Z|[+-]\d{2}:\d{2})?$/i;
+/** True when y-m-d is a real calendar day (rejects 2026-02-30, month 13, …). */
+function isCalendarDate(y, m, d) {
+    const date = new Date(Date.UTC(Number(y), Number(m) - 1, Number(d)));
+    return (date.getUTCFullYear() === Number(y) &&
+        date.getUTCMonth() === Number(m) - 1 &&
+        date.getUTCDate() === Number(d));
+}
+/**
+ * Validate an ISO-8601 date or datetime for `--from` / `--to` and normalise it to
+ * a UTC ISO timestamp. A bare date is a UTC day: `--from` starts at its first
+ * millisecond and `--to` includes the whole day (ends at its last millisecond).
+ * A datetime with no offset is read in local time, like `new Date()` does.
+ */
+export function parseDateBound(raw, flag) {
+    const v = raw.trim();
+    const dateOnly = DATE_RE.exec(v);
+    const parts = dateOnly ?? DATETIME_RE.exec(v);
+    const ms = parts ? Date.parse(v) : NaN;
+    if (!parts || Number.isNaN(ms) || !isCalendarDate(parts[1], parts[2], parts[3])) {
+        throw new ExportUsageError(`${flag} must be an ISO-8601 date or datetime, like 2026-09-01 or 2026-09-01T09:30:00Z (got "${raw}").`);
+    }
+    if (dateOnly && flag === "--to")
+        return `${v}T23:59:59.999Z`;
+    return new Date(ms).toISOString();
+}
+/** Resolve `--since` / `--from` / `--to` into the period sent to the server. */
+export function resolvePeriod(flags, now) {
+    if (flags.since !== undefined && flags.from !== undefined) {
+        throw new ExportUsageError("Use either --since or --from, not both.");
+    }
+    const from = flags.since !== undefined
+        ? parseSince(flags.since, now)
+        : flags.from !== undefined
+            ? parseDateBound(flags.from, "--from")
+            : null;
+    const to = flags.to !== undefined ? parseDateBound(flags.to, "--to") : null;
+    if (from !== null && to !== null && from > to) {
+        throw new ExportUsageError(`The start of the period (${from}) is after its end (${to}).`);
+    }
+    return { from, to };
+}
+/** All the flag validation, done locally before any network call. */
+export function parseExportFlags(flags, now) {
+    const output = flags.output?.trim();
+    if (output === "")
+        throw new ExportUsageError("-o/--output needs a file path, or - for stdout.");
+    return {
+        format: parseFormat(flags.format),
+        period: resolvePeriod(flags, now),
+        output,
+        force: flags.force === true,
+        json: flags.json === true,
+    };
+}
+/** `?format=…&from=…&to=…` for the compliance-export route. */
+export function buildExportQuery(format, period) {
+    const params = new URLSearchParams({ format });
+    if (period.from !== null)
+        params.set("from", period.from);
+    if (period.to !== null)
+        params.set("to", period.to);
+    return `?${params.toString()}`;
+}
+// ─── agent ────────────────────────────────────────────────────────────────────
+export const NO_AGENT_MESSAGE = "No agent given. Pass one: mnemom agent export <id-or-name> (see mnemom agent list)";
+/**
+ * The agent to export: the positional `[id-or-name]` when given; else, in
+ * order, MNEMOM_AGENT, the saved launcher-config `agent`, and the agent of the
+ * newest launch in the session ledger that resolved one (resolved by id, named
+ * after its slug). null when none of them has an agent.
+ */
+export function pickAgentRef(given, sources) {
+    const named = given?.trim() || sources.env()?.trim() || sources.configAgent()?.trim();
+    if (named)
+        return { ref: named, label: named };
+    const launch = sources
+        .ledger()
+        .find((r) => Boolean(r.agent_id));
+    if (!launch)
+        return null;
+    return { ref: launch.agent_id, label: launch.agent_slug || launch.agent_id };
+}
+// ─── output path ──────────────────────────────────────────────────────────────
+/** The filename-safe agent label: `label` sanitised; the resolved id when that leaves nothing. */
+export function filenameLabel(label, agentId) {
+    return sanitizeAgentName(label) || sanitizeAgentName(agentId);
+}
+/** `./mnemom-record-<label>-<YYYY-MM-DD>.<json|csv>` (UTC date). */
+export function defaultOutputPath(label, format, now) {
+    return `./mnemom-record-${label}-${now.toISOString().slice(0, 10)}.${format}`;
+}
+// ─── counts ───────────────────────────────────────────────────────────────────
+function isCount(v) {
+    return typeof v === "number" && Number.isInteger(v) && v >= 0;
+}
+/**
+ * Counts from a JSON export body: the server's `counts` object where it has a
+ * section, else the length of that section's array. null when the body is not
+ * a JSON object.
+ */
+export function countsFromJsonBody(text) {
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (body === null || typeof body !== "object" || Array.isArray(body))
+        return null;
+    const record = body;
+    const declared = record.counts !== null && typeof record.counts === "object"
+        ? record.counts
+        : {};
+    const counts = {};
+    for (const section of EXPORT_SECTIONS) {
+        const fromServer = declared[section];
+        const rows = record[section];
+        counts[section] = isCount(fromServer) ? fromServer : Array.isArray(rows) ? rows.length : null;
+    }
+    return counts;
+}
+/**
+ * Counts from the CSV response header
+ * `checkpoints=N;score_history=N;…`. null when the header is absent or carries
+ * no recognisable section (an older API) — the summary then says so.
+ */
+const COUNT_PAIR_RE = /^\s*([a-z_]+)\s*=\s*(\d+)\s*$/;
+export function countsFromHeader(header) {
+    if (header === null)
+        return null;
+    const counts = Object.fromEntries(EXPORT_SECTIONS.map((s) => [s, null]));
+    let found = false;
+    for (const pair of header.split(";")) {
+        const m = COUNT_PAIR_RE.exec(pair);
+        if (m && EXPORT_SECTIONS.includes(m[1])) {
+            counts[m[1]] = Number(m[2]);
+            found = true;
+        }
+    }
+    return found ? counts : null;
+}
+export function extractCounts(format, body, headers) {
+    return format === "csv"
+        ? countsFromHeader(headers.get(COUNTS_HEADER))
+        : countsFromJsonBody(new TextDecoder().decode(body));
+}
+// ─── summary ──────────────────────────────────────────────────────────────────
+export function sha256Hex(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+export function verificationLinks(agentId, websiteBase, apiBase) {
+    const id = encodeURIComponent(agentId);
+    return {
+        reputation_url: `${websiteBase}/agents/${id}/reputation`,
+        verify_url: `${apiBase}/v1/reputation/${id}/verify`,
+    };
+}
+export function buildSummary(input) {
+    return {
+        agent_id: input.agentId,
+        output: input.output,
+        format: input.format,
+        period: input.period,
+        counts: input.counts,
+        bytes: input.body.byteLength,
+        sha256: sha256Hex(input.body),
+        verification: verificationLinks(input.agentId, input.websiteBase, input.apiBase),
+    };
+}
+export function describePeriod(period) {
+    if (period.from !== null && period.to !== null)
+        return `${period.from} to ${period.to}`;
+    if (period.from !== null)
+        return `${period.from} to now`;
+    if (period.to !== null)
+        return `everything up to ${period.to}`;
+    return "all time";
+}
+/** The human summary, one line per entry (no colour; the driver adds none). */
+export function formatSummaryLines(summary) {
+    const lines = [
+        `Exported the record of ${summary.agent_id}`,
+        `  Output:   ${summary.output === "-" ? "stdout" : summary.output} (${summary.format}, ${summary.bytes} bytes)`,
+        `  Period:   ${describePeriod(summary.period)}`,
+    ];
+    if (summary.counts === null) {
+        lines.push("  Counts:   unavailable (this server version does not report them)");
+    }
+    else {
+        lines.push("  Counts:");
+        const width = Math.max(...EXPORT_SECTIONS.map((s) => s.length));
+        for (const section of EXPORT_SECTIONS) {
+            const n = summary.counts[section];
+            lines.push(`    ${section.padEnd(width)}  ${n === null ? "unavailable" : n}`);
+        }
+    }
+    lines.push(`  SHA-256:  ${summary.sha256}`);
+    lines.push("            (file checksum — lets the recipient confirm the file was not altered in transit)");
+    lines.push(`  Verify:   ${summary.verification.reputation_url}`);
+    lines.push(`            ${summary.verification.verify_url}`);
+    return lines;
+}
+/** The one-line sensitivity note (the driver prints it dim, on stderr). */
+export function sensitivityNote(toStdout) {
+    const where = toStdout
+        ? "handle it as confidential"
+        : "the file is readable by you only (mode 0600)";
+    return (`This export holds full checkpoint reasoning and concerns that outsiders normally see redacted — ${where}. ` +
+        "To share proof without the contents, send the public verification link instead.");
+}
+// ─── errors ───────────────────────────────────────────────────────────────────
+/** The user-facing message for a failed export request. */
+export function exportErrorMessage(error, agentId) {
+    if (error instanceof MnemomApiError) {
+        // effectiveStatus, not status: the enforce hook can rewrite an undocumented
+        // status to a synthetic 500 carrying spec_deviation.original_status.
+        const status = error.effectiveStatus;
+        if (status === 401)
+            return "Not signed in, or your session has expired. Run `mnemom login`.";
+        if (status === 403)
+            return `You are not a member of the org that owns agent ${agentId}.`;
+        if (status === 404)
+            return `Agent not found: ${agentId}.`;
+        if (status === 413 || error.code === "export_too_large") {
+            return "That period has more rows than the server exports in one go. Narrow it with --since, --from or --to.";
+        }
+        return `Export failed: ${error.message}`;
+    }
+    return `Export failed: ${error instanceof Error ? error.message : String(error)}`;
+}
+/** The user-facing message for a failed file write. */
+export function writeErrorMessage(error, path) {
+    const code = error?.code;
+    if (code === "EEXIST") {
+        return `${path} already exists. Pass --force to overwrite it, or pick another path with -o.`;
+    }
+    return `Could not write ${path}: ${error instanceof Error ? error.message : String(error)}`;
+}

package/dist/lib/api.d.ts

@@ -371,6 +371,18 @@ export interface MoveAgentResult {
 export declare function moveAgent(agentId: string, destOrgId: string, opts?: {
     idempotencyKey?: string;
 }): Promise<MoveAgentResult>;
+/**
+ * GET /v1/agents/:id/compliance-export — the agent's full record (JSON or CSV).
+ *
+ * Returns the raw body bytes (written to disk verbatim so the checksum the CLI
+ * prints matches what the server sent) plus the response headers (CSV carries
+ * its per-section counts in `X-Mnemom-Export-Counts`). `query` is the full
+ * `?format=…&from=…&to=…` string (see lib/agent-export.ts buildExportQuery).
+ */
+export declare function getComplianceExport(agentId: string, query: string): Promise<{
+    body: Uint8Array;
+    headers: Headers;
+}>;
 /**
  * GET /v1/auth/me/personal-org — accessor for the user's personal org.
  * Idempotent: lazily provisions for legacy accounts that pre-date the

package/dist/lib/api.js

@@ -367,6 +367,23 @@ export async function moveAgent(agentId, destOrgId, opts = {}) {
         to_org_id: data.to_org_id ?? null,
     };
 }
+/**
+ * GET /v1/agents/:id/compliance-export — the agent's full record (JSON or CSV).
+ *
+ * Returns the raw body bytes (written to disk verbatim so the checksum the CLI
+ * prints matches what the server sent) plus the response headers (CSV carries
+ * its per-section counts in `X-Mnemom-Export-Counts`). `query` is the full
+ * `?format=…&from=…&to=…` string (see lib/agent-export.ts buildExportQuery).
+ */
+export async function getComplianceExport(agentId, query) {
+    const url = validateUrl(`${API_BASE}/v1/agents/${encodeURIComponent(agentId)}/compliance-export${query}`);
+    const response = await fetchWithAuthRetry(url, async () => ({
+        headers: { ...(await authHeaders()), Accept: "application/json, text/csv" },
+    }));
+    if (!response.ok)
+        throw await readApiError(response, "Failed to export the agent record");
+    return { body: new Uint8Array(await response.arrayBuffer()), headers: response.headers };
+}
 /**
  * GET /v1/auth/me/personal-org — accessor for the user's personal org.
  * Idempotent: lazily provisions for legacy accounts that pre-date the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnemom/mnemom",
-  "version": "0.17.21",
+  "version": "0.17.22",
   "description": "Transparent AI agent tracing",
   "type": "module",
   "bin": {