@mnemom/mnemom 0.17.0 → 0.17.1

package/dist/commands/agent-doctor.js

@@ -164,6 +164,9 @@ export async function probeCodeAccess() {
         return {
             mark: "ok",
             text: `Mnemom Agent access: enabled for ${orgLabel} (${sourceLabel(ent.source)})`,
+            hint: ent.remote_control
+                ? undefined
+                : "Remote Control (steer from claude.ai / the Claude app) is an internal feature — your sessions run terminal-only",
         };
     }
     catch (err) {

package/dist/commands/agent-invite.d.ts

@@ -41,7 +41,7 @@ export declare function isCodeNotEnabled(err: unknown): err is MnemomApiError;
  * guidance + throws CodeNotEnabledError) ONLY on a determined `code_not_enabled`;
  * every other failure is inconclusive and fails open with a dim note.
  */
-export declare function assertCodeEnabled(orgId: string, orgLabel: string): Promise<void>;
+export declare function assertCodeEnabled(orgId: string, orgLabel: string): Promise<CodeEntitlement | null>;
 /** Ensures a Mnemom session exists (injected so tests never touch the real login flow). */
 export type EnsureSession = (opts: {
     interactive?: boolean;

package/dist/commands/agent-invite.js

@@ -85,7 +85,7 @@ function printNotEnabled(orgLabel, hint) {
  */
 export async function assertCodeEnabled(orgId, orgLabel) {
     try {
-        await getCodeEntitlement(orgId);
+        return await getCodeEntitlement(orgId);
     }
     catch (err) {
         if (isCodeNotEnabled(err)) {
@@ -93,6 +93,9 @@ export async function assertCodeEnabled(orgId, orgLabel) {
             throw new CodeNotEnabledError(orgLabel);
         }
         say(fmt.dim(`  (Could not verify Mnemom Agent access — ${err instanceof Error ? err.message : String(err)}. Continuing.)`));
+        // Inconclusive (network / 5xx / membership 403) → fail open on access, but
+        // the null entitlement fails CLOSED on Remote Control at the call site.
+        return null;
     }
 }
 async function defaultEnsureSession(opts) {

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

@@ -23,6 +23,7 @@
  * birthThroughGateway (wrap.ts), deriveHashProof (agents.ts), claimAgent +
  * putAlignmentCard/putProtectionCard (lib/api.ts) — rather than reinventing it.
  */
+import { type CodeEntitlement } from "../lib/api.js";
 /**
  * The default governed-agent slug for the current customer: `agent-<handle>`,
  * where <handle> is the local-part of their mnemom login email (sanitised), or
@@ -112,4 +113,5 @@ export declare function ensureSessionAndBalance(opts: {
 }): Promise<{
     orgId: string;
     orgLabel: string;
+    entitlement: CodeEntitlement | null;
 }>;

package/dist/commands/agent-setup.js

@@ -379,9 +379,9 @@ export async function ensureSessionAndBalance(opts) {
     const orgLabel = active ? `${active.name} (${active.slug})` : "your personal org";
     // Invited-cohort gate FIRST: an org that is not enabled for Mnemom Agent gets
     // the invite guidance, not a top-up message (the µ check would be moot).
-    await assertCodeEnabled(orgId, orgLabel);
+    const entitlement = await assertCodeEnabled(orgId, orgLabel);
     await assertMuBalance(orgId, orgLabel);
-    return { orgId, orgLabel };
+    return { orgId, orgLabel, entitlement };
 }
 // ── The default coding posture (cards observe-only; goal contracts nudge) ────
 function buildCodeAlignmentCard(agentId) {

package/dist/commands/agent.js

@@ -38,7 +38,7 @@ import { fmt } from "../lib/format.js";
 import { askInput, askSelect, askYesNo, isInteractive } from "../lib/prompt.js";
 import { goalAlignmentLine, resolveSessionSetup } from "./agent-session.js";
 import { defaultAgentSlug, ensureGovernedAgent, ensureSessionAndBalance, isQuietPreambleExit, resolveDefaultSlug, } from "./agent-setup.js";
-import { assembleContract, buildGoalModeHeader, buildCustomHeaders, isProdGateway, launchPreferenceExplicit, resolveAnthropicDoor, resolveConversationId, resolveGatewayHost, resolveLaunchShape, sanitizeAgentName, } from "../lib/agent.js";
+import { assembleContract, buildGoalModeHeader, buildCustomHeaders, isProdGateway, launchPreferenceExplicit, remoteControlAllowed, resolveAnthropicDoor, resolveConversationId, resolveGatewayHost, resolveLaunchShape, resolveRemoteControlShape, sanitizeAgentName, } from "../lib/agent.js";
 /** The CLI's own provider-key store (zero 1Password): ~/.mnemom/launcher.json, 0600. */
 const CODE_STORE = join(MNEMOM_DIR, "launcher.json");
 const say = (line = "") => console.error(line);
@@ -106,33 +106,26 @@ export async function agentCommand(scenarioArg, options = {}) {
     catch (err) {
         cliError = err instanceof Error ? err : new Error(String(err));
     }
-    // Default launch shape: prefer Remote-Control-in-terminal (the good default —
-    // one session steerable from this terminal AND claude.ai/the app) when the
-    // machine can do it; otherwise terminal-only with a clear notice. An explicit
-    // choice (flag / env / config launch=) is always respected. Needs a resolved
-    // CLI to test RC capability, so it's applied once the CLI is known.
-    const applyAutoShape = (resolved) => {
-        if (shapeExplicit || shape !== "terminal")
-            return;
-        const rc = checkRcCapability(resolved);
-        if (rc.ok) {
-            shape = "remote-control";
-        }
-        else {
-            say(`mnemom agent: launching terminal-only (Remote Control unavailable: ${rc.missing.join("; ")}).`);
-            say("mnemom agent: once those are in place, `mnemom agent <scenario> --remote-control` (or `config set launch remote-control`) gives you a session steerable from claude.ai and the Claude app too.");
-        }
-    };
-    if (cli)
-        applyAutoShape(cli);
+    // NB: the launch SHAPE (terminal vs Remote Control) is resolved in two steps.
+    // Remote Control is an INTERNAL Mnemom capability, so the auto-upgrade and any
+    // explicit `--remote-control`/`--server` are gated on the org's entitlement —
+    // which we only know AFTER sign-in. The entitlement-aware decision
+    // (`resolveRemoteControlShape`) happens below, right after
+    // `ensureSessionAndBalance`. --dry-run prints the plan BEFORE sign-in, so it
+    // can't know the entitlement; it previews the shape the MACHINE is capable of
+    // (as the pre-gate behaviour did), then notes that the real launch applies the
+    // entitlement gate. `shape` itself stays the requested (ungated) shape.
     if (options.dryRun) {
         const planCli = cli ?? {
             bin: "(not found — pass --cli <path> or `mnemom agent config set cli <path>`)",
             name: basename((options.cli || env.MNEMOM_AGENT_CLI || "claude").trim()),
         };
+        const previewShape = !shapeExplicit && shape === "terminal" && cli && checkRcCapability(cli).ok
+            ? "remote-control"
+            : shape;
         printPlan({
             scenario,
-            shape,
+            shape: previewShape,
             agent,
             conversationId,
             door,
@@ -142,6 +135,9 @@ export async function agentCommand(scenarioArg, options = {}) {
             yolo,
             cli: planCli,
         });
+        if (previewShape === "remote-control") {
+            say("mnemom agent: the plan shows Remote Control because this machine can run it; the real launch uses it only if your account is entitled (internal Mnemom accounts), else terminal-only.");
+        }
         return;
     }
     // Real launch: make sure we actually have a CLI to run. If we couldn't find it,
@@ -149,7 +145,6 @@ export async function agentCommand(scenarioArg, options = {}) {
     // non-interactive session still gets the clear, actionable error.
     if (!cli) {
         cli = await promptForCliPath(options.cli, env, cliError);
-        applyAutoShape(cli);
     }
     // ── resolve the Anthropic key (zero 1Password; never logged) ──
     const anthropicKey = await resolveAnthropicKey(env, {
@@ -171,6 +166,30 @@ export async function agentCommand(scenarioArg, options = {}) {
             process.exit(1); // guidance already printed
         throw err;
     }
+    // ── Remote-Control entitlement gate ─────────────────────────────────────────
+    // Remote Control (a session steerable from claude.ai / the Claude app) is
+    // internal-only. Now that we know the org's entitlement, resolve the final
+    // shape: auto-upgrade only for an allowed account on a capable machine, and
+    // degrade an explicit RC/server request from a non-allowed account to
+    // terminal-only with a notice. FAIL-CLOSED — a null entitlement (gate failed
+    // open) or an api without the field yields no Remote Control.
+    const rcAllowed = remoteControlAllowed(account.entitlement);
+    const rc = checkRcCapability(cli);
+    // Preserve the "how to turn Remote Control on" guidance for an allowed account
+    // whose machine can't do it yet and who didn't pin a shape (the old
+    // applyAutoShape behaviour). Non-allowed accounts never see it — RC isn't
+    // theirs — resolveRemoteControlShape gives them the internal-only notice.
+    if (rcAllowed && !shapeExplicit && shape === "terminal" && !rc.ok) {
+        say(`mnemom agent: launching terminal-only (Remote Control unavailable: ${rc.missing.join("; ")}).`);
+        say("mnemom agent: once those are in place, `mnemom agent <scenario> --remote-control` (or `config set launch remote-control`) gives you a session steerable from claude.ai and the Claude app too.");
+    }
+    shape = resolveRemoteControlShape({
+        shape,
+        shapeExplicit,
+        rcAllowed,
+        rcCapable: rc.ok,
+        say,
+    });
     // 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.

package/dist/lib/agent.d.ts

@@ -156,6 +156,39 @@ export declare function launchPreferenceExplicit(opts: {
     remoteControl?: boolean;
     server?: boolean;
 }, env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Is this account allowed to use Remote Control (a session steerable from
+ * claude.ai and the Claude app)? Remote Control is an INTERNAL Mnemom capability
+ * — only the internal cohort (@mnemom.ai) and platform staff get it; invited
+ * customers run terminal-only. The server decides and returns `remote_control`
+ * on `GET /v1/code/entitlement`; this reads that flag, FAIL-CLOSED: a `null`
+ * entitlement (the gate failed open / no session) or an absent field (an older
+ * api that predates this flag) both mean "not allowed".
+ */
+export declare function remoteControlAllowed(entitlement: {
+    remote_control?: boolean;
+} | null | undefined): boolean;
+/**
+ * Final launch shape after applying the Remote-Control entitlement. Pure: the
+ * machine-capability probe is passed in as `rcCapable`, and narration goes
+ * through the injected `say`.
+ *
+ *   - Not allowed + a requested RC/server shape (explicit flag, env, or
+ *     config)  → degrade to `terminal` with a one-line notice. The CLI can't
+ *     block a binary the user owns, but it won't route them through Remote
+ *     Control by default.
+ *   - Not allowed + terminal            → terminal (nothing to say).
+ *   - Allowed + terminal + not pinned   → AUTO-upgrade to `remote-control` when
+ *     the machine can do it (the zero-friction default), else terminal.
+ *   - Allowed + an explicit RC/server shape → kept as-is.
+ */
+export declare function resolveRemoteControlShape(args: {
+    shape: LaunchShape;
+    shapeExplicit: boolean;
+    rcAllowed: boolean;
+    rcCapable: boolean;
+    say?: (line?: string) => void;
+}): LaunchShape;
 /**
  * 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

package/dist/lib/agent.js

@@ -291,6 +291,49 @@ export function launchPreferenceExplicit(opts, env = process.env) {
         return true;
     return (env.MNEMOM_AGENT_REMOTE_CONTROL ?? "").trim() !== "";
 }
+/**
+ * Is this account allowed to use Remote Control (a session steerable from
+ * claude.ai and the Claude app)? Remote Control is an INTERNAL Mnemom capability
+ * — only the internal cohort (@mnemom.ai) and platform staff get it; invited
+ * customers run terminal-only. The server decides and returns `remote_control`
+ * on `GET /v1/code/entitlement`; this reads that flag, FAIL-CLOSED: a `null`
+ * entitlement (the gate failed open / no session) or an absent field (an older
+ * api that predates this flag) both mean "not allowed".
+ */
+export function remoteControlAllowed(entitlement) {
+    return entitlement?.remote_control === true;
+}
+/**
+ * Final launch shape after applying the Remote-Control entitlement. Pure: the
+ * machine-capability probe is passed in as `rcCapable`, and narration goes
+ * through the injected `say`.
+ *
+ *   - Not allowed + a requested RC/server shape (explicit flag, env, or
+ *     config)  → degrade to `terminal` with a one-line notice. The CLI can't
+ *     block a binary the user owns, but it won't route them through Remote
+ *     Control by default.
+ *   - Not allowed + terminal            → terminal (nothing to say).
+ *   - Allowed + terminal + not pinned   → AUTO-upgrade to `remote-control` when
+ *     the machine can do it (the zero-friction default), else terminal.
+ *   - Allowed + an explicit RC/server shape → kept as-is.
+ */
+export function resolveRemoteControlShape(args) {
+    const emit = args.say ?? (() => { });
+    if (!args.rcAllowed) {
+        if (args.shape !== "terminal") {
+            emit("mnemom agent: Remote Control is an internal Mnemom feature — launching terminal-only.");
+        }
+        return "terminal";
+    }
+    // Allowed. Only auto-upgrade a non-pinned terminal shape, and only when the
+    // machine can do it. When it can't, stay terminal silently — the caller owns
+    // the detailed "why unavailable / how to enable" narration (it has the
+    // RcCapability with the specific missing pieces).
+    if (args.shape === "terminal" && !args.shapeExplicit) {
+        return args.rcCapable ? "remote-control" : "terminal";
+    }
+    return args.shape;
+}
 /**
  * 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

package/dist/lib/api.d.ts

@@ -1209,6 +1209,13 @@ export interface CodeEntitlement {
     org_id: string;
     enabled: true;
     source: "internal_cohort" | "staff" | "invitation";
+    /**
+     * May this account use Remote Control (a session steerable from claude.ai and
+     * the Claude app)? Internal cohort + staff only; invited customers run
+     * terminal-only. OPTIONAL for fail-closed back-compat: an older api that
+     * predates the flag omits it, and absent is treated as `false`.
+     */
+    remote_control?: boolean;
 }
 /** The machine-readable code on the gate's 403 when the org is not enabled. */
 export declare const CODE_NOT_ENABLED = "code_not_enabled";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnemom/mnemom",
-  "version": "0.17.0",
+  "version": "0.17.1",
   "description": "Transparent AI agent tracing",
   "type": "module",
   "bin": {