@superblocksteam/cli 2.0.157-next.4 → 2.0.157-next.5

package/dist/{dist-2M5L5FNH.js → dist-NJHWXUHQ.js}

@@ -1,7 +1,7 @@
 if (typeof process === 'object' && process !== null &&
     process.env !== null && typeof process.env === 'object') {
   process.env.DD_GIT_REPOSITORY_URL = 'https://token@github.com/superblocksteam/superblocks.git';
-  process.env.DD_GIT_COMMIT_SHA = 'b4017d1f7aca518ff00f7059ba25e73fc7ea4cb9';
+  process.env.DD_GIT_COMMIT_SHA = '35eb352f57c1fbed7b4c3e71ec22cd31d0c49921';
 }
 import { createRequire as $dd_createRequire } from 'module';
 import { fileURLToPath as $dd_fileURLToPath } from 'url';
@@ -13,7 +13,7 @@ globalThis.__dirname ??= $dd_dirname(globalThis.__filename);
 import {
   McpServer,
   StdioServerTransport
-} from "./chunk-FLZB4YF5.js";
+} from "./chunk-LEBMSKJP.js";
 import {
   CallToolResultSchema,
   ContentBlockSchema,
@@ -27,30 +27,37 @@ import {
   executeToolCall,
   runWithAuthContext,
   toolDefinitions
-} from "./chunk-Z2X5CQMK.js";
+} from "./chunk-7FF5Q3TT.js";
 import {
   external_exports
-} from "./chunk-HK6JH3R3.js";
-import "./chunk-2M6BYRVF.js";
+} from "./chunk-F5V42P6U.js";
+import "./chunk-PAGW2Y3I.js";
 import {
+  getDefaultPolicy,
+  import_shared,
   import_websocket,
+  initNodeTelemetry,
+  parseDeploymentType,
   require_dist
-} from "./chunk-STWY7L44.js";
-import "./chunk-U4R6POH4.js";
-import "./chunk-72HOGMVP.js";
-import "./chunk-PSOBYRL5.js";
-import "./chunk-LQB4PWSW.js";
-import "./chunk-3CHQLJTS.js";
-import "./chunk-OK32IXZD.js";
+} from "./chunk-YBAGYCX4.js";
+import "./chunk-QVKSQHMA.js";
+import "./chunk-I4TBU2RS.js";
+import "./chunk-RH52ZSDO.js";
+import "./chunk-VPLRE4U5.js";
+import "./chunk-O4SXABRB.js";
+import "./chunk-BOHZPNHE.js";
 import {
+  SpanStatusCode,
+  context,
   init_esm,
-  metrics
-} from "./chunk-AMN5CPNU.js";
+  metrics,
+  trace
+} from "./chunk-NHR7FAPE.js";
 import {
   __require,
   __toESM,
   init_cjs_shims
-} from "./chunk-Q6H6AYB3.js";
+} from "./chunk-LTWZXD76.js";
 
 // ../../../gateway/dist/index.js
 init_cjs_shims();
@@ -232,7 +239,7 @@ function formatCaptureModeSummary(input) {
 
 // ../../../gateway/dist/capabilities/lifecycle.js
 init_cjs_shims();
-var import_shared2 = __toESM(require_dist());
+var import_shared3 = __toESM(require_dist());
 import { randomUUID } from "node:crypto";
 import { readFile, realpath, stat } from "node:fs/promises";
 import path2 from "node:path";
@@ -437,7 +444,7 @@ function buildOpenablePreviewUrls(input) {
 
 // ../../../gateway/dist/server/client.js
 init_cjs_shims();
-var import_shared = __toESM(require_dist());
+var import_shared2 = __toESM(require_dist());
 
 // ../../../gateway/dist/telemetry/metrics.js
 init_cjs_shims();
@@ -841,7 +848,7 @@ var HttpSuperblocksServerClient = class {
   }
   async uploadAttachment(input) {
     const mimeType = input.mimeType ?? "application/zip";
-    const response = await (0, import_shared.uploadAttachmentToServerApi)({
+    const response = await (0, import_shared2.uploadAttachmentToServerApi)({
       applicationId: input.applicationId,
       authorization: `Bearer ${input.apiKey}`,
       baseUrl: this.baseUrl(),
@@ -888,10 +895,18 @@ var HttpSuperblocksServerClient = class {
    */
   async issueScopedToken(input) {
     const scope = input.scope ?? "apps:update";
-    const body = {
-      applicationId: input.applicationId,
-      scope
-    };
+    const body = { scope };
+    if (scope === "integrations:build") {
+      if (!input.integrationId?.trim()) {
+        throw new Error("integrations:build scoped tokens require an integrationId; the token authorizes exactly one integration");
+      }
+      body.integrationId = input.integrationId;
+    } else {
+      if (!input.applicationId?.trim()) {
+        throw new Error(`${scope} scoped tokens require an applicationId`);
+      }
+      body.applicationId = input.applicationId;
+    }
     if (scope === "apps:preview") {
       if (!input.commitId?.trim()) {
         throw new Error("apps:preview scoped tokens require a commitId so the viewer can load that commit");
@@ -1831,37 +1846,37 @@ async function captureModeOf(ctx) {
   });
 }
 function libraryCaptureInput(ctx, applicationId) {
-  const context = ctx.sessionPeer.libraryBrowserContext?.(applicationId);
-  if (!context) {
+  const context2 = ctx.sessionPeer.libraryBrowserContext?.(applicationId);
+  if (!context2) {
     return void 0;
   }
-  const auth = context.initData.devServerAuthorization;
+  const auth = context2.initData.devServerAuthorization;
   if (!auth) {
     console.error("gateway live canvas skipped: missing_dev_server_authorization", { applicationId });
     return void 0;
   }
   return {
     bootstrapData: {
-      accessToken: context.bootstrapData.accessToken,
-      agents: context.bootstrapData.agents ?? [],
-      ...context.bootstrapData.agentUrls ? { agentUrls: context.bootstrapData.agentUrls } : {},
-      appId: context.bootstrapData.appId,
+      accessToken: context2.bootstrapData.accessToken,
+      agents: context2.bootstrapData.agents ?? [],
+      ...context2.bootstrapData.agentUrls ? { agentUrls: context2.bootstrapData.agentUrls } : {},
+      appId: context2.bootstrapData.appId,
       devServerAuthorization: auth,
-      ...context.bootstrapData.featureFlags ? { featureFlags: context.bootstrapData.featureFlags } : {},
-      ...context.bootstrapData.orgId ? { orgId: context.bootstrapData.orgId } : {},
-      ...context.bootstrapData.profiles ? { profiles: context.bootstrapData.profiles } : {},
-      token: context.bootstrapData.token,
-      ...context.bootstrapData.userEmail ? { userEmail: context.bootstrapData.userEmail } : {},
-      userId: context.bootstrapData.userId,
-      ...context.bootstrapData.windowOriginUrl ? { windowOriginUrl: context.bootstrapData.windowOriginUrl } : {}
+      ...context2.bootstrapData.featureFlags ? { featureFlags: context2.bootstrapData.featureFlags } : {},
+      ...context2.bootstrapData.orgId ? { orgId: context2.bootstrapData.orgId } : {},
+      ...context2.bootstrapData.profiles ? { profiles: context2.bootstrapData.profiles } : {},
+      token: context2.bootstrapData.token,
+      ...context2.bootstrapData.userEmail ? { userEmail: context2.bootstrapData.userEmail } : {},
+      userId: context2.bootstrapData.userId,
+      ...context2.bootstrapData.windowOriginUrl ? { windowOriginUrl: context2.bootstrapData.windowOriginUrl } : {}
     },
-    iframeBaseUrl: context.iframeBaseUrl,
+    iframeBaseUrl: context2.iframeBaseUrl,
     initData: {
-      appId: context.initData.appId,
+      appId: context2.initData.appId,
       devServerAuthorization: auth,
-      peerId: context.initData.peerId,
-      ...context.initData.userId ? { userId: context.initData.userId } : {},
-      ...context.initData.windowOriginUrl ? { windowOriginUrl: context.initData.windowOriginUrl } : {}
+      peerId: context2.initData.peerId,
+      ...context2.initData.userId ? { userId: context2.initData.userId } : {},
+      ...context2.initData.windowOriginUrl ? { windowOriginUrl: context2.initData.windowOriginUrl } : {}
     }
   };
 }
@@ -1985,13 +2000,15 @@ function defaultAppName(prompt) {
 async function ensurePrincipal(ctx) {
   const { principal } = ctx;
   if (principal.organizationId && principal.userId) {
+    const resolved2 = {
+      ...principal,
+      organizationId: principal.organizationId,
+      userId: principal.userId
+    };
+    ctx.onPrincipalResolved?.(resolved2);
     return {
       kind: "ok",
-      value: {
-        ...principal,
-        organizationId: principal.organizationId,
-        userId: principal.userId
-      }
+      value: resolved2
     };
   }
   let validated;
@@ -2021,14 +2038,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
   };
 }
 async function nameWithClark(ctx, input) {
@@ -2221,7 +2240,7 @@ function turnSummary(turn) {
     return "Superblocks is still working, but only the editor can show it \u2014 open the edit URL";
   }
   if (turn.generationStatus === "live_edit_terminated") {
-    return "The Superblocks live-edit session terminated before anything was built \u2014 send the prompt again with edit_app";
+    return turn.retryAction === "retry_import" ? "The Superblocks live-edit session terminated before anything was built \u2014 send the archive again with import_app" : "The Superblocks live-edit session terminated before anything was built \u2014 send the prompt again with edit_app";
   }
   if (turn.checkpointCommitId) {
     return `Application ready \u2014 checkpoint saved. ${NEXT_STEPS}`;
@@ -2347,6 +2366,7 @@ async function forwardClarkPrompt(ctx, input) {
       generationStatus: forward.generationStatus,
       ...forward.liveEditId ? { liveEditId: forward.liveEditId } : {},
       ...forward.recentRuns && forward.recentRuns.length > 0 ? { recentRuns: forward.recentRuns } : {},
+      ...forward.retryAction ? { retryAction: forward.retryAction } : {},
       viewStatus: forward.viewStatus
     }
   };
@@ -2392,7 +2412,7 @@ function namingCreatedApplication(applicationId, capability, result) {
   return namingApplication(applicationId, result);
 }
 function retryIfReplayable(attachments) {
-  return attachments && attachments.length > 0 ? void 0 : { pendingAction: "retry_build" };
+  return attachments && attachments.length > 0 ? { pendingAction: "retry_import" } : { pendingAction: "retry_build" };
 }
 function liveEditUnavailable(error, attachments) {
   return {
@@ -2413,7 +2433,8 @@ 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
     });
   } catch (error) {
@@ -2443,7 +2464,12 @@ async function promptNewApplication(ctx, args) {
       organizationId: principal.organizationId
     });
   } 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?.({
@@ -2638,7 +2664,7 @@ async function resolveImportArchive(input, searchDirs) {
   if (bytes.byteLength > IMPORT_ZIP_MAX_BYTES) {
     return tooLargeError(bytes.byteLength);
   }
-  const archiveType = (0, import_shared2.detectAttachmentArchiveType)({ fileName });
+  const archiveType = (0, import_shared3.detectAttachmentArchiveType)({ fileName });
   if (archiveType === null) {
     return {
       kind: "error",
@@ -2680,14 +2706,15 @@ function normalizeImportSource(source) {
   }
 }
 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);
@@ -2698,23 +2725,26 @@ 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;
-  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,
@@ -2722,7 +2752,8 @@ async function importApp(ctx, input) {
     name,
     principal,
     source
-  }));
+  });
+  return resumedApplicationId ? namingApplication(applicationId, result) : namingCreatedApplication(applicationId, "import_app", result);
 }
 async function migrateArchiveIntoApplication(ctx, args) {
   const { applicationId, archive, principal } = args;
@@ -2741,10 +2772,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
+      message,
+      pendingAction: "retry_import"
     };
   }
   return promptNewApplication(ctx, {
@@ -2829,7 +2868,7 @@ async function checkAppProgress(ctx, input) {
   }
   const applicationId = resolved.value;
   if (ctx.signal?.aborted) {
-    return cancelled("check_app_progress");
+    return namingApplication(applicationId, cancelled("check_app_progress"));
   }
   const cursorKey2 = cursorKeyFor(ctx, principal, applicationId);
   const stored = cursorKey2 ? await ctx.progressCursors?.getCursor(cursorKey2) : void 0;
@@ -2841,7 +2880,7 @@ 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,
@@ -2915,6 +2954,7 @@ 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
     }
@@ -3336,7 +3376,11 @@ function localUnbuiltReason(turn, pending) {
     return void 0;
   }
   const status = emptyTurnStatus(turn.generationStatus);
-  return status ? { kind: "empty_turn", status } : void 0;
+  return status ? {
+    kind: "empty_turn",
+    retryAction: turn.retryAction ?? "retry_build",
+    status
+  } : void 0;
 }
 async function persistedUnbuiltReason(ctx, principal, applicationId) {
   let snapshot;
@@ -3379,6 +3423,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
@@ -3437,7 +3483,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 {
@@ -3539,7 +3589,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"));
     }
     if (nowMs(ctx) >= deadline) {
       return { kind: "ok", value: { built: false } };
@@ -4193,7 +4243,7 @@ async function createStores() {
 // ../../../gateway/dist/sabs/websocket-session-peer.js
 init_cjs_shims();
 import { randomUUID as randomUUID3 } from "node:crypto";
-var import_shared5 = __toESM(require_dist());
+var import_shared6 = __toESM(require_dist());
 
 // ../../../gateway/dist/agents/resolve-orchestrator-url.js
 init_cjs_shims();
@@ -4514,15 +4564,15 @@ var HttpOrchestratorClient = class {
 
 // ../../../gateway/dist/sabs/browser-context.js
 init_cjs_shims();
-var import_shared3 = __toESM(require_dist());
+var import_shared4 = __toESM(require_dist());
 function toProfile(row) {
-  return new import_shared3.Profile({
+  return new import_shared4.Profile({
     allowedInEditor: row.allowedInEditor,
     description: "",
     displayName: row.displayName ?? row.key,
     id: row.id ?? row.key,
     key: row.key,
-    type: import_shared3.ProfileType.RESERVED
+    type: import_shared4.ProfileType.RESERVED
   });
 }
 function selectProfiles(input) {
@@ -4586,7 +4636,7 @@ function buildBrowserContext(input) {
 
 // ../../../gateway/dist/sabs/editor-client-methods.js
 init_cjs_shims();
-var import_shared4 = __toESM(require_dist());
+var import_shared5 = __toESM(require_dist());
 
 // ../../../gateway/dist/integrations/map.js
 init_cjs_shims();
@@ -4741,7 +4791,7 @@ function sanitizeAgentFacingValue(value) {
 }
 
 // ../../../gateway/dist/sabs/editor-client-methods.js
-var ADMIN_MCP_SETUP_MESSAGE = "Integrations CRUD is available on this Superblocks MCP via create_integration, update_integration, and list_integrations (same connector as start_app). Use those Admin tools, then continue with edit_app. The headless editor session cannot open the Integrations UI.";
+var ADMIN_MCP_SETUP_MESSAGE = "Integrations CRUD is available on this Superblocks MCP via get_integration_config_schema, create_integration, update_integration, and list_integrations (same connector as start_app). Call get_integration_config_schema before create_integration. Use those Admin tools, then continue with edit_app. The headless editor session cannot open the Integrations UI.";
 var HEADLESS_AUTO_APPROVED_TOOLS = /* @__PURE__ */ new Set([
   "build_deleteFile",
   "build_installPackages",
@@ -4827,27 +4877,27 @@ function clarifySdkExecutionErrorMessage(message) {
   }
   return sanitizeAgentFacingText(clarified);
 }
-async function executeRequestToIntegrationViaOrchestrator(context, payload) {
+async function executeRequestToIntegrationViaOrchestrator(context2, payload) {
   let pluginId = payload.integrationHint?.type;
   let integrationName = payload.integrationHint?.displayName ?? payload.integrationHint?.name ?? "Integration";
   if (!pluginId) {
     let row;
     try {
-      row = await context.server.getIntegration({
-        apiKey: context.apiKey,
+      row = await context2.server.getIntegration({
+        apiKey: context2.apiKey,
         integrationId: payload.integrationId
       });
       if (!row) {
-        const rows = await context.server.getSupersetIntegrations({
-          apiKey: context.apiKey,
-          applicationId: context.applicationId,
-          organizationId: context.organizationId
+        const rows = await context2.server.getSupersetIntegrations({
+          apiKey: context2.apiKey,
+          applicationId: context2.applicationId,
+          organizationId: context2.organizationId
         });
         row = rows.find((candidate) => candidate.id === payload.integrationId);
       }
     } catch (error) {
       console.warn("gateway failed to resolve integration for execute", {
-        applicationId: context.applicationId,
+        applicationId: context2.applicationId,
         integrationId: payload.integrationId,
         message: error instanceof Error ? error.message : String(error)
       });
@@ -4860,7 +4910,7 @@ async function executeRequestToIntegrationViaOrchestrator(context, payload) {
     pluginId = row.pluginId;
     integrationName = row.name || integrationName;
   }
-  const pluginIdForStep = (0, import_shared4.getBasePluginId)(pluginId);
+  const pluginIdForStep = (0, import_shared5.getBasePluginId)(pluginId);
   const now = (/* @__PURE__ */ new Date()).toISOString();
   const inlineApiId = `ai-inline-${payload.integrationId}-${Date.now()}`;
   const definition = {
@@ -4876,14 +4926,14 @@ async function executeRequestToIntegrationViaOrchestrator(context, payload) {
     metadata: {
       id: inlineApiId,
       name: `${integrationName} AI Query`,
-      organization: context.organizationId,
+      organization: context2.organizationId,
       timestamps: { created: now, updated: now }
     },
     trigger: { application: {} }
   };
   try {
-    const result = await context.orchestrator.executeV2Api({
-      apiKey: context.apiKey,
+    const result = await context2.orchestrator.executeV2Api({
+      apiKey: context2.apiKey,
       body: {
         definition: { api: definition },
         inputs: {},
@@ -4894,10 +4944,10 @@ async function executeRequestToIntegrationViaOrchestrator(context, payload) {
           isAiTriggered: true,
           suppressTracking: true
         },
-        ...context.profileKey ? { profile: { name: context.profileKey } } : {}
+        ...context2.profileKey ? { profile: { name: context2.profileKey } } : {}
       },
-      profileKey: context.profileKey,
-      scopedToken: context.sessionToken
+      profileKey: context2.profileKey,
+      scopedToken: context2.sessionToken
     });
     if (result && typeof result === "object" && "systemError" in result) {
       const systemError = String(result.systemError ?? "Integration execution failed");
@@ -4933,11 +4983,11 @@ async function executeRequestToIntegrationViaOrchestrator(context, payload) {
     return { error: clarifySdkExecutionErrorMessage(message) };
   }
 }
-async function loadIntegrationsForPrompt(context) {
-  const rows = await context.server.getSupersetIntegrations({
-    apiKey: context.apiKey,
-    applicationId: context.applicationId,
-    organizationId: context.organizationId
+async function loadIntegrationsForPrompt(context2) {
+  const rows = await context2.server.getSupersetIntegrations({
+    apiKey: context2.apiKey,
+    applicationId: context2.applicationId,
+    organizationId: context2.organizationId
   });
   return listIntegrationsForClark(rows);
 }
@@ -5082,10 +5132,9 @@ function createEditorClientMethods(getListener, onInbound, deps) {
     ],
     updateApiInputs: ack,
     updateScope: ack,
-    // No browser tab means no viewport to photograph. The flag matters more
-    // than the message: it tells the ai-service this was a refusal, not a
-    // failed capture, so Clark can fall back to the sandbox's own browser
-    // instead of reporting that it cannot see the app it just built.
+    // No browser tab means no viewport to photograph. viewportUnavailable
+    // marks this as a refusal, not a failed capture. The screenshot tool
+    // does not read that flag; MCP turns omit the tool via disabledTools.
     aiCaptureScreenshot: [
       async () => ({
         error: "the headless gateway session has no browser viewport",
@@ -5097,13 +5146,13 @@ function createEditorClientMethods(getListener, onInbound, deps) {
     aiDeleteIntegration: setupUnavailable,
     aiExecuteRequestToIntegration: [
       async (payload) => {
-        const context = deps?.getContext();
-        if (!context) {
+        const context2 = deps?.getContext();
+        if (!context2) {
           return {
             error: "the headless gateway session cannot execute integration requests without an active prompt session"
           };
         }
-        const result = await executeRequestToIntegrationViaOrchestrator(context, payload);
+        const result = await executeRequestToIntegrationViaOrchestrator(context2, payload);
         const name = payload.integrationHint?.name || payload.integrationId || "integration";
         deps?.onToolRun?.({
           detail: result,
@@ -5116,8 +5165,8 @@ function createEditorClientMethods(getListener, onInbound, deps) {
     ],
     aiExecuteSdkApi: [
       async (payload) => {
-        const context = deps?.getContext();
-        if (!context) {
+        const context2 = deps?.getContext();
+        if (!context2) {
           throw missingSessionError("execute SDK APIs");
         }
         if (!payload.entryPoint) {
@@ -5137,7 +5186,7 @@ function createEditorClientMethods(getListener, onInbound, deps) {
           return missing;
         }
         try {
-          const inSync = await context.waitUntilFilesSynced();
+          const inSync = await context2.waitUntilFilesSynced();
           if (!inSync) {
             const syncing = {
               success: false,
@@ -5154,15 +5203,15 @@ function createEditorClientMethods(getListener, onInbound, deps) {
             });
             return syncing;
           }
-          const response = await context.orchestrator.executeSdkApiV3({
-            apiKey: context.apiKey,
-            applicationId: context.applicationId,
-            branchName: context.branchName,
+          const response = await context2.orchestrator.executeSdkApiV3({
+            apiKey: context2.apiKey,
+            applicationId: context2.applicationId,
+            branchName: context2.branchName,
             entryPoint: payload.entryPoint,
             exportName: payload.exportName,
             inputs: payload.input ?? {},
-            profileKey: context.profileKey,
-            scopedToken: context.sessionToken
+            profileKey: context2.profileKey,
+            scopedToken: context2.sessionToken
           });
           const mapped = mapSdkExecutionResponse(response);
           deps?.onToolRun?.({
@@ -5192,8 +5241,8 @@ function createEditorClientMethods(getListener, onInbound, deps) {
     ],
     aiExecuteV2Api: [
       async (payload) => {
-        const context = deps?.getContext();
-        if (!context) {
+        const context2 = deps?.getContext();
+        if (!context2) {
           throw missingSessionError("execute V2 APIs");
         }
         if (payload.api.type === "fetch") {
@@ -5206,14 +5255,14 @@ function createEditorClientMethods(getListener, onInbound, deps) {
           ...payload.api.definition,
           metadata: {
             ...payload.api.definition.metadata ?? {},
-            organization: context.organizationId,
+            organization: context2.organizationId,
             timestamps: { created: now, updated: now }
           },
           trigger: { application: {} }
         };
         try {
-          const result = await context.orchestrator.executeV2Api({
-            apiKey: context.apiKey,
+          const result = await context2.orchestrator.executeV2Api({
+            apiKey: context2.apiKey,
             body: {
               definition: { api: definition },
               inputs: payload.inputs ?? {},
@@ -5224,10 +5273,10 @@ function createEditorClientMethods(getListener, onInbound, deps) {
                 isAiTriggered: true,
                 suppressTracking: true
               },
-              ...context.profileKey ? { profile: { name: context.profileKey } } : {}
+              ...context2.profileKey ? { profile: { name: context2.profileKey } } : {}
             },
-            profileKey: context.profileKey,
-            scopedToken: context.sessionToken
+            profileKey: context2.profileKey,
+            scopedToken: context2.sessionToken
           });
           if (result && typeof result === "object" && "systemError" in result) {
             return result;
@@ -5249,27 +5298,27 @@ function createEditorClientMethods(getListener, onInbound, deps) {
     ],
     aiGetIntegration: [
       async (payload) => {
-        const context = deps?.getContext();
-        if (!context) {
+        const context2 = deps?.getContext();
+        if (!context2) {
           throw missingSessionError("provide integration metadata");
         }
         let row;
         try {
-          row = await context.server.getIntegration({
-            apiKey: context.apiKey,
+          row = await context2.server.getIntegration({
+            apiKey: context2.apiKey,
             integrationId: payload.integrationId
           });
           if (!row) {
-            const rows = await context.server.getSupersetIntegrations({
-              apiKey: context.apiKey,
-              applicationId: context.applicationId,
-              organizationId: context.organizationId
+            const rows = await context2.server.getSupersetIntegrations({
+              apiKey: context2.apiKey,
+              applicationId: context2.applicationId,
+              organizationId: context2.organizationId
             });
             row = rows.find((candidate) => candidate.id === payload.integrationId);
           }
         } catch (error) {
           console.warn("gateway failed to load integration for Clark", {
-            applicationId: context.applicationId,
+            applicationId: context2.applicationId,
             integrationId: payload.integrationId,
             message: error instanceof Error ? error.message : String(error)
           });
@@ -5285,11 +5334,11 @@ function createEditorClientMethods(getListener, onInbound, deps) {
         }
         let metadata = {};
         try {
-          metadata = await context.orchestrator.getMetadata({
-            apiKey: context.apiKey,
+          metadata = await context2.orchestrator.getMetadata({
+            apiKey: context2.apiKey,
             integrationId: payload.integrationId,
-            profileKey: context.profileKey,
-            scopedToken: context.sessionToken
+            profileKey: context2.profileKey,
+            scopedToken: context2.sessionToken
           });
         } catch {
           metadata = {};
@@ -5311,15 +5360,15 @@ function createEditorClientMethods(getListener, onInbound, deps) {
     ],
     aiGetIntegrations: [
       async () => {
-        const context = deps?.getContext();
-        if (!context) {
+        const context2 = deps?.getContext();
+        if (!context2) {
           return [];
         }
         try {
-          return await loadIntegrationsForPrompt(context);
+          return await loadIntegrationsForPrompt(context2);
         } catch (error) {
           console.warn("gateway failed to list integrations for Clark", {
-            applicationId: context.applicationId,
+            applicationId: context2.applicationId,
             message: error instanceof Error ? error.message : String(error)
           });
           return [];
@@ -5420,6 +5469,7 @@ function truncate(text, max = RECENT_TOOL_RUN_SUMMARY_MAX) {
 var GENERATE_METHOD = "editor.aiGenerateWithQueue";
 var ACCEPT_DRAFT_METHOD = "editor.aiAcceptDraft";
 var RELOAD_CHAT_METHOD = "editor.aiChatGetMessages";
+var RELEASE_TURN_LOCK_METHOD = "editor.releaseTurnLock";
 var RESPOND_TOOL_PERMISSION_METHOD = "editor.aiRespondToToolPermission";
 var PING_METHOD = "editor.ping";
 var DEFAULT_TIMEOUT_MS3 = 12e4;
@@ -5761,6 +5811,7 @@ var WebSocketSessionPeer = class {
     this.failedStarts.set(input, {
       generationStatus: "live_edit_terminated",
       reply: input.reason,
+      ...input.retryAction ? { retryAction: input.retryAction } : {},
       // Nothing ran, so nothing is viewable. Reporting "ready" here is how a
       // caller comes to show the untouched starter template as the app.
       viewStatus: "unknown"
@@ -5793,7 +5844,11 @@ var WebSocketSessionPeer = class {
     }
     const failed = this.failedStarts.get(input);
     if (failed) {
-      return { generationStatus: failed.generationStatus, phase: "finished" };
+      return {
+        generationStatus: failed.generationStatus,
+        phase: "finished",
+        ...failed.retryAction ? { retryAction: failed.retryAction } : {}
+      };
     }
     if (!turn?.finished) {
       return void 0;
@@ -5801,7 +5856,8 @@ var WebSocketSessionPeer = class {
     return {
       ...turn.finished.checkpointCommitId ? { checkpointCommitId: turn.finished.checkpointCommitId } : {},
       generationStatus: turn.finished.generationStatus,
-      phase: "finished"
+      phase: "finished",
+      ...turn.retryAction ? { retryAction: turn.retryAction } : {}
     };
   }
   clearPendingPlan(applicationId) {
@@ -5947,6 +6003,7 @@ var WebSocketSessionPeer = class {
       normalized: void 0,
       recentRuns: [],
       reconnects: 0,
+      ...input.attachments?.length ? { retryAction: "retry_import" } : {},
       startedAt: Date.now(),
       turnId: randomUUID3(),
       unsubscribe: () => void 0,
@@ -6007,6 +6064,7 @@ var WebSocketSessionPeer = class {
         jwt: input.sessionToken,
         llmConfig: {
           coreModel: this.options.coreModel ?? DEFAULT_LLM.coreModel,
+          disabledTools: ["build_captureScreenshot", "build_navigatePreview"],
           // The ai-service gates Clark's testing tools on this flag *and* a
           // browser context, so the two travel together or not at all.
           ...browserContext ? { flags: { isTestingEnabled: true } } : {},
@@ -6112,6 +6170,7 @@ var WebSocketSessionPeer = class {
         elapsedMs,
         status: "finished",
         ...turn.finished,
+        ...turn.retryAction ? { retryAction: turn.retryAction } : {},
         ...recentRuns ? { recentRuns } : {}
       };
     }
@@ -6252,6 +6311,15 @@ var WebSocketSessionPeer = class {
       collector.dispose();
       const stillMapped = this.turns.get(input.applicationId) === turn;
       if (stillMapped) {
+        try {
+          await turn.held.client.requestWithTracing(RELEASE_TURN_LOCK_METHOD, this.turnCorrelator(turn.turnId), {}, `Bearer ${input.sessionToken}`);
+        } catch (error) {
+          console.warn("gateway could not release the live-edit turn lock", {
+            applicationId: input.applicationId,
+            message: describeSocketError(error),
+            turnId: turn.turnId
+          });
+        }
         if (turn.finished?.generationStatus === "needs_decision") {
           this.armIdle(turn.held);
         } else {
@@ -6668,7 +6736,7 @@ var WebSocketSessionPeer = class {
     const heldRef = {
       current: void 0
     };
-    const socket = new import_shared5.ISocket(ws, createEditorClientMethods(() => {
+    const socket = new import_shared6.ISocket(ws, createEditorClientMethods(() => {
       const listeners = heldRef.current?.listeners;
       if (!listeners || listeners.size === 0) {
         return void 0;
@@ -6745,7 +6813,7 @@ var WebSocketSessionPeer = class {
         noResponseTimeoutInSeconds: (this.options.timeoutMs ?? DEFAULT_TIMEOUT_MS3) / 1e3
       }
     });
-    const client = (0, import_shared5.createISocketClient)(socket);
+    const client = (0, import_shared6.createISocketClient)(socket);
     const heartbeat = this.buildHeartbeat(heldRef);
     const held = {
       applicationId: input.applicationId,
@@ -6781,7 +6849,7 @@ var WebSocketSessionPeer = class {
    * who to tell.
    */
   buildHeartbeat(heldRef) {
-    return new import_shared5.SocketHeartbeat({
+    return new import_shared6.SocketHeartbeat({
       beat: async () => {
         const held = heldRef.current;
         if (!held?.sessionToken) {
@@ -7308,6 +7376,233 @@ var WebSocketSessionPeer = class {
   }
 };
 
+// ../../../gateway/dist/telemetry/runtime.js
+init_cjs_shims();
+
+// ../../../gateway/dist/telemetry/mcp-client.js
+init_cjs_shims();
+init_esm();
+function bounded(value, maxLength) {
+  return value.slice(0, maxLength);
+}
+function stringProperty(value, key2) {
+  if (typeof value !== "object" || value === null || !(key2 in value)) {
+    return void 0;
+  }
+  const property = Reflect.get(value, key2);
+  return typeof property === "string" ? property : void 0;
+}
+var McpClientTelemetry = class {
+  tracer;
+  ended = false;
+  hadError = false;
+  organizationId;
+  sessionContext;
+  sessionSpan;
+  constructor(tracer) {
+    this.tracer = tracer;
+    this.sessionSpan = tracer.startSpan("gen_ai.request", {
+      attributes: {
+        "gen_ai.operation.name": "invoke_agent"
+      }
+    });
+    this.sessionContext = trace.setSpan(context.active(), this.sessionSpan);
+  }
+  setOrganizationId(organizationId) {
+    this.organizationId = organizationId;
+    this.sessionSpan.setAttribute("organization.id", organizationId);
+  }
+  async runTool(call, operation) {
+    const attributes = {
+      "gen_ai.operation.name": "execute_tool",
+      ...call.client ? {
+        "mcp.client.name": bounded(call.client.name, 80),
+        ...call.client.version ? {
+          "mcp.client.version": bounded(call.client.version, 40)
+        } : {}
+      } : {},
+      ...this.organizationId ? { "organization.id": this.organizationId } : {},
+      "tool.name": bounded(call.toolName, 80)
+    };
+    if (call.client) {
+      this.sessionSpan.setAttributes({
+        "mcp.client.name": bounded(call.client.name, 80),
+        ...call.client.version ? { "mcp.client.version": bounded(call.client.version, 40) } : {}
+      });
+    }
+    let span;
+    try {
+      span = this.tracer.startSpan("gen_ai.tool_call", { attributes }, this.sessionContext);
+    } catch {
+      return operation();
+    }
+    const startedAt = Date.now();
+    try {
+      const result = await context.with(trace.setSpan(this.sessionContext, span), operation);
+      span.setAttribute("tool.duration_ms", Date.now() - startedAt);
+      if (this.organizationId) {
+        span.setAttribute("organization.id", this.organizationId);
+      }
+      if (result.kind === "error") {
+        this.hadError = true;
+        span.setAttributes({
+          ...result.applicationId ? { "application.id": result.applicationId } : {},
+          "mcp.error.code": bounded(result.code, 80),
+          "tool.error_category": result.code === "cancelled" ? "timeout" : "execution_error",
+          "tool.status": "error"
+        });
+        span.setStatus({ code: SpanStatusCode.ERROR });
+      } else if (result.kind === "auth_required") {
+        this.hadError = true;
+        span.setAttributes({
+          "mcp.result.status": "auth_required",
+          "tool.error_category": "permission_denied",
+          "tool.status": "error"
+        });
+      } else {
+        const applicationId = stringProperty(result.value, "applicationId");
+        const resultStatus = stringProperty(result.value, "status");
+        span.setAttributes({
+          ...applicationId ? { "application.id": applicationId } : {},
+          ...resultStatus ? { "mcp.result.status": bounded(resultStatus, 80) } : {},
+          "tool.error_category": "none",
+          "tool.status": "success"
+        });
+      }
+      return result;
+    } catch (error) {
+      this.hadError = true;
+      span.setAttributes({
+        "tool.duration_ms": Date.now() - startedAt,
+        "tool.error_category": "execution_error",
+        "tool.status": "error"
+      });
+      span.setStatus({ code: SpanStatusCode.ERROR });
+      throw error;
+    } finally {
+      span.end();
+    }
+  }
+  endSession() {
+    if (this.ended) {
+      return;
+    }
+    this.ended = true;
+    this.sessionSpan.setAttribute("gen_ai.request.status", this.hadError ? "error" : "success");
+    this.sessionSpan.end();
+  }
+};
+
+// ../../../gateway/dist/telemetry/runtime.js
+var TELEMETRY_SHUTDOWN_MS = 2e3;
+function logToStderr(first, message) {
+  if (message === void 0) {
+    console.error(first);
+    return;
+  }
+  console.error(first, message);
+}
+var stderrLogger = {
+  error: logToStderr,
+  info: logToStderr,
+  warn: logToStderr
+};
+function telemetryBaseUrl(serverUrl) {
+  try {
+    const url = new URL(serverUrl);
+    url.hash = "";
+    url.pathname = `${url.pathname.replace(/\/$/u, "")}/api`;
+    url.search = "";
+    return url.toString().replace(/\/$/u, "");
+  } catch {
+    console.error("gateway telemetry skipped: server URL is not parseable");
+    return void 0;
+  }
+}
+function environmentName(config) {
+  if (config.deploymentEnvironmentName !== "unknown") {
+    return config.deploymentEnvironmentName;
+  }
+  try {
+    return environmentFromHostname(new URL(config.serverUrl).hostname);
+  } catch {
+    return "unknown";
+  }
+}
+function environmentFromHostname(hostname) {
+  if (hostname.match(/^app\.superblocks(?:hq)?\.com$/u)) {
+    return "prod";
+  }
+  if (hostname.match(/^eu\.superblocks(?:hq)?\.com$/u)) {
+    return "prod-eu";
+  }
+  if (hostname.match(/^staging\.superblocks(?:hq)?\.com$/u)) {
+    return "staging";
+  }
+  if (hostname.match(/^dev\.superblocks(?:hq)?\.com$/u)) {
+    return "dev";
+  }
+  if (hostname.match(/^pr-[0-9]+\.superblocks(?:hq)?\.dev$/u)) {
+    return "ephemeral";
+  }
+  if (hostname === "localhost" || hostname === "127.0.0.1") {
+    return "local";
+  }
+  return "other";
+}
+function deploymentTypeFor(config) {
+  if (config.localAgentMode) {
+    return import_shared.DeploymentTypeEnum.CLOUD_PREM;
+  }
+  try {
+    return parseDeploymentType(process.env.SUPERBLOCKS_DEPLOYMENT_TYPE);
+  } catch {
+    return import_shared.DeploymentTypeEnum.CLOUD;
+  }
+}
+async function settleWithin(work, timeoutMs) {
+  let timer;
+  try {
+    await Promise.race([
+      work,
+      new Promise((resolve) => {
+        timer = setTimeout(resolve, timeoutMs);
+      })
+    ]);
+  } finally {
+    if (timer !== void 0) {
+      clearTimeout(timer);
+    }
+  }
+}
+function startGatewayTelemetry(input) {
+  const otlpUrl = telemetryBaseUrl(input.config.serverUrl);
+  const telemetry = initNodeTelemetry({
+    environment: environmentName(input.config),
+    logger: stderrLogger,
+    logsEnabled: false,
+    // Counters in metrics.ts are created at import time, before this SDK
+    // starts, so they stay no-ops. Do not turn metrics on until those
+    // instruments are created after init.
+    metricsEnabled: false,
+    otlpHeaders: { Authorization: `Bearer ${input.apiKey}` },
+    ...otlpUrl ? { otlpUrl } : {},
+    serviceName: "gateway",
+    serviceVersion: "0.0.1"
+  }, getDefaultPolicy(deploymentTypeFor(input.config)));
+  const mcpTelemetry = new McpClientTelemetry(telemetry.getTracer("gateway.mcp"));
+  return {
+    mcpTelemetry,
+    shutdown: async () => {
+      try {
+        mcpTelemetry.endSession();
+      } finally {
+        await settleWithin(telemetry.shutdown(), TELEMETRY_SHUTDOWN_MS);
+      }
+    }
+  };
+}
+
 // ../../../gateway/dist/transports/mcp/mount.js
 init_cjs_shims();
 import { randomUUID as randomUUID4 } from "node:crypto";
@@ -7407,6 +7702,150 @@ function N3(Z, $, J, X, V) {
   return Z.registerResource($, J, { mimeType: p, ...X }, V);
 }
 
+// ../../../gateway/dist/capabilities/integration-metadata.js
+init_cjs_shims();
+var DEFAULT_LIMIT = 100;
+function labelPart(value) {
+  return typeof value === "string" ? value.trim().replaceAll(/[.[\]]/g, "_") : "";
+}
+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, path3 = "", entries = []) {
+  if (value === null || typeof value === "boolean" || typeof value === "number" || typeof value === "string") {
+    entries.push({ path: path3, value });
+    return entries;
+  }
+  if (Array.isArray(value)) {
+    const seen = /* @__PURE__ */ new Set();
+    value.forEach((entry, index) => {
+      const label = arrayEntryLabel(entry, index);
+      const unique = seen.has(label) ? `${label}#${index}` : label;
+      seen.add(unique);
+      metadataEntries(entry, `${path3}[${unique}]`, entries);
+    });
+    return entries;
+  }
+  if (value && typeof value === "object") {
+    for (const [key2, entry] of Object.entries(value)) {
+      metadataEntries(entry, path3 ? `${path3}.${key2}` : key2, entries);
+    }
+  }
+  return entries;
+}
+async function getIntegrationMetadata(context2, input) {
+  const principal = await ensurePrincipal(context2);
+  if (principal.kind !== "ok") {
+    return principal;
+  }
+  let applicationId;
+  let label = sanitizeAgentFacingText(input.integrationId);
+  try {
+    const resolved = await resolveApplicationId(context2, principal.value, input.applicationId);
+    applicationId = resolved.kind === "ok" ? resolved.value : void 0;
+    const rows = await context2.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 context2.server.getOrganizationProfiles({
+      apiKey: principal.value.apiKey,
+      organizationId: principal.value.organizationId
+    });
+    const profileKey = pickEditorProfileKey(context2.config.profileKey, profiles);
+    const inventory = await context2.server.getAgentInventory({
+      apiKey: principal.value.apiKey,
+      organizationId: principal.value.organizationId
+    });
+    const orchestratorUrl = pickOrchestratorBaseUrl({
+      agentType: inventory.agentType,
+      agents: inventory.agents,
+      profileKey
+    });
+    const scopedToken = await context2.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}`
+    };
+  }
+}
+
 // ../../../gateway/dist/capture/browser-instructions.js
 init_cjs_shims();
 var BROWSER_DRIVER_INSTRUCTIONS = `Browser capture (MUST):
@@ -8068,6 +8507,16 @@ function resolveToken(options, auth) {
 function superblocksProductCopy(text) {
   return text.replaceAll(/\bClark AI Apps\b/g, "Superblocks AI Apps").replaceAll(/\bClark\b/g, "Superblocks");
 }
+function completeToolAnnotations(annotations) {
+  const readOnlyHint = annotations?.readOnlyHint ?? false;
+  return {
+    ...annotations,
+    destructiveHint: annotations?.destructiveHint ?? (readOnlyHint ? false : true),
+    idempotentHint: annotations?.idempotentHint ?? readOnlyHint,
+    openWorldHint: annotations?.openWorldHint ?? true,
+    readOnlyHint
+  };
+}
 function registerAdminTools(server, options) {
   const registry = buildToolRegistry(toolDefinitions, "customer", {
     requireEntitledPlan: options.localAgentMode !== true
@@ -8078,7 +8527,7 @@ function registerAdminTools(server, options) {
     }
     const definition = toolDefinitions.find((d2) => d2.name === tool.name);
     server.registerTool(tool.name, {
-      annotations: tool.annotations,
+      annotations: completeToolAnnotations(tool.annotations),
       description: superblocksProductCopy(tool.description ?? ""),
       inputSchema: gatewayAdminInputShape(tool.inputSchema),
       title: tool.title ?? definition?.title
@@ -8119,7 +8568,7 @@ function registerAdminTools(server, options) {
 
 // ../../../gateway/dist/transports/mcp/app-status-html.js
 init_cjs_shims();
-var APP_STATUS_RESOURCE_URI = "ui://gateway/app-status-v6.html";
+var APP_STATUS_RESOURCE_URI = "ui://gateway/app-status-v8.html";
 var APP_STATUS_HTML = `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -8233,11 +8682,29 @@ var APP_STATUS_HTML = `<!DOCTYPE html>
   <script>
     (() => {
       const PROTOCOL_VERSION = "2026-01-26";
+      // Statuses get_app reports when the app is still the empty starter
+      // template. "building" is deliberately absent: the card only hears a
+      // build finished if a new result arrives, so a stale badge would strand
+      // the button.
+      const UNBUILT_STATUSES = [
+        "cancelled",
+        "live_edit_terminated",
+        "needs_decision",
+        "no_changes",
+        "timeout",
+      ];
+      const BLOCKED_ACTIONS = [
+        "answer_question",
+        "approve_plan",
+        "retry_build",
+        "retry_import",
+      ];
       let nextId = 1;
       const pending = new Map();
       let applicationId = "";
       let appName = "";
       let commitId = "";
+      let pendingAction = "";
       let editUrl = "";
       let previewUrl = "";
       let publishUrl = "";
@@ -8245,6 +8712,13 @@ var APP_STATUS_HTML = `<!DOCTYPE html>
       let canCallTools = false;
       let publishing = false;
       let lastHeight = 0;
+      let refreshInFlight = false;
+      let refreshTimer = 0;
+      let refreshGeneration = 0;
+      let refreshAttempts = 0;
+      let pollAfterMs = 2000;
+      const MIN_POLL_MS = 2000;
+      const MAX_REFRESH_ATTEMPTS = 40;
 
       function post(message) {
         window.parent.postMessage(message, "*");
@@ -8334,6 +8808,31 @@ var APP_STATUS_HTML = `<!DOCTYPE html>
         }
       }
 
+      /**
+       * True when publishing would deploy the empty starter template.
+       * pendingAction is the server's own "nothing to preview" signal;
+       * wait_for_build is the building exception. Status is only a fallback
+       * when the payload omitted pendingAction. loading/waiting with no
+       * preview fail closed so Publish is not clickable before get_app
+       * returns.
+       */
+      function nothingToPublish() {
+        if (previewUrl || publishUrl) {
+          return false;
+        }
+        if (pendingAction === "wait_for_build") {
+          return false;
+        }
+        if (BLOCKED_ACTIONS.indexOf(pendingAction) !== -1) {
+          return true;
+        }
+        const badge = element("status").textContent;
+        if (!badge || badge === "loading" || badge === "waiting") {
+          return true;
+        }
+        return UNBUILT_STATUSES.indexOf(badge) !== -1;
+      }
+
       /**
        * Keep URLs in memory for openLink \u2014 never print them (preview JWTs are
        * huge and ugly in the card).
@@ -8348,7 +8847,10 @@ var APP_STATUS_HTML = `<!DOCTYPE html>
           : "Publish app";
         element("publishApp").disabled = publishUrl
           ? !canOpenLinks
-          : !applicationId || !canCallTools || publishing;
+          : !applicationId ||
+            !canCallTools ||
+            publishing ||
+            nothingToPublish();
         // Only warn about what is actually broken. Hosts that do open links
         // handle local http fine; if one refuses, refused() says so then.
         if (!canOpenLinks && (editUrl || previewUrl) && !publishUrl) {
@@ -8420,6 +8922,11 @@ var APP_STATUS_HTML = `<!DOCTYPE html>
         if (typeof value.commitId === "string") {
           commitId = value.commitId;
         }
+        if (typeof value.pendingAction === "string") {
+          pendingAction = value.pendingAction;
+        } else if (typeof value.status === "string") {
+          pendingAction = "";
+        }
         if (typeof value.screenshotBase64 === "string") {
           showScreenshot(value.screenshotBase64, "image/jpeg");
         }
@@ -8432,6 +8939,9 @@ var APP_STATUS_HTML = `<!DOCTYPE html>
         if (typeof value.publishUrl === "string") {
           publishUrl = webUrl(value.publishUrl);
         }
+        if (typeof value.nextPollAfterMs === "number") {
+          pollAfterMs = value.nextPollAfterMs;
+        }
         // Hosts that deliver URLs without a status left the badge on the HTML
         // default ("loading") even after the app was built.
         const badge = element("status").textContent;
@@ -8446,29 +8956,91 @@ var APP_STATUS_HTML = `<!DOCTYPE html>
       }
 
       /**
-       * When the host opened the card with tool input (applicationId) but never
-       * pushed a tool result, refresh ourselves so the badge is not stuck on
-       * "loading" after the build finished.
+       * Re-ask get_app when the host gave us no result, or while status is
+       * still building. wait:false and ensurePreview:false so polls only
+       * ask for status. Honor nextPollAfterMs; 0 means stop.
        */
+      function clearRefreshTimer() {
+        if (refreshTimer) {
+          clearTimeout(refreshTimer);
+          refreshTimer = 0;
+        }
+      }
+
+      function retryDelay() {
+        return Math.max(MIN_POLL_MS, pollAfterMs || MIN_POLL_MS);
+      }
+
+      function scheduleRefresh(delayMs) {
+        clearRefreshTimer();
+        if (refreshAttempts >= MAX_REFRESH_ATTEMPTS) {
+          note("Stopped checking whether the app is still building.");
+          return;
+        }
+        refreshTimer = setTimeout(() => {
+          refreshTimer = 0;
+          refreshFromServer();
+        }, delayMs);
+      }
+
       function refreshFromServer() {
-        if (!canCallTools || !applicationId || editUrl) {
+        clearRefreshTimer();
+        if (!canCallTools || !applicationId || refreshInFlight) {
+          return;
+        }
+        if (typeof document.hidden === "boolean" && document.hidden) {
+          scheduleRefresh(retryDelay());
+          return;
+        }
+        const badge = element("status").textContent;
+        if (editUrl && badge !== "building") {
+          return;
+        }
+        if (refreshAttempts >= MAX_REFRESH_ATTEMPTS) {
+          note("Stopped checking whether the app is still building.");
           return;
         }
+        refreshAttempts += 1;
+        const generation = refreshGeneration;
+        refreshInFlight = true;
         request("tools/call", {
           name: "get_app",
-          arguments: { applicationId },
+          arguments: {
+            applicationId,
+            ensurePreview: false,
+            wait: false,
+          },
         })
           .then((result) => {
+            refreshInFlight = false;
+            if (generation !== refreshGeneration) {
+              if (element("status").textContent === "building") {
+                scheduleRefresh(retryDelay());
+              }
+              return;
+            }
             if (!result || result.isError) {
+              scheduleRefresh(retryDelay());
               return;
             }
             applyPayload(result);
             if (result.structuredContent) {
               applyPayload(result.structuredContent);
             }
+            if (element("status").textContent !== "building") {
+              return;
+            }
+            if (pollAfterMs === 0) {
+              return;
+            }
+            scheduleRefresh(retryDelay());
           })
           .catch(() => {
-            // Host declined; stay on whatever we have.
+            refreshInFlight = false;
+            if (generation !== refreshGeneration) {
+              return;
+            }
+            scheduleRefresh(retryDelay());
           });
       }
 
@@ -8521,6 +9093,10 @@ var APP_STATUS_HTML = `<!DOCTYPE html>
         if (!applicationId || !canCallTools || publishing) {
           return;
         }
+        if (nothingToPublish()) {
+          note("Nothing to publish yet: this turn did not build the app.");
+          return;
+        }
         publishing = true;
         renderActions();
         note("Publishing\u2026");
@@ -8604,6 +9180,10 @@ var APP_STATUS_HTML = `<!DOCTYPE html>
           if (params.structuredContent) {
             applyPayload(params.structuredContent);
           }
+          refreshGeneration += 1;
+          if (element("status").textContent === "building") {
+            refreshFromServer();
+          }
         }
         if (method === "ui/notifications/tool-input" && params.arguments) {
           applyPayload(params.arguments);
@@ -8933,6 +9513,24 @@ function createProgressNotifier(extra) {
 }
 
 // ../../../gateway/dist/transports/mcp/mount.js
+var DESTRUCTIVE_TOOL_ANNOTATIONS = {
+  destructiveHint: true,
+  idempotentHint: false,
+  openWorldHint: true,
+  readOnlyHint: false
+};
+var NON_DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS = {
+  destructiveHint: false,
+  idempotentHint: false,
+  openWorldHint: true,
+  readOnlyHint: false
+};
+var READ_ONLY_TOOL_ANNOTATIONS = {
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: true,
+  readOnlyHint: true
+};
 var eventCursorInputSchema = external_exports.object({
   streams: external_exports.record(external_exports.string(), external_exports.unknown()).optional(),
   version: external_exports.unknown().optional()
@@ -8953,10 +9551,11 @@ Name the builder "Superblocks" in every word you write. Users sometimes call it
 Use these tools whenever the user asks to build, change, import, or ship an app, whichever of those names they reach for.
 
 - start_app: create a new application and hand a prompt to Superblocks. Returns as soon as Superblocks accepts, with status "building". Superblocks names it unless a name is given.
-- import_app: import an existing app from a ZIP (or .tgz/.gz) into Superblocks and start a Superblocks migration. Pass the archive's file name as zipPath \u2014 the gateway opens the file on this machine itself. Archives larger than 1 MB are rejected \u2014 they almost certainly include node_modules; re-export without install artifacts. Optional prompt carries extra intent (e.g. "make it more secure"). Returns like start_app with status "building".
+- import_app: import an existing app from a ZIP (or .tgz/.gz) into Superblocks and start a Superblocks migration. Pass the archive's file name as zipPath \u2014 the gateway opens the file on this machine itself. Archives larger than 1 MB are rejected \u2014 they almost certainly include node_modules; re-export without install artifacts. Optional prompt carries extra intent (e.g. "make it more secure"). Returns like start_app with status "building". Pass applicationId only when retrying a failed import into the application that call already created.
 - edit_app: send a follow-up prompt (including the answer when Superblocks asked a question) for an existing application. Also returns at status "building". Defaults to the most recent app, so an applicationId is only needed to target a different app.
 - check_app_progress: wait for the next thing Superblocks does and return it. It returns the moment Superblocks says anything, and after ~10 seconds of silence at the latest. "activity" holds Superblocks' own words since the previous call, in order; a quiet poll still returns a short heartbeat with elapsedSeconds.
-- get_app: return editor and preview URLs for the recent or specified app (builds a private preview when needed). Prefer this after status "ready" so the user can open the live app. Hosts that support MCP Apps show the status card (Open editor / Open preview) on this call \u2014 not on check_app_progress or preview_app \u2014 so only one card opens. When Superblocks has written code the tool includes a screenshot: the live Vite canvas (library peer) if a held session exists, otherwise the signed-in preview. Never open canvas.doNotOpen (the edit URL) to take that screenshot. It refuses to build a preview of an app Superblocks has not written yet: while a plan or question is outstanding it returns status "needs_decision" with "pendingAction", while a turn is running it returns status "building", and when the last turn ended without writing anything it returns that turn's status ("timeout", "live_edit_terminated", "no_changes" or "cancelled") with pendingAction "retry_build". In each case there are no preview URLs and no screenshot \u2014 do the pendingAction first rather than calling get_app again.
+- get_app: return editor and preview URLs for the recent or specified app (builds a private preview when needed). Prefer this after status "ready" so the user can open the live app. Hosts that support MCP Apps show the status card (Open editor / Open preview) on this call \u2014 not on check_app_progress or preview_app \u2014 so only one card opens. When Superblocks has written code the tool includes a screenshot: the live Vite canvas (library peer) if a held session exists, otherwise the signed-in preview. Never open canvas.doNotOpen (the edit URL) to take that screenshot. It refuses to build a preview of an app Superblocks has not written yet: while a plan or question is outstanding it returns status "needs_decision" with "pendingAction", while a turn is running it returns status "building", and when the last turn ended without writing anything it returns that turn's status ("timeout", "live_edit_terminated", "no_changes" or "cancelled") with pendingAction "retry_build" for ordinary prompts or pendingAction "retry_import" for imports. In each case there are no preview URLs and no screenshot \u2014 do the pendingAction first rather than calling get_app again.
+- get_integration_metadata: inspect the tables, columns, and types in a connected integration. It needs no application and never executes an integration action, so do not call start_app or hunt through list_applications to satisfy it. Pass applicationId only for an integration that belongs to one application, such as a Native DB. Use search, limit, and offset to page large results. get_integration_config_schema is the JSON form for create_integration; it does not inspect connected data.
 - preview_app: build the application's current work and return a URL that runs it, without deploying it \u2014 the editor's Preview button. Nobody else can reach a preview. Text/markdown only (no MCP Apps widget); use get_app instead when you want the status card.
 - publish_app: deploy an application and wait until it is live. It commits the current work first, so a commitId is only needed to publish an earlier commit.
 
@@ -8964,21 +9563,25 @@ A build takes two to four minutes, and start_app/edit_app/import_app return with
 
 The user sees nothing at all while a tool call is outstanding, so between two calls always write out the new "activity" lines as a short message in your own reply \u2014 quote or paraphrase them, oldest first, before calling check_app_progress again. Do not batch them up for a summary at the end, and do not go two calls in a row without writing something: the point of the loop is that the user watches the build happen. When a call comes back with only a heartbeat (no new Superblocks words), say Superblocks is still working and how long it has been going, then poll again.
 
-status "ready" means the turn finished: report the "reply" field, then call get_app (not preview_app as well \u2014 calling both used to open two widgets) so the user gets Open preview / an https link or a screenshot. status "needs_decision" means Superblocks is waiting \u2014 often with a plan \u2014 so stop polling and put the decision to the user. When "decision.kind" is "plan", show the plan markdown, then invite them to build it as written or say what to change \u2014 the same fork the editor's Build-it button offers. Ask that as an ordinary closing question in your own words; do not turn it into a numbered or bulleted menu, and do not wrap the choices in quotation marks. When they say "Build it", "approve", "looks good", or "go ahead", you MUST call edit_app with planAction "approve" and omit prompt (do not re-send the plan, and do not put "approve" or "Build it" in the prompt field \u2014 that is refine feedback to Superblocks, not the editor Build-it path). When they want changes, call edit_app with planAction "refine" and their feedback as prompt. When "decision.kind" is "multi_choice", relay the question and options and send their answer with edit_app. Do not claim the app is built while status is "needs_decision". status "no_changes" means the Superblocks job ended without building anything: relay reply, say no app was built, and do not present the edit URL as a finished app. status "live_edit_terminated" means the live-edit session that was to run the turn died before it built anything, or never opened at all \u2014 the prompt was fine and nothing timed out, so relay reply, tell the user the session did not survive, and offer to send the same instruction again with edit_app. status "detached" means Superblocks is still working but the gateway can no longer see it \u2014 usually because the app is open in a browser editor, which takes over Superblocks updates. Stop polling, say so, and point the user at the edit URL. status "unknown" means nothing is in flight for that app. A checkpointCommitId means Superblocks work is saved and the edit URL opens the finished app; when viewStatus is unknown, say the app may still be finishing in the editor.
+status "ready" means the turn finished: report the "reply" field, then call get_app (not preview_app as well \u2014 calling both used to open two widgets) so the user gets Open preview / an https link or a screenshot. status "needs_decision" means Superblocks is waiting \u2014 often with a plan \u2014 so stop polling and put the decision to the user. When "decision.kind" is "plan", show the plan markdown, then invite them to build it as written or say what to change \u2014 the same fork the editor's Build-it button offers. Ask that as an ordinary closing question in your own words; do not turn it into a numbered or bulleted menu, and do not wrap the choices in quotation marks. When they say "Build it", "approve", "looks good", or "go ahead", you MUST call edit_app with planAction "approve" and omit prompt (do not re-send the plan, and do not put "approve" or "Build it" in the prompt field \u2014 that is refine feedback to Superblocks, not the editor Build-it path). When they want changes, call edit_app with planAction "refine" and their feedback as prompt. When "decision.kind" is "multi_choice", relay the question and options and send their answer with edit_app. Do not claim the app is built while status is "needs_decision". status "no_changes" means the Superblocks job ended without building anything: relay reply, say no app was built, and do not present the edit URL as a finished app. status "live_edit_terminated" means the live-edit session that was to run the turn died before it built anything, or never opened at all \u2014 relay reply, tell the user the session did not survive, and follow its pendingAction to retry with edit_app or import_app. status "detached" means Superblocks is still working but the gateway can no longer see it \u2014 usually because the app is open in a browser editor, which takes over Superblocks updates. Stop polling, say so, and point the user at the edit URL. status "unknown" means nothing is in flight for that app. A checkpointCommitId means Superblocks work is saved and the edit URL opens the finished app; when viewStatus is unknown, say the app may still be finishing in the editor.
+
+When get_app returns a screenshot, inspect it yourself before reporting that the app looks correct. If it shows skeletons, spinners, empty tables or charts, or "Loading...", call get_app again a few seconds later instead of treating that as a defect. If it shows a problem the user would plainly recognize as wrong, call edit_app once with a concrete correction, follow that turn to completion, and inspect the next get_app screenshot. Otherwise describe what you see and ask the user whether to fix it.
 
 start_app, edit_app, and import_app default to Plan mode (Superblocks proposes a plan before writing). Pass mode "BUILD" only when the user asks to skip planning and build immediately. Approving a plan after start_app or import_app is always a follow-up edit_app with planAction "approve" \u2014 never a second start_app/import_app with prompt "approve". Once the app has run in Build mode, later edit_app calls stay in Build mode on their own: you do not need to re-send mode "BUILD", and a new instruction is not a fresh planning round. Send mode "PLAN" only when the user explicitly asks to plan again before building. Every start_app / edit_app / import_app result reports the "mode" the turn ran in, so you can tell the user whether Superblocks is planning or building rather than guessing \u2014 and if a result comes back "PLAN" after a long gap, the build session was recycled rather than the user asking to plan, so pass mode "BUILD" again to carry on building. editUrl / previewUrl / publishUrl may appear in structured JSON for openLink buttons \u2014 do not dump raw URLs (especially preview JWTs) into the chat. Prefer the MCP Apps Open editor / Open preview buttons from get_app. Claude Desktop can only openLink https URLs; when previewUrl is http, say so briefly and rely on any screenshot image the tool returned rather than pasting the URL.
 
 Once a build reaches "ready", call get_app so the user can open the app, then offer publish_app to deploy for their organization when they ask. Prefer get_app over preview_app after a build \u2014 get_app already ensures a private preview and is the only tool that opens the MCP Apps status card. Only publish when the user asks. If preview_app or get_app comes back with status "building", the URL is already correct; tell the user it is still building and call again to check.
 
-There is nothing to preview until Superblocks has written code, so get_app is not the way out of a plan, a question, or a turn that failed. When it answers status "needs_decision" (pendingAction "approve_plan" or "answer_question"), the app is still the empty starter template: put the decision to the user, send their answer with edit_app, and only call get_app once a turn has finished. When it answers "timeout", "live_edit_terminated", "no_changes" or "cancelled" with pendingAction "retry_build", that turn built nothing: tell the user so plainly, and send the instruction again with edit_app if they want to retry. Repeating get_app instead opens another status card and tells the user nothing new.
+There is nothing to preview until Superblocks has written code, so get_app is not the way out of a plan, a question, or a turn that failed. When it answers status "needs_decision" (pendingAction "approve_plan" or "answer_question"), the app is still the empty starter template: put the decision to the user, send their answer with edit_app, and only call get_app once a turn has finished. When it answers "timeout", "live_edit_terminated", "no_changes" or "cancelled" with pendingAction "retry_build", that turn built nothing: tell the user so plainly, and send the instruction again with edit_app if they want to retry. For pendingAction "retry_import", call import_app again with the same archive and applicationId. One of those statuses can arrive with no pendingAction at all, which means the gateway knows the turn wrote nothing but not how it was started: say so, and pick the retry from what this conversation already knows \u2014 import_app with the archive and applicationId for an app you imported, edit_app with the same prompt otherwise. Repeating get_app instead opens another status card and tells the user nothing new.
 
 Superblocks tests what it builds: it opens the app in a browser and runs its APIs, and the test run arrives as ordinary "activity" lines ("Testing the orders page", "Test passed: \u2026", "Tests failed: \u2026"). Relay those lines like any other activity, and say which cases passed and which failed \u2014 a test run is the only evidence the user has that the app actually works. A failing test is a build signal, not an auth problem: it means the app has a bug Superblocks is about to work on, so keep polling and never tell the user to sign in again or re-enter credentials over one.
 
-A failed call still names the application it was working on. start_app and import_app create the application before the build can start, so an error from either one leaves an application that exists and belongs to this conversation, and the error says which: read the "applicationId" field, never a UUID out of the message text. Never take an error to mean nothing happened. Do not answer a failed start_app with a second start_app \u2014 that abandons the app you already have and creates a duplicate. When the error carries pendingAction "retry_build" \u2014 a "live_edit_unavailable" session that would not open, or a turn that ran out of budget \u2014 send the same prompt again with edit_app and that applicationId. A failed import_app carries no such recovery, because edit_app cannot resupply the archive the migration prompt reads: that application is empty and nothing can continue it in place, so name it to the user and let them decide whether to import again. Every edit_app error names its applicationId too, which is the one place to see which app a call that omitted the id actually ran on.
+A failed call still names the application it was working on. start_app and import_app create the application before the build can start, so an error from either one leaves an application that exists and belongs to this conversation, and the error says which: read the "applicationId" field, never a UUID out of the message text. Never take an error to mean nothing happened. Do not answer a failed start_app with a second start_app \u2014 that abandons the app you already have and creates a duplicate. When the error carries pendingAction "retry_build" \u2014 a "live_edit_unavailable" session that would not open, or a turn that ran out of budget \u2014 send the same prompt again with edit_app and that applicationId. When import_app returns pendingAction "retry_import", call import_app again with the same archive and applicationId so it resumes the existing app instead of creating another one. Every edit_app error names its applicationId too, which is the one place to see which app a call that omitted the id actually ran on.
+
+A cancelled call does not stop the build, and it is not permission to start over. Cancelling only ends the waiting \u2014 Superblocks carries on, and the "cancelled" error names the application it was driving in "applicationId". Read that id, call check_app_progress or get_app on it, and act on what comes back. When the user then asks to redo, retry, or resume an import, that is a request to finish the application you already have: never answer it with an import_app that omits applicationId, which builds a second app and strands the first. The same holds when no pendingAction is in front of you \u2014 after a cancel, or in a later session. If the app came from an import, the way back in is import_app with the same archive and that applicationId; if you cannot tell which application the user means, ask rather than create one.
 
 Prompts are forwarded to Superblocks verbatim \u2014 pass the user's wording rather than a summary.
 
-This connector is the single Superblocks MCP: Builder tools (start_app, import_app, edit_app, check_app_progress, get_app, preview_app, publish_app) and Admin tools (integrations, apps, users, folders, deploy_application, and the rest of the customer Admin surface) share this endpoint. Prefer create_integration / update_integration / list_integrations here when Superblocks needs a missing Postgres, REST, or other datasource \u2014 do not send the user to a second MCP. create_integration is Admin CRUD for org datasources; start_app creates a new application and hands a prompt to Superblocks. deploy_application is Admin deploy of an existing commit; publish_app is the Builder path that commits current work and waits until the app is live. Omit base_url on Admin tools unless targeting a different control plane \u2014 the gateway injects its configured Server URL. checkout_application is not exposed on this network surface (host filesystem writes); use the CLI/workspace checkout path instead.
+This connector is the single Superblocks MCP: Builder tools (start_app, import_app, edit_app, check_app_progress, get_app, get_integration_metadata, preview_app, publish_app) and Admin tools (integrations, apps, users, folders, deploy_application, and the rest of the customer Admin surface) share this endpoint. Prefer create_integration / update_integration / list_integrations here when Superblocks needs a missing Postgres, REST, or other datasource \u2014 do not send the user to a second MCP. Call get_integration_config_schema with the plugin_id before create_integration, then pass name, plugin_id, and configuration \u2014 never the raw integrations API envelope. create_integration is Admin CRUD for org datasources; start_app creates a new application and hands a prompt to Superblocks. deploy_application is Admin deploy of an existing commit; publish_app is the Builder path that commits current work and waits until the app is live. Omit base_url on Admin tools unless targeting a different control plane \u2014 the gateway injects its configured Server URL. checkout_application is not exposed on this network surface (host filesystem writes); use the CLI/workspace checkout path instead.
 
 This connection is already authenticated and already pointed at one Superblocks Server, so there is no setup, login, or auth-status call to make first. Call the tool that does the job \u2014 list_integrations to see the org's datasources, start_app to create an application \u2014 and read its error if something is genuinely wrong. Do not look for a tool that reports credentials or environments; there is none, and asking for one costs the user a turn.
 
@@ -8988,7 +9591,7 @@ For import_app, the archive never travels through you. A file the user attached
 
 ${BROWSER_DRIVER_INSTRUCTIONS}`;
 function createMcpServer(deps) {
-  const context = async (progress, notify, signal) => ({
+  const context2 = async (progress, notify, signal) => ({
     caller: callerFrom(),
     captureLibraryScreenshot: captureLibraryScreenshotWithPlaywright,
     capturePreviewScreenshot: capturePreviewScreenshotWithPlaywright,
@@ -8998,6 +9601,9 @@ function createMcpServer(deps) {
       progress.push(event);
       notify?.(event.message);
     },
+    onPrincipalResolved: (principal) => {
+      deps.mcpTelemetry?.setOrganizationId(principal.organizationId);
+    },
     principal: principalFrom(deps),
     progressCursors: deps.progressCursors,
     recentApps: deps.recentApps,
@@ -9010,22 +9616,22 @@ function createMcpServer(deps) {
     gatewayDebugStack("tool started", { "tool.name": toolName });
     const progress = [];
     const notify = createProgressNotifier(extra);
-    let result;
-    if (!deps.cliApiKey) {
-      gatewayDebug("tool short-circuited", {
-        "tool.name": toolName,
-        "tool.reason": "missing_cli_session"
-      });
-      result = {
-        kind: "error",
-        code: "unauthenticated",
-        message: "This Gateway has no CLI session. Run: superblocks login"
-      };
-    } else {
+    const execute = async () => {
+      if (!deps.cliApiKey) {
+        gatewayDebug("tool short-circuited", {
+          "tool.name": toolName,
+          "tool.reason": "missing_cli_session"
+        });
+        return {
+          kind: "error",
+          code: "unauthenticated",
+          message: "This Gateway has no CLI session. Run: superblocks login"
+        };
+      }
       try {
         const signal = extra?.signal;
-        const capabilityContext = await context(progress, notify, signal);
-        result = await capability(capabilityContext, () => {
+        const capabilityContext = await context2(progress, notify, signal);
+        return await capability(capabilityContext, () => {
           for (let index = progress.length - 1; index >= 0; index -= 1) {
             if (progress[index]?.type === "completed") {
               progress.splice(index, 1);
@@ -9034,13 +9640,23 @@ function createMcpServer(deps) {
         });
       } catch (error) {
         console.error("gateway capability failed", error);
-        result = {
+        return {
           kind: "error",
           code: "capability_failed",
           message: error instanceof Error ? error.message : "The gateway failed for an unknown reason."
         };
       }
-    }
+    };
+    const client = server.server.getClientVersion();
+    const result = deps.mcpTelemetry ? await deps.mcpTelemetry.runTool({
+      ...client ? {
+        client: {
+          name: client.name,
+          version: client.version
+        }
+      } : {},
+      toolName
+    }, execute) : await execute();
     const resultStatus = result.kind === "ok" && result.value && typeof result.value === "object" && "status" in result.value && typeof result.value.status === "string" ? result.value.status : void 0;
     gatewayDebug("tool finished", {
       "progress.event_count": progress.length,
@@ -9066,12 +9682,12 @@ function createMcpServer(deps) {
     title: "Superblocks",
     version: "0.0.1"
   }, { instructions: SERVER_INSTRUCTIONS });
-  const progressWithDecisionForm = async (context2, input, extra, forgetFinishedTurn) => {
+  const progressWithDecisionForm = async (context3, input, extra, forgetFinishedTurn) => {
     gatewayDebug("progress decision flow started", {
       "application.id": input.applicationId,
       "progress.cursor_provided": Boolean(input.cursor)
     });
-    const result = await checkAppProgress(context2, input);
+    const result = await checkAppProgress(context3, input);
     const decision = pendingDecision(result);
     if (!decision) {
       gatewayDebug("progress decision flow finished", {
@@ -9091,7 +9707,7 @@ function createMcpServer(deps) {
     const resolved = await resolveDecisionByElicitation({
       apply: (answer) => {
         forgetFinishedTurn();
-        return editApp(context2, {
+        return editApp(context3, {
           applicationId: input.applicationId,
           idempotencyKey: `mcp-decision:${randomUUID4()}`,
           wait: "ack",
@@ -9123,7 +9739,20 @@ function createMcpServer(deps) {
     });
   }
   function registerBuilderTools() {
+    server.registerTool("get_integration_metadata", {
+      annotations: READ_ONLY_TOOL_ANNOTATIONS,
+      description: "Inspect the tables, columns, and types in a connected Superblocks integration. Needs no application and never executes an integration action. Pass integrationId, which list_integrations returns. A large result comes back paged: narrow it with search, take more or fewer entries with limit, and continue from nextOffset with offset. Requires build permission on the integration. Do not use this to learn how to create an integration; that is get_integration_config_schema.",
+      inputSchema: {
+        applicationId: external_exports.string().uuid().optional().describe("Only for an integration owned by a single application, such as a Native DB. Leave unset otherwise; do not go looking for an application to supply."),
+        integrationId: external_exports.string().uuid(),
+        limit: external_exports.number().int().min(1).max(200).optional(),
+        offset: external_exports.number().int().min(0).optional(),
+        search: external_exports.string().min(1).optional()
+      },
+      title: "Get Integration Metadata"
+    }, async (input, extra) => run("get_integration_metadata", (context3) => getIntegrationMetadata(context3, input), extra));
     server.registerTool("start_app", {
+      annotations: NON_DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS,
       description: 'Create a Superblocks application and hand a prompt to Superblocks in Plan mode by default. Returns as soon as Superblocks accepts, with status "building" and an edit URL; follow with check_app_progress until status is no longer "building". When Superblocks returns needs_decision with a plan and the user says "Build it", call edit_app with planAction "approve" (omit prompt) \u2014 do not call start_app again with prompt "approve". Pass mode "BUILD" to skip planning. Superblocks names the application unless name is given. An error from this tool does not mean nothing happened: the application is created before the build starts, so the error names it in "applicationId". Retry that app with edit_app rather than calling start_app another time, which would leave the first one abandoned.',
       inputSchema: {
         branch: external_exports.string().optional(),
@@ -9136,7 +9765,7 @@ function createMcpServer(deps) {
       // the tool name: a host that ranks tools by title has to be able to find
       // this one from the request.
       title: "Create Superblocks App"
-    }, async ({ branch, idempotencyKey, mode, name, prompt }, extra) => run("start_app", (context2) => startApp(context2, {
+    }, async ({ branch, idempotencyKey, mode, name, prompt }, extra) => run("start_app", (context3) => startApp(context3, {
       branch,
       idempotencyKey: idempotencyKey ?? `mcp-start:${randomUUID4()}`,
       mode,
@@ -9148,8 +9777,10 @@ function createMcpServer(deps) {
       wait: "ack"
     }), extra));
     server.registerTool("import_app", {
-      description: `Import an existing app from a ZIP/.tgz/.gz archive into Superblocks and start a Superblocks migration. Pass the archive's file name (or its full path on this machine) as zipPath: the gateway reads the file itself, so a path from your own sandbox is fine as long as the name matches the file the user has. Never encode the archive as base64 \u2014 zipBase64 only carries test fixtures. Archives larger than 1 MB are rejected \u2014 exclude node_modules. Optional prompt adds intent such as hardening security. Returns status "building"; follow with check_app_progress. Defaults to Plan mode \u2014 when Superblocks returns a plan and the user says "Build it", call edit_app with planAction "approve" (omit prompt); do not call import_app again with prompt "approve". An error from this tool does not mean nothing happened: the application is created before the migration starts, so the error names it in "applicationId". That application is empty \u2014 the migration never ran \u2014 and nothing can continue it in place, so say it exists and let the user decide whether to import again rather than silently retrying.`,
+      annotations: DESTRUCTIVE_TOOL_ANNOTATIONS,
+      description: `Import an existing app from a ZIP/.tgz/.gz archive into Superblocks and start a Superblocks migration. Pass the archive's file name (or its full path on this machine) as zipPath: the gateway reads the file itself, so a path from your own sandbox is fine as long as the name matches the file the user has. Never encode the archive as base64 \u2014 zipBase64 only carries test fixtures. Archives larger than 1 MB are rejected \u2014 exclude node_modules. Optional prompt adds intent such as hardening security. Returns status "building"; follow with check_app_progress. Defaults to Plan mode \u2014 when Superblocks returns a plan and the user says "Build it", call edit_app with planAction "approve" (omit prompt); do not call import_app again with prompt "approve". An error from this tool does not mean nothing happened: the application is created before the migration starts, so the error names it in "applicationId". When it returns pendingAction "retry_import", call import_app again with the same archive and applicationId to resume that application instead of creating another one.`,
       inputSchema: {
+        applicationId: external_exports.string().uuid().optional(),
         branch: external_exports.string().optional(),
         idempotencyKey: external_exports.string().optional(),
         mode: external_exports.enum(["BUILD", "PLAN"]).optional(),
@@ -9169,7 +9800,8 @@ function createMcpServer(deps) {
         zipPath: external_exports.string().min(1).optional()
       },
       title: "Import App"
-    }, async ({ branch, idempotencyKey, mode, name, prompt, source, zipBase64, zipPath }, extra) => run("import_app", (context2) => importApp(context2, {
+    }, async ({ applicationId, branch, idempotencyKey, mode, name, prompt, source, zipBase64, zipPath }, extra) => run("import_app", (context3) => importApp(context3, {
+      applicationId,
       branch,
       idempotencyKey: idempotencyKey ?? `mcp-import:${randomUUID4()}`,
       mode,
@@ -9181,6 +9813,7 @@ function createMcpServer(deps) {
       zipPath
     }), extra));
     server.registerTool("edit_app", {
+      annotations: DESTRUCTIVE_TOOL_ANNOTATIONS,
       description: 'Forward a prompt to Superblocks for the recent or specified application. Defaults to Plan mode until the app has run in Build mode; after that later edits keep building directly \u2014 you do not need to pass mode again. Pass mode "PLAN" only when the user explicitly asks to plan before building. The result reports the "mode" the turn ran in; a "PLAN" result after a long gap means the build session was recycled, so pass mode "BUILD" again rather than treating it as a new planning round. When status was needs_decision with a plan and the user says "Build it" / approve / go ahead, call edit_app with planAction "approve" and omit prompt \u2014 do not put "approve" or "Build it" in prompt (that is refine feedback, not the Build-it path). Use planAction "refine" with their feedback as prompt to change the plan. Also use edit_app to answer multi_choice questions. Returns status "building"; follow with check_app_progress.',
       inputSchema: {
         applicationId: external_exports.string().uuid().optional(),
@@ -9191,7 +9824,7 @@ function createMcpServer(deps) {
         prompt: external_exports.string().min(1).optional()
       },
       title: "Edit App"
-    }, async ({ applicationId, branch, idempotencyKey, mode, planAction, prompt }, extra) => run("edit_app", (context2) => editApp(context2, {
+    }, async ({ applicationId, branch, idempotencyKey, mode, planAction, prompt }, extra) => run("edit_app", (context3) => editApp(context3, {
       applicationId,
       branch,
       idempotencyKey: idempotencyKey ?? `mcp-edit:${randomUUID4()}`,
@@ -9201,24 +9834,26 @@ function createMcpServer(deps) {
       wait: "ack"
     }), extra));
     server.registerTool("check_app_progress", {
+      annotations: NON_DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS,
       description: `Wait for the next thing Superblocks does on the recent or specified application and return it: "activity" carries Superblocks' words since the previous call (or a short heartbeat when Superblocks is quiet), and status is "building" while the app is still being generated. Returns as soon as Superblocks says anything, and after ~10 seconds of silence at the latest. Call within about 10 seconds of start_app, import_app, or edit_app so a plan or question surfaces quickly. Once the plan is approved and Superblocks is building, space later polls about 30 seconds apart (honor "nextPollAfterMs" when present) until status is no longer "building" \u2014 a 10-second cadence on a multi-minute build burns through the host's tool-call budget. Relay each new activity line to the user between calls. When status becomes "needs_decision", stop polling and put the decision to the user \u2014 for a plan, show it and ask whether to build it or say what to change; for multi_choice, relay the question and options. Hosts that support form elicitation get a native picker instead, and this tool then returns the answered turn. When status becomes "ready", follow with get_app so the user can open the preview. Progress is text-only (no MCP Apps widget) so each poll does not reopen a blank card. Optional "cursor" from a prior result resumes from that composite position (per producer, no global sequence); omit it to use the gateway's stored place for this caller.`,
       inputSchema: {
         applicationId: external_exports.string().uuid().optional(),
         cursor: eventCursorInputSchema.optional()
       },
       title: "Check App Progress"
-    }, async ({ applicationId, cursor }, extra) => run("check_app_progress", (context2, forgetFinishedTurn) => {
+    }, async ({ applicationId, cursor }, extra) => run("check_app_progress", (context3, forgetFinishedTurn) => {
       const parsed = cursor === void 0 ? void 0 : parseEventCursor(cursor);
       gatewayDebug("progress cursor parsed", {
         "progress.cursor_provided": cursor !== void 0,
         "progress.cursor_valid": Boolean(parsed)
       });
-      return progressWithDecisionForm(context2, {
+      return progressWithDecisionForm(context3, {
         applicationId,
         ...parsed ? { cursor: parsed } : {}
       }, extra, forgetFinishedTurn);
     }, extra));
     K3(server, "get_app", {
+      annotations: READ_ONLY_TOOL_ANNOTATIONS,
       description: 'Return editor and preview URLs for the recent or specified Superblocks application. Ensures a private preview build by default (same as preview_app), but only once Superblocks has something to show: while a plan or question is outstanding it returns status "needs_decision" with the "decision" and a "pendingAction" of "approve_plan" or "answer_question", while a turn is running it returns status "building", and when the last turn ended without writing anything it returns "timeout", "live_edit_terminated", "no_changes" or "cancelled" with pendingAction "retry_build" \u2014 no preview URLs and no screenshot in any of those cases, because the app is still the empty starter template. Act on "pendingAction" through edit_app instead of calling this again. Prefer this after check_app_progress reaches status "ready". Also the right call when you do not know where a build stands \u2014 after a reconnect, when no turn of yours is running, or when the conversation moved to another channel: pass wait false and read "status" and "cursor" from the result rather than guessing. Hosts that support MCP Apps show Open editor / Open preview buttons. When Superblocks has written code the result includes a screenshot of the live Vite canvas if a held session exists, otherwise the signed-in preview \u2014 never the edit URL.',
       inputSchema: {
         applicationId: external_exports.string().uuid().optional(),
@@ -9230,15 +9865,16 @@ function createMcpServer(deps) {
       _meta: {
         ui: { resourceUri: APP_STATUS_RESOURCE_URI }
       }
-    }, async ({ applicationId, branch, ensurePreview, wait }, extra) => run("get_app", (context2) => getApp(context2, { applicationId, branch, ensurePreview, wait }), extra));
+    }, async ({ applicationId, branch, ensurePreview, wait }, extra) => run("get_app", (context3) => getApp(context3, { applicationId, branch, ensurePreview, wait }), extra));
     server.registerTool("preview_app", {
+      annotations: READ_ONLY_TOOL_ANNOTATIONS,
       description: `Build the recent or specified Superblocks application's current work and return a URL that runs it, without deploying it \u2014 the same thing the editor's Preview button does. Only the user can open it. Status "ready" means the URL works now; "building" means the build is still running and calling again resumes watching it. Prefer get_app when you want the MCP Apps status card (Open editor / Open preview); this tool returns the same URLs as text/markdown without opening a second widget.`,
       inputSchema: {
         applicationId: external_exports.string().uuid().optional(),
         branch: external_exports.string().optional()
       },
       title: "Preview App"
-    }, async ({ applicationId, branch }, extra) => run("preview_app", (context2) => previewApp(context2, { applicationId, branch }), extra));
+    }, async ({ applicationId, branch }, extra) => run("preview_app", (context3) => previewApp(context3, { applicationId, branch }), extra));
     const uiCsp = { csp: { frameDomains: [] } };
     N3(server, "Gateway app status", APP_STATUS_RESOURCE_URI, {
       description: "Status card with Open editor / Open preview / Publish app",
@@ -9255,6 +9891,7 @@ function createMcpServer(deps) {
       ]
     }));
     server.registerTool("publish_app", {
+      annotations: DESTRUCTIVE_TOOL_ANNOTATIONS,
       description: "Publish/deploy the recent or specified Superblocks application and wait until it is live. Commits the application's current work first, so commitId is only needed to publish an earlier commit.",
       inputSchema: {
         applicationId: external_exports.string().uuid().optional(),
@@ -9264,7 +9901,7 @@ function createMcpServer(deps) {
         prompt: external_exports.string().min(1)
       },
       title: "Publish App"
-    }, async ({ applicationId, branch, commitId, idempotencyKey, prompt }, extra) => run("publish_app", (context2) => publishApp(context2, {
+    }, async ({ applicationId, branch, commitId, idempotencyKey, prompt }, extra) => run("publish_app", (context3) => publishApp(context3, {
       applicationId,
       branch,
       commitId,
@@ -9284,6 +9921,7 @@ function createMcpServer(deps) {
 async function createRuntime(apiKey) {
   const config = loadConfig();
   const stores = await createStores();
+  const telemetry = startGatewayTelemetry({ apiKey, config });
   const serverClient = new HttpSuperblocksServerClient(config.serverUrl);
   const sessionPeer = new WebSocketSessionPeer({
     beatLostGraceMs: config.beatLostGraceMs,
@@ -9301,6 +9939,7 @@ async function createRuntime(apiKey) {
     cliApiKey: apiKey,
     config,
     events: stores.events,
+    mcpTelemetry: telemetry.mcpTelemetry,
     progressCursors: stores.progressCursors,
     recentApps: stores.recentApps,
     server: serverClient,
@@ -9312,7 +9951,7 @@ async function createRuntime(apiKey) {
     deps,
     close: async () => {
       sessionPeer.closeAll();
-      await stores.close();
+      await Promise.allSettled([stores.close(), telemetry.shutdown()]);
     }
   };
 }
@@ -9358,4 +9997,4 @@ export {
   startApp,
   startStdioGateway
 };
-//# sourceMappingURL=dist-2M5L5FNH.js.map
+//# sourceMappingURL=dist-NJHWXUHQ.js.map