@opengeni/api-router 0.23.1 → 0.30.0

package/src/memory-slack-delivery.ts

@@ -0,0 +1,209 @@
+import {
+  claimMemorySlackPublication,
+  completeMemorySlackPublication,
+  currentMemorySlackConfigurationMatches,
+  deferMemorySlackPublication,
+  failMemorySlackPublication,
+  type ClaimedMemorySlackPublication,
+} from "@opengeni/db";
+import { sanitizeSlackPublicationText, type ApiRouteDeps } from "@opengeni/core";
+import {
+  createOpenGeniSlackBotInteractionClient,
+  SlackBotProviderError,
+} from "./integrations/slack-bot";
+
+const DELIVERY_LEASE_MS = 30_000;
+const MAX_DELIVERY_ATTEMPTS = 8;
+const MAX_DELIVERY_RETRY_MS = 5 * 60_000;
+const MAX_SLACK_MESSAGE_CHARS = 3_500;
+
+export async function drainMemorySlackPublicationsOnce(deps: ApiRouteDeps): Promise<boolean> {
+  const claimHolderId = crypto.randomUUID();
+  const publication = await claimMemorySlackPublication(deps.db, claimHolderId, DELIVERY_LEASE_MS);
+  if (!publication) return false;
+
+  try {
+    if (!(await currentMemorySlackConfigurationMatches(deps.db, publication))) {
+      await failMemorySlackPublication(deps.db, {
+        publication,
+        claimHolderId,
+        errorCode: "configuration_changed",
+        cancelled: true,
+      });
+      return true;
+    }
+    const client = await createOpenGeniSlackBotInteractionClient(deps, {
+      accountId: publication.accountId,
+      workspaceId: publication.workspaceId,
+      connectionId: publication.connectionId,
+      subjectId: publication.initiatorSubjectId,
+      sessionId: publication.sessionId,
+    });
+    const result = await client.postMessage({
+      operationId: publication.operationId,
+      channelId: publication.slackChannelId,
+      text: formatMemorySlackPublicationMessage(deps, publication),
+      requireActiveNonSharedChannel: true,
+    });
+    const completed = await completeMemorySlackPublication(deps.db, {
+      publication,
+      claimHolderId,
+      slackChannelId: result.channelId,
+      slackMessageTimestamp: result.timestamp,
+    });
+    if (!completed) throw new Error("Memory Slack publication lost its durable claim");
+  } catch (error) {
+    const errorCode = deliveryErrorCode(error);
+    if (memorySlackDestinationDrift(error)) {
+      await failMemorySlackPublication(deps.db, {
+        publication,
+        claimHolderId,
+        errorCode,
+        cancelled: true,
+      }).catch(() => undefined);
+    } else if (publication.attemptCount >= MAX_DELIVERY_ATTEMPTS || permanentDeliveryError(error)) {
+      await failMemorySlackPublication(deps.db, {
+        publication,
+        claimHolderId,
+        errorCode,
+      }).catch(() => undefined);
+    } else {
+      await deferMemorySlackPublication(deps.db, {
+        publication,
+        claimHolderId,
+        errorCode,
+        retryAt: new Date(Date.now() + deliveryRetryMs(error, publication.attemptCount)),
+      }).catch(() => undefined);
+    }
+  }
+  return true;
+}
+
+export function startMemorySlackPublicationPump(
+  deps: ApiRouteDeps,
+  options: { intervalMs?: number; maxPerTick?: number } = {},
+): () => Promise<void> {
+  let stopped = false;
+  let running: Promise<void> | undefined;
+  const intervalMs = Math.max(250, options.intervalMs ?? 1_000);
+  const maxPerTick = Math.max(1, Math.min(50, options.maxPerTick ?? 10));
+  const tick = () => {
+    if (stopped || running) return;
+    running = (async () => {
+      for (let index = 0; index < maxPerTick; index += 1) {
+        if (!(await drainMemorySlackPublicationsOnce(deps))) break;
+      }
+    })()
+      .catch((error) => {
+        deps.observability?.error("Memory Slack publication claim failed", {
+          errorClass: error instanceof Error ? error.name : "MemorySlackPublicationPumpError",
+          errorCode: deliveryErrorCode(error),
+          origin: "api",
+        });
+      })
+      .finally(() => {
+        running = undefined;
+      });
+  };
+  const timer = setInterval(tick, intervalMs);
+  queueMicrotask(tick);
+  return async () => {
+    stopped = true;
+    clearInterval(timer);
+    await running;
+  };
+}
+
+export function formatMemorySlackPublicationMessage(
+  deps: Pick<ApiRouteDeps, "settings">,
+  publication: ClaimedMemorySlackPublication,
+): string {
+  const projection = publication.projection;
+  const summary = boundedProjectionString(projection["summary"], 512) || "Important change";
+  const owner = boundedProjectionString(projection["ownerLabel"], 96);
+  const occurredAt = boundedProjectionString(projection["occurredAt"], 64);
+  const changeKind = boundedProjectionString(projection["changeKind"], 32);
+  const destination = boundedProjectionString(projection["destination"], 64);
+  const outcome = boundedProjectionString(projection["outcome"], 64);
+  const heading =
+    publication.sourceType === "workspace_memory"
+      ? `Workspace Memory ${changeKind || "change"}`
+      : `Governed learning ${outcome || "change"}`;
+  const details = [
+    `Importance: ${publication.importance}`,
+    ...(destination ? [`Surface: ${destination}`] : []),
+    ...(owner ? [`Owner: ${owner}`] : []),
+    ...(occurredAt ? [`Recorded: ${occurredAt}`] : []),
+  ];
+  const path =
+    publication.sourceType === "workspace_memory"
+      ? `/workspaces/${publication.workspaceId}/memory?memoryId=${encodeURIComponent(publication.sourceId)}`
+      : `/workspaces/${publication.workspaceId}/workspace-state`;
+  const base = deps.settings.webBaseUrl ?? deps.settings.publicBaseUrl;
+  const link = base ? new URL(path, base).toString() : null;
+  const text = `*${heading}*\n${summary}\n\n${details.join(" · ")}${link ? `\n${link}` : ""}`;
+  return text.length <= MAX_SLACK_MESSAGE_CHARS
+    ? text
+    : `${text.slice(0, MAX_SLACK_MESSAGE_CHARS - 20)}\n… message truncated`;
+}
+
+const PERMANENT_DELIVERY_CODES = new Set([
+  "account_inactive",
+  "channel_not_found",
+  "invalid_auth",
+  "is_archived",
+  "not_authed",
+  "not_in_channel",
+  "token_expired",
+  "token_revoked",
+]);
+
+const MEMORY_SLACK_DESTINATION_DRIFT_CODES = new Set([
+  "channel_not_found",
+  "is_archived",
+  "not_in_channel",
+  "slack_connect_unsupported",
+]);
+
+export function memorySlackDestinationDrift(error: unknown) {
+  return (
+    error instanceof SlackBotProviderError && MEMORY_SLACK_DESTINATION_DRIFT_CODES.has(error.code)
+  );
+}
+
+function permanentDeliveryError(error: unknown) {
+  if (!(error instanceof SlackBotProviderError)) return false;
+  if (PERMANENT_DELIVERY_CODES.has(error.code)) return true;
+  const status = /^http_(\d{3})$/.exec(error.code)?.[1];
+  return status
+    ? Number(status) >= 400 && Number(status) < 500 && status !== "408" && status !== "429"
+    : false;
+}
+
+function deliveryRetryMs(error: unknown, attemptCount: number) {
+  if (error instanceof SlackBotProviderError && error.retryAfterMs) {
+    return Math.min(Math.max(error.retryAfterMs, 1_000), MAX_DELIVERY_RETRY_MS);
+  }
+  return Math.min(1_000 * 2 ** Math.max(0, attemptCount - 1), MAX_DELIVERY_RETRY_MS);
+}
+
+function deliveryErrorCode(error: unknown) {
+  if (error instanceof SlackBotProviderError) return error.code.slice(0, 128);
+  const raw = error instanceof Error ? error.name : "memory_slack_delivery_error";
+  return (
+    raw
+      .toLowerCase()
+      .replace(/[^a-z0-9_-]/g, "_")
+      .slice(0, 128) || "error"
+  );
+}
+
+function boundedProjectionString(value: unknown, maxChars: number) {
+  return typeof value === "string"
+    ? escapeSlackText(sanitizeSlackPublicationText(value).slice(0, maxChars))
+    : "";
+}
+
+function escapeSlackText(value: string) {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}

package/src/model-catalog.ts

@@ -2,6 +2,7 @@ import {
   configuredModels,
   configuredProviders,
   withCodexCatalogProvider,
+  withXaiSubscriptionCatalogProvider,
   withWorkspaceGatewayCatalogProvider,
   type ConfiguredModel,
   type Settings,
@@ -37,16 +38,20 @@ export const MODEL_CREDENTIAL_READINESS_OBSERVATION_MAX_AGE_MS = 5 * 60_000;
 export function projectClientModel(model: ConfiguredModel): ClientModel {
   const source =
     model.credentialSource.kind === "connected_subscription"
-      ? "codex"
+      ? model.credentialSource.provider === "xai"
+        ? "supergrok"
+        : "codex"
       : model.credentialSource.kind === "workspace_connection"
         ? "workspace_gateway"
         : "opengeni";
   const publicProvider =
     source === "codex"
       ? { provider: "codex", providerLabel: "Codex" }
-      : source === "workspace_gateway"
-        ? { provider: "workspace-gateway", providerLabel: "Your Gateway" }
-        : { provider: "opengeni", providerLabel: "OpenGeni" };
+      : source === "supergrok"
+        ? { provider: "supergrok", providerLabel: "SuperGrok" }
+        : source === "workspace_gateway"
+          ? { provider: "workspace-gateway", providerLabel: "Your Gateway" }
+          : { provider: "opengeni", providerLabel: "OpenGeni" };
   return ClientModel.parse({
     id: model.id,
     label: model.label,
@@ -131,6 +136,7 @@ function credentialReadinessFor(input: {
   model: ConfiguredModel;
   provider: ReturnType<typeof configuredProviders>[number] | undefined;
   codexSubscriptionActive: boolean;
+  xaiSubscriptionActive: boolean;
   workspaceGatewayConnectionActive: boolean;
   observation: ModelCredentialReadinessObservation | undefined;
   nowMs: number;
@@ -138,7 +144,9 @@ function credentialReadinessFor(input: {
 }): ModelCredentialReadinessV1 {
   const source = input.model.credentialSource;
   if (source.kind === "connected_subscription") {
-    return input.codexSubscriptionActive
+    const active =
+      source.provider === "xai" ? input.xaiSubscriptionActive : input.codexSubscriptionActive;
+    return active
       ? { status: "ready", reason: null, basis: "connection", checkedAt: null }
       : {
           status: "not_ready",
@@ -309,6 +317,7 @@ export function buildWorkspaceModelCatalog(input: {
   settings: Settings;
   policy: WorkspaceModelPolicyContract | null;
   codexSubscriptionActive: boolean;
+  xaiSubscriptionActive?: boolean;
   workspaceGatewayConnectionActive?: boolean;
   credentialReadinessObservations?:
     | Readonly<Record<string, ModelCredentialReadinessObservation>>
@@ -320,7 +329,10 @@ export function buildWorkspaceModelCatalog(input: {
   const codexSettings = input.settings.codexSubscriptionEnabled
     ? withCodexCatalogProvider(input.settings)
     : input.settings;
-  const catalogSettings = withWorkspaceGatewayCatalogProvider(codexSettings);
+  const xaiSettings = input.settings.supergrokSubscriptionEnabled
+    ? withXaiSubscriptionCatalogProvider(codexSettings)
+    : codexSettings;
+  const catalogSettings = withWorkspaceGatewayCatalogProvider(xaiSettings);
   const providers = new Map(
     configuredProviders(catalogSettings).map((provider) => [provider.id, provider]),
   );
@@ -341,6 +353,7 @@ export function buildWorkspaceModelCatalog(input: {
       model,
       provider,
       codexSubscriptionActive: input.codexSubscriptionActive,
+      xaiSubscriptionActive: input.xaiSubscriptionActive === true,
       workspaceGatewayConnectionActive: input.workspaceGatewayConnectionActive === true,
       observation: input.credentialReadinessObservations?.[model.definitionVersion],
       nowMs,

package/src/routes/api-integrations.ts

@@ -0,0 +1,410 @@
+import {
+  CORE_INTEGRATION_DEFINITIONS,
+  createPinnedIntegrationTransport,
+  integrationFacetDefinitions,
+  type IntegrationCredentialResolver,
+} from "@opengeni/capabilities";
+import {
+  ApiIntegrationPreview,
+  ListIntegrationDefinitionsResponse,
+  ApiIntegrationUninstallPreview,
+  InstallApiIntegrationRequest,
+  InstalledApiIntegration,
+  ListApiIntegrationsResponse,
+  PreviewApiIntegrationRequest,
+  UninstallApiIntegrationRequest,
+  UninstallApiIntegrationResult,
+} from "@opengeni/contracts";
+import { requireAccessGrant, type ApiRouteDeps } from "@opengeni/core";
+import {
+  ApiIntegrationInstallationVersionConflictError,
+  buildConnectionTokenResolver,
+  getApiIntegrationUninstallPreview,
+  getConnectionMetadata,
+  installApiIntegration,
+  IntegrationFacetBindingOwnershipConflictError,
+  IntegrationFacetBindingVersionConflictError,
+  IntegrationFacetBindingVersionRequiredError,
+  listInstalledApiIntegrations,
+  uninstallApiIntegration,
+  type ConnectionMetadataWithVerification,
+} from "@opengeni/db";
+import type { FetchLike } from "@opengeni/network";
+import type { Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+
+import {
+  resolveApiIntegrationPreview,
+  type ApiIntegrationConnectionDescriptor,
+} from "../integrations/api-integrations";
+
+export type ApiIntegrationRouteOverrides = Readonly<{ fetchImpl?: FetchLike }>;
+
+export function apiIntegrationRequiresConnection(authScheme: Record<string, unknown>): boolean {
+  const authKind = authScheme.kind;
+  return typeof authKind === "string" && authKind !== "none";
+}
+
+export function registerApiIntegrationRoutes(
+  app: Hono,
+  deps: ApiRouteDeps,
+  overrides: ApiIntegrationRouteOverrides = {},
+): void {
+  const transport = createPinnedIntegrationTransport({
+    network: deps.settings,
+    ...(overrides.fetchImpl ? { fetchImpl: overrides.fetchImpl } : {}),
+  });
+
+  app.get("/v1/workspaces/:workspaceId/integrations/definitions", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    await requireAccessGrant(c, deps, workspaceId, "workspace:read");
+    return c.json(
+      ListIntegrationDefinitionsResponse.parse({
+        definitions: CORE_INTEGRATION_DEFINITIONS.map((definition) => ({
+          id: definition.id,
+          name: definition.name,
+          summary: definition.summary,
+          protocol: definition.protocol,
+          provider: { ...definition.provider },
+          authentication: {
+            kind: definition.authentication.kind,
+            scopes: [...definition.authentication.scopes],
+          },
+          facets: definition.facets.map((facet) => ({
+            facetKey: facet.facetKey,
+            kind: facet.kind,
+            configSchema: { ...facet.configSchema },
+            capabilities: { ...facet.capabilities },
+          })),
+        })),
+      }),
+    );
+  });
+
+  app.get("/v1/workspaces/:workspaceId/integrations", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:read");
+    const integrations = await listInstalledApiIntegrations(deps.db, workspaceId, grant.subjectId);
+    return c.json(
+      ListApiIntegrationsResponse.parse({
+        integrations: integrations.map((integration) => {
+          return {
+            capabilityId: integration.capabilityId,
+            pluginKey: integration.pluginKey,
+            installationVersion: integration.installationVersion,
+            instanceId: integration.instanceId,
+            instanceKey: integration.instanceKey,
+            displayName: integration.displayName,
+            instanceVersion: integration.instanceVersion,
+            serverId: integration.serverId,
+            name: integration.name,
+            description: integration.description,
+            protocol: integration.protocol,
+            definitionId: integration.definitionId,
+            definitionProvenance: integration.definitionProvenance,
+            providerDomain: integration.providerDomain,
+            baseUrl: integration.baseUrl,
+            sourceUrl: integration.sourceUrl,
+            connected: integration.connectionRef !== null,
+            requiresConnection: apiIntegrationRequiresConnection(integration.authScheme),
+            connectionId: integration.connectionRef?.connectionId ?? null,
+            ownership:
+              integration.connectionRef?.subjectScope === "subject"
+                ? "personal"
+                : integration.connectionRef
+                  ? "workspace"
+                  : "none",
+            allowedTools: integration.allowedTools,
+            toolCount: integration.allowedTools.length,
+            approvalRequiredToolCount:
+              integration.requireApproval === true
+                ? integration.allowedTools.length
+                : integration.requireApproval.length,
+            revisionId: integration.revision.id,
+            contentSha256: integration.revision.contentSha256,
+          };
+        }),
+      }),
+    );
+  });
+
+  app.post("/v1/workspaces/:workspaceId/integrations/preview", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:read");
+    const payload = PreviewApiIntegrationRequest.parse(await c.req.json());
+    const resolved = await resolveForRoute({
+      deps,
+      transport,
+      workspaceId,
+      subjectId: grant.subjectId,
+      payload,
+    });
+    return c.json(ApiIntegrationPreview.parse(resolved.preview));
+  });
+
+  app.post("/v1/workspaces/:workspaceId/integrations/install", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
+    const payload = InstallApiIntegrationRequest.parse(await c.req.json());
+    const resolved = await resolveForRoute({
+      deps,
+      transport,
+      workspaceId,
+      subjectId: grant.subjectId,
+      payload,
+    });
+    if (
+      resolved.preview.revisionId !== payload.expectedRevisionId ||
+      resolved.preview.contentSha256 !== payload.expectedContentSha256
+    ) {
+      throw new HTTPException(409, {
+        message:
+          "The Integration source changed after preview. Review the new tools and permissions before installing.",
+      });
+    }
+    if (resolved.preview.auth.kind !== "none" && !payload.connectionId) {
+      throw new HTTPException(422, {
+        message: "Connect an account before installing this Integration.",
+      });
+    }
+    if (
+      payload.ownership &&
+      resolved.preview.connectionOwnership &&
+      payload.ownership !== resolved.preview.connectionOwnership
+    ) {
+      throw new HTTPException(422, {
+        message: "The selected Connection ownership does not match this install request.",
+      });
+    }
+    if (payload.ownership === "personal" && !resolved.preview.connectionOwnership) {
+      throw new HTTPException(422, {
+        message: "Choose a Personal Connection before installing for yourself.",
+      });
+    }
+    try {
+      return c.json(
+        InstalledApiIntegration.parse(
+          await installApiIntegration(deps.db, {
+            accountId: grant.accountId,
+            workspaceId,
+            subjectId: grant.subjectId,
+            capabilityId: resolved.preview.capabilityId,
+            pluginKey: resolved.preview.pluginKey,
+            serverId: resolved.preview.serverId,
+            name: resolved.preview.name,
+            description: resolved.preview.description,
+            category: "integrations",
+            tags: [resolved.preview.protocol, resolved.preview.provider ?? "custom"],
+            definitionId: resolved.preview.definitionId,
+            definitionProvenance: resolved.preview.definitionProvenance,
+            ...(resolved.provider ? { provider: resolved.provider } : {}),
+            providerDomain: resolved.preview.providerDomain,
+            protocol: resolved.preview.protocol,
+            baseUrl: resolved.preview.baseUrl,
+            sourceUrl: resolved.preview.sourceUrl,
+            authScheme: resolved.authScheme,
+            ...(payload.connectionId ? { connectionId: payload.connectionId } : {}),
+            ...(payload.instanceKey ? { instanceKey: payload.instanceKey } : {}),
+            ...(payload.displayName ? { displayName: payload.displayName } : {}),
+            ...(payload.expectedInstanceVersion !== undefined
+              ? { expectedInstanceVersion: payload.expectedInstanceVersion }
+              : {}),
+            requiredScopes: resolved.requiredScopes,
+            ownership:
+              resolved.preview.connectionOwnership === "personal" ? "subject" : "workspace",
+            ...(payload.allowedTools ? { allowedTools: payload.allowedTools } : {}),
+            facetDefinitions: integrationFacetDefinitions(resolved.preview.definitionId),
+            revision: resolved.revision,
+          }),
+        ),
+        payload.expectedInstanceVersion === undefined ? 201 : 200,
+      );
+    } catch (error) {
+      if (
+        error instanceof IntegrationFacetBindingVersionConflictError ||
+        error instanceof IntegrationFacetBindingVersionRequiredError ||
+        error instanceof IntegrationFacetBindingOwnershipConflictError
+      ) {
+        throw new HTTPException(409, {
+          message:
+            "The Integration instance changed or is shared by another owner. Refresh its details before updating it.",
+        });
+      }
+      throw error;
+    }
+  });
+
+  app.get(
+    "/v1/workspaces/:workspaceId/integrations/:capabilityId/instances/:instanceKey/uninstall-preview",
+    async (c) => {
+      const workspaceId = c.req.param("workspaceId");
+      const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:read");
+      return c.json(
+        ApiIntegrationUninstallPreview.parse(
+          await getApiIntegrationUninstallPreview(
+            deps.db,
+            workspaceId,
+            grant.subjectId,
+            decodeURIComponent(c.req.param("capabilityId")),
+            decodeURIComponent(c.req.param("instanceKey")),
+          ),
+        ),
+      );
+    },
+  );
+
+  app.delete(
+    "/v1/workspaces/:workspaceId/integrations/:capabilityId/instances/:instanceKey",
+    async (c) => {
+      const workspaceId = c.req.param("workspaceId");
+      const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
+      const capabilityId = decodeURIComponent(c.req.param("capabilityId"));
+      const instanceKey = decodeURIComponent(c.req.param("instanceKey"));
+      const payload = UninstallApiIntegrationRequest.parse(await c.req.json());
+      try {
+        return c.json(
+          UninstallApiIntegrationResult.parse(
+            await uninstallApiIntegration(deps.db, {
+              accountId: grant.accountId,
+              workspaceId,
+              subjectId: grant.subjectId,
+              capabilityId,
+              instanceKey,
+              expectedInstallationVersion: payload.expectedInstallationVersion,
+              expectedInstanceVersion: payload.expectedInstanceVersion,
+            }),
+          ),
+        );
+      } catch (error) {
+        if (
+          error instanceof ApiIntegrationInstallationVersionConflictError ||
+          error instanceof IntegrationFacetBindingVersionConflictError
+        ) {
+          throw new HTTPException(409, {
+            message:
+              "The Integration instance changed after preview. Review uninstall impact again.",
+          });
+        }
+        throw error;
+      }
+    },
+  );
+}
+
+async function resolveForRoute(input: {
+  deps: ApiRouteDeps;
+  transport: ReturnType<typeof createPinnedIntegrationTransport>;
+  workspaceId: string;
+  subjectId: string;
+  payload: PreviewApiIntegrationRequest | InstallApiIntegrationRequest;
+}): ReturnType<typeof resolveApiIntegrationPreview> {
+  try {
+    const connection = input.payload.connectionId
+      ? await requireVisibleConnection(
+          input.deps,
+          input.workspaceId,
+          input.subjectId,
+          input.payload.connectionId,
+        )
+      : null;
+    return await resolveApiIntegrationPreview({
+      source: input.payload.source,
+      connection: connectionDescriptor(connection),
+      transport: input.transport,
+      authority: {
+        accountId: connection?.accountId ?? "preview",
+        workspaceId: input.workspaceId,
+        initiatingSubjectId: input.subjectId,
+        ...(connection ? { connectionRef: connection.id } : {}),
+      },
+      ...(connection
+        ? {
+            credentialResolver: previewCredentialResolver(
+              input.deps,
+              input.workspaceId,
+              input.subjectId,
+              connection,
+            ),
+          }
+        : {}),
+    });
+  } catch (error) {
+    if (error instanceof HTTPException) throw error;
+    throw new HTTPException(422, {
+      message:
+        error instanceof Error
+          ? error.message
+          : "The Integration source could not be detected safely",
+    });
+  }
+}
+
+async function requireVisibleConnection(
+  deps: ApiRouteDeps,
+  workspaceId: string,
+  subjectId: string,
+  connectionId: string,
+): Promise<ConnectionMetadataWithVerification> {
+  const connection = await getConnectionMetadata(deps.db, workspaceId, connectionId, subjectId);
+  if (!connection) throw new HTTPException(404, { message: "connection not found" });
+  if (connection.status !== "active") {
+    throw new HTTPException(422, { message: "connection is not active" });
+  }
+  return connection;
+}
+
+function connectionDescriptor(
+  connection: ConnectionMetadataWithVerification | null,
+): ApiIntegrationConnectionDescriptor | null {
+  return connection
+    ? {
+        id: connection.id,
+        kind: connection.kind,
+        providerDomain: connection.providerDomain,
+        scopes: [...connection.grantedScopes],
+        ownership: connection.subjectId ? "personal" : "workspace",
+      }
+    : null;
+}
+
+function previewCredentialResolver(
+  deps: ApiRouteDeps,
+  workspaceId: string,
+  subjectId: string,
+  connection: ConnectionMetadataWithVerification,
+): IntegrationCredentialResolver {
+  const resolve = buildConnectionTokenResolver(deps.db, deps.settings);
+  return {
+    resolve: async (request) => {
+      const result = await resolve({
+        workspaceId,
+        ...(connection.subjectId ? { subjectId } : {}),
+        serverId: `preview_${connection.id}`,
+        toolName: request.operationKey,
+        connectionRef: {
+          connectionId: connection.id,
+          providerDomain: connection.providerDomain,
+          kind: connection.kind,
+          ...(connection.grantedScopes.length > 0 ? { scopes: [...connection.grantedScopes] } : {}),
+          subjectScope: connection.subjectId ? "subject" : "workspace",
+        },
+        destinationUrl: request.destinationUrl,
+        credentialTarget: "http_api",
+        forceRefresh: request.forceRefresh === true,
+      });
+      if (result.status === "auth_needed") return null;
+      const destination = new URL(request.destinationUrl);
+      return {
+        audience: { origin: destination.origin, pathPrefix: "/" },
+        placements:
+          result.placements ??
+          Object.entries(result.headers).map(([name, value]) => ({
+            carrier: "header" as const,
+            name,
+            value,
+          })),
+        ...(result.expiresAt ? { expiresAt: result.expiresAt.toISOString() } : {}),
+      };
+    },
+  };
+}