@mnemom/mnemom 0.17.9-next.0 → 0.17.10

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

@@ -6,22 +6,24 @@
  * governed identity `agent-<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. The CARDS are
- * observe-only (visibility, no active intervention); the goal contract is what
- * nudges (re-anchor on drift). Specifically:
- *   - alignment card: autonomy_mode + integrity_mode = observe,
+ * OFF by default (operator 2026-10-02: alignment and protection analysis are
+ * billed, so nobody pays for them until they turn them on); the goal contract is
+ * what nudges (re-anchor on drift). Specifically:
+ *   - alignment card: autonomy_mode + integrity_mode = off,
  *     principal.relationship = delegated_authority, coding bounded/forbidden
  *     actions, escalate-on-irreversible;
- *   - protection card: mode = observe, thresholds 0.60/0.80/0.95, all four
- *     screen_surfaces on (screened for observation).
+ *   - protection card: mode = off, thresholds 0.60/0.80/0.95 and all four
+ *     screen_surfaces declared, ready for when it is turned on.
  *   - goal-alignment: nudge — sealed per-conversation via the goal contract
  *     (--goal …), graded and re-anchored by the gateway.
  *
- * 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.
+ * A launch never runs on an unclaimed agent (operator 2026-10-03): an unclaimed agent lands in
+ * the sandbox org and bills nobody. ensureClaimedServedAgent asks the gateway which agent it
+ * serves for this launch's credential + name, claims it into the org the launch bills when it
+ * is not claimed yet, and refuses otherwise — interactive or not, there is no unclaimed
+ * fallback. Reuses the existing machinery — birthThroughGateway (wrap.ts), deriveHashProof
+ * (agents.ts), claimAgent + putAlignmentCard/putProtectionCard (lib/api.ts) — rather than
+ * reinventing it.
  */
 import { type CodeEntitlement } from "../lib/api.js";
 /**
@@ -47,58 +49,75 @@ export declare function resolveDefaultSlug(opts?: {
     strict?: boolean;
 }): Promise<string>;
 /**
- * Thrown when a name-matched agent in the caller's org is NOT the agent the
- * gateway serves for (credential, name). Both ids are in the message; the
- * launcher treats it as fatal on an explicit `--setup` (MNE-7650).
+ * `mnemom agent` refuses to launch: the agent the gateway would serve is not claimed and could
+ * not be claimed here (or could not be identified at all). An unclaimed agent lands in the
+ * sandbox org and bills nobody, so there is no fallback — the message says what to do.
  */
-export declare class AgentIdentityMismatchError extends Error {
-    readonly slug: string;
-    /** The agent the org lookup found by name. */
-    readonly namedId: string;
-    /** The agent the gateway answered with on x-mnemom-agent. */
-    readonly servedId: string;
-    constructor(slug: string, 
-    /** The agent the org lookup found by name. */
-    namedId: string, 
-    /** The agent the gateway answered with on x-mnemom-agent. */
-    servedId: string);
+export declare class UnclaimedAgentError extends Error {
+    constructor(message: string);
 }
-export interface EnsureAgentOptions {
+export interface ClaimedAgentOptions {
     /** 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). */
+    /** Anthropic-key launch: the key that anchors the gateway identity. Never logged. */
+    anthropicKey?: string;
+    /** Subscription launch: the Mnemom API key that anchors the gateway identity. Never logged. */
+    mnemomKey?: string;
+    /** Gateway host the launch targets (the probe goes to the same cell). */
     gatewayHost: string;
-    /** Override interactivity (defaults to isInteractive()). */
-    interactive?: boolean;
+    /**
+     * The org this launch bills — the one ensureSessionAndBalance resolved and checked the µ of.
+     * A claim lands here. The active/default org is never changed.
+     */
+    orgId: string;
+    orgLabel: string;
+    /** true = --setup (re-ask the gateway, refresh the cards); false = --no-setup (no card writes). */
+    setup?: boolean;
     /** Where the served-agent cache lives (defaults to ~/.mnemom). */
     cacheDir?: string;
 }
 /** A bare launch never waits on the served-agent probe longer than this. */
 export declare const SERVED_PROBE_TIMEOUT_MS = 10000;
-export interface EnsureAgentResult {
+/**
+ * The waits between the tries of a call that failed transiently (network, timeout, 429, 5xx):
+ * three tries, about four seconds of backoff. Exported so tests can zero it.
+ */
+export declare const CONFIRM_RETRY_DELAYS_MS: number[];
+export interface ClaimedAgentResult {
     slug: string;
-    /** true only when this call actually birthed/claimed/published. */
-    provisioned: boolean;
-    /**
-     * The mnm- id the gateway serves for (key, slug), when this call learned it (a verified name
-     * match, a mismatch, or a fresh birth). Absent when it never asked the gateway.
-     */
-    agentId?: string;
+    /** The mnm- id the gateway serves for (credential, slug) — claimed when this returns. */
+    agentId: string;
+    /** true only when this call claimed it. */
+    claimedNow: 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 agent
- * setup`) or a warn-and-continue (a bare launch).
+ * A failure worth retrying, and that an outage fallback may cover: no answer at all (network,
+ * timeout, an unparseable reply) or a 408/429/5xx. A 4xx, a missing route, or a refusal is a
+ * definite answer.
+ */
+export declare function isTransient(err: unknown): boolean;
+/**
+ * The one invariant behind every `mnemom agent` launch: the coding CLI never starts unless the
+ * agent the gateway serves for THIS launch's credential + name is claimed.
+ *
+ * 1. Ask which agent the gateway serves (an Anthropic-key launch: the birth probe, cached per
+ *    key + name + gateway; a subscription launch: the gateway's identity route).
+ * 2. Read its claim state. Claimed ⇒ launch, and never claim it again: a re-claim by its owner
+ *    MOVES it to the requested org.
+ * 3. Unclaimed ⇒ claim it into `orgId` with the hash proof of the key that anchors it. Another
+ *    account owns it ⇒ refuse; any other claim failure ⇒ refuse.
+ *
+ * A definite answer (unclaimed and can't be claimed, owned by another account, the identity
+ * route missing, a rejected key) always refuses. A transient failure is retried; if Mnemom still
+ * can't be reached, the launch uses the agent this machine last confirmed claimed for the same
+ * credential + name — and only when the gateway hasn't since named a different one — or
+ * refuses. There is deliberately no switch that launches unclaimed (operator ruling 2026-10-03).
+ *
+ * Interactive and non-interactive runs behave the same: there is no prompt to decline.
+ * MNE-7650: the name is client-controlled, so a same-named org agent proves nothing — only the
+ * served id counts.
  */
-export declare function ensureGovernedAgent(opts: EnsureAgentOptions): Promise<EnsureAgentResult>;
+export declare function ensureClaimedServedAgent(opts: ClaimedAgentOptions): Promise<ClaimedAgentResult>;
 /**
  * One line for an api failure that keeps the parts an operator can act on: the
  * message, the error code, and the scope the endpoint said it needed