@superblocksteam/gateway 2.0.155-next.0

package/dist/capabilities/lifecycle.js

@@ -0,0 +1,2531 @@
+import { randomUUID } from "node:crypto";
+import { readFile, realpath, stat } from "node:fs/promises";
+import path from "node:path";
+import { detectAttachmentArchiveType } from "@superblocksteam/shared";
+import { buildBrowserDriverContract, needsBrowserDriverError, } from "../capture/browser-contract.js";
+import { resolveCaptureMode } from "../capture/mode.js";
+import { EMPTY_EVENT_CURSOR, parseEventCursor } from "../events/cursor.js";
+import { playwrightChromiumPresent } from "../playwright/ensure-chromium.js";
+import { buildEmbedShellPreviewUrl, buildOpenablePreviewUrls, } from "../preview/viewer-url.js";
+import { ServerHttpError } from "../server/client.js";
+import { IdentityUnavailableError } from "../server/identity-reads.js";
+import { buildImportPrompt } from "./import-prompt.js";
+import { readPersistedProgress } from "./persisted-progress.js";
+import { buildStatusOf } from "./types.js";
+import { IMPORT_ZIP_MAX_BYTES } from "./types.js";
+export { IMPORT_ZIP_MAX_BYTES } from "./types.js";
+const APPLICATION_CONTEXT_REQUIRED = "No applicationId provided and no recent application is available. Call start_app first or pass applicationId.";
+/**
+ * Every app the gateway starts is a code-mode app (`createUsingReact`), which
+ * the UI serves from `/code-mode` — the legacy `/applications/:id/edit` route
+ * does not open it.
+ */
+function editUrl(config, applicationId) {
+    return `${config.uiBaseUrl.replace(/\/$/, "")}/code-mode/applications/edit/${applicationId}`;
+}
+function uiOrigin(config) {
+    return config.uiBaseUrl.replace(/\/$/, "");
+}
+async function gatewayChromiumIsPresent(ctx) {
+    if (typeof ctx.config.gatewayChromiumPresent === "boolean") {
+        return ctx.config.gatewayChromiumPresent;
+    }
+    return playwrightChromiumPresent();
+}
+async function captureModeOf(ctx) {
+    return resolveCaptureMode({
+        gatewayChromium: await gatewayChromiumIsPresent(ctx),
+        hostMcpConfigured: ctx.config.captureHostMcp,
+    });
+}
+function libraryCaptureInput(ctx, applicationId) {
+    const context = ctx.sessionPeer.libraryBrowserContext?.(applicationId);
+    if (!context) {
+        return undefined;
+    }
+    const auth = context.initData.devServerAuthorization;
+    if (!auth) {
+        console.error("gateway live canvas skipped: missing_dev_server_authorization", { applicationId });
+        return undefined;
+    }
+    return {
+        bootstrapData: {
+            accessToken: context.bootstrapData.accessToken,
+            agents: context.bootstrapData.agents ?? [],
+            ...(context.bootstrapData.agentUrls
+                ? { agentUrls: context.bootstrapData.agentUrls }
+                : {}),
+            appId: context.bootstrapData.appId,
+            ...(context.bootstrapData.featureFlags
+                ? { featureFlags: context.bootstrapData.featureFlags }
+                : {}),
+            ...(context.bootstrapData.orgId
+                ? { orgId: context.bootstrapData.orgId }
+                : {}),
+            ...(context.bootstrapData.profiles
+                ? { profiles: context.bootstrapData.profiles }
+                : {}),
+            token: context.bootstrapData.token,
+            ...(context.bootstrapData.userEmail
+                ? { userEmail: context.bootstrapData.userEmail }
+                : {}),
+            userId: context.bootstrapData.userId,
+            ...(context.bootstrapData.windowOriginUrl
+                ? { windowOriginUrl: context.bootstrapData.windowOriginUrl }
+                : {}),
+        },
+        iframeBaseUrl: context.iframeBaseUrl,
+        initData: {
+            appId: context.initData.appId,
+            devServerAuthorization: auth,
+            peerId: context.initData.peerId,
+            ...(context.initData.userId ? { userId: context.initData.userId } : {}),
+            ...(context.initData.windowOriginUrl
+                ? { windowOriginUrl: context.initData.windowOriginUrl }
+                : {}),
+        },
+    };
+}
+/**
+ * Live-library capture input for get_app: reuse a held session, or re-open
+ * live-edit when the in-memory hold is empty (MCP respawn / tool timeout).
+ */
+async function ensureLibraryCaptureInput(ctx, principal, applicationId, branch) {
+    const existing = libraryCaptureInput(ctx, applicationId);
+    if (existing) {
+        return existing;
+    }
+    if (!ctx.sessionPeer.holdLiveEdit) {
+        console.error("gateway live canvas skipped: hold_live_edit_unavailable", {
+            applicationId,
+        });
+        return undefined;
+    }
+    if (!(await gatewayChromiumIsPresent(ctx))) {
+        console.error("gateway live canvas skipped: chromium_absent_no_rehold", {
+            applicationId,
+        });
+        return undefined;
+    }
+    try {
+        const session = await openLiveEdit(ctx, {
+            apiKey: principal.apiKey,
+            applicationId,
+            branch,
+            organizationId: principal.organizationId,
+        });
+        const sessionToken = await ctx.server.issueScopedToken({
+            apiKey: principal.apiKey,
+            applicationId,
+        });
+        await ctx.sessionPeer.holdLiveEdit({
+            apiKey: principal.apiKey,
+            applicationId,
+            branch,
+            keepalive: async () => {
+                await ctx.server.connectLiveEdit({
+                    apiKey: principal.apiKey,
+                    applicationId,
+                    branch,
+                });
+            },
+            liveEditUrl: session.liveEditUrl,
+            organizationId: principal.organizationId,
+            sessionToken,
+            userId: principal.userId,
+        });
+    }
+    catch (error) {
+        console.error("gateway live canvas skipped: rehold_failed", {
+            applicationId,
+            message: error instanceof Error ? error.message : String(error),
+        });
+        return undefined;
+    }
+    const live = libraryCaptureInput(ctx, applicationId);
+    if (!live) {
+        console.error("gateway live canvas skipped: context_incomplete_after_rehold", { applicationId });
+    }
+    return live;
+}
+async function captureLiveLibraryIfNeeded(ctx, applicationId, live) {
+    if (!live) {
+        return {};
+    }
+    if (!ctx.captureLibraryScreenshot) {
+        console.error("gateway live canvas skipped: no_capture_function", {
+            applicationId,
+        });
+        return { needsBrowserDriver: true };
+    }
+    if (!(await gatewayChromiumIsPresent(ctx))) {
+        console.error("gateway live canvas skipped: chromium_absent", {
+            applicationId,
+        });
+        return {
+            needsBrowserDriver: true,
+        };
+    }
+    console.error("Capturing a live canvas screenshot", { applicationId });
+    ctx.onProgress?.({
+        message: "Capturing a live canvas screenshot",
+        type: "progress",
+    });
+    try {
+        const shot = await ctx.captureLibraryScreenshot(live);
+        return { screenshotBase64: shot?.dataBase64 };
+    }
+    catch (error) {
+        console.warn("gateway library screenshot threw; continuing with URLs", {
+            message: error instanceof Error ? error.message : String(error),
+        });
+        return { needsBrowserDriver: true };
+    }
+}
+async function browserContractFor(ctx, applicationId) {
+    return buildBrowserDriverContract({
+        captureMode: await captureModeOf(ctx),
+        editUrl: editUrl(ctx.config, applicationId),
+        isolated: ctx.config.captureHostIsolated,
+        uiOrigin: uiOrigin(ctx.config),
+    });
+}
+async function withBrowser(ctx, applicationId, value) {
+    return {
+        ...value,
+        browser: await browserContractFor(ctx, applicationId),
+    };
+}
+/**
+ * Where the deployed app is served; `/deployments` is an API path, not a page.
+ * Needs the same `/code-mode` prefix as {@link editUrl}: the bare
+ * `/applications/:id` route is proxied to the legacy SPA, which 404s.
+ */
+function publishUrl(config, applicationId) {
+    return `${config.uiBaseUrl.replace(/\/$/, "")}/code-mode/applications/${applicationId}`;
+}
+/**
+ * Where a built, undeployed commit can be opened — what the editor's Preview
+ * button hands the browser. Distinct from {@link publishUrl}: this serves a
+ * specific commit and needs nothing deployed.
+ */
+function previewUrl(config, applicationId, commitId) {
+    return `${config.uiBaseUrl.replace(/\/$/, "")}/code-mode/applications/preview/${applicationId}?commitId=${encodeURIComponent(commitId)}`;
+}
+function defaultAppName(prompt) {
+    const trimmed = prompt.trim().replace(/\s+/g, " ");
+    if (!trimmed) {
+        return "Untitled Gateway App";
+    }
+    return trimmed.length > 80 ? `${trimmed.slice(0, 77)}...` : trimmed;
+}
+/**
+ * Resolves the Superblocks user behind the CLI session this Gateway was
+ * started with.
+ *
+ * Identity is the already-logged-in Superblocks CLI user. A rejection here
+ * means that personal API key is bad, not that the user needs a second login,
+ * so it surfaces as an error rather than an interactive-auth elicitation.
+ */
+async function ensurePrincipal(ctx) {
+    const { principal } = ctx;
+    // MCP already has the CLI session key. Looking it up again would spend a
+    // second round trip on `/users/me`, the slowest endpoint the Superblocks
+    // API has, when the principal is already resolved (ENG-5806).
+    if (principal.organizationId && principal.userId) {
+        return {
+            kind: "ok",
+            value: {
+                ...principal,
+                organizationId: principal.organizationId,
+                userId: principal.userId,
+            },
+        };
+    }
+    let validated;
+    try {
+        validated = await ctx.server.validateApiKey(principal.apiKey);
+    }
+    catch (error) {
+        // A 5xx says nothing about the credential. Reporting it as an auth problem
+        // would send the user off to re-link an account that is perfectly fine.
+        if (error instanceof ServerHttpError && error.status >= 500) {
+            return {
+                kind: "error",
+                code: "downstream_unavailable",
+                message: `The Superblocks API could not confirm who this caller is: ${error.message}. This is usually transient — try again.`,
+            };
+        }
+        // The identity endpoint stopped answering. Same class of outage as the 5xx
+        // above, and it must not fall through to `capability_failed`: that told the
+        // caller its progress poll had failed on an identity route it never asked
+        // about, which reads as a broken gateway rather than a slow dependency.
+        if (error instanceof IdentityUnavailableError) {
+            return {
+                kind: "error",
+                code: "downstream_unavailable",
+                message: error.message,
+            };
+        }
+        throw error;
+    }
+    if (!validated) {
+        return {
+            kind: "error",
+            code: "downstream_unauthorized",
+            message: "The Superblocks API rejected the credential issued for this caller.",
+        };
+    }
+    return {
+        kind: "ok",
+        value: {
+            ...principal,
+            email: validated.email,
+            organizationId: validated.organizationId,
+            userId: validated.userId,
+        },
+    };
+}
+/**
+ * Names a freshly created app the way the editor does: create it under a
+ * placeholder, then let Clark propose something readable.
+ *
+ * Best-effort by design. The AI endpoint is behind an org kill switch and is a
+ * network call like any other; a working application is not worth discarding
+ * over a cosmetic name.
+ */
+async function nameWithClark(ctx, input) {
+    try {
+        const name = await ctx.server.generateAppName({
+            apiKey: input.apiKey,
+            applicationId: input.applicationId,
+            prompt: input.prompt,
+        });
+        await ctx.server.renameApplication({
+            apiKey: input.apiKey,
+            applicationId: input.applicationId,
+            name,
+        });
+        return name;
+    }
+    catch (error) {
+        console.warn("gateway could not name the application with Superblocks", error);
+        return undefined;
+    }
+}
+/**
+ * The name the app ends up with: whatever the caller asked for, or Clark's
+ * suggestion. Asked for only after the prompt is on its way so Clark starts
+ * building immediately.
+ */
+async function finalAppName(ctx, input) {
+    if (input.explicitName) {
+        return input.name;
+    }
+    ctx.onProgress?.({ message: "Naming application", type: "progress" });
+    return ((await nameWithClark(ctx, {
+        apiKey: input.apiKey,
+        applicationId: input.applicationId,
+        prompt: input.prompt,
+    })) ?? input.name);
+}
+async function elicitStepUp(ctx, idempotencyKey, applicationId) {
+    if (!ctx.config.captureHostMcp) {
+        return needsBrowserDriverError();
+    }
+    const existing = await ctx.turns.getByIdempotencyKey(idempotencyKey);
+    if (existing?.status === "ready") {
+        return {
+            kind: "error",
+            code: "reinvoke_required",
+            message: "Step-up authentication completed. Re-invoke the capability to continue.",
+        };
+    }
+    const browser = await browserContractFor(ctx, applicationId);
+    if (existing?.status === "pending") {
+        return {
+            kind: "auth_required",
+            elicitation: {
+                authUrl: existing.authUrl,
+                browser,
+                reason: existing.reason,
+                turnId: existing.turnId,
+            },
+        };
+    }
+    const turnId = randomUUID();
+    const callbackToken = randomUUID();
+    const authUrl = uiOrigin(ctx.config);
+    const turn = await ctx.turns.create({
+        authUrl,
+        callbackToken,
+        idempotencyKey,
+        reason: "idp_step_up",
+        ttlMs: ctx.config.turnTtlMs,
+        turnId,
+    });
+    ctx.onProgress?.({
+        message: `Authorize in browser: ${turn.authUrl}`,
+        type: "auth_required",
+    });
+    return {
+        kind: "auth_required",
+        elicitation: {
+            authUrl: turn.authUrl,
+            browser,
+            reason: "idp_step_up",
+            turnId: turn.turnId,
+        },
+    };
+}
+async function resolveApplicationId(ctx, principal, applicationId) {
+    if (applicationId?.trim()) {
+        return { kind: "ok", value: applicationId.trim() };
+    }
+    const recent = await ctx.recentApps.get({
+        organizationId: principal.organizationId,
+        userId: principal.userId,
+    });
+    if (!recent?.applicationId) {
+        return {
+            kind: "error",
+            code: "application_context_required",
+            message: APPLICATION_CONTEXT_REQUIRED,
+        };
+    }
+    return { kind: "ok", value: recent.applicationId };
+}
+async function rememberApplication(ctx, principal, applicationId) {
+    await ctx.recentApps.set({
+        applicationId,
+        organizationId: principal.organizationId,
+        userId: principal.userId,
+    });
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Sleeps between polls, and gives up the moment the caller does.
+ *
+ * A plain sleep here would have a cancelled call sit out the rest of the gap
+ * before anything looked at the signal, holding a timer on behalf of a
+ * request that nobody is waiting for any more. Both the timer and the
+ * listener are released on the way out, whichever of the two arrives first.
+ */
+function sleepUntilAbort(ms, signal) {
+    if (signal === undefined) {
+        return sleep(ms);
+    }
+    if (signal.aborted) {
+        return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+        const done = () => {
+            clearTimeout(timer);
+            signal.removeEventListener("abort", done);
+            resolve();
+        };
+        const timer = setTimeout(done, ms);
+        signal.addEventListener("abort", done, { once: true });
+    });
+}
+async function waitForDeployLive(ctx, input) {
+    const deadline = Date.now() + ctx.config.publishWaitTimeoutMs;
+    let lastStatus = "queued";
+    while (Date.now() < deadline) {
+        if (input.signal?.aborted) {
+            return {
+                kind: "error",
+                code: "publish_aborted",
+                message: "Publish wait was cancelled.",
+            };
+        }
+        let status;
+        try {
+            status = await ctx.server.getDeployStatus({
+                apiKey: input.apiKey,
+                applicationId: input.applicationId,
+                commitId: input.commitId,
+            });
+        }
+        catch (error) {
+            return {
+                kind: "error",
+                code: "publish_failed",
+                message: error instanceof Error ? error.message : String(error),
+            };
+        }
+        lastStatus = status.status;
+        if (status.status === "DEPLOYED") {
+            ctx.onProgress?.({ message: "App is live", type: "progress" });
+            return { kind: "ok", value: {} };
+        }
+        if (status.status === "FAILED") {
+            return {
+                kind: "error",
+                code: "publish_failed",
+                message: status.error ?? "The Superblocks API could not deploy the app.",
+            };
+        }
+        if (status.status === "AWAITING_ACK") {
+            return {
+                kind: "error",
+                code: "publish_needs_acknowledgement",
+                message: `${status.error ?? "Policy checks passed with advisory findings."} Publishing is on hold until they are reviewed in Superblocks, or until this is published again with the findings acknowledged.`,
+            };
+        }
+        // "none" is not evidence of a successful deploy: the queue row may be
+        // missing, cleaned up after failure, or the deploy path may be unavailable.
+        // Keep waiting until DEPLOYED, FAILED, AWAITING_ACK, or timeout.
+        ctx.onProgress?.({
+            message: `Waiting for deploy (${status.status})…`,
+            type: "progress",
+        });
+        await sleep(ctx.config.publishPollIntervalMs);
+    }
+    return {
+        kind: "error",
+        code: "publish_timeout",
+        message: `Timed out waiting for the app to go live (last status: ${lastStatus}). Open ${publishUrl(ctx.config, input.applicationId)} to check progress.`,
+    };
+}
+/**
+ * Both ways to look at a finished app, in the summary rather than only in the
+ * server instructions — clients follow a tool's own output more closely, and a
+ * user who is never offered the preview deploys to their whole organization to
+ * see what they built.
+ */
+const NEXT_STEPS = "Preview it with preview_app, or publish it with publish_app";
+/**
+ * Closing progress line, so the client's last word says whether the app is
+ * committed and openable or still needs something from Claude.
+ */
+function turnSummary(turn) {
+    if (turn.generationStatus === "needs_decision") {
+        return "Superblocks needs a decision — call edit_app with the answer";
+    }
+    if (turn.generationStatus === "no_changes") {
+        return "The Superblocks job ended without building anything — read its reply";
+    }
+    if (turn.generationStatus === "detached") {
+        return "Superblocks is still working, but only the editor can show it — open the edit URL";
+    }
+    if (turn.generationStatus === "live_edit_terminated") {
+        return "The Superblocks live-edit session terminated before anything was built — send the prompt again with edit_app";
+    }
+    if (turn.checkpointCommitId) {
+        return `Application ready — checkpoint saved. ${NEXT_STEPS}`;
+    }
+    if (turn.viewStatus === "ready") {
+        return `Application ready. ${NEXT_STEPS}`;
+    }
+    return "Superblocks finished generating; the app may still be building in the editor";
+}
+/**
+ * Combines local turn activity with durable Redis lines, oldest-first, without
+ * repeating the same message when both sources saw it.
+ */
+function mergeActivity(live, persisted) {
+    const seen = new Set();
+    const merged = [];
+    for (const line of [...persisted, ...live]) {
+        if (!line || seen.has(line)) {
+            continue;
+        }
+        seen.add(line);
+        merged.push(line);
+    }
+    return merged;
+}
+async function promptInput(ctx, input) {
+    return {
+        apiKey: ctx.principal.apiKey,
+        applicationId: input.applicationId,
+        ...(input.attachments ? { attachments: input.attachments } : {}),
+        ...(input.importSource ? { importSource: input.importSource } : {}),
+        keepalive: async () => {
+            await ctx.server.connectLiveEdit({
+                apiKey: ctx.principal.apiKey,
+                applicationId: input.applicationId,
+                branch: input.branch,
+            });
+        },
+        ...(input.liveEditId ? { liveEditId: input.liveEditId } : {}),
+        liveEditUrl: input.liveEditUrl,
+        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
+        // directly keeps the resume pointer honest: a session that moved is a
+        // different stream, and a caller polling by application id has to be sent
+        // to the new one.
+        resolveLiveEdit: () => openLiveEdit(ctx, {
+            apiKey: ctx.principal.apiKey,
+            applicationId: input.applicationId,
+            ...(input.branch ? { branch: input.branch } : {}),
+            organizationId: input.organizationId,
+        }),
+        onProgress: (message) => {
+            ctx.onProgress?.({ message, type: "progress" });
+        },
+        organizationId: input.organizationId,
+        ...(input.planContext ? { planContext: input.planContext } : {}),
+        prompt: input.prompt,
+        ...(input.responseMetadata
+            ? { responseMetadata: input.responseMetadata }
+            : {}),
+        sessionToken: await ctx.server.issueScopedToken({
+            apiKey: ctx.principal.apiKey,
+            applicationId: input.applicationId,
+        }),
+        userId: input.userId,
+    };
+}
+/**
+ * Opens the live-edit session a prompt will run on, and records which one it
+ * is against the application.
+ *
+ * The pointer is what makes resume reachable at all. A caller polling after a
+ * restart, from another replica, or from a channel that never started the
+ * build has an application id and nothing else; the event streams are keyed by
+ * live edit. Without this, every such caller finds no stream to read and falls
+ * back to "unknown" forever.
+ *
+ * Written before the prompt rather than after it, because the events this
+ * points at start arriving as soon as the turn does. A failure to record it is
+ * swallowed: it costs resume, and failing the prompt over it would trade a
+ * degraded poll for no build at all.
+ */
+async function openLiveEdit(ctx, input) {
+    const session = await ctx.server.connectLiveEdit({
+        apiKey: input.apiKey,
+        applicationId: input.applicationId,
+        branch: input.branch,
+    });
+    try {
+        await ctx.progressCursors?.setLiveEditId({
+            applicationId: input.applicationId,
+            liveEditId: session.liveEditId,
+            organizationId: input.organizationId,
+        });
+    }
+    catch (error) {
+        console.warn("gateway could not record the live edit for resume", {
+            message: error instanceof Error ? error.message : String(error),
+        });
+    }
+    return session;
+}
+/**
+ * Hands the prompt to Clark and returns as soon as it is accepted, leaving the
+ * turn running on the held session for `check_app_progress` to follow.
+ */
+async function startClarkPrompt(ctx, input) {
+    const started = await ctx.sessionPeer.startPrompt(await promptInput(ctx, input));
+    if (started.status === "auth_required") {
+        return elicitStepUp(ctx, `stepup:${input.idempotencyKey}`, input.applicationId);
+    }
+    if (input.mode === "BUILD") {
+        ctx.sessionPeer.markBuildMode?.(input.applicationId);
+    }
+    return {
+        kind: "ok",
+        value: {
+            activity: started.activity,
+            // Carried through because the peer may have followed the session to a
+            // host this call never named, and the result has to send the caller to
+            // the live edit the turn is actually on.
+            ...(started.liveEditId ? { liveEditId: started.liveEditId } : {}),
+        },
+    };
+}
+async function forwardClarkPrompt(ctx, input) {
+    const forward = await ctx.sessionPeer.forwardPrompt(await promptInput(ctx, input));
+    if (forward.status === "auth_required") {
+        return elicitStepUp(ctx, `stepup:${input.idempotencyKey}`, input.applicationId);
+    }
+    if (input.mode === "BUILD") {
+        ctx.sessionPeer.markBuildMode?.(input.applicationId);
+    }
+    if (forward.generationStatus === "timeout") {
+        return {
+            kind: "error",
+            code: "superblocks_turn_timeout",
+            message: `Superblocks did not finish within the turn budget.${forward.reply ? ` Partial reply: ${forward.reply.slice(0, 500)}` : ""} Continue in the editor at ${editUrl(ctx.config, input.applicationId)}.`,
+            ...retryIfReplayable(input.attachments),
+        };
+    }
+    return {
+        kind: "ok",
+        value: {
+            ...(forward.checkpointCommitId
+                ? { checkpointCommitId: forward.checkpointCommitId }
+                : {}),
+            reply: forward.reply,
+            ...(forward.decision ? { decision: forward.decision } : {}),
+            generationStatus: forward.generationStatus,
+            ...(forward.liveEditId ? { liveEditId: forward.liveEditId } : {}),
+            ...(forward.recentRuns && forward.recentRuns.length > 0
+                ? { recentRuns: forward.recentRuns }
+                : {}),
+            viewStatus: forward.viewStatus,
+        },
+    };
+}
+/**
+ * Waits between create attempts after a dev-env rejection. Short enough that
+ * `start_app` still returns in the seconds its callers expect.
+ */
+const DEV_ENV_RETRY_DELAYS_MS = [400, 1200];
+/**
+ * Whether a failed create is worth repeating.
+ *
+ * The server gates code-mode apps on a LaunchDarkly flag. A server that can tell
+ * an unreadable flag from one that is off answers 503 and means "ask again". An
+ * older one answers 400 "Dev Env is not enabled" for both, because the SDK hands
+ * back the gate's `false` default whenever its stream is down without saying so —
+ * which locally, where the stream drops constantly, greeted most first prompts.
+ */
+function isRetryableCreateFailure(error) {
+    if (!(error instanceof ServerHttpError)) {
+        return false;
+    }
+    return (error.status === 503 ||
+        (error.status === 400 && /dev env is not enabled/i.test(error.message)));
+}
+/**
+ * Creates the application, absorbing a dev-env rejection that is really a
+ * momentarily unreadable feature flag. Retrying here keeps the flap away from
+ * the user; only a rejection that outlives every attempt reaches them, and it
+ * says the flag read failed rather than blaming their account.
+ */
+async function createApplicationForPrompt(ctx, args) {
+    for (let attempt = 0; attempt <= DEV_ENV_RETRY_DELAYS_MS.length; attempt += 1) {
+        try {
+            return { kind: "ok", value: await ctx.server.createApplication(args) };
+        }
+        catch (error) {
+            if (!isRetryableCreateFailure(error)) {
+                throw error;
+            }
+            const delayMs = DEV_ENV_RETRY_DELAYS_MS[attempt];
+            if (delayMs !== undefined) {
+                await sleep(delayMs);
+            }
+        }
+    }
+    return {
+        kind: "error",
+        code: "dev_env_unavailable",
+        message: `Superblocks refused to create a code-mode app: it read the dev-env feature flag as off for this organization. The gateway already retried ${DEV_ENV_RETRY_DELAYS_MS.length + 1} times over a few seconds, so this is more than a momentary flag-store blip. What failed is the flag read, not the user's account: do not tell the user to contact support or an organization admin, and do not say their account lacks access. Say the build could not be started, that one more attempt is worth trying, and that if it persists the Superblocks deployment's flag delivery needs looking at.`,
+    };
+}
+/**
+ * Names the application a failed call was working on.
+ *
+ * Every failure past the point where an application exists has to carry its id,
+ * because that id is the caller's only handle on a resource the call already
+ * persisted. `start_app` creates the row before it reaches live edit, so a
+ * connect that times out leaves an app the caller owns and never saw; and every
+ * app-scoped entry point may have resolved the id from the recent-app default
+ * rather than from its arguments, so the failure is the one place a caller can
+ * learn which app it actually drove.
+ */
+function namingApplication(applicationId, result) {
+    return result.kind === "error" ? { ...result, applicationId } : result;
+}
+/**
+ * Names the application `start_app` or `import_app` created, and says on the
+ * way out that it is still there.
+ *
+ * These two are the entry points that persist an application before the build
+ * can start, so their failures are the ones that leave a resource behind. Until
+ * every caller reads `applicationId` and retries rather than starting over,
+ * this line is how an operator finds the applications they abandoned.
+ */
+function namingCreatedApplication(applicationId, capability, result) {
+    if (result.kind === "error") {
+        console.warn("gateway left an application behind", {
+            applicationId,
+            capability,
+            code: result.code,
+        });
+    }
+    return namingApplication(applicationId, result);
+}
+/**
+ * The recovery to advertise when the machinery around a turn fails: `edit_app`
+ * with the same prompt, which is what `retry_build` means.
+ *
+ * Only for a prompt `edit_app` could actually replay. A prompt carrying
+ * attachments is not one: `edit_app` has no way to resupply an attachment, so
+ * an import's migration prompt would reach Superblocks describing an archive it
+ * cannot see. Advertising a recovery that cannot finish is worse than
+ * advertising none, so the import path gets `applicationId` and no hint.
+ * TODO(ENG-5917): let `import_app` resume into an application it already
+ * created, and give the import path a recovery of its own.
+ */
+function retryIfReplayable(attachments) {
+    return attachments && attachments.length > 0
+        ? undefined
+        : { pendingAction: "retry_build" };
+}
+/**
+ * A live edit that would not open. The app itself is intact and Clark never ran,
+ * so where the prompt can be replayed the caller's way out is to send it again
+ * rather than start over on a second app.
+ */
+function liveEditUnavailable(error, attachments) {
+    return {
+        kind: "error",
+        code: "live_edit_unavailable",
+        message: error instanceof Error ? error.message : String(error),
+        ...retryIfReplayable(attachments),
+    };
+}
+/**
+ * Tell the peer that a turn for this application died before Superblocks ever
+ * saw it.
+ *
+ * Nothing else holds that: no turn was ever started, so without this the gateway
+ * forgets the attempt entirely and every later read answers "nothing in flight"
+ * - `check_app_progress` reports `unknown` while `get_app` commits and previews
+ * the untouched starter template as though a build were running (ENG-5808).
+ *
+ * Deliberately not called when the prompt itself failed on an open session. The
+ * prompt may well have reached Superblocks and be running now, and an
+ * unanswered acknowledgement does not say which; telling the caller "nothing is
+ * running, send it again" would be the same overclaim this fixes, and acting on
+ * it can build the app twice.
+ */
+function rememberFailedStart(ctx, input) {
+    if (refusedCaller(input.error)) {
+        return;
+    }
+    const cause = input.error instanceof Error ? input.error.message : String(input.error);
+    try {
+        ctx.sessionPeer.recordFailedStart?.({
+            applicationId: input.applicationId,
+            organizationId: input.principal.organizationId,
+            // Reaches the caller as the dead start's reply on its next poll, so it
+            // has to stand on its own there rather than lean on this call's error.
+            reason: `The Superblocks live-edit session for application ${input.applicationId} never opened, so the prompt never reached Superblocks and nothing was built. Nothing is running for that application; send the same instruction again to retry it. (${cause})`,
+            userId: input.principal.userId,
+        });
+    }
+    catch (error) {
+        // Swallowed: the failure the caller is actually being told about must not be
+        // replaced by a failure to write it down. Logged with the principal it was
+        // for, because the symptom is the one this record exists to prevent.
+        console.warn("gateway failed-start record on the session peer failed", {
+            applicationId: input.applicationId,
+            message: error instanceof Error ? error.message : String(error),
+            organizationId: input.principal.organizationId,
+            userId: input.principal.userId,
+        });
+    }
+}
+/**
+ * Whether Superblocks turned this caller away rather than failing to answer.
+ *
+ * A refusal is about the caller, not about the application. `connectLiveEdit`
+ * is where Superblocks authorizes them and it authorizes per application, while
+ * `resolveApplicationId` takes whatever application id it is handed - so
+ * recording a refusal would let anyone naming an app they cannot open author the
+ * status read by the people who can, and occupy a slot in a bounded store by
+ * naming one.
+ *
+ * 404 counts. Superblocks' existence checks are organization scoped, so an
+ * application belonging to another tenant reads as missing rather than as
+ * forbidden - and a caller who cannot see an app has no business authoring a
+ * status for it. A genuinely missing app is the same answer for the same reason.
+ */
+function refusedCaller(error) {
+    return (error instanceof ServerHttpError &&
+        (error.status === 401 || error.status === 403 || error.status === 404));
+}
+/**
+ * The first prompt on an application that was just created, for both
+ * `start_app` and `import_app`: connect a live-edit session, hand Clark the
+ * prompt, and shape the turn it ran.
+ */
+async function promptNewApplication(ctx, args) {
+    const { applicationId, input, principal, prompt } = args;
+    ctx.onProgress?.({
+        message: "Connecting live-edit session",
+        type: "progress",
+    });
+    let session;
+    try {
+        session = await openLiveEdit(ctx, {
+            apiKey: principal.apiKey,
+            applicationId,
+            branch: input.branch,
+            organizationId: principal.organizationId,
+        });
+    }
+    catch (error) {
+        rememberFailedStart(ctx, { applicationId, error, principal });
+        return liveEditUnavailable(error, args.attachments);
+    }
+    ctx.onProgress?.({
+        message: args.importSource
+            ? "Forwarding import prompt to Superblocks"
+            : "Forwarding prompt to Superblocks",
+        type: "progress",
+    });
+    const promptArgs = {
+        applicationId,
+        ...(args.attachments ? { attachments: args.attachments } : {}),
+        branch: input.branch,
+        idempotencyKey: input.idempotencyKey,
+        ...(args.importSource ? { importSource: args.importSource } : {}),
+        liveEditId: session.liveEditId,
+        liveEditUrl: session.liveEditUrl,
+        mode: input.mode ?? "PLAN",
+        organizationId: principal.organizationId,
+        prompt,
+        userId: principal.userId,
+    };
+    const named = () => finalAppName(ctx, {
+        apiKey: principal.apiKey,
+        applicationId,
+        explicitName: args.explicitName,
+        name: args.name,
+        prompt,
+    });
+    if (input.wait === "ack") {
+        const started = await startClarkPrompt(ctx, promptArgs);
+        if (started.kind !== "ok") {
+            return started;
+        }
+        return {
+            kind: "ok",
+            value: await withBrowser(ctx, applicationId, {
+                activity: started.value.activity,
+                applicationId,
+                editUrl: editUrl(ctx.config, applicationId),
+                liveEditId: started.value.liveEditId ?? session.liveEditId,
+                mode: promptArgs.mode,
+                name: await named(),
+                status: "building",
+            }),
+        };
+    }
+    const forward = await forwardClarkPrompt(ctx, promptArgs);
+    if (forward.kind !== "ok") {
+        return forward;
+    }
+    const result = {
+        applicationId,
+        ...(forward.value.checkpointCommitId
+            ? { checkpointCommitId: forward.value.checkpointCommitId }
+            : {}),
+        reply: forward.value.reply,
+        ...(forward.value.decision ? { decision: forward.value.decision } : {}),
+        editUrl: editUrl(ctx.config, applicationId),
+        generationStatus: forward.value.generationStatus,
+        liveEditId: forward.value.liveEditId ?? session.liveEditId,
+        mode: promptArgs.mode,
+        name: await named(),
+        ...(forward.value.recentRuns && forward.value.recentRuns.length > 0
+            ? { recentRuns: forward.value.recentRuns }
+            : {}),
+        status: buildStatusOf(forward.value.generationStatus),
+        viewStatus: forward.value.viewStatus,
+    };
+    ctx.onProgress?.({
+        message: turnSummary(forward.value),
+        type: "completed",
+    });
+    return { kind: "ok", value: await withBrowser(ctx, applicationId, result) };
+}
+export async function startApp(ctx, input) {
+    const principalResult = await ensurePrincipal(ctx);
+    if (principalResult.kind !== "ok") {
+        return principalResult;
+    }
+    const principal = principalResult.value;
+    const explicitName = input.name?.trim();
+    const name = explicitName || defaultAppName(input.prompt);
+    ctx.onProgress?.({ message: "Creating application", type: "progress" });
+    const created = await createApplicationForPrompt(ctx, {
+        apiKey: principal.apiKey,
+        name,
+        organizationId: principal.organizationId,
+    });
+    if (created.kind !== "ok") {
+        return created;
+    }
+    const app = created.value;
+    // The row is persisted from here on, so it is this caller's most recent app
+    // whether or not the turn ever runs. Waiting for the turn to be accepted left
+    // the recent-app default pointing at the previous app, and a caller retrying
+    // after a failure drove that one instead of the app it had just created.
+    await rememberApplication(ctx, principal, app.id);
+    return namingCreatedApplication(app.id, "start_app", await promptNewApplication(ctx, {
+        applicationId: app.id,
+        explicitName,
+        input,
+        name,
+        principal,
+        prompt: input.prompt,
+    }));
+}
+/** Resolves symlinks where possible so containment is checked on real paths. */
+async function realPath(candidate) {
+    try {
+        return await realpath(candidate);
+    }
+    catch {
+        return path.resolve(candidate);
+    }
+}
+/**
+ * Reads a candidate path only when it truly sits in one of the configured
+ * search directories.
+ *
+ * The caller is remote and holds nothing but a token, so a path it names must
+ * never widen what the gateway will read. Comparison happens after resolving
+ * symlinks on both sides: a link planted in a search directory is otherwise
+ * enough to walk straight back out of it, and on macOS the directories
+ * themselves (`/tmp`) are often links. The resolved path is also what gets
+ * read, so re-pointing the link afterwards changes nothing.
+ */
+async function readWithinSearchDirs(candidate, searchDirs) {
+    const file = await realPath(candidate);
+    for (const dir of searchDirs) {
+        const root = await realPath(dir);
+        // The separator matters: `~/downloads-evil` is not inside `~/downloads`.
+        if (file !== root && !file.startsWith(root + path.sep)) {
+            continue;
+        }
+        try {
+            const info = await stat(file);
+            if (!info.isFile()) {
+                return undefined;
+            }
+            // Sizing from the file rather than from bytes already read keeps a caller
+            // from spending the gateway's heap on a file it merely named.
+            if (info.size > IMPORT_ZIP_MAX_BYTES) {
+                return { oversizeBytes: info.size };
+            }
+            return { bytes: await readFile(file) };
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}
+/**
+ * Reads the archive by name from one of the configured search directories.
+ *
+ * Only the file name of `zipPath` is used. The directory part is thrown away
+ * before joining, so neither a sandbox path the model quotes nor a `../` in it
+ * can reach a file the operator did not put in one of these folders.
+ */
+async function readFromSearchDirs(fileName, searchDirs) {
+    for (const dir of searchDirs) {
+        const found = await readWithinSearchDirs(path.join(dir, fileName), [dir]);
+        if (found) {
+            return found;
+        }
+    }
+    return undefined;
+}
+function tooLargeError(size) {
+    return {
+        kind: "error",
+        code: "import_zip_too_large",
+        message: `Archive is ${size} bytes; the gateway import limit is ${IMPORT_ZIP_MAX_BYTES} bytes (1 MB). Larger archives almost certainly include node_modules or other install artifacts — re-export without those; dependencies are installed on or after import.`,
+    };
+}
+/**
+ * Reads the ZIP (or tarball) from a host path or base64 payload and enforces
+ * the gateway's 1 MB cap before any Superblocks API call.
+ */
+async function resolveImportArchive(input, searchDirs) {
+    const hasPath = Boolean(input.zipPath?.trim());
+    const hasBase64 = Boolean(input.zipBase64?.trim());
+    if (hasPath === hasBase64) {
+        return {
+            kind: "error",
+            code: "import_zip_required",
+            message: "Provide exactly one of zipPath (a path or file name on the gateway host) or zipBase64.",
+        };
+    }
+    let bytes;
+    let fileName;
+    if (hasPath) {
+        const zipPath = input.zipPath.trim();
+        fileName = path.basename(zipPath);
+        let read;
+        if (path.isAbsolute(zipPath)) {
+            // A path the caller can see is often one this host cannot — a chat
+            // attachment lives in the model's sandbox — and a path this host can see
+            // is only read when it is in a folder the operator opened up.
+            read = await readWithinSearchDirs(zipPath, searchDirs);
+        }
+        read ??= await readFromSearchDirs(fileName, searchDirs);
+        if (read && "oversizeBytes" in read) {
+            return tooLargeError(read.oversizeBytes);
+        }
+        if (!read) {
+            return {
+                kind: "error",
+                code: "import_zip_unreadable",
+                message: `No file named "${fileName}" that this gateway will read: "${zipPath}" is not in ${searchDirs.join(" or ")}, and those are the only folders it opens archives from. Ask the user to move the archive into one of them, or to say where it is so the operator can allow that folder. Do not encode the file as base64 — a real archive takes minutes to write out and arrives corrupted.`,
+            };
+        }
+        bytes = read.bytes;
+    }
+    else {
+        try {
+            bytes = Buffer.from(input.zipBase64.trim(), "base64");
+        }
+        catch {
+            return {
+                kind: "error",
+                code: "import_zip_invalid",
+                message: "zipBase64 is not valid base64.",
+            };
+        }
+        if (bytes.byteLength === 0) {
+            return {
+                kind: "error",
+                code: "import_zip_invalid",
+                message: "zipBase64 decoded to an empty payload.",
+            };
+        }
+        fileName = "import.zip";
+    }
+    if (bytes.byteLength > IMPORT_ZIP_MAX_BYTES) {
+        return tooLargeError(bytes.byteLength);
+    }
+    const archiveType = detectAttachmentArchiveType({ fileName });
+    if (archiveType === null) {
+        return {
+            kind: "error",
+            code: "import_zip_not_archive",
+            message: `Expected a .zip, .tgz, or .gz archive; got "${fileName}".`,
+        };
+    }
+    return {
+        kind: "ok",
+        value: {
+            bytes,
+            fileName,
+            mimeType: mimeTypeForArchiveType(archiveType),
+        },
+    };
+}
+function mimeTypeForArchiveType(archiveType) {
+    switch (archiveType) {
+        case "gz":
+        case "tgz":
+            return "application/gzip";
+        case "zip":
+            return "application/zip";
+    }
+}
+function normalizeImportSource(source) {
+    switch (source) {
+        case "chatgpt":
+        case "claude":
+        case "claude-design":
+        case "lovable":
+        case "replit":
+        case "streamlit":
+        case "v0":
+        case "zip":
+            return source;
+        default:
+            return "zip";
+    }
+}
+/**
+ * Creates a fullstack app, uploads the caller's archive as an app attachment,
+ * and hands Clark a migration prompt — the same path as the browser import
+ * wizard, without the sessionStorage hop.
+ */
+export async function importApp(ctx, input) {
+    const archiveResult = await resolveImportArchive(input, ctx.config.importSearchDirs);
+    if (archiveResult.kind !== "ok") {
+        return archiveResult;
+    }
+    const archive = archiveResult.value;
+    const principalResult = await ensurePrincipal(ctx);
+    if (principalResult.kind !== "ok") {
+        return principalResult;
+    }
+    const principal = principalResult.value;
+    const source = normalizeImportSource(input.source);
+    const migrationPrompt = buildImportPrompt({
+        extraPrompt: input.prompt,
+        source,
+        zipFileName: archive.fileName,
+    });
+    const explicitName = input.name?.trim();
+    const name = explicitName || defaultAppName(migrationPrompt);
+    ctx.onProgress?.({
+        message: "Creating application for import",
+        type: "progress",
+    });
+    const created = await createApplicationForPrompt(ctx, {
+        apiKey: principal.apiKey,
+        name,
+        organizationId: principal.organizationId,
+        templateName: "app-fullstack",
+    });
+    if (created.kind !== "ok") {
+        return created;
+    }
+    const app = created.value;
+    // See startApp: the row outlives any failure below it, so it is already this
+    // caller's most recent app.
+    await rememberApplication(ctx, principal, app.id);
+    return namingCreatedApplication(app.id, "import_app", await migrateArchiveIntoApplication(ctx, {
+        applicationId: app.id,
+        archive,
+        explicitName,
+        input,
+        migrationPrompt,
+        name,
+        principal,
+        source,
+    }));
+}
+/**
+ * Uploads the archive onto an application that already exists and hands
+ * Superblocks the migration prompt that reads it.
+ */
+async function migrateArchiveIntoApplication(ctx, args) {
+    const { applicationId, archive, principal } = args;
+    ctx.onProgress?.({
+        message: "Uploading archive attachment",
+        type: "progress",
+    });
+    let upload;
+    try {
+        upload = await ctx.server.uploadAttachment({
+            apiKey: principal.apiKey,
+            applicationId,
+            bytes: archive.bytes,
+            fileName: archive.fileName,
+            mimeType: archive.mimeType,
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            kind: "error",
+            code: "import_upload_failed",
+            message,
+        };
+    }
+    return promptNewApplication(ctx, {
+        applicationId,
+        attachments: [
+            {
+                applicationId,
+                fileName: upload.fileName,
+                mediaType: upload.mimeType ?? archive.mimeType,
+                scopeType: "app",
+                signedUrl: upload.signedUrl,
+                signedUrlExpiresAt: upload.signedUrlExpiresAt,
+                storageKey: upload.storageKey,
+                type: "uploaded",
+                url: upload.contentUrl,
+            },
+        ],
+        explicitName: args.explicitName,
+        importSource: args.source,
+        input: args.input,
+        name: args.name,
+        principal,
+        prompt: args.migrationPrompt,
+    });
+}
+/** Machine-readable shape a cancelled wait answers with. */
+function cancelled(capability) {
+    return {
+        kind: "error",
+        code: "cancelled",
+        message: `${capability} was cancelled by the caller.`,
+    };
+}
+function nowMs(ctx) {
+    return (ctx.now ?? Date.now)();
+}
+/**
+ * The longest any single host-facing call may block.
+ *
+ * Independent of whether the host supports progress notifications, and
+ * deliberately so: a progress notification is a courtesy the host may ignore,
+ * and a call that outlives the host's tool-call ceiling is a hung request
+ * whether or not notifications were sent along the way. Every wait in this
+ * file is clamped to it, and a call that hits the clamp answers with pacing
+ * and a cursor instead of holding the line open.
+ */
+function hostCallBudgetMs(ctx, requestedMs) {
+    return Math.max(0, Math.min(requestedMs, ctx.config.hostCallCeilingMs));
+}
+/** Where a caller's cursor for one application lives. */
+function cursorKeyFor(ctx, principal, applicationId) {
+    if (!ctx.caller || !ctx.progressCursors) {
+        return undefined;
+    }
+    return {
+        applicationId,
+        caller: ctx.caller,
+        organizationId: principal.organizationId,
+    };
+}
+/**
+ * Reads the durable stream for this caller without consuming it.
+ *
+ * Returns nothing when resume is not wired (no store, or no live edit known
+ * for this application yet), which is what keeps one-shot callers and tests
+ * of the live path on exactly the behavior they had.
+ */
+async function readSnapshot(ctx, input) {
+    const store = ctx.events;
+    if (!store || !ctx.progressCursors) {
+        return undefined;
+    }
+    const liveEditId = await ctx.progressCursors.getLiveEditId({
+        applicationId: input.applicationId,
+        organizationId: input.organizationId,
+    });
+    if (!liveEditId) {
+        return undefined;
+    }
+    const scope = {
+        applicationId: input.applicationId,
+        liveEditId,
+        organizationId: input.organizationId,
+    };
+    // A cursor a caller handed back gets the same validation a stored one does.
+    // Anything unreadable falls back to that caller's own stored position: a
+    // position this contract cannot vouch for would otherwise skip the caller
+    // past unread events, and a corrupt one compares false against every
+    // sequence and hides the whole stream for as long as the caller keeps
+    // handing it back.
+    const supplied = input.overrideCursor === undefined
+        ? undefined
+        : parseEventCursor(input.overrideCursor);
+    return await store.snapshot({
+        ...scope,
+        cursor: supplied ?? input.cursor?.cursor,
+        ...(input.limit === undefined ? {} : { limit: input.limit }),
+    });
+}
+export async function checkAppProgress(ctx, input) {
+    const principalResult = await ensurePrincipal(ctx);
+    if (principalResult.kind !== "ok") {
+        return principalResult;
+    }
+    const principal = principalResult.value;
+    const resolved = await resolveApplicationId(ctx, principal, input.applicationId);
+    if (resolved.kind !== "ok") {
+        return resolved;
+    }
+    const applicationId = resolved.value;
+    // Checked before the wait as well as after it. A caller that cancelled
+    // while the credential was being resolved should never reach the point of
+    // registering a waiter it will not read.
+    if (ctx.signal?.aborted) {
+        return cancelled("check_app_progress");
+    }
+    const cursorKey = cursorKeyFor(ctx, principal, applicationId);
+    const stored = cursorKey
+        ? await ctx.progressCursors?.getCursor(cursorKey)
+        : undefined;
+    const update = await ctx.sessionPeer.awaitTurn({
+        applicationId,
+        organizationId: principal.organizationId,
+        ...(ctx.signal ? { signal: ctx.signal } : {}),
+        userId: principal.userId,
+        waitMs: hostCallBudgetMs(ctx, ctx.config.clarkProgressWaitMs),
+    });
+    if (ctx.signal?.aborted) {
+        return cancelled("check_app_progress");
+    }
+    const snapshot = await readSnapshot(ctx, {
+        applicationId,
+        cursor: stored,
+        organizationId: principal.organizationId,
+        ...(input.cursor ? { overrideCursor: input.cursor } : {}),
+    });
+    // The local turn is an accelerator, not the record. When this process is
+    // not holding the turn (restart, another replica), the persisted stream is
+    // all there is. When it is holding a still-running turn, Redis may still
+    // carry durable progress from another path that the local collector missed
+    // — merge that activity so a quiet local turn does not look hung.
+    const streamProgress = snapshot
+        ? readPersistedProgress(snapshot, streamLiveness(ctx), ctx.config.clarkSettleMs)
+        : undefined;
+    const resumeFromStream = update.status === "unknown" ? streamProgress : undefined;
+    const elapsedSeconds = Math.round(update.elapsedMs / 1000);
+    const liveActivity = update.status === "running" && update.activity.length === 0
+        ? []
+        : update.activity;
+    const mergedWhileRunning = update.status === "running" && streamProgress
+        ? mergeActivity(liveActivity, streamProgress.activity)
+        : undefined;
+    const activity = resumeFromStream
+        ? resumeFromStream.activity
+        : mergedWhileRunning && mergedWhileRunning.length > 0
+            ? mergedWhileRunning
+            : update.status === "running" && update.activity.length === 0
+                ? [`Superblocks is still generating (${elapsedSeconds}s)`]
+                : liveActivity;
+    // Live lines were already shown on earlier polls for this turn. When Redis
+    // actually contributed durable lines, only stream those that are new relative
+    // to live so the same progress is not re-emitted. An empty/lagging store must
+    // still notify the live activity — otherwise a quiet Redis snapshot silences
+    // the turn.
+    const progressMessages = mergedWhileRunning !== undefined &&
+        (streamProgress?.activity.length ?? 0) > 0
+        ? mergedWhileRunning.filter((line) => !liveActivity.includes(line))
+        : activity;
+    for (const message of progressMessages) {
+        ctx.onProgress?.({ message, type: "progress" });
+    }
+    const status = resumeFromStream
+        ? resumeFromStream.status
+        : update.status === "finished"
+            ? buildStatusOf(update.generationStatus)
+            : update.status === "running"
+                ? "building"
+                : "unknown";
+    const terminal = status !== "building";
+    const pacing = await recordPacing(ctx, {
+        applicationId,
+        appScope: { applicationId, organizationId: principal.organizationId },
+        cursorKey,
+        elapsedMs: update.elapsedMs,
+        // Only advance the Redis cursor when this poll actually answered from
+        // persisted events. Advancing while answering from the live socket alone
+        // skips unread durable events after a restart.
+        advanceCursor: resumeFromStream !== undefined ||
+            (update.status === "running" &&
+                (streamProgress?.activity.length ?? 0) > 0),
+        // What Superblocks itself said, not what this poll is returning. The
+        // heartbeat below is the gateway's own words, added so a quiet poll has
+        // something to show; counting it as news would mean a build can never be
+        // detected as quiet, because every quiet poll manufactures a line.
+        saidSomething: resumeFromStream
+            ? resumeFromStream.activity.length > 0
+            : update.activity.length > 0 ||
+                (mergedWhileRunning !== undefined && mergedWhileRunning.length > 0),
+        snapshot,
+        stored,
+        terminal,
+        // Only the local turn carries a clock. A build read out of the persisted
+        // stream is running somewhere else and this process cannot say how long
+        // for, so it reports no budget rather than inventing a full one.
+        turnRunning: update.status === "running",
+    });
+    const base = {
+        ...pacing.pacing,
+        activity,
+        applicationId,
+        editUrl: editUrl(ctx.config, applicationId),
+        elapsedSeconds,
+        ...(pacing.stallHint ? { stallHint: pacing.stallHint } : {}),
+        ...("recentRuns" in update &&
+            Array.isArray(update.recentRuns) &&
+            update.recentRuns.length > 0
+            ? { recentRuns: update.recentRuns }
+            : {}),
+    };
+    if (resumeFromStream) {
+        return {
+            kind: "ok",
+            value: {
+                ...base,
+                ...(resumeFromStream.generationStatus
+                    ? { generationStatus: resumeFromStream.generationStatus }
+                    : {}),
+                ...(resumeFromStream.reply ? { reply: resumeFromStream.reply } : {}),
+                status,
+            },
+        };
+    }
+    if (update.status !== "finished") {
+        return { kind: "ok", value: { ...base, status } };
+    }
+    ctx.onProgress?.({ message: turnSummary(update), type: "completed" });
+    return {
+        kind: "ok",
+        value: {
+            ...base,
+            ...(update.checkpointCommitId
+                ? { checkpointCommitId: update.checkpointCommitId }
+                : {}),
+            reply: update.reply,
+            ...(update.decision ? { decision: update.decision } : {}),
+            generationStatus: update.generationStatus,
+            status,
+            viewStatus: update.viewStatus,
+        },
+    };
+}
+/**
+ * When this build last said anything, as far as this turn is concerned.
+ *
+ * Read app-scoped rather than per-caller so two readers of one build cannot
+ * disagree about whether it has gone quiet, and never earlier than the turn
+ * started: the stored value outlives the turn that wrote it, so the gap
+ * between two turns — a user reading a plan before approving it — would
+ * otherwise be counted as this turn having gone quiet.
+ *
+ * A store that cannot answer costs a stall hint, not the poll, so it reads as
+ * "nothing heard since this turn began".
+ */
+async function lastActivityWithinTurn(ctx, input) {
+    try {
+        const observedAtMs = await ctx.progressCursors?.getLastActivityAtMs(input.appScope);
+        return Math.max(observedAtMs ?? input.turnStartedAtMs, input.turnStartedAtMs);
+    }
+    catch (error) {
+        console.warn("gateway could not read when the build last spoke", {
+            message: error instanceof Error ? error.message : String(error),
+        });
+        return input.turnStartedAtMs;
+    }
+}
+/**
+ * Records when the build last spoke, for every reader of it rather than the
+ * one that happened to hear it.
+ *
+ * Swallowed on failure for the same reason the live-edit pointer is: it costs
+ * a stall hint, and failing a progress poll over stall bookkeeping would trade
+ * a degraded answer for no answer at all.
+ */
+async function rememberLastActivity(ctx, input) {
+    try {
+        await ctx.progressCursors?.setLastActivityAtMs(input);
+    }
+    catch (error) {
+        console.warn("gateway could not record when the build last spoke", {
+            message: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+/**
+ * Works out what to tell the caller about coming back, and persists its new
+ * position.
+ *
+ * The cursor is written only here, and only after the response it describes
+ * has been assembled: advancing it earlier would lose events for a call that
+ * then failed. It advances only this caller's key, so a second reader of the
+ * same build is unaffected.
+ */
+async function recordPacing(ctx, input) {
+    const quiet = !input.saidSomething && !input.terminal;
+    const currentTimeMs = nowMs(ctx);
+    const turnStartedAtMs = currentTimeMs - input.elapsedMs;
+    const lastActivityAtMs = input.saidSomething
+        ? currentTimeMs
+        : await lastActivityWithinTurn(ctx, {
+            appScope: input.appScope,
+            turnStartedAtMs,
+        });
+    const quietMs = Math.max(0, currentTimeMs - lastActivityAtMs);
+    const alreadyHinted = input.stored?.stallHintedAtMs !== undefined;
+    const stallHint = quiet && !alreadyHinted && quietMs >= ctx.config.clarkStallHintAfterMs
+        ? { quietMs, reason: "long_quiet" }
+        : undefined;
+    // Only what this poll actually heard, and whether or not this caller has a
+    // cursor, so a reader that never had one still measures silence from when
+    // the build last spoke. A quiet poll writing its own read back would clobber
+    // activity a concurrent reader heard between that read and this write.
+    if (input.saidSomething) {
+        await rememberLastActivity(ctx, {
+            ...input.appScope,
+            atMs: currentTimeMs,
+        });
+    }
+    if (input.cursorKey && ctx.progressCursors) {
+        const advanceCursor = input.advanceCursor !== false;
+        const cursor = advanceCursor
+            ? (input.snapshot?.cursor ?? input.stored?.cursor ?? EMPTY_EVENT_CURSOR)
+            : (input.stored?.cursor ?? EMPTY_EVENT_CURSOR);
+        // Hearing anything closes the quiet spell, so the next silence gets its
+        // own hint rather than being suppressed by the previous one.
+        const hintedAtMs = stallHint
+            ? currentTimeMs
+            : quiet
+                ? input.stored?.stallHintedAtMs
+                : undefined;
+        await ctx.progressCursors.setCursor({
+            ...input.cursorKey,
+            record: {
+                cursor,
+                ...(hintedAtMs === undefined ? {} : { stallHintedAtMs: hintedAtMs }),
+            },
+        });
+    }
+    return {
+        pacing: {
+            ...(input.snapshot && input.advanceCursor !== false
+                ? { cursor: input.snapshot.cursor }
+                : input.stored
+                    ? { cursor: input.stored.cursor }
+                    : {}),
+            nextPollAfterMs: input.terminal
+                ? 0
+                : nextPollAfterMs(ctx, input.applicationId),
+            ...(input.turnRunning
+                ? {
+                    remainingTurnBudgetMs: Math.max(0, ctx.config.clarkTurnTimeoutMs - input.elapsedMs),
+                }
+                : {}),
+            ...(input.snapshot && input.snapshot.lost.length > 0
+                ? { staleStreams: input.snapshot.lost }
+                : {}),
+        },
+        ...(stallHint ? { stallHint } : {}),
+    };
+}
+/**
+ * Pacing for a caller that is being handed a starting point rather than a
+ * batch of activity.
+ *
+ * Reads the caller's stored cursor and hands it straight back without
+ * advancing it. `get_app` reports no activity, so moving the cursor here would
+ * mark events as read that nobody has read — the caller's next
+ * `check_app_progress` would silently skip them.
+ *
+ * Carries no `remainingTurnBudgetMs`. `get_app` is not the tool that follows a
+ * turn and never has the turn's own clock, so any number it put there would be
+ * the full budget regardless of how long the turn had been running - or
+ * regardless of whether one was running at all, which is what it used to send
+ * alongside a preview build (ENG-5808). `check_app_progress` is where a caller
+ * following a turn reads what is left of it.
+ */
+async function buildPacing(ctx, input) {
+    const stored = ctx.caller
+        ? await ctx.progressCursors?.getCursor({
+            applicationId: input.applicationId,
+            caller: ctx.caller,
+            organizationId: input.organizationId,
+        })
+        : undefined;
+    return {
+        cursor: stored?.cursor ?? EMPTY_EVENT_CURSOR,
+        nextPollAfterMs: input.terminal
+            ? 0
+            : nextPollAfterMs(ctx, input.applicationId),
+    };
+}
+/**
+ * How soon the caller should poll again. Once the app is building it runs for
+ * minutes, so pace at clarkBuildPollAfterMs (~30s) to stay inside a host's
+ * tool-call budget; while it is still planning, keep the shorter progress wait
+ * so a plan or question surfaces quickly.
+ */
+function nextPollAfterMs(ctx, applicationId) {
+    const cadenceMs = ctx.sessionPeer.buildMode?.(applicationId)
+        ? ctx.config.clarkBuildPollAfterMs
+        : ctx.config.clarkProgressWaitMs;
+    return hostCallBudgetMs(ctx, cadenceMs);
+}
+export async function editApp(ctx, input) {
+    const principalResult = await ensurePrincipal(ctx);
+    if (principalResult.kind !== "ok") {
+        return principalResult;
+    }
+    const principal = principalResult.value;
+    const resolved = await resolveApplicationId(ctx, principal, input.applicationId);
+    if (resolved.kind !== "ok") {
+        return resolved;
+    }
+    const applicationId = resolved.value;
+    return namingApplication(applicationId, await promptExistingApplication(ctx, { applicationId, input, principal }));
+}
+async function promptExistingApplication(ctx, args) {
+    const { applicationId, input, principal } = args;
+    // Approve reuses the pending plan as the prompt. Every other path needs the
+    // caller's words — an empty or missing prompt would otherwise forward
+    // undefined into Clark.
+    if (input.planAction !== "approve" &&
+        !(typeof input.prompt === "string" && input.prompt.trim().length > 0)) {
+        return {
+            kind: "error",
+            code: "prompt_required",
+            message: 'edit_app needs a prompt, unless planAction is "approve" (Build it) for a pending plan.',
+        };
+    }
+    ctx.onProgress?.({ message: "Ensuring live-edit session", type: "progress" });
+    let session;
+    try {
+        session = await openLiveEdit(ctx, {
+            apiKey: principal.apiKey,
+            applicationId,
+            branch: input.branch,
+            organizationId: principal.organizationId,
+        });
+    }
+    catch (error) {
+        rememberFailedStart(ctx, { applicationId, error, principal });
+        return liveEditUnavailable(error);
+    }
+    ctx.onProgress?.({
+        message: "Forwarding prompt to Superblocks",
+        type: "progress",
+    });
+    const pending = ctx.sessionPeer.pendingPlan?.(applicationId);
+    // Approve / refine a pending plan the way the editor's "Build it" / chat
+    // refine path does. A bare prompt while a plan is pending is refine feedback.
+    const effectiveAction = input.planAction ?? (pending ? "refine" : undefined);
+    // Clark's headless default is PLAN, so a follow-up prompt after a BUILD turn
+    // used to propose a plan instead of continuing the build. Preserve BUILD
+    // until the caller explicitly asks to plan, regardless of how BUILD began.
+    const defaultMode = ctx.sessionPeer.buildMode?.(applicationId)
+        ? "BUILD"
+        : "PLAN";
+    let promptArgs = {
+        applicationId,
+        branch: input.branch,
+        idempotencyKey: input.idempotencyKey,
+        liveEditId: session.liveEditId,
+        liveEditUrl: session.liveEditUrl,
+        mode: input.mode ?? defaultMode,
+        organizationId: principal.organizationId,
+        prompt: input.prompt ?? "",
+        userId: principal.userId,
+    };
+    if (effectiveAction === "approve") {
+        if (pending?.plan) {
+            promptArgs = {
+                ...promptArgs,
+                mode: "BUILD",
+                planContext: {
+                    approved: true,
+                    plan: pending.plan,
+                    ...(pending.title ? { title: pending.title } : {}),
+                },
+                prompt: pending.plan,
+                responseMetadata: {
+                    approved: true,
+                    ...(pending.messageId
+                        ? { responseToMessageId: pending.messageId }
+                        : {}),
+                    type: "plan_response",
+                },
+            };
+        }
+        else if (awaitingDecision(ctx, {
+            applicationId,
+            organizationId: principal.organizationId,
+            userId: principal.userId,
+        })) {
+            // Clark is waiting on the user but streamed its plan as chat text, so no
+            // plan card was captured. "Build it" still means build: forward a build
+            // turn the way the editor's Build-it does. Clark still holds the plan in
+            // its own context, so the caller's words (or a plain go-ahead) suffice.
+            promptArgs = {
+                ...promptArgs,
+                mode: "BUILD",
+                planContext: { approved: true },
+                prompt: input.prompt?.trim() ||
+                    "The plan is approved. Build it as described.",
+                responseMetadata: { approved: true, type: "plan_response" },
+            };
+        }
+        else {
+            return {
+                kind: "error",
+                code: "plan_required",
+                message: "No pending Superblocks plan to approve for this application. Start or edit in Plan mode first, then approve after needs_decision.",
+            };
+        }
+    }
+    else if (effectiveAction === "refine" && pending?.plan) {
+        promptArgs = {
+            ...promptArgs,
+            mode: "PLAN",
+            planContext: {
+                approved: false,
+                plan: pending.plan,
+                ...(pending.title ? { title: pending.title } : {}),
+            },
+            responseMetadata: {
+                approved: false,
+                ...(pending.messageId
+                    ? { responseToMessageId: pending.messageId }
+                    : {}),
+                type: "plan_response",
+            },
+        };
+    }
+    if (input.wait === "ack") {
+        const started = await startClarkPrompt(ctx, promptArgs);
+        if (started.kind !== "ok") {
+            return started;
+        }
+        await rememberApplication(ctx, principal, applicationId);
+        return {
+            kind: "ok",
+            value: await withBrowser(ctx, applicationId, {
+                activity: started.value.activity,
+                applicationId,
+                editUrl: editUrl(ctx.config, applicationId),
+                mode: promptArgs.mode,
+                status: "building",
+            }),
+        };
+    }
+    const forward = await forwardClarkPrompt(ctx, promptArgs);
+    if (forward.kind !== "ok") {
+        return forward;
+    }
+    await rememberApplication(ctx, principal, applicationId);
+    const result = {
+        applicationId,
+        ...(forward.value.checkpointCommitId
+            ? { checkpointCommitId: forward.value.checkpointCommitId }
+            : {}),
+        reply: forward.value.reply,
+        ...(forward.value.decision ? { decision: forward.value.decision } : {}),
+        editUrl: editUrl(ctx.config, applicationId),
+        generationStatus: forward.value.generationStatus,
+        mode: promptArgs.mode,
+        ...(forward.value.recentRuns && forward.value.recentRuns.length > 0
+            ? { recentRuns: forward.value.recentRuns }
+            : {}),
+        status: buildStatusOf(forward.value.generationStatus),
+        viewStatus: forward.value.viewStatus,
+    };
+    ctx.onProgress?.({
+        message: turnSummary(forward.value),
+        type: "completed",
+    });
+    return {
+        kind: "ok",
+        value: await withBrowser(ctx, applicationId, result),
+    };
+}
+/**
+ * Shows the app's current work on a real URL without deploying it - the
+ * editor's Preview button, driven from here.
+ *
+ * Three steps, the same ones and in the same order as the editor: snapshot the
+ * live-edit state as a commit, make sure a build exists for that commit's
+ * content, and hand back the URL that serves it. Builds are keyed on content
+ * rather than on the commit, so previewing work that was already built (by an
+ * earlier preview, or by a publish) waits on that build instead of starting a
+ * second one.
+ */
+export async function previewApp(ctx, input) {
+    const principalResult = await ensurePrincipal(ctx);
+    if (principalResult.kind !== "ok") {
+        return principalResult;
+    }
+    const principal = principalResult.value;
+    const resolved = await resolveApplicationId(ctx, principal, input.applicationId);
+    if (resolved.kind !== "ok") {
+        return resolved;
+    }
+    const applicationId = resolved.value;
+    // Not "Committing current work": a preview commits whether or not Superblocks
+    // wrote anything, and saying there is work to commit before finding out is the
+    // gateway narrating an intention as a fact (ENG-5808).
+    ctx.onProgress?.({ message: "Preparing a preview", type: "progress" });
+    let commit;
+    try {
+        commit = await ctx.server.createCommit({
+            apiKey: principal.apiKey,
+            applicationId,
+            branch: input.branch,
+            message: "Preview",
+        });
+    }
+    catch (error) {
+        if (error instanceof ServerHttpError &&
+            (error.status === 401 || error.status === 403)) {
+            return elicitStepUp(ctx, `stepup:preview:${applicationId}`, applicationId);
+        }
+        return {
+            kind: "error",
+            code: "commit_failed",
+            message: error instanceof Error ? error.message : String(error),
+        };
+    }
+    const directoryHash = commit.directoryHash;
+    if (!directoryHash) {
+        return {
+            kind: "error",
+            code: "preview_unavailable",
+            message: "This application has no directory contents to build, so it cannot be previewed. Only code-mode applications — the kind start_app creates — can be.",
+        };
+    }
+    const url = previewUrl(ctx.config, applicationId, commit.commitId);
+    const ready = await waitForBuild(ctx, {
+        apiKey: principal.apiKey,
+        applicationId,
+        commitId: commit.commitId,
+        directoryHash,
+        wait: input.wait !== false,
+    });
+    if (ready.kind !== "ok") {
+        return ready;
+    }
+    let jwt;
+    if (ctx.config.deployedShellBaseUrl) {
+        try {
+            jwt = await ctx.server.issueScopedToken({
+                apiKey: principal.apiKey,
+                applicationId,
+                commitId: commit.commitId,
+                scope: "apps:preview",
+            });
+        }
+        catch (error) {
+            console.warn("gateway preview scoped token failed; using UI preview URL", {
+                applicationId,
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    const openable = buildOpenablePreviewUrls({
+        applicationId,
+        commitId: commit.commitId,
+        deployedShellBaseUrl: ctx.config.deployedShellBaseUrl,
+        jwt,
+        publicViewerBaseUrl: ctx.config.publicViewerBaseUrl,
+        uiPreviewUrl: url,
+    });
+    let screenshotBase64;
+    let needsBrowserDriver = false;
+    const gatewayChromium = await gatewayChromiumIsPresent(ctx);
+    const includeScreenshot = input.includeScreenshot !== false;
+    // Always capture when the preview is ready and Gateway Chromium is present.
+    // urls_only must not wait on chromium.launch() (ENG-5858).
+    if (!includeScreenshot) {
+        console.error("gateway preview screenshot skipped", {
+            applicationId,
+            reason: "live library capture will run instead",
+        });
+    }
+    else if (!ready.value.built) {
+        console.error("gateway preview screenshot skipped", {
+            applicationId,
+            reason: "build not finished",
+        });
+    }
+    else if (!ctx.capturePreviewScreenshot) {
+        console.error("gateway preview screenshot skipped", {
+            applicationId,
+            reason: "no capture backend configured",
+        });
+        needsBrowserDriver = true;
+    }
+    else if (!gatewayChromium) {
+        console.error("gateway preview screenshot skipped", {
+            applicationId,
+            reason: "no gateway chromium",
+        });
+        needsBrowserDriver = true;
+    }
+    else {
+        ctx.onProgress?.({
+            message: "Capturing a preview screenshot",
+            type: "progress",
+        });
+        try {
+            const shot = await ctx.capturePreviewScreenshot({
+                embedToken: principal.apiKey,
+                url: buildEmbedShellPreviewUrl({
+                    applicationId,
+                    deployedShellBaseUrl: ctx.config.deployedShellBaseUrl,
+                    uiBaseUrl: ctx.config.uiBaseUrl,
+                }),
+            });
+            screenshotBase64 = shot?.dataBase64;
+            // A capture that soft-fails looks exactly like one that was never asked
+            // for, which is what made a missing demo screenshot undiagnosable.
+            console.error("gateway preview screenshot captured", {
+                applicationId,
+                base64Length: screenshotBase64?.length ?? 0,
+            });
+        }
+        catch (error) {
+            // Screenshot is optional; never fail get_app / preview_app for it.
+            console.warn("gateway preview screenshot threw; continuing with URLs", {
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    const name = await applicationName(ctx, principal, applicationId);
+    await rememberApplication(ctx, principal, applicationId);
+    ctx.onProgress?.({
+        message: ready.value.built
+            ? `Preview ready: ${openable.previewUrl}`
+            : "Preview is still building",
+        type: "completed",
+    });
+    return {
+        kind: "ok",
+        value: await withBrowser(ctx, applicationId, {
+            applicationId,
+            commitId: commit.commitId,
+            editUrl: editUrl(ctx.config, applicationId),
+            ...(name ? { name } : {}),
+            ...(needsBrowserDriver ? { needsBrowserDriver: true } : {}),
+            openableViaHttps: openable.openableViaHttps,
+            previewUrl: openable.previewUrl,
+            ...(screenshotBase64 ? { screenshotBase64 } : {}),
+            status: ready.value.built ? "ready" : "building",
+            viewerUrl: openable.viewerUrl,
+        }),
+    };
+}
+/**
+ * The app's display name, or undefined when it cannot be read. A label is
+ * never worth failing a preview over, so every failure here is swallowed.
+ */
+async function applicationName(ctx, principal, applicationId) {
+    try {
+        return await ctx.server.getApplicationName({
+            apiKey: principal.apiKey,
+            applicationId,
+        });
+    }
+    catch (error) {
+        console.warn("gateway application name lookup failed", {
+            applicationId,
+            message: error instanceof Error ? error.message : String(error),
+        });
+        return undefined;
+    }
+}
+/**
+ * Whether the app's last turn finished waiting on the user. True even when the
+ * collector captured no structured plan/question (Clark streamed it as chat
+ * text), so approve and get_app can treat a decision-less needs_decision the
+ * same as a plan card instead of dead-ending or previewing the template.
+ */
+function awaitingDecision(ctx, scope) {
+    const turn = ctx.sessionPeer.turnState?.(scope);
+    return (turn?.phase === "finished" && turn.generationStatus === "needs_decision");
+}
+function emptyTurnStatus(status) {
+    switch (status) {
+        case "cancelled":
+        case "live_edit_terminated":
+        case "no_changes":
+        case "timeout":
+            return status;
+        default:
+            return undefined;
+    }
+}
+/**
+ * Why the app cannot be previewed, read from the turn this process is holding.
+ */
+function localUnbuiltReason(turn, pending) {
+    if (turn?.phase === "running") {
+        return { kind: "running" };
+    }
+    if (pending) {
+        return { decision: pending.decision, kind: "awaiting_decision" };
+    }
+    if (turn?.phase !== "finished") {
+        return undefined;
+    }
+    // Clark can end a turn awaiting the user having streamed its plan or question
+    // as ordinary chat text, so the collector captured no structured decision.
+    // The turn is still a decision - previewing here is what commits and builds
+    // the untouched template into a blank card.
+    if (turn.generationStatus === "needs_decision") {
+        return { kind: "awaiting_decision" };
+    }
+    // A turn that ended without a checkpoint wrote nothing, so the only thing
+    // left to preview is the template the app was created from - the blank card
+    // this gate exists to prevent.
+    if (turn.checkpointCommitId) {
+        return undefined;
+    }
+    const status = emptyTurnStatus(turn.generationStatus);
+    return status ? { kind: "empty_turn", status } : undefined;
+}
+/**
+ * The same question asked of what was persisted, for a caller with no live turn
+ * to ask.
+ *
+ * Only a status that cannot coexist with committed work is read from here. The
+ * gateway checkpoints a turn that *completed*, and the stream carries no record
+ * of whether that landed, so a `cancelled` in the tail may well have a real app
+ * behind it and withholding its preview would hide one. A live edit that died
+ * and a turn still waiting on the user both certainly never reached completed.
+ *
+ * A stream with no terminal state at all is a build still running as far as it
+ * knows, and so is one this gateway timed out - a gateway budget is not
+ * something the dev server records. Neither is grounds to withhold a preview.
+ */
+async function persistedUnbuiltReason(ctx, principal, applicationId) {
+    let snapshot;
+    try {
+        snapshot = await readSnapshot(ctx, {
+            applicationId,
+            // get_app is not a poll: it reads the tail, which is cursor-independent,
+            // and must not move any caller's place in the stream.
+            cursor: undefined,
+            // Only the tail is read below, and the tail does not depend on this. It
+            // keeps the call from dragging back the whole retained stream to answer
+            // one question about the end of it.
+            limit: 1,
+            organizationId: principal.organizationId,
+        });
+    }
+    catch (error) {
+        // This is the only I/O on a path that had none. An event store having a
+        // bad moment is not a reason for get_app to fail: fall back to what the
+        // call answered before there was a stream to ask.
+        console.warn("gateway get_app persisted state unreadable", {
+            applicationId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return undefined;
+    }
+    if (!snapshot) {
+        return undefined;
+    }
+    const { generationStatus } = readPersistedProgress(snapshot, streamLiveness(ctx), ctx.config.clarkSettleMs);
+    return generationStatus ? persistedTurnEnd(generationStatus) : undefined;
+}
+/**
+ * When to stop believing what the stream last said. A turn cannot outlive its
+ * own budget, so work silent for longer than that has ended whatever the tail
+ * still holds.
+ *
+ * Shared by both readers so one rule governs every status read out of a stream,
+ * even where a caller happens not to use the part it governs: this reader takes
+ * only `generationStatus`, which never expires, while `check_app_progress` reads
+ * the status the rule applies to.
+ */
+function streamLiveness(ctx) {
+    return {
+        nowMs: nowMs(ctx),
+        staleAfterMs: ctx.config.clarkTurnTimeoutMs,
+    };
+}
+/**
+ * What a terminal status read from the stream says about previewing the app.
+ *
+ * Exhaustive on purpose: the live reader answers this same question from a
+ * `TurnState`, and the two are only guaranteed to agree while every status has
+ * been given an answer on both. A new one fails to compile here rather than
+ * quietly defaulting to buildable.
+ *
+ * `no_changes` never appears. Which of `completed` and `no_changes` a turn
+ * reached is decided by counting the work signals the collector saw, and the
+ * stream carries no such signal - the dev server reports the state, not the
+ * files. A no-work turn therefore reads as `completed` here and is previewed.
+ *
+ * TODO(ENG-5911): close that by persisting the gateway's own account of the
+ * turn - the settled status and whether a checkpoint landed - rather than
+ * adding another rule over the states the stream already has.
+ */
+function persistedTurnEnd(status) {
+    switch (status) {
+        // TODO(ENG-5912): carry the decision itself. The stream has the plan - it
+        // is an assistant `chat_message` with a `messageType` - but nothing reads
+        // it back into a `TurnDecision`, so a plan resumed from here renders as a
+        // plain question and cannot be approved.
+        case "needs_decision":
+            return { kind: "awaiting_decision" };
+        case "live_edit_terminated":
+            return { kind: "empty_turn", status };
+        // A `cancelled` in the tail may still have a real app behind it: the
+        // gateway checkpoints a turn that completed and the stream carries no
+        // record of whether that landed, so withholding the preview would hide
+        // one. `detached` and `timeout` are the gateway's own verdicts, which the
+        // dev server never records, and `completed` is the case this gate exists
+        // to let through.
+        case "cancelled":
+        case "completed":
+        case "detached":
+        case "no_changes":
+        case "timeout":
+            return undefined;
+        default: {
+            const exhaustive = status;
+            return exhaustive;
+        }
+    }
+}
+async function unbuiltReason(ctx, principal, applicationId) {
+    const turn = ctx.sessionPeer.turnState?.({
+        applicationId,
+        organizationId: principal.organizationId,
+        userId: principal.userId,
+    });
+    const pending = ctx.sessionPeer.pendingDecision?.(applicationId);
+    if (turn || pending) {
+        return localUnbuiltReason(turn, pending);
+    }
+    // The local turn is an accelerator, not the record. With nothing held here -
+    // after a restart, on another replica, or once a finished turn was released -
+    // the persisted stream is the only account of the turn that is left, and
+    // falling through without asking it is how the untouched starter template
+    // gets built and shown as a finished app.
+    return await persistedUnbuiltReason(ctx, principal, applicationId);
+}
+/**
+ * The answer `get_app` owes a caller while the app has nothing worth showing.
+ *
+ * Clark's headless default is PLAN, so a first prompt commonly ends on a plan
+ * or a question rather than on code. Previewing that state commits and builds
+ * the untouched template, and the caller shows the blank result as if the app
+ * were ready. Undefined once Clark's turn is over and a preview means something.
+ */
+async function unbuiltApp(ctx, principal, applicationId) {
+    const reason = await unbuiltReason(ctx, principal, applicationId);
+    if (!reason) {
+        return undefined;
+    }
+    const name = await applicationName(ctx, principal, applicationId);
+    await rememberApplication(ctx, principal, applicationId);
+    const app = await withBrowser(ctx, applicationId, {
+        applicationId,
+        editUrl: editUrl(ctx.config, applicationId),
+        ...(name ? { name } : {}),
+    });
+    if (reason.kind === "awaiting_decision") {
+        return {
+            kind: "ok",
+            value: {
+                ...app,
+                ...(reason.decision ? { decision: reason.decision } : {}),
+                pendingAction: reason.decision?.kind === "plan" ? "approve_plan" : "answer_question",
+                status: "needs_decision",
+            },
+        };
+    }
+    if (reason.kind === "empty_turn") {
+        return {
+            kind: "ok",
+            value: { ...app, pendingAction: "retry_build", status: reason.status },
+        };
+    }
+    return {
+        kind: "ok",
+        value: {
+            ...(await buildPacing(ctx, {
+                applicationId,
+                organizationId: principal.organizationId,
+                terminal: false,
+            })),
+            ...app,
+            pendingAction: "wait_for_build",
+            status: "building",
+        },
+    };
+}
+/**
+ * Lovable-style lookup: editor URL always, preview URLs when a build can be
+ * ensured (default). Captures a screenshot whenever the preview is ready.
+ */
+export async function getApp(ctx, input) {
+    const principalResult = await ensurePrincipal(ctx);
+    if (principalResult.kind !== "ok") {
+        return principalResult;
+    }
+    const principal = principalResult.value;
+    const resolved = await resolveApplicationId(ctx, principal, input.applicationId);
+    if (resolved.kind !== "ok") {
+        return resolved;
+    }
+    const applicationId = resolved.value;
+    const ensurePreview = input.ensurePreview !== false;
+    const unbuilt = await unbuiltApp(ctx, principal, applicationId);
+    const mayCapture = !unbuilt || unbuilt.value.status === "building";
+    const live = mayCapture
+        ? await ensureLibraryCaptureInput(ctx, principal, applicationId, input.branch)
+        : libraryCaptureInput(ctx, applicationId);
+    if (unbuilt) {
+        // Plan, question, and empty-starter stays fail-closed: photographing the
+        // untouched template is the bug unbuiltApp exists to prevent. A running
+        // turn is different: the held canvas is the thing being written, so a
+        // live shot is worth returning alongside wait_for_build.
+        if (unbuilt.value.status !== "building" || !live) {
+            return unbuilt;
+        }
+        const liveShot = await captureLiveLibraryIfNeeded(ctx, applicationId, live);
+        return {
+            kind: "ok",
+            value: {
+                ...unbuilt.value,
+                ...(liveShot.needsBrowserDriver ? { needsBrowserDriver: true } : {}),
+                ...(liveShot.screenshotBase64
+                    ? { screenshotBase64: liveShot.screenshotBase64 }
+                    : {}),
+            },
+        };
+    }
+    if (ensurePreview) {
+        const preview = await previewApp(ctx, {
+            applicationId,
+            branch: input.branch,
+            includeScreenshot: live === undefined,
+            ...(input.wait === undefined ? {} : { wait: input.wait }),
+        });
+        if (preview.kind !== "ok") {
+            return preview;
+        }
+        // A build still running is the case this pacing exists for: the caller
+        // has usable URLs and needs to know when to look again. A finished one
+        // gets it too, with a zero interval, so a caller does not have to treat
+        // the fields' absence as a third state.
+        const pacing = await buildPacing(ctx, {
+            applicationId,
+            organizationId: principal.organizationId,
+            terminal: preview.value.status === "ready",
+        });
+        const liveShot = await captureLiveLibraryIfNeeded(ctx, applicationId, live);
+        const screenshotBase64 = live
+            ? liveShot.screenshotBase64
+            : preview.value.screenshotBase64;
+        const needsBrowserDriver = live
+            ? liveShot.needsBrowserDriver
+            : preview.value.needsBrowserDriver;
+        return {
+            kind: "ok",
+            value: {
+                ...pacing,
+                applicationId,
+                ...(preview.value.browser ? { browser: preview.value.browser } : {}),
+                commitId: preview.value.commitId,
+                editUrl: preview.value.editUrl,
+                ...(preview.value.name ? { name: preview.value.name } : {}),
+                ...(needsBrowserDriver ? { needsBrowserDriver: true } : {}),
+                openableViaHttps: preview.value.openableViaHttps,
+                previewUrl: preview.value.previewUrl,
+                ...(screenshotBase64 ? { screenshotBase64 } : {}),
+                status: preview.value.status,
+                viewerUrl: preview.value.viewerUrl,
+            },
+        };
+    }
+    const name = await applicationName(ctx, principal, applicationId);
+    await rememberApplication(ctx, principal, applicationId);
+    const liveShot = await captureLiveLibraryIfNeeded(ctx, applicationId, live);
+    return {
+        kind: "ok",
+        value: await withBrowser(ctx, applicationId, {
+            applicationId,
+            editUrl: editUrl(ctx.config, applicationId),
+            ...(name ? { name } : {}),
+            ...(liveShot.needsBrowserDriver ? { needsBrowserDriver: true } : {}),
+            ...(liveShot.screenshotBase64
+                ? { screenshotBase64: liveShot.screenshotBase64 }
+                : {}),
+            status: "unknown",
+        }),
+    };
+}
+/**
+ * Sees a build of this content through, starting one if none exists.
+ *
+ * `built: false` is not a failure: the build is still going and the caller has
+ * a URL that will work once it lands. Bounded by the publish wait budget — the
+ * same SABS build a publish waits on, so the same patience applies.
+ */
+async function waitForBuild(ctx, input) {
+    // Clamped to the host ceiling even though the build's own budget is far
+    // longer. A wait that outlives the host's tool-call timeout is not patience,
+    // it is a call nobody is left to read the answer of.
+    const deadline = nowMs(ctx) + hostCallBudgetMs(ctx, ctx.config.publishWaitTimeoutMs);
+    let started = false;
+    for (;;) {
+        if (ctx.signal?.aborted) {
+            return cancelled("get_app");
+        }
+        // Checked before the network call, not only after it: a budget already
+        // exhausted when this loop begins (or used up by the previous
+        // iteration's own round trip) should not pay for a poll whose answer is
+        // discarded the moment it arrives.
+        if (nowMs(ctx) >= deadline) {
+            return { kind: "ok", value: { built: false } };
+        }
+        let progress;
+        try {
+            progress = await ctx.server.getBuildProgress({
+                apiKey: input.apiKey,
+                applicationId: input.applicationId,
+                directoryHash: input.directoryHash,
+            });
+        }
+        catch (error) {
+            return {
+                kind: "error",
+                code: "preview_build_failed",
+                message: error instanceof Error ? error.message : String(error),
+            };
+        }
+        if (progress === "success") {
+            return { kind: "ok", value: { built: true } };
+        }
+        // A build this call started and that then reported failure is a real
+        // failure. One that was already failed when we arrived is a stale result
+        // for the same content, and starting a fresh build is what the editor does.
+        if ((progress === "failed" || progress === "timed_out") && started) {
+            return {
+                kind: "error",
+                code: "preview_build_failed",
+                message: `The build for this application ${progress === "timed_out" ? "timed out" : "failed"}. Open the app in the editor to see why.`,
+            };
+        }
+        if (progress !== "running" && !started) {
+            ctx.onProgress?.({ message: "Building a preview", type: "progress" });
+            try {
+                await ctx.server.createBuild({
+                    apiKey: input.apiKey,
+                    applicationId: input.applicationId,
+                    commitId: input.commitId,
+                    directoryHash: input.directoryHash,
+                });
+            }
+            catch (error) {
+                return {
+                    kind: "error",
+                    code: "preview_build_failed",
+                    message: error instanceof Error ? error.message : String(error),
+                };
+            }
+            started = true;
+        }
+        // The caller asked to be told where the build stands, not to be held here
+        // until it lands. Starting it above is the whole of the work; a second
+        // look would be the first iteration of a wait it declined.
+        if (!input.wait || nowMs(ctx) >= deadline) {
+            return { kind: "ok", value: { built: false } };
+        }
+        ctx.onProgress?.({
+            message: "Waiting for the preview build…",
+            type: "progress",
+        });
+        // Never sleep past the deadline: the ceiling reserves the tail of the
+        // host's patience for the answer to be written and read, and a full poll
+        // interval spent past it comes out of that reserve.
+        await sleepUntilAbort(Math.min(ctx.config.publishPollIntervalMs, deadline - nowMs(ctx)), ctx.signal);
+    }
+}
+export async function publishApp(ctx, input) {
+    const principalResult = await ensurePrincipal(ctx);
+    if (principalResult.kind !== "ok") {
+        return principalResult;
+    }
+    const principal = principalResult.value;
+    const resolved = await resolveApplicationId(ctx, principal, input.applicationId);
+    if (resolved.kind !== "ok") {
+        return resolved;
+    }
+    const applicationId = resolved.value;
+    return namingApplication(applicationId, await publishResolvedApp(ctx, { applicationId, input, principal }));
+}
+async function publishResolvedApp(ctx, args) {
+    const { applicationId, input, principal } = args;
+    // 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
+    // never committed could not publish at all.
+    let commitId = input.commitId?.trim();
+    if (!commitId) {
+        ctx.onProgress?.({ message: "Committing current work", type: "progress" });
+        try {
+            const commit = await ctx.server.createCommit({
+                apiKey: principal.apiKey,
+                applicationId,
+                branch: input.branch,
+                message: input.prompt,
+            });
+            commitId = commit.commitId;
+        }
+        catch (error) {
+            return {
+                kind: "error",
+                code: "commit_failed",
+                message: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    ctx.onProgress?.({ message: "Publishing application", type: "progress" });
+    try {
+        const deployment = await ctx.server.deployApplication({
+            apiKey: principal.apiKey,
+            applicationId,
+            commitId,
+        });
+        // Nothing is published on these two paths and nothing will be without
+        // someone acting, so neither can report as success.
+        if (deployment.status === "failed") {
+            ctx.sessionPeer.release?.(applicationId);
+            return {
+                kind: "error",
+                code: "publish_failed",
+                message: deployment.message ?? "The Superblocks API could not deploy the app.",
+            };
+        }
+        if (deployment.status === "awaiting_ack") {
+            ctx.sessionPeer.release?.(applicationId);
+            return {
+                kind: "error",
+                code: "publish_needs_acknowledgement",
+                message: `${deployment.message ?? "Policy checks passed with advisory findings."} Publishing is on hold until they are reviewed in Superblocks, or until this is published again with the findings acknowledged.`,
+            };
+        }
+        const deploymentId = deployment.deploymentId;
+        if (deployment.status === "queued") {
+            ctx.onProgress?.({
+                message: "Waiting for deploy…",
+                type: "progress",
+            });
+            const waited = await waitForDeployLive(ctx, {
+                apiKey: principal.apiKey,
+                applicationId,
+                commitId,
+            });
+            if (waited.kind !== "ok") {
+                ctx.sessionPeer.release?.(applicationId);
+                return waited;
+            }
+        }
+        await rememberApplication(ctx, principal, applicationId);
+        // Deploy finished — the held editor socket is no longer needed.
+        ctx.sessionPeer.release?.(applicationId);
+        const result = {
+            applicationId,
+            commitId,
+            deploymentId,
+            publishUrl: publishUrl(ctx.config, applicationId),
+            status: "deployed",
+        };
+        ctx.onProgress?.({
+            message: "Publish complete — app is live",
+            type: "completed",
+        });
+        return { kind: "ok", value: result };
+    }
+    catch (error) {
+        // Step up on the status the server actually returned. Matching words in the
+        // message instead would send a "token count exceeded" 500 or anything
+        // mentioning an author through a re-auth flow and bury the real failure.
+        if (error instanceof ServerHttpError &&
+            (error.status === 401 || error.status === 403)) {
+            return elicitStepUp(ctx, `stepup:${input.idempotencyKey}`, applicationId);
+        }
+        return {
+            kind: "error",
+            code: "publish_failed",
+            message: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+//# sourceMappingURL=lifecycle.js.map