@mnemom/mnemom 0.16.2 → 0.17.0-next.0

package/dist/commands/code-setup.js

@@ -0,0 +1,330 @@
+/**
+ * `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.
+ */
+import { claimAgent, getAgentByName, getMuBalance, getMyPersonalOrg, MnemomApiError, putAlignmentCard, putProtectionCard, } from "../lib/api.js";
+import { getAuthInfo, isLoggedIn, loginWithBrowser, loginWithDeviceFlow, resolveAuth, } from "../lib/auth.js";
+import { getActiveOrg } from "../lib/cli-config.js";
+import { getWebsiteUrl } from "../lib/config.js";
+import { fmt } from "../lib/format.js";
+import { askYesNo, isInteractive } from "../lib/prompt.js";
+import { resolveGatewayHost, sanitizeAgentName } from "../lib/code.js";
+import { configKeySpec, loadCodeConfig, writeCodeConfig } from "../lib/code-config.js";
+import { deriveHashProof } from "./agents.js";
+import { birthThroughGateway } from "./wrap.js";
+import { resolveAnthropicKey } from "./code.js";
+const say = (line = "") => console.error(line);
+/**
+ * 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 function defaultAgentSlug() {
+    const email = getAuthInfo()?.email ?? "";
+    const local = email.split("@")[0] ?? "";
+    const handle = sanitizeAgentName(local) || "user";
+    return `code-${handle}`;
+}
+/**
+ * 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 async function ensureGovernedAgent(opts) {
+    const slug = opts.slug;
+    const interactive = opts.interactive ?? isInteractive();
+    // 1. Already usable? A named agent in the caller's fleet is claimed by them.
+    const loggedIn = await isLoggedIn();
+    if (loggedIn) {
+        const existing = await getAgentByName(slug).catch(() => null);
+        if (existing)
+            return { slug, provisioned: false };
+    }
+    // 2. Are we allowed to provision here?
+    const canProvision = opts.setup === true || (opts.setup !== false && interactive);
+    if (!canProvision) {
+        warnUnclaimed(slug);
+        return { slug, provisioned: false };
+    }
+    // 3. Writing to the org needs a mnemom session.
+    if (!loggedIn) {
+        if (opts.setup === true && !interactive) {
+            throw new Error("not authenticated — run `mnemom login` (or set MNEMOM_API_KEY) first.");
+        }
+        say(fmt.warn(`mnemom code: not logged in — can't provision '${slug}'.`));
+        say(fmt.dim("  Run `mnemom login`, then `mnemom code setup`. Launching with the unclaimed identity for now."));
+        return { slug, provisioned: false };
+    }
+    // 4. Confirm the plan (interactive runs; --setup non-interactive proceeds).
+    const org = getActiveOrg();
+    const orgLabel = org ? `${org.name} (${org.slug})` : "your personal org";
+    if (interactive) {
+        say(fmt.section("Set up a governed coding agent"));
+        say(fmt.label("  Agent:", slug));
+        say(fmt.label("  Org:", orgLabel));
+        say(fmt.label("  Posture:", "nudge / nudge (alignment: autonomy + integrity nudge; protection: all surfaces screened)"));
+        say(fmt.dim("  Births the agent through the gateway, claims it to your org, and publishes its cards."));
+        if (!(await askYesNo("Provision and claim this agent now?", true))) {
+            say(fmt.dim("  Skipped — launching under the unclaimed identity. Run `mnemom code setup` anytime."));
+            return { slug, provisioned: false };
+        }
+    }
+    // 5. Birth → claim → publish nudge/nudge cards. (Key never logged.)
+    const gatewayUrl = opts.gatewayHost.replace(/\/+$/, "");
+    const agentId = await birthThroughGateway(gatewayUrl, "anthropic", slug, opts.anthropicKey);
+    const hashProof = deriveHashProof(opts.anthropicKey, slug);
+    await claimAgent(agentId, { hashProof, orgId: org?.org_id });
+    await putAlignmentCard(agentId, JSON.stringify(buildCodeAlignmentCard(agentId)), "application/json");
+    await putProtectionCard(agentId, JSON.stringify(buildCodeProtectionCard(agentId)), "application/json");
+    say(fmt.success(`mnemom code: provisioned + claimed '${slug}' (${agentId}) in ${orgLabel} — nudge/nudge posture published.`));
+    // 6. Remember the slug so future launches skip straight to usable.
+    persistAgentSlug(slug);
+    return { slug, provisioned: true };
+}
+/** `mnemom code setup [--agent <slug>]` — the explicit provisioning entry point. */
+export async function codeSetupCommand(opts = {}) {
+    const gatewayHost = resolveGatewayHost(process.env);
+    // Sign in (offer sign-up) and enforce the MU balance before any account write.
+    try {
+        await ensureSessionAndBalance({});
+    }
+    catch (err) {
+        if (err instanceof MuInsufficientError)
+            process.exit(1);
+        throw err;
+    }
+    const anthropicKey = await resolveAnthropicKey(process.env, { allowPrompt: true });
+    const slug = opts.agent?.trim() ? sanitizeAgentName(opts.agent.trim()) : defaultAgentSlug();
+    if (!slug)
+        throw new Error("mnemom code setup: agent slug sanitised to empty — pass --agent <slug>.");
+    const result = await ensureGovernedAgent({ slug, anthropicKey, setup: true, gatewayHost });
+    if (!result.provisioned) {
+        say(fmt.dim(`  '${slug}' is ready (already claimed) or setup was skipped.`));
+    }
+}
+function warnUnclaimed(slug) {
+    say(fmt.warn(`mnemom code: agent '${slug}' is not set up in your org — launching with an UNCLAIMED identity (governance is advisory/fail-open).`));
+    say(fmt.dim("  Provision it (creates + claims the agent, publishes nudge/nudge cards): mnemom code setup"));
+}
+function persistAgentSlug(slug) {
+    try {
+        const cfg = loadCodeConfig();
+        if (!cfg.agent) {
+            configKeySpec("agent").set(cfg, slug);
+            writeCodeConfig(cfg);
+        }
+    }
+    catch {
+        // best effort — provisioning already succeeded either way
+    }
+}
+// ── Session (login/sign-up, the try-me flow) + MU balance gate ──────────────
+/** 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 class MuInsufficientError extends Error {
+    orgLabel;
+    constructor(orgLabel) {
+        super("insufficient MU balance");
+        this.orgLabel = orgLabel;
+        this.name = "MuInsufficientError";
+    }
+}
+/** Best-effort detection of a headless/SSH box where a browser can't open. */
+function headlessEnv() {
+    const e = process.env;
+    if (e.SSH_CONNECTION || e.SSH_TTY)
+        return true;
+    if (process.platform === "linux" && !e.DISPLAY && !e.WAYLAND_DISPLAY)
+        return true;
+    return false;
+}
+/**
+ * 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 async function ensureMnemomSession(opts = {}) {
+    const cred = await resolveAuth();
+    if (cred.type !== "none")
+        return true; // already a jwt or api-key session
+    const interactive = opts.interactive ?? isInteractive();
+    if (!interactive)
+        return false;
+    say(fmt.section("Sign in to Mnemom"));
+    say(fmt.dim("  mnemom code runs your coding session governed and under your Mnemom account,"));
+    say(fmt.dim("  so it shows up in your traces and bills to your org's Mnemom Units."));
+    say(fmt.dim(`  New to Mnemom? You can create a free account in the same flow (or at ${getWebsiteUrl()}/signup).`));
+    if (!(await askYesNo("Sign in or create your account now?", true)))
+        return false;
+    const device = headlessEnv();
+    try {
+        if (device)
+            await loginWithDeviceFlow();
+        else
+            await loginWithBrowser();
+    }
+    catch (err) {
+        if (!device) {
+            say(fmt.dim("  Browser sign-in didn't work here — falling back to a device code…"));
+            await loginWithDeviceFlow();
+        }
+        else {
+            throw err;
+        }
+    }
+    say(fmt.success("Signed in to Mnemom."));
+    return true;
+}
+/**
+ * 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 async function assertMuBalance(orgId, orgLabel) {
+    let bal;
+    try {
+        bal = await getMuBalance(orgId);
+    }
+    catch (err) {
+        if (err instanceof MnemomApiError && err.status === 409) {
+            // Org has no billing account ⇒ no MUs. Block.
+            printTopUp(orgLabel, "0");
+            throw new MuInsufficientError(orgLabel);
+        }
+        // Inconclusive — don't lock out a paying customer on a transient failure.
+        say(fmt.dim(`  (Could not verify your MU balance — ${err instanceof Error ? err.message : String(err)}. Continuing.)`));
+        return;
+    }
+    const available = safeBigInt(bal.balanceMmu) - safeBigInt(bal.activeHoldsMmu);
+    if (available <= 0n) {
+        printTopUp(orgLabel, bal.balanceMu ?? "0");
+        throw new MuInsufficientError(orgLabel);
+    }
+}
+function safeBigInt(v) {
+    try {
+        return BigInt(String(v ?? "0").trim().split(".")[0] || "0");
+    }
+    catch {
+        return 0n;
+    }
+}
+/**
+ * The "you need Mnemom Units" message (no free tier). Voiced like the portal's
+ * enforcement-paused banner — safety features can't run without µ — but never
+ * says "exhausted" (that assumes a prior balance; a new org may simply have none).
+ */
+function printTopUp(orgLabel, balanceMu) {
+    say();
+    say(fmt.warn(`No Mnemom Units — ${orgLabel} has a balance of ${balanceMu} µ.`));
+    say(fmt.dim("  mnemom code runs on Mnemom Units (µ), and there's no free tier. Without µ,"));
+    say(fmt.dim("  Mnemom's safety features can't run, so the launch is blocked. Top up to launch"));
+    say(fmt.dim("  a governed session:"));
+    say();
+    say(`    Top up µ:  ${getWebsiteUrl()}/settings/billing`);
+    say(fmt.dim("  If you don't manage billing for this org, ask an admin to top up."));
+    say();
+    say(fmt.dim("  Your balance updates the moment a top-up completes — then re-run `mnemom code`."));
+}
+/**
+ * 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 async function ensureSessionAndBalance(opts) {
+    const interactive = opts.interactive ?? isInteractive();
+    const haveSession = await ensureMnemomSession({ interactive });
+    if (!haveSession) {
+        throw new Error("mnemom code needs a Mnemom account — it runs your coding session governed and on Mnemom Units.\n" +
+            "  Sign in:   mnemom login   (or set MNEMOM_API_KEY)\n" +
+            `  New here?  create a free account, then add MUs: ${getWebsiteUrl()}/settings/billing`);
+    }
+    const active = getActiveOrg();
+    const orgId = active?.org_id ?? (await getMyPersonalOrg()).org_id;
+    const orgLabel = active ? `${active.name} (${active.slug})` : "your personal org";
+    await assertMuBalance(orgId, orgLabel);
+    return { orgId, orgLabel };
+}
+// ── The default coding posture (nudge/nudge) ────────────────────────────────
+function buildCodeAlignmentCard(agentId) {
+    return {
+        card_version: "unified/2026-04-26",
+        agent_id: agentId,
+        autonomy_mode: "nudge",
+        integrity_mode: "nudge",
+        principal: { type: "agent", identifier: agentId, relationship: "delegated_authority" },
+        values: {
+            declared: ["transparency", "safety", "honesty", "user_control", "harm_prevention"],
+        },
+        autonomy: {
+            bounded_actions: [
+                "read_files",
+                "search_code",
+                "edit_files",
+                "run_commands",
+                "fetch_web_content",
+                "use_developer_tools",
+            ],
+            forbidden_actions: [
+                "push_to_main",
+                "force_push",
+                "delete_remote_branches",
+                "trigger_production_deploy",
+                "exfiltrate_credentials",
+                "modify_ci_secrets",
+            ],
+            escalation_triggers: [
+                {
+                    condition: "an irreversible or destructive operation is requested",
+                    action: "escalate",
+                    reason: "a human should confirm before irreversible changes",
+                },
+            ],
+        },
+        audit: { retention_days: 30, queryable: false, trace_format: "otel" },
+    };
+}
+function buildCodeProtectionCard(agentId) {
+    return {
+        card_version: "protection/2026-04-26",
+        agent_id: agentId,
+        mode: "nudge",
+        thresholds: { warn: 0.6, quarantine: 0.8, block: 0.95 },
+        screen_surfaces: {
+            incoming: true,
+            outgoing: true,
+            tool_calls: true,
+            tool_responses: true,
+        },
+        trusted_sources: { domains: [], agent_ids: [], ip_ranges: [] },
+    };
+}

package/dist/commands/code.d.ts

@@ -0,0 +1,133 @@
+/**
+ * `mnemom code <scenario>` — the CLI's first-class governed-coding-agent launcher.
+ *
+ * Launches your coding-agent CLI (Claude Code in v1) with its dev-time model
+ * traffic routed through the Mnemom gateway's /anthropic door for observability +
+ * governance, under a governed agent identity and an optional per-conversation
+ * CONTRACT the gateway seals on the first turn.
+ *
+ * v1 scope:
+ *   - The Claude Code launch adapter (Anthropic /anthropic door; Anthropic-only,
+ *     no router door / Mnemom key). `--cli` selects the executable to run (name or
+ *     full path) so codex/cursor/github adapters can be added later.
+ *   - The us-2/PROD gateway is the DEFAULT door (https://gateway.mnemom.ai); an
+ *     explicit MNEMOM_CODE_GATEWAY / --gateway still wins, never silently prod.
+ *   - Three launch shapes: `terminal` (DEFAULT), `remote-control` (interactive RC
+ *     in this terminal), `server` (headless RC dispatcher). RC runs the CLI
+ *     UNTOUCHED behind a bundled local TLS proxy (rc-proxy.mjs) — Claude Code
+ *     gates RC on a first-party claude.ai-OAuth setup, so the gateway door cannot
+ *     be wired via env there.
+ *   - yolo (`--dangerously-skip-permissions`) is ON by default; `--no-yolo` opts out.
+ *
+ * The Anthropic key is resolved from a credential source with ZERO 1Password
+ * dependency (env → the CLI's own ~/.mnemom/code.json store → interactive
+ * prompt) and placed ONLY in the launched process (an `ANTHROPIC_CUSTOM_HEADERS`
+ * line, or the proxy's stdin under RC). It is never logged, printed, or passed as
+ * an argv value.
+ */
+export interface CodeOptions {
+    goal?: string;
+    requirement?: string[];
+    allow?: string[];
+    forbid?: string[];
+    goalId?: string;
+    budget?: string;
+    maxTurns?: string;
+    stall?: string;
+    /** x-mnemom-agent value (defaults to "code-agent"). */
+    agent?: string;
+    conversationId?: string;
+    cli?: string;
+    remoteControl?: boolean;
+    server?: boolean;
+    model?: string;
+    effort?: string;
+    trimMcp?: boolean;
+    /** yolo default: commander `--no-yolo` sets this false. */
+    yolo?: boolean;
+    /** context-hint seed default: commander `--no-context-hint` sets this false. */
+    contextHint?: boolean;
+    /**
+     * Governed-agent provisioning: undefined = AUTO (provision-with-confirm when
+     * interactive, warn-and-continue otherwise), true = force (`--setup`), false =
+     * skip entirely (`--no-setup`).
+     */
+    setup?: boolean;
+    /**
+     * Where to source the Anthropic key (from ~/.mnemom/code.toml `key_source`).
+     * Restricts the default env → store → prompt search: "env" uses env only,
+     * "store" uses env → store (no prompt), "prompt" forces the interactive prompt.
+     * Undefined = the full default order.
+     */
+    keySource?: "env" | "store" | "prompt";
+    passthrough?: string[];
+    /** Print the resolved launch plan and exit — no key read, no spawn. */
+    dryRun?: boolean;
+}
+/** Entry point for `mnemom code <scenario>`. Throws on fatal misconfig. */
+export declare function codeCommand(scenario: string, options?: CodeOptions): Promise<void>;
+/**
+ * Resolve the Anthropic key with NO 1Password dependency (built for external
+ * customer adoption), in order:
+ *   1. env: MNEMOM_CODE_ANTHROPIC_KEY, else ANTHROPIC_API_KEY
+ *   2. the CLI's own store: ~/.mnemom/code.json (`anthropic_key`)
+ *   3. interactive prompt (masked), offering to save it to the store
+ * Never logged / printed. Throws with guidance when nothing resolves — we refuse
+ * to launch un-routed.
+ */
+export declare function resolveAnthropicKey(env: NodeJS.ProcessEnv, opts: {
+    allowPrompt: boolean;
+    keySource?: "env" | "store" | "prompt";
+}): Promise<string>;
+/**
+ * Where an Anthropic key would resolve from RIGHT NOW, without reading its value:
+ * "env" (MNEMOM_CODE_ANTHROPIC_KEY / ANTHROPIC_API_KEY), "store" (~/.mnemom/code.json),
+ * or null (would fall to the interactive prompt). For `mnemom code doctor`.
+ */
+export declare function anthropicKeySource(env?: NodeJS.ProcessEnv): "env" | "store" | null;
+export interface ResolvedCli {
+    /** The executable to spawn (a resolved path, or a bare name on PATH). */
+    bin: string;
+    /** The basename, e.g. "claude" — selects the launch adapter. */
+    name: string;
+}
+/**
+ * Resolve which coding-agent CLI to launch. `--cli` (or MNEMOM_CODE_CLI) is a
+ * name or a full path; default "claude". A value with a path separator is used
+ * verbatim (must exist); a bare name is resolved on PATH, then — for claude — the
+ * fnm/nvm/asdf install dirs (a version-manager shim / shell function is absent in
+ * the fresh shell that runs the launch). v1 wires only the Claude Code adapter;
+ * a non-claude executable is launched through it with a warning.
+ */
+export declare function resolveCliBin(cliOpt: string | undefined, env: NodeJS.ProcessEnv): ResolvedCli;
+export declare function commandExists(cmd: string): boolean;
+/**
+ * Does the resolved coding-agent CLI advertise the `--remote-control` startup
+ * flag (Claude Code >= 2.1.269)? Determined by scanning its `--help`. Best-effort:
+ * a spawn failure or timeout reads as "no". Only the claude adapter wires RC.
+ */
+export declare function cliSupportsRemoteControl(bin: string): boolean;
+/** The result of checking whether Remote Control can run here. */
+export interface RcCapability {
+    ok: boolean;
+    /** Human reasons RC is unavailable (empty when ok). */
+    missing: string[];
+}
+/**
+ * Can we launch the DEFAULT Remote-Control-in-terminal shape on this machine?
+ * Needs node + openssl (the local proxy mints an ephemeral CA) and a claude
+ * adapter that advertises `--remote-control`. Used both by `mnemom code doctor`
+ * and by the auto-default selection (a bare launch prefers RC when capable).
+ */
+export declare function checkRcCapability(cli: ResolvedCli): RcCapability;
+/**
+ * Build the coding-agent CLI args from the model/effort/trim-mcp/yolo knobs plus
+ * the caller's passthrough. `--model`/`--effort` are injected only when given (no
+ * silent default). yolo appends `--dangerously-skip-permissions`. `--trim-mcp`
+ * appends `--strict-mcp-config --mcp-config {}` LAST so it wins over any
+ * caller-supplied --mcp-config.
+ */
+export declare function buildCliArgs(options: CodeOptions, ctx: {
+    yolo: boolean;
+    allowCliFlags: boolean;
+}): string[];