@superblocksteam/gateway 2.0.157-next.3 → 2.0.157-next.4

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`, `get_integration_metadata`, `preview_app`, `publish_app`) plus
-customer Admin tools from `@superblocksteam/mcp-server` share this process.
+`get_app`, `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,18 +147,7 @@ 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`, `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.
+`edit_app`, `check_app_progress`, `get_app`, `preview_app`, and `publish_app`.
 See `.env.example` for optional configuration.
 
 ## Env
@@ -179,19 +168,3 @@ 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/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, ResolvedPrincipal, StartAppInput, StartAppResult } from "./types.js";
+import type { CapabilityResult, CheckAppProgressInput, CheckAppProgressResult, EditAppInput, EditAppResult, GetAppInput, GetAppResult, ImportAppInput, ImportAppResult, PreviewAppInput, PreviewAppResult, Principal, ProgressEvent, PublishAppInput, PublishAppResult, StartAppInput, StartAppResult } from "./types.js";
 export { IMPORT_ZIP_MAX_BYTES } from "./types.js";
 export type CapabilityContext = {
     /**
@@ -23,7 +23,6 @@ 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;
@@ -45,16 +44,6 @@ 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,21 +228,19 @@ 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.
  */
-export async function ensurePrincipal(ctx) {
+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: resolved,
+            value: {
+                ...principal,
+                organizationId: principal.organizationId,
+                userId: principal.userId,
+            },
         };
     }
     let validated;
@@ -279,16 +277,14 @@ export 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: resolved,
+        value: {
+            ...principal,
+            email: validated.email,
+            organizationId: validated.organizationId,
+            userId: validated.userId,
+        },
     };
 }
 /**
@@ -383,7 +379,7 @@ async function elicitStepUp(ctx, idempotencyKey, applicationId) {
         },
     };
 }
-export async function resolveApplicationId(ctx, principal, applicationId) {
+async function resolveApplicationId(ctx, principal, applicationId) {
     if (applicationId?.trim()) {
         return { kind: "ok", value: applicationId.trim() };
     }
@@ -517,9 +513,7 @@ 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 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";
+        return "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}`;
@@ -675,7 +669,6 @@ async function forwardClarkPrompt(ctx, input) {
             ...(forward.recentRuns && forward.recentRuns.length > 0
                 ? { recentRuns: forward.recentRuns }
                 : {}),
-            ...(forward.retryAction ? { retryAction: forward.retryAction } : {}),
             viewStatus: forward.viewStatus,
         },
     };
@@ -765,13 +758,17 @@ 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.
  *
- * 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.
+ * 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.
  */
 function retryIfReplayable(attachments) {
     return attachments && attachments.length > 0
-        ? { pendingAction: "retry_import" }
+        ? undefined
         : { pendingAction: "retry_build" };
 }
 /**
@@ -813,9 +810,7 @@ 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: 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 } : {}),
+            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})`,
             userId: input.principal.userId,
         });
     }
@@ -871,12 +866,7 @@ async function promptNewApplication(ctx, args) {
         });
     }
     catch (error) {
-        rememberFailedStart(ctx, {
-            applicationId,
-            error,
-            principal,
-            ...(args.attachments?.length ? { retryAction: "retry_import" } : {}),
-        });
+        rememberFailedStart(ctx, { applicationId, error, principal });
         return liveEditUnavailable(error, args.attachments);
     }
     ctx.onProgress?.({
@@ -1161,19 +1151,14 @@ 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 resumedApplicationId
-            ? namingApplication(resumedApplicationId, archiveResult)
-            : archiveResult;
+        return archiveResult;
     }
     const archive = archiveResult.value;
     const principalResult = await ensurePrincipal(ctx);
     if (principalResult.kind !== "ok") {
-        return resumedApplicationId
-            ? namingApplication(resumedApplicationId, principalResult)
-            : principalResult;
+        return principalResult;
     }
     const principal = principalResult.value;
     const source = normalizeImportSource(input.source);
@@ -1184,26 +1169,25 @@ export async function importApp(ctx, input) {
     });
     const explicitName = input.name?.trim();
     const name = explicitName || defaultAppName(migrationPrompt);
-    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;
+    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;
     }
-    await rememberApplication(ctx, principal, applicationId);
-    const result = await migrateArchiveIntoApplication(ctx, {
-        applicationId,
+    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,
         archive,
         explicitName,
         input,
@@ -1211,10 +1195,7 @@ 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
@@ -1238,18 +1219,10 @@ 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, {
@@ -1275,13 +1248,7 @@ async function migrateArchiveIntoApplication(ctx, args) {
         prompt: args.migrationPrompt,
     });
 }
-/**
- * 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.
- */
+/** Machine-readable shape a cancelled wait answers with. */
 function cancelled(capability) {
     return {
         kind: "error",
@@ -1370,7 +1337,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 namingApplication(applicationId, cancelled("check_app_progress"));
+        return cancelled("check_app_progress");
     }
     const cursorKey = cursorKeyFor(ctx, principal, applicationId);
     const stored = cursorKey
@@ -1384,7 +1351,7 @@ export async function checkAppProgress(ctx, input) {
         waitMs: hostCallBudgetMs(ctx, ctx.config.clarkProgressWaitMs),
     });
     if (ctx.signal?.aborted) {
-        return namingApplication(applicationId, cancelled("check_app_progress"));
+        return cancelled("check_app_progress");
     }
     const snapshot = await readSnapshot(ctx, {
         applicationId,
@@ -1502,9 +1469,6 @@ 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,
         },
@@ -2089,13 +2053,7 @@ function localUnbuiltReason(turn, pending) {
         return undefined;
     }
     const status = emptyTurnStatus(turn.generationStatus);
-    return status
-        ? {
-            kind: "empty_turn",
-            retryAction: turn.retryAction ?? "retry_build",
-            status,
-        }
-        : undefined;
+    return status ? { kind: "empty_turn", status } : undefined;
 }
 /**
  * The same question asked of what was persisted, for a caller with no live turn
@@ -2183,8 +2141,6 @@ 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
@@ -2256,11 +2212,7 @@ async function unbuiltApp(ctx, principal, applicationId) {
     if (reason.kind === "empty_turn") {
         return {
             kind: "ok",
-            value: {
-                ...app,
-                ...(reason.retryAction ? { pendingAction: reason.retryAction } : {}),
-                status: reason.status,
-            },
+            value: { ...app, pendingAction: "retry_build", status: reason.status },
         };
     }
     return {
@@ -2394,7 +2346,7 @@ async function waitForBuild(ctx, input) {
     let started = false;
     for (;;) {
         if (ctx.signal?.aborted) {
-            return namingApplication(input.applicationId, cancelled("get_app"));
+            return 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