aui-agent-builder 0.3.104 → 0.3.106

package/dist/commands/import-agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"import-agent.d.ts","sourceRoot":"","sources":["../../src/commands/import-agent.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAwDH,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,OAAO,wBAAwB,EAAE,UAAU,CAAC;IACzD,MAAM,CAAC,EAAE,OAAO,oCAAoC,EAAE,WAAW,EAAE,CAAC;IACpE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAmED,wBAAsB,WAAW,CAC/B,OAAO,CAAC,EAAE,MAAM,EAChB,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAiBf;AA0PD,wBAAsB,sBAAsB,CAC1C,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAgBf;AAoFD,wBAAsB,kBAAkB,CACtC,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAgBf"}
+{"version":3,"file":"import-agent.d.ts","sourceRoot":"","sources":["../../src/commands/import-agent.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAwDH,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,OAAO,wBAAwB,EAAE,UAAU,CAAC;IACzD,MAAM,CAAC,EAAE,OAAO,oCAAoC,EAAE,WAAW,EAAE,CAAC;IACpE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAmED,wBAAsB,WAAW,CAC/B,OAAO,CAAC,EAAE,MAAM,EAChB,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAiBf;AAqVD,wBAAsB,sBAAsB,CAC1C,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAgBf;AAoFD,wBAAsB,kBAAkB,CACtC,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAgBf"}

package/dist/commands/import-agent.js

@@ -128,69 +128,148 @@ async function _importAgent(parentSpan, agentId, options = {}) {
         // 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.
+        // Resolution order (first success wins, then 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):
+        //
+        //   0) listAgents with BOTH `network_id=<input>` AND
+        //      `network_category_id=<input>` — handles the case where the
+        //      input is either a legacy `network_id` (regular agent) or a
+        //      `network_category_id` (template). The server OR's the two
+        //      filters, so a single call covers both shapes (verified
+        //      2026-05-27 against staging — see thread with Adli). If the
+        //      input is actually an `agent_management_id`, listAgents
+        //      returns no items (an agent_management_id is almost never
+        //      also a network_id / category_id of a DIFFERENT agent), and
+        //      we fall through to step 1.
+        //
+        //      Originally added (2026-05-26) as a [TEMP] workaround for
+        //      the BFF passing `network_id` instead of `agent_management_id`.
+        //      Promoted to the canonical first step once we extended it
+        //      to also resolve `network_category_id` — there is no longer
+        //      a "remove once the BFF migrates" exit condition because the
+        //      template case has no other resolver (templates never appear
+        //      in `networks.get` and `getAgent(category_id)` 404s).
+        //
+        //   1) getAgent(<input>) — treat the id as an agent_management_id.
+        //      Still the canonical path for callers that already have it.
+        //
+        //   2) networks.get(<input>) — last-ditch legacy networks lookup.
+        //      Kept for back-compat with old scripts that have neither
+        //      flow available (e.g. agent-management endpoint down).
         const spinner = startSpinner("Fetching agent...");
         let resolved = false;
         let lastErr;
-        // 1) Treat the id as an agent-management UUID.
+        // 0) listAgents with both `network_id` and `network_category_id`
+        //    set to the input id — server OR's the filters, returning
+        //    either a regular agent (matched by `scope.network_id`) or a
+        //    template (matched by `scope.network_category_id`). If the
+        //    input is actually an `agent_management_id`, neither filter
+        //    matches and we fall through to step 1.
         try {
-            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);
+            const resp = await client.agentManagement.listAgents(client.getOrganizationId(), 1, 50, {
+                network_id: effectiveAgentId,
+                network_category_id: effectiveAgentId,
+            });
+            // `find` (not `[0]`) to be defensive about the server returning
+            // unrelated rows. We require `scope.network_id === <input>` for
+            // the regular-agent case OR `scope.network_category_id === <input>`
+            // for the template case so siblings on the same listing page
+            // can't accidentally win.
+            const match = resp.items.find((a) => a.scope.network_id === effectiveAgentId ||
+                a.scope.network_category_id === effectiveAgentId);
+            if (match) {
+                knownAgentInfo = match;
+                selectedAgent = agentInfoToNetwork(match);
+                // Bias scope toward the agent's own org/account (mirrors the
+                // step-1 success branch — keep both in sync). Templates have
+                // `scope.account_id === null` (category-scoped, not account-
+                // scoped) — skipping the scope update in that case keeps the
+                // session's org context as-is, which is what downstream
+                // template flows expect.
+                const scopeUpdate = {};
+                if (match.scope?.account_id)
+                    scopeUpdate.accountId = match.scope.account_id;
+                if (match.scope?.organization_id)
+                    scopeUpdate.organizationId = match.scope.organization_id;
+                if (scopeUpdate.accountId || scopeUpdate.organizationId) {
+                    client.setScope(scopeUpdate);
+                }
+                const matchedVia = match.scope.network_id === effectiveAgentId
+                    ? "network_id"
+                    : "network_category_id";
+                spinner.succeed(`Found agent (via listAgents ${matchedVia} lookup): ${match.name}`);
+                resolved = true;
+            }
+            else if (process.env.AUI_DEBUG) {
+                console.log(`[debug] listAgents(network_id=${effectiveAgentId}, network_category_id=${effectiveAgentId}) returned ${resp.items.length} row(s) but none matched; trying getAgent next`);
             }
-            spinner.succeed(`Found agent (via agent-management): ${ami.name}`);
-            resolved = true;
         }
         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;
-            }
+            // Listing failed (auth / 5xx / org context wrong). Don't bail
+            // — fall through to the existing dual-shape resolution. Worst
+            // case we make the same call sequence we'd have made before
+            // this resolver was added.
             if (process.env.AUI_DEBUG) {
-                console.log(`[debug] agentManagement.getAgent(${effectiveAgentId}) → ${status ?? "non-auth error"}; trying legacy networks.get next`);
+                console.log(`[debug] listAgents(network_id=${effectiveAgentId}, network_category_id=${effectiveAgentId}) failed: ${err instanceof Error ? err.message : err}; trying getAgent next`);
             }
         }
+        // 1) Treat the id as an agent-management UUID.
+        if (!resolved) {
+            try {
+                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 (via agent-management): ${ami.name}`);
+                resolved = true;
+            }
+            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`);
+                }
+            }
+        } // close: if (!resolved) — wrapping step 1 (added with step 0 above)
         // 2) Fall back: treat the id as a legacy network_id.
         if (!resolved) {
             try {
@@ -1035,55 +1114,72 @@ knownAgentInfo) {
             }
         }
     }
-    // ─── Use the new pull endpoint (strict, no legacy fallback) ───
+    // ─── Mode dispatch (with pure-legacy short-circuit) ─────────────
+    //
+    // Three layers, in order:
+    //
+    //   1. No agent_management_id at all (pure legacy)
+    //      → The agent exists in `networks` (step 2 of resolution) but
+    //        not in agent-management. It predates the agent-management
+    //        rollout entirely, which means it predates `bundle_mode`,
+    //        which means it can only be records-mode. Skip the
+    //        `detectAgentBundleMode` call (it'd need an
+    //        agent_management_id we don't have) and force-route to
+    //        records-mode dispatch. `exportAgent(...)` is happy with
+    //        scope filters alone — no agent_management_id needed.
     //
-    // 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.
+    //        Concrete repro (2026-05-26): `aui import 6a0cb854...` (a
+    //        legacy `test-v15` network) found the agent via
+    //        `networks.get` but `listAgents(network_id=…)` returned
+    //        nothing. Without this branch, the import bailed with
+    //        "Could not resolve agent_management_id for this agent"
+    //        even though `exportAgent` would have worked.
     //
-    // 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) {
+    //   2. Agent_management_id present → call `detectAgentBundleMode`
+    //      to read the agent's `bundle_mode` flag. Routes to /pull
+    //      (bundle) or per-entity /view (records) accordingly.
+    //
+    //   3. Bundle mode + no version_id → hard error. /pull is keyed
+    //      on version_id in the URL and can't fall back to scope
+    //      filters. Records-mode + no version_id is fine —
+    //      `exportAgent` handles it via scope-level filters.
+    let importModeResolution;
+    if (!effectiveAgentMgmtId) {
+        // (1) Pure legacy — force records mode, skip the dispatcher call
+        // entirely (it'd throw since we have no id to pass it).
+        importModeResolution = { mode: "records", source: "no_agent_management_id" };
+        if (process.env.AUI_DEBUG) {
+            console.log(`[debug] doImport: no agent_management_id for network ${networkId} — forcing records-mode dispatch (pure-legacy agent)`);
+        }
+    }
+    else {
+        // (2) Normal dispatch path — agent_management_id resolved, ask
+        // the server which mode to use. Reuses `knownAgentInfo` so we
+        // don't pay an extra `GET /v1/agents/{id}` round-trip.
+        importModeResolution = await detectAgentBundleMode(client, effectiveAgentMgmtId, knownAgentInfo);
+    }
+    // (3) Bundle mode requires version_id. Records mode doesn't —
+    // `exportAgent` falls back to scope filters when versionId is
+    // undefined (the legacy contract that's been in the CLI since
+    // before version management existed).
+    if (importModeResolution.mode === "bundle" && !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.",
+            suggestion: "Pass --version <versionId>, or re-run `aui import` interactively so a version can be selected. " +
+                "Bundle-mode agents must have at least one push (creates v{N}.1) before they can be imported via /pull. " +
+                "If this is a fresh bundle-mode agent, run `aui push` from the source project first, then re-import.",
         });
     }
-    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=…)`).",
+    // Bundle mode ALSO requires an agent_management_id (it's in the
+    // /pull URL path). This was implicit before — `detectAgentBundleMode`
+    // would have thrown — but now that we short-circuit to records when
+    // agent_management_id is missing, we should only ever reach this
+    // branch when bundle mode was a real positive detection. Keep the
+    // guard for defensive symmetry with the records path above.
+    if (importModeResolution.mode === "bundle" && !effectiveAgentMgmtId) {
+        throw new ConfigError("Could not resolve agent_management_id for this bundle-mode agent.", {
+            suggestion: "Pass the agent_management_id directly as the positional arg, or verify 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);
@@ -1203,6 +1299,13 @@ knownAgentInfo) {
         }
         else {
             // ─── Blob-mode (new /pull endpoint) ─────────────────────────
+            //
+            // `versionId!` assertion: we reach this branch only when
+            // `useLegacyImport === false` (bundle mode), and the conditional
+            // throw above ("No version_id available for the new /pull
+            // endpoint.") already guarantees `versionId` is defined in
+            // that case. TS can't narrow across the throw, so the
+            // assertion is documented intent rather than a hand-wave.
             let pullData = null;
             try {
                 pullData = await tryPullViaBlobEndpoint(client, effectiveAgentMgmtId, versionId, options.tag);