@superblocksteam/gateway 2.0.157 → 2.0.158-next.0

package/README.md

@@ -4,8 +4,8 @@ Standalone Superblocks entry point for a **single MCP connector** (Admin + Build
 over **stdio**, running as the already-logged-in Superblocks CLI user.
 
 Builder tools (`start_app`, `import_app`, `edit_app`, `check_app_progress`,
-`get_app`, `preview_app`, `publish_app`) plus customer Admin tools from
-`@superblocksteam/mcp-server` share this process.
+`get_app`, `get_integration_metadata`, `preview_app`, `publish_app`) plus
+customer Admin tools from `@superblocksteam/mcp-server` share this process.
 
 The MCP host owns process lifecycle: it spawns `superblocks gateway serve`.
 There is no foreground HTTP `/mcp`, no OAuth resource server, and no linked-grant
@@ -147,7 +147,18 @@ package only the customer Admin surface. Builder tools are not registered.
 ## MCP tools
 
 After `gateway setup`, restart Claude Code or Cursor and call `start_app`,
-`edit_app`, `check_app_progress`, `get_app`, `preview_app`, and `publish_app`.
+`edit_app`, `check_app_progress`, `get_app`, `get_integration_metadata`,
+`preview_app`, and `publish_app`. `get_integration_metadata` reads tables,
+columns, and types from a connected integration; use `search`, `limit`, and
+`offset` for large results. It needs no application: without one it mints an
+`integrations:build` token scoped to that single integration. Pass
+`applicationId` only for an integration owned by one application, such as a
+Native DB, which is invisible without app context.
+It resolves the integration through the RBAC-annotated superset list rather than
+the org-wide lookup by id, so it answers `integration_not_permitted` without
+build permission on that integration and `integration_not_supported` for a
+plugin Clark cannot use as a tool.
+`get_integration_config_schema` is the create-integration form, not live data.
 See `.env.example` for optional configuration.
 
 ## Env
@@ -168,3 +179,19 @@ Gateway debug logs include tool names, result states, decision branches, and
 entry-point stacks. They intentionally omit credentials, prompts, answers, and
 result payloads. Run `superblocks gateway setup --client <client> --debug`, then
 restart the MCP host. Re-run setup without `--debug` to turn them off.
+
+## Remote traceability
+
+Gateway exports one OpenTelemetry trace per MCP process through the authenticated
+Server `/api/v1/traces` proxy. Each tool call is a child span with the MCP client
+name and version, tool name, duration, outcome, organization ID, and application
+ID when available.
+
+Prompts, answers, result payloads, credentials, and raw error messages are never
+added to these spans. Use the application ID to correlate a trace with the
+existing server-side app and build records.
+
+Cloud-Prem uses `SUPERBLOCKS_DEPLOYMENT_TYPE=cloud-prem` (or `GATEWAY_LOCAL_AGENT`)
+so the stricter telemetry policy is selected. Laptop agents still drop client,
+organization, and application attributes until the Tier 2 traces contract lists
+them; tool name, duration, and outcome still export.

package/dist/capabilities/integration-metadata.d.ts

@@ -0,0 +1,28 @@
+import { type CapabilityContext } from "./lifecycle.js";
+import type { CapabilityResult } from "./types.js";
+export type GetIntegrationMetadataInput = {
+    applicationId?: string;
+    integrationId: string;
+    limit?: number;
+    offset?: number;
+    search?: string;
+};
+type MetadataEntry = {
+    path: string;
+    value: boolean | null | number | string;
+};
+export type GetIntegrationMetadataResult = {
+    /** Absent when the metadata was read through an integration-scoped token. */
+    applicationId?: string;
+    entries: MetadataEntry[];
+    hasMore: boolean;
+    integrationId: string;
+    integrationName: string;
+    nextOffset: number | null;
+    offset: number;
+    pluginId: string;
+    returnedCount: number;
+    totalCount: number;
+};
+export declare function getIntegrationMetadata(context: CapabilityContext, input: GetIntegrationMetadataInput): Promise<CapabilityResult<GetIntegrationMetadataResult>>;
+export {};

package/dist/capabilities/integration-metadata.js

@@ -0,0 +1,174 @@
+import { pickOrchestratorBaseUrl } from "../agents/resolve-orchestrator-url.js";
+import { integrationIsToolSupported } from "../integrations/filters.js";
+import { hasBuildPermission } from "../integrations/map.js";
+import { pickEditorProfileKey } from "../integrations/profile-key.js";
+import { HttpOrchestratorClient } from "../orchestrator/client.js";
+import { sanitizeAgentFacingText, sanitizeAgentFacingValue, } from "../sabs/agent-facing-text.js";
+import { ensurePrincipal, resolveApplicationId, } from "./lifecycle.js";
+const DEFAULT_LIMIT = 100;
+function labelPart(value) {
+    return typeof value === "string"
+        ? value.trim().replaceAll(/[.[\]]/g, "_")
+        : "";
+}
+/**
+ * A table name alone is ambiguous: `public.users` and `analytics.users` are
+ * different tables, so qualify with the schema whenever the row carries one.
+ */
+function arrayEntryLabel(value, index) {
+    if (value && typeof value === "object") {
+        const row = value;
+        const name = labelPart(row.name);
+        if (name) {
+            const schema = labelPart(row.schema);
+            return schema ? `${schema}.${name}` : name;
+        }
+    }
+    return String(index);
+}
+function metadataEntries(value, path = "", entries = []) {
+    if (value === null ||
+        typeof value === "boolean" ||
+        typeof value === "number" ||
+        typeof value === "string") {
+        entries.push({ path, value });
+        return entries;
+    }
+    if (Array.isArray(value)) {
+        const seen = new Set();
+        value.forEach((entry, index) => {
+            const label = arrayEntryLabel(entry, index);
+            // Two rows that still label identically would be indistinguishable, so
+            // fall back to the index for the later one.
+            const unique = seen.has(label) ? `${label}#${index}` : label;
+            seen.add(unique);
+            metadataEntries(entry, `${path}[${unique}]`, entries);
+        });
+        return entries;
+    }
+    if (value && typeof value === "object") {
+        for (const [key, entry] of Object.entries(value)) {
+            metadataEntries(entry, path ? `${path}.${key}` : key, entries);
+        }
+    }
+    return entries;
+}
+export async function getIntegrationMetadata(context, input) {
+    const principal = await ensurePrincipal(context);
+    if (principal.kind !== "ok") {
+        return principal;
+    }
+    let applicationId;
+    // Named for the agent before the integration resolves, so a failure on the
+    // way to the metadata still reports which integration it was reaching for.
+    let label = sanitizeAgentFacingText(input.integrationId);
+    try {
+        // An app is preferred but not required. App-owned integrations (Native DB
+        // among them) are only visible through an app-scoped token, so use one
+        // whenever an app is in play and fall back to the integration-scoped token
+        // rather than making the caller invent an application.
+        const resolved = await resolveApplicationId(context, principal.value, input.applicationId);
+        applicationId = resolved.kind === "ok" ? resolved.value : undefined;
+        // The RBAC-annotated list, not the org-wide lookup by id: only this one
+        // carries the permissions that say whether the caller may build with the
+        // integration at all.
+        const rows = await context.server.getSupersetIntegrations({
+            apiKey: principal.value.apiKey,
+            ...(applicationId && { applicationId }),
+            organizationId: principal.value.organizationId,
+        });
+        const integration = rows.find((row) => row.id === input.integrationId);
+        if (!integration) {
+            return {
+                ...(applicationId && { applicationId }),
+                kind: "error",
+                code: "integration_not_accessible",
+                message: `Integration ${label} was not found or is not accessible.`,
+            };
+        }
+        const integrationName = sanitizeAgentFacingText(integration.name);
+        const pluginId = sanitizeAgentFacingText(integration.pluginId);
+        label = integrationName;
+        if (!hasBuildPermission(integration)) {
+            return {
+                ...(applicationId && { applicationId }),
+                kind: "error",
+                code: "integration_not_permitted",
+                message: `You do not have build permission on ${integrationName}.`,
+            };
+        }
+        if (!integrationIsToolSupported(integration.pluginId)) {
+            return {
+                ...(applicationId && { applicationId }),
+                kind: "error",
+                code: "integration_not_supported",
+                message: `${integrationName} is a ${pluginId} integration, which this tool cannot inspect.`,
+            };
+        }
+        const profiles = await context.server.getOrganizationProfiles({
+            apiKey: principal.value.apiKey,
+            organizationId: principal.value.organizationId,
+        });
+        const profileKey = pickEditorProfileKey(context.config.profileKey, profiles);
+        const inventory = await context.server.getAgentInventory({
+            apiKey: principal.value.apiKey,
+            organizationId: principal.value.organizationId,
+        });
+        const orchestratorUrl = pickOrchestratorBaseUrl({
+            agentType: inventory.agentType,
+            agents: inventory.agents,
+            profileKey,
+        });
+        const scopedToken = await context.server.issueScopedToken(applicationId
+            ? {
+                apiKey: principal.value.apiKey,
+                applicationId,
+                scope: "apps:update",
+            }
+            : {
+                apiKey: principal.value.apiKey,
+                integrationId: input.integrationId,
+                scope: "integrations:build",
+            });
+        const metadata = await new HttpOrchestratorClient(orchestratorUrl).getMetadata({
+            apiKey: principal.value.apiKey,
+            integrationId: input.integrationId,
+            profileKey,
+            scopedToken,
+        });
+        const sanitized = sanitizeAgentFacingValue(metadata);
+        const search = input.search?.trim().toLowerCase();
+        const matched = metadataEntries(sanitized).filter((entry) => !search ||
+            entry.path.toLowerCase().includes(search) ||
+            String(entry.value).toLowerCase().includes(search));
+        const limit = input.limit ?? DEFAULT_LIMIT;
+        const offset = input.offset ?? 0;
+        const entries = matched.slice(offset, offset + limit);
+        const nextOffset = offset + entries.length < matched.length ? offset + entries.length : null;
+        return {
+            kind: "ok",
+            value: {
+                ...(applicationId && { applicationId }),
+                entries,
+                hasMore: nextOffset !== null,
+                integrationId: integration.id,
+                integrationName,
+                nextOffset,
+                offset,
+                pluginId,
+                returnedCount: entries.length,
+                totalCount: matched.length,
+            },
+        };
+    }
+    catch (error) {
+        const detail = sanitizeAgentFacingText(error instanceof Error ? error.message : "Unknown metadata error").replaceAll("\u2014", "-");
+        return {
+            ...(applicationId && { applicationId }),
+            kind: "error",
+            code: "integration_metadata_unavailable",
+            message: `Could not load metadata for ${label}: ${detail}`,
+        };
+    }
+}
+//# sourceMappingURL=integration-metadata.js.map

package/dist/capabilities/integration-metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"integration-metadata.js","sourceRoot":"","sources":["../../src/capabilities/integration-metadata.ts"],"names":[],"mappings":"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"}

package/dist/capabilities/lifecycle.d.ts

@@ -5,7 +5,7 @@ import type { CapturePreviewScreenshot } from "../preview/capture-screenshot.js"
 import type { CallerRef, ProgressStore, RecentAppStore, TurnStore } from "../resume/types.js";
 import type { SessionPeer } from "../sabs/session-peer.js";
 import type { SuperblocksServerClient } from "../server/client.js";
-import type { CapabilityResult, CheckAppProgressInput, CheckAppProgressResult, EditAppInput, EditAppResult, GetAppInput, GetAppResult, ImportAppInput, ImportAppResult, PreviewAppInput, PreviewAppResult, Principal, ProgressEvent, PublishAppInput, PublishAppResult, StartAppInput, StartAppResult } from "./types.js";
+import type { CapabilityResult, CheckAppProgressInput, CheckAppProgressResult, EditAppInput, EditAppResult, GetAppInput, GetAppResult, ImportAppInput, ImportAppResult, PreviewAppInput, PreviewAppResult, Principal, ProgressEvent, PublishAppInput, PublishAppResult, ResolvedPrincipal, StartAppInput, StartAppResult } from "./types.js";
 export { IMPORT_ZIP_MAX_BYTES } from "./types.js";
 export type CapabilityContext = {
     /**
@@ -23,6 +23,7 @@ export type CapabilityContext = {
     /** Injected so pacing and stall thresholds are testable without real time. */
     now?: () => number;
     onProgress?: (event: ProgressEvent) => void;
+    onPrincipalResolved?: (principal: ResolvedPrincipal) => void;
     principal: Principal;
     /** Where each caller's place in the event stream is kept between calls. */
     progressCursors?: ProgressStore;
@@ -44,6 +45,16 @@ export type CapabilityContext = {
     signal?: AbortSignal;
     turns: TurnStore;
 };
+/**
+ * Resolves the Superblocks user behind the CLI session this Gateway was
+ * started with.
+ *
+ * Identity is the already-logged-in Superblocks CLI user. A rejection here
+ * means that personal API key is bad, not that the user needs a second login,
+ * so it surfaces as an error rather than an interactive-auth elicitation.
+ */
+export declare function ensurePrincipal(ctx: CapabilityContext): Promise<CapabilityResult<ResolvedPrincipal>>;
+export declare function resolveApplicationId(ctx: CapabilityContext, principal: ResolvedPrincipal, applicationId: string | undefined): Promise<CapabilityResult<string>>;
 export declare function startApp(ctx: CapabilityContext, input: StartAppInput): Promise<CapabilityResult<StartAppResult>>;
 /**
  * Creates a fullstack app, uploads the caller's archive as an app attachment,

package/dist/capabilities/lifecycle.js

@@ -228,19 +228,21 @@ function defaultAppName(prompt) {
  * means that personal API key is bad, not that the user needs a second login,
  * so it surfaces as an error rather than an interactive-auth elicitation.
  */
-async function ensurePrincipal(ctx) {
+export async function ensurePrincipal(ctx) {
     const { principal } = ctx;
     // MCP already has the CLI session key. Looking it up again would spend a
     // second round trip on `/users/me`, the slowest endpoint the Superblocks
     // API has, when the principal is already resolved (ENG-5806).
     if (principal.organizationId && principal.userId) {
+        const resolved = {
+            ...principal,
+            organizationId: principal.organizationId,
+            userId: principal.userId,
+        };
+        ctx.onPrincipalResolved?.(resolved);
         return {
             kind: "ok",
-            value: {
-                ...principal,
-                organizationId: principal.organizationId,
-                userId: principal.userId,
-            },
+            value: resolved,
         };
     }
     let validated;
@@ -277,14 +279,16 @@ async function ensurePrincipal(ctx) {
             message: "The Superblocks API rejected the credential issued for this caller.",
         };
     }
+    const resolved = {
+        ...principal,
+        email: validated.email,
+        organizationId: validated.organizationId,
+        userId: validated.userId,
+    };
+    ctx.onPrincipalResolved?.(resolved);
     return {
         kind: "ok",
-        value: {
-            ...principal,
-            email: validated.email,
-            organizationId: validated.organizationId,
-            userId: validated.userId,
-        },
+        value: resolved,
     };
 }
 /**
@@ -379,7 +383,7 @@ async function elicitStepUp(ctx, idempotencyKey, applicationId) {
         },
     };
 }
-async function resolveApplicationId(ctx, principal, applicationId) {
+export async function resolveApplicationId(ctx, principal, applicationId) {
     if (applicationId?.trim()) {
         return { kind: "ok", value: applicationId.trim() };
     }
@@ -513,7 +517,9 @@ function turnSummary(turn) {
         return "Superblocks is still working, but only the editor can show it — open the edit URL";
     }
     if (turn.generationStatus === "live_edit_terminated") {
-        return "The Superblocks live-edit session terminated before anything was built — send the prompt again with edit_app";
+        return turn.retryAction === "retry_import"
+            ? "The Superblocks live-edit session terminated before anything was built — send the archive again with import_app"
+            : "The Superblocks live-edit session terminated before anything was built — send the prompt again with edit_app";
     }
     if (turn.checkpointCommitId) {
         return `Application ready — checkpoint saved. ${NEXT_STEPS}`;
@@ -669,6 +675,7 @@ async function forwardClarkPrompt(ctx, input) {
             ...(forward.recentRuns && forward.recentRuns.length > 0
                 ? { recentRuns: forward.recentRuns }
                 : {}),
+            ...(forward.retryAction ? { retryAction: forward.retryAction } : {}),
             viewStatus: forward.viewStatus,
         },
     };
@@ -758,17 +765,13 @@ function namingCreatedApplication(applicationId, capability, result) {
  * The recovery to advertise when the machinery around a turn fails: `edit_app`
  * with the same prompt, which is what `retry_build` means.
  *
- * Only for a prompt `edit_app` could actually replay. A prompt carrying
- * attachments is not one: `edit_app` has no way to resupply an attachment, so
- * an import's migration prompt would reach Superblocks describing an archive it
- * cannot see. Advertising a recovery that cannot finish is worse than
- * advertising none, so the import path gets `applicationId` and no hint.
- * TODO(ENG-5917): let `import_app` resume into an application it already
- * created, and give the import path a recovery of its own.
+ * A regular prompt is retried with `edit_app`. An import prompt carries an
+ * attachment, so it must be retried with `import_app` to upload the archive
+ * again and obtain a fresh signed URL.
  */
 function retryIfReplayable(attachments) {
     return attachments && attachments.length > 0
-        ? undefined
+        ? { pendingAction: "retry_import" }
         : { pendingAction: "retry_build" };
 }
 /**
@@ -810,7 +813,9 @@ function rememberFailedStart(ctx, input) {
             organizationId: input.principal.organizationId,
             // Reaches the caller as the dead start's reply on its next poll, so it
             // has to stand on its own there rather than lean on this call's error.
-            reason: `The Superblocks live-edit session for application ${input.applicationId} never opened, so the prompt never reached Superblocks and nothing was built. Nothing is running for that application; send the same instruction again to retry it. (${cause})`,
+            reason: input.reason ??
+                `The Superblocks live-edit session for application ${input.applicationId} never opened, so the prompt never reached Superblocks and nothing was built. Nothing is running for that application; send the same instruction again to retry it. (${cause})`,
+            ...(input.retryAction ? { retryAction: input.retryAction } : {}),
             userId: input.principal.userId,
         });
     }
@@ -866,7 +871,12 @@ async function promptNewApplication(ctx, args) {
         });
     }
     catch (error) {
-        rememberFailedStart(ctx, { applicationId, error, principal });
+        rememberFailedStart(ctx, {
+            applicationId,
+            error,
+            principal,
+            ...(args.attachments?.length ? { retryAction: "retry_import" } : {}),
+        });
         return liveEditUnavailable(error, args.attachments);
     }
     ctx.onProgress?.({
@@ -1151,14 +1161,19 @@ function normalizeImportSource(source) {
  * wizard, without the sessionStorage hop.
  */
 export async function importApp(ctx, input) {
+    const resumedApplicationId = input.applicationId?.trim();
     const archiveResult = await resolveImportArchive(input, ctx.config.importSearchDirs);
     if (archiveResult.kind !== "ok") {
-        return archiveResult;
+        return resumedApplicationId
+            ? namingApplication(resumedApplicationId, archiveResult)
+            : archiveResult;
     }
     const archive = archiveResult.value;
     const principalResult = await ensurePrincipal(ctx);
     if (principalResult.kind !== "ok") {
-        return principalResult;
+        return resumedApplicationId
+            ? namingApplication(resumedApplicationId, principalResult)
+            : principalResult;
     }
     const principal = principalResult.value;
     const source = normalizeImportSource(input.source);
@@ -1169,25 +1184,26 @@ export async function importApp(ctx, input) {
     });
     const explicitName = input.name?.trim();
     const name = explicitName || defaultAppName(migrationPrompt);
-    ctx.onProgress?.({
-        message: "Creating application for import",
-        type: "progress",
-    });
-    const created = await createApplicationForPrompt(ctx, {
-        apiKey: principal.apiKey,
-        name,
-        organizationId: principal.organizationId,
-        templateName: "app-fullstack",
-    });
-    if (created.kind !== "ok") {
-        return created;
+    let applicationId = resumedApplicationId;
+    if (!applicationId) {
+        ctx.onProgress?.({
+            message: "Creating application for import",
+            type: "progress",
+        });
+        const created = await createApplicationForPrompt(ctx, {
+            apiKey: principal.apiKey,
+            name,
+            organizationId: principal.organizationId,
+            templateName: "app-fullstack",
+        });
+        if (created.kind !== "ok") {
+            return created;
+        }
+        applicationId = created.value.id;
     }
-    const app = created.value;
-    // See startApp: the row outlives any failure below it, so it is already this
-    // caller's most recent app.
-    await rememberApplication(ctx, principal, app.id);
-    return namingCreatedApplication(app.id, "import_app", await migrateArchiveIntoApplication(ctx, {
-        applicationId: app.id,
+    await rememberApplication(ctx, principal, applicationId);
+    const result = await migrateArchiveIntoApplication(ctx, {
+        applicationId,
         archive,
         explicitName,
         input,
@@ -1195,7 +1211,10 @@ export async function importApp(ctx, input) {
         name,
         principal,
         source,
-    }));
+    });
+    return resumedApplicationId
+        ? namingApplication(applicationId, result)
+        : namingCreatedApplication(applicationId, "import_app", result);
 }
 /**
  * Uploads the archive onto an application that already exists and hands
@@ -1219,10 +1238,18 @@ async function migrateArchiveIntoApplication(ctx, args) {
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
+        rememberFailedStart(ctx, {
+            applicationId,
+            error,
+            principal,
+            reason: `The archive for application ${applicationId} could not be uploaded, so the migration never started and nothing was built. Send the same archive again with import_app to retry it. (${message})`,
+            retryAction: "retry_import",
+        });
         return {
             kind: "error",
             code: "import_upload_failed",
             message,
+            pendingAction: "retry_import",
         };
     }
     return promptNewApplication(ctx, {
@@ -1248,7 +1275,13 @@ async function migrateArchiveIntoApplication(ctx, args) {
         prompt: args.migrationPrompt,
     });
 }
-/** Machine-readable shape a cancelled wait answers with. */
+/**
+ * Machine-readable shape a cancelled wait answers with.
+ *
+ * Callers name the application alongside it. A cancelled wait says nothing
+ * about the work, which carries on: a caller asked to resume it has to be able
+ * to point at the application rather than start a second one.
+ */
 function cancelled(capability) {
     return {
         kind: "error",
@@ -1337,7 +1370,7 @@ export async function checkAppProgress(ctx, input) {
     // while the credential was being resolved should never reach the point of
     // registering a waiter it will not read.
     if (ctx.signal?.aborted) {
-        return cancelled("check_app_progress");
+        return namingApplication(applicationId, cancelled("check_app_progress"));
     }
     const cursorKey = cursorKeyFor(ctx, principal, applicationId);
     const stored = cursorKey
@@ -1351,7 +1384,7 @@ export async function checkAppProgress(ctx, input) {
         waitMs: hostCallBudgetMs(ctx, ctx.config.clarkProgressWaitMs),
     });
     if (ctx.signal?.aborted) {
-        return cancelled("check_app_progress");
+        return namingApplication(applicationId, cancelled("check_app_progress"));
     }
     const snapshot = await readSnapshot(ctx, {
         applicationId,
@@ -1469,6 +1502,9 @@ export async function checkAppProgress(ctx, input) {
             reply: update.reply,
             ...(update.decision ? { decision: update.decision } : {}),
             generationStatus: update.generationStatus,
+            ...(update.retryAction && emptyTurnStatus(update.generationStatus)
+                ? { pendingAction: update.retryAction }
+                : {}),
             status,
             viewStatus: update.viewStatus,
         },
@@ -2053,7 +2089,13 @@ function localUnbuiltReason(turn, pending) {
         return undefined;
     }
     const status = emptyTurnStatus(turn.generationStatus);
-    return status ? { kind: "empty_turn", status } : undefined;
+    return status
+        ? {
+            kind: "empty_turn",
+            retryAction: turn.retryAction ?? "retry_build",
+            status,
+        }
+        : undefined;
 }
 /**
  * The same question asked of what was persisted, for a caller with no live turn
@@ -2141,6 +2183,8 @@ function persistedTurnEnd(status) {
         // plain question and cannot be approved.
         case "needs_decision":
             return { kind: "awaiting_decision" };
+        // The stream never recorded whether the prompt carried an archive, so
+        // this path cannot pick retry_build vs retry_import. Omit rather than guess.
         case "live_edit_terminated":
             return { kind: "empty_turn", status };
         // A `cancelled` in the tail may still have a real app behind it: the
@@ -2212,7 +2256,11 @@ async function unbuiltApp(ctx, principal, applicationId) {
     if (reason.kind === "empty_turn") {
         return {
             kind: "ok",
-            value: { ...app, pendingAction: "retry_build", status: reason.status },
+            value: {
+                ...app,
+                ...(reason.retryAction ? { pendingAction: reason.retryAction } : {}),
+                status: reason.status,
+            },
         };
     }
     return {
@@ -2346,7 +2394,7 @@ async function waitForBuild(ctx, input) {
     let started = false;
     for (;;) {
         if (ctx.signal?.aborted) {
-            return cancelled("get_app");
+            return namingApplication(input.applicationId, cancelled("get_app"));
         }
         // Checked before the network call, not only after it: a budget already
         // exhausted when this loop begins (or used up by the previous