Skip to content

The open-source app everyone uses to manage agents at work

18.3 KB
Raw Blame
import type { VerifiedProviderIdentity } from "../runtime-types.js";

import type { EndpointRow, DbTransaction, LifecycleRuntimeFence, InternalSetupState } from "../runtime-types.js";

import { createChatResourceReconciliation } from "../resource-reconciliation.js";

import { notifyChatDeliveryWork } from "../../chat-work-notifications.js";

import { type CredentialMutationLeaseGuard } from "../../chat-credential-mutation-lease.js";

import {
  and,
  eq,
  inArray,
} from "drizzle-orm";

import type { Db } from "@paperclipai/db";

import {
  chatConversations,
  chatDeliveries,
  chatEndpointResources,
  chatEndpoints,
  toolConnections,
} from "@paperclipai/db";
import type {
  ChatEndpointSetupState,
  ChatProvider,
  ToolCredentialSecretRef,
} from "@paperclipai/shared";

import {
  conflict,
  notFound,
} from "../../../errors.js";

import { redactSensitiveText } from "../../../redaction.js";

import {
  type ChatProviderLifecycleEffect,
} from "../../chat-provider-lifecycle.js";

import type { EndpointRecord, PreparedProviderInventory } from "../runtime-types.js";

type GitHubInstallationLifecycleOptions = {
  endpointRecord: (endpointId: string) => Promise<EndpointRecord | null>;
  resolveCredentials: (endpoint: EndpointRow) => Promise<Record<string, string>>;
  runtimeCallbackEndpoint: (tx: DbTransaction, endpointId: string, context: LifecycleRuntimeFence, statuses: EndpointRow["status"][]) => Promise<EndpointRow | null>;
  runtimeGeneration: (setup: ChatEndpointSetupState) => number;
  credentialFingerprint: (refs: ToolCredentialSecretRef[]) => string;
  verifyCredentials: (provider: ChatProvider, credentials: Record<string, string>) => Promise<VerifiedProviderIdentity>;
  legacyGitHubLabelsMatchVerifiedCredentials: (current: VerifiedProviderIdentity, verified: VerifiedProviderIdentity) => boolean;
  nativeBotIdentityMatches: (provider: ChatProvider, current: VerifiedProviderIdentity, incoming: VerifiedProviderIdentity) => boolean;
  assertNativeBotIdentityAvailable: (endpoint: EndpointRow, identity: VerifiedProviderIdentity) => Promise<void>;
  prepareProviderInventory: (endpoint: EndpointRow, credentials: Record<string, string>) => Promise<PreparedProviderInventory>;
  persistCredentials: (endpoint: EndpointRow, credentials: Record<string, string>, lease: CredentialMutationLeaseGuard, actorUserId?: string | null) => Promise<ToolCredentialSecretRef[]>;
  reconcileProviderResourceRows: ReturnType<typeof createChatResourceReconciliation>["reconcileProviderResourceRows"];
  redactError: (error: unknown) => string;
  normalizedLifecycleWithRuntimeFence: (delivery: typeof chatDeliveries.$inferSelect, fence: LifecycleRuntimeFence) => Record<string, unknown>;
  MAX_ERROR_TEXT: number;
};

type GitHubInstallationLifecycleInput = {
  currentEndpoint: EndpointRow;
  effect: ChatProviderLifecycleEffect;
  credentialLease: CredentialMutationLeaseGuard;
  admittedRuntimeContext: LifecycleRuntimeFence;
  claimed: { id: string };
  candidate: typeof chatDeliveries.$inferSelect;
  onFailurePersisted: () => void;
};

type GitHubInstallationLifecycleOutcome = {
  refreshRuntimeAfterLifecycle: boolean;
  stopRuntimeAfterLifecycle: boolean;
};

export function createGitHubInstallationLifecycle(db: Db, options: GitHubInstallationLifecycleOptions) {
  const { endpointRecord, resolveCredentials, runtimeCallbackEndpoint, runtimeGeneration, credentialFingerprint, verifyCredentials, legacyGitHubLabelsMatchVerifiedCredentials, nativeBotIdentityMatches, assertNativeBotIdentityAvailable, prepareProviderInventory, persistCredentials, reconcileProviderResourceRows, redactError, normalizedLifecycleWithRuntimeFence, MAX_ERROR_TEXT } = options;

  async function applyGitHubInstallationLifecycle(input: GitHubInstallationLifecycleInput): Promise<GitHubInstallationLifecycleOutcome> {
    const { currentEndpoint, effect, credentialLease, admittedRuntimeContext, claimed, candidate } = input;
    let refreshRuntimeAfterLifecycle = false;
    let stopRuntimeAfterLifecycle = false;
    try {
      const currentCredentials =
        await resolveCredentials(currentEndpoint);
      const lifecycleInstallationId =
        effect.kind === "endpoint" &&
        typeof effect.metadata?.installationId === "string"
          ? effect.metadata.installationId
          : null;
      const removesCurrentInstallation =
        effect.kind === "endpoint" &&
        effect.availability === "revoked" &&
        lifecycleInstallationId !== null &&
        lifecycleInstallationId === currentCredentials.installationId;
      const currentInstallationRemovalReason =
        removesCurrentInstallation && effect.kind === "endpoint"
          ? effect.reason
          : null;
      if (removesCurrentInstallation) {
        // A signed deletion for the installation currently bound to
        // this endpoint is authoritative provider truth. Inventory now
        // correctly contains zero active installations, so treating its
        // empty result as a transient discovery failure would strand the
        // endpoint in attention and ask GitHub to redeliver forever.
        // Keep the App key and webhook secret so a later installation
        // event can recover this same immutable bot identity.
        const revoked = await db.transaction(async (tx) => {
          await credentialLease.assertOwned(tx);
          const current = await runtimeCallbackEndpoint(
            tx,
            currentEndpoint.id,
            admittedRuntimeContext,
            ["verifying", "active", "attention", "revoked"],
          );
          const revokedAt = new Date();
          if (!current) {
            await notifyChatDeliveryWork(tx);
            const [filtered] = await tx
              .update(chatDeliveries)
              .set({
                state: "filtered",
                processedAt: revokedAt,
                nextAttemptAt: null,
                redactedError:
                  "GitHub installation deletion belonged to a superseded runtime",
                updatedAt: revokedAt,
              })
              .where(
                and(
                  eq(chatDeliveries.id, claimed.id),
                  eq(chatDeliveries.state, "processing"),
                  eq(chatDeliveries.attempts, candidate.attempts + 1),
                ),
              )
              .returning({ id: chatDeliveries.id });
            if (!filtered) {
              throw new Error(
                "GitHub installation deletion ownership changed before stale settlement",
              );
            }
            await credentialLease.assertOwned(tx);
            return false;
          }
          const reason = redactSensitiveText(
            currentInstallationRemovalReason ??
              "GitHub App installation was removed",
          ).slice(0, MAX_ERROR_TEXT);
          await tx
            .update(chatEndpoints)
            .set({
              status: "revoked",
              healthMessage: reason,
              lastError: reason,
              lastEventAt: revokedAt,
              setup: {
                ...current.setup,
                runtimeGeneration: runtimeGeneration(current.setup) + 1,
              } as InternalSetupState,
              updatedAt: revokedAt,
            })
            .where(eq(chatEndpoints.id, current.id));
          await tx
            .update(toolConnections)
            .set({
              status: "disabled",
              enabled: false,
              healthStatus: "failed",
              healthMessage: reason,
              lastError: reason,
              healthCheckedAt: revokedAt,
              updatedAt: revokedAt,
            })
            .where(eq(toolConnections.id, current.connectionId));
          await tx
            .update(chatEndpointResources)
            .set({ availability: "unavailable", updatedAt: revokedAt })
            .where(
              and(
                eq(chatEndpointResources.companyId, current.companyId),
                eq(chatEndpointResources.endpointId, current.id),
              ),
            );
          await tx
            .update(chatConversations)
            .set({ state: "unavailable", updatedAt: revokedAt })
            .where(
              and(
                eq(chatConversations.companyId, current.companyId),
                eq(chatConversations.endpointId, current.id),
                inArray(chatConversations.state, ["active", "waiting"]),
              ),
            );
          await notifyChatDeliveryWork(tx);
          const [processed] = await tx
            .update(chatDeliveries)
            .set({
              state: "processed",
              processedAt: revokedAt,
              redactedError: null,
              nextAttemptAt: null,
              updatedAt: revokedAt,
            })
            .where(
              and(
                eq(chatDeliveries.id, claimed.id),
                eq(chatDeliveries.state, "processing"),
                eq(chatDeliveries.attempts, candidate.attempts + 1),
              ),
            )
            .returning({ id: chatDeliveries.id });
          if (!processed) {
            throw new Error(
              "GitHub installation deletion ownership changed before revocation settlement",
            );
          }
          await credentialLease.assertOwned(tx);
          return true;
        });
        stopRuntimeAfterLifecycle = revoked;
        return { refreshRuntimeAfterLifecycle, stopRuntimeAfterLifecycle };
      }
      const identity = await verifyCredentials(
        "github",
        currentCredentials,
      );
      const upgradingLegacyIdentity =
        !currentEndpoint.botExternalId &&
        legacyGitHubLabelsMatchVerifiedCredentials(
          currentEndpoint,
          identity,
        );
      if (
        !upgradingLegacyIdentity &&
        !nativeBotIdentityMatches("github", currentEndpoint, identity)
      ) {
        throw conflict(
          "The GitHub App identity changed while reconciling this connection",
          {
            code: "chat_bot_identity_changed",
          },
        );
      }
      await assertNativeBotIdentityAvailable(currentEndpoint, identity);
      if (upgradingLegacyIdentity) {
        await db.transaction(async (tx) => {
          await credentialLease.assertOwned(tx);
          await tx
            .update(chatEndpoints)
            .set({
              botExternalId: identity.botExternalId,
              updatedAt: new Date(),
            })
            .where(eq(chatEndpoints.id, currentEndpoint.id));
          await credentialLease.assertOwned(tx);
        });
      }

      // GitHub lifecycle payloads are wake-up signals, not provider
      // truth. Re-read the one active App installation and its complete
      // repository inventory while the credential lease excludes secret
      // rotation and every other lifecycle callback for this endpoint.
      const prepared = await prepareProviderInventory(
        currentEndpoint,
        currentCredentials,
      );
      if (
        prepared.credentials.installationId !==
        currentCredentials.installationId
      ) {
        await persistCredentials(
          currentEndpoint,
          prepared.credentials,
          credentialLease,
        );
        refreshRuntimeAfterLifecycle = true;
      }
      if (prepared.inventory)
        await reconcileProviderResourceRows(
          currentEndpoint,
          prepared.inventory,
          credentialLease,
        );

      const canonical = await endpointRecord(currentEndpoint.id);
      if (!canonical) throw notFound("Chat endpoint not found");
      const now = new Date();
      const intentionallyUnavailable =
        canonical.endpoint.status === "paused" ||
        canonical.endpoint.status === "archived" ||
        (canonical.endpoint.status === "attention" && canonical.endpoint.setup.step === "provider_setup") ||
        !canonical.endpoint.setup.webhookVerifiedAt;
      const advanceRuntimeGeneration =
        refreshRuntimeAfterLifecycle ||
        (canonical.endpoint.status === "attention" && canonical.endpoint.setup.step === "provider_setup") ||
        !canonical.endpoint.setup.webhookVerifiedAt;
      await db.transaction(async (tx) => {
        await credentialLease.assertOwned(tx);
        if (intentionallyUnavailable) {
          await tx
            .update(chatEndpoints)
            .set({
              ...(advanceRuntimeGeneration
                ? {
                    setup: {
                      ...canonical.endpoint.setup,
                      runtimeGeneration:
                        runtimeGeneration(canonical.endpoint.setup) + 1,
                    } as InternalSetupState,
                  }
                : {}),
              lastEventAt: now,
              updatedAt: now,
            })
            .where(eq(chatEndpoints.id, canonical.endpoint.id));
        } else {
          const status =
            canonical.endpoint.setup.step === "complete"
              ? "active"
              : "verifying";
          await tx
            .update(chatEndpoints)
            .set({
              status,
              healthMessage:
                status === "active"
                  ? "Connected"
                  : "Waiting for a test conversation",
              lastError: null,
              lastEventAt: now,
              ...(advanceRuntimeGeneration
                ? {
                    setup: {
                      ...canonical.endpoint.setup,
                      runtimeGeneration:
                        runtimeGeneration(canonical.endpoint.setup) + 1,
                    } as InternalSetupState,
                  }
                : {}),
              updatedAt: now,
            })
            .where(eq(chatEndpoints.id, canonical.endpoint.id));
          await tx
            .update(toolConnections)
            .set({
              status: "active",
              enabled: true,
              healthStatus: "healthy",
              healthMessage: "Connected",
              lastError: null,
              healthCheckedAt: now,
              updatedAt: now,
            })
            .where(
              eq(toolConnections.id, canonical.endpoint.connectionId),
            );
        }
        await notifyChatDeliveryWork(tx);
        await tx
          .update(chatDeliveries)
          .set({
            state: "processed",
            processedAt: now,
            redactedError: null,
            nextAttemptAt: null,
            updatedAt: now,
          })
          .where(
            and(
              eq(chatDeliveries.id, claimed.id),
              eq(chatDeliveries.state, "processing"),
              eq(chatDeliveries.attempts, candidate.attempts + 1),
            ),
          );
        await credentialLease.assertOwned(tx);
      });
      if (intentionallyUnavailable) {
        stopRuntimeAfterLifecycle = true;
      }
    } catch (error) {
      const latest = await endpointRecord(currentEndpoint.id);
      const preserveIntentionalState =
        !latest ||
        latest.endpoint.status === "paused" ||
        latest.endpoint.status === "archived" ||
        (latest.endpoint.status === "attention" && latest.endpoint.setup.step === "provider_setup") ||
        !latest.endpoint.setup.webhookVerifiedAt;
      if (!preserveIntentionalState) {
        const failedAt = new Date();
        const failure = redactError(error);
        const nextGeneration =
          runtimeGeneration(latest.endpoint.setup) + 1;
        const retryRuntimeContext: LifecycleRuntimeFence = {
          credentialFingerprint: credentialFingerprint(
            latest.credentialSecretRefs,
          ),
          generation: nextGeneration,
        };
        const terminal = candidate.attempts + 1 >= 5;
        await db.transaction(async (tx) => {
          await credentialLease.assertOwned(tx);
          await tx
            .update(chatEndpoints)
            .set({
              status: "attention",
              healthMessage:
                "GitHub App credentials, permissions, events, or identity need attention",
              lastError: failure,
              lastEventAt: failedAt,
              setup: {
                ...latest.endpoint.setup,
                runtimeGeneration: nextGeneration,
              } as InternalSetupState,
              updatedAt: failedAt,
            })
            .where(eq(chatEndpoints.id, currentEndpoint.id));
          await tx
            .update(toolConnections)
            .set({
              status: "disabled",
              enabled: false,
              healthStatus: "degraded",
              healthMessage:
                "GitHub App credentials, permissions, events, or identity need attention",
              lastError: failure,
              healthCheckedAt: failedAt,
              updatedAt: failedAt,
            })
            .where(eq(toolConnections.id, currentEndpoint.connectionId));
          await tx
            .update(chatEndpointResources)
            .set({ availability: "unavailable", updatedAt: failedAt })
            .where(
              and(
                eq(
                  chatEndpointResources.companyId,
                  currentEndpoint.companyId,
                ),
                eq(chatEndpointResources.endpointId, currentEndpoint.id),
              ),
            );
          await tx
            .update(chatConversations)
            .set({ state: "unavailable", updatedAt: failedAt })
            .where(
              and(
                eq(
                  chatConversations.companyId,
                  currentEndpoint.companyId,
                ),
                eq(chatConversations.endpointId, currentEndpoint.id),
                inArray(chatConversations.state, ["active", "waiting"]),
              ),
            );
          await notifyChatDeliveryWork(tx);
          await tx
            .update(chatDeliveries)
            .set({
              state: terminal ? "failed" : "retry",
              normalizedEvent: normalizedLifecycleWithRuntimeFence(
                candidate,
                retryRuntimeContext,
              ),
              redactedError: failure,
              nextAttemptAt: terminal ? null : failedAt,
              updatedAt: failedAt,
            })
            .where(
              and(
                eq(chatDeliveries.id, claimed.id),
                eq(chatDeliveries.state, "processing"),
                eq(chatDeliveries.attempts, candidate.attempts + 1),
              ),
            );
          await credentialLease.assertOwned(tx);
        });
        input.onFailurePersisted();
      }
      throw error;
    }
    return { refreshRuntimeAfterLifecycle, stopRuntimeAfterLifecycle };
  }
  return { applyGitHubInstallationLifecycle };
}