@superblocksteam/gateway 2.0.177-next.0 → 2.0.178-next.0

package/dist/server/client.js

@@ -1,5 +1,7 @@
 import { llmConfigFromFlags, } from "@superblocksteam/library-shared/types";
-import { uploadAttachmentToServerApi } from "@superblocksteam/shared";
+import { errorCode, isLostConnection, isRequestNotSent, isTransientHttpStatus, MIN_RETRY_ATTEMPT_MS, ReadRetrySchedule, } from "@superblocksteam/mcp-server/read-retry";
+import { PlatformMcpServerRequest, uploadAttachmentToServerApi, } from "@superblocksteam/shared";
+import { internalIngress } from "../internal-ingress.js";
 import { recordFactsFlagBootstrapOutcome, recordIdentityReadOutcome, recordServerReadRetryOutcome, } from "../telemetry/metrics.js";
 import { withGuardedIdentityReads, } from "./identity-reads.js";
 const MAX_DETAIL_LENGTH = 300;
@@ -54,51 +56,6 @@ export class ServerTimeoutError extends Error {
         this.name = "ServerTimeoutError";
     }
 }
-const RETRYABLE_TRANSPORT_CODES = new Set([
-    "EAI_AGAIN",
-    "ECONNABORTED",
-    "ECONNREFUSED",
-    "ECONNRESET",
-    "EHOSTUNREACH",
-    "ENETDOWN",
-    "ENETUNREACH",
-    "EPIPE",
-    "ETIMEDOUT",
-    "UND_ERR_BODY_TIMEOUT",
-    "UND_ERR_CONNECT_TIMEOUT",
-    "UND_ERR_HEADERS_TIMEOUT",
-    "UND_ERR_SOCKET",
-]);
-const UNSENT_TRANSPORT_CODES = new Set([
-    "EAI_AGAIN",
-    "ECONNREFUSED",
-    "EHOSTUNREACH",
-    "ENETDOWN",
-    "ENETUNREACH",
-    "UND_ERR_CONNECT_TIMEOUT",
-]);
-function errorCode(error, depth = 0) {
-    if (depth >= 4 || !error || typeof error !== "object") {
-        return undefined;
-    }
-    const { cause, code } = error;
-    if (typeof code === "string") {
-        return code;
-    }
-    const causeCode = errorCode(cause, depth + 1);
-    if (causeCode) {
-        return causeCode;
-    }
-    if (error instanceof AggregateError) {
-        for (const nested of error.errors) {
-            const nestedCode = errorCode(nested, depth + 1);
-            if (nestedCode) {
-                return nestedCode;
-            }
-        }
-    }
-    return undefined;
-}
 /**
  * The connection failed: refused, reset, or dropped before the answer was
  * complete. Named so a retry can cover it without also covering a response
@@ -118,10 +75,8 @@ export class ServerTransportError extends Error {
         this.name = "ServerTransportError";
         this.code = code;
         this.requestNotSent =
-            options.requestNotSent === true &&
-                code !== undefined &&
-                UNSENT_TRANSPORT_CODES.has(code);
-        this.retryable = code !== undefined && RETRYABLE_TRANSPORT_CODES.has(code);
+            options.requestNotSent === true && isRequestNotSent(options.cause);
+        this.retryable = isLostConnection(options.cause);
     }
 }
 /**
@@ -144,6 +99,10 @@ const DEFAULT_TIMEOUT_MS = 120_000;
  * rather than never can still finish and fill the cache.
  */
 const DEFAULT_IDENTITY_TIMEOUT_MS = 30_000;
+/** The live-edit connect route, on the branch when there is one. */
+const liveEditConnectRequest = (applicationId, branch) => branch
+    ? PlatformMcpServerRequest.to("GET /api/v3/applications/*/branches/*/connect", applicationId, branch)
+    : PlatformMcpServerRequest.to("GET /api/v3/applications/*/connect", applicationId);
 /**
  * Whether a failed identity read means the endpoint is unhealthy rather than
  * that this one credential is bad.
@@ -162,72 +121,15 @@ const DEFAULT_IDENTITY_TIMEOUT_MS = 30_000;
 function identityEndpointUnhealthy(error) {
     return !(error instanceof ServerHttpError && !isTransientHttpStatus(error.status));
 }
-function isTransientHttpStatus(status) {
-    return status >= 500 || status === 429;
-}
 /**
- * How long a read waits before each re-send, by what failed it.
- *
- * Only reads are retried, and only because the call sites that leave `retry`
- * on are pure lookups: a repeat of one changes nothing. A failed POST may well
- * have taken effect, and re-sending one can deploy or commit twice; a read
- * that provisions, or that already sits in its own poll loop, opts out.
- *
- * A transient status is a fast answer from a route that is up, so a short
- * pause is enough. 429 counts as transient alongside 5xx: it is the route
- * reporting its own capacity, and backing off is the whole point of it.
- * Retry-After replaces that pause when it is at most five seconds; a longer
- * server window is surfaced immediately rather than parking a tool call.
- *
- * A lost connection is usually a deployment rolling through the API, which
- * refuses and resets connections for a few seconds. This schedule waits that
- * out, and still finishes well inside the ten seconds a tool call waits on
- * identity. A timeout is never retried: that attempt already spent its whole
- * bound, and sending it again spends another.
- *
- * Each delay is one retry: transient statuses get two, lost connections get
- * four.
+ * What failed one attempt, in the terms {@link ReadRetrySchedule} judges.
+ * Anything else, such as an answer that did not parse, is never retried.
  */
-const TRANSIENT_STATUS_RETRY_DELAYS_MS = [100, 200];
-const LOST_CONNECTION_RETRY_DELAYS_MS = [250, 500, 1_000, 2_000];
-const MAX_RETRY_AFTER_MS = 5_000;
-const MIN_RETRY_ATTEMPT_MS = 50;
-function jitter(delayMs) {
-    return Math.ceil(delayMs * (0.75 + Math.random() * 0.25));
-}
-function jitterAfterMinimum(delayMs) {
-    return Math.ceil(delayMs * (1 + Math.random() * 0.25));
-}
-class ReadRetrySchedule {
-    lostConnections = 0;
-    transientStatuses = 0;
-    next(error) {
-        if (error instanceof ServerHttpError) {
-            if (!isTransientHttpStatus(error.status)) {
-                return undefined;
-            }
-            const delayMs = TRANSIENT_STATUS_RETRY_DELAYS_MS[this.transientStatuses++];
-            if (delayMs === undefined) {
-                return "exhausted";
-            }
-            if (error.retryAfterMs === undefined) {
-                return { cause: "http", waitMs: jitter(delayMs) };
-            }
-            return error.retryAfterMs > MAX_RETRY_AFTER_MS
-                ? undefined
-                : {
-                    cause: "http",
-                    waitMs: jitterAfterMinimum(Math.max(delayMs, error.retryAfterMs)),
-                };
-        }
-        if (error instanceof ServerTransportError && error.retryable) {
-            const delayMs = LOST_CONNECTION_RETRY_DELAYS_MS[this.lostConnections++];
-            return delayMs === undefined
-                ? "exhausted"
-                : { cause: "transport", waitMs: jitter(delayMs) };
-        }
-        return undefined;
-    }
+function readFailure(error) {
+    return error instanceof ServerHttpError ||
+        error instanceof ServerTransportError
+        ? error
+        : undefined;
 }
 function parseRetryAfterMs(value) {
     const retryAfter = value?.trim();
@@ -379,6 +281,14 @@ export class HttpSuperblocksServerClient {
             ...options.identityReads,
         });
     }
+    async reportMcpUsage(input) {
+        await this.request(PlatformMcpServerRequest.to("POST /api/v1/builder-usage"), {
+            apiKey: input.apiKey,
+            body: JSON.stringify(input.event),
+            retry: false,
+            timeoutMs: 1000,
+        });
+    }
     baseUrl() {
         return this.serverUrl.replace(/\/$/, "");
     }
@@ -390,10 +300,10 @@ export class HttpSuperblocksServerClient {
      * every field, which is indistinguishable from a legitimately empty response
      * — so this is deliberately strict rather than falling back to the raw body.
      */
-    async requestData(path, init) {
-        const body = await this.request(path, init);
+    async requestData(target, init) {
+        const body = await this.request(target, init);
         if (body?.data === undefined) {
-            throw new Error(`Server ${path} returned no data field; expected a { responseMeta, data } envelope`);
+            throw new Error(`Server ${target.path} returned no data field; expected a { responseMeta, data } envelope`);
         }
         return body.data;
     }
@@ -408,8 +318,9 @@ export class HttpSuperblocksServerClient {
      * lost connection used to fail on first sight, which is how a build's poll
      * loop lost its caller's identity while a deployment rolled through the API.
      */
-    async request(path, init) {
-        const method = (init.method ?? "GET").toUpperCase();
+    async request(target, { query, ...init }) {
+        const path = query ? `${target.path}?${query}` : target.path;
+        const method = target.method;
         const repeatSafe = init.retry ?? method === "GET";
         const retries = new ReadRetrySchedule();
         const timeoutMs = init.timeoutMs ?? this.timeoutMs;
@@ -431,6 +342,7 @@ export class HttpSuperblocksServerClient {
                 try {
                     const result = await this.send(path, {
                         ...init,
+                        method,
                         timeoutMs: remainingMs,
                     });
                     if (retryCause) {
@@ -455,7 +367,7 @@ export class HttpSuperblocksServerClient {
                         (method === "GET" &&
                             error instanceof ServerTransportError &&
                             error.requestNotSent)
-                        ? retries.next(error)
+                        ? retries.next(readFailure(error))
                         : undefined;
                     if (retry === undefined || retry === "exhausted") {
                         retryExhausted = retryCause !== undefined && retry === "exhausted";
@@ -558,9 +470,8 @@ export class HttpSuperblocksServerClient {
     /** The unguarded read behind {@link validateApiKey}. */
     async readIdentityFromServer(apiKey) {
         try {
-            const data = await this.requestData("/api/v1/users/me", {
+            const data = await this.requestData(PlatformMcpServerRequest.to("GET /api/v1/users/me"), {
                 apiKey,
-                method: "GET",
                 operation: "identity",
                 timeoutMs: this.identityTimeoutMs,
             });
@@ -586,9 +497,8 @@ export class HttpSuperblocksServerClient {
         }
     }
     async getAgentInventory(input) {
-        const data = await this.requestData("/api/v1/users/me", {
+        const data = await this.requestData(PlatformMcpServerRequest.to("GET /api/v1/users/me"), {
             apiKey: input.apiKey,
-            method: "GET",
             operation: "identity",
             // Same route, so the same bound. This one runs on the build path rather
             // than per tool call, and left at the sandbox timeout a wedged
@@ -631,7 +541,7 @@ export class HttpSuperblocksServerClient {
         };
     }
     async createApplication(input) {
-        return this.requestData("/api/v2/applications/", {
+        return this.requestData(PlatformMcpServerRequest.to("POST /api/v2/applications/"), {
             apiKey: input.apiKey,
             // Live edit only attaches to code-mode apps; without this the server
             // builds a legacy DSL app and `connect` rejects it.
@@ -641,7 +551,6 @@ export class HttpSuperblocksServerClient {
                 organizationId: input.organizationId,
                 ...(input.templateName ? { templateName: input.templateName } : {}),
             }),
-            method: "POST",
             ...(input.signal ? { signal: input.signal } : {}),
             ...(input.timeoutMs === undefined
                 ? {}
@@ -678,10 +587,7 @@ export class HttpSuperblocksServerClient {
     }
     async connectLiveEdit(input) {
         const deadlineAtMs = Date.now() + this.timeoutMs;
-        const branchSegment = input.branch
-            ? `/branches/${encodeURIComponent(input.branch)}`
-            : "";
-        const path = `/api/v3/applications/${input.applicationId}${branchSegment}/connect`;
+        const connect = liveEditConnectRequest(input.applicationId, input.branch);
         let liveEditId = "session";
         const deadlineError = () => new Error(`Live edit ${liveEditId} did not become active within ${this.timeoutMs}ms`);
         const requestBeforeDeadline = async (query) => {
@@ -689,9 +595,9 @@ export class HttpSuperblocksServerClient {
                 throw deadlineError();
             }
             try {
-                return await this.requestData(`${path}${query}`, {
+                return await this.requestData(connect, {
                     apiKey: input.apiKey,
-                    method: "GET",
+                    query,
                     operation: "live_edit",
                     retry: false,
                     timeoutMs: Math.max(1, deadlineAtMs - Date.now()),
@@ -704,7 +610,7 @@ export class HttpSuperblocksServerClient {
                 throw error;
             }
         };
-        let data = await requestBeforeDeadline("?returnBeforeReady=true");
+        let data = await requestBeforeDeadline("returnBeforeReady=true");
         let polled = false;
         for (;;) {
             const session = data.sandboxStartData;
@@ -716,11 +622,13 @@ export class HttpSuperblocksServerClient {
             const status = liveEditStatus(session.status);
             if (session.pitcherURL &&
                 (session.status === undefined || status === "active")) {
+                internalIngress.route(session.pitcherURL);
                 return {
                     liveEditId: session.sandboxId,
                     liveEditUrl: session.pitcherURL,
                     pitcherToken: session.pitcherToken,
                     pitcherURL: session.pitcherURL,
+                    ...(data.targetBranch ? { targetBranch: data.targetBranch } : {}),
                 };
             }
             if (status !== "starting") {
@@ -733,18 +641,14 @@ export class HttpSuperblocksServerClient {
                 throw deadlineError();
             }
             polled = true;
-            data = await requestBeforeDeadline(`?liveEditId=${encodeURIComponent(session.sandboxId)}`);
+            data = await requestBeforeDeadline(`liveEditId=${encodeURIComponent(session.sandboxId)}`);
         }
     }
     async getLiveEditStatus(input) {
-        const branchSegment = input.branch
-            ? `/branches/${encodeURIComponent(input.branch)}`
-            : "";
-        const path = `/api/v3/applications/${input.applicationId}${branchSegment}/connect?liveEditId=${encodeURIComponent(input.liveEditId)}`;
         try {
-            const data = await this.requestData(path, {
+            const data = await this.requestData(liveEditConnectRequest(input.applicationId, input.branch), {
                 apiKey: input.apiKey,
-                method: "GET",
+                query: `liveEditId=${encodeURIComponent(input.liveEditId)}`,
                 retry: false,
                 signal: input.signal,
             });
@@ -790,10 +694,9 @@ export class HttpSuperblocksServerClient {
             }
             body.commitId = input.commitId;
         }
-        const data = await this.request("/api/v1/token/scoped", {
+        const data = await this.request(PlatformMcpServerRequest.to("POST /api/v1/token/scoped"), {
             apiKey: input.apiKey,
             body: JSON.stringify(body),
-            method: "POST",
         });
         if (!data?.access_token) {
             throw new Error("Server /api/v1/token/scoped returned no access_token; the live-edit session has nothing to verify");
@@ -811,16 +714,16 @@ export class HttpSuperblocksServerClient {
         if (input.applicationId) {
             params.set("applicationId", input.applicationId);
         }
-        const data = await this.requestData(`/api/v1/integrations/superset?${params.toString()}`, {
+        const data = await this.requestData(PlatformMcpServerRequest.to("GET /api/v1/integrations/superset"), {
             apiKey: input.apiKey,
-            method: "GET",
+            query: params.toString(),
             operation: "superset_integrations",
         });
         return Array.isArray(data) ? data : [];
     }
     async getIntegration(input) {
         try {
-            return await this.requestData(`/api/v1/integrations/${encodeURIComponent(input.integrationId)}`, { apiKey: input.apiKey, method: "GET", operation: "integration" });
+            return await this.requestData(PlatformMcpServerRequest.to("GET /api/v1/integrations/*", input.integrationId), { apiKey: input.apiKey, operation: "integration" });
         }
         catch (error) {
             if (error instanceof ServerHttpError && error.status === 404) {
@@ -831,7 +734,7 @@ export class HttpSuperblocksServerClient {
     }
     async getApplicationEnvironment(input) {
         try {
-            const data = await this.requestData(`/api/v2/applications/${encodeURIComponent(input.applicationId)}/environments`, { apiKey: input.apiKey, method: "GET" });
+            const data = await this.requestData(PlatformMcpServerRequest.to("GET /api/v2/applications/*/environments", input.applicationId), { apiKey: input.apiKey });
             const editor = data?.profiles?.editor;
             const availableProfileIds = Array.isArray(editor?.availableProfileIds)
                 ? editor.availableProfileIds.filter((id) => typeof id === "string")
@@ -862,9 +765,8 @@ export class HttpSuperblocksServerClient {
         }
     }
     async getOrganizationProfiles(input) {
-        const data = await this.requestData(`/api/v1/organizations/${encodeURIComponent(input.organizationId)}/profiles`, {
+        const data = await this.requestData(PlatformMcpServerRequest.to("GET /api/v1/organizations/*/profiles", input.organizationId), {
             apiKey: input.apiKey,
-            method: "GET",
             operation: "organization_profiles",
         });
         if (!Array.isArray(data)) {
@@ -884,6 +786,29 @@ export class HttpSuperblocksServerClient {
             key: row.key,
         }));
     }
+    async getBranchStatus(input) {
+        const data = await this.requestData(PlatformMcpServerRequest.to("GET /api/v2/applications/*/branch/status", input.applicationId), {
+            apiKey: input.apiKey,
+            ...(input.signal ? { signal: input.signal } : {}),
+            ...(input.timeoutMs !== undefined
+                ? { timeoutMs: input.timeoutMs }
+                : {}),
+        });
+        return { branch: data.branch, mainHead: data.mainHead, mode: data.mode };
+    }
+    async landBranch(input) {
+        return this.requestData(PlatformMcpServerRequest.to("POST /api/v2/applications/*/branch/land", input.applicationId), {
+            apiKey: input.apiKey,
+            body: JSON.stringify({
+                publish: true,
+                retryFailedMigrations: input.retryFailedMigrations,
+            }),
+            ...(input.signal ? { signal: input.signal } : {}),
+            ...(input.timeoutMs !== undefined
+                ? { timeoutMs: input.timeoutMs }
+                : {}),
+        });
+    }
     /**
      * Snapshots the application's current live-edit state as a commit.
      *
@@ -892,10 +817,9 @@ export class HttpSuperblocksServerClient {
      * editor's publish flow does.
      */
     async createCommit(input) {
-        const branchSegment = input.branch
-            ? `/branches/${encodeURIComponent(input.branch)}`
-            : "";
-        const data = await this.requestData(`/api/v2/applications/${input.applicationId}${branchSegment}/commit`, {
+        const data = await this.requestData(input.branch
+            ? PlatformMcpServerRequest.to("POST /api/v2/applications/*/branches/*/commit", input.applicationId, input.branch)
+            : PlatformMcpServerRequest.to("POST /api/v2/applications/*/commit", input.applicationId), {
             apiKey: input.apiKey,
             body: JSON.stringify({
                 commitMessage: input.message,
@@ -903,9 +827,10 @@ export class HttpSuperblocksServerClient {
                 // a commit racing an editor that has moved on since.
                 lastSuccessfulWrite: Date.now(),
             }),
-            method: "POST",
             ...(input.signal ? { signal: input.signal } : {}),
-            ...(input.timeoutMs !== undefined ? { timeoutMs: input.timeoutMs } : {}),
+            ...(input.timeoutMs !== undefined
+                ? { timeoutMs: input.timeoutMs }
+                : {}),
         });
         return {
             commitId: data.commitId,
@@ -923,20 +848,18 @@ export class HttpSuperblocksServerClient {
      * same content end up watching one build instead of racing two.
      */
     async createBuild(input) {
-        await this.request(`/api/v3/applications/${input.applicationId}/${encodeURIComponent(input.directoryHash)}/builds`, {
+        await this.request(PlatformMcpServerRequest.to("POST /api/v3/applications/*/*/builds", input.applicationId, input.directoryHash), {
             apiKey: input.apiKey,
             body: JSON.stringify({ commitId: input.commitId }),
-            method: "POST",
         });
     }
     async getBuildProgress(input) {
-        const path = `/api/v3/applications/${input.applicationId}/build-bulk-status`;
+        const target = PlatformMcpServerRequest.to("POST /api/v3/applications/*/build-bulk-status", input.applicationId);
         // POST because the hashes go in the body, but it is a read: the server
         // asks SABS for status and changes nothing.
-        const data = await this.requestData(path, {
+        const data = await this.requestData(target, {
             apiKey: input.apiKey,
             body: JSON.stringify({ directoryHashes: [input.directoryHash] }),
-            method: "POST",
             operation: "build_progress",
             retry: true,
             ...(input.signal ? { signal: input.signal } : {}),
@@ -947,14 +870,13 @@ export class HttpSuperblocksServerClient {
         return buildProgress(data.directoryHashToStatus?.[input.directoryHash]?.status);
     }
     async deployApplication(input) {
-        const path = `/api/v2/applications/${input.applicationId}/deployments`;
-        const body = await this.request(path, {
+        const target = PlatformMcpServerRequest.to("POST /api/v2/applications/*/deployments", input.applicationId);
+        const body = await this.request(target, {
             apiKey: input.apiKey,
             // PostApplicationDeployRequestBody rejects unknown properties, so this
             // body carries the commit and nothing else — the branch is already
             // fixed by the commit being deployed.
             body: JSON.stringify({ commitId: input.commitId }),
-            method: "POST",
             ...(input.signal ? { signal: input.signal } : {}),
             ...(input.timeoutMs !== undefined ? { timeoutMs: input.timeoutMs } : {}),
         });
@@ -966,16 +888,15 @@ export class HttpSuperblocksServerClient {
         }
         // Neither shape. Guessing "it worked" here would report a publish that
         // never happened as a success.
-        throw new Error(`Server ${path} returned neither a deployment nor a deploy status`);
+        throw new Error(`Server ${target.path} returned neither a deployment nor a deploy status`);
     }
     /**
      * Polls the deploy queue for a commit the UI watches after a queued publish.
      */
     async getDeployStatus(input) {
-        const path = `/api/v2/applications/${input.applicationId}/deploy-status/${encodeURIComponent(input.commitId)}`;
-        const body = await this.request(path, {
+        const target = PlatformMcpServerRequest.to("GET /api/v2/applications/*/deploy-status/*", input.applicationId, input.commitId);
+        const body = await this.request(target, {
             apiKey: input.apiKey,
-            method: "GET",
             retry: false,
             ...(input.signal ? { signal: input.signal } : {}),
             ...(input.timeoutMs !== undefined ? { timeoutMs: input.timeoutMs } : {}),
@@ -993,7 +914,7 @@ export class HttpSuperblocksServerClient {
                 status,
             };
         }
-        throw new Error(`Server ${path} returned an unknown deploy status`);
+        throw new Error(`Server ${target.path} returned an unknown deploy status`);
     }
     /**
      * Asks Clark for an app name, the same way the editor header does after a
@@ -1001,13 +922,12 @@ export class HttpSuperblocksServerClient {
      */
     async generateAppName(input) {
         // Another bare body rather than the `{ responseMeta, data }` envelope.
-        const data = await this.request("/api/v1/ai/generate-app-name", {
+        const data = await this.request(PlatformMcpServerRequest.to("POST /api/v1/ai/generate-app-name"), {
             apiKey: input.apiKey,
             body: JSON.stringify({
                 applicationId: input.applicationId,
                 prompt: input.prompt,
             }),
-            method: "POST",
         });
         if (!data?.name?.trim()) {
             throw new Error("Server /api/v1/ai/generate-app-name returned no name");
@@ -1023,21 +943,19 @@ export class HttpSuperblocksServerClient {
      * why nothing on a hot path should call it.
      */
     async getApplicationName(input) {
-        const body = await this.request("/api/v2/applications", {
+        const body = await this.request(PlatformMcpServerRequest.to("GET /api/v2/applications"), {
             apiKey: input.apiKey,
-            method: "GET",
             operation: "applications",
         });
         const found = body?.data?.applications?.find((application) => application?.id === input.applicationId);
         return found?.name?.trim() || undefined;
     }
     async renameApplication(input) {
-        await this.request(`/api/v2/applications/${input.applicationId}/metadata`, {
+        await this.request(PlatformMcpServerRequest.to("PUT /api/v2/applications/*/metadata", input.applicationId), {
             apiKey: input.apiKey,
             // PutApplicationMetadataUpdateRequestBody accepts exactly one of name,
             // folderId, or isPublic — sending more than one fails validation.
             body: JSON.stringify({ name: input.name }),
-            method: "PUT",
         });
     }
 }