fix(cli): pingKey distinguishes network failures from invalid keys + tests

PR review surfaced a data-loss path: pingKey returned False on ANY exception,
so a VPN flap or DNS hiccup made Rules 1/2 (reuse existing valid key) fall
through to Rule 3 (mint new shadow), silently rotating the user's API key
and rewriting plugin-sync targets (~/.claude/settings.json, .zshrc).

Now pingKey returns False ONLY on a definitive auth failure (HTTP 401/403).
Network errors, timeouts, and 5xx responses return True so the existing key
is preferred over re-minting. Mirror change in both Python and Node.

Additional fixes from the same review pass:

  - --agent-caller is now PATCHed to the backend when supplied on a Rule 1
    or Rule 2 reuse path (previously silently dropped). Best-effort —
    failures don't break reuse.

  - bootstrap_via_backend / bootstrapViaBackend renames the `body` local on
    the error path to `err_body` (no longer shadows the request payload).
    Same rename in the claim flow.

  - Bootstrap envelope is now validated for non-empty api_key +
    default_user_id before mutation — defends against partial backend
    responses silently persisting null/undefined into typed string fields.

  - Stale docstrings in agent_detect.{py,ts} and bootstrap_via_backend no
    longer claim env-var sniffing fills `agent_caller`; the field is
    self-declared via --agent-caller only.

Tests (new file mirrored across runtimes):

  - test_init_internals.py / init-internals.test.ts
  - pingKey: 200/401/403/5xx/connect-error/timeout matrix
  - plugin_sync.updateShellRc: trailing-newline preservation, no-create,
    surrounding-content preservation, idempotency, missing-file no-op
  - plugin_sync.updateClaudeSettings: no env-block creation, no
    MEM0_API_KEY insertion into existing env, idempotency, malformed JSON
    no-op
  - Python only: bootstrap 403 "permission" → daily-limit translation

Python: 161 tests pass. Node: 112 tests pass. ruff + biome clean.

cli/node/src/agent-detect.ts

@@ -1,11 +1,14 @@
 /**
- * Detect which AI agent is invoking the CLI via environment variables.
+ * Detect whether the CLI is being invoked from inside an AI-agent context.
  *
- * Used by `mem0 init` to:
- *   1. Decide whether to auto-bootstrap an Agent Mode key (positive agent signal).
- *   2. Tag the `agent_caller` PostHog property on the cli.init event.
+ * Used by `mem0 init` to auto-enter Agent Mode (Rule 3 bootstrap) when an
+ * agent runtime env var is present. The return value is a context **trigger
+ * only** — the canonical agent identity is self-declared by the agent via
+ * `--agent-caller <name>` (Proof Editor-style) and never sniffed from env
+ * vars to fill the `agent_caller` field on the APIKey row.
  *
- * Returns a canonical short name or null when no agent is detected.
+ * Returns a short name or null. Honest reporting depends on `--agent-caller`;
+ * this list is just enough to enable the zero-friction auto-bootstrap UX.
  */
 
 const AGENT_CALLER_ENV: ReadonlyArray<readonly [string, readonly string[]]> = [

cli/node/src/commands/agent-mode.ts

@@ -24,6 +24,28 @@ export interface BootstrapEnvelope {
 	mem0_notice?: string;
 }
 
+function isValidEnvelope(v: unknown): v is BootstrapEnvelope {
+	return (
+		!!v &&
+		typeof v === "object" &&
+		typeof (v as BootstrapEnvelope).api_key === "string" &&
+		(v as BootstrapEnvelope).api_key.length > 0 &&
+		typeof (v as BootstrapEnvelope).default_user_id === "string" &&
+		(v as BootstrapEnvelope).default_user_id.length > 0
+	);
+}
+
+/**
+ * POST /api/v1/auth/agent_mode/ and mutate config in place.
+ *
+ * @param config - Mem0Config mutated in place with the new platform values.
+ * @param source - `--source` flag passthrough (analytics tag, free-form).
+ * @param agentCaller - Self-declared agent identity passed via `--agent-caller`
+ *   (e.g. `claude-code`, `cursor`). May be null when the caller omitted the
+ *   flag; the agent can backfill later via `mem0 identify <name>`. Sent to the
+ *   backend in the request body and saved into `platform.agentCaller` for
+ *   local introspection.
+ */
 export async function bootstrapViaBackend(
 	config: Mem0Config,
 	{
@@ -68,8 +90,11 @@ export async function bootstrapViaBackend(
 	if (!resp.ok) {
 		let detail: string = resp.statusText;
 		try {
-			const body = (await resp.json()) as { error?: string; detail?: string };
-			detail = body.error ?? body.detail ?? resp.statusText;
+			const errBody = (await resp.json()) as {
+				error?: string;
+				detail?: string;
+			};
+			detail = errBody.error ?? errBody.detail ?? resp.statusText;
 		} catch {
 			/* leave detail as statusText */
 		}
@@ -88,6 +113,15 @@ export async function bootstrapViaBackend(
 	}
 
 	const envelope = (await resp.json()) as BootstrapEnvelope;
+	if (!isValidEnvelope(envelope)) {
+		// Defend against partial/malformed backend responses (e.g. {api_key: null}).
+		// Without this guard, the typed `string` field is silently set to
+		// undefined/null and persisted, producing confusing downstream errors.
+		printError(
+			"Bootstrap response missing required fields — please update the CLI.",
+		);
+		process.exit(1);
+	}
 
 	config.platform.apiKey = envelope.api_key;
 	config.platform.baseUrl = baseUrl;
@@ -219,17 +253,17 @@ export async function claimViaOtp(
 		process.exit(1);
 	}
 
-	const body = (await verifyResp.json()) as {
+	const claimBody = (await verifyResp.json()) as {
 		claimed?: boolean;
 		claimed_at?: string;
 	};
-	if (!body.claimed) {
-		printError(`Unexpected verify response: ${JSON.stringify(body)}`);
+	if (!claimBody.claimed) {
+		printError(`Unexpected verify response: ${JSON.stringify(claimBody)}`);
 		process.exit(1);
 	}
 
 	config.platform.agentMode = false;
-	config.platform.claimedAt = body.claimed_at ?? new Date().toISOString();
+	config.platform.claimedAt = claimBody.claimed_at ?? new Date().toISOString();
 	config.platform.userEmail = email;
 	config.platform.createdVia = "email";
 	saveConfig(config);

cli/node/src/commands/init.ts

@@ -35,19 +35,62 @@ function validateEmail(email: string): void {
 	}
 }
 
-async function pingKey(
+/** @internal — exported for unit tests. */
+export async function pingKey(
 	apiKey: string,
 	baseUrl: string,
 	timeoutMs = 5000,
 ): Promise<boolean> {
+	// Returns false ONLY on a definitive "invalid key" signal (HTTP 401/403).
+	// Network errors, timeouts, and 5xx responses return true so we prefer
+	// reusing an existing key over silently minting a new shadow on a transient
+	// blip (which would also clobber config + plugin-sync targets).
 	try {
 		const resp = await fetch(`${baseUrl.replace(/\/+$/, "")}/v1/ping/`, {
 			headers: { Authorization: `Token ${apiKey}` },
 			signal: AbortSignal.timeout(timeoutMs),
 		});
-		return resp.status === 200;
+		return resp.status !== 401 && resp.status !== 403;
 	} catch {
-		return false;
+		return true; // unknown — prefer reuse
+	}
+}
+
+async function maybeIdentify(
+	key: string,
+	baseUrl: string,
+	agentCaller: string | undefined,
+): Promise<void> {
+	// Best-effort PATCH agent_caller when --agent-caller is supplied on a
+	// reused key. Silent no-op on any failure — reuse must not break.
+	if (!agentCaller) return;
+	try {
+		const resp = await fetch(
+			`${baseUrl.replace(/\/+$/, "")}/api/v1/auth/agent_mode/caller/`,
+			{
+				method: "PATCH",
+				headers: {
+					Authorization: `Token ${key}`,
+					"Content-Type": "application/json",
+				},
+				body: JSON.stringify({ agent_caller: agentCaller }),
+				signal: AbortSignal.timeout(10_000),
+			},
+		);
+		if (resp.ok) {
+			try {
+				const body = (await resp.json()) as { agent_caller?: string };
+				if (fs.existsSync(CONFIG_FILE)) {
+					const cfg = loadConfig();
+					cfg.platform.agentCaller = body.agent_caller ?? agentCaller;
+					saveConfig(cfg);
+				}
+			} catch {
+				/* swallow — best effort */
+			}
+		}
+	} catch {
+		/* swallow — best effort */
 	}
 }
 
@@ -354,6 +397,7 @@ export async function runInit(
 		// Rule 1: env MEM0_API_KEY valid → reuse, no new key.
 		const envKey = (process.env.MEM0_API_KEY || "").trim();
 		if (envKey && (await pingKey(envKey, baseUrl))) {
+			await maybeIdentify(envKey, baseUrl, opts.agentCaller);
 			emitReuseEnvelope("env");
 			fireInit("existing_key");
 			return;
@@ -363,6 +407,11 @@ export async function runInit(
 			savedConfig.platform.apiKey &&
 			(await pingKey(savedConfig.platform.apiKey, baseUrl))
 		) {
+			await maybeIdentify(
+				savedConfig.platform.apiKey,
+				baseUrl,
+				opts.agentCaller,
+			);
 			emitReuseEnvelope("config");
 			fireInit("existing_key");
 			return;

cli/node/src/plugin-sync.ts

@@ -49,7 +49,11 @@ export function syncApiKey(apiKey: string): string[] {
 	return updated;
 }
 
-function updateClaudeSettings(filePath: string, apiKey: string): boolean {
+/** @internal — exported for unit tests; consumers should use {@link syncApiKey}. */
+export function updateClaudeSettings(
+	filePath: string,
+	apiKey: string,
+): boolean {
 	if (!fs.existsSync(filePath)) return false;
 	let raw: string;
 	let data: Record<string, unknown>;
@@ -70,7 +74,8 @@ function updateClaudeSettings(filePath: string, apiKey: string): boolean {
 	return true;
 }
 
-function updateShellRc(filePath: string, apiKey: string): boolean {
+/** @internal — exported for unit tests; consumers should use {@link syncApiKey}. */
+export function updateShellRc(filePath: string, apiKey: string): boolean {
 	if (!fs.existsSync(filePath)) return false;
 	let text: string;
 	try {