aui-agent-builder 0.3.103 → 0.3.104

package/dist/commands/pull-agent.js

@@ -1,18 +1,20 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import * as fs from "fs";
 import * as path from "path";
-import { render } from "ink";
+import { render, Box } from "ink";
 import inquirer from "inquirer";
 import { getConfig, loadSession, loadProjectConfig, saveProjectConfig, findProjectRoot, loadAgentSettingsApiKey, saveAgentSettingsApiKey, } from "../config/index.js";
-import { AUIClient } from "../api-client/index.js";
+import { AUIClient, AUIAPIError } from "../api-client/index.js";
 import { getTracer, SpanStatusCode, setUserContext } from "../telemetry.js";
-import { AuthenticationError } from "../errors/index.js";
+import { AuthenticationError, CLIError, ConfigError } from "../errors/index.js";
 import { KBViewClient } from "../api-client/kb-view-client.js";
 import { exportToFolder, buildScope, } from "../services/kb-view.service.js";
 import { fetchSchemas } from "../services/pull-schema.service.js";
 import { initAndCommitBaseline } from "../utils/git.js";
+import { disassembleBundleToFiles, normalizeBundleFileBody, readBundleTools, } from "../utils/index.js";
 import { Header, StatusLine, Spinner, ErrorDisplay, Hint, } from "../ui/components/index.js";
 import { ImportWarnings } from "../ui/views/ImportAgentView.js";
+import { detectAgentBundleMode, isModeMismatchError, } from "./util/agent-mode.js";
 import { PullAgentView } from "../ui/views/PullAgentView.js";
 // ─── Ink Rendering Helpers ───
 function log(node) {
@@ -39,8 +41,35 @@ function startSpinner(label) {
         },
     };
 }
-// ─── Response normalizers (same as import-agent) ───
-function normalizeGeneralSettings(raw) {
+// ─── Filename routing (server bundle → local folder layout) ───
+//
+// The push/pull endpoint disallows path separators in filenames, so tool
+// files live at the root of the bundle (e.g. `web_search.aui.json`).
+// Locally we keep them under `tools/<name>.aui.json` for ergonomics —
+// every file in the response is routed to one of these two locations.
+const CANONICAL_ROOT_FILES = new Set([
+    "agent.aui.json",
+    "parameters.aui.json",
+    "entities.aui.json",
+    "integrations.aui.json",
+    "rules.aui.json",
+    "tools.aui.json",
+    "manifest.json",
+]);
+function targetPathForBundleFile(projectRoot, filename) {
+    if (CANONICAL_ROOT_FILES.has(filename)) {
+        return path.join(projectRoot, filename);
+    }
+    // Server filenames have no path separators (enforced by the endpoint),
+    // so anything that isn't a canonical root file is a per-tool blob —
+    // write under `tools/`.
+    return path.join(projectRoot, "tools", filename);
+}
+// ─── Legacy normalizers (only the old export endpoints need these) ───
+// Kept under a `Legacy` suffix to make it obvious from the call site
+// which path you're on. New-pull blob bodies are pre-shaped server-side
+// and don't need normalization.
+function normalizeGeneralSettingsLegacy(raw) {
     if (!raw)
         return null;
     if (typeof raw === "object" && !Array.isArray(raw)) {
@@ -50,7 +79,7 @@ function normalizeGeneralSettings(raw) {
     }
     return raw;
 }
-function normalizeWrapped(key, raw) {
+function normalizeWrappedLegacy(key, raw) {
     if (!raw)
         return null;
     if (Array.isArray(raw)) {
@@ -165,24 +194,69 @@ async function _pullAgent(parentSpan, options = {}) {
     // not have `agent_management_id` recorded — refresh it whenever we resolve
     // one here, regardless of whether the user passed --version.
     let resolvedAgentManagementId;
-    // Resolve the agent-management entry for this project's network_id.
+    // Captured AgentInfo from `findAgentMgmtId` — re-used by
+    // `detectAgentBundleMode` later so we don't pay a second
+    // `GET /v1/agents/{id}` round-trip just to read `bundle_mode`.
+    // `listAgents` returns full AgentInfo rows including the
+    // `bundle_mode` field, so the dispatch decision is already
+    // available from this resolver. Saves one network call per
+    // `aui pull` run and avoids the duplicate-fetch pattern.
+    let resolvedAgentInfo;
+    // Resolve the agent-management entry for this project.
+    //
+    // Priority order (top → first match wins):
+    //
+    //   1. `.auirc.agent_management_id` — the CANONICAL id `aui
+    //      import-agent` persisted on the last import. Picks the
+    //      RIGHT agent when multiple records share a `network_id`
+    //      (e.g. a bundle-mode + records-mode sibling pair). Lookup
+    //      is a single `getAgent(...)` — no list scan, no
+    //      pagination quirks. Aligns with `push.tsx:lookupAgent…`
+    //      and `version-snapshot.tsx:resolveAgentForSnapshot`.
+    //
+    //   2. `listAgents(network_id=...)` first match — back-compat
+    //      path for legacy projects without `agent_management_id`
+    //      in `.auirc` (imported pre-PR #54). Has the sibling-pick
+    //      risk; a one-time `aui import-agent` re-import promotes
+    //      the project to branch 1 on every subsequent call.
     //
-    // We use `listAgents` with the `network_id` filter (matches what
-    // `version list` does in `commands/version.tsx#resolveAgentId`). This is a
-    // single targeted lookup — listing every agent in the org and scanning is
-    // unreliable at scale (orgs with many accounts can have thousands of
-    // agents and pagination quirks miss the match) and was the cause of
-    // spurious "this agent has no version management" errors.
+    //   3. Session `agent_management_id` (if it points at this
+    //      network) — last-resort for the rare case where the
+    //      filtered list returns nothing but the session knows the
+    //      id from a previous resolve.
     //
-    // Fall back to session.agent_management_id (if it points at this network)
-    // for the rare case where the filtered list returns nothing but the
-    // session already knows the id from a previous resolve.
+    // Each branch caches the resolved AgentInfo into
+    // `resolvedAgentInfo` so `detectAgentBundleMode` reuses it
+    // and we avoid a duplicate `GET /agents/{id}` round-trip.
     const findAgentMgmtId = async () => {
+        // 1. Canonical: `.auirc.agent_management_id`
+        if (projectConfig.agent_management_id) {
+            try {
+                const agent = await client.agentManagement.getAgent(projectConfig.agent_management_id);
+                resolvedAgentManagementId = agent.id;
+                resolvedAgentInfo = agent;
+                if (!options.version && agent.active_version_id) {
+                    activeVersionId = agent.active_version_id;
+                }
+                return agent.id;
+            }
+            catch (err) {
+                // Stale id (agent deleted, scope flipped). Fall through
+                // to the network-id resolver below. Debug-log only —
+                // silent fall-through matches push.tsx's pattern for the
+                // same case.
+                if (process.env.AUI_DEBUG) {
+                    console.log(`[debug] pull.findAgentMgmtId: getAgent(${projectConfig.agent_management_id}) from .auirc failed, falling back to network_id lookup: ${err instanceof Error ? err.message : err}`);
+                }
+            }
+        }
+        // 2. Network-id listing (legacy projects + general fallback)
         try {
             const resp = await client.agentManagement.listAgents(client.getOrganizationId(), 1, 50, { network_id: networkId });
             const agentMatch = resp.items.find((a) => a.scope.network_id === networkId || a.id === networkId);
             if (agentMatch) {
                 resolvedAgentManagementId = agentMatch.id;
+                resolvedAgentInfo = agentMatch;
                 if (!options.version && agentMatch.active_version_id) {
                     activeVersionId = agentMatch.active_version_id;
                 }
@@ -192,10 +266,12 @@ async function _pullAgent(parentSpan, options = {}) {
         catch {
             // Filtered listing failed — fall through to session hint.
         }
+        // 3. Session hint
         if (session.agent_management_id && session.network_id === networkId) {
             try {
                 const agent = await client.agentManagement.getAgent(session.agent_management_id);
                 resolvedAgentManagementId = agent.id;
+                resolvedAgentInfo = agent;
                 if (!options.version && agent.active_version_id) {
                     activeVersionId = agent.active_version_id;
                 }
@@ -236,6 +312,11 @@ async function _pullAgent(parentSpan, options = {}) {
     }
     else {
         try {
+            // `findAgentMgmtId` already prefers `.auirc.agent_management_id`
+            // (its branch 1), so we get the right agent without an extra
+            // sibling-disambiguation step here. No-op when the project is
+            // legacy (no canonical id) — the function still falls through
+            // to the network-id listing.
             const agentMgmtId = await findAgentMgmtId();
             if (agentMgmtId && activeVersionId) {
                 try {
@@ -247,6 +328,45 @@ async function _pullAgent(parentSpan, options = {}) {
                 }
                 log(_jsx(StatusLine, { kind: "info", label: `Using active version: ${activeVersionLabel || activeVersionId.slice(0, 10) + "…"}` }));
             }
+            else if (agentMgmtId && projectConfig.version_id) {
+                // ─── Fallback: `.auirc.version_id` from the last import/pull
+                //
+                // `aui import-agent` persists `version_id` on every import
+                // (regular OR draft-only agents). Without this fallback, a
+                // bare `aui pull` inside a freshly-imported draft-only agent
+                // (the common case — most agents under active development
+                // have no published/activated version) would error out with
+                // "No version_id available to pull" even though the project
+                // clearly knows which version it's tracking.
+                //
+                // Hierarchy:
+                //   1. --version <id>            (explicit; handled above)
+                //   2. agent.active_version_id   (published+activated; the
+                //                                 default "what's live" the
+                //                                 user usually wants)
+                //   3. .auirc.version_id         (this branch — what they
+                //                                 originally imported / last
+                //                                 pulled from)
+                //
+                // We still resolve the version label by calling getVersion so
+                // the UX line below matches the active-version branch above.
+                try {
+                    const ver = await client.agentManagement.getVersion(agentMgmtId, projectConfig.version_id);
+                    activeVersionId = ver.id;
+                    activeVersionLabel = `v${ver.version_number}`;
+                    log(_jsx(StatusLine, { kind: "info", label: `Using project version (from .auirc): ${activeVersionLabel}` }));
+                }
+                catch (err) {
+                    // The version in .auirc no longer exists on the server
+                    // (got deleted, agent_id drift, etc.). Don't silently
+                    // promote `projectConfig.version_id` as the activeVersionId
+                    // — that would round-trip back as a 404 on /pull. Let the
+                    // `!activeVersionId` guard below fire its actionable error.
+                    if (process.env.AUI_DEBUG) {
+                        console.log(`[debug] pull: getVersion(${projectConfig.version_id}) from .auirc failed: ${err instanceof Error ? err.message : err}`);
+                    }
+                }
+            }
         }
         catch {
             // No version management available, pull latest
@@ -270,51 +390,297 @@ async function _pullAgent(parentSpan, options = {}) {
             return;
         }
     }
-    const spinner = startSpinner("Fetching agent data (7 endpoints)...");
+    // ─── Resolve the agent-management UUID for the new pull endpoint ───
+    // The new bundle endpoint is keyed on `{agent_id, version_id}` where
+    // `agent_id` is the agent-management UUID — NOT the network_id we have
+    // in `.auirc`. Re-use the same `findAgentMgmtId` resolver as version
+    // discovery: filtered listAgents → session hint → give up loud.
+    const pullAgentMgmtId = projectConfig.agent_management_id ||
+        resolvedAgentManagementId ||
+        (await findAgentMgmtId());
+    if (!pullAgentMgmtId) {
+        throw new ConfigError("Could not resolve agent-management id for this project.", {
+            suggestion: "Re-run `aui import-agent` to back-fill `.auirc.agent_management_id`, then try `aui pull` again.",
+        });
+    }
+    if (!activeVersionId) {
+        throw new ConfigError("No version_id available to pull — the new pull endpoint requires one.", {
+            suggestion: "Pass `--version <version-id>` explicitly, or re-run `aui import-agent` " +
+                "to refresh `.auirc.version_id`. If the project's `.auirc` already " +
+                "had a `version_id`, the server returned 404 for that id (the " +
+                "version may have been deleted or the agent_id changed) — verify " +
+                "with `aui agent --versions`.",
+        });
+    }
+    // ─── Mode dispatch: blob (/pull) vs records (legacy /view) ───
+    // Same dispatch as `push.tsx`. Reads `Agent.bundle_mode` on the
+    // resolved agent record and decides which API surface to use:
+    //
+    //   - `bundle_mode=true`   → call the new `/pull` endpoint below
+    //                             and write the assembled bundle inline.
+    //   - `bundle_mode=false`  → call legacy `client.exportAgent(...)`
+    //   - `bundle_mode` missing  (older backend; per-domain export +
+    //                             local bundle reconstruction).
+    //
+    // The two surfaces are mutually exclusive: a `/pull` request against
+    // a records-mode agent returns 422 mode-mismatch, and a legacy
+    // /view export against a blob-mode agent returns empty arrays for
+    // every domain (silently wrong — the worst kind of mismatch). The
+    // up-front check guarantees we go to the right surface on the
+    // first try.
+    // Pass the AgentInfo from `findAgentMgmtId` so the dispatcher
+    // doesn't re-fetch what we already have. `resolvedAgentInfo` is
+    // only populated when `findAgentMgmtId` ran (the common case);
+    // if `.auirc.agent_management_id` short-circuited the resolver,
+    // `cachedInfo` will be undefined and the dispatcher fetches it
+    // itself — same safe fallback as before, just one fewer call in
+    // the happy path.
+    const pullModeResolution = await detectAgentBundleMode(client, pullAgentMgmtId, resolvedAgentInfo);
+    parentSpan.setAttribute("pull.dispatch.mode", pullModeResolution.mode);
+    parentSpan.setAttribute("pull.dispatch.mode_source", pullModeResolution.source);
+    const useLegacyExport = pullModeResolution.mode === "records";
+    const spinner = startSpinner(useLegacyExport
+        ? "Fetching agent data (legacy /view endpoints)..."
+        : options.tag
+            ? `Pulling bundle at tag ${options.tag} (version ${activeVersionLabel || activeVersionId.slice(0, 10) + "…"})...`
+            : `Pulling bundle ${activeVersionLabel || activeVersionId.slice(0, 10) + "…"}...`);
     try {
+        // ─── New blob endpoint OR legacy /view, decided by mode above ───
+        // `useLegacyExport` was set just before the spinner. We skip the
+        // /pull call entirely for records-mode agents — calling it would
+        // return 422 mode-mismatch and cost a useless round-trip.
+        let pullData = null;
+        // `useLegacyExport` is `let`-mutable because a server-side mode
+        // flip mid-pull (rare: admin toggles `bundle_mode` while we're
+        // dispatching) can force us to switch surfaces after the initial
+        // detection. We catch the 422 mode-mismatch below and convert it
+        // into a legacy-path fall-through.
+        let useLegacyExportLocal = useLegacyExport;
+        try {
+            if (!useLegacyExportLocal) {
+                pullData = await client.agentManagement.pullVersionBlobs(pullAgentMgmtId, activeVersionId, {
+                    // Forward `--tag` so the user can pull a specific historical
+                    // revision (e.g. `v3.2`). When omitted, the server picks the
+                    // version row's current revision.
+                    versionTag: options.tag,
+                });
+            }
+        }
+        catch (err) {
+            if (isModeMismatchError(err)) {
+                // Agent's mode changed since our detectAgentBundleMode call —
+                // server says it's records-mode now. Switch surfaces and
+                // continue. Single retry, no recursion.
+                parentSpan.addEvent("pull.mode_mismatch_falling_back_to_records", {
+                    agent_management_id: pullAgentMgmtId,
+                    version_id: activeVersionId,
+                });
+                useLegacyExportLocal = true;
+            }
+            else if (err instanceof AUIAPIError && err.status === 404) {
+                // Expected when the agent has never been Pushed via the new
+                // endpoint. Falls through to the "no blob revision" error
+                // (or the records-mode legacy export, if applicable).
+                if (process.env.AUI_DEBUG) {
+                    console.log("[debug] new pull returned 404 — no blob revision for this version");
+                }
+            }
+            else if (err instanceof AUIAPIError &&
+                (err.status === 401 || err.status === 403) &&
+                !loadAgentSettingsApiKey()) {
+                spinner.warn("Authentication failed.");
+                log(_jsx(StatusLine, { kind: "warning", label: "Your access token may not have permission for the agent-settings pull endpoint." }));
+                log(_jsx(Hint, { message: "You can provide an API key as a fallback. It will be saved to ~/.aui/agent-settings-key" }));
+                const { key } = await inquirer.prompt([
+                    {
+                        type: "password",
+                        name: "key",
+                        message: "Paste the Agent Settings API key (or press Enter to abort):",
+                        mask: "*",
+                    },
+                ]);
+                if (key && key.trim()) {
+                    saveAgentSettingsApiKey(key.trim());
+                    client.setAgentSettingsApiKey(key.trim());
+                    log(_jsx(StatusLine, { kind: "success", label: "Key saved. Retrying..." }));
+                    const retrySpinner = startSpinner("Retrying pull with API key...");
+                    try {
+                        pullData = await client.agentManagement.pullVersionBlobs(pullAgentMgmtId, activeVersionId, { versionTag: options.tag });
+                        retrySpinner.stop();
+                    }
+                    catch (retryErr) {
+                        retrySpinner.stop();
+                        if (retryErr instanceof AUIAPIError &&
+                            retryErr.status === 404) {
+                            // Same strict-mode error below.
+                        }
+                        else {
+                            throw retryErr;
+                        }
+                    }
+                }
+                else {
+                    throw err;
+                }
+            }
+            else {
+                throw err;
+            }
+        }
+        // ─── Shared output variables (set by either branch) ───
         let generalSettings = {
             general_settings: { name: projectConfig.agent_code },
         };
-        let parameters = { parameters: [] };
-        let entities = { entities: [] };
-        let integrations = { integrations: [] };
-        let tools = { tools: [] };
-        let rules = { rules: [] };
-        let exportData = await client.exportAgent(networkId, networkCategoryId, activeVersionId, options.scopeLevel);
-        const hasAuthErrors = exportData.errors.some((e) => /\b(401|403)\b/.test(e) ||
-            /unauthorized|forbidden|not.*member/i.test(e));
-        if (hasAuthErrors && !loadAgentSettingsApiKey()) {
-            spinner.warn("Authentication failed for some endpoints.");
-            log(_jsx(StatusLine, { kind: "warning", label: "Your access token may not have permission for the agent-settings endpoints." }));
-            log(_jsx(Hint, { message: "You can provide an API key as a fallback. It will be saved to ~/.aui/agent-settings-key" }));
-            const { key } = await inquirer.prompt([
-                {
-                    type: "password",
-                    name: "key",
-                    message: "Paste the Agent Settings API key (or press Enter to skip):",
-                    mask: "*",
-                },
-            ]);
-            if (key && key.trim()) {
-                saveAgentSettingsApiKey(key.trim());
-                client.setAgentSettingsApiKey(key.trim());
-                log(_jsx(StatusLine, { kind: "success", label: "Key saved. Retrying..." }));
-                const retrySpinner = startSpinner("Retrying agent configuration fetch...");
-                exportData = await client.exportAgent(networkId, networkCategoryId, activeVersionId, options.scopeLevel);
-                retrySpinner.stop();
+        let paramCount = 0;
+        let entityCount = 0;
+        let integrationCount = 0;
+        let toolCount = 0;
+        let ruleCount = 0;
+        const writtenFiles = [];
+        // Revision tag from the response (e.g. "v8.14") — saved to
+        // `.auirc.version_tag` after the file write so the next `aui pull`
+        // can default to the same tag. NOT the same as `activeVersionLabel`
+        // (which stays as the major-only "v8" for telemetry / UX).
+        let resolvedVersionTag;
+        if (pullData) {
+            // ─── New bundle path: write files inline ───
+            if (pullData.version_tag) {
+                resolvedVersionTag = pullData.version_tag;
+                parentSpan.setAttribute("pull.version_tag", pullData.version_tag);
+            }
+            parentSpan.setAttribute("pull.path", "blob_endpoint");
+            const disassembled = disassembleBundleToFiles(pullData.bundle);
+            spinner.succeed(`Pulled bundle via /pull (${disassembled.length} file(s)) at ${resolvedVersionTag || activeVersionLabel || "current"}`);
+            // ─── Empty-domain warning banner ─────────────────────────────────
+            // Same rationale as `import-agent.tsx`: an empty domain in the
+            // pulled bundle is a real server-side state (not a CLI bug), but
+            // it's usually a sign the user pulled the wrong version. Surface
+            // every empty domain prominently so they can decide whether to
+            // re-pull a different version instead of being surprised by an
+            // empty `tools/` (or empty `entities`, etc.) on disk.
+            const emptyDomains = [];
+            if (!pullData.bundle.general_settings)
+                emptyDomains.push("general_settings");
+            if (!pullData.bundle.parameters || pullData.bundle.parameters.length === 0)
+                emptyDomains.push("parameters");
+            if (!pullData.bundle.entities || pullData.bundle.entities.length === 0)
+                emptyDomains.push("entities");
+            if (!pullData.bundle.integrations || pullData.bundle.integrations.length === 0)
+                emptyDomains.push("integrations");
+            if (!pullData.bundle.rules || pullData.bundle.rules.length === 0)
+                emptyDomains.push("rules");
+            // Tools live under `agent_tools` on the live `/pull` response and
+            // under `tools` per the OpenAPI schema. Either counts as "present".
+            const bundleTools = readBundleTools(pullData.bundle);
+            if (!bundleTools || bundleTools.length === 0)
+                emptyDomains.push("tools");
+            if (emptyDomains.length > 0) {
+                log(_jsxs(Box, { flexDirection: "column", paddingX: 1, marginY: 1, children: [_jsx(StatusLine, { kind: "warning", label: `Bundle at ${resolvedVersionTag || activeVersionLabel || "current"} has 0 ${emptyDomains.join(", 0 ")}.` }), _jsx(Hint, { message: "If you expected content in these domains, you may be on the wrong version. " +
+                                "Check the LIVE version in the Playground or run `aui agent --versions` to see all versions on this agent, then re-pull with `--version <id>`." })] }));
+                parentSpan.setAttribute("pull.empty_domains", emptyDomains.join(","));
+            }
+            cleanAgentFiles(projectRoot);
+            const toolsDir = path.join(projectRoot, "tools");
+            if (!fs.existsSync(toolsDir)) {
+                fs.mkdirSync(toolsDir, { recursive: true });
+            }
+            for (const entry of disassembled) {
+                const targetPath = path.join(projectRoot, entry.relativePath);
+                fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+                // Normalize before write — disassemble already produces the
+                // canonical shape, but normalize handles any edge cases the
+                // server might have stored historically (legacy
+                // wrap/unwrap drift, alternate domain-key locations) so the
+                // on-disk file always matches the spec.
+                const normalized = normalizeBundleFileBody(path.basename(entry.relativePath), entry.body);
+                writeJson(targetPath, normalized);
+                writtenFiles.push(entry.relativePath);
+                const basename = path.basename(entry.relativePath);
+                if (basename === "agent.aui.json") {
+                    generalSettings = normalized;
+                }
+                else if (basename === "parameters.aui.json") {
+                    paramCount = (normalized?.parameters || []).length;
+                }
+                else if (basename === "entities.aui.json") {
+                    entityCount = (normalized?.entities || []).length;
+                }
+                else if (basename === "integrations.aui.json") {
+                    integrationCount =
+                        (normalized?.integrations || []).length;
+                }
+                else if (basename === "rules.aui.json") {
+                    ruleCount = (normalized?.rules || []).length;
+                }
+                else if (entry.relativePath.startsWith("tools/")) {
+                    toolCount++;
+                }
+                else if (basename === "tools.aui.json") {
+                    toolCount += (normalized?.tools || []).length;
+                }
             }
         }
-        generalSettings =
-            normalizeGeneralSettings(exportData.general_settings) || generalSettings;
-        parameters =
-            normalizeWrapped("parameters", exportData.parameters) || parameters;
-        entities = normalizeWrapped("entities", exportData.entities) || entities;
-        integrations =
-            normalizeWrapped("integrations", exportData.integrations) || integrations;
-        tools = normalizeWrapped("tools", exportData.tools) || tools;
-        rules = normalizeWrapped("rules", exportData.rules) || rules;
-        if (exportData.errors.length > 0) {
-            if (parentSpan) {
+        else if (useLegacyExportLocal) {
+            // ─── Records-mode legacy export ───────────────────────────────
+            // Restored 2026-05-24 (per owner directive: "do the fallback
+            // exactly right carefully all the prev features should be
+            // available"). For agents with `bundle_mode=false` we use the
+            // per-entity /view endpoints (`parameters/view`,
+            // `scope-entities/view`, `integrations/view`, `agent-tools`,
+            // `agent-tools/rules`, `general-settings/view`) via
+            // `client.exportAgent(...)`, then reconstruct the canonical
+            // `.aui.json` layout locally. This block mirrors the legacy
+            // pull behaviour from before the blob migration — keep in
+            // sync with `import-agent.tsx`'s equivalent branch.
+            //
+            // Auth-failure handling: the legacy /view endpoints often
+            // 401/403 against an interactive session token even when the
+            // user has access via the agent-settings API key. We surface
+            // a one-time prompt for the key, save it, and retry once.
+            parentSpan.setAttribute("pull.path", "legacy_export");
+            let parameters = { parameters: [] };
+            let entities = { entities: [] };
+            let integrations = { integrations: [] };
+            let tools = { tools: [] };
+            let rules = { rules: [] };
+            let exportData = await client.exportAgent(networkId, networkCategoryId, activeVersionId, options.scopeLevel);
+            const hasAuthErrors = exportData.errors.some((e) => /\b(401|403)\b/.test(e) ||
+                /unauthorized|forbidden|not.*member/i.test(e));
+            if (hasAuthErrors && !loadAgentSettingsApiKey()) {
+                spinner.warn("Authentication failed for some endpoints.");
+                log(_jsx(StatusLine, { kind: "warning", label: "Your access token may not have permission for the agent-settings endpoints." }));
+                log(_jsx(Hint, { message: "You can provide an API key as a fallback. It will be saved to ~/.aui/agent-settings-key" }));
+                const { key } = await inquirer.prompt([
+                    {
+                        type: "password",
+                        name: "key",
+                        message: "Paste the Agent Settings API key (or press Enter to skip):",
+                        mask: "*",
+                    },
+                ]);
+                if (key && key.trim()) {
+                    saveAgentSettingsApiKey(key.trim());
+                    client.setAgentSettingsApiKey(key.trim());
+                    log(_jsx(StatusLine, { kind: "success", label: "Key saved. Retrying..." }));
+                    const retrySpinner = startSpinner("Retrying agent configuration fetch...");
+                    exportData = await client.exportAgent(networkId, networkCategoryId, activeVersionId, options.scopeLevel);
+                    retrySpinner.stop();
+                }
+            }
+            generalSettings =
+                normalizeGeneralSettingsLegacy(exportData.general_settings) ||
+                    generalSettings;
+            parameters =
+                normalizeWrappedLegacy("parameters", exportData.parameters) ||
+                    parameters;
+            entities =
+                normalizeWrappedLegacy("entities", exportData.entities) || entities;
+            integrations =
+                normalizeWrappedLegacy("integrations", exportData.integrations) ||
+                    integrations;
+            tools = normalizeWrappedLegacy("tools", exportData.tools) || tools;
+            rules = normalizeWrappedLegacy("rules", exportData.rules) || rules;
+            if (exportData.errors.length > 0) {
                 parentSpan.setStatus({
                     code: SpanStatusCode.ERROR,
                     message: exportData.errors.join("; "),
@@ -322,80 +688,126 @@ async function _pullAgent(parentSpan, options = {}) {
                 for (const e of exportData.errors) {
                     parentSpan.recordException(new Error(e));
                 }
-                parentSpan.setAttribute("pull.failed_endpoints", exportData.errors);
+                parentSpan.setAttribute("pull.failed_endpoints", exportData.errors.join(","));
+                spinner.warn(`Fetched agent configuration (${exportData.errors.length} endpoint(s) failed)`);
+                log(_jsx(ImportWarnings, { errors: exportData.errors }));
             }
-            spinner.warn(`Fetched agent configuration (${exportData.errors.length} endpoint(s) failed)`);
-            log(_jsx(ImportWarnings, { errors: exportData.errors }));
-        }
-        else {
-            spinner.succeed("Agent configuration fetched (all 6 endpoints OK)");
-        }
-        // Clean existing agent files before writing new ones
-        cleanAgentFiles(projectRoot);
-        const toolsDir = path.join(projectRoot, "tools");
-        if (!fs.existsSync(toolsDir)) {
-            fs.mkdirSync(toolsDir, { recursive: true });
-        }
-        const writtenFiles = [];
-        writeJson(path.join(projectRoot, "agent.aui.json"), generalSettings);
-        writtenFiles.push("agent.aui.json");
-        writeJson(path.join(projectRoot, "parameters.aui.json"), parameters);
-        writtenFiles.push("parameters.aui.json");
-        writeJson(path.join(projectRoot, "entities.aui.json"), entities);
-        writtenFiles.push("entities.aui.json");
-        writeJson(path.join(projectRoot, "integrations.aui.json"), integrations);
-        writtenFiles.push("integrations.aui.json");
-        writeJson(path.join(projectRoot, "rules.aui.json"), rules);
-        writtenFiles.push("rules.aui.json");
-        const toolsData = tools;
-        if (toolsData.tools &&
-            Array.isArray(toolsData.tools) &&
-            toolsData.tools.length > 0) {
-            for (const tool of toolsData.tools) {
-                const toolCode = (tool.code ||
-                    tool.name ||
-                    tool.tool_name ||
-                    "unknown");
-                const fileName = `${toolCode.toLowerCase().replace(/\s+/g, "_")}.aui.json`;
-                writeJson(path.join(toolsDir, fileName), { tool });
-                writtenFiles.push(`tools/${fileName}`);
+            else {
+                spinner.succeed("Agent configuration fetched (all 6 endpoints OK)");
+            }
+            cleanAgentFiles(projectRoot);
+            const toolsDir = path.join(projectRoot, "tools");
+            if (!fs.existsSync(toolsDir)) {
+                fs.mkdirSync(toolsDir, { recursive: true });
             }
+            writeJson(path.join(projectRoot, "agent.aui.json"), generalSettings);
+            writtenFiles.push("agent.aui.json");
+            writeJson(path.join(projectRoot, "parameters.aui.json"), parameters);
+            writtenFiles.push("parameters.aui.json");
+            writeJson(path.join(projectRoot, "entities.aui.json"), entities);
+            writtenFiles.push("entities.aui.json");
+            writeJson(path.join(projectRoot, "integrations.aui.json"), integrations);
+            writtenFiles.push("integrations.aui.json");
+            writeJson(path.join(projectRoot, "rules.aui.json"), rules);
+            writtenFiles.push("rules.aui.json");
+            // Per-tool file layout matches the blob disassembler: one
+            // `tools/<tool_code>.aui.json` per tool, wrapped under `{ tool }`.
+            // Empty tool list collapses to a single `tools.aui.json`
+            // wrapper so the rest of the toolchain doesn't choke on a
+            // missing baseline.
+            const toolsData = tools;
+            if (toolsData.tools &&
+                Array.isArray(toolsData.tools) &&
+                toolsData.tools.length > 0) {
+                for (const tool of toolsData.tools) {
+                    const toolCode = (tool.code ||
+                        tool.name ||
+                        tool.tool_name ||
+                        "unknown");
+                    const fileName = `${toolCode
+                        .toLowerCase()
+                        .replace(/\s+/g, "_")}.aui.json`;
+                    writeJson(path.join(toolsDir, fileName), { tool });
+                    writtenFiles.push(`tools/${fileName}`);
+                }
+            }
+            else {
+                writeJson(path.join(projectRoot, "tools.aui.json"), tools);
+                writtenFiles.push("tools.aui.json");
+            }
+            paramCount = (parameters?.parameters || []).length;
+            entityCount = (entities?.entities || []).length;
+            integrationCount =
+                (integrations?.integrations || []).length;
+            toolCount = (toolsData.tools || []).length;
+            ruleCount = (rules?.rules || []).length;
         }
         else {
-            writeJson(path.join(projectRoot, "tools.aui.json"), tools);
-            writtenFiles.push("tools.aui.json");
+            // ─── Bundle-mode but no revision found ───
+            // The agent IS in blob-mode (we just checked) and `/pull`
+            // returned 404, meaning no bundle has been uploaded for this
+            // version_id yet. Throw a clear error pointing at `aui push`
+            // — the user almost certainly meant to seed the version
+            // first. This is a different failure mode from "agent doesn't
+            // exist" (which would have been caught earlier in mode
+            // detection).
+            parentSpan.setAttribute("pull.path", "blob_endpoint_404");
+            spinner.fail("No blob revision found at this version.");
+            throw new CLIError(options.tag
+                ? `No blob revision found at tag ${options.tag} for version ${activeVersionLabel || activeVersionId}.`
+                : `No blob revision found for version ${activeVersionLabel || activeVersionId}.`, {
+                suggestion: "Run `aui push` first to create the initial blob revision via the new /push endpoint, then re-run `aui pull`.",
+            });
         }
-        const paramCount = parameters?.parameters?.length || 0;
-        const entityCount = entities?.entities?.length || 0;
-        const integrationCount = integrations?.integrations?.length || 0;
-        const toolCount = (toolsData.tools || []).length;
-        const ruleCount = rules?.rules?.length || 0;
+        // ─── Skip KB export for templates ─────────────────────────────
+        //
+        // Templates are NETWORK_CATEGORY-scoped and have no `network_id`
+        // / `account_id` on their scope row, so the KB endpoint
+        // (`knowledge-base-manager/v1/knowledge-bases/view/export`)
+        // rejects with 422 ("Id must be of type PydanticObjectId") on the
+        // empty account_id query param. Mirror the same skip in
+        // `import-agent.tsx` — KBs are inherently network-scoped and
+        // templates don't have them in this data model. See
+        // `import-agent.tsx` for the longer comment + reproduction
+        // trace from 2026-05-24.
+        //
+        // `resolvedAgentInfo` is populated by `findAgentMgmtId` above
+        // (branch 1 = .auirc canonical id), so `kind` is reliable for
+        // any project that ran `aui import-agent` on a recent CLI
+        // version. Falls back to `scope.type` for legacy/edge cases.
+        const isTemplateForKb = resolvedAgentInfo?.kind === "template" ||
+            resolvedAgentInfo?.scope?.type === "NETWORK_CATEGORY";
         const kbExportPromise = options.skipKbFiles
             ? Promise.resolve({ kind: "skipped" })
-            : (async () => {
-                try {
-                    const kbClient = new KBViewClient({
-                        authToken: config.authToken,
-                        apiKey: loadAgentSettingsApiKey() || options.apiKey,
-                        organizationId: projectConfig.organization_id || config.organizationId || "",
-                        environment: config.environment || "staging",
-                    });
-                    const scope = buildScope({
-                        networkId,
-                        organizationId: projectConfig.organization_id || config.organizationId || "",
-                        accountId: projectConfig.account_id || config.accountId || "",
-                    });
-                    const result = await exportToFolder(kbClient, scope, projectRoot, options.withKbFiles ?? false);
-                    return { kind: "ok", result };
-                }
-                catch (kbError) {
-                    return {
-                        kind: "error",
-                        error: kbError,
-                        message: kbError instanceof Error ? kbError.message : String(kbError),
-                    };
-                }
-            })();
+            : isTemplateForKb
+                ? Promise.resolve({
+                    kind: "skipped",
+                    reason: "templates are NETWORK_CATEGORY-scoped and don't have knowledge bases",
+                })
+                : (async () => {
+                    try {
+                        const kbClient = new KBViewClient({
+                            authToken: config.authToken,
+                            apiKey: loadAgentSettingsApiKey() || options.apiKey,
+                            organizationId: projectConfig.organization_id || config.organizationId || "",
+                            environment: config.environment || "staging",
+                        });
+                        const scope = buildScope({
+                            networkId,
+                            organizationId: projectConfig.organization_id || config.organizationId || "",
+                            accountId: projectConfig.account_id || config.accountId || "",
+                        });
+                        const result = await exportToFolder(kbClient, scope, projectRoot, options.withKbFiles ?? false);
+                        return { kind: "ok", result };
+                    }
+                    catch (kbError) {
+                        return {
+                            kind: "error",
+                            error: kbError,
+                            message: kbError instanceof Error ? kbError.message : String(kbError),
+                        };
+                    }
+                })();
         const schemaPromise = (async () => {
             try {
                 const data = await fetchSchemas({
@@ -423,7 +835,9 @@ async function _pullAgent(parentSpan, options = {}) {
         parallelSpinner.stop();
         // Knowledge-hub status
         if (kbOutcome.kind === "skipped") {
-            log(_jsx(StatusLine, { kind: "muted", label: "Skipping knowledge hub export (--skip-kb-files)" }));
+            log(_jsx(StatusLine, { kind: "muted", label: kbOutcome.reason
+                    ? `Skipping knowledge hub export — ${kbOutcome.reason}.`
+                    : "Skipping knowledge hub export (--skip-kb-files)" }));
         }
         else if (kbOutcome.kind === "ok") {
             const r = kbOutcome.result;
@@ -459,13 +873,36 @@ async function _pullAgent(parentSpan, options = {}) {
         else {
             log(_jsx(StatusLine, { kind: "warning", label: "Failed to pull schemas (non-blocking)" }));
         }
-        // Preserve original behaviour: a KB export failure aborts `pull`.
+        // KB export failure is non-blocking — same UX as `aui import-agent`.
+        //
+        // Rationale (2026-05-24): the main bundle (`agent.aui.json`,
+        // `parameters.aui.json`, `entities.aui.json`, `integrations.aui.json`,
+        // `rules.aui.json`, `tools/*.aui.json`) has already been written to
+        // disk successfully at this point — the only thing missing is the
+        // `knowledge-hubs/` folder. Killing the whole `aui pull` and
+        // discarding the .auirc / version_tag updates over a transient KB
+        // service issue (e.g. the GCS object-rate-limit on staging that
+        // surfaces as a 500 wrapping a 429) is a worse UX than the
+        // import path's "tell the user, keep going" behaviour. Both paths
+        // now treat KB export the same way:
+        //
+        //   1. Log the failure prominently with the full server message
+        //      (already done above at line ~1110).
+        //   2. Show an actionable hint pointing at `aui rag --export` /
+        //      retry, instead of crashing.
+        //   3. Continue with the .auirc / baseline writes below so the
+        //      project's tracking state matches what was actually pulled.
+        //
+        // The KB failure is still visible in `aui curl` and in the
+        // pre-existing per-task push-logs, so debugging the underlying
+        // GCS or KB-service issue stays straightforward.
         if (kbOutcome.kind === "error") {
-            throw kbOutcome.error;
+            log(_jsx(StatusLine, { kind: "muted", label: "Knowledge hub export failed (non-blocking). Try again with `aui rag --export` or re-run `aui pull` once the KB service recovers." }));
         }
         // Update .auirc with the pulled version info and any newly resolved
         // agent-management id (back-fills it for projects that pre-date the field).
         const shouldRewriteConfig = !!activeVersionId ||
+            !!resolvedVersionTag ||
             (resolvedAgentManagementId &&
                 projectConfig.agent_management_id !== resolvedAgentManagementId);
         if (shouldRewriteConfig) {
@@ -476,6 +913,10 @@ async function _pullAgent(parentSpan, options = {}) {
                     : {}),
                 ...(activeVersionId ? { version_id: activeVersionId } : {}),
                 ...(activeVersionLabel ? { version_label: activeVersionLabel } : {}),
+                // Persist the revision tag from the manifest (e.g. "v8.14")
+                // so the next `aui pull` can default `?version_tag=…` to it
+                // without an extra round-trip.
+                ...(resolvedVersionTag ? { version_tag: resolvedVersionTag } : {}),
                 ...(options.scopeLevel ? { scope_level: options.scopeLevel } : {}),
             }, projectRoot);
         }