@superblocksteam/gateway 2.0.0-SNAPSHOT.1d4c72c0ab174c21

package/dist/stores/types.d.ts

@@ -0,0 +1,74 @@
+/**
+ * What one Gateway process remembers between tool calls.
+ *
+ * All of it is in-memory and lives exactly as long as the process: Gateway
+ * speaks MCP over stdio as a single CLI user, so there is no second reader to
+ * coordinate with and no restart to survive. The stores are synchronous for
+ * the same reason — they are maps, and an async signature would only promise a
+ * round trip that never happens.
+ */
+export type AppScopeKey = {
+    applicationId: string;
+    organizationId: string;
+};
+export type UserScopeKey = {
+    organizationId: string;
+    userId: string;
+};
+/**
+ * The application a caller most recently worked on, so a tool call that names
+ * none still has one to act on.
+ */
+export type RecentAppStore = {
+    get(key: UserScopeKey): string | undefined;
+    set(input: UserScopeKey & {
+        applicationId: string;
+    }): void;
+};
+/**
+ * When a build last spoke, and whether its silence has already been reported.
+ *
+ * App-scoped rather than per-caller: whether a build has gone quiet is a fact
+ * about the build, and two readers of one build must not disagree about it.
+ */
+export type ProgressStore = {
+    lastActivityAtMs(key: AppScopeKey): number | undefined;
+    recordActivity(input: AppScopeKey & {
+        atMs: number;
+    }): void;
+    stallHintedAtMs(key: AppScopeKey): number | undefined;
+    /** `undefined` clears the mark, so the next quiet spell gets its own hint. */
+    recordStallHint(input: AppScopeKey & {
+        atMs: number | undefined;
+    }): void;
+};
+export type StepUpTurnStatus = "pending" | "ready" | "expired";
+/**
+ * An interactive authorization a capability is waiting on.
+ *
+ * The one thing here with a real expiry: a step-up a caller walked away from
+ * must not still be claimable an hour later.
+ */
+export type StepUpTurn = {
+    authUrl: string;
+    callbackToken: string;
+    createdAtMs: number;
+    idempotencyKey: string;
+    reason: "idp_step_up";
+    status: StepUpTurnStatus;
+    turnId: string;
+};
+export type StepUpTurnStore = {
+    complete(turnId: string, callbackToken: string): StepUpTurn | undefined;
+    create(input: {
+        authUrl: string;
+        callbackToken?: string;
+        idempotencyKey: string;
+        reason: StepUpTurn["reason"];
+        ttlMs?: number;
+        turnId?: string;
+    }): StepUpTurn;
+    get(turnId: string): StepUpTurn | undefined;
+    getByIdempotencyKey(idempotencyKey: string): StepUpTurn | undefined;
+};
+export declare const DEFAULT_STEP_UP_TTL_MS = 180000;

package/dist/stores/types.js

@@ -0,0 +1,11 @@
+/**
+ * What one Gateway process remembers between tool calls.
+ *
+ * All of it is in-memory and lives exactly as long as the process: Gateway
+ * speaks MCP over stdio as a single CLI user, so there is no second reader to
+ * coordinate with and no restart to survive. The stores are synchronous for
+ * the same reason — they are maps, and an async signature would only promise a
+ * round trip that never happens.
+ */
+export const DEFAULT_STEP_UP_TTL_MS = 180_000;
+//# sourceMappingURL=types.js.map

package/dist/stores/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/stores/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAmEH,MAAM,CAAC,MAAM,sBAAsB,GAAG,OAAO,CAAC"}

package/dist/telemetry/mcp-client.d.ts

@@ -0,0 +1,22 @@
+import { type Tracer } from "@opentelemetry/api";
+import type { CapabilityResult } from "../capabilities/types.js";
+export type McpClientInfo = {
+    name: string;
+    version?: string;
+};
+export type McpToolCall = {
+    client?: McpClientInfo;
+    toolName: string;
+};
+export declare class McpClientTelemetry {
+    private readonly tracer;
+    private ended;
+    private hadError;
+    private organizationId;
+    private readonly sessionContext;
+    private readonly sessionSpan;
+    constructor(tracer: Tracer);
+    setOrganizationId(organizationId: string): void;
+    runTool<T>(call: McpToolCall, operation: () => Promise<CapabilityResult<T>>): Promise<CapabilityResult<T>>;
+    endSession(): void;
+}

package/dist/telemetry/mcp-client.js

@@ -0,0 +1,140 @@
+import { context, SpanStatusCode, trace, } from "@opentelemetry/api";
+import { recordMcpToolCall } from "./metrics.js";
+function bounded(value, maxLength) {
+    return value.slice(0, maxLength);
+}
+function stringProperty(value, key) {
+    if (typeof value !== "object" || value === null || !(key in value)) {
+        return undefined;
+    }
+    const property = Reflect.get(value, key);
+    return typeof property === "string" ? property : undefined;
+}
+export class McpClientTelemetry {
+    tracer;
+    ended = false;
+    hadError = false;
+    organizationId;
+    sessionContext;
+    sessionSpan;
+    constructor(tracer) {
+        this.tracer = tracer;
+        this.sessionSpan = tracer.startSpan("gen_ai.request", {
+            attributes: {
+                "gen_ai.operation.name": "invoke_agent",
+            },
+        });
+        this.sessionContext = trace.setSpan(context.active(), this.sessionSpan);
+    }
+    setOrganizationId(organizationId) {
+        this.organizationId = organizationId;
+        this.sessionSpan.setAttribute("organization.id", organizationId);
+    }
+    async runTool(call, operation) {
+        const attributes = {
+            "gen_ai.operation.name": "execute_tool",
+            ...(call.client
+                ? {
+                    "mcp.client.name": bounded(call.client.name, 80),
+                    ...(call.client.version
+                        ? {
+                            "mcp.client.version": bounded(call.client.version, 40),
+                        }
+                        : {}),
+                }
+                : {}),
+            ...(this.organizationId
+                ? { "organization.id": this.organizationId }
+                : {}),
+            "tool.name": bounded(call.toolName, 80),
+        };
+        if (call.client) {
+            this.sessionSpan.setAttributes({
+                "mcp.client.name": bounded(call.client.name, 80),
+                ...(call.client.version
+                    ? { "mcp.client.version": bounded(call.client.version, 40) }
+                    : {}),
+            });
+        }
+        let span;
+        try {
+            span = this.tracer.startSpan("gen_ai.tool_call", { attributes }, this.sessionContext);
+        }
+        catch {
+            return operation();
+        }
+        const startedAt = Date.now();
+        let status = "success";
+        try {
+            const result = await context.with(trace.setSpan(this.sessionContext, span), operation);
+            span.setAttribute("tool.duration_ms", Date.now() - startedAt);
+            if (this.organizationId) {
+                span.setAttribute("organization.id", this.organizationId);
+            }
+            if (result.kind === "error") {
+                this.hadError = true;
+                status = "error";
+                span.setAttributes({
+                    ...(result.applicationId
+                        ? { "application.id": result.applicationId }
+                        : {}),
+                    "mcp.error.code": bounded(result.code, 80),
+                    "tool.error_category": result.code === "cancelled" ? "timeout" : "execution_error",
+                    "tool.status": "error",
+                });
+                span.setStatus({ code: SpanStatusCode.ERROR });
+            }
+            else if (result.kind === "auth_required") {
+                this.hadError = true;
+                status = "error";
+                span.setAttributes({
+                    "mcp.result.status": "auth_required",
+                    "tool.error_category": "permission_denied",
+                    "tool.status": "error",
+                });
+            }
+            else {
+                const applicationId = stringProperty(result.value, "applicationId");
+                const resultStatus = stringProperty(result.value, "status");
+                span.setAttributes({
+                    ...(applicationId ? { "application.id": applicationId } : {}),
+                    ...(resultStatus
+                        ? { "mcp.result.status": bounded(resultStatus, 80) }
+                        : {}),
+                    "tool.error_category": "none",
+                    "tool.status": "success",
+                });
+            }
+            return result;
+        }
+        catch (error) {
+            this.hadError = true;
+            status = "error";
+            span.setAttributes({
+                "tool.duration_ms": Date.now() - startedAt,
+                "tool.error_category": "execution_error",
+                "tool.status": "error",
+            });
+            span.setStatus({ code: SpanStatusCode.ERROR });
+            throw error;
+        }
+        finally {
+            recordMcpToolCall({
+                ...(call.client ? { clientName: bounded(call.client.name, 80) } : {}),
+                durationSeconds: (Date.now() - startedAt) / 1000,
+                status,
+                toolName: bounded(call.toolName, 80),
+            });
+            span.end();
+        }
+    }
+    endSession() {
+        if (this.ended) {
+            return;
+        }
+        this.ended = true;
+        this.sessionSpan.setAttribute("gen_ai.request.status", this.hadError ? "error" : "success");
+        this.sessionSpan.end();
+    }
+}
+//# sourceMappingURL=mcp-client.js.map

package/dist/telemetry/mcp-client.js.map

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

package/dist/telemetry/metrics.d.ts

@@ -0,0 +1,41 @@
+import type { IdentityReadOutcome } from "../server/identity-reads.js";
+/**
+ * Series scale with distinct client names, which the caller chooses at
+ * initialize; the name is length-bounded but not enumerated.
+ */
+export declare function recordMcpToolCall(input: {
+    clientName?: string;
+    durationSeconds: number;
+    status: "error" | "success";
+    toolName: string;
+}): void;
+export type CheckpointMetricOutcome = "authentication_failure" | "cleanup_warning" | "conflict_failure" | "downstream_failure" | "saved" | "sync_timeout" | "timeout_failure" | "unchanged";
+/**
+ * How the identity lookup behind a capability is behaving.
+ *
+ * No credential, user, or organization is ever a label — the outcome is a
+ * closed set, so the series count grows with code and not with traffic.
+ */
+export declare function recordIdentityReadOutcome(outcome: IdentityReadOutcome): void;
+export declare function recordCheckpointOutcome(outcome: CheckpointMetricOutcome): void;
+/**
+ * How often the gateway is absorbing faults it used to die from (ENG-5809).
+ *
+ * Neither the message nor a stack is a label; both go to the log line instead.
+ */
+export declare function recordGatewayFault(fault: {
+    fatal: boolean;
+    kind: string;
+}): void;
+/**
+ * Separates "this gateway is broken" from "the platform it fronts is down".
+ *
+ * Kept so in-process dispatch probes can still record a verdict. Stdio Gateway
+ * does not bind `/health`.
+ */
+export declare function recordReadinessVerdict(input: {
+    dispatch: string;
+    probe: "liveness" | "readiness";
+    ready: boolean;
+    upstream: string;
+}): void;

package/dist/telemetry/metrics.js

@@ -0,0 +1,103 @@
+import { metrics, } from "@opentelemetry/api";
+/**
+ * The metrics API has no proxy provider, unlike traces: a meter taken before
+ * the SDK registers one is a no-op forever. Bind on first record instead, and
+ * rebind whenever the global provider changes.
+ */
+function lazyInstrument(create) {
+    let boundMeter;
+    let instrument;
+    return () => {
+        const current = metrics.getMeter("gateway");
+        if (current !== boundMeter || instrument === undefined) {
+            boundMeter = current;
+            instrument = create(current);
+        }
+        return instrument;
+    };
+}
+function lazyCounter(name, description) {
+    return lazyInstrument((boundMeter) => boundMeter.createCounter(name, { description }));
+}
+function lazyHistogram(name, description, bucketBoundaries) {
+    return lazyInstrument((boundMeter) => boundMeter.createHistogram(name, {
+        advice: { explicitBucketBoundaries: bucketBoundaries },
+        description,
+        unit: "s",
+    }));
+}
+const mcpToolCalls = lazyCounter("gateway.mcp.tool_calls", "MCP tool calls by tool, calling client, and outcome");
+/** Tool calls run from single-digit milliseconds to a multi-minute build. */
+const TOOL_DURATION_BUCKETS_SECONDS = [
+    0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30, 60, 120, 300,
+];
+const mcpToolCallDuration = lazyHistogram("gateway.mcp.tool_call_duration_seconds", "Wall-clock duration of an MCP tool call", TOOL_DURATION_BUCKETS_SECONDS);
+/**
+ * Series scale with distinct client names, which the caller chooses at
+ * initialize; the name is length-bounded but not enumerated.
+ */
+export function recordMcpToolCall(input) {
+    const attributes = {
+        ...(input.clientName ? { "mcp.client.name": input.clientName } : {}),
+        "tool.name": input.toolName,
+        "tool.status": input.status,
+    };
+    mcpToolCalls().add(1, attributes);
+    mcpToolCallDuration().record(input.durationSeconds, attributes);
+}
+function resourceAttributes() {
+    return {
+        "deployment.environment.name": process.env.DEPLOYMENT_ENVIRONMENT_NAME ?? "local",
+        "service.name": "gateway",
+    };
+}
+const identityReadOutcomes = lazyCounter("gateway.identity.read.outcomes", "Caller-identity lookups by outcome: served from cache, resolved, refused, or unavailable");
+/**
+ * How the identity lookup behind a capability is behaving.
+ *
+ * No credential, user, or organization is ever a label — the outcome is a
+ * closed set, so the series count grows with code and not with traffic.
+ */
+export function recordIdentityReadOutcome(outcome) {
+    identityReadOutcomes().add(1, {
+        ...resourceAttributes(),
+        "gateway.outcome": outcome,
+    });
+}
+const checkpointOutcomes = lazyCounter("gateway.checkpoint.outcomes", "Clark checkpoint attempts by bounded outcome");
+export function recordCheckpointOutcome(outcome) {
+    checkpointOutcomes().add(1, {
+        ...resourceAttributes(),
+        "gateway.checkpoint.outcome": outcome,
+    });
+}
+const processFaults = lazyCounter("gateway.process.faults", "Faults the process-level barrier caught, by kind and whether it gave up the process");
+/**
+ * How often the gateway is absorbing faults it used to die from (ENG-5809).
+ *
+ * Neither the message nor a stack is a label; both go to the log line instead.
+ */
+export function recordGatewayFault(fault) {
+    processFaults().add(1, {
+        ...resourceAttributes(),
+        "gateway.fault.fatal": String(fault.fatal),
+        "gateway.fault.kind": fault.kind,
+    });
+}
+const readinessVerdicts = lazyCounter("gateway.readiness.verdicts", "Health and readiness probe verdicts, by dispatch state and upstream reachability");
+/**
+ * Separates "this gateway is broken" from "the platform it fronts is down".
+ *
+ * Kept so in-process dispatch probes can still record a verdict. Stdio Gateway
+ * does not bind `/health`.
+ */
+export function recordReadinessVerdict(input) {
+    readinessVerdicts().add(1, {
+        ...resourceAttributes(),
+        "gateway.readiness.dispatch": input.dispatch,
+        "gateway.readiness.probe": input.probe,
+        "gateway.readiness.ready": String(input.ready),
+        "gateway.readiness.upstream": input.upstream,
+    });
+}
+//# sourceMappingURL=metrics.js.map

package/dist/telemetry/metrics.js.map

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

package/dist/telemetry/runtime.d.ts

@@ -0,0 +1,9 @@
+import type { GatewayConfig } from "../config.js";
+import { McpClientTelemetry } from "./mcp-client.js";
+export declare function startGatewayTelemetry(input: {
+    apiKey: string;
+    config: GatewayConfig;
+}): {
+    mcpTelemetry: McpClientTelemetry;
+    shutdown: () => Promise<void>;
+};

package/dist/telemetry/runtime.js

@@ -0,0 +1,118 @@
+import { DeploymentType, getDefaultPolicy, parseDeploymentType, } from "@superblocksteam/telemetry";
+import { initNodeTelemetry } from "@superblocksteam/telemetry/node";
+import { McpClientTelemetry } from "./mcp-client.js";
+const TELEMETRY_SHUTDOWN_MS = 2_000;
+/**
+ * stdout is the MCP JSON-RPC wire. Without a logger the shared init falls back
+ * to console.info, which writes there and corrupts the protocol.
+ */
+function logToStderr(first, message) {
+    if (message === undefined) {
+        console.error(first);
+        return;
+    }
+    console.error(first, message);
+}
+const stderrLogger = {
+    error: logToStderr,
+    info: logToStderr,
+    warn: logToStderr,
+};
+function telemetryBaseUrl(serverUrl) {
+    try {
+        const url = new URL(serverUrl);
+        url.hash = "";
+        url.pathname = `${url.pathname.replace(/\/$/u, "")}/api`;
+        url.search = "";
+        return url.toString().replace(/\/$/u, "");
+    }
+    catch {
+        console.error("gateway telemetry skipped: server URL is not parseable");
+        return undefined;
+    }
+}
+function environmentName(config) {
+    if (config.deploymentEnvironmentName !== "unknown") {
+        return config.deploymentEnvironmentName;
+    }
+    try {
+        return environmentFromHostname(new URL(config.serverUrl).hostname);
+    }
+    catch {
+        return "unknown";
+    }
+}
+function environmentFromHostname(hostname) {
+    if (hostname.match(/^app\.superblocks(?:hq)?\.com$/u)) {
+        return "prod";
+    }
+    if (hostname.match(/^eu\.superblocks(?:hq)?\.com$/u)) {
+        return "prod-eu";
+    }
+    if (hostname.match(/^staging\.superblocks(?:hq)?\.com$/u)) {
+        return "staging";
+    }
+    if (hostname.match(/^dev\.superblocks(?:hq)?\.com$/u)) {
+        return "dev";
+    }
+    if (hostname.match(/^pr-[0-9]+\.superblocks(?:hq)?\.dev$/u)) {
+        return "ephemeral";
+    }
+    if (hostname === "localhost" || hostname === "127.0.0.1") {
+        return "local";
+    }
+    return "other";
+}
+function deploymentTypeFor(config) {
+    if (config.localAgentMode) {
+        return DeploymentType.CLOUD_PREM;
+    }
+    try {
+        return parseDeploymentType(process.env.SUPERBLOCKS_DEPLOYMENT_TYPE);
+    }
+    catch {
+        return DeploymentType.CLOUD;
+    }
+}
+async function settleWithin(work, timeoutMs) {
+    let timer;
+    try {
+        await Promise.race([
+            work,
+            new Promise((resolve) => {
+                timer = setTimeout(resolve, timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timer !== undefined) {
+            clearTimeout(timer);
+        }
+    }
+}
+export function startGatewayTelemetry(input) {
+    const otlpUrl = telemetryBaseUrl(input.config.serverUrl);
+    const telemetry = initNodeTelemetry({
+        environment: environmentName(input.config),
+        logger: stderrLogger,
+        logsEnabled: false,
+        metricsEnabled: true,
+        otlpHeaders: { Authorization: `Bearer ${input.apiKey}` },
+        ...(otlpUrl ? { otlpUrl } : {}),
+        serviceName: "gateway",
+        serviceVersion: "0.0.1",
+    }, getDefaultPolicy(deploymentTypeFor(input.config)));
+    const mcpTelemetry = new McpClientTelemetry(telemetry.getTracer("gateway.mcp"));
+    return {
+        mcpTelemetry,
+        shutdown: async () => {
+            try {
+                mcpTelemetry.endSession();
+            }
+            finally {
+                await settleWithin(telemetry.shutdown(), TELEMETRY_SHUTDOWN_MS);
+            }
+        },
+    };
+}
+//# sourceMappingURL=runtime.js.map

package/dist/telemetry/runtime.js.map

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

package/dist/transports/mcp/admin-tools.d.ts

@@ -0,0 +1,56 @@
+import type { AuthInfo } from "@modelcontextprotocol/sdk/server/auth/types.js";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { Tool, ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+import { type ToolRegistry } from "@superblocksteam/mcp-server";
+import type { ClientProfile } from "./client-presentation.js";
+export type RegisterAdminToolsOptions = {
+    /**
+     * Superblocks Server base URL injected as `base_url` when the caller omits it.
+     * Models should not invent environments; the gateway already knows the control plane.
+     */
+    serverUrl: string;
+    /**
+     * Fixed credential for tests and tightly scoped callers. Prefer `resolveApiKey`
+     * on the live HTTP path so each tool call uses the caller's downstream key.
+     */
+    apiKey?: string;
+    resolveApiKey?: (auth: AuthInfo | undefined) => Promise<string>;
+    /**
+     * Cloud-Prem / laptop Admin agents (`GATEWAY_LOCAL_AGENT`) talk to a control
+     * plane that carries no SaaS billing plan, so the Admin tools' Enterprise/POC
+     * plan lookup would refuse every call. Entitlement for those installs is
+     * established by the deployment itself. SaaS-hosted Gateways leave this off
+     * and keep the check.
+     */
+    localAgentMode?: boolean;
+    clientProfile?: () => ClientProfile;
+    /**
+     * When the session already has an application, send credential entry to the
+     * editor Integrations tab instead of the org Integrations page.
+     */
+    resolveEditorIntegrationSetupUrl?: (integrationId: string) => string | undefined | Promise<string | undefined>;
+};
+export type JsonSchemaToZodShapeOptions = {
+    /** Advertised as optional no matter what the source schema requires. */
+    optionalKeys?: readonly string[];
+};
+/**
+ * Loose JSON-Schema -> Zod conversion so `registerTool` can list Admin tools
+ * with usable shapes. Handlers still validate through `@superblocksteam/mcp-server`.
+ */
+export declare function jsonSchemaToZodShape(inputSchema: Tool["inputSchema"], options?: JsonSchemaToZodShapeOptions): Record<string, z.ZodType>;
+/**
+ * Gateway product copy names the builder Superblocks. Admin tool definitions
+ * still mention the retired "Clark" alias in places; rewrite for this surface
+ * so clients do not reintroduce that name.
+ */
+export declare function superblocksProductCopy(text: string): string;
+/** Completes MCP hints without overriding shared Admin definitions. */
+export declare function completeToolAnnotations(annotations: ToolAnnotations | undefined): ToolAnnotations;
+/**
+ * Registers customer-profile Admin MCP tools on the same McpServer as Builder
+ * tools. Each call runs under `runWithAuthContext` with the Gateway's
+ * downstream credential, against the `serverUrl` that credential belongs to.
+ */
+export declare function registerAdminTools(server: McpServer, options: RegisterAdminToolsOptions): ToolRegistry;