@superblocksteam/gateway 2.0.155-next.0

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { loadConfig } from "./config.js";
+export { scanHostBrowserMcp } from "./capture/host-mcp-scan.js";
+export { formatCaptureModeSummary, resolveCaptureMode, } from "./capture/mode.js";
+export { editApp, importApp, IMPORT_ZIP_MAX_BYTES, previewApp, publishApp, startApp, } from "./capabilities/lifecycle.js";
+export { GATEWAY_FAULT_EXIT_CODE } from "./process/fault-barrier.js";
+export { startStdioGateway } from "./start.js";
+export type { StartGatewayOptions, StartedGateway } from "./start.js";
+export { ensurePlaywrightChromium, playwrightChromiumPresent, } from "./playwright/ensure-chromium.js";
+export { MemoryRecentAppStore } from "./resume/memory-recent-app-store.js";
+export { MemoryTurnStore } from "./resume/memory-turn-store.js";

package/dist/index.js

@@ -0,0 +1,10 @@
+export { loadConfig } from "./config.js";
+export { scanHostBrowserMcp } from "./capture/host-mcp-scan.js";
+export { formatCaptureModeSummary, resolveCaptureMode, } from "./capture/mode.js";
+export { editApp, importApp, IMPORT_ZIP_MAX_BYTES, previewApp, publishApp, startApp, } from "./capabilities/lifecycle.js";
+export { GATEWAY_FAULT_EXIT_CODE } from "./process/fault-barrier.js";
+export { startStdioGateway } from "./start.js";
+export { ensurePlaywrightChromium, playwrightChromiumPresent, } from "./playwright/ensure-chromium.js";
+export { MemoryRecentAppStore } from "./resume/memory-recent-app-store.js";
+export { MemoryTurnStore } from "./resume/memory-turn-store.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,EACL,wBAAwB,EACxB,kBAAkB,GACnB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,OAAO,EACP,SAAS,EACT,oBAAoB,EACpB,UAAU,EACV,UAAU,EACV,QAAQ,GACT,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AACrE,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE/C,OAAO,EACL,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,oBAAoB,EAAE,MAAM,qCAAqC,CAAC;AAC3E,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC"}

package/dist/integrations/filters.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Whether Clark's tool surface can use this plugin id.
+ *
+ * Fullstack apps (what Gateway creates) are SDK-enabled, so ad-hoc REST/GraphQL
+ * variants are excluded; preconfigured `restapiintegration` /
+ * `graphqlintegration` stay.
+ */
+export declare function integrationIsToolSupported(pluginId: string, sdkApiEnabled?: boolean): boolean;

package/dist/integrations/filters.js

@@ -0,0 +1,40 @@
+/**
+ * Plugin ids Clark cannot use as tools. Mirrored from the UI's
+ * `integration-filters` so this package does not depend on `packages/ui`.
+ */
+const UNSUPPORTED_INTEGRATION_TYPES = new Set([
+    "confluentkafka",
+    "email",
+    "googlesheets",
+    "kafka",
+    "kinesis",
+    "openai",
+    "redis",
+    "redpanda",
+    "superblocks-ocr",
+    "workflow",
+]);
+/** Ad-hoc types filtered out for SDK-enabled (fullstack) apps. */
+const AD_HOC_INTEGRATION_TYPES = new Set([
+    "graphql",
+    "javascript",
+    "python",
+    "restapi",
+]);
+/**
+ * Whether Clark's tool surface can use this plugin id.
+ *
+ * Fullstack apps (what Gateway creates) are SDK-enabled, so ad-hoc REST/GraphQL
+ * variants are excluded; preconfigured `restapiintegration` /
+ * `graphqlintegration` stay.
+ */
+export function integrationIsToolSupported(pluginId, sdkApiEnabled = true) {
+    if (UNSUPPORTED_INTEGRATION_TYPES.has(pluginId)) {
+        return false;
+    }
+    if (sdkApiEnabled && AD_HOC_INTEGRATION_TYPES.has(pluginId)) {
+        return false;
+    }
+    return true;
+}
+//# sourceMappingURL=filters.js.map

package/dist/integrations/filters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filters.js","sourceRoot":"","sources":["../../src/integrations/filters.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,6BAA6B,GAAG,IAAI,GAAG,CAAC;IAC5C,gBAAgB;IAChB,OAAO;IACP,cAAc;IACd,OAAO;IACP,SAAS;IACT,QAAQ;IACR,OAAO;IACP,UAAU;IACV,iBAAiB;IACjB,UAAU;CACX,CAAC,CAAC;AAEH,kEAAkE;AAClE,MAAM,wBAAwB,GAAG,IAAI,GAAG,CAAC;IACvC,SAAS;IACT,YAAY;IACZ,QAAQ;IACR,SAAS;CACV,CAAC,CAAC;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,0BAA0B,CACxC,QAAgB,EAChB,aAAa,GAAG,IAAI;IAEpB,IAAI,6BAA6B,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;QAChD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,aAAa,IAAI,wBAAwB,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC5D,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/integrations/map.d.ts

@@ -0,0 +1,26 @@
+import type { PromptContextIntegration } from "@superblocksteam/library-shared/types";
+/** Minimal fields needed from `GET /api/v1/integrations/superset`. */
+export type SupersetIntegrationRow = {
+    configurations?: Array<{
+        configuration?: {
+            openApiSpecRef?: string;
+        };
+        isDefault?: boolean;
+    }>;
+    id: string;
+    managedBy?: string | null;
+    name: string;
+    permissions?: string[];
+    pluginId: string;
+    readOnly?: boolean;
+};
+/**
+ * Maps a superset row to the shape Clark expects on `aiGetIntegrations`
+ * (no metadata).
+ */
+export declare function toPromptContextIntegrationSummary(row: SupersetIntegrationRow): Omit<PromptContextIntegration, "metadata">;
+/**
+ * BUILD-filtered, tool-supported integrations for Clark's discovery list.
+ */
+export declare function listIntegrationsForClark(rows: SupersetIntegrationRow[], sdkApiEnabled?: boolean): Omit<PromptContextIntegration, "metadata">[];
+export declare function toPromptContextIntegration(row: SupersetIntegrationRow, metadata?: Record<string, unknown>): PromptContextIntegration;

package/dist/integrations/map.js

@@ -0,0 +1,43 @@
+import { integrationIsToolSupported } from "./filters.js";
+function hasBuildPermission(row) {
+    if (row.permissions && row.permissions.length > 0) {
+        return row.permissions.includes("build");
+    }
+    // Legacy rows without RBAC annotations: BUILD means not read-only.
+    return !row.readOnly;
+}
+function openApiSpecRef(row) {
+    const fromConfig = row.configurations?.find((c) => c.isDefault)?.configuration
+        ?.openApiSpecRef;
+    return fromConfig || undefined;
+}
+/**
+ * Maps a superset row to the shape Clark expects on `aiGetIntegrations`
+ * (no metadata).
+ */
+export function toPromptContextIntegrationSummary(row) {
+    return {
+        displayName: row.name,
+        id: row.id,
+        ...(row.managedBy != null ? { managedBy: row.managedBy } : {}),
+        name: row.name,
+        ...(openApiSpecRef(row) ? { openApiSpecRef: openApiSpecRef(row) } : {}),
+        type: row.pluginId,
+    };
+}
+/**
+ * BUILD-filtered, tool-supported integrations for Clark's discovery list.
+ */
+export function listIntegrationsForClark(rows, sdkApiEnabled = true) {
+    return rows
+        .filter(hasBuildPermission)
+        .filter((row) => integrationIsToolSupported(row.pluginId, sdkApiEnabled))
+        .map(toPromptContextIntegrationSummary);
+}
+export function toPromptContextIntegration(row, metadata = {}) {
+    return {
+        ...toPromptContextIntegrationSummary(row),
+        metadata,
+    };
+}
+//# sourceMappingURL=map.js.map

package/dist/integrations/map.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"map.js","sourceRoot":"","sources":["../../src/integrations/map.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAgB1D,SAAS,kBAAkB,CAAC,GAA2B;IACrD,IAAI,GAAG,CAAC,WAAW,IAAI,GAAG,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClD,OAAO,GAAG,CAAC,WAAW,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IAC3C,CAAC;IACD,mEAAmE;IACnE,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC;AACvB,CAAC;AAED,SAAS,cAAc,CAAC,GAA2B;IACjD,MAAM,UAAU,GAAG,GAAG,CAAC,cAAc,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,EAAE,aAAa;QAC5E,EAAE,cAAc,CAAC;IACnB,OAAO,UAAU,IAAI,SAAS,CAAC;AACjC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iCAAiC,CAC/C,GAA2B;IAE3B,OAAO;QACL,WAAW,EAAE,GAAG,CAAC,IAAI;QACrB,EAAE,EAAE,GAAG,CAAC,EAAE;QACV,GAAG,CAAC,GAAG,CAAC,SAAS,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9D,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,GAAG,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,cAAc,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACvE,IAAI,EAAE,GAAG,CAAC,QAAQ;KACnB,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,wBAAwB,CACtC,IAA8B,EAC9B,aAAa,GAAG,IAAI;IAEpB,OAAO,IAAI;SACR,MAAM,CAAC,kBAAkB,CAAC;SAC1B,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,0BAA0B,CAAC,GAAG,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC;SACxE,GAAG,CAAC,iCAAiC,CAAC,CAAC;AAC5C,CAAC;AAED,MAAM,UAAU,0BAA0B,CACxC,GAA2B,EAC3B,WAAoC,EAAE;IAEtC,OAAO;QACL,GAAG,iCAAiC,CAAC,GAAG,CAAC;QACzC,QAAQ;KACT,CAAC;AACJ,CAAC"}

package/dist/integrations/profile-key.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Picks which Superblocks integration profile key Gateway should send to the
+ * orchestrator. Local orgs almost never have a profile literally named
+ * `default` — they use `dev` / `staging` / `production` — and a wrong key
+ * surfaces as orchestrator "Invalid profile specified" / HTTP 500.
+ */
+export type OrgProfileRow = {
+    allowedInEditor?: boolean;
+    key: string;
+};
+/**
+ * Resolves an editor profile key from the org's profile list.
+ *
+ * - Honors `preferred` when it exists on the org (and is not the legacy
+ *   placeholder `default`).
+ * - Otherwise prefers staging → dev → production, then the first listed key.
+ * - When the org list is unavailable, falls back to `preferred` or `staging`.
+ */
+export declare function pickEditorProfileKey(preferred: string | undefined, profiles: OrgProfileRow[]): string;

package/dist/integrations/profile-key.js

@@ -0,0 +1,35 @@
+/**
+ * Picks which Superblocks integration profile key Gateway should send to the
+ * orchestrator. Local orgs almost never have a profile literally named
+ * `default` — they use `dev` / `staging` / `production` — and a wrong key
+ * surfaces as orchestrator "Invalid profile specified" / HTTP 500.
+ */
+const AUTO_PREFERRED_KEYS = ["staging", "dev", "production"];
+/**
+ * Resolves an editor profile key from the org's profile list.
+ *
+ * - Honors `preferred` when it exists on the org (and is not the legacy
+ *   placeholder `default`).
+ * - Otherwise prefers staging → dev → production, then the first listed key.
+ * - When the org list is unavailable, falls back to `preferred` or `staging`.
+ */
+export function pickEditorProfileKey(preferred, profiles) {
+    const configured = preferred?.trim() ?? "";
+    const isAuto = !configured || configured.toLowerCase() === "default";
+    const keys = profiles
+        .map((profile) => profile.key?.trim())
+        .filter((key) => Boolean(key));
+    if (!isAuto && keys.includes(configured)) {
+        return configured;
+    }
+    if (keys.length === 0) {
+        return isAuto ? "staging" : configured;
+    }
+    for (const candidate of AUTO_PREFERRED_KEYS) {
+        if (keys.includes(candidate)) {
+            return candidate;
+        }
+    }
+    return keys[0] ?? "staging";
+}
+//# sourceMappingURL=profile-key.js.map

package/dist/integrations/profile-key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile-key.js","sourceRoot":"","sources":["../../src/integrations/profile-key.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,mBAAmB,GAAG,CAAC,SAAS,EAAE,KAAK,EAAE,YAAY,CAAU,CAAC;AAOtE;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAClC,SAA6B,EAC7B,QAAyB;IAEzB,MAAM,UAAU,GAAG,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAC3C,MAAM,MAAM,GAAG,CAAC,UAAU,IAAI,UAAU,CAAC,WAAW,EAAE,KAAK,SAAS,CAAC;IACrE,MAAM,IAAI,GAAG,QAAQ;SAClB,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC;SACrC,MAAM,CAAC,CAAC,GAAG,EAAiB,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;IAEhD,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;QACzC,OAAO,UAAU,CAAC;IACpB,CAAC;IAED,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC;IACzC,CAAC;IAED,KAAK,MAAM,SAAS,IAAI,mBAAmB,EAAE,CAAC;QAC5C,IAAI,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;YAC7B,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC,CAAC,CAAC,IAAI,SAAS,CAAC;AAC9B,CAAC"}

package/dist/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/main.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+console.error("This process speaks MCP over stdio as the Superblocks CLI user. Run: superblocks gateway serve");
+process.exit(1);
+export {};
+//# sourceMappingURL=main.js.map

package/dist/main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":";AAEA,OAAO,CAAC,KAAK,CACX,gGAAgG,CACjG,CAAC;AACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC"}

package/dist/orchestrator/client.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Thin HTTP client for the Superblocks orchestrator / agent used by Gateway
+ * when Clark asks the editor peer to run APIs or load integration metadata.
+ *
+ * The base URL is discovered per session from Server `/users/me` agents
+ * (same filters as the browser), not operator-picked env. Scoped JWTs travel
+ * in `x-superblocks-authorization`, matching the editor's execute path.
+ */
+export declare class OrchestratorHttpError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+/**
+ * Credential identifying who is asking, sent as `Authorization`.
+ *
+ * The orchestrator forwards this header verbatim when it fetches the app's
+ * code bundle from the Superblocks server, and that route authenticates it in
+ * its own right: a Superblocks JWT presented there is checked against
+ * `apps:view`, which a live-edit session's `apps:update` token does not carry.
+ * Sending the API key instead mirrors the browser editor, which puts its user
+ * session token here and keeps the scoped JWT to
+ * `x-superblocks-authorization`.
+ */
+type RequesterCredential = {
+    apiKey?: string;
+};
+export type SdkApiV3ExecuteInput = RequesterCredential & {
+    applicationId: string;
+    branchName?: string;
+    entryPoint: string;
+    exportName?: string;
+    inputs: Record<string, unknown>;
+    profileKey?: string;
+    scopedToken: string;
+};
+export type V2ExecuteInput = RequesterCredential & {
+    body: Record<string, unknown>;
+    profileKey?: string;
+    scopedToken: string;
+};
+export type MetadataInput = RequesterCredential & {
+    integrationId: string;
+    profileKey: string;
+    scopedToken: string;
+    stepConfiguration?: Record<string, unknown>;
+};
+export type OrchestratorClient = {
+    executeSdkApiV3(input: SdkApiV3ExecuteInput): Promise<unknown>;
+    executeV2Api(input: V2ExecuteInput): Promise<unknown>;
+    getMetadata(input: MetadataInput): Promise<Record<string, unknown>>;
+};
+export declare class HttpOrchestratorClient implements OrchestratorClient {
+    private readonly orchestratorUrl;
+    private readonly timeoutMs;
+    constructor(orchestratorUrl: string, timeoutMs?: number);
+    private baseUrl;
+    private post;
+    executeSdkApiV3(input: SdkApiV3ExecuteInput): Promise<unknown>;
+    executeV2Api(input: V2ExecuteInput): Promise<unknown>;
+    getMetadata(input: MetadataInput): Promise<Record<string, unknown>>;
+}
+export {};

package/dist/orchestrator/client.js

@@ -0,0 +1,160 @@
+/**
+ * Thin HTTP client for the Superblocks orchestrator / agent used by Gateway
+ * when Clark asks the editor peer to run APIs or load integration metadata.
+ *
+ * The base URL is discovered per session from Server `/users/me` agents
+ * (same filters as the browser), not operator-picked env. Scoped JWTs travel
+ * in `x-superblocks-authorization`, matching the editor's execute path.
+ */
+const SUPERBLOCKS_AUTHORIZATION_HEADER = "x-superblocks-authorization";
+/** Protobuf `api.v1.ViewMode.EDIT` — same numeric the UI sends on v3/execute. */
+const ORCHESTRATOR_VIEW_MODE_EDIT = 1;
+const DEFAULT_TIMEOUT_MS = 120_000;
+const MAX_DETAIL_LENGTH = 300;
+function detailSuffix(body) {
+    if (!body.trim()) {
+        return "";
+    }
+    let detail = body;
+    try {
+        const parsed = JSON.parse(body);
+        if (parsed && typeof parsed === "object") {
+            const record = parsed;
+            const message = record.responseMeta?.message ?? record.message ?? record.error;
+            if (typeof message === "string" && message.trim()) {
+                detail = message;
+            }
+        }
+    }
+    catch {
+        // Not JSON — fall back to the raw body.
+    }
+    return ` — ${detail.trim().slice(0, MAX_DETAIL_LENGTH)}`;
+}
+export class OrchestratorHttpError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = "OrchestratorHttpError";
+    }
+}
+export class HttpOrchestratorClient {
+    orchestratorUrl;
+    timeoutMs;
+    constructor(orchestratorUrl, timeoutMs = DEFAULT_TIMEOUT_MS) {
+        this.orchestratorUrl = orchestratorUrl;
+        this.timeoutMs = timeoutMs;
+    }
+    baseUrl() {
+        return this.orchestratorUrl.replace(/\/$/, "");
+    }
+    async post(path, input) {
+        const url = new URL(`${this.baseUrl()}/${path.replace(/^\//, "")}`);
+        for (const [key, value] of Object.entries(input.query ?? {})) {
+            url.searchParams.set(key, value);
+        }
+        const headers = new Headers({
+            Authorization: `Bearer ${input.apiKey ?? input.scopedToken}`,
+            "Content-Type": "application/json",
+            [SUPERBLOCKS_AUTHORIZATION_HEADER]: `Bearer ${input.scopedToken}`,
+        });
+        if (input.profileKey) {
+            headers.set("x-superblocks-profile", input.profileKey);
+        }
+        let response;
+        try {
+            response = await fetch(url, {
+                body: JSON.stringify(input.body),
+                headers,
+                method: "POST",
+                signal: AbortSignal.timeout(this.timeoutMs),
+            });
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === "TimeoutError") {
+                throw new Error(`Orchestrator ${path} timed out after ${this.timeoutMs}ms`);
+            }
+            throw error;
+        }
+        if (!response.ok) {
+            if (response.status === 401) {
+                console.warn("gateway orchestrator auth rejected", {
+                    path,
+                    profileKey: input.profileKey,
+                    status: response.status,
+                });
+            }
+            throw new OrchestratorHttpError(`Orchestrator ${path} failed: ${response.status}${detailSuffix(await response.text().catch(() => ""))}`, response.status);
+        }
+        if (response.status === 204) {
+            return undefined;
+        }
+        const text = await response.text();
+        if (!text.trim()) {
+            return undefined;
+        }
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+    async executeSdkApiV3(input) {
+        return this.post("v3/execute", {
+            apiKey: input.apiKey,
+            body: {
+                applicationId: input.applicationId,
+                entryPoint: input.entryPoint,
+                inputs: input.inputs,
+                viewMode: ORCHESTRATOR_VIEW_MODE_EDIT,
+                ...(input.exportName ? { exportName: input.exportName } : {}),
+                ...(input.branchName ? { branchName: input.branchName } : {}),
+                ...(input.profileKey
+                    ? {
+                        profile: {
+                            key: input.profileKey,
+                            name: input.profileKey,
+                        },
+                    }
+                    : {}),
+            },
+            profileKey: input.profileKey,
+            scopedToken: input.scopedToken,
+        });
+    }
+    async executeV2Api(input) {
+        return this.post("v2/execute", {
+            apiKey: input.apiKey,
+            body: input.body,
+            profileKey: input.profileKey,
+            query: {
+                eventType: "ON_CLARK_REQUEST",
+                viewMode: "editor",
+            },
+            scopedToken: input.scopedToken,
+        });
+    }
+    async getMetadata(input) {
+        const raw = await this.post("v2/metadata", {
+            apiKey: input.apiKey,
+            body: {
+                integration: input.integrationId,
+                profile: { name: input.profileKey },
+                stepConfiguration: input.stepConfiguration ?? {},
+            },
+            profileKey: input.profileKey,
+            scopedToken: input.scopedToken,
+        });
+        if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+            const record = raw;
+            if (record.data && typeof record.data === "object") {
+                return record.data;
+            }
+            return raw;
+        }
+        return {};
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/orchestrator/client.js.map

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

package/dist/playwright/ensure-chromium.d.ts

@@ -0,0 +1,26 @@
+export type EnsurePlaywrightChromiumOptions = {
+    /** Override for tests. Defaults to Playwright's Chromium executable path. */
+    chromiumExecutablePath?: string;
+    /** CLI invoked when Chromium is missing. Defaults to `pnpm`. */
+    playwrightCli?: string;
+    playwrightArgs?: string[];
+};
+export type EnsurePlaywrightChromiumResult = {
+    /** True when this call ran an install. */
+    installed: boolean;
+};
+/**
+ * Probe only: true when Playwright Chromium is already on disk. Does not
+ * download anything. Used by `gateway setup` capture.mode and by capabilities
+ * that must fail closed instead of waiting on `chromium.launch()`.
+ */
+export declare function playwrightChromiumPresent(options?: Pick<EnsurePlaywrightChromiumOptions, "chromiumExecutablePath">): Promise<boolean>;
+/**
+ * Ensures Playwright Chromium is on disk. Intended for `gateway setup`, not
+ * every `gateway serve` - corp laptops need a one-time download with network.
+ */
+export declare function ensurePlaywrightChromium(options?: EnsurePlaywrightChromiumOptions): Promise<EnsurePlaywrightChromiumResult>;
+/**
+ * Clear error for `gateway serve` when setup was skipped.
+ */
+export declare function assertPlaywrightChromiumInstalled(options?: Pick<EnsurePlaywrightChromiumOptions, "chromiumExecutablePath">): Promise<void>;

package/dist/playwright/ensure-chromium.js

@@ -0,0 +1,60 @@
+import { execFile as execFileCallback } from "node:child_process";
+import { access } from "node:fs/promises";
+import { promisify } from "node:util";
+import { chromium } from "playwright";
+const execFile = promisify(execFileCallback);
+async function pathExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Probe only: true when Playwright Chromium is already on disk. Does not
+ * download anything. Used by `gateway setup` capture.mode and by capabilities
+ * that must fail closed instead of waiting on `chromium.launch()`.
+ */
+export async function playwrightChromiumPresent(options = {}) {
+    const executablePath = options.chromiumExecutablePath ?? chromium.executablePath();
+    return pathExists(executablePath);
+}
+/**
+ * Ensures Playwright Chromium is on disk. Intended for `gateway setup`, not
+ * every `gateway serve` - corp laptops need a one-time download with network.
+ */
+export async function ensurePlaywrightChromium(options = {}) {
+    const executablePath = options.chromiumExecutablePath ?? chromium.executablePath();
+    if (await pathExists(executablePath)) {
+        return { installed: false };
+    }
+    const cli = options.playwrightCli ?? "pnpm";
+    const args = options.playwrightArgs ??
+        (options.playwrightCli
+            ? ["install", "chromium"]
+            : ["exec", "playwright", "install", "chromium"]);
+    try {
+        await execFile(cli, args);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to install Playwright Chromium (needed for preview screenshots). Run: pnpm exec playwright install chromium. (${detail})`);
+    }
+    if (!(await pathExists(executablePath))) {
+        throw new Error(`Playwright Chromium is still missing after install at ${executablePath}. Run: pnpm exec playwright install chromium`);
+    }
+    return { installed: true };
+}
+/**
+ * Clear error for `gateway serve` when setup was skipped.
+ */
+export async function assertPlaywrightChromiumInstalled(options = {}) {
+    const executablePath = options.chromiumExecutablePath ?? chromium.executablePath();
+    if (await pathExists(executablePath)) {
+        return;
+    }
+    throw new Error(`Playwright Chromium is not installed (looked for ${executablePath}). Run: superblocks gateway setup`);
+}
+//# sourceMappingURL=ensure-chromium.js.map

package/dist/playwright/ensure-chromium.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensure-chromium.js","sourceRoot":"","sources":["../../src/playwright/ensure-chromium.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,IAAI,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAClE,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC,MAAM,QAAQ,GAAG,SAAS,CAAC,gBAAgB,CAAC,CAAC;AAe7C,KAAK,UAAU,UAAU,CAAC,IAAY;IACpC,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC;QACnB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,UAA2E,EAAE;IAE7E,MAAM,cAAc,GAClB,OAAO,CAAC,sBAAsB,IAAI,QAAQ,CAAC,cAAc,EAAE,CAAC;IAC9D,OAAO,UAAU,CAAC,cAAc,CAAC,CAAC;AACpC,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,UAA2C,EAAE;IAE7C,MAAM,cAAc,GAClB,OAAO,CAAC,sBAAsB,IAAI,QAAQ,CAAC,cAAc,EAAE,CAAC;IAC9D,IAAI,MAAM,UAAU,CAAC,cAAc,CAAC,EAAE,CAAC;QACrC,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IAC9B,CAAC;IAED,MAAM,GAAG,GAAG,OAAO,CAAC,aAAa,IAAI,MAAM,CAAC;IAC5C,MAAM,IAAI,GACR,OAAO,CAAC,cAAc;QACtB,CAAC,OAAO,CAAC,aAAa;YACpB,CAAC,CAAC,CAAC,SAAS,EAAE,UAAU,CAAC;YACzB,CAAC,CAAC,CAAC,MAAM,EAAE,YAAY,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC,CAAC;IAErD,IAAI,CAAC;QACH,MAAM,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IAC5B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,MAAM,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACtE,MAAM,IAAI,KAAK,CACb,wHAAwH,MAAM,GAAG,CAClI,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,CAAC,MAAM,UAAU,CAAC,cAAc,CAAC,CAAC,EAAE,CAAC;QACxC,MAAM,IAAI,KAAK,CACb,yDAAyD,cAAc,8CAA8C,CACtH,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;AAC7B,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,iCAAiC,CACrD,UAA2E,EAAE;IAE7E,MAAM,cAAc,GAClB,OAAO,CAAC,sBAAsB,IAAI,QAAQ,CAAC,cAAc,EAAE,CAAC;IAC9D,IAAI,MAAM,UAAU,CAAC,cAAc,CAAC,EAAE,CAAC;QACrC,OAAO;IACT,CAAC;IACD,MAAM,IAAI,KAAK,CACb,oDAAoD,cAAc,mCAAmC,CACtG,CAAC;AACJ,CAAC"}

package/dist/preview/capture-screenshot.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Headless capture of a preview viewer URL for MCP image content.
+ *
+ * Best-effort: callers must succeed with URLs alone when this returns
+ * undefined. Output is capped for Claude Desktop tool-result size limits.
+ */
+export type PreviewScreenshot = {
+    dataBase64: string;
+    mimeType: "image/jpeg";
+};
+/** Soft cap on decoded bytes before base64 (~256 KiB). */
+export declare const PREVIEW_SCREENSHOT_MAX_BYTES: number;
+export type CapturePreviewScreenshot = (input: {
+    /**
+     * Bearer the embed shell should authenticate with. Without it the shell
+     * falls back to Auth0 silent login, which cannot succeed headless.
+     */
+    embedToken?: string;
+    url: string;
+    timeoutMs?: number;
+}) => Promise<PreviewScreenshot | undefined>;
+/**
+ * Page source that hands the deployed shell its bearer, and the whole reason a
+ * headless capture can paint a real app.
+ *
+ * `ui-deployed-shell` only accepts a bearer through an `INITIALIZE_EMBED`
+ * message from its embedder, and ~300ms after mount it gives up and tries
+ * Auth0 silent login instead — which has no session to find here. At top level
+ * the shell's embedder port has no parent window to check messages against, so
+ * it accepts one posted by the page itself.
+ *
+ * Delivery happens exactly once: each `INITIALIZE_EMBED` replaces the shell's
+ * auth state and restarts its bootstrap, so a repeating handshake would keep
+ * the app from ever settling.
+ *
+ * This is source text rather than a function handed to `addInitScript` because
+ * Playwright ships a function by serializing it, which drags in whatever
+ * helpers the bundler injected into its body (`__name` under tsx) and throws a
+ * ReferenceError in the page.
+ *
+ * The result is only ever evaluated as script source (Playwright forwards it
+ * to CDP `addScriptToEvaluateOnNewDocument`), never interpolated into HTML, so
+ * `JSON.stringify` is sufficient to contain the token. Putting it in a
+ * `<script>` element would not be — the token would need `</script>` escaped.
+ */
+export declare function buildEmbedHandshakeScript(token: string): string;
+/**
+ * Captures a JPEG screenshot via Playwright when available. Soft-fails when
+ * Chromium is missing or the page never becomes ready — callers must still
+ * return preview URLs when this returns undefined.
+ */
+export declare const capturePreviewScreenshotWithPlaywright: CapturePreviewScreenshot;