@superblocksteam/gateway 2.0.161 → 2.0.162-next.1

package/dist/transports/mcp/mount.js

@@ -1,21 +1,30 @@
 import { randomUUID } from "node:crypto";
-import { registerAppResource, registerAppTool, RESOURCE_MIME_TYPE, } from "@modelcontextprotocol/ext-apps/server";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { ElicitResultSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { getUiCapability, registerAppResource, registerAppTool, RESOURCE_MIME_TYPE, RESOURCE_URI_META_KEY, } from "@modelcontextprotocol/ext-apps/server";
+import { McpServer, } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
+import { URL_PARAMS } from "@superblocksteam/library-shared";
+import { assertEnterprisePlan, EntitlementError, } from "@superblocksteam/mcp-server";
 import { getIntegrationMetadata } from "../../capabilities/integration-metadata.js";
-import { checkAppProgress, editApp, getApp, importApp, previewApp, publishApp, startApp, } from "../../capabilities/lifecycle.js";
+import { askUser, checkAppProgress, checkPublishProgress, editApp, getApp, getPreviewStatus, previewApp, publishApp, startApp, uploadArtifact, } from "../../capabilities/lifecycle.js";
 import { IMPORT_ZIP_BASE64_MAX_CHARS } from "../../capabilities/types.js";
+import { HOST_BROWSER_TOOLS_COWORK, HOST_BROWSER_TOOLS_UNKNOWN, } from "../../capture/browser-contract.js";
 import { BROWSER_DRIVER_INSTRUCTIONS } from "../../capture/browser-instructions.js";
 import { captureLibraryScreenshotWithPlaywright } from "../../capture/capture-library.js";
 import { gatewayDebug, gatewayDebugStack } from "../../debug.js";
-import { EVENT_CURSOR_VERSION, parseEventCursor } from "../../events/cursor.js";
-import { EVENT_PRODUCERS } from "../../events/types.js";
 import { capturePreviewScreenshotWithPlaywright } from "../../preview/capture-screenshot.js";
 import { registerAdminTools } from "./admin-tools.js";
 import { APP_STATUS_HTML, APP_STATUS_RESOURCE_URI } from "./app-status-html.js";
-import { clientSupportsFormElicitation, pendingDecision, resolveDecisionByElicitation, } from "./decision-elicitation.js";
+import { clientPresentationCapabilities, } from "./client-presentation.js";
+import { APP_DECISION_HTML, APP_DECISION_RESOURCE_URI, CONFIRM_PLAN_APPROVAL_TOOL, PLAN_APPROVAL_TOKEN_META_KEY, } from "./decision-card-html.js";
+import { clientSupportsFormElicitation, elicitDecision, pendingDecision, resolveDecisionByElicitation, resultApplicationId, resultBranch, } from "./decision-elicitation.js";
+import { createEditorDocumentProbe, } from "./editor-document-probe.js";
+import { EDITOR_SETUP_RECENT_APP_WINDOW_MS, editorIntegrationSetupUrl, } from "./editor-integration-setup-url.js";
 import { formatMcpToolContent } from "./format-tool-content.js";
+import { attachAgentInstructions, instructionFor, } from "./instructions/index.js";
+import { isRecord } from "./instructions/result.js";
+import { APP_LOAD_CHECK, COWORK_BROWSER_TOOLSEARCH, } from "./instructions/tools/copy.js";
+import { NativeBrowserPresence, nativeBrowserPresenceDirectory, } from "./native-browser-presence.js";
+import { planApprovalDirectory, PlanApprovalChallenges, } from "./plan-approval.js";
 import { createProgressNotifier } from "./progress-notifier.js";
 const DESTRUCTIVE_TOOL_ANNOTATIONS = {
     destructiveHint: true,
@@ -35,23 +44,91 @@ const READ_ONLY_TOOL_ANNOTATIONS = {
     openWorldHint: true,
     readOnlyHint: true,
 };
-/**
- * Optional composite progress cursor a host may hand back on
- * `check_app_progress`.
- *
- * Kept deliberately loose at the schema boundary: `parseEventCursor` is the
- * authority for version and per-producer positions. A foreign or corrupt
- * cursor must fall through to the caller's stored place rather than fail the
- * tool call — otherwise a host that cached an older shape would permanently
- * stall.
- */
-const eventCursorInputSchema = z
-    .object({
-    streams: z.record(z.string(), z.unknown()).optional(),
-    version: z.unknown().optional(),
-})
-    .passthrough()
-    .describe(`Optional composite resume cursor from a previous check_app_progress or get_app result. Shape: { version: ${EVENT_CURSOR_VERSION}, streams: { ${EVENT_PRODUCERS.join("?: number, ")}?: number } }. There is no global sequence — each producer (dev_server, sabs) has its own position. Omit to resume from the gateway's per-caller stored place. A cursor from an older contract or with bad positions is ignored and the stored place is used instead.`);
+const APP_STATUS_CARD_META = {
+    ui: { resourceUri: APP_STATUS_RESOURCE_URI },
+    [RESOURCE_URI_META_KEY]: APP_STATUS_RESOURCE_URI,
+};
+const ARTIFACT_SCHEMA = z.object({
+    fileName: z.string().min(1).max(255),
+    id: z.string().uuid(),
+    // Any type attachments accept, not just the archive pair: upload_artifact
+    // returns image/png for an image, and this is where that comes back in.
+    mediaType: z
+        .string()
+        .regex(/^[\w.+-]+\/[\w.+-]+$/)
+        .max(255),
+    storageKey: z.string().min(1),
+});
+class ResultAcknowledgingMcpServer extends McpServer {
+    onResultDeliveryFailed;
+    onResultDelivered;
+    connect(transport) {
+        const send = transport.send.bind(transport);
+        transport.send = async (message, options) => {
+            const outgoing = withClientInstructions(message, this.server.getClientVersion());
+            try {
+                await send(outgoing, options);
+                if (isRecord(outgoing) && "result" in outgoing && "id" in outgoing) {
+                    this.onResultDelivered?.(outgoing.result, outgoing.id);
+                }
+            }
+            catch (error) {
+                if (isRecord(outgoing) && "result" in outgoing && "id" in outgoing) {
+                    this.onResultDeliveryFailed?.(outgoing.result, outgoing.id);
+                }
+                throw error;
+            }
+        };
+        return super.connect(transport);
+    }
+}
+function planFromDecision(branch, decision) {
+    return {
+        ...(branch ? { branch } : {}),
+        ...(decision.messageId ? { messageId: decision.messageId } : {}),
+        plan: decision.plan,
+        ...(decision.title ? { title: decision.title } : {}),
+    };
+}
+function plansMatch(left, right) {
+    return (left.branch === right.branch &&
+        left.messageId === right.messageId &&
+        left.plan === right.plan &&
+        left.title === right.title);
+}
+function deliveredNativePlan(result) {
+    const value = result
+        ?.structuredContent;
+    if (!value || typeof value !== "object") {
+        return undefined;
+    }
+    const delivered = value;
+    return delivered.status === "needs_decision" &&
+        typeof delivered.applicationId === "string" &&
+        delivered.decision?.kind === "plan"
+        ? {
+            applicationId: delivered.applicationId,
+            plan: planFromDecision(typeof delivered.branch === "string" ? delivered.branch : undefined, delivered.decision),
+        }
+        : undefined;
+}
+function rememberDisplayedPlan(appState, applicationId, branch, decision) {
+    if (!applicationId) {
+        return undefined;
+    }
+    const displayedPlan = planFromDecision(branch, decision);
+    const pendingDecision = appState.pendingDecision(applicationId);
+    if (pendingDecision &&
+        (pendingDecision.branch !== branch || pendingDecision.decision !== decision)) {
+        return undefined;
+    }
+    const pendingPlan = appState.pendingPlan(applicationId);
+    if (pendingPlan) {
+        return plansMatch(pendingPlan, displayedPlan) ? pendingPlan : undefined;
+    }
+    appState.setPendingPlan(applicationId, displayedPlan);
+    return displayedPlan;
+}
 /**
  * Builds the principal from the CLI session this Gateway was started with.
  * Identity is the already-logged-in Superblocks user; there is no second PAT
@@ -67,15 +144,18 @@ function principalFrom(deps) {
         ...(deps.cliIdentity ?? {}),
     };
 }
-/**
- * Who is polling, for the purpose of keeping their place in a build's stream.
- *
- * Stdio is a single-user process owned by the MCP host, so every tool call
- * shares this stable id. The value is never stored as-is; the progress store
- * hashes it.
- */
-function callerFrom() {
-    return { channel: "mcp", id: "cli" };
+const SOURCE_ARTIFACT_INSTRUCTIONS = "When the source is a readable tree on this machine, archive the source and assets with their original relative paths, excluding .git, node_modules, build output, secrets, and production data. Inspect the archive, upload it with upload_artifact filePath, then pass the returned artifact unchanged in start_app or edit_app artifacts. Local paths and prose descriptions are not a substitute for the source artifact: Superblocks cannot read the host's workspace. Ask Superblocks to read the attached source and preserve its UI and behavior. Reuse the artifact on retries. Follow the superblocks-import skill when available; Superblocks writes the application, not the host.";
+function compactRecord(value) {
+    if (!value) {
+        return undefined;
+    }
+    const compacted = {};
+    for (const [key, entry] of Object.entries(value)) {
+        if (entry !== undefined) {
+            compacted[key] = entry;
+        }
+    }
+    return Object.keys(compacted).length > 0 ? compacted : undefined;
 }
 /**
  * Told to the model on connect, so it can match what a user actually says
@@ -88,79 +168,113 @@ function callerFrom() {
  * is input-only, because a client that reads "Clark" here repeats it back and
  * reintroduces the retired name to the user.
  */
-const SERVER_INSTRUCTIONS = `Superblocks builds, edits, and publishes internal web applications. Prompts sent through these tools are handed to Superblocks, which writes the application code in a live-edit session.
+export const SERVER_INSTRUCTIONS = `Superblocks builds, edits, and publishes internal web applications. Prompts sent through these tools are handed to Superblocks, which writes the application code in a live-edit session.
 
 Name the builder "Superblocks" in every word you write. Users sometimes call it "Clark", an older name for this same system: understand them, and answer about Superblocks. Never write "Clark" yourself — not as a name, not as an aside, not even when the user just used it, and never as a separate agent or persona. If Superblocks' own words come back naming Clark, relay the substance and say Superblocks.
 
-Use these tools whenever the user asks to build, change, import, or ship an app, whichever of those names they reach for.
+The user you are interacting with is a non-technical business user. Keep discussions focused on requirements, and avoid technical jargon, discussing code, or implementation details. If errors or problems occur, give the user easy-to-follow, actionable instructions for how they can resolve the issue.
 
-- 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 — the gateway opens the file on this machine itself. Archives larger than 1 MB are rejected — 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 — not on check_app_progress or preview_app — 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 — 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 — 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.
+Use these tools whenever the user asks to build, change, import, or ship an app, whichever of those names they reach for. They can also inspect what data the org has rather than building an app to explore it: list_integrations names the datasources, and get_integration_metadata reads the tables and columns inside one. Create a persistent app or API only when the user explicitly asks for one.
 
-A build takes two to four minutes, and start_app/edit_app/import_app return within seconds — long before it is done. After any of them, call check_app_progress within about 10 seconds so a plan or question surfaces quickly. Once the plan is approved and Superblocks is building the app, space later polls about 30 seconds apart (honor "nextPollAfterMs" when present) — a 10-second cadence on a multi-minute build burns through the host's tool-call budget. A "nextPollAfterMs" of 0 means nothing is in flight: stop polling rather than calling again immediately. "remainingTurnBudgetMs" appears only while this gateway is following the turn itself and can see its clock, so never read a missing budget as a fresh one — but do not read it as a reason to stop either. A build this gateway is not itself timing reports "building" with no budget, and "status" and "nextPollAfterMs" are what say whether to keep polling. Never claim the app is built while status is "building".
+After create_integration creates an integration or list_integrations selects one for an app, include the returned mention unchanged in the next edit_app prompt. The mention gives Superblocks the exact integration ID; do not construct one from the display name.
 
-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 — 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.
+Superblocks is itself an agent, not a code library: prompts sent through start_app and edit_app are handed to it verbatim, and it decides how to build the application. Your role is to facilitate the user's interaction with Superblocks, not to build anything yourself — pass the user's own request through unchanged, without inventing, embellishing, or adding requirements, scope, or design detail they did not ask for.
 
-status "ready" means the turn finished: report the "reply" field, then call get_app (not preview_app as well — 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 — often with a plan — 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 — 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 — 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 — 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 — 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.
+After each tool call, check for agentInstructions in the result and follow them. These instructions are tailored to the scenario.
 
-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.
+Superblocks has an interactive flow: when it needs a person to decide something, it stops rather than guessing. Follow the result's agentInstructions to use the decision surface this client supports. Never supply that answer yourself.
 
-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" — 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 — 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 — 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.
+Building or editing an app follows one loop: start_app hands a new application to Superblocks, edit_app continues an existing one, and both return immediately with status "building". Call check_app_progress to follow the turn, relaying what Superblocks says as it happens. When it stops for a decision, follow agentInstructions and send the answer back through edit_app. Once status is "ready", call get_app so the user can open the result, and offer publish_app when they want to deploy it. Each tool's own description covers its exact inputs, return fields, and retry/error behavior.
 
-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 — 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.
+${APP_LOAD_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. 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 — 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.
+When the user attached a file in this chat (a log, CSV, screenshot, image, zip, or anything else), or when migrating source visible in this conversation, call upload_artifact. Pass upload_artifact filePath with the full host path when you have it; a bare file name falls back to the gateway's search folders. If the file exists only in this chat's scratchpad path (for example /tmp/claude-.../scratchpad), send text source through files: [{ path, content }] instead of filePath. The gateway reads filePath bytes itself, so an image or PDF costs nothing to send. Only source you are writing out yourself goes in files, which is archived as text - never base64 a file into it. Then pass the returned artifact in start_app or edit_app artifacts. Do not create a Claude artifact or use the host's own file-upload UI.
 
-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: …", "Tests failed: …"). Relay those lines like any other activity, and say which cases passed and which failed — 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.
+${SOURCE_ARTIFACT_INSTRUCTIONS}
 
-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 — that abandons the app you already have and creates a duplicate. When the error carries pendingAction "retry_build" — a "live_edit_unavailable" session that would not open, or a turn that ran out of budget — 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.
+For a migrated app with missing integrations, call list_integrations first. Reuse only the same plugin and the same connection: the same REST base URL, or the same host, port, and database. A similar name is not a match. list_integrations and get_integration_metadata do not expose connection URLs or hosts, so do not use them to guess a match. When there is no exact match, follow the result's agentInstructions to create and wire every declared integration.
 
-A cancelled call does not stop the build, and it is not permission to start over. Cancelling only ends the waiting — 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 — 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.
+This connector is the single Superblocks MCP: Builder tools (upload_artifact, start_app, edit_app, check_app_progress, ask_user, get_app, build_app, publish_app, check_publish_progress) 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 over sending the user to a second MCP. create_integration takes name, plugin_id, and configuration, never the raw integrations API envelope. create_integration is Admin CRUD for org datasources; start_app creates an application and hands it a prompt. deploy_application is Admin deploy of an existing commit; publish_app is the Builder path that commits current work and waits for it to go live. Omit base_url on Admin tools unless targeting a different control plane. checkout_application is not exposed on this network surface (host filesystem writes); use the CLI/workspace checkout path instead.
 
-Prompts are forwarded to Superblocks verbatim — pass the user's wording rather than a summary.
+This connection is already authenticated against one Superblocks Server — there is no setup, login, or auth-status call to make first. Call the tool that does the job and read its error if something is genuinely wrong; there is no tool that reports credentials or environments.
 
-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 — 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 — 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 — 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.
+Never tell the user to restart the MCP server; keep the MCP server running.
 
-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 — list_integrations to see the org's datasources, start_app to create an application — 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.
+A cancelled tool call does not undo work Superblocks already did. The application still exists; read applicationId on the error and follow agentInstructions (or pendingAction) instead of starting over.
 
-This MCP also discovers integrations mid-build and runs live integration queries (username/password and other stored credentials) through the orchestrator. When an integration needs interactive IdP/OAuth login, the tool error will say to authenticate in the Superblocks editor (edit URL) and retry — only follow that when the error says so. A 401 AuthorizationError from an orchestrator execute path is Superblocks/orchestrator auth (the scoped JWT or selected profile), not Snowflake username/password — never advise verifying or re-entering the Snowflake password, account, or other stored credentials in the integrations UI for that error. Only advise credential edits when an error from Snowflake itself clearly says stored credentials failed or a connection test failed. Do not tell the user to re-authenticate for Snowflake SQL permission wording ("does not exist or not authorized") or OpenAI API key failures. If status later reaches "ready" and the user can open the app, do not lead with or alarm on mid-build testApi orchestrator 401s unless the user asks about data or API failures — prefer "build succeeded" and mention a transient API check only if asked.
-
-For import_app, the archive never travels through you. A file the user attached to the chat sits in your own sandbox, which this gateway cannot read, but the user downloaded that same file to this machine and the gateway looks for it by name where downloads land. So pass zipPath — the full path if you have a real one for this machine, otherwise the attachment's file name, which is all the gateway needs. The gateway only opens archives that sit in the folders its operator allowed, so if it answers that it will not read the path you gave, ask the user to move the archive into one of the folders it names. Never write the archive out as base64: it costs thousands of tokens, takes minutes, and the call is rejected before it runs.
+get_app's previewUrl opens the current development app with existing app permissions; it is not a published end-user URL. For a requested live-preview link, return that exact URL; do not open Share, change permissions, invite anyone, or publish. Call build_app only when the user explicitly requests an unpublished build or a shareable versioned preview, never automatically after an ordinary app creation, edit, or get_app. It creates a commit preview without publishing; retain its previewUrl and use get_preview_status for subsequent checks. If a sharing request is ambiguous (including "Can I share this app?"), ask before calling any tools whether they mean live preview, an unpublished commit preview, or publishing. Access permissions and deployment history cannot resolve this intent; an empty deployment history does not mean publishing is required to share a preview. Call publish_app or deploy_application only when the user explicitly asks to publish or deploy. Otherwise prefer MCP Apps Open editor / Open preview buttons over dumping editUrl / previewUrl / publishUrl into chat, especially preview JWTs. Claude Desktop can only openLink https URLs; when a URL is http, say so and rely on any screenshot instead.
 
 ${BROWSER_DRIVER_INSTRUCTIONS}`;
+const COWORK_EMBEDDED_BROWSER_TOOLS = `Load your browser pane tools, you will need them. Call ToolSearch with query ${COWORK_BROWSER_TOOLSEARCH}. When a check_app_progress or get_app result includes browserNavigation, ensure its exact URL is open in Cowork's embedded Page browser before any other action. If that app is already open, do not reload it; otherwise, focus the Page URL field, enter that exact URL, and press Enter. Verify the app loaded; normal authentication or canonical URL redirects are allowed. A blank tab is insufficient. Keep the Page open so the user can watch the live canvas update.`;
+function serverInstructionsFor(client) {
+    if (!clientPresentationCapabilities(client).hasNativeBrowser) {
+        return SERVER_INSTRUCTIONS;
+    }
+    return `${SERVER_INSTRUCTIONS}
+
+${COWORK_EMBEDDED_BROWSER_TOOLS}`;
+}
+const PUBLISH_APP_DESCRIPTION_PREFIX = 'Publish/deploy the recent or specified Superblocks application. Commits the application\'s current work first, so commitId is only needed to publish an earlier commit. Returns status "deployed" once the app is live, or status "publishing" when the deploy was accepted and is still rolling out - that is a success, not a failure: the commit is made and the policy gates passed. On "publishing", tell the user the publish went through and is rolling out, then follow it with check_publish_progress until it reports "deployed"; carry the returned commitId back on every check_publish_progress poll. ';
+function publishAppDescription(hasNativeBrowser) {
+    return (PUBLISH_APP_DESCRIPTION_PREFIX +
+        (hasNativeBrowser
+            ? "On either successful status, open publishDetailsUrl automatically in the browser pane before the first check_publish_progress poll."
+            : "On either successful status, include publishDetailsUrl immediately in your next user-facing response before the first check_publish_progress poll."));
+}
+function withClientInstructions(message, client) {
+    if (!isRecord(message) || !("result" in message)) {
+        return message;
+    }
+    const result = message.result;
+    if (!isRecord(result) ||
+        typeof result.protocolVersion !== "string" ||
+        !isRecord(result.serverInfo)) {
+        return message;
+    }
+    return {
+        ...message,
+        result: {
+            ...result,
+            instructions: serverInstructionsFor(client),
+        },
+    };
+}
 /**
  * The MCP server behind one stdio session.
  *
  * Tools run as the already-logged-in CLI user. There is no per-request OAuth
  * token to expire independently of the process.
  */
-export function createMcpServer(deps) {
+export function createMcpServer(deps, probeEditorDocument = createEditorDocumentProbe()) {
+    // `cliIdentity` is optional and the stdio runtime does not set it, so the
+    // only identity this session has is whatever a capability already resolved.
+    let resolvedIdentity;
     const context = async (progress, notify, signal) => ({
-        caller: callerFrom(),
+        appState: deps.appState,
         captureLibraryScreenshot: captureLibraryScreenshotWithPlaywright,
         capturePreviewScreenshot: capturePreviewScreenshotWithPlaywright,
         config: deps.config,
-        events: deps.events,
+        hostBrowserTools: clientPresentationCapabilities(server.server.getClientVersion()).hasNativeBrowser
+            ? HOST_BROWSER_TOOLS_COWORK
+            : HOST_BROWSER_TOOLS_UNKNOWN,
         onProgress: (event) => {
             progress.push(event);
             notify?.(event.message);
         },
         onPrincipalResolved: (principal) => {
+            resolvedIdentity = {
+                organizationId: principal.organizationId,
+                userId: principal.userId,
+            };
             deps.mcpTelemetry?.setOrganizationId(principal.organizationId);
         },
         principal: principalFrom(deps),
-        progressCursors: deps.progressCursors,
+        progress: deps.progress,
         recentApps: deps.recentApps,
         server: deps.server,
         sessionPeer: deps.sessionPeer,
         ...(signal ? { signal } : {}),
-        turns: deps.turns,
+        stepUpTurns: deps.stepUpTurns,
     });
     /**
      * Runs a capability and renders it as tool content. An unexpected throw
@@ -168,8 +282,19 @@ export function createMcpServer(deps) {
      * its own message: this catch cannot tell which downstream failed, and
      * naming one it did not diagnose points the reader at a healthy system.
      */
-    const run = async (toolName, capability, extra) => {
-        gatewayDebugStack("tool started", { "tool.name": toolName });
+    const run = async (toolName, capability, extra, browserNavigationOrArguments, toolArguments) => {
+        const browserNavigationReady = browserNavigationOrArguments === "status" ||
+            browserNavigationOrArguments === "viewStatus"
+            ? browserNavigationOrArguments
+            : undefined;
+        const callArguments = compactRecord(browserNavigationReady === undefined &&
+            typeof browserNavigationOrArguments === "object"
+            ? browserNavigationOrArguments
+            : toolArguments);
+        gatewayDebugStack("tool started", {
+            "tool.name": toolName,
+            metadata: extra?._meta,
+        });
         const progress = [];
         const notify = createProgressNotifier(extra);
         const execute = async () => {
@@ -185,6 +310,10 @@ export function createMcpServer(deps) {
                 };
             }
             try {
+                if (!deps.config.localAgentMode) {
+                    // Same ENTERPRISE/POC gate as Admin tools; skipped for local-agent.
+                    await assertEnterprisePlan(deps.config.serverUrl.replace(/\/$/, ""), deps.cliApiKey);
+                }
                 // The SDK aborts this on `notifications/cancelled` and on a dropped
                 // connection. Handing it to the capability is what turns "the host
                 // stopped listening" into "stop waiting", instead of leaving a timer
@@ -200,6 +329,13 @@ export function createMcpServer(deps) {
                 });
             }
             catch (error) {
+                if (error instanceof EntitlementError) {
+                    return {
+                        kind: "error",
+                        code: "entitlement",
+                        message: error.message,
+                    };
+                }
                 console.error("gateway capability failed", error);
                 return {
                     kind: "error",
@@ -211,8 +347,16 @@ export function createMcpServer(deps) {
             }
         };
         const client = server.server.getClientVersion();
-        const result = deps.mcpTelemetry
+        const executeWithBrowserNavigation = async () => {
+            let result = await execute();
+            if (browserNavigationReady) {
+                result = await withBrowserNavigation(result, browserNavigationReady, extra?.signal);
+            }
+            return result;
+        };
+        let result = deps.mcpTelemetry
             ? await deps.mcpTelemetry.runTool({
+                ...(callArguments ? { arguments: callArguments } : {}),
                 ...(client
                     ? {
                         client: {
@@ -222,8 +366,10 @@ export function createMcpServer(deps) {
                     }
                     : {}),
                 toolName,
-            }, execute)
-            : await execute();
+            }, executeWithBrowserNavigation)
+            : await executeWithBrowserNavigation();
+        const profile = clientProfileFor();
+        result = attachAgentInstructions(toolName, result, profile);
         const resultStatus = result.kind === "ok" &&
             result.value &&
             typeof result.value === "object" &&
@@ -251,72 +397,265 @@ export function createMcpServer(deps) {
             })()
             : undefined;
         return {
-            content: formatMcpToolContent(result, progress),
+            content: formatMcpToolContent(result, progress, profile),
             ...(structuredContent ? { structuredContent } : {}),
         };
     };
-    const server = new McpServer({
+    const clientProfileFor = () => {
+        const presentation = clientPresentationCapabilities(server.server.getClientVersion());
+        return {
+            ...presentation,
+            supportsFormElicitation: clientSupportsFormElicitation(server.server.getClientCapabilities()),
+        };
+    };
+    const server = new ResultAcknowledgingMcpServer({
         name: "superblocks",
         // The product the user is thinking of, not the implementation process
         // serving it. The client shows this string.
         title: "Superblocks",
         version: "0.0.1",
     }, { instructions: SERVER_INSTRUCTIONS });
+    const planApprovals = new PlanApprovalChallenges({
+        directory: planApprovalDirectory(deps.cliApiKey, deps.config.serverUrl),
+    });
+    const nativeBrowsers = new NativeBrowserPresence({
+        directory: nativeBrowserPresenceDirectory(deps.cliApiKey, deps.config.serverUrl),
+    });
+    const nativePlanApprovals = new Map();
+    const pendingNativePlanApprovals = new Map();
+    let announcedNativeBrowser = false;
+    let stopWatchingNativeBrowsers;
+    let askUserTool;
+    let confirmPlanApprovalTool;
+    let publishAppTool;
+    const statusCardTools = [];
+    const enableStatusCards = () => {
+        for (const tool of statusCardTools) {
+            tool.update({ _meta: APP_STATUS_CARD_META });
+        }
+    };
+    const clientSupportsAppCard = () => getUiCapability(server.server.getClientCapabilities())?.mimeTypes?.includes(RESOURCE_MIME_TYPE) === true;
+    const clientSupportsDecisionCard = () => !clientPresentationCapabilities(server.server.getClientVersion())
+        .hasNativeAskForm && clientSupportsAppCard();
+    server.onResultDelivered = (result, requestId) => {
+        const deliveredPlan = deliveredNativePlan(result);
+        if (deliveredPlan) {
+            const pending = pendingNativePlanApprovals.get(deliveredPlan.applicationId);
+            if (pending?.requestId === requestId &&
+                plansMatch(pending.plan, deliveredPlan.plan)) {
+                pendingNativePlanApprovals.delete(deliveredPlan.applicationId);
+                nativePlanApprovals.set(deliveredPlan.applicationId, pending.plan);
+            }
+        }
+    };
+    server.onResultDeliveryFailed = (result, requestId) => {
+        const deliveredPlan = deliveredNativePlan(result);
+        if (deliveredPlan) {
+            const pending = pendingNativePlanApprovals.get(deliveredPlan.applicationId);
+            if (pending?.requestId === requestId &&
+                plansMatch(pending.plan, deliveredPlan.plan)) {
+                pendingNativePlanApprovals.delete(deliveredPlan.applicationId);
+            }
+        }
+    };
+    const withBrowserNavigation = async (result, ready, signal) => {
+        if (signal?.aborted ||
+            !clientPresentationCapabilities(server.server.getClientVersion())
+                .hasNativeBrowser ||
+            result.kind !== "ok" ||
+            !result.value ||
+            typeof result.value !== "object") {
+            return result;
+        }
+        const value = result.value;
+        const applicationId = value.applicationId;
+        const editUrl = value.editUrl;
+        const readyToNavigate = value[ready] === "ready" ||
+            (ready === "status" && value.pendingAction === "open_editor");
+        if (!readyToNavigate ||
+            typeof applicationId !== "string" ||
+            typeof editUrl !== "string") {
+            return result;
+        }
+        if (!(await probeEditorDocument(editUrl, signal))) {
+            if (value.pendingAction === "open_editor") {
+                return {
+                    kind: "ok",
+                    value: {
+                        ...value,
+                        agentInstructions: "The build finished but did not save. Do not tell the user the app was saved. The editor is temporarily unavailable. Call `get_app` again in a few seconds. Do not tell the user the editor is open until the result includes `browserNavigation`.",
+                    },
+                };
+            }
+            if (ready === "status" && value.status === "ready") {
+                return {
+                    kind: "ok",
+                    value: {
+                        ...value,
+                        agentInstructions: "The editor is temporarily unavailable. Call `get_app` again in a few seconds. Do not tell the user the app is open until the result includes `browserNavigation`.",
+                    },
+                };
+            }
+            return result;
+        }
+        const navigationUrl = `${editUrl}${editUrl.includes("?") ? "&" : "?"}${URL_PARAMS.editorHost}=cowork`;
+        return {
+            kind: "ok",
+            value: {
+                ...value,
+                browserNavigation: { action: "open_editor", url: navigationUrl },
+            },
+        };
+    };
+    server.server.oninitialized = () => {
+        const presentation = clientPresentationCapabilities(server.server.getClientVersion());
+        const supportsDecisionCard = clientSupportsDecisionCard();
+        if (presentation.hasNativeBrowser || !supportsDecisionCard) {
+            askUserTool?.update({ _meta: {} });
+        }
+        if (!supportsDecisionCard) {
+            confirmPlanApprovalTool?.disable();
+        }
+        if (presentation.hasNativeBrowser) {
+            publishAppTool?.update({
+                description: publishAppDescription(true),
+            });
+            nativeBrowsers.announce();
+            announcedNativeBrowser = true;
+        }
+        else if (clientSupportsAppCard()) {
+            if (nativeBrowsers.active()) {
+                stopWatchingNativeBrowsers =
+                    nativeBrowsers.whenInactive(enableStatusCards);
+            }
+            else {
+                enableStatusCards();
+            }
+        }
+        gatewayDebug("mcp server initialized for client", {
+            "client.version": server.server.getClientVersion(),
+            "client.capabilities": server.server.getClientCapabilities(),
+        });
+    };
+    server.server.onclose = () => {
+        stopWatchingNativeBrowsers?.();
+        if (announcedNativeBrowser) {
+            nativeBrowsers.withdraw();
+        }
+    };
+    /** Sends a decision answer to Superblocks, however the user gave it. */
+    const applyDecisionAnswer = (context, applicationId, branch, answer, approvedPlan) => editApp(context, {
+        applicationId,
+        branch,
+        idempotencyKey: `mcp-decision:${randomUUID()}`,
+        wait: "ack",
+        ...(answer.kind === "approve"
+            ? { planAction: "approve" }
+            : answer.kind === "refine"
+                ? { planAction: "refine", prompt: answer.feedback }
+                : { prompt: answer.prompt }),
+    }, answer.kind === "approve" ? approvedPlan : undefined);
+    const stageNativePlanApproval = (result, requestId) => {
+        const decision = pendingDecision(result);
+        const applicationId = resultApplicationId(result);
+        if (!clientProfileFor().hasNativeAskForm || !decision || !applicationId) {
+            return;
+        }
+        nativePlanApprovals.delete(applicationId);
+        if (decision.kind !== "plan") {
+            pendingNativePlanApprovals.delete(applicationId);
+            return;
+        }
+        const plan = rememberDisplayedPlan(deps.appState, applicationId, resultBranch(result), decision);
+        if (plan) {
+            pendingNativePlanApprovals.set(applicationId, { plan, requestId });
+        }
+        else {
+            pendingNativePlanApprovals.delete(applicationId);
+        }
+    };
     /**
      * A progress poll that also puts a decision to the user as a native form when
      * the host supports one, answering Superblocks itself and returning the turn
-     * that follows. Hosts without form elicitation (Claude Desktop today) get the
-     * decision back as data and ask the user in chat.
+     * that follows. A decision that comes back as data instead carries
+     * instructions naming the ask surface this host actually has.
      */
     const progressWithDecisionForm = async (context, input, extra, forgetFinishedTurn) => {
         gatewayDebug("progress decision flow started", {
             "application.id": input.applicationId,
-            "progress.cursor_provided": Boolean(input.cursor),
         });
         const result = await checkAppProgress(context, input);
         const decision = pendingDecision(result);
         if (!decision) {
             gatewayDebug("progress decision flow finished", {
+                "decision.instructions": "none",
                 "decision.resolved": false,
                 "decision.reason": "no_pending_decision",
             });
             return result;
         }
+        gatewayDebug("client info", {
+            version: server.server.getClientVersion(),
+            capabilities: server.server.getClientCapabilities(),
+        });
+        const profile = clientProfileFor();
+        const { hasNativeAskForm } = profile;
+        // Which surface the agent should ask on is a property of the host, not of
+        // whether this particular poll managed to show a form.
+        const agentInstructions = decision.kind === "plan" || decision.kind === "multi_choice"
+            ? instructionFor("check_app_progress", result, profile)
+            : undefined;
+        const instructionsChosen = agentInstructions
+            ? hasNativeAskForm
+                ? "native_ask_form"
+                : "call_ask_user"
+            : "none";
+        const unresolvedDecision = () => {
+            if (agentInstructions) {
+                forgetFinishedTurn();
+                context.onProgress?.({
+                    message: agentInstructions,
+                    type: "completed",
+                });
+            }
+            return result;
+        };
+        const decidedApp = resultApplicationId(result) ?? input.applicationId;
+        const decidedBranch = resultBranch(result) ?? input.branch;
+        const displayedPlan = decision.kind === "plan"
+            ? rememberDisplayedPlan(context.appState, decidedApp, decidedBranch, decision)
+            : undefined;
         if (!clientSupportsFormElicitation(server.server.getClientCapabilities())) {
+            stageNativePlanApproval(result, extra.requestId);
             gatewayDebug("progress decision flow finished", {
                 "decision.kind": decision.kind,
+                "decision.instructions": instructionsChosen,
                 "decision.resolved": false,
                 "decision.reason": "form_unsupported",
             });
-            return result;
+            return unresolvedDecision();
+        }
+        if (decision.kind === "plan" && !displayedPlan) {
+            return unresolvedDecision();
         }
         const resolved = await resolveDecisionByElicitation({
             apply: (answer) => {
                 forgetFinishedTurn();
-                return editApp(context, {
-                    applicationId: input.applicationId,
-                    idempotencyKey: `mcp-decision:${randomUUID()}`,
-                    wait: "ack",
-                    ...(answer.kind === "approve"
-                        ? { planAction: "approve" }
-                        : answer.kind === "refine"
-                            ? { planAction: "refine", prompt: answer.feedback }
-                            : { prompt: answer.prompt }),
-                });
+                // The id the poll resolved, not the one the call named: those differ
+                // when the call named none, and the answer has to reach the same
+                // application the decision came from.
+                return applyDecisionAnswer(context, decidedApp, decidedBranch, answer, displayedPlan);
             },
             decision,
-            // Sent through the tool call's own extra so it rides that call's response
-            // stream: a request the gateway raises on its own goes to the standalone
-            // stream instead, which a host that never opened one silently drops,
-            // leaving the tool call waiting for an answer that cannot arrive.
-            elicit: (request) => extra.sendRequest({ method: "elicitation/create", params: request }, ElicitResultSchema),
+            elicit: elicitDecision(extra),
         });
         gatewayDebug("progress decision flow finished", {
             "decision.kind": decision.kind,
+            "decision.instructions": resolved ? "none" : instructionsChosen,
             "decision.resolved": Boolean(resolved),
             "decision.reason": resolved ? "answered" : "left_in_chat",
         });
-        return resolved ?? result;
+        return resolved ?? unresolvedDecision();
     };
     // Cloud-Prem Admin laptop agent: this machine has no Playwright Chromium
     // and never opens a live-edit session, so the Builder surface (start_app,
@@ -336,7 +675,7 @@ export 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.",
+            description: "Inspect the tables, columns, and types in a connected Superblocks integration. Superblocks integrations are how superblocks apps connect with external data sources. They can be to internal or external APIs, databases, or other services. Use this tool to see what data is available when a user asks to connect to an external service. 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; a missing integration arrives with the configuration and configurationSchema create_integration needs.",
             inputSchema: {
                 applicationId: z
                     .string()
@@ -349,79 +688,79 @@ export function createMcpServer(deps) {
                 search: z.string().min(1).optional(),
             },
             title: "Get Integration Metadata",
-        }, async (input, extra) => run("get_integration_metadata", (context) => getIntegrationMetadata(context, input), extra));
+        }, async (input, extra) => run("get_integration_metadata", (context) => getIntegrationMetadata(context, input), extra, input));
         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) — 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.',
+            description: 'Create a Superblocks application and hand it a prompt. Pass the user\'s own request as prompt, verbatim - do not invent, embellish, or add requirements, scope, or design detail the user did not ask for. Use Plan mode by omitting mode unless the user explicitly and unambiguously asks to bypass planning. A request to "build", "create", or "make" an app is not such a request. Pass mode "BUILD" only for directions like "use build mode", "skip the plan", or "no planning". Returns as soon as Superblocks accepts, with status "building" and an edit URL. When a later result includes "browserNavigation", open its exact URL in the browser pane and verify the app loaded. If the user imported via an artifact, close the artifact before opening that 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) - do not call start_app again with prompt "approve". 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". Unless pendingAction is "start_new_app", retry that app with edit_app rather than calling start_app another time, which would leave the first one abandoned. When pendingAction is "start_new_app", call start_app once with the same prompt, mode, and artifacts and set replacesApplicationId to the failed result\'s applicationId. If that replacement ends live_edit_terminated with no pendingAction, stop and report its reply; do not retry or create another application. When migrating source uploaded with upload_artifact, or when Superblocks should read any other uploaded file, pass its returned artifact unchanged in artifacts.',
             inputSchema: {
+                artifacts: z.array(ARTIFACT_SCHEMA).min(1).max(20).optional(),
                 branch: z.string().optional(),
                 idempotencyKey: z.string().optional(),
                 mode: z.enum(["BUILD", "PLAN"]).optional(),
                 name: z.string().min(1).optional(),
                 prompt: z.string().min(1),
+                replacesApplicationId: z
+                    .string()
+                    .uuid()
+                    .optional()
+                    .describe("Set only for the one fresh application requested by pendingAction start_new_app; use the failed result's applicationId."),
             },
             // Named for what a user asks for ("create an app"), not for the verb in
             // 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", (context) => startApp(context, {
+        }, async ({ artifacts, branch, idempotencyKey, mode, name, prompt, replacesApplicationId, }, extra) => run("start_app", (context) => startApp(context, {
+            artifacts,
             branch,
             idempotencyKey: idempotencyKey ?? `mcp-start:${randomUUID()}`,
-            mode,
+            mode: mode ?? "PLAN",
             name,
             prompt,
+            replacesApplicationId,
             // MCP clients get the polling loop, not a blocking call: Claude
             // Desktop sends no progressToken, so a call that waits out the whole
             // build shows the user nothing until it returns.
             wait: "ack",
-        }), extra));
-        server.registerTool("import_app", {
-            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 — zipBase64 only carries test fixtures. Archives larger than 1 MB are rejected — exclude node_modules. Optional prompt adds intent such as hardening security. Returns status "building"; follow with check_app_progress. Defaults to Plan mode — 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.',
+        }), extra, {
+            artifacts,
+            branch,
+            idempotencyKey,
+            mode,
+            name,
+            prompt,
+            replacesApplicationId,
+        }));
+        server.registerTool("upload_artifact", {
+            annotations: NON_DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS,
+            description: `Use upload_artifact to upload source once for a later start_app or edit_app migration, or any other file the user attached in this chat (a log, CSV, screenshot, image, document, or a ZIP/.tgz/.gz). Batch related text source files into one files call, up to 100 files and 1 MB (1,048,576 bytes) of UTF-8 content before compression. Split only when those limits require it, and tell the user which batch you are preparing before composing its contents. Pass filePath with the full host path when you have it. A bare file name falls back to the gateway's search folders. If the file exists only in this chat's scratchpad path (for example /tmp/claude-.../scratchpad), send text source through files: [{ path, content }] instead of filePath. The gateway reads filePath bytes itself. Only source you are writing out yourself goes in files, which is archived as text: never put an image, PDF, or other binary in there, and never base64 a file into it. Doing that spends minutes emitting the encoding and uploads those characters under the file's name instead of the file. zipBase64 is only for test fixtures. Files larger than 50 MB are rejected - the same cap as Superblocks attachments. ${SOURCE_ARTIFACT_INSTRUCTIONS} This uploads an organization-scoped artifact but does not create, edit, build, or commit an application. Pass its returned artifact unchanged in start_app or edit_app artifacts, and reuse it on retries instead of uploading again. Do not create a Claude artifact or use the host's own file-upload UI.`,
             inputSchema: {
-                applicationId: z.string().uuid().optional(),
-                branch: z.string().optional(),
-                idempotencyKey: z.string().optional(),
-                mode: z.enum(["BUILD", "PLAN"]).optional(),
-                name: z.string().min(1).optional(),
-                prompt: z.string().min(1).optional(),
-                source: z
-                    .enum([
-                    "chatgpt",
-                    "claude",
-                    "claude-design",
-                    "lovable",
-                    "replit",
-                    "streamlit",
-                    "v0",
-                    "zip",
-                ])
+                files: z
+                    .array(z.object({
+                    content: z.string(),
+                    path: z.string().min(1),
+                }))
+                    .min(1)
+                    .max(100)
                     .optional(),
+                filePath: z.string().min(1).optional(),
                 zipBase64: z
                     .string()
                     .min(1)
                     .max(IMPORT_ZIP_BASE64_MAX_CHARS)
                     .optional(),
-                zipPath: z.string().min(1).optional(),
             },
-            title: "Import App",
-        }, async ({ applicationId, branch, idempotencyKey, mode, name, prompt, source, zipBase64, zipPath, }, extra) => run("import_app", (context) => importApp(context, {
-            applicationId,
-            branch,
-            idempotencyKey: idempotencyKey ?? `mcp-import:${randomUUID()}`,
-            mode,
-            name,
-            prompt,
-            source,
-            wait: "ack",
+            title: "Upload File or Source Artifact",
+        }, async ({ filePath, files, zipBase64 }, extra) => run("upload_artifact", (context) => uploadArtifact(context, {
+            filePath,
+            files,
             zipBase64,
-            zipPath,
-        }), extra));
+        }), extra, { filePath, files, zipBase64 }));
         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 — 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 — 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.',
+            description: 'Forward a prompt to Superblocks for the recent or specified application. Pass the user\'s request directly as prompt, verbatim. DO NOT invent, embellish, or add requirements, scope, or design detail they did not ask for. This will cause Superblocks to do things the user did not ask for. Defaults to Plan mode on every call - an edit never inherits Build mode from an earlier turn. Pass mode "BUILD" only when the user asks for it explicitly (e.g. "use build mode" or "skip the plan") on this edit. Answering a multi_choice question is not skipping the plan: omit mode and stay in Plan until Superblocks has proposed a plan and the user approves it. The result reports the "mode" the turn ran in. 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 - 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. When a later result includes "browserNavigation", open its exact URL in the browser pane and verify the app loaded. An error from this call still names the application it was working on in "applicationId". When migrating or resuming source uploaded with upload_artifact, or when Superblocks should read any other uploaded file, pass its returned artifact unchanged in artifacts.',
             inputSchema: {
                 applicationId: z.string().uuid().optional(),
+                artifacts: z.array(ARTIFACT_SCHEMA).min(1).max(20).optional(),
                 branch: z.string().optional(),
                 idempotencyKey: z.string().optional(),
                 mode: z.enum(["BUILD", "PLAN"]).optional(),
@@ -429,82 +768,262 @@ export function createMcpServer(deps) {
                 prompt: z.string().min(1).optional(),
             },
             title: "Edit App",
-        }, async ({ applicationId, branch, idempotencyKey, mode, planAction, prompt }, extra) => run("edit_app", (context) => editApp(context, {
+        }, async ({ applicationId, artifacts, branch, idempotencyKey, mode, planAction, prompt, }, extra) => run("edit_app", async (context) => {
+            const { hasNativeAskForm } = clientPresentationCapabilities(server.server.getClientVersion());
+            const nativeApprovalApplicationId = planAction === "approve" && hasNativeAskForm
+                ? (applicationId ??
+                    (nativePlanApprovals.size === 1
+                        ? nativePlanApprovals.keys().next().value
+                        : undefined))
+                : undefined;
+            const nativePlan = nativeApprovalApplicationId
+                ? nativePlanApprovals.get(nativeApprovalApplicationId)
+                : undefined;
+            const consumedNativeApplicationId = applicationId ?? nativeApprovalApplicationId;
+            if (hasNativeAskForm && consumedNativeApplicationId) {
+                nativePlanApprovals.delete(consumedNativeApplicationId);
+                pendingNativePlanApprovals.delete(consumedNativeApplicationId);
+            }
+            const nativeApproval = nativePlan &&
+                (branch === undefined || nativePlan.branch === branch) &&
+                nativeApprovalApplicationId
+                ? {
+                    applicationId: nativeApprovalApplicationId,
+                    branch: nativePlan.branch,
+                    plan: nativePlan,
+                }
+                : undefined;
+            const confirmedApproval = planAction === "approve" && !hasNativeAskForm
+                ? await planApprovals.consumeConfirmed(context.appState, applicationId, branch)
+                : undefined;
+            const approval = nativeApproval ??
+                (confirmedApproval?.kind === "approved"
+                    ? confirmedApproval.target
+                    : undefined);
+            if (planAction === "approve" && !approval) {
+                if (confirmedApproval?.kind === "stale") {
+                    return {
+                        kind: "error",
+                        code: "plan_approval_stale",
+                        message: "The plan changed after the user approved it. Show the current plan and ask again.",
+                    };
+                }
+                return {
+                    kind: "error",
+                    code: "approval_not_from_user",
+                    message: "Provide the applicationId for the current plan the user approved through a supported decision form, or show the current plan and ask again.",
+                };
+            }
+            return editApp(context, {
+                applicationId: applicationId ?? approval?.applicationId,
+                artifacts,
+                branch: branch ?? approval?.branch,
+                idempotencyKey: idempotencyKey ?? `mcp-edit:${randomUUID()}`,
+                mode,
+                planAction,
+                prompt,
+                wait: "ack",
+            }, approval?.plan);
+        }, extra, {
             applicationId,
+            artifacts,
             branch,
-            idempotencyKey: idempotencyKey ?? `mcp-edit:${randomUUID()}`,
+            idempotencyKey,
             mode,
             planAction,
             prompt,
-            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" — 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 — 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.',
+            // A poll every few seconds through a multi-minute build is a permission
+            // prompt every few seconds unless the host is told this only reads.
+            //
+            // It is not quite only a read: answering a decision here sends that
+            // answer to Superblocks. But the host prompt exists to get the user's
+            // consent, and this call only ever writes an answer the user just gave
+            // by hand in the elicitation form. It writes nothing the model decided
+            // on its own.
+            annotations: READ_ONLY_TOOL_ANNOTATIONS,
+            description: `Polls for the given application's current Superblocks turn. Use this after start_app or edit_app. The result includes the "activity" field, which carries Superblocks' words since the previous call (or a short heartbeat when Superblocks is quiet). Possible statuses are: "building", "ready", "checkpoint_failed", "needs_decision", "no_changes", "live_edit_terminated", "timeout", "cancelled", "detached", "unknown". The result may carry "agentInstructions" on any poll; follow it whenever present. CRITICAL DO NOT IGNORE: When this result includes "browserNavigation", open its exact URL in the browser pane and verify the app loaded. Always follow "agentInstructions" in the result. When "building", continue polling. When "ready", call get_app to get the editor and preview URLs. When status "checkpoint_failed", follow "agentInstructions": open the editor only when "browserNavigation" is present; when it says the editor is temporarily unavailable, call get_app again. Do not claim the app was saved or keep polling. When "no_changes", do not present the edit URL as a finished app. For "no_changes", "timeout", "cancelled", or "live_edit_terminated", follow "pendingAction"; "retry_build" means call edit_app, while "start_new_app" means call start_app once with the same prompt and set replacesApplicationId to this result's applicationId. A terminal "live_edit_terminated" with no pendingAction means stop and report its reply; do not retry or create another application. When "detached", stop polling and point the user at the edit URL. When "unknown", the gateway is not following a turn for that app; the build may still be running, so follow "agentInstructions". The user sees nothing while this call is outstanding, so you MUST relay what Superblocks says between every pair of calls: before calling again, write the new "activity" lines into your own reply, oldest first, in Superblocks' own words. Relay every line, not just the latest — two different lines are two things to watch happen, not one. Never make two check_app_progress calls in a row with no message of your own in between, and never save the lines for a recap at the end. A heartbeat with no new words just means still working — say how long, then poll again. A checkpointCommitId means work is saved and the edit URL opens the finished app. 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: …", "Tests failed: …"). Relay those like any other activity and say which cases passed and failed. A failing test is a build signal, not an auth problem: keep polling, and never tell the user to re-authenticate over one. This tool also surfaces integration errors from mid-build queries run through the orchestrator. A 401 AuthorizationError from an orchestrator execute path is Superblocks/orchestrator auth (the scoped JWT or selected profile), not the datasource's own credentials: for Snowflake, do not advise re-entering the password or account in the integrations UI unless Snowflake itself clearly says stored credentials or a connection test failed — not SQL-permission wording like "does not exist or not authorized". The same goes for OpenAI API key failures: do not tell the user to re-authenticate. If status later reaches "ready", lead with "build succeeded" and mention a transient mid-build auth check only if asked.`,
             inputSchema: {
                 applicationId: z.string().uuid().optional(),
-                cursor: eventCursorInputSchema.optional(),
+                branch: z.string().optional(),
             },
             title: "Check App Progress",
-        }, async ({ applicationId, cursor }, extra) => run("check_app_progress", (context, forgetFinishedTurn) => {
-            // Validate at the boundary so a foreign/corrupt cursor falls back
-            // to the stored place instead of failing the tool call.
-            const parsed = cursor === undefined ? undefined : parseEventCursor(cursor);
-            gatewayDebug("progress cursor parsed", {
-                "progress.cursor_provided": cursor !== undefined,
-                "progress.cursor_valid": Boolean(parsed),
-            });
-            return progressWithDecisionForm(context, {
-                applicationId,
-                ...(parsed ? { cursor: parsed } : {}),
-            }, extra, forgetFinishedTurn);
-        }, extra));
-        registerAppTool(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" — 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 — 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 — never the edit URL.',
+        }, async ({ applicationId, branch }, extra) => run("check_app_progress", (context, forgetFinishedTurn) => progressWithDecisionForm(context, { applicationId, branch }, extra, forgetFinishedTurn), extra, "viewStatus", { applicationId, branch }));
+        // Its own card, because an MCP App binds to one tool and check_app_progress
+        // must stay text-only: a card tool reopens its card on every call, which
+        // would flash a blank form through a whole multi-minute build.
+        askUserTool = registerAppTool(server, "ask_user", {
+            description: 'Render a form to put the plan or question Superblocks stopped on to the user — call this the moment any tool reports status "needs_decision", except pendingAction "decide_in_editor" (nothing to show; point the user at the edit URL instead). Do not call this if check_app_progress agentInstructions says not too because you already have a native ask user form. Do not call this for missing integration setup during an import: follow check_app_progress agentInstructions instead. This is the one call to make before they answer: do not call check_app_progress, get_app, build_app, or any other Builder tool until the user has answered — polling cannot move a turn waiting on a person, and Superblocks decides, not you: you MUST NOT answer, supply, or decide it yourself. Do not guess, do not pick the option that looks obvious, do not read an answer out of something the user said earlier in the conversation, and do not approve a plan because it looks correct to you — an earlier "just build it" is not approval of this plan. Hosts that support MCP Apps render the plan with Build it / Change something next to it, or the question with one button per option, and the user\'s answer arrives as their own next message; when that form or card is showing, say nothing in chat. Hosts that do not render it get the whole decision in this result, which you must write out in your own reply — say anything else first, then the question, then end that reply with it. When you do write it out, show what Superblocks actually wrote: for "decision.kind" "plan" that is the whole "decision.plan" markdown, laid out as markdown, not a paraphrase — the user is approving this plan and has to be able to read it. For "multi_choice" it is "decision.question" plus every entry of "decision.options", none dropped or merged. Put the options to the user as something they can act on: if your host can render them as a picker, a form, or suggested replies, use that, carrying Superblocks\' own wording; if it cannot, ask in plain prose. Either way the options are an affordance, not typing — never type a numbered menu, a lettered list, or a row of quoted labels into the chat as a stand-in for one, least of all next to a picker already showing them. Answers go back through edit_app: planAction "approve" and no prompt only after the user clicks Build it in the MCP App or accepts a native elicitation form; a host that rendered neither must point the user to the Superblocks editor to approve. Use planAction "refine" with their words for changes, or the chosen option as prompt for "multi_choice". Returns the current status instead when nothing is waiting on the user, which is the signal to follow the build rather than ask again.',
             inputSchema: {
                 applicationId: z.string().uuid().optional(),
                 branch: z.string().optional(),
-                ensurePreview: z.boolean().optional(),
-                wait: z
+            },
+            title: "Ask User",
+            // Reads the decision Superblocks is already waiting on and puts it on
+            // screen. It starts nothing and changes nothing about the app, so a
+            // host that prompts here is asking permission to show the user a
+            // question they are the one being asked.
+            annotations: READ_ONLY_TOOL_ANNOTATIONS,
+            _meta: {
+                ui: { resourceUri: APP_DECISION_RESOURCE_URI },
+            },
+        }, async ({ applicationId, branch }, extra) => {
+            let asked;
+            const response = await run("ask_user", async (context) => {
+                asked = await askUser(context, {
+                    applicationId,
+                    branch,
+                });
+                return asked;
+            }, extra, { applicationId, branch });
+            const decision = asked ? pendingDecision(asked) : undefined;
+            if (!clientSupportsDecisionCard() ||
+                !asked ||
+                decision?.kind !== "plan") {
+                return response;
+            }
+            const decidedApp = resultApplicationId(asked) ?? applicationId;
+            if (!decidedApp) {
+                return response;
+            }
+            const decidedBranch = resultBranch(asked) ?? branch;
+            if (!rememberDisplayedPlan(deps.appState, decidedApp, decidedBranch, decision)) {
+                return response;
+            }
+            const approvalToken = await planApprovals.issue(deps.appState, decidedApp, decidedBranch);
+            return approvalToken
+                ? {
+                    ...response,
+                    _meta: { [PLAN_APPROVAL_TOKEN_META_KEY]: approvalToken },
+                }
+                : response;
+        });
+        confirmPlanApprovalTool = registerAppTool(server, CONFIRM_PLAN_APPROVAL_TOOL, {
+            annotations: NON_DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS,
+            description: "Internal to the decision card: confirms that the user clicked Build it for the current plan.",
+            inputSchema: {
+                approvalToken: z.string().uuid(),
+            },
+            title: "Confirm Plan Approval",
+            _meta: {
+                ui: {
+                    resourceUri: APP_DECISION_RESOURCE_URI,
+                    visibility: ["app"],
+                },
+            },
+        }, async ({ approvalToken }, extra) => {
+            let confirmed = false;
+            const response = await run(CONFIRM_PLAN_APPROVAL_TOOL, async (context) => {
+                confirmed = await planApprovals.confirm(context.appState, approvalToken);
+                return confirmed
+                    ? { kind: "ok", value: { confirmed: true } }
+                    : {
+                        kind: "error",
+                        code: "invalid_plan_approval",
+                        message: "This plan approval is missing, expired, or belongs to a plan that is no longer current.",
+                    };
+            }, extra);
+            return confirmed ? response : { ...response, isError: true };
+        });
+        registerAppResource(server, "Gateway decision", APP_DECISION_RESOURCE_URI, {
+            description: "Form for the plan or question Superblocks is waiting on",
+            mimeType: RESOURCE_MIME_TYPE,
+        }, async () => ({
+            contents: [
+                {
+                    uri: APP_DECISION_RESOURCE_URI,
+                    mimeType: RESOURCE_MIME_TYPE,
+                    text: APP_DECISION_HTML,
+                },
+            ],
+        }));
+        const getAppTool = server.registerTool("get_app", {
+            annotations: READ_ONLY_TOOL_ANNOTATIONS,
+            description: 'Return editor and live fullscreen-preview URLs for the recent or specified Superblocks application without committing or building it. While a plan or question is outstanding it returns status "needs_decision" with the "decision" and a "pendingAction" of "approve_plan", "answer_question", or "decide_in_editor" (nothing to show in chat — point the user at the edit URL), 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 no preview URLs or screenshot. When status "checkpoint_failed", follow "agentInstructions": open the editor only when "browserNavigation" is present; when it says the editor is temporarily unavailable, call get_app again. Do not claim the app was saved. Except for this checkpoint retry, follow "pendingAction" instead of calling this again; "retry_build" means call edit_app, while "start_new_app" means call start_app once with the same prompt and set replacesApplicationId to this result\'s applicationId. A terminal "live_edit_terminated" with no pendingAction means stop and report its reply; do not retry or create another application. A "detached" turn may still be running, so do not retry it; open the existing application in the editor. Prefer this after check_app_progress reaches status "ready". Also the right call when you do not know where a build stands — after a reconnect, when no turn of yours is running, or when the conversation moved to another channel: read "status" from the result rather than guessing. Hosts with a native browser receive a browserNavigation request without a duplicate status card; open its exact URL in that browser. Other 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 — never the edit URL. When this result includes a screenshot, inspect it yourself before reporting that the app looks correct. Skeletons, spinners, empty tables or charts, or "Loading..." — call get_app again a few seconds later rather than treating it as a defect. Do not test, debug, or correct a visible problem unless the user requests it; report what you see.',
+            inputSchema: {
+                applicationId: z.uuid().optional(),
+                branch: z.string().optional(),
+                includeScreenshot: z
                     .boolean()
-                    .optional()
-                    .describe('Whether to wait for the preview build. Defaults to true. Pass false to get the URLs and current status straight away, with "nextPollAfterMs" telling you when to look again — use that whenever you just need to know where things stand. This is a boolean and has nothing to do with the "ack" wait on start_app / edit_app.'),
+                    .default(true)
+                    .describe("Whether to capture a screenshot. Defaults to true."),
             },
             title: "Get App",
+        }, async ({ applicationId, branch, includeScreenshot }, extra) => run("get_app", async (context) => {
+            const result = await getApp(context, {
+                applicationId,
+                branch,
+                includeScreenshot: clientPresentationCapabilities(server.server.getClientVersion()).hasNativeBrowser
+                    ? false
+                    : includeScreenshot,
+            });
+            stageNativePlanApproval(result, extra.requestId);
+            return result;
+        }, extra, "status", { applicationId, branch, includeScreenshot }));
+        statusCardTools.push(getAppTool);
+        registerAppTool(server, "get_app_status", {
+            annotations: READ_ONLY_TOOL_ANNOTATIONS,
+            description: "Internal to the status card: returns the current app status without creating another card or screenshot.",
+            inputSchema: {
+                applicationId: z.uuid().optional(),
+                branch: z.string().optional(),
+            },
+            title: "Get App Status",
             _meta: {
-                ui: { resourceUri: APP_STATUS_RESOURCE_URI },
+                ui: {
+                    resourceUri: APP_STATUS_RESOURCE_URI,
+                    visibility: ["app"],
+                },
             },
-        }, async ({ applicationId, branch, ensurePreview, wait }, extra) => run("get_app", (context) => getApp(context, { applicationId, branch, ensurePreview, wait }), extra));
-        server.registerTool("preview_app", {
+        }, async ({ applicationId, branch }, extra) => run("get_app_status", (context) => getApp(context, {
+            applicationId,
+            branch,
+            includeScreenshot: false,
+        }), extra, { applicationId, branch }));
+        server.registerTool("get_preview_status", {
             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 — 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.',
+            description: "Check an existing unpublished build using the applicationId, commitId, directoryHash, and branch returned by build_app. Does not create commits, builds, or deployments. On ready, share the original build_app previewUrl; do not call build_app again to poll.",
+            inputSchema: {
+                applicationId: z.uuid(),
+                branch: z.string().optional(),
+                commitId: z.string(),
+                directoryHash: z.string(),
+                wait: z
+                    .boolean()
+                    .default(true)
+                    .describe("Wait until the build finishes or the tool deadline; false returns one status check for the app card."),
+            },
+            title: "Get Preview Status",
+        }, async (input, extra) => run("get_preview_status", (context) => getPreviewStatus(context, input), extra, input));
+        // The card is what puts a screenshot on screen: hosts that render an MCP
+        // App render it instead of the tool's content blocks, so without it this
+        // tool's deployed-shell screenshot reached nobody.
+        const buildAppTool = server.registerTool("build_app", {
+            annotations: NON_DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS,
+            description: 'Snapshot the recent or specified application\'s current work and return a URL for that commit, without publishing or deploying it. Call only when the user explicitly requests an unpublished build or a shareable versioned preview, never automatically after creating, editing, or viewing an app. For the live development preview use read-only get_app. Each build_app call creates a commit. On status "building", retain previewUrl and poll get_preview_status with the returned applicationId, commitId, directoryHash, and branch; do not call build_app again to poll. Status "ready" means the commit preview is built. Sharing the returned link does not change app permissions or publish the app.',
             inputSchema: {
                 applicationId: z.string().uuid().optional(),
                 branch: z.string().optional(),
             },
-            title: "Preview App",
-        }, async ({ applicationId, branch }, extra) => run("preview_app", (context) => previewApp(context, { applicationId, branch }), extra));
-        // Nested iframes were removed (auth + Private Network Access). Empty
-        // frameDomains keeps the MCP Apps CSP shape without advertising embed origins.
-        const uiCsp = { csp: { frameDomains: [] } };
+            title: "Build App",
+        }, async ({ applicationId, branch }, extra) => run("build_app", (context) => previewApp(context, { applicationId, branch, wait: false }), extra, { applicationId, branch }));
+        statusCardTools.push(buildAppTool);
         registerAppResource(server, "Gateway app status", APP_STATUS_RESOURCE_URI, {
             description: "Status card with Open editor / Open preview / Publish app",
             mimeType: RESOURCE_MIME_TYPE,
-            _meta: { ui: uiCsp },
         }, async () => ({
             contents: [
                 {
                     uri: APP_STATUS_RESOURCE_URI,
                     mimeType: RESOURCE_MIME_TYPE,
                     text: APP_STATUS_HTML,
-                    _meta: { ui: uiCsp },
                 },
             ],
         }));
-        server.registerTool("publish_app", {
+        publishAppTool = 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.",
+            description: publishAppDescription(false),
             inputSchema: {
                 applicationId: z.string().uuid().optional(),
                 branch: z.string().optional(),
@@ -519,14 +1038,52 @@ export function createMcpServer(deps) {
             commitId,
             idempotencyKey: idempotencyKey ?? `mcp-publish:${randomUUID()}`,
             prompt,
-        }), extra));
+        }), extra, { applicationId, branch, commitId, idempotencyKey, prompt }));
+        server.registerTool("check_publish_progress", {
+            description: 'Report on the status of a publish. Each call watches the rollout for up to about 25 seconds and returns as soon as it completes. Returns status "deployed" once the app is live and "publishing" while the deploy is still rolling out; call it again until it is no longer "publishing". Follows the commit publish_app queued, so commitId is only needed to follow a different one. Publishing can take a long time, depending on the number of configured policy gates. Continue to poll until the app is live. Never re-deploys, and never claim the app is live while status is "publishing".',
+            inputSchema: {
+                applicationId: z.string().uuid().optional(),
+                commitId: z.string().optional(),
+            },
+            title: "Check Publish Progress",
+            // The same poll loop as check_app_progress, on the deploy instead of
+            // the build: it reports where the publish got to and does nothing else.
+            annotations: READ_ONLY_TOOL_ANNOTATIONS,
+        }, async ({ applicationId, commitId }, extra) => run("check_publish_progress", (context) => checkPublishProgress(context, { applicationId, commitId }), extra, { applicationId, commitId }));
     }
     // Customer Admin tools (integrations, apps, users, deploy_application, ...)
     // on the same MCP surface. Credential is the CLI session this process
     // started with; base_url defaults to this gateway's Server URL.
     registerAdminTools(server, {
         apiKey: deps.cliApiKey,
+        clientProfile: clientProfileFor,
         localAgentMode: deps.config.localAgentMode,
+        resolveEditorIntegrationSetupUrl: (integrationId, applicationId) => {
+            // Only the caller knows which application its conversation is building.
+            // This process serves every chat in the client and stdio carries no chat
+            // identity, so recency of the work cannot tell "the editor the user is
+            // looking at" from one another conversation left open: guessing lands
+            // credential entry in an unrelated app. Unnamed means the org page.
+            if (!applicationId) {
+                return undefined;
+            }
+            const identity = deps.cliIdentity ?? resolvedIdentity;
+            const recent = identity
+                ? deps.recentApps.recentForApplication({
+                    organizationId: identity.organizationId,
+                    userId: identity.userId,
+                }, applicationId, EDITOR_SETUP_RECENT_APP_WINDOW_MS)
+                : undefined;
+            return editorIntegrationSetupUrl({
+                applicationId,
+                // Branch only, and only for the application the caller named, so a
+                // stale entry cannot redirect the app itself.
+                branch: deps.sessionPeer.heldContext(applicationId)?.branch ?? recent?.branch,
+                cowork: clientProfileFor().hasNativeBrowser,
+                integrationId,
+                uiBaseUrl: deps.config.uiBaseUrl,
+            });
+        },
         serverUrl: deps.config.serverUrl,
     });
     return server;