aui-agent-builder 0.3.103 → 0.3.104

package/dist/commands/import-agent.js

@@ -1,19 +1,22 @@
-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 { Box } from "ink";
 import inquirer from "inquirer";
 import chalk from "chalk";
 import { getConfig, loadSession, saveProjectConfig, loadAgentSettingsApiKey, saveAgentSettingsApiKey, } from "../config/index.js";
 import { AUIClient, AUIAPIError } from "../api-client/index.js";
 import { getTracer, SpanStatusCode, setUserContext } from "../telemetry.js";
 import { getMissingGitConfig, initAndCommitBaseline } from "../utils/git.js";
-import { AuthenticationError } from "../errors/index.js";
+import { disassembleBundleToFiles, normalizeBundleFileBody, readBundleTools, } from "../utils/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 { Header, StatusLine, Spinner, ErrorDisplay, Hint, } from "../ui/components/index.js";
 import { ImportAgentView, ImportSessionInfo, ImportWarnings, } from "../ui/views/ImportAgentView.js";
+import { detectAgentBundleMode, isModeMismatchError, } from "./util/agent-mode.js";
 // ─── Ink Rendering Helpers ───
 function log(node) {
     const { unmount } = render(node);
@@ -108,29 +111,143 @@ async function _importAgent(parentSpan, agentId, options = {}) {
         environment: config.environment,
     });
     applyAgentSettingsKey(client, options.apiKey);
+    // `selectedAgent` is definitely assigned by either branch below
+    // (explicit-id path throws on resolution failure; interactive path
+    // returns early), but TS can't follow assignment through the
+    // try/fallback pair so we declare with `!` and assert below.
     let selectedAgent;
     let knownAgentInfo;
     // Resolve agent: explicit ID > session agent (when --version is given) > full interactive flow
     const effectiveAgentId = agentId || (options.version ? session.network_id : undefined);
     if (effectiveAgentId) {
+        // ─── Dual-shape id resolution ───
+        // The positional `[agent-id]` arg historically accepted only the
+        // legacy `network_id` (24-char hex of a `Network` document).
+        // After the v3 agent-settings migration, users naturally copy IDs
+        // from the new Swagger ("agent_id (path)" on `/pull` / `/push`) —
+        // those are `agent_management_id`s (also 24-char hex, but a
+        // different document family). Same regex, different collection.
+        //
+        // Try agent-management FIRST (it's the new path and the most
+        // common id today), fall back to the legacy networks lookup on
+        // 404 so existing scripts that pass `network_id` keep working.
+        // Whichever resolves wins, and we cache the resolved `AgentInfo`
+        // as `knownAgentInfo` so `selectVersionForAgent` / `doImport`
+        // skip a duplicate lookup AND the new `/pull` endpoint is
+        // reachable on the first import attempt.
         const spinner = startSpinner("Fetching agent...");
+        let resolved = false;
+        let lastErr;
+        // 1) Treat the id as an agent-management UUID.
         try {
-            const response = await client.networks.get(effectiveAgentId);
-            selectedAgent = response.data;
-            if (selectedAgent.account || selectedAgent.organization) {
-                client.setScope({
-                    ...(selectedAgent.account ? { accountId: selectedAgent.account } : {}),
-                    ...(selectedAgent.organization ? { organizationId: selectedAgent.organization } : {}),
-                });
+            const ami = await client.agentManagement.getAgent(effectiveAgentId);
+            knownAgentInfo = ami;
+            selectedAgent = agentInfoToNetwork(ami);
+            // Bias the client scope toward the agent's own org/account so
+            // downstream listAgents/listVersions calls don't 403 against the
+            // session's default scope.
+            const scopeUpdate = {};
+            if (ami.scope?.account_id)
+                scopeUpdate.accountId = ami.scope.account_id;
+            if (ami.scope?.organization_id)
+                scopeUpdate.organizationId = ami.scope.organization_id;
+            if (scopeUpdate.accountId || scopeUpdate.organizationId) {
+                client.setScope(scopeUpdate);
             }
-            spinner.succeed(`Found agent: ${selectedAgent.name}`);
+            spinner.succeed(`Found agent (via agent-management): ${ami.name}`);
+            resolved = true;
         }
-        catch (error) {
-            spinner.fail(isAuthError(error) ? "Authentication failed" : "Agent not found");
-            handleAuthError(error);
-            throw error;
+        catch (err) {
+            lastErr = err;
+            const status = err instanceof AUIAPIError
+                ? err.status
+                : (err.statusCode ??
+                    err.status);
+            // Fall through to the legacy networks lookup on ANY non-auth
+            // error — not just 404. Rationale (2026-05-24):
+            //
+            //   - 404 ⇒ id isn't an agent_management_id; try as network_id.
+            //   - 422 ⇒ the new agent-settings response schema has stricter
+            //          validation than some legacy docs (e.g. the post-`kind`
+            //          rollout returned 422 for any pre-rollout agent until
+            //          a backfill landed). The legacy networks endpoint
+            //          lives in a different service and doesn't share that
+            //          validation, so it can still resolve the same agent.
+            //   - 5xx / network blip ⇒ a transient agent-settings failure
+            //          shouldn't block the import when there's an alternate
+            //          resolver available; the legacy attempt will either
+            //          succeed (problem masked) or 4xx itself (we report
+            //          the more informative agent-settings error via
+            //          `lastErr` at the end of step 2).
+            //
+            // Auth errors (401/403) STILL fail loudly here — no point in
+            // trying the next endpoint with the same credentials.
+            if (isAuthError(err)) {
+                spinner.fail("Authentication failed");
+                handleAuthError(err);
+                throw err;
+            }
+            if (process.env.AUI_DEBUG) {
+                console.log(`[debug] agentManagement.getAgent(${effectiveAgentId}) → ${status ?? "non-auth error"}; trying legacy networks.get next`);
+            }
+        }
+        // 2) Fall back: treat the id as a legacy network_id.
+        if (!resolved) {
+            try {
+                const response = await client.networks.get(effectiveAgentId);
+                selectedAgent = response.data;
+                if (selectedAgent.account || selectedAgent.organization) {
+                    client.setScope({
+                        ...(selectedAgent.account ? { accountId: selectedAgent.account } : {}),
+                        ...(selectedAgent.organization
+                            ? { organizationId: selectedAgent.organization }
+                            : {}),
+                    });
+                }
+                spinner.succeed(`Found agent (via legacy networks): ${selectedAgent.name}`);
+                resolved = true;
+            }
+            catch (error) {
+                // Neither id shape resolved. Surface the FIRST failure
+                // (agent-management) since that's the new-world canonical
+                // path and is the more informative error in the migration
+                // window. Fall back to the second error if the first was
+                // suppressed for some reason.
+                spinner.fail(isAuthError(error) || isAuthError(lastErr)
+                    ? "Authentication failed"
+                    : "Agent not found (tried both agent-management and legacy networks)");
+                const errToReport = lastErr ?? error;
+                handleAuthError(errToReport);
+                throw errToReport;
+            }
         }
     }
+    else if (options.templates) {
+        // ─── Templates picker (NETWORK_CATEGORY-scoped, kind=template) ──
+        //
+        // Templates don't live under an account — they're category-scoped
+        // and visible to every account in the org. The default
+        // `listAgents` call only returns NETWORK-scoped regulars, so we
+        // need the new `scope_type=NETWORK_CATEGORY` + `kind=template`
+        // filters (added to the API client 2026-05-24). The walk becomes:
+        //
+        //   org → category → template → version
+        //
+        // (vs. the regular org → account → agent → version)
+        //
+        // We still pass through `selectVersionForAgent` afterwards —
+        // template version management uses the same /v1/agents/{id}/versions
+        // endpoints regardless of `kind`.
+        const orgResult = await selectOrgForImport(client, session);
+        if (!orgResult)
+            return;
+        log(_jsx(ImportSessionInfo, { orgName: orgResult.orgName, accountName: "(templates are category-scoped)", environment: session.environment }));
+        const result = await selectTemplateFromList(client, options.category);
+        if (!result)
+            return;
+        selectedAgent = result.network;
+        knownAgentInfo = result.agentInfo;
+    }
     else {
         // Step 1: Choose organization
         const orgResult = await selectOrgForImport(client, session);
@@ -153,15 +270,29 @@ async function _importAgent(parentSpan, agentId, options = {}) {
     const networkId = selectedAgent._id || selectedAgent.id;
     parentSpan.setAttribute("import.agent_id", networkId);
     parentSpan.setAttribute("import.agent_name", selectedAgent.name);
-    const selectedVersion = await selectVersionForAgent(client, networkId, options.version, knownAgentInfo);
+    const { version: selectedVersion, agentInfo: resolvedAgentInfo } = await selectVersionForAgent(client, networkId, options.version, knownAgentInfo);
+    // `selectVersionForAgent` may resolve the agent-management record
+    // internally (via `listAgents(network_id=…)`) even when the upstream
+    // `selectAgentFromList` had to fall back to legacy networks. Prefer
+    // the freshly-resolved id so `doImport` can reach the new `/pull`
+    // endpoint instead of silently degrading to the legacy export path.
+    const effectiveAgentMgmtId = knownAgentInfo?.id ?? resolvedAgentInfo?.id;
     if (selectedVersion) {
         parentSpan.setAttribute("import.version_id", selectedVersion.id);
         parentSpan.setAttribute("import.version", `v${selectedVersion.version_number}`);
     }
+    if (effectiveAgentMgmtId) {
+        parentSpan.setAttribute("import.agent_management_id", effectiveAgentMgmtId);
+    }
     const vLabel = selectedVersion
         ? `v${selectedVersion.version_number}`
         : undefined;
-    await doImport(client, selectedAgent, config, options, parentSpan, selectedVersion?.id, vLabel, selectedVersion?.status, knownAgentInfo?.id);
+    // Prefer the AgentInfo fetched in step 1 (`knownAgentInfo`); fall
+    // back to the version-resolver's lookup (`resolvedAgentInfo`).
+    // Either way, downstream `detectAgentBundleMode` reuses it instead
+    // of re-fetching.
+    const effectiveAgentInfo = knownAgentInfo ?? resolvedAgentInfo;
+    await doImport(client, selectedAgent, config, options, parentSpan, selectedVersion?.id, vLabel, selectedVersion?.status, effectiveAgentMgmtId, effectiveAgentInfo);
 }
 // ─── Import from another account ───
 export async function importFromOtherAccount(options = {}) {
@@ -230,11 +361,13 @@ async function _importFromOtherAccount(parentSpan, options = {}) {
         if (!result)
             return;
         const networkId = result.network._id || result.network.id;
-        const selectedVersion = await selectVersionForAgent(client, networkId, undefined, result.agentInfo);
+        const { version: selectedVersion, agentInfo: resolvedAgentInfo } = await selectVersionForAgent(client, networkId, undefined, result.agentInfo);
+        const effectiveAgentMgmtId = result.agentInfo?.id ?? resolvedAgentInfo?.id;
+        const effectiveAgentInfo = result.agentInfo ?? resolvedAgentInfo;
         const vLabel = selectedVersion
             ? `v${selectedVersion.version_number}`
             : undefined;
-        await doImport(client, result.network, config, options, parentSpan, selectedVersion?.id, vLabel, selectedVersion?.status, result.agentInfo?.id);
+        await doImport(client, result.network, config, options, parentSpan, selectedVersion?.id, vLabel, selectedVersion?.status, effectiveAgentMgmtId, effectiveAgentInfo);
     }
     catch (error) {
         spinner.fail("Failed to fetch accounts");
@@ -330,11 +463,13 @@ async function _importFromOtherOrg(parentSpan, options = {}) {
         if (!result)
             return;
         const networkId = result.network._id || result.network.id;
-        const selectedVersion = await selectVersionForAgent(client, networkId, undefined, result.agentInfo);
+        const { version: selectedVersion, agentInfo: resolvedAgentInfo } = await selectVersionForAgent(client, networkId, undefined, result.agentInfo);
+        const effectiveAgentMgmtId = result.agentInfo?.id ?? resolvedAgentInfo?.id;
+        const effectiveAgentInfo = result.agentInfo ?? resolvedAgentInfo;
         const vLabel = selectedVersion
             ? `v${selectedVersion.version_number}`
             : undefined;
-        await doImport(client, result.network, config, options, parentSpan, selectedVersion?.id, vLabel, selectedVersion?.status, result.agentInfo?.id);
+        await doImport(client, result.network, config, options, parentSpan, selectedVersion?.id, vLabel, selectedVersion?.status, effectiveAgentMgmtId, effectiveAgentInfo);
     }
     catch (error) {
         orgSpinner.fail("Failed to fetch organizations");
@@ -444,6 +579,97 @@ function agentInfoToNetwork(a) {
         updatedAt: a.updated_at,
     };
 }
+/**
+ * Picker for template (kind=template, NETWORK_CATEGORY-scoped) agents.
+ *
+ * Mirrors `selectAgentFromList` but calls `listAgents` with the new
+ * `scope_type=NETWORK_CATEGORY` + `kind=template` filters so only
+ * templates show up. No legacy `networks.list()` fallback — there's no
+ * equivalent legacy concept for templates (they only exist in the
+ * agent-management world).
+ *
+ * If `categoryFilter` is provided, it's resolved to a category id (via
+ * the same id/key/name lookup `agents --create --category` uses) and
+ * forwarded as `network_category_id` so the listing only returns
+ * templates in that category. Invalid filter ⇒ helpful error + bail.
+ */
+async function selectTemplateFromList(client, categoryFilter) {
+    let resolvedCategoryId;
+    if (categoryFilter) {
+        const catSpinner = startSpinner(`Resolving category "${categoryFilter}"...`);
+        try {
+            const catResp = await client.categories.list();
+            const catUpper = categoryFilter.toUpperCase();
+            const match = catResp.data.find((c) => c._id === categoryFilter ||
+                c.key?.toUpperCase() === catUpper ||
+                c.name?.toUpperCase() === catUpper);
+            if (match) {
+                resolvedCategoryId = match._id;
+                catSpinner.succeed(`Category: ${match.name} (${match.key})`);
+            }
+            else {
+                catSpinner.fail(`Category "${categoryFilter}" not found.`);
+                const available = catResp.data
+                    .map((c) => `${c.name} (${c.key})`)
+                    .slice(0, 10)
+                    .join(", ");
+                log(_jsx(StatusLine, { kind: "muted", label: `Available: ${available}${catResp.data.length > 10 ? `, … (${catResp.data.length} total)` : ""}` }));
+                return null;
+            }
+        }
+        catch (err) {
+            catSpinner.warn(`Could not resolve category — listing all templates instead. (${err instanceof Error ? err.message : err})`);
+        }
+    }
+    const spinner = startSpinner("Fetching templates...");
+    try {
+        const allTemplates = [];
+        let page = 1;
+        let hasMore = true;
+        while (hasMore) {
+            const response = await client.agentManagement.listAgents(client.getOrganizationId(), page, 50, {
+                scope_type: "NETWORK_CATEGORY",
+                kind: "template",
+                ...(resolvedCategoryId ? { network_category_id: resolvedCategoryId } : {}),
+            });
+            allTemplates.push(...response.items);
+            hasMore = page < response.pages;
+            page++;
+        }
+        if (allTemplates.length === 0) {
+            spinner.succeed("No templates found");
+            log(_jsx(StatusLine, { kind: "warning", label: resolvedCategoryId
+                    ? `No templates in this category. Use \`aui agents --create --template --category <id> --name <name>\` to create one.`
+                    : "No templates found in this organization. Use `aui agents --create --template --category <id> --name <name>` to create one." }));
+            return null;
+        }
+        spinner.succeed(`Found ${allTemplates.length} template(s)`);
+        const { chosen } = await inquirer.prompt([
+            {
+                type: "list",
+                name: "chosen",
+                message: "Select template to import:",
+                choices: allTemplates.map((a) => {
+                    // Surface the category id when it's the differentiator —
+                    // templates with the same name across categories is a real
+                    // case worth disambiguating in the picker.
+                    const cat = a.scope?.network_category_id
+                        ? ` (${a.scope.network_category_id.slice(0, 8)}…)`
+                        : "";
+                    return { name: `${a.name}${cat}`, value: a };
+                }),
+                pageSize: 15,
+            },
+        ]);
+        const selected = chosen;
+        return { network: agentInfoToNetwork(selected), agentInfo: selected };
+    }
+    catch (error) {
+        spinner.fail("Failed to fetch templates");
+        handleAuthError(error);
+        throw error;
+    }
+}
 async function selectAgentFromList(client) {
     const spinner = startSpinner("Fetching agents...");
     try {
@@ -519,6 +745,21 @@ async function selectAgentFromList(client) {
     }
 }
 // ─── Shared: select version for an agent ───
+/**
+ * Resolve a version (and the underlying agent-management record) for an
+ * agent identified by `networkId`. Returns BOTH so the caller can
+ * forward the agent-management UUID into `doImport` — without it the
+ * new `/pull` blob endpoint can never be reached (it's keyed on
+ * `agent_id` = agent-management UUID, not network_id).
+ *
+ * Previously this returned just `AgentVersion | null`. When the
+ * upstream `selectAgentFromList` fell back to the legacy
+ * `networks.list()` (because agentManagement `listAgents` returned 0),
+ * the agent-management UUID was resolved here locally but lost on the
+ * way back, so `doImport` saw `agentManagementId === undefined` and
+ * silently took the legacy export path. Returning `agentInfo` plugs
+ * that hole.
+ */
 async function selectVersionForAgent(client, networkId, versionIdOverride, knownAgentInfo) {
     const spinner = startSpinner("Fetching agent versions...");
     try {
@@ -558,7 +799,7 @@ async function selectVersionForAgent(client, networkId, versionIdOverride, known
         }
         if (!agentInfo) {
             spinner.succeed("No version management found — importing latest");
-            return null;
+            return { version: null, agentInfo: undefined };
         }
         if (process.env.AUI_DEBUG) {
             console.log(`[debug] resolved agent: id=${agentInfo.id} name=${agentInfo.name} network=${agentInfo.scope.network_id} active_version=${agentInfo.active_version_id}`);
@@ -574,19 +815,74 @@ async function selectVersionForAgent(client, networkId, versionIdOverride, known
         }
         if (allVersions.length === 0) {
             spinner.succeed("No versions found — importing latest");
-            return null;
+            return { version: null, agentInfo };
         }
         spinner.succeed(`Found ${allVersions.length} version(s)`);
         if (versionIdOverride) {
             const match = allVersions.find((v) => v.id === versionIdOverride);
-            if (!match) {
-                log(_jsx(StatusLine, { kind: "error", label: `Version not found: ${versionIdOverride}` }));
-                log(_jsx(Hint, { message: "Run `aui agent --versions` to see available versions." }));
-                throw new Error(`Version not found: ${versionIdOverride}`);
+            if (match) {
+                const vLabel = `v${match.version_number}`;
+                log(_jsx(StatusLine, { kind: "info", label: `Version: ${vLabel} [${match.status}]` }));
+                return { version: match, agentInfo };
             }
-            const vLabel = `v${match.version_number}`;
-            log(_jsx(StatusLine, { kind: "info", label: `Version: ${vLabel} [${match.status}]` }));
-            return match;
+            // ─── Multi-agent fallback for shared network_ids ──────────────
+            // It's legitimate for one `network_id` to map to MULTIPLE
+            // agent-management records (e.g. duplicates from data migration,
+            // or one record per account scope under the same network). We
+            // picked the first match from `listAgents(network_id=…)` above,
+            // but the user's `--version <id>` may belong to a SIBLING agent
+            // record. Before throwing "version not found", paginate every
+            // agent for this network_id and try `getVersion(candidate.id,
+            // versionIdOverride)` on each — return the first one that
+            // succeeds (and switch `agentInfo` to that candidate so
+            // downstream `/pull` uses the right `agent_id`).
+            const probeSpinner = startSpinner(`Version not on agent ${agentInfo.id.slice(0, 10)}…; searching sibling agents for the same network...`);
+            try {
+                const allCandidates = [];
+                let probePage = 1;
+                let probeHasMore = true;
+                while (probeHasMore) {
+                    const resp = await client.agentManagement.listAgents(client.getOrganizationId(), probePage, 50, { network_id: networkId });
+                    allCandidates.push(...resp.items);
+                    probeHasMore = probePage < resp.pages;
+                    probePage++;
+                }
+                const siblings = allCandidates.filter((c) => c.id !== agentInfo.id);
+                if (process.env.AUI_DEBUG) {
+                    console.log(`[debug] multi-agent fallback: found ${siblings.length} sibling agent(s) for network_id=${networkId}; probing each for version ${versionIdOverride}`);
+                }
+                for (const sibling of siblings) {
+                    try {
+                        const ver = await client.agentManagement.getVersion(sibling.id, versionIdOverride);
+                        probeSpinner.succeed(`Found version on sibling agent ${sibling.id.slice(0, 10)}… (${sibling.name})`);
+                        const vLabel = `v${ver.version_number}`;
+                        log(_jsx(StatusLine, { kind: "info", label: `Version: ${vLabel} [${ver.status}] (agent: ${sibling.name})` }));
+                        return { version: ver, agentInfo: sibling };
+                    }
+                    catch (err) {
+                        const status = err.statusCode ??
+                            err.status;
+                        if (status !== 404) {
+                            // Non-404 (auth / 5xx) — bubble immediately so we
+                            // don't silently skip a real failure.
+                            probeSpinner.fail("Sibling-agent probe failed");
+                            throw err;
+                        }
+                        if (process.env.AUI_DEBUG) {
+                            console.log(`[debug] multi-agent fallback: getVersion(${sibling.id}, ${versionIdOverride}) → 404; trying next sibling`);
+                        }
+                    }
+                }
+                probeSpinner.fail(`Version ${versionIdOverride} not found on any of ${allCandidates.length} agent record(s) for network ${networkId}`);
+            }
+            catch (probeErr) {
+                if (probeSpinner.stop)
+                    probeSpinner.stop();
+                throw probeErr;
+            }
+            log(_jsx(StatusLine, { kind: "error", label: `Version not found: ${versionIdOverride}` }));
+            log(_jsx(Hint, { message: "Run `aui agent --versions` to see available versions on this agent, or verify the version_id from the Playground's `Versions management` dialog." }));
+            throw new Error(`Version not found: ${versionIdOverride}`);
         }
         // Auto-select active version if one exists
         if (agentInfo.active_version_id) {
@@ -594,7 +890,7 @@ async function selectVersionForAgent(client, networkId, versionIdOverride, known
             if (active) {
                 const vLabel = `v${active.version_number}`;
                 log(_jsx(StatusLine, { kind: "info", label: `Using active version: ${vLabel}` }));
-                return active;
+                return { version: active, agentInfo };
             }
         }
         const { selectedVersion } = await inquirer.prompt([
@@ -624,7 +920,7 @@ async function selectVersionForAgent(client, networkId, versionIdOverride, known
             const vLabel = `v${selectedVersion.version_number}`;
             log(_jsx(StatusLine, { kind: "info", label: `Version: ${vLabel}` }));
         }
-        return selectedVersion;
+        return { version: selectedVersion, agentInfo };
     }
     catch (error) {
         if (error.message?.startsWith("Version not found:"))
@@ -632,11 +928,19 @@ async function selectVersionForAgent(client, networkId, versionIdOverride, known
         spinner.fail("Failed to fetch versions");
         handleAuthError(error);
         log(_jsx(StatusLine, { kind: "muted", label: "Continuing without version selection..." }));
-        return null;
+        return { version: null, agentInfo: undefined };
     }
 }
 // ─── Shared: perform the actual import ───
-async function doImport(client, selectedAgent, config, options, span, versionId, versionLabel, versionStatus, agentManagementId) {
+async function doImport(client, selectedAgent, config, options, span, versionId, versionLabel, versionStatus, agentManagementId, 
+// The full `AgentInfo` if a previous step already fetched it (e.g.
+// `_importAgent` step 1 or `selectAgentFromList` in the picker
+// flow). Passing it lets `detectAgentBundleMode` skip its own
+// `GET /v1/agents/{id}` round-trip — saving one network call per
+// import and avoiding the duplicate-fetch the user observed in
+// the trace (2026-05-24). Undefined is safe; the dispatcher
+// falls back to its own fetch.
+knownAgentInfo) {
     const networkCategoryId = getCategoryId(selectedAgent);
     if (!networkCategoryId) {
         log(_jsx(StatusLine, { kind: "warning", label: "No category ID found for this agent. Some exports may fail." }));
@@ -672,111 +976,379 @@ async function doImport(client, selectedAgent, config, options, span, versionId,
         }
         cleanAgentFiles(outputDir);
     }
-    const spinner = startSpinner("Exporting agent data (7 endpoints)...");
-    try {
-        const networkId = selectedAgent._id || selectedAgent.id;
-        let generalSettings = {
-            general_settings: { name: selectedAgent.name },
-        };
-        let parameters = { parameters: [] };
-        let entities = { entities: [] };
-        let integrations = { integrations: [] };
-        let tools = { tools: [] };
-        let rules = { rules: [] };
-        let exportData = await client.exportAgent(networkId, networkCategoryId || "", versionId, 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 || "", versionId, options.scopeLevel);
-                retrySpinner.stop();
-            }
-        }
-        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 (span) {
-                span.setStatus({ code: SpanStatusCode.ERROR, message: exportData.errors.join("; ") });
-                for (const e of exportData.errors) {
-                    span.recordException(new Error(e));
+    const networkId = selectedAgent._id || selectedAgent.id;
+    // ─── 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.
+    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",
+    ]);
+    const targetPathForBundleFile = (bundleDir, filename) => CANONICAL_ROOT_FILES.has(filename)
+        ? path.join(bundleDir, filename)
+        : path.join(bundleDir, "tools", filename);
+    // ─── Default in-memory bundle (used by both new + legacy paths) ───
+    let generalSettings = {
+        general_settings: { name: selectedAgent.name },
+    };
+    let parameters = { parameters: [] };
+    let entities = { entities: [] };
+    let integrations = { integrations: [] };
+    let tools = { tools: [] };
+    let rules = { rules: [] };
+    let writtenFiles = [];
+    let paramCount = 0;
+    let entityCount = 0;
+    let integrationCount = 0;
+    let toolCount = 0;
+    let ruleCount = 0;
+    let resolvedVersionTag;
+    // ─── Last-ditch agent_management_id resolve ───
+    // The new `/pull` endpoint is keyed on the agent-management UUID,
+    // NOT network_id. If neither `_importAgent` nor `selectVersionForAgent`
+    // managed to resolve it (e.g. the user took the legacy `networks.list()`
+    // path because agentManagement `listAgents(org_id=…)` returned 0 items),
+    // try ONE more `listAgents(network_id=…)` before giving up. Without
+    // this, the explicit-`--agent-id` branch silently took the legacy
+    // export path on every import.
+    let effectiveAgentMgmtId = agentManagementId;
+    if (!effectiveAgentMgmtId && versionId && networkId) {
+        try {
+            const resp = await client.agentManagement.listAgents(client.getOrganizationId(), 1, 50, { network_id: networkId });
+            const match = resp.items.find((a) => a.scope.network_id === networkId || a.id === networkId);
+            if (match) {
+                effectiveAgentMgmtId = match.id;
+                if (process.env.AUI_DEBUG) {
+                    console.log(`[debug] doImport: last-ditch listAgents(network_id=${networkId}) → ${match.id}`);
                 }
-                span.setAttribute("import.failed_endpoints", 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)");
-        }
-        if (!fs.existsSync(outputDir)) {
-            fs.mkdirSync(outputDir, { recursive: true });
-        }
-        const toolsDir = path.join(outputDir, "tools");
-        if (!fs.existsSync(toolsDir)) {
-            fs.mkdirSync(toolsDir, { recursive: true });
-        }
-        const writtenFiles = [];
-        writeJson(path.join(outputDir, "agent.aui.json"), generalSettings);
-        writtenFiles.push("agent.aui.json");
-        writeJson(path.join(outputDir, "parameters.aui.json"), parameters);
-        writtenFiles.push("parameters.aui.json");
-        writeJson(path.join(outputDir, "entities.aui.json"), entities);
-        writtenFiles.push("entities.aui.json");
-        writeJson(path.join(outputDir, "integrations.aui.json"), integrations);
-        writtenFiles.push("integrations.aui.json");
-        writeJson(path.join(outputDir, "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}`);
+        catch (err) {
+            if (process.env.AUI_DEBUG) {
+                console.log(`[debug] doImport: last-ditch listAgents failed: ${err instanceof Error ? err.message : err}`);
             }
         }
-        else {
-            writeJson(path.join(outputDir, "tools.aui.json"), tools);
-            writtenFiles.push("tools.aui.json");
+    }
+    // ─── Use the new pull endpoint (strict, no legacy fallback) ───
+    //
+    // STRICT MODE (2026-05-18 owner directive): the v3 agent-settings
+    // /pull endpoint is the only supported import path. If it fails for
+    // any reason (404, auth, 5xx, network), we surface a clear error
+    // instead of falling back to the legacy per-entity exports. The
+    // legacy `client.exportAgent` flow is preserved below but commented
+    // out — it's the bootstrap path for agents that haven't been
+    // Pushed via the new endpoint yet, and may be re-enabled later if a
+    // migration adapter is needed.
+    //
+    // What this means for the user:
+    //   - The agent MUST have at least one Push via the new endpoint
+    //     (creates the first blob revision at `v{N}.1`).
+    //   - The agent MUST have an `agent_management_id` (resolvable via
+    //     `listAgents(network_id=…)`) and a `version_id`.
+    //   - 404 from /pull → "no blobs at this version" → user must run
+    //     `aui push` first (or re-import via the deprecated bootstrap
+    //     path if temporarily re-enabled).
+    //   - Any other error bubbles unchanged.
+    if (!versionId) {
+        throw new ConfigError("No version_id available for the new /pull endpoint.", {
+            suggestion: "Pass --version <versionId>, or re-run `aui import` interactively so a version can be selected. Legacy agents without version management cannot be imported under the strict no-fallback policy.",
+        });
+    }
+    if (!effectiveAgentMgmtId) {
+        throw new ConfigError("Could not resolve agent_management_id for this agent.", {
+            suggestion: "Pass the agent_management_id directly as the positional arg, or check that the agent exists in agent-management (`listAgents(network_id=…)`).",
+        });
+    }
+    // ─── Mode dispatch ────────────────────────────────────────────────
+    // Restored 2026-05-24. Detect `Agent.bundle_mode` once via the agent
+    // record we already resolved, then either:
+    //
+    //   - bundle mode → call new `/pull` endpoint (existing logic
+    //                    below; strict 404 → "run aui push first")
+    //   - records mode → fall back to per-entity `/view` endpoints via
+    //                    `client.exportAgent(...)` and reconstruct
+    //                    canonical .aui.json files locally
+    //
+    // The two surfaces are mutually exclusive at the API layer; calling
+    // the wrong one returns 422 (or empty payload for legacy reads
+    // against blob-mode), which the user can't recover from at the
+    // CLI level. We dispatch BEFORE any /pull or /view call so the
+    // first attempt is always the right surface.
+    // Reuse the AgentInfo from step 1 / selectAgentFromList when we have
+    // it — saves one `GET /v1/agents/{id}` and avoids the duplicate-fetch
+    // observed in the 2026-05-24 trace.
+    const importModeResolution = await detectAgentBundleMode(client, effectiveAgentMgmtId, knownAgentInfo);
+    if (span) {
+        span.setAttribute("import.dispatch.mode", importModeResolution.mode);
+        span.setAttribute("import.dispatch.mode_source", importModeResolution.source);
+    }
+    const useLegacyImport = importModeResolution.mode === "records";
+    const spinner = startSpinner(useLegacyImport
+        ? "Fetching agent data (legacy /view endpoints)..."
+        : options.tag
+            ? `Pulling bundle at tag ${options.tag} via new /pull endpoint...`
+            : `Pulling agent bundle via new /pull endpoint...`);
+    try {
+        if (useLegacyImport) {
+            // ─── Records-mode legacy export ─────────────────────────────
+            // Same shape as the legacy block restored in `pull-agent.tsx`
+            // (kept in sync). Hits the per-entity /view endpoints once,
+            // optionally retries with an API-key prompt on auth failure,
+            // then writes the canonical .aui.json layout to disk.
+            if (span)
+                span.setAttribute("import.path", "legacy_export");
+            let exportData = await client.exportAgent(networkId, networkCategoryId || "", versionId, 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 || "", versionId, options.scopeLevel);
+                    retrySpinner.stop();
+                }
+            }
+            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 (span) {
+                    span.setAttribute("import.failed_endpoints", exportData.errors.join(","));
+                }
+                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)");
+            }
+            if (!fs.existsSync(outputDir)) {
+                fs.mkdirSync(outputDir, { recursive: true });
+            }
+            const toolsDir = path.join(outputDir, "tools");
+            if (!fs.existsSync(toolsDir)) {
+                fs.mkdirSync(toolsDir, { recursive: true });
+            }
+            writeJson(path.join(outputDir, "agent.aui.json"), generalSettings);
+            writtenFiles.push("agent.aui.json");
+            writeJson(path.join(outputDir, "parameters.aui.json"), parameters);
+            writtenFiles.push("parameters.aui.json");
+            writeJson(path.join(outputDir, "entities.aui.json"), entities);
+            writtenFiles.push("entities.aui.json");
+            writeJson(path.join(outputDir, "integrations.aui.json"), integrations);
+            writtenFiles.push("integrations.aui.json");
+            writeJson(path.join(outputDir, "rules.aui.json"), rules);
+            writtenFiles.push("rules.aui.json");
+            // Per-tool files match the disassembler layout: one
+            // `tools/<tool_code>.aui.json` per tool. Empty tools list
+            // collapses to a single `tools.aui.json` so downstream code
+            // always finds a 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(outputDir, "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;
+            // Skip the rest of the new-endpoint branch (the blob disassembler
+            // code below). Drop into the shared finalization block by
+            // simply not entering the `else` block. We DO continue past
+            // this point to write `.auirc` etc. — same as the new path.
         }
+        else {
+            // ─── Blob-mode (new /pull endpoint) ─────────────────────────
+            let pullData = null;
+            try {
+                pullData = await tryPullViaBlobEndpoint(client, effectiveAgentMgmtId, versionId, options.tag);
+            }
+            catch (pullErr) {
+                if (pullErr instanceof PullModeMismatch) {
+                    // Server changed the agent's mode between detection and
+                    // this call. Re-run with `useLegacyImport=true`. Recursing
+                    // into _doImport would duplicate every preflight — instead
+                    // do the legacy export inline. We hit the same code path
+                    // as the records-mode branch above, so we just bail out
+                    // and ask the user to rerun.
+                    if (span) {
+                        span.setAttribute("import.dispatch.mode_changed_midflight", true);
+                    }
+                    spinner.warn("Server reports the agent is now in records-mode.");
+                    throw new CLIError("Server reports this agent is now in DB-records mode mid-import.", {
+                        suggestion: "Re-run `aui import` — the CLI re-detects the agent's mode on every invocation and will pick the legacy per-entity import path on the next run.",
+                    });
+                }
+                throw pullErr;
+            }
+            if (!pullData) {
+                // 404 from /pull — agent has never been Pushed via the new
+                // endpoint, or the requested tag doesn't exist on that version.
+                spinner.fail("No blob revision found at this version.");
+                throw new CLIError(options.tag
+                    ? `No blob revision found at tag ${options.tag} for version ${versionId}.`
+                    : `No blob revision found for version ${versionId}.`, {
+                    suggestion: "Either (a) push to this version first via `aui push` to create the initial blob revision, or (b) pick a different version with `aui agent --versions`.",
+                });
+            }
+            // ─── New bundle path: disassemble + write files ───
+            if (!fs.existsSync(outputDir)) {
+                fs.mkdirSync(outputDir, { recursive: true });
+            }
+            const toolsDir = path.join(outputDir, "tools");
+            if (!fs.existsSync(toolsDir)) {
+                fs.mkdirSync(toolsDir, { recursive: true });
+            }
+            const disassembled = disassembleBundleToFiles(pullData.bundle);
+            for (const entry of disassembled) {
+                const targetPath = path.join(outputDir, entry.relativePath);
+                fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+                // Normalize to canonical on-disk shape before writing. The
+                // disassembler already produces canonical shapes; this is a
+                // belt+suspenders pass for any edge case the disassembler
+                // might mishandle on legacy bundle data.
+                const basename = path.basename(entry.relativePath);
+                const normalized = normalizeBundleFileBody(basename, entry.body);
+                writeJson(targetPath, normalized);
+                writtenFiles.push(entry.relativePath);
+                if (basename === "agent.aui.json") {
+                    generalSettings = normalized;
+                }
+                else if (basename === "parameters.aui.json") {
+                    parameters = normalized;
+                    paramCount = (normalized?.parameters || []).length;
+                }
+                else if (basename === "entities.aui.json") {
+                    entities = normalized;
+                    entityCount = (normalized?.entities || []).length;
+                }
+                else if (basename === "integrations.aui.json") {
+                    integrations = normalized;
+                    integrationCount = (normalized?.integrations || []).length;
+                }
+                else if (basename === "rules.aui.json") {
+                    rules = normalized;
+                    ruleCount = (normalized?.rules || []).length;
+                }
+                else if (entry.relativePath.startsWith("tools/")) {
+                    toolCount++;
+                }
+                else if (basename === "tools.aui.json") {
+                    tools = normalized;
+                    toolCount += (normalized?.tools || []).length;
+                }
+            }
+            resolvedVersionTag = pullData.version_tag;
+            if (span) {
+                span.setAttribute("import.path", "blob_endpoint");
+                if (resolvedVersionTag) {
+                    span.setAttribute("import.version_tag", resolvedVersionTag);
+                }
+            }
+            spinner.succeed(`Pulled bundle via /pull (${disassembled.length} file(s)) at ${resolvedVersionTag || `v${versionLabel}`}`);
+            // ─── Empty-domain warning banner ─────────────────────────────────
+            // The server can legitimately return a bundle with an empty
+            // domain (e.g. tools[]=[]) — it's not a CLI error. But it IS
+            // usually a sign the user pulled the wrong version (a v8 line
+            // that has no tools while v9-LIVE has them, etc.). Surface
+            // every empty domain prominently so the user can decide whether
+            // to re-import a different version instead of being surprised
+            // when their `tools/` folder is empty after import.
+            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 || `v${versionLabel}`} 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-import with `--version <id>`." })] }));
+                if (span) {
+                    span.setAttribute("import.empty_domains", emptyDomains.join(","));
+                }
+            }
+        } // end of bundle-mode `else` branch (matches `if (useLegacyImport)` above)
+        // Persist agent + version + revision context to `.auirc`.
+        // `version_label` = `v{version_number}` (e.g. "v8") — the version
+        // document's display label, used by telemetry / version UX.
+        // `version_tag`   = full revision tag from the manifest (e.g.
+        // "v8.14") — used as the default `?version_tag=` on the next
+        // `aui pull` so users re-pull the exact revision they imported
+        // without having to remember it.
+        //
+        // Prefer `effectiveAgentMgmtId` (resolved via the dual-shape
+        // helper above) over the original `agentManagementId` arg so the
+        // saved id reflects whatever actually worked, even when the
+        // upstream `selectAgentFromList` had to fall back to legacy
+        // `networks.list()`.
         saveProjectConfig({
             agent_code: selectedAgent.niceName ||
                 selectedAgent.name.toLowerCase().replace(/\s+/g, "-"),
             agent_id: networkId,
-            ...(agentManagementId ? { agent_management_id: agentManagementId } : {}),
+            ...(effectiveAgentMgmtId
+                ? { agent_management_id: effectiveAgentMgmtId }
+                : {}),
             environment: config.environment,
             account_id: client.getAccountId() || config.accountId,
             organization_id: client.getOrganizationId() || config.organizationId,
             network_category_id: networkCategoryId,
             ...(versionId ? { version_id: versionId } : {}),
             ...(versionLabel ? { version_label: versionLabel } : {}),
+            ...(resolvedVersionTag ? { version_tag: resolvedVersionTag } : {}),
             ...(options.scopeLevel ? { scope_level: options.scopeLevel } : {}),
         }, outputDir);
         writtenFiles.push(".auirc");
@@ -793,36 +1365,63 @@ async function doImport(client, selectedAgent, config, options, span, versionId,
         catch {
             // optional
         }
-        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 (no `scope.network_id`,
+        // no `scope.account_id`). KB exports are inherently network-
+        // scoped — the `knowledge-base-manager/v1/knowledge-bases/view/
+        // export` endpoint expects valid `network_id` + `account_id`
+        // query params. Calling it for a template results in:
+        //
+        //   GET .../export?network_id=<template_agent_mgmt_id>
+        //                 &account_id=                           ← empty!
+        //   → 422 {"detail":[{"loc":["query","account_id"],
+        //                     "msg":"Id must be of type PydanticObjectId",
+        //                     "input":""}]}
+        //
+        // (The bogus `network_id` substitution happens because
+        // `agentInfoToNetwork` falls back to `agent.id` when
+        // `scope.network_id` is null.) The right answer is to not
+        // make the call at all — templates don't have knowledge bases
+        // in this data model.
+        //
+        // Detect templates by either `kind === "template"` (canonical,
+        // present on AgentInfo from the new agent-settings response)
+        // OR `scope.type === "NETWORK_CATEGORY"` (back-compat for any
+        // future agent kinds that also live at category scope and
+        // share the same constraint).
+        const isTemplateForKb = knownAgentInfo?.kind === "template" ||
+            knownAgentInfo?.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: config.organizationId || "",
-                        environment: config.environment || "staging",
-                    });
-                    const scope = buildScope({
-                        networkId,
-                        organizationId: client.getOrganizationId() || config.organizationId || "",
-                        accountId: client.getAccountId() || config.accountId || "",
-                    });
-                    const result = await exportToFolder(kbClient, scope, outputDir, options.withKbFiles ?? false);
-                    return { kind: "ok", result };
-                }
-                catch (kbError) {
-                    return {
-                        kind: "error",
-                        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: config.organizationId || "",
+                            environment: config.environment || "staging",
+                        });
+                        const scope = buildScope({
+                            networkId,
+                            organizationId: client.getOrganizationId() || config.organizationId || "",
+                            accountId: client.getAccountId() || config.accountId || "",
+                        });
+                        const result = await exportToFolder(kbClient, scope, outputDir, options.withKbFiles ?? false);
+                        return { kind: "ok", result };
+                    }
+                    catch (kbError) {
+                        return {
+                            kind: "error",
+                            message: kbError instanceof Error ? kbError.message : String(kbError),
+                        };
+                    }
+                })();
         const schemaPromise = (async () => {
             try {
                 const data = await fetchSchemas({
@@ -851,7 +1450,9 @@ async function doImport(client, selectedAgent, config, options, span, versionId,
         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;
@@ -902,6 +1503,11 @@ async function doImport(client, selectedAgent, config, options, span, versionId,
             gitOk,
             writtenFiles,
             dirName,
+            // Forward `kind` + `scope.type` from the cached AgentInfo so the
+            // view can show the template banner. Both default-safe (the view
+            // falls back to "regular" / no-scope-row when these are omitted).
+            kind: knownAgentInfo?.kind,
+            scopeType: knownAgentInfo?.scope?.type,
         };
         log(_jsx(ImportAgentView, { data: summaryData }));
     }
@@ -911,6 +1517,51 @@ async function doImport(client, selectedAgent, config, options, span, versionId,
         throw error;
     }
 }
+// ─── New pull endpoint (with 404 fallback to legacy export) ───
+//
+// The new bundle endpoint replaces the per-entity multi-endpoint export
+// for any agent that has been Pushed via the new endpoint. We try it
+// first and silently fall through to `exportAgent` on 404 (agent has
+// no blobs yet — typical for pre-migration agents). Other errors are
+// propagated so we don't mask auth / network issues.
+//
+// `versionTag` is optional; when omitted the server picks the version
+// row's current revision (latest successful Push on that version).
+/**
+ * Sentinel thrown by `tryPullViaBlobEndpoint` when the server reports
+ * the target agent is in records-mode. Caller catches this and
+ * dispatches to the legacy `client.exportAgent(...)` path instead.
+ * Distinct from a plain 404 (no blob revision yet) — that's a
+ * non-error, while this requires switching surfaces.
+ */
+class PullModeMismatch extends Error {
+    constructor() {
+        super("Server reports this agent is in records-mode (422)");
+        this.name = "PullModeMismatch";
+    }
+}
+async function tryPullViaBlobEndpoint(client, agentManagementId, versionId, versionTag) {
+    try {
+        return await client.agentManagement.pullVersionBlobs(agentManagementId, versionId, { versionTag });
+    }
+    catch (err) {
+        const status = err instanceof AUIAPIError ? err.status : undefined;
+        if (status === 404) {
+            // No blobs at this version (or no blob at the requested tag) yet —
+            // caller surfaces a "run aui push first" error.
+            return null;
+        }
+        if (isModeMismatchError(err)) {
+            // Server flipped `bundle_mode` since our up-front detect.
+            // Caller swaps to the legacy export branch.
+            throw new PullModeMismatch();
+        }
+        // Anything else (auth, 5xx, network) is a real failure: bubble up so
+        // the import surfaces a clear error rather than silently degrading
+        // and ending up with stale data.
+        throw err;
+    }
+}
 // ─── Response normalizers ───
 function normalizeGeneralSettings(raw) {
     if (!raw)