@mnemom/mnemom 0.16.1 → 0.17.0-next.0

package/dist/lib/code.js

@@ -0,0 +1,252 @@
+/**
+ * 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`.
+ */
+import { createHash, randomUUID } from "node:crypto";
+/** The us-2/prod gateway host. The default door — never any other cell silently. */
+export const PROD_GATEWAY_HOST = "https://gateway.mnemom.ai";
+/**
+ * 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 function resolveGatewayHost(env = process.env) {
+    const raw = (env.MNEMOM_CODE_GATEWAY ?? "").trim();
+    const host = raw.length > 0 ? raw : PROD_GATEWAY_HOST;
+    return host.replace(/\/+$/, "");
+}
+/**
+ * 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 function resolveAnthropicDoor(env = process.env) {
+    const override = (env.MNEMOM_CODE_ANTHROPIC_GATEWAY ?? "").trim();
+    if (override.length > 0)
+        return override.replace(/\/+$/, "");
+    return `${resolveGatewayHost(env)}/anthropic`;
+}
+/** True when the resolved gateway host is the us-2/prod cell (used for the launch banner). */
+export function isProdGateway(env = process.env) {
+    return resolveGatewayHost(env) === PROD_GATEWAY_HOST;
+}
+/**
+ * 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 function sanitizeAgentName(raw) {
+    return raw
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+/, "")
+        .replace(/-+$/, "");
+}
+/** A single-line, header-safe conversation id: honour a caller value, else a uuid. */
+export function resolveConversationId(raw) {
+    const trimmed = (raw ?? "").replace(/[\r\n]+/g, "").trim();
+    if (trimmed.length > 0)
+        return trimmed;
+    return randomUUID().toLowerCase();
+}
+/** A strictly-positive integer (rejects 0, negatives, decimals, NaN, non-numeric strings). */
+export function isPositiveInt(value) {
+    const n = typeof value === "number" ? value : Number(String(value).trim());
+    return Number.isInteger(n) && n > 0 && /^\d+$/.test(String(value).trim());
+}
+/** A strictly-positive finite number (rejects 0, negatives, NaN, Infinity, non-numeric). */
+export function isPositiveNumber(value) {
+    const s = String(value).trim();
+    if (!/^([0-9]+(\.[0-9]*)?|\.[0-9]+)$/.test(s))
+        return false;
+    const n = Number(s);
+    return Number.isFinite(n) && n > 0;
+}
+/**
+ * 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 function canonicalJson(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    const obj = value;
+    const keys = Object.keys(obj)
+        .filter((k) => obj[k] !== undefined)
+        .sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(obj[k])}`).join(",")}}`;
+}
+/** sha256 hex (first 16 chars) of a string — the operator-eyeball contract hash. */
+export function sha256Hex16(text) {
+    return createHash("sha256").update(text, "utf8").digest("hex").slice(0, 16);
+}
+/**
+ * Was ANY contract/guardrail flag supplied? A contract is built only then; if so
+ * `--goal` becomes required (see `assembleContract`). Purely presence-based.
+ */
+export function contractFlagsPresent(flags) {
+    return (hasText(flags.goal) ||
+        (flags.requirement?.length ?? 0) > 0 ||
+        (flags.allow?.length ?? 0) > 0 ||
+        (flags.forbid?.length ?? 0) > 0 ||
+        hasText(flags.goalId) ||
+        flags.maxTurns !== undefined ||
+        flags.budget !== undefined ||
+        flags.stall !== undefined);
+}
+function hasText(v) {
+    return typeof v === "string" && v.trim().length > 0;
+}
+/**
+ * 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 function assembleContract(flags) {
+    if (!contractFlagsPresent(flags))
+        return null;
+    const statement = (flags.goal ?? "").trim();
+    if (!statement) {
+        throw new Error("--goal is required when any contract flag " +
+            "(--requirement/--allow/--forbid/--goal-id/--budget/--max-turns/--stall) is given.");
+    }
+    const contract = { statement };
+    const requirements = cleanList(flags.requirement);
+    if (requirements.length)
+        contract.requirements = requirements;
+    const allowed = cleanList(flags.allow);
+    if (allowed.length)
+        contract.allowed_paths = allowed;
+    const forbidden = cleanList(flags.forbid);
+    if (forbidden.length)
+        contract.forbidden_paths = forbidden;
+    const goalId = (flags.goalId ?? "").trim();
+    if (goalId)
+        contract.goal_id = goalId;
+    if (flags.maxTurns !== undefined) {
+        if (!isPositiveInt(flags.maxTurns)) {
+            throw new Error(`--max-turns must be a positive integer (got '${flags.maxTurns}').`);
+        }
+        contract.max_turns = Number(flags.maxTurns);
+    }
+    if (flags.budget !== undefined) {
+        if (!isPositiveNumber(flags.budget)) {
+            throw new Error(`--budget must be a positive USD amount (got '${flags.budget}').`);
+        }
+        contract.budget_usd = Number(flags.budget);
+    }
+    if (flags.stall !== undefined) {
+        if (!isPositiveInt(flags.stall)) {
+            throw new Error(`--stall must be a positive integer (got '${flags.stall}').`);
+        }
+        contract.stall_turns = Number(flags.stall);
+    }
+    const canonical = canonicalJson(contract);
+    return {
+        contract,
+        canonical,
+        base64: Buffer.from(canonical, "utf8").toString("base64"),
+        sha: sha256Hex16(canonical),
+    };
+}
+/** Trim, drop empties — matches the gateway's `stringArray` filtering. */
+function cleanList(values) {
+    return (values ?? []).map((v) => v.trim()).filter((v) => v.length > 0);
+}
+/**
+ * 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 function resolveLaunchShape(opts, env = process.env) {
+    let rc = false;
+    let server = false;
+    const envRc = (env.MNEMOM_CODE_REMOTE_CONTROL ?? "").trim();
+    switch (envRc) {
+        case "":
+        case "0":
+            break;
+        case "1":
+        case "terminal":
+            rc = true;
+            break;
+        case "server":
+            rc = true;
+            server = true;
+            break;
+        default:
+            throw new Error(`MNEMOM_CODE_REMOTE_CONTROL must be 0, 1, terminal or server (got '${envRc}').`);
+    }
+    if (opts.remoteControl)
+        rc = true;
+    if (opts.server) {
+        rc = true;
+        server = true;
+    }
+    if (server)
+        return "server";
+    if (rc)
+        return "remote-control";
+    return "terminal";
+}
+/**
+ * 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 function launchPreferenceExplicit(opts, env = process.env) {
+    if (opts.remoteControl || opts.server)
+        return true;
+    return (env.MNEMOM_CODE_REMOTE_CONTROL ?? "").trim() !== "";
+}
+/**
+ * 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 function buildCustomHeaders(opts) {
+    const lines = [
+        `x-api-key: ${opts.anthropicKey}`,
+        `x-mnemom-agent: ${opts.agent}`,
+        `x-mnemom-conversation-id: ${opts.conversationId}`,
+    ];
+    if (opts.contractB64)
+        lines.push(`x-mnemom-contract: ${opts.contractB64}`);
+    return lines.join("\n");
+}

package/dist/lib/config.d.ts

@@ -13,6 +13,18 @@ export type Environment = "production" | "staging" | "local";
  * Defaults to production.
  */
 export declare function getEnvironment(): Environment;
+export type CellRing = "us-1";
+/** Explicitly select a ring for this process (clears on undefined). Wins over MNEMOM_RING. */
+export declare function setRing(ring: CellRing | undefined): void;
+/**
+ * Resolve the active ring, if any: an explicit `setRing()` call wins over
+ * the `MNEMOM_RING` env var. Returns undefined for an unset or unrecognized
+ * value — an unknown ring name is deliberately NOT resolved to production;
+ * callers fall through to the existing Environment-based URLs instead.
+ */
+export declare function getRing(): CellRing | undefined;
+/** Override the active API base for this process (clears on undefined/empty). */
+export declare function setApiUrlOverride(url: string | undefined): void;
 export declare function getApiUrl(): string;
 export declare function getGatewayUrl(): string;
 export declare function getWebsiteUrl(): string;

package/dist/lib/config.js

@@ -34,12 +34,64 @@ export function getEnvironment() {
         return env;
     return "production";
 }
+const RING_URLS = {
+    "us-1": {
+        api: "https://api-us1.mnemom.ai",
+        gateway: "https://gateway-us1.mnemom.ai",
+        website: "https://preview.mnemom.ai",
+    },
+};
+function isCellRing(value) {
+    return Object.prototype.hasOwnProperty.call(RING_URLS, value);
+}
+let ringOverride;
+/** Explicitly select a ring for this process (clears on undefined). Wins over MNEMOM_RING. */
+export function setRing(ring) {
+    ringOverride = ring;
+}
+/**
+ * Resolve the active ring, if any: an explicit `setRing()` call wins over
+ * the `MNEMOM_RING` env var. Returns undefined for an unset or unrecognized
+ * value — an unknown ring name is deliberately NOT resolved to production;
+ * callers fall through to the existing Environment-based URLs instead.
+ */
+export function getRing() {
+    if (ringOverride)
+        return ringOverride;
+    const env = process.env.MNEMOM_RING?.trim();
+    return env && isCellRing(env) ? env : undefined;
+}
+// Process-level base overrides. MNEMOM_ENV only selects prod/staging/local;
+// to target an arbitrary ring (preview/us-1, test) a command can set an
+// explicit override (e.g. `try-me --api <ring>`) or the operator can export
+// MNEMOM_API_URL / MNEMOM_GATEWAY_URL / MNEMOM_WEBSITE_URL. Crucially these
+// flow through EVERY surface — including OAuth discovery + the one-click claim
+// login — so a non-prod ring's sign-in no longer falls back to the prod AS.
+//
+// Precedence (highest wins): apiUrlOverride > raw MNEMOM_*_URL env >
+// ring (setRing()/MNEMOM_RING) > Environment table. A ring only fills the
+// gap the raw overrides leave — it never has to be perfectly bypass-able,
+// because the raw overrides above it in the chain always can.
+let apiUrlOverride;
+/** Override the active API base for this process (clears on undefined/empty). */
+export function setApiUrlOverride(url) {
+    const trimmed = url?.trim().replace(/\/+$/, "");
+    apiUrlOverride = trimmed || undefined;
+}
+function envBase(name) {
+    const v = process.env[name]?.trim();
+    return v ? v.replace(/\/+$/, "") : undefined;
+}
+function ringUrls() {
+    const ring = getRing();
+    return ring ? RING_URLS[ring] : undefined;
+}
 export function getApiUrl() {
-    return API_URLS[getEnvironment()];
+    return (apiUrlOverride ?? envBase("MNEMOM_API_URL") ?? ringUrls()?.api ?? API_URLS[getEnvironment()]);
 }
 export function getGatewayUrl() {
-    return GATEWAY_URLS[getEnvironment()];
+    return envBase("MNEMOM_GATEWAY_URL") ?? ringUrls()?.gateway ?? GATEWAY_URLS[getEnvironment()];
 }
 export function getWebsiteUrl() {
-    return WEBSITE_URLS[getEnvironment()];
+    return envBase("MNEMOM_WEBSITE_URL") ?? ringUrls()?.website ?? WEBSITE_URLS[getEnvironment()];
 }

package/dist/lib/keyed-identity.d.ts

@@ -0,0 +1,35 @@
+import { type ValidationCheck } from "../commands/protection.js";
+export declare const KEYED_MODES: readonly ["observe", "nudge", "enforce"];
+export type KeyedMode = (typeof KEYED_MODES)[number];
+export declare const EVAL_BATTERY_MODEL: "claude-opus-5";
+export interface KeyedModeEntry {
+    label?: unknown;
+    mode?: unknown;
+    model?: unknown;
+    agent_id?: unknown;
+    agent_hash?: unknown;
+    secret_ref?: unknown;
+    snapshot?: unknown;
+}
+export interface KeyedDirectLane {
+    label?: unknown;
+    mode?: unknown;
+    path?: unknown;
+    secret_ref?: unknown;
+    model?: unknown;
+    snapshot?: unknown;
+    agent_id?: unknown;
+    agent_hash?: unknown;
+}
+/**
+ * Validate the keyed-mode manifest against the three parsed snapshots.
+ *
+ * @param manifest  Parsed `cards/keyed-modes.manifest.yaml` (`{ entries: [...] }`).
+ * @param snapshots Map of snapshot filename → parsed protection card, keyed by
+ *                  the `snapshot:` value each manifest entry declares.
+ * @returns Flat list of `{ name, passed, message }` checks (mirrors
+ *          ValidationCheck) so callers can render/aggregate. A returned list
+ *          with every `passed === true` means the record is internally
+ *          consistent; any `passed === false` is a failing invariant.
+ */
+export declare function validateKeyedModeManifest(manifest: Record<string, unknown>, snapshots: Record<string, Record<string, unknown>>): ValidationCheck[];