@superblocksteam/gateway 2.0.0-SNAPSHOT.1d4c72c0ab174c21

package/dist/transports/mcp/mount.js

@@ -0,0 +1,1040 @@
+import { randomUUID } from "node:crypto";
+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 { getIntegrationMetadata } from "../../capabilities/integration-metadata.js";
+import { askUser, checkAppProgress, checkPublishProgress, editApp, getApp, getPreviewStatus, previewApp, publishApp, startApp, uploadArtifact, } from "../../capabilities/lifecycle.js";
+import { queryIntegration } from "../../capabilities/query-integration.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 { 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 { 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 { 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 { 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,
+    idempotentHint: false,
+    openWorldHint: true,
+    readOnlyHint: false,
+};
+const NON_DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS = {
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true,
+    readOnlyHint: false,
+};
+const READ_ONLY_TOOL_ANNOTATIONS = {
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+    readOnlyHint: true,
+};
+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
+ * and no OAuth authInfo on stdio.
+ *
+ * When `cliIdentity` is already known, it is handed over fully resolved so no
+ * capability spends a `/users/me` round trip (ENG-5806). Otherwise
+ * `ensurePrincipal` resolves it once through the guarded identity read.
+ */
+function principalFrom(deps) {
+    return {
+        apiKey: deps.cliApiKey,
+        ...(deps.cliIdentity ?? {}),
+    };
+}
+/**
+ * Told to the model on connect, so it can match what a user actually says
+ * against these tools.
+ *
+ * People refer to this one system as the product and builder ("Superblocks")
+ * or by an older name for that same builder ("Clark"). Listing that accepted
+ * alias here is what lets "get Clark to build me a to-do app" reach
+ * `start_app`. Recognizing a name and using it are different things: the alias
+ * is input-only, because a client that reads "Clark" here repeats it back and
+ * reintroduces the retired name to the user.
+ */
+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.
+
+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.
+
+Use these tools whenever the user asks to build, change, import, or ship an app, whichever of those names they reach for. They also answer questions about what data the org has: list_integrations names the datasources, get_integration_metadata reads the tables and columns inside one, and query_integration runs a bounded read-only SQL query to answer the question directly rather than building an app to explore it. Create a persistent app or API only when the user explicitly asks for one.
+
+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.
+
+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.
+
+After each tool call, check for agentInstructions in the result and follow them. These instructions are tailored to the scenario.
+
+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.
+
+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.
+
+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.
+
+When the source is a readable tree already on this machine (a clone, an unzipped export, or a workspace folder), do not zip or upload it. Follow the Superblocks Agent Skill "superblocks-import" when the host has loaded it: inventory locally, start_app a scaffold, then slice via edit_app (integrations first, then one API or page at a time), grounding each slice in get_application_structure. Superblocks writes the application; do not invent Superblocks client/ or server/ files on the laptop.
+
+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.
+
+This connector is the single Superblocks MCP: Builder tools (upload_artifact, query_integration, start_app, edit_app, check_app_progress, ask_user, get_app, preview_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.
+
+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.
+
+Never tell the user to restart the MCP server; keep the MCP server running.
+
+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.
+
+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. 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 embedded browser tools, you will need them. Call ToolSearch with query select:mcp__remote-devices__Claude_Browser__preview_start,mcp__remote-devices__Claude_Browser__navigate,mcp__remote-devices__Claude_Browser__tabs_context. 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.replace(", preview_app", "")}
+
+${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 embedded browser 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, 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) => ({
+        appState: deps.appState,
+        captureLibraryScreenshot: captureLibraryScreenshotWithPlaywright,
+        capturePreviewScreenshot: capturePreviewScreenshotWithPlaywright,
+        config: deps.config,
+        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),
+        progress: deps.progress,
+        recentApps: deps.recentApps,
+        server: deps.server,
+        sessionPeer: deps.sessionPeer,
+        ...(signal ? { signal } : {}),
+        stepUpTurns: deps.stepUpTurns,
+    });
+    /**
+     * Runs a capability and renders it as tool content. An unexpected throw
+     * becomes an error result rather than taking the process down, and carries
+     * 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, browserNavigationReady) => {
+        gatewayDebugStack("tool started", {
+            "tool.name": toolName,
+            metadata: extra?._meta,
+        });
+        const progress = [];
+        const notify = createProgressNotifier(extra);
+        const execute = async () => {
+            if (!deps.cliApiKey) {
+                gatewayDebug("tool short-circuited", {
+                    "tool.name": toolName,
+                    "tool.reason": "missing_cli_session",
+                });
+                return {
+                    kind: "error",
+                    code: "unauthenticated",
+                    message: "This Gateway has no CLI session. Run: superblocks login",
+                };
+            }
+            try {
+                // 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
+                // and a waiter running for an answer nobody will read.
+                const signal = extra?.signal;
+                const capabilityContext = await context(progress, notify, signal);
+                return await capability(capabilityContext, () => {
+                    for (let index = progress.length - 1; index >= 0; index -= 1) {
+                        if (progress[index]?.type === "completed") {
+                            progress.splice(index, 1);
+                        }
+                    }
+                });
+            }
+            catch (error) {
+                console.error("gateway capability failed", error);
+                return {
+                    kind: "error",
+                    code: "capability_failed",
+                    message: error instanceof Error
+                        ? error.message
+                        : "The gateway failed for an unknown reason.",
+                };
+            }
+        };
+        const client = server.server.getClientVersion();
+        const 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({
+                ...(client
+                    ? {
+                        client: {
+                            name: client.name,
+                            version: client.version,
+                        },
+                    }
+                    : {}),
+                toolName,
+            }, executeWithBrowserNavigation)
+            : await executeWithBrowserNavigation();
+        const profile = clientProfileFor();
+        result = attachAgentInstructions(toolName, result, profile);
+        const resultStatus = result.kind === "ok" &&
+            result.value &&
+            typeof result.value === "object" &&
+            "status" in result.value &&
+            typeof result.value.status === "string"
+            ? result.value.status
+            : undefined;
+        gatewayDebug("tool finished", {
+            "progress.event_count": progress.length,
+            ...(result.kind === "error" ? { "result.code": result.code } : {}),
+            "result.kind": result.kind,
+            ...(resultStatus ? { "result.status": resultStatus } : {}),
+            "tool.name": toolName,
+        });
+        // structuredContent lets MCP Apps hosts hand the capability value to the
+        // status card without making it re-parse the JSON text block.
+        const structuredContent = result.kind === "ok" &&
+            result.value &&
+            typeof result.value === "object" &&
+            !Array.isArray(result.value)
+            ? (() => {
+                const value = { ...result.value };
+                delete value.screenshotBase64;
+                return value;
+            })()
+            : undefined;
+        return {
+            content: formatMcpToolContent(result, progress, profile),
+            ...(structuredContent ? { structuredContent } : {}),
+        };
+    };
+    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 previewAppTool;
+    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) {
+            previewAppTool?.disable();
+            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. 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,
+        });
+        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 unresolvedDecision();
+        }
+        if (decision.kind === "plan" && !displayedPlan) {
+            return unresolvedDecision();
+        }
+        const resolved = await resolveDecisionByElicitation({
+            apply: (answer) => {
+                forgetFinishedTurn();
+                // 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,
+            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 ?? 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,
+    // edit_app, ...) is skipped entirely rather than registered and left to
+    // fail on its first call.
+    if (!deps.config.adminToolsOnly) {
+        gatewayDebug("builder tool registration selected", {
+            "gateway.admin_tools_only": false,
+        });
+        registerBuilderTools();
+    }
+    else {
+        gatewayDebug("builder tool registration skipped", {
+            "gateway.admin_tools_only": true,
+        });
+    }
+    function registerBuilderTools() {
+        server.registerTool("get_integration_metadata", {
+            annotations: READ_ONLY_TOOL_ANNOTATIONS,
+            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()
+                    .uuid()
+                    .optional()
+                    .describe("Only for an integration owned by a single application, such as a Native DB. Leave unset otherwise; do not go looking for an application to supply."),
+                integrationId: z.string().uuid(),
+                limit: z.number().int().min(1).max(200).optional(),
+                offset: z.number().int().min(0).optional(),
+                search: z.string().min(1).optional(),
+            },
+            title: "Get Integration Metadata",
+        }, async (input, extra) => run("get_integration_metadata", (context) => getIntegrationMetadata(context, input), extra));
+        server.registerTool("query_integration", {
+            annotations: READ_ONLY_TOOL_ANNOTATIONS,
+            description: "Run one bounded read-only SQL query, parser-constrained to PostgreSQL-compatible Superblocks integrations, and return the result directly. Use this after list_integrations and get_integration_metadata to inspect rows or answer a one-off data question. This direct operation does not create an API or application and does not prompt Superblocks. Only one SELECT, read-only CTE, SHOW, or EXPLAIN statement is accepted; mutations, schema or session changes, row locks, explicit casts, and functions other than count, sum, avg, min, and max are rejected before execution. Requires build permission on the integration. Keep result sets focused with a small LIMIT.",
+            inputSchema: {
+                integrationId: z.string().uuid(),
+                query: z.string().trim().min(1).max(20_000),
+            },
+            title: "Query Integration",
+        }, async (input, extra) => run("query_integration", (context) => queryIntegration(context, input), extra));
+        server.registerTool("start_app", {
+            annotations: NON_DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS,
+            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 embedded browser 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 ({ artifacts, branch, idempotencyKey, mode, name, prompt, replacesApplicationId, }, extra) => run("start_app", (context) => startApp(context, {
+            artifacts,
+            branch,
+            idempotencyKey: idempotencyKey ?? `mcp-start:${randomUUID()}`,
+            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("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). 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. Exclude node_modules. If the project is a readable tree on this machine or already on disk, do not upload it; follow the superblocks-import skill and migrate it in slices. 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: {
+                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(),
+            },
+            title: "Upload File or Source Artifact",
+        }, async ({ filePath, files, zipBase64 }, extra) => run("upload_artifact", (context) => uploadArtifact(context, {
+            filePath,
+            files,
+            zipBase64,
+        }), extra));
+        server.registerTool("edit_app", {
+            annotations: DESTRUCTIVE_TOOL_ANNOTATIONS,
+            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 embedded browser 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(),
+                planAction: z.enum(["approve", "refine"]).optional(),
+                prompt: z.string().min(1).optional(),
+            },
+            title: "Edit App",
+        }, 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;
+            if (planAction === "approve" && !approval) {
+                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));
+        server.registerTool("check_app_progress", {
+            // 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 embedded browser 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(),
+                branch: z.string().optional(),
+            },
+            title: "Check App Progress",
+        }, async ({ applicationId, branch }, extra) => run("check_app_progress", (context, forgetFinishedTurn) => progressWithDecisionForm(context, { applicationId, branch }, extra, forgetFinishedTurn), extra, "viewStatus"));
+        // 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, preview_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(),
+            },
+            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);
+            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. 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 screenshot. Otherwise describe what you see and ask the user whether to fix it.',
+            inputSchema: {
+                applicationId: z.uuid().optional(),
+                branch: z.string().optional(),
+                includeScreenshot: z
+                    .boolean()
+                    .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"));
+        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,
+                    visibility: ["app"],
+                },
+            },
+        }, async ({ applicationId, branch }, extra) => run("get_app_status", (context) => getApp(context, {
+            applicationId,
+            branch,
+            includeScreenshot: false,
+        }), extra));
+        registerAppTool(server, "get_preview_status", {
+            annotations: READ_ONLY_TOOL_ANNOTATIONS,
+            description: "Internal to the status card: checks an existing commit preview build without creating another commit or build.",
+            inputSchema: {
+                applicationId: z.uuid(),
+                branch: z.string().optional(),
+                commitId: z.string(),
+                directoryHash: z.string(),
+            },
+            title: "Get Preview Status",
+            _meta: {
+                ui: {
+                    resourceUri: APP_STATUS_RESOURCE_URI,
+                    visibility: ["app"],
+                },
+            },
+        }, async (input, extra) => run("get_preview_status", (context) => getPreviewStatus(context, input), extra));
+        // 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.
+        previewAppTool = server.registerTool("preview_app", {
+            annotations: NON_DESTRUCTIVE_WRITE_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. Hosts that support MCP Apps show the same status card get_app shows (Open editor / Open preview), carrying a screenshot of the deployed preview shell rather than the live Vite canvas. Call this instead of get_app, not as well as it — both open a card, and calling both opens two.',
+            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));
+        statusCardTools.push(previewAppTool);
+        registerAppResource(server, "Gateway app status", APP_STATUS_RESOURCE_URI, {
+            description: "Status card with Open editor / Open preview / Publish app",
+            mimeType: RESOURCE_MIME_TYPE,
+        }, async () => ({
+            contents: [
+                {
+                    uri: APP_STATUS_RESOURCE_URI,
+                    mimeType: RESOURCE_MIME_TYPE,
+                    text: APP_STATUS_HTML,
+                },
+            ],
+        }));
+        publishAppTool = server.registerTool("publish_app", {
+            annotations: DESTRUCTIVE_TOOL_ANNOTATIONS,
+            description: publishAppDescription(false),
+            inputSchema: {
+                applicationId: z.string().uuid().optional(),
+                branch: z.string().optional(),
+                commitId: z.string().optional(),
+                idempotencyKey: z.string().optional(),
+                prompt: z.string().min(1),
+            },
+            title: "Publish App",
+        }, async ({ applicationId, branch, commitId, idempotencyKey, prompt }, extra) => run("publish_app", (context) => publishApp(context, {
+            applicationId,
+            branch,
+            commitId,
+            idempotencyKey: idempotencyKey ?? `mcp-publish:${randomUUID()}`,
+            prompt,
+        }), extra));
+        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));
+    }
+    // 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) => {
+            const identity = deps.cliIdentity ?? resolvedIdentity;
+            if (!identity) {
+                return undefined;
+            }
+            const applicationId = deps.recentApps.get({
+                organizationId: identity.organizationId,
+                userId: identity.userId,
+            });
+            if (!applicationId) {
+                return undefined;
+            }
+            const held = deps.sessionPeer.heldContext(applicationId);
+            if (!held) {
+                return undefined;
+            }
+            return editorIntegrationSetupUrl({
+                applicationId,
+                branch: held.branch,
+                cowork: clientProfileFor().hasNativeBrowser,
+                integrationId,
+                uiBaseUrl: deps.config.uiBaseUrl,
+            });
+        },
+        serverUrl: deps.config.serverUrl,
+    });
+    return server;
+}
+//# sourceMappingURL=mount.js.map