@superblocksteam/gateway 2.0.155-next.0

package/dist/transports/mcp/decision-elicitation.d.ts

@@ -0,0 +1,74 @@
+/**
+ * MCP form elicitation for Superblocks decisions (plan approve/refine and
+ * multi_choice questions).
+ *
+ * Chat is the baseline: every decision is also returned as needs_decision +
+ * decision so a host without elicitation can ask the user in its own words. A
+ * host that declares form elicitation gets a real picker instead, and the tool
+ * call answers Superblocks itself rather than handing the question back to the
+ * model.
+ */
+import type { CapabilityResult, DecisionPayload } from "../../capabilities/types.js";
+export type DecisionAnswer = {
+    kind: "answer";
+    prompt: string;
+} | {
+    kind: "approve";
+} | {
+    feedback: string;
+    kind: "refine";
+};
+type EnumProperty = {
+    description?: string;
+    enum: string[];
+    enumNames?: string[];
+    title?: string;
+    type: "string";
+};
+type StringProperty = {
+    description?: string;
+    title?: string;
+    type: "string";
+};
+export type DecisionElicitationRequest = {
+    message: string;
+    mode: "form";
+    requestedSchema: {
+        properties: Record<string, EnumProperty | StringProperty>;
+        required: string[];
+        type: "object";
+    };
+};
+/** What a host returns from elicitation/create. */
+type ElicitationOutcome = {
+    action: "accept" | "cancel" | "decline";
+    content?: Record<string, unknown>;
+};
+/**
+ * True when the client advertised form elicitation at initialize.
+ * Empty `elicitation: {}` means form-only per the 2025-11-25 spec.
+ */
+export declare function clientSupportsFormElicitation(capabilities: {
+    elicitation?: Record<string, unknown>;
+} | undefined): boolean;
+/** The decision a capability result is waiting on, if it is waiting on one. */
+export declare function pendingDecision(result: CapabilityResult<unknown>): DecisionPayload | undefined;
+export declare function decisionElicitationRequest(decision: DecisionPayload): DecisionElicitationRequest | undefined;
+/**
+ * The answer a host collected, or undefined when there is nothing to send on —
+ * a dismissed form, or an answer too incomplete to act on (refine with no
+ * feedback). Undefined means the caller should leave the decision in chat.
+ */
+export declare function readDecisionAnswer(decision: DecisionPayload, outcome: ElicitationOutcome): DecisionAnswer | undefined;
+/**
+ * Puts a decision to the user as a form and sends their answer on, returning
+ * the follow-up turn. Returns undefined when the decision should stay in chat,
+ * including when the host rejects the elicitation outright — an older client
+ * that declared the capability but cannot serve it must not lose the decision.
+ */
+export declare function resolveDecisionByElicitation(args: {
+    apply: (answer: DecisionAnswer) => Promise<CapabilityResult<unknown>>;
+    decision: DecisionPayload;
+    elicit: (request: DecisionElicitationRequest) => Promise<ElicitationOutcome>;
+}): Promise<CapabilityResult<unknown> | undefined>;
+export {};

package/dist/transports/mcp/decision-elicitation.js

@@ -0,0 +1,233 @@
+/**
+ * MCP form elicitation for Superblocks decisions (plan approve/refine and
+ * multi_choice questions).
+ *
+ * Chat is the baseline: every decision is also returned as needs_decision +
+ * decision so a host without elicitation can ask the user in its own words. A
+ * host that declares form elicitation gets a real picker instead, and the tool
+ * call answers Superblocks itself rather than handing the question back to the
+ * model.
+ */
+import { gatewayDebug } from "../../debug.js";
+/**
+ * True when the client advertised form elicitation at initialize.
+ * Empty `elicitation: {}` means form-only per the 2025-11-25 spec.
+ */
+export function clientSupportsFormElicitation(capabilities) {
+    if (!capabilities?.elicitation) {
+        gatewayDebug("elicitation capability checked", {
+            "decision.form_supported": false,
+            "decision.reason": "capability_missing",
+        });
+        return false;
+    }
+    const elicitation = capabilities.elicitation;
+    if (Object.keys(elicitation).length === 0) {
+        gatewayDebug("elicitation capability checked", {
+            "decision.form_supported": true,
+            "decision.reason": "empty_capability",
+        });
+        return true;
+    }
+    const result = "form" in elicitation;
+    gatewayDebug("elicitation capability checked", {
+        "decision.form_supported": result,
+        "decision.modes": Object.keys(elicitation),
+        "decision.reason": result ? "form_advertised" : "form_missing",
+    });
+    return result;
+}
+/** The decision a capability result is waiting on, if it is waiting on one. */
+export function pendingDecision(result) {
+    if (result.kind !== "ok") {
+        gatewayDebug("pending decision checked", {
+            "decision.found": false,
+            "decision.reason": "result_error",
+            ...("code" in result ? { "result.code": result.code } : {}),
+            "result.kind": result.kind,
+        });
+        return undefined;
+    }
+    if (!result.value || typeof result.value !== "object") {
+        gatewayDebug("pending decision checked", {
+            "decision.found": false,
+            "decision.reason": "result_has_no_object",
+        });
+        return undefined;
+    }
+    const value = result.value;
+    const decision = value.status === "needs_decision" ? value.decision : undefined;
+    gatewayDebug("pending decision checked", {
+        "decision.found": Boolean(decision),
+        ...(decision ? { "decision.kind": decision.kind } : {}),
+        "decision.reason": decision ? "waiting" : "status_not_waiting",
+        "result.status": value.status,
+    });
+    return decision;
+}
+export function decisionElicitationRequest(decision) {
+    if (decision.kind === "plan") {
+        gatewayDebug("decision request created", {
+            "decision.kind": decision.kind,
+        });
+        return {
+            message: decision.title
+                ? `Superblocks planned "${decision.title}". Build it, or say what to change?`
+                : "Superblocks has a plan. Build it, or say what to change?",
+            mode: "form",
+            requestedSchema: {
+                properties: {
+                    action: {
+                        description: "Approve the plan to build it, or refine it",
+                        enum: ["approve", "refine"],
+                        enumNames: ["Approve — build this plan", "Refine — change it"],
+                        title: "Plan",
+                        type: "string",
+                    },
+                    feedback: {
+                        description: "What to change. Required when refining.",
+                        title: "Changes",
+                        type: "string",
+                    },
+                },
+                required: ["action"],
+                type: "object",
+            },
+        };
+    }
+    if (decision.options.length === 0) {
+        gatewayDebug("decision request skipped", {
+            "decision.kind": decision.kind,
+            "decision.reason": "no_options",
+        });
+        return undefined;
+    }
+    gatewayDebug("decision request created", {
+        "decision.kind": decision.kind,
+        "decision.option_count": decision.options.length,
+    });
+    return {
+        message: decision.question,
+        mode: "form",
+        requestedSchema: {
+            properties: {
+                choice: {
+                    enum: [...decision.options],
+                    title: decision.question,
+                    type: "string",
+                },
+            },
+            required: ["choice"],
+            type: "object",
+        },
+    };
+}
+/**
+ * The answer a host collected, or undefined when there is nothing to send on —
+ * a dismissed form, or an answer too incomplete to act on (refine with no
+ * feedback). Undefined means the caller should leave the decision in chat.
+ */
+export function readDecisionAnswer(decision, outcome) {
+    if (outcome.action !== "accept" || !outcome.content) {
+        gatewayDebug("decision answer read", {
+            "decision.answer_kind": "none",
+            "decision.kind": decision.kind,
+            "decision.reason": outcome.action,
+        });
+        return undefined;
+    }
+    if (decision.kind === "plan") {
+        const action = outcome.content.action;
+        if (action === "approve") {
+            gatewayDebug("decision answer read", {
+                "decision.answer_kind": "approve",
+                "decision.kind": decision.kind,
+            });
+            return { kind: "approve" };
+        }
+        if (action !== "refine") {
+            gatewayDebug("decision answer read", {
+                "decision.answer_kind": "none",
+                "decision.kind": decision.kind,
+                "decision.reason": "invalid_plan_action",
+            });
+            return undefined;
+        }
+        const feedback = typeof outcome.content.feedback === "string"
+            ? outcome.content.feedback.trim()
+            : "";
+        gatewayDebug("decision answer read", {
+            "decision.answer_kind": feedback ? "refine" : "none",
+            "decision.kind": decision.kind,
+            ...(!feedback ? { "decision.reason": "missing_feedback" } : {}),
+        });
+        return feedback ? { feedback, kind: "refine" } : undefined;
+    }
+    const choice = outcome.content.choice;
+    // Only an option Superblocks offered: a free-typed answer would reach Clark
+    // as a prompt for a question it did not ask.
+    const offered = typeof choice === "string" && decision.options.includes(choice);
+    gatewayDebug("decision answer read", {
+        "decision.answer_kind": offered ? "answer" : "none",
+        "decision.kind": decision.kind,
+        ...(!offered ? { "decision.reason": "choice_not_offered" } : {}),
+    });
+    return offered ? { kind: "answer", prompt: choice } : undefined;
+}
+/**
+ * Puts a decision to the user as a form and sends their answer on, returning
+ * the follow-up turn. Returns undefined when the decision should stay in chat,
+ * including when the host rejects the elicitation outright — an older client
+ * that declared the capability but cannot serve it must not lose the decision.
+ */
+export async function resolveDecisionByElicitation(args) {
+    const request = decisionElicitationRequest(args.decision);
+    if (!request) {
+        gatewayDebug("decision elicitation skipped", {
+            "decision.kind": args.decision.kind,
+            "decision.reason": "request_unavailable",
+        });
+        return undefined;
+    }
+    gatewayDebug("decision elicitation started", {
+        "decision.kind": args.decision.kind,
+    });
+    let outcome;
+    try {
+        outcome = await args.elicit(request);
+    }
+    catch (error) {
+        console.error("gateway decision elicitation failed", error);
+        gatewayDebug("decision elicitation finished", {
+            "decision.kind": args.decision.kind,
+            "decision.reason": "host_error",
+            "decision.resolved": false,
+        });
+        return undefined;
+    }
+    gatewayDebug("decision elicitation response received", {
+        "decision.kind": args.decision.kind,
+        "decision.outcome": outcome.action,
+    });
+    const answer = readDecisionAnswer(args.decision, outcome);
+    if (!answer) {
+        gatewayDebug("decision elicitation finished", {
+            "decision.kind": args.decision.kind,
+            "decision.reason": "answer_unavailable",
+            "decision.resolved": false,
+        });
+        return undefined;
+    }
+    gatewayDebug("decision answer applying", {
+        "decision.answer_kind": answer.kind,
+        "decision.kind": args.decision.kind,
+    });
+    const result = await args.apply(answer);
+    gatewayDebug("decision elicitation finished", {
+        "decision.kind": args.decision.kind,
+        "decision.resolved": true,
+        "result.kind": result.kind,
+    });
+    return result;
+}
+//# sourceMappingURL=decision-elicitation.js.map

package/dist/transports/mcp/decision-elicitation.js.map

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

package/dist/transports/mcp/dispatch-probe.d.ts

@@ -0,0 +1,24 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { AppDeps } from "../../deps.js";
+import type { DispatchProbe } from "../../health/readiness.js";
+/**
+ * Proves the gateway can still serve a request end to end on its own tool
+ * surface.
+ *
+ * A route handler that answers `{"status":"ok"}` proves that express is
+ * listening. It does not prove that the MCP server builds, that its tools
+ * registered, or that a JSON-RPC request can be routed to one - which is
+ * exactly the gap ENG-5809 reported: `/health` green in 1ms while every tool
+ * call timed out. This runs the real `createMcpServer` over a linked in-memory
+ * transport and asks it to list its tools, so a break anywhere in construction,
+ * registration, framing, or routing shows up as a failed probe.
+ *
+ * It deliberately stops short of invoking a tool. Every tool needs the caller's
+ * credential and reaches the platform behind the gateway, and a liveness check
+ * that fails when the platform is slow is how a healthy gateway gets restarted
+ * during someone else's outage. Upstream reachability is reported separately
+ * (see {@link GatewayReadiness}).
+ */
+export declare function createMcpDispatchProbe(deps: AppDeps, options?: {
+    createServer?: () => McpServer;
+}): DispatchProbe;

package/dist/transports/mcp/dispatch-probe.js

@@ -0,0 +1,48 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { createMcpServer } from "./mount.js";
+/**
+ * Proves the gateway can still serve a request end to end on its own tool
+ * surface.
+ *
+ * A route handler that answers `{"status":"ok"}` proves that express is
+ * listening. It does not prove that the MCP server builds, that its tools
+ * registered, or that a JSON-RPC request can be routed to one - which is
+ * exactly the gap ENG-5809 reported: `/health` green in 1ms while every tool
+ * call timed out. This runs the real `createMcpServer` over a linked in-memory
+ * transport and asks it to list its tools, so a break anywhere in construction,
+ * registration, framing, or routing shows up as a failed probe.
+ *
+ * It deliberately stops short of invoking a tool. Every tool needs the caller's
+ * credential and reaches the platform behind the gateway, and a liveness check
+ * that fails when the platform is slow is how a healthy gateway gets restarted
+ * during someone else's outage. Upstream reachability is reported separately
+ * (see {@link GatewayReadiness}).
+ */
+export function createMcpDispatchProbe(deps, options = {}) {
+    const createServer = options.createServer ?? (() => createMcpServer(deps));
+    return async () => {
+        const server = createServer();
+        const client = new Client({
+            name: "gateway-dispatch-probe",
+            version: "0.0.1",
+        });
+        const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+        try {
+            await Promise.all([
+                server.connect(serverTransport),
+                client.connect(clientTransport),
+            ]);
+            const { tools } = await client.listTools();
+            if (tools.length === 0) {
+                throw new Error("the gateway's MCP server registered no tools, so no call could be dispatched");
+            }
+        }
+        finally {
+            // Every probe run gets its own server and session. Leaking either would
+            // turn a polled health endpoint into the gateway's largest consumer.
+            await Promise.allSettled([client.close(), server.close()]);
+        }
+    };
+}
+//# sourceMappingURL=dispatch-probe.js.map

package/dist/transports/mcp/dispatch-probe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch-probe.js","sourceRoot":"","sources":["../../../src/transports/mcp/dispatch-probe.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAK1E,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE7C;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,sBAAsB,CACpC,IAAa,EACb,UAA8C,EAAE;IAEhD,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,CAAC,GAAG,EAAE,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC;IAC3E,OAAO,KAAK,IAAI,EAAE;QAChB,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;QAC9B,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC;YACxB,IAAI,EAAE,wBAAwB;YAC9B,OAAO,EAAE,OAAO;SACjB,CAAC,CAAC;QACH,MAAM,CAAC,eAAe,EAAE,eAAe,CAAC,GACtC,iBAAiB,CAAC,gBAAgB,EAAE,CAAC;QACvC,IAAI,CAAC;YACH,MAAM,OAAO,CAAC,GAAG,CAAC;gBAChB,MAAM,CAAC,OAAO,CAAC,eAAe,CAAC;gBAC/B,MAAM,CAAC,OAAO,CAAC,eAAe,CAAC;aAChC,CAAC,CAAC;YACH,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,SAAS,EAAE,CAAC;YAC3C,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACvB,MAAM,IAAI,KAAK,CACb,8EAA8E,CAC/E,CAAC;YACJ,CAAC;QACH,CAAC;gBAAS,CAAC;YACT,wEAAwE;YACxE,qEAAqE;YACrE,MAAM,OAAO,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QAC7D,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

package/dist/transports/mcp/format-tool-content.d.ts

@@ -0,0 +1,25 @@
+import type { CapabilityResult } from "../../capabilities/types.js";
+type ContentBlock = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    data: string;
+    mimeType: "image/jpeg";
+};
+/**
+ * Serializes a capability result for MCP. Screenshot bytes stay in the JSON
+ * (Cursor CLI agents never see the image content block) and are also emitted
+ * as an image block for hosts that render it. App URLs stay in the JSON for
+ * the model and MCP Apps openLink buttons — they are not duplicated as a
+ * markdown chat dump.
+ *
+ * Decisions travel as data too. Prepending a rendered plan plus instructions
+ * on how to offer the options made the model paste that scaffolding into the
+ * chat; the server instructions say how to ask.
+ */
+export declare function formatMcpToolContent(result: CapabilityResult<unknown>, progress?: Array<{
+    type: string;
+    message: string;
+}>): ContentBlock[];
+export {};

package/dist/transports/mcp/format-tool-content.js

@@ -0,0 +1,48 @@
+/**
+ * Serializes a capability result for MCP. Screenshot bytes stay in the JSON
+ * (Cursor CLI agents never see the image content block) and are also emitted
+ * as an image block for hosts that render it. App URLs stay in the JSON for
+ * the model and MCP Apps openLink buttons — they are not duplicated as a
+ * markdown chat dump.
+ *
+ * Decisions travel as data too. Prepending a rendered plan plus instructions
+ * on how to offer the options made the model paste that scaffolding into the
+ * chat; the server instructions say how to ask.
+ */
+export function formatMcpToolContent(result, progress = []) {
+    const { screenshotBase64, textResult } = extractScreenshot(result);
+    const content = [];
+    // Every text block ends in a newline because hosts concatenate them: without
+    // it the trail read "}[progress] Creating application[progress] Connecting
+    // live-edit session", running the JSON body into the first marker and every
+    // marker into the next.
+    content.push({
+        text: `${JSON.stringify(textResult, null, 2)}\n`,
+        type: "text",
+    });
+    content.push(...progress.map((event) => ({
+        text: `[${event.type}] ${event.message}\n`,
+        type: "text",
+    })));
+    if (screenshotBase64) {
+        content.push({
+            data: screenshotBase64,
+            mimeType: "image/jpeg",
+            type: "image",
+        });
+    }
+    return content;
+}
+function extractScreenshot(result) {
+    if (result.kind !== "ok" ||
+        !result.value ||
+        typeof result.value !== "object") {
+        return { screenshotBase64: undefined, textResult: result };
+    }
+    const value = result.value;
+    const screenshotBase64 = typeof value.screenshotBase64 === "string"
+        ? value.screenshotBase64
+        : undefined;
+    return { screenshotBase64, textResult: result };
+}
+//# sourceMappingURL=format-tool-content.js.map

package/dist/transports/mcp/format-tool-content.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-tool-content.js","sourceRoot":"","sources":["../../../src/transports/mcp/format-tool-content.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;GAUG;AACH,MAAM,UAAU,oBAAoB,CAClC,MAAiC,EACjC,WAAqD,EAAE;IAEvD,MAAM,EAAE,gBAAgB,EAAE,UAAU,EAAE,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC;IACnE,MAAM,OAAO,GAAmB,EAAE,CAAC;IACnC,6EAA6E;IAC7E,2EAA2E;IAC3E,4EAA4E;IAC5E,wBAAwB;IACxB,OAAO,CAAC,IAAI,CAAC;QACX,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI;QAChD,IAAI,EAAE,MAAM;KACb,CAAC,CAAC;IACH,OAAO,CAAC,IAAI,CACV,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAC1B,IAAI,EAAE,IAAI,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,OAAO,IAAI;QAC1C,IAAI,EAAE,MAAe;KACtB,CAAC,CAAC,CACJ,CAAC;IACF,IAAI,gBAAgB,EAAE,CAAC;QACrB,OAAO,CAAC,IAAI,CAAC;YACX,IAAI,EAAE,gBAAgB;YACtB,QAAQ,EAAE,YAAY;YACtB,IAAI,EAAE,OAAO;SACd,CAAC,CAAC;IACL,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,iBAAiB,CAAC,MAAiC;IAI1D,IACE,MAAM,CAAC,IAAI,KAAK,IAAI;QACpB,CAAC,MAAM,CAAC,KAAK;QACb,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ,EAChC,CAAC;QACD,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC;IAC7D,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,KAAgC,CAAC;IACtD,MAAM,gBAAgB,GACpB,OAAO,KAAK,CAAC,gBAAgB,KAAK,QAAQ;QACxC,CAAC,CAAC,KAAK,CAAC,gBAAgB;QACxB,CAAC,CAAC,SAAS,CAAC;IAChB,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC;AAClD,CAAC"}

package/dist/transports/mcp/mount.d.ts

@@ -0,0 +1,9 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { AppDeps } from "../../deps.js";
+/**
+ * The MCP server behind one stdio session.
+ *
+ * Tools run as the already-logged-in CLI user. There is no per-request OAuth
+ * token to expire independently of the process.
+ */
+export declare function createMcpServer(deps: AppDeps): McpServer;