@mnemom/mnemom 0.16.2 → 0.17.0-next.0

package/dist/lib/cli-config.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Persistent CLI preference store — ~/.mnemom/config.json.
+ *
+ * Deliberately SEPARATE from auth.ts → auth.json: auth.json holds bearer
+ * credentials and is wiped on logout; config.json holds preferences that
+ * survive re-login. Today it holds one preference: the ACTIVE ORG.
+ *
+ * Why an active org exists at all: `mnemom login` binds no org — the OAuth
+ * token carries only scope + expiry (see lib/auth.ts), so every org-scoped
+ * command historically needed an explicit `--org` or silently defaulted to
+ * the caller's personal org (the "why did my agent land in Personal?"
+ * footgun). `mnemom org use <slug>` records a durable default; commands
+ * resolve org as: explicit flag > active org > loud personal-org fallback.
+ *
+ * The stored value is the VALIDATED membership snapshot ({org_id, slug,
+ * name}) so consumers can send org_id without a per-command round-trip.
+ * Membership can change after it's stored — consumers must treat a server
+ * 403 as the truth (the claim path already renders the teaching list).
+ */
+export interface ActiveOrg {
+    org_id: string;
+    slug: string;
+    name: string;
+}
+export interface CliConfig {
+    activeOrg?: ActiveOrg;
+}
+/** Load the config; a missing or corrupt file degrades to `{}`. */
+export declare function loadCliConfig(): CliConfig;
+/** Persist (or with `null`, clear) the active org. */
+export declare function setActiveOrg(org: ActiveOrg | null): void;
+/** The active org, or undefined when none is set. */
+export declare function getActiveOrg(): ActiveOrg | undefined;

package/dist/lib/cli-config.js

@@ -0,0 +1,70 @@
+/**
+ * Persistent CLI preference store — ~/.mnemom/config.json.
+ *
+ * Deliberately SEPARATE from auth.ts → auth.json: auth.json holds bearer
+ * credentials and is wiped on logout; config.json holds preferences that
+ * survive re-login. Today it holds one preference: the ACTIVE ORG.
+ *
+ * Why an active org exists at all: `mnemom login` binds no org — the OAuth
+ * token carries only scope + expiry (see lib/auth.ts), so every org-scoped
+ * command historically needed an explicit `--org` or silently defaulted to
+ * the caller's personal org (the "why did my agent land in Personal?"
+ * footgun). `mnemom org use <slug>` records a durable default; commands
+ * resolve org as: explicit flag > active org > loud personal-org fallback.
+ *
+ * The stored value is the VALIDATED membership snapshot ({org_id, slug,
+ * name}) so consumers can send org_id without a per-command round-trip.
+ * Membership can change after it's stored — consumers must treat a server
+ * 403 as the truth (the claim path already renders the teaching list).
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { MNEMOM_DIR } from "./config.js";
+function configFile() {
+    return path.join(MNEMOM_DIR, "config.json");
+}
+/** Load the config; a missing or corrupt file degrades to `{}`. */
+export function loadCliConfig() {
+    try {
+        if (!fs.existsSync(configFile()))
+            return {};
+        const parsed = JSON.parse(fs.readFileSync(configFile(), "utf-8"));
+        return parsed && typeof parsed === "object" ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function saveCliConfig(config) {
+    if (!fs.existsSync(MNEMOM_DIR)) {
+        // 0700 to match the auth store — the directory also holds credentials.
+        fs.mkdirSync(MNEMOM_DIR, { recursive: true, mode: 0o700 });
+    }
+    const resolvedPath = path.resolve(configFile());
+    const tmpFile = `${resolvedPath}.${process.pid}.tmp`;
+    // No secrets in here, but keep the same owner-only posture as auth.json —
+    // the active org is still account metadata. Write-then-rename = atomic.
+    fs.writeFileSync(tmpFile, JSON.stringify(config, null, 2), { mode: 0o600 });
+    try {
+        fs.chmodSync(tmpFile, 0o600);
+    }
+    catch {
+        /* best effort on platforms without POSIX perms */
+    }
+    fs.renameSync(tmpFile, resolvedPath);
+}
+/** Persist (or with `null`, clear) the active org. */
+export function setActiveOrg(org) {
+    const config = loadCliConfig();
+    if (org === null) {
+        delete config.activeOrg;
+    }
+    else {
+        config.activeOrg = org;
+    }
+    saveCliConfig(config);
+}
+/** The active org, or undefined when none is set. */
+export function getActiveOrg() {
+    return loadCliConfig().activeOrg;
+}

package/dist/lib/code-config.d.ts

@@ -0,0 +1,78 @@
+/**
+ * lib/code-config.ts — persistent per-customer settings for `mnemom code`.
+ *
+ * Settings live in a human-editable TOML file at ~/.mnemom/code.toml (the
+ * Cargo/Codex `config.toml` convention — comments allowed, easy to hand-edit) so
+ * a customer never has to retype their flags. The SECRET Anthropic key is
+ * deliberately NOT stored here: it stays in ~/.mnemom/code.json at 0600 (see
+ * commands/code.ts), so the file customers open, edit, and share never carries a
+ * credential — the same split gh (config.yml/hosts.yml), aws (config/credentials)
+ * and Codex (config.toml/auth.json) use.
+ *
+ * Precedence, highest wins: command-line FLAG > ENV > code.toml > built-in.
+ * `loadCodeConfig` is pure parse+validate; `applyConfigToEnv` folds the
+ * env-backed settings UNDER any real env var (so env still wins and the
+ * resolvers in lib/code.ts keep the built-in default as the final fallback);
+ * the caller folds the plain-value settings under the CLI flags.
+ */
+import { type LaunchShape } from "./code.js";
+/** The human-editable settings file. Secret key lives elsewhere (code.json). */
+export declare const CODE_CONFIG_PATH: string;
+/** Where the CLI resolves the Anthropic key from; advisory ordering/restriction. */
+export type KeySource = "env" | "store" | "prompt";
+/** The validated settings, camelCased for TS (TOML keys are snake_case). */
+export interface CodeConfig {
+    gateway?: string;
+    model?: string;
+    agent?: string;
+    effort?: string;
+    cli?: string;
+    launch?: LaunchShape;
+    keySource?: KeySource;
+    guardrails?: {
+        maxTurns?: number;
+        budgetUsd?: number;
+        stallTurns?: number;
+    };
+}
+/**
+ * A settable key: its dotted config name, the getter/setter into a CodeConfig,
+ * and a one-line description for `config list`/help. Kept as data so get/set/list
+ * stay a single source of truth.
+ */
+export interface ConfigKeySpec {
+    key: string;
+    describe: string;
+    get(cfg: CodeConfig): string | number | undefined;
+    set(cfg: CodeConfig, raw: string): void;
+}
+/** The full set of settable keys — drives get/set/unset/list and validation. */
+export declare const CONFIG_KEYS: ConfigKeySpec[];
+export declare function configKeySpec(key: string): ConfigKeySpec | undefined;
+/**
+ * Parse + validate a TOML settings document into a CodeConfig. Pure (no fs), so
+ * it is unit-testable. Unknown top-level keys are ignored (forward-compatible);
+ * known keys with the wrong shape throw a human-readable error.
+ */
+export declare function parseCodeConfig(text: string): CodeConfig;
+/**
+ * Load the settings from ~/.mnemom/code.toml (or `path`). A missing file is an
+ * empty config (never an error — first run has none). A malformed or invalid
+ * file throws with the path so the customer can fix it, rather than silently
+ * launching with the wrong settings.
+ */
+export declare function loadCodeConfig(path?: string): CodeConfig;
+/** Serialize a CodeConfig back to TOML (snake_case keys), with a header comment. */
+export declare function serializeCodeConfig(cfg: CodeConfig): string;
+/** Persist a CodeConfig to `path` (default code.toml), atomically (temp+rename), 0600. */
+export declare function writeCodeConfig(cfg: CodeConfig, path?: string): void;
+/**
+ * Fold the ENV-backed settings from config UNDER the environment: set the
+ * MNEMOM_CODE_* var ONLY when it is not already present, so a real env var (and
+ * therefore a flag that set one) still wins. The resolvers in lib/code.ts then
+ * apply the built-in default when neither env nor config supplied a value.
+ *
+ * launch maps to MNEMOM_CODE_REMOTE_CONTROL using that var's existing contract
+ * (see resolveLaunchShape): terminal→"0", remote-control→"1", server→"server".
+ */
+export declare function applyConfigToEnv(cfg: CodeConfig, env?: NodeJS.ProcessEnv): void;

package/dist/lib/code-config.js

@@ -0,0 +1,281 @@
+/**
+ * lib/code-config.ts — persistent per-customer settings for `mnemom code`.
+ *
+ * Settings live in a human-editable TOML file at ~/.mnemom/code.toml (the
+ * Cargo/Codex `config.toml` convention — comments allowed, easy to hand-edit) so
+ * a customer never has to retype their flags. The SECRET Anthropic key is
+ * deliberately NOT stored here: it stays in ~/.mnemom/code.json at 0600 (see
+ * commands/code.ts), so the file customers open, edit, and share never carries a
+ * credential — the same split gh (config.yml/hosts.yml), aws (config/credentials)
+ * and Codex (config.toml/auth.json) use.
+ *
+ * Precedence, highest wins: command-line FLAG > ENV > code.toml > built-in.
+ * `loadCodeConfig` is pure parse+validate; `applyConfigToEnv` folds the
+ * env-backed settings UNDER any real env var (so env still wins and the
+ * resolvers in lib/code.ts keep the built-in default as the final fallback);
+ * the caller folds the plain-value settings under the CLI flags.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { parse as parseToml, stringify as stringifyToml, TomlError } from "smol-toml";
+import { MNEMOM_DIR } from "./config.js";
+import { isPositiveInt, isPositiveNumber } from "./code.js";
+/** The human-editable settings file. Secret key lives elsewhere (code.json). */
+export const CODE_CONFIG_PATH = join(MNEMOM_DIR, "code.toml");
+const LAUNCH_SHAPES = ["terminal", "remote-control", "server"];
+const EFFORTS = ["low", "medium", "high", "xhigh", "max"];
+const KEY_SOURCES = ["env", "store", "prompt"];
+function coerceLaunch(raw) {
+    const v = raw.trim();
+    if (LAUNCH_SHAPES.includes(v))
+        return v;
+    throw new Error(`launch must be one of ${LAUNCH_SHAPES.join(", ")} (got '${raw}').`);
+}
+function coerceEffort(raw) {
+    const v = raw.trim();
+    if (EFFORTS.includes(v))
+        return v;
+    throw new Error(`effort must be one of ${EFFORTS.join(", ")} (got '${raw}').`);
+}
+function coerceKeySource(raw) {
+    const v = raw.trim();
+    if (KEY_SOURCES.includes(v))
+        return v;
+    throw new Error(`key_source must be one of ${KEY_SOURCES.join(", ")} (got '${raw}').`);
+}
+function coerceNonEmpty(name, raw) {
+    const v = raw.trim();
+    if (!v)
+        throw new Error(`${name} must be a non-empty string.`);
+    return v;
+}
+function ensureGuardrails(cfg) {
+    if (!cfg.guardrails)
+        cfg.guardrails = {};
+    return cfg.guardrails;
+}
+/** The full set of settable keys — drives get/set/unset/list and validation. */
+export const CONFIG_KEYS = [
+    {
+        key: "gateway",
+        describe: "Gateway host (default https://gateway.mnemom.ai — the us-2/prod cell)",
+        get: (c) => c.gateway,
+        set: (c, v) => {
+            c.gateway = coerceNonEmpty("gateway", v);
+        },
+    },
+    {
+        key: "model",
+        describe: "Model to launch (CLI alias or concrete id, e.g. claude-sonnet-5)",
+        get: (c) => c.model,
+        set: (c, v) => {
+            c.model = coerceNonEmpty("model", v);
+        },
+    },
+    {
+        key: "agent",
+        describe: "Governed agent identity slug (x-mnemom-agent)",
+        get: (c) => c.agent,
+        set: (c, v) => {
+            c.agent = coerceNonEmpty("agent", v);
+        },
+    },
+    {
+        key: "effort",
+        describe: `Reasoning effort (${EFFORTS.join("|")})`,
+        get: (c) => c.effort,
+        set: (c, v) => {
+            c.effort = coerceEffort(v);
+        },
+    },
+    {
+        key: "cli",
+        describe: "Coding-agent CLI to launch (name or full path; default claude)",
+        get: (c) => c.cli,
+        set: (c, v) => {
+            c.cli = coerceNonEmpty("cli", v);
+        },
+    },
+    {
+        key: "launch",
+        describe: `Launch shape (${LAUNCH_SHAPES.join("|")})`,
+        get: (c) => c.launch,
+        set: (c, v) => {
+            c.launch = coerceLaunch(v);
+        },
+    },
+    {
+        key: "key_source",
+        describe: `Where to source the Anthropic key (${KEY_SOURCES.join("|")})`,
+        get: (c) => c.keySource,
+        set: (c, v) => {
+            c.keySource = coerceKeySource(v);
+        },
+    },
+    {
+        key: "guardrails.max_turns",
+        describe: "Contract guardrail: turn ceiling (positive integer)",
+        get: (c) => c.guardrails?.maxTurns,
+        set: (c, v) => {
+            if (!isPositiveInt(v))
+                throw new Error(`guardrails.max_turns must be a positive integer (got '${v}').`);
+            ensureGuardrails(c).maxTurns = Number(v);
+        },
+    },
+    {
+        key: "guardrails.budget_usd",
+        describe: "Contract guardrail: spend ceiling in USD (positive number)",
+        get: (c) => c.guardrails?.budgetUsd,
+        set: (c, v) => {
+            if (!isPositiveNumber(v))
+                throw new Error(`guardrails.budget_usd must be a positive number (got '${v}').`);
+            ensureGuardrails(c).budgetUsd = Number(v);
+        },
+    },
+    {
+        key: "guardrails.stall_turns",
+        describe: "Contract guardrail: consecutive no-write turns (positive integer)",
+        get: (c) => c.guardrails?.stallTurns,
+        set: (c, v) => {
+            if (!isPositiveInt(v))
+                throw new Error(`guardrails.stall_turns must be a positive integer (got '${v}').`);
+            ensureGuardrails(c).stallTurns = Number(v);
+        },
+    },
+];
+export function configKeySpec(key) {
+    return CONFIG_KEYS.find((k) => k.key === key);
+}
+/**
+ * Parse + validate a TOML settings document into a CodeConfig. Pure (no fs), so
+ * it is unit-testable. Unknown top-level keys are ignored (forward-compatible);
+ * known keys with the wrong shape throw a human-readable error.
+ */
+export function parseCodeConfig(text) {
+    let raw;
+    try {
+        raw = parseToml(text);
+    }
+    catch (err) {
+        const detail = err instanceof TomlError ? err.message : String(err);
+        throw new Error(`could not parse code.toml: ${detail}`);
+    }
+    const cfg = {};
+    const str = (v) => typeof v === "string" && v.trim() ? v.trim() : v === undefined ? undefined : String(v);
+    if (raw.gateway !== undefined)
+        cfg.gateway = coerceNonEmpty("gateway", str(raw.gateway) ?? "");
+    if (raw.model !== undefined)
+        cfg.model = coerceNonEmpty("model", str(raw.model) ?? "");
+    if (raw.agent !== undefined)
+        cfg.agent = coerceNonEmpty("agent", str(raw.agent) ?? "");
+    if (raw.effort !== undefined)
+        cfg.effort = coerceEffort(str(raw.effort) ?? "");
+    if (raw.cli !== undefined)
+        cfg.cli = coerceNonEmpty("cli", str(raw.cli) ?? "");
+    if (raw.launch !== undefined)
+        cfg.launch = coerceLaunch(str(raw.launch) ?? "");
+    if (raw.key_source !== undefined)
+        cfg.keySource = coerceKeySource(str(raw.key_source) ?? "");
+    const g = raw.guardrails;
+    if (g !== undefined) {
+        if (typeof g !== "object" || g === null || Array.isArray(g)) {
+            throw new Error("[guardrails] must be a table.");
+        }
+        const gr = g;
+        if (gr.max_turns !== undefined)
+            configKeySpec("guardrails.max_turns").set(cfg, String(gr.max_turns));
+        if (gr.budget_usd !== undefined)
+            configKeySpec("guardrails.budget_usd").set(cfg, String(gr.budget_usd));
+        if (gr.stall_turns !== undefined)
+            configKeySpec("guardrails.stall_turns").set(cfg, String(gr.stall_turns));
+    }
+    return cfg;
+}
+/**
+ * Load the settings from ~/.mnemom/code.toml (or `path`). A missing file is an
+ * empty config (never an error — first run has none). A malformed or invalid
+ * file throws with the path so the customer can fix it, rather than silently
+ * launching with the wrong settings.
+ */
+export function loadCodeConfig(path = CODE_CONFIG_PATH) {
+    if (!existsSync(path))
+        return {};
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch {
+        return {};
+    }
+    try {
+        return parseCodeConfig(text);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`mnemom code: ${msg}\n  Fix or remove ${path}.`);
+    }
+}
+/** Serialize a CodeConfig back to TOML (snake_case keys), with a header comment. */
+export function serializeCodeConfig(cfg) {
+    const doc = {};
+    if (cfg.gateway !== undefined)
+        doc.gateway = cfg.gateway;
+    if (cfg.model !== undefined)
+        doc.model = cfg.model;
+    if (cfg.agent !== undefined)
+        doc.agent = cfg.agent;
+    if (cfg.effort !== undefined)
+        doc.effort = cfg.effort;
+    if (cfg.cli !== undefined)
+        doc.cli = cfg.cli;
+    if (cfg.launch !== undefined)
+        doc.launch = cfg.launch;
+    if (cfg.keySource !== undefined)
+        doc.key_source = cfg.keySource;
+    const g = cfg.guardrails;
+    if (g && (g.maxTurns !== undefined || g.budgetUsd !== undefined || g.stallTurns !== undefined)) {
+        const gr = {};
+        if (g.maxTurns !== undefined)
+            gr.max_turns = g.maxTurns;
+        if (g.budgetUsd !== undefined)
+            gr.budget_usd = g.budgetUsd;
+        if (g.stallTurns !== undefined)
+            gr.stall_turns = g.stallTurns;
+        doc.guardrails = gr;
+    }
+    const header = "# ~/.mnemom/code.toml — settings for `mnemom code` (the governed coding-agent launcher).\n" +
+        "# Command-line flags override these; these override the built-in defaults.\n" +
+        "# The secret Anthropic key is NOT here — it lives in ~/.mnemom/code.json (0600).\n" +
+        "# Edit with `mnemom code config edit`, or set one key with `mnemom code config set <key> <value>`.\n\n";
+    const body = Object.keys(doc).length ? stringifyToml(doc) : "";
+    return `${header}${body}${body.endsWith("\n") || !body ? "" : "\n"}`;
+}
+/** Persist a CodeConfig to `path` (default code.toml), atomically (temp+rename), 0600. */
+export function writeCodeConfig(cfg, path = CODE_CONFIG_PATH) {
+    const dir = dirname(path);
+    mkdirSync(dir, { recursive: true });
+    const tmp = join(dir, `.code-toml-tmp-${process.pid}-${Date.now()}`);
+    writeFileSync(tmp, serializeCodeConfig(cfg), { mode: 0o600 });
+    renameSync(tmp, path);
+}
+/**
+ * Fold the ENV-backed settings from config UNDER the environment: set the
+ * MNEMOM_CODE_* var ONLY when it is not already present, so a real env var (and
+ * therefore a flag that set one) still wins. The resolvers in lib/code.ts then
+ * apply the built-in default when neither env nor config supplied a value.
+ *
+ * launch maps to MNEMOM_CODE_REMOTE_CONTROL using that var's existing contract
+ * (see resolveLaunchShape): terminal→"0", remote-control→"1", server→"server".
+ */
+export function applyConfigToEnv(cfg, env = process.env) {
+    if (cfg.gateway && !(env.MNEMOM_CODE_GATEWAY ?? "").trim()) {
+        env.MNEMOM_CODE_GATEWAY = cfg.gateway;
+    }
+    if (cfg.cli && !(env.MNEMOM_CODE_CLI ?? "").trim()) {
+        env.MNEMOM_CODE_CLI = cfg.cli;
+    }
+    if (cfg.launch && !(env.MNEMOM_CODE_REMOTE_CONTROL ?? "").trim()) {
+        env.MNEMOM_CODE_REMOTE_CONTROL =
+            cfg.launch === "server" ? "server" : cfg.launch === "remote-control" ? "1" : "0";
+    }
+}

package/dist/lib/code.d.ts

@@ -0,0 +1,154 @@
+/**
+ * lib/code.ts — the pure, IO-free core of `mnemom code`, the CLI's first-class
+ * governed-coding-agent launcher.
+ *
+ * `mnemom code` launches your coding-agent CLI (Claude Code in v1) with its
+ * dev-time model traffic routed through the Mnemom gateway for observability and
+ * governance, under a governed agent identity and (optionally) a governed
+ * per-conversation CONTRACT (goal / requirements / path allow-forbid lists +
+ * guardrail ceilings) that the gateway SEALS on the first turn of a conversation.
+ *
+ * Everything here is deterministic and side-effect-free so it can be unit-tested
+ * without spawning a process or touching the network: the contract builder + its
+ * canonical seal (byte-identical to the gateway's `parseContractHeader` +
+ * `canonicalHash`), the guardrail validators, agent-name sanitisation, and the
+ * gateway-door resolution. The command shell (commands/code.ts) does the IO —
+ * key resolution, env assembly, and spawning the coding-agent CLI.
+ *
+ * The us-2/PROD gateway is the DEFAULT door (https://gateway.mnemom.ai). An
+ * explicit MNEMOM_CODE_GATEWAY still wins (so any other cell is reachable when
+ * NAMED), but prod is never selected silently — see `resolveGatewayHost`.
+ */
+/** The us-2/prod gateway host. The default door — never any other cell silently. */
+export declare const PROD_GATEWAY_HOST = "https://gateway.mnemom.ai";
+/**
+ * The sealed-contract shape sent as `x-mnemom-contract` and re-parsed by the
+ * gateway's goal-contract hook (gateway/src/goal-contract.ts `SealedContract`).
+ * Empty arrays / empty `goal_id` are omitted, and the guardrail ceilings are
+ * plain finite numbers.
+ */
+export interface SealedContract {
+    goal_id?: string;
+    statement: string;
+    requirements?: string[];
+    allowed_paths?: string[];
+    forbidden_paths?: string[];
+    /** Guardrail ceilings — positive finite numbers, sealed into the contract hash. */
+    max_turns?: number;
+    budget_usd?: number;
+    stall_turns?: number;
+}
+/** The raw contract/guardrail flags as commander hands them to the command. */
+export interface ContractFlags {
+    goal?: string;
+    requirement?: string[];
+    allow?: string[];
+    forbid?: string[];
+    goalId?: string;
+    maxTurns?: string | number;
+    budget?: string | number;
+    stall?: string | number;
+}
+/** The three launch shapes the command supports (see commands/code.ts). */
+export type LaunchShape = "terminal" | "remote-control" | "server";
+/**
+ * Resolve the gateway HOST (scheme + host, no path). An explicit, non-empty
+ * `MNEMOM_CODE_GATEWAY` wins verbatim; otherwise the us-2/prod host. The default
+ * is PROD — an unset var resolves to prod, and any other cell is reached only by
+ * NAMING it. Trailing slash trimmed so door concatenation is clean.
+ */
+export declare function resolveGatewayHost(env?: NodeJS.ProcessEnv): string;
+/**
+ * The Anthropic door the CLI points Claude Code at:
+ * `${MNEMOM_CODE_GATEWAY}/anthropic`, or the full-door override
+ * `MNEMOM_CODE_ANTHROPIC_GATEWAY` when set. v1 is Anthropic-only (no router door
+ * / Mnemom key), so the /anthropic door carries the whole contract: x-api-key +
+ * x-mnemom-{agent,conversation-id,contract}.
+ */
+export declare function resolveAnthropicDoor(env?: NodeJS.ProcessEnv): string;
+/** True when the resolved gateway host is the us-2/prod cell (used for the launch banner). */
+export declare function isProdGateway(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Sanitise a header value into a safe wire token: lowercase, alphanumerics and
+ * single hyphens only, no leading/trailing hyphen. Returns "" when nothing
+ * survives (the caller rejects that).
+ */
+export declare function sanitizeAgentName(raw: string): string;
+/** A single-line, header-safe conversation id: honour a caller value, else a uuid. */
+export declare function resolveConversationId(raw: string | undefined): string;
+/** A strictly-positive integer (rejects 0, negatives, decimals, NaN, non-numeric strings). */
+export declare function isPositiveInt(value: unknown): boolean;
+/** A strictly-positive finite number (rejects 0, negatives, NaN, Infinity, non-numeric). */
+export declare function isPositiveNumber(value: unknown): boolean;
+/**
+ * Canonical JSON — object keys sorted recursively, arrays in order, no
+ * whitespace, `undefined` keys dropped. Byte-identical to the gateway's
+ * `canonicalJson` (gateway/src/goal-contract.ts), so the base64 we send and the
+ * sha we print match what the gateway seals.
+ */
+export declare function canonicalJson(value: unknown): string;
+/** sha256 hex (first 16 chars) of a string — the operator-eyeball contract hash. */
+export declare function sha256Hex16(text: string): string;
+/**
+ * Was ANY contract/guardrail flag supplied? A contract is built only then; if so
+ * `--goal` becomes required (see `assembleContract`). Purely presence-based.
+ */
+export declare function contractFlagsPresent(flags: ContractFlags): boolean;
+/**
+ * The output of sealing a contract: the canonical JSON, its base64 (the
+ * `x-mnemom-contract` header value), and the display hash.
+ */
+export interface SealedContractEnvelope {
+    contract: SealedContract;
+    canonical: string;
+    base64: string;
+    sha: string;
+}
+/**
+ * Build + seal the contract from the raw flags, or return null when no contract
+ * flag was given. Throws (with a human message) on the two invalid states the
+ * gateway would otherwise silently swallow:
+ *   - a contract flag present without `--goal` (the statement is required);
+ *   - a guardrail ceiling that is not strictly positive (`parseContractHeader`
+ *     drops those, so a "guarded" launch would actually be unguarded).
+ *
+ * The canonical form OMITS empty arrays and an empty goal_id, so the sha printed
+ * here matches whatever the gateway seals for the same flags.
+ */
+export declare function assembleContract(flags: ContractFlags): SealedContractEnvelope | null;
+/**
+ * Resolve the launch shape from the flags and the `MNEMOM_CODE_REMOTE_CONTROL`
+ * env var (the flags win). Default is `terminal` — a plain governed launch in
+ * THIS terminal. `--remote-control` → `remote-control` (interactive RC in this
+ * terminal); `--server` (or `MNEMOM_CODE_REMOTE_CONTROL=server`) → `server` (the
+ * headless `claude remote-control` dispatcher). Throws on an invalid env value.
+ */
+export declare function resolveLaunchShape(opts: {
+    remoteControl?: boolean;
+    server?: boolean;
+}, env?: NodeJS.ProcessEnv): LaunchShape;
+/**
+ * Did anyone EXPLICITLY choose a launch shape — a `--remote-control`/`--server`
+ * flag, or a non-empty `MNEMOM_CODE_REMOTE_CONTROL` (which config.launch also
+ * sets)? When false, the command is free to AUTO-select the best shape: prefer
+ * Remote-Control-in-terminal when the machine can do it, else terminal-only. An
+ * explicit `terminal` choice (config `launch = "terminal"` → env "0") is
+ * explicit and must be respected — never auto-upgraded.
+ */
+export declare function launchPreferenceExplicit(opts: {
+    remoteControl?: boolean;
+    server?: boolean;
+}, env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Build the `ANTHROPIC_CUSTOM_HEADERS` value for the terminal-only launch: the
+ * real Anthropic key as `x-api-key`, plus the governed-identity headers and the
+ * sealed contract when present. Newline-separated, exactly the wire shape Claude
+ * Code sends to the /anthropic door. NB: the returned string contains the key —
+ * callers must place it only in the child's env, never in a log line.
+ */
+export declare function buildCustomHeaders(opts: {
+    anthropicKey: string;
+    agent: string;
+    conversationId: string;
+    contractB64?: string;
+}): string;