@mnemom/mnemom 0.17.21 → 0.17.23

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/agent.d.ts

@@ -342,16 +342,24 @@ export declare const CONTEXT_HEAD_RECLAIM_KEY = "CONTEXT_RUNTIME_HEAD_BREAKPOINT
 export declare const CONTEXT_SIZE_POLICY_KEY = "CONTEXT_RUNTIME_SIZE_POLICY";
 /**
  * The two gateway env keys the `compaction_intercept` setting turns on for a single session
- * (payload-bound fix; both default OFF on the gateway, both read from the per-session overlay):
+ * (payload-bound fix; both read from the per-session overlay). The us-2 prod cell runs both on in
+ * its own cell env; the test and us-1 preview cells leave them at the gateway default (off). Since
+ * 0.17.23 the CLI asks for them on every launch — a deliberate, authorized rollout decision
+ * (MNE-8532, CTO 2026-10-12): every cell a `mnemom agent` session runs on then behaves like
+ * prod, rather than the CLI deferring to a non-prod cell's off default. The keys are TUNE-tier
+ * (gateway session-config allowlist, honored for any authenticated agent), so a cell without
+ * the companion support drops them and the session behaves as before.
  *   - `GATEWAY_USAGE_REAL_SIZE` — report the size of the body the client actually sent (the
  *     REAL, unfolded context) in the last `usage.iterations` entry, so Claude Code's own
  *     auto-compact threshold (its 1M default, or the user's `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` /
  *     `CLAUDE_CODE_AUTO_COMPACT_WINDOW` / `autoCompactWindow`) fires as it would without the fold;
  *   - `GATEWAY_COMPACTION_INTERCEPT` — answer the client's compaction request at once from the
  *     gateway's own fold digest (no model call), so the compaction never blocks the user.
- * Sent together, value `"on"`, when the `compaction_intercept` setting is on
- * (`resolveCompactionIntercept`) OR when `--compact-at` arms a target below 1M (below) — a
- * target cannot be honored without both. The `off` context profile sends both as `"off"`.
+ * Sent together, value `"on"`, when the `compaction_intercept` setting is on — the DEFAULT since
+ * 0.17.23 (`resolveCompactionIntercept`) — OR when `--compact-at` arms a target below 1M (below):
+ * a target cannot be honored without both. An opt-out (`--no-compaction-intercept`,
+ * `compaction_intercept = false`, `MNEMOM_AGENT_COMPACTION_INTERCEPT=0`) and the `off` context
+ * profile send both as `"off"`, so the opt-out holds on a cell whose own default is on.
  */
 export declare const USAGE_REAL_SIZE_KEY = "GATEWAY_USAGE_REAL_SIZE";
 export declare const COMPACTION_INTERCEPT_KEY = "GATEWAY_COMPACTION_INTERCEPT";
@@ -461,8 +469,7 @@ export declare function resolveCompactAt(opts: {
  * (either silently re-arming the intercept the user just turned off, or silently sending an
  * inert upload-target the gateway can never act on). `compactionIntercept` here is the raw,
  * pre-`resolveCompactionIntercept` flag value: `false` only when `--no-compaction-intercept`
- * was explicitly passed (or the experimental gate forced it, which `compactAt` cannot reach
- * past either — see index.ts's `assertEnabled`), never the mere absence of `--compaction-intercept`.
+ * was explicitly passed, never the mere absence of `--compaction-intercept`.
  */
 export declare function assertCompactAtCompatible(opts: {
     compactionIntercept?: boolean;
@@ -648,18 +655,23 @@ export declare function resolveContextProfile(opts: {
  * no profile was chosen), then `CONTEXT_HANDOFF_ENABLED: "true"` when context handoff is ON, then
  * `GATEWAY_USAGE_SAVINGS: "on"` when measured savings is ON (under every profile), then
  * `GATEWAY_USAGE_REAL_SIZE: "on"` + `GATEWAY_COMPACTION_INTERCEPT: "on"` when EITHER the
- * `compaction_intercept` setting is ON OR `--compact-at` arms a target below 1M (the target
- * cannot be honored without the intercept), then `GATEWAY_COMPACTION_UPLOAD_TARGET_TOKENS: "<N>"`
- * when a target is set. The `off` profile wins over the intercept and the target: a session with
+ * `compaction_intercept` setting is ON (the default) OR `--compact-at` arms a target below 1M (the
+ * target cannot be honored without the intercept) — or both as `"off"` when the setting is
+ * explicitly `false` (an opt-out) and no target is armed, so the opt-out holds on a cell whose own
+ * env turns them on — then `GATEWAY_COMPACTION_UPLOAD_TARGET_TOKENS: "<N>"` when a target is set. The `off` profile wins over the intercept and the target: a session with
  * no fold never has its compaction intercepted (`assertOffProfileCompatible` refuses the explicit
  * flag pair; a standing intercept or target from the environment or launcher.toml is dropped).
- * Empty with no profile chosen and everything off — the common case, where
- * no header is sent at all. Exported so `--dry-run` can list exactly what the header carries.
+ * Empty with no profile chosen, everything else off and `compactionIntercept` absent (callers
+ * that do not resolve it) — then no header is sent at all. Exported so `--dry-run` can list exactly what the header carries.
  */
 export declare function buildSessionConfig(opts: {
     /** `resolveContextProfile` output: `null` ⇒ no profile chosen, no fold key sent. */
     profile: ContextProfile | null;
     contextHandoff: boolean;
+    /**
+     * `resolveCompactionIntercept` output: `true` (the default) ⇒ both keys `"on"`; `false` (an
+     * opt-out) ⇒ both `"off"`; absent ⇒ neither key is sent (the cell's own default stands).
+     */
     compactionIntercept?: boolean;
     /** `resolveCompactAt` output: `null` (or absent) ⇒ no target, send nothing new. */
     compactAt?: number | null;
@@ -691,8 +703,8 @@ export declare function buildSessionConfigPayload(opts: {
  *     `aggressive` → the three fold-tuning keys + `CONTEXT_RUNTIME_SIZE_POLICY: "off"`,
  *     `balanced` → `CONTEXT_RUNTIME_SIZE_POLICY: "off"`, `adaptive` →
  *     `CONTEXT_RUNTIME_SIZE_POLICY: "banded"`, none chosen → nothing;
- *   - `compactionIntercept: true` → `GATEWAY_USAGE_REAL_SIZE` + `GATEWAY_COMPACTION_INTERCEPT`
- *     `"on"` (the `compaction_intercept` setting);
+ *   - `compactionIntercept: true` (the default) → `GATEWAY_USAGE_REAL_SIZE` +
+ *     `GATEWAY_COMPACTION_INTERCEPT` `"on"`; `false` (an opt-out) → both `"off"`;
  *   - `compactAt: <N>` (`--compact-at`, below 1M) → the SAME two intercept keys plus
  *     `GATEWAY_COMPACTION_UPLOAD_TARGET_TOKENS: "<N>"`; unset, `1m` or `off` → nothing beyond
  *     what `compactionIntercept` already sent (Claude Code's own 1M window, untouched);
@@ -725,10 +737,11 @@ export declare function resolveContextHandoff(opts: {
 }): boolean;
 /**
  * Is the compaction intercept (`GATEWAY_USAGE_REAL_SIZE` + `GATEWAY_COMPACTION_INTERCEPT` in the
- * session-config header) ON for this launch? OFF by default, same shape as
- * `resolveContextHandoff`: an explicit `--compaction-intercept` / `--no-compaction-intercept`
- * wins, else `MNEMOM_AGENT_COMPACTION_INTERCEPT` (which `applyConfigToEnv` sets from the
- * `compaction_intercept` config key), else OFF.
+ * session-config header) ON for this launch? ON by default since 0.17.23 (it graduated from the
+ * `compaction-intercept` experimental feature). An explicit `--compaction-intercept` /
+ * `--no-compaction-intercept` wins, else `MNEMOM_AGENT_COMPACTION_INTERCEPT` (which
+ * `applyConfigToEnv` sets from the `compaction_intercept` config key: `0`/`false`/`off`/`no`
+ * opt out), else ON.
  */
 export declare function resolveCompactionIntercept(opts: {
     compactionIntercept?: boolean;