PaperClipAI/server/src/services/tool-access.ts

import { notifyVoiceChange } from "./voice/voice-recovery-notifications.js";
import { notifyToolConnectionHealth, writeToolConnectionHealthChange } from "./tool-connection-health-notifications.js";
import { connectionHealthSchedule } from "./tool-access/catalog/health-schedule.js";
import type { ConnectionManagementContext } from "./connection-management.js";
import { connectionActorUserId } from "./tool-access/actor.js";
import { restConnectorFor } from "./connectors/rest-registry.js";
import { createConnectionCredentialValidation } from "./tool-access/connections/credential-validation.js";
import { createConnectionGrants } from "./tool-access/connections/grants.js";
import { createConnectionInstalls } from "./tool-access/connections/installs.js";
import { createConnectionRemoval } from "./tool-access/connections/removal.js";
import { createToolRemoteHttp } from "./tool-access/remote-http.js";
import { classifyRisk, normalizeToolDescriptor, type McpToolDescriptor } from "./tool-access/catalog/descriptors.js";
export { classifyRisk, isGmailToolPermanentlyBlocked, isGoogleWorkspaceToolAllowed, type McpToolDescriptor } from "./tool-access/catalog/descriptors.js";
import { toCatalogEntry } from "./tool-access/catalog/projection.js";
import { toConnection, toConnectionInstall } from "./tool-access/connections/projection.js";
import { isOAuthEndpointRejection } from "./tool-access/catalog/failures.js";
import { createCatalogDefaultAccess, toPolicy } from "./tool-access/catalog/default-access.js";
import { createToolCatalogDiscovery } from "./tool-access/catalog/discovery.js";
import { createConnectionHealth } from "./tool-access/catalog/health.js";
import { createToolAppAttention } from "./tool-access/catalog/attention.js";
import { createToolCatalogPublication } from "./tool-access/catalog/publication.js";
import { createToolCatalogReader } from "./tool-access/catalog/reader.js";
import { createAggregatorAccounts } from "./tool-access/catalog/aggregator-accounts.js";
import { actorBinding } from "./tool-access/actor.js";
import { toApplication } from "./tool-access/applications/projection.js";
import { groupedActions } from "./tool-access/catalog/action-summary.js";
import { createConnectionSetupPolicy, assertSupportedConnection } from "./tool-access/connections/setup-policy.js";
import { createOrganizationGrantStore } from "./tool-access/connections/organization-grant.js";
import { createPersonalConnectionIdentity } from "./tool-access/connections/personal-identity.js";
import { createOAuthStateStore } from "./tool-access/oauth/state.js";
import { createOAuthCatalogCompletion } from "./tool-access/oauth/catalog-completion.js";
import { createOAuthAuthorizationStart } from "./tool-access/oauth/authorization-start.js";
import { createDirectOAuthCallback } from "./tool-access/oauth/direct-callback.js";
import { createCloudOAuthCallback } from "./tool-access/oauth/cloud-callback.js";
import { createVercelOAuthCallback } from "./tool-access/oauth/vercel-callback.js";
import { createOAuthAccessFinalization } from "./tool-access/oauth/access-finalization.js";
import { createVercelCredentialService, vercelConnectHttpError } from "./tool-access/vercel-credentials.js";
import { createConnectionCredentialAccess } from "./tool-access/credential-access.js";

import { createOAuthCredentialStore, actorForSecret } from "./tool-access/oauth/credential-store.js";
import { managedConnectorProfile } from "./tool-access/oauth/client-settings.js";
import { createOAuthClientRegistration } from "./tool-access/oauth/client-registration.js";
import { createOAuthRefreshLeases } from "./tool-access/oauth/refresh-leases.js";
import { createLegacyOAuthRefresh } from "./tool-access/oauth/connection-refresh.js";
import { createOAuthGrantRefresh } from "./tool-access/oauth/grant-refresh.js";
import { createGitHubGrantContinuity } from "./tool-access/github-grant-continuity.js";
import { createToolRuntimeHealth } from "./tool-access/runtime/health.js";
import { createToolRuntimeSlots } from "./tool-access/runtime/slots.js";
import { createToolActivityService } from "./tool-access/activity/service.js";
import { createToolActionReviewQueue } from "./tool-access/activity/review-queue.js";
import { createToolAccessAudit } from "./tool-access/audit.js";
import { createConnectionTokenBroker } from "./tool-access/token-broker/service.js";

import { createToolProfileService } from "./tool-access/profiles/service.js";
import { createToolProfileResolver } from "./tool-access/profiles/resolution.js";
import { toProfile, toProfileEntry, toProfileBinding } from "./tool-access/profiles/projection.js";
import { lockManagedAppPolicies, lockToolAssignmentAgents } from "./tool-access/assignment-locks.js";
export { lockToolConnectionRuntimeInputs } from "./tool-access/assignment-locks.js";
import type { ActorInfo } from "./tool-access/types.js";
import { normalizeKey, connectionUid } from "./tool-access/identifiers.js";
import { createOAuthEndpointPolicy } from "./tool-access/oauth/endpoint-policy.js";
import { createOAuthDiscovery } from "./tool-access/oauth/discovery.js";
import { createOAuthClientProtocol } from "./tool-access/oauth/client.js";

import type { OAuthClientRegistrationSource } from "./tool-access/oauth/types.js";
export { OAUTH_CLIENT_ID_METADATA_DOCUMENT_PATH, resolveOAuthClientIdMetadataDocumentUrl, oauthClientIdMetadataDocument } from "./tool-access/oauth/client-metadata.js";
import { connectionMethodFor, connectionMethodForConnection, credentialFieldsFor, normalizeConnectionMethodConfig, projectedConnectionToolInputSchema } from "./tool-access/connection-methods.js";
export {
  normalizeConnectionMethodConfig,
  projectedConnectionHeaders,
  projectConnectionMethodToolArguments,
  projectConnectionMethodToolInputSchema,
  projectedConnectionToolArguments,
  projectedConnectionToolInputSchema,
} from "./tool-access/connection-methods.js";
import { loadGitHubTokenRepositories } from "./tool-access/github-access-discovery.js";
export { loadGitHubGrantMetadata, loadGitHubTokenRepositories } from "./tool-access/github-access-discovery.js";

import { stableHash } from "./tool-catalog-hash.js";

import { NATIVE_PROVIDER_SLUGS, nativeProviderCatalogFor } from "./native-provider-catalogs.js";
import { connectorToolPolicy } from "./connectors/tool-policy.js";

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

import { defaultConnectionAgentInstructions } from "@paperclipai/shared";

import { isBrowserUseConnection } from "./browser-use-client.js";

import { COGNEE_STDIO_TEMPLATE } from "./cognee-connection.js";
import { isRemoteMcpConnectorMethod } from "@paperclipai/shared";

import { githubBotRequest } from "./chat-github-client.js";
import { syncConnectionCredentialBindings } from "./connection-credential-bindings.js";
import {
  emitConnectionCreated,
  emitConnectionUpdated,
} from "./connector-telemetry.js";
import { canBrowseProjectRepositoryGrant, mergeProjectRepository } from "./project-repositories.js";

import { measureRunPhase } from "./execution-preparation-timing.js";

import { randomUUID } from "node:crypto";
import { readFileSync } from "node:fs";
import { and, asc, desc, eq, inArray, max, ne, sql } from "drizzle-orm";
import type { Db } from "@paperclipai/db";
import { agents, connectionGrantMembers, connectionGrants, companyMemberships, principalPermissionGrants, userSecretDefinitions, plugins, toolAccessAuditEvents, toolApplications, toolCatalogEntries, toolConnectionInstalls, toolConnections, toolStdioCommandTemplates, toolCallEvents, toolPolicies, toolProfileBindings, toolProfileEntries, toolProfiles } from "@paperclipai/db";
import type { AppDefinition, ConnectionGrantKind, CreateToolApplication, CreateToolConnection, ConnectToolApp, ConnectToolAppResult, CreateToolStdioCommandTemplate, FinishToolApp, FinishToolAppResult, CreateToolProfileBindingForProfile, CreateToolProfileEntryForProfile, DeploymentExposure, DeploymentMode, ImportMcpJson, McpConnectionCredentialRef, McpJsonImportPreview, ToolApplication, ToolCatalogEntry, ToolCatalogRefreshResult, ToolConnection, ToolConnectionInstall, ToolConnectionHealthCheckResult, ToolConnectionAuthKind, ToolConnectionCredentialPolicy, ToolConnectionCredentialSource, ToolConnectionTransport, ToolAppMetadataPreflightResult, ToolExampleInstallResult, ToolExampleSmokeCheck, ToolExampleSmokeResult, ToolExampleSummary, ToolProfileBinding, ToolProfileEntry, ToolPolicyDecision, ToolStdioCommandTemplate, UpdateToolApplication, UpdateToolConnection, VercelConnectCredentialReference } from "@paperclipai/shared";
import { getAppDefinitionForUrl, getAvailableConnectionMethods, getConnectableAppDefinition, recommendedDefaultsForApp } from "@paperclipai/shared";
import {
  checkMcpRemoteHeaderName,
  checkMcpRemoteHeaderValue,
  mcpRemoteHeaderNameFromConfigPath,
  mcpRemoteHeaderRejectionMessage,
} from "@paperclipai/shared";
import {
  badRequest,
  conflict,
  forbidden,
  HttpError,
  notFound,
  unprocessable,
} from "../errors.js";
import { isUniqueViolation } from "../db-errors.js";

import { forgetMcpHttpSessions } from "./mcp-http.js";
import { type RemoteHttpEndpointLookup } from "./remote-http-endpoint-guard.js";

import {
  REMOTE_URL_SECRET_CONFIG_PATH,
  remoteUrlCredentialMatchesPublicUrl,
  splitRemoteUrlCredential,
} from "./remote-url-credentials.js";
import { secretService } from "./secrets.js";
import { connectionCredentialConfigPath as credentialRefConfigPath, validateConnectionGrantSecretOwnership, writeConnectionCredential } from "./connection-credentials.js";

import type { ConfigureRailwaySsh, RailwaySshSetup } from "@paperclipai/shared";
import { generateRailwaySshKey, RAILWAY_SSH_SECRET_PATH, validateRailwayKnownHosts } from "./railway-ssh.js";
import { isRailwayConnection } from "./railway.js";
import { toolAccessPolicyService } from "./tool-access-policy.js";

import { googleChatToolDescription } from "./google-chat-tool-policy.js";
import { gmailArchiveToolDescription } from "./gmail-archive-tool-policy.js";

import { createToolRuntimeSupervisor } from "./tool-runtime-supervisor.js";

import { appWithPaperclipCloudConnectorAvailability, paperclipCloudConnectorCapabilitiesFromEnv, createPaperclipCloudConnector, isPaperclipCloudConnectorStrategy, paperclipCloudConnectorConfigFromEnv, type PaperclipCloudConnector } from "./paperclip-cloud-connector.js";
import { createVercelConnectClient, deriveVercelConnectSubject, vercelConnectIntegrationStatus, type VercelConnectClient } from "./vercel-connect.js";

type ToolAccessServiceOptions = {
  deploymentMode?: DeploymentMode;
  deploymentExposure?: DeploymentExposure;
  trustedLocalStdioRuntimeHost?: string | null;
  now?: () => Date;
  /** How long persisted remote MCP action discovery remains fresh. */
  catalogCacheTtlMs?: number;
  /** Test seam for deciding whether an OAuth client metadata URL is publicly resolvable. */
  oauthClientMetadataLookup?: RemoteHttpEndpointLookup;
  /** Test seam for deterministic remote endpoint resolution. Production uses DNS. */
  remoteHttpEndpointLookup?: RemoteHttpEndpointLookup;
  /** Test seam for protocol fixtures. Production uses the DNS-pinned transport. */
  remoteHttpRequest?: (url: string, init: RequestInit) => Promise<Response>;
  /** Smaller reviewed catalog for deterministic discovery fixtures. */
  composioAppToolkits?: readonly string[];
  /** Test seam for the centrally registered Gmail OAuth broker. */
  paperclipCloudConnector?: PaperclipCloudConnector | null;
  /** @deprecated Use paperclipCloudConnector. */
  paperclipIdGmailConnector?: PaperclipCloudConnector | null;
  /** Test seam for Vercel Connect without live vendor traffic. */
  vercelConnectClient?: VercelConnectClient | null;
};

const GOOGLE_SHEETS_SPREADSHEET_SCHEMA = {
  type: "object",
  properties: {
    spreadsheetId: { type: "string", minLength: 1 },
  },
  required: ["spreadsheetId"],
};

const GOOGLE_SHEETS_RANGE_SCHEMA = {
  type: "object",
  properties: {
    spreadsheetId: { type: "string", minLength: 1 },
    range: { type: "string", minLength: 1, maxLength: 500 },
  },
  required: ["spreadsheetId", "range"],
};

const GOOGLE_SHEETS_VALUE_ROWS_SCHEMA = {
  type: "array",
  minItems: 1,
  items: {
    type: "array",
    items: {
      anyOf: [
        { type: "string" },
        { type: "number" },
        { type: "boolean" },
        { type: "null" },
      ],
    },
  },
};

const GOOGLE_SHEETS_WRITE_VALUES_SCHEMA = {
  type: "object",
  properties: {
    spreadsheetId: { type: "string", minLength: 1 },
    range: { type: "string", minLength: 1, maxLength: 500 },
    values: GOOGLE_SHEETS_VALUE_ROWS_SCHEMA,
    valueInputOption: {
      type: "string",
      enum: ["RAW", "USER_ENTERED"],
      default: "RAW",
    },
  },
  required: ["spreadsheetId", "range", "values"],
};

function schemaHasInputProperties(schema: unknown): boolean {
  if (!schema || typeof schema !== "object" || Array.isArray(schema))
    return false;
  const properties = (schema as Record<string, unknown>).properties;
  return Boolean(
    properties &&
    typeof properties === "object" &&
    !Array.isArray(properties) &&
    Object.keys(properties).length > 0,
  );
}

const APPROVED_STDIO_TEMPLATES: Record<
  string,
  {
    name: string;
    command?: string | null;
    args?: string[];
    envKeys?: string[];
    tools: McpToolDescriptor[];
  }
> = {
  "paperclip.echo-calculator-time": {
    name: "Paperclip Echo / Calculator / Time fixture",
    tools: [
      {
        name: "echo",
        description: "Return the provided message.",
        inputSchema: {
          type: "object",
          properties: { message: { type: "string" } },
          required: ["message"],
        },
        annotations: { readOnlyHint: true },
      },
      {
        name: "add",
        description: "Add two numbers.",
        inputSchema: {
          type: "object",
          properties: { a: { type: "number" }, b: { type: "number" } },
          required: ["a", "b"],
        },
        annotations: { readOnlyHint: true },
      },
      {
        name: "now",
        description: "Return the current server time.",
        inputSchema: { type: "object", properties: {} },
        annotations: { readOnlyHint: true },
      },
      {
        name: "fail_with_code",
        description: "Deterministically fail with a requested status code.",
        inputSchema: {
          type: "object",
          properties: { code: { type: "number" } },
          required: ["code"],
        },
        annotations: { readOnlyHint: true },
      },
    ],
  },
  "paperclip.synthetic-todo-kv": {
    name: "Paperclip Synthetic Todo / KV fixture",
    tools: [
      {
        name: "list_items",
        description: "List synthetic todo items.",
        annotations: { readOnlyHint: true },
      },
      {
        name: "create_item",
        description: "Create a synthetic todo item.",
        annotations: { readOnlyHint: false },
      },
      {
        name: "mark_done",
        description: "Mark a synthetic todo item done.",
        annotations: { readOnlyHint: false },
      },
      {
        name: "delete_item",
        description: "Delete a synthetic todo item.",
        annotations: { destructiveHint: true },
      },
      {
        name: "get_value",
        description: "Read a synthetic KV value.",
        annotations: { readOnlyHint: true },
      },
      {
        name: "set_value",
        description: "Write a synthetic KV value.",
        annotations: { readOnlyHint: false },
      },
    ],
  },
  "paperclip.cognee-cloud": COGNEE_STDIO_TEMPLATE,
  "paperclip.google-sheets": {
    name: "Google Sheets",
    command: "paperclip-google-sheets-mcp-server",
    args: [],
    envKeys: [
      "GOOGLE_SHEETS_SERVICE_ACCOUNT_JSON",
      "GOOGLE_SHEETS_SERVICE_ACCOUNT_JSON_PATH",
      "GOOGLE_SHEETS_ALLOWED_SPREADSHEET_IDS",
    ],
    tools: [
      {
        name: "list_spreadsheets",
        description:
          "List the Google Sheets spreadsheets configured in this connection allowlist.",
        inputSchema: { type: "object", properties: {} },
        annotations: { readOnlyHint: true },
      },
      {
        name: "get_spreadsheet_info",
        description:
          "Get spreadsheet metadata and sheet tab information for an allowlisted spreadsheet.",
        inputSchema: GOOGLE_SHEETS_SPREADSHEET_SCHEMA,
        annotations: { readOnlyHint: true },
      },
      {
        name: "read_values",
        description: "Read cell values from an allowlisted spreadsheet range.",
        inputSchema: GOOGLE_SHEETS_RANGE_SCHEMA,
        annotations: { readOnlyHint: true },
      },
      {
        name: "search_rows",
        description: "Search rows in an allowlisted spreadsheet range.",
        inputSchema: {
          type: "object",
          properties: {
            spreadsheetId: { type: "string", minLength: 1 },
            range: { type: "string", minLength: 1, maxLength: 500 },
            query: { type: "string", minLength: 1 },
            caseSensitive: { type: "boolean", default: false },
            maxResults: {
              type: "integer",
              minimum: 1,
              maximum: 500,
              default: 50,
            },
          },
          required: ["spreadsheetId", "range", "query"],
        },
        annotations: { readOnlyHint: true },
      },
      {
        name: "append_rows",
        description: "Append rows to an allowlisted spreadsheet range.",
        inputSchema: GOOGLE_SHEETS_WRITE_VALUES_SCHEMA,
        annotations: { readOnlyHint: false },
      },
      {
        name: "update_values",
        description: "Update values in an allowlisted spreadsheet range.",
        inputSchema: GOOGLE_SHEETS_WRITE_VALUES_SCHEMA,
        annotations: { readOnlyHint: false },
      },
      {
        name: "add_sheet_tab",
        description: "Add a sheet tab to an allowlisted spreadsheet.",
        inputSchema: {
          type: "object",
          properties: {
            spreadsheetId: { type: "string", minLength: 1 },
            title: { type: "string", minLength: 1, maxLength: 100 },
            rowCount: { type: "integer", minimum: 1, maximum: 1000000 },
            columnCount: { type: "integer", minimum: 1, maximum: 18278 },
          },
          required: ["spreadsheetId", "title"],
        },
        annotations: { readOnlyHint: false },
      },
      {
        name: "clear_values",
        description: "Clear values in an allowlisted spreadsheet range.",
        inputSchema: GOOGLE_SHEETS_RANGE_SCHEMA,
        annotations: { destructiveHint: true },
      },
      {
        name: "delete_rows",
        description: "Delete rows from an allowlisted spreadsheet tab.",
        inputSchema: {
          type: "object",
          properties: {
            spreadsheetId: { type: "string", minLength: 1 },
            sheetId: { type: "integer", minimum: 0 },
            startIndex: { type: "integer", minimum: 0 },
            endIndex: { type: "integer", minimum: 1 },
          },
          required: ["spreadsheetId", "sheetId", "startIndex", "endIndex"],
        },
        annotations: { destructiveHint: true },
      },
    ],
  },
};

const GOOGLE_SHEETS_GALLERY_KEY = "google-sheets";
const GOOGLE_SHEETS_TEMPLATE_ID = "paperclip.google-sheets";
const GOOGLE_SHEETS_ALLOWED_SPREADSHEET_IDS_ENV =
  "GOOGLE_SHEETS_ALLOWED_SPREADSHEET_IDS";

type ToolExampleDefinition = {
  id: string;
  title: string;
  description: string;
  applicationKey: string;
  applicationName: string;
  applicationDescription: string;
  connectionName: string;
  templateId: keyof typeof APPROVED_STDIO_TEMPLATES;
  profileKey: string;
  profileName: string;
  profileDescription: string;
};

const TOOL_EXAMPLES: ToolExampleDefinition[] = [
  {
    id: "safe-read-only-todo-kv",
    title: "Safe read-only Todo / KV fixture",
    description:
      "Installs a deterministic local MCP fixture and grants only its read-only catalog entries.",
    applicationKey: "paperclip.examples.safe-read-only-todo-kv",
    applicationName: "Paperclip example: Safe read-only Todo / KV",
    applicationDescription:
      "Deterministic MCP fixture for first-run tool governance checks.",
    connectionName: "Paperclip example: Safe read-only Todo / KV",
    templateId: "paperclip.synthetic-todo-kv",
    profileKey: "paperclip.examples.safe-read-only-todo-kv.profile",
    profileName: "Example safe read-only tools",
    profileDescription:
      "Allows only the read-only tools from the Paperclip Todo / KV example fixture.",
  },
];

function asRecord(value: unknown): Record<string, unknown> {
  if (value && typeof value === "object" && !Array.isArray(value))
    return value as Record<string, unknown>;
  return {};
}

export function googleSheetsRobotEmailFromEnv(
  env: NodeJS.ProcessEnv = process.env,
):
  | { available: true; robotEmail: string }
  | { available: false; reason: string } {
  const inlineOrPath = env.GOOGLE_SHEETS_SERVICE_ACCOUNT_JSON?.trim();
  const explicitPath = env.GOOGLE_SHEETS_SERVICE_ACCOUNT_JSON_PATH?.trim();
  if (!inlineOrPath && !explicitPath) {
    return {
      available: false,
      reason: "Google Sheets is not available on this instance yet.",
    };
  }

  try {
    const raw = explicitPath
      ? readFileSync(explicitPath, "utf8")
      : inlineOrPath!.startsWith("{")
        ? inlineOrPath!
        : readFileSync(inlineOrPath!, "utf8");
    const parsed = JSON.parse(raw) as { client_email?: unknown };
    if (typeof parsed.client_email === "string" && parsed.client_email.trim()) {
      return { available: true, robotEmail: parsed.client_email.trim() };
    }
  } catch {
    return {
      available: false,
      reason: "Google Sheets is not available on this instance yet.",
    };
  }
  return {
    available: false,
    reason: "Google Sheets is not available on this instance yet.",
  };
}

function googleSheetsAllowedSpreadsheetIds(
  configValues: Record<string, unknown> | undefined,
): string[] {
  const raw = configValues?.allowedSpreadsheetIds;
  const values = Array.isArray(raw)
    ? raw
    : typeof raw === "string"
      ? raw.split(/[\n,]/g)
      : [];
  return Array.from(
    new Set(values.map((value) => String(value).trim()).filter(Boolean)),
  );
}

function isGoogleSheetsConnectionConfig(
  configValues: Record<string, unknown> | undefined,
): boolean {
  return (
    configValues?.sourceTemplateKey === GOOGLE_SHEETS_GALLERY_KEY ||
    configValues?.templateId === GOOGLE_SHEETS_TEMPLATE_ID
  );
}

function normalizeGoogleSheetsConnectionConfig(
  configValues: Record<string, unknown>,
): Record<string, unknown> {
  if (!isGoogleSheetsConnectionConfig(configValues)) return configValues;
  const allowedSpreadsheetIds = googleSheetsAllowedSpreadsheetIds(configValues);
  if (allowedSpreadsheetIds.length === 0) {
    throw badRequest("Paste at least one Google Sheets link.");
  }
  return {
    ...configValues,
    allowedSpreadsheetIds,
    env: {
      ...asRecord(configValues.env),
      [GOOGLE_SHEETS_ALLOWED_SPREADSHEET_IDS_ENV]:
        allowedSpreadsheetIds.join(","),
    },
  };
}

// Detects a Postgres foreign_key_violation (SQLSTATE 23503) raised by the
// tool_connections.application_id constraint — i.e. an application delete that lost the race to
// a concurrently-created connection now that the FK is ON DELETE RESTRICT. Walks the error and
// its `cause` since the driver may wrap the original pg error.
function isToolConnectionForeignKeyViolation(error: unknown): boolean {
  const records: Record<string, unknown>[] = [];
  let current: unknown = error;
  for (
    let depth = 0;
    depth < 4 && current && typeof current === "object";
    depth += 1
  ) {
    const record = current as Record<string, unknown>;
    records.push(record);
    current = record.cause;
  }
  return records.some((record) => {
    const code = typeof record.code === "string" ? record.code : null;
    const constraint =
      typeof record.constraint === "string"
        ? record.constraint
        : typeof record.constraint_name === "string"
          ? record.constraint_name
          : null;
    const message = typeof record.message === "string" ? record.message : "";
    return (
      code === "23503" &&
      (constraint ===
        "tool_connections_application_id_tool_applications_id_fk" ||
        /tool_connections/.test(constraint ?? "") ||
        /tool_connections/.test(message))
    );
  });
}

function toCatalogEntryForConnection(
  row: typeof toolCatalogEntries.$inferSelect,
  connection: typeof toolConnections.$inferSelect,
): ToolCatalogEntry {
  const rawCatalogEntry = toCatalogEntry(row);
  const catalogEntry = {
    ...rawCatalogEntry,
    inputSchema: projectedConnectionToolInputSchema(
      connection,
      rawCatalogEntry.inputSchema ?? {},
      row.toolName,
    ),
    description: gmailArchiveToolDescription(
      connection,
      row.toolName,
      googleChatToolDescription(connection, row.toolName, rawCatalogEntry.description),
    ),
  };
  if (
    connection.transport === "local_stdio" &&
    asRecord(connection.config).templateId === GOOGLE_SHEETS_TEMPLATE_ID &&
    !schemaHasInputProperties(catalogEntry.inputSchema)
  ) {
    const templateTool = APPROVED_STDIO_TEMPLATES[
      GOOGLE_SHEETS_TEMPLATE_ID
    ].tools.find((tool) => tool.name === row.toolName);
    if (schemaHasInputProperties(templateTool?.inputSchema)) {
      return { ...catalogEntry, inputSchema: templateTool!.inputSchema! };
    }
  }
  return catalogEntry;
}

function builtInStdioTemplate(
  templateId: string,
): ToolStdioCommandTemplate | null {
  const template = APPROVED_STDIO_TEMPLATES[templateId];
  if (!template) return null;
  return {
    templateId,
    name: template.name,
    title: template.name,
    description: null,
    status: "active",
    source: "built_in",
    command: template.command ?? null,
    args: template.args ?? [],
    envKeys: template.envKeys ?? [],
    tools: template.tools.map((tool) => ({
      name: tool.name,
      title: tool.title ?? null,
      description: tool.description ?? null,
      inputSchema: tool.inputSchema ?? { type: "object", properties: {} },
      annotations: tool.annotations ?? {},
    })),
  };
}

function toStdioCommandTemplate(
  row: typeof toolStdioCommandTemplates.$inferSelect,
): ToolStdioCommandTemplate {
  return {
    id: row.id,
    companyId: row.companyId,
    templateId: row.templateKey,
    name: row.name,
    title: row.name,
    description: row.description,
    status: row.status,
    source: "admin",
    command: row.command,
    args: row.args ?? [],
    envKeys: row.envKeys ?? [],
    tools: (row.tools ?? [])
      .map((tool) => normalizeToolDescriptor(tool))
      .filter((tool): tool is McpToolDescriptor => Boolean(tool))
      .map((tool) => ({
        name: tool.name,
        title: tool.title ?? null,
        description: tool.description ?? null,
        inputSchema: tool.inputSchema ?? { type: "object", properties: {} },
        annotations: tool.annotations ?? {},
      })),
    createdByAgentId: row.createdByAgentId,
    createdByUserId: row.createdByUserId,
    disabledAt: row.disabledAt,
    createdAt: row.createdAt,
    updatedAt: row.updatedAt,
  };
}

function connectionSetupMutationFingerprint(
  row: typeof toolConnections.$inferSelect,
): string {
  return stableHash({
    name: row.name,
    transport: row.transport,
    status: row.status,
    enabled: row.enabled,
    agentInstructions: row.agentInstructions,
    config: row.config,
    transportConfig: row.transportConfig,
    credentialRefs: row.credentialRefs,
    credentialSecretRefs: row.credentialSecretRefs,
    credentialSource: row.credentialSource,
    externalCredential: row.externalCredential,
    credentialPolicy: row.credentialPolicy,
  });
}

function readStdioTemplateId(config: Record<string, unknown>): string {
  const templateId = config.templateId;
  if (typeof templateId !== "string" || templateId.trim().length === 0) {
    throw badRequest(
      "Local stdio MCP connections must use an approved templateId",
    );
  }
  return templateId.trim();
}

async function gitHubReadGrantAccess(db: Db, companyId: string, connectionId: string, userId: string | null, localTrusted: boolean) {
  const [connection] = await db.select().from(toolConnections).where(and(eq(toolConnections.companyId, companyId), eq(toolConnections.id, connectionId)));
  if (!connection || !connection.enabled || connection.status !== "active" || asRecord(connection.config).sourceTemplateKey !== "github") {
    throw forbidden("GitHub connection is unavailable. Choose a connection you can use.");
  }
  const [membership] = userId ? await db.select().from(companyMemberships).where(and(eq(companyMemberships.companyId, companyId), eq(companyMemberships.principalId, userId), eq(companyMemberships.principalType, "user"), eq(companyMemberships.status, "active"))) : [];
  if (!localTrusted && (!membership || membership.membershipRole === "viewer")) throw forbidden("GitHub access requires an active company member.");
  const grants = await db.select().from(connectionGrants).where(and(eq(connectionGrants.companyId, companyId), eq(connectionGrants.connectionId, connectionId)));
  const members = await db.select().from(connectionGrantMembers).where(eq(connectionGrantMembers.companyId, companyId));
  const candidates = grants.filter(grant => !(grant.kind === "organization" && ["per_user", "per_agent"].includes(connection.credentialPolicy)) && canBrowseProjectRepositoryGrant({
    grant, userId, activeMember: localTrusted || Boolean(membership), audience: members.filter(member => member.grantId === grant.id).map(member => member.subjectId),
  }));
  const allowed: typeof candidates = [];
  for (const grant of candidates) {
    const ref = grant.credentialSecretRefs.find(ref => ref.configPath === "oauth.access_token" || /authorization|token|api_key/i.test(ref.configPath));
    if (!ref) continue;
    try {
      await validateConnectionGrantSecretOwnership(db, connection, grant, ref);
      allowed.push(grant);
    } catch (error) {
      if (!(error instanceof HttpError && asRecord(error.details).code === "grant_credential_invalid")) throw error;
    }
  }
  const legacyShared = !grants.length && connection.credentialPolicy === "shared";
  if (!allowed.length && !legacyShared) throw forbidden("Choose a GitHub connection with an active authorization you can use.");
  return { connection, allowed, legacyShared };
}

export function toolAccessService(
  db: Db,
  options: ToolAccessServiceOptions = {},
) {
  const secrets = secretService(db);
  const remoteHttp = createToolRemoteHttp(options);
  const { allowPrivateRemoteEndpoints, assertRemoteHttpUrlAllowed, fetchRemoteHttpUrl, assertRemoteEndpointAllowed, assertRemoteConnectionEndpointsAllowed, requestRemoteHttpEndpoint } = remoteHttp;
  const { assertOAuthEndpointUrl, safeOAuthEndpointUrl } = createOAuthEndpointPolicy(allowPrivateRemoteEndpoints);
  const { oauthEndpointsForConnection, discoverOAuthEndpoints, preflightConnectionMetadata } = createOAuthDiscovery({
    fetchRemoteHttpUrl, assertRemoteEndpointAllowed, assertOAuthEndpointUrl, safeOAuthEndpointUrl,
  });
  const { requestOAuthClientRegistration, exchangeOAuthToken } = createOAuthClientProtocol({
    fetchRemoteHttpUrl, assertOAuthEndpointUrl,
  });
  const policySvc = toolAccessPolicyService(db);
  const now = options.now ?? (() => new Date());
  const assertSecretRefs = createConnectionCredentialValidation(db);
  const connectionInstalls = createConnectionInstalls(db, { now, getConnectionRow, assertOptionalAgent });
  const { resolveInstalledConnectionsForAgent, listConnectionInstalls } = connectionInstalls;
  const audit = createToolAccessAudit(db);
  const ensureDefaultOrganizationGrant = createOrganizationGrantStore(db);
  const { mintConnectionTokenForAgent, loadBrokerRunContext } = createConnectionTokenBroker(db, { now, secrets, policySvc, audit, getConnectionRow, ensureDefaultOrganizationGrant });
  const profileService = createToolProfileService(db, now);
  const profileDetails = profileService.getProfile;
  const profileResolver = createToolProfileResolver(db, { assertOptionalAgent, resolveInstalledConnectionsForAgent, toCatalogEntry });
  const configuredCloudConnector =
    options.paperclipCloudConnector ?? options.paperclipIdGmailConnector;
  const connectorWasProvided =
    options.paperclipCloudConnector !== undefined ||
    options.paperclipIdGmailConnector !== undefined;
  let cachedCloudConnector = configuredCloudConnector ?? null;
  const currentCloudConnector = (): PaperclipCloudConnector | null => {
    if (cachedCloudConnector || connectorWasProvided)
      return cachedCloudConnector;
    const config = paperclipCloudConnectorConfigFromEnv();
    cachedCloudConnector = config
      ? createPaperclipCloudConnector({ config, now: () => now().getTime() })
      : null;
    return cachedCloudConnector;
  };
  async function appForConnectionSetup(app: AppDefinition): Promise<AppDefinition> {
    if (!app.methods.some((method) => isPaperclipCloudConnectorStrategy(method.oauthStrategy))) {
      return app;
    }
    const profiles = connectorWasProvided
      ? (await currentCloudConnector()?.getCapabilities() ?? [])
      : await paperclipCloudConnectorCapabilitiesFromEnv();
    return appWithPaperclipCloudConnectorAvailability(app, profiles);
  }
  const vercelConnect =
    options.vercelConnectClient === undefined
      ? createVercelConnectClient()
      : options.vercelConnectClient;
  const runtimeSupervisor = createToolRuntimeSupervisor(db, options);
  const connectionGrantsService = createConnectionGrants(db, { getConnectionRow, assertSecretRefs, vercelConnect });
  const removeConnection = createConnectionRemoval(db, { options, secrets, runtimeSupervisor, vercelConnect, getConnectionRow });
  const credentialStore = createOAuthCredentialStore(db, secrets);
  const { syncCredentialBindings, annotateSavedOAuthClientSecret, oauthClientForConnection, createOrRotateOAuthSecret, getOAuthGrantRow, resolveOAuthGrantSecret } = credentialStore;
  const ensureOAuthClient = createOAuthClientRegistration(db, { now, options, store: credentialStore, getConnectionRow, requestOAuthClientRegistration });
  const refreshLeases = createOAuthRefreshLeases(db, now, getConnectionRow, getOAuthGrantRow);
  const maybeRefreshOAuthCredentials = createLegacyOAuthRefresh(db, { now, secrets, store: credentialStore, leases: refreshLeases, getConnectionRow, exchangeOAuthToken });
  const refreshOAuthGrantCredentials = createOAuthGrantRefresh(db, { now, store: credentialStore, leases: refreshLeases, currentCloudConnector, getConnectionRow, exchangeOAuthToken });
  const { refreshManagedGitHubGrantAccess, sweepGitHubConnectionContinuity } = createGitHubGrantContinuity(db, { now, currentCloudConnector, refreshOAuthGrantCredentials, resolveOAuthGrantSecret });
  const vercelCredentials = createVercelCredentialService(db, now, vercelConnect);
  const { resolveVercelCredentialHeaders, vercelGrantForConnection } = vercelCredentials;
  const credentialAccess = createConnectionCredentialAccess(db, { secrets, audit, vercel: vercelCredentials, resolveOAuthGrantSecret, maybeRefreshOAuthCredentials, refreshOAuthGrantCredentials });
  const { vaultGrantForConnection, resolveCredentialHeaders, resolvedRemoteEndpoint } = credentialAccess;
  const setupPolicy = createConnectionSetupPolicy(db);
  const { assertConnectorConnectionSetupEnabled, assertExperimentalConnectorSetupEnabled } = setupPolicy;
  const fixedPersonalIdentityForReconnect = createPersonalConnectionIdentity(db);
  const runtimeSlots = createToolRuntimeSlots(db, runtimeSupervisor);
  const { ensureRuntimeSlot } = runtimeSlots;
  const defaultCatalogAccess = createCatalogDefaultAccess(db);
  const { enableCatalogEntriesByDefault, upsertAskFirstPolicies } = defaultCatalogAccess;
  const catalogDiscovery = createToolCatalogDiscovery(db, { now, audit, secrets, credentials: credentialAccess, vercel: vercelCredentials, vercelConnect, setupPolicy, requestRemoteHttpEndpoint, resolveOAuthGrantSecret, discoverOAuthEndpoints, localTools });
  const connectionHealth = createConnectionHealth(db, { now, audit, getConnectionRow, discovery: catalogDiscovery, setupPolicy, resolveCredentialHeaders, refreshManagedGitHubGrantAccess, ensureRuntimeSlot, stdioTemplateId });
  const { updateConnectionHealth, checkConnectionHealth, sweepConnectionHealth } = connectionHealth;
  const refreshCatalog = createToolCatalogPublication(db, { now, audit, getConnectionRow, discoverTools: catalogDiscovery.discoverTools, assertConnectorConnectionSetupEnabled, updateConnectionHealth, vaultGrantForConnection, ensureRuntimeSlot, enableCatalogEntriesByDefault });
  const catalogReader = createToolCatalogReader(db, options, now, getConnectionRow, refreshCatalog, toCatalogEntryForConnection);
  const listAppsNeedingAttention = createToolAppAttention(db, now);
  const aggregatorAccounts = createAggregatorAccounts(db, { options, secrets, audit, credentials: credentialAccess, getConnectionRow, requestRemoteHttpEndpoint, remoteTools: catalogDiscovery.remoteTools });
  const oauthState = createOAuthStateStore(db);
  const { peekOAuthState } = oauthState;
  const finishOAuthCatalogWithRecommendedDefaults = createOAuthCatalogCompletion(db, finishGalleryAppConnection);
  const startOAuth = createOAuthAuthorizationStart(db, { now, getConnectionRow, setupPolicy, fixedPersonalIdentityForReconnect, currentCloudConnector, vercelConnect, ensureOAuthClient, oauthEndpointsForConnection, assertOAuthEndpointUrl });
  const completeOAuthCallback = createDirectOAuthCallback(db, { now, getConnectionRow, state: oauthState, store: credentialStore, setupPolicy, refreshCatalog, finishOAuthCatalogWithRecommendedDefaults, checkConnectionHealth, ensureDefaultOrganizationGrant, oauthEndpointsForConnection, exchangeOAuthToken });
  const completePaperclipCloudConnectorCallback = createCloudOAuthCallback(db, { now, getConnectionRow, state: oauthState, store: credentialStore, refreshCatalog, finishOAuthCatalogWithRecommendedDefaults, currentCloudConnector });
  const completeVercelConnectCallback = createVercelOAuthCallback(db, { now, getConnectionRow, state: oauthState, refreshCatalog, finishOAuthCatalogWithRecommendedDefaults, vercelConnect });
  const finalizeOAuthAccess = createOAuthAccessFinalization(db, { getConnectionRow, secrets, store: credentialStore, assertAgentsInCompany, finishGalleryAppConnection });
  const runtimeHealth = createToolRuntimeHealth(db, options, now, trustedRuntimeHost);
  const toolActivity = createToolActivityService(db, getConnectionRow);
  const toolActionReviewQueue = createToolActionReviewQueue(db);

  function trustedRuntimeHost() {
    return (
      options.trustedLocalStdioRuntimeHost ??
      process.env.PAPERCLIP_TRUSTED_MCP_RUNTIME_HOST ??
      process.env.PAPERCLIP_TOOL_RUNTIME_TRUSTED_HOST ??
      null
    );
  }

  function assertLocalStdioCanBeEnabled(
    transport: ToolConnectionTransport,
    enabled: boolean,
    config: Record<string, unknown> = {},
  ) {
    if (config.templateId === "paperclip.cognee-cloud") return;
    if (
      transport === "local_stdio" &&
      enabled &&
      options.deploymentMode === "authenticated" &&
      options.deploymentExposure === "public" &&
      !trustedRuntimeHost()
    ) {
      throw unprocessable(
        "Local stdio MCP connections cannot be enabled in authenticated public deployments without a trusted runtime host",
      );
    }
  }

  async function getAdminStdioTemplate(companyId: string, templateId: string) {
    return db
      .select()
      .from(toolStdioCommandTemplates)
      .where(
        and(
          eq(toolStdioCommandTemplates.companyId, companyId),
          eq(toolStdioCommandTemplates.templateKey, templateId),
        ),
      )
      .limit(1)
      .then((rows) => rows[0] ?? null);
  }

  async function resolveStdioTemplate(
    companyId: string,
    configOrTemplateId: Record<string, unknown> | string,
  ) {
    const templateId =
      typeof configOrTemplateId === "string"
        ? configOrTemplateId.trim()
        : readStdioTemplateId(configOrTemplateId);
    const builtIn = builtInStdioTemplate(templateId);
    if (builtIn) return builtIn;
    const adminTemplate = await getAdminStdioTemplate(companyId, templateId);
    if (!adminTemplate || adminTemplate.status !== "active") {
      throw badRequest(
        "Local stdio MCP connections must use an approved templateId",
      );
    }
    return toStdioCommandTemplate(adminTemplate);
  }

  async function stdioTemplateId(
    companyId: string,
    config: Record<string, unknown>,
  ): Promise<string> {
    return (await resolveStdioTemplate(companyId, config)).templateId;
  }

  async function assertApplication(companyId: string, applicationId: string) {
    const [row] = await db
      .select()
      .from(toolApplications)
      .where(
        and(
          eq(toolApplications.id, applicationId),
          eq(toolApplications.companyId, companyId),
        ),
      );
    if (!row) throw notFound("Tool application not found");
    return row;
  }

  async function assertOptionalAgent(
    companyId: string,
    agentId: string | null | undefined,
    label: string,
  ) {
    if (!agentId) return;
    const [row] = await db
      .select({ id: agents.id })
      .from(agents)
      .where(and(eq(agents.id, agentId), eq(agents.companyId, companyId)));
    if (!row) throw unprocessable(`${label} must belong to the same company`);
  }

  async function assertOptionalPlugin(pluginId: string | null | undefined) {
    if (!pluginId) return;
    const [row] = await db
      .select({ id: plugins.id })
      .from(plugins)
      .where(eq(plugins.id, pluginId));
    if (!row) throw unprocessable("Tool application plugin was not found");
  }

  async function assertGoogleSheetsSpreadsheetOwnership(
    companyId: string,
    config: Record<string, unknown>,
    options: { excludeConnectionId?: string } = {},
  ) {
    if (!isGoogleSheetsConnectionConfig(config)) return;
    const allowedSpreadsheetIds = googleSheetsAllowedSpreadsheetIds(config);
    if (allowedSpreadsheetIds.length === 0) return;
    const allowed = new Set(allowedSpreadsheetIds);
    const rows = await db
      .select({
        id: toolConnections.id,
        companyId: toolConnections.companyId,
        config: toolConnections.config,
      })
      .from(toolConnections)
      .where(ne(toolConnections.status, "archived"));

    const conflictingSpreadsheetIds = new Set<string>();
    for (const row of rows) {
      if (row.id === options.excludeConnectionId || row.companyId === companyId)
        continue;
      if (!isGoogleSheetsConnectionConfig(row.config)) continue;
      for (const spreadsheetId of googleSheetsAllowedSpreadsheetIds(
        row.config,
      )) {
        if (allowed.has(spreadsheetId))
          conflictingSpreadsheetIds.add(spreadsheetId);
      }
    }

    if (conflictingSpreadsheetIds.size > 0) {
      throw conflict(
        "Google Sheets spreadsheet is already connected to another company.",
        {
          code: "google_sheets_spreadsheet_already_bound",
          spreadsheetIds: Array.from(conflictingSpreadsheetIds).sort(),
        },
      );
    }
  }

  async function assertCatalogEntry(
    companyId: string,
    catalogEntryId: string | null | undefined,
  ) {
    if (!catalogEntryId) return;
    const [row] = await db
      .select({ id: toolCatalogEntries.id })
      .from(toolCatalogEntries)
      .where(
        and(
          eq(toolCatalogEntries.id, catalogEntryId),
          eq(toolCatalogEntries.companyId, companyId),
        ),
      );
    if (!row)
      throw unprocessable(
        "Tool profile catalog entry selector must belong to the same company",
      );
  }

  async function getConnectionRow(idOrUid: string, companyId?: string) {
    const identifier =
      /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(
        idOrUid,
      )
        ? eq(toolConnections.id, idOrUid)
        : eq(toolConnections.uid, idOrUid);
    const where = companyId
      ? and(identifier, eq(toolConnections.companyId, companyId))
      : identifier;
    const [row] = await db.select().from(toolConnections).where(where);
    if (!row) throw notFound("Tool connection not found");
    return row;
  }

  async function localTools(
    connection: typeof toolConnections.$inferSelect,
  ): Promise<McpToolDescriptor[]> {
    const template = await resolveStdioTemplate(
      connection.companyId,
      connection.config,
    );
    return template.tools.map((tool) => ({
      name: tool.name,
      title: tool.title ?? null,
      description: tool.description ?? null,
      inputSchema: tool.inputSchema ?? { type: "object", properties: {} },
      annotations: tool.annotations ?? {},
    }));
  }

  async function annotateAiGrantHealth(connections: ToolConnection[]) {
    const aiConnections = connections.filter(connection => connection.connectionPurpose === "ai");
    if (!aiConnections.length) return;
    const grants = await db.select({ connectionId: connectionGrants.connectionId, status: connectionGrants.status })
      .from(connectionGrants).where(and(eq(connectionGrants.companyId, aiConnections[0].companyId),
        inArray(connectionGrants.connectionId, aiConnections.map(connection => connection.id))));
    for (const connection of aiConnections) {
      const identities = grants.filter(grant => grant.connectionId === connection.id);
      if (identities.length && identities.every(grant => grant.status === "revoked")) {
        connection.healthStatus = "missing_secret";
        connection.healthMessage = "This credential was revoked. Reconnect the account to restore access.";
        connection.requiresReauthorization = true;
      }
    }
  }

  async function annotateGitHubAuthorization(
    connections: ToolConnection[],
    viewerUserId?: string,
  ) {
    const github = connections.filter(
      (connection) =>
        asRecord(connection.config).sourceTemplateKey === "github",
    );
    if (!github.length) return;
    const grants = await db
      .select({
        connectionId: connectionGrants.connectionId,
        status: connectionGrants.status,
        kind: connectionGrants.kind,
        subjectUserId: connectionGrants.subjectUserId,
      })
      .from(connectionGrants)
      .where(
        and(
          eq(connectionGrants.companyId, github[0].companyId),
          inArray(
            connectionGrants.connectionId,
            github.map((connection) => connection.id),
          ),
        ),
      );
    for (const connection of github) {
      const userId = viewerUserId ?? connection.createdByUserId;
      const eligible = grants.filter(
        (grant) =>
          grant.connectionId === connection.id &&
          (connection.credentialPolicy !== "per_user" ||
            (grant.kind === "user" && grant.subjectUserId === userId)),
      );
      connection.requiresReauthorization = !eligible.some(
        (grant) => grant.status === "active",
      );
    }
  }

  function findExample(exampleId: string): ToolExampleDefinition {
    const definition = TOOL_EXAMPLES.find(
      (example) => example.id === exampleId,
    );
    if (!definition) throw notFound("Tool example not found");
    return definition;
  }

  function localStdioInstallBlocker(): string | null {
    return options.deploymentMode === "authenticated" &&
      options.deploymentExposure === "public" &&
      !trustedRuntimeHost()
      ? "Local stdio examples require a trusted MCP runtime host in authenticated public deployments."
      : null;
  }

  function exampleToolSummaries(
    definition: ToolExampleDefinition,
  ): ToolExampleSummary["fixture"]["tools"] {
    return APPROVED_STDIO_TEMPLATES[definition.templateId].tools.map((tool) => {
      const riskLevel = classifyRisk(tool);
      return {
        name: tool.name,
        description: tool.description ?? null,
        riskLevel,
        readOnly: riskLevel === "read",
      };
    });
  }

  async function exampleRows(
    companyId: string,
    definition: ToolExampleDefinition,
  ) {
    const [application] = await db
      .select()
      .from(toolApplications)
      .where(
        and(
          eq(toolApplications.companyId, companyId),
          eq(toolApplications.applicationKey, definition.applicationKey),
        ),
      );
    const [connection] = await db
      .select()
      .from(toolConnections)
      .where(
        and(
          eq(toolConnections.companyId, companyId),
          eq(toolConnections.name, definition.connectionName),
        ),
      );
    const [profile] = await db
      .select()
      .from(toolProfiles)
      .where(
        and(
          eq(toolProfiles.companyId, companyId),
          eq(toolProfiles.profileKey, definition.profileKey),
        ),
      );
    const [profileBinding] = profile
      ? await db
          .select()
          .from(toolProfileBindings)
          .where(
            and(
              eq(toolProfileBindings.companyId, companyId),
              eq(toolProfileBindings.profileId, profile.id),
              eq(toolProfileBindings.targetType, "company"),
              eq(toolProfileBindings.targetId, companyId),
            ),
          )
      : [];
    const catalog = connection
      ? await db
          .select()
          .from(toolCatalogEntries)
          .where(
            and(
              eq(toolCatalogEntries.companyId, companyId),
              eq(toolCatalogEntries.connectionId, connection.id),
            ),
          )
          .orderBy(asc(toolCatalogEntries.toolName))
      : [];
    return {
      application: application ?? null,
      connection: connection ?? null,
      profile: profile ?? null,
      profileBinding: profileBinding ?? null,
      catalog,
    };
  }

  function exampleSummary(
    definition: ToolExampleDefinition,
    rows: Awaited<ReturnType<typeof exampleRows>>,
  ): ToolExampleSummary {
    const blocker = localStdioInstallBlocker();
    const tools = exampleToolSummaries(definition);
    const installed = Boolean(
      rows.application &&
      rows.connection &&
      rows.profile &&
      rows.profileBinding &&
      rows.connection.status !== "archived" &&
      rows.profile.status !== "archived",
    );
    return {
      id: definition.id,
      title: definition.title,
      description: definition.description,
      fixture: {
        transport: "local_stdio",
        templateId: definition.templateId,
        available: Boolean(APPROVED_STDIO_TEMPLATES[definition.templateId]),
        tools,
      },
      safeDefaultProfile: {
        profileKey: definition.profileKey,
        name: definition.profileName,
        defaultAction: "deny",
        allowedToolNames: tools
          .filter((tool) => tool.readOnly)
          .map((tool) => tool.name),
      },
      install: {
        installed,
        canInstall: !blocker,
        reason: blocker,
        applicationId: rows.application?.id ?? null,
        connectionId: rows.connection?.id ?? null,
        profileId: rows.profile?.id ?? null,
        profileBindingId: rows.profileBinding?.id ?? null,
      },
    };
  }

  async function upsertExampleApplication(
    companyId: string,
    definition: ToolExampleDefinition,
    existing: typeof toolApplications.$inferSelect | null,
  ) {
    const metadata = {
      ...(existing?.metadata ?? {}),
      source: "paperclip_example",
      exampleId: definition.id,
      safeDefault: true,
    };
    if (existing) {
      const [updated] = await db.transaction(async tx => {
        const [current] = await tx.select({ type: toolApplications.type }).from(toolApplications)
          .where(and(eq(toolApplications.id, existing.id), eq(toolApplications.companyId, companyId)))
          .for("no key update");
        if (current && current.type !== "mcp_stdio") await notifyToolConnectionHealth(tx, { companyId, applicationId: existing.id });
        return tx.update(toolApplications)
        .set({
          name: definition.applicationName,
          description: definition.applicationDescription,
          type: "mcp_stdio",
          status: "active",
          metadata,
          archivedAt: null,
          updatedAt: new Date(),
        })
        .where(eq(toolApplications.id, existing.id))
        .returning();
      });
      return { row: updated, created: false };
    }
    const [created] = await db
      .insert(toolApplications)
      .values({
        companyId,
        applicationKey: definition.applicationKey,
        name: definition.applicationName,
        description: definition.applicationDescription,
        type: "mcp_stdio",
        status: "active",
        metadata,
      })
      .returning();
    return { row: created, created: true };
  }

  async function upsertExampleConnection(
    companyId: string,
    definition: ToolExampleDefinition,
    applicationId: string,
    existing: typeof toolConnections.$inferSelect | null,
  ) {
    const config = {
      templateId: definition.templateId,
      exampleId: definition.id,
      safeDefault: true,
      quarantineNewEntries: true,
    };
    if (existing) {
      const updated = await writeToolConnectionHealthChange(db, existing, async tx => {
        const [updated] = await tx
          .update(toolConnections)
          .set({
            applicationId,
            name: definition.connectionName,
            transport: "local_stdio",
            status: "active",
            enabled: true,
            config,
            transportConfig: config,
            credentialRefs: [],
            credentialSecretRefs: [],
            updatedAt: new Date(),
          })
          .where(eq(toolConnections.id, existing.id))
          .returning();
        await ensureDefaultOrganizationGrant(updated, tx);
        await syncCredentialBindings(updated, [], tx);
        await createToolRuntimeSlots(tx, runtimeSupervisor).ensureRuntimeSlot(updated);
        return updated;
      });
      emitConnectionUpdated(updated, existing, "example");
      return { row: updated, created: false };
    }
    const connectionId = randomUUID();
    const created = await writeToolConnectionHealthChange(db, { companyId, id: connectionId }, async tx => {
      const [created] = await tx
        .insert(toolConnections)
        .values({
          id: connectionId,
          companyId,
          applicationId,
          name: definition.connectionName,
          uid: connectionUid(
            "paperclip",
            definition.connectionName,
            connectionId,
          ),
          connectionKind: "managed",
          transport: "local_stdio",
          status: "active",
          enabled: true,
          config,
          transportConfig: config,
          credentialRefs: [],
          credentialSecretRefs: [],
        })
        .returning();
      await ensureDefaultOrganizationGrant(created, tx);
      await syncCredentialBindings(created, [], tx);
      await createToolRuntimeSlots(tx, runtimeSupervisor).ensureRuntimeSlot(created);
      return created;
    });
    emitConnectionCreated(created, "example");
    return { row: created, created: true };
  }

  async function upsertExampleProfile(
    companyId: string,
    definition: ToolExampleDefinition,
    existing: typeof toolProfiles.$inferSelect | null,
  ) {
    const metadata = {
      ...(existing?.metadata ?? {}),
      source: "paperclip_example",
      exampleId: definition.id,
      safeDefault: true,
    };
    if (existing) {
      const [updated] = await db
        .update(toolProfiles)
        .set({
          name: definition.profileName,
          description: definition.profileDescription,
          status: "active",
          defaultAction: "deny",
          metadata,
          updatedAt: new Date(),
        })
        .where(eq(toolProfiles.id, existing.id))
        .returning();
      return { row: updated, created: false };
    }
    const [created] = await db
      .insert(toolProfiles)
      .values({
        companyId,
        profileKey: definition.profileKey,
        name: definition.profileName,
        description: definition.profileDescription,
        status: "active",
        defaultAction: "deny",
        metadata,
      })
      .returning();
    return { row: created, created: true };
  }

  async function syncExampleProfileEntries(
    companyId: string,
    profileId: string,
    catalog: ToolCatalogEntry[],
  ): Promise<ToolProfileEntry[]> {
    await db
      .delete(toolProfileEntries)
      .where(
        and(
          eq(toolProfileEntries.companyId, companyId),
          eq(toolProfileEntries.profileId, profileId),
        ),
      );
    const readEntries = catalog.filter(
      (entry) => entry.riskLevel === "read" && entry.status === "active",
    );
    if (readEntries.length === 0) return [];
    const rows = await db
      .insert(toolProfileEntries)
      .values(
        readEntries.map((entry) => ({
          companyId,
          profileId,
          selectorType: "catalog_entry" as const,
          effect: "include" as const,
          applicationId: entry.applicationId,
          connectionId: entry.connectionId,
          catalogEntryId: entry.id,
          toolName: entry.toolName,
          riskLevel: entry.riskLevel,
          conditions: { source: "paperclip_example" },
        })),
      )
      .returning();
    return rows.map(toProfileEntry);
  }

  async function upsertExampleProfileBinding(
    companyId: string,
    profileId: string,
    existing: typeof toolProfileBindings.$inferSelect | null,
    actor?: ActorInfo,
  ): Promise<ToolProfileBinding> {
    const metadata = {
      ...(existing?.metadata ?? {}),
      source: "paperclip_example",
      safeDefault: true,
    };
    if (existing) {
      const [updated] = await db
        .update(toolProfileBindings)
        .set({ priority: 100, metadata, updatedAt: new Date() })
        .where(eq(toolProfileBindings.id, existing.id))
        .returning();
      return toProfileBinding(updated);
    }
    const [created] = await db
      .insert(toolProfileBindings)
      .values({
        companyId,
        profileId,
        targetType: "company",
        targetId: companyId,
        priority: 100,
        metadata,
        createdByAgentId:
          actor?.actorType === "agent" ? (actor.actorId ?? null) : null,
        createdByUserId:
          connectionActorUserId(actor),
      })
      .returning();
    return toProfileBinding(created);
  }

  async function exampleSmokeActor(companyId: string, actor?: ActorInfo) {
    const [agent] = await db
      .select({ id: agents.id })
      .from(agents)
      .where(eq(agents.companyId, companyId))
      .limit(1);
    if (agent) {
      return {
        actorType: "agent" as const,
        actorId: agent.id,
        agentId: agent.id,
      };
    }
    const actorType =
      actor?.actorType === "user" ? ("user" as const) : ("system" as const);
    return {
      actorType,
      actorId: actor?.actorId ?? "example-smoke",
      agentId: null,
    };
  }

  function sampleArguments(toolName: string): Record<string, unknown> {
    if (toolName === "get_value") return { key: "project" };
    if (toolName === "set_value") return { key: "project", value: "paperclip" };
    if (toolName === "create_item") return { title: "Smoke test item" };
    if (toolName === "mark_done" || toolName === "delete_item")
      return { id: "todo-1" };
    return {};
  }

  async function runSmokeDecisionCheck(input: {
    companyId: string;
    actor: Awaited<ReturnType<typeof exampleSmokeActor>>;
    connection: ToolConnection;
    catalogEntry: ToolCatalogEntry;
    expectedDecision: ToolPolicyDecision;
    name: string;
  }): Promise<ToolExampleSmokeCheck> {
    const decisionInput = {
      companyId: input.companyId,
      actor: input.actor,
      request: {
        applicationId: input.connection.applicationId,
        connectionId: input.connection.id,
        catalogEntryId: input.catalogEntry.id,
        toolName: input.catalogEntry.toolName,
        arguments: sampleArguments(input.catalogEntry.toolName),
      },
    };
    const decision = await policySvc.decide(decisionInput);
    const auditResult = await policySvc.writeAudit(
      decisionInput,
      decision,
      "policy_decision",
    );
    return {
      name: input.name,
      ok: decision.decision === input.expectedDecision,
      toolName: input.catalogEntry.toolName,
      expectedDecision: input.expectedDecision,
      decision: decision.decision,
      reasonCode: decision.reasonCode,
      explanation: decision.explanation,
      auditEventId: auditResult.legacyAuditEvent.id,
      toolCallEventId: auditResult.toolCallEvent.id,
    };
  }

  function defaultLinkName(link: string): string {
    try {
      const url = new URL(link);
      const host = url.host.replace(/^www\./, "");
      const path = url.pathname === "/" ? "" : url.pathname.replace(/\/+$/, "");
      return `${host}${path}`.slice(0, 160) || "MCP app";
    } catch {
      return "MCP app";
    }
  }

  function linkCredentialFields(credentialValues: Record<string, string>) {
    const fields: Array<{
      label: string;
      configPath: string;
      required: boolean;
      placement: "header";
      key: string;
      prefix: string | null;
    }> = [];
    if (credentialValues["credentials.authorization"]?.trim()) {
      fields.push({
        label: "App key",
        configPath: "credentials.authorization",
        required: false,
        placement: "header",
        key: "Authorization",
        prefix: "Bearer ",
      });
    }
    for (const configPath of Object.keys(credentialValues).sort()) {
      if (!configPath.startsWith("headers.")) continue;
      const headerName = mcpRemoteHeaderNameFromConfigPath(configPath);
      if (!headerName)
        throw badRequest("Header names cannot be blank.", {
          code: "mcp_header_rejected",
        });
      // The API schema already rejected unsafe headers, but this is the last
      // point before a name becomes a real outbound request header — and the
      // normalized paste-config path lands here too — so re-check rather than
      // trust the caller.
      const nameCheck = checkMcpRemoteHeaderName(headerName);
      if (!nameCheck.ok) {
        throw badRequest(
          mcpRemoteHeaderRejectionMessage(headerName, nameCheck.reason!),
          {
            code: "mcp_header_rejected",
            headerName,
          },
        );
      }
      const valueCheck = checkMcpRemoteHeaderValue(
        credentialValues[configPath] ?? "",
      );
      if (!valueCheck.ok) {
        throw badRequest(
          mcpRemoteHeaderRejectionMessage(headerName, valueCheck.reason!),
          {
            code: "mcp_header_rejected",
            headerName,
          },
        );
      }
      fields.push({
        label: headerName,
        configPath,
        required: true,
        placement: "header",
        key: headerName,
        prefix: null,
      });
    }
    return fields;
  }

  function nextAvailableConnectionName(
    requestedName: string,
    existingNames: readonly string[],
  ): string {
    const base = requestedName.trim() || "Custom app";
    const used = new Set(
      existingNames.map((candidate) => candidate.trim().toLocaleLowerCase()),
    );
    const unsuffixed = base.slice(0, 160);
    if (!used.has(unsuffixed.toLocaleLowerCase())) return unsuffixed;
    for (let index = 2; index < 10_000; index += 1) {
      const suffix = ` (${index})`;
      const candidate = `${base.slice(0, 160 - suffix.length).trimEnd()}${suffix}`;
      if (!used.has(candidate.toLocaleLowerCase())) return candidate;
    }
    return `${base.slice(0, 151).trimEnd()} (${randomUUID().slice(0, 6)})`;
  }

  async function connectGalleryApp(
    companyId: string,
    input: ConnectToolApp,
    actor?: ActorInfo,
  ): Promise<ConnectToolAppResult> {
    await actor?.managementContext?.reauthorize();
    const definition = input.galleryKey
      ? getConnectableAppDefinition(input.galleryKey)
      : null;
    if (input.galleryKey && !definition)
      throw notFound("Tool app gallery entry not found");

    const galleryEntry = definition ? await appForConnectionSetup(definition) : null;

    let existingApplication: typeof toolApplications.$inferSelect | null = null;
    let requestedResumeConnection: typeof toolConnections.$inferSelect | null =
      null;
    const requestedConnectionId =
      input.resumeConnectionId ?? input.reconnectConnectionId;
    if (requestedConnectionId) {
      const [connection] = await db
        .select()
        .from(toolConnections)
        .where(
          and(
            eq(toolConnections.id, requestedConnectionId),
            eq(toolConnections.companyId, companyId),
          ),
        );
      if (!connection) throw notFound("Incomplete app connection not found");
      assertSupportedConnection(connection);
      if (input.resumeConnectionId && connection.status !== "draft") {
        throw conflict("Only an incomplete app connection can resume setup", {
          code: "connection_setup_not_incomplete",
        });
      }
      if (
        input.applicationId &&
        input.applicationId !== connection.applicationId
      ) {
        throw badRequest("The app and draft connection do not match");
      }
      const [application] = await db
        .select()
        .from(toolApplications)
        .where(
          and(
            eq(toolApplications.id, connection.applicationId),
            eq(toolApplications.companyId, companyId),
          ),
        );
      if (!application) throw notFound("App not found");
      const source =
        asRecord(connection.config).sourceTemplateKey ??
        asRecord(connection.transportConfig).sourceTemplateKey ??
        asRecord(application.metadata).sourceTemplateKey ??
        asRecord(application.metadata).source;
      if (
        input.reconnectConnectionId &&
        ((galleryEntry && source !== galleryEntry.slug) ||
          (!galleryEntry &&
            typeof source === "string" &&
            getConnectableAppDefinition(source)))
      ) {
        throw badRequest("Reconnect must preserve the configured provider");
      }
      requestedResumeConnection = connection;
      existingApplication = application;
    } else if (input.applicationId) {
      const [row] = await db
        .select()
        .from(toolApplications)
        .where(
          and(
            eq(toolApplications.id, input.applicationId),
            eq(toolApplications.companyId, companyId),
          ),
        );
      if (!row) throw notFound("App not found");
      existingApplication = row;
    } else {
      // Removal and interrupted setup intentionally retain their
      // application/connection rows. A fresh gallery click has no
      // applicationId, so recover that retained identity by its company-unique
      // name and source instead of inserting a duplicate application that the
      // unique index rejects. Active applications are excluded: connecting a
      // second account still requires its own name/application identity.
      const requestedName =
        input.name ?? galleryEntry?.name ?? defaultLinkName(input.link ?? "");
      const recoverableApplicationStatuses = galleryEntry
        ? (["draft", "archived"] as const)
        : (["archived"] as const);
      const [recoverableApplication] = await db
        .select()
        .from(toolApplications)
        .where(
          and(
            eq(toolApplications.companyId, companyId),
            eq(toolApplications.name, requestedName),
            inArray(toolApplications.status, recoverableApplicationStatuses),
          ),
        )
        .orderBy(desc(toolApplications.updatedAt))
        .limit(1);
      const recoverableSource = recoverableApplication?.metadata
        ? (recoverableApplication.metadata.sourceTemplateKey ??
          recoverableApplication.metadata.galleryKey ??
          recoverableApplication.metadata.source)
        : null;
      const requestedSource =
        galleryEntry?.slug ?? (input.link ? "link" : null);
      if (
        recoverableApplication &&
        requestedSource &&
        recoverableSource === requestedSource
      ) {
        existingApplication = recoverableApplication;
      }
    }

    await assertConnectorConnectionSetupEnabled(requestedResumeConnection ?? {}, existingApplication?.applicationKey);
    const requestedName =
      input.name ??
      existingApplication?.name ??
      galleryEntry?.name ??
      defaultLinkName(input.link ?? "");
    // Compatibility for the original Sheets robot flow, whose clients predate
    // method selection and identify the method by its spreadsheet allowlist.
    const inferredMethodKey =
      !input.connectionMethodKey &&
      galleryEntry?.slug === "google-sheets" &&
      Array.isArray(input.configValues?.allowedSpreadsheetIds)
        ? "local"
        : input.connectionMethodKey;
    if (!galleryEntry && input.connectionMethodKey)
      throw badRequest("Connection method selection requires a gallery app");
    if (
      galleryEntry &&
      getAvailableConnectionMethods(galleryEntry).filter(
        (candidate) =>
          candidate.purpose !== "channel" && candidate.purpose !== "ai"
          && candidate.transport !== "chat_sdk" && candidate.transport !== "runtime_auth",
      ).length > 1 &&
      !inferredMethodKey
    ) {
      throw badRequest("Choose a connection method for this app");
    }
    const method = galleryEntry
      ? connectionMethodFor(galleryEntry, inferredMethodKey)
      : null;
    const remoteMcpConnector = isRemoteMcpConnectorMethod(galleryEntry?.slug, method?.key);
    await assertExperimentalConnectorSetupEnabled(galleryEntry?.slug, Boolean(
      input.reconnectConnectionId && requestedResumeConnection?.status !== "draft"
      && requestedResumeConnection?.config.sourceTemplateKey === galleryEntry?.slug,
    ));
    if (galleryEntry && input.link) {
      const acceptsProviderGeneratedUrl =
        method?.transport === "mcp_remote" &&
        method.auth === "none" &&
        !method.defaults?.serverUrl &&
        !method.defaults?.serverUrlTemplate;
      if (!acceptsProviderGeneratedUrl && !remoteMcpConnector) {
        throw badRequest(
          `${galleryEntry.name} does not accept a provider-generated connection URL`,
        );
      }
      if (!(remoteMcpConnector && galleryEntry.slug === "executor") && !getAppDefinitionForUrl(input.link, [galleryEntry])) {
        throw badRequest(
          `That connection URL does not belong to ${galleryEntry.name}`,
        );
      }
    }
    if (requestedResumeConnection && galleryEntry) {
      const storedConnectionSource =
        requestedResumeConnection.config?.sourceTemplateKey ??
        requestedResumeConnection.transportConfig?.sourceTemplateKey;
      const storedApplicationSource =
        existingApplication?.metadata?.sourceTemplateKey ??
        existingApplication?.metadata?.galleryKey;
      if (
        storedConnectionSource !== galleryEntry.slug &&
        storedApplicationSource !== galleryEntry.slug
      ) {
        throw badRequest(
          "The selected provider does not match this incomplete connection",
        );
      }
    }
    // Reconnect is not a second identity decision. Removed connections retain
    // their row precisely so the next credential can be attached to the same
    // identity and history. Resolve that retained row before interpreting the
    // request so a client default cannot silently turn a personal connection
    // into an organization connection (or vice versa).
    const canResumeInterruptedDraft =
      Boolean(requestedResumeConnection) ||
      (!input.applicationId &&
        Boolean(galleryEntry) &&
        existingApplication?.status === "draft");
    const retainedConnectionStatuses = canResumeInterruptedDraft
      ? (["draft", "archived"] as const)
      : (["archived"] as const);
    const [recoveredConnection] =
      !requestedResumeConnection && existingApplication
        ? await db
            .select()
            .from(toolConnections)
            .where(
              and(
                eq(toolConnections.companyId, companyId),
                eq(toolConnections.applicationId, existingApplication.id),
                inArray(toolConnections.status, retainedConnectionStatuses),
              ),
            )
            .orderBy(desc(toolConnections.updatedAt))
            .limit(1)
        : [undefined];
    let retainedConnection = requestedResumeConnection ?? recoveredConnection;
    const transport = method?.transport ?? "mcp_remote";
    const applicationType = transport === "rest_api" ? "rest_api"
      : transport === "mcp_remote" ? "mcp_http"
        : transport === "local_stdio" ? "mcp_stdio" : null;
    if ((retainedConnection && retainedConnection.transport !== transport)
      || (existingApplication && applicationType && existingApplication.type !== applicationType)) {
      if (requestedResumeConnection || input.applicationId) {
        throw conflict("Create a separate app connection to change its connection method transport.", {
          code: "connection_transport_change_not_supported",
        });
      }
      // A new gallery connection may use another transport for the same app.
      // Do not revive an archived MCP identity as REST (or the reverse): the
      // application's type and any sibling connections belong to that identity.
      retainedConnection = undefined;
      existingApplication = null;
    }
    let applicationName = existingApplication?.name ?? requestedName;
    let name = retainedConnection?.name ?? requestedName;
    if (!existingApplication) {
      const applicationNames = await db
        .select({ name: toolApplications.name })
        .from(toolApplications)
        .where(eq(toolApplications.companyId, companyId));
      applicationName = nextAvailableConnectionName(
        requestedName,
        applicationNames.map((row) => row.name),
      );
      name = applicationName;
    } else if (!retainedConnection) {
      const connectionNames = await db
        .select({ name: toolConnections.name })
        .from(toolConnections)
        .where(
          and(
            eq(toolConnections.companyId, companyId),
            eq(toolConnections.applicationId, existingApplication.id),
          ),
        );
      name = nextAvailableConnectionName(
        requestedName,
        connectionNames.map((row) => row.name),
      );
    }
    const previousGrantKind: ConnectionGrantKind | null = retainedConnection
      ? retainedConnection.credentialPolicy === "per_user"
        ? "user"
        : retainedConnection.credentialPolicy === "per_agent"
          ? "agent"
          : "organization"
      : null;
    // An explicit resume/application reconnect continues the retained identity.
    // A fresh gallery connect may still reuse an archived row for stable history
    // and company-unique naming, but an explicit Access choice is a new identity
    // decision and must replace the archived policy. Without this distinction,
    // removing a dedicated-agent connection and reconnecting the default personal
    // account leaves `per_agent` behind and the OAuth callback cannot persist its
    // user grant.
    const retainsIdentity = Boolean(
      retainedConnection &&
      (retainedConnection.status === "draft" ||
        requestedResumeConnection ||
        input.applicationId),
    );
    const retainedGrantKind = retainsIdentity ? previousGrantKind : null;
    // The route can authorize an explicit resume before entering the service,
    // but name/source recovery happens here. Do not let a caller submit a
    // personal grant choice to pass the route and then inherit an implicitly
    // recovered organization identity. Local implicit mode is already the
    // unrestricted instance operator; every authenticated user must still hold
    // current connection-manager authority before this retained row is touched.
    if (
      previousGrantKind &&
      input.grantKind &&
      previousGrantKind !== input.grantKind &&
      Boolean(connectionActorUserId(actor)) &&
      actor?.actorSource !== "local_implicit"
    ) {
      const actorUserId = connectionActorUserId(actor);
      const [membership] = actorUserId
        ? await db
            .select({
              membershipRole: companyMemberships.membershipRole,
            })
            .from(companyMemberships)
            .where(
              and(
                eq(companyMemberships.companyId, companyId),
                eq(companyMemberships.principalType, "user"),
                eq(companyMemberships.principalId, actorUserId),
                eq(companyMemberships.status, "active"),
              ),
            )
            .limit(1)
        : [];
      const roleCanManage =
        membership?.membershipRole === "owner" ||
        membership?.membershipRole === "admin";
      const [explicitManagerGrant] =
        roleCanManage || !actorUserId
          ? []
          : await db
              .select({
                id: principalPermissionGrants.id,
              })
              .from(principalPermissionGrants)
              .where(
                and(
                  eq(principalPermissionGrants.companyId, companyId),
                  eq(principalPermissionGrants.principalType, "user"),
                  eq(principalPermissionGrants.principalId, actorUserId),
                  eq(
                    principalPermissionGrants.permissionKey,
                    "tools:manage_connections",
                  ),
                ),
              )
              .limit(1);
      if (!roleCanManage && !explicitManagerGrant) {
        throw forbidden(
          "Only a company owner, admin, or member with connection-manager permission can change this connection's credential identity.",
        );
      }
    }
    const requestedGrantKind =
      retainedGrantKind ?? input.grantKind ?? (method?.grantKinds?.length === 1 ? method.grantKinds[0]! : "organization");
    if (method?.grantKinds && !method.grantKinds.includes(requestedGrantKind)) {
      throw badRequest(
        `${galleryEntry?.name ?? "This app"} supports only ${method.grantKinds.join(" or ")} credentials`,
      );
    }
    const dedicatedAgentId =
      requestedGrantKind === "agent" ? (input.subjectAgentId ?? null) : null;
    if (dedicatedAgentId) {
      const [subjectAgent] = await db
        .select({ id: agents.id })
        .from(agents)
        .where(
          and(eq(agents.id, dedicatedAgentId), eq(agents.companyId, companyId)),
        )
        .limit(1);
      if (!subjectAgent)
        throw badRequest(
          "Dedicated GitHub identity requires an agent in this company",
        );
    }
    const credentialSource: ToolConnectionCredentialSource =
      input.credentialSource ?? "paperclip_vault";
    if (
      retainedConnection &&
      retainedConnection.credentialSource !== credentialSource
    ) {
      throw conflict(
        "Changing credential source requires a new app connection",
        {
          code: "credential_source_migration_not_supported",
        },
      );
    }
    let externalCredential: VercelConnectCredentialReference | null = null;
    if (credentialSource === "vercel_connect") {
      const integration = vercelConnectIntegrationStatus();
      if (!integration.enabled || !integration.configured || !vercelConnect) {
        throw unprocessable(
          "Vercel Connect setup is not available on this Paperclip instance",
          {
            code: "vercel_connect_unavailable",
          },
        );
      }
      if (
        !galleryEntry ||
        !method ||
        method.transport !== "mcp_remote" ||
        method.auth === "none"
      ) {
        throw badRequest(
          "Vercel Connect is available only for reviewed remote MCP app methods",
        );
      }
      const reviewed = method.credentialSources?.vercelConnect;
      if (!reviewed) {
        throw unprocessable(
          `${galleryEntry.name} has not been reviewed for Vercel Connect`,
          {
            code: "vercel_connect_method_not_reviewed",
          },
        );
      }
      const expectedPrincipalMode = method.auth === "oauth" ? "user" : "app";
      if (!reviewed.principalModes.includes(expectedPrincipalMode)) {
        throw unprocessable(
          "This connector principal mode has not been reviewed for this app",
          {
            code: "vercel_connect_principal_not_reviewed",
          },
        );
      }
      if (
        expectedPrincipalMode === "app" &&
        requestedGrantKind !== "organization"
      ) {
        throw badRequest(
          "App-subject Vercel connectors can only back an organization identity",
        );
      }
      let metadata;
      try {
        metadata = await vercelConnect.getConnectorMetadata(
          input.vercelConnect!.connector,
        );
      } catch (error) {
        throw vercelConnectHttpError(error);
      }
      const service = metadata.service.trim().toLowerCase();
      if (
        !reviewed.services.map((value) => value.toLowerCase()).includes(service)
      ) {
        throw badRequest(
          `That Vercel connector is for ${metadata.service}, not ${galleryEntry.name}`,
          {
            code: "vercel_connect_service_mismatch",
          },
        );
      }
      if (expectedPrincipalMode === "app") {
        const [connectorInUse] = await db
          .select({ id: toolConnections.id })
          .from(toolConnections)
          .where(
            and(
              eq(toolConnections.credentialSource, "vercel_connect"),
              ne(toolConnections.status, "archived"),
              sql`${toolConnections.externalCredential}->>'connectorUid' = ${metadata.uid}`,
              ...(retainedConnection
                ? [ne(toolConnections.id, retainedConnection.id)]
                : []),
            ),
          )
          .limit(1);
        if (connectorInUse) {
          throw conflict(
            "App-subject Vercel connectors are dedicated to one Paperclip connection. Create or attach a separate connector in Vercel.",
            {
              code: "vercel_connect_app_connector_in_use",
            },
          );
        }
      }
      externalCredential = {
        provider: "vercel_connect",
        connectorId: metadata.id,
        connectorUid: metadata.uid,
        service: metadata.service,
        connectorType: metadata.type,
        principalMode: expectedPrincipalMode,
        headerName: reviewed.header.name,
        headerPrefix: reviewed.header.prefix ?? null,
        scopes: [...reviewed.scopes],
      };
    }
    const isGoogleSheetsRobotMethod =
      galleryEntry?.slug === GOOGLE_SHEETS_GALLERY_KEY &&
      method?.key === "local";
    const normalizedMethodConfig =
      isGoogleSheetsRobotMethod || !method
        ? null
        : normalizeConnectionMethodConfig(method, input.configValues ?? asRecord(asRecord(retainedConnection?.config).methodConfig));
    const remoteUrlCredential =
      transport === "mcp_remote" && input.link
        ? splitRemoteUrlCredential(input.link)
        : null;
    const baseConfig =
      (transport === "mcp_remote" || transport === "rest_api")
        ? {
            url:
              (remoteMcpConnector ? remoteUrlCredential?.publicUrl : undefined) ??
              normalizedMethodConfig?.url ??
              method?.defaults?.serverUrl ??
              remoteUrlCredential?.publicUrl ??
              input.link ??
              "",
          }
        : { templateId: method?.defaults?.templateKey };
    let config: Record<string, unknown> = galleryEntry
      ? {
          ...baseConfig,
          sourceTemplateKey: galleryEntry.slug,
          connectionMethodKey: method?.key,
          methodConfig: normalizedMethodConfig?.values ?? {},
          ...(galleryEntry.slug === "google-workspace" && retainedConnection?.status === "draft"
            ? { workspaceSetup: retainedConnection.config.workspaceSetup }
            : {}),
          ...(method?.defaults?.mcpSessionRequired === true
            ? { mcpSessionRequired: true }
            : {}),
          // Grant-backed setup keeps the full discovered catalog selectable;
          // the wizard projects the app's action defaults into policies at
          // finish time instead of using catalog quarantine as access state.
          quarantineNewEntries: connectorToolPolicy(galleryEntry.slug).quarantineNewEntries,
          ...(remoteMcpConnector ? {
            mcpSessionRequired: true,
            mcpAuthMode: input.authMode ?? "auto",
            mcpPreserveAccess: Boolean(retainedConnection && (retainedConnection.status === "active" || asRecord(retainedConnection.config).mcpPreserveAccess === true)),
          } : {}),
          ...(galleryEntry.slug === "posthog" ? { safeDefault: true } : {}),
          // Telem.AI attributes each search to the Paperclip company, agent,
          // run and issue, so its catalog connection forwards those context
          // headers by default (the gateway still drops empty values). A
          // reconnect keeps the policy the operator saved on the connection.
          ...(galleryEntry.slug === "telem"
            ? {
                headerPolicy: asRecord(retainedConnection?.config).headerPolicy ?? {
                  metadata: {
                    forward: ["company_id", "issue_id", "agent_id", "run_id", "project_id", "correlation_id"],
                  },
                },
              }
            : {}),
        }
      : { ...baseConfig, quarantineNewEntries: false, unverifiedServer: true };
    if (method && isPaperclipCloudConnectorStrategy(method.oauthStrategy)) {
      const connectorProfile = method.connectorProfile;
      const profile = managedConnectorProfile(connectorProfile);
      if (!profile)
        throw badRequest("This app has an invalid managed connector profile");
      config.oauth = {
        strategy: method.oauthStrategy,
        provider: profile.provider,
        connectorProfile: profile.id,
        resource: method.defaults?.serverUrl,
        scopes: [...profile.scopes],
      };
      config.quarantineNewEntries = true;
    }
    const acceptsCustomerOAuthClient =
      remoteMcpConnector || (method?.auth === "oauth" && method.ownershipModes.includes("customer"));
    if (galleryEntry && input.oauthClient && !acceptsCustomerOAuthClient) {
      throw badRequest(
        `${galleryEntry.name} does not accept customer-owned OAuth client credentials`,
      );
    }
    // A pasted URL or an explicitly customer-owned curated method may arrive
    // with a client the operator preregistered in the provider's console. Record
    // the client id now; the secret becomes an encrypted Paperclip secret below.
    if (input.oauthClient) {
      config.oauth = {
        clientId: input.oauthClient.clientId.trim(),
        clientRegistrationSource:
          "manual" satisfies OAuthClientRegistrationSource,
        clientCompanyId: companyId,
      };
    }
    if (isGoogleSheetsRobotMethod) {
      const availability = googleSheetsRobotEmailFromEnv();
      if (!availability.available) {
        throw unprocessable(availability.reason, {
          code: "google_sheets_unavailable",
        });
      }
      const allowedSpreadsheetIds = googleSheetsAllowedSpreadsheetIds(
        input.configValues,
      );
      if (allowedSpreadsheetIds.length === 0) {
        throw badRequest("Paste at least one Google Sheets link.");
      }
      config.allowedSpreadsheetIds = allowedSpreadsheetIds;
      config.robotEmail = availability.robotEmail;
      config.env = {
        [GOOGLE_SHEETS_ALLOWED_SPREADSHEET_IDS_ENV]:
          allowedSpreadsheetIds.join(","),
      };
      config = normalizeGoogleSheetsConnectionConfig(config);
      await assertGoogleSheetsSpreadsheetOwnership(companyId, config);
    }
    if (transport === "mcp_remote")
      await assertRemoteConnectionEndpointsAllowed(config);
    if (transport === "local_stdio") await stdioTemplateId(companyId, config);
    assertLocalStdioCanBeEnabled(transport, false);

    const credentialValues = input.credentialValues ?? {};
    // A curated method declares its auth kind. A pasted URL declares one only
    // under Advanced authentication; on the simple path it starts from what the
    // operator supplied and is upgraded to `oauth` when discovery proves the
    // endpoint needs sign-in (see `remoteTools` and `startOAuth`).
    const genericAuthKind: ToolConnectionAuthKind =
      (remoteMcpConnector ? undefined : method?.auth) ??
      (input.authMode === "oauth" || input.oauthClient
        ? "oauth"
        : input.authMode === "bearer" || input.authMode === "custom_headers"
          ? "api_key"
          : input.authMode === "none"
            ? "none"
            : Object.keys(credentialValues).length > 0
              ? "api_key"
              : "none");
    const credentialSecretRefs: CreateToolConnection["credentialSecretRefs"] =
      [];
    const credentialRefs: McpConnectionCredentialRef[] = [];
    const createdSecretIds: string[] = [];
    const createdDefinitionIds: string[] = [];
    // Personal consent belongs to the authenticated responsible user. A delegated
    // agent is recorded separately and never becomes the account owner.
    const personalIdentityUserId = requestedGrantKind === "user" ? connectionActorUserId(actor) : null;
    if (requestedGrantKind === "user" && !personalIdentityUserId) {
      throw badRequest(
        "Connecting an app as yourself requires a signed-in user",
      );
    }
    const retainedPersonalIdentity =
      retainedConnection?.credentialPolicy === "per_user"
        ? await fixedPersonalIdentityForReconnect(
            retainedConnection,
            personalIdentityUserId ?? undefined,
            actor,
          )
        : null;
    const retainedConfig = asRecord(retainedConnection?.config);
    const retainedMethodKey = retainedConfig.connectionMethodKey;
    const retainedSource =
      retainedConfig.sourceTemplateKey ??
      asRecord(retainedConnection?.transportConfig).sourceTemplateKey;
    // Setup forms never receive stored secret values. Treat an omitted value as
    // "keep the existing secret" only while resuming the exact same curated
    // provider and method. This prevents a retry from detaching a client secret
    // or API key, without carrying credentials across a method/provider change.
    const canRetainCredentialMaterial = Boolean(
      retainedConnection &&
      previousGrantKind === requestedGrantKind &&
      galleryEntry &&
      retainedSource === galleryEntry.slug &&
      retainedMethodKey === method?.key &&
      (!remoteMcpConnector || (baseConfig.url === retainedConfig.url && genericAuthKind === retainedConnection.authKind)),
    );
    const retainedCredentialSecretRefs = canRetainCredentialMaterial
      ? (retainedPersonalIdentity?.grant?.credentialSecretRefs ??
        retainedConnection?.credentialSecretRefs ??
        [])
      : [];
    const credentialPolicy: ToolConnectionCredentialPolicy =
      requestedGrantKind === "user"
        ? "per_user"
        : requestedGrantKind === "agent"
          ? "per_agent"
          : "shared";
    const connectionOwnership = isPaperclipCloudConnectorStrategy(
      method?.oauthStrategy,
    )
      ? "platform_shared"
      : "customer";
    let applicationRow: typeof toolApplications.$inferSelect | null = null;
    let connectionRow: typeof toolConnections.$inferSelect | null = null;
    let revivedConnectionPrevious: typeof toolConnections.$inferSelect | null =
      retainedConnection ?? null;
    let revivedGrantMutation: {
      previous: typeof connectionGrants.$inferSelect | null;
      current: typeof connectionGrants.$inferSelect;
    } | null = null;
    let personalPublicSetupEstablished = false;

    try {
      const credentialFields =
        credentialSource === "vercel_connect"
          ? []
          : galleryEntry && !remoteMcpConnector
            ? credentialFieldsFor(galleryEntry, method?.key)
            : linkCredentialFields({ ...Object.fromEntries(retainedCredentialSecretRefs.filter((ref) => ref.configPath.startsWith("headers.") || ref.configPath === "credentials.authorization").map((ref) => [ref.configPath, "retained"])), ...credentialValues });
      for (const field of credentialFields) {
        const value = credentialValues[field.configPath];
        const retainedSecretRef = retainedCredentialSecretRefs.find(
          (ref) => ref.configPath === field.configPath,
        );
        if (!value && retainedSecretRef) {
          credentialSecretRefs.push(retainedSecretRef);
          if (field.placement === "header" && field.key) {
            credentialRefs.push({
              name: field.configPath,
              secretId: retainedSecretRef.secretId,
              version: retainedSecretRef.versionSelector ?? "latest",
              placement: "header",
              key: field.key,
              prefix: field.prefix ?? null,
            });
          }
          continue;
        }
        if (!value && field.required !== false) {
          throw badRequest(`Missing credential value for ${field.configPath}`);
        }
        if (!value) continue;
        const written = await db.transaction((tx) => writeConnectionCredential(tx, {
          companyId, connectionName: name, configPath: field.configPath,
          label: field.label, value, ownerUserId: personalIdentityUserId,
          actor: actorForSecret(actor),
        }));
        const { secret } = written;
        if (written.definitionId) createdDefinitionIds.push(written.definitionId);
        createdSecretIds.push(secret.id);
        credentialSecretRefs.push({
          secretId: secret.id,
          versionSelector: "latest",
          configPath: field.configPath,
          required: field.required ?? true,
          label: field.label,
        });
        if (field.placement === "header" && field.key) {
          credentialRefs.push({
            name: field.configPath,
            secretId: secret.id,
            version: "latest",
            placement: "header",
            key: field.key,
            prefix: field.prefix ?? null,
          });
        }
      }

      if (!remoteUrlCredential?.secretUrl && canRetainCredentialMaterial && baseConfig.url === retainedConfig.url) {
        const retainedUrl = retainedCredentialSecretRefs.find((ref) => ref.configPath === REMOTE_URL_SECRET_CONFIG_PATH);
        if (retainedUrl) {
          credentialSecretRefs.push(retainedUrl);
          credentialRefs.push({ name: REMOTE_URL_SECRET_CONFIG_PATH, secretId: retainedUrl.secretId, version: retainedUrl.versionSelector ?? "latest", placement: "url", key: "url", prefix: null });
        }
      }
      if (remoteUrlCredential?.secretUrl) {
        const written = await db.transaction((tx) => writeConnectionCredential(tx, {
          companyId, connectionName: name, configPath: REMOTE_URL_SECRET_CONFIG_PATH,
          label: "MCP server URL", value: remoteUrlCredential.secretUrl!,
          ownerUserId: personalIdentityUserId, actor: actorForSecret(actor),
        }));
        const { secret } = written;
        if (written.definitionId) createdDefinitionIds.push(written.definitionId);
        createdSecretIds.push(secret.id);
        credentialSecretRefs.push({
          secretId: secret.id,
          versionSelector: "latest",
          configPath: REMOTE_URL_SECRET_CONFIG_PATH,
          required: true,
          label: "MCP server URL",
        });
        credentialRefs.push({
          name: REMOTE_URL_SECRET_CONFIG_PATH,
          secretId: secret.id,
          version: "latest",
          placement: "url",
          key: "url",
          prefix: null,
        });
      }

      // A preregistered OAuth client secret is not a request header — it is only
      // ever sent to the token endpoint — so it gets a secret ref with no
      // credential ref, keeping it out of `projectedConnectionHeaders`.
      if (input.oauthClient?.clientSecret) {
        const secret = await secrets.create(
          companyId,
          {
            name: `${name} OAuth client secret ${randomUUID().slice(0, 8)}`,
            key: `tool_app.${randomUUID()}.oauth_client_secret`,
            provider: "local_encrypted",
            value: input.oauthClient.clientSecret,
            description: `OAuth client secret for ${name}.`,
          },
          actorForSecret(actor),
        );
        createdSecretIds.push(secret.id);
        credentialSecretRefs.push({
          secretId: secret.id,
          versionSelector: "latest",
          configPath: "oauth.client_secret",
          required: false,
          label: "OAuth client secret",
        });
      } else if (input.oauthClient) {
        const retainedOAuth = asRecord(retainedConfig.oauth);
        const clientIdUnchanged =
          retainedOAuth.clientId === input.oauthClient.clientId.trim();
        const retainedClientSecretRef = clientIdUnchanged
          ? retainedCredentialSecretRefs.find(
              (ref) => ref.configPath === "oauth.client_secret",
            )
          : undefined;
        if (retainedClientSecretRef)
          credentialSecretRefs.push(retainedClientSecretRef);
      }

      const safeApplicationDescription =
        galleryEntry?.description ??
        `Connected app at ${remoteUrlCredential?.publicUrl ?? input.link}`;
      if (existingApplication) {
        if (existingApplication.status !== "active") {
          [applicationRow] = await db
            .update(toolApplications)
            .set({
              status: "draft",
              archivedAt: null,
              ...(!galleryEntry
                ? { description: safeApplicationDescription }
                : {}),
              updatedAt: new Date(),
            })
            .where(eq(toolApplications.id, existingApplication.id))
            .returning();
        } else {
          applicationRow = existingApplication;
        }
      } else {
        // Name selection is optimistic because multiple setup requests can
        // legitimately begin at the same time. The company/name unique index
        // is the authority: if another request wins after our read, refresh the
        // names and retry with the next suffix instead of surfacing a conflict
        // the user never asked to resolve.
        for (let attempt = 0; attempt < 10 && !applicationRow; attempt += 1) {
          try {
            [applicationRow] = await db
              .insert(toolApplications)
              .values({
                companyId,
                applicationKey: `app-gallery:${galleryEntry?.slug ?? "link"}:${randomUUID()}`,
                name: applicationName,
                description: safeApplicationDescription,
                type: transport === "rest_api" && (["browser-use-cloud", ...NATIVE_PROVIDER_SLUGS].includes(galleryEntry?.slug ?? "") || Boolean(restConnectorFor({ transport, config }))) ? "rest_api" : transport === "mcp_remote" ? "mcp_http" : "mcp_stdio",
                status: "draft",
                metadata: galleryEntry
                  ? {
                      sourceTemplateKey: galleryEntry.slug,
                      galleryKey: galleryEntry.slug,
                    }
                  : { source: "link" },
              })
              .returning();
          } catch (error) {
            if (!isUniqueViolation(error, "tool_applications_company_name_uq"))
              throw error;
            const applicationNames = await db
              .select({ name: toolApplications.name })
              .from(toolApplications)
              .where(eq(toolApplications.companyId, companyId));
            applicationName = nextAvailableConnectionName(
              requestedName,
              applicationNames.map((row) => row.name),
            );
            name = applicationName;
          }
        }
        if (!applicationRow) {
          throw conflict(
            "Paperclip could not allocate a unique connection name",
            {
              code: "tool_access_name_allocation_exhausted",
            },
          );
        }
      }

      await assertSecretRefs(companyId, [
        ...credentialRefs,
        ...credentialSecretRefs,
      ]);
      // Reconnecting an app revives its most recent archived connection instead
      // of inserting a fresh row: keeps the connection id (and its activity
      // history) stable and avoids the unique (company, name) constraint.
      // A personal credential never becomes the connection's shared secret: the
      // row carries the header shape only, and the secret refs go to the user
      // grant below. `ensureDefaultOrganizationGrant` copies this list, so
      // leaving it empty is what keeps the secret off an organization grant.
      const connectionCredentialSecretRefs =
        personalIdentityUserId || dedicatedAgentId ? [] : credentialSecretRefs;
      if (revivedConnectionPrevious) {
        forgetMcpHttpSessions(revivedConnectionPrevious.id);
        [connectionRow] = await writeToolConnectionHealthChange(db, revivedConnectionPrevious, tx => tx
          .update(toolConnections)
          .set({
            name,
            authKind: genericAuthKind,
            transport,
            status: "draft",
            enabled: false,
            agentInstructions: input.agentInstructions !== undefined
              ? input.agentInstructions
              : retainedConnection ? retainedConnection.agentInstructions
              : defaultConnectionAgentInstructions(galleryEntry?.agentInstructions),
            config,
            transportConfig: config,
            credentialRefs,
            credentialSecretRefs: connectionCredentialSecretRefs,
            credentialSource,
            externalCredential,
            credentialPolicy,
            updatedAt: new Date(),
          })
          .where(eq(toolConnections.id, revivedConnectionPrevious.id))
          .returning());
      } else {
        const connectionId = randomUUID();
        [connectionRow] = await db
          .insert(toolConnections)
          .values({
            id: connectionId,
            companyId,
            applicationId: applicationRow.id,
            name,
            uid: connectionUid(
              applicationRow.applicationKey ?? applicationRow.name,
              name,
              connectionId,
            ),
            connectionKind: "managed",
            ownership: connectionOwnership,
            authKind: genericAuthKind,
            credentialSource,
            externalCredential,
            transport,
            status: "draft",
            enabled: false,
            agentInstructions: input.agentInstructions !== undefined
              ? input.agentInstructions
              : retainedConnection ? retainedConnection.agentInstructions
              : defaultConnectionAgentInstructions(galleryEntry?.agentInstructions),
            config,
            transportConfig: config,
            credentialRefs,
            credentialSecretRefs: connectionCredentialSecretRefs,
            credentialPolicy,
            createdByAgentId:
              actor?.actorType === "agent" ? (actor.actorId ?? null) : null,
            createdByUserId:
              connectionActorUserId(actor),
          })
          .returning();
      }
      if (revivedConnectionPrevious) {
        emitConnectionUpdated(
          connectionRow,
          revivedConnectionPrevious,
          "gallery",
        );
      } else {
        emitConnectionCreated(connectionRow, "gallery");
      }
      if (personalIdentityUserId) {
        // "Just me" (PAP-17835 seam #4). The credential is committed straight to
        // the caller's own grant; the connection row keeps only the header
        // *shape* in `credentialRefs` (which the gateway reads for placement and
        // then resolves against the acting user's grant) and no shared secret
        // refs at all. Two consequences the design requires:
        //  - `ensureDefaultOrganizationGrant` is skipped, so no organization
        //    grant is created first and later "moved" to a user grant. It stays
        //    absent until someone explicitly connects an organization identity,
        //    which is what makes "Organization identity · Not connected"
        //    truthful rather than a silent fallback.
        //  - the credential never lands in `connection.credentialSecretRefs`,
        //    which is what an organization grant would have copied.
        //
        // OAuth is the exception: no credential exists yet at connect time, and
        // the callback upserts this same (connection, user, subject) grant with
        // the tokens. Pre-creating an empty `active` grant there would render as
        // "Connected" with nothing behind it, so the grant is left to the
        // callback and only the organization grant is suppressed.
        if (credentialSecretRefs.length > 0) {
          let changedGrant: typeof connectionGrants.$inferSelect;
          let previousGrant: typeof connectionGrants.$inferSelect | null = null;
          if (retainedPersonalIdentity?.grant) {
            const [grantSnapshot] = await db
              .select({
                grant: connectionGrants,
                // Preserve PostgreSQL microseconds for the optimistic update;
                // a JavaScript Date truncates them and falsely reports a race.
                updatedAtVersion: sql<string>`${connectionGrants.updatedAt}::text`,
              })
              .from(connectionGrants)
              .where(eq(connectionGrants.id, retainedPersonalIdentity.grant.id))
              .limit(1);
            const currentGrant = grantSnapshot?.grant;
            if (!currentGrant)
              throw conflict(
                "The personal credential changed during setup. Please try again.",
              );
            previousGrant = currentGrant;
            [changedGrant] = await db
              .update(connectionGrants)
              .set({
                credentialSecretRefs,
                status: "active",
                revokedAt: null,
                revokedByAgentId: null,
                revokedByUserId: null,
                updatedAt: new Date(),
              })
              .where(
                and(
                  eq(connectionGrants.id, currentGrant.id),
                  sql`${connectionGrants.updatedAt} = ${grantSnapshot!.updatedAtVersion}::timestamptz`,
                ),
              )
              .returning();
            if (!changedGrant)
              throw conflict(
                "The personal credential changed during setup. Please try again.",
              );
          } else {
            [changedGrant] = await db
              .insert(connectionGrants)
              .values({
                companyId,
                connectionId: connectionRow.id,
                kind: "user",
                subjectUserId: personalIdentityUserId,
                credentialSecretRefs,
                status: "active",
                isDefault: false,
                createdByUserId: personalIdentityUserId,
              })
              .returning();
            if (!changedGrant)
              throw new Error("Failed to create personal connection grant");
          }
          if (revivedConnectionPrevious) {
            revivedGrantMutation = {
              previous: previousGrant,
              current: changedGrant,
            };
          }
          await db.insert(toolAccessAuditEvents).values({
            companyId,
            connectionId: connectionRow.id,
            actorType: "user",
            actorId: personalIdentityUserId,
            action: retainedPersonalIdentity?.grant
              ? "connection_grant.updated"
              : "connection_grant.created",
            outcome: "success",
            reasonCode: retainedPersonalIdentity?.grant
              ? "personal_identity_reconnected"
              : "personal_identity_created",
            details: {
              kind: "user",
              credentialSecretRefCount: credentialSecretRefs.length,
            },
          });
        }
      } else if (dedicatedAgentId) {
        // Managed OAuth creates the credential-bearing grant in the callback.
        // Keep the connection free of organization secrets from the outset.
      } else {
        const organizationGrant = await ensureDefaultOrganizationGrant(
          connectionRow,
          db,
          revivedConnectionPrevious
            ? (mutation) => {
                revivedGrantMutation = mutation;
              }
            : undefined,
        );
        if (credentialSource === "vercel_connect") {
          const derived = deriveVercelConnectSubject({
            credential: externalCredential!,
            connectionId: connectionRow.id,
            companyId,
            grantKind: "organization",
          });
          const updatedOrganizationGrant = await db.transaction(async (tx) => {
            const [lockedGrant] = await tx
              .select()
              .from(connectionGrants)
              .where(eq(connectionGrants.id, organizationGrant.id))
              .limit(1)
              .for("update");
            if (
              !lockedGrant ||
              lockedGrant.updatedAt.getTime() !==
                organizationGrant.updatedAt.getTime()
            ) {
              throw conflict(
                "The organization credential changed during setup. Please try again.",
              );
            }
            const [updated] = await tx
              .update(connectionGrants)
              .set({
                externalCredential: {
                  provider: "vercel_connect",
                  subjectType: externalCredential!.principalMode,
                  ...(derived.subjectId
                    ? { subjectId: derived.subjectId }
                    : {}),
                },
                credentialSecretRefs: [],
                updatedAt: now(),
              })
              .where(eq(connectionGrants.id, organizationGrant.id))
              .returning();
            return updated;
          });
          if (!updatedOrganizationGrant) {
            throw conflict(
              "The organization credential changed during setup. Please try again.",
            );
          }
          if (revivedGrantMutation) {
            revivedGrantMutation = {
              previous: revivedGrantMutation.previous,
              current: updatedOrganizationGrant,
            };
          }
        }
      }
      await syncCredentialBindings(
        connectionRow,
        personalIdentityUserId || dedicatedAgentId ? credentialSecretRefs : [],
      );
      await ensureRuntimeSlot(connectionRow);

      if (input.saveDraft && remoteMcpConnector) {
        return { connectionId: connectionRow.id, application: toApplication(applicationRow), connection: toConnection(connectionRow),
          catalog: [], actions: { readOnly: [], canMakeChanges: [] }, suggestedDefaults: { access: "all_agents", askFirstRiskLevels: [] } };
      }
      if (galleryEntry && method?.auth === "oauth") {
        const suggestedDefaults = recommendedDefaultsForApp(
          galleryEntry,
          method.key,
        );
        return {
          connectionId: connectionRow.id,
          application: toApplication(applicationRow),
          connection: toConnection(connectionRow),
          catalog: [],
          actions: { readOnly: [], canMakeChanges: [] },
          suggestedDefaults: dedicatedAgentId
            ? { ...suggestedDefaults, access: { agentIds: [dedicatedAgentId] } }
            : suggestedDefaults,
          auth: { kind: "oauth", startUrl: null },
        };
      }

      // A pasted MCP URL starts with unknown auth. For a personal connection,
      // there is deliberately no empty active grant yet, so probe this one
      // creator-owned draft without credentials. A 401 can then discover OAuth
      // and leave grant creation to the callback; a public endpoint gets an
      // empty personal grant below so later catalog refreshes use the same
      // identity policy.
      const unauthenticatedPersonalProbe = Boolean(
        (!galleryEntry || remoteMcpConnector) &&
          genericAuthKind === "none" &&
          credentialSecretRefs.length === 0 &&
          personalIdentityUserId &&
          !retainedPersonalIdentity?.grant,
      );
      let health: ToolConnectionHealthCheckResult;
      try {
        health = await checkConnectionHealth(connectionRow.id, actor, {
          allowUnauthenticatedProbe: unauthenticatedPersonalProbe,
        });
      } catch (error) {
        if (
          (!galleryEntry || remoteMcpConnector) &&
          input.authMode !== "none" &&
          input.authMode !== "bearer" &&
          input.authMode !== "custom_headers" &&
          error instanceof HttpError &&
          asRecord(error.details).code === "oauth_challenge"
        ) {
          const [oauthConnection] = await db
            .select()
            .from(toolConnections)
            .where(eq(toolConnections.id, connectionRow.id));
          const endpoints = await discoverOAuthEndpoints(oauthConnection).catch(
            (discoveryError: unknown) => {
              // "This server advertised an address Paperclip refuses to open" is a
              // refusal, not a failed discovery: keep it instead of collapsing it
              // into the generic sign-in-required error.
              if (isOAuthEndpointRejection(discoveryError))
                throw discoveryError;
              return null;
            },
          );
          if (!endpoints) throw error;
          return {
            connectionId: oauthConnection.id,
            application: toApplication(applicationRow),
            connection: toConnection(oauthConnection),
            catalog: [],
            actions: { readOnly: [], canMakeChanges: [] },
            suggestedDefaults: {
              access: "all_agents",
              askFirstRiskLevels: [],
            },
            // The endpoint asked for authorization and discovery found a real
            // authorization server, so the wizard can offer "Sign in to
            // continue" instead of a dead end. The caller starts the flow and
            // fills in `startUrl`/`registrationSource`; it only needs the issuer
            // and resource here to show which server the operator is about to
            // trust.
            auth: {
              kind: "oauth",
              startUrl: null,
              issuer: endpoints.issuer ?? null,
              resource: endpoints.resource ?? null,
            },
          };
        }
        throw error;
      }
      if (unauthenticatedPersonalProbe) {
        const personalConnectionId = connectionRow.id;
        const grant = await db.transaction(async (tx) => {
          const [createdGrant] = await tx
            .insert(connectionGrants)
            .values({
              companyId,
              connectionId: personalConnectionId,
              kind: "user",
              subjectUserId: personalIdentityUserId!,
              credentialSecretRefs: [],
              status: "active",
              isDefault: false,
              createdByUserId: personalIdentityUserId!,
            })
            .onConflictDoNothing()
            .returning();
          if (createdGrant) {
            await tx.insert(toolAccessAuditEvents).values({
              companyId,
              connectionId: personalConnectionId,
              actorType: "user",
              actorId: personalIdentityUserId!,
              action: "connection_grant.created",
              outcome: "success",
              reasonCode: "personal_identity_created",
              details: { kind: "user", credentialSecretRefCount: 0 },
            });
          }
          return createdGrant;
        });
        if (!grant) {
          // Another setup attempt may have created this user's grant while
          // both probes were in flight. Reuse only an active personal grant;
          // never overwrite credentials, revive a revoked grant, or claim its
          // audit/rollback ownership in this attempt.
          const existingGrant = await vaultGrantForConnection(connectionRow, actor);
          if (existingGrant?.kind !== "user" || existingGrant.subjectUserId !== personalIdentityUserId) {
            throw conflict("The personal credential changed during setup. Please try again.");
          }
        }
        // A successful public probe establishes this identity, like OAuth
        // consent does. Keep its draft and grant if catalog/default discovery
        // later fails: another retry may already be using the committed grant.
        personalPublicSetupEstablished = true;
      }
      const restoreDraftDefaults = Boolean(revivedConnectionPrevious);
      const refreshOptions = {
        enableAllByDefault: restoreDraftDefaults && !remoteMcpConnector,
        restoreDraftDefaults,
      };
      const catalogConnectionId = connectionRow.id;
      // Keep the established public identity outside this transaction while
      // making catalog, defaults, and their audits one all-or-nothing step.
      const refresh: ToolCatalogRefreshResult = personalPublicSetupEstablished
        ? await db.transaction(async (tx): Promise<ToolCatalogRefreshResult> =>
            toolAccessService(tx as unknown as Db, options).refreshCatalog(
              catalogConnectionId,
              actor,
              refreshOptions,
            ),
          )
        : await refreshCatalog(catalogConnectionId, actor, refreshOptions);
      const [application] = await db
        .select()
        .from(toolApplications)
        .where(eq(toolApplications.id, applicationRow.id));
      return {
        connectionId: refresh.connection.id,
        application: toApplication(application),
        connection: refresh.connection,
        catalog: refresh.catalog,
        actions: groupedActions(refresh.catalog),
        suggestedDefaults: galleryEntry
          ? recommendedDefaultsForApp(galleryEntry, method?.key)
          : {
              access: "all_agents",
              askFirstRiskLevels: [],
            },
      };
    } catch (error) {
      if (personalPublicSetupEstablished) throw error;
      let identityRollbackError: unknown = null;
      let preserveConcurrentRevival = false;
      if (connectionRow && revivedConnectionPrevious) {
        const attemptedConnection = connectionRow;
        try {
          await db.transaction(async (tx) => {
            if (revivedGrantMutation) await tx.select({ id: connectionGrants.id }).from(connectionGrants)
              .where(and(eq(connectionGrants.id, revivedGrantMutation.current.id), eq(connectionGrants.companyId, companyId)))
              .for("update");
            const [latestConnection] = await tx
              .select()
              .from(toolConnections)
              .where(
                and(
                  eq(toolConnections.id, revivedConnectionPrevious.id),
                  eq(toolConnections.companyId, companyId),
                ),
              )
              .limit(1)
              .for("update");
            // Health/catalog failures from this setup may update only health
            // fields and `updatedAt`, so compare the identity/configuration
            // fields this attempt owned. If another request changed any of
            // those fields, its newer connection state is authoritative.
            const connectionMutationIsStillCurrent = Boolean(
              latestConnection &&
              connectionSetupMutationFingerprint(latestConnection) ===
                connectionSetupMutationFingerprint(attemptedConnection),
            );
            if (connectionMutationIsStillCurrent) {
              await notifyToolConnectionHealth(tx, revivedConnectionPrevious);
              await tx
                .update(toolConnections)
                .set({
                  agentInstructions: revivedConnectionPrevious.agentInstructions,
                  name: revivedConnectionPrevious.name,
                  transport: revivedConnectionPrevious.transport,
                  status: revivedConnectionPrevious.status,
                  enabled: revivedConnectionPrevious.enabled,
                  config: revivedConnectionPrevious.config,
                  transportConfig: revivedConnectionPrevious.transportConfig,
                  credentialRefs: revivedConnectionPrevious.credentialRefs,
                  credentialSecretRefs:
                    revivedConnectionPrevious.credentialSecretRefs,
                  credentialSource: revivedConnectionPrevious.credentialSource,
                  externalCredential:
                    revivedConnectionPrevious.externalCredential,
                  credentialPolicy: revivedConnectionPrevious.credentialPolicy,
                  updatedAt: new Date(),
                })
                .where(eq(toolConnections.id, revivedConnectionPrevious.id));
            } else {
              preserveConcurrentRevival = true;
            }

            if (connectionMutationIsStillCurrent && revivedGrantMutation) {
              const { previous, current } = revivedGrantMutation;
              const [latestGrant] = await tx
                .select()
                .from(connectionGrants)
                .where(eq(connectionGrants.id, current.id))
                .limit(1)
                .for("update");
              const mutationIsStillCurrent = Boolean(
                latestGrant &&
                latestGrant.updatedAt.getTime() === current.updatedAt.getTime(),
              );
              // A grant manager may have changed this grant while provider
              // setup was in flight. Restore/delete only the exact version this
              // attempt wrote; a newer version is authoritative and remains
              // untouched.
              if (previous && mutationIsStillCurrent) {
                await tx
                  .update(connectionGrants)
                  .set({
                    kind: previous.kind,
                    subjectUserId: previous.subjectUserId,
                    subjectAgentId: previous.subjectAgentId,
                    providerTenant: previous.providerTenant,
                    credentialSecretRefs: previous.credentialSecretRefs,
                    externalCredential: previous.externalCredential,
                    status: previous.status,
                    isDefault: previous.isDefault,
                    createdByAgentId: previous.createdByAgentId,
                    createdByUserId: previous.createdByUserId,
                    revokedAt: previous.revokedAt,
                    revokedByAgentId: previous.revokedByAgentId,
                    revokedByUserId: previous.revokedByUserId,
                    lastUsedAt: previous.lastUsedAt,
                    updatedAt: previous.updatedAt,
                  })
                  .where(eq(connectionGrants.id, current.id));
              } else if (!previous && mutationIsStillCurrent) {
                await tx
                  .delete(connectionGrants)
                  .where(eq(connectionGrants.id, current.id));
              }
            }
          });
        } catch (rollbackError) {
          identityRollbackError = rollbackError;
          // The attempted identity and its grants may no longer agree. Keep the
          // connection unusable until a manager explicitly reconnects it, and
          // surface the restoration failure instead of returning only the
          // original provider error.
          try {
            await writeToolConnectionHealthChange(db, revivedConnectionPrevious, tx => tx
              .update(toolConnections)
              .set({
                status: "draft",
                enabled: false,
                healthStatus: "error",
                healthMessage:
                  "Connection identity restoration failed. Reconnect this app to continue.",
                lastError: "connection_identity_rollback_failed",
                updatedAt: new Date(),
              })
              .where(
                and(
                  eq(toolConnections.id, revivedConnectionPrevious.id),
                  eq(toolConnections.companyId, companyId),
                ),
              ));
          } catch (quarantineError) {
            identityRollbackError = new AggregateError(
              [rollbackError, quarantineError],
              "Connection identity rollback and quarantine both failed",
            );
          }
        }
      } else if (connectionRow) {
        const failedConnectionId = connectionRow.id;
        await writeToolConnectionHealthChange(db, { companyId, id: failedConnectionId }, tx => tx
          .delete(toolConnections)
          .where(eq(toolConnections.id, failedConnectionId)))
          .catch(() => undefined);
      }
      if (
        !preserveConcurrentRevival &&
        applicationRow &&
        !existingApplication
      ) {
        await db
          .delete(toolApplications)
          .where(eq(toolApplications.id, applicationRow.id))
          .catch(() => undefined);
      } else if (
        !preserveConcurrentRevival &&
        existingApplication &&
        applicationRow &&
        applicationRow.status !== existingApplication.status
      ) {
        await db
          .update(toolApplications)
          .set({
            status: existingApplication.status,
            archivedAt: existingApplication.archivedAt,
            updatedAt: new Date(),
          })
          .where(eq(toolApplications.id, existingApplication.id))
          .catch(() => undefined);
      }
      if (!preserveConcurrentRevival) {
        for (const secretId of createdSecretIds) {
          await secrets.remove(secretId).catch(() => undefined);
        }
        for (const definitionId of createdDefinitionIds) {
          await db.delete(userSecretDefinitions).where(eq(userSecretDefinitions.id, definitionId)).catch(() => undefined);
        }
      }
      if (identityRollbackError) {
        throw new HttpError(
          500,
          "Connection setup failed and its prior identity could not be restored.",
          {
            code: "connection_identity_rollback_failed",
          },
        );
      }
      throw error;
    }
  }

  async function assertCatalogEntriesForConnection(
    companyId: string,
    connectionId: string,
    catalogEntryIds: string[],
  ): Promise<Array<typeof toolCatalogEntries.$inferSelect>> {
    const uniqueIds = [...new Set(catalogEntryIds)];
    if (uniqueIds.length === 0) return [];
    const rows = await db
      .select()
      .from(toolCatalogEntries)
      .where(
        and(
          eq(toolCatalogEntries.companyId, companyId),
          eq(toolCatalogEntries.connectionId, connectionId),
          inArray(toolCatalogEntries.id, uniqueIds),
        ),
      );
    if (rows.length !== uniqueIds.length) {
      throw unprocessable(
        "All selected catalog entries must belong to this app connection",
      );
    }
    return rows;
  }

  async function assertAgentsInCompany(companyId: string, agentIds: string[]) {
    if (agentIds.length === 0) return;
    const rows = await db
      .select({ id: agents.id })
      .from(agents)
      .where(
        and(
          eq(agents.companyId, companyId),
          inArray(agents.id, [...new Set(agentIds)]),
        ),
      );
    if (rows.length !== new Set(agentIds).size) {
      throw unprocessable(
        "All app access agent ids must belong to the same company",
      );
    }
  }

  async function finishGalleryAppConnection(
    companyId: string,
    connectionId: string,
    input: FinishToolApp,
    actor?: ActorInfo,
  ): Promise<FinishToolAppResult> {
    await actor?.managementContext?.reauthorize();
    const connection = await getConnectionRow(connectionId, companyId);
    await assertConnectorConnectionSetupEnabled(connection);
    if (connection.status === "archived")
      throw conflict("Archived app connections cannot be finished");
    if (connection.config.mcpPreserveAccess === true && isRemoteMcpConnectorMethod(connection.config.sourceTemplateKey, connection.config.connectionMethodKey)) {
      const [profile] = await db.select().from(toolProfiles).where(and(
        eq(toolProfiles.companyId, companyId), eq(toolProfiles.profileKey, `app:${connection.id}`),
      )).limit(1);
      if (!profile) throw conflict("The saved connection permissions could not be found");
      const config = { ...connection.config };
      delete config.mcpPreserveAccess;
      const updated = await db.transaction(async (tx) => {
        await tx.select({ id: toolApplications.id }).from(toolApplications)
          .where(and(eq(toolApplications.id, connection.applicationId), eq(toolApplications.companyId, companyId)))
          .for("update");
        await notifyToolConnectionHealth(tx, connection);
        const [row] = await tx.update(toolConnections).set({ config, transportConfig: config, status: "active", enabled: true, ...(input.agentInstructions !== undefined ? { agentInstructions: input.agentInstructions } : {}), updatedAt: new Date() })
          .where(and(eq(toolConnections.id, connection.id), eq(toolConnections.companyId, companyId))).returning();
        await tx.update(toolApplications).set({ status: "active", updatedAt: new Date() }).where(and(eq(toolApplications.id, connection.applicationId), eq(toolApplications.companyId, companyId)));
        return row;
      });
      const details = await profileDetails(profile.id, companyId);
      const policies = (await db.select().from(toolPolicies).where(eq(toolPolicies.companyId, companyId))).filter((policy) => asRecord(policy.config).connectionId === connection.id);
      return { connection: toConnection(updated), profile: toProfile(profile), profileEntries: details.entries, profileBindings: details.bindings, policies: policies.map(toPolicy) };
    }
    const enabledIds = [
      ...new Set([
        ...input.enabledCatalogEntryIds,
        ...input.askFirstCatalogEntryIds,
      ]),
    ];
    const requestedReviewedIds = input.reviewedCatalogEntryIds ?? [];
    const reviewedIds = [...new Set(requestedReviewedIds)];
    if (reviewedIds.length !== requestedReviewedIds.length) {
      throw badRequest(
        "Action review decisions must not contain duplicate catalogEntryId values",
      );
    }
    const enabledRows = await assertCatalogEntriesForConnection(
      companyId,
      connection.id,
      enabledIds,
    );
    const askFirstRows = await assertCatalogEntriesForConnection(
      companyId,
      connection.id,
      input.askFirstCatalogEntryIds,
    );
    if (enabledRows.some((entry) => entry.status === "disabled" && !(entry.quarantineReason === "mcp_tool_removed" && isRemoteMcpConnectorMethod(connection.config.sourceTemplateKey, connection.config.connectionMethodKey)))) {
      throw badRequest("Disabled actions cannot be enabled");
    }
    if (reviewedIds.length > 0) {
      await assertCatalogEntriesForConnection(
        companyId,
        connection.id,
        reviewedIds,
      );
      const quarantinedRows = await db
        .select({ id: toolCatalogEntries.id })
        .from(toolCatalogEntries)
        .where(
          and(
            eq(toolCatalogEntries.companyId, companyId),
            eq(toolCatalogEntries.connectionId, connection.id),
            eq(toolCatalogEntries.status, "quarantined"),
          ),
        );
      const reviewedIdSet = new Set(reviewedIds);
      if (
        quarantinedRows.length !== reviewedIdSet.size ||
        quarantinedRows.some((entry) => !reviewedIdSet.has(entry.id))
      ) {
        throw badRequest(
          "Action review decisions must cover every currently quarantined action exactly once",
        );
      }
    }
    if (input.access !== "all_agents")
      await assertAgentsInCompany(companyId, input.access.agentIds);

    const entries: CreateToolProfileEntryForProfile[] = enabledRows.map(
      (entry) => ({
        selectorType: "catalog_entry",
        effect: "include",
        catalogEntryId: entry.id,
        connectionId: connection.id,
        applicationId: connection.applicationId,
      }),
    );
    const profileKey = `app:${connection.id}`;
    const bindingInputs: CreateToolProfileBindingForProfile[] =
      input.access === "all_agents"
        ? [
            {
              targetType: "company",
              targetId: companyId,
              priority: 100,
              metadata: { source: "app_gallery_finish" },
            },
          ]
        : [...new Set(input.access.agentIds)].map((agentId) => ({
            targetType: "agent" as const,
            targetId: agentId,
            priority: 100,
            metadata: { source: "app_gallery_finish" },
          }));
    await actor?.managementContext?.reauthorize();
    const transactionResult = await db.transaction(async (tx) => {
      await tx.select({ id: toolApplications.id }).from(toolApplications)
        .where(and(eq(toolApplications.id, connection.applicationId), eq(toolApplications.companyId, companyId)))
        .for("update");
      const [lockedConnection] = await tx
        .select({ id: toolConnections.id, status: toolConnections.status, enabled: toolConnections.enabled })
        .from(toolConnections)
        .where(
          and(
            eq(toolConnections.id, connectionId),
            eq(toolConnections.companyId, companyId),
          ),
        )
        .for("update");
      if (!lockedConnection) throw notFound("Tool connection not found");
      const [existingProfile] = await tx
        .select()
        .from(toolProfiles)
        .where(
          and(
            eq(toolProfiles.companyId, companyId),
            eq(toolProfiles.profileKey, profileKey),
          ),
        )
        .limit(1).for("no key update");
      await lockManagedAppPolicies(tx, companyId, connection.id);
      const existingBindings = existingProfile ? await tx.select().from(toolProfileBindings)
        .where(and(eq(toolProfileBindings.companyId, companyId), eq(toolProfileBindings.profileId, existingProfile.id))) : [];
      const existingInstalls = await tx.select().from(toolConnectionInstalls)
        .where(and(eq(toolConnectionInstalls.companyId, companyId), eq(toolConnectionInstalls.connectionId, connection.id)));
      const companyTargets = lockedConnection.status !== "active" || !lockedConnection.enabled || (existingProfile && existingProfile.status !== "active")
        ? [{ targetType: "company", targetId: companyId }] : [];
      await lockToolAssignmentAgents(tx, companyId, [...existingBindings, ...bindingInputs, ...existingInstalls, ...companyTargets]);
      // A renamed connection can leave its old profile name in use. Resolve
      // names against profiles too, including when finalizing an installed draft.
      const otherProfiles = await tx
        .select({ name: toolProfiles.name })
        .from(toolProfiles)
        .where(and(
          eq(toolProfiles.companyId, companyId),
          ne(toolProfiles.profileKey, profileKey),
        ));
      const profileName = nextAvailableConnectionName(
        connection.name,
        otherProfiles.map((profile) => profile.name),
      );
      let profileId: string;
      if (existingProfile) {
        if (input.preserveExistingAccess) {
          for (const prior of existingBindings)
            if (
              !bindingInputs.some(
                (binding) =>
                  binding.targetType === prior.targetType &&
                  binding.targetId === prior.targetId,
              )
            )
              bindingInputs.push({
                targetType: prior.targetType,
                targetId: prior.targetId,
                priority: prior.priority,
                metadata: prior.metadata,
              });
          const priorEntries = await tx
            .select()
            .from(toolProfileEntries)
            .where(eq(toolProfileEntries.profileId, existingProfile.id));
          for (const prior of priorEntries)
            if (
              !entries.some(
                (entry) =>
                  entry.catalogEntryId &&
                  entry.catalogEntryId === prior.catalogEntryId,
              )
            )
              entries.push({
                selectorType: prior.selectorType,
                effect: prior.effect,
                applicationId: prior.applicationId,
                connectionId: prior.connectionId,
                catalogEntryId: prior.catalogEntryId,
                toolName: prior.toolName,
                riskLevel: prior.riskLevel,
                conditions: prior.conditions,
              });
        }
        await tx
          .delete(toolProfileBindings)
          .where(
            and(
              eq(toolProfileBindings.companyId, companyId),
              eq(toolProfileBindings.profileId, existingProfile.id),
            ),
          );
        await tx
          .delete(toolProfileEntries)
          .where(
            and(
              eq(toolProfileEntries.companyId, companyId),
              eq(toolProfileEntries.profileId, existingProfile.id),
            ),
          );
        if (entries.length > 0) {
          await tx.insert(toolProfileEntries).values(
            entries.map((entry) => ({
              companyId,
              profileId: existingProfile.id,
              selectorType: entry.selectorType,
              effect: entry.effect ?? "include",
              applicationId: entry.applicationId ?? null,
              connectionId: entry.connectionId ?? null,
              catalogEntryId: entry.catalogEntryId ?? null,
              toolName: entry.toolName ?? null,
              riskLevel: entry.riskLevel ?? null,
              conditions: entry.conditions ?? null,
            })),
          );
        }
        const [updated] = await tx
          .update(toolProfiles)
          .set({
            name: profileName,
            description: `Access profile for ${connection.name}.`,
            status: "active",
            defaultAction: "deny",
            metadata: {
              source: "app_gallery_finish",
              connectionId: connection.id,
            },
            updatedAt: new Date(),
          })
          .where(eq(toolProfiles.id, existingProfile.id))
          .returning();
        profileId = updated.id;
      } else {
        const [created] = await tx
          .insert(toolProfiles)
          .values({
            companyId,
            profileKey,
            name: profileName,
            description: `Access profile for ${connection.name}.`,
            status: "active",
            defaultAction: "deny",
            metadata: {
              source: "app_gallery_finish",
              connectionId: connection.id,
            },
          })
          .returning();
        if (entries.length > 0) {
          await tx.insert(toolProfileEntries).values(
            entries.map((entry) => ({
              companyId,
              profileId: created.id,
              selectorType: entry.selectorType,
              effect: entry.effect ?? "include",
              applicationId: entry.applicationId ?? null,
              connectionId: entry.connectionId ?? null,
              catalogEntryId: entry.catalogEntryId ?? null,
              toolName: entry.toolName ?? null,
              riskLevel: entry.riskLevel ?? null,
              conditions: entry.conditions ?? null,
            })),
          );
        }
        profileId = created.id;
      }

      const profileBindings: ToolProfileBinding[] = [];
      // These connectors expose one agent-access choice. Commit installation
      // reach and permission bindings together, including an empty selection.
      if (isRemoteMcpConnectorMethod(connection.config.sourceTemplateKey, connection.config.connectionMethodKey)) {
        const desired = new Map(bindingInputs.flatMap((binding) => binding.targetType === "company" || binding.targetType === "agent"
          ? [[`${binding.targetType}:${binding.targetId}`, { targetType: binding.targetType, targetId: binding.targetId }] as const] : []));
        const removed = existingInstalls.filter((install) => !desired.has(`${install.targetType}:${install.targetId}`));
        const added = [...desired.values()].filter((binding) => !existingInstalls.some((install) => install.targetType === binding.targetType && install.targetId === binding.targetId));
        if (removed.length) await tx.delete(toolConnectionInstalls).where(inArray(toolConnectionInstalls.id, removed.map((install) => install.id)));
        if (added.length) await tx.insert(toolConnectionInstalls).values(added.map((binding) => ({
          companyId, connectionId: connection.id, targetType: binding.targetType, targetId: binding.targetId,
          createdByAgentId: actor?.actorType === "agent" ? (actor.actorId ?? null) : null,
          createdByUserId: connectionActorUserId(actor),
        })));
        if (added.length || removed.length) await tx.insert(toolAccessAuditEvents).values({
          companyId, connectionId: connection.id, actorType: actor?.actorType ?? "system", actorId: actor?.actorId ?? null,
          action: "connection_installs.changed", outcome: "success", reasonCode: "installs_changed",
          details: { added: added.map(({ targetType, targetId }) => ({ targetType, targetId })), removed: removed.map(({ targetType, targetId }) => ({ targetType, targetId })) },
        });
      }
      for (const bindingInput of bindingInputs) {
        const [binding] = await tx
          .insert(toolProfileBindings)
          .values({
            companyId,
            profileId,
            targetType: bindingInput.targetType,
            targetId: bindingInput.targetId,
            priority: bindingInput.priority ?? 100,
            metadata: bindingInput.metadata ?? {},
            createdByAgentId:
              actor?.actorType === "agent" ? (actor.actorId ?? null) : null,
            createdByUserId:
              connectionActorUserId(actor),
          })
          .returning();
        profileBindings.push(toProfileBinding(binding));
      }

      const reviewedAt = new Date();
      if (reviewedIds.length > 0) {
        await tx
          .update(toolCatalogEntries)
          .set({
            status: "active",
            reviewedAt,
            reviewedByAgentId:
              actor?.actorType === "agent" ? (actor.actorId ?? null) : null,
            reviewedByUserId:
              connectionActorUserId(actor),
            quarantinedAt: null,
            quarantineReason: null,
            updatedAt: reviewedAt,
          })
          .where(
            and(
              eq(toolCatalogEntries.companyId, companyId),
              eq(toolCatalogEntries.connectionId, connection.id),
              inArray(toolCatalogEntries.id, reviewedIds),
              eq(toolCatalogEntries.status, "quarantined"),
            ),
          );
      }
      if (enabledIds.length > 0) {
        await tx
          .update(toolCatalogEntries)
          .set({
            status: "active",
            reviewedAt,
            reviewedByAgentId:
              actor?.actorType === "agent" ? (actor.actorId ?? null) : null,
            reviewedByUserId:
              connectionActorUserId(actor),
            quarantinedAt: null,
            quarantineReason: null,
            updatedAt: reviewedAt,
          })
          .where(
            and(
              eq(toolCatalogEntries.companyId, companyId),
              inArray(toolCatalogEntries.id, enabledIds),
              ne(toolCatalogEntries.status, "quarantined"),
              ne(toolCatalogEntries.status, "disabled"),
            ),
          );
      }

      const policies = await upsertAskFirstPolicies(
        {
          companyId,
          connection,
          askFirstEntries: askFirstRows,
          disableStale: !input.preserveExistingAccess,
          actor,
        },
        tx,
      );
      await notifyToolConnectionHealth(tx, connection);
      const [updatedConnection] = await tx
        .update(toolConnections)
        .set({ status: "active", enabled: true, ...(input.agentInstructions !== undefined ? { agentInstructions: input.agentInstructions } : {}), updatedAt: new Date() })
        .where(eq(toolConnections.id, connection.id))
        .returning();
      await tx
        .update(toolApplications)
        .set({ status: "active", updatedAt: new Date() })
        .where(eq(toolApplications.id, connection.applicationId));

      return { profileId, profileBindings, policies, updatedConnection };
    });
    emitConnectionUpdated(
      transactionResult.updatedConnection,
      connection,
      "gallery",
    );

    const details = await profileDetails(
      transactionResult.profileId,
      companyId,
    );
    return {
      connection: toConnection(transactionResult.updatedConnection),
      profile: {
        id: details.id,
        companyId: details.companyId,
        profileKey: details.profileKey,
        name: details.name,
        description: details.description,
        status: details.status,
        defaultAction: details.defaultAction,
        newToolsReviewedAt: details.newToolsReviewedAt,
        metadata: details.metadata,
        createdAt: details.createdAt,
        updatedAt: details.updatedAt,
      },
      profileEntries: details.entries,
      profileBindings: transactionResult.profileBindings,
      policies: transactionResult.policies,
    };
  }

  /**
   * Replace the credential(s) on an existing connection and re-run the health
   * check — the "Replace key" / reconnect flow (M7, PAP-10859). Rotates the
   * secret in place when a ref already exists so the connection keeps its
   * profile, policies, and catalog; creates a fresh secret only when the field
   * had none (e.g. a link connection added a key after the fact).
   */
  async function reconnectGalleryApp(
    connectionId: string,
    companyId: string,
    input: { credentialValues: Record<string, string> },
    actor?: ActorInfo,
  ): Promise<ToolConnectionHealthCheckResult> {
    await actor?.managementContext?.reauthorize();
    const connection = await getConnectionRow(connectionId, companyId);
    assertSupportedConnection(connection);
    await assertConnectorConnectionSetupEnabled(connection);
    await assertExperimentalConnectorSetupEnabled(connection.config.sourceTemplateKey, connection.status !== "draft");
    if (connection.status === "archived")
      throw conflict("Archived app connections cannot be reconnected");
    if (connection.credentialSource === "vercel_connect") {
      throw conflict(
        "Manage this connector in Vercel Connect, then run a Paperclip health check to verify it.",
        {
          code: "vercel_connect_managed_externally",
          manageUrl: vercelConnectIntegrationStatus().manageUrl,
        },
      );
    }
    const sourceTemplateKey =
      typeof connection.config.sourceTemplateKey === "string"
        ? connection.config.sourceTemplateKey
        : null;
    const galleryEntry = sourceTemplateKey
      ? getConnectableAppDefinition(sourceTemplateKey)
      : null;
    const storedCredentialFields = connection.credentialRefs
      .filter((ref) => ref.placement === "header" || ref.placement === "url")
      .map((ref) => ({
        label: ref.placement === "url" ? "MCP server URL" : ref.prefix === "Bearer " ? "App key" : ref.key ?? ref.name,
        configPath: credentialRefConfigPath(ref),
        helpUrl: "",
        required: false,
        placement: ref.placement,
        key: ref.key,
        prefix: ref.prefix,
      }));
    const galleryCredentialFields = galleryEntry
      ? credentialFieldsFor(galleryEntry, connectionMethodForConnection(galleryEntry, connection).key)
      : [];
    const credentialFields = galleryCredentialFields.length > 0
      ? galleryCredentialFields
      : storedCredentialFields.length > 0 ? storedCredentialFields : [
          {
            label: "App key",
            configPath: "credentials.authorization",
            helpUrl: "",
            required: false,
            placement: "header" as const,
            key: "Authorization",
            prefix: "Bearer ",
          },
        ];

    const providedFields = credentialFields.filter(
      (field) =>
        (input.credentialValues[field.configPath]?.trim().length ?? 0) > 0,
    );
    if (providedFields.length === 0)
      throw badRequest("Enter a replacement credential to reconnect this app");

    const personalIdentity = await fixedPersonalIdentityForReconnect(
      connection,
      undefined,
      actor,
    );
    const credentialSecretRefs = [
      ...(personalIdentity?.grant?.credentialSecretRefs ??
        connection.credentialSecretRefs),
    ];
    const credentialRefs: McpConnectionCredentialRef[] = [
      ...(connection.credentialRefs ?? []),
    ];

    const updated = await db.transaction(async (tx) => {
      await tx.select({ id: connectionGrants.id }).from(connectionGrants)
        .where(and(eq(connectionGrants.companyId, companyId), eq(connectionGrants.connectionId, connection.id)))
        .orderBy(connectionGrants.id).for("update");
      await tx.select({ id: toolApplications.id }).from(toolApplications)
        .where(and(eq(toolApplications.id, connection.applicationId), eq(toolApplications.companyId, companyId)))
        .for("update");
      await tx.select({ id: toolConnections.id }).from(toolConnections)
        .where(and(eq(toolConnections.id, connection.id), eq(toolConnections.companyId, companyId)))
        .for("update");
      for (const field of providedFields) {
        const value = input.credentialValues[field.configPath]!.trim();
        if (field.placement === "url" && !remoteUrlCredentialMatchesPublicUrl(String(connection.config.url ?? ""), value)) {
          throw badRequest("The replacement server URL must use the same endpoint as this connection.", {
            code: "mcp_remote_url_credential_mismatch",
          });
        }
        const existing = credentialSecretRefs.find(
          (ref) => ref.configPath === field.configPath,
        );
        const { secret } = await writeConnectionCredential(tx, {
          companyId, connectionName: connection.name, configPath: field.configPath,
          label: field.label, value, ownerUserId: personalIdentity?.subjectUserId,
          existingRef: existing, actor: actorForSecret(actor),
        });
        const nextRef = { secretId: secret.id, versionSelector: "latest" as const,
          configPath: field.configPath, required: field.required ?? true, label: field.label };
        const refIndex = credentialSecretRefs.findIndex((ref) => ref.configPath === field.configPath);
        if (refIndex >= 0) credentialSecretRefs[refIndex] = nextRef;
        else credentialSecretRefs.push(nextRef);
        if ((field.placement === "header" && field.key) || field.placement === "url") {
          const nextCredentialRef = {
            name: field.configPath,
            secretId: secret.id,
            version: "latest",
            placement: field.placement,
            key: field.key ?? "url",
            prefix: field.prefix ?? null,
          } satisfies McpConnectionCredentialRef;
          const existingCredentialRefIndex = credentialRefs.findIndex(
            (ref) => credentialRefConfigPath(ref) === field.configPath,
          );
          if (existingCredentialRefIndex >= 0)
            credentialRefs[existingCredentialRefIndex] = nextCredentialRef;
          else credentialRefs.push(nextCredentialRef);
        }
      }

      const updatedAt = new Date();
      if (personalIdentity) {
        const grantValues = {
          credentialSecretRefs,
          status: "active" as const,
          revokedAt: null,
          revokedByAgentId: null,
          revokedByUserId: null,
          updatedAt,
        };
        if (personalIdentity.grant) {
          await tx
            .update(connectionGrants)
            .set(grantValues)
            .where(eq(connectionGrants.id, personalIdentity.grant.id));
        } else {
          await tx.insert(connectionGrants).values({
            companyId: connection.companyId,
            connectionId: connection.id,
            kind: "user",
            subjectUserId: personalIdentity.subjectUserId,
            ...grantValues,
            isDefault: false,
            createdByUserId: personalIdentity.subjectUserId,
          });
        }
      }
      const [nextConnection] = await tx
        .update(toolConnections)
        .set({
          credentialRefs,
          // Personal reconnect rotates the existing user's grant. The
          // connection-level organization slot stays exactly as it was.
          credentialSecretRefs: personalIdentity
            ? connection.credentialSecretRefs
            : credentialSecretRefs,
          lastError: null,
          updatedAt,
        })
        .where(eq(toolConnections.id, connection.id))
        .returning();
      await syncConnectionCredentialBindings(tx, nextConnection,
        personalIdentity ? credentialSecretRefs : []);
      return nextConnection;
    });
    const health = await checkConnectionHealth(updated.id, actor);
    const refresh = await refreshCatalog(updated.id, actor, {
      enableAllByDefault: true,
    });
    return { ...health, connection: refresh.connection };
  }

  async function preflightGalleryAppMetadata(
    galleryKey: string,
    methodKey?: string | null,
  ): Promise<ToolAppMetadataPreflightResult> {
    const app = getConnectableAppDefinition(galleryKey);
    if (!app || app.availability?.available === false)
      throw notFound("App not found");
    const method = connectionMethodFor(app, methodKey);
    await assertExperimentalConnectorSetupEnabled(app.slug);
    if (method.transport !== "mcp_remote" || !method.defaults?.serverUrl) {
      throw unprocessable(
        "This app method does not use a hosted remote MCP endpoint",
      );
    }

    const serverUrl = await assertRemoteHttpUrlAllowed(
      method.defaults.serverUrl,
    );
    return preflightConnectionMetadata(app, method, method.defaults, serverUrl, () => options.now?.() ?? new Date());
  }

  return {
    /** Identity-only verification: no bot installation/repository access required. */
    verifyPersonalGitHubIdentity: async (companyId: string, connectionId: string, userId: string) => {
      const [connection] = await db.select().from(toolConnections).where(and(eq(toolConnections.companyId, companyId), eq(toolConnections.id, connectionId), eq(toolConnections.enabled, true)));
      if (!connection || (connection.config.sourceTemplateKey !== "github" && connection.transportConfig?.sourceTemplateKey !== "github")) throw notFound("GitHub connection not found");
      const [ownGrant] = await db.select().from(connectionGrants).where(and(eq(connectionGrants.companyId, companyId), eq(connectionGrants.connectionId, connectionId), eq(connectionGrants.kind, "user"), eq(connectionGrants.subjectUserId, userId), eq(connectionGrants.status, "active")));
      if (!ownGrant) throw forbidden("Connect your own GitHub account first. Shared and agent connections cannot prove your identity.");
      const actor = { actorType: "user" as const, actorId: userId };
      const grant = await refreshOAuthGrantCredentials({ companyId, connectionId, grantId: ownGrant.id, actor });
      const accessRef = grant.credentialSecretRefs.find(ref => ref.configPath === "oauth.access_token");
      if (!accessRef) throw unprocessable("Reconnect your personal GitHub connection");
      const { value } = await resolveOAuthGrantSecret(connection, grant, accessRef, actor, undefined);
      const identity = await githubBotRequest<{ id?: number; login?: string; avatar_url?: string }>(fetch, value, "/user");
      if (!Number.isSafeInteger(identity.id) || !identity.id || !identity.login || !/^[a-zA-Z0-9][a-zA-Z0-9-]{0,38}$/.test(identity.login)) throw unprocessable("GitHub returned an invalid account identity");
      const [current] = await db.select({ id: connectionGrants.id }).from(connectionGrants).where(and(eq(connectionGrants.id, grant.id), eq(connectionGrants.companyId, companyId), eq(connectionGrants.subjectUserId, userId), eq(connectionGrants.status, "active")));
      if (!current) throw forbidden("Your GitHub connection was revoked. Connect it again.");
      return { githubUserId: String(identity.id), login: identity.login, avatarUrl: identity.avatar_url ?? null, connectionId, grantId: grant.id };
    },
    preflightGalleryAppMetadata,
    approvedStdioTemplates: async (
      companyId: string,
    ): Promise<ToolStdioCommandTemplate[]> => {
      const adminTemplates = await db
        .select()
        .from(toolStdioCommandTemplates)
        .where(eq(toolStdioCommandTemplates.companyId, companyId))
        .orderBy(asc(toolStdioCommandTemplates.templateKey));
      return [
        ...Object.keys(APPROVED_STDIO_TEMPLATES)
          .sort()
          .map((templateId) => builtInStdioTemplate(templateId)!),
        ...adminTemplates.map(toStdioCommandTemplate),
      ];
    },

    createStdioCommandTemplate: async (
      companyId: string,
      input: CreateToolStdioCommandTemplate,
      actor?: ActorInfo,
    ): Promise<ToolStdioCommandTemplate> => {
      await actor?.managementContext?.reauthorize();
      if (builtInStdioTemplate(input.templateId)) {
        throw conflict(
          "A built-in stdio template already uses this templateId",
        );
      }
      const existing = await getAdminStdioTemplate(companyId, input.templateId);
      if (existing)
        throw conflict("A stdio command template already uses this templateId");
      const tools = input.tools
        .map((tool) => normalizeToolDescriptor(tool))
        .filter((tool): tool is McpToolDescriptor => Boolean(tool));
      const [row] = await db
        .insert(toolStdioCommandTemplates)
        .values({
          companyId,
          templateKey: input.templateId,
          name: input.name,
          description: input.description ?? null,
          status: "active",
          command: input.command,
          args: input.args,
          envKeys: input.envKeys,
          tools,
          createdByAgentId:
            actor?.actorType === "agent" ? (actor.actorId ?? null) : null,
          createdByUserId:
            connectionActorUserId(actor),
        })
        .returning();
      return toStdioCommandTemplate(row);
    },

    disableStdioCommandTemplate: async (
      companyId: string,
      templateId: string,
    ): Promise<ToolStdioCommandTemplate> => {
      if (builtInStdioTemplate(templateId))
        throw unprocessable("Built-in stdio templates cannot be disabled");
      const existing = await getAdminStdioTemplate(companyId, templateId);
      if (!existing) throw notFound("Stdio command template not found");
      if (existing.status === "disabled")
        return toStdioCommandTemplate(existing);
      const at = now();
      const [row] = await db
        .update(toolStdioCommandTemplates)
        .set({ status: "disabled", disabledAt: at, updatedAt: at })
        .where(
          and(
            eq(toolStdioCommandTemplates.companyId, companyId),
            eq(toolStdioCommandTemplates.templateKey, templateId),
          ),
        )
        .returning();
      return toStdioCommandTemplate(row);
    },
    ...aggregatorAccounts,

    connectGalleryApp,

    finishGalleryAppConnection,

    reconnectGalleryApp,

    storeConnectorOAuthSecret: createOrRotateOAuthSecret,
    resolveConnectorOAuthGrantSecret: resolveOAuthGrantSecret,
    startOAuth,

    startAuthorizationForAgent: async (input: {
      companyId: string;
      connectionId: string;
      agentId: string;
      runId: string;
      subjectUserId: string;
      scopes?: string[];
      returnTo?: string;
      redirectUri: string;
      managementContext?: ConnectionManagementContext;
    }) => {
      await input.managementContext?.reauthorize();
      const runContext = await loadBrokerRunContext(input);
      const connection = await getConnectionRow(
        input.connectionId,
        input.companyId,
      );
      if (
        !runContext.responsibleUserId ||
        runContext.responsibleUserId !== input.subjectUserId
      ) {
        throw new HttpError(
          403,
          "The agent run cannot start authorization for the requested user",
          {
            code: "subject_not_permitted",
            connection: { uid: connection.uid },
            subject: { type: "user", userId: input.subjectUserId },
          },
        );
      }
      return startOAuth(input.companyId, connection.id, {
        redirectUri: input.redirectUri,
        actor: { actorType: "agent", actorId: input.agentId, ...input.managementContext?.audit, managementContext: input.managementContext },
        subjectUserId: input.subjectUserId,
        scopes: input.scopes,
        returnTo: input.returnTo,
        issueId: runContext.issueId ?? undefined,
      });
    },

    peekOAuthState,

    completePaperclipCloudConnectorCallback,

    completeVercelConnectCallback,

    completeOAuthCallback,
    refreshOAuthGrantCredentials,
    finalizeOAuthAccess,

    listExamples: async (companyId: string): Promise<ToolExampleSummary[]> => {
      return Promise.all(
        TOOL_EXAMPLES.map(async (definition) => {
          const rows = await exampleRows(companyId, definition);
          return exampleSummary(definition, rows);
        }),
      );
    },

    installExample: async (
      companyId: string,
      exampleId: string,
      actor?: ActorInfo,
    ): Promise<ToolExampleInstallResult> => {
      const definition = findExample(exampleId);
      const blocker = localStdioInstallBlocker();
      if (blocker) throw unprocessable(blocker);
      assertLocalStdioCanBeEnabled("local_stdio", true);
      await stdioTemplateId(companyId, { templateId: definition.templateId });
      const before = await exampleRows(companyId, definition);
      const application = await upsertExampleApplication(
        companyId,
        definition,
        before.application,
      );
      const connection = await upsertExampleConnection(
        companyId,
        definition,
        application.row.id,
        before.connection,
      );
      const refresh = await refreshCatalog(connection.row.id, actor);
      let catalog = refresh.catalog;
      const safeReadEntryIds = catalog
        .filter((entry) => entry.riskLevel === "read")
        .map((entry) => entry.id);
      if (safeReadEntryIds.length > 0) {
        const reviewedAt = new Date();
        await db
          .update(toolCatalogEntries)
          .set({
            status: "active",
            reviewedAt,
            reviewedByAgentId:
              actor?.actorType === "agent" ? (actor.actorId ?? null) : null,
            reviewedByUserId:
              connectionActorUserId(actor),
            quarantinedAt: null,
            quarantineReason: null,
            updatedAt: reviewedAt,
          })
          .where(
            and(
              eq(toolCatalogEntries.companyId, companyId),
              inArray(toolCatalogEntries.id, safeReadEntryIds),
            ),
          );
        catalog = catalog.map((entry) =>
          safeReadEntryIds.includes(entry.id)
            ? {
                ...entry,
                status: "active",
                reviewedAt,
                quarantinedAt: null,
                quarantineReason: null,
                updatedAt: reviewedAt,
              }
            : entry,
        );
      }
      const profile = await upsertExampleProfile(
        companyId,
        definition,
        before.profile,
      );
      const profileEntries = await syncExampleProfileEntries(
        companyId,
        profile.row.id,
        catalog,
      );
      const profileBinding = await upsertExampleProfileBinding(
        companyId,
        profile.row.id,
        before.profileBinding,
        actor,
      );
      const after = await exampleRows(companyId, definition);
      return {
        example: exampleSummary(definition, after),
        created:
          application.created ||
          connection.created ||
          profile.created ||
          !before.profileBinding,
        application: toApplication(application.row),
        connection: refresh.connection,
        profile: toProfile(profile.row),
        profileEntries,
        profileBinding,
        catalog,
      };
    },

    smokeExample: async (
      companyId: string,
      exampleId: string,
      actor?: ActorInfo,
    ): Promise<ToolExampleSmokeResult> => {
      const definition = findExample(exampleId);
      const rows = await exampleRows(companyId, definition);
      if (!rows.connection || !rows.profile || !rows.profileBinding) {
        throw conflict("Install this tool example before running smoke checks");
      }
      const catalog =
        rows.catalog.length > 0
          ? rows.catalog.map(toCatalogEntry)
          : (await refreshCatalog(rows.connection.id, actor)).catalog;
      const readEntry = catalog.find(
        (entry) => entry.riskLevel === "read" && entry.status === "active",
      );
      const deniedEntry = catalog.find(
        (entry) =>
          entry.riskLevel === "write" || entry.riskLevel === "destructive",
      );
      if (!readEntry || !deniedEntry) {
        throw unprocessable(
          "Example smoke requires at least one read tool and one denied write/destructive tool",
        );
      }
      const smokeActor = await exampleSmokeActor(companyId, actor);
      const connection = toConnection(rows.connection);
      const allowCheck = await runSmokeDecisionCheck({
        companyId,
        actor: smokeActor,
        connection,
        catalogEntry: readEntry,
        expectedDecision: "allow",
        name: "allow_read_tool",
      });
      const denyCheck = await runSmokeDecisionCheck({
        companyId,
        actor: smokeActor,
        connection,
        catalogEntry: deniedEntry,
        expectedDecision: "deny",
        name: "deny_write_tool",
      });
      const auditCheck: ToolExampleSmokeCheck = {
        name: "audit_written",
        ok: Boolean(
          allowCheck.auditEventId &&
          allowCheck.toolCallEventId &&
          denyCheck.auditEventId &&
          denyCheck.toolCallEventId,
        ),
        details: {
          auditEventIds: [allowCheck.auditEventId, denyCheck.auditEventId],
          toolCallEventIds: [
            allowCheck.toolCallEventId,
            denyCheck.toolCallEventId,
          ],
        },
      };
      const checks = [allowCheck, denyCheck, auditCheck];
      return {
        exampleId: definition.id,
        ok: checks.every((check) => check.ok),
        actor: smokeActor,
        connection,
        profile: toProfile(rows.profile),
        checks,
      };
    },

    listApplications: async (companyId: string): Promise<ToolApplication[]> => {
      const rows = await db
        .select()
        .from(toolApplications)
        .where(eq(toolApplications.companyId, companyId))
        .orderBy(desc(toolApplications.updatedAt));
      return rows.map(toApplication);
    },

    createApplication: async (
      companyId: string,
      input: CreateToolApplication,
      managementContext?: ConnectionManagementContext,
    ): Promise<ToolApplication> => {
      await assertOptionalPlugin(input.pluginId);
      await assertOptionalAgent(
        companyId,
        input.ownerAgentId,
        "Tool application owner agent",
      );
      await managementContext?.reauthorize();
      const [row] = await db
        .insert(toolApplications)
        .values({
          companyId,
          applicationKey: input.applicationKey ?? normalizeKey(input.name),
          name: input.name,
          description: input.description ?? null,
          type: input.type,
          status: input.status ?? "active",
          pluginId: input.pluginId ?? null,
          ownerAgentId: input.ownerAgentId ?? null,
          ownerUserId: input.ownerUserId ?? null,
          metadata: input.metadata ?? {},
        })
        .returning();
      return toApplication(row);
    },

    getApplication: async (
      applicationId: string,
      companyId?: string,
    ): Promise<ToolApplication> => {
      const where = companyId
        ? and(
            eq(toolApplications.id, applicationId),
            eq(toolApplications.companyId, companyId),
          )
        : eq(toolApplications.id, applicationId);
      const [row] = await db.select().from(toolApplications).where(where);
      if (!row) throw notFound("Tool application not found");
      return toApplication(row);
    },

    updateApplication: async (
      applicationId: string,
      input: UpdateToolApplication,
      managementContext?: ConnectionManagementContext,
    ): Promise<ToolApplication> => {
      const [existing] = await db
        .select()
        .from(toolApplications)
        .where(eq(toolApplications.id, applicationId));
      if (!existing) throw notFound("Tool application not found");
      await assertOptionalPlugin(input.pluginId);
      await assertOptionalAgent(
        existing.companyId,
        input.ownerAgentId,
        "Tool application owner agent",
      );
      if (input.name && input.name !== existing.name) {
        const [duplicate] = await db
          .select({ id: toolApplications.id })
          .from(toolApplications)
          .where(
            and(
              eq(toolApplications.companyId, existing.companyId),
              eq(toolApplications.name, input.name),
              ne(toolApplications.id, applicationId),
            ),
          )
          .limit(1);
        if (duplicate) {
          throw conflict("A tool access record with that name already exists", {
            code: "tool_access_name_conflict",
          });
        }
      }
      await managementContext?.reauthorize();
      const [row] = await db
        .update(toolApplications)
        .set({
          name: input.name ?? existing.name,
          description: input.description ?? existing.description,
          status: input.status ?? existing.status,
          pluginId: input.pluginId ?? existing.pluginId,
          ownerAgentId: input.ownerAgentId ?? existing.ownerAgentId,
          ownerUserId: input.ownerUserId ?? existing.ownerUserId,
          metadata: input.metadata ?? existing.metadata,
          updatedAt: new Date(),
        })
        .where(eq(toolApplications.id, applicationId))
        .returning();
      return toApplication(row);
    },

    deleteApplication: async (
      applicationId: string,
      managementContext?: ConnectionManagementContext,
    ): Promise<ToolApplication> => {
      const [existing] = await db
        .select()
        .from(toolApplications)
        .where(eq(toolApplications.id, applicationId));
      if (!existing) throw notFound("Tool application not found");
      // Guard: never orphan connections. The caller must remove the connections
      // or archive the application instead — there is no force-cascade in v1.
      const linkedConnections = await db
        .select({ id: toolConnections.id })
        .from(toolConnections)
        .where(eq(toolConnections.applicationId, applicationId));
      if (linkedConnections.length > 0) {
        throw conflict(
          "This application still has connections. Remove its connections or archive the application instead of deleting it.",
          { connectionCount: linkedConnections.length },
        );
      }
      // The pre-check above gives a friendly 409 in the common case, but it cannot close the
      // race where a connection is created in the gap before this delete runs. The FK is now
      // ON DELETE RESTRICT, so such a delete fails closed with a foreign_key_violation instead
      // of silently cascading the new connection away. Translate that into the same 409 so the
      // endpoint keeps its contract instead of surfacing a 500.
      await managementContext?.reauthorize();
      let row: typeof toolApplications.$inferSelect | undefined;
      try {
        [row] = await db
          .delete(toolApplications)
          .where(eq(toolApplications.id, applicationId))
          .returning();
      } catch (error) {
        if (isToolConnectionForeignKeyViolation(error)) {
          throw conflict(
            "This application still has connections. Remove its connections or archive the application instead of deleting it.",
          );
        }
        throw error;
      }
      if (!row) throw notFound("Tool application not found");
      return toApplication(row);
    },

    // Repository discovery uses credential audiences, not connection-management
    // visibility. An administrator cannot browse another user's private repos.
    listProjectRepositories: async (companyId: string, userId: string | null, localTrusted = false) =>
      toolAccessService(db).listGitHubRepositories(companyId, userId, localTrusted),

    // Return identifiers, never credentials, so each attempted read can recheck its grant.
    githubReadConnectionIds: async (companyId: string, userId: string | null, localTrusted = false): Promise<string[]> => {
      const connections = await db.select().from(toolConnections).where(and(eq(toolConnections.companyId, companyId), eq(toolConnections.enabled, true))).orderBy(desc(toolConnections.updatedAt));
      const ids: string[] = [];
      for (const connection of connections) {
        if (connection.status !== "active" || asRecord(connection.config).sourceTemplateKey !== "github") continue;
        try {
          await gitHubReadGrantAccess(db, companyId, connection.id, userId, localTrusted);
          ids.push(connection.id);
        } catch (error) {
          // Only ineligible grants are skipped; database/service failures must surface.
          if (!(error instanceof Error && "status" in error && error.status === 403)) throw error;
        }
      }
      return ids;
    },

    githubReadGrantIds: async (companyId: string, connectionId: string, userId: string | null, localTrusted = false): Promise<Array<string | null>> => {
      const { allowed, legacyShared } = await gitHubReadGrantAccess(db, companyId, connectionId, userId, localTrusted);
      return legacyShared ? [null] : allowed.map(grant => grant.id);
    },

    // Server-side reads share the same grant audience and credential lifecycle as discovery.
    githubReadHeaders: async (companyId: string, connectionId: string, userId: string | null, localTrusted = false, forceRefresh = false, grantId?: string | null): Promise<Record<string, string>> => {
      const { connection, allowed, legacyShared } = await gitHubReadGrantAccess(db, companyId, connectionId, userId, localTrusted);
      const actor: ActorInfo = { actorType: "user", actorId: userId ?? "board" };
      if (legacyShared && !grantId) return resolveCredentialHeaders(connection, actor);
      let grant = grantId ? allowed.find(candidate => candidate.id === grantId) : allowed.length === 1 ? allowed[0] : undefined;
      if (!grant) throw forbidden("Choose an active GitHub authorization you can use.");
      if (asRecord(asRecord(connection.config).oauth).connectorProfile === "github.code") {
        grant = await refreshOAuthGrantCredentials({ companyId, connectionId, grantId: grant.id, actor, forceRefresh });
      }
      const ref = grant.credentialSecretRefs.find(ref => ref.configPath === "oauth.access_token" || /authorization|token|api_key/i.test(ref.configPath));
      if (!ref) throw unprocessable("Reconnect GitHub to read repository files.");
      const secret = await resolveOAuthGrantSecret(connection, grant, ref, actor, undefined);
      return { Authorization: `Bearer ${secret.value}` };
    },

    listGitHubRepositories: async (
      companyId: string,
      userId: string | null,
      localTrusted = false,
    ) => measureRunPhase("connectors.github.catalog", async () => {
      const [connections, grants, members, memberships] = await Promise.all([
        measureRunPhase("connectors.github.connections", () => db
          .select()
          .from(toolConnections)
          .where(
            and(
              eq(toolConnections.companyId, companyId),
              eq(toolConnections.enabled, true),
            ),
          )),
        measureRunPhase("connectors.github.grants", () => db
          .select()
          .from(connectionGrants)
          .where(eq(connectionGrants.companyId, companyId))),
        measureRunPhase("connectors.github.grant_members", () => db
          .select()
          .from(connectionGrantMembers)
          .where(eq(connectionGrantMembers.companyId, companyId))),
        userId
          ? measureRunPhase("connectors.github.membership", () => db
              .select()
              .from(companyMemberships)
              .where(
                and(
                  eq(companyMemberships.companyId, companyId),
                  eq(companyMemberships.principalType, "user"),
                  eq(companyMemberships.principalId, userId),
                  eq(companyMemberships.status, "active"),
                ),
              ))
          : Promise.resolve([]),
      ]);
      const repositories = new Map<
        string,
        import("@paperclipai/shared").ProjectRepository
      >();
      const usableConnections: Array<{ id: string; name: string }> = [];
      let connectionCount = 0;
      let failedConnectionCount = 0;
      for (const connection of connections) {
        if (
          connection.status !== "active" ||
          asRecord(connection.config).sourceTemplateKey !== "github"
        )
          continue;
        const connectionGrants = grants.filter(
          (grant) => grant.connectionId === connection.id,
        );
        const availableGrants = connectionGrants.filter(
          (grant) =>
            !(
              grant.kind === "organization" &&
              ["per_user", "per_agent"].includes(connection.credentialPolicy)
            ) &&
            canBrowseProjectRepositoryGrant({
              grant,
              userId,
              activeMember: localTrusted || memberships.length > 0,
              audience: members
                .filter((member) => member.grantId === grant.id)
                .map((member) => member.subjectId),
            }),
        );
        // Legacy shared PAT connections predate grants. Never fall back when a
        // grant exists but is revoked, private, or outside the caller's audience.
        const legacyShared =
          connectionGrants.length === 0 &&
          connection.credentialPolicy === "shared" &&
          (localTrusted || (!!userId && memberships.length > 0));
        if (!availableGrants.length && !legacyShared) continue;
        connectionCount += 1;
        usableConnections.push({ id: connection.id, name: connection.name });
        const actor: ActorInfo = {
          actorType: "user",
          actorId: userId ?? "board",
        };
        let failed = false;
        for (const initialGrant of legacyShared ? [null] : availableGrants) {
          try {
            let rows: Array<{
              id: string;
              fullName: string;
              private?: boolean;
            }>;
            if (
              initialGrant &&
              asRecord(asRecord(connection.config).oauth).connectorProfile ===
                "github.code"
            ) {
              const grant = await refreshManagedGitHubGrantAccess(
                connection,
                initialGrant,
                actor,
              );
              rows = grant.providerTenant?.github?.repositories ?? [];
            } else {
              const headers = await measureRunPhase("connectors.github.credentials", () => initialGrant
                ? (async () => {
                    const ref = initialGrant.credentialSecretRefs.find(
                      (ref) =>
                        ref.configPath === "oauth.access_token" ||
                        /authorization|token|api_key/i.test(ref.configPath),
                    );
                    if (!ref)
                      throw unprocessable(
                        "Reconnect GitHub to load repositories",
                      );
                    const secret = await resolveOAuthGrantSecret(
                      connection,
                      initialGrant,
                      ref,
                      actor,
                      undefined,
                    );
                    return { Authorization: `Bearer ${secret.value}` };
                  })()
                : resolveCredentialHeaders(connection, actor));
              rows = await measureRunPhase("connectors.github.repositories", () => loadGitHubTokenRepositories(headers));
            }
            for (const row of rows) {
              mergeProjectRepository(repositories, row, connection.name, connection.id);
            }
          } catch {
            // Credential/provider errors may contain secrets. Only expose an
            // aggregate failure; successful connections remain usable.
            failed = true;
          }
        }
        if (failed) failedConnectionCount += 1;
      }
      return {
        repositories: [...repositories.values()].sort((a, b) =>
          a.fullName.localeCompare(b.fullName),
        ),
        connections: usableConnections,
        connectionCount,
        failedConnectionCount,
      };
    }),

    listConnections: async (
      companyId: string,
      viewerUserId?: string,
    ): Promise<ToolConnection[]> => {
      const rows = await db
        .select()
        .from(toolConnections)
        .where(eq(toolConnections.companyId, companyId))
        .orderBy(desc(toolConnections.updatedAt));
      const connections = rows.map(toConnection);
      if (connections.length === 0) return connections;
      const installRows = await db
        .select()
        .from(toolConnectionInstalls)
        .where(eq(toolConnectionInstalls.companyId, companyId))
        .orderBy(
          asc(toolConnectionInstalls.targetType),
          asc(toolConnectionInstalls.targetId),
        );
      const installsByConnection = new Map<string, ToolConnectionInstall[]>();
      for (const row of installRows) {
        const installs = installsByConnection.get(row.connectionId) ?? [];
        installs.push(toConnectionInstall(row));
        installsByConnection.set(row.connectionId, installs);
      }
      for (const connection of connections)
        connection.installs = installsByConnection.get(connection.id) ?? [];
      // Enrich with "last used" = most recent tool-call event per connection so the
      // prosumer Apps list can surface a staleness signal without an N+1 fan-out.
      const lastUsedRows = await db
        .select({
          connectionId: toolCallEvents.connectionId,
          lastUsedAt: max(toolCallEvents.createdAt),
        })
        .from(toolCallEvents)
        .where(
          and(
            eq(toolCallEvents.companyId, companyId),
            inArray(
              toolCallEvents.connectionId,
              connections.map((connection) => connection.id),
            ),
          ),
        )
        .groupBy(toolCallEvents.connectionId);
      const lastUsedByConnection = new Map(
        lastUsedRows.map((row) => [row.connectionId, row.lastUsedAt]),
      );
      for (const connection of connections) {
        connection.lastUsedAt = lastUsedByConnection.get(connection.id) ?? null;
      }
      await annotateAiGrantHealth(connections);
      await annotateGitHubAuthorization(connections, viewerUserId);
      await annotateSavedOAuthClientSecret(connections, viewerUserId);
      return connections;
    },

    createConnection: async (
      companyId: string,
      input: CreateToolConnection,
      actor?: ActorInfo,
    ): Promise<ToolConnection> => {
      await actor?.managementContext?.reauthorize();
      let applicationId = input.applicationId;
      let applicationNamespace = input.applicationName ?? input.name;
      const transport = input.transport;
      if (!transport) throw badRequest("Tool connection transport is required");
      const config = normalizeGoogleSheetsConnectionConfig(
        input.config ?? input.transportConfig ?? {},
      );
      await assertConnectorConnectionSetupEnabled({ config, applicationId, companyId });
      // Validate company-scoped references before touching a caller-supplied
      // network endpoint. Besides failing fast, this keeps cross-company
      // authorization errors from being masked by DNS or SSRF validation.
      await assertSecretRefs(companyId, [
        ...(input.credentialRefs ?? []),
        ...(input.credentialSecretRefs ?? []),
      ]);
      if (transport === "mcp_remote")
        await assertRemoteConnectionEndpointsAllowed(config);
      if (transport === "local_stdio") await stdioTemplateId(companyId, config);
      assertLocalStdioCanBeEnabled(transport, input.enabled ?? false, config);
      await assertGoogleSheetsSpreadsheetOwnership(companyId, config);
      if (applicationId) {
        const app = await assertApplication(companyId, applicationId);
        applicationNamespace = app.applicationKey ?? app.name;
        await assertConnectorConnectionSetupEnabled({ config }, applicationNamespace);
        if (
          (transport === "mcp_remote" && app.type !== "mcp_http") ||
          (transport === "local_stdio" && app.type !== "mcp_stdio")
        ) {
          throw unprocessable(
            "Connection transport must match application type",
          );
        }
      } else {
        const [app] = await db
          .insert(toolApplications)
          .values({
            companyId,
            applicationKey: normalizeKey(input.applicationName ?? input.name),
            name: input.applicationName ?? input.name,
            type: isBrowserUseConnection({ transport, config }) || nativeProviderCatalogFor({ transport, config }) || restConnectorFor({ transport, config }) ? "rest_api" : transport === "mcp_remote" ? "mcp_http" : "mcp_stdio",
            status: "active",
            metadata: {},
          })
          .returning();
        applicationId = app.id;
      }
      await actor?.managementContext?.reauthorize();
      const connectionId = randomUUID();
      const binding = actorBinding(actor);
      const row = await writeToolConnectionHealthChange(db, { companyId, id: connectionId }, async tx => {
        const [row] = await tx
          .insert(toolConnections)
          .values({
            id: connectionId,
            companyId,
            applicationId,
            name: input.name,
            uid: connectionUid(applicationNamespace, input.name, connectionId),
            connectionKind: input.connectionKind ?? "managed",
            ownership: input.ownership ?? "customer",
            transport,
            authKind: input.authKind ?? "none",
            credentialPolicy:
              input.credentialPolicy ??
              (input.authKind === "oauth" ? "per_user" : "shared"),
            status: input.status ?? "draft",
            enabled: input.enabled ?? false,
            agentInstructions: input.agentInstructions !== undefined ? input.agentInstructions : defaultConnectionAgentInstructions(
              typeof config.sourceTemplateKey === "string" ? getConnectableAppDefinition(config.sourceTemplateKey)?.agentInstructions : null,
            ),
            config,
            transportConfig: isGoogleSheetsConnectionConfig(config)
              ? config
              : (input.transportConfig ?? config),
            credentialRefs: input.credentialRefs ?? [],
            credentialSecretRefs: input.credentialSecretRefs ?? [],
            createdByAgentId:
              binding.actorType === "agent" ? binding.actorId : null,
            createdByUserId: connectionActorUserId(actor),
          })
          .returning();
        await ensureDefaultOrganizationGrant(row, tx);
        await syncCredentialBindings(row, [], tx);
        await createToolRuntimeSlots(tx, runtimeSupervisor).ensureRuntimeSlot(row);
        return row;
      });
      emitConnectionCreated(row, "api");
      return toConnection(row);
    },

    getConnection: async (
      connectionId: string,
      companyId?: string,
      viewerUserId?: string,
    ): Promise<ToolConnection> => {
      const connection = toConnection(
        await getConnectionRow(connectionId, companyId),
      );
      connection.installs = await listConnectionInstalls(
        connection.id,
        connection.companyId,
      );
      await annotateAiGrantHealth([connection]);
      await annotateGitHubAuthorization([connection], viewerUserId);
      await annotateSavedOAuthClientSecret([connection], viewerUserId);
      return connection;
    },
    ...connectionGrantsService,
    ...toolActivity,

    listConnectionInstalls,
    putConnectionInstalls: connectionInstalls.putConnectionInstalls,

    updateConnection: async (
      connectionId: string,
      input: UpdateToolConnection,
      managementContext?: ConnectionManagementContext,
    ): Promise<ToolConnection> => {
      const existing = await getConnectionRow(connectionId);
      if (managementContext?.actor.type === "agent" && existing.connectionPurpose === "channel"
        && (input.credentialRefs !== undefined || input.credentialSecretRefs !== undefined)) {
        throw forbidden("Use chat endpoint setup to change channel credentials; verification keys require human entry", {
          code: "chat_endpoint_credentials_require_setup",
        });
      }
      if (existing.connectionPurpose === "ai" && (input.config || input.transportConfig || input.credentialRefs || input.credentialSecretRefs || (input.credentialPolicy && input.credentialPolicy !== existing.credentialPolicy))) throw badRequest("Use AI account reconnect to change credentials. Provider, sign-in method, and ownership cannot be changed.");
      const config = normalizeGoogleSheetsConnectionConfig(
        input.config ?? input.transportConfig ?? existing.config,
      );
      if (input.config?.methodConfig !== undefined && typeof config.sourceTemplateKey === "string") {
        const app = getConnectableAppDefinition(config.sourceTemplateKey);
        if (app) normalizeConnectionMethodConfig(connectionMethodForConnection(app, { ...existing, config }), asRecord(config.methodConfig));
      }
      if (existing.transport === "mcp_remote")
        await assertRemoteConnectionEndpointsAllowed(config);
      if (existing.transport === "local_stdio")
        await stdioTemplateId(existing.companyId, config);
      assertLocalStdioCanBeEnabled(
        existing.transport,
        input.enabled ?? existing.enabled,
        config,
      );
      await assertGoogleSheetsSpreadsheetOwnership(existing.companyId, config, {
        excludeConnectionId: existing.id,
      });
      await assertSecretRefs(existing.companyId, [
        ...(input.credentialRefs ?? existing.credentialRefs),
        ...(input.credentialSecretRefs ?? existing.credentialSecretRefs),
      ]);
      await managementContext?.reauthorize();
      const write = (database: Db) => database
        .update(toolConnections)
        .set({
          name: input.name ?? existing.name,
          status: input.status ?? existing.status,
          enabled: input.enabled ?? existing.enabled,
          ...(input.agentInstructions !== undefined ? { agentInstructions: input.agentInstructions } : {}),
          config,
          transportConfig: isGoogleSheetsConnectionConfig(config)
            ? config
            : (input.transportConfig ?? config),
          credentialRefs: input.credentialRefs ?? existing.credentialRefs,
          credentialSecretRefs:
            input.credentialSecretRefs ?? existing.credentialSecretRefs,
          credentialPolicy: input.credentialPolicy ?? existing.credentialPolicy,
          updatedAt: new Date(),
        })
        .where(eq(toolConnections.id, connectionId))
        .returning();
      const [row] = existing.transport === "chat_sdk"
        ? await db.transaction(async tx => {
            await notifyChatEndpointWork(tx, existing.id, existing.companyId);
            const rows = await write(tx as unknown as Db);
            // Credential resolution must never observe the binding rebuild's
            // delete/insert gap after a configuration wake.
            await syncCredentialBindings(rows[0]!, [], tx);
            return rows;
          })
        : await writeToolConnectionHealthChange(db, existing, async tx => {
            if (existing.transport === "voice") await notifyVoiceChange(tx, { kind: "connection", id: existing.id });
            const rows = await write(tx);
            await syncCredentialBindings(rows[0]!, [], tx);
            await createToolRuntimeSlots(tx, runtimeSupervisor).ensureRuntimeSlot(rows[0]!);
            return rows;
          });
      emitConnectionUpdated(row, existing, "api");
      return toConnection(row);
    },

    archiveConnection: removeConnection,

    checkHealth: checkConnectionHealth,

    refreshCatalog,

    configureRailwaySsh: async (connectionId: string, companyId: string, input: ConfigureRailwaySsh, actor: ActorInfo): Promise<RailwaySshSetup | null> => {
      await actor.managementContext?.reauthorize();
      const knownHosts = input.action === "enable" ? validateRailwayKnownHosts(input.knownHosts) : "";
      const setup = await db.transaction(async (tx) => {
        const [grant] = await tx.select().from(connectionGrants).where(and(eq(connectionGrants.id, input.grantId), eq(connectionGrants.connectionId, connectionId), eq(connectionGrants.companyId, companyId))).for("update");
        const [connection] = await tx.select().from(toolConnections).where(and(eq(toolConnections.id, connectionId), eq(toolConnections.companyId, companyId))).for("update");
        if (!connection || !isRailwayConnection(connection) || (connection.status !== "active" && input.action !== "remove")) throw unprocessable("Connect Railway before configuring container access.");
        if (!grant || (grant.status !== "active" && input.action !== "remove")) throw unprocessable("Select an active Railway authorization.");
        if (grant.kind === "user" && connectionActorUserId(actor) !== grant.subjectUserId) throw forbidden("Only this authorization's owner can configure its SSH key.");
        const existing = asRecord(connection.config.railwaySsh);
        if (existing.grantId && existing.grantId !== grant.id) throw conflict("Remove the existing container key before choosing another authorization.");
        const currentRef = grant.credentialSecretRefs.find((ref) => ref.configPath === RAILWAY_SSH_SECRET_PATH);
        let next: RailwaySshSetup | null = null;
        let refs = grant.credentialSecretRefs;
        if (input.action === "remove") {
          if (currentRef) await secretService(tx).remove(currentRef.secretId);
          refs = refs.filter((ref) => ref.configPath !== RAILWAY_SSH_SECRET_PATH);
        } else if (input.action === "prepare") {
          if (currentRef && typeof existing.publicKey === "string") return existing as unknown as RailwaySshSetup;
          const key = await generateRailwaySshKey();
          const ref = await createOrRotateOAuthSecret({ companyId, connection, configPath: RAILWAY_SSH_SECRET_PATH, label: "Railway container SSH key", value: key.privateKey, existingRefs: [], ownerUserId: grant.kind === "user" ? grant.subjectUserId ?? undefined : undefined, actor }, { dbClient: tx, secretClient: secretService(tx) });
          refs = [...refs.filter((ref) => ref.configPath !== RAILWAY_SSH_SECRET_PATH), ref];
          next = { grantId: grant.id, publicKey: key.publicKey, knownHosts: "", enabled: false };
        } else {
          if (!currentRef || typeof existing.publicKey !== "string") throw unprocessable("Generate and register a container key first.");
          next = { grantId: grant.id, publicKey: existing.publicKey, knownHosts, enabled: true };
        }
        await tx.update(connectionGrants).set({ credentialSecretRefs: refs, updatedAt: now() }).where(and(eq(connectionGrants.id, grant.id), eq(connectionGrants.companyId, companyId)));
        const config = { ...connection.config, railwaySsh: next };
        const [updated] = await tx.update(toolConnections).set({ config, transportConfig: config, updatedAt: now() }).where(and(eq(toolConnections.id, connectionId), eq(toolConnections.companyId, companyId))).returning();
        await syncCredentialBindings(updated, [], tx);
        return next;
      });
      await audit({ companyId, connectionId, action: "tool_connection.railway_ssh_updated", outcome: "success", actor, details: { action: input.action, grantId: input.grantId, enabled: setup?.enabled ?? false } });
      return setup;
    },

    listAppsNeedingAttention,

    sweepConnectionHealth,
    scheduledHealth: connectionHealthSchedule(db, checkConnectionHealth),

    sweepGitHubConnectionContinuity,
    ...catalogReader,
    ...toolActionReviewQueue,
    ...profileService,
    ...profileResolver,
    mintConnectionTokenForAgent,
    ...runtimeSlots.api,

    getRuntimeHealth: runtimeHealth,

    previewMcpJsonImport: async (
      input: ImportMcpJson,
    ): Promise<McpJsonImportPreview> => {
      let raw: unknown;
      try {
        raw =
          typeof input.mcpJson === "string"
            ? (JSON.parse(input.mcpJson) as unknown)
            : input.mcpJson;
      } catch {
        throw badRequest("mcp.json must be valid JSON");
      }
      const mcpServers = asRecord(asRecord(raw).mcpServers);
      const drafts = Object.entries(mcpServers).map(([name, rawServer]) => {
        const server = asRecord(rawServer);
        const warnings: string[] = [];
        if (
          typeof server.url === "string" ||
          typeof server.endpoint === "string"
        ) {
          const headers = asRecord(server.headers);
          const credentialFields = Object.keys(headers)
            .sort()
            .map((key) => {
              warnings.push(
                `Header ${key} will be stored as a Paperclip secret before activation.`,
              );
              return {
                configPath: `headers.${key}`,
                label: key,
                placement: "header" as const,
                key,
                prefix: null,
                required: true,
              };
            });
          return {
            name,
            transport: "mcp_remote" as const,
            status: "draft" as const,
            config: { url: server.url ?? server.endpoint },
            credentialRefs: [] as McpConnectionCredentialRef[],
            credentialFields,
            warnings,
          };
        }
        if (typeof server.command === "string") {
          warnings.push(
            "Imported stdio commands stay draft-only unless mapped to an approved Paperclip template.",
          );
          return {
            name,
            transport: "local_stdio" as const,
            status: "draft" as const,
            config: {
              importedCommand: server.command,
              importedArgs: Array.isArray(server.args) ? server.args : [],
            },
            credentialRefs: [],
            credentialFields: [],
            warnings,
          };
        }
        warnings.push("Unsupported MCP server entry.");
        return {
          name,
          transport: "mcp_remote" as const,
          status: "draft" as const,
          config: {},
          credentialRefs: [],
          credentialFields: [],
          warnings,
        };
      });
      if (drafts.length === 0)
        throw badRequest("mcp.json must include an mcpServers object");
      return { drafts };
    },

    assertConnectionCompany: async (
      connectionId: string,
      companyId: string,
    ) => {
      const connection = await getConnectionRow(connectionId, companyId);
      return toConnection(connection);
    },

    ensureNoDuplicateNameError: (error: unknown) => {
      const maybeRecord =
        typeof error === "object" && error !== null
          ? (error as Record<string, unknown>)
          : null;
      const cause = maybeRecord?.cause;
      const maybeCause =
        typeof cause === "object" && cause !== null
          ? (cause as Record<string, unknown>)
          : null;
      const message = [
        error instanceof Error ? error.message : String(error),
        maybeRecord && typeof maybeRecord.detail === "string"
          ? maybeRecord.detail
          : null,
        maybeCause instanceof Error ? maybeCause.message : null,
        maybeCause && typeof maybeCause.detail === "string"
          ? maybeCause.detail
          : null,
      ]
        .filter(Boolean)
        .join("\n");
      const code =
        maybeRecord && typeof maybeRecord.code === "string"
          ? maybeRecord.code
          : maybeCause && typeof maybeCause.code === "string"
            ? maybeCause.code
            : null;
      const constraint =
        maybeRecord && typeof maybeRecord.constraint === "string"
          ? maybeRecord.constraint
          : maybeRecord && typeof maybeRecord.constraint_name === "string"
            ? maybeRecord.constraint_name
            : maybeCause && typeof maybeCause.constraint === "string"
              ? maybeCause.constraint
              : maybeCause && typeof maybeCause.constraint_name === "string"
                ? maybeCause.constraint_name
                : null;
      if (
        code === "23505" ||
        constraint?.includes("tool_applications") ||
        /duplicate key value|unique constraint|tool_applications_company_id_name_unique/i.test(
          message,
        )
      ) {
        throw conflict("A tool access record with that name already exists", {
          code: "tool_access_name_conflict",
        });
      }
      throw error;
    },
  };
}