@mnemom/mnemom 0.14.5 → 0.14.6

package/dist/commands/agents.js

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { listAgents, listOrgAgents, listMyOrgs, getAgentByName, claimAgent, MnemomApiError, } from "../lib/api.js";
+import { listAgents, listOrgAgents, listMyOrgs, getAgent, getAgentByName, claimAgent, MnemomApiError, } from "../lib/api.js";
 import { requireAuth } from "../lib/auth.js";
 import { fmt } from "../lib/format.js";
 export async function agentsListCommand(options = {}) {
@@ -152,6 +152,15 @@ export async function agentsClaimCommand(idOrName, options = {}) {
             return;
         }
     }
+    else if (!derivationName && options.key && !options.hashProof) {
+        // ID given, no --name, --key will be used for proof derivation: try to
+        // auto-resolve the agent's provisioned name so `claim <id> --key <k>`
+        // works on the first try without requiring an explicit --name.
+        const found = await getAgent(idOrName).catch(() => null);
+        if (found?.name) {
+            derivationName = found.name;
+        }
+    }
     // 2. Establish the hash proof: --hash-proof (raw) takes precedence, else
     //    derive from --key. Exactly one source is needed.
     let hashProof;
@@ -242,6 +251,22 @@ export async function agentsClaimCommand(idOrName, options = {}) {
             process.exit(1);
             return;
         }
+        if (err instanceof MnemomApiError &&
+            err.effectiveStatus === 403 &&
+            (err.code === "invalid_hash_proof" || /hash[ _]?proof/i.test(err.message))) {
+            // The proof derived from --key (and the agent's name) didn't match the
+            // agent's stored proof. Name the real cause instead of the bare "Invalid
+            // hash proof": verify the key, and let the user supply the name when it
+            // couldn't be auto-resolved from the id. Ordered AFTER the not-a-member
+            // 403 (also a 403, distinguished by isNotAMemberError) so it doesn't
+            // shadow the org-teaching path.
+            console.log(fmt.error("Failed to claim agent: the --key (and agent name) didn't match the agent's stored proof (invalid hash proof)."));
+            console.log(fmt.dim(`  Confirm --key is the exact provider key the agent runs with.\n` +
+                `  If the name couldn't be auto-resolved from the id, pass it explicitly:\n` +
+                `    mnemom agents claim ${agentId} --key <key> --name <provisioned-name>`) + "\n");
+            process.exit(1);
+            return;
+        }
         const msg = err instanceof Error ? err.message : String(err);
         console.log(fmt.error(`Failed to claim agent: ${msg}`) + "\n");
         process.exit(1);

package/dist/commands/auth.js

@@ -5,14 +5,23 @@ export async function loginCommand(options = {}) {
     try {
         let tokens;
         if (options.noBrowser) {
+            // Non-interactive hint: when stdin is piped, credentials are read as two
+            // lines (email, then password). If either is missing we fail loudly with
+            // a non-zero exit and never touch the stored session (MNE-269).
+            const piped = !process.stdin.isTTY;
+            const pipeHint = "Pipe credentials as two lines: printf 'EMAIL\\nPASSWORD\\n' | mnemom login --no-browser";
             const email = await askInput("Email:");
             if (!email) {
                 console.log(fmt.error("Email is required."));
+                if (piped)
+                    console.log(fmt.error(`No email received on stdin. ${pipeHint}`));
                 process.exit(1);
             }
             const password = await askInput("Password:", true);
             if (!password) {
                 console.log(fmt.error("Password is required."));
+                if (piped)
+                    console.log(fmt.error(`No password received on stdin. ${pipeHint}`));
                 process.exit(1);
             }
             tokens = await loginWithPassword(email, password);

package/dist/commands/integrity.js

@@ -1,5 +1,6 @@
 import { resolveAgentId, getIntegrity, MnemomApiError } from "../lib/api.js";
 import { fmt } from "../lib/format.js";
+import { TRACES_PENDING_NOTE } from "../lib/onboarding.js";
 export async function integrityCommand(agentName) {
     const agentId = await resolveAgentId(agentName);
     console.log("\nFetching agent activity...\n");
@@ -18,7 +19,8 @@ export async function integrityCommand(agentName) {
             console.log("\n" + fmt.warn("You have integrity violations. Run `mnemom logs` to investigate.") + "\n");
         }
         else if (integrity.total_traces === 0) {
-            console.log("\nNo traces recorded yet. Start using Claude to build your integrity score.\n");
+            console.log("\nNo traces recorded yet. Start using Claude to build your integrity score.");
+            console.log("\n" + fmt.dim(TRACES_PENDING_NOTE) + "\n");
         }
         else {
             console.log("\n" + fmt.success("Your agent has a clean integrity record!") + "\n");
@@ -35,7 +37,8 @@ export async function integrityCommand(agentName) {
             console.log(`  ${fmt.label("Total:     ", "0 traces")}`);
             console.log(`  ${fmt.label("Verified:  ", "0")}`);
             console.log(`  ${fmt.label("Violations:", " 0")}`);
-            console.log("\nNo traces recorded yet. Start using Claude to build your integrity score.\n");
+            console.log("\nNo traces recorded yet. Start using Claude to build your integrity score.");
+            console.log("\n" + fmt.dim(TRACES_PENDING_NOTE) + "\n");
         }
         else {
             const message = error instanceof Error ? error.message : String(error);

package/dist/commands/logs.js

@@ -1,6 +1,7 @@
 import { resolveAgentId, getTraces, MnemomApiError, } from "../lib/api.js";
 import { getGatewayUrl, getWebsiteUrl } from "../lib/config.js";
 import { fmt } from "../lib/format.js";
+import { TRACES_PENDING_NOTE, gatewayIntegrationHelp } from "../lib/onboarding.js";
 export async function logsCommand(options = {}) {
     const agentId = await resolveAgentId(options.agentName);
     const gatewayUrl = getGatewayUrl();
@@ -10,9 +11,8 @@ export async function logsCommand(options = {}) {
         const traces = await getTraces(agentId, limit);
         if (traces.length === 0) {
             console.log(fmt.header("No traces found"));
-            console.log("\nStart using Claude to generate traces.\n");
-            console.log("Make sure ANTHROPIC_BASE_URL is set correctly:\n");
-            console.log(`  export ANTHROPIC_BASE_URL="${gatewayUrl}/v1/proxy/${agentId}"\n`);
+            console.log("\n" + TRACES_PENDING_NOTE + "\n");
+            console.log(gatewayIntegrationHelp(gatewayUrl, options.agentName) + "\n");
             return;
         }
         console.log(fmt.header(`Recent Traces (${traces.length})`));
@@ -29,7 +29,8 @@ export async function logsCommand(options = {}) {
         // effectiveStatus surfaces the true status (=== status when documented).
         if (error instanceof MnemomApiError && error.effectiveStatus === 404) {
             console.log(fmt.header("No traces found"));
-            console.log("\nStart using Claude to generate traces.\n");
+            console.log("\n" + TRACES_PENDING_NOTE + "\n");
+            console.log(gatewayIntegrationHelp(gatewayUrl, options.agentName) + "\n");
         }
         else {
             const message = error instanceof Error ? error.message : String(error);
@@ -51,8 +52,15 @@ function displayTrace(trace) {
     // shape); fall back to the action type, then a dash.
     const actionLabel = trace.action?.name ?? trace.action?.type ?? "—";
     console.log(`  ${fmt.label("Action:", ` ${actionLabel}`)}`);
+    // A pure-LLM inference turn carries category "escalation_trigger" on the wire
+    // (it is the *point at which* an escalation could fire, not a turn that demanded
+    // one). Rendering that raw reads as if every benign turn escalated, so present a
+    // friendly label instead. Presentation-only — the underlying category is unchanged.
     if (trace.action?.category) {
-        console.log(`  ${fmt.label("Type:  ", ` ${trace.action.category}`)}`);
+        const categoryLabel = trace.action.category === "escalation_trigger" && trace.action.name === "inference"
+            ? "inference (no tool)"
+            : trace.action.category;
+        console.log(`  ${fmt.label("Type:  ", ` ${categoryLabel}`)}`);
     }
     const reasoning = trace.decision?.selection_reasoning;
     if (reasoning) {

package/dist/commands/status.js

@@ -2,6 +2,7 @@ import { getGatewayUrl, getWebsiteUrl } from "../lib/config.js";
 import { resolveAgentId, getAgent, getIntegrity, getTraces, MnemomApiError } from "../lib/api.js";
 import { isLoggedIn, getAuthInfo } from "../lib/auth.js";
 import { fmt } from "../lib/format.js";
+import { TRACES_PENDING_NOTE } from "../lib/onboarding.js";
 export async function statusCommand(agentName) {
     console.log(fmt.header("mnemom status"));
     console.log();
@@ -195,6 +196,8 @@ async function showTraceSummary(agentId) {
         }
         else {
             console.log("\nLast Activity:   None");
+            // Eventual consistency: don't let a just-sent request read as "broken".
+            console.log("\n" + fmt.dim(TRACES_PENDING_NOTE));
         }
     }
     catch {

package/dist/index.js

@@ -322,7 +322,7 @@ agentsCmd
     .option("--org <slug>", "Org slug or id to claim into (default: your personal org)")
     .option("--key <key>", "The agent's provider API key — the CLI derives the hash proof from it")
     .option("--hash-proof <hex>", "A pre-computed 64-hex SHA-256 proof (advanced/CI; alternative to --key)")
-    .option("--name <name>", "Provisioned agent name used in proof derivation (defaults to a name-shaped positional arg)")
+    .option("--name <name>", "Provisioned agent name for proof derivation — auto-resolved from the agent id when possible; pass only to override")
     .option("--json", "Output JSON instead of human-readable text")
     .action(async (idOrName, opts) => {
     try {

package/dist/lib/onboarding.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Shared first-run / onboarding copy for the CLI's empty states.
+ *
+ * Centralised so the gateway-integration instructions and the trace-ingestion
+ * note stay identical across `logs`, `status`, and `integrity`, and stay in
+ * lockstep with the canonical gateway quickstart
+ * (docs.mnemom.ai/quickstart/gateway).
+ */
+/**
+ * Traces are eventually-consistent: they're processed asynchronously and take
+ * a short while to land. Surfacing this turns a bare "0 traces" — which reads
+ * as a broken pipeline right after a successful call — into an expected,
+ * temporary state (MNE-270).
+ */
+export declare const TRACES_PENDING_NOTE: string;
+/**
+ * Canonical gateway integration instructions (MNE-268).
+ *
+ * Mirrors the quickstart: point the provider client at the gateway's
+ * `/anthropic` base URL and name the agent with the `x-mnemom-agent` header.
+ * The previously-printed `/v1/proxy/<id>` base-URL form is NOT a real gateway
+ * route — the gateway only serves `/anthropic/*`, `/openai/*`, `/gemini/*` and
+ * resolves the agent from the `x-mnemom-agent` header (which is a name, not an
+ * id). `agentName` is the customer-chosen agent name; we fall back to a
+ * placeholder rather than printing the resolved `mnm-` id, which would be the
+ * wrong value for that header.
+ */
+export declare function gatewayIntegrationHelp(gatewayUrl: string, agentName?: string): string;

package/dist/lib/onboarding.js

@@ -0,0 +1,35 @@
+/**
+ * Shared first-run / onboarding copy for the CLI's empty states.
+ *
+ * Centralised so the gateway-integration instructions and the trace-ingestion
+ * note stay identical across `logs`, `status`, and `integrity`, and stay in
+ * lockstep with the canonical gateway quickstart
+ * (docs.mnemom.ai/quickstart/gateway).
+ */
+/**
+ * Traces are eventually-consistent: they're processed asynchronously and take
+ * a short while to land. Surfacing this turns a bare "0 traces" — which reads
+ * as a broken pipeline right after a successful call — into an expected,
+ * temporary state (MNE-270).
+ */
+export const TRACES_PENDING_NOTE = "Traces are processed asynchronously and can take a minute or two to appear.\n" +
+    "If you just made a request, wait a moment and run this again.";
+/**
+ * Canonical gateway integration instructions (MNE-268).
+ *
+ * Mirrors the quickstart: point the provider client at the gateway's
+ * `/anthropic` base URL and name the agent with the `x-mnemom-agent` header.
+ * The previously-printed `/v1/proxy/<id>` base-URL form is NOT a real gateway
+ * route — the gateway only serves `/anthropic/*`, `/openai/*`, `/gemini/*` and
+ * resolves the agent from the `x-mnemom-agent` header (which is a name, not an
+ * id). `agentName` is the customer-chosen agent name; we fall back to a
+ * placeholder rather than printing the resolved `mnm-` id, which would be the
+ * wrong value for that header.
+ */
+export function gatewayIntegrationHelp(gatewayUrl, agentName) {
+    const label = agentName ?? "<your-agent-name>";
+    return ("Route requests through the gateway and name your agent with a header:\n\n" +
+        `  ANTHROPIC_BASE_URL="${gatewayUrl}/anthropic"\n` +
+        `  header  x-mnemom-agent: ${label}\n\n` +
+        "Quickstart: https://docs.mnemom.ai/quickstart/gateway");
+}

package/dist/lib/prompt.d.ts

@@ -5,9 +5,11 @@
  * @returns Promise<boolean> - true for yes, false for no
  */
 export declare function askYesNo(question: string, defaultYes?: boolean): Promise<boolean>;
+/** Test-only: reset the cached piped-stdin reader between cases. */
+export declare function __resetPipedStdinForTests(): void;
 /**
  * Prompt for a single line of text input.
- * If mask is true, input is hidden (for API keys).
+ * If mask is true, input is hidden (for API keys / passwords).
  */
 export declare function askInput(question: string, mask?: boolean): Promise<string>;
 /**

package/dist/lib/prompt.js

@@ -32,11 +32,57 @@ export async function askYesNo(question, defaultYes = true) {
         });
     });
 }
+// ----------------------------------------------------------------------------
+// Non-interactive (piped / scripted / CI) stdin.
+//
+// When stdin is NOT a TTY, prompts must read sequential lines from a SINGLE
+// shared reader. Creating a fresh `readline.createInterface` per prompt — as
+// askInput did historically — silently drops buffered input on a pipe: the
+// first interface reads all currently-available bytes into its internal
+// buffer, emits the first line, then discards the rest on close, so the next
+// prompt sees EOF and resolves empty. That made `mnemom login --no-browser`
+// with a piped password silently fail (MNE-269): the email read fine, the
+// password came back empty, and login looked like it had asked but got
+// nothing. We read every line of stdin once, then hand them out in order. On
+// EOF (no more lines) callers get "" and can fail loudly instead of hanging.
+let pipedStdinLines = null;
+let pipedStdinPromise = null;
+function readPipedStdinLines() {
+    if (pipedStdinLines)
+        return Promise.resolve(pipedStdinLines);
+    if (!pipedStdinPromise) {
+        pipedStdinPromise = new Promise((resolve) => {
+            const lines = [];
+            const rl = readline.createInterface({ input: process.stdin });
+            rl.on("line", (line) => lines.push(line));
+            rl.on("close", () => {
+                pipedStdinLines = lines;
+                resolve(lines);
+            });
+        });
+    }
+    return pipedStdinPromise;
+}
+/** Test-only: reset the cached piped-stdin reader between cases. */
+export function __resetPipedStdinForTests() {
+    pipedStdinLines = null;
+    pipedStdinPromise = null;
+}
 /**
  * Prompt for a single line of text input.
- * If mask is true, input is hidden (for API keys).
+ * If mask is true, input is hidden (for API keys / passwords).
  */
 export async function askInput(question, mask = false) {
+    // Non-interactive stdin (pipe / CI / script): serve the next buffered line
+    // from the shared reader. Masking is meaningless on a pipe — just consume the
+    // line. On EOF this returns "" so callers can fail loudly (and never hang).
+    if (!process.stdin.isTTY) {
+        process.stdout.write(`${question} `);
+        const lines = await readPipedStdinLines();
+        const next = lines.shift();
+        process.stdout.write("\n");
+        return (next ?? "").trim();
+    }
     const rl = readline.createInterface({
         input: process.stdin,
         output: process.stdout,

package/package.json

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