Skip to content

Open-source AI coworkers that each get a computer of their own: a browser, files and tools, with every action decided before it happens and recorded after. Bring any AG-UI agent.

118 KB
Raw Blame
import { and, asc, eq, inArray, isNull, sql } from "drizzle-orm";
import { recordAuditEvent } from "../../audit";
import {
  databaseComplaint,
  isQueryFailure,
  reasonWithoutStatement,
  withoutStatement,
} from "../../db/query-failure";
import {
  brokeredConnections,
  credentials as credentialRows,
  mcpServers,
  mcpTools,
  pluginGrants,
} from "../../db/schema";
import { BROKERED_PROFILE, brokeredProvenance, toolkitOfFor } from "../access";
import { ownerGrantsOf } from "../app-access";
import {
  type BrokerConnection,
  BrokerUnconfiguredError,
  type Decides,
  schemeKind,
} from "../broker";
import {
  catalogueEntry,
  classifyTool,
  customUrlRefusal,
  resolveServerUrl,
  serverCredentialKind,
  tokenHeaderFor,
} from "../catalogue";
import type { ListedTool } from "../mcp";
import {
  type AccountMode,
  type AccountRef,
  asAccountRef,
} from "../shared-accounts";
import { transportFor } from "../transport";
import type { StoreContext } from "./context";
import {
  BROKERED_ID_PREFIXES,
  BROKERED_SCREEN_NAMES,
  CatalogueEntryUnknownError,
  CustomServerRefusedError,
  DEPLOYMENT_ACTOR,
  effectiveUrl,
  isDeploymentFault,
  iso,
  PluginInvariantError,
  type ServerAddress,
  type ServerRecord,
  type StorableTool,
  schemeFor,
  storableTools,
  unlistedAdvertisedTools,
} from "./model";

/** Adding, removing, refreshing and listing MCP servers and brokered apps, and an app's account mode. */
export function serverMethods(context: StoreContext) {
  const {
    database,
    auditStore,
    credentials,
    broker,
    mcpGrantsForServers,
    accountRefFor,
    connectionTokenFor,
    requireCredentialOfKind,
    requireNotBrokered,
    requireServer,
    brokeredAppRow,
    brokeredAppRowsAt,
    brokeredAppScheme,
    brokerProvider,
    resolveSiblings,
    vendorRevocationClaim,
    clearEndedSiblings,
  } = context;
  return {
    /**
     * The one provider this store's rows belong to, readable by the layer above it.
     *
     * EXPOSED SO THE ROUTES DO NOT DECIDE IT A SECOND TIME. `routes.ts` used to take the name off
     * the broker it was handed and write `?? "composio"` when there was none — which is a second
     * answer to the question {@link PluginStoreOptions.brokerProvider} argues must have exactly one.
     * The two came apart precisely where it hurt: a deployment with both keys set and
     * `OPENBOT_BROKER_PROVIDER` unset is wired with no broker at all, so the routes read every
     * `arcade://` row of this store with Composio's parser. Read from here, the parser the routes
     * use and the filter this store queries with cannot disagree.
     */
    brokerProvider,
    accountRefFor,
    /**
     * Add a server from the catalogue.
     *
     * The URL is resolved from the catalogue rather than accepted from the caller, so the only thing
     * a person can influence is which entry and, for a per-instance vendor, their own instance
     * hostname, which is then checked against that vendor's anchored pattern before anything is
     * stored.
     */
    async addServer(input: {
      key: string;
      instanceHost?: string;
      credentialId?: string;
      by: string;
    }): Promise<ServerRecord> {
      const resolved = resolveServerUrl(input.key, input.instanceHost);
      if (!resolved) throw new CatalogueEntryUnknownError(input.key);

      /*
       * The pointer is checked here for the same reason it is on the path below: the refresh that
       * runs before this returns dereferences whatever it names.
       *
       * What that reaches is narrower on this path, because the URL is the catalogue's rather than
       * the caller's, so a credential cannot be delivered to an address somebody chose. That is a
       * property of today's catalogue rather than of this function: the one entry it holds is
       * `user-oauth`, and the catalogue's own comment invites a fork to re-add the vendors that were
       * taken out. The first `deployment-bearer` entry restores the full shape, so the check belongs
       * here now rather than in the review that re-adds one.
       */
      const credentialId = input.credentialId?.trim() || undefined;
      if (credentialId) {
        await requireCredentialOfKind(
          resolved.entry.title,
          resolved.entry.key,
          credentialId,
          serverCredentialKind(resolved.entry),
        );
      }

      /*
       * Not over a brokered row. See {@link requireNotBrokered} for what such a row would lose.
       *
       * Unreachable from the shipped product as it stands — `addBrokeredApp` mints `composio-<slug>`
       * and no catalogue entry is spelled that way — and asked anyway, because the row the check is
       * about is by definition one that arrived some other way: a hand edit, a restore, a build
       * whose catalogue named an app a past build brokered. This path writes the catalogue's url
       * over whatever is there, which is exactly the write that strands the accounts.
       */
      const [existing] = await database
        .select({
          provenance: mcpServers.provenance,
          url: mcpServers.url,
          // Part of what `accessFor` resolves a row with — see there. Nothing on this path reads
          // the answer's `reachedAs`, but the column travels with the other two so no caller has
          // to know which of the four answers the one it wants depends on.
          authScheme: mcpServers.authScheme,
        })
        .from(mcpServers)
        .where(eq(mcpServers.id, resolved.entry.key));
      requireNotBrokered(resolved.entry.key, existing);

      await database
        .insert(mcpServers)
        .values({
          id: resolved.entry.key,
          title: resolved.entry.title,
          vendor: resolved.entry.vendor,
          url: resolved.url,
          credentialId: credentialId ?? null,
          addedBy: input.by,
        })
        .onConflictDoUpdate({
          target: mcpServers.id,
          set: {
            url: resolved.url,
            /*
             * THE WHOLE IDENTITY THE CATALOGUE DECIDES, not the url alone.
             *
             * These three columns and the url are one statement — this row is that reviewed entry —
             * and an update that moved one of them and left the rest was a row describing two
             * different servers at once. `provenance` is read by `requireServer`, which refuses a
             * `first-party` row with no entry, and by `accessFor`, which reads it whenever there is
             * no entry to overrule it; `vendor` is what the first-party rule is checked against.
             * Left behind, a row that arrived by another path kept saying so at an address only the
             * catalogue chose — so every surface that asks how a server got here answered with the
             * way it USED to get here.
             *
             * The entry wins over the row everywhere else too (see `accessFor`), so this is that
             * same order written down at the one moment the row is being established rather than
             * read.
             */
            title: resolved.entry.title,
            vendor: resolved.entry.vendor,
            provenance: "first-party",
            /*
             * Left alone when the caller sends none, rather than cleared.
             *
             * `registerOAuthClient` keeps the client it minted in this column, and adding the server
             * again to change an instance host is not a statement about that client. Clearing it
             * orphaned the credential row, which nothing then revokes, and told everybody who had
             * connected that the deployment has no OAuth client registered. There is no longer a way
             * to hand it back through this call either, since a `user-oauth` entry now refuses a
             * credential id, so the pointer has to survive here.
             */
            ...(credentialId ? { credentialId } : {}),
            addedBy: input.by,
            updatedAt: new Date(),
          },
        });

      await recordAuditEvent(auditStore, {
        eventType: "configuration.changed",
        targetType: "mcp_server",
        targetId: resolved.entry.key,
        payload: {
          actor: input.by,
          change: "mcp_server_added",
          server: resolved.entry.key,
          url: resolved.url,
        },
      });

      // Refreshed immediately so the page that added it can show what it offers, and so a bad
      // credential is reported now rather than the first time a Bot tries to use it.
      await this.refreshTools(resolved.entry.key);
      const servers = await this.listServers();
      const added = servers.find((server) => server.id === resolved.entry.key);
      if (!added) throw new CatalogueEntryUnknownError(input.key);
      return added;
    },

    /**
     * Add a server that is not in the catalogue, by URL.
     *
     * The administrator's path is different from pressing Add on a curated entry. That
     * one picks a reviewed vendor at a pinned host; this one points the deployment at an address
     * somebody typed. Both are useful and only one of them can be reviewed in advance, so this one
     * is guarded at the URL, recorded with its provenance, and every tool it offers is treated as a
     * write because nothing here knows otherwise.
     */
    async addCustomServer(input: {
      id: string;
      title: string;
      url: string;
      credentialId?: string;
      by: string;
    }): Promise<ServerRecord> {
      const refusal = customUrlRefusal(input.url);
      if (refusal) throw new CustomServerRefusedError(refusal);

      // A custom server may not take a curated entry's slug. The slug prefixes tool names and is
      // what a grant and a policy rule are written against, so allowing a shadow would let a custom
      // server inherit rules an operator wrote about the vendor.
      if (catalogueEntry(input.id)) {
        throw new CustomServerRefusedError(
          `${input.id} is the name of a server this deployment already knows. Choose another.`,
        );
      }

      /*
       * Nor may it take the name of a screen. `/admin/plugins/composio` is a static route — the app
       * directory's own page — and `/admin/plugins/arcade` is the Arcade equivalent, and a static
       * route is matched ahead of `/admin/plugins/$key`, so a server sitting at either id would be
       * listed and then open somebody else's page instead of its own. Brokered servers are
       * `<provider>-<slug>` and no catalogue entry is called either of these, which leaves a
       * hand-typed id as the only way to reach them.
       *
       * BOTH, ON WHICHEVER BROKER THIS DEPLOYMENT RUNS, and derived from
       * {@link BROKERED_SCREEN_NAMES} rather than from a literal — the same argument the id-prefix
       * loop six lines below makes for its own namespace: the screen is there to be collided with
       * whether or not this deployment brokers through it today, and a reservation spelled twice is
       * the one that gets added to once. Each refusal still names the id it refused.
       */
      for (const [screen, { vendor }] of BROKERED_SCREEN_NAMES) {
        if (input.id === screen) {
          throw new CustomServerRefusedError(
            `${screen} is the name of this deployment's own ${vendor} screen, so a server added there could never be opened. Choose another.`,
          );
        }
      }

      /*
       * NOR THE NAMESPACE THE BROKERED ROWS ARE MINTED IN, which is the reservation above one step
       * further out.
       *
       * CRITERION. No server added by URL may take an id beginning `composio-` or `arcade-`, whether
       * or not a row is sitting there today, and on whichever broker this deployment runs.
       *
       * REASON. {@link addBrokeredApp} composes its id as `composio-<slug>` from the app an
       * administrator enabled, so that space is already spoken for by a path that writes
       * `composio://` urls into it. Unreserved, the two paths write one row: enabling an app over a
       * typed endpoint, or typing an endpoint over an app somebody is connected to. The second of
       * those is the one that cannot be undone — see {@link requireNotBrokered} — and this is what
       * stops either from arising in the first place, rather than catching them one row at a time.
       *
       * A PREFIX RATHER THAN A LOOKUP OF WHAT IS ENABLED TODAY. "Is there a brokered row at this id"
       * is a question whose answer changes: an app removed this morning frees the name, and the next
       * press of Add takes it back from whoever typed it in between. The namespace is what a reader
       * of a grant or a policy rule can rely on without asking the database what year it is.
       *
       * It is the same objection the curated-slug refusal above makes, and the same one
       * `addBrokeredApp` records for its own id: the id prefixes every tool name and is what a grant
       * and a policy rule are written against, so a row shadowing another path's namespace inherits
       * rules that were written about something else.
       */
      for (const { idPrefix, vendor } of BROKERED_ID_PREFIXES) {
        if (input.id.startsWith(idPrefix)) {
          throw new CustomServerRefusedError(
            `Names beginning ${idPrefix} belong to the ${vendor} apps this deployment enables, so ${input.id} is not a name a server added by URL can take. Choose another.`,
          );
        }
      }
      if (!/^[a-z0-9][a-z0-9-]{0,38}[a-z0-9]$/.test(input.id)) {
        throw new CustomServerRefusedError(
          "A server name is lower-case letters, numbers and hyphens.",
        );
      }

      /*
       * The pointer is checked here because the add is what dereferences it.
       *
       * `refreshTools` runs before this method returns, and for a custom server there is no
       * catalogue entry, so `connectionTokenFor` decrypts whatever `credential_id` names and
       * `listTools` sends it to the URL from this same request. An unchecked pointer therefore is
       * not "a wrong token later", it is this call delivering that secret to an address the caller
       * chose, before any grant, policy check or Bot exists.
       *
       * `mcp` is the only kind that answers "this server's own token". A `mcp_user_token` is one
       * person's grant and a `mcp_oauth_client` identifies the deployment to a vendor; neither is
       * this deployment's bearer token for this server, and spending either here would be using a
       * credential on behalf of somebody who never agreed to it. `POST /api/admin/credentials`
       * already refuses to mint those two by hand for that reason, and its comment says so; this is
       * the same objection at the point they are referenced rather than created.
       *
       * One message for both "wrong kind" and "no such credential", deliberately. A caller who can
       * tell those apart can ask this endpoint which credential ids are real.
       */
      /*
       * A credential is spent at the address it was given to, or not spent.
       *
       * Adding a server that is already here rewrites its URL, and the refresh that follows sends
       * whatever credential it holds to the new one, in the same call. That is the same disclosure
       * as naming another server's token and it needs no trick at all: the token really does belong
       * to this server, and only the address moved. A check on whose credential it is cannot see it,
       * which is why this rule is here and not folded into that one.
       *
       * Refused rather than repaired, because the two harmless readings of the request are both
       * served by something else. Correcting a title or retrying an interrupted add sends the same
       * URL and is unaffected, and genuinely moving a server means the vendor is at a new address,
       * where the honest act is to remove it and add it again with the token that address is
       * supposed to hold.
       *
       * Only this path. A curated server's URL comes from the catalogue rather than the request, so
       * the most a caller can influence is an instance hostname, and that is matched against the
       * vendor's own anchored pattern before anything is stored. Re-adding one cannot point it at an
       * address of the caller's choosing, which is the whole of what this refuses.
       */
      const credentialId = input.credentialId?.trim() || undefined;
      const [existing] = await database
        .select({
          url: mcpServers.url,
          credentialId: mcpServers.credentialId,
          // Read for the refusal below. The namespace rule above already keeps this path away from
          // every id `addBrokeredApp` mints; this is the same rule asked of the ROW, which is what
          // covers one that arrived before the namespace was reserved, or by restore.
          provenance: mcpServers.provenance,
          // The third of what `accessFor` resolves a row with. See there.
          authScheme: mcpServers.authScheme,
        })
        .from(mcpServers)
        .where(eq(mcpServers.id, input.id));

      /*
       * Before the address rule below, because it is the stronger statement about the same write.
       *
       * That one is about a credential being carried to an address, and it lets an add through when
       * no token is involved. This one is about the address ITSELF being the only record of which
       * app a set of connections belongs to, and no absence of a credential makes that write
       * survivable. See {@link requireNotBrokered}.
       */
      requireNotBrokered(input.id, existing);

      if (
        existing &&
        existing.url !== input.url &&
        (existing.credentialId || credentialId)
      ) {
        throw new CustomServerRefusedError(
          `${input.id} is already here at a different address and holds a credential. Remove it and add it again, with the token the new address is meant to have.`,
        );
      }

      if (credentialId) {
        // Always `mcp`: a server added by URL is reached with the one token the deployment holds for
        // it, whatever the vendor is, because nothing here knows the vendor.
        await requireCredentialOfKind(
          input.title,
          input.id,
          credentialId,
          "mcp",
        );
      }

      await database
        .insert(mcpServers)
        .values({
          id: input.id,
          title: input.title,
          vendor: new URL(input.url).hostname,
          url: input.url,
          provenance: "custom",
          credentialId: credentialId ?? null,
          addedBy: input.by,
        })
        .onConflictDoUpdate({
          target: mcpServers.id,
          set: {
            title: input.title,
            url: input.url,
            /*
             * WHAT THE ROW NOW IS, written beside the address that made it that.
             *
             * `vendor` is derived from the url on the way in, so leaving it behind while the url
             * moved left the column naming a host this row no longer addresses — and it is what the
             * first-party rule is checked against, not a caption. `provenance` is the same fact one
             * level up: a row whose entry a build removed still reads `first-party`, and
             * `requireServer` refuses exactly that shape as a vendor it can no longer check a pinned
             * host for. Adding it by URL is what makes it a typed address rather than a reviewed
             * one, so this is the act that settles the column.
             *
             * The one conversion this cannot make is out of a brokered row, which is refused above
             * rather than written here: there the url is the only record of which app a set of
             * consents belongs to, so a rewrite loses them whatever else is written alongside.
             */
            vendor: new URL(input.url).hostname,
            provenance: "custom",
            /*
             * Kept when the caller names none, rather than cleared, for a reason beyond tidiness.
             *
             * Clearing it left the credential live with nothing pointing at it, and `removeServer`
             * retires a token by reading it off the row: with the pointer gone it revoked nothing
             * and deleted the server, so the token outlived the server it was minted for. It could
             * then be attached to a freshly created server at any address, because the rule above
             * compares against a row that no longer existed. Three ordinary acts, and the address
             * this server was entrusted to stopped meaning anything.
             *
             * So the pointer survives, `removeServer` finds it, and a removed server's token is
             * dead rather than loose. Detaching a token without removing the server is not a thing
             * this endpoint does, and nothing asks it to.
             */
            ...(credentialId ? { credentialId } : {}),
            addedBy: input.by,
            updatedAt: new Date(),
          },
        });

      await recordAuditEvent(auditStore, {
        eventType: "configuration.changed",
        targetType: "mcp_server",
        targetId: input.id,
        payload: {
          actor: input.by,
          change: "mcp_server_added",
          server: input.id,
          url: input.url,
          // Named in the trail, because "who added a server nobody reviewed" is a question somebody
          // will ask and the answer should not require reading the catalogue of a past build.
          provenance: "custom",
        },
      });

      await this.refreshTools(input.id);
      const added = (await this.listServers()).find(
        (server) => server.id === input.id,
      );
      if (!added) throw new CatalogueEntryUnknownError(input.id);
      return added;
    },

    /**
     * Enable one app of the broker's catalogue, which is a third way for a server to arrive.
     *
     * NO URL IS TAKEN FROM A CALLER, WHICH IS WHY THERE IS NO HOST RULE HERE. `addCustomServer`
     * guards the address because the address is what an administrator typed and what a credential
     * would then be spent at; this one composes `<scheme>://<slug>` itself from the store's provider, and a brokered row is
     * never dialled at a host at all — the transport reads the app off that url and asks the active
     * broker, over the deployment's own key. So the only thing left to check about the url is that it says
     * what this call meant, and {@link toolkitOfFor} is what checks it: the slug goes in, the url comes
     * back out through the very function `accessFor` will read it with, and a slug those two
     * disagree about is refused rather than stored. A pattern written here instead would be a second
     * opinion about the shape of an app name, and the reading that decides which app a call runs
     * against is the one that has to be satisfied.
     *
     * THE AUTH CONFIG COMES BEFORE THE ROW, in that order and not the other. An auth config is what
     * a person's connection is then created against, so a row written first is an app an
     * administrator can see on the page, grant to a Bot and press Connect on, with nothing at the
     * vendor for any of it to attach to. Asking first is also what makes a failure leave nothing
     * behind: the broker throws, this call throws, and no row, no action and no audit entry claims
     * an app was enabled. {@link ComposioBroker.ensureAuthConfig} is idempotent precisely so that
     * enabling an app twice — two administrators, or a retried request — is allowed to do this.
     *
     * THE ID IS PREFIXED AND THE URL IS NOT. `composio-linear` is what prefixes tool names and what
     * a grant and a policy rule are written against, so it must not land on a curated entry's key —
     * which `accessFor` refuses outright as a row claiming to be two servers at once — nor on one of
     * the ids the integration suite reserves for its own fixtures: `gmail`, `notion`, `bot_helper`.
     * The prefix puts every brokered row out of reach of all of them. WHICH APP THE ROW IS still
     * comes off the url and only off the url, because that is where `accessFor` and the brokered
     * gate behind it both read it from; the id names the row and never the app, and nothing may
     * start reading one as the other.
     */
    async addBrokeredApp(input: {
      slug: string;
      title: string;
      logo?: string | null;
      by: string;
      /**
       * How this app connects, resolved from the catalogue row the administrator chose.
       *
       * Taken rather than derived here, because the caller has already read it off that row and a
       * second derivation is a second answer — the one thing {@link BrokerConnection} exists to
       * prevent. It decides what config is created at the vendor, and it is what this row records.
       */
      connection: BrokerConnection;
    }): Promise<ServerRecord> {
      // Before anything at all. A deployment with no key has no catalogue for this app to have been
      // chosen from, so there is nothing here to half-do and nothing to say but the setting.
      if (!broker)
        throw new BrokerUnconfiguredError(brokerProvider, "operator");

      const profile = BROKERED_PROFILE[brokerProvider];
      const url = `${profile.scheme}${input.slug}`;
      const rowId = `${profile.idPrefix}${input.slug}`;
      if (toolkitOfFor(brokerProvider, url) !== input.slug) {
        throw new CustomServerRefusedError(
          `${input.slug} is not a name ${brokerProvider === "arcade" ? "an" : "a"} ${profile.vendor} app can have. An app is named in letters, numbers, underscores and hyphens, because that name is read back out of this row's url to decide which app a call is against.`,
        );
      }

      /*
       * WHAT THE ROW ALREADY SAYS, READ BEFORE ANYTHING IS WRITTEN, because after the upsert this
       * question cannot be asked any more — the insert below would have answered it.
       *
       * It is the scheme the app's ANSWERING row records, which is what every brokered reader
       * resolves and is not always the row the upsert names. See {@link brokeredAppRow}.
       */
      const recorded = await brokeredAppScheme(input.slug);

      const configured = await broker.ensureAuthConfig({
        toolkit: input.slug,
        name: input.title,
        connection: input.connection,
      });

      /*
       * THE SCHEME THIS ENABLE MAY WRITE DOWN, WHICH IS NOT ALWAYS THE ONE THE CATALOGUE RESOLVES.
       *
       * CRITERION. What this row records is what the authorization config standing at Composio was
       * created as — never what today's catalogue says the app could be connected with.
       *
       * REASON. {@link ComposioBroker.ensureAuthConfig} reuses a config of ours whatever scheme it
       * holds, and it used to say nothing about having done so, so every path here wrote the
       * catalogue's answer. An app enabled while Composio published only a key, and later given
       * managed OAuth, came out of a second press of Add recording `OAUTH2` beside a config that is
       * still `API_KEY`: `brokeredAppKind` then says `consent`, so `connectBrokeredWithFields`
       * refuses every submission while `authorize` mints consent links against a key config — the
       * exact "sent to a consent screen that had nothing to ask them for" failure that method's own
       * comment describes. And pressing Add again could never repair it, because the reuse is what
       * caused it.
       *
       * `standing` IS THEREFORE THE ONE ANSWER THAT KEEPS WHAT WAS THERE, and it falls back to the
       * catalogue only where nothing was recorded at all — a row restored without the column, or an
       * app whose config was made before this deployment recorded one. A guess is the best available
       * answer there and it is no worse than what stood before; everywhere else the recorded word
       * wins.
       *
       * AND `created` MAY WRITE FREELY, connections or no connections: the config those connections
       * were made against is gone from Composio — that is why one had to be created — so the new
       * scheme is the only true thing to record about the app.
       */
      const scheme =
        configured === "standing"
          ? (recorded ?? schemeFor(input.connection))
          : schemeFor(input.connection);

      /*
       * THE COMPOSED NAME IS SPELLED WHERE IT IS MINTED AND IS GIVEN NO BINDING TO BE REUSED FROM.
       *
       * It used to be `const id`, and everything below this statement then had a plausible-looking
       * server id to reach for — which is how four review rounds each moved one site onto the
       * resolved row and left the next one standing. See {@link _EnableNamesTheRow}: after this
       * statement there is exactly one id in scope, and it is the answering row's.
       */
      await database
        .insert(mcpServers)
        .values({
          id: rowId,
          title: input.title,
          logo: input.logo ?? null,
          // The broker, whoever publishes the app behind it. `vendor` is what the first-party rule
          // is checked against, and Composio is who this deployment is actually talking to.
          vendor: profile.vendor,
          url,
          provenance: brokerProvider,
          // Nothing for the vault to hold. A brokered call runs as the person asking, on their own
          // connection at the vendor, which is a `composio_connections` row rather than a secret.
          credentialId: null,
          /*
           * What the config standing at Composio was created AS, which is the scheme every later
           * connection against it has to keep using.
           *
           * THE RESOLVED ONE AND NOT THE CATALOGUE'S, WHICH THIS BRANCH USED TO WRITE UNGUARDED.
           * The write-once rule below protects only the UPDATE, and this INSERT fires exactly when
           * no row stands at the composed id — which is not the same as no row standing for the
           * APP. In the two-rows-at-one-url state this method is built around, a restored or
           * hand-added `gmail` at `composio://gmail` holding `API_KEY` and live key connections is
           * untouched by the guard: the insert at `composio-gmail` fired, wrote `OAUTH2`, and
           * `composio-gmail` sorts first, so `brokeredAppRowsAt` made the new row the answering
           * one. `confirmBrokeredConnection` then classified the app `consent`, saw `verified:
           * false` on a key row, and wrote `verified: true, probeAction: null` over it — erasing a
           * recorded failed check on the next page load. See the derivation of `scheme` above.
           */
          authScheme: scheme,
          /*
           * PERSONAL ON A NEW ROW, AND NULL WHERE THERE IS NO ACCOUNT TO HOLD.
           *
           * A freshly enabled app is reached through each asking person's own account until an
           * administrator deliberately switches it to Shared — sharing one account across everyone
           * a Bot reaches is a decision somebody makes, never a default this method makes for them.
           * A `no-auth` app has no account at all, so it has no mode to choose between, and the
           * column says so rather than claiming one; see {@link mcpServers.accountMode}.
           *
           * WRITTEN ON THE INSERT ONLY. The update below is the branch a second press of Add takes,
           * and an app an administrator has already made Shared must not be quietly turned back
           * into Personal by it.
           */
          accountMode: input.connection.kind === "no-auth" ? null : "personal",
          addedBy: input.by,
        })
        .onConflictDoUpdate({
          target: mcpServers.id,
          set: {
            title: input.title,
            logo: input.logo ?? null,
            url,
            /*
             * WRITTEN BESIDE THE URL, BECAUSE THE TWO ARE ONE FACT AND A ROW HOLDING HALF OF IT IS
             * NOT A SERVER AT ALL.
             *
             * CRITERION. Every row this method leaves behind says `composio`, whatever it said
             * before. The url above and this column are what `accessFor` reads to answer that a call
             * is brokered and which app it is against, and no path may write one without the other.
             *
             * REASON. This branch rewrote the url and left `provenance` standing, so enabling an app
             * at an id a custom server already held produced a row reading `custom` at a
             * `composio://` address. That is not a display inconsistency: `accessFor` answers
             * `deployment-token` for it, so the transport dialled the row as an ordinary MCP
             * endpoint on the deployment's own credential while the Composio screen went on
             * attaching people's real accounts to the app its url named. The per-person gate was not
             * weakened but SKIPPED — `connectionTokenFor` only ever asks for a connection down the
             * brokered branch — which is the whole property this connector exists for. And
             * `removeServer` finds the accounts to end at the vendor through that same answer, so it
             * revoked nothing and reported the connector gone.
             *
             * A CONVERSION HERE, A REFUSAL IN THE OTHER DIRECTION, and the asymmetry is the point.
             * What this method writes IS the app — the auth config stands at Composio before the row
             * is touched, and the url names the app the connections will be keyed on — so a row it
             * lands on comes out saying exactly what it now is, with nothing lost. Going the other
             * way, the url being overwritten is the only record of which app a set of consents
             * belongs to, and no column written alongside brings it back; see
             * {@link requireNotBrokered}.
             *
             * `vendor` for the same reason one notch quieter: it is what the first-party rule is
             * checked against, and a row reached over the broker whose vendor column still names the
             * host somebody typed is answering that rule about a server this deployment no longer
             * dials.
             */
            provenance: brokerProvider,
            vendor: profile.vendor,
            addedBy: input.by,
            updatedAt: new Date(),
            /*
             * `credential_id` is neither written here nor cleared here.
             *
             * Every row this method creates has none and no path in this module attaches one, so
             * there is nothing for an enable to set. Clearing it anyway would matter in the single
             * case it could apply — a pointer that arrived by hand edit or restore — because
             * `removeServer` retires a server's secret by reading it off this column, and a null
             * written over it leaves that secret live with nothing left to name it.
             */
            /*
             * `auth_scheme` is not written here either, and for a neighbouring reason.
             *
             * This is the branch a second press of Add takes, and the scheme is the one thing on
             * the row that live connections depend on rather than merely display. Rewriting it
             * here would move them; the statement below rewrites it only where there are none.
             */
          },
        });

      /*
       * WHICH ROW THIS DEPLOYMENT WILL ANSWER FOR THE APP WITH, RESOLVED ONCE AND FOR EVERYTHING
       * BELOW.
       *
       * CRITERION. After the upsert, every act of this method — the scheme it records, the actions
       * it lists, the row it files on the trail and the record it hands its caller back — is about
       * the row {@link brokeredAppRow} names for this app. The composed `composio-<slug>` is what
       * the statement above MINTS and is a stand-in for nothing.
       *
       * REASON. `mcp_servers.url` has no unique index, deliberately — see {@link brokeredAppRow} —
       * so the row this method names and the row every brokered reader resolves are allowed to be
       * different rows, and in the ordinary two-rows-at-one-url state they are. Every act keyed on
       * the composed id was then an act performed somewhere nothing looks. FOUR ROUNDS OF REVIEW
       * EACH MOVED ONE OF THEM AND LEFT THE NEXT STANDING: the probe was resolved by url, then
       * `brokeredAppRow` was introduced and the probe and the confirm routed through it, then the
       * scheme WRITE was moved here — and the actions went on being listed under the composed name
       * the whole time. That last one is the deadlock the single-row rule exists to close: the
       * chooser reads actions by server id, finds none on the answering row, so `checkable` is
       * false on every page load, the browser draws no Re-check button, and the one press that
       * could earn the app a verdict can never be made.
       *
       * THE ROW IS RE-READ RATHER THAN ASSUMED, because the upsert may have created it, found it,
       * or landed beside an older row that sorts first — and which of those happened is exactly what
       * decides the answer. The composed name is respelled as the fallback for the unreachable case
       * of a row this method has just written not being found at its own url, which would mean the
       * insert above and this read disagree about what was stored; it is respelled rather than held
       * in a binding so that nothing below can take it by mistake.
       */
      const answering = (await brokeredAppRow(input.slug))?.id ?? rowId;

      /**
       * WHICH ROW EACH ACT OF AN ENABLE NAMES, WRITTEN DOWN BECAUSE NOTHING ELSE CAN SAY IT.
       *
       * Type-only and erased; see {@link Decides}. Every other roster in this file is keyed on a
       * vocabulary the compiler already knows — {@link SchemeKind}, {@link BrokeredProbe} — and
       * this one is keyed on the acts of a single method, because the drift being pinned is not a
       * branch that forgot a member but a SITE that reached for the wrong name. There is no type
       * whose inhabitants are "the things an enable does", so the checklist is the union and the
       * roster is what forces an answer out of it: a sixth act added to `BrokeredEnableAct` fails
       * `tsc` here until somebody says which row it is about, and the two legal answers are a closed
       * pair rather than free text so the seam cannot drift in the direction it has drifted four
       * times.
       *
       * `minted` IS THE ANSWER FOR EXACTLY ONE ACT, and that is the whole shape of the rule. The
       * upsert has to be keyed on the composed name — it is what converts a row an administrator
       * typed at that id into the brokered app it now is, which is a property with its own test —
       * and every act after it is about the row the readers read.
       */
      type BrokeredEnableAct =
        | "upsert"
        | "scheme"
        | "actions"
        | "trail"
        | "answer";
      type _EnableNamesTheRow = Decides<
        BrokeredEnableAct,
        {
          upsert: "minted";
          scheme: "answering";
          actions: "answering";
          trail: "answering";
          answer: "answering";
        },
        "minted" | "answering"
      >;

      /*
       * WRITTEN EXACTLY WHERE A CONFIG WAS MADE TO WRITE IT ABOUT, AND NEVER OVER A STANDING ONE.
       *
       * A row's scheme is what its authorization config was created as, and every connection made
       * against that config depends on it. Re-enabling must not rewrite it underneath them: a
       * vendor that starts publishing managed OAuth for an app somebody connected by key would,
       * one press of Add later, leave this deployment minting consent links against a config full
       * of keys.
       *
       * THE GUARD WAS "NOBODY HAS CONNECTED YET" ALONE, AND THAT HALF CANNOT SETTLE IT. It reasoned
       * that with no connections there is nothing to strand, so the rewrite is safe and is how an
       * operator picks up a vendor's change without removing and re-adding the app. The second
       * clause was false, for one reason: {@link ComposioBroker.ensureAuthConfig} REUSES a config of
       * ours whatever scheme it holds and creates nothing, so a press of Add does not pick the
       * vendor's change up — it records a word beside a config that never moved. An app enabled as
       * `API_KEY` and given managed OAuth by the vendor came out of that press recording `OAUTH2`
       * against a key config, which makes `connectBrokeredWithFields` refuse every submission while
       * `authorize` mints consent links that ask for nothing — and pressing Add again can never
       * repair it, because the reuse is the cause.
       *
       * SO BOTH CLAUSES STAND, AND EACH CLOSES WHAT THE OTHER CANNOT. Nothing connected means no
       * connection is moved by the write; a config this call actually CREATED means there is a
       * config that was made as the word being written. `standing` writes nothing whatever the
       * connection count, and remove-and-re-add is then the one act that genuinely changes an app's
       * scheme, because it is the one that deletes the config.
       *
       * AND IT IS WRITTEN ON THE ROW THAT ANSWERS FOR THE APP, WHICH IS NOT ALWAYS THE ONE THE
       * UPSERT NAMED.
       *
       * CRITERION. After this call, the scheme {@link brokeredAppScheme} answers with for the app is
       * the scheme the authorization config standing at Composio was created as.
       *
       * REASON. The statement was keyed on the composed `composio-<slug>` while every reader of this
       * column finds the app by its URL. Where those are two rows the write and the reads were about
       * different rows: an app enabled with a key that every reader calls a consent app. What the
       * person then meets is the connect form refusing them in a sentence about a sign-in screen
       * that does not exist for this app, and a Re-check button that will not press. A writer keyed
       * on a composed id has not recorded the fact; it has recorded it somewhere nothing looks.
       */
      // Anyone at all, of either holder: a deployment's shared account was made against the
      // standing config exactly as a person's was, and a rewrite would strand it the same way.
      const connections = await database
        .select({ app: brokeredConnections.app })
        .from(brokeredConnections)
        .where(
          and(
            eq(brokeredConnections.provider, brokerProvider),
            eq(brokeredConnections.app, input.slug),
          ),
        )
        .limit(1);

      if (configured !== "standing" && connections.length === 0) {
        await database
          .update(mcpServers)
          .set({ authScheme: scheme, updatedAt: new Date() })
          .where(eq(mcpServers.id, answering));
      }

      /*
       * AN APP WITH AN ACCOUNT LEAVES THIS METHOD SAYING WHOSE, ALWAYS — AND THAT IS A SEPARATE
       * STATEMENT FROM THE SCHEME ABOVE FOR A REASON.
       *
       * CRITERION. After `addBrokeredApp` returns, the row that answers for the app either records
       * a mode or is an app with no account to hold one about ({@link schemeKind} `none`). There is
       * no third state, and in particular no enabled key-or-consent app with a null here.
       *
       * REASON. The null is not a cosmetic gap: {@link accountFor} refuses a call against such a
       * row as `ambiguous` — "does not say whether it is reached through each person's account or a
       * shared one, so it was not called" — so an app in that state is enabled, listed, connectable
       * and dead. THREE THINGS HAD TO BE TRUE AT ONCE FOR IT TO HAPPEN AND ALL THREE WERE. The
       * INSERT above settles the column, but this method's second branch is the upsert's CONFLICT
       * arm, which writes the url and the provenance — it CONVERTS a row that was not brokered
       * into one that is — and never wrote this column at all. The guard that stood here then asked
       * `schemeKind(recorded) === "none"`, which is the question "was this a no-auth app a moment
       * ago"; `recorded` is {@link brokeredAppScheme}, and a row that was not brokered a moment ago
       * answers `null`, which is `unreadable` rather than `none`. And the whole block was gated on
       * `configured !== "standing"`, so the one obvious remedy — press Add again — reaches it only
       * on the single press that created the config and never afterwards. An administrator
       * converting a hand-added or restored row got an app that refused every call, and nothing
       * they could press repaired it: the Plugins page offers "Make shared" for a null mode (it
       * reads any non-`shared` value as Personal) and no way to say Personal at all.
       *
       * SO THE QUESTION ASKED HERE IS THE ONE THE REFUSAL ASKS, and nothing else: does the row
       * answering for this app have an account to hold, and does it fail to say whose. The scheme
       * is re-read rather than taken from `scheme` because the branch above may or may not have
       * written it, and what matters is what now STANDS on the answering row — including the
       * `unreadable` null a converted row carries, which {@link accountFor} treats as having an
       * account and which is therefore exactly as dead without a mode as a recorded `OAUTH2`.
       *
       * `personal` IS THE FILL, which is the insert's own default and the conservative one: it
       * reaches each asking person's own account. `shared` would hand everybody one account nobody
       * chose to share.
       *
       * AND NEVER OVER A MODE THAT IS THERE. The `IS NULL` lives in the WHERE rather than in a
       * read-then-write, so an administrator's Shared choice cannot be lost to this statement, nor
       * to a switch racing it.
       *
       * ON THE ANSWERING ROW, WHICH IS WHY THE CONFLICT ARM STILL DOES NOT WRITE THE COLUMN. Every
       * reader of a brokered app's mode — {@link brokeredAppRowsAt} and so `serverAddress`, the
       * listing, the call gate — resolves it off the row that answers for the url, which is not
       * always the row the upsert keyed on. A fill in the conflict arm would settle the minted row
       * and leave the one that is actually read still null.
       *
       * ROWS ALREADY STUCK IN THE NULL STATE ARE NOT REACHED FROM HERE AT ALL, because an enabled
       * app cannot be re-added without first being removed. They are repaired by
       * `0058_arcade_provider_backfill`, which is the same decision written once against the
       * table; see `tests/brokered-account-mode-backfill.integration.test.ts`.
       */
      const [settled] = await database
        .select({ authScheme: mcpServers.authScheme })
        .from(mcpServers)
        .where(eq(mcpServers.id, answering))
        .limit(1);
      if (schemeKind(settled?.authScheme ?? null) !== "none") {
        await database
          .update(mcpServers)
          .set({ accountMode: "personal", updatedAt: new Date() })
          .where(
            and(eq(mcpServers.id, answering), isNull(mcpServers.accountMode)),
          );
      }

      await recordAuditEvent(auditStore, {
        eventType: "configuration.changed",
        targetType: "mcp_server",
        /*
         * THE ROW A READER WOULD GO AND LOOK AT, which is the one this deployment answers for the
         * app with and not the one the upsert happened to key on. Where those differ the composed
         * row exists too, so a trail naming it would send somebody to a row whose scheme, whose
         * actions and whose Re-check button are all somewhere else — and `url` below names the app
         * itself, so nothing about which app was enabled is lost by naming the answering row here.
         */
        targetId: answering,
        payload: {
          actor: input.by,
          change: "mcp_server_added",
          server: answering,
          url,
          // Named for the same reason the custom path names its own: "who enabled an app whose
          // actions nobody reviewed" is a question somebody will ask, and the answer should not
          // require knowing how ids were spelled in a past build.
          provenance: brokerProvider,
        },
      });

      /*
       * Refreshed now for the reason the paths above are: the page that enabled the app can show
       * what it offers, and a broker that will not list it says so here rather than at first use.
       *
       * ONTO THE ANSWERING ROW, which is the site this whole block is about. `mcp_tools.server_id`
       * is what {@link probeActionFor} reads actions by and what {@link listServers} joins them on,
       * and every brokered caller hands those the id resolved above — so actions written under the
       * composed name are actions nothing in the brokered path can see.
       */
      await this.refreshTools(answering);
      const added = (await this.listServers()).find(
        (server) => server.id === answering,
      );
      if (!added) throw new CatalogueEntryUnknownError(answering);
      return added;
    },

    /**
     * Remove a server, and stop every secret it was reached with being live.
     *
     * TWO KINDS OF SECRET, and both have to go. The server's own credential is whatever
     * `mcp_servers.credential_id` names — a `mcp` bearer token an administrator added, or, for a
     * `user-oauth` vendor, the deployment's OAuth client, keyed `oauth-client-<serverId>`. Nothing
     * else revokes it, so leaving it behind means re-adding the same server meets its own abandoned
     * row on `credentials_active_key_idx`.
     *
     * The other kind is every PERSON'S grant for this server, keyed `mcp_user_token` on the server id.
     * `mcp_user_credentials` cascades on the server row, so removing the connector used to delete
     * every pointer and leave every refresh token live and unreferenced: reachable from no screen,
     * revoked by no operation, and still a usable grant at the vendor. "We removed the connector" has
     * to be true of the thing that matters, which is the token sitting at the vendor.
     *
     * Revoked rather than deleted, because the vault keeps revoked rows for audit.
     *
     * A THIRD KIND OF ACCESS THAT IS NOT A SECRET. A brokered app holds no per-person secret at all
     * — Composio keeps the accounts and the deployment sends a user id — so the only thing standing
     * between a person and their mailbox is a `composio_connections` row, and that table references
     * nothing that would cascade it. Removing the app therefore left every one of them behind, and
     * adding the app back turned them live again without anybody being asked. That row goes too —
     * and before it goes, the account it stands for is ended at Composio, because clearing the row
     * alone shuts a gate and leaves the mailbox attached. The deployment's auth config for the app
     * goes last, once nobody is connected to it any more.
     *
     * The revokes go first. These are writes on two tables and the store exposes no transaction that
     * spans both, so the order decides what a failure between them leaves: revoke-then-delete leaves
     * a server whose secrets no longer work and which removing again will finish off, while
     * delete-then-revoke leaves live secrets no server references and no operation can reach.
     */
    async removeServer(serverId: string, by: string): Promise<void> {
      const [existing] = await database
        .select({
          credentialId: mcpServers.credentialId,
          // Read so the brokered connections below can be keyed on the app the url names, which is
          // the same key the call gate uses. See there for why the row id will not do.
          provenance: mcpServers.provenance,
          url: mcpServers.url,
          // The third of what `accessFor` resolves a row with. See there.
          authScheme: mcpServers.authScheme,
        })
        .from(mcpServers)
        .where(eq(mcpServers.id, serverId));

      /**
       * Whether that token is still live, read rather than inferred from a
       * thrown error, so a token a previous attempt already revoked, or one
       * whose row is gone entirely, is skipped while a database fault still
       * propagates and leaves the server row in place to be removed again.
       *
       * Two queries rather than a join because `mcp_servers.credential_id` is
       * `text` and `credentials.id` is `uuid`, so the two columns do not
       * compare without a cast.
       */
      const [live] = existing?.credentialId
        ? await database
            .select({ id: credentialRows.id })
            .from(credentialRows)
            .where(
              and(
                eq(credentialRows.id, existing.credentialId),
                isNull(credentialRows.revokedAt),
              ),
            )
        : [];

      if (live) {
        await credentials.revoke(live.id);
        await recordAuditEvent(auditStore, {
          eventType: "credential.revoked",
          targetType: "credential",
          targetId: live.id,
          payload: {
            actor: by,
            reason: "mcp_server_removed",
            server: serverId,
          },
        });
      }

      /*
       * Every person's grant for this server, read out of the VAULT rather than through the join
       * table.
       *
       * `credentials.provider` holds the server id for an `mcp_user_token`, so the vault can be asked
       * directly — which matters because the join row is the thing about to be cascaded away, and a
       * grant whose pointer has already gone (a person removed earlier) would otherwise be invisible
       * here too. The same argument `retireConnectionsFor` makes from the other direction.
       */
      const held = await database
        .select({ id: credentialRows.id, keyId: credentialRows.keyId })
        .from(credentialRows)
        .where(
          and(
            eq(credentialRows.kind, "mcp_user_token"),
            eq(credentialRows.provider, serverId),
            isNull(credentialRows.revokedAt),
          ),
        )
        .orderBy(asc(credentialRows.keyId));

      for (const grant of held) {
        await credentials.revoke(grant.id);
        await recordAuditEvent(auditStore, {
          eventType: "mcp.account_disconnected",
          targetType: "mcp_server",
          targetId: serverId,
          payload: {
            actor: by,
            server: serverId,
            // Whose it was. `key_id` holds the user id for this kind, and it is the only place left
            // to read it from once the join row has been cascaded away.
            owner: grant.keyId,
            /*
             * Not "they disconnected" and not "they were removed": an administrator took the whole
             * connector away, and the person did nothing. An auditor asking what happened to their
             * access should see which of the three this was.
             */
            reason: "mcp_server_removed",
            vendorRevocationRequested: false,
          },
        });
      }

      /*
       * The third kind of access, which is not a secret at all: everybody's brokered connection.
       *
       * CRITERION. Removing an app must leave nobody holding brokered access to it, so that adding
       * it back again grants nothing until each person has consented afresh.
       *
       * REASON. `composio_connections` is the whole gate on a brokered call and it references
       * nothing — not `mcp_servers`, not `users` — so nothing cascaded it and removing the app left
       * every row standing. Two ordinary administrative acts, remove and add back, then restored
       * everybody's access at a url the second act chose, with nobody asked again and no screen
       * saying it had happened. Consent that reattaches by itself is not consent.
       *
       * KEYED ON THE APP THE URL NAMES, exactly as `connectionTokenFor` keys the gate. `row.id` is a
       * display key and nothing holds it equal to the slug in the url, so a delete by id would clear
       * some other app's connections, or none, for the very row shape that gate already refuses to
       * trust. The slug is read with {@link toolkitOfFor} — the one per-provider parser `accessFor`
       * itself reads it with — so this cannot drift from what the gate resolves; see the comment on
       * `rowProvider` below for why the PROVIDER is read beside it rather than the slug alone.
       *
       * ASKED WITH NO ENTRY, deliberately, and that is not the entry-wins order being dodged. An
       * entry can only ever SUPPRESS this answer — `accessFor` returns a null toolkit for every row
       * that has one — so passing the entry a colliding id looks up would hide the brokered state of
       * the one row most in need of clearing, and would now refuse outright the very row this method
       * exists to get rid of, leaving the collision unremovable. Nothing is dialled here, so there is
       * no vendor for an entry to protect; the only question is which app's consent rows this row's
       * own url stands for.
       *
       * Before the server row goes, for the reason the revokes above are: what a failure between
       * two writes leaves has to be the recoverable half. A connection cleared with the app still
       * present is fixed by removing it again; an app deleted with the connections standing is
       * reachable by no operation at all, because the toolkit was only ever readable off its url.
       *
       * AND THE ACCOUNT IS ENDED AT THE VENDOR, not merely forgotten here. Deleting the row closes
       * the gate this deployment owns and does nothing whatever to the account: the person's
       * mailbox stays attached at Composio, the grant stays live, and an administrator who pressed
       * "remove" was told the connector was gone. So every connected person is revoked through the
       * broker first, exactly as {@link disconnectBrokered} revokes for one — the same
       * shape at the scale of an app.
       *
       * REVOKE BEFORE DELETE, ALWAYS, and the argument is the one that method makes. The row is the
       * only thing here that names which app this person connected, so a delete that ran first
       * would leave a failed revoke with nothing to revoke under: a live grant on somebody's
       * mailbox that no operation in this deployment can reach. The other order costs a repeat of
       * an administrative act nobody minds repeating. Dead and reachable beats live and
       * unreachable.
       *
       * WHICH MAKES THE FAILURE LOUD. Nothing is caught around the revokes: a broker that will not
       * answer ends this method with the rows still standing and the app still present, rather than
       * letting it report an ending that did not happen.
       *
       * THE AUTH CONFIG GOES LAST, after every account is dead and every row is gone, for the same
       * reasoning one step out. An orphaned auth config grants nobody anything — it is a shape this
       * deployment holds at Composio, not an account — while a live account whose config has
       * already been deleted is access that nothing left here can end.
       */
      /*
       * AND ALL OF IT IS ABOUT THE BROKER THE ROW WAS MINTED AT, which is not always the one this
       * deployment is configured with.
       *
       * CRITERION. One removal names ONE vendor. The app slug, the connection rows it clears and
       * the account it ends are all that row's own broker's, and a vendor is asked only where it is
       * the one this deployment can reach.
       *
       * REASON. These three were read three different ways in one operation: the slug off the ROW's
       * provenance (through `accessFor`, which parses the url with the parser belonging to whatever
       * that column says), the connection rows off the CONFIGURED `brokerProvider`, and the
       * revocation off the ACTIVE broker. A deployment that has switched broker — or a restore, or a
       * hand edit — holds rows whose provenance is the other vendor, and for one of those the three
       * disagreed: a non-null FOREIGN slug went to `revoke` and `deleteAuthConfig` at the wrong
       * vendor, naming one of its apps by a name that means something else there, while the deletes
       * beneath matched no row at all. The removal then reported the connector gone, with every
       * local consent row still standing and the right vendor never asked.
       *
       * SO THE ROW'S PROVENANCE DECIDES WHAT IS CLEARED, AND THE CONFIGURED PROVIDER DECIDES ONLY
       * WHETHER A VENDOR IS ASKED. The local half always runs: the criterion two comments up —
       * removing an app leaves nobody holding brokered access to it — is about this deployment's own
       * gate, and it holds whichever broker minted the row. The vendor half is skipped where the
       * row's broker is not the configured one, because there is no client for it here and no
       * credential to reach it with; `vendorRevocationRequested` then says `false` on every trail
       * row, which is exactly what that field is for and the same answer a deployment with no broker
       * at all gets. An account left standing at a vendor this deployment can no longer reach is not
       * a thing a removal can end, and saying so is better than asking the wrong vendor to.
       *
       * The parse is {@link toolkitOfFor} with the ROW's provider rather than `accessFor`, because
       * what this needs is the pair — which broker, and which app at it — and `accessFor` answers
       * only the second. It is the same answer for the same rows: `accessFor` reads the slug with
       * the very same per-provider parser, under the same brokered-provenance test, and is asked
       * with no entry here for the reason the comment above gives.
       */
      const rowProvider =
        existing && brokeredProvenance(existing.provenance)
          ? existing.provenance
          : null;
      const toolkit =
        existing && rowProvider
          ? toolkitOfFor(rowProvider, existing.url)
          : null;
      /** The broker to ask, which is none at all where the row is the other vendor's. */
      const rowBroker = rowProvider === brokerProvider ? broker : null;

      if (rowProvider && toolkit) {
        /*
         * Read before anything is deleted, because the revokes below need the people and the rows
         * are where the people are. Sorted, so two removals of the same app revoke in the same
         * order and write their trail rows in the same order.
         */
        const connected = await database
          .select({
            holder: brokeredConnections.holder,
            userId: brokeredConnections.userId,
            vendorUserId: brokeredConnections.vendorUserId,
          })
          .from(brokeredConnections)
          .where(
            and(
              // The row's own broker, not the configured one: see the comment above `rowProvider`.
              eq(brokeredConnections.provider, rowProvider),
              eq(brokeredConnections.app, toolkit),
            ),
          )
          .orderBy(
            asc(brokeredConnections.holder),
            asc(brokeredConnections.userId),
          );

        /*
         * BOTH HOLDERS, EACH NAMED AS WHAT IT IS. Removing an app ends every account standing for
         * it — every person's own, and the one the deployment holds if the app was ever Shared,
         * which may still be standing after a switch back that has not retired it yet. Each is
         * revoked as the account its row says it is, under the vendor id the row was filed under,
         * so the deployment's account is asked for as the deployment's and never as whoever
         * pressed "remove".
         *
         * READ THROUGH {@link asAccountRef}, AND A ROW THAT NAMES NO ACCOUNT STOPS THE REMOVAL
         * BEFORE ANYTHING IS ASKED OR DELETED. This was a ternary whose else-branch absorbed every
         * pair it did not recognise into `{ holder: "deployment" }`, and the two readings below —
         * the revoke and the trail's `owner` — each repeated it. `brokered_connections_holder_check`
         * makes `person` with a NULL user id unwritable, which is exactly why this is a refusal
         * rather than a coercion: a state the database says cannot exist, absorbed into the other
         * holder, is a withdrawal aimed at the DEPLOYMENT's account over a person's row. The
         * EMPTY STRING is not hypothetical — `IS NOT NULL` does not stop `''` — and the old
         * reading's `!== null` let it through as a person ref under nobody's id, which reached
         * `rowBroker.revoke` and was filed as an `owner` of `""`.
         *
         * RESOLVED FOR THE WHOLE SET UP FRONT, so the throw lands before the first revoke rather
         * than part-way through one: a removal that had already withdrawn two accounts at the
         * vendor and then threw would leave their rows standing and no trail for either.
         */
        const accounts = connected.map((connection): AccountRef => {
          const account = asAccountRef(connection);
          if (!account) {
            throw new PluginInvariantError(
              `${toolkit} holds a connection row whose holder and user id name no account, so the accounts standing for it cannot be ended.`,
            );
          }
          return account;
        });

        /*
         * What the broker was actually asked for each of them, kept so the trail below records the
         * answer rather than the call. False where there is no broker at all: a deployment whose
         * key has since been unset can still remove the app, and it could not have been calling it
         * either way — but nothing was asked of Composio and the row must not claim otherwise.
         */
        const revokeAnswers: boolean[] = [];
        /*
         * What the trail may CLAIM from those answers about this app, read before anything is
         * revoked, as {@link disconnectBrokered} reads its own; see {@link vendorRevocationClaim}.
         */
        const claim = await vendorRevocationClaim(toolkit);
        /*
         * THE APPS EACH ACCOUNT'S REVOCATION ENDS BESIDES THIS ONE, read BEFORE anything is revoked
         * and through {@link resolveSiblings}, the one place that answers it. Where a connection is
         * keyed `(identity, auth provider)` — Arcade — withdrawing it ends every app sharing it, so a
         * local row left for one of them claims an account the vendor no longer holds. On Composio the
         * set is empty by construction and nothing below differs from what this method always did.
         */
        const endedBesides: { siblings: string[]; unanswered: number }[] = [];
        /*
         * ONE AUTH-PROVIDER RESOLUTION PER TOOLKIT FOR THE WHOLE REMOVAL, not one per person.
         *
         * `connected` holds a row per PERSON who connected this app, and each `resolveSiblings`
         * above resolves the asked toolkit plus every app that person holds. Unmemoized that is a
         * live vendor call per (person × app) on Arcade — a removal on a deployment with two
         * hundred people holding five apps each is over a thousand serial calls inside one admin
         * request, which times out partway and leaves accounts revoked at the vendor with every
         * local row still standing. Memoized, the bound is the number of DISTINCT TOOLKITS across
         * those rows, whatever the number of people.
         *
         * The memo lives exactly as long as this removal and is dropped with it; see
         * {@link resolveSiblings} for why one call's worth is semantically free.
         */
        const authProviders = new Map<string, Promise<string | null>>();
        for (const account of accounts) {
          /*
           * ASKED OF `rowBroker` AND NOT OF `broker`, both here and at the revoke below.
           * {@link resolveSiblings} resolves against the CONFIGURED provider's rows and the active
           * broker's `authProviderOf`, so asking it about a foreign row's app would be the same
           * wrong-vendor question the revoke was asking. No broker for this row means nothing was
           * asked, which is the answer the empty set and the `false` beside it already carry.
           */
          endedBesides.push(
            rowBroker
              ? await resolveSiblings({ toolkit, account }, authProviders)
              : { siblings: [], unanswered: 0 },
          );
          revokeAnswers.push(
            rowBroker ? await rowBroker.revoke({ account, toolkit }) : false,
          );
        }

        await database.delete(brokeredConnections).where(
          and(
            // The row's own broker, as the read above.
            eq(brokeredConnections.provider, rowProvider),
            eq(brokeredConnections.app, toolkit),
          ),
        );

        for (const [index, account] of accounts.entries()) {
          await recordAuditEvent(auditStore, {
            eventType: "mcp.account_disconnected",
            targetType: "mcp_server",
            /*
             * THE APP, not this row's id, and the same key `retireConnectionsFor` files under.
             *
             * CRITERION. Every `mcp.account_disconnected` row a brokered connection produces is
             * keyed on the app at the broker, whichever act produced it, so one query answers
             * what happened to one person's brokered access.
             *
             * REASON. The two acts that can end such a connection were keyed differently: this
             * one on `mcp_servers.id`, offboarding on `composio_connections.toolkit` — which is
             * all that row records and all that is left once the server row is gone. Nothing
             * holds the two strings equal, so on any renamed row half the trail is filed under a
             * name the other half never mentions, and the disagreement is invisible everywhere
             * they happen to match.
             *
             * THE APP IS WHAT WAS CONSENTED TO. The gate is `(toolkit, user_id)`, the delete
             * above is by toolkit, and the row outlives the server row entirely; the id is a
             * display key that may not exist by the time somebody asks. Which server row was
             * removed is not lost — the `configuration.changed` row written below names it.
             */
            targetId: toolkit,
            payload: {
              actor: by,
              server: toolkit,
              // Whose account this was, by the rule {@link disconnectBrokered} names it by: a
              // person's own under their id, the deployment's own as the deployment, never as
              // the administrator who removed the app. Taken off the SAME `AccountRef` the revoke
              // above was asked with — read once, by `asAccountRef` — so the trail cannot name a
              // holder the withdrawal did not use.
              owner:
                account.holder === "person" ? account.userId : "deployment",
              // The same three-way distinction the vault loop above draws, and the same answer: an
              // administrator took the whole app away and the person did nothing.
              reason: "mcp_server_removed",
              /*
               * What was asked of the vendor, not that a call was made — {@link
               * ComposioBroker.revoke}'s own answer, passed through. True where an account was
               * found and its withdrawal asked for, false where there was none to withdraw or
               * where this deployment has no broker to have asked. The value of the field is
               * exactly that a reader can tell an account this deployment acted on from one that
               * outlives it somewhere else, so a constant here would be worse than none. It says
               * "requested" because that is the strongest thing the vendor's answer supports:
               * the upstream withdrawal runs as a background job nothing here can poll.
               *
               * AND NEVER FOR A KEY: the claim is {@link vendorRevocationClaim}'s, the one
               * {@link disconnectBrokered} and {@link retireConnectionsFor} make, and for a key app
               * it is `false` whatever the vendor answered. This row used to pass the raw answer
               * through for a key (round 2, A5c).
               */
              ...claim(revokeAnswers[index] ?? false),
            },
          });
        }

        /*
         * THE SIBLINGS THE VENDOR ENDED WITH THIS APP, by the three rules written down once in
         * {@link clearEndedSiblings} — the same call {@link disconnectBrokered} and
         * {@link clearWithdrawnAccount} make. This loop used to spell rules 2 and 3 itself and so
         * missed rule 1: a KEY sibling's row was deleted on the strength of an OAuth revoke that
         * never ended it, leaving a live account at the vendor with no local row to reach it.
         *
         * WHAT DIFFERS FROM THOSE CALLERS IS ONLY THE ASKED APP, and it is handled above rather
         * than here: a removal ends EVERY holder's row for `toolkit` in one delete keyed on the
         * ROW's provider, where a disconnect ends one account's. So `endedWith` is `toolkit`, whose
         * rows are already gone, and the helper never clears it. `revoked` is the vendor's raw
         * answer per account, as `disconnectBrokered` passes its own `ended`.
         *
         * It sits after the revokes above for the same reason the asked app's rows do: an exception
         * from any of them left every row standing. AND IT CAN CLEAR ONLY THE CONFIGURED PROVIDER'S
         * OWN ROWS, which is what keeps the helper's `accountRow` delete — keyed on `brokerProvider`
         * — about the same broker as the siblings it deletes: `revoked` true requires `rowBroker`,
         * and there is no `rowBroker` for a row the other broker minted.
         */
        for (const [index, account] of accounts.entries()) {
          const { siblings, unanswered } = endedBesides[index] ?? {
            siblings: [],
            unanswered: 0,
          };
          await clearEndedSiblings({
            siblings,
            account,
            endedWith: toolkit,
            revoked: revokeAnswers[index] ?? false,
            unanswered,
            by,
            reason: "mcp_server_removed",
          });
        }

        // Last of all, for the reason above, and skipped entirely on a deployment with no
        // broker to have made one — or, for a row of the other broker's, no broker of ITS that
        // this deployment can reach. Nothing here holds an auth config at a vendor it is not
        // configured for, and this slug is not a name that vendor's apps go by.
        if (rowBroker) await rowBroker.deleteAuthConfig(toolkit);
      }

      const released = await database.transaction(async (transaction) => {
        const removed = await transaction
          .delete(pluginGrants)
          .where(
            and(
              eq(pluginGrants.kind, "mcp"),
              eq(sql`split_part(${pluginGrants.ref}, '/', 1)`, serverId),
            ),
          )
          .returning({ ref: pluginGrants.ref, agentId: pluginGrants.agentId });
        await transaction.delete(mcpServers).where(eq(mcpServers.id, serverId));
        return removed.sort((left, right) => left.ref.localeCompare(right.ref));
      });

      await recordAuditEvent(auditStore, {
        eventType: "configuration.changed",
        targetType: "mcp_server",
        targetId: serverId,
        payload: {
          actor: by,
          change: "mcp_server_removed",
          server: serverId,
          ...(released.length > 0
            ? {
                releasedGrants: released.map((grant) => grant.ref),
                bots: [...new Set(released.map((grant) => grant.agentId))],
              }
            : {}),
        },
      });
    },

    /**
     * Ask a server what it offers and replace what we hold.
     *
     * Replaced wholesale, never merged. A tool a vendor withdrew has to stop being offered, and a
     * merge would leave it in the list forever as a name the model will happily call.
     *
     * `actorId` is who is asking, and whether it is needed at all is the transport's answer rather
     * than an assumption here. Where listing means asking a remote server — MCP — a `user-oauth`
     * vendor has no deployment credential to ask with, so the listing runs on the grant of whoever
     * pressed refresh, and an administrator who has not connected gets a refusal that lands in
     * `lastError`. That is the honest state: until somebody has connected, this deployment genuinely
     * does not know what that server offers.
     *
     * Where the tool list is this deployment's own code, nothing is asked and no credential is
     * consulted. Requiring one anyway is what made setting Drive up a round trip through an
     * administrator's personal settings page for a token that was then discarded.
     *
     * Absent for the refresh that happens right after a server is added, where nobody can have
     * connected yet. It makes no difference to a `deployment-bearer` server, which never consults it.
     */
    async refreshTools(
      serverId: string,
      actorId = "",
    ): Promise<{ tools: number }> {
      const { row, entry, access } = await requireServer(serverId);

      /*
       * Who the trail says asked for this listing, which is not the same value as who to list AS.
       *
       * CRITERION. The two audit rows below must never name an actor of `""`.
       *
       * REASON. `actorId` does double duty: it selects the person's credential where listing needs
       * one, and it is copied into those rows. The add paths pass neither, deliberately — nobody can
       * have connected an app in the second it is added, and the comment above this method says why
       * requiring one there was wrong. So the absence is permanent and correct for the credential,
       * and meaningless for the trail, which was left writing `actor: ""` on every row an add
       * produced. The deployment refreshing on its own behalf is a real answer and `reachedAs`
       * already spells it that way; see {@link DEPLOYMENT_ACTOR}. Held separately rather than
       * defaulting the parameter, because defaulting it would hand `connectionTokenFor` a person
       * called "deployment" to look a grant up by.
       */
      const auditActor = actorId || DEPLOYMENT_ACTOR;

      // How a row is reached is resolved once, in `requireServer`. Derived from the entry here,
      // a Composio app — which has no entry — was dialled as MCP at `composio://gmail`.
      const transport = transportFor(access.transport);

      /*
       * A brokered row with no app in its url has nobody to ask, and saying so is not the transport's
       * job.
       *
       * CRITERION. A listing this deployment could not even attempt must not be committed as a
       * refresh, and must not be written down as a vendor's answer.
       *
       * REASON. `accessFor` answers `brokered` for every row whose provenance column says so, and
       * reads the app slug off the url — so `{ credential: "brokered", toolkit: null }` is a real
       * state, which a hand edit or a restored backup produces and nothing in the product does.
       * `connectionTokenFor` already refuses it, but only where listing needs a credential, and a
       * brokered listing needs none: the broker publishes an action's schema to anybody. So the gate
       * was skipped on exactly the path that reaches the vendor with no app named, and the transport
       * answered `[]` — indistinguishable, one line later, from an app that advertises nothing.
       *
       * READ AS FIELDS, not as a transport. `credential` and `toolkit` are both resolved in
       * `access.ts` and this asks nothing about which protocol is underneath: any broker reached
       * without an app named is unroutable, which is the property `toolkit` is documented to carry.
       * A `transport === "composio"` test here would put back the per-call-site derivation that
       * module exists to have removed.
       */
      if (access.credential === "brokered" && !access.toolkit) {
        throw new PluginInvariantError(
          `${row.id} resolves to a brokered credential with no app in its url, so there is nothing to ask what it offers.`,
        );
      }

      /*
       * ASKING THE VENDOR, and the only part of this method whose failure is a vendor's.
       *
       * CRITERION. What lands in `lastError` must be something a vendor, a credential or a person
       * could have caused. An invariant this deployment violated and a fault in its own database must
       * not read as a vendor misbehaving.
       *
       * REASON. This used to be one `try` around everything below as well — the wholesale replace,
       * the server-row update and both audit writes — with a `catch` that copied any message into
       * `lastError` and answered `{ tools: 0 }`. So a statement timeout, a duplicate-key refusal or an
       * `audit_events` insert that would not go in all reported a vendor that had in fact answered
       * correctly, and reported it beside actions the refresh had already committed. Narrowing that
       * by error class would be narrowing by prose; narrowing it by SHAPE is what this split does, so
       * a line added below cannot quietly acquire a vendor's excuse.
       */
      let listed: ListedTool[];
      try {
        /*
         * A credential only when listing actually needs one.
         *
         * Where it is needed, it is taken from the same selection the call path uses rather than by
         * decrypting `row.credentialId` — which is what this used to do, and which for a `user-oauth`
         * server would have sent the deployment's OAuth client secret to the vendor as somebody's
         * access token. One answer to "what token does this server get", and it cannot be a secret of
         * the wrong kind.
         *
         * Where it is NOT needed, asking anyway is not a harmless extra check. For a `user-oauth`
         * server that call refuses unless the person pressing the button has connected their own
         * account — so an administrator setting Drive up was blocked at "refresh tools" and sent to
         * their personal settings page to grant access, so that a token could be minted and handed to
         * a function that discards it. The gate outlived the reason for it.
         */
        const token = transport.listNeedsCredential
          ? (await connectionTokenFor(row, entry, actorId, access)).token
          : undefined;

        listed = await transport.listTools({
          url: effectiveUrl(row, entry),
          token,
          tokenHeader: tokenHeaderFor(entry),
        });
      } catch (error) {
        /*
         * Ours rather than a vendor's, asked as one question about the whole shelf.
         *
         * CRITERION. Nothing on the `isDeploymentFault` shelf is written into `lastError`, and
         * nothing raised from here carries a statement or a bound value.
         *
         * WHAT THIS USED TO BE, and why the difference is not cosmetic. It read `error instanceof
         * PluginInvariantError` — which was DEAD, and its own comment named two throws that cannot
         * arrive here: `connectionTokenFor` is only called when `transport.listNeedsCredential`,
         * which is false for `composio`, the only brokered transport, so the brokered narrowing
         * cannot fire inside this `try`; and the `person-oauth` narrowing is unreachable because
         * `accessFor` answers that credential only for a `user-oauth` entry. So the line could be
         * deleted with every test still green while the arrival it should have been catching —
         * a query of ours failing — went straight past it into the column below.
         *
         * A QUERY FAILURE IS THE REACHABLE ONE. `connectionTokenFor`'s vault read, its connection
         * lookup and its locked credential swap all run inside this `try` for an MCP listing, and
         * each throws a `DrizzleQueryError` whose message is the statement plus every value bound
         * to it. Recorded, that put a SQL dump in the column the Plugins page draws, under a
         * heading that says a vendor said it. Raised as an invariant of ours, with the driver's
         * complaint and none of the query.
         */
        if (isDeploymentFault(error)) {
          throw isQueryFailure(error)
            ? new PluginInvariantError(
                `${row.id}: asking this app what it offers failed on a query of this deployment's own, so nothing about the app was learned and nothing it holds was changed. ${databaseComplaint(error)}`,
              )
            : error;
        }

        /*
         * ASKED THROUGH THE ONE DOOR, like the `storableTools` catch forty lines below that writes
         * the same column.
         *
         * `McpServerError` in the old test was doing nothing — it extends `Error`, so the second arm
         * answered for it — and what the whole expression amounted to was
         * `error instanceof Error ? error.message : String(error)`, which is precisely the reflex
         * {@link reasonWithoutStatement} exists to replace: it reads `.message` directly and so walks
         * straight past {@link withoutStatement}.
         *
         * NOTHING REACHABLE CHANGES BEHAVIOUR HERE TODAY, and that is the reason to write it rather
         * than an argument against. The guard above answers every query failure before this line, so
         * the shape whose message must never travel cannot arrive by any path anybody can name. What
         * CAN arrive is a wrapper — `composio.listTools` rethrows `new Error(listingSentence(...))`,
         * and `listingSentence` falls through to the thrown message verbatim — and a wrapper carries
         * no `query` and no `params` of its own, so it is on nobody's shelf and answers to nobody's
         * check. "No thrower reachable today" was also true of the credential envelope before the
         * rotation path started writing one; the door costs nothing and does not need to be
         * rediscovered at the next site.
         */
        const message = reasonWithoutStatement(error);
        // The failure is recorded rather than thrown away, because a server with no tools and no
        // explanation reads as a server that offers nothing, and an operator would go looking in
        // the wrong place. The tools already held are left alone: a vendor being briefly
        // unreachable is not a reason to revoke what Bots are using.
        await database
          .update(mcpServers)
          .set({
            /*
             * Capped at the same 400 characters `callTool` caps its recorded failure at.
             *
             * Parts of this sentence come from a vendor, and it is drawn on the admin page — neither
             * is a promise about length, and the two paths that show a vendor's words to an operator
             * should not disagree about how much of them to keep.
             */
            lastError: message.slice(0, 400),
            updatedAt: new Date(),
          })
          .where(eq(mcpServers.id, serverId));
        return { tools: 0 };
      }

      /*
       * An empty listing never destroys what a real listing recorded.
       *
       * CRITERION ONE. An empty answer must not be committed as a healthy refresh where doing so
       * would delete actions this deployment holds, and must not clear `lastError`.
       *
       * CRITERION TWO. "This app advertises nothing" stays recordable: an app with nothing held has
       * nothing to lose, so the empty answer falls through to the replace below and commits — a
       * refresh stamp, no error, no actions.
       *
       * REASON. The replace below is a delete and an insert, so an empty answer committed here
       * deletes every `mcp_tools` row for the server, taking the recorded `effect`, `destructive`
       * and `version` with it. `version` is the one that cannot be reconstructed: `callTool` refuses
       * an action without it, so a refresh that reported success broke every subsequent call, and
       * the grants survived pointing at rows that no longer existed — absent from `listServers`, and
       * revived only by a later refresh that worked.
       *
       * WHAT USED TO REACH THIS LINE, and no longer does. `composio.listTools` once answered `[]`
       * for a url naming no app and for a deployment with no Composio client installed, neither of
       * which is a vendor's answer, and the second of those is the state of every real deployment.
       * Both throw now, so that particular arrival is closed at the seam rather than here. The guard
       * stays because its argument never depended on who sent the empty answer.
       *
       * KEPT RATHER THAN TRUSTED, and that asymmetry is the whole argument. Holding actions the vendor
       * has withdrawn is visible and reversible: the next listing replaces them. Deleting actions the
       * vendor never withdrew is neither — `mcp_tools` is shared, so it is every replica at once, and
       * only a refresh from a deployment that can actually reach the vendor puts it back. That holds
       * for any vendor that suddenly lists nothing, whatever made it do so, which is why removing
       * this would reopen the same data loss for a different reason.
       *
       * THE SEAM REQUIREMENT this leans on, and it is satisfied: a transport that could not ask
       * anybody must THROW rather than return `[]`. `composio.listTools` opens with two throws that
       * say which of the two it is — no app in the url, no client installed — and no transport has
       * an early `return []` left in it at all: `builtin-routines` answers a static list, and `mcp`
       * and `google-drive-rest` hand back only what a request returned. So an empty listing reaching
       * this line is a vendor's own answer, which is what the sentence below says. Nothing here asks
       * which transport it is talking to, and nothing has to: the requirement is met at each seam
       * rather than branched on here.
       */
      if (listed.length === 0) {
        const held = await database
          .select({ name: mcpTools.name })
          .from(mcpTools)
          .where(eq(mcpTools.serverId, serverId));

        if (held.length > 0) {
          await database
            .update(mcpServers)
            .set({
              // Named as the state it is, because "listed nothing" and "would not answer" send an
              // operator to different places, and reaching this line settles which one it was: a
              // listing that could not be made throws and lands in the `catch` above instead. So
              // this sentence must not send anybody to check their configuration — that is the
              // other state's sentence, written by the transport that refused. No
              // `toolsRefreshedAt`: that column says when this deployment last learned what the app
              // offers, and it did not learn it here.
              lastError: `This app was asked and answered with no actions at all, so the ${held.length} already recorded for it were kept rather than deleted. Check whether it still publishes them, then refresh again.`,
              updatedAt: new Date(),
            })
            .where(eq(mcpServers.id, serverId));
          // What the app advertises, which is what it advertised before: the honest count, because
          // nothing was replaced.
          return { tools: held.length };
        }
      }

      /*
       * TURNING THE VENDOR'S ANSWER INTO ROWS, which is still the vendor's answer and so is still
       * caught.
       *
       * CRITERION. Nothing a vendor can put in a listing leaves this method as an uncaught throw,
       * and nothing a vendor can put in a listing half-applies the add that called it.
       *
       * REASON. Names are deduplicated and vendor text is made storable before a transaction is
       * opened on any of it, because both of those failures used to abort the replace from inside
       * one — see {@link storableTools}. Moving the work earlier moved the THROW earlier with it,
       * to a line between the two `try` blocks and covered by neither. A schema that this could not
       * make storable then left `refreshTools` raw: the refresh route has no mapping for it, so the
       * admin page got a bodiless 500 and `lastError` kept whatever it held before; and `addServer`
       * refreshes before it answers, so the add died AFTER its server row and its audit row had
       * committed, leaving a configured app nobody had finished configuring.
       *
       * A NAME NO MODEL COULD BE OFFERED IS NOT ONE OF THESE THROWS. It costs only its own action:
       * it comes back in `skipped` and is reported below, while the rest of the listing is stored.
       *
       * RECORDED RATHER THAN RAISED, which is the same answer the vendor `try` gives, because this
       * is the same kind of event: the app was reached, it answered, and its answer is not something
       * this deployment can write down. The actions it already holds are kept, no `toolsRefreshedAt`
       * is stamped — nothing was learned — and the add completes with the failure on the row for an
       * administrator to read.
       *
       * `withoutStatement` rather than `error.message`, so that the one shape whose message must
       * never travel cannot reach the column even from a line that should never produce one.
       */
      let storable: StorableTool[];
      let skipped: string[];
      try {
        ({ rows: storable, skipped } = storableTools(serverId, listed));
      } catch (error) {
        const reason =
          error instanceof Error ? withoutStatement(error) : String(error);
        await database
          .update(mcpServers)
          .set({
            // Capped where every other quoted failure in this file is capped, and for the same
            // reason: part of this sentence comes from elsewhere and none of it is a promise about
            // length.
            lastError:
              `This app answered with an action whose schema could not be stored as it arrived, so the actions already recorded for it were kept rather than replaced. ${reason}`.slice(
                0,
                400,
              ),
            updatedAt: new Date(),
          })
          .where(eq(mcpServers.id, serverId));
        return { tools: 0 };
      }

      /*
       * ACTIONS LEFT OUT FOR THEIR NAMES, said where the person who pressed Refresh will read it.
       *
       * CRITERION. A name {@link storableTools} skipped is recorded in `skippedTools`, which the
       * app's page draws as a warning, and in a log line with the server id, and costs only
       * itself: every other action in the listing is still recorded.
       *
       * REASON. The guard used to refuse the whole listing over one name, and the MCP spec allows a
       * dot in a tool name, so a custom server with one dotted action stored nothing on its add and
       * froze on every refresh after. Skipped silently instead, the action would simply be missing
       * with nobody told why.
       *
       * NOT `lastError`, which is where this used to go. That column is a failure, and the Plugins
       * list turns a row red for it; a refresh that stored every other action did not fail, and a
       * server that keeps listing a dotted name would have read as broken on every refresh, for
       * good. The sentence is still built, for the one case below where nothing was stored at all —
       * that refresh did learn nothing, and says so as a failure.
       */
      const skippedSentence =
        skipped.length > 0
          ? `This app listed ${skipped.length === 1 ? "an action" : `${skipped.length} actions`} that cannot be offered to a model, so ${skipped.length === 1 ? "it was" : "they were"} left out: ${skipped.map((name) => `"${name}"`).join(", ")}. A tool name may only use letters, digits, underscores and hyphens.`
          : null;
      if (skipped.length > 0) {
        console.warn(
          JSON.stringify({
            type: "mcp-tools-unofferable-names-skipped",
            serverId,
            names: skipped,
          }),
        );
      }

      /*
       * A LISTING WHERE NOTHING SURVIVED THE GUARD IS THE EMPTY ANSWER BY ANOTHER ROUTE, and is kept
       * like one — see the guard on an empty listing above. Before names were skipped, a listing of
       * nothing but unofferable names threw and kept what was held; replacing with nothing here
       * would be the deletion that guard exists to prevent, arriving through a vendor that renamed
       * every action at once.
       */
      if (storable.length === 0 && skippedSentence !== null) {
        const held = await database
          .select({ name: mcpTools.name })
          .from(mcpTools)
          .where(eq(mcpTools.serverId, serverId));

        if (held.length > 0) {
          await database
            .update(mcpServers)
            .set({
              lastError:
                `Nothing else was listed, so the ${held.length} actions already recorded for this app were kept rather than deleted. ${skippedSentence}`.slice(
                  0,
                  400,
                ),
              skippedTools: skipped,
              updatedAt: new Date(),
            })
            .where(eq(mcpServers.id, serverId));
          return { tools: held.length };
        }
      }

      /*
       * COMMITTING WHAT THE VENDOR SAID. Nothing from here down is a vendor's doing, so nothing
       * from here down is recorded as one — see the criterion on the vendor `try` further up, and
       * the one on the `try` immediately above this, which is the last thing here that still is.
       *
       * ONE STEP, because the paragraph above promises the held actions are left alone.
       *
       * "The tools already held are left alone" is only true while nothing has been written yet.
       * As two auto-committed statements the delete landed on its own whenever the insert did not:
       * a pod killed mid-refresh, a dropped connection, a statement timeout — or, with no crash at
       * all, a server that answers `tools/list` with the same `name` twice, which `mcp_tools`'
       * `(server_id, name)` primary key refuses as one multi-row insert. `mcp_tools` is shared, so
       * that is every replica at once, and nothing repopulates it: `refreshTools` is only ever
       * called by `addServer`, `addCustomServer` and an administrator pressing Refresh. The
       * connector kept every grant an administrator had made and offered none of them, and
       * `grantedToolGuidance` then told the Bot outright that it holds none of that vendor's tools.
       *
       * Rolled back together, the Bots go on using what they were granted — and the fault raises
       * rather than being copied into `lastError`, because a transaction this database would not take
       * is not something the vendor did.
       */
      try {
        await database.transaction(async (transaction) => {
          await transaction
            .delete(mcpTools)
            .where(eq(mcpTools.serverId, serverId));
          if (storable.length > 0) {
            await transaction.insert(mcpTools).values(storable);
          }
        });
      } catch (error) {
        /*
         * A database failure, with the statement and its parameters left behind.
         *
         * CRITERION. Nothing raised from here carries the SQL or the values bound to it.
         *
         * REASON. drizzle wraps every failure as a `DrizzleQueryError`, whose message is
         * `Failed query:` followed by the whole statement and then every parameter — here, the
         * vendor's entire tool list. That message is what an unhandled throw puts in the logs and
         * what any caller that prints an error puts on a screen. A SQL dump on an error path is
         * the same disclosure shape as a credential leak one layer out, and it is gratuitous: the
         * driver's own complaint says what went wrong without any of it.
         *
         * RAISED, NOT RECORDED, which is what the paragraph above this transaction argues for and
         * is now true rather than merely intended: with duplicate names and unstorable text
         * removed before the statement is built, what is left is this database refusing something
         * this deployment's own schema says it will take, and `lastError` is where a VENDOR's
         * answer goes.
         */
        throw new PluginInvariantError(
          `${row.id}: the actions this app listed were not stored, so what it already had is unchanged. ${databaseComplaint(error)}`,
        );
      }

      await database
        .update(mcpServers)
        .set({
          toolsRefreshedAt: new Date(),
          // Cleared: the listing was stored. The names it left out are a warning — see above.
          lastError: null,
          skippedTools: skipped.length > 0 ? skipped : null,
          updatedAt: new Date(),
        })
        .where(eq(mcpServers.id, serverId));

      /*
       * A grant left pointing at nothing goes in the trail, at the moment it starts pointing at
       * nothing.
       *
       * Reporting it on a screen answers "what is true now", which somebody has to go and look at.
       * This answers "when did it stop being offered, and what was holding it" — the question asked
       * after a transport is swapped back and a name starts resolving again. Without the row, the
       * only record of the gap is its absence.
       *
       * Not a refusal and not an error, so `configuration.changed` rather than a new event type:
       * nothing was denied and the refresh succeeded. Written after the tool list is replaced, so
       * what it names is what is actually left over — and only ever after a listing that was
       * committed, because the guard above returns before this on an empty answer that would have
       * named every grant the app holds.
       */
      // The names as STORED, so a grant is compared against a row that exists: a duplicate the
      // vendor listed twice is one row, and a name is spelled here the way the insert spelled it.
      const advertised = new Set(storable.map((tool) => tool.name));
      const stranded = [...(await mcpGrantsForServers([serverId])).entries()]
        .filter(([ref]) => !advertised.has(ref.slice(serverId.length + 1)))
        .sort(([left], [right]) => left.localeCompare(right));

      if (stranded.length > 0) {
        await recordAuditEvent(auditStore, {
          eventType: "configuration.changed",
          targetType: "mcp_server",
          targetId: serverId,
          payload: {
            actor: auditActor,
            change: "grants_not_advertised",
            server: serverId,
            // The refs, because that is what a grant is keyed on and what an administrator revokes.
            refs: stranded.map(([ref]) => ref),
            bots: [...new Set(stranded.flatMap(([, agents]) => agents))],
            note: "Held by a Bot and not offered to any model, because this server no longer advertises the tool. Offered again if it starts.",
          },
        });
      }

      /*
       * Tools the vendor advertises that this deployment's write list does not name.
       *
       * The mechanical half of the reconciliation Notion's catalogue entry says is required. See
       * {@link unlistedAdvertisedTools} for why only that shape of vendor is named here: an
       * advertised tool absent from `writeTools` classifies as a READ, so an under-inclusive list
       * is silent, and for a vendor with no scope strings there is nothing else standing behind it.
       *
       * `configuration.changed` rather than a type of its own, the same as the stranded grants
       * above and for the same reason: nothing was denied and the refresh succeeded. What changed
       * is that the deployment now knows a name it had not classified.
       */
      const unlisted = unlistedAdvertisedTools(entry, [...advertised]);
      if (unlisted.length > 0) {
        await recordAuditEvent(auditStore, {
          eventType: "configuration.changed",
          targetType: "mcp_server",
          targetId: serverId,
          payload: {
            actor: auditActor,
            change: "unlisted_tools_advertised",
            server: serverId,
            tools: unlisted,
            note: "Advertised by this server and not named in its reviewed write list, so each is offered to models as a read. This vendor has no read-only scope behind that list, so anything here that writes should be added to the entry.",
          },
        });
      }

      // What was recorded, which is what "this app offers N actions" means on the page. Counting
      // the listing instead reported a duplicate the vendor named twice as two actions the
      // deployment holds, when `mcp_tools` holds one row for it.
      return { tools: storable.length };
    },

    async listServers(): Promise<ServerRecord[]> {
      const rows = await database
        .select()
        .from(mcpServers)
        .orderBy(asc(mcpServers.title));
      if (rows.length === 0) return [];

      const tools = await database
        .select()
        .from(mcpTools)
        .where(
          inArray(
            mcpTools.serverId,
            rows.map((row) => row.id),
          ),
        )
        .orderBy(asc(mcpTools.name));

      /*
       * Every grant on these servers, not only the ones matching a tool that is still advertised.
       * Asking about the advertised refs answers "who holds what is offered", which cannot report the
       * grants that are the point here — see `mcpGrantsForServers`.
       */
      const grants = await mcpGrantsForServers(rows.map((row) => row.id));
      const advertised = new Set(
        tools.map((tool) => `${tool.serverId}/${tool.name}`),
      );

      /*
       * HOW EACH APP CONNECTS, WHICH IS A FACT ABOUT THE APP AND NOT ABOUT THE ROW BESIDE IT.
       *
       * CRITERION. Every row here whose url names a Composio app reports the scheme
       * {@link brokeredAppScheme} answers for that app — so two rows at one url report one answer,
       * and it is the answer {@link connectBrokeredWithFields} will act on.
       *
       * REASON. The browser forks on this field: `brokered-account-row.tsx` draws a consent button,
       * a form or a "nothing to connect" sentence out of it, and the press then lands in a store
       * method that resolves the app by its URL. Reported off each row's own column those were two
       * readings of one fact — a form drawn from this row and a submission refused by the other
       * row's scheme, telling somebody to connect the app the way it asks for over an app they were
       * asked exactly that way. {@link serverAddress} answers the same field the same way, so the
       * page that lists an app and the route that connects it cannot come apart either.
       *
       * ONE EXTRA READ FOR THE WHOLE LIST, and none where the deployment has enabled no apps.
       */
      const brokeredApps = await brokeredAppRowsAt(
        rows
          .filter((row) => toolkitOfFor(brokerProvider, row.url) !== null)
          .map((row) => row.url),
      );

      /*
       * WHICH APPS THE DEPLOYMENT HOLDS AN ACCOUNT AT, IN ONE READ FOR THE WHOLE LIST. Keyed by
       * app rather than by server, because the account belongs to the app's url and not to a row:
       * two rows at one url are one Composio app with one deployment account behind it.
       */
      const deploymentHeld = new Set(
        (
          await database
            .select({ app: brokeredConnections.app })
            .from(brokeredConnections)
            .where(
              and(
                eq(brokeredConnections.provider, brokerProvider),
                eq(brokeredConnections.holder, "deployment"),
              ),
            )
        ).map((held) => held.app),
      );

      return rows.map((row) => {
        const entry = catalogueEntry(row.id);
        const toolkit = toolkitOfFor(brokerProvider, row.url);
        return {
          id: row.id,
          title: row.title,
          logo: row.logo,
          vendor: row.vendor,
          url: effectiveUrl(row, entry),
          summary: entry?.summary ?? "",
          docsUrl: entry?.docsUrl ?? "",
          provenance: row.provenance,
          hasCredential: row.credentialId !== null,
          toolsRefreshedAt: iso(row.toolsRefreshedAt),
          lastError: row.lastError,
          skippedTools: row.skippedTools ?? [],
          addedBy: row.addedBy,
          dynamicClient:
            entry?.auth.kind === "user-oauth" &&
            entry.auth.clientRegistration === "dynamic",
          // The app's, for a row whose url names one; this row's own column for everything else,
          // which is a null on every server that is not brokered. See the read above.
          authScheme: toolkit
            ? (brokeredApps.get(row.url)?.authScheme ?? null)
            : row.authScheme,
          /*
           * The app's mode for the same reason as its scheme: a duplicate row at a Shared app's url
           * is the Shared app, and the memory ingestion decides whose account a source reads from
           * exactly these two fields.
           */
          accountMode: toolkit
            ? (brokeredApps.get(row.url)?.accountMode ?? null)
            : row.accountMode,
          sharedVendorConnected:
            toolkit !== null &&
            brokeredApps.get(row.url)?.accountMode === "shared" &&
            deploymentHeld.has(toolkit),
          ownerGrants: ownerGrantsOf({
            provider: toolkit ? brokerProvider : entry ? "catalogue" : "custom",
            authScheme: toolkit
              ? (brokeredApps.get(row.url)?.authScheme ?? null)
              : row.authScheme,
            accountMode: toolkit
              ? (brokeredApps.get(row.url)?.accountMode ?? null)
              : row.accountMode,
            catalogueAuth: entry?.auth ?? null,
            ownerGrants: row.ownerGrants,
          }),
          ownerGrantsChosen: row.ownerGrants,
          tools: tools
            .filter((tool) => tool.serverId === row.id)
            .map((tool) => {
              const ref = `${tool.serverId}/${tool.name}`;
              return {
                serverId: tool.serverId,
                name: tool.name,
                description: tool.description,
                inputSchema: tool.inputSchema as Record<string, unknown>,
                ref,
                effect: classifyTool(entry, tool.name, true, tool.effect),
                destructive: tool.destructive,
                grantedTo: grants.get(ref) ?? [],
              };
            }),
          /*
           * Sorted by ref so the list is stable between reads, which matters because this is the one
           * place a discrepancy is reported and a reader comparing two visits should see the same
           * order.
           */
          withdrawn: [...grants.entries()]
            .filter(
              ([ref]) => ref.startsWith(`${row.id}/`) && !advertised.has(ref),
            )
            .sort(([left], [right]) => left.localeCompare(right))
            .map(([ref, grantedTo]) => ({
              ref,
              name: ref.slice(row.id.length + 1),
              grantedTo,
            })),
        };
      });
    },

    /**
     * Where one server is, by id, and nothing that hangs off it.
     *
     * WHY IT EXISTS BESIDE {@link listServers}. Three routes asked that one for a single row's url
     * — the brokered branch of connect, and the confirm and disconnect pair behind
     * `brokeredAppFor` — and it answers by running three queries and materialising every server,
     * every tool and every grant in the deployment. Confirm is the sharp end: both brokered account
     * screens call it from an effect on mount, so opening a large app's page read the whole tool and
     * grant table to ask whether one row is brokered. None of the three looks at a tool or a grant.
     *
     * THE URL IS THE ROW'S OWN, read out of the column rather than composed from the id. The whole
     * brokered feature rests on the two being allowed to differ: `addBrokeredApp` writes
     * `composio://<slug>` and names the row for it, but nothing holds them equal afterwards, and a
     * row called `gmail` at `composio://slack` is exactly the shape the connection gate was once
     * keyed on the wrong half of. The catalogue reconciliation {@link effectiveUrl} applies for
     * `listServers` is deliberately not applied here, and changes no answer: it only ever
     * substitutes the pinned host of a first-party entry, and neither reading of such a row names a
     * Composio app.
     *
     * `undefined` for an id naming no row, which is what the `.find` over the whole list answered
     * before — so a route that refused an unknown id still refuses it, in the same words.
     *
     * AND THE SCHEME IS THE APP'S, NOT THIS ROW'S, WHICH IS THE ONE FIELD HERE THAT IS NOT ABOUT A
     * ROW AT ALL.
     *
     * CRITERION. For a row whose url names a Composio app, `authScheme` is what
     * {@link brokeredAppScheme} answers for that app.
     *
     * REASON. The connect route forks on this field — a form for a key app, a consent link for a
     * consent one, a refusal for a no-auth one — and the store method that fork leads to,
     * {@link connectBrokeredWithFields}, reads the scheme off the row that answers for the APP. Two
     * rows may name one app, so those were two different reads of one fact: the page draws a form
     * off this row and the submission is refused by the other row's scheme, in a sentence telling
     * somebody to connect an app the way it asks for — over an app they were just asked exactly
     * that way. The id and the title stay this row's own, because those name the row the page
     * opened; the scheme is a fact about the app, and the app has one answer.
     *
     * `accountMode` IS THE APP'S FOR THE SAME REASON, off the same answering row and in the same
     * read, never this row's own column; a row that names no app has no mode and answers null.
     *
     * ONE EXTRA READ, AND ONLY FOR A BROKERED URL. A row that names no app takes the read it always
     * took.
     */
    async serverAddress(serverId: string): Promise<ServerAddress | undefined> {
      const [row] = await database
        .select({
          id: mcpServers.id,
          title: mcpServers.title,
          url: mcpServers.url,
          authScheme: mcpServers.authScheme,
        })
        .from(mcpServers)
        .where(eq(mcpServers.id, serverId))
        .limit(1);
      if (!row) return undefined;
      const toolkit = toolkitOfFor(brokerProvider, row.url);
      if (!toolkit) return { ...row, accountMode: null };
      const app = await brokeredAppRow(toolkit);
      return {
        ...row,
        authScheme: app?.authScheme ?? null,
        accountMode: app?.accountMode ?? null,
      };
    },

    /**
     * Where every added server is, for the one caller whose question is about the whole set.
     *
     * A SECOND READ RATHER THAN {@link serverAddress} IN A LOOP, and rather than one method serving
     * both. The app directory asks which of Composio's apps are already enabled here, which has no
     * id to look up — answered a row at a time it would be one query per app in the directory. And
     * it needs strictly less than the row read hands back: the app comes off the url, so an id and
     * a title would be nothing but two fields a reader could take the app out of by mistake. The
     * directory route's own comment says why that matters — the url is where the transport reads
     * which app a call is against, and the id is a row name that happens to look similar.
     *
     * Ordered, so two readings of an unchanged deployment answer alike.
     */
    async serverUrls(): Promise<string[]> {
      const rows = await database
        .select({ url: mcpServers.url })
        .from(mcpServers)
        .orderBy(asc(mcpServers.id));
      return rows.map((row) => row.url);
    },

    /**
     * Every account any holder has on a brokered app, as the broker would be asked to end it.
     *
     * READ THROUGH {@link asAccountRef}, AND A ROW THAT NAMES NO ACCOUNT STOPS THE READ. Every
     * account handed back here is passed straight to {@link disconnectBrokered} by the mode
     * switch, so what is minted here is what a revoke is aimed at and what the trail records. The
     * reading this replaces was `userId: row.userId ?? ""`, the quiet direction of the same
     * coercion `asAccountRef` exists to refuse: a person row carrying no user id came out as a
     * person ref belonging to NOBODY and was withdrawn under an owner of `""`. `''` is the pair
     * that is actually reachable — `brokered_connections_holder_check` tests `IS NOT NULL`, which
     * `''` satisfies — and `null` is unwritable, which is why both are a refusal rather than a
     * default. The `null` answer below still means only "not a brokered app at this broker";
     * a row that cannot be read is this deployment contradicting its own CHECK, and says so.
     */
    async accountsOn(
      serverId: string,
    ): Promise<{ toolkit: string; accounts: AccountRef[] } | null> {
      const [row] = await database
        .select({ url: mcpServers.url })
        .from(mcpServers)
        .where(eq(mcpServers.id, serverId))
        .limit(1);
      const toolkit = row ? toolkitOfFor(brokerProvider, row.url) : null;
      if (!toolkit) return null;
      const held = await database
        .select({
          holder: brokeredConnections.holder,
          userId: brokeredConnections.userId,
          vendorUserId: brokeredConnections.vendorUserId,
        })
        .from(brokeredConnections)
        .where(
          and(
            eq(brokeredConnections.provider, brokerProvider),
            eq(brokeredConnections.app, toolkit),
          ),
        );
      return {
        toolkit,
        accounts: held.map((row): AccountRef => {
          const account = asAccountRef(row);
          if (!account) {
            throw new PluginInvariantError(
              `${toolkit} holds a connection row whose holder and user id name no account, so the accounts standing for it cannot be listed.`,
            );
          }
          return account;
        }),
      };
    },

    /**
     * Write an app's mode and deployment identity — onto the row that ANSWERS for the app.
     *
     * Every reader takes these two columns off {@link brokeredAppRow}, so a write landing on a
     * duplicate row at the same url would be a switch nobody reads: the page would say Shared and
     * every call would go on running as it did. The id given is resolved to its url, the url to its
     * app, and the app to its answering row; a row that names no app is written as itself, which is
     * the only row there is to write.
     */
    async setAccountModeColumns(
      serverId: string,
      mode: AccountMode,
      sharedVendorUserId: string | null,
    ) {
      const [dialled] = await database
        .select({ url: mcpServers.url })
        .from(mcpServers)
        .where(eq(mcpServers.id, serverId))
        .limit(1);
      const toolkit = dialled
        ? toolkitOfFor(brokerProvider, dialled.url)
        : null;
      const app = toolkit ? await brokeredAppRow(toolkit) : null;
      await database
        .update(mcpServers)
        .set({ accountMode: mode, sharedVendorUserId })
        .where(eq(mcpServers.id, app?.id ?? serverId));
    },
  };
}