aui-agent-builder 0.4.0-alpha.0 → 0.4.0

package/dist/api-client/index.js

@@ -13,12 +13,13 @@
  *   - x-aui-environment: "staging" | "production"
  *   - x-aui-origin: "stores"
  */
-import fetch from "node-fetch";
+import fetch, { FetchTimeoutError } from "../utils/fetch-with-timeout.js";
 import { randomUUID } from "crypto";
 import * as fs from "fs";
 import * as path from "path";
 import { getAgentSettingsBaseUrl, getAgentSettingsWriteUrl, getAgentManagementBaseUrl, } from "../config/index.js";
-import { captureRequest } from "../utils/request-capture.js";
+import { captureRequest, formatAsCurlSafe } from "../utils/request-capture.js";
+import { trace } from "@opentelemetry/api";
 // ─── Helpers ───
 function stripTestCurlResponse(settings) {
     if (!settings || typeof settings !== "object")
@@ -72,6 +73,22 @@ export class AUIClient {
         if (scope.organizationId)
             this.organizationId = scope.organizationId;
     }
+    /**
+     * Describe the request a given call WOULD send — the resolved URL, the
+     * exact headers, the method, and the body — without issuing it. Lets a
+     * caller attach an `aui.curl_repro` / `http.url` to its command span
+     * (the secrets in the headers are redacted by `formatAsCurlSafe`) so the
+     * endpoint a command hit is visible in Logfire, mirroring the preflight /
+     * validate telemetry. The URL is built the same way `request()` does.
+     */
+    previewRequest(method, endpoint, body) {
+        return {
+            method: method.toUpperCase(),
+            url: `${this.baseUrl}/${endpoint.replace(/^\/+/, "")}`,
+            headers: this.getHeaders(),
+            body,
+        };
+    }
     /**
      * Build request headers matching the real AUI API expectations
      */
@@ -91,9 +108,20 @@ export class AUIClient {
     }
     /**
      * Make an HTTP request to the AUI backend.
+     *
      * On 401, automatically attempts a token refresh and retries once.
+     *
+     * The internal options object explicitly carries `_isRetry` (this is the
+     * second attempt after a 401-triggered refresh) and `_isRefreshCall` (this
+     * IS the refresh call itself, so a 401 here must NOT trigger another
+     * refresh — that would cause stack-overflow). Previously the refresh call
+     * was identified by URL substring match on `"token/refresh"`, which is
+     * fragile against future endpoint renames; the explicit flag removes that
+     * footgun.
      */
-    async request(method, endpoint, body, _isRetry = false) {
+    async request(method, endpoint, body, internal) {
+        const _isRetry = internal?._isRetry === true;
+        const _isRefreshCall = internal?._isRefreshCall === true;
         const url = `${this.baseUrl}/${endpoint.replace(/^\/+/, "")}`;
         const options = {
             method,
@@ -107,15 +135,18 @@ export class AUIClient {
             response = await fetch(url, options);
         }
         catch (error) {
+            // FetchTimeoutError already has a clear, structured message. Other
+            // errors get wrapped to keep the legacy "Network error: ..." prefix
+            // so existing callers / log scrapers don't break.
+            if (error instanceof FetchTimeoutError)
+                throw error;
             throw new Error(`Network error: ${error instanceof Error ? error.message : "Connection failed"}`);
         }
         if (!response.ok) {
-            if (response.status === 401 &&
-                !_isRetry &&
-                !endpoint.includes("token/refresh")) {
+            if (response.status === 401 && !_isRetry && !_isRefreshCall) {
                 const refreshed = await this.attemptTokenRefresh();
                 if (refreshed) {
-                    return this.request(method, endpoint, body, true);
+                    return this.request(method, endpoint, body, { _isRetry: true });
                 }
             }
             let errorBody;
@@ -254,8 +285,32 @@ export class AUIClient {
         loginWithOtp: (email, otp) => this.post("identity/user/login", { email, password: otp, isOTP: true }),
         /** Logout (invalidate session server-side) */
         logout: () => this.post("identity/user/logout", {}),
-        /** Exchange a refresh token for a new access + refresh token pair */
-        refreshToken: (refreshToken) => this.post("identity/user/token/refresh", { refreshToken }),
+        /**
+         * Exchange a refresh token for a new access + refresh token pair.
+         *
+         * Marked `_isRefreshCall: true` so the generic `request()` 401 handler
+         * NEVER tries to refresh-and-retry the refresh call itself (would recurse
+         * indefinitely on an expired refresh token). Internal refresh inside
+         * `_doTokenRefresh` bypasses `request()` entirely via direct `fetch`, but
+         * this public surface needs the same guarantee for external callers.
+         */
+        refreshToken: (refreshToken) => this.request("POST", "identity/user/token/refresh", { refreshToken }, { _isRefreshCall: true }),
+        /**
+         * Switch the active organization and mint a NEW access token scoped to
+         * the target org. This is the only way to obtain a token whose
+         * `organizationId` claim matches an org other than the one the user
+         * logged in with — the org-id *header* alone is advisory and the
+         * gateway trusts the token claim (so org-scoped runtime endpoints like
+         * Apollo's create-task 404 with "Agent not found" when the two
+         * diverge).
+         *
+         * Mirrors the playground's org-switch call. Authenticated by the
+         * caller's CURRENT token (sent as `x-access-token` by `getHeaders`);
+         * the TARGET org goes in the body as `{ organization }`. The response
+         * shape is read defensively by callers because the field nesting
+         * (`data.token` vs `token`) is owned by the identity service.
+         */
+        switchOrganization: (organizationId) => this.post("identity/user/switch-organization", { organization: organizationId }),
     };
     // ─── Organizations ───
     /** List and fetch organizations the current user belongs to */
@@ -322,22 +377,95 @@ export class AUIClient {
             });
             if (filters?.network_id)
                 qs.set("network_id", filters.network_id);
+            if (filters?.scope_type)
+                qs.set("scope_type", filters.scope_type);
+            if (filters?.kind)
+                qs.set("kind", filters.kind);
+            if (filters?.network_category_id)
+                qs.set("network_category_id", filters.network_category_id);
+            if (filters?.account_id)
+                qs.set("account_id", filters.account_id);
+            if (filters?.name)
+                qs.set("name", filters.name);
             const url = `${getAgentManagementBaseUrl()}/v1/agents?${qs}`;
-            const resp = await this.agentManagementFetch(url, {
+            // `list_agents` is the fallback resolver used by `aui pull` /
+            // `aui import-agent` when `.auirc` has no `agent_management_id`
+            // (legacy projects pre-PR #54). Full preflight telemetry —
+            // curl repro + truncated response — so Logfire shows which
+            // sibling agents the resolver saw and which one it picked.
+            // Mirrors the contract used by `get_agent` and `get_version`.
+            const { resp, responseText } = await this.preflightFetch({
+                name: "list_agents",
+                label: "list agents",
+                url,
                 method: "GET",
-                headers: this.agentManagementHeaders(),
-            }, "list agents");
+                extraAttrs: {
+                    organization_id: orgId,
+                    page,
+                    size,
+                    ...(filters?.network_id
+                        ? { filter_network_id: filters.network_id }
+                        : {}),
+                    ...(filters?.network_category_id
+                        ? { filter_network_category_id: filters.network_category_id }
+                        : {}),
+                    ...(filters?.scope_type ? { filter_scope_type: filters.scope_type } : {}),
+                    ...(filters?.kind ? { filter_kind: filters.kind } : {}),
+                    ...(filters?.account_id ? { filter_account_id: filters.account_id } : {}),
+                    ...(filters?.name ? { filter_name: filters.name } : {}),
+                },
+                extractAttrs: (parsed) => {
+                    const out = {};
+                    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                        const obj = parsed;
+                        if (Array.isArray(obj.items))
+                            out.items_count = obj.items.length;
+                        if (typeof obj.total === "number")
+                            out.total = obj.total;
+                        if (typeof obj.pages === "number")
+                            out.pages = obj.pages;
+                        // Capture the bundle_mode breakdown for the page — useful
+                        // when the resolver picks the "wrong" sibling on a
+                        // bundle/records mixed account.
+                        if (Array.isArray(obj.items)) {
+                            let bundleTrue = 0;
+                            let bundleFalse = 0;
+                            let bundleUnset = 0;
+                            for (const it of obj.items) {
+                                const bm = it && typeof it === "object"
+                                    ? it.bundle_mode
+                                    : undefined;
+                                if (bm === true)
+                                    bundleTrue++;
+                                else if (bm === false)
+                                    bundleFalse++;
+                                else
+                                    bundleUnset++;
+                            }
+                            out.items_bundle_mode_true = bundleTrue;
+                            out.items_bundle_mode_false = bundleFalse;
+                            out.items_bundle_mode_unset = bundleUnset;
+                        }
+                    }
+                    return out;
+                },
+            });
             if (!resp.ok) {
                 let errorBody;
                 try {
-                    errorBody = await resp.json();
+                    errorBody = JSON.parse(responseText);
                 }
                 catch {
-                    errorBody = await resp.text();
+                    errorBody = responseText || null;
                 }
                 throw new AUIAPIError(resp.status, `agents: ${resp.statusText}`, errorBody);
             }
-            return (await resp.json());
+            try {
+                return JSON.parse(responseText);
+            }
+            catch {
+                throw new AUIAPIError(resp.status, `agents: invalid JSON response`, responseText);
+            }
         },
         listVersions: async (agentId, page = 1, size = 50, filters) => {
             const qs = new URLSearchParams({
@@ -387,22 +515,69 @@ export class AUIClient {
             return (await resp.json());
         },
         getAgent: async (agentId) => {
+            // `GET /v1/agents/{id}` is the dispatch oracle for the whole CLI —
+            // every `aui import-agent`, `aui pull`, and `aui push` hits it
+            // before touching the per-entity / bundle endpoints (see
+            // `commands/util/agent-mode.ts → detectAgentBundleMode`). When
+            // a user reports "the CLI hit the wrong push endpoint" or
+            // "import keeps failing on this agent", the FIRST question is
+            // "what did the get-agent response say (especially bundle_mode)?".
+            //
+            // Telemetry is wired through `preflightFetch` (shared with
+            // `getVersion` and `listAgents`), which attaches a span event
+            // with curl repro, status, duration, and response body. Using
+            // `addEvent` (vs `setAttribute`) preserves multiple per-command
+            // calls: push's `lookupAgentManagementInfoForPush` +
+            // `resolveVersionDraft` can call `getAgent` more than once, and
+            // we want each call visible as its own log entry under the
+            // parent span.
             const url = `${getAgentManagementBaseUrl()}/v1/agents/${agentId}`;
-            const resp = await this.agentManagementFetch(url, {
+            const { resp, responseText } = await this.preflightFetch({
+                name: "get_agent",
+                label: "get agent",
+                url,
                 method: "GET",
-                headers: this.agentManagementHeaders(),
-            }, "get agent");
+                extraAttrs: { agent_id: agentId },
+                extractAttrs: (parsed, spanAttrs) => {
+                    const out = {};
+                    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                        const obj = parsed;
+                        if (typeof obj.bundle_mode === "boolean") {
+                            out.bundle_mode = obj.bundle_mode;
+                            // Also pin the most-recent observed mode at the span level
+                            // so it's filterable without expanding the event list.
+                            // Multiple calls per command overwrite — the last call
+                            // wins, which is the one whose decision actually drove
+                            // the dispatch.
+                            spanAttrs["agent.bundle_mode"] = obj.bundle_mode;
+                        }
+                        if (typeof obj.name === "string")
+                            out.agent_name = obj.name;
+                        if (typeof obj.active_version_id === "string") {
+                            out.active_version_id = obj.active_version_id;
+                        }
+                        if (typeof obj.kind === "string")
+                            out.agent_kind = obj.kind;
+                    }
+                    return out;
+                },
+            });
             if (!resp.ok) {
                 let errorBody;
                 try {
-                    errorBody = await resp.json();
+                    errorBody = JSON.parse(responseText);
                 }
                 catch {
-                    errorBody = await resp.text();
+                    errorBody = responseText || null;
                 }
                 throw new AUIAPIError(resp.status, `get agent: ${resp.statusText}`, errorBody);
             }
-            return (await resp.json());
+            try {
+                return JSON.parse(responseText);
+            }
+            catch {
+                throw new AUIAPIError(resp.status, `get agent: invalid JSON response`, responseText);
+            }
         },
         activateVersion: async (agentId, versionId) => {
             const url = `${getAgentManagementBaseUrl()}/v1/agents/${agentId}/active-version`;
@@ -443,22 +618,58 @@ export class AUIClient {
             return (await resp.json());
         },
         getVersion: async (agentId, versionId) => {
+            // `GET /v1/agents/{id}/versions/{id}` is the second preflight read
+            // every push/pull issues — it resolves the draft target (and
+            // returns the version's `status`, `version_number`, etc.). When
+            // a user reports "push failed with 422 not-a-draft" or "pull
+            // returned 404", the diff between WHAT the CLI saw here and WHAT
+            // it then sent on /push or /pull is the smoking gun. Full
+            // preflight telemetry — curl repro + truncated response — keeps
+            // both pieces of evidence in one Logfire row.
             const url = `${getAgentManagementBaseUrl()}/v1/agents/${agentId}/versions/${versionId}`;
-            const resp = await this.agentManagementFetch(url, {
+            const { resp, responseText } = await this.preflightFetch({
+                name: "get_version",
+                label: "get version",
+                url,
                 method: "GET",
-                headers: this.agentManagementHeaders(),
-            }, "get version");
+                extraAttrs: { agent_id: agentId, version_id: versionId },
+                extractAttrs: (parsed) => {
+                    const out = {};
+                    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                        const obj = parsed;
+                        if (typeof obj.status === "string")
+                            out.status = obj.status;
+                        if (typeof obj.version_number === "number") {
+                            out.version_number = obj.version_number;
+                        }
+                        if (typeof obj.version_revision_number === "number") {
+                            out.version_revision_number = obj.version_revision_number;
+                        }
+                        if (typeof obj.label === "string")
+                            out.label = obj.label;
+                        if (typeof obj.is_active === "boolean") {
+                            out.is_active = obj.is_active;
+                        }
+                    }
+                    return out;
+                },
+            });
             if (!resp.ok) {
                 let errorBody;
                 try {
-                    errorBody = await resp.json();
+                    errorBody = JSON.parse(responseText);
                 }
                 catch {
-                    errorBody = await resp.text();
+                    errorBody = responseText || null;
                 }
                 throw new AUIAPIError(resp.status, `get version: ${resp.statusText}`, errorBody);
             }
-            return (await resp.json());
+            try {
+                return JSON.parse(responseText);
+            }
+            catch {
+                throw new AUIAPIError(resp.status, `get version: invalid JSON response`, responseText);
+            }
         },
         updateVersion: async (agentId, versionId, data) => {
             const url = `${getAgentManagementBaseUrl()}/v1/agents/${agentId}/versions/${versionId}`;
@@ -626,6 +837,404 @@ export class AUIClient {
             }
             return resp.json();
         },
+        /**
+         * POST /v1/agents/{agentId}/versions/{versionId}/push
+         *
+         * JSON-only upload (multipart was retired on 2026-05-20 — see
+         * Notion "Agent Settings Push/Pull" and the OpenAPI under
+         * `PushRequestSchema`).
+         *
+         * Server flow:
+         *   1. Validates the assembled `bundle` through the v1 transcoder
+         *      BEFORE acquiring the per-version Redis lock — fail-fast 422
+         *      with a structured `BundleValidationResult` and no GCS /
+         *      Mongo writes.
+         *   2. Canonicalizes the bundle bytes (deterministic key order,
+         *      no extra whitespace), hashes with SHA-256, and writes a
+         *      single `bundle.json` blob to GCS under
+         *      `agent_id={id}/version_id={id}/version_tag={tag}/bundle.json`.
+         *   3. Bumps `version_revision_number` by exactly 1 and returns the
+         *      new `version_tag`, `gcs_key`, `sha256`, and `size` so
+         *      clients can verify integrity locally.
+         *
+         * Request body (`PushRequestSchema`):
+         *   - `caller`         : "agent_builder" | "ui" | "cli" (required)
+         *   - `commit_message` : optional save note (≤ 4000 chars after trim)
+         *   - `bundle`         : `AgentSettingsBundle` — the CLI assembles
+         *                        this from local `.aui.json` files (see
+         *                        `assembleBundleFromFiles` in `utils/`).
+         *
+         * Auth: Bearer JWT + `X-Organization-ID` (same as other v1 routes).
+         * The legacy `x-api-key` fallback is NOT honoured here — Bearer only.
+         * Push requires `update` on `agent_settings` for the target agent.
+         */
+        pushVersionBlobs: async (agentId, versionId, body) => {
+            const url = `${getAgentManagementBaseUrl()}/v1/agents/${agentId}/versions/${versionId}/push`;
+            // Defensive normalization of the request body:
+            //   - `caller` always set (TS already enforces it, but be belt+suspenders)
+            //   - `commit_message` trimmed + capped (server caps too, but the
+            //     CLI shouldn't make the server do work on bad input)
+            //   - `pushed_by` forwarded as-is when the caller supplies it
+            //     (added 2026-05-25 per backend team — recorded on the
+            //     blob revision row so revision provenance ties back to a
+            //     real user, not just a surface). Only emitted when set so
+            //     older server versions that don't read the field still
+            //     accept the request body unchanged.
+            //   - `bundle.schema_version` defaults to 1 if the caller forgot
+            const reqBody = {
+                caller: body.caller,
+                ...(body.commit_message && body.commit_message.trim()
+                    ? { commit_message: body.commit_message.trim().slice(0, 4000) }
+                    : {}),
+                ...(body.pushed_by ? { pushed_by: body.pushed_by } : {}),
+                bundle: {
+                    schema_version: body.bundle.schema_version ?? 1,
+                    ...body.bundle,
+                },
+            };
+            if (process.env.AUI_DEBUG) {
+                const b = reqBody.bundle;
+                const summary = {
+                    schema_version: b.schema_version,
+                    general_settings: b.general_settings ? "<object>" : null,
+                    parameters: b.parameters ? b.parameters.length : null,
+                    entities: b.entities ? b.entities.length : null,
+                    integrations: b.integrations ? b.integrations.length : null,
+                    rules: b.rules ? b.rules.length : null,
+                    tools: b.tools ? b.tools.length : null,
+                };
+                console.log(`[debug] POST ${url} as caller=${reqBody.caller} pushed_by=${reqBody.pushed_by ?? "(absent)"}; bundle:`, JSON.stringify(summary));
+            }
+            const headers = {
+                Accept: "application/json",
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${this.authToken}`,
+                "X-Organization-ID": this.organizationId,
+            };
+            // Bundle uploads can be moderately large (every parameter +
+            // entity + tool encoded as JSON). Cap the request at 5 minutes —
+            // long enough for a slow E2B sandbox cold-start, short enough
+            // that a truly hung request surfaces before the BFF's own
+            // pipeline timeout (BFF caps `aui push` at 5 min in
+            // `agent-builder-bff`'s `sandbox-command-client.ts:auiPush`).
+            // Override via `AUI_PUSH_TIMEOUT_MS` env var if needed (legacy
+            // `AUI_SNAPSHOT_TIMEOUT_MS` honoured too for back-compat).
+            const pushTimeoutMs = (() => {
+                const fromEnv = process.env.AUI_PUSH_TIMEOUT_MS ?? process.env.AUI_SNAPSHOT_TIMEOUT_MS;
+                if (fromEnv) {
+                    const parsed = parseInt(fromEnv, 10);
+                    if (!Number.isNaN(parsed) && parsed >= 0)
+                        return parsed;
+                }
+                return 300_000;
+            })();
+            const pushController = new AbortController();
+            const pushTimer = pushTimeoutMs > 0
+                ? setTimeout(() => pushController.abort(), pushTimeoutMs)
+                : null;
+            const pushStart = Date.now();
+            const serialized = JSON.stringify(reqBody);
+            let resp;
+            try {
+                resp = await globalThis.fetch(url, {
+                    method: "POST",
+                    headers,
+                    body: serialized,
+                    signal: pushController.signal,
+                });
+            }
+            catch (err) {
+                if (pushTimer)
+                    clearTimeout(pushTimer);
+                const elapsedMs = Date.now() - pushStart;
+                const isAbort = err instanceof Error &&
+                    (err.name === "AbortError" || pushController.signal.aborted);
+                if (isAbort && pushTimeoutMs > 0 && elapsedMs >= pushTimeoutMs - 50) {
+                    const msg = `Push blob upload timed out after ${elapsedMs}ms (limit ${pushTimeoutMs}ms): POST ${url}. ` +
+                        `Override with AUI_PUSH_TIMEOUT_MS=<ms> if your agent is unusually large.`;
+                    captureRequest({
+                        timestamp: new Date().toISOString(),
+                        method: "POST",
+                        url,
+                        headers,
+                        body: {
+                            caller: reqBody.caller,
+                            commit_message: reqBody.commit_message,
+                            pushed_by: reqBody.pushed_by,
+                            bundle_size_bytes: serialized.length,
+                        },
+                        status: 0,
+                        responseBody: msg,
+                        label: "push version blobs",
+                        success: false,
+                    });
+                    return { success: false, error: msg };
+                }
+                throw err;
+            }
+            if (pushTimer)
+                clearTimeout(pushTimer);
+            // Read the body ONCE — used for telemetry, the error envelope,
+            // and the success parse. (Web fetch bodies are single-shot.)
+            const responseText = await resp.text();
+            // Summary body for both captureRequest and the span curl. We do
+            // NOT inline the full bundle (it can be megabytes) — the
+            // reproducible signal for a push is the endpoint + the RESPONSE
+            // (new_version_tag on success, or the 422 BundleValidationResult
+            // on failure), both of which we capture in full (truncated 32KB).
+            const pushSummaryBody = {
+                caller: reqBody.caller,
+                commit_message: reqBody.commit_message,
+                pushed_by: reqBody.pushed_by,
+                bundle_size_bytes: serialized.length,
+            };
+            captureRequest({
+                timestamp: new Date().toISOString(),
+                method: "POST",
+                url,
+                headers,
+                body: pushSummaryBody,
+                status: resp.status,
+                responseBody: responseText,
+                label: "push version blobs",
+                success: resp.ok,
+            });
+            // Attach the replayable curl + response to the active span
+            // (`aui.push.task.bundle`) for BOTH success and failure, so the
+            // bundle-mode push endpoint is fully visible in Logfire — the
+            // counterpart to the records-mode per-entity write curls.
+            this.attachHttpCurlTelemetry({
+                name: "push_bundle",
+                label: "push version blobs",
+                method: "POST",
+                url,
+                headers,
+                requestBody: pushSummaryBody,
+                responseText,
+                status: resp.status,
+                success: resp.ok,
+                durationMs: Date.now() - pushStart,
+            });
+            if (!resp.ok) {
+                let errorBody;
+                try {
+                    errorBody = JSON.parse(responseText);
+                }
+                catch {
+                    errorBody = responseText;
+                }
+                if (process.env.AUI_DEBUG) {
+                    console.log(`[debug] push version blobs failed: ${resp.status} ${JSON.stringify(errorBody)}`);
+                }
+                // 422 has two flavours per the doc:
+                //   - request validation: { detail: "string" } or { detail: [{ loc, msg, type }] }
+                //   - bundle validation : BundleValidationResult JSON
+                // Surface whichever is present without losing the structured body.
+                const detail = errorBody?.detail;
+                let errorMsg;
+                if (Array.isArray(detail)) {
+                    errorMsg = detail
+                        .map((d) => `${d.msg ?? d.message ?? ""} (${(d.loc ?? []).join(".")})`)
+                        .join("; ");
+                }
+                else if (typeof detail === "string") {
+                    errorMsg = detail;
+                }
+                else if (typeof errorBody === "string") {
+                    errorMsg = errorBody;
+                }
+                else {
+                    errorMsg = JSON.stringify(errorBody);
+                }
+                return {
+                    success: false,
+                    error: `${resp.status}: ${errorMsg}`,
+                    data: errorBody,
+                };
+            }
+            let responseData;
+            try {
+                responseData = (responseText ? JSON.parse(responseText) : undefined);
+            }
+            catch {
+                responseData = undefined;
+            }
+            if (process.env.AUI_DEBUG) {
+                console.log(`[debug] push version blobs succeeded: ${JSON.stringify(responseData)}`);
+            }
+            return { success: true, data: responseData };
+        },
+        /**
+         * GET /v1/agents/{agentId}/versions/{versionId}/pull
+         *
+         * JSON-only read (signed-URL + `return_type=json` modes were
+         * retired on 2026-05-20 — the new server returns the assembled
+         * bundle inline as `PullReadResponse`).
+         *
+         * Caching: every `version_tag` is an immutable snapshot — Pull
+         * tries Redis first. `expires_at` on the response is the snapshot
+         * row's TTL, not a per-request expiry.
+         *
+         * Auth: Bearer JWT + `X-Organization-ID`. The legacy `x-api-key`
+         * fallback is NOT honoured here — Bearer only. Pull requires
+         * `read` on `agent_settings`.
+         */
+        pullVersionBlobs: async (agentId, versionId, options = {}) => {
+            const qs = new URLSearchParams();
+            if (options.versionTag)
+                qs.set("version_tag", options.versionTag);
+            const search = qs.toString();
+            const url = `${getAgentManagementBaseUrl()}/v1/agents/${agentId}/versions/${versionId}/pull${search ? `?${search}` : ""}`;
+            if (process.env.AUI_DEBUG) {
+                console.log(`[debug] GET ${url}`);
+            }
+            const pullHeaders = {
+                Accept: "application/json",
+                Authorization: `Bearer ${this.authToken}`,
+                "X-Organization-ID": this.organizationId,
+            };
+            const pullStart = Date.now();
+            const resp = await this.agentManagementFetch(url, { method: "GET", headers: pullHeaders }, "pull version blobs");
+            // Read the body ONCE — used for telemetry, the error envelope,
+            // and the success parse.
+            const responseText = await resp.text();
+            // Attach the replayable curl + response to the active span
+            // (`aui.pull` / `aui.import`) for the bundle-mode `/pull` read —
+            // the counterpart to the records-mode `/view` read curls, so the
+            // import endpoint is fully visible in Logfire for both modes.
+            this.attachHttpCurlTelemetry({
+                name: "pull_bundle",
+                label: "pull version blobs",
+                method: "GET",
+                url,
+                headers: pullHeaders,
+                responseText,
+                status: resp.status,
+                success: resp.ok,
+                durationMs: Date.now() - pullStart,
+            });
+            if (!resp.ok) {
+                let errorBody;
+                try {
+                    errorBody = JSON.parse(responseText);
+                }
+                catch {
+                    errorBody = responseText;
+                }
+                throw new AUIAPIError(resp.status, `pull version blobs: ${resp.statusText}`, errorBody);
+            }
+            return JSON.parse(responseText);
+        },
+        /**
+         * @deprecated Multipart-files upload was removed on 2026-05-20. The
+         * new server only accepts the JSON `PushBundleRequest` shape via
+         * {@link pushVersionBlobs}. Callers must assemble the bundle from
+         * local files (see `utils/assembleBundleFromFiles`) and pass it
+         * in directly.
+         */
+        pushSnapshot: async () => {
+            throw new AUIAPIError(410, "pushSnapshot is gone. The multipart /push endpoint was retired on 2026-05-20; use pushVersionBlobs with an assembled AgentSettingsBundle.");
+        },
+        /**
+         * @deprecated Signed-URL pull mode was removed on 2026-05-20. The
+         * new server returns the assembled bundle inline as
+         * {@link PullReadResponse}; consumers should call
+         * {@link pullVersionBlobs} directly and read `response.bundle`
+         * instead of paging through per-file signed URLs.
+         */
+        getSnapshot: async () => {
+            throw new AUIAPIError(410, "getSnapshot is gone. Signed-URL pull mode was retired on 2026-05-20; use pullVersionBlobs and read response.bundle.");
+        },
+        /**
+         * POST /v1/agents/{agentId}/validate
+         *
+         * Server-side validation for an agent bundle. The CLI assembles every
+         * `.aui.json` file into a flat payload and forwards it as-is — the
+         * endpoint runs the canonical pydantic + cross-reference checks that
+         * used to be duplicated in the CLI (AJV + JS, see commented-out
+         * `_validate` in commands/validate.tsx).
+         *
+         * The endpoint always returns 200 on success even when `valid: false`
+         * (the body carries per-section errors/warnings). A non-2xx response
+         * means the request itself was malformed (422) or the backend is down
+         * (5xx) and we surface it as an AUIAPIError so the caller can attach a
+         * "validation infra failure" message to its span instead of pretending
+         * the agent is valid.
+         */
+        validateAgent: async (agentId, payload) => {
+            // Validate is the only gate between local files and a partial-state
+            // push, so its span needs to be self-contained for triage: full curl
+            // repro (redacted), HTTP method/url/status, and the response body —
+            // on every call, not just failures. The push-task spans already do
+            // this; we mirror the contract here so any "why did validate say
+            // valid:false?" question can be answered straight from Logfire
+            // without re-running the CLI.
+            const url = `${getAgentManagementBaseUrl()}/v1/agents/${agentId}/validate`;
+            const method = "POST";
+            const headers = this.agentManagementWriteHeaders();
+            const bodyStr = JSON.stringify(payload);
+            const startedAt = Date.now();
+            let resp;
+            try {
+                resp = await this.agentManagementFetch(url, { method, headers, body: bodyStr }, "validate agent");
+            }
+            catch (err) {
+                // Network-level failure (ECONNREFUSED, DNS, abort, ...). The
+                // upstream catch in `_validate` already records status / message;
+                // we attach the request-side telemetry (curl + payload size +
+                // duration) before re-throwing so the trace tells the full story.
+                const networkErr = err instanceof Error ? err : new Error(String(err));
+                this.attachValidateTelemetry({
+                    method,
+                    url,
+                    headers,
+                    payload,
+                    requestBodyStr: bodyStr,
+                    responseText: networkErr.message,
+                    status: 0,
+                    success: false,
+                    durationMs: Date.now() - startedAt,
+                });
+                throw networkErr;
+            }
+            // Read once — Response bodies can only be consumed a single time
+            // and we need the same string for telemetry, error envelopes, and
+            // the success JSON parse below.
+            let responseText;
+            try {
+                responseText = await resp.text();
+            }
+            catch (e) {
+                responseText = "";
+            }
+            this.attachValidateTelemetry({
+                method,
+                url,
+                headers,
+                payload,
+                requestBodyStr: bodyStr,
+                responseText,
+                status: resp.status,
+                success: resp.ok,
+                durationMs: Date.now() - startedAt,
+            });
+            if (!resp.ok) {
+                let errorBody;
+                try {
+                    errorBody = JSON.parse(responseText);
+                }
+                catch {
+                    errorBody = responseText || null;
+                }
+                throw new AUIAPIError(resp.status, `validate agent: ${resp.statusText}`, errorBody);
+            }
+            try {
+                return JSON.parse(responseText);
+            }
+            catch {
+                throw new AUIAPIError(resp.status, `validate agent: invalid JSON response`, responseText);
+            }
+        },
     };
     async agentManagementFetch(url, init, label, _isRetry = false) {
         const resp = await fetch(url, init);
@@ -674,6 +1283,268 @@ export class AUIClient {
         });
         return resp;
     }
+    /**
+     * Attach validate-call telemetry to the currently-active span. Called on
+     * every validate request — success, validation-fail, and infra-fail —
+     * so Logfire shows the full story (curl repro, request size, response
+     * body, duration) without us having to re-run the CLI. Mirrors the
+     * shape the `writeV2` failure-path telemetry uses for push tasks, with
+     * the one difference that we attach on success too: validate is the
+     * push safety gate, so even a `valid: true` response deserves a curl
+     * in case the verdict was wrong (false negative) and someone needs to
+     * audit later.
+     *
+     * Always wrapped in a try/catch — telemetry must never break a call.
+     */
+    attachValidateTelemetry(input) {
+        try {
+            const span = trace.getActiveSpan();
+            if (!span)
+                return;
+            const MAX = 32 * 1024;
+            const truncatedResponse = input.responseText.length > MAX
+                ? input.responseText.slice(0, MAX) +
+                    `... [truncated ${input.responseText.length - MAX} bytes]`
+                : input.responseText;
+            span.setAttribute("http.method", input.method);
+            span.setAttribute("http.url", input.url);
+            // status === 0 ⇒ no HTTP response (network failure). We deliberately
+            // *omit* http.status_code in that case so dashboards filtering on
+            // `status_code = X` don't conflate "couldn't reach backend" with
+            // some real status.
+            if (input.status > 0) {
+                span.setAttribute("http.status_code", input.status);
+            }
+            span.setAttribute("validate.remote.request_payload_bytes", Buffer.byteLength(input.requestBodyStr, "utf8"));
+            span.setAttribute("validate.remote.response_body", truncatedResponse);
+            span.setAttribute("validate.remote.duration_ms", input.durationMs);
+            span.setAttribute("aui.curl_repro", formatAsCurlSafe({
+                timestamp: new Date().toISOString(),
+                method: input.method,
+                url: input.url,
+                headers: input.headers,
+                body: input.payload,
+                status: input.status,
+                responseBody: input.responseText,
+                label: "validate agent",
+                success: input.success,
+            }, { maxBodyBytes: MAX }));
+        }
+        catch {
+            // Telemetry must never break the call path.
+        }
+    }
+    /**
+     * Attach preflight HTTP telemetry to the currently-active span
+     * (typically `aui.import` / `aui.pull` / `aui.push`).
+     *
+     * The CLI fires up to three preflight reads BEFORE issuing the
+     * actual push/pull body:
+     *   1. `GET /v1/agents/{id}`               → reads `bundle_mode`
+     *   2. `GET /v1/agents/{id}/versions/{id}` → resolves the draft/version
+     *   3. `GET /v1/agents?network_id=…`       → legacy-project fallback
+     *      when `.auirc` has no `agent_management_id`.
+     *
+     * All three are essential for triaging "push hit the wrong endpoint"
+     * / "pull pulled the wrong version" reports. Each one is emitted as
+     * its own span event with the full curl repro (auth redacted),
+     * status, duration, response body (truncated), and a handful of
+     * extracted highlights pulled by `extractAttrs` (e.g. `bundle_mode`,
+     * `active_version_id`, version `status`, item counts).
+     *
+     * Best-effort throughout: telemetry must NEVER break the call path.
+     */
+    attachPreflightTelemetry(input) {
+        try {
+            const span = trace.getActiveSpan();
+            if (!span)
+                return;
+            const MAX = 32 * 1024;
+            const truncatedResponse = input.responseText.length > MAX
+                ? input.responseText.slice(0, MAX) +
+                    `... [truncated ${input.responseText.length - MAX} bytes]`
+                : input.responseText;
+            const eventAttrs = {
+                "http.method": input.method,
+                "http.url": input.url,
+                [`${input.name}.duration_ms`]: input.durationMs,
+                [`${input.name}.success`]: input.success,
+                [`${input.name}.response_body`]: truncatedResponse,
+                "aui.curl_repro": formatAsCurlSafe({
+                    timestamp: new Date().toISOString(),
+                    method: input.method,
+                    url: input.url,
+                    headers: input.headers,
+                    body: input.requestBody,
+                    status: input.status,
+                    responseBody: input.responseText,
+                    label: input.label,
+                    success: input.success,
+                }, { maxBodyBytes: MAX }),
+            };
+            // status === 0 ⇒ no HTTP response (network failure). Mirror the
+            // validate-call convention and omit `http.status_code` so
+            // dashboards filtering on status don't conflate "couldn't reach
+            // backend" with a real status.
+            if (input.status > 0) {
+                eventAttrs["http.status_code"] = input.status;
+            }
+            if (input.extraAttrs) {
+                for (const [k, v] of Object.entries(input.extraAttrs)) {
+                    eventAttrs[`${input.name}.${k}`] = v;
+                }
+            }
+            // Parse the response body once for the per-endpoint highlight
+            // extractor. The extractor can also push attributes onto the
+            // parent span (`spanAttrs`) for things that are stable across
+            // every call (e.g. `agent.bundle_mode`).
+            if (input.extractAttrs) {
+                const spanAttrs = {};
+                try {
+                    const parsed = JSON.parse(input.responseText);
+                    const extracted = input.extractAttrs(parsed, spanAttrs) || {};
+                    for (const [k, v] of Object.entries(extracted)) {
+                        eventAttrs[`${input.name}.${k}`] = v;
+                    }
+                }
+                catch {
+                    // Response wasn't JSON (network failure stringified error,
+                    // 5xx HTML page, etc.) — fall through without highlights.
+                }
+                for (const [k, v] of Object.entries(spanAttrs)) {
+                    span.setAttribute(k, v);
+                }
+            }
+            span.addEvent(input.name, eventAttrs);
+        }
+        catch {
+            // Telemetry must never break the call path.
+        }
+    }
+    /**
+     * Run a preflight `agentManagementFetch` and attach full
+     * curl+request+response telemetry to the active span. Use for
+     * `GET` reads that drive the push/pull dispatch (getAgent,
+     * getVersion, listAgents). Returns the response text so callers
+     * still parse the body themselves — keeps the existing single-
+     * read-once invariant from `getAgent` (response bodies are
+     * single-shot).
+     */
+    async preflightFetch(input) {
+        const headers = this.agentManagementHeaders();
+        const startedAt = Date.now();
+        let resp;
+        try {
+            resp = await this.agentManagementFetch(input.url, { method: input.method, headers }, input.label);
+        }
+        catch (err) {
+            const networkErr = err instanceof Error ? err : new Error(String(err));
+            this.attachPreflightTelemetry({
+                name: input.name,
+                label: input.label,
+                method: input.method,
+                url: input.url,
+                headers,
+                responseText: networkErr.message,
+                status: 0,
+                success: false,
+                durationMs: Date.now() - startedAt,
+                extraAttrs: input.extraAttrs,
+                extractAttrs: input.extractAttrs,
+            });
+            throw networkErr;
+        }
+        let responseText;
+        try {
+            responseText = await resp.text();
+        }
+        catch {
+            responseText = "";
+        }
+        this.attachPreflightTelemetry({
+            name: input.name,
+            label: input.label,
+            method: input.method,
+            url: input.url,
+            headers,
+            responseText,
+            status: resp.status,
+            success: resp.ok,
+            durationMs: Date.now() - startedAt,
+            extraAttrs: input.extraAttrs,
+            extractAttrs: input.extractAttrs,
+        });
+        return { resp, responseText };
+    }
+    /**
+     * Attach a redacted curl + request/response telemetry to the active
+     * span for the core import/push endpoints (the `/pull` & `/push`
+     * bundle routes and the records-mode `/view` reads & per-entity
+     * writes). These already land in `aui curl` (via `captureRequest`)
+     * and `.aui/push-logs/`, but were NOT visible in Logfire — so a
+     * failed bundle push or a wrong-version pull showed only a span
+     * with a bare error string. This makes the exact replayable curl +
+     * (truncated) response body part of the trace, for BOTH success and
+     * failure, in both records and bundle mode.
+     *
+     * Emits a `http.<name>` event (preserves history when several calls
+     * share one span, e.g. the ~6 `/view` reads under a single
+     * `aui.import`) AND mirrors the curl + HTTP fields onto the span
+     * itself (so a dedicated per-call task span like
+     * `aui.push.task.bundle` / `aui.push.task.<entity>` shows the curl
+     * directly in its attributes). For multi-call spans the span-level
+     * attrs are last-call-wins; the per-call events retain every curl.
+     *
+     * Best-effort throughout: telemetry must NEVER break the call path.
+     */
+    attachHttpCurlTelemetry(input) {
+        try {
+            const span = trace.getActiveSpan();
+            if (!span)
+                return;
+            const MAX = 32 * 1024;
+            const truncatedResponse = input.responseText.length > MAX
+                ? input.responseText.slice(0, MAX) +
+                    `... [truncated ${input.responseText.length - MAX} bytes]`
+                : input.responseText;
+            const curl = formatAsCurlSafe({
+                timestamp: new Date().toISOString(),
+                method: input.method,
+                url: input.url,
+                headers: input.headers,
+                body: input.requestBody,
+                status: input.status,
+                responseBody: input.responseText,
+                label: input.label,
+                success: input.success,
+            }, { maxBodyBytes: MAX });
+            const eventAttrs = {
+                "http.method": input.method,
+                "http.url": input.url,
+                [`${input.name}.success`]: input.success,
+                [`${input.name}.response_body`]: truncatedResponse,
+                "aui.curl_repro": curl,
+            };
+            if (input.status > 0)
+                eventAttrs["http.status_code"] = input.status;
+            if (typeof input.durationMs === "number") {
+                eventAttrs[`${input.name}.duration_ms`] = input.durationMs;
+            }
+            span.addEvent(`http.${input.name}`, eventAttrs);
+            // Mirror onto the span for direct visibility on dedicated
+            // per-call spans (push bundle / per-entity write task spans).
+            span.setAttribute("aui.curl_repro", curl);
+            span.setAttribute("http.method", input.method);
+            span.setAttribute("http.url", input.url);
+            span.setAttribute("http.response_body", truncatedResponse);
+            if (input.status > 0) {
+                span.setAttribute("http.status_code", input.status);
+            }
+        }
+        catch {
+            // Telemetry must never break the call path.
+        }
+    }
     agentManagementHeaders() {
         return {
             Accept: "application/json",
@@ -917,20 +1788,40 @@ export class AUIClient {
             console.log(`[debug] GET ${url}`);
         }
         const hdrs = this.agentSettingsReadHeaders();
+        const startedAt = Date.now();
         const resp = await fetch(url, { method: "GET", headers: hdrs });
+        // Read the body ONCE — used for telemetry, the error envelope, and
+        // the success parse. node-fetch bodies are single-shot.
+        const responseText = await resp.text();
         if (resp.status === 401 && !_isRetry) {
             const refreshed = await this.attemptTokenRefresh();
             if (refreshed) {
                 return this.fetchV2(path, params, true);
             }
         }
+        // Attach the replayable curl + response to the active span for the
+        // records-mode `/view` reads `aui import` / `aui pull` issue (the
+        // ~6 per-entity reads run under one `aui.import` / `aui.pull`
+        // span). Success + failure, so the import endpoints are fully
+        // visible in Logfire — not just `aui curl`.
+        this.attachHttpCurlTelemetry({
+            name: "import_view",
+            label: `GET ${path}`,
+            method: "GET",
+            url,
+            headers: hdrs,
+            responseText,
+            status: resp.status,
+            success: resp.ok,
+            durationMs: Date.now() - startedAt,
+        });
         if (!resp.ok) {
             let errorBody;
             try {
-                errorBody = await resp.json();
+                errorBody = JSON.parse(responseText);
             }
             catch {
-                errorBody = await resp.text();
+                errorBody = responseText;
             }
             if (process.env.AUI_DEBUG) {
                 console.log(`[debug] ${path} → ${resp.status}: ${JSON.stringify(errorBody)}`);
@@ -949,7 +1840,7 @@ export class AUIClient {
             err.statusCode = resp.status;
             throw err;
         }
-        const data = await resp.json();
+        const data = responseText ? JSON.parse(responseText) : {};
         captureRequest({
             timestamp: new Date().toISOString(),
             method: "GET",
@@ -1017,11 +1908,22 @@ export class AUIClient {
         }
         return new URLSearchParams(filtered).toString();
     }
+    /**
+     * Add agent-management identifiers (`agent_version_id` + `agent_id`) onto a
+     * write body when present on `params`. All agent-settings CRUD methods —
+     * parameters, scope-entities, rules, integrations, tools, general settings —
+     * funnel through here, so the CLI is the single source of truth for both
+     * fields. The BFF should NOT inject either; if you see it doing so for a
+     * subset of routes (e.g. parameters / scope-entities / rules but not
+     * integrations), that is a BFF bug to remove rather than mirror here.
+     */
     versionBody(params, body) {
-        if (params.version_id) {
-            return { ...body, agent_version_id: params.version_id };
-        }
-        return body;
+        const enriched = { ...body };
+        if (params.version_id)
+            enriched.agent_version_id = params.version_id;
+        if (params.agent_id)
+            enriched.agent_id = params.agent_id;
+        return enriched;
     }
     scopeBody(params) {
         const fields = {};
@@ -1083,6 +1985,22 @@ export class AUIClient {
             label: label || `${method} ${path}`,
             success: resp.ok,
         });
+        // Attach the replayable curl + response to the active span for
+        // BOTH success and failure (records-mode per-entity writes run
+        // inside their own `aui.push.task.<entity>` span). Previously only
+        // failures got a curl here; the owner asked for curl on every
+        // pushed endpoint so triage never depends on `.aui/push-logs/`.
+        this.attachHttpCurlTelemetry({
+            name: "entity_write",
+            label: label || `${method} ${path}`,
+            method,
+            url,
+            headers,
+            requestBody: body,
+            responseText,
+            status: resp.status,
+            success: resp.ok,
+        });
         if (this.pushLogDir) {
             this.writePushLog(method, url, headers, body, resp.status, responseText, label);
         }
@@ -1307,6 +2225,7 @@ export class AUIClient {
         const createBody = this.versionBody(params, {
             name,
             created_by: params.updated_by,
+            type: item.type || "normal",
             description: item.description || "",
             identifier: item.identifier || null,
             parameters: item.parameters || [],
@@ -1324,6 +2243,7 @@ export class AUIClient {
         });
         const patchBody = this.versionBody(params, {
             updated_by: params.updated_by,
+            type: item.type || null,
             description: item.description || null,
             identifier: item.identifier || null,
             parameters: item.parameters || null,
@@ -1353,6 +2273,7 @@ export class AUIClient {
         });
         const code = item.code;
         const createBody = this.versionBody(params, {
+            code: code,
             name: item.name || code,
             type: item.type || "API",
             settings: stripTestCurlResponse(item.settings || {}),
@@ -1370,6 +2291,7 @@ export class AUIClient {
             enable_reduce_by_scope: "true",
         });
         const patchBody = this.versionBody(params, {
+            name: item.name || null,
             updated_by: params.updated_by,
             description: item.description || null,
             settings: item.settings ? stripTestCurlResponse(item.settings) : null,
@@ -1679,22 +2601,6 @@ export class AUIClient {
         });
         return this.writeV2("PUT", "agent-tools/rules", qs, bodyWithUser, "PUT rules");
     }
-    // ─── Widget (Card Template View Mode) ───
-    /** POST /card-templates/view:generate — stateless server-side widget generation. */
-    async generateWidget(params, body) {
-        const enrichedBody = { ...body };
-        if (params.network_id)
-            enrichedBody.network_id = params.network_id;
-        if (params.account_id)
-            enrichedBody.account_id = params.account_id;
-        if (params.organization_id)
-            enrichedBody.organization_id = params.organization_id;
-        if (params.network_category_id)
-            enrichedBody.network_category_id = params.network_category_id;
-        if (params.version_id)
-            enrichedBody.agent_version_id = params.version_id;
-        return (await this.writeV2("POST", "card-templates/view:generate", "", enrichedBody, "generate widget"));
-    }
 }
 export function applyScopeLevel(params, level) {
     if (!level || level === "network")