@superblocksteam/gateway 2.0.0-SNAPSHOT.1d4c72c0ab174c21

package/dist/sabs/awaited-decision.d.ts

@@ -0,0 +1,47 @@
+import type { TurnDecision } from "./session-peer.js";
+/**
+ * What Clark is waiting on a human for, assembled from the pushes that carry
+ * it.
+ *
+ * Neither shape arrives whole. A plan opens with one message and streams in
+ * deltas, and the caller only has something to approve once the pieces are
+ * joined; a question arrives with its options in one of two different push
+ * types. Keeping that assembly here is what lets the turn ask a single
+ * question - "is Clark waiting on anyone?" - instead of tracking four fields
+ * to work it out.
+ */
+export declare class AwaitedDecision {
+    private readonly integrations;
+    private planChunks;
+    private planMessageId;
+    private planTitle;
+    private choice;
+    /** A `plan` push: the start of a plan, replacing any plan before it. */
+    openPlan(input: {
+        messageId?: string;
+        title?: string;
+    }): void;
+    /** A `plan` or `plan-delta` push carrying more of the plan's text. */
+    appendPlan(content: string): void;
+    /** A `multi_choice` or `searchable_dropdown` push. */
+    askChoice(input: {
+        messageId?: string;
+        options: string[];
+        question: string;
+    }): void;
+    /** A headless integration setup request for the MCP host to fulfill. */
+    requireIntegration(input: {
+        configuration: Record<string, unknown>;
+        name?: string;
+        pluginId: string;
+    }): void;
+    /** True once a plan has streamed any text, whether or not it has finished. */
+    hasPlan(): boolean;
+    /**
+     * The decision to report, preferring a plan over a question when both
+     * arrived in the same turn: a plan is what approve/refine acts on, and a
+     * question Clark asked on the way to it is not the turn's outcome.
+     */
+    decision(): TurnDecision | undefined;
+    private plan;
+}

package/dist/sabs/awaited-decision.js

@@ -0,0 +1,124 @@
+import { McpError } from "@modelcontextprotocol/sdk/types.js";
+import { getPluginConfigurationSchema } from "@superblocksteam/mcp-server";
+/** Matches library-shared AI_PLAN_STREAMING_END_MARKER. */
+const PLAN_STREAMING_END_MARKER = "[__SUPERBLOCKS_PLAN_DONE__]";
+/**
+ * The plugin's configuration form, from the schema bundled in the MCP server.
+ *
+ * Carrying it with the request is what keeps the host from having to ask for
+ * it: a separate schema tool call is a second approval prompt for a lookup
+ * that touches nothing. Superblocks can name a plugin the bundle has no
+ * schema for, and a missing form is no reason to drop the whole request.
+ */
+function pluginConfigurationForm(pluginId) {
+    try {
+        return getPluginConfigurationSchema(pluginId);
+    }
+    catch (error) {
+        if (error instanceof McpError) {
+            return undefined;
+        }
+        throw error;
+    }
+}
+/**
+ * What Clark is waiting on a human for, assembled from the pushes that carry
+ * it.
+ *
+ * Neither shape arrives whole. A plan opens with one message and streams in
+ * deltas, and the caller only has something to approve once the pieces are
+ * joined; a question arrives with its options in one of two different push
+ * types. Keeping that assembly here is what lets the turn ask a single
+ * question - "is Clark waiting on anyone?" - instead of tracking four fields
+ * to work it out.
+ */
+export class AwaitedDecision {
+    integrations = [];
+    planChunks = [];
+    planMessageId;
+    planTitle;
+    choice;
+    /** A `plan` push: the start of a plan, replacing any plan before it. */
+    openPlan(input) {
+        this.planChunks = [];
+        if (input.messageId) {
+            this.planMessageId = input.messageId;
+        }
+        if (input.title?.trim()) {
+            this.planTitle = input.title.trim();
+        }
+    }
+    /** A `plan` or `plan-delta` push carrying more of the plan's text. */
+    appendPlan(content) {
+        if (content) {
+            this.planChunks.push(content);
+        }
+    }
+    /** A `multi_choice` or `searchable_dropdown` push. */
+    askChoice(input) {
+        this.choice = {
+            ...(input.messageId ? { messageId: input.messageId } : {}),
+            options: input.options,
+            question: input.question,
+        };
+    }
+    /** A headless integration setup request for the MCP host to fulfill. */
+    requireIntegration(input) {
+        const pluginId = input.pluginId === "restapi" ? "restapiintegration" : input.pluginId;
+        const { baseUrl, ...restConfiguration } = input.configuration;
+        const configuration = input.pluginId === "restapi"
+            ? {
+                ...restConfiguration,
+                ...(baseUrl !== undefined && restConfiguration.urlBase === undefined
+                    ? { urlBase: baseUrl }
+                    : {}),
+            }
+            : input.configuration;
+        const configurationSchema = pluginConfigurationForm(pluginId);
+        this.integrations.push({
+            ...input,
+            configuration,
+            pluginId,
+            ...(configurationSchema ? { configurationSchema } : {}),
+        });
+    }
+    /** True once a plan has streamed any text, whether or not it has finished. */
+    hasPlan() {
+        return this.plan() !== undefined;
+    }
+    /**
+     * The decision to report, preferring a plan over a question when both
+     * arrived in the same turn: a plan is what approve/refine acts on, and a
+     * question Clark asked on the way to it is not the turn's outcome.
+     */
+    decision() {
+        if (this.integrations.length > 0) {
+            return {
+                integrations: [...this.integrations],
+                kind: "missing_integrations",
+            };
+        }
+        const plan = this.plan();
+        if (plan) {
+            return {
+                kind: "plan",
+                ...(this.planMessageId ? { messageId: this.planMessageId } : {}),
+                plan,
+                ...(this.planTitle ? { title: this.planTitle } : {}),
+            };
+        }
+        return this.choice ? { kind: "multi_choice", ...this.choice } : undefined;
+    }
+    plan() {
+        if (this.planChunks.length === 0) {
+            return undefined;
+        }
+        const plan = this.planChunks
+            .join("")
+            .split(PLAN_STREAMING_END_MARKER)
+            .join("")
+            .trimEnd();
+        return plan || undefined;
+    }
+}
+//# sourceMappingURL=awaited-decision.js.map

package/dist/sabs/awaited-decision.js.map

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

package/dist/sabs/browser-context.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Builds the `browserContext` the ai-service needs before it will register
+ * Clark's Playwright tools.
+ *
+ * Opt-in: the sandbox launches Chromium, mocks `window.parent`, and
+ * replays `initData` / `bootstrapData` to the app shell as `sb-init` and
+ * `sb-bootstrap-response`. The gateway only supplies the same context the
+ * browser editor assembles from Redux. Gateway preview screenshots use
+ * laptop Chromium instead and do not call this.
+ */
+import type { BrowserContext } from "@superblocksteam/library-shared/types";
+/**
+ * An org profile as the Superblocks API returns it. `key` is what selects the
+ * profile; `id` and `displayName` round out the `Profile` shape the app shell
+ * types against.
+ */
+export type BrowserContextProfile = {
+    allowedInEditor?: boolean;
+    displayName?: string;
+    id?: string;
+    key: string;
+};
+export type BrowserContextInput = {
+    applicationId: string;
+    /**
+     * Personal API key sent as library `token` / `Authorization`. The
+     * orchestrator forwards that header to the code-bundle route, which
+     * checks `apps:view` and rejects the live-edit `apps:update` JWT.
+     */
+    apiKey?: string;
+    /** Sandbox origin from `connectLiveEdit`; the editor iframe's own base URL. */
+    liveEditUrl: string;
+    orchestratorUrl: string;
+    organizationId?: string;
+    /** Held-session peer id, so the app shell reuses this editor's socket. */
+    peerId: string;
+    /** Profile key already resolved for this session's orchestrator calls. */
+    profileKey?: string;
+    profiles?: BrowserContextProfile[];
+    /** Scoped `apps:update` JWT the live-edit session was opened with. */
+    sessionToken: string;
+    uiBaseUrl: string;
+    userEmail?: string;
+    userId: string;
+};
+/**
+ * Returns the context, or `undefined` when the sandbox URL is unusable.
+ *
+ * Undefined rather than a throw: browser testing is an enhancement to a turn,
+ * so a sandbox we cannot address should cost Clark its Playwright tools, not
+ * the whole prompt.
+ */
+export declare function buildBrowserContext(input: BrowserContextInput): BrowserContext | undefined;

package/dist/sabs/browser-context.js

@@ -0,0 +1,92 @@
+/**
+ * Builds the `browserContext` the ai-service needs before it will register
+ * Clark's Playwright tools.
+ *
+ * Opt-in: the sandbox launches Chromium, mocks `window.parent`, and
+ * replays `initData` / `bootstrapData` to the app shell as `sb-init` and
+ * `sb-bootstrap-response`. The gateway only supplies the same context the
+ * browser editor assembles from Redux. Gateway preview screenshots use
+ * laptop Chromium instead and do not call this.
+ */
+import { Profile, ProfileType } from "@superblocksteam/shared";
+function toProfile(row) {
+    return new Profile({
+        allowedInEditor: row.allowedInEditor,
+        description: "",
+        displayName: row.displayName ?? row.key,
+        id: row.id ?? row.key,
+        key: row.key,
+        type: ProfileType.RESERVED,
+    });
+}
+function selectProfiles(input) {
+    const rows = input.profiles ?? [];
+    if (rows.length === 0) {
+        return undefined;
+    }
+    const chosen = rows.find((row) => row.key === input.profileKey) ?? rows[0];
+    if (!chosen) {
+        return undefined;
+    }
+    const selected = toProfile(chosen);
+    return {
+        available: rows.map(toProfile),
+        default: selected,
+        selected,
+    };
+}
+/**
+ * Returns the context, or `undefined` when the sandbox URL is unusable.
+ *
+ * Undefined rather than a throw: browser testing is an enhancement to a turn,
+ * so a sandbox we cannot address should cost Clark its Playwright tools, not
+ * the whole prompt.
+ */
+export function buildBrowserContext(input) {
+    let iframeBaseUrl;
+    try {
+        iframeBaseUrl = new URL(input.liveEditUrl);
+    }
+    catch {
+        return undefined;
+    }
+    if (iframeBaseUrl.protocol !== "http:" &&
+        iframeBaseUrl.protocol !== "https:") {
+        return undefined;
+    }
+    // The editor's iframe carries this too. Without it the app shell boots in
+    // its viewer mode, where the editing affordances Clark's tests drive are
+    // absent.
+    iframeBaseUrl.searchParams.set("app_mode", "EDIT");
+    const profiles = selectProfiles(input);
+    return {
+        bootstrapData: {
+            accessToken: input.sessionToken,
+            agents: [],
+            agentUrls: [input.orchestratorUrl],
+            appId: input.applicationId,
+            devServerAuthorization: `Bearer ${input.sessionToken}`,
+            featureFlags: {
+                "clark.sdk-api.enabled": true,
+            },
+            orgId: input.organizationId,
+            ...(profiles ? { profiles } : {}),
+            // Library fetch: Authorization = this token, x-superblocks-authorization
+            // = accessToken. The API key belongs on Authorization; the scoped JWT
+            // does not carry apps:view for the orchestrator's code-bundle fetch.
+            token: input.apiKey ?? input.sessionToken,
+            userEmail: input.userEmail,
+            userId: input.userId,
+            windowOriginUrl: input.uiBaseUrl,
+        },
+        iframeBaseUrl: iframeBaseUrl.toString(),
+        initData: {
+            appId: input.applicationId,
+            devServerAuthorization: `Bearer ${input.sessionToken}`,
+            peerId: input.peerId,
+            userId: input.userId,
+            windowOriginUrl: input.uiBaseUrl,
+        },
+    };
+}
+//# sourceMappingURL=browser-context.js.map

package/dist/sabs/browser-context.js.map

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

package/dist/sabs/editor-client-methods.d.ts

@@ -0,0 +1,164 @@
+import type { EditorHasDefaultStructure, PromptContextIntegration, SdkApiExecutionResult } from "@superblocksteam/library-shared/types";
+import { type MethodHandlers, type RequestContextBase } from "@superblocksteam/shared";
+import type { OrchestratorClient } from "../orchestrator/client.js";
+import type { SuperblocksServerClient } from "../server/client.js";
+export type IntegrationExecuteResult = {
+    error?: string;
+    response?: string;
+};
+export type IntegrationExecutePayload = {
+    integrationHint?: {
+        displayName?: string;
+        name: string;
+        type: string;
+    };
+    integrationId: string;
+    request: Record<string, unknown>;
+};
+/**
+ * The subset of library-shared's AiChatMessage the gateway reads. Test-run
+ * fields are flattened in here because Clark reports a whole test run through
+ * ordinary `aiPushMessage` pushes, distinguished only by `type`.
+ */
+export type ClarkMessage = {
+    choices?: Array<string | {
+        text: string;
+        subText?: string;
+    }>;
+    content?: string;
+    gatewayObserverSource?: "browser";
+    header?: string;
+    id?: string;
+    name?: string;
+    options?: Array<string | {
+        label?: string;
+        value?: string;
+    }>;
+    role?: string;
+    summary?: string;
+    testCaseId?: string;
+    testCaseStatus?: string;
+    testCases?: Array<{
+        id?: string;
+        name?: string;
+        status?: string;
+    }>;
+    testRunId?: string;
+    testStatus?: string;
+    title?: string;
+    type?: string;
+};
+export type ClarkPeerEvent = {
+    kind: "message";
+    message: ClarkMessage;
+} | {
+    configuration: Record<string, unknown>;
+    kind: "missing_integration";
+    name?: string;
+    pluginId: string;
+} | {
+    kind: "change_info";
+    label: string;
+} | {
+    kind: "draft_state";
+    hasDraft: boolean;
+} | {
+    hasDefaultStructure: EditorHasDefaultStructure;
+    kind: "editor_structure";
+} | {
+    kind: "generation_state";
+    /**
+     * The generation this state is about. Absent from dev servers that
+     * predate the field, which is why a turn cannot require it.
+     */
+    generationId?: string;
+    gatewayObserverSource?: "browser";
+    hasError?: boolean;
+    hasSuggestions?: boolean;
+    state: string;
+} | {
+    kind: "reload_iframe";
+} | {
+    kind: "sync_status";
+    status?: string;
+} | {
+    kind: "task_status";
+    label: string;
+};
+export type ClarkPeerListener = (event: ClarkPeerEvent) => void;
+/**
+ * Credentials and clients the held gateway peer needs to answer Clark's
+ * discovery and testApi RPCs without a browser tab.
+ */
+export type EditorSessionContext = {
+    apiKey: string;
+    applicationId: string;
+    branchName?: string;
+    organizationId: string;
+    orchestrator: OrchestratorClient;
+    profileKey: string;
+    server: SuperblocksServerClient;
+    sessionToken: string;
+    waitUntilFilesSynced: () => Promise<boolean>;
+};
+export type IntegrationExecutionContext = Pick<EditorSessionContext, "apiKey" | "orchestrator" | "organizationId" | "profileKey" | "server" | "sessionToken"> & {
+    applicationId?: string;
+};
+export type EditorClientMethodDeps = {
+    getContext: () => EditorSessionContext | undefined;
+    /**
+     * Records a mid-turn testApi / testIntegration outcome for MCP progress and
+     * needs_decision payloads.
+     */
+    onToolRun?: (run: {
+        detail?: unknown;
+        kind: "test_api" | "test_integration";
+        name: string;
+        success: boolean;
+    }) => void;
+    /**
+     * Forwards a tool-permission decision to the ai-service via
+     * `editor.aiRespondToToolPermission` on the held socket. Headless sessions
+     * auto-approve only the allowlisted Clark agent tools; other tools deny.
+     */
+    respondToToolPermission: (payload: {
+        approved: boolean;
+        messageId: string;
+        requestId?: string;
+    }) => Promise<void>;
+};
+/**
+ * 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 declare function executeRequestToIntegrationViaOrchestrator(context: IntegrationExecutionContext, payload: IntegrationExecutePayload): Promise<IntegrationExecuteResult>;
+/**
+ * Prefills Clark's promptContext.integrations the same way the editor does.
+ */
+export declare function loadIntegrationsForPrompt(context: Pick<EditorSessionContext, "apiKey" | "applicationId" | "organizationId" | "server">): Promise<Omit<PromptContextIntegration, "metadata">[]>;
+export declare function mapSdkExecutionResponse(response: unknown): SdkApiExecutionResult;
+/**
+ * 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 `GatewayClientMethods` 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 declare function createEditorClientMethods(getListener?: () => ClarkPeerListener | undefined, onInbound?: (method: string) => void, deps?: EditorClientMethodDeps): MethodHandlers<Record<string, never>, Record<string, never>, RequestContextBase>;