@opengeni/api-router 3.0.0-canary.0 → 3.0.1-canary.0

package/src/integrations/provider-oauth.ts

@@ -1,3 +1,5 @@
+import { withOrganizationIntegrationAcquisition } from "@opengeni/db/organization-integration-policy";
+import { claimOAuthAcquisition, finishOAuthAcquisition } from "./oauth-client";
 import { Buffer } from "node:buffer";
 import { createHash, randomBytes } from "node:crypto";
 
@@ -18,7 +20,11 @@ import {
   type ApiIntegrationOAuthStartRequest,
   type ConnectionOwnership,
 } from "@opengeni/contracts";
-import { requireEnvironmentEncryption, type ApiRouteDeps } from "@opengeni/core";
+import {
+  integrationKeyForConnectProvider,
+  requireEnvironmentEncryption,
+  type ApiRouteDeps,
+} from "@opengeni/core";
 import { ExternalActorContinuation } from "@opengeni/contracts/external-identities";
 import {
   consumeIntegrationOAuthStateNonce,
@@ -28,7 +34,6 @@ import {
   loadConnectionCredentialForBroker,
   persistProviderOAuthConnection,
   getConnectAttempt,
-  claimConnectOperation,
   finishConnectOperation,
 } from "@opengeni/db";
 import { createSignedState, readSignedState } from "@opengeni/github";
@@ -149,6 +154,7 @@ export async function startApiIntegrationProviderOAuth(
   },
 ): Promise<OAuthStartResponse> {
   const definition = requiredDefinition(input.payload.definitionId);
+  await withOrganizationIntegrationAcquisition(deps.db, input, [definition.id], async () => {});
   const providerDomain = integrationDefinitionProviderDomain(definition);
   const existing = input.payload.connectionId
     ? await getConnectionMetadata(
@@ -307,12 +313,18 @@ export async function completeApiIntegrationProviderOAuth(
         operationId: `oauth:${state.nonce}`,
         inputDigest: createHash("sha256").update(input.state!).digest("hex"),
       };
-      const claim = await claimConnectOperation(deps.db, state, {
-        ...connectOperation,
-        expectedRevision: stored.attempt.revision,
-        authorize: (tx, _attempt, origin) =>
-          requireConnectOwnerAuthority(tx, state!, "connections:write", origin),
-      });
+      const claim = await claimOAuthAcquisition(
+        deps.db,
+        state,
+        {
+          ...connectOperation,
+          expectedRevision: stored.attempt.revision,
+          authorize: (tx, _attempt, origin) =>
+            requireConnectOwnerAuthority(tx, state!, "connections:write", origin),
+        },
+        integrationKeyForConnectProvider(state.definitionId),
+        Boolean(input.code && !input.error),
+      );
       if (claim.status === "replayed") return { redirectTo: exactReturnUrl, exactReturn: true };
     }
     requireProviderOAuthOwner(state);
@@ -350,6 +362,7 @@ export async function completeApiIntegrationProviderOAuth(
 
     const definition = integrationDefinitionById(state.definitionId);
     if (!definition) throw new ProviderOAuthCallbackError("state_invalid");
+    await withOrganizationIntegrationAcquisition(deps.db, state, [definition.id], async () => {});
     if (
       state.definitionFingerprint !== providerDefinitionFingerprint(definition) ||
       state.providerDomain !== integrationDefinitionProviderDomain(definition) ||
@@ -480,32 +493,42 @@ export async function completeApiIntegrationProviderOAuth(
     const persist = (database: import("@opengeni/db").Database) =>
       persistProviderOAuthConnection(database, persistenceInput);
     if (connectOperation) {
-      await finishConnectOperation(deps.db, state, {
-        ...connectOperation,
-        authorize: (tx, _attempt, origin) =>
-          requireConnectOwnerAuthority(tx, state!, "connections:write", origin),
-        commit: async (tx, current) => {
-          const connection = await persist(tx);
-          if (!connection) throw new ProviderOAuthCallbackError("connection_conflict");
-          return {
-            ...current,
-            revision: current.revision + 1,
-            state: "connected_but_incomplete",
-            credentialsCommitted: true,
-            nextAction: { type: "none" },
-            account: {
-              id: connection.id,
-              providerId: current.providerId,
-              label: identity.displayName ?? identity.email ?? identity.principalId,
-              ownership: current.ownership,
-              status: "connected",
-            },
-          };
+      await finishOAuthAcquisition(
+        deps.db,
+        state,
+        {
+          ...connectOperation,
+          authorize: (tx, _attempt, origin) =>
+            requireConnectOwnerAuthority(tx, state!, "connections:write", origin),
+          commit: async (tx, current) => {
+            const connection = await persist(tx);
+            if (!connection) throw new ProviderOAuthCallbackError("connection_conflict");
+            return {
+              ...current,
+              revision: current.revision + 1,
+              state: "connected_but_incomplete",
+              credentialsCommitted: true,
+              nextAction: { type: "none" },
+              account: {
+                id: connection.id,
+                providerId: current.providerId,
+                label: identity.displayName ?? identity.email ?? identity.principalId,
+                ownership: current.ownership,
+                status: "connected",
+              },
+            };
+          },
         },
-      });
+        definition.id,
+      );
       return { redirectTo: exactReturnUrl!, exactReturn: true };
     }
-    const connection = await persist(deps.db);
+    const connection = await withOrganizationIntegrationAcquisition(
+      deps.db,
+      state,
+      [definition.id],
+      persist,
+    );
     if (!connection) throw new ProviderOAuthCallbackError("connection_conflict");
     return {
       redirectTo: providerOAuthReturnUrl(returnBaseUrl, state.returnPath, "success", {

package/src/integrations/social-oauth.ts

@@ -1,3 +1,5 @@
+import { withOrganizationIntegrationAcquisition } from "@opengeni/db/organization-integration-policy";
+import { claimOAuthAcquisition, finishOAuthAcquisition } from "./oauth-client";
 import { parseSocialOauthClientsJson, type Settings } from "@opengeni/config";
 import {
   OAuthStartResponse,
@@ -15,7 +17,6 @@ import {
   loadSocialConnectionCredential,
   updateSocialConnectionCredential,
   upsertSocialOAuthConnection,
-  claimConnectOperation,
   finishConnectOperation,
   getConnectAttempt,
   type Database,
@@ -196,6 +197,7 @@ export async function startSocialOAuth(
 ): Promise<OAuthStartResponse> {
   const { settings } = deps;
   const provider = SOCIAL_OAUTH_PROVIDERS[context.payload.provider];
+  await withOrganizationIntegrationAcquisition(deps.db, context, [provider.id], async () => {});
   const client = socialOAuthClientFor(settings, provider.id);
   const redirectUri = socialOAuthRedirectUri(settings, context.requestUrl);
   const returnPath = safeReturnPath(context.payload.returnPath ?? "/integrations");
@@ -323,6 +325,7 @@ export async function completeSocialOAuthCallback(
   }
   try {
     const provider = SOCIAL_OAUTH_PROVIDERS[state.provider];
+    await withOrganizationIntegrationAcquisition(db, state, [provider.id], async () => {});
     const client = socialOAuthClientFor(settings, provider.id);
     const key = requireEnvironmentEncryption(settings);
     const verifier = state.encryptedPkceVerifier
@@ -344,18 +347,31 @@ export async function completeSocialOAuthCallback(
       ...(token.scope ? { scope: token.scope } : {}),
     };
     const grantedScopes = token.scope ? token.scope.split(/[\s,]+/).filter(Boolean) : state.scopes;
-    const connection = await upsertSocialOAuthConnection(db, {
-      accountId: state.accountId,
-      workspaceId: state.workspaceId,
-      subjectId: state.ownership === "personal" ? state.subjectId : null,
-      provider: provider.id,
-      accountHandle: identity.handle,
-      accountName: identity.name ?? null,
-      externalAccountId: identity.externalAccountId,
-      scopes: grantedScopes,
-      credentialEncrypted: encryptEnvironmentValue(key, JSON.stringify(bundle)),
-      tokenMetadata: publicTokenMetadata(bundle),
-    });
+    const acceptedState = state;
+    const connection = await withOrganizationIntegrationAcquisition(
+      db,
+      acceptedState,
+      [provider.id],
+      async (tx) => {
+        await requireConnectOwnerAuthority(
+          tx,
+          acceptedState,
+          acceptedState.ownership === "workspace" ? "workspace:admin" : "workspace:read",
+        );
+        return upsertSocialOAuthConnection(tx, {
+          accountId: acceptedState.accountId,
+          workspaceId: acceptedState.workspaceId,
+          subjectId: acceptedState.ownership === "personal" ? acceptedState.subjectId : null,
+          provider: provider.id,
+          accountHandle: identity.handle,
+          accountName: identity.name ?? null,
+          externalAccountId: identity.externalAccountId,
+          scopes: grantedScopes,
+          credentialEncrypted: encryptEnvironmentValue(key, JSON.stringify(bundle)),
+          tokenMetadata: publicTokenMetadata(bundle),
+        });
+      },
+    );
     return {
       redirectTo: callbackReturnPath(state.returnPath, "success", {
         connectionId: connection.id,
@@ -407,10 +423,16 @@ async function completeSocialConnect(
     authorize,
   };
   try {
-    const claim = await claimConnectOperation(deps.db, state, {
-      ...operation,
-      expectedRevision: stored.attempt.revision,
-    });
+    const claim = await claimOAuthAcquisition(
+      deps.db,
+      state,
+      {
+        ...operation,
+        expectedRevision: stored.attempt.revision,
+      },
+      state.provider,
+      Boolean(input.code && !input.error),
+    );
     if (claim.status === "replayed") return { redirectTo: stored.returnUrl, exactReturn: true };
     if (!personalOwnerStateAccepted(state))
       throw new HTTPException(403, { message: PERSONAL_CONNECTION_PRINCIPAL_MESSAGE });
@@ -455,46 +477,51 @@ async function completeSocialConnect(
         ...(token.expiresAt ? { expiresAt: token.expiresAt } : {}),
         ...(token.scope ? { scope: token.scope } : {}),
       };
-      await finishConnectOperation(deps.db, state, {
-        ...operation,
-        commit: async (tx, current) => {
-          const connection = await upsertSocialOAuthConnection(tx, {
-            accountId: state.accountId,
-            workspaceId: state.workspaceId,
-            ...(current.account
-              ? {
-                  expectedConnection: {
-                    id: current.account.id.slice("social:".length),
-                    version: current.account.version!,
-                  },
-                }
-              : {}),
-            subjectId: state.ownership === "personal" ? state.subjectId : null,
-            provider: provider.id,
-            accountHandle: identity.handle,
-            accountName: identity.name ?? null,
-            externalAccountId: identity.externalAccountId,
-            scopes: token.scope ? token.scope.split(/[\s,]+/).filter(Boolean) : state.scopes,
-            credentialEncrypted: encryptEnvironmentValue(key, JSON.stringify(bundle)),
-            tokenMetadata: publicTokenMetadata(bundle),
-          });
-          return {
-            ...current,
-            revision: current.revision + 1,
-            state: "complete",
-            credentialsCommitted: true,
-            nextAction: { type: "none" },
-            account: {
-              id: `social:${connection.id}`,
-              providerId: provider.id,
-              version: connection.version!,
-              label: identity.handle,
-              ownership: state.ownership,
-              status: "connected",
-            },
-          };
+      await finishOAuthAcquisition(
+        deps.db,
+        state,
+        {
+          ...operation,
+          commit: async (tx, current) => {
+            const connection = await upsertSocialOAuthConnection(tx, {
+              accountId: state.accountId,
+              workspaceId: state.workspaceId,
+              ...(current.account
+                ? {
+                    expectedConnection: {
+                      id: current.account.id.slice("social:".length),
+                      version: current.account.version!,
+                    },
+                  }
+                : {}),
+              subjectId: state.ownership === "personal" ? state.subjectId : null,
+              provider: provider.id,
+              accountHandle: identity.handle,
+              accountName: identity.name ?? null,
+              externalAccountId: identity.externalAccountId,
+              scopes: token.scope ? token.scope.split(/[\s,]+/).filter(Boolean) : state.scopes,
+              credentialEncrypted: encryptEnvironmentValue(key, JSON.stringify(bundle)),
+              tokenMetadata: publicTokenMetadata(bundle),
+            });
+            return {
+              ...current,
+              revision: current.revision + 1,
+              state: "complete",
+              credentialsCommitted: true,
+              nextAction: { type: "none" },
+              account: {
+                id: `social:${connection.id}`,
+                providerId: provider.id,
+                version: connection.version!,
+                label: identity.handle,
+                ownership: state.ownership,
+                status: "connected",
+              },
+            };
+          },
         },
-      });
+        state.provider,
+      );
     }
   } catch (error) {
     // An uncertain exchange stays occupied: do not replay a consumed OAuth code.

package/src/mcp/first-party-tool-permissions.ts

@@ -21,6 +21,7 @@ export const FIRST_PARTY_TOOL_AUTHORIZATION = {
   goal_pause: { sessionRequired: true, allOf: ["goals:manage"] },
   goal_resume: { sessionRequired: true, allOf: ["goals:manage"] },
   knowledge_search: { sessionRequired: true, allOf: ["documents:search"] },
+  knowledge_prepare_save: { sessionRequired: true, allOf: ["documents:search"] },
   knowledge_get: { sessionRequired: true, allOf: ["documents:search"] },
   knowledge_browse: { sessionRequired: true, allOf: ["documents:search"] },
   knowledge_retain_file: { sessionRequired: true, allOf: ["documents:search", "files:read"] },

package/src/mcp/knowledge-entries.ts

@@ -2,12 +2,14 @@ import {
   AgentInstructionSaveRequest,
   WorkspaceInstructionPolicyTarget,
   KnowledgeEntryListRequest,
+  KnowledgeSavePreparationRequest,
   KnowledgeEntrySaveRequest,
   KnowledgeTaskNotePromotionRequest,
   type AccessGrant,
 } from "@opengeni/contracts";
 import {
   prepareKnowledgeFile,
+  prepareKnowledgeSave,
   retainKnowledgeMessage,
   searchKnowledgeEntries,
   requireLiveAgentAttemptAuthorization,
@@ -131,11 +133,23 @@ export function registerKnowledgeEntryTools(
         throw new Error("Pass exactly one existing confirmation target");
       }),
   );
+  server.registerTool(
+    "knowledge_prepare_save",
+    {
+      description:
+        "Before saving useful lasting Knowledge, find related published entries and unapproved proposals, and fetch the full authorized collection map with descriptions and parent IDs in one read-only call. Supply a concise subject and the proposed fact, decision, requirement or incident. Search spans all authorized collections. Reuse an existing entry when unchanged; read its current content before a correction, preserve evidence, or create only when distinct. Pending matches are unapproved. Choose collections from this map in your writable scope. A collection may have both published and pending versions. If collections.complete is false, continue with collectionCursors=collections.nextCursors; never mistake a partial catalog for the whole map. Long descriptions explicitly report truncation and can be read with knowledge_get. This call saves and approves nothing.",
+      inputSchema: KnowledgeSavePreparationRequest.shape,
+    },
+    (input) =>
+      run((context) =>
+        prepareKnowledgeSave(deps.db, context, input, () => deps.getDocumentServices().embedder),
+      ),
+  );
   server.registerTool(
     "knowledge_search",
     {
       description:
-        "Find Knowledge from retained sources and findings. Use a concise subject or entity name first (for example Acme); omit scope to search all authorized scopes. If a query returns no entries, retry the key name alone in the same scope or browse groups before concluding the information is absent. Default view=published is accepted knowledge. Also search view=needs_review before creating or updating entries, to reuse pending findings and collections from earlier tasks. Pending revisions are unapproved proposals, not accepted facts or instructions; preserve that status when discussing them. Reading a proposal never approves it. Personal tasks search the verified user's personal and authorized shared Knowledge; shared tasks search shared Knowledge.",
+        "Find Knowledge from useful findings and explicitly retained reference sources. Supporting chat/file evidence is excluded from ordinary published discovery; set includeEvidence=true only when searching that evidence deliberately. Use a concise subject or entity name first (for example Acme); omit scope to search all authorized scopes. If a query returns no entries, retry the key name alone in the same scope or browse groups before concluding the information is absent. Default view=published is accepted knowledge. Also search view=needs_review before creating or updating entries, to reuse pending findings and collections from earlier tasks. Pending revisions are unapproved proposals, not accepted facts or instructions; preserve that status when discussing them. Reading a proposal never approves it. Personal tasks search the verified user's personal and authorized shared Knowledge; shared tasks search shared Knowledge.",
       inputSchema: KnowledgeEntryListRequest.omit({
         view: true,
         sessionId: true,
@@ -210,16 +224,19 @@ export function registerKnowledgeEntryTools(
     "knowledge_retain_file",
     {
       description:
-        "Retain searchable source text from an existing uploaded file. Chat attachments are prepared automatically; use this for a newly fetched file or to retry a failed preparation. The original stays in Files. Repeated calls reuse the same source and do not duplicate review requests or revive rejected/archived sources. Selected findings are optional separate knowledge_save entries with evidence pointing to the returned revision. A pending receipt never pauses the task.",
-      inputSchema: { fileId: z.uuid() },
+        "Retain source text from an existing uploaded file only when it supports useful lasting Knowledge, or the user wants the file kept as a reusable reference. Ordinary chat attachments are not automatically added to Knowledge. Use purpose=evidence (default) for supporting material, or purpose=reference for a deliberately retained searchable reference. The original stays in Files. Read the image itself before drawing visual conclusions; OCR text is only evidence. Repeated calls reuse the same source and do not change its purpose, duplicate review requests or revive rejected/archived sources. To make previously retained evidence a searchable reference, read its current revision with knowledge_get and use knowledge_save to set source.purpose=reference while preserving content and links. Selected findings are optional separate knowledge_save entries with evidence pointing to the returned revision. A pending receipt never pauses the task.",
+      inputSchema: {
+        fileId: z.uuid(),
+        purpose: z.enum(["evidence", "reference"]).default("evidence"),
+      },
     },
-    ({ fileId }) => run((context) => prepareKnowledgeFile(deps, context, fileId)),
+    ({ fileId, purpose }) => run((context) => prepareKnowledgeFile(deps, context, fileId, purpose)),
   );
   server.registerTool(
     "knowledge_retain_message",
     {
       description:
-        "Retain the exact text of a user message from this conversation as a source entry. Use when a user supplies or confirms a durable fact, before saving a finding based on it. Omit messageId for the user message that triggered this turn, or pass an earlier user message event ID from this same conversation. The server copies the actual message, preserves its identity and follows this task's learning policy. Repeated calls reuse the source. Cite the returned entryId/revisionId as evidence in knowledge_save, with location.messageIds=[messageId]. Retaining a message does not prove every statement in it or approve a pending finding.",
+        "Retain the exact text of a user message as supporting evidence only after identifying useful lasting Knowledge to save. Do not retain routine approvals, acknowledgments, task instructions or status chatter merely because they occurred. The source stays out of ordinary Knowledge discovery and can be read through its evidence link. Use when a user supplies or confirms a durable fact, before saving a finding based on it. Omit messageId for the user message that triggered this turn, or pass an earlier user message event ID from this same conversation. The server copies the actual message, preserves its identity and follows this task's learning policy. Repeated calls reuse the source. Cite the returned entryId/revisionId as evidence in knowledge_save, with location.messageIds=[messageId]. Retaining a message does not prove every statement in it or approve a pending finding.",
       inputSchema: { messageId: z.uuid().optional() },
     },
     ({ messageId }) => run((context) => retainKnowledgeMessage(deps.db, context, messageId)),
@@ -228,7 +245,7 @@ export function registerKnowledgeEntryTools(
     "knowledge_save",
     {
       description:
-        "Retain useful source text, facts, decisions, requirements, incidents or notes, or organize them with groups and relationships. Do this autonomously when useful for future work. Choose kind by content: source for retained original text; fact for a specific claim (the label is not verification); decision for a choice made and its reasoning; requirement for a need or constraint; incident for a problem with cause, fix and outcome when known; note for other useful context. Choose the closest kind without asking the user to classify it. A group is a collection about a customer, product, system or subject, not a finding type. Search published and needs_review views for an existing entry and relevant group before creating one, use groupIds to link entries across sources, and reuse an entry in multiple groups instead of copying it. Nest collections by setting a group entry's groupIds to its parent collections; keep the hierarchy shallow and useful, and never create circular membership. Use a new entryId and expectedVersion 0 to create; use an existing ID and its current version to correct or reorganize. Source text and selected facts are independent entries, not mandatory duplicate stages. Evidence pins another entry's exact revision. When a user supplies or confirms a fact, retain the actual message with knowledge_retain_message and cite the returned revision; do not leave its provenance only in prose. Preserve existing evidence and relationships on corrections unless they are specifically no longer applicable; a contradictory original remains useful evidence of what changed. Use the same operationId only for an exact retry. Agent learning decides publication: published is available immediately; pending is saved for review and your task continues without an approval prompt. Do not turn Knowledge into instructions or Skills.",
+        "Retain useful lasting facts, decisions, requirements, incidents or notes, or deliberately selected reference sources. First use knowledge_prepare_save when available (otherwise search published and needs_review Knowledge and browse collections). Skip unchanged duplicates; improve an existing entry when the subject is the same. Do not save routine approvals, acknowledgments, temporary instructions, screenshots or OCR merely because they occurred. State the reusable finding with enough context for a future task, preserve uncertainty and evidence, and place it in the relevant existing collections. Do this autonomously when useful for future work. Choose kind by content: source for retained original text; fact for a specific claim (the label is not verification); decision for a choice made and its reasoning; requirement for a need or constraint; incident for a problem with cause, fix and outcome when known; note for other useful context. Choose the closest kind without asking the user to classify it. A group is a collection about a customer, product, system or subject, not a finding type. Search published and needs_review views for an existing entry and relevant group before creating one, use groupIds to link entries across sources, and reuse an entry in multiple groups instead of copying it. Nest collections by setting a group entry's groupIds to its parent collections; keep the hierarchy shallow and useful, and never create circular membership. Use a new entryId and expectedVersion 0 to create; use an existing ID and its current version to correct or reorganize. Source text and selected facts are independent entries, not mandatory duplicate stages. Evidence pins another entry's exact revision. When a user supplies or confirms a fact, retain the actual message with knowledge_retain_message and cite the returned revision; do not leave its provenance only in prose. Preserve existing evidence and relationships on corrections unless they are specifically no longer applicable; a contradictory original remains useful evidence of what changed. Use the same operationId only for an exact retry. Agent learning decides publication: published is available immediately; pending is saved for review and your task continues without an approval prompt. Do not turn Knowledge into instructions or Skills.",
       inputSchema: KnowledgeEntrySaveRequest.omit({ scope: true }).shape,
     },
     (input) => run((context) => saveKnowledgeEntry(deps.db, context, input)),

package/src/routes/api-integrations.ts

@@ -7,6 +7,7 @@ import {
 } from "@opengeni/capabilities";
 import {
   ApiIntegrationPreview,
+  OrganizationIntegrationDeniedError,
   ListIntegrationDefinitionsResponse,
   ApiIntegrationUninstallPreview,
   InstallApiIntegrationRequest,
@@ -17,12 +18,18 @@ import {
   UninstallApiIntegrationResult,
   type AccessGrant,
 } from "@opengeni/contracts";
-import { requireAccessGrant, type ApiRouteDeps } from "@opengeni/core";
+import {
+  requireAccessGrant,
+  integrationSourceForOrganizationPolicy,
+  type ApiRouteDeps,
+} from "@opengeni/core";
+import { withOrganizationIntegrationPolicyFence } from "@opengeni/db/organization-integration-policy";
 import {
   ApiIntegrationInstallationVersionConflictError,
   buildConnectionTokenResolver,
   getApiIntegrationUninstallPreview,
   getConnectionMetadata,
+  getApiIntegrationReconciliationSnapshot,
   installApiIntegration,
   IntegrationFacetBindingOwnershipConflictError,
   IntegrationFacetBindingVersionConflictError,
@@ -209,6 +216,7 @@ export function registerApiIntegrationRoutes(
     const resolved = await resolveForRoute({
       deps,
       transport,
+      accountId: grant.accountId,
       workspaceId,
       subjectId: grant.subjectId,
       payload,
@@ -223,6 +231,7 @@ export function registerApiIntegrationRoutes(
     const resolved = await resolveForRoute({
       deps,
       transport,
+      accountId: grant.accountId,
       workspaceId,
       subjectId: grant.subjectId,
       payload,
@@ -308,21 +317,45 @@ export function registerApiIntegrationRoutes(
 export async function resolveForRoute(input: {
   deps: ApiRouteDeps;
   transport: ReturnType<typeof createPinnedIntegrationTransport>;
+  accountId: string;
   workspaceId: string;
   subjectId: string;
   payload: PreviewApiIntegrationRequest | InstallApiIntegrationRequest;
 }): ReturnType<typeof resolveApiIntegrationPreview> {
+  const payload = structuredClone(input.payload);
+  const preparation = await withOrganizationIntegrationPolicyFence(
+    input.deps.db,
+    input,
+    async (tx, policy) => {
+      try {
+        return { source: integrationSourceForOrganizationPolicy(policy, payload.source) };
+      } catch (error) {
+        if (!(error instanceof OrganizationIntegrationDeniedError)) throw error;
+        const install = InstallApiIntegrationRequest.safeParse(payload);
+        if (install.success) {
+          const resolved = await storedReconciliationPreview(
+            { ...input, deps: { ...input.deps, db: tx } },
+            install.data,
+          );
+          if (resolved) return { resolved };
+        }
+        throw error;
+      }
+    },
+  );
+  if (preparation.resolved) return preparation.resolved;
+  const source = preparation.source!;
   try {
-    const connection = input.payload.connectionId
+    const connection = payload.connectionId
       ? await requireVisibleConnection(
           input.deps,
           input.workspaceId,
           input.subjectId,
-          input.payload.connectionId,
+          payload.connectionId,
         )
       : null;
     return await resolveApiIntegrationPreview({
-      source: input.payload.source,
+      source,
       connection: connectionDescriptor(connection),
       transport: input.transport,
       authority: {
@@ -353,6 +386,85 @@ export async function resolveForRoute(input: {
   }
 }
 
+async function storedReconciliationPreview(
+  input: { deps: ApiRouteDeps; accountId: string; workspaceId: string; subjectId: string },
+  payload: InstallApiIntegrationRequest,
+): Promise<ResolvedApiIntegrationPreview | null> {
+  const snapshot = await getApiIntegrationReconciliationSnapshot(input.deps.db, {
+    accountId: input.accountId,
+    workspaceId: input.workspaceId,
+    subjectId: input.subjectId,
+    source: payload.source,
+    expectedRevisionId: payload.expectedRevisionId,
+    expectedContentSha256: payload.expectedContentSha256,
+    ...(payload.connectionId !== undefined ? { connectionId: payload.connectionId } : {}),
+    ...(payload.instanceKey !== undefined ? { instanceKey: payload.instanceKey } : {}),
+    ...(payload.allowedTools !== undefined ? { allowedTools: payload.allowedTools } : {}),
+  });
+  if (!snapshot) return null;
+  const { runtime, baseServerId, name, provider, requiredScopes } = snapshot;
+  const connection = payload.connectionId
+    ? await requireVisibleConnection(
+        input.deps,
+        input.workspaceId,
+        input.subjectId,
+        payload.connectionId,
+      )
+    : null;
+  const scheme = runtime.authScheme;
+  const auth = !apiIntegrationRequiresConnection(scheme)
+    ? { kind: "none" }
+    : scheme.kind === "oauth2"
+      ? { kind: "oauth2", providerDomain: runtime.providerDomain, scopes: requiredScopes }
+      : scheme.kind === "api_key"
+        ? {
+            kind: "api_key",
+            providerDomain: runtime.providerDomain,
+            carrier: scheme.carrier,
+            name: scheme.name,
+          }
+        : scheme.kind === "http"
+          ? { kind: "http", providerDomain: runtime.providerDomain, scheme: scheme.scheme }
+          : null;
+  if (!auth) return null;
+  return {
+    preview: ApiIntegrationPreview.parse({
+      source: payload.source,
+      definitionId: runtime.definitionId,
+      definitionProvenance: runtime.definitionProvenance,
+      protocol: runtime.protocol,
+      capabilityId: runtime.capabilityId,
+      pluginKey: runtime.pluginKey,
+      serverId: baseServerId,
+      name,
+      description: runtime.description,
+      provider,
+      providerDomain: runtime.providerDomain,
+      baseUrl: runtime.baseUrl,
+      sourceUrl: runtime.sourceUrl,
+      revisionId: runtime.revision.id,
+      contentSha256: runtime.revision.contentSha256,
+      auth,
+      connectionId: connection?.id ?? null,
+      connectionOwnership: connection ? (connection.subjectId ? "personal" : "workspace") : null,
+      tools: runtime.revision.tools.map((tool) => ({
+        id: tool.id,
+        operationKey: tool.operationKey,
+        name: tool.name,
+        description: tool.description,
+        safety: tool.safety,
+        approvalMode: tool.approvalMode,
+        deprecated: tool.deprecated,
+      })),
+      warnings: [],
+    }),
+    revision: runtime.revision,
+    provider,
+    requiredScopes,
+    authScheme: runtime.authScheme,
+  };
+}
+
 async function requireVisibleConnection(
   deps: ApiRouteDeps,
   workspaceId: string,