@superblocksteam/gateway 2.0.0-SNAPSHOT.1d4c72c0ab174c21

package/dist/capture/classify-library-paint.js

@@ -0,0 +1,13 @@
+/**
+ * Preview sign-in copy is a failed live-library capture: the JPEG looks like
+ * a real page but is the auth wall. A white/empty canvas is returned as
+ * bytes so the agent can see it; screenshotBase64 now travels in MCP JSON.
+ */
+const SIGN_IN_COPY = /\b(?:sign[\s-]?in|log[\s-]?in|continue with google|continue with github)\b/i;
+export function classifyLibraryPaint(paint) {
+    if (SIGN_IN_COPY.test(paint.innerText)) {
+        return { kind: "skip", reason: "preview_sign_in" };
+    }
+    return { kind: "ok" };
+}
+//# sourceMappingURL=classify-library-paint.js.map

package/dist/capture/classify-library-paint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"classify-library-paint.js","sourceRoot":"","sources":["../../src/capture/classify-library-paint.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAiBH,MAAM,YAAY,GAChB,6EAA6E,CAAC;AAEhF,MAAM,UAAU,oBAAoB,CAAC,KAAmB;IACtD,IAAI,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC;QACvC,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC;IACrD,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AACxB,CAAC"}

package/dist/capture/host-mcp-scan.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Setup-time scan of an MCP client config for known host browser drivers.
+ *
+ * Gateway cannot see other MCP servers at tool-call time. This only inspects
+ * what is on disk (or about to be written). Config can lie: the server may
+ * fail to start or `npx` may miss PATH.
+ */
+export type HostBrowserMcpScan = {
+    found: boolean;
+    isolated: boolean;
+};
+/**
+ * Walks `mcpServers` (Claude Code, Cursor, Desktop). Superblocks Gateway is
+ * skipped so a self-scan cannot count as a host browser.
+ */
+export declare function scanHostBrowserMcp(config: unknown): HostBrowserMcpScan;

package/dist/capture/host-mcp-scan.js

@@ -0,0 +1,64 @@
+/**
+ * Setup-time scan of an MCP client config for known host browser drivers.
+ *
+ * Gateway cannot see other MCP servers at tool-call time. This only inspects
+ * what is on disk (or about to be written). Config can lie: the server may
+ * fail to start or `npx` may miss PATH.
+ */
+const HOST_BROWSER_MARKERS = [
+    "@playwright/mcp",
+    "agent-browser",
+    "chrome-devtools-mcp",
+    "puppeteer",
+];
+function tokensOf(entry) {
+    if (!entry || typeof entry !== "object") {
+        return [];
+    }
+    const record = entry;
+    const tokens = [];
+    if (typeof record.command === "string") {
+        tokens.push(record.command);
+    }
+    if (Array.isArray(record.args)) {
+        for (const arg of record.args) {
+            if (typeof arg === "string") {
+                tokens.push(arg);
+            }
+        }
+    }
+    return tokens;
+}
+function isHostBrowserDriver(tokens) {
+    return tokens.some((token) => HOST_BROWSER_MARKERS.some((marker) => token.includes(marker)));
+}
+/**
+ * Walks `mcpServers` (Claude Code, Cursor, Desktop). Superblocks Gateway is
+ * skipped so a self-scan cannot count as a host browser.
+ */
+export function scanHostBrowserMcp(config) {
+    if (!config || typeof config !== "object") {
+        return { found: false, isolated: false };
+    }
+    const mcpServers = config.mcpServers;
+    if (!mcpServers || typeof mcpServers !== "object") {
+        return { found: false, isolated: false };
+    }
+    let found = false;
+    let isolated = false;
+    for (const [name, entry] of Object.entries(mcpServers)) {
+        if (name === "superblocks") {
+            continue;
+        }
+        const tokens = tokensOf(entry);
+        if (!isHostBrowserDriver(tokens)) {
+            continue;
+        }
+        found = true;
+        if (tokens.includes("--isolated")) {
+            isolated = true;
+        }
+    }
+    return { found, isolated };
+}
+//# sourceMappingURL=host-mcp-scan.js.map

package/dist/capture/host-mcp-scan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-mcp-scan.js","sourceRoot":"","sources":["../../src/capture/host-mcp-scan.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,oBAAoB,GAAG;IAC3B,iBAAiB;IACjB,eAAe;IACf,qBAAqB;IACrB,WAAW;CACH,CAAC;AAOX,SAAS,QAAQ,CAAC,KAAc;IAC9B,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACxC,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,MAAM,MAAM,GAAG,KAAgC,CAAC;IAChD,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,IAAI,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;QACvC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC9B,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;QAC/B,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;YAC9B,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;gBAC5B,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACnB,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,mBAAmB,CAAC,MAAgB;IAC3C,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAC3B,oBAAoB,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAC9D,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAe;IAChD,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC1C,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;IAC3C,CAAC;IACD,MAAM,UAAU,GAAI,MAAmC,CAAC,UAAU,CAAC;IACnE,IAAI,CAAC,UAAU,IAAI,OAAO,UAAU,KAAK,QAAQ,EAAE,CAAC;QAClD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;IAC3C,CAAC;IAED,IAAI,KAAK,GAAG,KAAK,CAAC;IAClB,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CACxC,UAAqC,CACtC,EAAE,CAAC;QACF,IAAI,IAAI,KAAK,aAAa,EAAE,CAAC;YAC3B,SAAS;QACX,CAAC;QACD,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;QAC/B,IAAI,CAAC,mBAAmB,CAAC,MAAM,CAAC,EAAE,CAAC;YACjC,SAAS;QACX,CAAC;QACD,KAAK,GAAG,IAAI,CAAC;QACb,IAAI,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC;YAClC,QAAQ,GAAG,IAAI,CAAC;QAClB,CAAC;IACH,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;AAC7B,CAAC"}

package/dist/capture/library-parent-script.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Page source that makes a top-level pitcherURL visit look like the Code Mode
+ * iframe: mock `window.parent`, answer `sb-ready` / bootstrap / API auth in
+ * page JS so the host driver never sees the scoped JWT.
+ *
+ * Source text rather than a function handed to `addInitScript` because
+ * Playwright serializes functions and can drag bundler helpers (`__name`)
+ * into the page. Same rule as `buildEmbedHandshakeScript`.
+ */
+export type LibraryParentInitData = {
+    appId: string;
+    devServerAuthorization: string;
+    peerId: string;
+    userId?: string;
+    windowOriginUrl?: string;
+};
+export type LibraryParentBootstrapData = {
+    accessToken: string;
+    agents?: unknown[];
+    agentUrls?: string[];
+    appId: string;
+    devServerAuthorization: string;
+    featureFlags?: Record<string, unknown>;
+    orgId?: string;
+    profiles?: unknown;
+    token: string;
+    userEmail?: string;
+    userId: string;
+    windowOriginUrl?: string;
+};
+export type LibraryParentPayload = {
+    bootstrapData: LibraryParentBootstrapData;
+    initData: LibraryParentInitData;
+};
+export declare function buildLibraryParentScript(payload: LibraryParentPayload): string;

package/dist/capture/library-parent-script.js

@@ -0,0 +1,82 @@
+/**
+ * Page source that makes a top-level pitcherURL visit look like the Code Mode
+ * iframe: mock `window.parent`, answer `sb-ready` / bootstrap / API auth in
+ * page JS so the host driver never sees the scoped JWT.
+ *
+ * Source text rather than a function handed to `addInitScript` because
+ * Playwright serializes functions and can drag bundler helpers (`__name`)
+ * into the page. Same rule as `buildEmbedHandshakeScript`.
+ */
+export function buildLibraryParentScript(payload) {
+    return `(function () {
+    if (window.parent !== window) return;
+    var payload = ${JSON.stringify(payload)};
+    var init = payload.initData;
+    var bootstrap = payload.bootstrapData;
+    window.__sbGatewayCaptureEvents = [];
+    function record(message) {
+      if (message && typeof message.type === "string") {
+        window.__sbGatewayCaptureEvents.push({ type: message.type });
+      }
+    }
+    function send(message) {
+      window.postMessage(message, window.location.origin);
+    }
+    var mockParent = {
+      postMessage: function (message) {
+        record(message);
+        if (message && message.type === "sb-ready" && init) {
+        send({
+          payload: {
+            appId: init.appId,
+            devServerAuthorization: init.devServerAuthorization,
+            peerId: init.peerId,
+            userId: init.userId,
+            windowOriginUrl: init.windowOriginUrl,
+          },
+          startTime: Date.now(),
+          type: "sb-init",
+        });
+      }
+      if (message && message.type === "sb-editor-request-bootstrap" && bootstrap) {
+        send({
+          payload: bootstrap,
+          startTime: Date.now(),
+          type: "sb-bootstrap-response",
+        });
+        if (bootstrap.profiles) {
+          send({
+            payload: { global: { profiles: bootstrap.profiles } },
+            startTime: Date.now(),
+            type: "sb-global-sync",
+          });
+        }
+      }
+      if (message && message.type === "authenticate-api-request") {
+        var callbackId = message.payload && message.payload.callbackId;
+        if (callbackId) {
+          send({
+            callbackId: callbackId,
+            payload: {
+              tokens: {
+                accessToken: bootstrap.accessToken,
+                token: bootstrap.token,
+              },
+            },
+            type: "resolve-promise",
+          });
+        }
+      }
+    },
+    document: document,
+    location: window.location,
+    window: window,
+  };
+  Object.defineProperty(window, "parent", {
+    configurable: true,
+    value: mockParent,
+    writable: false,
+  });
+})();`;
+}
+//# sourceMappingURL=library-parent-script.js.map

package/dist/capture/library-parent-script.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"library-parent-script.js","sourceRoot":"","sources":["../../src/capture/library-parent-script.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA8BH,MAAM,UAAU,wBAAwB,CACtC,OAA6B;IAE7B,OAAO;;oBAEW,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAmErC,CAAC;AACP,CAAC"}

package/dist/capture/mode.d.ts

@@ -0,0 +1,29 @@
+/**
+ * How this Gateway can (or cannot) capture a live canvas or complete IdP.
+ *
+ * `host_mcp_configured` is a setup-time scan of the MCP client config. That
+ * file can lie: the listed server may fail to start or miss PATH. Tool results
+ * therefore keep hostBrowserTools as "unknown" rather than claiming this turn
+ * has Playwright.
+ */
+export declare const CAPTURE_MODES: readonly ["gateway_chromium", "host_mcp_configured", "urls_only"];
+export type CaptureMode = (typeof CAPTURE_MODES)[number];
+export declare function resolveCaptureMode(input: {
+    gatewayChromium: boolean;
+    hostMcpConfigured: boolean;
+}): CaptureMode;
+/**
+ * Human + machine summary for `mcp setup --debug`. Info goes to stderr so
+ * a redirected stdout report stays clean.
+ */
+export declare function formatCaptureModeSummary(input: {
+    isolated: boolean;
+    mode: CaptureMode;
+}): string;
+/**
+ * End-user copy for `mcp setup`. No machine keys, no internal error codes.
+ */
+export declare function formatCaptureModeUserSummary(input: {
+    isolated: boolean;
+    mode: CaptureMode;
+}): string | undefined;

package/dist/capture/mode.js

@@ -0,0 +1,65 @@
+/**
+ * How this Gateway can (or cannot) capture a live canvas or complete IdP.
+ *
+ * `host_mcp_configured` is a setup-time scan of the MCP client config. That
+ * file can lie: the listed server may fail to start or miss PATH. Tool results
+ * therefore keep hostBrowserTools as "unknown" rather than claiming this turn
+ * has Playwright.
+ */
+export const CAPTURE_MODES = [
+    "gateway_chromium",
+    "host_mcp_configured",
+    "urls_only",
+];
+export function resolveCaptureMode(input) {
+    if (input.hostMcpConfigured) {
+        return "host_mcp_configured";
+    }
+    if (input.gatewayChromium) {
+        return "gateway_chromium";
+    }
+    return "urls_only";
+}
+/**
+ * Human + machine summary for `mcp setup --debug`. Info goes to stderr so
+ * a redirected stdout report stays clean.
+ */
+export function formatCaptureModeSummary(input) {
+    const lines = [`capture.mode: ${input.mode}`];
+    switch (input.mode) {
+        case "host_mcp_configured":
+            lines.push("A host browser MCP is listed in this client config. Config on disk can lie if that server fails to start or misses PATH.");
+            break;
+        case "gateway_chromium":
+            lines.push("Gateway Playwright Chromium is present for preview screenshots. No host browser MCP was found. Config on disk can lie if a listed server fails to start. IdP step-up still returns needs_browser_driver until a host browser MCP (@playwright/mcp) is configured. Gateway Chromium cannot complete IdP.");
+            break;
+        case "urls_only":
+            lines.push("URLs only: no host browser MCP and no Gateway Chromium. Config on disk can lie if a listed server fails to start. Live-canvas capture will return needs_browser_driver; superblocks mcp setup --with-screenshots may enable live-canvas capture and does not clear IdP. Add @playwright/mcp for IdP step-up.");
+            break;
+    }
+    if (input.isolated) {
+        lines.push("Warning: a scanned browser MCP includes --isolated. IdP cookies will not survive browser_close.");
+    }
+    return lines.join("\n");
+}
+/**
+ * End-user copy for `mcp setup`. No machine keys, no internal error codes.
+ */
+export function formatCaptureModeUserSummary(input) {
+    const lines = [];
+    switch (input.mode) {
+        case "host_mcp_configured":
+            lines.push("Screenshots and browser sign-in will use Playwright MCP in your editor.");
+            break;
+        case "gateway_chromium":
+            break;
+        case "urls_only":
+            lines.push("App preview screenshots are off. Re-run: superblocks mcp setup --with-screenshots");
+            break;
+    }
+    if (input.isolated) {
+        lines.push("Warning: Playwright MCP uses --isolated, so sign-in cookies will not persist.");
+    }
+    return lines.length > 0 ? lines.join("\n") : undefined;
+}
+//# sourceMappingURL=mode.js.map

package/dist/capture/mode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mode.js","sourceRoot":"","sources":["../../src/capture/mode.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,kBAAkB;IAClB,qBAAqB;IACrB,WAAW;CACH,CAAC;AAIX,MAAM,UAAU,kBAAkB,CAAC,KAGlC;IACC,IAAI,KAAK,CAAC,iBAAiB,EAAE,CAAC;QAC5B,OAAO,qBAAqB,CAAC;IAC/B,CAAC;IACD,IAAI,KAAK,CAAC,eAAe,EAAE,CAAC;QAC1B,OAAO,kBAAkB,CAAC;IAC5B,CAAC;IACD,OAAO,WAAW,CAAC;AACrB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CAAC,KAGxC;IACC,MAAM,KAAK,GAAG,CAAC,iBAAiB,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;IAC9C,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;QACnB,KAAK,qBAAqB;YACxB,KAAK,CAAC,IAAI,CACR,0HAA0H,CAC3H,CAAC;YACF,MAAM;QACR,KAAK,kBAAkB;YACrB,KAAK,CAAC,IAAI,CACR,ySAAyS,CAC1S,CAAC;YACF,MAAM;QACR,KAAK,WAAW;YACd,KAAK,CAAC,IAAI,CACR,8SAA8S,CAC/S,CAAC;YACF,MAAM;IACV,CAAC;IACD,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;QACnB,KAAK,CAAC,IAAI,CACR,iGAAiG,CAClG,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,4BAA4B,CAAC,KAG5C;IACC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;QACnB,KAAK,qBAAqB;YACxB,KAAK,CAAC,IAAI,CACR,yEAAyE,CAC1E,CAAC;YACF,MAAM;QACR,KAAK,kBAAkB;YACrB,MAAM;QACR,KAAK,WAAW;YACd,KAAK,CAAC,IAAI,CACR,mFAAmF,CACpF,CAAC;YACF,MAAM;IACV,CAAC;IACD,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;QACnB,KAAK,CAAC,IAAI,CACR,+EAA+E,CAChF,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AACzD,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,148 @@
+export type GatewayConfig = {
+    deploymentEnvironmentName: string;
+    /** Cloud-Prem laptop agent: single-user process on a corp machine. */
+    localAgentMode: boolean;
+    /**
+     * Cloud-Prem Admin laptop agent: register Admin tools (integrations, apps,
+     * users, deploy_application, ...) only, and skip the Builder surface
+     * (start_app, edit_app, ...) that needs Playwright Chromium for preview
+     * screenshots and a live-edit session it never opens on this machine.
+     */
+    adminToolsOnly: boolean;
+    /**
+     * Where `upload_artifact` looks when it was handed only a file name or a
+     * sandbox path that does not exist on this host.
+     *
+     * A file attached to a chat lives in the model's own sandbox, so the path the
+     * model can quote is unreadable here even though the user downloaded the file
+     * to this machine. Exact absolute host paths are read directly.
+     */
+    importSearchDirs: string[];
+    /**
+     * How long the held socket's liveness beat must stay lost before the turn
+     * running on it is given up on. Exposed because this is the one knob that can
+     * end a turn the sandbox might still have finished: raising it far past the
+     * turn budget disables the behavior without a deploy.
+     */
+    beatLostGraceMs: number;
+    /**
+     * How long to hold an editor websocket after the last prompt before
+     * releasing it. Headless MCP needs the socket kept open so the sandbox
+     * startup watchdog does not tear the session down.
+     */
+    heldSessionIdleMs: number;
+    /**
+     * Grace period between a Clark turn settling and the held editor socket
+     * being dropped. Keeping it short leaves the user's own editor tab as the
+     * sandbox's only editor peer, which is the peer Clark's API calls run on.
+     */
+    heldSessionReleaseAfterTurnMs: number;
+    /**
+     * How long `start_app` / `edit_app` wait for Clark's generation turn after
+     * the prompt is acknowledged.
+     */
+    clarkTurnTimeoutMs: number;
+    /**
+     * Quiet window after Clark emits completed/idle before treating the job as
+     * done, so an acknowledgment that resumes generating is coalesced.
+     */
+    clarkSettleMs: number;
+    /**
+     * After Clark's job settles, how long to wait for the dev server to flush
+     * Clark's files before giving up on checkpointing them.
+     */
+    clarkReadyWaitMs: number;
+    /**
+     * Opt-in: hands Clark a browser context so its Playwright test tools are
+     * registered on headless turns. Off by default because that launches
+     * Chromium inside the live-edit pod (3Gi), which OOMKills generation.
+     * Gateway preview screenshots use laptop Chromium and ignore this flag.
+     * Set GATEWAY_CLARK_TESTING_ENABLED=true only when the sandbox has
+     * Chromium headroom and you want Clark to drive browser_* tools.
+     */
+    clarkTestingEnabled: boolean;
+    /**
+     * Least time a single `check_app_progress` call collects Clark activity for
+     * before answering, so a talkative build comes back in whole thoughts rather
+     * than a line at a time. Only ever spends part of
+     * {@link GatewayConfig.clarkProgressWaitMs}, and never delays a finished
+     * turn: a decision waiting on a human is what the poll exists to surface.
+     * Zero answers on the first line.
+     */
+    clarkProgressFloorMs: number;
+    /**
+     * How long a single `check_app_progress` call waits for new Clark activity
+     * before answering with what it has. Sized to stay inside a client's tool
+     * timeout so the caller can poll again rather than lose the turn.
+     */
+    clarkProgressWaitMs: number;
+    /**
+     * How long a build may run without saying anything before a poll warns that
+     * it has gone quiet. Nonterminal and well under
+     * {@link GatewayConfig.clarkTurnTimeoutMs}, so the caller hears about the
+     * silence long before the turn is given up on.
+     */
+    clarkStallHintAfterMs: number;
+    /**
+     * Ceiling on any single host-facing call, whatever it is waiting for.
+     *
+     * Hosts abandon a tool call after their own timeout, and a host that
+     * advertises progress notifications is under no obligation to act on them —
+     * so a call cannot be allowed to run past this on the strength of having
+     * sent progress. Anything still unfinished here returns its current status
+     * and a cursor instead of holding the request open.
+     */
+    hostCallCeilingMs: number;
+    /**
+     * How long `publish_app` polls a queued deploy before giving up.
+     */
+    publishWaitTimeoutMs: number;
+    /**
+     * How long a single `check_publish_progress` call watches the rollout
+     * before answering with its current state. Sized to stay inside a client's
+     * tool timeout so the caller can poll again rather than lose the turn.
+     */
+    publishProgressWaitMs: number;
+    /**
+     * Interval between deploy-status polls while waiting for a queued publish.
+     */
+    publishPollIntervalMs: number;
+    /**
+     * Preferred integration profile key. When unset or `default`, Gateway
+     * picks a real org profile (staging → dev → production → first).
+     */
+    profileKey: string;
+    serverUrl: string;
+    turnTtlMs: number;
+    uiBaseUrl: string;
+    /**
+     * Base URL of the deployed-app shell / CDN used for JWT preview links.
+     * Local default is the csb-mock CDN. May include `__SB_APP_ID`.
+     */
+    deployedShellBaseUrl: string | undefined;
+    /**
+     * Optional https front door for the deployed shell (viewer/CDN tunnel).
+     * When set, Claude Desktop can openLink preview URLs. Stdio Gateway does
+     * not bind HTTP, so this is never a gateway origin.
+     */
+    publicViewerBaseUrl: string | undefined;
+    /**
+     * When true, always attempt a headless screenshot even if previewUrl is
+     * already https (demo / debugging).
+     */
+    forcePreviewScreenshot: boolean;
+    /**
+     * Setup-time scan: a host browser MCP (@playwright/mcp, chrome-devtools,
+     * puppeteer, agent-browser) was listed in the client config. Config on disk
+     * can lie; tool results keep hostBrowserTools as "unknown".
+     */
+    captureHostMcp: boolean;
+    /** Scanned host browser MCP args included --isolated (IdP cookies die). */
+    captureHostIsolated: boolean;
+    /**
+     * Test override for whether Playwright Chromium is on disk. Unset in
+     * production: capabilities probe without installing.
+     */
+    gatewayChromiumPresent?: boolean;
+};
+export declare function loadConfig(env?: NodeJS.ProcessEnv): GatewayConfig;

package/dist/config.js

@@ -0,0 +1,111 @@
+import { homedir } from "node:os";
+import path from "node:path";
+import { DEFAULT_STEP_UP_TTL_MS } from "./stores/types.js";
+/**
+ * Reads an env var, treating blank as absent.
+ *
+ * Every optional var the Tilt profile passes is written as
+ * `os.getenv(name, '')`, and `FOO= cmd` sets an empty string too. Without this,
+ * `??` happily accepts `""` and it reaches config as a real value — a zero
+ * turn TTL, an empty UI URL that then fails URL construction.
+ */
+function readEnv(env, name) {
+    return env[name]?.trim() || undefined;
+}
+function required(env, name, fallback) {
+    const value = readEnv(env, name) ?? fallback;
+    if (!value) {
+        throw new Error(`Missing required env var: ${name}`);
+    }
+    return value;
+}
+function explicitEnvironmentName(env) {
+    return (readEnv(env, "DEPLOYMENT_ENVIRONMENT_NAME") ?? readEnv(env, "NODE_ENV"));
+}
+/**
+ * Where a file the user just got hold of actually sits: the browser's download
+ * folder, the desktop, or a temp directory, which is where Claude's own
+ * downloads land. `/tmp` and `/private/tmp` cover the macOS `/tmp` symlink both
+ * ways; `/private/var/folders` covers Claude's realpath'd temp dirs without
+ * opening the rest of `/private` during the fallback search.
+ */
+function resolveImportSearchDirs(env) {
+    const configured = readEnv(env, "GATEWAY_IMPORT_SEARCH_DIRS");
+    if (configured) {
+        return configured
+            .split(",")
+            .map((dir) => dir.trim())
+            .filter(Boolean);
+    }
+    const home = homedir();
+    return [
+        path.join(home, "Downloads"),
+        path.join(home, "Desktop"),
+        "/tmp",
+        "/private/tmp",
+        "/private/var/folders",
+    ];
+}
+function isTruthyFlag(value) {
+    if (!value) {
+        return false;
+    }
+    const normalized = value.toLowerCase();
+    return normalized === "1" || normalized === "true" || normalized === "yes";
+}
+export function loadConfig(env = process.env) {
+    const explicitEnvironment = explicitEnvironmentName(env);
+    const localAgentMode = isTruthyFlag(readEnv(env, "GATEWAY_LOCAL_AGENT"));
+    const adminToolsOnly = isTruthyFlag(readEnv(env, "GATEWAY_ADMIN_TOOLS_ONLY"));
+    // Never default the label to "local". A deployment that forgot to set the
+    // variable is not local, and anything reading the label would otherwise
+    // relax itself on the strength of a default.
+    const deploymentEnvironmentName = explicitEnvironment ?? "unknown";
+    // One origin standing in for both the server and the UI, for environments
+    // that serve them together - an ee deployment, a shared dev box. The local
+    // stack splits them across ports and sets each explicitly, and those still
+    // win: this is only the fallback beneath them.
+    const baseUrl = readEnv(env, "GATEWAY_BASE_URL");
+    return {
+        deploymentEnvironmentName,
+        localAgentMode,
+        adminToolsOnly,
+        importSearchDirs: resolveImportSearchDirs(env),
+        beatLostGraceMs: Number(readEnv(env, "GATEWAY_BEAT_LOST_GRACE_MS") ?? String(60_000)),
+        heldSessionIdleMs: Number(readEnv(env, "GATEWAY_HELD_SESSION_IDLE_MS") ?? String(30 * 60 * 1000)),
+        heldSessionReleaseAfterTurnMs: Number(readEnv(env, "GATEWAY_HELD_SESSION_RELEASE_AFTER_TURN_MS") ??
+            String(30_000)),
+        clarkTurnTimeoutMs: Number(readEnv(env, "GATEWAY_CLARK_TURN_TIMEOUT_MS") ?? String(10 * 60 * 1000)),
+        clarkSettleMs: Number(readEnv(env, "GATEWAY_CLARK_SETTLE_MS") ?? String(12_000)),
+        clarkReadyWaitMs: Number(readEnv(env, "GATEWAY_CLARK_READY_WAIT_MS") ?? String(30_000)),
+        clarkTestingEnabled: readEnv(env, "GATEWAY_CLARK_TESTING_ENABLED") === "true" ||
+            readEnv(env, "GATEWAY_CLARK_TESTING_ENABLED") === "1",
+        // clarkProgressFloorMs and clarkProgressWaitMs are used to control the polling behavior
+        // of the progress poll in the check_app_progress tool.
+        // Minimum time a progress poll waits to collect activity for before it answers.
+        // If the turn is finished (ex: needs a user decision), it will answer immediately.
+        clarkProgressFloorMs: Number(readEnv(env, "GATEWAY_CLARK_PROGRESS_FLOOR_MS") ?? String(20_000)),
+        // Maximum time a progress poll waits to collect activity for before it answers.
+        // This is the ceiling on the poll. If we reach the ceiling,
+        // we will answer with what we have (can be empty if no activity).
+        clarkProgressWaitMs: Number(readEnv(env, "GATEWAY_CLARK_PROGRESS_WAIT_MS") ?? String(25_000)),
+        clarkStallHintAfterMs: Number(readEnv(env, "GATEWAY_CLARK_STALL_HINT_AFTER_MS") ?? String(120_000)),
+        // Under the 60s most MCP hosts allow a tool call, with room for the
+        // response to be written and read.
+        hostCallCeilingMs: Number(readEnv(env, "GATEWAY_HOST_CALL_CEILING_MS") ?? String(50_000)),
+        publishWaitTimeoutMs: Number(readEnv(env, "GATEWAY_PUBLISH_WAIT_TIMEOUT_MS") ?? String(2 * 60 * 1000)),
+        publishProgressWaitMs: Number(readEnv(env, "GATEWAY_PUBLISH_PROGRESS_WAIT_MS") ?? String(25_000)),
+        publishPollIntervalMs: Number(readEnv(env, "GATEWAY_PUBLISH_POLL_INTERVAL_MS") ?? "2000"),
+        profileKey: required(env, "GATEWAY_PROFILE_KEY", "default"),
+        serverUrl: required(env, "SUPERBLOCKS_SERVER_URL", readEnv(env, "GATEWAY_SERVER_URL") ?? baseUrl ?? "http://localhost:8080"),
+        turnTtlMs: Number(readEnv(env, "GATEWAY_TURN_TTL_MS") ?? DEFAULT_STEP_UP_TTL_MS),
+        uiBaseUrl: required(env, "GATEWAY_UI_BASE_URL", baseUrl ?? "http://localhost:3000"),
+        deployedShellBaseUrl: readEnv(env, "GATEWAY_DEPLOYED_SHELL_BASE_URL"),
+        publicViewerBaseUrl: readEnv(env, "GATEWAY_PUBLIC_VIEWER_BASE_URL"),
+        forcePreviewScreenshot: readEnv(env, "GATEWAY_FORCE_PREVIEW_SCREENSHOT") === "true" ||
+            readEnv(env, "GATEWAY_FORCE_PREVIEW_SCREENSHOT") === "1",
+        captureHostMcp: isTruthyFlag(readEnv(env, "GATEWAY_CAPTURE_HOST_MCP")),
+        captureHostIsolated: isTruthyFlag(readEnv(env, "GATEWAY_CAPTURE_HOST_ISOLATED")),
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/debug.d.ts

@@ -0,0 +1,2 @@
+export declare const gatewayDebug: import("util").DebugLogger;
+export declare function gatewayDebugStack(message: string, attributes?: Record<string, unknown>): void;

package/dist/debug.js

@@ -0,0 +1,9 @@
+import { debuglog } from "node:util";
+export const gatewayDebug = debuglog("gateway");
+export function gatewayDebugStack(message, attributes = {}) {
+    if (!gatewayDebug.enabled) {
+        return;
+    }
+    gatewayDebug(message, { ...attributes, stack: new Error().stack });
+}
+//# sourceMappingURL=debug.js.map

package/dist/debug.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.js","sourceRoot":"","sources":["../src/debug.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAErC,MAAM,CAAC,MAAM,YAAY,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC;AAEhD,MAAM,UAAU,iBAAiB,CAC/B,OAAe,EACf,aAAsC,EAAE;IAExC,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE,CAAC;QAC1B,OAAO;IACT,CAAC;IACD,YAAY,CAAC,OAAO,EAAE,EAAE,GAAG,UAAU,EAAE,KAAK,EAAE,IAAI,KAAK,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC;AACrE,CAAC"}

package/dist/deps.d.ts

@@ -0,0 +1,38 @@
+import type { GatewayConfig } from "./config.js";
+import type { AppState } from "./sabs/app-state.js";
+import type { SessionPeer } from "./sabs/session-peer.js";
+import type { SuperblocksServerClient } from "./server/client.js";
+import type { ProgressStore, RecentAppStore, StepUpTurnStore } from "./stores/types.js";
+import type { McpClientTelemetry } from "./telemetry/mcp-client.js";
+/**
+ * Runtime collaborators for one Gateway process. Stdio MCP is the only
+ * production transport; tests build the same bag and connect an in-memory
+ * client.
+ */
+export type AppDeps = {
+    /** Per-application facts shared by the session peer and the capabilities. */
+    appState: AppState;
+    config: GatewayConfig;
+    /**
+     * Personal API key of the already-logged-in Superblocks CLI user.
+     * Gateway tools call the control plane as this identity.
+     */
+    cliApiKey: string;
+    /**
+     * Superblocks user already resolved for this CLI session. When present,
+     * capabilities skip `/users/me` (ENG-5806). When absent, the first tool
+     * call resolves it through the guarded identity read.
+     */
+    cliIdentity?: {
+        email?: string;
+        organizationId: string;
+        userId: string;
+    };
+    /** When each build last spoke, and whether its silence was reported. */
+    progress: ProgressStore;
+    recentApps: RecentAppStore;
+    mcpTelemetry?: Pick<McpClientTelemetry, "runTool" | "setOrganizationId">;
+    server: SuperblocksServerClient;
+    sessionPeer: SessionPeer;
+    stepUpTurns: StepUpTurnStore;
+};

package/dist/deps.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=deps.js.map