@mnemom/mnemom 0.16.1 → 0.17.0-next.0

package/dist/commands/code-config.js

@@ -0,0 +1,147 @@
+/**
+ * `mnemom code config …` — read and write the persistent per-customer settings
+ * for `mnemom code` (see lib/code-config.ts). A sub-verb of `mnemom code`, so a
+ * customer configures the launcher once and never retypes their flags:
+ *
+ *   mnemom code config list                 # show the current settings
+ *   mnemom code config get <key>            # print one value
+ *   mnemom code config set <key> <value>    # validate + persist one value
+ *   mnemom code config unset <key>          # remove one value
+ *   mnemom code config edit                 # open ~/.mnemom/code.toml in $EDITOR
+ *   mnemom code config path                 # print the settings file path
+ *
+ * Settable keys are the single source of truth in lib/code-config.ts CONFIG_KEYS.
+ * The secret Anthropic key is NOT a config key — it lives in ~/.mnemom/code.json.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { CODE_CONFIG_PATH, CONFIG_KEYS, configKeySpec, loadCodeConfig, writeCodeConfig, } from "../lib/code-config.js";
+const out = (line = "") => console.log(line);
+const err = (line = "") => console.error(line);
+/** Entry point for `mnemom code config <verb> [args...]`. Throws on misuse. */
+export async function codeConfigCommand(argv) {
+    const [verb, ...rest] = argv;
+    switch (verb) {
+        case undefined:
+        case "list":
+            return listConfig();
+        case "path":
+            out(CODE_CONFIG_PATH);
+            return;
+        case "get":
+            return getConfig(rest[0]);
+        case "set":
+            return setConfig(rest[0], rest[1]);
+        case "unset":
+            return unsetConfig(rest[0]);
+        case "edit":
+            return editConfig();
+        default:
+            throw new Error(`mnemom code config: unknown verb '${verb}'. Use list | get | set | unset | edit | path.`);
+    }
+}
+function listConfig() {
+    const cfg = loadCodeConfig();
+    const rows = [];
+    for (const spec of CONFIG_KEYS) {
+        const v = spec.get(cfg);
+        if (v !== undefined)
+            rows.push([spec.key, String(v)]);
+    }
+    if (!rows.length) {
+        out(`No settings yet at ${CODE_CONFIG_PATH}.`);
+        out("Set one with:  mnemom code config set <key> <value>");
+        out("");
+        out("Settable keys:");
+        for (const spec of CONFIG_KEYS)
+            out(`  ${spec.key.padEnd(22)} ${spec.describe}`);
+        return;
+    }
+    const width = Math.max(...rows.map(([k]) => k.length));
+    out(`# ${CODE_CONFIG_PATH}`);
+    for (const [k, v] of rows)
+        out(`${k.padEnd(width)}  ${v}`);
+}
+function getConfig(key) {
+    if (!key)
+        throw new Error("mnemom code config get: a <key> is required.");
+    const spec = requireSpec(key);
+    const value = spec.get(loadCodeConfig());
+    if (value === undefined) {
+        err(`mnemom code config: '${key}' is not set.`);
+        process.exitCode = 1;
+        return;
+    }
+    out(String(value));
+}
+function setConfig(key, value) {
+    if (!key)
+        throw new Error("mnemom code config set: a <key> is required.");
+    if (value === undefined)
+        throw new Error(`mnemom code config set: a value for '${key}' is required.`);
+    const spec = requireSpec(key);
+    const cfg = loadCodeConfig();
+    spec.set(cfg, value); // validates + coerces; throws on invalid
+    writeCodeConfig(cfg);
+    out(`${key} = ${String(spec.get(cfg))}   (saved to ${CODE_CONFIG_PATH})`);
+}
+function unsetConfig(key) {
+    if (!key)
+        throw new Error("mnemom code config unset: a <key> is required.");
+    requireSpec(key);
+    const cfg = loadCodeConfig();
+    deleteKey(cfg, key);
+    writeCodeConfig(cfg);
+    out(`unset ${key}   (saved to ${CODE_CONFIG_PATH})`);
+}
+function editConfig() {
+    // Seed a header-only file so $EDITOR opens something with guidance, not a blank.
+    if (!existsSync(CODE_CONFIG_PATH))
+        writeCodeConfig(loadCodeConfig());
+    const editor = process.env.VISUAL || process.env.EDITOR || fallbackEditor();
+    const res = spawnSync(editor, [CODE_CONFIG_PATH], { stdio: "inherit" });
+    if (res.error) {
+        throw new Error(`mnemom code config edit: could not launch editor '${editor}': ${res.error.message}\n` +
+            `  Set $EDITOR, or edit ${CODE_CONFIG_PATH} directly.`);
+    }
+    // Re-parse so a typo surfaces now, not at the next launch.
+    loadCodeConfig();
+    out(`Saved ${CODE_CONFIG_PATH}.`);
+}
+function fallbackEditor() {
+    for (const cand of ["nano", "vim", "vi"]) {
+        const r = spawnSync("sh", ["-c", `command -v "$1" >/dev/null 2>&1`, "sh", cand], {
+            stdio: "ignore",
+        });
+        if (r.status === 0)
+            return cand;
+    }
+    return "vi";
+}
+function requireSpec(key) {
+    const spec = configKeySpec(key);
+    if (!spec) {
+        throw new Error(`mnemom code config: unknown key '${key}'.\n  Known keys: ${CONFIG_KEYS.map((k) => k.key).join(", ")}`);
+    }
+    return spec;
+}
+/** Remove a (possibly dotted) key from a config object, pruning an emptied table. */
+function deleteKey(cfg, key) {
+    if (key.startsWith("guardrails.")) {
+        const g = cfg.guardrails;
+        if (!g)
+            return;
+        const field = key.slice("guardrails.".length);
+        if (field === "max_turns")
+            delete g.maxTurns;
+        if (field === "budget_usd")
+            delete g.budgetUsd;
+        if (field === "stall_turns")
+            delete g.stallTurns;
+        if (g.maxTurns === undefined && g.budgetUsd === undefined && g.stallTurns === undefined) {
+            delete cfg.guardrails;
+        }
+        return;
+    }
+    delete cfg[key === "key_source" ? "keySource" : key];
+}

package/dist/commands/code-doctor.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `mnemom code doctor` — a read-only preflight for `mnemom code`. It checks the
+ * things a governed launch needs and prints a checklist with clear, actionable
+ * remediation, so a customer can see at a glance why a launch would fail before
+ * it does. Writes nothing and reads no secret VALUE (only whether a key is
+ * resolvable). Exits non-zero when the machine is not launch-ready (no coding
+ * agent CLI, or no Anthropic key), so it can gate a script.
+ *
+ * Checks: settings file, coding-agent CLI, Anthropic key source, gateway health
+ * (200 + the x-mnemom-verdict header that proves the governance pipeline is
+ * live), Remote-Control capability (node + openssl + the --remote-control flag),
+ * and claude.ai login (informational — Remote Control needs it).
+ */
+export interface DoctorOptions {
+    cli?: string;
+}
+/** Run the preflight and print the checklist. Sets process.exitCode on failure. */
+export declare function codeDoctorCommand(options?: DoctorOptions): Promise<void>;

package/dist/commands/code-doctor.js

@@ -0,0 +1,138 @@
+/**
+ * `mnemom code doctor` — a read-only preflight for `mnemom code`. It checks the
+ * things a governed launch needs and prints a checklist with clear, actionable
+ * remediation, so a customer can see at a glance why a launch would fail before
+ * it does. Writes nothing and reads no secret VALUE (only whether a key is
+ * resolvable). Exits non-zero when the machine is not launch-ready (no coding
+ * agent CLI, or no Anthropic key), so it can gate a script.
+ *
+ * Checks: settings file, coding-agent CLI, Anthropic key source, gateway health
+ * (200 + the x-mnemom-verdict header that proves the governance pipeline is
+ * live), Remote-Control capability (node + openssl + the --remote-control flag),
+ * and claude.ai login (informational — Remote Control needs it).
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { anthropicKeySource, checkRcCapability, resolveCliBin, } from "./code.js";
+import { isProdGateway, resolveAnthropicDoor, resolveGatewayHost, } from "../lib/code.js";
+import { CODE_CONFIG_PATH } from "../lib/code-config.js";
+const MARK = { ok: "[ ok ]", warn: "[warn]", miss: "[MISS]", info: "[info]" };
+const out = (line = "") => console.log(line);
+/** Run the preflight and print the checklist. Sets process.exitCode on failure. */
+export async function codeDoctorCommand(options = {}) {
+    const env = process.env;
+    const lines = [];
+    const add = (mark, text, hint) => {
+        lines.push({ mark, text, hint });
+    };
+    // ── settings file ──
+    if (existsSync(CODE_CONFIG_PATH))
+        add("ok", `settings: ${CODE_CONFIG_PATH}`);
+    else
+        add("info", `settings: none yet (${CODE_CONFIG_PATH}) — using built-in defaults`, "save your defaults with `mnemom code config set <key> <value>`");
+    // ── coding-agent CLI ──
+    let cli;
+    try {
+        cli = resolveCliBin(options.cli, env);
+        add("ok", `coding-agent CLI: ${cli.name} (${cli.bin})`);
+    }
+    catch (err) {
+        add("miss", `coding-agent CLI: ${err instanceof Error ? err.message.split("\n")[0] : err}`, "install Claude Code, or pass --cli <name|/full/path> / set it with `mnemom code config set cli <path>`");
+    }
+    // ── Anthropic key ──
+    const keySrc = anthropicKeySource(env);
+    if (keySrc === "env")
+        add("ok", "Anthropic key: found in the environment");
+    else if (keySrc === "store")
+        add("ok", "Anthropic key: found in ~/.mnemom/code.json");
+    else
+        add("miss", "Anthropic key: none found", "export MNEMOM_CODE_ANTHROPIC_KEY=sk-ant-… (or ANTHROPIC_API_KEY), or run `mnemom code` once and accept the save prompt");
+    // ── gateway health ──
+    const host = resolveGatewayHost(env);
+    const cell = isProdGateway(env) ? "us-2/prod" : "custom";
+    const health = await probeGateway(host);
+    if (health.ok && health.verdictHeader) {
+        add("ok", `gateway: ${host} [${cell}] healthy (governance pipeline live)`);
+    }
+    else if (health.ok) {
+        add("warn", `gateway: ${host} [${cell}] responded ${health.status} but without an x-mnemom-verdict header`, "the cell is up but the governance pipeline may not be wired — traces/nudges may not appear");
+    }
+    else {
+        add("warn", `gateway: ${host} [${cell}] unreachable (${health.detail})`, "check the host (MNEMOM_CODE_GATEWAY / `mnemom code config set gateway <url>`) and your network");
+    }
+    // ── Remote Control capability ──
+    if (cli) {
+        const rc = checkRcCapability(cli);
+        if (rc.ok)
+            add("ok", "Remote Control: available (node + openssl + --remote-control)");
+        else
+            add("warn", `Remote Control: unavailable — ${rc.missing.join("; ")}`, "launches fall back to terminal-only until these are in place");
+        // ── claude.ai login (informational — RC needs it) ──
+        if (cli.name === "claude") {
+            const login = claudeLoggedIn(cli.bin);
+            if (login === true)
+                add("ok", "claude.ai login: logged in");
+            else if (login === false)
+                add("info", "claude.ai login: not logged in", "Remote Control needs a claude.ai login; the terminal-only shape does not");
+            else
+                add("info", "claude.ai login: could not determine");
+        }
+    }
+    // ── render ──
+    const door = resolveAnthropicDoor(env);
+    out("mnemom code doctor");
+    out(`  door: ${door}`);
+    out("");
+    for (const l of lines) {
+        out(`  ${MARK[l.mark]} ${l.text}`);
+        if (l.hint)
+            out(`         ↳ ${l.hint}`);
+    }
+    out("");
+    const launchReady = !lines.some((l) => l.mark === "miss");
+    if (launchReady) {
+        out("  Ready to launch:  mnemom code <scenario>");
+    }
+    else {
+        out("  Not launch-ready — resolve the [MISS] items above.");
+        process.exitCode = 1;
+    }
+}
+/** GET <host>/health with a short timeout; report status + whether the verdict header rode along. */
+async function probeGateway(host) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 6000);
+    try {
+        const res = await fetch(`${host}/health`, { signal: controller.signal });
+        return {
+            ok: res.status >= 200 && res.status < 300,
+            status: res.status,
+            verdictHeader: res.headers.has("x-mnemom-verdict"),
+        };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            verdictHeader: false,
+            detail: err instanceof Error ? err.message : String(err),
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** true / false / null(unknown) — whether the claude CLI reports a claude.ai login. */
+function claudeLoggedIn(bin) {
+    try {
+        const res = spawnSync(bin, ["auth", "status", "--json"], { encoding: "utf8", timeout: 10_000 });
+        const text = `${res.stdout ?? ""}${res.stderr ?? ""}`;
+        if (/"loggedIn"\s*:\s*true/.test(text))
+            return true;
+        if (/"loggedIn"\s*:\s*false/.test(text))
+            return false;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/commands/code-setup.d.ts

@@ -0,0 +1,97 @@
+/**
+ * `mnemom code setup` + the zero-friction provisioning behind a bare
+ * `mnemom code <scenario>`.
+ *
+ * If a customer names no agent, `mnemom code` launches under a per-customer
+ * governed identity `code-<handle>`. This module makes that identity REAL in
+ * their Mnemom org: it births the agent through the gateway, claims it (so the
+ * customer owns it), and publishes a sane default coding posture — nudge/nudge:
+ *   - alignment card: autonomy_mode + integrity_mode = nudge,
+ *     principal.relationship = delegated_authority, coding bounded/forbidden
+ *     actions, escalate-on-irreversible;
+ *   - protection card: mode = nudge, thresholds 0.60/0.80/0.95, all four
+ *     screen_surfaces on.
+ *
+ * All account writes are gated: interactive runs show the plan and confirm;
+ * non-interactive runs provision only with an explicit `--setup`, and otherwise
+ * launch under the unclaimed (fail-open) identity with a clear warning. A
+ * provisioning failure never blocks the launch. Reuses the existing machinery —
+ * birthThroughGateway (wrap.ts), deriveHashProof (agents.ts), claimAgent +
+ * putAlignmentCard/putProtectionCard (lib/api.ts) — rather than reinventing it.
+ */
+/**
+ * The default governed-agent slug for the current customer: `code-<handle>`,
+ * where <handle> is the local-part of their mnemom login email (sanitised), or
+ * "user" when no email is available (API-key auth / opaque OAuth token).
+ */
+export declare function defaultAgentSlug(): string;
+export interface EnsureAgentOptions {
+    /** The already-resolved final agent slug (what rides as x-mnemom-agent). */
+    slug: string;
+    /** The customer's Anthropic key (for the birth call + hash-proof). Never logged. */
+    anthropicKey: string;
+    /** undefined = auto, true = force (--setup), false handled by the caller (skip). */
+    setup?: boolean;
+    /** Gateway host the launch targets (birth goes to the same cell). */
+    gatewayHost: string;
+    /** Override interactivity (defaults to isInteractive()). */
+    interactive?: boolean;
+}
+export interface EnsureAgentResult {
+    slug: string;
+    /** true only when this call actually birthed/claimed/published. */
+    provisioned: boolean;
+}
+/**
+ * Ensure `slug` is a usable governed agent in the customer's org. Returns
+ * {provisioned:false} when it is already usable, when provisioning is not
+ * allowed here (non-interactive without --setup, or not logged in), or when the
+ * customer declines the confirm — in all those cases the launch continues under
+ * the given slug. THROWS only on an actual provisioning failure (birth/claim/
+ * card write) so the caller can decide whether that is fatal (`mnemom code
+ * setup`) or a warn-and-continue (a bare launch).
+ */
+export declare function ensureGovernedAgent(opts: EnsureAgentOptions): Promise<EnsureAgentResult>;
+/** `mnemom code setup [--agent <slug>]` — the explicit provisioning entry point. */
+export declare function codeSetupCommand(opts?: {
+    agent?: string;
+}): Promise<void>;
+/** Thrown when the agent's org has no spendable MU balance. The user-facing
+ *  top-up guidance is already printed when this is thrown — callers exit quietly. */
+export declare class MuInsufficientError extends Error {
+    readonly orgLabel: string;
+    constructor(orgLabel: string);
+}
+/**
+ * Ensure the customer has a Mnemom session, the way `mnemom try-me` does: if
+ * they are not signed in, offer a one-click browser sign-in (device-flow
+ * fallback for headless/SSH boxes), mentioning that a free account can be
+ * created in the same flow. Returns true if a session exists (or was just
+ * created), false if the customer declined or the run is non-interactive.
+ * Idempotent — a no-op when already authenticated.
+ */
+export declare function ensureMnemomSession(opts?: {
+    interactive?: boolean;
+}): Promise<boolean>;
+/**
+ * Enforce a positive Mnemom Units balance on the org the agent lives in.
+ * `mnemom code` has NO free tier — a determined zero/negative balance (or an org
+ * with no billing account) is BLOCKED with a portal-style top-up message.
+ * Fails OPEN on an inconclusive error (transient 5xx / network / 403), since the
+ * gateway is the real enforcement and this is a friendly pre-check; hard-blocks
+ * only on a determined depletion. Requires a session (caller ensures one first).
+ */
+export declare function assertMuBalance(orgId: string, orgLabel: string): Promise<void>;
+/**
+ * The shared pre-launch preamble for `mnemom code` (and `mnemom code setup`):
+ * ensure a Mnemom session (login/sign-up), then enforce the MU balance on the
+ * org the agent lives in (default: the user's personal org). Returns the
+ * resolved org so the caller can reuse it. Throws with clear guidance when there
+ * is no session, or MuInsufficientError (message already printed) on zero MUs.
+ */
+export declare function ensureSessionAndBalance(opts: {
+    interactive?: boolean;
+}): Promise<{
+    orgId: string;
+    orgLabel: string;
+}>;