The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
import { preparePhotonConfiguration, createPhotonConfiguration } from "./imessage-photon/setup.js";
import { slackRuntimeConfig } from "./slack/setup.js";
import { createTelegramSetup } from "./telegram/setup.js";
import { createGitHubSetup } from "./github/setup.js";
import { createSpekoSetup } from "./speko/setup.js";
import { createGitHubAppSetup } from "./github/app-setup.js";
import type { VerifiedProviderIdentity } from "./runtime-types.js";
import { isProvisionedSlackSetup } from "@paperclipai/shared";
import { slackCallbackMatchesPublicUrl } from "./slack/callback-verification.js";
import { createDiscordCommands } from "./discord/commands.js";
import { createTelegramMaintenance } from "./telegram/maintenance.js";
import type { EndpointRow, RuntimeContext, InternalSetupState } from "./runtime-types.js";
import { createChatResourceReconciliation } from "./resource-reconciliation.js";
import { notifyChatDeliveryWork, notifyChatEndpointWork } from "../chat-work-notifications.js";
import type { ChatEndpointRuntime } from "../voice/voice-runtime.js";
import { chatCredentialMutationLease, type CredentialMutationLeaseGuard } from "../chat-credential-mutation-lease.js";
import { slackChatRegistrationService } from "../chat-slack-registration.js";
import {
createHash,
} from "node:crypto";
import {
and,
eq,
inArray,
isNull,
ne,
sql,
} from "drizzle-orm";
import type { Db } from "@paperclipai/db";
import {
chatConversations,
chatDeliveries,
chatEndpoints,
toolApplications,
toolConnections,
} from "@paperclipai/db";
import type {
ChatEndpoint,
ChatEndpointSetupState,
ChatProvider,
ConfigureChatEndpointInput,
} from "@paperclipai/shared";
import {
MAX_ATTACHMENT_BYTES,
} from "../../attachment-types.js";
import {
badRequest,
conflict,
notFound,
unprocessable,
} from "../../errors.js";
import {
type ResolvedChatSdkProviderConfig,
} from "../chat-sdk-runtime.js";
import {
logActivity,
} from "../activity-log.js";
import type { EndpointRecord } from "./runtime-types.js";
import type { createChatCredentials } from "./credentials.js";
type ChatConfigurationOptions = Pick<ReturnType<typeof createChatCredentials>, "normalizedCredentials" | "verifyCredentials" | "nativeBotIdentityMatches" | "legacyGitHubLabelsMatchVerifiedCredentials" | "assertNativeBotIdentityAvailable" | "isNativeBotIdentityUniqueViolation" | "nativeBotIdentityConflict" | "persistCredentials" | "clearCredentials" | "resolveCredentials" | "prepareProviderInventory"> & {
endpointRecord: (endpointId: string) => Promise<EndpointRecord | null>;
get: (endpointId: string) => Promise<ChatEndpoint>;
withCredentialMutationLease: ReturnType<typeof chatCredentialMutationLease>;
getWebhookPublicBaseUrl: () => string | null;
invalidateRuntime: (endpointId: string) => Promise<boolean>;
reconcileProviderResourceRows: ReturnType<typeof createChatResourceReconciliation>["reconcileProviderResourceRows"];
reconcileDiscordCommands: ReturnType<typeof createDiscordCommands>["reconcileDiscordCommands"];
runtimeFor: (endpoint: EndpointRow, input?: { requireDiscordOwnership?: boolean; waitForDiscordOwnership?: boolean }) => Promise<ChatEndpointRuntime>;
runtimeContextForRecord: (record: EndpointRecord) => RuntimeContext;
stageTelegramMaintenance: ReturnType<typeof createTelegramMaintenance>["stageTelegramMaintenance"];
processTelegramMaintenance: ReturnType<typeof createTelegramMaintenance>["processTelegramMaintenance"];
recordTelegramStopSubscription: ReturnType<typeof createTelegramMaintenance>["recordTelegramStopSubscription"];
fetchImpl: typeof globalThis.fetch;
redactError: (error: unknown) => string;
runtimeGeneration: (setup: ChatEndpointSetupState) => number;
leasedChatProvider: (provider: string) => boolean;
PROVIDER_LABELS: Record<ChatProvider, string>;
SUPPLIED_CREDENTIAL_KEYS: Record<ChatProvider, readonly string[]>;
PROVIDER_CREDENTIAL_CHECK_TIMEOUT_MS: number;
isSupportedTelegramWebhookBaseUrl: (url: string | null) => boolean;
slackRegistration: Pick<ReturnType<typeof slackChatRegistrationService>, "cleanup">;
githubWizard: Pick<ReturnType<typeof createGitHubAppSetup>["githubWizard"], "repairCloud">;
nativeBotIdentityClaimBarrier?: () => Promise<void>;
allowLocalVoiceBoard?: boolean;
};
export function createChatConfiguration(db: Db, options: ChatConfigurationOptions) {
const { endpointRecord, get, withCredentialMutationLease, getWebhookPublicBaseUrl, invalidateRuntime, nativeBotIdentityMatches, assertNativeBotIdentityAvailable, isNativeBotIdentityUniqueViolation, nativeBotIdentityConflict, legacyGitHubLabelsMatchVerifiedCredentials, normalizedCredentials, verifyCredentials, persistCredentials, clearCredentials, resolveCredentials, prepareProviderInventory, reconcileProviderResourceRows, reconcileDiscordCommands, runtimeFor, runtimeContextForRecord, stageTelegramMaintenance, processTelegramMaintenance, recordTelegramStopSubscription, fetchImpl, redactError, runtimeGeneration, leasedChatProvider, PROVIDER_LABELS, SUPPLIED_CREDENTIAL_KEYS, PROVIDER_CREDENTIAL_CHECK_TIMEOUT_MS, isSupportedTelegramWebhookBaseUrl } = options;
const { persistPhotonConfiguration } = createPhotonConfiguration(db, { invalidateRuntime });
const { registerTelegramWebhook } = createTelegramSetup(db, { fetchImpl, getWebhookPublicBaseUrl, PROVIDER_CREDENTIAL_CHECK_TIMEOUT_MS, runtimeContextForRecord, recordTelegramStopSubscription, stageTelegramMaintenance, processTelegramMaintenance });
const { repairGitHubCloudSetup, repairGitHubWebhookSetup } = createGitHubSetup(db, { fetchImpl, getWebhookPublicBaseUrl, get githubWizard() { return options.githubWizard; } });
const { installSpekoVoiceTools, configureSpekoTools } = createSpekoSetup(db, { fetchImpl, getWebhookPublicBaseUrl, get allowLocalVoiceBoard() { return options.allowLocalVoiceBoard; } });
async function configure(
endpointId: string,
input: ConfigureChatEndpointInput,
actorUserId?: string | null,
) {
const record = await endpointRecord(endpointId);
if (!record) throw notFound("Chat endpoint not found");
if (record.endpoint.provider === "agentmail") throw badRequest("Use the email inbox API for AgentMail");
if (input.photon && record.endpoint.provider !== "imessage-photon") throw badRequest("Photon configuration is only valid for iMessage Photon");
const suppliedCredentialKeys = Object.keys(input.credentials ?? {});
if (suppliedCredentialKeys.length > 0) {
const credentialAction =
input.action === "configure" || input.action === "reconnect";
const allowedKeys = new Set(
credentialAction
? SUPPLIED_CREDENTIAL_KEYS[record.endpoint.provider]
: [],
);
const unsupportedKeys = suppliedCredentialKeys.filter(
(key) => !allowedKeys.has(key),
);
if (unsupportedKeys.length > 0) {
throw unprocessable(
`Unsupported ${PROVIDER_LABELS[record.endpoint.provider]} credential fields for ${input.action}: ${unsupportedKeys.join(", ")}`,
{
code: "chat_endpoint_credentials_invalid",
provider: record.endpoint.provider,
action: input.action,
unsupportedKeys,
},
);
}
}
return withCredentialMutationLease(record.endpoint, (credentialLease) =>
configureWithCredentialLease(
endpointId,
input,
credentialLease,
actorUserId,
),
);
}
async function configureWithCredentialLease(
endpointId: string,
input: ConfigureChatEndpointInput,
credentialLease: CredentialMutationLeaseGuard,
actorUserId?: string | null,
) {
const record = await endpointRecord(endpointId);
if (!record) throw notFound("Chat endpoint not found");
const endpoint = record.endpoint;
if (input.action === "pause") {
if (endpoint.status !== "active") {
throw conflict("Only an active chat connection can be paused", {
code: "chat_endpoint_not_active",
});
}
await db.transaction(async (tx) => {
await credentialLease.assertOwned(tx);
const pausedAt = new Date();
const current = await tx
.select({ setup: chatEndpoints.setup, status: chatEndpoints.status })
.from(chatEndpoints)
.where(eq(chatEndpoints.id, endpoint.id))
.for("update")
.then((rows) => rows[0] ?? null);
if (!current || current.status !== "active") {
throw conflict("Only an active chat connection can be paused", {
code: "chat_endpoint_not_active",
});
}
await notifyChatEndpointWork(tx, endpoint.connectionId);
await tx
.update(chatEndpoints)
.set({
status: "paused",
setup: {
...current.setup,
runtimeGeneration: runtimeGeneration(current.setup) + (endpoint.provider === "imessage-photon" ? 0 : 1),
} as InternalSetupState,
updatedAt: pausedAt,
})
.where(eq(chatEndpoints.id, endpoint.id));
await tx
.update(toolConnections)
.set({ status: "disabled", enabled: false, updatedAt: new Date() })
.where(eq(toolConnections.id, endpoint.connectionId));
await notifyChatDeliveryWork(tx);
await tx
.update(chatDeliveries)
.set({
state: "filtered",
nextAttemptAt: null,
redactedError: "Connection was paused before processing",
processedAt: pausedAt,
updatedAt: pausedAt,
})
.where(
and(
endpoint.provider === "imessage-photon" ? sql`false` : undefined,
eq(chatDeliveries.endpointId, endpoint.id),
inArray(chatDeliveries.state, ["received", "retry"]),
),
);
await credentialLease.assertOwned(tx);
});
await invalidateRuntime(endpoint.id);
await logActivity(db, {
companyId: endpoint.companyId,
actorType: "user",
actorId: actorUserId ?? "board",
action: "chat_endpoint.paused",
entityType: "tool_connection",
entityId: endpoint.connectionId,
details: { endpointId: endpoint.id },
});
return get(endpoint.id);
}
if (input.action === "resume") {
if (endpoint.status !== "paused" || endpoint.setup.step !== "complete") {
throw conflict(
"Only a previously active chat connection can be resumed",
{
code: "chat_endpoint_not_resumable",
},
);
}
let credentials = await resolveCredentials(endpoint).catch(() => {
throw conflict("Reconnect the provider credentials before resuming", {
code: "chat_endpoint_credentials_missing",
});
});
const identity = await verifyCredentials(endpoint.provider, credentials);
const upgradingLegacyGitHubIdentity =
endpoint.provider === "github" &&
!endpoint.botExternalId &&
legacyGitHubLabelsMatchVerifiedCredentials(endpoint, identity);
if (
!upgradingLegacyGitHubIdentity &&
!nativeBotIdentityMatches(endpoint.provider, endpoint, identity)
) {
throw conflict(
"The provider credentials now identify a different bot; reconnect this connection instead",
{
code: "chat_bot_identity_changed",
},
);
}
await assertNativeBotIdentityAvailable(endpoint, identity);
const prepared = await prepareProviderInventory(endpoint, credentials);
if (
endpoint.provider === "github" &&
prepared.credentials.installationId !== credentials.installationId
) {
await persistCredentials(
endpoint,
prepared.credentials,
credentialLease,
actorUserId,
);
}
credentials = prepared.credentials;
if (prepared.inventory)
await reconcileProviderResourceRows(
endpoint,
prepared.inventory,
credentialLease,
);
let activatedEndpoint!: EndpointRow;
try {
await db.transaction(async (tx) => {
await credentialLease.assertOwned(tx);
const resumedAt = new Date();
const current = await tx
.select()
.from(chatEndpoints)
.where(eq(chatEndpoints.id, endpoint.id))
.for("update")
.then((rows) => rows[0] ?? null);
if (!current || current.status !== "paused") {
throw conflict(
"Only a previously active chat connection can be resumed",
{
code: "chat_endpoint_not_resumable",
},
);
}
// Fail closed for any legacy or racing delivery that remained open
// while this endpoint was paused. Resume must never execute traffic
// that Paperclip acknowledged during the inactive interval.
await notifyChatDeliveryWork(tx);
await tx
.update(chatDeliveries)
.set({
state: "filtered",
nextAttemptAt: null,
redactedError: "Connection was paused when this event arrived",
processedAt: resumedAt,
updatedAt: resumedAt,
})
.where(
and(
endpoint.provider === "imessage-photon" ? sql`false` : undefined,
eq(chatDeliveries.endpointId, endpoint.id),
inArray(chatDeliveries.state, ["received", "retry"]),
),
);
await notifyChatEndpointWork(tx, endpoint.connectionId);
[activatedEndpoint] = await tx
.update(chatEndpoints)
.set({
status: "active",
...(upgradingLegacyGitHubIdentity
? { botExternalId: identity.botExternalId }
: {}),
healthMessage: "Connected",
lastError: null,
setup: {
...current.setup,
...(endpoint.provider === "imessage-photon" ? { photonIntakeAfter: resumedAt.toISOString() } : {}),
runtimeGeneration: runtimeGeneration(current.setup) + (endpoint.provider === "imessage-photon" ? 0 : 1),
} as InternalSetupState,
updatedAt: resumedAt,
})
.where(eq(chatEndpoints.id, endpoint.id))
.returning();
await tx
.update(toolConnections)
.set({
status: "active",
enabled: true,
healthStatus: "healthy",
healthMessage: "Connected",
lastError: null,
healthCheckedAt: new Date(),
updatedAt: new Date(),
})
.where(eq(toolConnections.id, endpoint.connectionId));
await credentialLease.assertOwned(tx);
});
await invalidateRuntime(endpoint.id);
if (activatedEndpoint.provider === "discord")
await reconcileDiscordCommands(endpoint.id, credentialLease, true);
await runtimeFor(activatedEndpoint, {
requireDiscordOwnership: leasedChatProvider(activatedEndpoint.provider),
waitForDiscordOwnership: leasedChatProvider(activatedEndpoint.provider),
});
} catch (error) {
await invalidateRuntime(endpoint.id).catch(() => undefined);
if (activatedEndpoint) {
const failure = redactError(error);
const failedAt = new Date();
await db.transaction(async (tx) => {
await credentialLease.assertOwned(tx);
await notifyChatEndpointWork(tx, endpoint.connectionId);
await tx
.update(chatEndpoints)
.set({
status: "attention",
healthMessage: "Provider resume needs attention",
lastError: failure,
updatedAt: failedAt,
})
.where(
and(
eq(chatEndpoints.id, endpoint.id),
eq(chatEndpoints.status, "active"),
sql`coalesce((${chatEndpoints.setup}->>'runtimeGeneration')::integer, 0) = ${runtimeGeneration(activatedEndpoint.setup)}`,
),
);
await tx
.update(toolConnections)
.set({
status: "disabled",
enabled: false,
healthStatus: "degraded",
healthMessage: "Provider resume failed",
lastError: failure,
healthCheckedAt: failedAt,
updatedAt: failedAt,
})
.where(eq(toolConnections.id, endpoint.connectionId));
await notifyChatDeliveryWork(tx);
await tx
.update(chatDeliveries)
.set({
state: "filtered",
nextAttemptAt: null,
redactedError: "Connection activation failed",
processedAt: failedAt,
updatedAt: failedAt,
})
.where(
and(
eq(chatDeliveries.endpointId, endpoint.id),
inArray(chatDeliveries.state, ["received", "retry"]),
),
);
await credentialLease.assertOwned(tx);
});
}
throw error;
}
await logActivity(db, {
companyId: endpoint.companyId,
actorType: "user",
actorId: actorUserId ?? "board",
action: "chat_endpoint.resumed",
entityType: "tool_connection",
entityId: endpoint.connectionId,
details: { endpointId: endpoint.id },
});
return get(endpoint.id);
}
if (input.action === "remove") {
if (endpoint.status === "archived") {
if (endpoint.provider === "slack") await options.slackRegistration.cleanup(endpoint.id, credentialLease);
// Archival is the durable ingress fence and intentionally commits
// before secret-store cleanup. If that cleanup failed, a repeated
// remove is the recovery operation; once refs are empty, retain the
// normal already-removed conflict contract.
if (record.credentialSecretRefs.length > 0) {
await invalidateRuntime(endpoint.id).catch(() => undefined);
if (endpoint.provider === "telegram") {
await credentialLease.assertOwned();
const action = await stageTelegramMaintenance(
endpoint,
"remove_endpoint",
);
if (action)
await processTelegramMaintenance(
action.id,
true,
credentialLease,
);
} else {
await clearCredentials(endpoint, credentialLease);
}
return get(endpoint.id);
}
throw conflict("This chat connection has already been removed", {
code: "chat_endpoint_already_removed",
});
}
await db.transaction(async (tx) => {
await credentialLease.assertOwned(tx);
const current = await tx
.select({ setup: chatEndpoints.setup, status: chatEndpoints.status })
.from(chatEndpoints)
.where(eq(chatEndpoints.id, endpoint.id))
.for("update")
.then((rows) => rows[0] ?? null);
if (!current || current.status === "archived") {
throw conflict("This chat connection has already been removed", {
code: "chat_endpoint_already_removed",
});
}
await notifyChatEndpointWork(tx, endpoint.connectionId);
await tx
.update(chatEndpoints)
.set({
status: "archived",
setup: {
...current.setup,
runtimeGeneration: runtimeGeneration(current.setup) + 1,
} as InternalSetupState,
archivedAt: new Date(),
updatedAt: new Date(),
})
.where(eq(chatEndpoints.id, endpoint.id));
await tx
.update(chatConversations)
.set({ state: "endpoint_removed", updatedAt: new Date() })
.where(eq(chatConversations.endpointId, endpoint.id));
await tx
.update(toolConnections)
.set({ status: "archived", enabled: false, updatedAt: new Date() })
.where(eq(toolConnections.id, endpoint.connectionId));
const otherConnection = await tx
.select({ id: toolConnections.id })
.from(toolConnections)
.where(
and(
eq(toolConnections.companyId, endpoint.companyId),
eq(toolConnections.applicationId, record.applicationId),
ne(toolConnections.id, endpoint.connectionId),
ne(toolConnections.status, "archived"),
),
)
.limit(1)
.then((rows) => rows[0] ?? null);
if (!otherConnection) {
await tx
.update(toolApplications)
.set({
status: "archived",
archivedAt: new Date(),
updatedAt: new Date(),
})
.where(eq(toolApplications.id, record.applicationId));
}
await credentialLease.assertOwned(tx);
});
if (endpoint.provider === "slack") await options.slackRegistration.cleanup(endpoint.id, credentialLease);
await invalidateRuntime(endpoint.id).catch(() => undefined);
if (endpoint.provider === "telegram") {
await credentialLease.assertOwned();
const action = await stageTelegramMaintenance(
endpoint,
"remove_endpoint",
);
if (action) {
await processTelegramMaintenance(action.id, true, credentialLease);
}
} else {
await clearCredentials(endpoint, credentialLease);
}
return get(endpoint.id);
}
if (
input.action !== "configure" &&
input.action !== "reconnect" &&
input.action !== "verify"
) {
throw unprocessable("Unsupported chat endpoint setup action");
}
if (!getWebhookPublicBaseUrl() && endpoint.provider !== "discord" && endpoint.provider !== "imessage-photon" && !(endpoint.provider === "github" && endpoint.setup.github?.cloudRegistrationId)) {
throw unprocessable(
`A public HTTPS Paperclip URL is required before connecting ${PROVIDER_LABELS[endpoint.provider]}`,
);
}
if (
endpoint.provider === "telegram" &&
(input.action === "configure" || input.action === "reconnect") &&
!isSupportedTelegramWebhookBaseUrl(getWebhookPublicBaseUrl())
) {
throw unprocessable(
"Telegram webhooks require PAPERCLIP_CHAT_WEBHOOK_PUBLIC_URL to use HTTPS on port 443, 80, 88, or 8443",
{
code: "chat_telegram_webhook_url_unsupported",
provider: "telegram",
supportedPorts: [443, 80, 88, 8443],
},
);
}
if (input.action === "verify") {
if (
endpoint.provider !== "slack" ||
endpoint.status !== "verifying" ||
endpoint.setup.step !== "provider_setup"
) {
throw conflict(
"Provider verification is not available at this setup step",
{
code: "chat_endpoint_invalid_setup_step",
},
);
}
if (!endpoint.setup.webhookVerifiedAt) {
throw conflict("Paperclip has not received a verified Slack callback yet", {
code: "chat_webhook_not_verified",
});
}
} else if (
input.action === "configure" &&
!["draft", "attention", "revoked"].includes(endpoint.status) &&
// GitHub installation discovery can advance the status before the
// wizard has configured its runtime. Finish that exact setup stage;
// configured connections still require the explicit reconnect flow.
!(
endpoint.provider === "github" &&
endpoint.status === "verifying" &&
endpoint.setup.step === "provider_setup"
)
) {
throw conflict(
"This connection is already configured; use its reconnect flow if credentials need repair",
{
code: "chat_endpoint_already_configured",
},
);
} else if (
input.action === "reconnect" &&
!["verifying", "active", "attention", "revoked", "paused"].includes(
endpoint.status,
)
) {
throw conflict(
"This chat connection does not currently need reconnecting",
{
code: "chat_endpoint_not_reconnectable",
},
);
}
if (
endpoint.provider === "github" &&
(input.action === "configure" || input.action === "reconnect") &&
!endpoint.setup.webhookVerifiedAt
) {
throw conflict(
"GitHub has not delivered a signed webhook ping for this secret yet",
{
code: "chat_webhook_not_verified",
},
);
}
let verifiedCurrentIdentity: VerifiedProviderIdentity = endpoint;
if (
input.action === "reconnect" &&
endpoint.provider === "github" &&
!endpoint.botExternalId
) {
const storedCredentials = await resolveCredentials(endpoint).catch(() => {
throw conflict(
"Reconnect the existing GitHub App credentials before changing them",
{
code: "chat_bot_identity_unverifiable",
},
);
});
const storedIdentity = await verifyCredentials(
"github",
storedCredentials,
);
if (
!legacyGitHubLabelsMatchVerifiedCredentials(endpoint, storedIdentity)
) {
throw conflict(
"The stored credentials no longer verify the GitHub App that owns this connection",
{
code: "chat_bot_identity_unverifiable",
},
);
}
verifiedCurrentIdentity = storedIdentity;
}
const previousSpekoSigningSecret = endpoint.provider === "speko"
? (await resolveCredentials(endpoint).catch(() => ({} as Record<string, string>))).signingSecret : undefined;
let credentials =
input.credentials && Object.keys(input.credentials).length > 0
? await normalizedCredentials(endpoint, input.credentials)
: await resolveCredentials(endpoint).catch(() => {
throw unprocessable(
`${PROVIDER_LABELS[endpoint.provider]} credentials are required`,
);
});
if (endpoint.provider === "imessage-photon") {
credentials = preparePhotonConfiguration(endpoint, input, credentials);
}
const identity = await verifyCredentials(endpoint.provider, credentials);
// Once setup has claimed a provider bot identity, every credential repair
// must prove that same identity before secrets can be replaced. A process
// interruption can leave the endpoint in `attention` after the claim but
// before credential persistence; a repeated first-setup request must not
// turn that recovery state into an identity-swap escape hatch.
if (input.action === "reconnect" || Boolean(endpoint.botExternalId)) {
if (
!nativeBotIdentityMatches(
endpoint.provider,
verifiedCurrentIdentity,
identity,
)
) {
throw conflict(
"The provider credentials identify a different bot; create a new connection for that bot instead",
{ code: "chat_bot_identity_changed" },
);
}
}
await assertNativeBotIdentityAvailable(endpoint, identity);
const prepared = await prepareProviderInventory(endpoint, credentials);
const credentialsChangedByDiscovery =
endpoint.provider === "github" &&
prepared.credentials.installationId !== credentials.installationId;
credentials = prepared.credentials;
await options.nativeBotIdentityClaimBarrier?.();
// Claim a fresh provider identity before any newly supplied secrets are
// persisted. The provider-global unique indexes are the multi-process
// arbitration boundary when two setup requests both pass the optimistic
// preflight. A process that stops after this small claim leaves a
// fail-closed attention endpoint that the same operator can reconnect;
// it never leaves credentials bound to the losing endpoint.
if (!endpoint.botExternalId) {
try {
const claimed = await db.transaction(async (tx) => {
await credentialLease.assertOwned(tx);
await notifyChatEndpointWork(tx, endpoint.connectionId);
const rows = await tx
.update(chatEndpoints)
.set({
status: "attention",
providerAccountId: identity.providerAccountId ?? null,
providerAccountLabel: identity.providerAccountLabel ?? null,
botExternalId: identity.botExternalId ?? null,
botUsername: identity.botUsername ?? null,
botDisplayName:
identity.botLabel ??
endpoint.botDisplayName ??
record.assignedAgentName,
healthMessage: "Provider setup must be completed",
lastError: null,
updatedAt: new Date(),
})
.where(
and(
eq(chatEndpoints.id, endpoint.id),
eq(chatEndpoints.status, endpoint.status),
isNull(chatEndpoints.botExternalId),
),
)
.returning({ id: chatEndpoints.id });
await credentialLease.assertOwned(tx);
return rows;
});
if (claimed.length !== 1) {
throw conflict("This chat connection changed during setup", {
code: "chat_endpoint_setup_changed",
});
}
} catch (error) {
if (isNativeBotIdentityUniqueViolation(error)) {
throw nativeBotIdentityConflict(endpoint.provider);
}
throw error;
}
}
if (endpoint.provider === "imessage-photon") {
await persistPhotonConfiguration(endpoint, credentials, credentialLease);
}
if (
(input.credentials && Object.keys(input.credentials).length > 0) ||
credentialsChangedByDiscovery
)
await persistCredentials(
endpoint,
credentials,
credentialLease,
actorUserId,
);
if (prepared.inventory)
await reconcileProviderResourceRows(
endpoint,
prepared.inventory,
credentialLease,
);
const updatedAt = new Date();
const waitingForSlackConfiguration =
endpoint.provider === "slack" &&
(input.action === "configure" || input.action === "reconnect");
try {
await db.transaction(async (tx) => {
await credentialLease.assertOwned(tx);
const current = await tx
.select({ setup: chatEndpoints.setup })
.from(chatEndpoints)
.where(eq(chatEndpoints.id, endpoint.id))
.for("update")
.then((rows) => rows[0] ?? null);
if (!current) throw notFound("Chat endpoint not found");
if (endpoint.provider === "speko") {
await installSpekoVoiceTools(tx, endpoint, actorUserId);
}
const observedSlackUrl = (current.setup as InternalSetupState).slackCallbackSurfaces?.events?.url;
const preserveSlackVerification = isProvisionedSlackSetup(current.setup.slackSetupMethod)
&& (current.setup as InternalSetupState).slackVerificationSigningFingerprint === createHash("sha256").update(credentials.signingSecret ?? "").digest("hex")
&& Boolean(observedSlackUrl && slackCallbackMatchesPublicUrl(observedSlackUrl, `${getWebhookPublicBaseUrl()}/api/chat-webhooks/${endpoint.publicId}/slack`));
await notifyChatEndpointWork(tx, endpoint.connectionId);
await tx
.update(chatEndpoints)
.set({
status: "verifying",
providerAccountId: identity.providerAccountId ?? null,
providerAccountLabel: identity.providerAccountLabel ?? null,
botExternalId: identity.botExternalId ?? null,
botUsername: identity.botUsername ?? null,
botDisplayName:
identity.botLabel ??
endpoint.botDisplayName ??
record.assignedAgentName,
healthMessage: waitingForSlackConfiguration
? "Finish provider webhook configuration"
: "Waiting for a test conversation",
lastError: null,
lastEventAt: null,
setup: {
...current.setup,
...(endpoint.provider === "github" ? { github: { ...current.setup.github, stage: current.setup.github?.stage ?? "connect", appOwnerType: identity.githubOwnerType, appOwnerLogin: identity.githubOwnerLogin } } : {}),
step: waitingForSlackConfiguration ? "provider_setup" : "test",
...(endpoint.provider === "imessage-photon" ? { photonIntakeAfter: (current.setup as InternalSetupState).photonIntakeAfter ?? updatedAt.toISOString() } : {}),
testStartedAt: waitingForSlackConfiguration
? null
: updatedAt.toISOString(),
webhookVerifiedAt: waitingForSlackConfiguration
? preserveSlackVerification ? (current.setup.webhookVerifiedAt ?? null) : null
: (current.setup.webhookVerifiedAt ?? null),
runtimeGeneration: runtimeGeneration(current.setup) + 1,
} as InternalSetupState,
updatedAt,
})
.where(eq(chatEndpoints.id, endpoint.id));
await tx
.update(toolConnections)
.set({
status: "active",
enabled: true,
healthStatus: "healthy",
healthMessage: "Provider credentials verified",
healthCheckedAt: updatedAt,
updatedAt,
})
.where(eq(toolConnections.id, endpoint.connectionId));
await tx
.update(toolApplications)
.set({ status: "active", archivedAt: null, updatedAt })
.where(eq(toolApplications.id, record.applicationId));
await credentialLease.assertOwned(tx);
});
} catch (error) {
if (isNativeBotIdentityUniqueViolation(error)) {
throw nativeBotIdentityConflict(endpoint.provider);
}
throw error;
}
try {
const next = await endpointRecord(endpoint.id);
if (!next) throw notFound("Chat endpoint not found");
await invalidateRuntime(endpoint.id);
if (endpoint.provider === "github" && input.action === "reconnect" && endpoint.setup.github?.cloudRegistrationId) {
await repairGitHubCloudSetup(endpoint, credentialLease, actorUserId);
}
if (endpoint.provider === "github" && input.action === "reconnect" && !endpoint.setup.github?.cloudRegistrationId) {
await repairGitHubWebhookSetup(endpoint, credentials, credentialLease, actorUserId);
}
if (next.endpoint.provider === "speko") {
await configureSpekoTools(endpoint, credentials, credentialLease, previousSpekoSigningSecret);
}
if (next.endpoint.provider === "discord")
await reconcileDiscordCommands(endpoint.id, credentialLease, true);
await runtimeFor(next.endpoint, {
requireDiscordOwnership: next.endpoint.provider === "discord",
waitForDiscordOwnership: next.endpoint.provider === "discord",
});
if (endpoint.provider === "telegram" && getWebhookPublicBaseUrl()) {
await registerTelegramWebhook(endpoint, input, credentials, credentialLease, next);
}
} catch (error) {
const failure = redactError(error);
await invalidateRuntime(endpoint.id).catch(() => undefined);
await db.transaction(async (tx) => {
await credentialLease.assertOwned(tx);
await notifyChatEndpointWork(tx, endpoint.connectionId);
await tx
.update(chatEndpoints)
.set({
status: "attention",
healthMessage: "Provider setup needs attention",
lastError: failure,
updatedAt: new Date(),
})
.where(eq(chatEndpoints.id, endpoint.id));
await tx
.update(toolConnections)
.set({
healthStatus: "degraded",
healthMessage: "Provider setup failed",
lastError: failure,
healthCheckedAt: new Date(),
updatedAt: new Date(),
})
.where(eq(toolConnections.id, endpoint.connectionId));
await credentialLease.assertOwned(tx);
});
throw unprocessable(failure, { code: "chat_provider_setup_failed" });
}
await db.transaction(async (tx) => {
await credentialLease.assertOwned(tx);
await logActivity(tx as unknown as Db, {
companyId: endpoint.companyId,
actorType: "user",
actorId: actorUserId ?? "board",
action:
input.action === "reconnect"
? "chat_endpoint.reconnected"
: "chat_endpoint.credentials_verified",
entityType: "tool_connection",
entityId: endpoint.connectionId,
details: { endpointId: endpoint.id, provider: endpoint.provider },
});
await credentialLease.assertOwned(tx);
});
return get(endpoint.id);
}
function runtimeConfig(
endpoint: EndpointRow,
userName: string,
credentials: Record<string, string>,
): ResolvedChatSdkProviderConfig {
if (endpoint.provider === "speko") throw conflict("Speko uses the voice runtime");
if (endpoint.provider === "imessage-photon") return {
provider: "imessage-photon", userName,
intakeAfter: Date.parse(String((endpoint.setup as InternalSetupState).photonIntakeAfter ?? endpoint.setup.testStartedAt ?? endpoint.createdAt.toISOString())),
credentials: { allocation: credentials.allocation === "shared" ? "shared" : "dedicated", projectId: credentials.projectId, lineId: credentials.lineId, projectSecret: credentials.projectSecret, phoneNumber: endpoint.botExternalId! },
};
if (endpoint.provider === "slack")
return slackRuntimeConfig(endpoint, userName, credentials);
if (endpoint.provider === "telegram")
return {
provider: "telegram",
userName,
maxDownloadBytes: MAX_ATTACHMENT_BYTES,
credentials: {
botToken: credentials.botToken,
secretToken: credentials.webhookSecret,
},
};
if (endpoint.provider === "discord")
return {
provider: "discord",
userName,
credentials: {
applicationId: credentials.applicationId,
botToken: credentials.botToken,
guildId: credentials.guildId,
},
};
if (endpoint.provider === "microsoft-teams")
return {
provider: "microsoft-teams",
userName,
credentials: {
appId: credentials.clientId,
appPassword: credentials.clientSecret,
appTenantId: credentials.tenantId,
appType: "SingleTenant",
},
};
return {
provider: "github",
userName,
credentials: {
appId: credentials.appId,
privateKey: credentials.privateKey,
installationId: credentials.installationId
? Number(credentials.installationId)
: undefined,
webhookSecret: credentials.webhookSecret,
},
};
}
return { configure, configureWithCredentialLease, runtimeConfig };
}