aui-agent-builder 0.4.32 → 0.4.34

package/dist/services/mock-db.service.js

@@ -19,6 +19,9 @@
  * calls use the per-agent `runtimeKey`. Keys are persisted under `~/.aui/`
  * (out of the project repo).
  */
+import * as fs from "fs";
+import * as path from "path";
+import { trace } from "@opentelemetry/api";
 import { getConfig, loadProjectConfig, findProjectRoot, loadMockDbKeys, saveMockDbKeys, clearMockDbKeys, getMockDbBaseUrl, getLegacyMockDbBaseUrl, } from "../config/index.js";
 import { getAuthenticatedSession } from "./account.service.js";
 import { MockDbClient, } from "../api-client/mock-db-client.js";
@@ -28,7 +31,7 @@ import { CLIError, ConfigError } from "../errors/index.js";
  * Resolve session + `.auirc` into everything a mock-db call needs. Throws
  * clear config errors when the agent id can't be determined.
  */
-export async function resolveMockDbContext(options, opts = {}) {
+export async function resolveMockDbContext(options) {
     const session = await getAuthenticatedSession();
     const projectRoot = options.path
         ? options.path
@@ -46,15 +49,14 @@ export async function resolveMockDbContext(options, opts = {}) {
         config.organizationId ||
         session.organization_id;
     const apiUrl = session.api_url || config.apiUrl;
-    const { backend, baseUrl, deferredCommit } = await resolveMockDbBackend({
+    const { backend, baseUrl } = await resolveMockDbBackend({
         agentId,
         accountId,
         organizationId,
         apiUrl,
         authToken: session.auth_token,
         environment: session.environment,
-        auiManaged: options.auiManaged,
-        deferAuiManagedPersist: opts.deferAuiManagedPersist,
+        projectRoot,
     });
     const client = new MockDbClient({ environment: session.environment, baseUrl });
     return {
@@ -69,91 +71,180 @@ export async function resolveMockDbContext(options, opts = {}) {
         baseUrl,
         projectRoot,
         projectConfig,
-        commitBackendOnProvision: deferredCommit,
     };
 }
 /**
- * Decide which mock-db deployment an agent talks to and the base URL for it.
+ * Best-effort span event on the active `aui.mockdb.*` span. Used to make the
+ * backend decision, key recovery, and cache writes visible in Logfire with full
+ * detail. Never throws — telemetry must never break a command.
+ */
+function mockdbEvent(name, attrs) {
+    try {
+        trace.getActiveSpan()?.addEvent(name, attrs);
+    }
+    catch {
+        // telemetry is best-effort
+    }
+}
+/** Classify a mock-db execute URL by host → which backend owns the agent. */
+function classifyMockDbHost(url) {
+    if (url.includes("mock-db-service.vercel.app"))
+        return "vercel";
+    if (url.includes("/api/mock-db/") || url.includes("/api/mock-db?")) {
+        return "aui-managed";
+    }
+    return null;
+}
+/** Pull the literal runtime key out of an integration endpoint's auth header.
+ *  Handles both accepted forms (`Authorization: Bearer <key>` and
+ *  `X-API-Key: <key>`); returns undefined for templated/placeholder values. */
+function extractRuntimeKey(endpoint) {
+    const ep = endpoint;
+    const apiKey = ep?.authentication?.apiKey;
+    if (!apiKey || typeof apiKey.value !== "string")
+        return undefined;
+    const raw = apiKey.value.trim();
+    if (!raw || /\{\{.*\}\}/.test(raw))
+        return undefined; // templated → not a literal
+    const headerName = typeof apiKey.key === "string" ? apiKey.key.toLowerCase() : "";
+    const key = headerName === "authorization" ? raw.replace(/^Bearer\s+/i, "").trim() : raw;
+    return key.startsWith("mdb_run_") ? key : undefined;
+}
+/**
+ * Inspect the agent's pulled `integrations.aui.json` to determine which backend
+ * its mock DB lives on — the ground truth of what the deployed agent calls, and
+ * the ONLY signal available for a Vercel agent (Vercel has no `/status`). Also
+ * recovers the runtime key from the wired auth header when it's a literal.
  *
- * Precedence:
- *   1. `--aui-managed` — explicit opt-in; sticky (persisted), always wins.
- *   2. `AUI_MOCKDB_URL` / `AUI_TEST_BASE_URL` — a fixed host overrides routing;
- *      we keep the agent's known label but point at the override.
- *   3. Stored `backend` — the cached decision (fast path, no network).
- *   4. Legacy keys with no `backend` field — agents provisioned before this
- *      field existed are, by definition, on the legacy (Vercel) deployment.
- *   5. No local state at all — a NEW agent (or one with no mock DB yet). New
- *      mock DBs are ALWAYS created on the AUI-managed backend; the CLI never
- *      creates a new one on the legacy Vercel deployment. (An agent that already
- *      lives on Vercel keeps working via its cached backend/keys in step 4 until
- *      it is auto-migrated.) No `/status` probe is needed — an AUI-owned agent
- *      would bind here anyway, and skipping it also drops a round-trip on the
- *      very management path that degrades under load.
+ * Backend-agnostic and offline: works for an imported agent with no local cache.
+ * Returns null when there's no project, no file, or no mock-db integration.
+ */
+export function detectBackendFromIntegrations(projectRoot, agentId) {
+    if (!projectRoot)
+        return null;
+    let parsed;
+    try {
+        const file = path.join(projectRoot, "integrations.aui.json");
+        if (!fs.existsSync(file))
+            return null;
+        parsed = JSON.parse(fs.readFileSync(file, "utf-8"));
+    }
+    catch {
+        return null; // unreadable / non-JSON → no signal
+    }
+    const list = Array.isArray(parsed?.integrations)
+        ? (parsed.integrations)
+        : Array.isArray(parsed)
+            ? parsed
+            : [];
+    // Match this agent's execute URL on either backend host.
+    const execRe = new RegExp(`/api/agents/${agentId.replace(/[^a-zA-Z0-9]/g, "\\$&")}/apis/[^/]+/execute`);
+    for (const intg of list) {
+        const endpoint = intg?.settings
+            ?.endpoint;
+        const url = typeof endpoint?.url === "string" ? endpoint.url : "";
+        if (!url || !execRe.test(url))
+            continue;
+        const backend = classifyMockDbHost(url);
+        if (!backend)
+            continue;
+        return { backend, runtimeKey: extractRuntimeKey(endpoint), matchedUrl: url };
+    }
+    return null;
+}
+/**
+ * Decide which mock-db deployment an agent talks to, deterministically and
+ * WITHOUT trusting the local cache as authority. Precedence (see the
+ * mock-database-simulation skill for the full design):
  *
- * The decision is cached to `~/.aui/mockdb/<agentId>.json` so steps 3/4 cover
- * essentially every call after the first.
+ *   0. `AUI_MOCKDB_URL` / `AUI_TEST_BASE_URL` — a fixed override host wins
+ *      (manual override / flow-test collapse); keep the cached label if any.
+ *   1. AUI `/status` (token auth) — authoritative owner-check for the
+ *      AUI-managed backend. `exists && hasData === true` → AUI-managed. A
+ *      blank/unreachable `/status` is treated as "unknown" (never a negative)
+ *      and falls through.
+ *   2. `integrations.aui.json` — the ground truth of what the deployed agent
+ *      actually calls, and the ONLY Vercel detector (Vercel has no `/status`).
+ *      A vercel.app host → Vercel; a `/api/mock-db` gateway host → AUI-managed.
+ *      The wired runtime key is recovered here too.
+ *   3. Nothing owns it and nothing is wired → a NEW agent → AUI-managed
+ *      (provision creates it there; we never create a new DB on Vercel).
  *
- * Full design / rollout notes: ../../MOCKDB_AUI_MANAGED_BACKEND.md
+ * The result is written back to `~/.aui/mockdb/<agentId>.json` as a fast-path
+ * memo — but it is never CONSULTED as an authority (steps 1–3 re-derive it), so
+ * a stale/wrong cache can't misroute. Parallel work on DIFFERENT agents is fully
+ * isolated (per-agent file, per-agent keys).
  */
 async function resolveMockDbBackend(args) {
-    const stored = loadMockDbKeys(args.agentId);
-    // 1. Explicit opt-in — sticky.
-    if (args.auiManaged) {
+    // 0. Fixed override host (manual override or flow-test collapse).
+    if (process.env.AUI_MOCKDB_URL || process.env.AUI_TEST_BASE_URL) {
+        const stored = loadMockDbKeys(args.agentId);
+        const backend = stored.backend ?? "aui-managed";
         const baseUrl = getMockDbBaseUrl(args.environment);
-        // `provision` defers the commit: route to AUI-managed for this call but DON'T
-        // rewrite the routing cache yet. provision commits it only after the agent is
-        // actually established there, so a blanked/failed provision can never strand
-        // the agent on a dead backend with the wrong (stale) keys.
-        if (args.deferAuiManagedPersist) {
-            return { backend: "aui-managed", baseUrl, deferredCommit: true };
+        mockdbEvent("mockdb.backend_resolved", {
+            "mockdb.resolve.method": "env_override",
+            "mockdb.backend": backend,
+            "mockdb.base_url": baseUrl,
+            "mockdb.agent_id": args.agentId,
+        });
+        return { backend, baseUrl };
+    }
+    // 1. AUI /status — authoritative for the AUI-managed backend.
+    try {
+        const status = await fetchAuiStatus(args);
+        if (status.exists && status.hasData === true) {
+            const baseUrl = getMockDbBaseUrl(args.environment);
+            persistBackend(args.agentId, "aui-managed", baseUrl);
+            mockdbEvent("mockdb.backend_resolved", {
+                "mockdb.resolve.method": "status",
+                "mockdb.backend": "aui-managed",
+                "mockdb.base_url": baseUrl,
+                "mockdb.agent_id": args.agentId,
+            });
+            return { backend: "aui-managed", baseUrl };
         }
-        return persistBackend(args.agentId, "aui-managed", baseUrl);
     }
-    // 2. A fixed override host (manual override or flow-test collapse) — route
-    //    there without re-deriving or probing. Keep the known label if any.
-    if (process.env.AUI_MOCKDB_URL || process.env.AUI_TEST_BASE_URL) {
-        return {
-            backend: stored.backend ?? "vercel",
-            baseUrl: getMockDbBaseUrl(args.environment),
-        };
+    catch {
+        // unreachable / blank / no account → "unknown", fall through (never negative)
     }
-    // 3. Cached AUI-managed → fast path. Never re-probe, never demote (an agent on
-    //    AUI-managed is committed there; nothing migrates it back to Vercel).
-    if (stored.backend === "aui-managed") {
-        return {
-            backend: "aui-managed",
-            baseUrl: stored.mockDbUrl ?? getMockDbBaseUrl(args.environment),
-        };
+    // 2. integrations.aui.json — ground truth of the wired backend (+ runtime key).
+    const detected = detectBackendFromIntegrations(args.projectRoot, args.agentId);
+    if (detected) {
+        const baseUrl = detected.backend === "vercel"
+            ? getLegacyMockDbBaseUrl()
+            : getMockDbBaseUrl(args.environment);
+        persistBackend(args.agentId, detected.backend, baseUrl);
+        if (detected.runtimeKey) {
+            const stored = loadMockDbKeys(args.agentId);
+            if (stored.runtimeKey !== detected.runtimeKey) {
+                saveMockDbKeys(args.agentId, { runtimeKey: detected.runtimeKey });
+                mockdbEvent("mockdb.runtime_key.recovered_from_integration", {
+                    "mockdb.agent_id": args.agentId,
+                    "mockdb.runtime_key_prefix": detected.runtimeKey.slice(0, 16),
+                    "mockdb.matched_url": detected.matchedUrl,
+                });
+            }
+        }
+        mockdbEvent("mockdb.backend_resolved", {
+            "mockdb.resolve.method": "integration",
+            "mockdb.backend": detected.backend,
+            "mockdb.base_url": baseUrl,
+            "mockdb.agent_id": args.agentId,
+            "mockdb.runtime_key_recovered": !!detected.runtimeKey,
+        });
+        return { backend: detected.backend, baseUrl };
     }
-    // 4. Vercel-cached — explicit `"vercel"` OR legacy keys with no backend field.
-    //    These agents may since have been MIGRATED to AUI-managed (raw DB copy +
-    //    republished URLs). Opportunistically re-check `/status` (TTL-throttled)
-    //    and auto-switch when AUI now has the data, so users never have to clear a
-    //    stale cache by hand. Not migrated / unreachable / throttled → stay Vercel.
-    const isVercelCached = stored.backend === "vercel" || !!(stored.managementKey || stored.runtimeKey);
-    if (isVercelCached) {
-        const migrated = await maybeAutoMigrate(args, stored).catch(() => null);
-        if (migrated)
-            return migrated;
-        return persistBackend(args.agentId, "vercel", stored.mockDbUrl ?? getLegacyMockDbBaseUrl());
-    }
-    // 5. No local state → a NEW agent (or one with no mock DB yet). New mock DBs
-    //    are ALWAYS created on the AUI-managed backend now — we never create one
-    //    on the legacy Vercel deployment. (Agents already on Vercel keep working
-    //    via their cached backend/keys in step 4 until auto-migrated.)
+    // 3. Nothing owns it, nothing wired → NEW → AUI-managed.
     const baseUrl = getMockDbBaseUrl(args.environment);
-    if (args.deferAuiManagedPersist) {
-        // provision: route AUI-managed for this call but commit the routing only
-        // after provision actually establishes the agent there — same no-stranding
-        // guarantee as the explicit `--aui-managed` path (step 1).
-        return { backend: "aui-managed", baseUrl, deferredCommit: true };
-    }
-    return persistBackend(args.agentId, "aui-managed", baseUrl);
-}
-/** How long to wait before re-checking whether a Vercel-cached agent has been
- *  migrated to AUI-managed. Bounds the extra `/status` call to ~once per window
- *  per agent (not per command), on the legacy path only. */
-const MIGRATION_RECHECK_TTL_MS = 6 * 60 * 60 * 1000; // 6h
+    persistBackend(args.agentId, "aui-managed", baseUrl);
+    mockdbEvent("mockdb.backend_resolved", {
+        "mockdb.resolve.method": "new",
+        "mockdb.backend": "aui-managed",
+        "mockdb.base_url": baseUrl,
+        "mockdb.agent_id": args.agentId,
+    });
+    return { backend: "aui-managed", baseUrl };
+}
 /**
  * Read the AUI-managed `/status` for an agent (token-auth, read-only). Throws on
  * a blank body (transport blank under load) so callers treat it as "unknown"
@@ -184,60 +275,6 @@ async function fetchAuiStatus(args) {
         mgmtKeyPrefix: typeof r.mgmtKeyPrefix === "string" ? r.mgmtKeyPrefix : null,
     };
 }
-/**
- * Auto-detect a Vercel→AUI-managed migration for a Vercel-cached agent and
- * switch routing to AUI-managed, so no one has to delete a stale cache by hand.
- *
- * Safe by construction:
- *  - **TTL-throttled** via `migrationCheckedAt` — at most one extra `/status`
- *    per window per agent (and the timestamp is recorded even on a negative or
- *    failed check, so we don't re-probe every command).
- *  - **Switches only on strong evidence** (`exists && hasData === true`): never
- *    binds an empty AUI shell; a not-yet-migrated agent stays on Vercel.
- *  - **Never demotes** (only Vercel→AUI), and a blank/unreachable `/status`
- *    leaves routing unchanged.
- *  - **Key-safe**: a raw-copy migration preserves the keys (deterministic hash),
- *    so when the stored runtime key's prefix matches AUI's we KEEP the keys. If
- *    the prefixes differ (an export/replay migration minted new keys) we DROP
- *    the stale keys so management falls back to the AUI token and `execute`
- *    returns a clean "rotate-runtime-key" hint instead of a confusing 401.
- *
- * Returns the new AUI-managed routing on switch, or `null` to stay on Vercel.
- */
-async function maybeAutoMigrate(args, stored) {
-    const now = Date.now();
-    if (now - (stored.migrationCheckedAt ?? 0) < MIGRATION_RECHECK_TTL_MS) {
-        return null; // checked recently — don't re-probe on every command
-    }
-    let status = null;
-    try {
-        status = await fetchAuiStatus(args);
-    }
-    catch {
-        status = null; // unreachable / blank → leave routing unchanged
-    }
-    // Not migrated (or couldn't tell): record the check time so we throttle, stay Vercel.
-    if (!(status && status.exists === true && status.hasData === true)) {
-        saveMockDbKeys(args.agentId, { migrationCheckedAt: now });
-        return null;
-    }
-    // Migrated → switch to AUI-managed.
-    const baseUrl = getMockDbBaseUrl(args.environment);
-    const keysCarryOver = !stored.runtimeKey ||
-        !status.runtimeKeyPrefix ||
-        stored.runtimeKey.slice(0, status.runtimeKeyPrefix.length) ===
-            status.runtimeKeyPrefix;
-    if (!keysCarryOver) {
-        // Stale keys won't authenticate on the new backend — drop them cleanly.
-        clearMockDbKeys(args.agentId);
-    }
-    saveMockDbKeys(args.agentId, {
-        backend: "aui-managed",
-        mockDbUrl: baseUrl,
-        migrationCheckedAt: now,
-    });
-    return { backend: "aui-managed", baseUrl };
-}
 /** Persist the backend decision (cache) and return it. */
 function persistBackend(agentId, backend, baseUrl) {
     const stored = loadMockDbKeys(agentId);
@@ -266,40 +303,107 @@ function tokenAuth(ctx) {
     };
 }
 /**
- * Run a management call, preferring the stored per-agent management key, and
- * transparently fall back to the AUI token (Apollo-delegated) if that key is
- * rejected (401/403).
+ * Run a management call. The management key is sourced from the cache first, and
+ * a fresh one is MINTED (token-auth `rotate-mgmt-key`) + cached when the cache
+ * has none or the stored one is rejected (401/403). The AUI token is the safety
+ * net under every branch, so a missing/dead management key never fails a command
+ * (and minting that fails — e.g. an unprovisioned agent — falls back to it too).
  *
- * Why: after an auto-detected migration (Vercel→AUI-managed), a stored key may
- * not authenticate on the new backend (e.g. an export/replay migration minted
- * fresh keys). Rather than surfacing a confusing 401, we retry once with the
- * token — which always works for anyone with access to the agent's account — so
- * management keeps working seamlessly. A non-auth error is rethrown untouched.
+ * Parallel work on the SAME agent is explicitly out of scope: a concurrent mint
+ * can invalidate another caller's key, but each branch self-heals (re-mint /
+ * token fallback), so the worst case is one extra retry — never a hard failure.
  */
 async function withManage(ctx, fn) {
-    const { managementKey } = loadMockDbKeys(ctx.agentId);
-    if (!managementKey)
-        return fn(tokenAuth(ctx));
+    let managementKey = loadMockDbKeys(ctx.agentId).managementKey;
+    // 1. No cached key → mint one (+cache). If minting isn't possible, use the token.
+    if (!managementKey) {
+        managementKey = await tryMintManagementKey(ctx);
+        if (!managementKey)
+            return fn(tokenAuth(ctx));
+    }
+    // 2. Use the key; on rejection mint a fresh one (+cache) and retry once; the
+    //    token is the final safety net.
     try {
         return await fn({ mode: "mgmt", managementKey });
     }
     catch (err) {
         if (err instanceof AUIAPIError && (err.status === 401 || err.status === 403)) {
+            const fresh = await tryMintManagementKey(ctx);
+            if (fresh) {
+                try {
+                    return await fn({ mode: "mgmt", managementKey: fresh });
+                }
+                catch (err2) {
+                    if (err2 instanceof AUIAPIError &&
+                        (err2.status === 401 || err2.status === 403)) {
+                        return fn(tokenAuth(ctx));
+                    }
+                    throw err2;
+                }
+            }
             return fn(tokenAuth(ctx));
         }
         throw err;
     }
 }
-/** Runtime auth from the stored per-agent runtime key. */
+/**
+ * Mint + cache a fresh management key via the token-auth `rotate-mgmt-key` path.
+ * Returns the minted key, or `undefined` when minting isn't possible (the agent
+ * isn't provisioned yet, no account id, or the backend's mint path is failing)
+ * so callers fall back to token auth. Never throws.
+ */
+async function tryMintManagementKey(ctx) {
+    try {
+        const resp = await rotateMgmtKey(ctx); // persists the key on success
+        const key = typeof resp.managementKey === "string" ? resp.managementKey : undefined;
+        if (key) {
+            mockdbEvent("mockdb.mgmt_key.minted_and_cached", {
+                "mockdb.agent_id": ctx.agentId,
+                "mockdb.mgmt_key_prefix": key.slice(0, 16),
+            });
+        }
+        return key;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Runtime auth from the per-agent runtime key: the stored cache first, else the
+ * key recovered from the agent's wired `integrations.aui.json` (persisted back
+ * when found). Throws when neither is available — `executeEndpoint` turns that
+ * into a mint-and-retry.
+ */
 function runtimeAuth(ctx, sessionKey) {
-    const { runtimeKey } = loadMockDbKeys(ctx.agentId);
+    const runtimeKey = resolveRuntimeKey(ctx);
     if (!runtimeKey) {
-        throw new ConfigError("No runtime key stored for this agent's mock DB.", {
-            suggestion: "Run `aui mockdb provision` first — it mints and stores the runtime key.",
+        throw new ConfigError("No runtime key available for this agent's mock DB.", {
+            suggestion: "Wire the agent's mock-db integration (its auth header carries the runtime key), or run `aui mockdb rotate-runtime-key` to mint one.",
         });
     }
     return { mode: "runtime", runtimeKey, sessionKey };
 }
+/**
+ * Resolve the runtime key without minting: the stored cache first, then the
+ * literal recovered from `integrations.aui.json` (cached back when found, so the
+ * next call is a fast cache hit). Returns undefined when neither is available.
+ */
+function resolveRuntimeKey(ctx) {
+    const stored = loadMockDbKeys(ctx.agentId).runtimeKey;
+    if (stored)
+        return stored;
+    const detected = detectBackendFromIntegrations(ctx.projectRoot, ctx.agentId);
+    if (detected?.runtimeKey) {
+        saveMockDbKeys(ctx.agentId, { runtimeKey: detected.runtimeKey });
+        mockdbEvent("mockdb.runtime_key.recovered_from_integration", {
+            "mockdb.agent_id": ctx.agentId,
+            "mockdb.runtime_key_prefix": detected.runtimeKey.slice(0, 16),
+            "mockdb.matched_url": detected.matchedUrl,
+        });
+        return detected.runtimeKey;
+    }
+    return undefined;
+}
 /** A read result is "empty" only when the HTTP body was blank → `request()`
  * returned a zero-key `{}`. A real read (even of an empty DB) returns a keyed
  * object like `{ collections: [] }`, so this never flags a legitimately-empty
@@ -433,33 +537,23 @@ export async function provisionMockDb(ctx) {
     // server created anything.
     const resp = await retryWhile(isEmptyReadObject, () => ctx.client.provision(ctx.agentId, tokenAuth(ctx)));
     if (isEmptyReadObject(resp)) {
-        // Blank/failed: nothing is committed (a deferred --aui-managed selection is
-        // NOT written), so the agent stays on whatever backend it was on — never
-        // stranded on the dead one.
         throw new CLIError(`mockdb provision: the mock-db service (${ctx.backend} @ ${ctx.baseUrl}) returned HTTP 2xx but a blank body for agent ${ctx.agentId}, even after retries.`, {
             code: "API_SERVER_ERROR",
-            suggestion: "Transient backend overload (an empty 2xx body). The DB may or may not have been created — wait a moment, then run `aui mockdb status`; if it exists, mint keys with `aui mockdb rotate-runtime-key` / `rotate-mgmt-key`. Routing was NOT changed. Do NOT blindly re-provision; retry once the service is healthy.",
+            suggestion: "Transient backend overload (an empty 2xx body). The DB may or may not have been created — wait a moment, then run `aui mockdb status`; if it exists, mint keys with `aui mockdb rotate-runtime-key` / `rotate-mgmt-key`. Do NOT blindly re-provision; retry once the service is healthy.",
         });
     }
     persistReturnedKeys(ctx.agentId, resp);
-    // Commit a DEFERRED `--aui-managed` routing decision only now that provision
-    // actually ESTABLISHED the agent on AUI-managed (a fresh creation, or keys
-    // were minted/healed). A bare `created:false` with no keys (an empty
-    // pre-registered shell, often from a load-induced lazy registration) must NOT
-    // flip routing — that's the stranding bug. Such a response leaves routing
-    // unchanged and is surfaced to the user as `backendCommitted:false`.
-    if (ctx.commitBackendOnProvision) {
-        const established = resp.created === true ||
-            typeof resp.runtimeKey === "string" ||
-            typeof resp.managementKey === "string";
-        if (established) {
-            persistBackend(ctx.agentId, ctx.backend, ctx.baseUrl);
-            resp.backendCommitted = true;
-        }
-        else {
-            resp.backendCommitted = false;
-        }
-    }
+    // Cache the backend the agent was just established on as a fast-path memo.
+    // (Routing is still re-derived deterministically on later commands; this is
+    // only a hint, never consulted as authority.)
+    persistBackend(ctx.agentId, ctx.backend, ctx.baseUrl);
+    mockdbEvent("mockdb.keys.cache_saved", {
+        "mockdb.agent_id": ctx.agentId,
+        "mockdb.backend": ctx.backend,
+        "mockdb.created": resp.created === true,
+        "mockdb.runtime_key_returned": typeof resp.runtimeKey === "string",
+        "mockdb.mgmt_key_returned": typeof resp.managementKey === "string",
+    });
     return resp;
 }
 export async function describeMockDb(ctx) {
@@ -495,28 +589,82 @@ export async function createEndpoint(ctx, body) {
 export async function listEndpoints(ctx) {
     return readWithRetry(ctx, "endpoint list", () => withManage(ctx, (auth) => ctx.client.listEndpoints(ctx.agentId, auth)));
 }
+export async function getEndpoint(ctx, slug) {
+    // Idempotent read (a real endpoint returns a keyed object; a 404 throws).
+    return readWithRetry(ctx, `endpoint get ${slug}`, () => withManage(ctx, (auth) => ctx.client.getEndpoint(ctx.agentId, auth, slug)));
+}
+export async function updateEndpoint(ctx, slug, body) {
+    // A PATCH-merge is a write — never auto-retry a blank (a repeat is safe here,
+    // but a blank may mean the merge already landed; surface it honestly).
+    const resp = await withManage(ctx, (auth) => ctx.client.updateEndpoint(ctx.agentId, auth, slug, body));
+    if (isEmptyReadObject(resp))
+        blankBodyError(ctx, `endpoint update ${slug}`, "write");
+    return resp;
+}
+export async function deleteEndpoint(ctx, slug) {
+    // Delete is idempotent server-side (a second delete 404s), but a blank 2xx is
+    // ambiguous — surface it rather than returning a false success.
+    const resp = await withManage(ctx, (auth) => ctx.client.deleteEndpoint(ctx.agentId, auth, slug));
+    if (isEmptyReadObject(resp))
+        blankBodyError(ctx, `endpoint delete ${slug}`, "write");
+    return resp;
+}
+/**
+ * Mint + cache a fresh runtime key (`rotate-runtime-key`, retries a blank mint).
+ * Emits a telemetry event flagging that the deployed agent's integration must be
+ * re-wired (its `Authorization`/`X-API-Key` header) and `aui push`ed — rotating
+ * invalidates the key the live agent is using. Throws loudly if no key is minted.
+ */
+async function mintRuntimeKey(ctx, reason) {
+    const resp = await rotateRuntimeKey(ctx); // persists + loud-fails on a blank mint
+    const key = typeof resp.runtimeKey === "string" ? resp.runtimeKey : "";
+    mockdbEvent("mockdb.runtime_key.rotated", {
+        "mockdb.agent_id": ctx.agentId,
+        "mockdb.reason": reason,
+        "mockdb.runtime_key_prefix": key.slice(0, 16),
+        "mockdb.rewire_required": true,
+    });
+    return key;
+}
 export async function executeEndpoint(ctx, slug, sessionKey, body) {
+    // Ensure a runtime key exists before the first attempt: cache → integration
+    // file → mint. (The runtime plane has NO token fallback, so a key is required.)
+    if (!resolveRuntimeKey(ctx)) {
+        await mintRuntimeKey(ctx, "no runtime key available (cache + integration empty)");
+    }
     const run = () => ctx.client.execute(ctx.agentId, slug, runtimeAuth(ctx, sessionKey), body);
     // A WRITE always requires a session (the service rejects a write with no
     // session key), so an execute WITHOUT `--session` is guaranteed a read and is
     // safe to retry on a transient blank. WITH a session the endpoint could be a
     // write, so we do NOT auto-retry (a repeat could duplicate rows).
+    const attempt = () => sessionKey === undefined ? retryWhile(isEmptyReadObject, run) : run();
     let resp;
     try {
-        resp = sessionKey === undefined ? await retryWhile(isEmptyReadObject, run) : await run();
+        resp = await attempt();
     }
     catch (err) {
-        // A stale/rotated runtime key (e.g. after a migration that minted new keys)
-        // reads as 401/403 here. The runtime route only accepts the runtime key (no
-        // token fallback is possible), so surface the precise remedy instead of a
-        // confusing raw error — and never mislabel it as a transient blank.
+        // A stale/rotated runtime key reads as 401/403 here (no token fallback on the
+        // runtime plane). Self-heal: mint a fresh key (+cache) and retry once. This
+        // invalidates the key wired into the deployed agent — re-wire + push after.
         if (err instanceof AUIAPIError && (err.status === 401 || err.status === 403)) {
-            throw new CLIError(`mockdb execute ${slug}: the runtime key is invalid for agent ${ctx.agentId} on the ${ctx.backend} backend (HTTP ${err.status}).`, {
-                code: "API_CLIENT_ERROR",
-                suggestion: "The stored runtime key was rejected — it was likely rotated or replaced (e.g. by a backend migration). Mint a fresh one with `aui mockdb rotate-runtime-key`, then re-wire the agent's integration Authorization header and `aui push`.",
-            });
+            await mintRuntimeKey(ctx, `runtime key rejected (HTTP ${err.status})`);
+            try {
+                resp = await attempt();
+            }
+            catch (err2) {
+                if (err2 instanceof AUIAPIError &&
+                    (err2.status === 401 || err2.status === 403)) {
+                    throw new CLIError(`mockdb execute ${slug}: the runtime key is still invalid for agent ${ctx.agentId} on the ${ctx.backend} backend even after minting a fresh one (HTTP ${err2.status}).`, {
+                        code: "API_CLIENT_ERROR",
+                        suggestion: "Confirm the agent is provisioned on this backend with `aui mockdb status`; the backend may be rejecting freshly-minted keys (report it). After a successful rotate, re-wire the agent's integration auth header and `aui push`.",
+                    });
+                }
+                throw err2;
+            }
+        }
+        else {
+            throw err;
         }
-        throw err;
     }
     if (isEmptyReadObject(resp)) {
         blankBodyError(ctx, `execute ${slug}`, sessionKey === undefined ? "read" : "write");
@@ -637,12 +785,22 @@ function assessMockDbStatus(ctx, aui, hasLocalKeys) {
         if (aui.exists && aui.hasData === false) {
             return {
                 verdict: "empty",
-                message: `Routing to the AUI-managed backend, but the AUI service reports this record is EMPTY (no data). If you expected data it may live on the legacy Vercel backend — delete ${cacheHint} and re-run to force re-detection, then \`aui mockdb describe\`.`,
+                message: `Routing to the AUI-managed backend, but the AUI service reports this record is EMPTY (no data). If you expected data, check the agent's integrations.aui.json (its wired mock-db URL shows the real backend — the resolver uses it); otherwise the DB is simply empty/unprovisioned — seed it. (The local cache ${cacheHint} is only a memo; routing is re-derived each command, so deleting it won't change the backend.)`,
+            };
+        }
+        // AUI doesn't own it. With local keys present this is a real drift (data
+        // likely on Vercel); with NO local keys it's just an unprovisioned/new agent
+        // (new agents now default to AUI-managed, so "routes AUI-managed + AUI
+        // doesn't own it yet + no keys" simply means "not provisioned").
+        if (!hasLocalKeys) {
+            return {
+                verdict: "new",
+                message: "No mock DB found on the AUI-managed backend and no local keys for this agent — it likely has no mock DB yet. Run `aui mockdb provision` to create one (new mock DBs are created on AUI-managed). If you expected existing data, confirm the agent's `integrations.aui.json` is pulled (its wired URL reveals the backend) or run `aui mockdb describe`.",
             };
         }
         return {
             verdict: "drift",
-            message: `DRIFT: the local cache routes to AUI-managed, but the AUI service does NOT own this agent — the data is likely on the legacy Vercel backend. Delete ${cacheHint} and re-run to re-detect the correct backend (your data is not affected).`,
+            message: `DRIFT: resolved to AUI-managed, but the AUI service does NOT own this agent — the data is likely on the legacy Vercel backend. The deterministic resolver detects Vercel from the agent's integrations.aui.json (its wired mock-db URL), so make sure that file is pulled into the project — re-pull the agent if it's missing. Your data is not affected. (The local cache ${cacheHint} is only a memo; deleting it won't change routing.)`,
         };
     }
     // Vercel-bound (or defaulting to Vercel).
@@ -655,7 +813,7 @@ function assessMockDbStatus(ctx, aui, hasLocalKeys) {
     if (!hasLocalKeys) {
         return {
             verdict: "new",
-            message: `No mock DB found on the AUI-managed backend and no local keys for this agent. Either it has no mock DB yet (provision a new one with \`aui mockdb provision --aui-managed\`), OR it has one on the legacy Vercel backend whose local cache was lost (run \`aui mockdb describe\` — if it returns data it's on Vercel; re-mint keys with \`rotate-runtime-key\`/\`rotate-mgmt-key\`). Until you provision, the CLI routes to Vercel by default.`,
+            message: `No mock DB found on the AUI-managed backend and no local keys for this agent. Either it has no mock DB yet (provision a new one with \`aui mockdb provision\`), OR it has one on the legacy Vercel backend whose local cache was lost (the resolver recovers that from the agent's \`integrations.aui.json\`; or run \`aui mockdb describe\` — if it returns data it's on Vercel — and re-mint keys with \`rotate-runtime-key\`/\`rotate-mgmt-key\`).`,
         };
     }
     return {