aui-agent-builder 0.3.102 → 0.3.104

package/dist/api-client/index.js

@@ -345,6 +345,12 @@ 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);
             const url = `${getAgentManagementBaseUrl()}/v1/agents?${qs}`;
             const resp = await this.agentManagementFetch(url, {
                 method: "GET",
@@ -410,22 +416,84 @@ 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)?".
+            //
+            // To answer that straight from Logfire — without re-running the
+            // CLI with `AUI_DEBUG=1` — we attach an event on the active span
+            // (`aui.import` / `aui.pull` / `aui.push`) carrying the full
+            // curl repro (auth redacted), HTTP method/url/status, duration,
+            // and the 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, {
-                method: "GET",
-                headers: this.agentManagementHeaders(),
-            }, "get agent");
+            const method = "GET";
+            const headers = this.agentManagementHeaders();
+            const startedAt = Date.now();
+            let resp;
+            try {
+                resp = await this.agentManagementFetch(url, { method, headers }, "get agent");
+            }
+            catch (err) {
+                // Network-level failure (DNS, ECONNREFUSED, timeout, abort, ...).
+                // Attach the request-side telemetry before re-throwing so the
+                // span tells the full story even when there's no HTTP response.
+                const networkErr = err instanceof Error ? err : new Error(String(err));
+                this.attachGetAgentTelemetry({
+                    method,
+                    url,
+                    headers,
+                    agentId,
+                    responseText: networkErr.message,
+                    status: 0,
+                    success: false,
+                    durationMs: Date.now() - startedAt,
+                });
+                throw networkErr;
+            }
+            // Read the body ONCE — Response bodies are single-shot and we
+            // need the same string for telemetry, error envelopes, and the
+            // success JSON parse below. Mirrors the validate-call path.
+            let responseText;
+            try {
+                responseText = await resp.text();
+            }
+            catch {
+                responseText = "";
+            }
+            this.attachGetAgentTelemetry({
+                method,
+                url,
+                headers,
+                agentId,
+                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 || 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`;
@@ -650,34 +718,89 @@ export class AUIClient {
             return resp.json();
         },
         /**
-         * POST /v1/agents/{agentId}/versions/{versionId}/snapshot
-         * Pushes local files as a version snapshot via multipart form data.
-         * Uses JWT auth (Bearer token). Bump is automatic on success.
+         * 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.
          */
-        pushSnapshot: async (agentId, versionId, files) => {
-            const url = `${getAgentManagementBaseUrl()}/v1/agents/${agentId}/versions/${versionId}/snapshot`;
-            const fd = new FormData();
-            for (const file of files) {
-                fd.append("files", new File([file.content], file.fileName, { type: "application/json" }));
-            }
+        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) {
-                console.log(`[debug] POST ${url}`);
-                console.log(`[debug] Uploading ${files.length} file(s): ${files.map((f) => f.fileName).join(", ")}`);
+                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,
             };
-            // Snapshot uploads can legitimately be large (entire agent file set
-            // multipart-uploaded). Cap at 5 minutes — long enough for a 50-file
-            // snapshot on 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 per-call via
-            // `AUI_SNAPSHOT_TIMEOUT_MS` env var if needed.
-            const snapshotTimeoutMs = (() => {
-                const fromEnv = process.env.AUI_SNAPSHOT_TIMEOUT_MS;
+            // 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)
@@ -685,56 +808,65 @@ export class AUIClient {
                 }
                 return 300_000;
             })();
-            const snapshotController = new AbortController();
-            const snapshotTimer = snapshotTimeoutMs > 0
-                ? setTimeout(() => snapshotController.abort(), snapshotTimeoutMs)
+            const pushController = new AbortController();
+            const pushTimer = pushTimeoutMs > 0
+                ? setTimeout(() => pushController.abort(), pushTimeoutMs)
                 : null;
-            const snapshotStart = Date.now();
+            const pushStart = Date.now();
+            const serialized = JSON.stringify(reqBody);
             let resp;
             try {
                 resp = await globalThis.fetch(url, {
                     method: "POST",
                     headers,
-                    body: fd,
-                    signal: snapshotController.signal,
+                    body: serialized,
+                    signal: pushController.signal,
                 });
             }
             catch (err) {
-                if (snapshotTimer)
-                    clearTimeout(snapshotTimer);
-                const elapsedMs = Date.now() - snapshotStart;
+                if (pushTimer)
+                    clearTimeout(pushTimer);
+                const elapsedMs = Date.now() - pushStart;
                 const isAbort = err instanceof Error &&
-                    (err.name === "AbortError" || snapshotController.signal.aborted);
-                if (isAbort && snapshotTimeoutMs > 0 && elapsedMs >= snapshotTimeoutMs - 50) {
-                    // Loud, structured failure so Logfire / push-logs / BFF logs all
-                    // see the same wording — never silently retry forever.
-                    const msg = `Snapshot upload timed out after ${elapsedMs}ms (limit ${snapshotTimeoutMs}ms): POST ${url}. ` +
-                        `Override with AUI_SNAPSHOT_TIMEOUT_MS=<ms> if your agent is unusually large.`;
+                    (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: { files: files.map((f) => f.fileName) },
+                        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 snapshot",
+                        label: "push version blobs",
                         success: false,
                     });
-                    return { success: false, failed: files.map((f) => f.fileName), error: msg };
+                    return { success: false, error: msg };
                 }
                 throw err;
             }
-            if (snapshotTimer)
-                clearTimeout(snapshotTimer);
+            if (pushTimer)
+                clearTimeout(pushTimer);
             captureRequest({
                 timestamp: new Date().toISOString(),
                 method: "POST",
                 url,
                 headers,
-                body: { files: files.map((f) => f.fileName) },
+                body: {
+                    caller: reqBody.caller,
+                    commit_message: reqBody.commit_message,
+                    pushed_by: reqBody.pushed_by,
+                    bundle_size_bytes: serialized.length,
+                },
                 status: resp.status,
-                label: "push snapshot",
+                label: "push version blobs",
                 success: resp.ok,
             });
             if (!resp.ok) {
@@ -746,37 +878,67 @@ export class AUIClient {
                     errorBody = await resp.text();
                 }
                 if (process.env.AUI_DEBUG) {
-                    console.log(`[debug] snapshot push failed: ${resp.status} ${JSON.stringify(errorBody)}`);
+                    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;
-                const errorMsg = Array.isArray(detail)
-                    ? detail.map((d) => `${d.msg} (${d.loc?.join(".")})`).join("; ")
-                    : typeof errorBody === "string" ? errorBody : JSON.stringify(errorBody);
-                const failedFiles = errorBody?.failed ?? files.map((f) => f.fileName);
-                return { success: false, failed: failedFiles, error: `${resp.status}: ${errorMsg}`, data: errorBody };
+                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 = await resp.json();
+                responseData = (await resp.json());
             }
             catch {
-                responseData = null;
+                responseData = undefined;
             }
             if (process.env.AUI_DEBUG) {
-                console.log(`[debug] snapshot push succeeded: ${JSON.stringify(responseData)}`);
+                console.log(`[debug] push version blobs succeeded: ${JSON.stringify(responseData)}`);
             }
-            return { success: true, failed: [], data: responseData };
+            return { success: true, data: responseData };
         },
         /**
-         * GET /v1/agents/{agentId}/versions/{versionId}/snapshot
-         * Retrieves the snapshot manifest + signed download URLs for a version_tag.
+         * 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`.
          */
-        getSnapshot: async (agentId, versionId, options) => {
+        pullVersionBlobs: async (agentId, versionId, options = {}) => {
             const qs = new URLSearchParams();
-            qs.set("version_tag", options.versionTag);
-            if (options.expiresIn)
-                qs.set("expires_in", String(options.expiresIn));
-            const url = `${getAgentManagementBaseUrl()}/v1/agents/${agentId}/versions/${versionId}/snapshot?${qs}`;
+            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}`);
             }
@@ -787,7 +949,7 @@ export class AUIClient {
                     Authorization: `Bearer ${this.authToken}`,
                     "X-Organization-ID": this.organizationId,
                 },
-            }, "get snapshot");
+            }, "pull version blobs");
             if (!resp.ok) {
                 let errorBody;
                 try {
@@ -796,9 +958,29 @@ export class AUIClient {
                 catch {
                     errorBody = await resp.text();
                 }
-                throw new AUIAPIError(resp.status, `get snapshot: ${resp.statusText}`, errorBody);
+                throw new AUIAPIError(resp.status, `pull version blobs: ${resp.statusText}`, errorBody);
             }
-            return resp.json();
+            return (await resp.json());
+        },
+        /**
+         * @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
@@ -989,6 +1171,92 @@ export class AUIClient {
             // Telemetry must never break the call path.
         }
     }
+    /**
+     * Attach `GET /v1/agents/{id}` telemetry to the currently-active span
+     * (typically `aui.import` / `aui.pull` / `aui.push`). The CLI calls
+     * this endpoint before every import/pull/push to read `bundle_mode`
+     * and decide which surface to use — so making every call self-
+     * describing in Logfire (curl repro, status, response body, duration)
+     * answers "did the CLI even know the right mode?" without re-running
+     * locally. See the comment block in `getAgent` for the rationale.
+     *
+     * Best-effort throughout: telemetry must NEVER break the call path.
+     */
+    attachGetAgentTelemetry(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;
+            // Best-effort: surface `bundle_mode` as its own event attribute
+            // so dashboards can filter "show me every push where the agent
+            // reported bundle_mode=false" without grepping response bodies.
+            let bundleMode;
+            let agentName;
+            let activeVersionId;
+            try {
+                const parsed = JSON.parse(input.responseText);
+                if (typeof parsed.bundle_mode === "boolean") {
+                    bundleMode = parsed.bundle_mode;
+                }
+                if (typeof parsed.name === "string")
+                    agentName = parsed.name;
+                if (typeof parsed.active_version_id === "string") {
+                    activeVersionId = parsed.active_version_id;
+                }
+            }
+            catch {
+                // Response wasn't JSON (network failure stringified error,
+                // 5xx HTML page, etc.) — fall through with bundleMode unset.
+            }
+            const eventAttrs = {
+                "http.method": input.method,
+                "http.url": input.url,
+                "get_agent.agent_id": input.agentId,
+                "get_agent.duration_ms": input.durationMs,
+                "get_agent.success": input.success,
+                "get_agent.response_body": truncatedResponse,
+                "aui.curl_repro": formatAsCurlSafe({
+                    timestamp: new Date().toISOString(),
+                    method: input.method,
+                    url: input.url,
+                    headers: input.headers,
+                    status: input.status,
+                    responseBody: input.responseText,
+                    label: "get agent",
+                    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 (typeof bundleMode === "boolean") {
+                eventAttrs["get_agent.bundle_mode"] = bundleMode;
+                // 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.
+                span.setAttribute("agent.bundle_mode", bundleMode);
+            }
+            if (agentName)
+                eventAttrs["get_agent.agent_name"] = agentName;
+            if (activeVersionId) {
+                eventAttrs["get_agent.active_version_id"] = activeVersionId;
+            }
+            span.addEvent("get_agent", eventAttrs);
+        }
+        catch {
+            // Telemetry must never break the call path.
+        }
+    }
     agentManagementHeaders() {
         return {
             Accept: "application/json",