@superblocksteam/gateway 2.0.155-next.0

package/dist/sabs/editor-client-methods.js

@@ -0,0 +1,715 @@
+import { getBasePluginId, } from "@superblocksteam/shared";
+import { listIntegrationsForClark, toPromptContextIntegration, } from "../integrations/map.js";
+import { sanitizeAgentFacingText, sanitizeAgentFacingValue, } from "./agent-facing-text.js";
+const ADMIN_MCP_SETUP_MESSAGE = "Integrations CRUD is available on this Superblocks MCP via create_integration, update_integration, and list_integrations (same connector as start_app). Use those Admin tools, then continue with edit_app. The headless editor session cannot open the Integrations UI.";
+/**
+ * Clark tools that already use PROMPT access rules in the editor. The headless
+ * gateway has no human approval UI, so only these may be auto-approved; any
+ * other toolName is denied.
+ */
+const HEADLESS_AUTO_APPROVED_TOOLS = new Set([
+    "build_deleteFile",
+    "build_installPackages",
+    "executeRequestToIntegration",
+    "runMigrationVerification",
+    "testApi",
+    "updateMigrationWritePolicy",
+]);
+function taskLabel(summary) {
+    const parts = [
+        summary.label || summary.taskType,
+        summary.state,
+        summary.message,
+    ].filter((part) => Boolean(part && part.trim()));
+    return parts.join(": ").slice(0, 160);
+}
+function changeLabel(info) {
+    const parts = [info.action || info.status, info.type, info.name].filter((part) => Boolean(part && String(part).trim()));
+    return parts.join(" ").slice(0, 160);
+}
+function missingSessionError(action) {
+    return new Error(`the headless gateway session cannot ${action} without an active prompt session`);
+}
+function formatIntegrationResult(data) {
+    if (data === undefined) {
+        return { response: "" };
+    }
+    if (data === null) {
+        return { response: "null" };
+    }
+    if (typeof data === "string") {
+        return { response: sanitizeAgentFacingText(data) };
+    }
+    try {
+        // Sanitized as a value first, then as text. Serializing first leaves only
+        // the text patterns to work with, and those cannot see field names: a row
+        // with a short `password` column reads as ordinary JSON to them.
+        const serialized = JSON.stringify(sanitizeAgentFacingValue(data), null, 2);
+        if (serialized) {
+            return { response: sanitizeAgentFacingText(serialized) };
+        }
+    }
+    catch (error) {
+        return {
+            error: sanitizeAgentFacingText(`Failed to serialize integration result: ${error instanceof Error ? error.message : String(error)}`),
+        };
+    }
+    return { response: sanitizeAgentFacingText(String(data)) };
+}
+function extractIntegrationResult(executionResult) {
+    if (!executionResult || typeof executionResult !== "object") {
+        return executionResult;
+    }
+    const result = executionResult;
+    if (result.output?.result !== undefined) {
+        return result.output.result;
+    }
+    for (const event of result.events ?? []) {
+        const eventResult = event.result?.event?.end?.output?.result;
+        if (eventResult !== undefined) {
+            return eventResult;
+        }
+    }
+    return executionResult;
+}
+/**
+ * True only for interactive IdP / OAuth style failures — not generic HTTP 401s
+ * from control-plane hydration (e.g. missing JWT on integration fetch) and not
+ * SQL/object permission wording like Snowflake's "does not exist or not authorized".
+ */
+function looksLikeInteractiveAuthRequired(message) {
+    return /authentication is required|please authenticate|oauth(?:\s+token)?|idp|login required|token (?:expired|missing)|interactive auth/i.test(message);
+}
+/** Snowflake object RBAC / wrong FQN — not Superblocks or IdP auth. */
+function looksLikeSnowflakeObjectPermissionError(message) {
+    return /does not exist or not authorized/i.test(message);
+}
+function looksLikeOrchestratorJwtGate401(message) {
+    return /orchestrator.*\b401\b/i.test(message);
+}
+const SNOWFLAKE_OBJECT_PERMISSION_HINT = " This is a Snowflake object permission or schema/name error for the integration's role — not Superblocks re-auth. Fix the fully-qualified name or grant access, then retry.";
+const ORCHESTRATOR_JWT_GATE_HINT = " This is Superblocks/orchestrator auth (the scoped JWT or selected profile), not Snowflake username/password. Do not tell the user to re-enter credentials in the integrations panel. If the build still reaches ready, treat this as a mid-build API-check note rather than a user-facing blocker.";
+function clarifySdkExecutionErrorMessage(message) {
+    let clarified = message;
+    if (looksLikeOrchestratorJwtGate401(message)) {
+        if (!message.includes(ORCHESTRATOR_JWT_GATE_HINT.trim())) {
+            clarified = `${message}${ORCHESTRATOR_JWT_GATE_HINT}`;
+        }
+    }
+    else if (looksLikeSnowflakeObjectPermissionError(message)) {
+        if (!message.includes(SNOWFLAKE_OBJECT_PERMISSION_HINT.trim())) {
+            clarified = `${message}${SNOWFLAKE_OBJECT_PERMISSION_HINT}`;
+        }
+    }
+    return sanitizeAgentFacingText(clarified);
+}
+/**
+ * Runs Clark's executeRequestToIntegration the same way the browser editor
+ * does: one inline V2 API step against the orchestrator. Username/password and
+ * other stored-credential integrations execute here; interactive IdP auth
+ * surfaces as an error asking the user to authenticate in the editor.
+ */
+export async function executeRequestToIntegrationViaOrchestrator(context, payload) {
+    let pluginId = payload.integrationHint?.type;
+    let integrationName = payload.integrationHint?.displayName ??
+        payload.integrationHint?.name ??
+        "Integration";
+    if (!pluginId) {
+        let row;
+        try {
+            row = await context.server.getIntegration({
+                apiKey: context.apiKey,
+                integrationId: payload.integrationId,
+            });
+            if (!row) {
+                const rows = await context.server.getSupersetIntegrations({
+                    apiKey: context.apiKey,
+                    applicationId: context.applicationId,
+                    organizationId: context.organizationId,
+                });
+                row = rows.find((candidate) => candidate.id === payload.integrationId);
+            }
+        }
+        catch (error) {
+            console.warn("gateway failed to resolve integration for execute", {
+                applicationId: context.applicationId,
+                integrationId: payload.integrationId,
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
+        if (!row?.pluginId) {
+            return {
+                error: `Integration ${payload.integrationId} not found or not accessible`,
+            };
+        }
+        pluginId = row.pluginId;
+        integrationName = row.name || integrationName;
+    }
+    const pluginIdForStep = getBasePluginId(pluginId);
+    const now = new Date().toISOString();
+    const inlineApiId = `ai-inline-${payload.integrationId}-${Date.now()}`;
+    const definition = {
+        blocks: [
+            {
+                name: "InlineQuery",
+                step: {
+                    integration: payload.integrationId,
+                    [pluginIdForStep]: { ...payload.request },
+                },
+            },
+        ],
+        metadata: {
+            id: inlineApiId,
+            name: `${integrationName} AI Query`,
+            organization: context.organizationId,
+            timestamps: { created: now, updated: now },
+        },
+        trigger: { application: {} },
+    };
+    try {
+        const result = await context.orchestrator.executeV2Api({
+            apiKey: context.apiKey,
+            body: {
+                definition: { api: definition },
+                inputs: {},
+                options: {
+                    includeEventOutputs: true,
+                    includeEvents: true,
+                    includeResolved: true,
+                    isAiTriggered: true,
+                    suppressTracking: true,
+                },
+                ...(context.profileKey
+                    ? { profile: { name: context.profileKey } }
+                    : {}),
+            },
+            profileKey: context.profileKey,
+            scopedToken: context.sessionToken,
+        });
+        if (result && typeof result === "object" && "systemError" in result) {
+            const systemError = String(result.systemError ??
+                "Integration execution failed");
+            if (looksLikeInteractiveAuthRequired(systemError)) {
+                return {
+                    error: sanitizeAgentFacingText(`${systemError} Authenticate this integration in the Superblocks editor (open the app edit URL), then ask Superblocks to retry the query.`),
+                };
+            }
+            return { error: clarifySdkExecutionErrorMessage(systemError) };
+        }
+        if (result === undefined) {
+            return { error: "No response received from integration" };
+        }
+        const errors = result.errors;
+        const unhandled = errors
+            ?.filter((entry) => !entry.handled)
+            .map((entry) => entry.message);
+        if (unhandled && unhandled.length > 0) {
+            const message = JSON.stringify(unhandled);
+            if (looksLikeInteractiveAuthRequired(message)) {
+                return {
+                    error: sanitizeAgentFacingText(`${message} Authenticate this integration in the Superblocks editor (open the app edit URL), then ask Superblocks to retry the query.`),
+                };
+            }
+            return { error: clarifySdkExecutionErrorMessage(message) };
+        }
+        return formatIntegrationResult(extractIntegrationResult(result));
+    }
+    catch (error) {
+        const message = error instanceof Error
+            ? error.message
+            : "Failed to execute integration query";
+        if (looksLikeInteractiveAuthRequired(message)) {
+            return {
+                error: sanitizeAgentFacingText(`${message} Authenticate this integration in the Superblocks editor (open the app edit URL), then ask Superblocks to retry the query.`),
+            };
+        }
+        return { error: clarifySdkExecutionErrorMessage(message) };
+    }
+}
+/**
+ * Prefills Clark's promptContext.integrations the same way the editor does.
+ */
+export async function loadIntegrationsForPrompt(context) {
+    const rows = await context.server.getSupersetIntegrations({
+        apiKey: context.apiKey,
+        applicationId: context.applicationId,
+        organizationId: context.organizationId,
+    });
+    return listIntegrationsForClark(rows);
+}
+export function mapSdkExecutionResponse(response) {
+    if (response && typeof response === "object" && "systemError" in response) {
+        const systemError = response.systemError;
+        return {
+            success: false,
+            error: {
+                code: "SYSTEM_ERROR",
+                message: clarifySdkExecutionErrorMessage(typeof systemError === "string"
+                    ? systemError
+                    : "Orchestrator returned a system error"),
+            },
+        };
+    }
+    if (response &&
+        typeof response === "object" &&
+        "errors" in response &&
+        Array.isArray(response.errors) &&
+        response.errors.length > 0) {
+        const first = response
+            .errors[0];
+        return {
+            success: false,
+            error: {
+                code: "EXECUTION_ERROR",
+                message: clarifySdkExecutionErrorMessage(first?.message ?? "API execution failed"),
+            },
+        };
+    }
+    if (response && typeof response === "object") {
+        const output = response.output
+            ?.result;
+        return {
+            success: true,
+            output: sanitizeAgentFacingValue(output),
+        };
+    }
+    return {
+        success: false,
+        error: {
+            code: "EMPTY_RESPONSE",
+            message: "No response from orchestrator",
+        },
+    };
+}
+/**
+ * Server -> editor calls the dev server makes into the peer driving a turn,
+ * whether that peer negotiated protocol "editor" or "gateway".
+ *
+ * Leaving these unimplemented is not inert. ISocket answers an unknown method
+ * with `{ code: 2, message: "unknown method <name>" }`, and the dev server does
+ * not catch every one of those rejections — `resetScope` in particular escalates
+ * to `unhandledRejection`, which exits the sandbox with "Dev server fatal exit"
+ * and takes the in-flight Clark build down with it. A browser editor answers
+ * all of them, so a held gateway socket has to as well.
+ *
+ * Keyed on `EditorClientMethods` rather than a hand-kept list so that a method
+ * added to the protocol upstream fails this package's typecheck instead of
+ * reaching a sandbox and crashing it. Same handler surface as
+ * `createEditorHandlers` in vite-plugin-file-sync's dev-server-ws-smoke-client,
+ * the other non-browser peer that speaks this protocol; it is not imported from
+ * there because the gateway does not depend on the vite plugin.
+ *
+ * When a listener is provided, chat, generation-state, task/change, and
+ * preview-ready pushes are forwarded so the gateway can wait for Clark's turn
+ * and surface progress over MCP.
+ */
+export function createEditorClientMethods(getListener, onInbound, deps) {
+    // Notifications and state pushes. The gateway keeps no editor state unless a
+    // turn wait is armed, so acknowledging is the whole contract — the dev
+    // server only needs to know the peer is alive and listening.
+    const ack = [async () => undefined];
+    const setupUnavailable = [
+        async () => ({
+            error: ADMIN_MCP_SETUP_MESSAGE,
+            success: false,
+        }),
+    ];
+    const handlers = {
+        aiApplyApplicationEnvironmentSettings: ack,
+        aiClearToolPermission: ack,
+        aiPushApiUsageSummary: ack,
+        aiPushChangeInfo: [
+            async (info) => {
+                const label = changeLabel(info);
+                if (!label) {
+                    return;
+                }
+                getListener?.()?.({ kind: "change_info", label });
+            },
+        ],
+        aiPushContextUsed: ack,
+        aiPushErrorSummary: ack,
+        aiPushMessage: [
+            async (message) => {
+                const listener = getListener?.();
+                listener?.({ kind: "message", message });
+            },
+        ],
+        aiPushPolicyAgentStep: ack,
+        aiPushPromptInterpretation: ack,
+        aiPushTaskStatus: [
+            async (summary) => {
+                const label = taskLabel(summary);
+                if (!label) {
+                    return;
+                }
+                getListener?.()?.({ kind: "task_status", label });
+            },
+        ],
+        aiPushTokenUsage: ack,
+        aiRequestToolPermission: [
+            async (payload) => {
+                // Headless gateway has no editor approval UI. Auto-approve only the
+                // Clark agent tools that already have PROMPT access rules and must run
+                // unattended for local builds (testApi WRITE, migration checks, etc.).
+                // Unknown tools are denied by default.
+                if (!deps) {
+                    return;
+                }
+                const toolName = payload.toolName?.trim() ?? "";
+                const approved = HEADLESS_AUTO_APPROVED_TOOLS.has(toolName);
+                await deps.respondToToolPermission({
+                    approved,
+                    messageId: payload.messageId,
+                    requestId: payload.requestId ?? payload.messageId,
+                });
+            },
+        ],
+        // Says whether Clark left uncommitted work behind. The gateway needs it
+        // for the same reason the browser editor does: a pending draft has to be
+        // accepted before the app the edit URL serves matches what Clark built.
+        aiSetDraftState: [
+            async (payload) => {
+                getListener?.()?.({
+                    kind: "draft_state",
+                    hasDraft: Boolean(payload?.hasDraft),
+                });
+            },
+        ],
+        aiSetGenerationState: [
+            async (snapshot) => {
+                if (typeof snapshot?.state === "string") {
+                    getListener?.()?.({
+                        hasError: snapshot.hasError,
+                        hasSuggestions: snapshot.hasSuggestions,
+                        kind: "generation_state",
+                        state: snapshot.state,
+                    });
+                }
+            },
+        ],
+        appFactsChanged: ack,
+        clarkLog: ack,
+        closedByServer: ack,
+        error: ack,
+        manualDeleteApi: ack,
+        manualUpdateApi: ack,
+        notifyDeploySuccess: ack,
+        reloadIframe: [
+            async () => {
+                getListener?.()?.({ kind: "reload_iframe" });
+            },
+        ],
+        releasingLock: ack,
+        requestGitRefresh: ack,
+        resetScope: ack,
+        setApiDependencies: ack,
+        setDegradedMode: ack,
+        syncStatus: [
+            async (payload) => {
+                getListener?.()?.({
+                    kind: "sync_status",
+                    status: typeof payload?.status === "string" ? payload.status : undefined,
+                });
+            },
+        ],
+        updateApiInputs: ack,
+        updateScope: ack,
+        // No browser tab means no viewport to photograph. The flag matters more
+        // than the message: it tells the ai-service this was a refusal, not a
+        // failed capture, so Clark can fall back to the sandbox's own browser
+        // instead of reporting that it cannot see the app it just built.
+        aiCaptureScreenshot: [
+            async () => ({
+                error: "the headless gateway session has no browser viewport",
+                success: false,
+                viewportUnavailable: true,
+            }),
+        ],
+        aiCloseIntegrationSetup: [async () => ({ success: true })],
+        aiDeleteIntegration: setupUnavailable,
+        aiExecuteRequestToIntegration: [
+            async (payload) => {
+                const context = deps?.getContext();
+                if (!context) {
+                    return {
+                        error: "the headless gateway session cannot execute integration requests without an active prompt session",
+                    };
+                }
+                const result = await executeRequestToIntegrationViaOrchestrator(context, payload);
+                const name = payload.integrationHint?.name ||
+                    payload.integrationId ||
+                    "integration";
+                deps?.onToolRun?.({
+                    detail: result,
+                    kind: "test_integration",
+                    name,
+                    success: !("error" in result && result.error),
+                });
+                return result;
+            },
+        ],
+        aiExecuteSdkApi: [
+            async (payload) => {
+                const context = deps?.getContext();
+                if (!context) {
+                    throw missingSessionError("execute SDK APIs");
+                }
+                if (!payload.entryPoint) {
+                    const missing = {
+                        success: false,
+                        error: {
+                            code: "UNKNOWN_API",
+                            message: `No entryPoint registered for API "${payload.apiName}". Was it discovered?`,
+                        },
+                    };
+                    deps?.onToolRun?.({
+                        detail: missing,
+                        kind: "test_api",
+                        name: payload.apiName,
+                        success: false,
+                    });
+                    return missing;
+                }
+                try {
+                    const inSync = await context.waitUntilFilesSynced();
+                    if (!inSync) {
+                        const syncing = {
+                            success: false,
+                            error: {
+                                code: "SYSTEM_ERROR",
+                                message: "The API files are still syncing. Wait for the current edit to finish saving, then retry testApi.",
+                            },
+                        };
+                        deps?.onToolRun?.({
+                            detail: syncing,
+                            kind: "test_api",
+                            name: payload.apiName,
+                            success: false,
+                        });
+                        return syncing;
+                    }
+                    const response = await context.orchestrator.executeSdkApiV3({
+                        apiKey: context.apiKey,
+                        applicationId: context.applicationId,
+                        branchName: context.branchName,
+                        entryPoint: payload.entryPoint,
+                        exportName: payload.exportName,
+                        inputs: payload.input ?? {},
+                        profileKey: context.profileKey,
+                        scopedToken: context.sessionToken,
+                    });
+                    const mapped = mapSdkExecutionResponse(response);
+                    deps?.onToolRun?.({
+                        detail: mapped,
+                        kind: "test_api",
+                        name: payload.apiName,
+                        success: mapped.success,
+                    });
+                    return mapped;
+                }
+                catch (error) {
+                    const failed = {
+                        success: false,
+                        error: {
+                            code: "SYSTEM_ERROR",
+                            message: error instanceof Error
+                                ? clarifySdkExecutionErrorMessage(error.message)
+                                : "Failed to execute SDK API",
+                        },
+                    };
+                    deps?.onToolRun?.({
+                        detail: failed,
+                        kind: "test_api",
+                        name: payload.apiName,
+                        success: false,
+                    });
+                    return failed;
+                }
+            },
+        ],
+        aiExecuteV2Api: [
+            async (payload) => {
+                const context = deps?.getContext();
+                if (!context) {
+                    throw missingSessionError("execute V2 APIs");
+                }
+                if (payload.api.type === "fetch") {
+                    return {
+                        systemError: `V2 API fetch for '${payload.api.apiName}' requires the browser editor; use SDK APIs (aiExecuteSdkApi) from Gateway, or open the app in the UI.`,
+                    };
+                }
+                const now = new Date().toISOString();
+                const definition = {
+                    ...payload.api.definition,
+                    metadata: {
+                        ...(payload.api.definition.metadata ?? {}),
+                        organization: context.organizationId,
+                        timestamps: { created: now, updated: now },
+                    },
+                    trigger: { application: {} },
+                };
+                try {
+                    const result = await context.orchestrator.executeV2Api({
+                        apiKey: context.apiKey,
+                        body: {
+                            definition: { api: definition },
+                            inputs: payload.inputs ?? {},
+                            options: {
+                                includeEventOutputs: true,
+                                includeEvents: true,
+                                includeResolved: true,
+                                isAiTriggered: true,
+                                suppressTracking: true,
+                            },
+                            ...(context.profileKey
+                                ? { profile: { name: context.profileKey } }
+                                : {}),
+                        },
+                        profileKey: context.profileKey,
+                        scopedToken: context.sessionToken,
+                    });
+                    if (result && typeof result === "object" && "systemError" in result) {
+                        return result;
+                    }
+                    if (result === undefined) {
+                        return { systemError: "No response received from API execution" };
+                    }
+                    const outputs = result.output?.result ?? {};
+                    return {
+                        errors: result.errors,
+                        outputs,
+                    };
+                }
+                catch (error) {
+                    return {
+                        systemError: error instanceof Error
+                            ? error.message
+                            : "Failed to execute V2 API",
+                    };
+                }
+            },
+        ],
+        aiGetIntegration: [
+            async (payload) => {
+                const context = deps?.getContext();
+                if (!context) {
+                    throw missingSessionError("provide integration metadata");
+                }
+                // A rejection here cancels Clark's turn, so every lookup failure
+                // degrades to the unknown-integration placeholder below.
+                let row;
+                try {
+                    row = await context.server.getIntegration({
+                        apiKey: context.apiKey,
+                        integrationId: payload.integrationId,
+                    });
+                    if (!row) {
+                        const rows = await context.server.getSupersetIntegrations({
+                            apiKey: context.apiKey,
+                            applicationId: context.applicationId,
+                            organizationId: context.organizationId,
+                        });
+                        row = rows.find((candidate) => candidate.id === payload.integrationId);
+                    }
+                }
+                catch (error) {
+                    console.warn("gateway failed to load integration for Clark", {
+                        applicationId: context.applicationId,
+                        integrationId: payload.integrationId,
+                        message: error instanceof Error ? error.message : String(error),
+                    });
+                }
+                if (!row) {
+                    return {
+                        displayName: payload.integrationId,
+                        id: payload.integrationId,
+                        metadata: {},
+                        name: payload.integrationId,
+                        type: "unknown",
+                    };
+                }
+                let metadata = {};
+                try {
+                    metadata = await context.orchestrator.getMetadata({
+                        apiKey: context.apiKey,
+                        integrationId: payload.integrationId,
+                        profileKey: context.profileKey,
+                        scopedToken: context.sessionToken,
+                    });
+                }
+                catch {
+                    metadata = {};
+                }
+                return toPromptContextIntegration(row, metadata);
+            },
+        ],
+        aiGetIntegrationDependents: [
+            async () => ({
+                error: "the headless gateway session cannot inspect integration dependents",
+                success: false,
+            }),
+        ],
+        aiGetIntegrationFormSchema: [
+            async () => ({
+                error: ADMIN_MCP_SETUP_MESSAGE,
+                success: false,
+            }),
+        ],
+        aiGetIntegrations: [
+            async () => {
+                const context = deps?.getContext();
+                if (!context) {
+                    return [];
+                }
+                try {
+                    return await loadIntegrationsForPrompt(context);
+                }
+                catch (error) {
+                    // Clark cancels the whole turn if this rejects, so a failed lookup
+                    // degrades to "no integrations" instead of killing the build.
+                    console.warn("gateway failed to list integrations for Clark", {
+                        applicationId: context.applicationId,
+                        message: error instanceof Error ? error.message : String(error),
+                    });
+                    return [];
+                }
+            },
+        ],
+        aiGetOpenApiSpec: [async () => undefined],
+        aiNavigatePreviewRoute: [
+            async () => ({
+                error: "the headless gateway session has no browser route",
+                success: false,
+            }),
+        ],
+        aiOpenExistingIntegration: setupUnavailable,
+        aiOpenIntegrationSetup: setupUnavailable,
+        aiSaveIntegration: setupUnavailable,
+        aiTestIntegrationConnection: [
+            async () => ({
+                error: {
+                    details: "",
+                    message: ADMIN_MCP_SETUP_MESSAGE,
+                },
+                success: false,
+            }),
+        ],
+        aiUpdateIntegrationFields: setupUnavailable,
+    };
+    const observed = handlers;
+    if (onInbound) {
+        for (const key of Object.keys(observed)) {
+            const chain = observed[key];
+            observed[key] = chain.map((handler) => async (...args) => {
+                onInbound(key);
+                return handler(...args);
+            });
+        }
+    }
+    // ISocket's MethodHandlers is keyed on the socket's own generic parameters,
+    // which the gateway leaves empty because it calls only one server method.
+    // Exhaustiveness is already enforced above, on the protocol type.
+    return observed;
+}
+//# sourceMappingURL=editor-client-methods.js.map