@mnemom/mnemom 0.17.3 → 0.17.4-next.0

package/dist/commands/agent-doctor.js

@@ -14,6 +14,7 @@
 import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { anthropicKeySource, checkRcCapability, resolveCliBin } from "./agent.js";
+import { resolveAgentAuth } from "../lib/subscription-login.js";
 import { isProdGateway, resolveAnthropicDoor, resolveGatewayHost, singleCellError, } from "../lib/agent.js";
 import { getApiUrl, getGatewayUrl } from "../lib/config.js";
 import { LAUNCHER_CONFIG_PATH } from "../lib/launcher-config.js";
@@ -45,14 +46,26 @@ export async function agentDoctorCommand(options = {}) {
     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 agent 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/launcher.json");
-    else
-        add("miss", "Anthropic key: none found", "export MNEMOM_AGENT_ANTHROPIC_KEY=sk-ant-… (or ANTHROPIC_API_KEY), or run `mnemom agent` once and accept the save prompt");
+    // ── auth: an Anthropic key, or the claude.ai subscription login (no key needed) ──
+    let auth = "api-key";
+    try {
+        auth = resolveAgentAuth(undefined, env);
+    }
+    catch (err) {
+        add("miss", `auth: ${err instanceof Error ? err.message : String(err)}`, "`mnemom agent config set auth api-key` (or subscription)");
+    }
+    if (auth === "subscription") {
+        add("ok", "auth: subscription — Claude Code uses your claude.ai login (Team/Enterprise plans only); no Anthropic key needed");
+    }
+    else {
+        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/launcher.json");
+        else
+            add("miss", "Anthropic key: none found", "export MNEMOM_AGENT_ANTHROPIC_KEY=sk-ant-… (or ANTHROPIC_API_KEY), or run `mnemom agent` once and accept the save prompt");
+    }
     // ── one cell: the launch door must be the CLI's own cell ──
     const cellError = singleCellError({
         door: resolveAnthropicDoor(env),

package/dist/commands/agent.d.ts

@@ -25,6 +25,7 @@
  * line, or the proxy's stdin under RC). It is never logged, printed, or passed as
  * an argv value.
  */
+import { type MnemomKeyDeps } from "../lib/subscription-login.js";
 import { type ExperimentalId } from "../lib/experimental.js";
 import { type ContextProfile, type LaunchShape, type SealedContractEnvelope } from "../lib/agent.js";
 export interface AgentOptions {
@@ -48,6 +49,8 @@ export interface AgentOptions {
     cli?: string;
     remoteControl?: boolean;
     server?: boolean;
+    /** `--auth api-key|subscription` (lib/subscription-login.ts); else MNEMOM_AGENT_AUTH / config. */
+    auth?: string;
     model?: string;
     effort?: string;
     trimMcp?: boolean;
@@ -124,6 +127,8 @@ export declare function recordSessionLaunch(ctx: {
     /** The resolved context profile this launch runs under. */
     contextProfile: ContextProfile;
 }): Promise<void>;
+/** The real I/O behind a subscription launch's Mnemom key (lib/subscription-login.ts). */
+export declare function defaultMnemomKeyDeps(storePath?: string): MnemomKeyDeps;
 /**
  * Resolve the Anthropic key with NO 1Password dependency (built for external
  * customer adoption), in order:

package/dist/commands/agent.js

@@ -28,11 +28,12 @@
 import { spawn, spawnSync } from "node:child_process";
 import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync, renameSync, } from "node:fs";
 import { randomUUID } from "node:crypto";
-import { tmpdir, homedir } from "node:os";
+import { tmpdir, homedir, hostname } from "node:os";
 import { basename, join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { getApiUrl, getGatewayUrl, MNEMOM_DIR } from "../lib/config.js";
-import { getAgentByName } from "../lib/api.js";
+import { createApiKey, getAgentByName } from "../lib/api.js";
+import { MNEMOM_KEY_STORE_FIELD, resolveAgentAuth, resolveSubscriptionMnemomKey, subscriptionChildEnv, subscriptionShape, } from "../lib/subscription-login.js";
 import { LEDGER_FILE, appendSessionRecord, resolveRetentionDays, toLedgerContract, } from "../lib/agent-ledger.js";
 import { loadCliConfig } from "../lib/cli-config.js";
 import { configKeySpec, loadLauncherConfig, writeLauncherConfig } from "../lib/launcher-config.js";
@@ -77,6 +78,9 @@ export async function agentCommand(scenarioArg, options = {}) {
     const env = process.env;
     let shape = resolveLaunchShape({ remoteControl: options.remoteControl, server: options.server }, env);
     const shapeExplicit = launchPreferenceExplicit({ remoteControl: options.remoteControl, server: options.server }, env);
+    // How Claude Code authenticates: an Anthropic key (default) or the user's claude.ai
+    // subscription login (Team/Enterprise; lib/subscription-login.ts).
+    const auth = resolveAgentAuth(options.auth, env);
     // ── governed identity ── (default: per-customer `agent-<handle>`, not a shared
     // "code-agent" — see defaultAgentSlug; provisioning claims exactly this slug.
     // `let` because a brand-new user who signs in during the pre-launch gate below
@@ -124,7 +128,12 @@ export async function agentCommand(scenarioArg, options = {}) {
         context: options.context,
         env,
     });
-    const contextHandoff = resolveContextHandoff({ contextHandoff: options.contextHandoff, env });
+    let contextHandoff = resolveContextHandoff({ contextHandoff: options.contextHandoff, env });
+    if (contextHandoff && auth === "subscription") {
+        // The handoff tool authenticates with the Anthropic key a subscription launch does not have.
+        say("mnemom agent: context handoff is not available with subscription login yet — launching without it.");
+        contextHandoff = false;
+    }
     const experimental = options.experimental ?? [];
     const sessionConfig = buildSessionConfig({ profile: contextProfile, contextHandoff });
     const sessionConfigB64 = buildSessionConfigB64({
@@ -175,6 +184,9 @@ export async function agentCommand(scenarioArg, options = {}) {
             sessionConfig,
             experimental,
         });
+        if (auth === "subscription") {
+            say("mnemom agent: auth = subscription — Claude Code would use your claude.ai login (Team/Enterprise plans only) with a Mnemom API key; no Anthropic key, terminal-only.");
+        }
         if (expNotice)
             say(expNotice);
         if (previewShape === "remote-control") {
@@ -193,10 +205,10 @@ export async function agentCommand(scenarioArg, options = {}) {
         cli = await promptForCliPath(options.cli, env, cliError);
     }
     // ── resolve the Anthropic key (zero 1Password; never logged) ──
-    const anthropicKey = await resolveAnthropicKey(env, {
-        allowPrompt: true,
-        keySource: options.keySource,
-    });
+    // Not on a subscription launch: Claude Code then sends its own claude.ai login instead.
+    const anthropicKey = auth === "api-key"
+        ? await resolveAnthropicKey(env, { allowPrompt: true, keySource: options.keySource })
+        : undefined;
     // ── account + µ-balance gate (no free tier) ─────────────────────────────────
     // mnemom agent runs governed and on µ, so before we seal a contract or launch we
     // (1) ensure a Mnemom session — offering the try-me-style sign-in / sign-up when
@@ -245,6 +257,14 @@ export async function agentCommand(scenarioArg, options = {}) {
         rcCapable: rc.ok,
         say,
     });
+    // Subscription login: terminal-only for now, and the governed identity anchors on a
+    // Mnemom API key (minted once and stored if there is none). Resolved after sign-in so
+    // minting can use the session.
+    let mnemomKey;
+    if (auth === "subscription") {
+        shape = subscriptionShape(shape, shapeExplicit, say);
+        mnemomKey = await resolveSubscriptionMnemomKey(defaultMnemomKeyDeps());
+    }
     // Now that a session exists, a defaulted slug uses the real login handle from
     // /v1/auth/me (the stored token has no email, so the pre-sign-in value was the
     // "agent-user" fallback). Only when the caller didn't name an agent. Under an
@@ -261,7 +281,12 @@ export async function agentCommand(scenarioArg, options = {}) {
     // provisions-with-confirm when interactive; warns and continues otherwise.
     // Skipped entirely by `--no-setup`. A provisioning failure never blocks the
     // launch — it degrades to the unclaimed (fail-open) identity with a warning.
-    if (options.setup !== false) {
+    if (options.setup !== false && !anthropicKey) {
+        // Subscription login: the gateway creates the agent in the Mnemom key's org on the first
+        // turn, so there is nothing to birth or claim here.
+        say(`mnemom agent: subscription login — '${agent}' is created in your org on the first turn (identity: your Mnemom API key).`);
+    }
+    else if (options.setup !== false && anthropicKey) {
         try {
             await ensureGovernedAgent({
                 slug: agent,
@@ -343,11 +368,13 @@ export async function agentCommand(scenarioArg, options = {}) {
             say(fmt.warn(`mnemom agent: context handoff could not be registered (${err instanceof Error ? err.message : String(err)}) — launching without the handoff tool.`));
         }
     }
-    if (shape === "terminal") {
+    // A subscription launch (no Anthropic key) is always terminal — see subscriptionShape.
+    if (shape === "terminal" || !anthropicKey) {
         launchTerminal({
             cli,
             door,
             anthropicKey,
+            mnemomKey,
             agent,
             scenario,
             conversationId,
@@ -425,6 +452,25 @@ export async function recordSessionLaunch(ctx) {
 // ───────────────────────────────────────────────────────────────────────────
 // Credential resolution (zero 1Password)
 // ───────────────────────────────────────────────────────────────────────────
+/** The real I/O behind a subscription launch's Mnemom key (lib/subscription-login.ts). */
+export function defaultMnemomKeyDeps(storePath = CODE_STORE) {
+    return {
+        env: process.env,
+        readStored: () => {
+            try {
+                const data = JSON.parse(readFileSync(storePath, "utf8"));
+                const v = data[MNEMOM_KEY_STORE_FIELD];
+                return typeof v === "string" ? stripCrlf(v) : undefined;
+            }
+            catch {
+                return undefined;
+            }
+        },
+        mint: async () => (await createApiKey(`mnemom-agent ${hostname()}`, ["gateway"])).key,
+        store: (key) => mergeStore({ [MNEMOM_KEY_STORE_FIELD]: key }, storePath),
+        say,
+    };
+}
 /**
  * Resolve the Anthropic key with NO 1Password dependency (built for external
  * customer adoption), in order:
@@ -660,6 +706,7 @@ function launchTerminal(ctx) {
     warnAdapter(ctx.cli);
     const headers = buildCustomHeaders({
         anthropicKey: ctx.anthropicKey,
+        mnemomKey: ctx.mnemomKey,
         agent: ctx.agent,
         conversationId: ctx.conversationId,
         contractB64: ctx.envelope?.base64,
@@ -675,11 +722,20 @@ function launchTerminal(ctx) {
     // Claude Code logged in via claude.ai (OAuth) PREEMPTS ANTHROPIC_API_KEY, so
     // it is force-unset; the real key rides in ANTHROPIC_CUSTOM_HEADERS and
     // ANTHROPIC_AUTH_TOKEN is a fixed non-secret placeholder.
-    const childEnv = { ...process.env };
-    delete childEnv.ANTHROPIC_API_KEY;
-    childEnv.ANTHROPIC_BASE_URL = ctx.door;
-    childEnv.ANTHROPIC_AUTH_TOKEN = "mnemom-gateway";
-    childEnv.ANTHROPIC_CUSTOM_HEADERS = headers;
+    //
+    // A subscription launch (no Anthropic key) sets NO auth token: Claude Code then sends its
+    // own claude.ai login to the gateway (lib/subscription-login.ts).
+    let childEnv;
+    if (ctx.anthropicKey) {
+        childEnv = { ...process.env };
+        delete childEnv.ANTHROPIC_API_KEY;
+        childEnv.ANTHROPIC_BASE_URL = ctx.door;
+        childEnv.ANTHROPIC_AUTH_TOKEN = "mnemom-gateway";
+        childEnv.ANTHROPIC_CUSTOM_HEADERS = headers;
+    }
+    else {
+        childEnv = subscriptionChildEnv(process.env, ctx.door, headers);
+    }
     const sessionName = passthroughName(ctx.options.passthrough ?? []) ?? sessionDisplayName(ctx.agent, ctx.scenario);
     childEnv[SESSION_NAME_ENV] = sessionName;
     if (ctx.options.slack)

package/dist/index.js

@@ -142,6 +142,7 @@ const agentCmd = program
     .option("--gateway <url>", "Gateway host override — must be the same cell as the rest of the CLI (default: that cell's gateway; or MNEMOM_AGENT_GATEWAY)")
     .option("--remote-control", "Interactive Remote Control session in THIS terminal (behind a local proxy)")
     .option("--server", "Headless `claude remote-control` dispatcher (behind a local proxy)")
+    .option("--auth <mode>", "How Claude Code authenticates: api-key (default) | subscription (your Claude Team/Enterprise login; terminal-only)")
     .option("--model <alias|id>", "Model to launch (CLI alias or concrete id)")
     .addOption(new Option("--effort <level>", "Reasoning effort").choices([
     "low",
@@ -278,6 +279,7 @@ const agentCmd = program
             conversationId: opts.conversationId,
             cli: opts.cli,
             remoteControl: opts.remoteControl,
+            auth: opts.auth,
             server: opts.server,
             model: opts.model ?? cfg.model,
             effort: opts.effort ?? cfg.effort,

package/dist/lib/agent.d.ts

@@ -283,7 +283,10 @@ export declare function resolveRemoteControlShape(args: {
  * callers must place it only in the child's env, never in a log line.
  */
 export declare function buildCustomHeaders(opts: {
-    anthropicKey: string;
+    /** Absent on a subscription-login launch: Claude Code then sends its own claude.ai login. */
+    anthropicKey?: string;
+    /** The governed-identity anchor on a subscription-login launch (lib/subscription-login.ts). */
+    mnemomKey?: string;
     agent: string;
     conversationId: string;
     contractB64?: string;

package/dist/lib/agent.js

@@ -466,7 +466,8 @@ export function resolveRemoteControlShape(args) {
  */
 export function buildCustomHeaders(opts) {
     const lines = [
-        `x-api-key: ${opts.anthropicKey}`,
+        ...(opts.anthropicKey ? [`x-api-key: ${opts.anthropicKey}`] : []),
+        ...(opts.mnemomKey ? [`x-mnemom-api-key: ${opts.mnemomKey}`] : []),
         `x-mnemom-agent: ${opts.agent}`,
         `x-mnemom-conversation-id: ${opts.conversationId}`,
     ];

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

@@ -15,6 +15,7 @@
  * 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 AgentAuth } from "./subscription-login.js";
 import type { ExperimentalId } from "./experimental.js";
 import { type ContextProfile, type GoalModeDefault, type LaunchShape } from "./agent.js";
 /** The human-editable settings file. Secret key lives elsewhere (launcher.json). */
@@ -29,6 +30,8 @@ export interface LauncherConfig {
     effort?: string;
     cli?: string;
     launch?: LaunchShape;
+    /** How Claude Code authenticates (lib/subscription-login.ts); api-key when unset. */
+    auth?: AgentAuth;
     keySource?: KeySource;
     /** Standing goal-alignment default when neither --goal nor --implicit is given. */
     goalMode?: GoalModeDefault;

package/dist/lib/launcher-config.js

@@ -15,6 +15,7 @@
  * 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 { AGENT_AUTH_ENV, AGENT_AUTHS, coerceAgentAuth, } from "./subscription-login.js";
 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";
@@ -132,6 +133,14 @@ export const CONFIG_KEYS = [
             c.launch = coerceLaunch(v);
         },
     },
+    {
+        key: "auth",
+        describe: `How Claude Code authenticates (${AGENT_AUTHS.join("|")}); subscription = your Claude Team/Enterprise login, terminal-only`,
+        get: (c) => c.auth,
+        set: (c, v) => {
+            c.auth = coerceAgentAuth(v);
+        },
+    },
     {
         key: "key_source",
         describe: `Where to source the Anthropic key (${KEY_SOURCES.join("|")})`,
@@ -258,6 +267,8 @@ export function parseLauncherConfig(text) {
         cfg.cli = coerceNonEmpty("cli", str(raw.cli) ?? "");
     if (raw.launch !== undefined)
         cfg.launch = coerceLaunch(str(raw.launch) ?? "");
+    if (raw.auth !== undefined)
+        cfg.auth = coerceAgentAuth(str(raw.auth) ?? "");
     if (raw.key_source !== undefined)
         cfg.keySource = coerceKeySource(str(raw.key_source) ?? "");
     if (raw.goal_mode !== undefined)
@@ -330,6 +341,8 @@ export function serializeLauncherConfig(cfg) {
         doc.cli = cfg.cli;
     if (cfg.launch !== undefined)
         doc.launch = cfg.launch;
+    if (cfg.auth !== undefined)
+        doc.auth = cfg.auth;
     if (cfg.keySource !== undefined)
         doc.key_source = cfg.keySource;
     if (cfg.goalMode !== undefined)
@@ -392,6 +405,9 @@ export function applyConfigToEnv(cfg, env = process.env) {
         env.MNEMOM_AGENT_REMOTE_CONTROL =
             cfg.launch === "server" ? "server" : cfg.launch === "remote-control" ? "1" : "0";
     }
+    if (cfg.auth && !(env[AGENT_AUTH_ENV] ?? "").trim()) {
+        env[AGENT_AUTH_ENV] = cfg.auth;
+    }
     if (cfg.context !== undefined && !(env.MNEMOM_AGENT_CONTEXT ?? "").trim()) {
         env.MNEMOM_AGENT_CONTEXT = cfg.context ? "1" : "0";
     }

package/dist/lib/subscription-login.d.ts

@@ -0,0 +1,53 @@
+/**
+ * `mnemom agent` with a Claude subscription login (`auth = subscription`) — Team and
+ * Enterprise plans only; the gateway checks the plan with Anthropic and refuses anything
+ * else (gateway/src/subscription-auth.ts).
+ *
+ * Claude Code then authenticates to the gateway with its own claude.ai OAuth login: the
+ * launch sets ANTHROPIC_BASE_URL and leaves ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN unset,
+ * so Claude Code sends `Authorization: Bearer <its login>`. No Anthropic key is involved.
+ * The gateway anchors the governed identity on a Mnemom API key instead
+ * (`x-mnemom-api-key`), which this module resolves — env, then the 0600 store, then a
+ * freshly minted gateway-only key — and the agent is created in that key's org on the
+ * first turn, so there is no CLI-side birth or claim.
+ *
+ * v1 is terminal-only: the Remote Control proxy rewrites the OAuth bearer away by design,
+ * and the context-handoff tool authenticates with an Anthropic key.
+ *
+ * Pure apart from the injected deps, so every arm is unit-tested.
+ */
+import type { LaunchShape } from "./agent.js";
+export type AgentAuth = "api-key" | "subscription";
+export declare const AGENT_AUTHS: readonly AgentAuth[];
+/** Env override for the setting (the launcher.toml `auth` key folds into it). */
+export declare const AGENT_AUTH_ENV = "MNEMOM_AGENT_AUTH";
+/** Env override for the Mnemom key a subscription launch sends. */
+export declare const MNEMOM_KEY_ENV = "MNEMOM_AGENT_MNEMOM_KEY";
+/** Field in ~/.mnemom/launcher.json (0600) holding the minted key. */
+export declare const MNEMOM_KEY_STORE_FIELD = "mnemom_api_key";
+export declare function coerceAgentAuth(raw: string): AgentAuth;
+/** `--auth` flag > MNEMOM_AGENT_AUTH (launcher.toml folds in here) > api-key. */
+export declare function resolveAgentAuth(flag: string | undefined, env: Record<string, string | undefined>): AgentAuth;
+export interface MnemomKeyDeps {
+    env: Record<string, string | undefined>;
+    readStored(): string | undefined;
+    /** Mint a gateway-only personal key for this machine; returns the secret. */
+    mint(): Promise<string>;
+    store(key: string): void;
+    say(line: string): void;
+}
+/**
+ * The Mnemom key a subscription launch sends: MNEMOM_AGENT_MNEMOM_KEY, else the stored
+ * key, else mint one (gateway scope only) and store it. The key is never printed.
+ */
+export declare function resolveSubscriptionMnemomKey(deps: MnemomKeyDeps): Promise<string>;
+/**
+ * Subscription login is terminal-only in v1. An explicit Remote Control / server request
+ * is refused; an automatic upgrade to Remote Control falls back to terminal with a notice.
+ */
+export declare function subscriptionShape(shape: LaunchShape, shapeExplicit: boolean, say: (line: string) => void): LaunchShape;
+/**
+ * The child env for a subscription launch: the gateway door, the Mnemom headers, and
+ * NOTHING that would make Claude Code send a key instead of its claude.ai login.
+ */
+export declare function subscriptionChildEnv(base: NodeJS.ProcessEnv, door: string, headers: string): NodeJS.ProcessEnv;

package/dist/lib/subscription-login.js

@@ -0,0 +1,103 @@
+/**
+ * `mnemom agent` with a Claude subscription login (`auth = subscription`) — Team and
+ * Enterprise plans only; the gateway checks the plan with Anthropic and refuses anything
+ * else (gateway/src/subscription-auth.ts).
+ *
+ * Claude Code then authenticates to the gateway with its own claude.ai OAuth login: the
+ * launch sets ANTHROPIC_BASE_URL and leaves ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN unset,
+ * so Claude Code sends `Authorization: Bearer <its login>`. No Anthropic key is involved.
+ * The gateway anchors the governed identity on a Mnemom API key instead
+ * (`x-mnemom-api-key`), which this module resolves — env, then the 0600 store, then a
+ * freshly minted gateway-only key — and the agent is created in that key's org on the
+ * first turn, so there is no CLI-side birth or claim.
+ *
+ * v1 is terminal-only: the Remote Control proxy rewrites the OAuth bearer away by design,
+ * and the context-handoff tool authenticates with an Anthropic key.
+ *
+ * Pure apart from the injected deps, so every arm is unit-tested.
+ */
+export const AGENT_AUTHS = ["api-key", "subscription"];
+/** Env override for the setting (the launcher.toml `auth` key folds into it). */
+export const AGENT_AUTH_ENV = "MNEMOM_AGENT_AUTH";
+/** Env override for the Mnemom key a subscription launch sends. */
+export const MNEMOM_KEY_ENV = "MNEMOM_AGENT_MNEMOM_KEY";
+/** Field in ~/.mnemom/launcher.json (0600) holding the minted key. */
+export const MNEMOM_KEY_STORE_FIELD = "mnemom_api_key";
+/**
+ * The key is spliced into the newline-joined ANTHROPIC_CUSTOM_HEADERS block, so an embedded
+ * CR/LF (a multi-line paste, a bad env value) would inject extra header lines.
+ */
+function headerSafe(raw) {
+    return raw.replace(/[\r\n]+/g, "").trim();
+}
+export function coerceAgentAuth(raw) {
+    const v = raw.trim().toLowerCase();
+    if (AGENT_AUTHS.includes(v))
+        return v;
+    throw new Error(`auth must be one of ${AGENT_AUTHS.join(", ")} (got '${raw}').`);
+}
+/** `--auth` flag > MNEMOM_AGENT_AUTH (launcher.toml folds in here) > api-key. */
+export function resolveAgentAuth(flag, env) {
+    if (flag !== undefined && flag.trim())
+        return coerceAgentAuth(flag);
+    const fromEnv = (env[AGENT_AUTH_ENV] ?? "").trim();
+    return fromEnv ? coerceAgentAuth(fromEnv) : "api-key";
+}
+/**
+ * The Mnemom key a subscription launch sends: MNEMOM_AGENT_MNEMOM_KEY, else the stored
+ * key, else mint one (gateway scope only) and store it. The key is never printed.
+ */
+export async function resolveSubscriptionMnemomKey(deps) {
+    const fromEnv = headerSafe(deps.env[MNEMOM_KEY_ENV] ?? "");
+    if (fromEnv)
+        return fromEnv;
+    const stored = headerSafe(deps.readStored() ?? "");
+    if (stored)
+        return stored;
+    let minted;
+    try {
+        minted = headerSafe(await deps.mint());
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`mnemom agent: subscription login needs a Mnemom API key and minting one failed (${msg}).\n` +
+            `  Create one with \`mnemom api-key create --name mnemom-agent --scopes gateway\` and set ${MNEMOM_KEY_ENV}.`, { cause: err });
+    }
+    if (!minted)
+        throw new Error("mnemom agent: the API returned an empty Mnemom key.");
+    try {
+        deps.store(minted);
+        deps.say("mnemom agent: minted a gateway-only Mnemom API key for subscription login (saved to ~/.mnemom/launcher.json, 0600).");
+    }
+    catch {
+        deps.say("mnemom agent: minted a gateway-only Mnemom API key for this launch but could not save it — the next launch mints another.");
+    }
+    return minted;
+}
+/**
+ * Subscription login is terminal-only in v1. An explicit Remote Control / server request
+ * is refused; an automatic upgrade to Remote Control falls back to terminal with a notice.
+ */
+export function subscriptionShape(shape, shapeExplicit, say) {
+    if (shape === "terminal")
+        return shape;
+    if (shapeExplicit) {
+        throw new Error(`mnemom agent: subscription login runs terminal-only for now — drop --${shape === "server" ? "server" : "remote-control"} (or \`mnemom agent config set launch terminal\`), or use auth = api-key.`);
+    }
+    say("mnemom agent: subscription login runs terminal-only for now — launching in this terminal.");
+    return "terminal";
+}
+/**
+ * The child env for a subscription launch: the gateway door, the Mnemom headers, and
+ * NOTHING that would make Claude Code send a key instead of its claude.ai login.
+ */
+export function subscriptionChildEnv(base, door, headers) {
+    const env = { ...base };
+    delete env.ANTHROPIC_API_KEY;
+    delete env.ANTHROPIC_AUTH_TOKEN;
+    // The key already rides in the headers; the child process has no other use for it.
+    delete env.MNEMOM_AGENT_MNEMOM_KEY;
+    env.ANTHROPIC_BASE_URL = door;
+    env.ANTHROPIC_CUSTOM_HEADERS = headers;
+    return env;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnemom/mnemom",
-  "version": "0.17.3",
+  "version": "0.17.4-next.0",
   "description": "Transparent AI agent tracing",
   "type": "module",
   "bin": {