@superblocksteam/gateway 2.0.177 → 2.0.178-next.1

package/dist/capabilities/lifecycle.js

@@ -1,9 +1,9 @@
 import { randomUUID } from "node:crypto";
 import { readFile, realpath, stat } from "node:fs/promises";
 import path from "node:path";
-import { detectAttachmentArchiveType, getAttachmentMimeTypeFromFileName, getTextAttachmentType, isSupportedAttachmentUploadType, } from "@superblocksteam/shared";
-import { buildBrowserDriverContract, HOST_BROWSER_TOOLS_COWORK, needsBrowserDriverError, } from "../capture/browser-contract.js";
-import { withCoworkEditorHost } from "../capture/cowork-editor-url.js";
+import { DESTRUCTIVE_MIGRATION_ACK_REQUIRED_MESSAGE, detectAttachmentArchiveType, getAttachmentMimeTypeFromFileName, getTextAttachmentType, isSupportedAttachmentUploadType, } from "@superblocksteam/shared";
+import { HOSTED_CUSTOMER_AGENT_PREVIEW_MESSAGE, hostedAgentAllowed, } from "../agents/hosted-boundary.js";
+import { buildBrowserDriverContract, needsBrowserDriverError, } from "../capture/browser-contract.js";
 import { resolveCaptureMode } from "../capture/mode.js";
 import { withDeadline } from "../deadline.js";
 import { gatewayDebug } from "../debug.js";
@@ -11,7 +11,7 @@ import { playwrightChromiumPresent } from "../playwright/ensure-chromium.js";
 import { isTrustedEmbedOrigin, } from "../preview/capture-screenshot.js";
 import { buildEmbedShellPreviewUrl, buildOpenablePreviewUrls, isHttpsUrl, } from "../preview/viewer-url.js";
 import { PromptNotSentError, } from "../sabs/session-peer.js";
-import { ServerHttpError } from "../server/client.js";
+import { ServerHttpError, ServerTimeoutError } from "../server/client.js";
 import { IdentityUnavailableError } from "../server/identity-reads.js";
 import { archiveSourceFiles } from "./source-files-archive.js";
 import { TOOL_PERMISSION_ANSWERS, ToolPermissionReply, } from "./tool-permission-reply.js";
@@ -36,15 +36,12 @@ const RECENT_APP_FALLBACK_WINDOW_MS = 30 * 60 * 1000;
 function editorBaseUrl(config, applicationId) {
     return `${config.uiBaseUrl.replace(/\/$/, "")}/code-mode/applications/edit/${applicationId}`;
 }
-/** The editor URL handed to the caller, in the host mode its client renders. */
+/** The editor URL handed to the caller. Every client gets the same one. */
 function editUrl(ctx, applicationId, branch) {
     const base = editorBaseUrl(ctx.config, applicationId);
-    const url = branch
+    return branch
         ? `${base}?${new URLSearchParams({ branch }).toString()}`
         : base;
-    return ctx.hostBrowserTools === HOST_BROWSER_TOOLS_COWORK
-        ? withCoworkEditorHost(url)
-        : url;
 }
 function fullscreenPreviewUrl(config, applicationId, branch) {
     const params = new URLSearchParams({ fullscreen: "true" });
@@ -188,6 +185,7 @@ async function attachLiveState(ctx, principal, scope) {
             branch,
             organizationId: principal.organizationId,
         });
+        ctx.liveStateAttaches.opened(scope, session.liveEditId);
         const sessionToken = await ctx.server.issueScopedToken({
             apiKey: principal.apiKey,
             applicationId,
@@ -212,6 +210,7 @@ async function attachLiveState(ctx, principal, scope) {
             },
             liveEditId: session.liveEditId,
             liveEditUrl: session.liveEditUrl,
+            ...(session.targetBranch ? { liveEditBranch: session.targetBranch } : {}),
             organizationId: principal.organizationId,
             sessionToken,
             userId: principal.userId,
@@ -237,6 +236,33 @@ async function attachLiveState(ctx, principal, scope) {
     }
     return { kind: "ok", value: undefined };
 }
+/**
+ * Whether the hosted Platform MCP may load this org's app in its own Chromium.
+ * The preview picks the org's agents itself, so for an org that runs its own
+ * agent any API that runs on page load would reach into the customer's network
+ * from our control plane. Fails closed when the agent type cannot be read.
+ */
+async function hostedBrowserMayLoadApp(ctx, principal) {
+    if (!ctx.config.hosted) {
+        return true;
+    }
+    try {
+        const inventory = await ctx.server.getAgentInventory({
+            apiKey: principal.apiKey,
+            organizationId: principal.organizationId,
+        });
+        return hostedAgentAllowed({
+            agentType: inventory.agentType,
+            hosted: true,
+        });
+    }
+    catch (error) {
+        console.warn("gateway hosted agent type unreadable; skipping preview", {
+            message: error instanceof Error ? error.message : String(error),
+        });
+        return false;
+    }
+}
 async function captureLiveLibraryIfNeeded(ctx, applicationId, live) {
     if (!live) {
         return {};
@@ -275,7 +301,6 @@ async function browserContractFor(ctx, directEditUrl) {
     return buildBrowserDriverContract({
         captureMode: await captureModeOf(ctx),
         editUrl: directEditUrl,
-        ...(ctx.hostBrowserTools ? { hostBrowserTools: ctx.hostBrowserTools } : {}),
         isolated: ctx.config.captureHostIsolated,
         uiOrigin: uiOrigin(ctx.config),
     });
@@ -766,6 +791,7 @@ function turnSummary(turn) {
 async function promptInput(ctx, input) {
     return {
         apiKey: ctx.principal.apiKey,
+        mcpClientName: ctx.mcpClientName,
         applicationId: input.applicationId,
         ...(input.attachments ? { attachments: input.attachments } : {}),
         ...(input.branch ? { branch: input.branch } : {}),
@@ -786,6 +812,7 @@ async function promptInput(ctx, input) {
         },
         ...(input.liveEditId ? { liveEditId: input.liveEditId } : {}),
         liveEditUrl: input.liveEditUrl,
+        ...(input.liveEditBranch ? { liveEditBranch: input.liveEditBranch } : {}),
         mode: input.mode ?? "PLAN",
         // Asked for only if the host above turns out not to serve the session any
         // more. Going back through openLiveEdit rather than connectLiveEdit
@@ -1194,6 +1221,7 @@ async function promptNewApplication(ctx, args) {
         idempotencyKey: input.idempotencyKey,
         liveEditId: session.liveEditId,
         liveEditUrl: session.liveEditUrl,
+        ...(session.targetBranch ? { liveEditBranch: session.targetBranch } : {}),
         mode: input.mode ?? "PLAN",
         organizationId: principal.organizationId,
         ...(args.pendingStartToken === undefined
@@ -1544,19 +1572,22 @@ function tooLargeError(size) {
  * out, so it accepts anything attachments support rather than archives alone.
  * The other two routes are text channels and stay archive-shaped.
  */
-async function resolveImportArchive(input, searchDirs) {
+async function resolveImportArchive(input, config) {
     const hasFiles = Boolean(input.files?.length);
-    const hasPath = Boolean(input.filePath?.trim());
+    // Hosted, the disk is the microVM's own, never the user's files.
+    const hasPath = !config.hosted && Boolean(input.filePath?.trim());
     const hasBase64 = Boolean(input.zipBase64?.trim());
     if (Number(hasFiles) + Number(hasPath) + Number(hasBase64) !== 1) {
         return {
             kind: "error",
             code: "import_zip_required",
-            message: "Provide exactly one of files, filePath (a path or file name on the gateway host), or zipBase64.",
+            message: config.hosted
+                ? "Provide exactly one of files or zipBase64."
+                : "Provide exactly one of files, filePath (a path or file name on the gateway host), or zipBase64.",
         };
     }
     if (hasPath) {
-        return resolveFileByPath(input.filePath.trim(), searchDirs);
+        return resolveFileByPath(input.filePath.trim(), config.importSearchDirs);
     }
     let bytes;
     if (hasFiles) {
@@ -1565,7 +1596,7 @@ async function resolveImportArchive(input, searchDirs) {
             return {
                 kind: "error",
                 code: "import_files_invalid",
-                message: `"${binaryFile.path}" is not a text file, and files entries are archived as the text they contain: base64 in there uploads as base64 characters wearing a "${path.extname(binaryFile.path)}" name. Pass filePath with the file's name instead, so the gateway reads its real bytes.`,
+                message: `"${binaryFile.path}" is not a text file, and files entries are archived as the text they contain: base64 in there uploads as base64 characters wearing a "${path.extname(binaryFile.path)}" name. ${config.hosted ? "Put it in a ZIP and pass that as zipBase64 instead, so its real bytes are uploaded. A ZIP too large for zipBase64 cannot be uploaded on this connection yet." : "Pass filePath with the file's name instead, so the gateway reads its real bytes."}`,
             };
         }
         const archive = archiveSourceFiles(input.files);
@@ -1689,7 +1720,7 @@ export async function uploadArtifact(ctx, input) {
     if (principalResult.kind !== "ok") {
         return principalResult;
     }
-    const archiveResult = await resolveImportArchive(input, ctx.config.importSearchDirs);
+    const archiveResult = await resolveImportArchive(input, ctx.config);
     if (archiveResult.kind !== "ok") {
         return archiveResult;
     }
@@ -2355,6 +2386,7 @@ async function promptExistingApplication(ctx, args) {
         idempotencyKey: input.idempotencyKey,
         liveEditId: session.liveEditId,
         liveEditUrl: session.liveEditUrl,
+        ...(session.targetBranch ? { liveEditBranch: session.targetBranch } : {}),
         mode: editTurnMode(input, answeringQuestion),
         organizationId: principal.organizationId,
         ...(args.pendingStartToken === undefined
@@ -2551,10 +2583,17 @@ export async function previewApp(ctx, input) {
     ctx.onProgress?.({ message: "Preparing a preview", type: "progress" });
     let commit;
     try {
+        // With branching on, the work is on the user's own branch, and a commit
+        // that names no branch would preview main instead.
+        const branch = input.branch ??
+            (await readUserBranch(ctx, {
+                apiKey: principal.apiKey,
+                applicationId,
+            }))?.branch;
         commit = await ctx.server.createCommit({
             apiKey: principal.apiKey,
             applicationId,
-            branch: input.branch,
+            branch,
             message: "Preview",
         });
     }
@@ -2652,6 +2691,13 @@ export async function previewApp(ctx, input) {
         });
         needsBrowserDriver = true;
     }
+    else if (!(await hostedBrowserMayLoadApp(ctx, principal))) {
+        screenshotUnavailableReason = HOSTED_CUSTOMER_AGENT_PREVIEW_MESSAGE;
+        console.error("gateway preview screenshot skipped", {
+            applicationId,
+            reason: "hosted_customer_agent",
+        });
+    }
     else if (!jwt) {
         screenshotUnavailableReason =
             "Preview screenshot unavailable because its scoped credential could not be created.";
@@ -2956,13 +3002,86 @@ async function unbuiltReason(ctx, principal, applicationId, requestedBranch) {
     });
     const candidate = ctx.appState.pendingDecision(applicationId, branch);
     const pending = turn && candidate?.branch !== turn.branch ? undefined : candidate;
-    const reason = localUnbuiltReason(turn, pending);
+    // The branch `currentTurnBranch` gave the read's attach.
+    const actualBranch = turn ? turn.branch : (pending?.branch ?? branch);
+    const reason = localUnbuiltReason(turn, pending) ??
+        (await stoppedLiveEditReason(ctx, principal, {
+            applicationId,
+            branch: actualBranch,
+            organizationId: principal.organizationId,
+            userId: principal.userId,
+        }));
     if (!reason) {
         return undefined;
     }
-    const actualBranch = turn ? turn.branch : (pending?.branch ?? branch);
     return { ...(actualBranch ? { branch: actualBranch } : {}), reason };
 }
+/** The status lookup runs after the read's deadline, so it is kept short. */
+const LIVE_EDIT_STATUS_TIMEOUT_MS = 3_000;
+const LIVE_EDIT_STOPPED_REPLY = "The Superblocks live-edit session for this app stopped, so nothing is serving the editor or preview. Your saved work is not affected. Call edit_app to start a new session.";
+/**
+ * Why a read that would otherwise say ready must not: the live edit its own
+ * attach opened has ended.
+ *
+ * A read that holds no socket answers from what this process knows, which
+ * for an app with no turn is "ready". A cold start, a full sandbox pool or
+ * another user's editor lock also leave nothing held, and those stay ready,
+ * so only the control plane saying the session ended counts.
+ */
+async function stoppedLiveEditReason(ctx, principal, scope) {
+    const opened = ctx.liveStateAttaches.openedLiveEdit(scope);
+    if (!opened ||
+        heldSocketFor(ctx, scope.applicationId, scope.branch) === "this_branch") {
+        return undefined;
+    }
+    // The control plane forgets an ended live edit once its editor lock
+    // expires, so an answer it gave once is kept until a new attach starts.
+    const cached = opened.endedStatus !== undefined;
+    let status = opened.endedStatus;
+    if (!status) {
+        try {
+            status = await ctx.server.getLiveEditStatus({
+                apiKey: principal.apiKey,
+                applicationId: scope.applicationId,
+                branch: scope.branch,
+                liveEditId: opened.liveEditId,
+                signal: AbortSignal.any([
+                    AbortSignal.timeout(LIVE_EDIT_STATUS_TIMEOUT_MS),
+                    ...(ctx.signal ? [ctx.signal] : []),
+                ]),
+            });
+        }
+        catch (error) {
+            // A caller that went away cancels the lookup, which is not a failure.
+            if (!ctx.signal?.aborted) {
+                console.error("gateway live edit status check failed", {
+                    applicationId: scope.applicationId,
+                    liveEditId: opened.liveEditId,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+            }
+            return undefined;
+        }
+        if (status !== "terminated" && status !== "terminating") {
+            return undefined;
+        }
+        ctx.liveStateAttaches.stopped(scope, opened.liveEditId, status);
+    }
+    console.warn("gateway live edit stopped", {
+        applicationId: scope.applicationId,
+        branch: scope.branch,
+        cached,
+        liveEditId: opened.liveEditId,
+        organizationId: scope.organizationId,
+        status,
+    });
+    return {
+        kind: "empty_turn",
+        pendingAction: "retry_build",
+        reply: LIVE_EDIT_STOPPED_REPLY,
+        status: "live_edit_terminated",
+    };
+}
 function currentTurnBranch(ctx, principal, applicationId, requestedBranch) {
     const branch = normalizeBranch(requestedBranch);
     const turn = ctx.sessionPeer.turnState({
@@ -3411,7 +3530,7 @@ export async function checkPublishProgress(ctx, input) {
         return namingApplication(applicationId, {
             kind: "error",
             code: "publish_not_started",
-            message: "No publish is in flight for this application. Call publish_app to deploy it, or name the commitId to follow.",
+            message: "No publish is in flight for this application. A publish that publish_app already reported as deployed is live. To follow a specific deploy, pass the commitId publish_app returned.",
         });
     }
     const claimedCommit = storedCommitId === undefined;
@@ -3563,6 +3682,155 @@ export async function checkPublishProgress(ctx, input) {
         }
     }
 }
+/**
+ * The caller's own branch when branching is on for this app, or undefined.
+ *
+ * With branching on, each user edits on their own branch, and a commit that
+ * names no branch goes to main. A server from before branching has no status
+ * route, and every app there commits and publishes as before.
+ */
+async function readUserBranch(ctx, input) {
+    try {
+        const status = await ctx.server.getBranchStatus({
+            ...input,
+            ...(ctx.signal ? { signal: ctx.signal } : {}),
+        });
+        return status.mode === "user-branch"
+            ? { branch: status.branch, mainHead: status.mainHead }
+            : undefined;
+    }
+    catch (error) {
+        if (error instanceof ServerHttpError && error.status === 404) {
+            return undefined;
+        }
+        throw error;
+    }
+}
+/** The server's refusal to deploy a commit that is still on a user's own branch. */
+const NOT_SHARED_REFUSAL = "Share your work to the team version before you publish";
+function notShared(applicationId, commitId) {
+    return {
+        kind: "error",
+        applicationId,
+        code: "publish_not_shared",
+        message: `Commit ${commitId} is not the team version, and only the team version can be published. Call publish_app with commitMessage instead of commitId to share the current work and publish it, or ask the user to share it from the Superblocks editor.`,
+        pendingAction: "open_editor",
+    };
+}
+/** The server's refusal to land a branch whose merge from main is not resolved yet. */
+const MERGE_IN_PROGRESS_REFUSAL = "has a merge in progress";
+function landConflict(applicationId) {
+    return {
+        kind: "error",
+        applicationId,
+        code: "publish_conflict",
+        message: "This work conflicts with changes on the team version. Ask the user to resolve the conflict in the Superblocks editor, then publish again.",
+        pendingAction: "open_editor",
+    };
+}
+function landMigrating(applicationId) {
+    return {
+        kind: "error",
+        applicationId,
+        code: "publish_migrating",
+        message: "The app database is still applying this work's migrations. Call publish_app again in a minute.",
+    };
+}
+/**
+ * Shares the caller's branch to main, the editor's first step of a publish,
+ * and returns main's head to deploy. Only main's head can be published.
+ */
+async function landForPublish(ctx, input) {
+    const { apiKey, applicationId, deadlineAtMs } = input;
+    ctx.onProgress?.({
+        message: "Sharing your work to the team version",
+        type: "progress",
+    });
+    const land = (retryFailedMigrations) => ctx.server.landBranch({
+        apiKey,
+        applicationId,
+        retryFailedMigrations,
+        ...(ctx.signal ? { signal: ctx.signal } : {}),
+        timeoutMs: Math.max(1, deadlineAtMs - nowMs(ctx)),
+    });
+    let result;
+    try {
+        // A publish is the user asking again, so a migration that failed before
+        // runs again. The asks that only wait on the migrations do not retry it.
+        result = await land(true);
+        while (result.outcome === "migrating" &&
+            !ctx.signal?.aborted &&
+            nowMs(ctx) + ctx.config.publishPollIntervalMs < deadlineAtMs) {
+            await sleepUntilAbort(ctx.config.publishPollIntervalMs, ctx.signal);
+            result = await land(false);
+        }
+    }
+    catch (error) {
+        if (ctx.signal?.aborted) {
+            return {
+                kind: "error",
+                code: "publish_aborted",
+                message: "Publish was cancelled while sharing your work.",
+            };
+        }
+        // A later ask can get only the time left in the call, too little for the
+        // server to answer. The migrations were still running at the last answer.
+        if (error instanceof ServerTimeoutError &&
+            result?.outcome === "migrating") {
+            return landMigrating(applicationId);
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.includes(MERGE_IN_PROGRESS_REFUSAL)) {
+            return landConflict(applicationId);
+        }
+        // Only the user can agree to delete data, and only the editor shows what
+        // would go, so this publish never sends that agreement itself.
+        if (message.includes(DESTRUCTIVE_MIGRATION_ACK_REQUIRED_MESSAGE)) {
+            return {
+                kind: "error",
+                applicationId,
+                code: "publish_needs_confirmation",
+                message: "Publishing would delete data in the app database. Ask the user to publish from the Superblocks editor, which shows what would be deleted and asks them to confirm.",
+                pendingAction: "open_editor",
+            };
+        }
+        return { kind: "error", applicationId, code: "publish_failed", message };
+    }
+    // Read before the switch narrows it away: a newer server can send an
+    // outcome this build has no case for.
+    const outcome = result.outcome;
+    switch (result.outcome) {
+        case "landed":
+        case "up-to-date":
+            return { kind: "ok", value: result.mainHead };
+        case "conflict":
+            return landConflict(applicationId);
+        case "migrating":
+            return landMigrating(applicationId);
+        case "contended":
+            return {
+                kind: "error",
+                applicationId,
+                code: "publish_busy",
+                message: "The team version kept changing while this publish tried to share the work. Call publish_app again.",
+            };
+        case "migration-failed":
+            return {
+                kind: "error",
+                applicationId,
+                code: "publish_failed",
+                message: `The app database could not apply this work's migrations: ${result.migrationError ?? "unknown error"}`,
+            };
+        default:
+            return {
+                kind: "error",
+                applicationId,
+                code: "publish_failed",
+                message: `Sharing your work to the team version ended with "${outcome}", which this Platform MCP does not know how to finish. Ask the user to publish from the Superblocks editor.`,
+                pendingAction: "open_editor",
+            };
+    }
+}
 async function publishResolvedApp(ctx, args) {
     const { applicationId, input, principal } = args;
     const requestedCommitId = input.commitId?.trim();
@@ -3583,6 +3851,37 @@ async function publishResolvedApp(ctx, args) {
             message: "Publish could not start within the host call budget.",
         };
     }
+    let userBranch;
+    try {
+        userBranch = await readUserBranch(ctx, {
+            apiKey: principal.apiKey,
+            applicationId,
+            timeoutMs: Math.max(1, deadlineAtMs - nowMs(ctx)),
+        });
+    }
+    catch (error) {
+        if (ctx.signal?.aborted) {
+            return {
+                kind: "error",
+                code: "publish_aborted",
+                message: "Publish was cancelled before it started.",
+            };
+        }
+        return {
+            kind: "error",
+            applicationId,
+            code: "publish_failed",
+            message: error instanceof Error ? error.message : String(error),
+        };
+    }
+    // The server only deploys main's head, so a commit still on the user's own
+    // branch has to be shared first.
+    if (userBranch &&
+        requestedCommitId &&
+        userBranch.mainHead !== null &&
+        requestedCommitId !== userBranch.mainHead) {
+        return notShared(applicationId, requestedCommitId);
+    }
     // Deploys address a commit and never fall back to the branch head, while
     // Clark's work sits uncommitted in the live-edit session. Committing here is
     // what the editor's own publish flow does, and without it a caller who has
@@ -3599,10 +3898,13 @@ async function publishResolvedApp(ctx, args) {
         }
         ctx.onProgress?.({ message: "Committing current work", type: "progress" });
         try {
+            // On the user's own branch the server still refuses to commit while a
+            // Superblocks draft waits to be accepted, so an unaccepted draft is
+            // never published.
             const commit = await ctx.server.createCommit({
                 apiKey: principal.apiKey,
                 applicationId,
-                branch: input.branch,
+                branch: userBranch?.branch ?? input.branch,
                 message: input.commitMessage,
                 ...(ctx.signal ? { signal: ctx.signal } : {}),
                 timeoutMs: Math.max(1, deadlineAtMs - nowMs(ctx)),
@@ -3623,6 +3925,17 @@ async function publishResolvedApp(ctx, args) {
                 message: error instanceof Error ? error.message : String(error),
             };
         }
+        if (userBranch) {
+            const landed = await landForPublish(ctx, {
+                apiKey: principal.apiKey,
+                applicationId,
+                deadlineAtMs,
+            });
+            if (landed.kind !== "ok") {
+                return landed;
+            }
+            commitId = landed.value;
+        }
     }
     if (ctx.signal?.aborted) {
         return {
@@ -3732,6 +4045,11 @@ async function publishResolvedApp(ctx, args) {
         }
         if (error instanceof ServerHttpError) {
             ctx.appState.clearPublishInFlight(applicationId, publishClaim);
+            // The server checks this too, for a commit the branch status above
+            // could not rule out.
+            if (error.message.includes(NOT_SHARED_REFUSAL)) {
+                return notShared(applicationId, commitId);
+            }
             return {
                 kind: "error",
                 code: "publish_failed",